feat(metrics): expose current context size to the frontend

contextSize = the turn's FINAL step inputTokens+outputTokens (true context
occupancy; NOT the aggregate usage, which sums per-step prompts and overcounts
multi-step turns). Stamped on both the live done event (kernel) and persisted
TurnMetrics (session-orchestrator); a client reads the latest turn's value.

- @dispatch/wire 0.4.0->0.5.0: optional contextSize on TurnDoneEvent + TurnMetrics
- @dispatch/transport-contract 0.5.0->0.6.0 (re-export only)
- glossary: context size (reserve 'context window' for the model limit, later)
- FE courier: frontend-context-size-handoff.md

881 vitest pass; tsc -b EXIT 0; biome clean.

9 files changed, 323 insertions, 2 deletions

diff --git a/packages/kernel/src/runtime/events.ts b/packages/kernel/src/runtime/events.ts
index 300e711..b194577 100644
--- a/packages/kernel/src/runtime/events.ts
+++ b/packages/kernel/src/runtime/events.ts
@@ -127,16 +127,29 @@ export function doneEvent(
 	reason: string,
 	durationMs?: number,
 	usage?: Usage,
+	contextSize?: number,
 ): AgentEvent {
+	if (durationMs !== undefined && usage !== undefined && contextSize !== undefined) {
+		return { type: "done", conversationId, turnId, reason, durationMs, usage, contextSize };
+	}
 	if (durationMs !== undefined && usage !== undefined) {
 		return { type: "done", conversationId, turnId, reason, durationMs, usage };
 	}
+	if (durationMs !== undefined && contextSize !== undefined) {
+		return { type: "done", conversationId, turnId, reason, durationMs, contextSize };
+	}
+	if (usage !== undefined && contextSize !== undefined) {
+		return { type: "done", conversationId, turnId, reason, usage, contextSize };
+	}
 	if (durationMs !== undefined) {
 		return { type: "done", conversationId, turnId, reason, durationMs };
 	}
 	if (usage !== undefined) {
 		return { type: "done", conversationId, turnId, reason, usage };
 	}
+	if (contextSize !== undefined) {
+		return { type: "done", conversationId, turnId, reason, contextSize };
+	}
 	return { type: "done", conversationId, turnId, reason };
 }
 
diff --git a/packages/kernel/src/runtime/run-turn.test.ts b/packages/kernel/src/runtime/run-turn.test.ts
index fa2aba4..dcaea7f 100644
--- a/packages/kernel/src/runtime/run-turn.test.ts
+++ b/packages/kernel/src/runtime/run-turn.test.ts
@@ -2480,4 +2480,101 @@ describe("runTurn", () => {
 			}
 		});
 	});
