Merge branch 'dev' into u3/agent-effort-level

# Conflicts:
#	packages/api/tests/agent-manager.test.ts

2 files changed, 417 insertions, 0 deletions

diff --git a/packages/frontend/tests/chat-store.test.ts b/packages/frontend/tests/chat-store.test.ts
index 33a9f69..c0763cd 100644
--- a/packages/frontend/tests/chat-store.test.ts
+++ b/packages/frontend/tests/chat-store.test.ts
@@ -71,6 +71,7 @@ beforeEach(() => {
 	);
 });
 
+import { computeContextUsage } from "../src/lib/context-window.js";
 import { appSettings } from "../src/lib/settings.svelte.js";
 import { createTabStore } from "../src/lib/tabs.svelte.js";
 import type { Chunk, PermissionPrompt } from "../src/lib/types.js";
@@ -1005,6 +1006,257 @@ describe("hydrateFromBackend", () => {
 		expect(tC?.renderGroups.length).toBe(0);
 		expect(tC?.agentStatus).toBe("idle");
 	});
+
+	// ─── usage persistence: seed cacheStats from the backend aggregate ──
+	it("seeds cacheStats from a tab's usageStats on hydrate (reload persistence)", async () => {
+		const usageStats = {
+			inputTokens: 2200,
+			outputTokens: 100,
+			cacheReadTokens: 1000,
+			cacheWriteTokens: 1000,
+			requests: 2,
+			last: { inputTokens: 1200, outputTokens: 60, cacheReadTokens: 1000, cacheWriteTokens: 100 },
+		};
+		vi.stubGlobal(
+			"fetch",
+			vi.fn((url: string) => {
+				if (url.endsWith("/tabs")) {
+					return Promise.resolve({
+						ok: true,
+						json: () =>
+							Promise.resolve({
+								tabs: [
+									{
+										id: "tu",
+										title: "Has usage",
+										keyId: null,
+										modelId: null,
+										parentTabId: null,
+										usageStats,
+									},
+									{
+										id: "tn",
+										title: "No usage",
+										keyId: null,
+										modelId: null,
+										parentTabId: null,
+										usageStats: null,
+									},
+								],
+							}),
+					});
+				}
+				if (url.endsWith("/status")) {
+					return Promise.resolve({ ok: true, json: () => Promise.resolve({ statuses: {} }) });
+				}
+				if (url.split("?")[0]?.endsWith("/tabs/tu/chunks")) {
+					return Promise.resolve({
+						ok: true,
+						json: () => Promise.resolve({ chunks: [], total: 0, oldestSeq: null }),
+					});
+				}
+				if (url.split("?")[0]?.endsWith("/tabs/tn/chunks")) {
+					return Promise.resolve({
+						ok: true,
+						json: () => Promise.resolve({ chunks: [], total: 0, oldestSeq: null }),
+					});
+				}
+				return Promise.reject(new Error(`unexpected fetch ${url}`));
+			}),
+		);
+
+		const store = createTabStore();
+		const n = await store.hydrateFromBackend();
+		expect(n).toBe(2);
+		// Tab with persisted usage → cacheStats seeded directly from the aggregate.
+		expect(store.tabs.find((t) => t.id === "tu")?.cacheStats).toEqual(usageStats);
+		// Tab with null usageStats → cacheStats stays undefined (no usage yet).
+		expect(store.tabs.find((t) => t.id === "tn")?.cacheStats).toBeUndefined();
+	});
+
+	it("does not re-seed or double-count cacheStats on a statuses reconnect after hydrate", async () => {
+		const usageStats = {
+			inputTokens: 1000,
+			outputTokens: 40,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 900,
+			requests: 1,
+			last: { inputTokens: 1000, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 900 },
+		};
+		vi.stubGlobal(
+			"fetch",
+			vi.fn((url: string) => {
+				if (url.endsWith("/tabs")) {
+					return Promise.resolve({
+						ok: true,
+						json: () =>
+							Promise.resolve({
+								tabs: [
+									{
+										id: "tr",
+										title: "Reconnect",
+										keyId: null,
+										modelId: null,
+										parentTabId: null,
+										usageStats,
+									},
+								],
+							}),
+					});
+				}
+				if (url.endsWith("/status")) {
+					return Promise.resolve({ ok: true, json: () => Promise.resolve({ statuses: {} }) });
+				}
+				if (url.split("?")[0]?.endsWith("/tabs/tr/chunks")) {
+					return Promise.resolve({
+						ok: true,
+						json: () => Promise.resolve({ chunks: [], total: 0, oldestSeq: null }),
+					});
+				}
+				return Promise.reject(new Error(`unexpected fetch ${url}`));
+			}),
+		);
+
+		const store = createTabStore();
+		await store.hydrateFromBackend();
+		expect(store.tabs.find((t) => t.id === "tr")?.cacheStats).toEqual(usageStats);
+
+		// A WS reconnect snapshot must NOT touch cacheStats (in-session live
+		// `usage` events own the running totals; the aggregate seed is reload-only).
+		store.handleEvent({ type: "statuses", statuses: { tr: { status: "idle" } } });
+		expect(store.tabs.find((t) => t.id === "tr")?.cacheStats).toEqual(usageStats);
+	});
+
+	it("keeps accumulating live usage events after a hydrate seed", async () => {
+		const usageStats = {
+			inputTokens: 1000,
+			outputTokens: 40,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 900,
+			requests: 1,
+			last: { inputTokens: 1000, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 900 },
+		};
+		vi.stubGlobal(
+			"fetch",
+			vi.fn((url: string) => {
+				if (url.endsWith("/tabs")) {
+					return Promise.resolve({
+						ok: true,
+						json: () =>
+							Promise.resolve({
+								tabs: [
+									{
+										id: "tl",
+										title: "Live after hydrate",
+										keyId: null,
+										modelId: null,
+										parentTabId: null,
+										usageStats,
+									},
+								],
+							}),
+					});
+				}
+				if (url.endsWith("/status")) {
+					return Promise.resolve({ ok: true, json: () => Promise.resolve({ statuses: {} }) });
+				}
+				if (url.split("?")[0]?.endsWith("/tabs/tl/chunks")) {
+					return Promise.resolve({
+						ok: true,
+						json: () => Promise.resolve({ chunks: [], total: 0, oldestSeq: null }),
+					});
+				}
+				return Promise.reject(new Error(`unexpected fetch ${url}`));
+			}),
+		);
+
+		const store = createTabStore();
+		await store.hydrateFromBackend();
+
+		// A new in-session usage event folds ON TOP of the seeded aggregate.
+		store.handleEvent({
+			type: "usage",
+			tabId: "tl",
+			usage: { inputTokens: 200, outputTokens: 10, cacheReadTokens: 150, cacheWriteTokens: 0 },
+		});
+		const stats = store.tabs.find((t) => t.id === "tl")?.cacheStats;
+		expect(stats?.requests).toBe(2);
+		expect(stats?.inputTokens).toBe(1200);
+		expect(stats?.outputTokens).toBe(50);
+		expect(stats?.cacheReadTokens).toBe(150);
+		expect(stats?.cacheWriteTokens).toBe(900);
+		expect(stats?.last).toEqual({
+			inputTokens: 200,
+			outputTokens: 10,
+			cacheReadTokens: 150,
+			cacheWriteTokens: 0,
+		});
+	});
+
+	// Cross-feature contract (Context Window view, branch u2): the panel derives
+	// current context size from `cacheStats.last` via computeContextUsage. This
+	// test proves persistence restores that field on hydrate, so the view shows a
+	// real "x / max" immediately after a reload on a NEW DEVICE — not "No context
+	// data yet". Guards the contract so neither side can silently break it.
+	it("restores cacheStats.last on hydrate so the Context Window view has data after reload", async () => {
+		const usageStats = {
+			inputTokens: 90000,
+			outputTokens: 3000,
+			cacheReadTokens: 40000,
+			cacheWriteTokens: 5000,
+			requests: 3,
+			// Most recent request's snapshot — the numerator the view reads.
+			last: { inputTokens: 47000, outputTokens: 1200, cacheReadTokens: 30000, cacheWriteTokens: 0 },
+		};
+		vi.stubGlobal(
+			"fetch",
+			vi.fn((url: string) => {
+				if (url.endsWith("/tabs")) {
+					return Promise.resolve({
+						ok: true,
+						json: () =>
+							Promise.resolve({
+								tabs: [
+									{
+										id: "tc",
+										title: "Context after reload",
+										keyId: null,
+										modelId: null,
+										parentTabId: null,
+										usageStats,
+									},
+								],
+							}),
+					});
+				}
+				if (url.endsWith("/status")) {
+					return Promise.resolve({ ok: true, json: () => Promise.resolve({ statuses: {} }) });
+				}
+				if (url.split("?")[0]?.endsWith("/tabs/tc/chunks")) {
+					return Promise.resolve({
+						ok: true,
+						json: () => Promise.resolve({ chunks: [], total: 0, oldestSeq: null }),
+					});
+				}
+				return Promise.reject(new Error(`unexpected fetch ${url}`));
+			}),
+		);
+
+		const store = createTabStore();
+		await store.hydrateFromBackend();
+
+		// What App.svelte passes into ContextWindowPanel: the active tab's cacheStats
+		// plus the model's max (re-resolved from models.dev on load — here 200k).
+		const cacheStats = store.tabs.find((t) => t.id === "tc")?.cacheStats ?? null;
+		expect(cacheStats?.last).not.toBeNull();
+
+		const usage = computeContextUsage(cacheStats, 200000);
+		// current = last.inputTokens + last.outputTokens (47000 + 1200), NOT the
+		// cumulative session totals (which would double-count history).
+		expect(usage.current).toBe(48200);
+		expect(usage.max).toBe(200000);
+		expect(usage.percent).toBeCloseTo(24.1, 5);
+	});
 });
 
 // ─── statuses WS event with the wider TabStatusSnapshot shape ───
