dsh-token-total 1.1.0 → 1.1.3

package/lib/index.js

@@ -1620,6 +1620,16 @@ function promptTokensOf(usage) {
 	const cached = Number(record?.cacheReadTokens) || 0;
 	return input + cached > 0 ? input + cached : null;
 }
+/** Prompt tokens one tool definition costs: its name, description and JSON
+*  schema, plus the framing every schema node pays. 0 for a nameless entry.
+*  Shared with the spend composition, which replays the same catalogue on
+*  every request. */
+function toolTokens(tool) {
+	const record = tool;
+	const name = String(record?.name ?? "");
+	if (name === "") return 0;
+	return estimateTokens(name) + valueTokens(record?.description) + estimateTokens(JSON.stringify(record?.parameters ?? {})) + TOOL_SCHEMA_OVERHEAD_TOKENS;
+}
 /** Fold one category's rows: keep the biggest until KEEP_SHARE is covered (and
 *  never more than MAX_ROWS_PER_CATEGORY), then merge the tail into one row so
 *  a session with 200 tool calls still yields a readable treemap. */
@@ -1774,10 +1784,10 @@ function buildSessionContextWindow(events) {
 	}
 	for (const summary of summaries) if (summary.tokens > 0) add("memory", "", summary.tokens, "compaction-summary");
 	for (const tool of tools) {
-		const record = tool;
-		const name = String(record?.name ?? "");
-		if (name === "") continue;
-		add("tools", name, estimateTokens(name) + valueTokens(record?.description) + estimateTokens(JSON.stringify(record?.parameters ?? {})) + TOOL_SCHEMA_OVERHEAD_TOKENS);
+		const tokens = toolTokens(tool);
+		const name = String(tool?.name ?? "");
+		if (name === "" || tokens === 0) continue;
+		add("tools", name, tokens);
 	}
 	const items = foldDrafts([...drafts.values()]);
 	return {
@@ -1793,6 +1803,197 @@ function buildSessionContextWindow(events) {
 	};
 }
 //#endregion