+
+	describe("contextSize", () => {
+		it("single-step turn: contextSize equals step inputTokens + outputTokens", async () => {
+			const provider = createFakeProvider([
+				[
+					{ type: "text-delta", delta: "Hello" },
+					{ type: "usage", usage: { inputTokens: 100, outputTokens: 50 } },
+					{ type: "finish", reason: "stop" },
+				],
+			]);
+
+			const { events, emit } = createCollectingEmit();
+
+			await runTurn({
+				provider,
+				messages: [userMessage],
+				tools: [],
+				dispatch: { maxConcurrent: 1, eager: false },
+				conversationId: "conv-1",
+				turnId: "turn-1",
+				emit,
+			});
+
+			const doneEvt = events.find((e) => e.type === "done");
+			expect(doneEvt).toBeDefined();
+			if (doneEvt?.type === "done") {
+				expect(doneEvt.contextSize).toBe(150);
+			}
+		});
+
+		it("multi-step turn: contextSize equals ONLY the last step's inputTokens + outputTokens", async () => {
+			const tool = createFakeTool("echo", async () => ({ content: "echoed" }));
+
+			const provider = createFakeProvider([
+				[
+					{ type: "tool-call", toolCallId: "tc1", toolName: "echo", input: {} },
+					{ type: "usage", usage: { inputTokens: 100, outputTokens: 20 } },
+					{ type: "finish", reason: "tool-calls" },
+				],
+				[
+					{ type: "text-delta", delta: "done" },
+					{ type: "usage", usage: { inputTokens: 300, outputTokens: 80 } },
+					{ type: "finish", reason: "stop" },
+				],
+			]);
+
+			const { events, emit } = createCollectingEmit();
+
+			await runTurn({
+				provider,
+				messages: [userMessage],
+				tools: [tool],
+				dispatch: { maxConcurrent: 1, eager: false },
+				conversationId: "conv-1",
+				turnId: "turn-1",
+				emit,
+			});
+
+			const doneEvt = events.find((e) => e.type === "done");
+			expect(doneEvt).toBeDefined();
+			if (doneEvt?.type === "done") {
+				expect(doneEvt.contextSize).toBe(380);
+				expect(doneEvt.usage).toBeDefined();
+				if (doneEvt.usage !== undefined) {
+					expect(doneEvt.contextSize).not.toBe(doneEvt.usage.inputTokens);
+				}
+			}
+		});
+
+		it("no usage reported: contextSize is undefined", async () => {
+			const provider = createFakeProvider([
+				[
+					{ type: "text-delta", delta: "Hello" },
+					{ type: "finish", reason: "stop" },
+				],
+			]);
+
+			const { events, emit } = createCollectingEmit();
+
+			await runTurn({
+				provider,
+				messages: [userMessage],
+				tools: [],
+				dispatch: { maxConcurrent: 1, eager: false },
+				conversationId: "conv-1",
+				turnId: "turn-1",
+				emit,
+			});
+
+			const doneEvt = events.find((e) => e.type === "done");
+			expect(doneEvt).toBeDefined();
+			if (doneEvt?.type === "done") {
+				expect(doneEvt.contextSize).toBeUndefined();
+				expect(doneEvt.usage).toBeUndefined();
+			}
+		});
+	});
 });
diff --git a/packages/kernel/src/runtime/run-turn.ts b/packages/kernel/src/runtime/run-turn.ts
index b50e8ee..bf57854 100644
--- a/packages/kernel/src/runtime/run-turn.ts
+++ b/packages/kernel/src/runtime/run-turn.ts
@@ -449,6 +449,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 	const messages: ChatMessage[] = [...input.messages];
 	const resultMessages: ChatMessage[] = [];
 	let totalUsage = zeroUsage();
+	let lastStepUsage: Usage | undefined;
 	let finishReason = "stop";
 
 	const toolMap = new Map<string, ToolContract>();
@@ -513,6 +514,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 			});
 
 			totalUsage = addUsage(totalUsage, stepResult.usage);