@@ -1120,6 +1372,87 @@ describe("tabStore — cache rate (usage events)", () => {
 		});
 		expect(store.tabs[0]?.cacheStats).toBeUndefined();
 	});
+
+	it("turn-sealed REPLACES cacheStats with the carried DB aggregate (reconcile to truth)", async () => {
+		const { store, tabId } = await setupStoreWithTab();
+		// Live events accumulate during the turn.
+		store.handleEvent({
+			type: "usage",
+			tabId,
+			usage: { inputTokens: 1000, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 900 },
+		});
+		expect(store.tabs.find((t) => t.id === tabId)?.cacheStats?.inputTokens).toBe(1000);
+
+		// turn-sealed carries the authoritative aggregate → cacheStats is REPLACED.
+		const aggregate = {
+			inputTokens: 1000,
+			outputTokens: 40,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 900,
+			requests: 1,
+			last: { inputTokens: 1000, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 900 },
+		};
+		store.handleEvent({ type: "turn-sealed", turnId: "t1", tabId, usageStats: aggregate });
+		expect(store.tabs.find((t) => t.id === tabId)?.cacheStats).toEqual(aggregate);
+	});
+
+	it("turn-sealed self-heals a live overshoot from a discarded fallback attempt", async () => {
+		const { store, tabId } = await setupStoreWithTab();
+		// Attempt 1 streamed usage live (overshoot), then rate-limited & discarded
+		// server-side; attempt 2's usage also streamed live. Live = sum of BOTH.
+		store.handleEvent({
+			type: "usage",
+			tabId,
+			usage: { inputTokens: 999, outputTokens: 9, cacheReadTokens: 0, cacheWriteTokens: 0 },
+		});
+		store.handleEvent({
+			type: "usage",
+			tabId,
+			usage: { inputTokens: 222, outputTokens: 22, cacheReadTokens: 100, cacheWriteTokens: 5 },
+		});
+		const overshoot = store.tabs.find((t) => t.id === tabId)?.cacheStats;
+		expect(overshoot?.requests).toBe(2);
+		expect(overshoot?.inputTokens).toBe(1221); // inflated: includes discarded attempt
+
+		// The DB only persisted attempt 2 (the survivor). turn-sealed reconciles.
+		const persisted = {
+			inputTokens: 222,
+			outputTokens: 22,
+			cacheReadTokens: 100,
+			cacheWriteTokens: 5,
+			requests: 1,
+			last: { inputTokens: 222, outputTokens: 22, cacheReadTokens: 100, cacheWriteTokens: 5 },
+		};
+		store.handleEvent({ type: "turn-sealed", turnId: "t1", tabId, usageStats: persisted });
+		// Overshoot healed: cacheStats now matches the DB truth exactly.
+		expect(store.tabs.find((t) => t.id === tabId)?.cacheStats).toEqual(persisted);
+	});
+
+	it("turn-sealed without usageStats leaves cacheStats untouched (back-compat)", async () => {
+		const { store, tabId } = await setupStoreWithTab();
+		store.handleEvent({
+			type: "usage",
+			tabId,
+			usage: { inputTokens: 500, outputTokens: 5, cacheReadTokens: 0, cacheWriteTokens: 0 },
+		});
+		const before = store.tabs.find((t) => t.id === tabId)?.cacheStats;
+		// Older backend: turn-sealed carries no usageStats field.
+		store.handleEvent({ type: "turn-sealed", turnId: "t1", tabId });
+		expect(store.tabs.find((t) => t.id === tabId)?.cacheStats).toEqual(before);
+	});
+
+	it("turn-sealed with usageStats: null clears cacheStats", async () => {
+		const { store, tabId } = await setupStoreWithTab();
+		store.handleEvent({
+			type: "usage",
+			tabId,
+			usage: { inputTokens: 500, outputTokens: 5, cacheReadTokens: 0, cacheWriteTokens: 0 },
+		});
+		expect(store.tabs.find((t) => t.id === tabId)?.cacheStats).toBeDefined();
+		// A null aggregate (no persisted usage rows) explicitly clears live stats.
+		store.handleEvent({ type: "turn-sealed", turnId: "t1", tabId, usageStats: null });
+		expect(store.tabs.find((t) => t.id === tabId)?.cacheStats).toBeUndefined();
+	});
 });
 
 // ─── chunk-native store: eviction, pagination, reconcile ────────