+//#region src/usage-buckets.ts
+const USAGE_BUCKET_ORDER = [
+	"systemPrompt",
+	"user",
+	"skill",
+	"toolResult",
+	"toolDef",
+	"injected",
+	"assistant",
+	"output"
+];
+USAGE_BUCKET_ORDER.filter((key) => key !== "output");
+//#endregion
+//#region src/usage-composition.ts
+/**
+* Spend composition: what the session's requests actually paid for, split by
+* what filled each prompt.
+*
+* The context-window snapshot answers "what is in the window NOW". This module
+* answers the other half of the picture: every provider request replays the
+* whole message list, so a session that made 300 calls paid for the system
+* prompt 300 times. The number the Token stats card shows per bucket is
+* therefore the sum of that bucket's size AT EVERY REQUEST — not its current
+* size, which would always favour whatever arrived last.
+*
+* The naive way to get that is to rebuild the replayed list per request, which
+* is O(requests × events) and far too slow for a view that polls every 1.5 s
+* over a long session. Instead this walks the log ONCE and keeps a live block
+* map with per-bucket subtotals: a request snapshots those subtotals (8 adds)
+* plus the tool catalogue total, and shadowed sequences subtract their block
+* the moment compaction prunes them. That is O(events + requests × 8).
+*
+* Token sizes are ESTIMATES from the same character-count estimator as
+* `context-window.ts` (the provider never reports a per-block number), so the
+* card labels them approximate. The billed total, cache split and request
+* count come straight from `usage` records and are exact.
+*/
+/** Shadowed sequences a compaction event removed from the replay list. */
+function shadowedSeqs(data) {
+	const seqs = [];
+	for (const seq of Array.isArray(data?.shadowedSeqs) ? data.shadowedSeqs : []) seqs.push(Number(seq));
+	const range = data?.shadowedRange;
+	if (typeof range?.start === "number" && typeof range?.end === "number") for (let seq = range.start; seq <= range.end; seq++) seqs.push(seq);
+	return seqs;
+}
+/**
+* Accumulate one session's own events into the eight legend buckets.
+*
+* Returns null for an empty log or a log whose requests never reported usage
+* (an older host writing no usage records) so the card can hide itself rather
+* than draw an empty ring.
+*/
+function buildSessionUsageComposition(events) {
+	if (events.length === 0) return null;
+	const ordered = [...events].sort((a, b) => a.seq - b.seq);
+	/** Blocks still replayed by the next request, keyed by their event sequence. */
+	const live = /* @__PURE__ */ new Map();
+	/** Current size of the replay list per bucket — what one request would send. */
+	const liveByBucket = /* @__PURE__ */ new Map();
+	/** What every request so far sent, summed per bucket. */
+	const acc = /* @__PURE__ */ new Map();
+	const totals = {
+		uncachedInputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	};
+	let billed = 0;
+	let requests = 0;
+	/** Prompt tokens the newest request/header's tool catalogue costs. */
+	let catalogue = 0;
+	const addBlock = (seq, bucket, tokens) => {
+		if (tokens <= 0) return;
+		live.set(seq, {
+			bucket,
+			tokens
+		});
+		liveByBucket.set(bucket, (liveByBucket.get(bucket) ?? 0) + tokens);
+	};
+	const dropBlock = (seq) => {
+		const block = live.get(seq);
+		if (block === void 0) return;
+		live.delete(seq);
+		liveByBucket.set(block.bucket, (liveByBucket.get(block.bucket) ?? 0) - block.tokens);
+	};
+	/** Charge one request for everything it replayed. */
+	const snapshot = () => {
+		for (const [bucket, tokens] of liveByBucket) if (tokens > 0) acc.set(bucket, (acc.get(bucket) ?? 0) + tokens);
+		if (catalogue > 0) acc.set("toolDef", (acc.get("toolDef") ?? 0) + catalogue);
+	};
+	/** Fold the provider's exact report into the billed split. */
+	const account = (usage) => {
+		const input = Number(usage?.inputTokens) || 0;
+		const cacheRead = Number(usage?.cacheReadTokens) || 0;
+		const cacheWrite = Number(usage?.cacheWriteTokens) || 0;
+		const output = Number(usage?.outputTokens) || 0;
+		totals.uncachedInputTokens += input;
+		totals.cacheReadTokens += cacheRead;
+		totals.cacheWriteTokens += cacheWrite;
+		totals.outputTokens += output;
+		billed += input + cacheRead + cacheWrite + output;
+		requests++;
+		if (output > 0) acc.set("output", (acc.get("output") ?? 0) + output);
+	};
+	for (const event of ordered) {
+		const data = event.data ?? {};
+		if (event.type === "compaction/prune" || event.type === "compaction/summary") {
+			if (event.type === "compaction/summary" && data.usage !== void 0 && data.usage !== null) {
+				snapshot();
+				account(data.usage);
+			}
+			for (const seq of shadowedSeqs(data)) dropBlock(seq);
+			if (event.type === "compaction/summary") addBlock(event.seq, "injected", messageTokens({ content: data.summary }));
+			continue;
+		}
+		if (event.type === "request/header") {
+			const header = data.header ?? {};
+			if (Array.isArray(header.tools)) {
+				catalogue = 0;
+				for (const tool of header.tools) catalogue += toolTokens(tool);
+			}
+			continue;
+		}
+		if (event.type === "assistant/message") {
+			if (data.usage !== void 0 && data.usage !== null) {
+				snapshot();
+				account(data.usage);
+			}
+			addBlock(event.seq, "assistant", messageTokens(data.message ?? { content: data.content }));
+			continue;
+		}
+		if (event.type === "system/message") {
+			const bucket = String(data.message?.source?.kind ?? data.source?.kind ?? "system-prompt") === "system-prompt" ? "systemPrompt" : "injected";
+			addBlock(event.seq, bucket, messageTokens(data.message ?? { content: data.content }));
+			continue;
+		}
+		if (event.type === "user/message") {
+			const kind = String(data.source?.kind ?? data.message?.source?.kind ?? "user");
+			const bucket = kind === "user" ? "user" : kind === "skill-catalog" ? "skill" : "injected";
+			addBlock(event.seq, bucket, messageTokens(data.message ?? { content: data.content }));
+			continue;
+		}
+		if (event.type === "tool/result") {
+			addBlock(event.seq, "toolResult", messageTokens(data.message ?? {}));
+			continue;
+		}
+	}
+	if (requests === 0) return null;
+	return {
+		buckets: USAGE_BUCKET_ORDER.map((key) => ({
+			key,
+			tokens: Math.max(0, Math.round(acc.get(key) ?? 0))
+		})),
+		billedTokens: billed,
+		totals,
+		requests
+	};
+}
+/** Add one tree's compositions into the root's, matching its other aggregates. */
+function mergeUsageCompositions(parts) {
+	const present = parts.filter((part) => part !== null && part !== void 0);
+	if (present.length === 0) return null;
+	const acc = /* @__PURE__ */ new Map();
+	const totals = {
+		uncachedInputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	};
+	let billed = 0;
+	let requests = 0;
+	for (const part of present) {
+		for (const bucket of part.buckets) acc.set(bucket.key, (acc.get(bucket.key) ?? 0) + bucket.tokens);
+		totals.uncachedInputTokens += part.totals.uncachedInputTokens;
+		totals.cacheReadTokens += part.totals.cacheReadTokens;
+		totals.cacheWriteTokens += part.totals.cacheWriteTokens;
+		totals.outputTokens += part.totals.outputTokens;
+		billed += part.billedTokens;
+		requests += part.requests;
+	}
+	return {
+		buckets: USAGE_BUCKET_ORDER.map((key) => ({
+			key,
+			tokens: acc.get(key) ?? 0
+		})),
+		billedTokens: billed,
+		totals,
+		requests
+	};
+}
+//#endregion
 //#region src/session-detail.ts
 const zero = () => ({
 	uncachedInputTokens: 0,
@@ -2120,7 +2321,8 @@ async function one(p, id, header, live) {
 		requests,
 		averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null,
 		tokensPerSecond: decodeRateOf(records),
-		context: buildSessionContextWindow(own)
+		context: buildSessionContextWindow(own),
+		composition: buildSessionUsageComposition(own)
 	};
 }
 async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
@@ -2220,7 +2422,8 @@ async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
 		}),
 		records,
 		routes: [...routeMap.values()],