+			lastStepUsage = stepResult.usage;
 
 			if (stepResult.assistantMessage !== undefined) {
 				messages.push(stepResult.assistantMessage);
@@ -571,6 +573,10 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 		totalUsage.outputTokens > 0 ||
 		totalUsage.cacheReadTokens !== undefined ||
 		totalUsage.cacheWriteTokens !== undefined;
+	const contextSize =
+		hasUsage && lastStepUsage !== undefined
+			? lastStepUsage.inputTokens + lastStepUsage.outputTokens
+			: undefined;
 	input.emit(
 		doneEvent(
 			conversationId,
@@ -578,6 +584,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 			finishReason,
 			turnDurationMs,
 			hasUsage ? totalUsage : undefined,
+			contextSize,
 		),
 	);
 
diff --git a/packages/session-orchestrator/src/metrics.test.ts b/packages/session-orchestrator/src/metrics.test.ts
index c123dba..1920fc0 100644
--- a/packages/session-orchestrator/src/metrics.test.ts
+++ b/packages/session-orchestrator/src/metrics.test.ts
@@ -261,4 +261,109 @@ describe("createMetricsAccumulator", () => {
 		expect(tm.usage.inputTokens).toBe(0);
 		expect(tm.usage.outputTokens).toBe(0);
 	});
+
+	it("contextSize equals inputTokens + outputTokens for a single-step turn", () => {
+		const acc = createMetricsAccumulator();
+
+		acc.ingest({
+			type: "usage",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#0"),
+			usage: { inputTokens: 10, outputTokens: 5 },
+		});
+		acc.ingest({
+			type: "step-complete",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#0"),
+		});
+		acc.ingest({
+			type: "done",
+			conversationId: "c1",
+			turnId: "t1",
+			reason: "stop",
+			usage: { inputTokens: 10, outputTokens: 5 },
+		});
+
+		const tm = acc.build("t1");
+		expect(tm.contextSize).toBe(15);
+	});
+
+	it("contextSize equals ONLY the last step's inputTokens + outputTokens for a multi-step turn", () => {
+		const acc = createMetricsAccumulator();
+
+		acc.ingest({
+			type: "usage",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#0"),
+			usage: { inputTokens: 10, outputTokens: 5 },
+		});
+		acc.ingest({
+			type: "step-complete",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#0"),
+		});
+		acc.ingest({
+			type: "usage",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#1"),
+			usage: { inputTokens: 20, outputTokens: 10 },
+		});
+		acc.ingest({
+			type: "step-complete",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#1"),
+		});
+		acc.ingest({
+			type: "done",
+			conversationId: "c1",
+			turnId: "t1",
+			reason: "stop",
+			usage: { inputTokens: 100, outputTokens: 50 },
+		});
+
+		const tm = acc.build("t1");
+		expect(tm.contextSize).toBe(30);
+		expect(tm.contextSize).not.toBe(tm.usage.inputTokens);
+	});
+
+	it("contextSize is undefined when the turn has no steps", () => {
+		const acc = createMetricsAccumulator();
+
+		acc.ingest({
+			type: "done",
+			conversationId: "c1",
+			turnId: "t1",
+			reason: "stop",
+		});
+
+		const tm = acc.build("t1");
+		expect(tm.contextSize).toBeUndefined();
+	});
+
+	it("contextSize is undefined when the last step has no usable per-step usage", () => {
+		const acc = createMetricsAccumulator();
+
+		acc.ingest({
+			type: "step-complete",
+			conversationId: "c1",
+			turnId: "t1",
+			stepId: stepId("t1#0"),
+			genTotalMs: 200,
+		});
+		acc.ingest({
+			type: "done",
+			conversationId: "c1",
+			turnId: "t1",
+			reason: "stop",
+		});
+
+		const tm = acc.build("t1");
+		expect(tm.contextSize).toBeUndefined();
+	});
 });
diff --git a/packages/session-orchestrator/src/metrics.ts b/packages/session-orchestrator/src/metrics.ts
index e953bd9..2dfa533 100644
--- a/packages/session-orchestrator/src/metrics.ts
+++ b/packages/session-orchestrator/src/metrics.ts
@@ -100,6 +100,20 @@ export function createMetricsAccumulator(): MetricsAccumulator {
 		if (doneDurationMs !== undefined) {
 			(tm as { durationMs?: number }).durationMs = doneDurationMs;
 		}
+
+		// contextSize = final step's inputTokens + outputTokens (true context occupancy).
+		// Omit when no steps or the last step had no usable per-step usage event.
+		if (stepMetrics.length > 0) {
+			const lastStep = stepMetrics[stepMetrics.length - 1];
+			if (lastStep !== undefined) {
+				const lastAcc = steps.get(lastStep.stepId);
+				if (lastAcc?.usage !== undefined) {
+					(tm as { contextSize?: number }).contextSize =
+						lastStep.usage.inputTokens + lastStep.usage.outputTokens;
+				}
+			}
+		}
+
 		return tm;
 	}
 
diff --git a/packages/session-orchestrator/src/orchestrator.test.ts b/packages/session-orchestrator/src/orchestrator.test.ts
index 33deb15..b33bdcc 100644
--- a/packages/session-orchestrator/src/orchestrator.test.ts
+++ b/packages/session-orchestrator/src/orchestrator.test.ts
@@ -834,6 +834,66 @@ describe("turn metrics persistence", () => {
 		expect(tm.usage.outputTokens).toBe(15);
 	});
 