diff --git a/packages/frontend/tests/context-window.test.ts b/packages/frontend/tests/context-window.test.ts
new file mode 100644
index 0000000..bb64ed5
--- /dev/null
+++ b/packages/frontend/tests/context-window.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { computeContextUsage } from "../src/lib/context-window.js";
+import type { CacheStats } from "../src/lib/types.js";
+
+function stats(last: CacheStats["last"]): CacheStats {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		requests: last ? 1 : 0,
+		last,
+	};
+}
+
+describe("computeContextUsage", () => {
+	it("derives current context from the LAST request's input + output", () => {
+		const usage = computeContextUsage(
+			stats({
+				inputTokens: 47000,
+				outputTokens: 1200,
+				cacheReadTokens: 40000,
+				cacheWriteTokens: 0,
+			}),
+			200000,
+		);
+		// 47000 + 1200 — NOT the cumulative totals, and cache tokens are already
+		// inside inputTokens (not re-added).
+		expect(usage.current).toBe(48200);
+		expect(usage.max).toBe(200000);
+		expect(usage.percent).toBeCloseTo(24.1, 5); // 48200 / 200000 * 100, unrounded
+	});
+
+	it("returns max=null and percent=null when the limit is unknown", () => {
+		const usage = computeContextUsage(
+			stats({ inputTokens: 100, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+			null,
+		);
+		expect(usage.current).toBe(100);
+		expect(usage.max).toBeNull();
+		expect(usage.percent).toBeNull();
+	});
+
+	it("treats a non-positive limit as unknown", () => {
+		const usage = computeContextUsage(
+			stats({ inputTokens: 100, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+			0,
+		);
+		expect(usage.max).toBeNull();
+		expect(usage.percent).toBeNull();
+	});
+
+	it("reports zero usage when no request has completed yet", () => {
+		expect(computeContextUsage(null, 200000)).toEqual({
+			current: 0,
+			max: 200000,
+			percent: 0,
+		});
+		expect(computeContextUsage(stats(null), 200000)).toEqual({
+			current: 0,
+			max: 200000,
+			percent: 0,
+		});
+	});
+
+	it("clamps percent to 100 when context overflows the window", () => {
+		const usage = computeContextUsage(
+			stats({ inputTokens: 250000, outputTokens: 5000, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+			200000,
+		);
+		expect(usage.current).toBe(255000);
+		expect(usage.percent).toBe(100);
+	});
+
+	it("keeps an unrounded percent so the UI can show 2 decimals", () => {
+		const usage = computeContextUsage(
+			stats({ inputTokens: 3690, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }),
+			1000000,
+		);
+		// 3690 / 1,000,000 * 100 = 0.369 → displayed as "0.37%" (toFixed(2)).
+		expect(usage.percent).toBeCloseTo(0.369, 6);
+		expect((usage.percent as number).toFixed(2)).toBe("0.37");
+	});
+});