-		context: parts[0]?.context ?? null
+		context: parts[0]?.context ?? null,
+		composition: mergeUsageCompositions(parts.map((p) => p.composition))
 	};
 }
 //#endregion

package/lib/types/client/UsageCards.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two cards that replaced the context-window panel.
+ *
+ * Left: what the window holds RIGHT NOW (the context snapshot). Right: what the
+ * session's requests actually spent, split by content (the spend composition).
+ * They answer two different questions — "what is in the prompt" and "what did
+ * the whole session pay for" — so they sit side by side at equal weight rather
+ * than one above the other.
+ *
+ * Everything is drawn from the detail payload the view already polls every
+ * 1.5 s (`useSessionDetail`), so both cards refresh with no extra timer. The
+ * charts are hand-rolled SVG/CSS: the plugin ships no chart dependency, and a
+ * ring plus a stacked bar is little enough markup to keep it that way.
+ *
+ * The palette is the plugin's tone scale, matching the stat cards above and the
+ * dashboard charts; dark values flip under `body[data-ds-dark-theme]` (the
+ * host's own theme switch), and every surface uses the host's semantic tokens
+ * so the cards sit on the same canvas as the tables.
+ */
+import type { SessionUsageDetail } from '../wire.ts';
+import type { SessionUsageKey } from './session-usage-locales.ts';
+type T = (key: SessionUsageKey, params?: Record<string, string>) => string;
+/** The pair, rendered where the context-window panel used to sit. */
+export declare function SessionUsageCards({ detail, t }: {
+    detail: SessionUsageDetail;
+    t: T;
+}): JSX.Element | null;
+export {};

package/lib/types/client/context-window-core.d.ts

@@ -4,6 +4,7 @@
  * separate from the component so both are testable without a DOM.
  */
 import type { SessionContextCategory, SessionContextItem, SessionContextWindow } from '../wire.ts';
+import type { SessionUsageBucket } from '../wire.ts';
 /** Legend order, also the color assignment order (see the CSS module). */
 export declare const CONTEXT_CATEGORY_ORDER: readonly SessionContextCategory[];
 /** One positioned treemap block in container pixels. */
@@ -19,6 +20,14 @@ export declare function contextCategoryTotals(items: readonly SessionContextItem
     key: SessionContextCategory;
     tokens: number;
 }>;
+/** The live window folded into the same legend the spend card prints, in
+ *  legend order and keeping zero buckets so both cards stay aligned. */
+export declare function contextBucketTotals(items: readonly SessionContextItem[]): Array<{
+    key: SessionUsageBucket;
+    tokens: number;
+}>;
+/** What a share of the whole is, for the legend column. */
+export declare function bucketPercent(tokens: number, total: number): number;
 /** Window occupancy in whole percent, or null when the host never reported the
  *  model's window (the panel then says "unknown" instead of guessing one). */
 export declare function contextWindowPercent(usedTokens: number, contextWindow: number | null): number | null;

package/lib/types/client/session-usage-locales.d.ts

@@ -60,6 +60,7 @@ export declare const usageZh: {
     asOf: string;
     refresh: string;
     contextTitle: string;
+    currentContextTitle: string;
     contextUsed: string;
     contextLive: string;
     contextWindowKnown: string;
@@ -90,6 +91,22 @@ export declare const usageZh: {
     contextTipShare: string;
     contextTipWindow: string;
     contextEstimateNote: string;
+    statsTitle: string;
+    statsTotal: string;
+    statsCacheHit: string;
+    statsIncludesThinking: string;
+    statsEmpty: string;
+    contextWindowTotal: string;
+    contextWindowTotalUnknown: string;
+    contextUsedShort: string;
+    bucketSystemPrompt: string;
+    bucketUser: string;
+    bucketSkill: string;
+    bucketToolResult: string;
+    bucketToolDef: string;
+    bucketInjected: string;
+    bucketAssistant: string;
+    bucketOutput: string;
 };
 export type SessionUsageKey = keyof typeof usageZh;
 export declare const usageEn: Record<SessionUsageKey, string>;

package/lib/types/context-window.d.ts

@@ -31,6 +31,11 @@ import type { SessionContextWindow } from './wire.ts';
 export declare function estimateTokens(text: string): number;
 /** Approximate tokens of one replayed message (content + framing). */
 export declare function messageTokens(message: unknown): number;
+/** Prompt tokens one tool definition costs: its name, description and JSON
+ *  schema, plus the framing every schema node pays. 0 for a nameless entry.
+ *  Shared with the spend composition, which replays the same catalogue on
+ *  every request. */
+export declare function toolTokens(tool: unknown): number;
 /** Build the context-window snapshot from one session's own events. Returns
  *  null for an empty log so the panel can hide itself. */
 export declare function buildSessionContextWindow(events: readonly UsageSessionEvent[]): SessionContextWindow | null;

package/lib/types/usage-buckets.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The legend order of the Token stats card, shared by the host accumulator and
+ * the client card so the two halves can never disagree about which bucket sits
+ * where. Left column first (what filled the prompt), right column second: the
+ * layout mirrors the reference design — system/user/skill/results on the left,
+ * tool definitions/injected/assistant/output on the right.
+ *
+ * Kept in its own dependency-free module: the host builds the numbers and the
+ * client paints them, and neither should pull the other's graph in for this.
+ */
+import type { SessionUsageBucket } from './wire.ts';
+export declare const USAGE_BUCKET_ORDER: readonly SessionUsageBucket[];
+/** The buckets that describe the live window (output never occupies it). */
+export declare const CONTEXT_BUCKET_ORDER: readonly SessionUsageBucket[];

package/lib/types/usage-composition.d.ts

@@ -0,0 +1,12 @@
+import type { UsageSessionEvent } from './context-types.ts';
+import type { SessionUsageComposition } from './wire.ts';
+/**
+ * Accumulate one session's own events into the eight legend buckets.
+ *
+ * Returns null for an empty log or a log whose requests never reported usage
+ * (an older host writing no usage records) so the card can hide itself rather
+ * than draw an empty ring.
+ */
+export declare function buildSessionUsageComposition(events: readonly UsageSessionEvent[]): SessionUsageComposition | null;
+/** Add one tree's compositions into the root's, matching its other aggregates. */
+export declare function mergeUsageCompositions(parts: ReadonlyArray<SessionUsageComposition | null | undefined>): SessionUsageComposition | null;

package/lib/types/wire.d.ts

@@ -191,6 +191,36 @@ export interface SessionUsageDetail {
     /** The root session's live context composition, rendered above the cards.
      *  Null when the log has no readable events (or on an older host). */
     context?: SessionContextWindow | null;
+    /** What the session's requests spent, split by what filled the prompt.
+     *  Null when the log has no readable usage (or on an older host). */
+    composition?: SessionUsageComposition | null;
+}
+/** The eight buckets the Token stats card names, in legend order: the left
+ *  column first (prompt composition), then the right column. */
+export type SessionUsageBucket = 'systemPrompt' | 'user' | 'skill' | 'toolResult' | 'toolDef' | 'injected' | 'assistant' | 'output';
+/** One session tree's spend split by prompt content.
+ *
+ *  Every provider request replays the whole message list, so a bucket's number
+ *  is what that bucket contributed ACROSS ALL REQUESTS, not its size in the
+ *  window today. The replay figures are ESTIMATES (character counts, the same
+ *  estimator the context-window snapshot uses) because the provider only bills
+ *  a whole prompt; the billed total and its cache split are exact and drive
+ *  the headline and the cache-hit badge. */
+export interface SessionUsageComposition {
+    /** Estimated replay tokens per bucket, in legend order (kept at 0 when a
+     *  bucket never appeared so the card can keep a stable order). */
+    buckets: Array<{
+        key: SessionUsageBucket;
+        tokens: number;
+    }>;
+    /** Exact provider-billed total across the same requests (prompt including
+     *  cached tokens, plus output). */
+    billedTokens: number;
+    /** The same spend split into the four billing buckets, for the cache badge
+     *  and any future detail row. */
+    totals: SessionUsageTotals;
+    /** How many provider answers the accumulation covers (compaction included). */
+    requests: number;
 }
 /** The six buckets the context-window panel paints, in legend order. They are
  *  the buckets a reader thinks in: the harness prompt, the tool catalogue, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-token-total",
-  "version": "1.1.0",
+  "version": "1.1.3",
   "description": "DSH web plugin: token 用量统计看板 + 单会话（主智能体 + 子智能体）用量统计。提供今日/近3天/近7天/近1月/近3月/自定义筛选、六个汇总卡片、活跃热力图、缓存命中率折线与分模型柱状图、按模型/按供应商 Top5 列表。",
   "icon": "./icon.svg",
   "type": "module",

package/src/client/SessionUsageView.tsx

@@ -5,7 +5,7 @@ import { billedTotal, cacheHitPercentOf } from './session-usage-core.ts'
 import { formatCompact, formatTokens, normalizeModelName, decodeRateOf } from './format.ts'
 import { SESSION_USAGE_NS, type SessionUsageKey } from './session-usage-locales.ts'
 import { useSessionDetail } from './use-session-detail.ts'
-import { ContextWindowPanel } from './ContextWindowPanel.tsx'
+import { SessionUsageCards } from './UsageCards.tsx'
 import { ModelLogo } from './ModelLogo.tsx'
 import css from './SessionUsageView.module.css'
 
@@ -206,11 +206,11 @@ function Records({ detail, t }: { detail: SessionUsageDetail; t: T }): JSX.Eleme
 export function SessionUsageContent({ detail, t, updatedAt }: { detail: SessionUsageDetail; t: T; updatedAt?: number | null }): JSX.Element {
   return <>
     <p className={css.scope}>{t('scope')}</p><Metrics detail={detail} t={t} /><Tables detail={detail} t={t} />
-    {/* The context window sits between the per-subagent/model tables and the
-        request records: it describes what the next request carries right now,
-        while everything above is spent-token history and everything below is
-        per-turn detail. */}
-    {detail.context ? <ContextWindowPanel context={detail.context} t={t} updatedAt={updatedAt} /> : null}
+    {/* The two live cards sit between the per-subagent/model tables and the
+        request records: the left one describes what the next request carries
+        right now, the right one what the whole session spent, while everything
+        above is spent-token history and everything below is per-turn detail. */}
+    <SessionUsageCards detail={detail} t={t} />
     <Records key={detail.sessionId} detail={detail} t={t} /><p className={css.note}>{t('note')}</p>
   </>
 }