+	it("persists contextSize as the last step's inputTokens + outputTokens", async () => {
+		const store = createInMemoryStore();
+		const tool = createFakeTool("echo", async () => ({ content: "echoed" }));
+
+		let callIndex = 0;
+		const provider: ProviderContract = {
+			id: "fake",
+			stream() {
+				const idx = callIndex++;
+				return (async function* () {
+					if (idx === 0) {
+						yield {
+							type: "tool-call",
+							toolCallId: "tc1",
+							toolName: "echo",
+							input: {},
+						} as ProviderEvent;
+						yield {
+							type: "usage",
+							usage: { inputTokens: 10, outputTokens: 5 },
+						} as ProviderEvent;
+						yield { type: "finish", reason: "tool-calls" } as ProviderEvent;
+					} else {
+						yield { type: "text-delta", delta: "Step2" } as ProviderEvent;
+						yield {
+							type: "usage",
+							usage: { inputTokens: 20, outputTokens: 10 },
+						} as ProviderEvent;
+						yield { type: "finish", reason: "stop" } as ProviderEvent;
+					}
+				})();
+			},
+		};
+
+		const { orchestrator } = createSessionOrchestrator({
+			conversationStore: store,
+			resolveProvider: () => provider,
+			resolveTools: () => [tool],
+			applyToolsFilter: identityApplyToolsFilter,
+			runTurn,
+			now: () => 1000,
+		});
+
+		await orchestrator.handleMessage({
+			conversationId: "conv-context-size",
+			text: "test",
+			onEvent: () => {},
+		});
+
+		const metrics = store.metricsData.get("conv-context-size");
+		expect(metrics).toBeDefined();
+		expect(metrics).toHaveLength(1);
+
+		const tm = metrics?.[0];
+		if (tm === undefined) throw new Error("expected metrics");
+
+		expect(tm.steps.length).toBeGreaterThanOrEqual(2);
+		expect(tm.contextSize).toBe(30);
+	});
+
 	it("does not persist metrics nor emit turn-sealed when chunk append fails", async () => {
 		const provider = createFakeProvider([
 			[
diff --git a/packages/transport-contract/package.json b/packages/transport-contract/package.json
index 7ebd2c2..5a2a61f 100644
--- a/packages/transport-contract/package.json
+++ b/packages/transport-contract/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@dispatch/transport-contract",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"type": "module",
 	"private": true,
 	"main": "dist/index.js",
diff --git a/packages/wire/package.json b/packages/wire/package.json
index 790c7e1..80671cf 100644
--- a/packages/wire/package.json
+++ b/packages/wire/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@dispatch/wire",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"type": "module",
 	"private": true,
 	"main": "dist/index.js",
diff --git a/packages/wire/src/index.ts b/packages/wire/src/index.ts
index aa6f9d0..52662ef 100644
--- a/packages/wire/src/index.ts
+++ b/packages/wire/src/index.ts
@@ -192,6 +192,16 @@ export interface TurnMetrics {
 	readonly durationMs?: number;
 	/** Per-step metrics in step order. */
 	readonly steps: readonly StepMetrics[];
+	/**
+	 * **Context size** — tokens the conversation occupies as of this turn: the
+	 * turn's FINAL step `inputTokens + outputTokens` (the last entry of `steps`),
+	 * NOT the aggregate `usage` (which sums per-step prompts and overcounts a
+	 * multi-step turn). The persisted, replayable counterpart of
+	 * `TurnDoneEvent.contextSize` and equal to it for the same turn. A client
+	 * reopening a past conversation reads the LAST turn's `contextSize` as the
+	 * current context usage. Optional: absent when no per-step usage was available.
+	 */
+	readonly contextSize?: number;
 }
 
 // ─── Outward events ─────────────────────────────────────────────────────────
@@ -364,6 +374,21 @@ export interface TurnDoneEvent {
 	 * provider reported no usage).
 	 */
 	readonly usage?: Usage;
+	/**
+	 * **Context size** — the number of tokens the conversation now occupies: this
+	 * (the most recent) turn's FINAL step `inputTokens + outputTokens` (the full
+	 * prompt sent into the last LLM round-trip plus that round-trip's output). This
+	 * is the "tokens in context" figure a client renders as the chat's current
+	 * context usage, and a client treats the LATEST turn's value as the live total.
+	 *
+	 * Deliberately NOT the aggregate `usage` above: `usage` SUMS each step's
+	 * `inputTokens`, which overcounts a multi-step / tool-calling turn because every
+	 * step re-prefills the growing prompt — the final step's input already includes
+	 * all prior context, so its input+output is the true occupancy. Optional: absent
+	 * when no per-step usage was observed this turn (mirrors `usage`). A later field
+	 * will carry the model's max context-window LIMIT; this is only the current size.
+	 */
+	readonly contextSize?: number;
 }
 
 /**