package/src/client/StatsLineEnhanced.tsx

@@ -31,9 +31,14 @@
  * cannot see.
  *
  * Streaming throughput replaces the gauge pill's speed
- * figure with a live estimate while a step is still streaming and drops back to
- * the official session figure the moment it settles. That subscription lives in
- * its own child component so stream deltas never re-render the pills. The live
+ * figure with a live estimate of what is happening now, and hands the slot back
+ * to the session's decode average when nothing is streaming. While a step
+ * streams the live rate is the only reading that can match the pace of the
+ * answer on screen; once the step settles it becomes a figure from a window
+ * nobody is watching any more, so the pill returns to the same quotient the
+ * usage view quotes (ΣoutputTokens / ΣdecodeMs) instead of freezing on the last
+ * measurement. That subscription lives in its own child component, so stream
+ * deltas never re-render the pills. The live
  * figure itself is measured by a bounded sliding window over observed token
  * growth (stats-line-core's StreamingRateSampler): the earlier cumulative
  * quotient charged a whole step's text to a window that had just opened, so a
@@ -176,29 +181,43 @@ const LIVE_SPEED_REFRESH_MS = 1_000
  * The gauge pill's always-on streaming speed slot.
  *
  * It subscribes to `legacy.partial` itself so per-frame deltas re-render only
- * this child, not the surrounding pills. Until the streaming step has a
- * measurable window the official session
- * figure stays on screen, so the slot is never empty and the handover at
- * settle is a plain value change.
+ * this child, not the surrounding pills. Two figures share the slot, chosen by
+ * whether a step is streaming right now:
+ *
+ * - while one is (`partial != null`), the measured rate of THAT stream — a
+ *   bounded sliding window over observed token growth (stats-line-core's
+ *   StreamingRateSampler), the only reading that can track the pace of the
+ *   answer currently on screen;
+ * - otherwise the session's own decode average, ΣoutputTokens / ΣdecodeMs —
+ *   the same quotient `decodeRateOf` quotes in the usage view. An idle composer
+ *   must not freeze on whatever the last window happened to measure: a settled
+ *   thirty-step turn kept showing its final second-long reading (57 tok/s)
+ *   beside the usage view's 156 tok/s for the same work, and the two read as a
+ *   contradiction rather than as two scopes of one number.
+ *
+ * The measured reading carries the step it was taken in, so a new step cannot
+ * inherit the previous one's figure before its own window publishes; nothing is
+ * held across the gap — the gap is exactly when the average applies.
  *
  * One window covers a whole step, across every output kind the accumulator
  * carries — reasoning, answer text, and Tool-call arguments — because the
  * provider bills all three as completion tokens and a step emits them in
- * sequence. Between steps the partial is gone (the step's assistant/message
- * settles it and the next step has not begun), so Tool execution shows the
- * official figure until the next step opens its own window.
+ * sequence.
  *
  * Sampling happens in a layout effect and the figure it yields is published as
  * state, so no render reads a clock or mutates the window: a render React starts
  * and then discards must not decide what the next committed one displays. The
  * rate itself comes from stats-line-core's StreamingRateSampler — a bounded
- * window over observed token growth, smoothed, and held while nothing arrives.
+ * window over observed token growth, smoothed, and held while nothing arrives
+ * inside the step it belongs to.
  */
 function LiveSpeed({ useChat, scale, fallback, t }: {
   useChat: ChatSnapshotSelectorHook
   /** Correction measured from this session's settled steps (1 = raw prior). */
   scale: number
-  /** The official session figure, shown until the estimate means something. */
+  /** The session's own decode average (ΣoutputTokens / ΣdecodeMs): what the
+   *  slot shows whenever no step is streaming, and before the streaming step's
+   *  window has published its first reading. */
   fallback: string | null
   t: T
 }) {
@@ -216,19 +235,22 @@ function LiveSpeed({ useChat, scale, fallback, t }: {
     sampler.current = { key, rate: new StreamingRateSampler() }
   }
   const rate = sampler.current.rate
-  // The reading the effect below produced, tagged with the step it describes. The
-  // tag is what keeps a switch honest: the frame after a switch renders before the
-  // new step's first observation lands, and without it that frame would show the
-  // previous step's rate.
-  const [published, setPublished] = useState<{ key: string | null; rate: number | null }>({
-    key: null,
-    rate: null,
-  })
+  // The figure last measured, tagged with the step it came from. The tag is
+  // what retires it: a reading taken in 3:4 never shows during 3:5, and with
+  // no step streaming (`key === null`) no tag can match at all, so the slot
+  // falls through to the session average on its own — no timer, no clearing
+  // effect, and no stale figure left standing after a turn settles.
+  const [reading, setReading] = useState<{ key: string; value: number } | null>(null)
   const scaleRef = useRef(scale)
   // Every delta re-runs this (its dependencies move), and the beat re-runs it once
   // a second so a step that has gone quiet still advances its window.
   const [beat, setBeat] = useState(0)
   useLayoutEffect(() => {
+    // Nothing is streaming: the slot shows the session average, and there is no
+    // window to advance. Skipping the observation also keeps a settled step's
+    // sampler from being fed a zero estimate, which would re-anchor it against
+    // text that is already counted.
+    if (key === null) return
     // A correction that moved re-prices the whole estimate, so growth already
     // counted under the old one must not be measured against the new one: that
     // would read as a burst the stream never produced.
@@ -237,10 +259,15 @@ function LiveSpeed({ useChat, scale, fallback, t }: {
       rate.reset()
     }
     rate.observe(tokens, Date.now())
+    // A null here means the fresh window has not measured anything yet (a step
+    // that just opened, or one that re-anchored); the average stays up until
+    // this step's own window publishes something.
     const next = rate.ratePerSecond()
-    setPublished((previous) => (
-      previous.key === key && previous.rate === next ? previous : { key, rate: next }
-    ))
+    if (next !== null) {
+      setReading(previous => (previous !== null && previous.key === key && previous.value === next
+        ? previous
+        : { key, value: next }))
+    }
   }, [tokens, key, beat, rate, scale])
   // Keyed on "a step is streaming", not on the step identity: switching steps
   // must not tear the beat down and defer the next one by a full period.
@@ -250,10 +277,12 @@ function LiveSpeed({ useChat, scale, fallback, t }: {
     const handle = setInterval(() => { setBeat(Date.now()) }, LIVE_SPEED_REFRESH_MS)
     return () => { clearInterval(handle) }
   }, [streaming])
-  const reading = published.key === key ? published.rate : null
-  return <SpeedFigure text={reading === null
+  // The tag test is the whole selection rule: a reading only shows while the
+  // step that produced it is the step streaming now.
+  const measured = reading !== null && reading.key === key ? reading.value : null
+  return <SpeedFigure text={measured === null
     ? fallback
-    : t('stats.tokensPerSecond', { throughput: formatTokensPerSecond(reading) })} />
+    : t('stats.tokensPerSecond', { throughput: formatTokensPerSecond(measured) })} />
 }
 
 function TimePill({ stats, t, dialog, useChat, scale, dock }: {
@@ -270,9 +299,10 @@ function TimePill({ stats, t, dialog, useChat, scale, dock }: {
 }) {
   const { open, setOpen, rootRef, panelRef, pos } = useStatDialog(dialog)
   const counts = t('stats.counts', { turns: stats.turns, steps: stats.steps })
-  // The pill's accessible name stays on the official figure: a screen reader
-  // gets the durable session reading rather than a value that changes every
-  // second while a step streams.
+  // The session figure now serves both jobs: the pill's accessible name (a
+  // screen reader gets the durable session reading rather than a value that
+  // changes every second while a step streams) and the visible figure whenever
+  // no step is streaming.
   const officialTps = stats.decodeMs > 0
     ? t('stats.tokensPerSecond', {
       throughput: formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000)),