Merge remote-tracking branch 'origin/master' into feat/todo-multi-in-progress

# Conflicts:
#	docs/core-data-structures/session.i18n.yaml
#	packages/client/ui-conversation/README.i18n.yaml

.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
+2026-08-05-context-meter-blind-to-compaction.md: ab39ae4e109f238960fd60de5e5b61075344f525
+2026-08-05-context-meter-blind-to-compaction.zh.md: c93aa509530e48acf906b18ba85bab4c7d355d69

.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md

@@ -0,0 +1,46 @@
+# Agent Note: the context meter could not see a compaction
+
+Status: implemented
+
+English | [中文](2026-08-05-context-meter-blind-to-compaction.zh.md)
+
+## Problem
+
+The composer's [context meter](../feature/2026-08-05-composer-context-meter-breakdown.md) took its ring, percentage, and `~used / capacity` header from `contextPressure.pressureTokens`, the newest provider-reported prompt size. That number moves only when a request reports usage, and compaction reports none: `compact-basic` summarizes through a direct `ctx.llm.stream()` call and appends `compact/start`, `compact/summary`, the replacement `user/message`, and `compact/end` — no `assistant/message`, no usage chunk.
+
+So the meter was frozen across the one action taken to change it. Driving a real `compactNow` through the agent loop:
+
+```
+BEFORE compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages 4365]
+AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages  286]
+```
+
+The composition rows, which fold the surface, dropped by 93%. The ring — the primary affordance, and the reason a user opens the panel right after compacting — did not move at all, and would not until an entire further turn completed. The panel then showed a header and rows disagreeing by more than an order of magnitude, at exactly the moment a reader was most likely to add the rows up.
+
+## Decision
+
+`contextPressure` publishes a second numerator, `projectedTokens`: the provider sample plus the heuristic repricing of everything the surface gained or lost since that sample was taken, clamped at zero. The fold carries the priced surface through the shared `surface-fold.ts` and stamps `sampledSurfaceTokens` when a usage sample lands — **before** the same event joins the surface, so an `assistant/message` anchors against the surface its own request actually carried. `stateVersion` moves to 3.
+
+Only the delta is estimated. The anchor stays provider-exact, which keeps the estimator's systematic CJK and JSON-schema underpricing out of the occupancy figure while still letting the number react the moment content lands or a span is shadowed. `contextOccupancy` reads `projectedTokens` and falls back to the bare sample, so a projection restored from a pre-field checkpoint degrades to the old behavior instead of vanishing.
+
+This reverses the "the ring, header, and bar length stay provider-exact" half of the [context meter decision](../feature/2026-08-05-composer-context-meter-breakdown.md). What that decision was protecting — not fabricating precision by scaling heuristic rows to a provider total — is preserved: the rows are still unscaled, and the header still does not equal their sum. What changed is the recognition that "provider-exact but describing a request two compactions ago" is not the more truthful figure.
+
+## Alternatives considered
+
+**Project `measure().totalTokens` instead.** The measurement service already composes exactly this (`baseline` anchor plus signed `surfaceDeltaTokens`), and it reacts correctly — measured at 4383 → 304 across the same compaction. But it is a service over private replay state, not a pure fold, and a projection cannot call it. Reproducing its anchor inside a `ProjectionDefinition` needs `_estimateProviderAssistant`'s random access to the chunk provenance (`session.events[seq]`), which `apply(state, event)` does not have. Anchoring on the sampled surface total is the same idea reachable from a pure per-event fold.
+
+**Emit a synthetic usage record at the end of compaction.** Would move `pressureTokens` itself, but the only usage compaction holds is the summarization request's own — a different prompt entirely. Recording it as the conversation's prompt size would be a lie in the durable log rather than in one display.
+
+**Let the UI subtract, exposing `sampledSurfaceTokens` and reading `contextBreakdown.messageTokens`.** Splits one figure's arithmetic across two projections and the client. The host owns the vocabulary; it should publish the whole value.
+
+## Consequences
+
+Occupancy now advances with every surface event rather than once per turn, so the ring creeps up as a turn produces tool results instead of jumping at its end — and drops the instant a compaction lands. That is more projection frames on the wire: one per surface event for `contextPressure`, the rate `contextBreakdown` already ran at.
+
+The panel's composition rows still do not sum to the header, and now for one clearly-stated reason instead of two: the rows carry the estimator's error, the header's anchor does not. The remaining lever is estimator accuracy (CJK-aware weighting in `estimate.ts`), which changes no seam.
+
+`sampledSurfaceTokens` assumes nothing joins the surface between a step's request and its usage report. The loop admits steering and context before `buildRequest` and drains tool results after `assistant/message`, so that holds; if it ever stops holding, the error is bounded by one message and self-corrects at the next sample.
+
+## Testing
+
+`packages/llm/token-meter/tests/token-usage-projection.spec.ts` covers the carry-forward across surface growth and a compaction (the sample holding still while the projection shrinks) and the zero clamp when heuristic error would drive the figure negative. `packages/client/ui-conversation/tests/context-meter.spec.tsx` pins the ring reading the projected figure, and `chat-stats-bash-sample.spec.tsx` pins `contextOccupancy`'s preference and its fallback. The end-to-end numbers above came from driving `BasicCompactService.compactNow` through a real `AgentLoop` with the projection registry mounted.

.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md

@@ -0,0 +1,46 @@
+# Agent Note：上下文仪表看不见压缩
+
+Status: implemented
+
+[English](2026-08-05-context-meter-blind-to-compaction.md) | 中文
+
+## 问题
+
+composer 的[上下文仪表](../feature/2026-08-05-composer-context-meter-breakdown.md)的圆环、百分比与 `~已用 / 容量` 标题都取自 `contextPressure.pressureTokens`，即提供方报告的最新提示词规模。这个数字只在某个请求报告用量时才会移动，而压缩不报告用量：`compact-basic` 通过直连的 `ctx.llm.stream()` 调用生成摘要，只追加 `compact/start`、`compact/summary`、用作替换的 `user/message` 和 `compact/end`——没有 `assistant/message`，也没有用量分片。
+
+于是在唯一一个专门用来改变它的操作面前，这块仪表纹丝不动。通过真实 agent loop 驱动一次 `compactNow`：
+
+```
+BEFORE compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages 4365]
+AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages  286]
+```
+
+折叠表层得出的组成明细行下降了 93%。而圆环——那个主要的可操作元素，也正是用户压缩完立刻会去点开面板的理由——完全没动，而且要等到又跑完一整轮才会动。此时面板上的标题与明细行相差一个数量级以上，恰恰发生在读者最可能去把明细行加总的时刻。
+
+## 决策
+
+`contextPressure` 发布第二个分子 `projectedTokens`：在提供方样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零。该折叠通过共享的 `surface-fold.ts` 携带已计价的表层，并在用量样本落地时记下 `sampledSurfaceTokens`——记录时机在同一条事件加入表层**之前**，因此 `assistant/message` 锚定的正是它自己那次请求实际携带的表层。`stateVersion` 提升到 3。
+
+只有增量部分是估算的。锚点保持提供方精确值，从而把估算器对 CJK 文本与 JSON schema 的系统性低估挡在占用率数字之外，同时又让这个数字能在内容落地或某段区间被遮蔽的瞬间做出反应。`contextOccupancy` 读取 `projectedTokens`，并回退到裸样本，因此从不含该字段的检查点恢复出来的投影会退化为旧行为，而不是直接消失。
+
+这推翻了[上下文仪表决策](../feature/2026-08-05-composer-context-meter-breakdown.md)中「圆环、标题与进度条总长保持提供方精确值」的那一半。那条决策真正想守住的东西——不要把启发式明细行按比例缩放到提供方总量、从而伪造精度——依然守住了：明细行仍未被缩放，标题仍不等于它们之和。改变的是这样一个认识：「提供方精确、但描述的是两次压缩之前那个请求」并不是更真实的数字。
+
+## 备选方案
+
+**改为投影 `measure().totalTokens`。** 测量服务本来就合成了正是这个量（`baseline` 锚点加有符号的 `surfaceDeltaTokens`），而且反应正确——同一次压缩前后实测为 4383 → 304。但它是一个建立在私有重放状态上的服务，不是纯折叠，投影无法调用它。要在 `ProjectionDefinition` 内部复现它的锚点，需要 `_estimateProviderAssistant` 对分片来源的随机访问（`session.events[seq]`），而 `apply(state, event)` 拿不到。以取样时的表层总量作为锚点，是同一个思路在纯逐事件折叠中可达的版本。
+
+**在压缩结束时补写一条合成的用量记录。** 这确实能推动 `pressureTokens` 本身，但压缩手上唯一的用量是摘要请求自己的用量——那是完全另一个提示词。把它记成本对话的提示词规模，等于把谎言写进持久日志，而不只是写进某一处展示。
+
+**让 UI 自己做减法：暴露 `sampledSurfaceTokens`，再读 `contextBreakdown.messageTokens`。** 这会把一个数字的算术拆散到两个投影和客户端三处。词汇的所有者是宿主，就应当由它发布完整值。
+
+## 影响
+
+占用率现在随每个表层事件推进，而不再是每轮跳一次，因此一轮中产生工具结果时圆环会持续爬升，而不是等到轮次结束才跳变——压缩落地的瞬间它也会掉下来。代价是线路上多了投影帧：`contextPressure` 每个表层事件推一帧，也就是 `contextBreakdown` 本来就在跑的频率。
+
+面板的组成明细行仍然加不出标题数字，但现在只剩一个能讲清楚的原因，而不是两个：明细行带着估算器的误差，标题的锚点不带。剩下的抓手是估算精度（在 `estimate.ts` 里做 CJK 感知加权），它不改动任何 seam。
+
+`sampledSurfaceTokens` 依赖一个前提：在某个步骤的请求与它的用量报告之间，不会有新内容加入表层。循环在 `buildRequest` 之前接纳 steering 与 context，在 `assistant/message` 之后才排空工具结果，因此该前提成立；即便将来不再成立，误差也被限制在一条消息以内，并在下一个样本处自行纠正。
+
+## 测试
+
+`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats-bash-sample.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。

.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md
+2026-08-04-web-latency-throughput-metrics.md: 4d7627a9a38127259f1ba07121cea7282f794f2e
+2026-08-04-web-latency-throughput-metrics.zh.md: 09e59242b799a3f4d03b9e0259f1a5a0d85f6a53

.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md

@@ -0,0 +1,31 @@
+# Agent Note: Web turn and window latency/throughput metrics
+
+Status: implemented
+
+English | [中文](2026-08-04-web-latency-throughput-metrics.zh.md)
+
+## Problem
+
+The Web chat records per-step LLM timing (`stepStartTime` / `firstTokenTime` / `completedTime`) and per-step usage, and the trajectory view exposes them per step, but the chat surface answers neither "how responsive was this turn" nor "how fast is this session going": the assistant footer shows only the turn wall time, and the stats line folds only wall-time totals.
+
+## Decision
+
+A package-local fold, `ui-conversation`'s `chat/turn-metrics.ts`, is the single derivation from assistant nodes to latency/throughput readings. `assistantStepReading` turns one node into a step reading: TTFT needs both `stepStartTime` and `firstTokenTime`, decode span needs `firstTokenTime`, negative spans clamp to zero, and output tokens come from the untrusted `usage` value only when they are finite and non-negative. `deriveTurnMetrics` folds readings per turn: the lowest-numbered step owns the turn's TTFT slot, and throughput divides the summed output tokens by the summed decode spans over exactly the steps carrying both, so an unsampled step drops out instead of skewing the ratio; a turn with neither figure emits no entry.
+
+The assistant footer appends the readings to the existing hover-revealed time chrome after `Ran for`, as `TTFT {s}s · {tps} tok/s`, each omitted independently when unrecorded. ChatView shows a turn's readings only when that turn's `turnTimings` entry has an `endTime`: the loaded window is a contiguous log suffix, so an in-window settled turn carries every one of its steps and the first-step TTFT is genuine rather than a window artifact. `formatLatencySeconds` is unit-less so each locale template owns its second suffix (`TTFT {seconds}s` / `首 token {seconds}秒`).
+
+The stats line reuses the same step reading in its window fold: `deriveStats` accumulates TTFT sum/count and decode span/tokens, rendering a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English) beside the LLM/tool wall times. The turn-count, step-count, duration, cache, and token labels use the same namespace. Like those wall times the group is window-scoped and folds no billing; token accounting stays on the token-meter projections.
+
+## Alternatives considered
+
+**A durable session projection (token-meter shape).** A `ProjectionDefinition` folding step timings host-side would survive compaction and window paging and cover the whole log. Deferred, not rejected: projection state must stay O(1) (averages, not percentiles), it needs a host change plus a schema, and the chat stats line is already documented as window-scoped for its duration facts — the new group joins that scope. A later PR can add the durable projection without moving these readings.
+
+**Per-step footer chrome.** Showing each assistant message its own TTFT would attach chrome to mid-turn narration nodes, which the footer design deliberately keeps chrome-free; the trajectory view already exposes per-step timing detail.
+
+**Gating footer metrics on node presence instead of `turn/end` timing.** Rendering whatever steps happen to be loaded would show a plausible-looking TTFT that is actually the first *loaded* step after paging. The `endTime` gate plus the suffix-window invariant makes the displayed figure the turn's true first-step latency or nothing.
+
+## Consequences
+
+A settled in-window turn's footer reveals `TTFT`/`tok/s` on hover after the wall time, and the stats line shows window-average latency and throughput with localized labels beside its wall times, all without new session events or host changes. Metrics degrade by omission: providers or steps without timing or usage samples drop individual figures rather than rendering zeros. Older history outside the loaded window stays uncounted, recorded in the package README's stats-line limitation.
+
+Both readings divide by measured wall time, so neither is reproducible: the same replayed scenario yielded 69 and 70 tok/s on consecutive local runs, and a 3 ms replayed stream reads 26333 tok/s. The Web aria goldens therefore normalize throughput to `{{throughput}}` beside the existing `{{duration}}`, and the footer's decorative separators gained flanking spaces — without them the readings concatenate into one accessible string (`Ran for 13sTTFT 0.2s12 tok/s`), which both loses the reading boundaries a screen reader needs and denies `{{duration}}` the word boundary it matches on.

.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md

@@ -0,0 +1,31 @@
+# Agent Note: Web 轮次与窗口级延迟/吞吐指标
+
+Status: implemented
+
+[English](2026-08-04-web-latency-throughput-metrics.md) | 中文
+
+## 问题
+
+Web 聊天已经记录了逐步骤的 LLM 计时（`stepStartTime`／`firstTokenTime`／`completedTime`）和逐步骤 usage，trajectory 视图也按步骤展示它们，但聊天界面既回答不了「这一轮响应有多快」，也回答不了「这个会话跑得有多快」：assistant 页脚只显示轮次实际耗时，统计行也只折算墙钟时间总量。
+
+## 决策
+
+包内折算 `ui-conversation` 的 `chat/turn-metrics.ts` 是从 assistant 节点推导延迟/吞吐读数的唯一位置。`assistantStepReading` 把一个节点转成一次步骤读数：TTFT（首 token 延迟）需要 `stepStartTime` 与 `firstTokenTime` 同时存在，解码时长需要 `firstTokenTime`，负时长收敛为零，输出 token 数只在不可信的 `usage` 值有限且非负时才采纳。`deriveTurnMetrics` 按轮次折算读数：编号最小的步骤拥有该轮次的 TTFT 槽位，吞吐用「同时携带两者的那些步骤」的输出 token 总和除以解码时长总和，因此缺采样的步骤直接退出而不是让比值失真；两个数字都没有的轮次不产生条目。
+
+assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、`用时` 之后，形如 `首 token {s}秒 · {tps} tok/s`，未记录的数字各自省略。ChatView 仅在该轮次的 `turnTimings` 条目带有 `endTime` 时才显示读数：已加载窗口是日志的连续后缀，因此窗口内已结算的轮次必然带着它的全部步骤，首步 TTFT 是真实值而非窗口截断的产物。`formatLatencySeconds` 不带单位，各语言模板各自拥有秒后缀（`TTFT {seconds}s`／`首 token {seconds}秒`）。
+
+统计行在其窗口折算中复用同一份步骤读数：`deriveStats` 累计 TTFT 总和／计数与解码时长／token 数，在 LLM／工具墙钟时间旁渲染经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。与那些墙钟时间一样，该分组是窗口作用域的，不折算任何计费；token 账目仍归 token-meter 投影。
+
+## 考虑过的替代方案
+
+**持久的会话投影（token-meter 形态）。** 在 host 侧用 `ProjectionDefinition` 折算步骤计时可以跨越压缩与窗口分页、覆盖整个日志。是暂缓而非否决：投影状态必须保持 O(1)（只能均值，不能分位数），它需要 host 改动加 schema，而聊天统计行的耗时事实本就被记录为窗口作用域——新分组沿用该作用域。后续 PR 可以在不挪动这些读数的情况下补上持久投影。
+
+**逐步骤页脚附属元素。** 让每条 assistant 消息显示自己的 TTFT，会给轮次中段的叙述节点挂上附属元素，而页脚设计刻意让它们保持无 chrome；trajectory 视图已经暴露逐步骤计时细节。
+
+**用节点是否在场而非 `turn/end` 计时做页脚门控。** 直接渲染碰巧加载到的步骤，会展示一个貌似合理、实为分页后「首个已加载步骤」的 TTFT。`endTime` 门控加上后缀窗口不变量，使显示的数字要么是该轮次真实的首步延迟，要么什么都不显示。
+
+## 后果
+
+窗口内已结算轮次的页脚在 hover 时于实际耗时之后显示 `首 token`／`tok/s`，统计行在墙钟时间旁以本地化标签显示窗口平均延迟与吞吐，全程不新增会话事件、不改 host。指标以省略的方式退化：没有计时或 usage 采样的提供方或步骤只是丢掉对应数字，而不会渲染成零。已加载窗口之外的更早历史仍不计入，已记录在包 README 的统计行限制中。
+
+两个读数都以实测墙钟时间作分母，因此都不可复现：同一个回放场景在本机连续两次跑出 69 与 70 tok/s，而一段 3 毫秒的回放流会读成 26333 tok/s。因此 Web aria golden 在既有的 `{{duration}}` 之外，把吞吐归一化为 `{{throughput}}`；页脚的装饰性分隔符也补上了两侧空格——没有它们，这些读数会连成一整串无障碍文本（`Ran for 13sTTFT 0.2s12 tok/s`），既让屏幕阅读器失去读数之间的边界，也让 `{{duration}}` 失去它赖以匹配的词边界。

.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md
+2026-08-05-composer-context-meter-breakdown.md: a757bcbc8bc57f4c3a16f663a9c922155b8bb575
+2026-08-05-composer-context-meter-breakdown.zh.md: 441fd3013f2db721527838955b5ce227865615f1

.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md

@@ -0,0 +1,31 @@
+# Agent Note: Composer context meter with heuristic composition breakdown
+
+Status: implemented
+
+English | [中文](2026-08-05-composer-context-meter-breakdown.zh.md)
+
+## Problem
+
+The Web chat's stats line showed context occupancy as one inline figure (`Context N% of X`) among its billing groups. That answers "how full" but not "what fills it": nothing showed how the window divides between the system prompt, tool schemas, and conversation, and the one-line row has no room for that detail. The available numbers also live in two vocabularies — the provider-exact billed prompt size from `contextPressure` versus the token-meter's fixed character heuristic — and no existing surface could present composition without conflating them.
+
+## Decision
+
+Three cooperating pieces, one per package boundary:
+
+`dsh-session` exports the pure `deriveEventMessage(event)` (previously reachable only as a `Session` method, which now delegates to it) so a host-side fold can price surface nodes without a `Session` instance.
+
+`dsh-token-meter` extracts its pricing heuristic into `src/estimate.ts` and its positional surface fold into `src/surface-fold.ts` — both shared verbatim with the measurement service — and registers a third session projection, `contextBreakdown`, carrying `systemTokens` / `toolsTokens` / `messageTokens`. Envelope figures reprice last-wins on each `request/header` through `canonicalHeader`; the message figure replays `foldSurfaceTokens` over a per-node `{seq, tokens}` list, so it equals `measure().surfaceTokens` at every event boundary by construction and compaction shrinks it the way it shrinks the next request. The shared fold is total and allocation-fresh — it returns the next surface rather than mutating one — which keeps the service's validate-before-commit replay transaction intact: a throw leaves the replay cursor unmoved and the same malformed event fails identically on retry. A replace range absent from the folded surface throws: committed logs are surface-validated at append time, so an unresolvable range is log corruption, not a skippable event.
+
+`ui-conversation` moves context occupancy off the stats line (one home per fact) onto a composer-trailing `ContextMeter`: a 14px occupancy ring after the model seat fed by `contextPressure`, click-opening a panel that pairs the provider-exact percent and `~used / capacity` header with a 4px color-segmented bar and `~`-prefixed composition rows. The two vocabularies deliberately never reconcile — the heuristic shares only proportion the bar's colored segments and rows, each marked `~` because the fixed 4-chars-per-token heuristic systematically underprices CJK text and code. (The ring, header, and bar length were provider-exact as shipped here; they now read the provider-anchored `projectedTokens` instead, because the bare sample could not see a compaction — see [the meter's compaction blindness](../bug-fix/2026-08-05-context-meter-blind-to-compaction.md).) The header is one localized sentence (`context.aria`, shared with the ring's accessible name) split around its `{percent}` slot, so each locale owns the reading's position — English leads with it, Chinese trails it — while the reading keeps its own tone; a bar part whose width computes to zero is dropped rather than rendered, because `.segment`'s min-width would otherwise paint a filled sliver at 0% occupancy.
+
+## Alternatives considered
+
+**Deriving composition client-side from the loaded window.** The window is a contiguous log suffix: the `request/header` events carrying the system prompt and tool schemas may sit outside it, and paging would silently change the figures. Only a durable host-side projection survives paging and compaction, which is why the data crosses the wire as a third projection rather than a chat-window fold.
+
+**Scaling the heuristic rows to sum to `pressureTokens`.** Forced reconciliation fabricates precision: pressure lags one request, includes provider envelope overhead the estimator never models, and would make the rows move when nothing in the composition changed. Showing the estimator's real vocabulary with an explicit `~` was chosen instead.
+
+**Finer categories (rules, skills, MCP tools) as in Claude Code's `/context`.** Not separable here: the harness folds those contributions into the system text and the tools list before the request header exists, so three categories are the honest resolution.
+
+## Consequences
+
+Token-meter now registers three projection keys; unloading removes all three, and `contextBreakdown` restores from JSON checkpoints (`stateVersion` 1). The stats line dropped its Context group and the ring is the sole context UI. The panel's heuristic rows visibly disagree with the provider-exact header — accepted and signposted by the `~` prefix; improving estimate accuracy (for example CJK-aware weighting) is localized to `estimate.ts` and changes no seam. The legend's purple segment tint is a literal color because the design platform ships no purple static token.

.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md

@@ -0,0 +1,31 @@
+# Agent Note: composer 上下文占用圆环与启发式组成明细
+
+Status: implemented
+
+[English](2026-08-05-composer-context-meter-breakdown.md) | 中文
+
+## 问题
+
+Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N% of X`）挤在计费分组之间。它回答了「有多满」，却回答不了「被什么占满」：没有任何地方展示窗口在系统提示词、工具 schema 与对话之间如何分配，而单行统计行也容纳不下这种明细。可用的数字还分属两套口径——来自 `contextPressure` 的提供方精确计费 prompt 规模，与 token-meter 的固定字符启发式——没有任何既有界面能在不混淆两者的前提下展示组成。
+
+## 决定
+
+三个协作部分，每个包边界一个：
+
+`dsh-session` 导出纯函数 `deriveEventMessage(event)`（此前只能通过 `Session` 方法访问，该方法现在委托给它），使 host 侧 fold 无需 `Session` 实例即可为表层节点计价。
+
+`dsh-token-meter` 把计价启发式抽取到 `src/estimate.ts`、把位置表层折叠抽取到 `src/surface-fold.ts`（两者都与测量服务逐字共享），并注册第三个会话投影 `contextBreakdown`，携带 `systemTokens` / `toolsTokens` / `messageTokens`。envelope 数字在每条 `request/header` 上经 `canonicalHeader` 按后者胜重新计价；消息数字在逐节点 `{seq, tokens}` 列表上重放 `foldSurfaceTokens`，因此它在每个事件边界上按构造等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。这份共享折叠是全函数且总是新建数组——返回下一个表层而不是原地改写——从而保留了服务侧「先校验再提交」的重放事务：抛出时重放游标不前进，同一条畸形事件在重试时报同样的错。折叠表层中不存在的替换范围会直接抛出：已提交日志在追加时就经过表层校验，无法解析的范围是日志损坏，而不是可跳过的事件。
+
+`ui-conversation` 把上下文占用率从统计行移走（一个事实一个家），放到 composer 尾部的 `ContextMeter`：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，点击弹出的面板把提供方精确的百分比与 `~已用 / 容量` 标题，与 4px 分色分段进度条及带 `~` 前缀的组成明细行并列。两套口径刻意永不对账——启发式占比只用于切分进度条的彩色分段与明细行，且每个启发式数字都标 `~`，因为固定的「4 字符≈1 token」启发式会系统性低估 CJK 文本与代码。（本记录落地时，圆环、标题与进度条总长取的是提供方精确值；它们现在改读锚定在提供方读数上的 `projectedTokens`，因为裸样本看不见压缩——见[仪表对压缩的失明](../bug-fix/2026-08-05-context-meter-blind-to-compaction.md)。）标题是一整句本地化文案（`context.aria`，与圆环的无障碍名共用），在 `{percent}` 槽位处切开渲染，于是读数的位置由各语言自己决定——英文在前、中文在后——同时读数保留自己的字重；宽度算出为零的分段直接不渲染，否则 `.segment` 的 min-width 会在 0% 占用时画出一段填充色。
+
+## 备选方案
+
+**在客户端从已加载窗口推导组成。** 窗口是日志的连续后缀：携带系统提示词与工具 schema 的 `request/header` 事件可能在窗口之外，翻页还会让数字悄悄变化。只有持久的 host 侧投影能在翻页与压缩后幸存，这正是数据以第三个投影而非聊天窗口 fold 的形式过线的原因。
+
+**把启发式明细行按比例缩放到与 `pressureTokens` 相加一致。** 强行对账是在捏造精度：压力滞后一个请求，还包含估算器从不建模的提供方封装开销，会让明细行在组成毫无变化时也跟着变动。最终选择以显式 `~` 展示估算器的真实口径。
+
+**更细的类别（rules、skills、MCP 工具，如 Claude Code 的 `/context`）。** 在这里不可分：harness 在请求标头存在之前就把这些贡献折入系统文本与工具列表，因此三个类别是诚实的分辨率。
+
+## 后果
+
+token-meter 现在注册三个投影键；卸载会移除全部三个，`contextBreakdown` 可从 JSON 检查点恢复（`stateVersion` 为 1）。统计行删除了 Context 分组，圆环成为唯一的上下文 UI。面板的启发式明细行与提供方精确的标题数字肉眼可见地不一致——已接受并以 `~` 前缀标示；提升估算精度（例如按 CJK 加权）只需改动 `estimate.ts`，不涉及任何 seam。图例的紫色分段色值是字面量，因为设计平台没有紫色静态 token。

apps/web/tests/built-boot.snapshot.ts

@@ -121,6 +121,21 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
     expect(document.querySelector('[data-sample="bash"]')).not.toBeNull()
   }, { timeout: 10_000 })
 
+  // Resolve the resident approval so the ordinary composer bar (which owns
+  // ContextMeter) resumes without replacing the session shell. This minimal
+  // boot graph intentionally does not mount the separate question UI plugin.
+  fireEvent.click(await screen.findByRole('button', { name: 'Allow once' }))
+
+  // The fixture mirrors all three token-meter projections, so the assembled
+  // ContextMeter reaches its composition panel instead of only the occupancy
+  // fallback path.
+  const contextTrigger = await screen.findByRole('button', { name: /of context used/ })
+  fireEvent.click(contextTrigger)
+  const contextPanel = await screen.findByRole('dialog', { name: 'of context used' })
+  within(contextPanel).getByText('System prompt')
+  within(contextPanel).getByText('Tools')
+  within(contextPanel).getByText('Messages')
+
   // The write/edit turns render a real diff card through the assembled graph
   // (the keyed FileMutationRow composing ToolRow + DiffBlock), not just the
   // fixture's raw text. The card is collapsed by default, so expand each edit/

apps/web/tests/math-rendering.e2e.ts

@@ -26,6 +26,7 @@ const DONE = 'MATH_RENDERING_DONE'
 /** Build a settled assistant reply that exercises every supported math delimiter. */
 function mathFixture(): string {
   const session = Session.create(SessionId('math-rendering-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
   session.append('turn/start', {
     turn: 1,
   })
@@ -76,7 +77,10 @@ function mathFixture(): string {
       createdAt: 0,
       cwd: '{{cwd}}',
     }),
-    ...session.events.map(event => JSON.stringify(event)),
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
     '',
   ].join('\n')
 }

apps/web/tests/scaffold.ts

@@ -476,15 +476,29 @@ export function fixtureUserPrompts(fixtureText: string): string[] {
  * @param id - the seeded session id (stable for deterministic goldens).
  * @returns the seeded id.
  */
-export async function seedSession(scaffold: WebScaffold, fixtureText: string, id: string): Promise<SessionId> {
+/**
+ * Realize a recorded seed fixture against one scaffold: substitute the
+ * `{{sessionId}}`/`{{cwd}}` placeholders and rewrite the recorded cwd to the
+ * scaffold's workspace. Idempotent, so a caller may realize early (e.g. to
+ * price content exactly as the host will fold it) and still pass the result
+ * through {@link seedSession}.
+ * @param scaffold - the booted scaffold whose workspace the seed targets.
+ * @param fixtureText - the committed seed fixture text.
+ * @param id - the session id the seed is realized for.
+ * @returns the realized fixture text.
+ */
+export function realizeSeedFixture(scaffold: WebScaffold, fixtureText: string, id: string): string {
   const realized = fixtureText
     .split('{{sessionId}}').join(id)
     .split('{{cwd}}').join(scaffold.workspaceCwd)
   const fixtureCwd = (JSON.parse(realized.split('\n', 1)[0]!) as { cwd?: string }).cwd
-  const rewritten = fixtureCwd === undefined
+  return fixtureCwd === undefined
     ? realized
     : realized.split(fixtureCwd).join(scaffold.workspaceCwd)
-  const events = parseSessionLog(rewritten)
+}
+
+export async function seedSession(scaffold: WebScaffold, fixtureText: string, id: string): Promise<SessionId> {
+  const events = parseSessionLog(realizeSeedFixture(scaffold, fixtureText, id))
   if (events.length === 0) throw new Error('seed fixture has no events')
   const last = events[events.length - 1]!
   // An open final turn would be mutated by resume's crash repair on first
@@ -518,8 +532,14 @@ export async function seedSession(scaffold: WebScaffold, fixtureText: string, id
 }
 
 /**
- * Normalize an aria snapshot: uuid, cwd, workspace-basename, and duration
- * volatility collapse to stable tokens.
+ * Normalize an aria snapshot: uuid, cwd, workspace-basename, duration, and
+ * decode-throughput volatility collapse to stable tokens.
+ *
+ * Throughput needs a token for the same reason durations do, and no fixture
+ * can supply one: the figure divides a replayed step's output tokens by the
+ * wall time the local run took to stream them, so it moves between two runs
+ * on one machine (measured 69 → 70 tok/s) and swings wildly on a fast replay
+ * (26333 tok/s for a 3 ms stream).
  */
 function normalizeAria(snapshot: string, workspaceCwd: string): string {
   // The session heading renders the workspace's basename, not the full
@@ -529,14 +549,17 @@ function normalizeAria(snapshot: string, workspaceCwd: string): string {
     .split(workspaceCwd).join('{{cwd}}')
     .split(base).join('{{workspace}}')
     .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '{{uuid}}')
+    // The optional space in `\d+m ?\d+s` covers both minute spellings: the
+    // stats line's compact `2m42s` and the message-chrome template's `2m 42s`.
     .replace(
-      /~\d+(?:y(?: \d+mo)?|mo(?: \d+d)?)|\b(?:\d+d(?: \d+h(?: \d+m \d+s)?)?|\d+h \d+m \d+s|\d+m \d+s|\d+(?:\.\d+)?s|\d+(?:\.\d+)?ms)\b/g,
+      /~\d+(?:y(?: \d+mo)?|mo(?: \d+d)?)|\b(?:\d+d(?: \d+h(?: \d+m \d+s)?)?|\d+h \d+m \d+s|\d+m ?\d+s|\d+(?:\.\d+)?s|\d+(?:\.\d+)?ms)\b/g,
       duration => duration.startsWith('~') ? duration : '{{duration}}',
     )
     .replace(
       /约\d+(?:年(?:\d+个月)?|个月(?:\d+天)?)|\d+(?:天(?:\d+小时(?:\d+分\d+秒)?)?|小时\d+分\d+秒|分\d+秒|(?:\.\d+)?秒)/g,
       duration => duration.startsWith('约') ? duration : '{{duration}}',
     )
+    .replace(/\d+(?:\.\d+)?(?= tok\/s(?!\w))/g, '{{throughput}}')
     // Message IconActions clocks widen by calendar day/year; collapse every
     // shape so goldens stay stable across midnight and year boundaries.
     .replace(/\d{4}年\d{1,2}月\d{1,2}日 \d{2}:\d{2}/g, '{{clock}}')

apps/web/tests/seeded-history.e2e.ts

@@ -16,11 +16,14 @@ import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
+import { deriveEventMessage, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { TokenMeterService } from '@deepseek-ai/dsh-token-meter'
 import { join } from 'node:path'
 import {
   assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
-  launchWebScaffold, recordFixture, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+  launchWebScaffold, realizeSeedFixture, recordFixture, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { newEnglishPage, saveFailureShot } from './support.ts'
 
@@ -41,17 +44,22 @@ const PROMPT = 'Use the read tool twice in one assistant message: read a.txt and
  * deterministic condition before seeding it cold, so the scenario pins the bug
  * this change fixes — a landed compaction must not erase history the reader
  * already saw — through the real host and the real browser.
- * @param raw - the committed seed fixture text.
+ * @param raw - the seed fixture text, already realized (placeholder-free) so
+ * the shadow price below is computed from the exact strings the host folds.
+ * @param meter - the composed token meter; the appended `compact/summary`'s
+ * shadow price must be the exact heuristic price of the shadowed nodes, the
+ * way compact-basic derives it, because the token-meter projections subtract
+ * it verbatim.
  * @returns the fixture with a compacted turn appended.
  */
-function withCompaction(raw: string): string {
+function withCompaction(raw: string, meter: TokenMeterService): string {
   const lines = raw.trimEnd().split('\n')
   const events = lines.slice(1).map(line => JSON.parse(line) as {
     type: string
     seq: number
     time: number
     surfaceOp?: unknown
-    data?: { turn?: unknown }
+    data?: { turn?: unknown; message?: unknown; content?: unknown; callId?: unknown; isError?: unknown }
   })
   const surfaceSeqs = events
     .filter(event => event.surfaceOp === 'append'
@@ -87,6 +95,31 @@ function withCompaction(raw: string): string {
   }
   at({ type: 'turn/start', data: { turn } })
   const startSeq = at({ type: 'compact/start', data: { turn } })
+  // Load-bearing exactness: the projections subtract this count verbatim, so
+  // it must equal what the host's fold prices for these nodes. The estimator
+  // prices message CONTENT only, so a minimal wrapper per storage shape is
+  // exact — pre-identity rows carry bare `content` (the persistence read path
+  // upgrades them), a current row carries the full `message` envelope.
+  const priceRow = (row: (typeof events)[number]): number => {
+    if (row.data?.message !== undefined) {
+      const message = deriveEventMessage(row as unknown as SessionEvent)
+      return message === null ? 0 : meter.estimateMessage(message)
+    }
+    const content = row.data?.content as ContentBlock[]
+    if (row.type === 'tool/result') {
+      return meter.estimateMessage({
+        content: [{ type: 'tool-result', toolCallId: row.data?.callId, content, isError: row.data?.isError === true }],
+      } as unknown as Message)
+    }
+    // An empty-content assistant message derives no transcript entry.
+    if (row.type === 'assistant/message' && content.length === 0) return 0
+    return meter.estimateMessage({ content } as unknown as Message)
+  }
+  const shadowedTokenCount = surfaceSeqs.reduce((total, surfaceSeq) => {
+    const event = events.find(candidate => candidate.seq === surfaceSeq)
+    if (event === undefined) throw new Error(`seeded-history compaction: shadowed seq ${surfaceSeq} is not in the seed`)
+    return total + priceRow(event)
+  }, 0)
   const summarySeq = at({
     type: 'compact/summary',
     data: {
@@ -96,7 +129,7 @@ function withCompaction(raw: string): string {
       }],
       shadowedRange: { start: first, end: last },
       shadowedSeqs: surfaceSeqs,
-      shadowedTokenCount: 10_000,
+      shadowedTokenCount,
       provider: 'snapshot',
       model: 'snapshot-compactor',
     },
@@ -137,7 +170,10 @@ describe('web e2e: seeded history renders through cold resume', () => {
     if (MODE !== 'record') {
       const raw = await readFile(SEED, 'utf8')
       expect(fixtureUserPrompts(raw), 'seed fixture must carry exactly the drive prompt').toEqual([PROMPT])
-      await seedSession(scaffold, withCompaction(raw), SEED_ID)
+      const meter = scaffold.ctx.get('tokenMeter')
+      if (meter === undefined) throw new Error('seeded-history requires the composed token meter')
+      const realized = realizeSeedFixture(scaffold, raw, SEED_ID)
+      await seedSession(scaffold, withCompaction(realized, meter), SEED_ID)
     }
     browser = await chromium.launch()
     page = await newEnglishPage(browser)

apps/web/tests/snapshots/bash-abort-row/ui.expected.md

@@ -30,4 +30,4 @@
   - text: Select model
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps Tool call {{duration}} Cache hit 0% Input 10 tok · Output 10 tok
+- text: 1 turns · 1 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 10 tok · Output 10 tok

apps/web/tests/snapshots/code-mode-round/ui.expected.md

@@ -36,7 +36,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -44,5 +44,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "7% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Context 7% of 128K Cache hit 52% Input 17.2K tok · Output 252 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 52% Input 17.2K tok · Output 252 tok

apps/web/tests/snapshots/cordis-tool-round/ui.expected.md

@@ -51,7 +51,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -59,5 +59,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "13% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 4 steps Tool call {{duration}} Context 13% of 128K Cache hit 77% Input 66.5K tok · Output 312 tok
+- text: 1 turns · 4 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 77% Input 66.5K tok · Output 312 tok

apps/web/tests/snapshots/fresh-round-trip/ui.expected.md

@@ -31,7 +31,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -39,5 +39,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Context 6% of 128K Cache hit 99% Input 15.7K tok · Output 111 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.7K tok · Output 111 tok

apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md

@@ -23,7 +23,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -31,5 +31,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps Context 6% of 128K Cache hit 99% Input 7.8K tok · Output 21 tok
+- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 21 tok

apps/web/tests/snapshots/live-interactions/cancel.expected.md

@@ -20,7 +20,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img

apps/web/tests/snapshots/live-interactions/retry.expected.md

@@ -25,7 +25,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -33,5 +33,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps Context 6% of 128K Cache hit 99% Input 7.8K tok · Output 79 tok
+- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 79 tok

apps/web/tests/snapshots/markdown-images/ui.expected.md

@@ -19,7 +19,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img

apps/web/tests/snapshots/math-rendering/ui.expected.md

@@ -35,7 +35,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -44,4 +44,4 @@
   - text: Select model
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps Input 0 tok · Output 0 tok
+- text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok

apps/web/tests/snapshots/message-actions/ui.expected.md

@@ -20,7 +20,7 @@
   - img
 - button "Branch into a new conversation" [disabled]:
   - img
-- text: Available only on the last message of a completed turn 7/25 {{clock}}Ran for {{duration}}
+- text: Available only on the last message of a completed turn 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - button "Read a.txt":
   - img
   - img
@@ -46,7 +46,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: 7/25 {{clock}}Ran for {{duration}}
+- text: 7/25 {{clock}} Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -55,4 +55,4 @@
   - text: Select model
   - img
 - button "Send message" [disabled]
-- text: 2 turns · 3 steps Tool call {{duration}} Cache hit 98% Input 7.8K tok · Output 103 tok
+- text: 2 turns · 3 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 7.8K tok · Output 103 tok

apps/web/tests/snapshots/plan-review/approved.expected.md

@@ -36,7 +36,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -44,5 +44,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "4% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Context 4% of 128K Cache hit 51% Input 10.2K tok · Output 346 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 51% Input 10.2K tok · Output 346 tok

apps/web/tests/snapshots/question-composer/answered.expected.md

@@ -31,7 +31,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -39,5 +39,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "3% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Context 3% of 128K Cache hit 95% Input 8.6K tok · Output 180 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 95% Input 8.6K tok · Output 180 tok

apps/web/tests/snapshots/queue-actions/preserved.expected.md

@@ -20,7 +20,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}}
 - button "2 queued messages" [expanded]
 - list:
   - listitem:

apps/web/tests/snapshots/seeded-history/command-row.expected.md

@@ -33,7 +33,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: 7/25 {{clock}}Ran for {{duration}}
+- text: 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - button "Context compacted View compaction summary":
   - img
   - text: Context compacted View compaction summary
@@ -51,4 +51,4 @@
   - text: Select model
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok

apps/web/tests/snapshots/seeded-history/ui.expected.md

@@ -33,7 +33,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: 7/25 {{clock}}Ran for {{duration}}
+- text: 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - button "Context compacted View compaction summary":
   - img
   - text: Context compacted View compaction summary
@@ -49,4 +49,4 @@
   - text: Select model
   - img
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Cache hit 98% Input 15.8K tok · Output 135 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok

apps/web/tests/snapshots/steering/settled.expected.md

@@ -37,7 +37,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -45,5 +45,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "6% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Context 6% of 128K Cache hit 98% Input 15.8K tok · Output 156 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 156 tok

apps/web/tests/snapshots/subagent-conversation/ui.expected.md

@@ -28,7 +28,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}} Now give the same explanation to a human reader. {{clock}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s Now give the same explanation to a human reader. {{clock}}
 - button "Copy":
   - img
 - button "Branch into a new conversation" [disabled]:
@@ -43,10 +43,11 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "6% of context used"
 - button "Send message" [disabled]
-- text: 2 turns · 2 steps Context 6% of 128K Cache hit 99% Input 15.6K tok · Output 158 tok
+- text: 2 turns · 2 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.6K tok · Output 158 tok

apps/web/tests/snapshots/web-search-round/ui.expected.md

@@ -23,7 +23,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
 - textbox "Message the agent"
 - button "Commands":
   - img
@@ -31,5 +31,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
+- button "0% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 2 steps Tool call {{duration}} Context 0% of 128K Cache hit 0% Input 22 tok · Output 7 tok
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 22 tok · Output 7 tok

docs/config-catalog.md

@@ -405,6 +405,8 @@ Source: [`packages/compact/compact-basic/src/types.ts:38`](../packages/compact/c
 
 ## `@deepseek-ai/dsh-compact-tool-result-prune`
 
+Requires: `tokenMeter`
+
 ```ts config-catalog
 /** Character-budget policy for deterministic tool-result pruning. */
 export interface ToolResultPruneConfig {

docs/cordis-catalog/services.md

@@ -1707,7 +1707,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId):
 
 Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [PrepareSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:837`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:800`](../../packages/core/session/src/index.ts)
 
 ## `ctx.sessionTitle` — `SessionTitleService`
 
@@ -2339,7 +2339,8 @@ Replay owner for one service-wide estimator and isolated per-session folds.
 measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 
 /**
- * Heuristically price one model-visible message.
+ * Heuristically price one model-visible message (instance face of the pure
+ * `estimateMessage` export from `estimate.ts`).
  * @param message - message to price without mutation.
  * @returns content and role-framing tokens under the fixed service heuristic.
  */
@@ -2348,7 +2349,7 @@ estimateMessage(message: Message): number
 
 Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md)
 
-Source: [`packages/llm/token-meter/src/index.ts:85`](../../packages/llm/token-meter/src/index.ts)
+Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 
 ## `ctx.toolResultPrune` — `ToolResultPruneService`
 
@@ -2374,7 +2375,10 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 /**
  * Prune every over-budget tool result from one stable current-surface snapshot.
  * Each replacement preserves the complete event data except for `content`,
- * and points at the shadowed node for durable provenance and replay.
+ * points at the shadowed node for durable provenance and replay, and is
+ * immediately preceded by a `compact/prune` shadow-price event pricing the
+ * shadowed node through the injected token meter, so pure consumers can
+ * subtract it without per-node state.
  * @param session - session whose current surface is rewritten.
  * @returns landed replacements and aggregate Unicode-code-point savings.
  * @throws when the session rejects a replacement; replacements committed
@@ -2385,7 +2389,7 @@ pruneSession(session: Session): PruneResult
 
 Types: [ContentBlock](../core-data-structures/core.md) · [PruneResult](../core-data-structures/compaction.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/compact/compact-tool-result-prune/src/index.ts:40`](../../packages/compact/compact-tool-result-prune/src/index.ts)
+Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 

docs/core-data-structures/session.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/session.md
-session.md: 525703f1494945f23d0e33e06c9cbe7dbabe1c91
-session.zh.md: 6586d7df48aed1701998c01e19b403325f29220f
+session.md: fb04ff3eb3c15d1f3c923ee73d4ba19537d36f11
+session.zh.md: 138159d97a5c368f28821715512632e0ca95b29e

docs/core-data-structures/session.md

@@ -494,15 +494,8 @@ declare class Session {
    */
   deriveMessages(): Message[];
   /**
-   * Project a single event into the LLM message it derives to, or null when
-   * it produces none — a non-surface event (chunk, boundary, log-only record)
-   * or an empty-content assistant/message (which exists only to host usage).
-   * The per-node pure function {@link deriveMessages} folds over the surface;
-   * an external reconstructor (or the dev invariant) folds the same function
-   * over a log prefix's surface to rebuild the exact messages any request was
-   * built from (the reconstructability Agent Note). The returned message is
-   * the already frozen message nested in the event wrapper and shared by
-   * delivery, durable history, and model requests.
+   * Instance face of the pure per-node `deriveEventMessage` export from
+   * `surface.ts`.
    * @param event - the event to project.
    * @returns the derived message, or null when the event produces none.
    */

docs/core-data-structures/session.zh.md

@@ -496,15 +496,8 @@ declare class Session {
    */
   deriveMessages(): Message[];
   /**
-   * Project a single event into the LLM message it derives to, or null when
-   * it produces none — a non-surface event (chunk, boundary, log-only record)
-   * or an empty-content assistant/message (which exists only to host usage).
-   * The per-node pure function {@link deriveMessages} folds over the surface;
-   * an external reconstructor (or the dev invariant) folds the same function
-   * over a log prefix's surface to rebuild the exact messages any request was
-   * built from (the reconstructability Agent Note). The returned message is
-   * the already frozen message nested in the event wrapper and shared by
-   * delivery, durable history, and model requests.
+   * Instance face of the pure per-node `deriveEventMessage` export from
+   * `surface.ts`.
    * @param event - the event to project.
    * @returns the derived message, or null when the event produces none.
    */

docs/module-graph.md

@@ -428,9 +428,6 @@ flowchart TD
   pkg_compact --> pkg_invariants
   pkg_compact --> pkg_llm
   pkg_compact --> pkg_session
-  pkg_compact_tool_result_prune --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_llm
-  pkg_compact_tool_result_prune --> pkg_session
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
@@ -490,6 +487,7 @@ flowchart TD
   pkg_llm_retry --> pkg_llm
   pkg_llm_retry --> pkg_session
   pkg_llm_retry --> pkg_timeout
+  pkg_token_meter --> pkg_compact
   pkg_token_meter --> pkg_invariants
   pkg_token_meter --> pkg_llm
   pkg_token_meter --> pkg_session
@@ -626,13 +624,11 @@ flowchart TD
   pkg_command_compact --> pkg_commands
   pkg_command_compact --> pkg_compact
   pkg_command_compact --> pkg_invariants
-  pkg_compact_basic --> pkg_agent
-  pkg_compact_basic --> pkg_compact
-  pkg_compact_basic --> pkg_compact_tool_result_prune
-  pkg_compact_basic --> pkg_invariants
-  pkg_compact_basic --> pkg_llm
-  pkg_compact_basic --> pkg_session
-  pkg_compact_basic --> pkg_token_meter
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
   pkg_session_query --> pkg_brand
   pkg_session_query --> pkg_invariants
   pkg_session_query --> pkg_llm
@@ -728,6 +724,13 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
   pkg_subagent --> pkg_agent
   pkg_subagent --> pkg_brand
   pkg_subagent --> pkg_invariants
@@ -1138,7 +1141,6 @@ flowchart TD
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
@@ -1155,7 +1157,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1188,7 +1190,7 @@ flowchart TD
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
 | [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
@@ -1204,6 +1206,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-query`](../packages/session-query/session-query), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |

docs/persistence-catalog.md

@@ -236,7 +236,31 @@ Source: [`packages/ui/commands/src/index.ts:132`](../packages/ui/commands/src/in
 'compact/end': { turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:51`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:54`](../packages/compact/compact/src/types.ts)
+
+#### `compact/prune` — log-only
+
+```ts persistence-catalog
+/**
+ * Shadow price of one model-free prune replacement — log-only, no
+ * surfaceOp. The shared shadow-price protocol: a surface `replace` event
+ * is priced by the metering event immediately before it (`compact/summary`
+ * for a summarizing compaction, this event for a prune), which states the
+ * heuristic token price of the exact replaced range so a pure consumer
+ * can subtract it without retaining per-node prices. The replacement MUST
+ * be appended synchronously right after this event.
+ */
+'compact/prune': {
+  /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
+  shadowedRange: { start: number; end: number }
+  /** The seqs of all shadowed surface nodes, in surface order. */
+  shadowedSeqs: number[]
+  /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
+  shadowedTokenCount: number
+}
+```
+
+Source: [`packages/compact/compact/src/types.ts:64`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -257,8 +281,11 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 /**
  * Provenance record of a completed summarization — log-only, no surfaceOp.
  * The summary content is in `data.summary`; the actual surface replacement
- * is performed by a subsequent `user/message` event that shadows the
- * compacted range.
+ * is performed by the immediately following `user/message` event that
+ * shadows the compacted range. That adjacency is contractual — the
+ * shadowed pricing fields are the replacement's shadow price, so a
+ * consumer may pair a replacement with the metering event directly
+ * before it (`compact/prune` documents the shared protocol).
  */
 'compact/summary': {
   summary: ContentBlock[]
@@ -285,7 +312,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 
 Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
 
-Source: [`packages/compact/compact/src/types.ts:26`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
 
 ### `goal/*`
 

packages/client/connection/src/client/fixture.ts

@@ -27,7 +27,7 @@ import type {
 // Type-only: the brand constructor is host-side; the fixture casts at its
 // wire-fabrication boundary (the schema layer's one-cast-point posture).
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-import { foldSurface } from '@deepseek-ai/dsh-session/surface'
+import { deriveEventMessage, foldSurface } from '@deepseek-ai/dsh-session/surface'
 import type {
   ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
   ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
@@ -358,6 +358,12 @@ function buildAlphaLog(): SessionEvent[] {
     events.push({ seq, time: (time += 800), ...authored })
     return seq
   }
+  // This resident history represents completed model requests, so retain the
+  // route capacity that accompanied them just as the live prompt path does.
+  push({
+    type: 'request/context',
+    data: { provider: 'deepseek-official', model: 'deepseek-v4-flash', contextWindow: 128_000 },
+  })
   for (let turn = 0; turn < 60; turn++) {
     push({ type: 'turn/start', data: { turn } })
     const userSeq = push({
@@ -822,6 +828,62 @@ interface FixtureRequestContext {
   contextWindow?: number
 }
 
+interface FixtureContextBreakdownProjection {
+  systemTokens: number
+  toolsTokens: number
+  messageTokens: number
+}
+
+/** Fixed token-meter heuristic constants mirrored by this client-only fixture. */
+const CHARS_PER_TOKEN = 4
+const BLOCK_OVERHEAD = 4
+const ROLE_OVERHEAD = 4
+
+/** Price fixture content with token-meter's fixed-density heuristic. */
+function estimateFixtureContent(blocks: readonly ContentBlock[]): number {
+  const densityPrice = (value: string): number => Math.ceil(value.length / CHARS_PER_TOKEN)
+  return blocks.reduce((tokens, block) => {
+    if (block.type === 'text' || block.type === 'reasoning') {
+      return tokens + densityPrice(block.text) + BLOCK_OVERHEAD
+    }
+    if (block.type === 'tool-call') {
+      return tokens + densityPrice(block.name) + densityPrice(block.arguments) + BLOCK_OVERHEAD
+    }
+    // ContentBlockMap is merge-extensible: this client graph sees only the
+    // base four members, but fixture turns do carry extended blocks at
+    // runtime, so the structural JSON fallback below is live code.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- the type collapses without the out-of-graph merges (see above).
+    if (block.type === 'tool-result') {
+      return tokens + estimateFixtureContent(block.content) + BLOCK_OVERHEAD
+    }
+    return tokens + densityPrice(JSON.stringify(block)) + BLOCK_OVERHEAD
+  }, 0)
+}
+
+/** Fixture parallel of token-meter's heuristic context-composition projection. */
+function contextBreakdownOf(log: readonly SessionEvent[]): FixtureContextBreakdownProjection {
+  const headerEvent = log.findLast(event => event.type === 'request/header')
+  const header = headerEvent === undefined
+    ? undefined
+    : headerEvent.data.header
+  let messageTokens = 0
+  for (const seq of foldSurface(log).nodes) {
+    const event = log[seq]
+    if (event === undefined) continue
+    const message = deriveEventMessage(event)
+    if (message !== null) messageTokens += estimateFixtureContent(message.content) + ROLE_OVERHEAD
+  }
+  return {
+    systemTokens: header?.system === undefined
+      ? 0
+      : Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD,
+    toolsTokens: header?.tools === undefined || header.tools.length === 0
+      ? 0
+      : Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD,
+    messageTokens,
+  }
+}
+
 /** Latest log-only route context, or undefined before any request ran. */
 function lastRequestContext(
   log: readonly SessionEvent[],
@@ -835,7 +897,11 @@ function lastRequestContext(
 /**
  * Fixture parallel of token-meter's request-pressure projection: the last
  * provider-reported prompt size paired with the last recorded capacity. The
- * two need not come from one request — see the token-meter README.
+ * two need not come from one request — see the token-meter README. The host's
+ * `projectedTokens` is deliberately absent: reproducing it would mean
+ * reimplementing the estimator client-side, and every consumer falls back to
+ * the bare sample, so a fixture-driven view simply lags a compaction the way
+ * the projection did before that field existed.
  */
 function contextPressureOf(
   log: readonly SessionEvent[],
@@ -873,28 +939,44 @@ function projectionValuesOf(log: readonly SessionEvent[]): Record<string, unknow
   values['tokenUsage'] = tokenUsageOf(log)
   // Always present (token-meter composed): last request pressure and capacity.
   values['contextPressure'] = contextPressureOf(log)
+  // Always present (token-meter composed): heuristic request composition.
+  values['contextBreakdown'] = contextBreakdownOf(log)
   return values
 }
 
 /** Host push-frame parallel: emit one session/projection frame per key the given event advanced. */
 function projectionFramesOf(id: SessionId, log: readonly SessionEvent[], event: SessionEvent): Extract<MuxFrame, { type: 'session/projection' }>[] {
   const type = (event as { type: string }).type
+  const frames: Extract<MuxFrame, { type: 'session/projection' }>[] = []
   // One usage sample advances both token-meter units.
   if (usageSampleOf(event) !== undefined) {
-    return [
+    frames.push(
       { type: 'session/projection', sessionId: id, key: 'tokenUsage', value: tokenUsageOf(log), seq: event.seq },
       { type: 'session/projection', sessionId: id, key: 'contextPressure', value: contextPressureOf(log), seq: event.seq },
-    ]
+    )
   }
   if (type === 'request/context') {
-    return [{
+    frames.push({
       type: 'session/projection',
       sessionId: id,
       key: 'contextPressure',
       value: contextPressureOf(log),
       seq: event.seq,
-    }]
+    })
+  }
+  if (type === 'request/header'
+    || type === 'user/message'
+    || type === 'assistant/message'
+    || type === 'tool/result') {
+    frames.push({
+      type: 'session/projection',
+      sessionId: id,
+      key: 'contextBreakdown',
+      value: contextBreakdownOf(log),
+      seq: event.seq,
+    })
   }
+  if (frames.length > 0) return frames
   if (type === 'session/title') {
     const values = projectionValuesOf(log)
     /* v8 ignore next -- the advancing title event is in the log, so the key is present. */

packages/client/connection/tests/fixture.spec.ts

@@ -159,6 +159,11 @@ describe('createFixtureApi', () => {
         },
         // No request ran, so neither pressure nor capacity is known yet.
         contextPressure: {},
+        contextBreakdown: {
+          systemTokens: 0,
+          toolsTokens: 0,
+          messageTokens: 0,
+        },
       } },
     })
   })
@@ -308,6 +313,10 @@ describe('createFixtureApi', () => {
       frame.type === 'session/projection'
       && frame.key === 'contextPressure'
       && (frame.value as { contextWindow?: number }).contextWindow === 128_000)).toBe(true)
+    expect(frames.some(frame =>
+      frame.type === 'session/projection'
+      && frame.key === 'contextBreakdown'
+      && (frame.value as { messageTokens?: number }).messageTokens! > 0)).toBe(true)
     const finalize = frames.find((f): f is Extract<MuxFrame, { type: 'session/event' }> => f.type === 'session/event' && f.event.type === 'assistant/message')
     expect(JSON.stringify(finalize?.event.data)).toContain('（已中断）')
     // Idle cancel: no replay in flight, must not explode; running flips false.
@@ -339,7 +348,7 @@ describe('createFixtureApi', () => {
       const envelopes: RpcRequest<MuxFrame>[] = []
       for await (const envelope of api.events.mux(req({}), abort.signal)) {
         envelopes.push(envelope)
-        if (envelopes.length >= 10) abort.abort()
+        if (envelopes.length >= 11) abort.abort()
       }
       return envelopes
     }
@@ -355,10 +364,15 @@ describe('createFixtureApi', () => {
     expect(first[5]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'goal', value: null })
     expect(first[6]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'tokenUsage' })
     expect(first[7]?.payload).toMatchObject({ type: 'session/projection', sessionId: 'fx-alpha', key: 'contextPressure' })
-    expect(first[8]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
-    expect(second[8]?.rpcId).toBe(first[8]?.rpcId) // stable rpcId across replays (host replay semantics)
-    expect(first[9]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
-    expect(second[9]?.rpcId).toBe(first[9]?.rpcId)
+    expect(first[8]?.payload).toMatchObject({
+      type: 'session/projection', sessionId: 'fx-alpha', key: 'contextBreakdown',
+      value: { systemTokens: 0, toolsTokens: 0 },
+    })
+    expect((first[8]?.payload as { value: { messageTokens: number } }).value.messageTokens).toBeGreaterThan(0)
+    expect(first[9]?.payload).toMatchObject({ type: 'approval/requested', toolName: 'dangerous_tool' })
+    expect(second[9]?.rpcId).toBe(first[9]?.rpcId) // stable rpcId across replays (host replay semantics)
+    expect(first[10]?.payload).toMatchObject({ type: 'question/requested', sessionId: 'fx-alpha' })
+    expect(second[10]?.rpcId).toBe(first[10]?.rpcId)
   })
 
   it('steer with no replay in flight falls through to a fresh queued turn; non-text blocks stringify empty', async () => {

packages/client/runtime/src/client/session-history/history-fold.ts

@@ -16,6 +16,8 @@ import type {
 } from '../sessions/conversation-context.ts'
 import type { ConversationPromptSnapshot } from '../sessions/request-inspection.ts'
 import { PartialAccumulator } from '../sessions/partial.ts'
+import type { AssistantStepMetadata } from '../sessions/assistant-timing.ts'
+import { indexAssistantStepTiming, settledAssistantTiming } from '../sessions/assistant-timing.ts'
 
 interface CallIndexEntry {
   name: string
@@ -30,11 +32,6 @@ interface FoldedContext {
   originSeq?: number
 }
 
-interface AssistantStepMetadata {
-  stepStartTime: number | null
-  firstTokenTime: number | null
-}
-
 /** Immutable conversation projections derived only from the history source. */
 export interface ConversationHistoryProjection {
   eventNodes: readonly ConversationNode[]
@@ -45,10 +42,6 @@ export interface ConversationHistoryProjection {
   codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }
 
-function assistantStepKey(turn: number, step: number): string {
-  return `${turn}\u0000${step}`
-}
-
 function replacementCrossesWindowHead(event: SessionEvent, baseSeq: number): boolean {
   if (!isSurfaceEvent(event) || event.surfaceOp === 'append') return false
   return event.surfaceOp.start < baseSeq || event.surfaceOp.end < baseSeq
@@ -64,21 +57,7 @@ function contextOriginKind(event: SessionEvent | undefined): ConversationContext
   return 'rewrite'
 }
 
-function isTokenDelta(chunk: SessionEvent<'assistant/chunk'>['data']['chunk']): boolean {
-  switch (chunk.type) {
-    case 'text-delta':
-    case 'reasoning-delta':
-      return chunk.text !== ''
-    case 'tool-call-delta':
-      return chunk.argumentsDelta !== '' || chunk.name !== undefined
-    default:
-      return false
-  }
-}
-
-function foldContexts(
-  events: readonly SessionEvent[],
-): readonly FoldedContext[] {
+function foldContexts(events: readonly SessionEvent[]): readonly FoldedContext[] {
   const replay: SessionEvent[] = []
   const originalSeqs: number[] = []
   const rebasedSeqByOriginal = new Map<number, number>()
@@ -381,6 +360,7 @@ export function projectConversationHistory(
       contextGeneration++
       if (activePrompt !== undefined) promptsByContext.set(contextGeneration, activePrompt)
     }
+    indexAssistantStepTiming(assistantSteps, event)
     if (event.type === 'request/header') {
       activeRequestConfig = event.data.header.config
       activePrompt = {
@@ -389,30 +369,10 @@ export function projectConversationHistory(
         tools: event.data.header.tools ?? [],
       }
       promptsByContext.set(contextGeneration, activePrompt)
-    } else if (event.type === 'step/start') {
-      assistantSteps.set(
-        assistantStepKey(event.data.turn, event.data.step),
-        { stepStartTime: event.time, firstTokenTime: null },
-      )
-    } else if (event.type === 'assistant/chunk' && isTokenDelta(event.data.chunk)) {
-      const key = assistantStepKey(event.data.turn, event.data.step)
-      const current = assistantSteps.get(key) ?? {
-        stepStartTime: null,
-        firstTokenTime: null,
-      }
-      if (current.firstTokenTime === null) {
-        assistantSteps.set(key, { ...current, firstTokenTime: event.time })
-      }
     } else if (event.type === 'assistant/message') {
       assistantTimings.set(
         event.seq,
-        {
-          ...(assistantSteps.get(assistantStepKey(event.data.turn, event.data.step)) ?? {
-            stepStartTime: null,
-            firstTokenTime: null,
-          }),
-          completedTime: event.time,
-        },
+        settledAssistantTiming(assistantSteps, event.data.turn, event.data.step, event.time),
       )
       if (activeRequestConfig !== undefined) {
         assistantRequestConfigs.set(event.seq, activeRequestConfig)

packages/client/runtime/src/client/sessions/assistant-timing.ts

@@ -0,0 +1,84 @@
+// Shared assistant step-timing fold: both transcript projections (the live
+// window adapter and the trajectory history fold) derive AssistantTiming from
+// the same step/start -> first token delta -> assistant/message sequence, so
+// the derivation lives once here instead of drifting per projection.
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { AssistantTiming } from './conversation.ts'
+
+/** Pre-finalize timing boundaries for one assistant step (start + first token). */
+export interface AssistantStepMetadata {
+  stepStartTime: number | null
+  firstTokenTime: number | null
+}
+
+/**
+ * Composite map key for one assistant step.
+ * @param turn - turn number from the event payload.
+ * @param step - step number from the event payload.
+ * @returns collision-free `turn`/`step` key (NUL separator).
+ */
+export function assistantStepKey(turn: number, step: number): string {
+  return `${turn}\u0000${step}`
+}
+
+/**
+ * Whether a chunk carries visible model output (first-token boundary). Empty
+ * deltas (heartbeats, empty tool-call frames) do not count as a first token.
+ * @param chunk - the assistant/chunk payload.
+ * @returns true when the chunk contains a non-empty text/reasoning/tool delta.
+ */
+export function isTokenDelta(chunk: SessionEvent<'assistant/chunk'>['data']['chunk']): boolean {
+  switch (chunk.type) {
+    case 'text-delta':
+    case 'reasoning-delta':
+      return chunk.text !== ''
+    case 'tool-call-delta':
+      return chunk.argumentsDelta !== '' || chunk.name !== undefined
+    default:
+      return false
+  }
+}
+
+/**
+ * Fold one event into the per-step timing index: step/start opens the entry,
+ * the first non-empty token delta stamps first-token time once. Other event
+ * types are no-ops.
+ * @param steps - the mutable per-step index, keyed by {@link assistantStepKey}.
+ * @param event - the raw window event.
+ */
+export function indexAssistantStepTiming(steps: Map<string, AssistantStepMetadata>, event: SessionEvent): void {
+  if (event.type === 'step/start') {
+    steps.set(
+      assistantStepKey(event.data.turn, event.data.step),
+      { stepStartTime: event.time, firstTokenTime: null },
+    )
+  } else if (event.type === 'assistant/chunk' && isTokenDelta(event.data.chunk)) {
+    const key = assistantStepKey(event.data.turn, event.data.step)
+    const current = steps.get(key) ?? { stepStartTime: null, firstTokenTime: null }
+    if (current.firstTokenTime === null) {
+      steps.set(key, { ...current, firstTokenTime: event.time })
+    }
+  }
+}
+
+/**
+ * Settle one finalized assistant message's timing from its step entry; a step
+ * whose start or first token fell outside the window yields null boundaries.
+ * @param steps - the per-step index built by {@link indexAssistantStepTiming}.
+ * @param turn - the assistant/message turn number.
+ * @param step - the assistant/message step number.
+ * @param completedTime - the assistant/message event timestamp (epoch ms).
+ * @returns the node-ready timing record.
+ */
+export function settledAssistantTiming(
+  steps: ReadonlyMap<string, AssistantStepMetadata>,
+  turn: number,
+  step: number,
+  completedTime: number,
+): AssistantTiming {
+  return {
+    ...(steps.get(assistantStepKey(turn, step)) ?? { stepStartTime: null, firstTokenTime: null }),
+    completedTime,
+  }
+}

packages/client/runtime/src/client/sessions/transcript-adapter.ts

@@ -22,6 +22,8 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
 import { toAssistantBlocks } from './conversation.ts'
+import type { AssistantStepMetadata } from './assistant-timing.ts'
+import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
 
 /**
  * The compaction seam's checkpoint plugin, pinned to the seam's own declaration
@@ -49,6 +51,7 @@ function materializeNode(
   event: SessionEvent,
   callIndex: ReadonlyMap<string, CallIndexEntry>,
   resultView: ToolResultView | null,
+  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
 ): ConversationNode {
   switch (event.type) {
     case 'user/message':
@@ -70,6 +73,7 @@ function materializeNode(
         kind: 'assistant', seq: event.seq, time: event.time,
         turn: event.data.turn, step: event.data.step,
         blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
+        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
       }
     case 'tool/result': {
       const result = event.data.message.content[0]
@@ -170,6 +174,8 @@ export class TranscriptAdapter {
   /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
   private projected: ConversationNode[] = []
   private callIdx = new Map<string, CallIndexEntry>()
+  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
+  private stepTimings = new Map<string, AssistantStepMetadata>()
   /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
   private resultViews = new Map<number, ToolResultView>()
   /**
@@ -200,6 +206,7 @@ export class TranscriptAdapter {
     this.callIdx = new Map()
     this.resultViews.clear()
     this.commandIdx = new Map()
+    this.stepTimings = new Map()
     for (let i = 0; i < events.length; i++) {
       const event = events[i]
       /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
@@ -207,6 +214,7 @@ export class TranscriptAdapter {
       this.eventIndex.set(event.seq, event)
       this.indexCall(event, views?.[i])
       this.indexCommand(event)
+      indexAssistantStepTiming(this.stepTimings, event)
     }
     // Indexes first, then project: a tool/result materializes against the
     // complete call index, and a checkpoint against the complete event index.
@@ -229,6 +237,7 @@ export class TranscriptAdapter {
   append(event: SessionEvent, view?: ToolEventView): void {
     this.eventIndex.set(event.seq, event)
     this.indexCall(event, view)
+    indexAssistantStepTiming(this.stepTimings, event)
     if (this.indexCommand(event)) this.rev++
     if (!isTranscriptEvent(event)) return
     this.projected = [...this.projected, this.materialize(event)]
@@ -267,7 +276,7 @@ export class TranscriptAdapter {
   private materialize(event: SessionEvent): ConversationNode {
     return isCompactCheckpoint(event)
       ? materializeCompaction(event, this.eventIndex)
-      : materializeNode(event, this.callIdx, this.resultViews.get(event.seq) ?? null)
+      : materializeNode(event, this.callIdx, this.resultViews.get(event.seq) ?? null, this.stepTimings)
   }
 
   /**

packages/client/runtime/tests/transcript-adapter.spec.ts

@@ -408,4 +408,48 @@ describe('TranscriptAdapter', () => {
       expect(nodes[1]).toMatchObject({ name: 'compact', outcome: { kind: 'success', text: '已压缩' } })
     })
   })
+
+  describe('assistant timing', () => {
+    const base = 1_700_000_000_000
+
+    it('derives step timing across a window rebuild (start + first token + completion)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.turnStart(0, 0),
+        ev.user(1, '问'),
+        ev.stepStart(2, 0),
+        ev.chunkStart(3, 0),
+        ev.chunkText(4, 0, '答'),
+        ev.chunkText(5, 0, '案'),
+        ev.assistant(6, 0, '答案'),
+        ev.turnEnd(7, 0),
+      ])
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
+      })
+    })
+
+    it('derives the same timing on the live append path, first token winning once', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.user(0, '问')])
+      adapter.append(ev.stepStart(1, 0))
+      adapter.append(ev.chunkText(2, 0, '首'))
+      adapter.append(ev.chunkText(3, 0, '次'))
+      adapter.append(ev.assistant(4, 0, '首次'))
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
+      })
+    })
+
+    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
+      })
+    })
+  })
 })

packages/client/ui-conversation/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 337cfa1e3cc995a7338a1b0d634381c8beb0b2f3
-README.zh.md: 56e91847999fa9903b20467e5059e936eeca80d1
+README.md: c34a5027aa6c606b3e1704d24c542db82ed01e73
+README.zh.md: 3fdb165b868b002b2444e542a697d3f719a50c24

packages/client/ui-conversation/src/client/apply.ts

@@ -330,7 +330,7 @@ export function apply(ctx: Context): void {
   }, ChatView)
 
   // Session stats stick with the composer (composer.dock = stats-line family).
-  slots.register({ name: 'conversation.composer.dock', id: 'stats', order: 0 }, StatsLine)
+  slots.register({ name: 'conversation.composer.dock', id: 'stats', order: 0, locale: NS }, StatsLine)
 
   // Class-plugin mount (packages/AGENTS.md service form): the service
   // registers itself as `conversation` and lives on its own child fiber.

packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx

@@ -30,6 +30,10 @@ export interface AssistantMarkdownProps {
   /** Turn wall time in ms for the IconActions run-time label; omitted when the
    *  turn's triggering input is outside the loaded window. */
   runMs?: number | undefined
+  /** Turn first-step TTFT in ms for the IconActions label; omitted when unrecorded. */
+  ttftMs?: number | undefined
+  /** Turn decode throughput for the IconActions label; omitted when unrecorded. */
+  tokensPerSecond?: number | undefined
   /** Event sequence used as the fork boundary; omitted while streaming. */
   seq?: number | undefined
   /** Fork the session through this finalized message's completed turn when eligible. */
@@ -82,7 +86,7 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, seq, onFork, forkUnavailable, t,
+  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
@@ -125,6 +129,8 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
           text={copyText(blocks)}
           time={time}
           runMs={runMs}
+          ttftMs={ttftMs}
+          tokensPerSecond={tokensPerSecond}
           clock="end"
           onBranch={onFork === undefined || seq === undefined ? undefined : () => { onFork(seq) }}
           branchUnavailable={forkUnavailable}

packages/client/ui-conversation/src/client/chat/ChatView.tsx

@@ -36,6 +36,7 @@ import { GenericCommandCard } from './GenericCommandCard.tsx'
 import { GenericToolCard } from './GenericToolCard.tsx'
 import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
 import { formatRunDuration } from './message-chrome.ts'
+import { deriveTurnMetrics } from './turn-metrics.ts'
 import css from './ChatView.module.css'
 
 const FOLLOW_THRESHOLD = 24
@@ -362,6 +363,7 @@ export function ChatView({
   const actionSeqs = useMemo(() => assistantActionsSeqs(nodes), [nodes])
   const branchSeqs = useMemo(() => messageBranchSeqs(nodes, turnEnds), [nodes, turnEnds])
   const runningTurnStart = useMemo(() => runningTurnStartTime(turnTimings), [turnTimings])
+  const turnMetrics = useMemo(() => deriveTurnMetrics(nodes), [nodes])
 
   const listRef = useRef<HTMLDivElement | null>(null)
   const columnRef = useRef<HTMLDivElement | null>(null)
@@ -599,6 +601,9 @@ export function ChatView({
     const node: ConversationNode = item.node
     if (node.kind === 'assistant') {
       const timing = actionSeqs.has(node.seq) ? turnTimings.get(node.turn) : undefined
+      // Metrics gate on the settled in-window timing: turn/start loaded means
+      // every step of the turn is loaded, so first-step TTFT is genuine.
+      const metrics = timing?.endTime === undefined ? undefined : turnMetrics.get(node.turn)
       return (
         <AssistantMarkdown
           blocks={node.blocks}
@@ -608,6 +613,8 @@ export function ChatView({
           runMs={timing?.endTime === undefined
             ? undefined
             : Math.max(0, timing.endTime - timing.startTime)}
+          ttftMs={metrics?.ttftMs}
+          tokensPerSecond={metrics?.tokensPerSecond}
           seq={node.seq}
           onFork={forkAt}
           forkUnavailable={!branchSeqs.has(node.seq)}

packages/client/ui-conversation/src/client/chat/MessageIconActions.tsx

@@ -6,7 +6,7 @@ import {
   IconBranchOutline16, IconCheckOutline16, IconCopyOutline16, Tooltip, writeClipboard,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { formatMessageClock, formatRunDuration } from './message-chrome.ts'
+import { formatLatencySeconds, formatMessageClock, formatRunDuration, formatTokensPerSecond } from './message-chrome.ts'
 import { useCalendarDay } from './use-calendar-day.ts'
 import css from './MessageIconActions.module.css'
 
@@ -17,6 +17,10 @@ export interface MessageIconActionsProps {
   time?: number | undefined
   /** Turn wall time in ms, appended to the clock as `· Ran for 15s`; omitted when the turn's start is unknown. */
   runMs?: number | undefined
+  /** Turn first-step TTFT in ms, appended as `· TTFT 1.2s`; omitted when unrecorded. */
+  ttftMs?: number | undefined
+  /** Turn decode throughput, appended as `· 34 tok/s`; omitted when unrecorded. */
+  tokensPerSecond?: number | undefined
   /** Clock before icons (user) or after (assistant). */
   clock: 'start' | 'end'
   /** Fork the session at this message; omission hides the branch action. */
@@ -37,7 +41,7 @@ export interface MessageIconActionsProps {
  * @returns The actions row element.
  */
 export function MessageIconActions({
-  text, time, runMs, clock, onBranch, branchUnavailable = false, showBranch = true, className, t,
+  text, time, runMs, ttftMs, tokensPerSecond, clock, onBranch, branchUnavailable = false, showBranch = true, className, t,
 }: MessageIconActionsProps) {
   const day = useCalendarDay()
   const reasonId = useId()
@@ -67,15 +71,36 @@ export function MessageIconActions({
       }, 1000)
     })
   }, [copied, text])
+  // The dot is decorative and stays hidden, but its margins separate the
+  // readings only on screen: without the flanking spaces a reader hears one
+  // run-on string ("Ran for 13sTTFT 0.2s12 tok/s") instead of three facts.
   const clockEl = time === undefined ? null : (
     <span className={clock === 'start' ? css.timeStart : css.timeEnd}>
       {formatMessageClock(time, t, day)}
       {runMs !== undefined && (
         <>
+          {' '}
           <span className={css.runTimeDot} aria-hidden>·</span>
+          {' '}
           {t('message.ranFor', { duration: formatRunDuration(runMs, t) })}
         </>
       )}
+      {ttftMs !== undefined && (
+        <>
+          {' '}
+          <span className={css.runTimeDot} aria-hidden>·</span>
+          {' '}
+          {t('message.ttft', { seconds: formatLatencySeconds(ttftMs) })}
+        </>
+      )}
+      {tokensPerSecond !== undefined && (
+        <>
+          {' '}
+          <span className={css.runTimeDot} aria-hidden>·</span>
+          {' '}
+          {t('message.tokensPerSecond', { tps: formatTokensPerSecond(tokensPerSecond) })}
+        </>
+      )}
     </span>
   )
   return (

packages/client/ui-conversation/src/client/chat/StatsLine.tsx

@@ -2,10 +2,14 @@
 // Mounted on 'conversation.composer.dock' so it sticks with the composer in the
 // active conversation scrollport (see ConversationRoot data-conversation-scroll).
 
-import { Fragment, memo, useMemo } from 'react'
+import { Fragment, memo, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ConversationSnapshot, UseProjection } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
+import type { ComposerBarProps } from '../contract/slots.ts'
+import { formatTokensPerSecond } from './message-chrome.ts'
+import { assistantStepReading } from './turn-metrics.ts'
 import css from './StatsLine.module.css'
 
 interface WindowStats {
@@ -15,6 +19,14 @@ interface WindowStats {
   llmMs: number
   /** Summed tool wall time (tool/call → tool/result); 0 when no pair is in-window. */
   toolMs: number
+  /** Summed first-token latency over `ttftSteps`; 0 when no step records it. */
+  ttftMs: number
+  /** Steps carrying a recorded TTFT. */
+  ttftSteps: number
+  /** Summed decode wall time over steps that also report output tokens. */
+  decodeMs: number
+  /** Summed output tokens over the same decode-timed steps. */
+  decodeTokens: number
 }
 
 /**
@@ -32,6 +44,10 @@ export function deriveStats(nodes: ConversationSnapshot['nodes']): WindowStats {
   let steps = 0
   let llmMs = 0
   let toolMs = 0
+  let ttftMs = 0
+  let ttftSteps = 0
+  let decodeMs = 0
+  let decodeTokens = 0
   for (const node of nodes) {
     if (node.kind === 'tool-result') {
       if (node.callTime !== null) toolMs += Math.max(0, node.time - node.callTime)
@@ -43,8 +59,17 @@ export function deriveStats(nodes: ConversationSnapshot['nodes']): WindowStats {
     if (node.timing !== undefined && node.timing.stepStartTime !== null) {
       llmMs += Math.max(0, node.timing.completedTime - node.timing.stepStartTime)
     }
+    const reading = assistantStepReading(node)
+    if (reading.ttftMs !== null) {
+      ttftMs += reading.ttftMs
+      ttftSteps += 1
+    }
+    if (reading.decodeMs !== null && reading.outputTokens !== null) {
+      decodeMs += reading.decodeMs
+      decodeTokens += reading.outputTokens
+    }
   }
-  return { turns: turns.size, steps, llmMs, toolMs }
+  return { turns: turns.size, steps, llmMs, toolMs, ttftMs, ttftSteps, decodeMs, decodeTokens }
 }
 
 /**
@@ -84,30 +109,41 @@ export function cacheHitPercent(usage: TokenUsageProjection): number | null {
     : Math.round(usage.cacheReadTokens / denominator * 100)
 }
 
-/** Sum the three disjoint prompt-side billing buckets. */
-function billedInputTokens(usage: TokenUsageProjection): number {
+/**
+ * Sum the three disjoint prompt-side billing buckets.
+ * @param usage - the session's token-usage projection value.
+ * @returns billed input tokens.
+ */
+export function billedInputTokens(usage: TokenUsageProjection): number {
   return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
 }
 
 interface ContextOccupancy {
   percent: number
+  usedTokens: number
   contextWindow: number
 }
 
 /**
  * Approximate context occupancy, using the TUI's integer rounding and upper
- * clamp. The numerator and capacity are independent last-wins projection
- * fields, so this is a reference figure rather than an exact measurement of one
- * request (see the token-meter README).
+ * clamp. The numerator is `projectedTokens` — the provider sample carried
+ * forward over the surface's movement since — so compaction shows immediately
+ * instead of waiting for the next request to report usage; it falls back to the
+ * bare sample only for a log whose projection predates that field. Numerator
+ * and capacity remain independent last-wins projection fields, so this is a
+ * reference figure rather than an exact measurement of one request (see the
+ * token-meter README).
  * @param pressure - the session's context-pressure projection value.
- * @returns occupancy and its denominator, or null until both values are known.
+ * @returns occupancy with its numerator and denominator, or null until both values are known.
  */
 export function contextOccupancy(
   pressure: ContextPressureProjection | undefined,
 ): ContextOccupancy | null {
-  if (pressure?.pressureTokens === undefined || pressure.contextWindow === undefined) return null
+  const usedTokens = pressure?.projectedTokens ?? pressure?.pressureTokens
+  if (usedTokens === undefined || pressure?.contextWindow === undefined) return null
   return {
-    percent: Math.min(100, Math.round(pressure.pressureTokens / pressure.contextWindow * 100)),
+    percent: Math.min(100, Math.round(usedTokens / pressure.contextWindow * 100)),
+    usedTokens,
     contextWindow: pressure.contextWindow,
   }
 }
@@ -116,46 +152,73 @@ export function contextOccupancy(
 export interface StatsLineProps {
   useSession: SnapshotSelectorHook<ConversationSnapshot>
   useProjection: UseProjection
+  /** The owning dock's locale seat. */
+  t: ComposerBarProps['t']
 }
 
-export const StatsLine = memo(function StatsLine({ useSession, useProjection }: StatsLineProps) {
+export const StatsLine = memo(function StatsLine({ useSession, useProjection, t }: StatsLineProps) {
   const nodes = useSession(s => s.nodes)
   const usage = useProjection('tokenUsage')
-  const pressure = useProjection('contextPressure')
   const stats = useMemo(() => deriveStats(nodes), [nodes])
   // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
   const groups: string[] = []
   if (stats.steps > 0) {
-    groups.push(`${stats.turns} turns · ${stats.steps} steps`)
+    groups.push(t('stats.counts', { turns: stats.turns, steps: stats.steps }))
     const durations: string[] = []
-    if (stats.llmMs > 0) durations.push(`LLM ${formatDuration(stats.llmMs)}`)
-    if (stats.toolMs > 0) durations.push(`Tool call ${formatDuration(stats.toolMs)}`)
+    if (stats.llmMs > 0) durations.push(t('stats.llm', { duration: formatDuration(stats.llmMs) }))
+    if (stats.toolMs > 0) durations.push(t('stats.toolCall', { duration: formatDuration(stats.toolMs) }))
     if (durations.length > 0) groups.push(durations.join(' · '))
+    // Window-scoped like the wall times above: averages describe loaded steps.
+    const speeds: string[] = []
+    if (stats.ttftSteps > 0) {
+      speeds.push(t('stats.ttftAverage', { duration: formatDuration(stats.ttftMs / stats.ttftSteps) }))
+    }
+    if (stats.decodeMs > 0) {
+      speeds.push(t('stats.tokensPerSecond', {
+        throughput: formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000)),
+      }))
+    }
+    if (speeds.length > 0) groups.push(speeds.join(' · '))
   }
-  const context = contextOccupancy(pressure)
-  if (context !== null) {
-    groups.push(`Context ${context.percent}% of ${formatTokens(context.contextWindow)}`)
-  }
+  // Context occupancy deliberately lives on the composer's ContextMeter ring,
+  // not here — one home per fact.
   // Billing rides the durable projection, so these survive paging and
   // compaction. Suppress the empty projection on a brand-new session.
   if (usage !== undefined
     && (stats.steps > 0 || billedInputTokens(usage) > 0 || usage.outputTokens > 0)) {
     const cacheHit = cacheHitPercent(usage)
-    if (cacheHit !== null) groups.push(`Cache hit ${cacheHit}%`)
-    groups.push(
-      `Input ${formatTokens(billedInputTokens(usage))} tok`
-      + ` · Output ${formatTokens(usage.outputTokens)} tok`,
-    )
+    if (cacheHit !== null) groups.push(t('stats.cacheHit', { percent: cacheHit }))
+    groups.push(t('stats.tokens', {
+      input: formatTokens(billedInputTokens(usage)),
+      output: formatTokens(usage.outputTokens),
+    }))
   }
+  const line = groups.join(' | ')
+  // The row elides with ellipsis when overlong; a delayed hover tooltip carries
+  // the full line, enabled only while content is actually clipped.
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const [truncated, setTruncated] = useState(false)
+  useLayoutEffect(() => {
+    const el = rootRef.current
+    if (el === null) return
+    const measure = () => { setTruncated(el.scrollWidth > el.clientWidth) }
+    measure()
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    return () => { observer.disconnect() }
+  }, [line])
   if (groups.length === 0) return null
   return (
-    <div className={css.root}>
-      {groups.map((group, i) => (
-        <Fragment key={group}>
-          {i > 0 && <><span className={css.sep} aria-hidden>|</span>{' '}</>}
-          <span>{group}</span>
-        </Fragment>
-      ))}
-    </div>
+    <Tooltip label={line} side="top" delayMs={500} disabled={!truncated}>
+      <div ref={rootRef} className={css.root}>
+        {groups.map((group, i) => (
+          <Fragment key={group}>
+            {i > 0 && <><span className={css.sep} aria-hidden>|</span>{' '}</>}
+            <span>{group}</span>
+          </Fragment>
+        ))}
+      </div>
+    </Tooltip>
   )
 })

packages/client/ui-conversation/src/client/chat/message-chrome.ts

@@ -48,6 +48,27 @@ export function formatRunDuration(ms: number, t: RunDurationTranslate): string {
     : t('duration.seconds', { seconds })
 }
 
+/**
+ * Sub-turn latency figure: one decimal under ten seconds, whole seconds
+ * beyond. Unit-less so the locale template owns the second suffix.
+ * @param ms - Latency in milliseconds (negatives clamp to zero).
+ * @returns Display number in seconds without unit.
+ */
+export function formatLatencySeconds(ms: number): string {
+  const s = Math.max(0, ms) / 1000
+  return s < 10 ? String(Math.round(s * 10) / 10) : String(Math.round(s))
+}
+
+/**
+ * Decode-throughput figure: whole tokens from ten up, one decimal below.
+ * @param tps - Tokens per second.
+ * @returns Display number without unit.
+ */
+export function formatTokensPerSecond(tps: number): string {
+  const clamped = Math.max(0, tps)
+  return clamped >= 10 ? String(Math.round(clamped)) : String(Math.round(clamped * 10) / 10)
+}
+
 /**
  * Compact local timestamp for message IconActions. Same calendar day →
  * `HH:mm`; earlier this year → the `clock.md` date template + clock; other

packages/client/ui-conversation/src/client/chat/turn-metrics.ts

@@ -0,0 +1,97 @@
+// Latency/throughput folds shared by the settled turn footer and StatsLine.
+
+import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Latency and decode-throughput readings for one turn's footer. */
+export interface TurnMetrics {
+  /** First-step TTFT in ms; absent when that step carries no recorded timing. */
+  ttftMs?: number
+  /** Decode throughput over steps carrying both timing and provider usage. */
+  tokensPerSecond?: number
+}
+
+/** One assistant step's derivable latency facts; null marks an unrecorded part. */
+export interface StepReading {
+  /** step/start → first token delta, in ms. */
+  ttftMs: number | null
+  /** First token delta → final message, in ms. */
+  decodeMs: number | null
+  /** Provider-reported completion tokens. */
+  outputTokens: number | null
+}
+
+interface UsageLike {
+  outputTokens?: number
+}
+
+type AssistantNode = Extract<ConversationSnapshot['nodes'][number], { kind: 'assistant' }>
+
+function usageOutputTokens(usage: unknown): number | null {
+  if (typeof usage !== 'object' || usage === null) return null
+  const value = (usage as UsageLike).outputTokens
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null
+}
+
+/**
+ * Read one assistant node's TTFT, decode wall time, and output tokens.
+ * @param node - A settled assistant node.
+ * @returns Per-part readings with `null` for unrecorded values.
+ */
+export function assistantStepReading(node: AssistantNode): StepReading {
+  const timing = node.timing
+  const ttftMs = timing !== undefined && timing.stepStartTime !== null && timing.firstTokenTime !== null
+    ? Math.max(0, timing.firstTokenTime - timing.stepStartTime)
+    : null
+  const decodeMs = timing !== undefined && timing.firstTokenTime !== null
+    ? Math.max(0, timing.completedTime - timing.firstTokenTime)
+    : null
+  return { ttftMs, decodeMs, outputTokens: usageOutputTokens(node.usage) }
+}
+
+interface TurnFold {
+  firstStep: number
+  firstStepTtftMs: number | null
+  decodeMs: number
+  outputTokens: number
+  sampled: boolean
+}
+
+/**
+ * Fold assistant nodes into per-turn footer metrics.
+ *
+ * TTFT is the turn's lowest-step request-dispatch-to-first-token reading, so
+ * it is only meaningful when the turn's start is inside
+ * the loaded window (the caller gates on `turnTimings`, which shares that
+ * window). Throughput divides summed output tokens by summed decode wall time,
+ * counting only steps that carry both.
+ * @param nodes - Snapshot nodes of the loaded window.
+ * @returns Turn number → available metrics; turns with none are absent.
+ */
+export function deriveTurnMetrics(nodes: ConversationSnapshot['nodes']): Map<number, TurnMetrics> {
+  const folds = new Map<number, TurnFold>()
+  for (const node of nodes) {
+    if (node.kind !== 'assistant') continue
+    const reading = assistantStepReading(node)
+    let fold = folds.get(node.turn)
+    if (fold === undefined) {
+      fold = { firstStep: node.step, firstStepTtftMs: reading.ttftMs, decodeMs: 0, outputTokens: 0, sampled: false }
+      folds.set(node.turn, fold)
+    } else if (node.step < fold.firstStep) {
+      fold.firstStep = node.step
+      fold.firstStepTtftMs = reading.ttftMs
+    }
+    if (reading.decodeMs !== null && reading.outputTokens !== null) {
+      fold.decodeMs += reading.decodeMs
+      fold.outputTokens += reading.outputTokens
+      fold.sampled = true
+    }
+  }
+  const metrics = new Map<number, TurnMetrics>()
+  for (const [turn, fold] of folds) {
+    const entry: TurnMetrics = {}
+    if (fold.firstStepTtftMs !== null) entry.ttftMs = fold.firstStepTtftMs
+    if (fold.sampled && fold.decodeMs > 0) entry.tokensPerSecond = fold.outputTokens / (fold.decodeMs / 1000)
+    if (entry.ttftMs !== undefined || entry.tokensPerSecond !== undefined) metrics.set(turn, entry)
+  }
+  return metrics
+}

packages/client/ui-conversation/src/client/locales.ts

@@ -23,6 +23,18 @@ export const zh = {
   'input.stop': '停止生成',
   'input.send': '发送消息',
   'input.accessMode': '访问模式，当前：{name}',
+  'context.aria': '上下文已用 {percent}',
+  'context.used': '上下文已用',
+  'context.system': '系统提示词',
+  'context.tools': '工具',
+  'context.messages': '对话消息',
+  'stats.counts': '{turns} 轮 · {steps} 步',
+  'stats.llm': 'LLM {duration}',
+  'stats.toolCall': '工具调用 {duration}',
+  'stats.ttftAverage': '首 token 平均 {duration}',
+  'stats.tokensPerSecond': '{throughput} tok/s',
+  'stats.cacheHit': '缓存命中 {percent}%',
+  'stats.tokens': '输入 {input} tok · 输出 {output} tok',
   'settings.enter.title': '繁忙时 Enter 键行为',
   'settings.enter.description': '仅在智能体运行时生效；Cmd/Ctrl+Enter 使用另一行为',
   'settings.enter.queue': '排队发送',
@@ -71,6 +83,8 @@ export const zh = {
   'message.retry.failure': '失败原因：',
   'message.turnError': '本轮运行失败',
   'message.ranFor': '用时 {duration}',
+  'message.ttft': '首 token {seconds}秒',
+  'message.tokensPerSecond': '{tps} tok/s',
   'duration.seconds': '{seconds}秒',
   'duration.minutes': '{minutes}分{seconds}秒',
   'command.running': '执行中…',
@@ -136,6 +150,18 @@ export const en = {
   'input.stop': 'Stop generating',
   'input.send': 'Send message',
   'input.accessMode': 'Access mode, current: {name}',
+  'context.aria': '{percent} of context used',
+  'context.used': 'of context used',
+  'context.system': 'System prompt',
+  'context.tools': 'Tools',
+  'context.messages': 'Messages',
+  'stats.counts': '{turns} turns · {steps} steps',
+  'stats.llm': 'LLM {duration}',
+  'stats.toolCall': 'Tool call {duration}',
+  'stats.ttftAverage': 'TTFT avg {duration}',
+  'stats.tokensPerSecond': '{throughput} tok/s',
+  'stats.cacheHit': 'Cache hit {percent}%',
+  'stats.tokens': 'Input {input} tok · Output {output} tok',
   'settings.enter.title': 'Enter behavior while busy',
   'settings.enter.description': 'Busy only; Cmd/Ctrl+Enter uses the other behavior',
   'settings.enter.queue': 'Queue',
@@ -184,6 +210,8 @@ export const en = {
   'message.retry.failure': 'Failure reason: ',
   'message.turnError': 'This turn failed',
   'message.ranFor': 'Ran for {duration}',
+  'message.ttft': 'TTFT {seconds}s',
+  'message.tokensPerSecond': '{tps} tok/s',
   'duration.seconds': '{seconds}s',
   'duration.minutes': '{minutes}m {seconds}s',
   'command.running': 'Running…',

packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css

@@ -0,0 +1,147 @@
+/* Context-occupancy ring beside the send button plus its click-open breakdown
+   panel (menu surface: r12, inverted hairline, shadow-lv3). */
+
+.root {
+  position: relative;
+  display: inline-flex;
+}
+
+/* Same 28px circular hit target family as the composer's attach button. */
+.trigger {
+  display: grid;
+  place-items: center;
+  flex: none;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.trigger:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.track {
+  fill: none;
+  stroke: var(--dsw-alias-border-l3);
+  stroke-width: 2;
+}
+
+.fill {
+  fill: none;
+  stroke: var(--dsw-alias-label-tertiary);
+  stroke-width: 2;
+  stroke-linecap: round;
+}
+
+.panel {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 0;
+  z-index: 100;
+  box-sizing: border-box;
+  width: 264px;
+  padding: 12px;
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 12px;
+  background: var(--dsw-specific-menu);
+  box-shadow: var(--dsw-shadow-lv3);
+  font-size: 12px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-secondary);
+  cursor: default;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.figures {
+  margin-left: auto;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+  color: var(--dsw-alias-label-primary);
+}
+
+.percent {
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary);
+}
+
+.headline {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* The headline brackets the reading, so the side a locale leaves empty must
+   drop out of the flex row rather than spend a gap. */
+.headline:empty {
+  display: none;
+}
+
+.bar {
+  display: flex;
+  gap: 1px;
+  margin: 10px 0 12px;
+  height: 4px;
+  border-radius: 999px;
+  background: var(--dsw-alias-interactive-bg-hover);
+  overflow: hidden;
+}
+
+.segment {
+  flex: none;
+  min-width: 2px;
+  height: 100%;
+  border-radius: 1px;
+  background: var(--meter-tint, var(--dsw-alias-label-tertiary));
+}
+
+.swatch {
+  display: inline-block;
+  margin-right: 6px;
+  width: 8px;
+  height: 8px;
+  border-radius: 2px;
+  background: var(--meter-tint);
+  vertical-align: baseline;
+}
+
+.colorSystem {
+  --meter-tint: var(--dsw-static-neutral-bluish-400);
+}
+
+.colorTools {
+  /* The design platform ships no purple static token; violet-400 literal. */
+  --meter-tint: rgb(167, 139, 250);
+}
+
+.colorMessages {
+  --meter-tint: var(--dsw-static-blue-450);
+}
+
+.rows {
+  margin: 6px 0 0;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 2px 0;
+}
+
+.row dt {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.row dd {
+  margin: 0;
+  font-variant-numeric: tabular-nums;
+  color: var(--dsw-alias-label-primary);
+}

packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx

@@ -0,0 +1,153 @@
+/** Composer context-occupancy meter: a ring beside the send button fed by the
+ * `contextPressure` projection, with a click-open panel of the heuristic
+ * `contextBreakdown` composition (system prompt, tools, conversation).
+ * Renders nothing until a provider reports both pressure and a route capacity
+ * (same gate as the stats row used). */
+
+import { useEffect, useRef, useState } from 'react'
+import type { UseProjection } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: the `contextPressure` / `contextBreakdown` projection key merges.
+import type {} from '@deepseek-ai/dsh-token-meter/client'
+import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ComposerBarProps } from '../contract/slots.ts'
+import { contextOccupancy, formatTokens } from '../chat/StatsLine.tsx'
+import css from './ContextMeter.module.css'
+
+/** Ring geometry: 14px viewBox, 2px stroke. */
+const RADIUS = 5.5
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS
+
+/**
+ * Marker the localized occupancy sentence is split on, so the panel headline
+ * keeps the reading in its own tone while each locale still owns the word
+ * order (`45% of context used` / `上下文已用 45%`).
+ */
+const READING_SLOT = '\u0000'
+
+/** Panel legend rows, in bar-segment order; each color class carries the shared swatch/segment tint. */
+const ROWS = [
+  { key: 'systemTokens', label: 'context.system', color: css.colorSystem },
+  { key: 'toolsTokens', label: 'context.tools', color: css.colorTools },
+  { key: 'messageTokens', label: 'context.messages', color: css.colorMessages },
+] as const
+
+export interface ContextMeterProps {
+  useProjection: UseProjection
+  /** The owning bar's locale seat, passed down as a plain prop. */
+  t: ComposerBarProps['t']
+}
+
+export function ContextMeter({ useProjection, t }: ContextMeterProps) {
+  const pressure = useProjection('contextPressure')
+  const breakdown = useProjection('contextBreakdown')
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLSpanElement | null>(null)
+  const context = contextOccupancy(pressure)
+  const available = context !== null
+
+  // A model switch can temporarily remove capacity while this component stays
+  // mounted. Close the now-unavailable panel instead of preserving stale UI.
+  useEffect(() => {
+    if (!available && open) setOpen(false)
+  }, [available, open])
+
+  // Outside click / Escape close, one document listener while open (Menu's pattern).
+  useEffect(() => {
+    if (!open || !available) return
+    const onPointerDown = (e: PointerEvent): void => {
+      if (e.target instanceof Node && rootRef.current?.contains(e.target) === true) return
+      setOpen(false)
+    }
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('pointerdown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [available, open])
+
+  if (context === null) return null
+  const percent = context.percent
+  const reading = `${percent}%`
+  const [headBefore = '', headAfter = ''] = t('context.aria', { percent: READING_SLOT })
+    .split(READING_SLOT)
+    .map(part => part.trim())
+
+  // The bar's overall length stays the provider-exact percent; the heuristic
+  // breakdown only proportions its colored parts. A zero-width part is dropped
+  // instead of rendered: `.segment`'s min-width keeps a hairline part visible,
+  // which at 0% occupancy would draw a filled bar over an empty context.
+  const breakdownTotal = breakdown === undefined
+    ? 0
+    : breakdown.systemTokens + breakdown.toolsTokens + breakdown.messageTokens
+  const parts = breakdown === undefined || breakdownTotal === 0
+    ? [{ key: 'total', color: undefined, width: percent }]
+    : ROWS.map(row => ({ key: row.key, color: row.color, width: percent * breakdown[row.key] / breakdownTotal }))
+  const segments = parts.filter(part => part.width > 0)
+
+  return (
+    <span ref={rootRef} className={css.root}>
+      <Tooltip label={t('context.aria', { percent: reading })} side="top" delayMs={200} disabled={open}>
+        <button
+          type="button"
+          className={css.trigger}
+          aria-label={t('context.aria', { percent: reading })}
+          aria-haspopup="dialog"
+          aria-expanded={open}
+          onClick={() => { setOpen(!open) }}
+        >
+          <svg viewBox="0 0 14 14" width="14" height="14" aria-hidden>
+            <circle className={css.track} cx="7" cy="7" r={RADIUS} />
+            <circle
+              className={css.fill}
+              cx="7"
+              cy="7"
+              r={RADIUS}
+              strokeDasharray={`${CIRCUMFERENCE * percent / 100} ${CIRCUMFERENCE}`}
+              transform="rotate(-90 7 7)"
+            />
+          </svg>
+        </button>
+      </Tooltip>
+      {open && (
+        <div className={css.panel} role="dialog" aria-label={t('context.used')}>
+          <div className={css.header}>
+            {/* Empty sides collapse through `.headline:empty` so the locale that
+                needs no leading (or trailing) text spends no header gap. */}
+            <span className={css.headline}>{headBefore}</span>
+            <span className={css.percent}>{reading}</span>
+            <span className={css.headline}>{headAfter}</span>
+            <span className={css.figures}>
+              {`~${formatTokens(context.usedTokens)} / ${formatTokens(context.contextWindow)}`}
+            </span>
+          </div>
+          <div className={css.bar}>
+            {segments.map(segment => (
+              <div
+                key={segment.key}
+                className={segment.color === undefined ? css.segment : `${css.segment} ${segment.color}`}
+                style={{ width: `${segment.width}%` }}
+              />
+            ))}
+          </div>
+          {breakdown !== undefined && (
+            <dl className={css.rows}>
+              {ROWS.map(row => (
+                <div key={row.key} className={css.row}>
+                  <dt>
+                    <span className={`${css.swatch} ${row.color}`} aria-hidden />
+                    {t(row.label)}
+                  </dt>
+                  <dd>{`~${formatTokens(breakdown[row.key])}`}</dd>
+                </div>
+              ))}
+            </dl>
+          )}
+        </div>
+      )}
+    </span>
+  )
+}

packages/client/ui-conversation/src/client/skeleton/InputBar.tsx

@@ -19,6 +19,7 @@ import type { Translate } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ComposerBarProps } from '../contract/slots.ts'
 import { deriveDecorations } from '../input/decorations.ts'
 import type { DraftDecorations } from '../input/decorations.ts'
+import { ContextMeter } from './ContextMeter.tsx'
 import { PermissionSelect } from './PermissionSelect.tsx'
 import css from './InputBar.module.css'
 
@@ -512,6 +513,7 @@ export function InputBar({
           <div className={css.trailing}>
             {rightItems}
             {renderSlot('conversation.input.model', { locked })}
+            <ContextMeter useProjection={useProjection} t={t} />
             {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
             <Tooltip label={primaryLabel} side="top" delayMs={500}>
               <button

packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx

@@ -18,9 +18,18 @@ import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
 import { StatsLine, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 import { zh } from '../src/client/locales.ts'
 
+/** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
+class ResizeObserverStub {
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+
+beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
 afterEach(() => {
   cleanup()
   vi.useRealTimers()
+  vi.unstubAllGlobals()
 })
 
 // Mirrors the real lookup chain (conversation namespace, then common).
@@ -545,12 +554,13 @@ describe('small branch tails', () => {
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
       <StatsLine
+        t={t}
         useSession={bindSnapshotSelector(source) as unknown as StatsLineProps['useSession']}
         useProjection={(key: string) => key === 'tokenUsage'
           ? { uncachedInputTokens: 0, outputTokens: 10, cacheReadTokens: 0, cacheWriteTokens: 0 }
           : undefined}
       />,
     )
-    expect(view.container.textContent).toBe('1 turns · 1 steps| Input 0 tok · Output 10 tok')
+    expect(view.container.textContent).toBe('1 轮 · 1 步| 输入 0 tok · 输出 10 tok')
   })
 })

packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx

@@ -3,25 +3,40 @@
 // hard acceptance — zero renders during streaming. Bash sample row: ToolRow
 // chrome (Bash · description) without a row click target.
 
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type {
   AssistantMessageNode, ConversationSnapshot, SessionId, SessionListState, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { StatsLine, deriveStats, formatDuration, formatTokens, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
+import { StatsLine, contextOccupancy, deriveStats, formatDuration, formatTokens, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
-import { zh } from '../src/client/locales.ts'
+import { en, zh } from '../src/client/locales.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: BashRowProps['t'] = makeTranslate(zh, commonZh)
+const tEn: StatsLineProps['t'] = makeTranslate(en, commonEn)
 
-afterEach(cleanup)
+/** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
+class ResizeObserverStub {
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+
+beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+})
 
 const SID = 's1' as SessionId
 
@@ -66,8 +81,11 @@ describe('deriveStats', () => {
     expect(stats.turns).toBe(2)
     expect(stats.steps).toBe(3)
     // Window-scoped by design: the paged window is not an accounting source, so
-    // the fold exposes no token fields at all (billing rides the projection).
-    expect(Object.keys(stats).sort()).toEqual(['llmMs', 'steps', 'toolMs', 'turns'])
+    // the fold exposes no billing fields (billing rides the projection);
+    // decodeTokens is a throughput input, not a billed total.
+    expect(Object.keys(stats).sort()).toEqual(
+      ['decodeMs', 'decodeTokens', 'llmMs', 'steps', 'toolMs', 'ttftMs', 'ttftSteps', 'turns'],
+    )
   })
 
   it('ignores tool results with no call time', () => {
@@ -97,6 +115,23 @@ describe('deriveStats', () => {
     expect(stats.llmMs).toBe(2_500)
     expect(stats.toolMs).toBe(3_000)
   })
+
+  it('sums ttft per recorded step and decode throughput inputs per usage-carrying step', () => {
+    const sampled: AssistantMessageNode = {
+      ...assistant(1, 1, { outputTokens: 40 }),
+      timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
+    }
+    const ttftOnly: AssistantMessageNode = {
+      ...assistant(2, 1),
+      timing: { stepStartTime: 5_000, firstTokenTime: 5_400, completedTime: 7_400 },
+    }
+    const stats = deriveStats([sampled, ttftOnly, assistant(3, 2)])
+    expect(stats.ttftMs).toBe(1_200)
+    expect(stats.ttftSteps).toBe(2)
+    // The usage-less step contributes no decode share, keeping the ratio honest.
+    expect(stats.decodeMs).toBe(3_000)
+    expect(stats.decodeTokens).toBe(40)
+  })
 })
 
 describe('formatters', () => {
@@ -125,7 +160,7 @@ describe('StatsLine', () => {
     source: { getSnapshot(): ConversationSnapshot; subscribe(fn: () => void): () => void },
     values: Record<string, unknown> = { tokenUsage: USAGE },
   ): StatsLineProps {
-    return { useSession: bindSnapshotSelector(source), useProjection: projections(values) }
+    return { useSession: bindSnapshotSelector(source), useProjection: projections(values), t: tEn }
   }
 
   it('renders the grouped stats row and hides a brand-new empty session', () => {
@@ -142,47 +177,84 @@ describe('StatsLine', () => {
     expect(emptyView.container.textContent).toBe('')
   })
 
-  it('keeps durable token and context groups after the visible step window is empty', () => {
-    const { source } = makeSource()
-    const view = render(<StatsLine {...props(source, {
-      tokenUsage: USAGE,
-      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
-    })} />)
-    expect(view.container.textContent)
-      .toBe('Context 25% of 128K| Cache hit 90%| Input 100 tok · Output 5 tok')
+  it('reveals the full line in a delayed hover tooltip only while the row is clipped', () => {
+    vi.useFakeTimers()
+    // jsdom lays nothing out; fake a row narrower than its content.
+    vi.spyOn(Element.prototype, 'scrollWidth', 'get').mockReturnValue(800)
+    vi.spyOn(Element.prototype, 'clientWidth', 'get').mockReturnValue(400)
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source)} />)
+    fireEvent.mouseEnter(view.container.firstElementChild!)
+    act(() => { vi.advanceTimersByTime(499) })
+    expect(view.container.querySelector('[role="tooltip"]')).toBeNull()
+    act(() => { vi.advanceTimersByTime(1) })
+    expect(view.container.querySelector('[role="tooltip"]')?.textContent)
+      .toBe('1 turns · 1 steps | Cache hit 90% | Input 100 tok · Output 5 tok')
   })
 
-  it('renders context occupancy only when the projection knows a capacity', () => {
+  it('suppresses the tooltip while the row fits without truncation', () => {
+    vi.useFakeTimers()
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const withCapacity = render(<StatsLine {...props(source, {
-      tokenUsage: USAGE,
-      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
-    })} />)
-    expect(withCapacity.container.textContent).toContain('Context 25% of 128K')
-    // Pressure without capacity has no denominator: the group drops out.
-    const noCapacity = render(<StatsLine {...props(source, {
-      tokenUsage: USAGE,
-      contextPressure: { pressureTokens: 32_000 },
-    })} />)
-    expect(noCapacity.container.textContent).not.toContain('Context')
-    // Capacity arrives before usage in the log; no provider sample means there
-    // is no numerator yet, rather than a synthetic 0%.
-    const noPressure = render(<StatsLine {...props(source, {
-      tokenUsage: USAGE,
-      contextPressure: { contextWindow: 128_000 },
-    })} />)
-    expect(noPressure.container.textContent).not.toContain('Context')
+    const view = render(<StatsLine {...props(source)} />)
+    fireEvent.mouseEnter(view.container.firstElementChild!)
+    act(() => { vi.advanceTimersByTime(500) })
+    expect(view.container.querySelector('[role="tooltip"]')).toBeNull()
+  })
+
+  it('renders window latency and throughput beside the wall-time group', () => {
+    const timed: AssistantMessageNode = {
+      ...assistant(1, 1, { outputTokens: 60 }),
+      timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
+    }
+    const { source } = makeSource({ nodes: [timed] })
+    const view = render(<StatsLine {...props(source)} />)
+    expect(view.container.textContent).toContain('LLM 3.8s| TTFT avg 0.8s · 20 tok/s')
+  })
+
+  it('takes every stats label from the active locale', () => {
+    const timed: AssistantMessageNode = {
+      ...assistant(1, 1, { outputTokens: 60 }),
+      timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
+    }
+    const { source } = makeSource({ nodes: [timed] })
+    const view = render(<StatsLine {...props(source)} t={t} />)
+    expect(view.container.textContent)
+      .toBe('1 轮 · 1 步| LLM 3.8s| 首 token 平均 0.8s · 20 tok/s| 缓存命中 90%| 输入 100 tok · 输出 5 tok')
   })
 
-  it('clamps occupancy at 100% when pressure exceeds the recorded capacity', () => {
-    // Capacity and pressure are independent last-wins fields, so a model switch
-    // can pair a smaller new window with the previous route's larger prompt.
+  it('renders without ResizeObserver support', () => {
+    vi.unstubAllGlobals()
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    expect(() => render(<StatsLine {...props(source)} />)).not.toThrow()
+  })
+
+  it('keeps durable token groups after the visible step window is empty', () => {
+    const { source } = makeSource()
     const view = render(<StatsLine {...props(source, {
       tokenUsage: USAGE,
-      contextPressure: { pressureTokens: 300_000, contextWindow: 128_000 },
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
     })} />)
-    expect(view.container.textContent).toContain('Context 100% of 128K')
+    // Context occupancy lives on the composer's ContextMeter ring, not here.
+    expect(view.container.textContent)
+      .toBe('Cache hit 90%| Input 100 tok · Output 5 tok')
+  })
+
+  it('computes context occupancy only when both a numerator and capacity are known', () => {
+    // The projected figure wins: it is the provider sample carried forward over
+    // the surface's movement, so a compaction shows without waiting a request.
+    expect(contextOccupancy({ pressureTokens: 32_000, projectedTokens: 6_000, contextWindow: 128_000 }))
+      .toEqual({ percent: 5, usedTokens: 6_000, contextWindow: 128_000 })
+    // A log whose projection predates the field still reads its bare sample.
+    expect(contextOccupancy({ pressureTokens: 32_000, contextWindow: 128_000 }))
+      .toEqual({ percent: 25, usedTokens: 32_000, contextWindow: 128_000 })
+    // A numerator without capacity has no denominator; capacity without a
+    // provider sample has no numerator yet, rather than a synthetic 0%.
+    expect(contextOccupancy({ pressureTokens: 32_000 })).toBeNull()
+    expect(contextOccupancy({ contextWindow: 128_000 })).toBeNull()
+    expect(contextOccupancy(undefined)).toBeNull()
+    // Capacity and the sample are independent last-wins fields, so a model
+    // switch can pair a smaller new window with the previous route's prompt.
+    expect(contextOccupancy({ pressureTokens: 300_000, contextWindow: 128_000 })?.percent).toBe(100)
   })
 
   it('drops every token group when no projection is composed', () => {

packages/client/ui-conversation/tests/chat-view.spec.tsx

@@ -534,6 +534,45 @@ describe('ChatView', () => {
     expect(view.getAllByText(/用时 19秒/)).toHaveLength(1)
   })
 
+  it('the settled footer appends first-step ttft and turn decode throughput', () => {
+    const first: AssistantMessageNode = {
+      kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 1, blocks: [{ kind: 'text', text: 'mid' }],
+      timing: { stepStartTime: 1_000, firstTokenTime: 2_200, completedTime: 5_200 },
+      usage: { outputTokens: 40 },
+    }
+    const second: AssistantMessageNode = {
+      kind: 'assistant', seq: 16, time: 16_000, turn: 1, step: 2, blocks: [{ kind: 'text', text: 'final' }],
+      timing: { stepStartTime: 10_000, firstTokenTime: 10_200, completedTime: 12_200 },
+      usage: { outputTokens: 60 },
+    }
+    const h = makeHarness({
+      nodes: [user(1, 'hi'), first, second],
+      turnTimings: new Map([[1, { startTime: 1_000, endTime: 20_000 }]]),
+      turnEnds: new Map([[1, 20]]),
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    // First-step ttft (1.2s) plus 100 tokens over 5s of decode.
+    expect(view.getAllByText(/用时 19秒/)).toHaveLength(1)
+    expect(view.getAllByText(/首 token 1\.2秒/)).toHaveLength(1)
+    expect(view.getAllByText(/20 tok\/s/)).toHaveLength(1)
+  })
+
+  it('withholds ttft and throughput while the turn is still running', () => {
+    const settled: AssistantMessageNode = {
+      kind: 'assistant', seq: 2, time: 2_000, turn: 1, step: 1, blocks: [{ kind: 'text', text: 'answer' }],
+      timing: { stepStartTime: 1_000, firstTokenTime: 1_500, completedTime: 2_000 },
+      usage: { outputTokens: 10 },
+    }
+    const h = makeHarness({
+      nodes: [user(1, 'hi'), settled],
+      turnTimings: new Map([[1, { startTime: 1_000 }]]),
+      turnEnds: new Map(),
+      running: true,
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.queryByText(/首 token|tok\/s/)).toBeNull()
+  })
+
   it('user and assistant message containers scope the hover-revealed time chrome', () => {
     const h = makeHarness({
       nodes: [user(1, 'hi'), assistant(2, 'answer')],

packages/client/ui-conversation/tests/context-meter.spec.tsx

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+// ContextMeter (composer trailing control): occupancy ring gating, the
+// click-open breakdown panel, and its close gestures.
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { en as commonEn, zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/index.ts'
+import { ContextMeter, type ContextMeterProps } from '../src/client/skeleton/ContextMeter.tsx'
+import css from '../src/client/skeleton/ContextMeter.module.css'
+import { en, zh } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+// Mirrors the real lookup chain (conversation namespace, then common).
+const t = makeTranslate(zh, commonZh) as ContextMeterProps['t']
+const tEn = makeTranslate(en, commonEn) as ContextMeterProps['t']
+
+const BREAKDOWN = { systemTokens: 120, toolsTokens: 21_500, messageTokens: 477_000 }
+
+const segmentClass = css.segment
+if (segmentClass === undefined) throw new Error('segment class missing from ContextMeter.module.css')
+
+/** Stub the projection seat: a key-addressed table of whole values. */
+function projections(values: Record<string, unknown>): ContextMeterProps['useProjection'] {
+  return (key: string) => values[key]
+}
+
+function meter(values: Record<string, unknown>, translate: ContextMeterProps['t'] = t) {
+  return render(<ContextMeter useProjection={projections(values)} t={translate} />)
+}
+
+describe('ContextMeter', () => {
+  it('renders nothing until both pressure and capacity are known', () => {
+    expect(meter({}).container.textContent).toBe('')
+    expect(meter({ contextPressure: { pressureTokens: 32_000 } }).container.textContent).toBe('')
+    expect(meter({ contextPressure: { contextWindow: 128_000 } }).container.textContent).toBe('')
+  })
+
+  it('shows the occupancy ring and opens the breakdown panel on click', () => {
+    const view = meter({
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    })
+    const trigger = view.getByRole('button', { name: '上下文已用 25%' })
+    expect(view.container.querySelector('[role="dialog"]')).toBeNull()
+    fireEvent.click(trigger)
+    const panel = view.container.querySelector('[role="dialog"]')!
+    expect(panel.textContent).toContain('~32K / 128K')
+    expect(panel.textContent).toContain('25%')
+    expect(panel.textContent).toContain('上下文已用')
+    expect(panel.textContent).toContain('系统提示词~120')
+    expect(panel.textContent).toContain('工具~21.5K')
+    expect(panel.textContent).toContain('对话消息~477K')
+    // The occupancy bar splits into one colored segment per composition row.
+    expect(panel.getElementsByClassName(segmentClass)).toHaveLength(3)
+    // Clicking the trigger again toggles the panel shut.
+    fireEvent.click(trigger)
+    expect(view.container.querySelector('[role="dialog"]')).toBeNull()
+  })
+
+  it('lets each locale own the headline word order around the reading', () => {
+    const values = {
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    }
+    const zhView = meter(values)
+    fireEvent.click(zhView.getByRole('button', { name: '上下文已用 25%' }))
+    // The reading follows the label in Chinese and leads it in English; both
+    // headers read as one sentence rather than a concatenated fragment.
+    expect(zhView.container.querySelector('[role="dialog"]')!.textContent)
+      .toMatch(/^上下文已用25%/)
+    const enView = meter(values, tEn)
+    fireEvent.click(enView.getByRole('button', { name: '25% of context used' }))
+    expect(enView.container.querySelector('[role="dialog"]')!.textContent)
+      .toMatch(/^25%of context used/)
+  })
+
+  it('draws no bar segment at zero occupancy', () => {
+    const view = meter({
+      contextPressure: { pressureTokens: 0, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    })
+    fireEvent.click(view.getByRole('button', { name: '上下文已用 0%' }))
+    const panel = view.container.querySelector('[role="dialog"]')!
+    // `.segment` carries a min-width, so a zero-width part would still paint a
+    // filled sliver over an empty context.
+    expect(panel.getElementsByClassName(segmentClass)).toHaveLength(0)
+    expect(panel.textContent).toContain('~0 / 128K')
+  })
+
+  it('reads the ring from the projected figure so a compaction shows at once', () => {
+    // Same provider sample, a surface a compaction just shrank: the ring must
+    // follow the projection rather than the sample it is anchored to.
+    const view = meter({
+      contextPressure: { pressureTokens: 32_000, projectedTokens: 3_000, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    })
+    const trigger = view.getByRole('button', { name: '上下文已用 2%' })
+    fireEvent.click(trigger)
+    expect(view.container.querySelector('[role="dialog"]')!.textContent).toContain('~3K / 128K')
+  })
+
+  it('omits the composition rows while the contextBreakdown projection is absent', () => {
+    const view = meter({ contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 } })
+    fireEvent.click(view.getByRole('button', { name: '上下文已用 25%' }))
+    const panel = view.container.querySelector('[role="dialog"]')!
+    expect(panel.textContent).toContain('~32K / 128K')
+    expect(panel.textContent).not.toContain('系统提示词')
+    expect(panel.textContent).not.toContain('对话消息')
+    // Without composition shares, the bar falls back to one plain segment.
+    expect(panel.getElementsByClassName(segmentClass)).toHaveLength(1)
+  })
+
+  it('closes when capacity disappears and stays closed when it returns', () => {
+    let values: Record<string, unknown> = {
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    }
+    const view = render(<ContextMeter useProjection={(key: string) => values[key]} t={t} />)
+    fireEvent.click(view.getByRole('button', { name: '上下文已用 25%' }))
+    expect(view.container.querySelector('[role="dialog"]')).not.toBeNull()
+
+    values = { contextPressure: { pressureTokens: 32_000 }, contextBreakdown: BREAKDOWN }
+    view.rerender(<ContextMeter useProjection={(key: string) => values[key]} t={t} />)
+    expect(view.container.textContent).toBe('')
+
+    values = {
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    }
+    view.rerender(<ContextMeter useProjection={(key: string) => values[key]} t={t} />)
+    expect(view.getByRole('button', { name: '上下文已用 25%' }).getAttribute('aria-expanded')).toBe('false')
+    expect(view.container.querySelector('[role="dialog"]')).toBeNull()
+  })
+
+  it('closes on outside pointerdown and Escape — but not inside clicks', () => {
+    const view = meter({
+      contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+      contextBreakdown: BREAKDOWN,
+    })
+    const trigger = view.getByRole('button', { name: '上下文已用 25%' })
+    const openPanel = () => {
+      fireEvent.click(trigger)
+      return view.container.querySelector('[role="dialog"]')!
+    }
+    // A pointerdown inside the panel keeps it open; outside closes it.
+    const again = openPanel()
+    fireEvent.pointerDown(again)
+    expect(view.container.querySelector('[role="dialog"]')).not.toBeNull()
+    fireEvent.pointerDown(document.body)
+    expect(view.container.querySelector('[role="dialog"]')).toBeNull()
+    // Escape.
+    openPanel()
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(view.container.querySelector('[role="dialog"]')).toBeNull()
+  })
+})

packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -18,7 +18,18 @@ import { zh } from '../src/client/locales.ts'
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
 
-afterEach(cleanup)
+/** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
+class ResizeObserverStub {
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+
+beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
 
 const SID = 's1' as SessionId
 
@@ -56,11 +67,12 @@ describe('render branch tails', () => {
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
       <StatsLine
+        t={t}
         useSession={bindSnapshotSelector(source) as unknown as UseSession<ConversationSnapshot>}
         useProjection={() => undefined}
       />,
     )
-    expect(view.container.textContent).toBe('2 turns · 3 steps')
+    expect(view.container.textContent).toBe('2 轮 · 3 步')
   })
 
   it('AssistantMarkdown reasoning as the streaming tail renders the running ring', () => {

packages/client/ui-conversation/tests/turn-metrics.spec.ts

@@ -0,0 +1,154 @@
+// Per-turn latency/throughput fold and the footer figure formatters.
+
+import { describe, expect, it } from 'vitest'
+import type { AssistantMessageNode, ConversationNode, UserMessageNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { assistantStepReading, deriveTurnMetrics } from '../src/client/chat/turn-metrics.ts'
+import { formatLatencySeconds, formatTokensPerSecond } from '../src/client/chat/message-chrome.ts'
+
+interface StepSpec {
+  seq: number
+  turn: number
+  step: number
+  timing?: AssistantMessageNode['timing']
+  usage?: unknown
+}
+
+const assistant = ({ seq, turn, step, timing, usage }: StepSpec): AssistantMessageNode => ({
+  kind: 'assistant', seq, time: seq * 1_000, turn, step, blocks: [{ kind: 'text', text: `t${seq}` }],
+  ...(timing === undefined ? {} : { timing }),
+  ...(usage === undefined ? {} : { usage }),
+})
+
+const user = (seq: number): UserMessageNode => ({
+  kind: 'user', seq, time: seq * 1_000, content: [{ type: 'text', text: 'hi' }] as never, source: null,
+})
+
+describe('assistantStepReading', () => {
+  it('derives ttft, decode time, and output tokens from a fully recorded step', () => {
+    const reading = assistantStepReading(assistant({
+      seq: 2, turn: 1, step: 1,
+      timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 6_800 },
+      usage: { outputTokens: 200 },
+    }))
+    expect(reading).toEqual({ ttftMs: 800, decodeMs: 5_000, outputTokens: 200 })
+  })
+
+  it('returns nulls when timing is absent', () => {
+    const reading = assistantStepReading(assistant({ seq: 2, turn: 1, step: 1, usage: { outputTokens: 5 } }))
+    expect(reading).toEqual({ ttftMs: null, decodeMs: null, outputTokens: 5 })
+  })
+
+  it('needs both boundaries for ttft and clamps negative spans to zero', () => {
+    expect(assistantStepReading(assistant({
+      seq: 2, turn: 1, step: 1,
+      timing: { stepStartTime: null, firstTokenTime: 1_800, completedTime: 6_800 },
+    }))).toEqual({ ttftMs: null, decodeMs: 5_000, outputTokens: null })
+    expect(assistantStepReading(assistant({
+      seq: 2, turn: 1, step: 1,
+      timing: { stepStartTime: 1_000, firstTokenTime: null, completedTime: 6_800 },
+    }))).toEqual({ ttftMs: null, decodeMs: null, outputTokens: null })
+    expect(assistantStepReading(assistant({
+      seq: 2, turn: 1, step: 1,
+      timing: { stepStartTime: 2_000, firstTokenTime: 1_500, completedTime: 1_200 },
+    }))).toEqual({ ttftMs: 0, decodeMs: 0, outputTokens: null })
+  })
+
+  it('rejects non-object, missing, and non-finite usage token counts', () => {
+    const timing = { stepStartTime: 1_000, firstTokenTime: 1_500, completedTime: 2_000 }
+    expect(assistantStepReading(assistant({ seq: 2, turn: 1, step: 1, timing, usage: 'weird' })).outputTokens).toBeNull()
+    expect(assistantStepReading(assistant({ seq: 2, turn: 1, step: 1, timing, usage: {} })).outputTokens).toBeNull()
+    const nan = assistant({ seq: 2, turn: 1, step: 1, timing, usage: { outputTokens: Number.NaN } })
+    expect(assistantStepReading(nan).outputTokens).toBeNull()
+    expect(assistantStepReading(assistant({ seq: 2, turn: 1, step: 1, timing, usage: { outputTokens: -3 } })).outputTokens).toBeNull()
+  })
+})
+
+describe('deriveTurnMetrics', () => {
+  it('takes ttft from the lowest step and throughput over all sampled steps', () => {
+    const nodes: ConversationNode[] = [
+      user(1),
+      // Out of step order on purpose: the lowest step owns the ttft slot.
+      assistant({
+        seq: 4, turn: 1, step: 2,
+        timing: { stepStartTime: 10_000, firstTokenTime: 10_200, completedTime: 12_200 },
+        usage: { outputTokens: 60 },
+      }),
+      assistant({
+        seq: 2, turn: 1, step: 1,
+        timing: { stepStartTime: 1_000, firstTokenTime: 2_200, completedTime: 5_200 },
+        usage: { outputTokens: 40 },
+      }),
+    ]
+    // 100 tokens over 5s of decode.
+    expect(deriveTurnMetrics(nodes).get(1)).toEqual({ ttftMs: 1_200, tokensPerSecond: 20 })
+  })
+
+  it('emits ttft without throughput when no step carries usage', () => {
+    const nodes = [assistant({
+      seq: 2, turn: 1, step: 1,
+      timing: { stepStartTime: 1_000, firstTokenTime: 1_900, completedTime: 3_000 },
+    })]
+    expect(deriveTurnMetrics(nodes).get(1)).toEqual({ ttftMs: 900 })
+  })
+
+  it('emits throughput without ttft when only a later step is recorded', () => {
+    const nodes = [
+      assistant({ seq: 2, turn: 1, step: 1 }),
+      assistant({
+        seq: 4, turn: 1, step: 2,
+        timing: { stepStartTime: 10_000, firstTokenTime: 10_500, completedTime: 12_500 },
+        usage: { outputTokens: 30 },
+      }),
+    ]
+    expect(deriveTurnMetrics(nodes).get(1)).toEqual({ tokensPerSecond: 15 })
+  })
+
+  it('omits turns with no readings and zero-decode throughput', () => {
+    const nodes = [
+      assistant({ seq: 2, turn: 1, step: 1 }),
+      assistant({
+        seq: 4, turn: 2, step: 1,
+        timing: { stepStartTime: null, firstTokenTime: 5_000, completedTime: 5_000 },
+        usage: { outputTokens: 10 },
+      }),
+    ]
+    expect(deriveTurnMetrics(nodes).size).toBe(0)
+  })
+
+  it('keeps turns independent and ignores non-assistant nodes', () => {
+    const nodes: ConversationNode[] = [
+      user(1),
+      assistant({
+        seq: 2, turn: 1, step: 1,
+        timing: { stepStartTime: 1_000, firstTokenTime: 1_400, completedTime: 2_400 },
+        usage: { outputTokens: 10 },
+      }),
+      user(3),
+      assistant({
+        seq: 4, turn: 2, step: 1,
+        timing: { stepStartTime: 4_000, firstTokenTime: 4_100, completedTime: 6_100 },
+        usage: { outputTokens: 100 },
+      }),
+    ]
+    const metrics = deriveTurnMetrics(nodes)
+    expect(metrics.get(1)).toEqual({ ttftMs: 400, tokensPerSecond: 10 })
+    expect(metrics.get(2)).toEqual({ ttftMs: 100, tokensPerSecond: 50 })
+  })
+})
+
+describe('footer figure formatters', () => {
+  it('formats latency with one decimal under ten seconds and whole seconds beyond', () => {
+    expect(formatLatencySeconds(840)).toBe('0.8')
+    expect(formatLatencySeconds(1_000)).toBe('1')
+    expect(formatLatencySeconds(9_949)).toBe('9.9')
+    expect(formatLatencySeconds(12_400)).toBe('12')
+    expect(formatLatencySeconds(-5)).toBe('0')
+  })
+
+  it('formats throughput with whole tokens from ten up and one decimal below', () => {
+    expect(formatTokensPerSecond(34.4)).toBe('34')
+    expect(formatTokensPerSecond(9.96)).toBe('10')
+    expect(formatTokensPerSecond(3.14)).toBe('3.1')
+    expect(formatTokensPerSecond(-1)).toBe('0')
+  })
+})

packages/compact/compact-tool-result-prune/package.json

@@ -25,9 +25,11 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -36,9 +38,11 @@
   "devDependencies": {
     "@cordisjs/plugin-include": "workspace:^",
     "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/compact/compact-tool-result-prune/src/index.ts

@@ -9,6 +9,10 @@ import z from 'schemastery'
 import { freezeMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, ToolResultMessage } from '@deepseek-ai/dsh-session'
+// Type-only: the `compact/*` SessionEventMap merges (the shadow-price event).
+import type {} from '@deepseek-ai/dsh-compact'
+// Type-only: the `ctx.tokenMeter` Context merge for the declared injection.
+import type {} from '@deepseek-ai/dsh-token-meter'
 import { codePointLength, DEFAULTS, PRUNE_MARKER, resolveConfig } from './config.ts'
 import type {
   PrunedEntry,
@@ -38,6 +42,10 @@ interface SnapshotCandidate {
 
 /** Deterministic head/middle/tail pruning for current tool-result surface nodes. */
 export class ToolResultPruneService extends Service {
+  // The token meter prices each shadowed node for its logged shadow-price
+  // event, so pruning genuinely requires the pricing capability.
+  static inject = ['tokenMeter']
+
   static Config: z<ToolResultPruneConfig> = z.object({
     thresholdChars: z.number().step(1).min(1).default(DEFAULTS.thresholdChars),
     headChars: z.number().step(1).min(0).default(DEFAULTS.headChars),
@@ -116,7 +124,10 @@ export class ToolResultPruneService extends Service {
   /**
    * Prune every over-budget tool result from one stable current-surface snapshot.
    * Each replacement preserves the complete event data except for `content`,
-   * and points at the shadowed node for durable provenance and replay.
+   * points at the shadowed node for durable provenance and replay, and is
+   * immediately preceded by a `compact/prune` shadow-price event pricing the
+   * shadowed node through the injected token meter, so pure consumers can
+   * subtract it without per-node state.
    * @param session - session whose current surface is rewritten.
    * @returns landed replacements and aggregate Unicode-code-point savings.
    * @throws when the session rejects a replacement; replacements committed
@@ -145,6 +156,14 @@ export class ToolResultPruneService extends Service {
           content,
         }] as [typeof result],
       })
+      // Shadow-price protocol: the metering event and its replacement are
+      // appended synchronously adjacent, so pure consumers subtract the
+      // shadowed node's heuristic price without retaining per-node state.
+      session.append('compact/prune', {
+        shadowedRange: { start: seq, end: seq },
+        shadowedSeqs: [seq],
+        shadowedTokenCount: this.ctx.tokenMeter.estimateMessage(event.data.message),
+      })
       const replacement = session.append('tool/result', {
         ...event.data,
         message,

packages/compact/compact-tool-result-prune/tests/loader-composition.spec.ts

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include from '@cordisjs/plugin-include'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import ToolResultPruneService from '@deepseek-ai/dsh-compact-tool-result-prune'
 
 let root: string | undefined
@@ -23,6 +24,7 @@ describe('compact-tool-result-prune real Loader composition', () => {
     root = await mkdtemp(join(tmpdir(), 'dsh-compact-tool-result-prune-loader-'))
     const configPath = join(root, 'cordis.yml')
     await writeFile(configPath, [
+      "- name: '@deepseek-ai/dsh-token-meter'",
       "- name: '@deepseek-ai/dsh-compact-tool-result-prune'",
       '  config:',
       '    thresholdChars: 100',
@@ -38,10 +40,9 @@ describe('compact-tool-result-prune real Loader composition', () => {
     context.loader.internal = {
       version: 'v2',
       async import(specifier: string) {
-        if (specifier !== '@deepseek-ai/dsh-compact-tool-result-prune') {
-          throw new Error(`unexpected Loader import: ${specifier}`)
-        }
-        return ToolResultPruneService
+        if (specifier === '@deepseek-ai/dsh-token-meter') return TokenMeterService
+        if (specifier === '@deepseek-ai/dsh-compact-tool-result-prune') return ToolResultPruneService
+        throw new Error(`unexpected Loader import: ${specifier}`)
       },
     } as unknown as NonNullable<typeof context.loader.internal>
     await context.loader.create({
@@ -60,6 +61,9 @@ describe('compact-tool-result-prune real Loader composition', () => {
 
   it('rejects stale config after plugin schema normalization', async () => {
     context = new Context()
+    // Satisfy the declared injection first: config normalization runs in the
+    // service constructor, which a pending fiber never reaches.
+    await context.plugin(TokenMeterService)
     await expect(context.plugin(ToolResultPruneService, {
       maxChars: 100,
     } as never)).rejects.toThrow(/unknown key "maxChars"/)

packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts

@@ -9,6 +9,7 @@ import SessionStore, {
 import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
 import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
 import InvariantService from '@deepseek-ai/dsh-invariants'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import ToolResultPruneService, {
   codePointLength,
   DEFAULTS,
@@ -25,9 +26,16 @@ const SMALL: ToolResultPruneConfig = {
 }
 
 function service(config: ToolResultPruneConfig = SMALL): ToolResultPruneService {
-  return new ToolResultPruneService(new Context(), config)
+  const ctx = new Context()
+  // Service constructors self-register, so `ctx.tokenMeter` resolves for the
+  // shadow-price pricing without a full plugin boot.
+  void new TokenMeterService(ctx)
+  return new ToolResultPruneService(ctx, config)
 }
 
+/** Pricing oracle mirroring the service's estimator for expectations. */
+const METER = new TokenMeterService(new Context())
+
 function appendToolStep(
   session: Session,
   turn: number,
@@ -203,6 +211,18 @@ describe('ToolResultPruneService session transaction', () => {
       sourceEventSeqs: [originalSeq],
     })
     expect(session.surface.nodes).not.toContain(originalSeq)
+
+    // Shadow-price protocol: the metering event sits directly before the
+    // replacement and prices the shadowed node with the shared estimator.
+    if (original.type !== 'tool/result') throw new Error('original is not a tool/result')
+    expect(session.events[entry.replacementSeq - 1]).toMatchObject({
+      type: 'compact/prune',
+      data: {
+        shadowedRange: { start: originalSeq, end: originalSeq },
+        shadowedSeqs: [originalSeq],
+        shadowedTokenCount: METER.estimateMessage(original.data.message),
+      },
+    })
   })
 
   it('prunes multiple results, skips short ones, and converges in one pass', () => {
@@ -240,6 +260,7 @@ describe('ToolResultPruneService session transaction', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(InvariantService)
     await ctx.plugin(SessionInvariant)
+    await ctx.plugin(TokenMeterService)
     const prune = new ToolResultPruneService(ctx, SMALL)
     const session = ctx.sessions.create(SessionId('invariants'))
     appendToolStep(session, 1, 'a', [{ type: 'text', text: 'A'.repeat(100) }])

packages/compact/compact-tool-result-prune/tsconfig.json

@@ -10,7 +10,9 @@
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
     { "path": "../../llm/llm" },
+    { "path": "../../llm/token-meter" },
     { "path": "../../core/session" },
+    { "path": "../compact" },
     { "path": "../../support/invariants" }
   ]
 }

packages/compact/compact/src/types.ts

@@ -20,8 +20,11 @@ declare module '@deepseek-ai/dsh-session' {
     /**
      * Provenance record of a completed summarization — log-only, no surfaceOp.
      * The summary content is in `data.summary`; the actual surface replacement
-     * is performed by a subsequent `user/message` event that shadows the
-     * compacted range.
+     * is performed by the immediately following `user/message` event that
+     * shadows the compacted range. That adjacency is contractual — the
+     * shadowed pricing fields are the replacement's shadow price, so a
+     * consumer may pair a replacement with the metering event directly
+     * before it (`compact/prune` documents the shared protocol).
      */
     'compact/summary': {
       summary: ContentBlock[]
@@ -49,6 +52,23 @@ declare module '@deepseek-ai/dsh-session' {
      * matches `compact/start`; `error` records an unsuccessful attempt.
      */
     'compact/end': { turn: number | null; error?: string }
+    /**
+     * Shadow price of one model-free prune replacement — log-only, no
+     * surfaceOp. The shared shadow-price protocol: a surface `replace` event
+     * is priced by the metering event immediately before it (`compact/summary`
+     * for a summarizing compaction, this event for a prune), which states the
+     * heuristic token price of the exact replaced range so a pure consumer
+     * can subtract it without retaining per-node prices. The replacement MUST
+     * be appended synchronously right after this event.
+     */
+    'compact/prune': {
+      /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
+      shadowedRange: { start: number; end: number }
+      /** The seqs of all shadowed surface nodes, in surface order. */
+      shadowedSeqs: number[]
+      /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
+      shadowedTokenCount: number
+    }
   }
 }
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -1044,7 +1044,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'estimateMessage(message: Message): number',
-        jsDoc: '/**\n * Heuristically price one model-visible message.\n * @param message - message to price without mutation.\n * @returns content and role-framing tokens under the fixed service heuristic.\n */',
+        jsDoc: '/**\n * Heuristically price one model-visible message (instance face of the pure\n * `estimateMessage` export from `estimate.ts`).\n * @param message - message to price without mutation.\n * @returns content and role-framing tokens under the fixed service heuristic.\n */',
       },
     ],
   },
@@ -1062,7 +1062,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'pruneSession(session: Session): PruneResult',
-        jsDoc: '/**\n * Prune every over-budget tool result from one stable current-surface snapshot.\n * Each replacement preserves the complete event data except for `content`,\n * and points at the shadowed node for durable provenance and replay.\n * @param session - session whose current surface is rewritten.\n * @returns landed replacements and aggregate Unicode-code-point savings.\n * @throws when the session rejects a replacement; replacements committed\n * earlier in the pass remain durable.\n */',
+        jsDoc: '/**\n * Prune every over-budget tool result from one stable current-surface snapshot.\n * Each replacement preserves the complete event data except for `content`,\n * points at the shadowed node for durable provenance and replay, and is\n * immediately preceded by a `compact/prune` shadow-price event pricing the\n * shadowed node through the injected token meter, so pure consumers can\n * subtract it without per-node state.\n * @param session - session whose current surface is rewritten.\n * @returns landed replacements and aggregate Unicode-code-point savings.\n * @throws when the session rejects a replacement; replacements committed\n * earlier in the pass remain durable.\n */',
       },
     ],
   },

packages/core/session/src/index.ts

@@ -15,7 +15,7 @@ import type { Message } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
 import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { snapshotJsonValue } from './json.ts'
-import { SurfaceManager } from './surface.ts'
+import { deriveEventMessage, SurfaceManager } from './surface.ts'
 import type { SessionSurface } from './surface.ts'
 import { foldRequestHeader } from './request-header.ts'
 
@@ -29,7 +29,7 @@ export { interruptedTurnClosers, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOM
 export { decodeStorageRecord, packChunkRuns } from './chunk-rows.ts'
 export type { ChunkRow, StorageRecord } from './chunk-rows.ts'
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
-export { foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
+export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
 /**
@@ -755,50 +755,13 @@ export class Session {
   }
 
   /**
-   * Project a single event into the LLM message it derives to, or null when
-   * it produces none — a non-surface event (chunk, boundary, log-only record)
-   * or an empty-content assistant/message (which exists only to host usage).
-   * The per-node pure function {@link deriveMessages} folds over the surface;
-   * an external reconstructor (or the dev invariant) folds the same function
-   * over a log prefix's surface to rebuild the exact messages any request was
-   * built from (the reconstructability Agent Note). The returned message is
-   * the already frozen message nested in the event wrapper and shared by
-   * delivery, durable history, and model requests.
+   * Instance face of the pure per-node `deriveEventMessage` export from
+   * `surface.ts`.
    * @param event - the event to project.
    * @returns the derived message, or null when the event produces none.
    */
   deriveEventMessage(event: SessionEvent): Message | null {
-    // Intentionally non-exhaustive: only message-producing events derive
-    // history; turn/step boundaries, chunks, usage, and errors are
-    // trace/replay data.
-
-    switch (event.type) {
-      // Ordinary prompts and injected context project in user role: the
-      // event's model-facing content stays verbatim. Do NOT
-      // re-add per-type framing (e.g. `<context>`) here: framing is
-      // caller-owned — a producer bakes it into `content`, as workspace-context
-      // does with `<system-reminder>` — or, if reintroduced, must be driven by
-      // the event `meta` map and a dedicated renderer, keeping this projection a
-      // verbatim pass-through. See the deferred design note in
-      // ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md
-      case 'user/message': {
-        return event.data
-      }
-      case 'assistant/message': {
-        // Skip an empty-content assistant/message: it exists only to host a
-        // max-tokens step's usage and must not inject a content-less assistant
-        // turn into the provider transcript.
-        if (event.data.message.content.length === 0) return null
-        return event.data.message
-      }
-      case 'tool/result': {
-        return event.data.message
-      }
-      default:
-        // A non-surface event (boundary, chunk, log-only record) projects to
-        // no message. Merge-extensible union: no assertNever here.
-        return null
-    }
+    return deriveEventMessage(event)
   }
 }
 

packages/core/session/src/surface.ts

@@ -8,6 +8,7 @@
  * @module @deepseek-ai/dsh-session/surface
  */
 
+import type { Message } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts'
 
 /** Runtime counterpart of the message-producing event union. */
@@ -66,6 +67,52 @@ export function isReplacementSurfaceEvent(
   return isSurfaceEvent(event) && event.surfaceOp !== 'append'
 }
 
+/**
+ * Project a single event into the LLM message it derives to, or null when it
+ * produces none — a non-surface event (chunk, boundary, log-only record) or an
+ * empty-content assistant/message (which exists only to host usage). This is
+ * THE per-node projection rule: `Session.deriveMessages` folds it over the
+ * live surface, external reconstructors and pure projections fold the same
+ * function over a log prefix's surface to rebuild the exact messages any
+ * request was built from. The returned message is the already frozen message
+ * nested in the event wrapper and shared by delivery, durable history, and
+ * model requests.
+ * @param event - the event to project.
+ * @returns the derived message, or null when the event produces none.
+ */
+export function deriveEventMessage(event: SessionEvent): Message | null {
+  // Intentionally non-exhaustive: only message-producing events derive
+  // history; turn/step boundaries, chunks, usage, and errors are trace/replay
+  // data.
+  switch (event.type) {
+    // Ordinary prompts and injected context project in user role: the event's
+    // model-facing content stays verbatim. Do NOT re-add per-type framing
+    // (e.g. `<context>`) here: framing is caller-owned — a producer bakes it
+    // into `content`, as workspace-context does with `<system-reminder>` — or,
+    // if reintroduced, must be driven by the event `meta` map and a dedicated
+    // renderer, keeping this projection a verbatim pass-through. See the
+    // deferred design note in
+    // ../../../../.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md
+    case 'user/message': {
+      return event.data
+    }
+    case 'assistant/message': {
+      // Skip an empty-content assistant/message: it exists only to host a
+      // max-tokens step's usage and must not inject a content-less assistant
+      // turn into the provider transcript.
+      if (event.data.message.content.length === 0) return null
+      return event.data.message
+    }
+    case 'tool/result': {
+      return event.data.message
+    }
+    default:
+      // A non-surface event (boundary, chunk, log-only record) projects to
+      // no message. Merge-extensible union: no assertNever here.
+      return null
+  }
+}
+
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
   /** Seq of the event that replaced the prior surface range. */

packages/llm/token-meter/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/token-meter/README.md
-README.md: 0935a48a5f5773fbb280bc45e07faaa05c0a4f6e
-README.zh.md: 83282ab47e6d406cfca30bbd8af40e0c94050504
+README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
+README.zh.md: 3621105ff35606b62b0587063038116b4772c6cf

packages/llm/token-meter/README.md

@@ -23,17 +23,21 @@ Usage accounting sums disjoint input, cache-read, cache-write, and output bucket
 
 ## Session projections
 
-When the composition provides `ctx.sessionProjections`, token-meter registers two units through an optional child fiber.
+When the composition provides `ctx.sessionProjections`, token-meter registers three units through an optional child fiber.
 
 `tokenUsage` carries the complete durable log's `uncachedInputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheWriteTokens`. Usage chunks are counted even when a request later fails; a final assistant-message usage for the same `(turn, step)` replaces that sample instead of double-counting it. Reasoning remains an output subdivision. The single last-sample slot relies on a session-log ordering property: once a later step reports usage, a legal log never reports usage for an earlier step again.
 
-`contextPressure` carries optional `pressureTokens` — the newest provider-reported prompt size, summing uncached input plus cache reads and writes — and optional `contextWindow` from the newest `request/context` record. Pressure stays absent until a provider reports usage; capacity stays absent for a route whose adapter advertises none. Output is excluded, so the numerator holds still while a turn streams and steps forward when the next request reports its usage.
+`contextPressure` carries optional `pressureTokens` — the newest provider-reported prompt size, summing uncached input plus cache reads and writes — optional `projectedTokens`, and optional `contextWindow` from the newest `request/context` record. Both figures stay absent until a provider reports usage; capacity stays absent for a route whose adapter advertises none. Output is excluded, so `pressureTokens` holds still while a turn streams and steps forward when the next request reports its usage.
 
-Both units use the standard projection baseline, live frame, higher-seq-wins store, and JSON checkpoint paths. Unloading token-meter removes both keys. A composition without the projection seam keeps the measurement service's existing behavior.
+`projectedTokens` is what the NEXT request's prompt would cost: the sample plus the heuristic repricing of everything the surface gained or lost since it was taken, clamped at zero and folded through the same `surface-fold.ts` the measurement service replays. Only the delta is estimated, so the figure stays anchored to the provider while reacting the moment content lands — or a compaction shadows a span. That last case is why the field exists: compaction summarizes through a direct `ctx.llm.stream()` call and appends no usage of its own, so `pressureTokens` alone reports the pre-compaction prompt until an entire further turn completes. Occupancy displays read `projectedTokens`.
+
+`contextBreakdown` carries heuristic `systemTokens`, `toolsTokens`, and `messageTokens` — the context's composition rather than its provider-billed size. The envelope figures reprice last-wins on every `request/header`; the message figure replays `surface-fold.ts` — the same positional fold `measure()` runs — so it equals `measure().surfaceTokens` at every event boundary and compaction shrinks it the way it shrinks the next request. All three figures use the measurement service's fixed heuristic and are estimates: they will not sum to `projectedTokens`, whose provider anchor carries exactly the error — CJK text and JSON schemas underprice badly at four characters per token — that the composition rows still contain. Present them as an approximate composition, never as a total.
+
+All three units use the standard projection baseline, live frame, higher-seq-wins store, and JSON checkpoint paths. Unloading token-meter removes all three keys. A composition without the projection seam keeps the measurement service's existing behavior.
 
 ### Context occupancy is an approximation, by design
 
-`pressureTokens` and `contextWindow` are independent last-wins fields and are **not** one atomic observation of a single request. Switching models pairs the fresh capacity with the previous route's pressure until the next request reports usage, and `pressureTokens` describes the last request rather than the surface as it stands right now.
+The occupancy fields are independent last-wins records and are **not** one atomic observation of a single request. Switching models pairs the fresh capacity with the previous route's sample until the next request reports usage, and `pressureTokens` describes the last request rather than the surface as it stands right now — `projectedTokens` carries that sample forward over the surface's movement, but its anchor is still the older request.
 
 This is deliberate. An occupancy percentage is a user-facing reference figure, not a billing record or a gating input — nothing in the harness makes decisions from it, and compaction reads `measure()` instead. A UI computes occupancy by dividing measured pressure by the separately resolved capacity for the selected model.
 

packages/llm/token-meter/README.zh.md

@@ -23,17 +23,21 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 
 ## 会话投影
 
-当组合提供 `ctx.sessionProjections` 时，token-meter 会通过一个可选子 fiber 注册两个单元。
+当组合提供 `ctx.sessionProjections` 时，token-meter 会通过一个可选子 fiber 注册三个单元。
 
 `tokenUsage` 携带完整持久日志中的 `uncachedInputTokens`、`outputTokens`、`cacheReadTokens` 和 `cacheWriteTokens`。即使请求随后失败，用量分片仍会计入；同一 `(turn, step)` 的最终 assistant 消息用量会替换该样本，而不是重复计数。推理仍是输出的一个细分项。只保留单个最新样本，依赖的是会话日志的一条顺序性质：一旦某个更晚的步骤报告了用量，合法日志就绝不会再为更早的步骤报告用量。
 
-`contextPressure` 携带可选的 `pressureTokens`（提供方报告的最新提示词规模，为未缓存输入加缓存读取与写入之和），以及来自最新一条 `request/context` 记录的可选 `contextWindow`。提供方报告用量前压力保持缺失；路由适配器未公布容量时容量也保持缺失。输出不计入其中，因此轮次流式输出期间分子保持不动，等到下一个请求报告用量时才前进。
+`contextPressure` 携带可选的 `pressureTokens`（提供方报告的最新提示词规模，为未缓存输入加缓存读取与写入之和）、可选的 `projectedTokens`，以及来自最新一条 `request/context` 记录的可选 `contextWindow`。提供方报告用量前两个数字都保持缺失；路由适配器未公布容量时容量也保持缺失。输出不计入其中，因此轮次流式输出期间 `pressureTokens` 保持不动，等到下一个请求报告用量时才前进。
 
-两个单元都使用标准的投影基线、实时帧、seq 高者胜值仓和 JSON 检查点路径。卸载 token-meter 会移除这两个键。不带投影 seam 的组合会保留测量服务的既有行为。
+`projectedTokens` 是「下一个请求的提示词要花多少」：在该样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零，折叠走的是测量服务重放的同一份 `surface-fold.ts`。只有增量部分是估算的，因此这个数字既锚定在提供方读数上，又能在内容落地——或压缩遮蔽一段区间——的瞬间做出反应。最后这种情况正是该字段存在的理由：压缩通过直连的 `ctx.llm.stream()` 调用生成摘要，自身不追加任何用量，所以仅凭 `pressureTokens` 会一直报告压缩前的提示词规模，直到又跑完一整轮为止。占用率展示读取 `projectedTokens`。
+
+`contextBreakdown` 携带启发式的 `systemTokens`、`toolsTokens` 与 `messageTokens`，描述上下文的组成而非提供方计费规模。envelope 数字在每条 `request/header` 上按后者胜重新计价；消息数字重放 `surface-fold.ts`——与 `measure()` 运行的位置折叠是同一份——因此它在每个事件边界上都等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。三个数字都使用测量服务的固定启发式规则，属于估算值：它们加起来不等于 `projectedTokens`——后者的提供方锚点恰好把这些明细行仍然带着的误差排除在外（按「4 字符 ≈ 1 token」计价，CJK 文本与 JSON schema 会被严重低估）。请把它们当作近似的**组成**呈现，而不是总量。
+
+三个单元都使用标准的投影基线、实时帧、seq 高者胜值仓和 JSON 检查点路径。卸载 token-meter 会移除这三个键。不带投影 seam 的组合会保留测量服务的既有行为。
 
 ### 上下文占用率是刻意为之的近似值
 
-`pressureTokens` 与 `contextWindow` 是两个各自后者胜的独立字段，**不是**对单个请求的一次原子观测。切换模型时，新容量会与上一路由的压力配对，直到下一个请求报告用量为止；而 `pressureTokens` 描述的是最后一个请求，不是此刻的表层。
+这些占用率字段各自后者胜、彼此独立，**不是**对单个请求的一次原子观测。切换模型时，新容量会与上一路由的样本配对，直到下一个请求报告用量为止；而 `pressureTokens` 描述的是最后一个请求，不是此刻的表层——`projectedTokens` 把该样本沿表层的增减推进到当下，但它的锚点仍然是那个较早的请求。
 
 这是刻意的选择。占用率百分比是面向用户的参考数字，既不是计费记录，也不是门控输入：harness 中没有任何环节依据它做决策，压缩改为直接读取 `measure()`。UI 用测得的压力除以为所选模型单独解析出的容量来计算占用率。
 

packages/llm/token-meter/package.json

@@ -30,6 +30,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -41,6 +42,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/llm/token-meter/src/breakdown-projection.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure fold for the heuristic context-composition projection: system prompt
+ * and tool schemas from the newest request envelope, conversation from the
+ * live surface. Prices with the same shared estimator as the meter service,
+ * so the three figures match `measure()`'s heuristic vocabulary exactly.
+ */
+
+import { z } from 'zod'
+import { canonicalHeader } from '@deepseek-ai/dsh-session'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import { estimateSystemTokens, estimateToolsTokens } from './estimate.ts'
+import { foldSurfaceProjection } from './surface-projection.ts'
+import type { ShadowPriceClaim } from './surface-projection.ts'
+// Import for the `contextBreakdown` SessionProjectionMap key merge.
+import type {} from './projection.ts'
+
+interface ContextBreakdownState {
+  systemTokens: number
+  toolsTokens: number
+  messageTokens: number
+  /** Shadow price armed by the immediately preceding metering event. */
+  claim?: ShadowPriceClaim
+}
+
+const breakdownSchema = z.object({
+  systemTokens: z.number().int().nonnegative(),
+  toolsTokens: z.number().int().nonnegative(),
+  messageTokens: z.number().int().nonnegative(),
+}).strict()
+
+/**
+ * Token-meter's context-composition projection unit.
+ *
+ * Envelope figures are last-wins per `request/header`; the message figure
+ * rides {@link foldSurfaceProjection} — the same O(1) fold the occupancy
+ * projection uses — so it equals `measure().surfaceTokens` at every event
+ * boundary and compaction shrinks it by its logged shadow price, the way it
+ * shrinks the next request. The state is a fixed handful of numbers, so the
+ * persisted checkpoint stays O(1) over the session's life.
+ */
+export const contextBreakdownProjectionDefinition:
+ProjectionDefinition<'contextBreakdown', ContextBreakdownState> = {
+  key: 'contextBreakdown',
+  schema: breakdownSchema,
+  init: () => ({ systemTokens: 0, toolsTokens: 0, messageTokens: 0 }),
+  apply: (state, event) => {
+    const fold = foldSurfaceProjection(state.claim, event)
+    let systemTokens = state.systemTokens
+    let toolsTokens = state.toolsTokens
+    if (event.type === 'request/header') {
+      const header = canonicalHeader(event.data.header)
+      systemTokens = estimateSystemTokens(header)
+      toolsTokens = estimateToolsTokens(header)
+    }
+    if (systemTokens === state.systemTokens
+      && toolsTokens === state.toolsTokens
+      && fold.deltaTokens === 0
+      && fold.claim === undefined
+      && state.claim === undefined) return state
+    return {
+      systemTokens,
+      toolsTokens,
+      messageTokens: state.messageTokens + fold.deltaTokens,
+      ...fold.claim === undefined ? {} : { claim: fold.claim },
+    }
+  },
+  view: ({ systemTokens, toolsTokens, messageTokens }) => ({ systemTokens, toolsTokens, messageTokens }),
+  stateVersion: 2,
+}

packages/llm/token-meter/src/estimate.ts

@@ -0,0 +1,87 @@
+/**
+ * Fixed-density heuristic token pricing shared by the meter service and the
+ * pure context-breakdown projection, so both surfaces price identical content
+ * to identical numbers.
+ *
+ * @module @deepseek-ai/dsh-token-meter/estimate
+ */
+
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader } from '@deepseek-ai/dsh-session'
+
+/** Fixed text-density estimate used until exact tokenization is needed. */
+const CHARS_PER_TOKEN = 4
+
+/** Per-block structural overhead for JSON framing and type tags. */
+const BLOCK_OVERHEAD = 4
+
+/** Role-field framing overhead added to every priced message. */
+export const ROLE_OVERHEAD = 4
+
+/**
+ * Price content blocks recursively under the fixed density heuristic.
+ * @param blocks - content blocks to price without mutation.
+ * @returns heuristic tokens including per-block structural overhead.
+ */
+export function estimateContent(blocks: readonly ContentBlock[]): number {
+  let tokens = 0
+  for (const block of blocks) {
+    switch (block.type) {
+      case 'text':
+      case 'reasoning':
+        tokens += Math.ceil(block.text.length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
+        break
+      case 'tool-call':
+        tokens += Math.ceil(block.name.length / CHARS_PER_TOKEN)
+          + Math.ceil(block.arguments.length / CHARS_PER_TOKEN)
+          + BLOCK_OVERHEAD
+        break
+      case 'tool-result':
+        tokens += estimateContent(block.content) + BLOCK_OVERHEAD
+        break
+      default:
+        // ContentBlockMap is merge-extensible; unknown blocks retain a
+        // conservative structural JSON price under the fixed heuristic.
+        tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN)
+    }
+  }
+  return tokens
+}
+
+/**
+ * Heuristically price one model-visible message.
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed heuristic.
+ */
+export function estimateMessage(message: Message): number {
+  return estimateContent(message.content) + ROLE_OVERHEAD
+}
+
+/**
+ * Price the system-prompt part of a canonical request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic system-prompt tokens; 0 when absent.
+ */
+export function estimateSystemTokens(header: EpochHeader | undefined): number {
+  if (header?.system === undefined) return 0
+  return Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD
+}
+
+/**
+ * Price the tool-schema part of a canonical request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic tool-schema tokens; 0 when absent or empty.
+ */
+export function estimateToolsTokens(header: EpochHeader | undefined): number {
+  if (header?.tools === undefined || header.tools.length === 0) return 0
+  return Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
+}
+
+/**
+ * Price the complete non-surface request envelope.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic system plus tool tokens.
+ */
+export function estimateHeader(header: EpochHeader | undefined): number {
+  return estimateSystemTokens(header) + estimateToolsTokens(header)
+}

packages/llm/token-meter/src/index.ts

@@ -7,8 +7,8 @@
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import { BlockAssembler, deepFreeze } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
-import type { EpochHeader, Session, SessionEvent, SurfaceEvent } from '@deepseek-ai/dsh-session'
+import type { Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session'
 // Type-only: resolves the optional projection registry Context seam.
 import type {} from '@deepseek-ai/dsh-session-projection'
@@ -18,19 +18,13 @@ import type {
   TokenMeterConfig,
   TokenSurfaceNode,
 } from './types.ts'
+import { contextBreakdownProjectionDefinition } from './breakdown-projection.ts'
 import { contextPressureProjectionDefinition, tokenUsageProjectionDefinition } from './usage-projection.ts'
+import { estimateContent, estimateHeader, estimateMessage, ROLE_OVERHEAD } from './estimate.ts'
+import { foldSurfaceTokens } from './surface-fold.ts'
 
 export type * from './types.ts'
 
-/** Fixed text-density estimate used until exact tokenization is needed. */
-const CHARS_PER_TOKEN = 4
-
-/** Per-block structural overhead for JSON framing and type tags. */
-const BLOCK_OVERHEAD = 4
-
-/** Role-field framing overhead added to every priced message. */
-const ROLE_OVERHEAD = 4
-
 interface MeasurementAnchor {
   readonly header: EpochHeader | undefined
   readonly surfaceTokens: number
@@ -46,11 +40,6 @@ interface ReplayState {
   anchor: MeasurementAnchor | undefined
 }
 
-interface PreparedSurfaceMutation {
-  readonly tokens: number
-  commit(state: ReplayState): void
-}
-
 /** Sum disjoint provider usage buckets without double-counting reasoning output. */
 function usageTokens(usage: TokenUsage): number {
   return usage.inputTokens
@@ -98,6 +87,7 @@ export class TokenMeterService extends Service {
     ctx.inject(['sessionProjections'], (projectionCtx) => {
       projectionCtx.sessionProjections.register(tokenUsageProjectionDefinition)
       projectionCtx.sessionProjections.register(contextPressureProjectionDefinition)
+      projectionCtx.sessionProjections.register(contextBreakdownProjectionDefinition)
     })
 
     // Readers catch up independently, while eager observation bounds ordinary
@@ -141,7 +131,7 @@ export class TokenMeterService extends Service {
     } else {
       baseline = {
         kind: 'estimated',
-        tokens: this._estimateHeader(header) + state.surfaceTokens,
+        tokens: estimateHeader(header) + state.surfaceTokens,
       }
       surfaceDeltaTokens = 0
     }
@@ -157,12 +147,13 @@ export class TokenMeterService extends Service {
   }
 
   /**
-   * Heuristically price one model-visible message.
+   * Heuristically price one model-visible message (instance face of the pure
+   * `estimateMessage` export from `estimate.ts`).
    * @param message - message to price without mutation.
    * @returns content and role-framing tokens under the fixed service heuristic.
    */
   estimateMessage(message: Message): number {
-    return this._estimateContent(message.content) + ROLE_OVERHEAD
+    return estimateMessage(message)
   }
 
   /** Catch one session's fold up to the current durable tail. */
@@ -224,7 +215,7 @@ export class TokenMeterService extends Service {
     }
 
     const surface = isSurfaceEvent(event)
-      ? this._prepareSurfaceMutation(session, state, event)
+      ? foldSurfaceTokens(state.surface, event)
       : undefined
 
     if (event.type === 'assistant/message') {
@@ -246,7 +237,7 @@ export class TokenMeterService extends Service {
         )
         const anchorSurfaceTokens = stepStart.surfaceTokens + providerAssistantTokens
         const providerTokens = usageTokens(event.data.usage)
-        const estimatedAnchorTokens = this._estimateHeader(nextHeader) + anchorSurfaceTokens
+        const estimatedAnchorTokens = estimateHeader(nextHeader) + anchorSurfaceTokens
         nextAnchor = {
           header: nextHeader,
           surfaceTokens: anchorSurfaceTokens,
@@ -263,7 +254,7 @@ export class TokenMeterService extends Service {
           surfaceTokens: anchorSurfaceTokens,
           baseline: {
             kind: 'estimated',
-            tokens: this._estimateHeader(nextHeader) + anchorSurfaceTokens,
+            tokens: estimateHeader(nextHeader) + anchorSurfaceTokens,
           },
         }
       }
@@ -271,51 +262,11 @@ export class TokenMeterService extends Service {
 
     state.header = nextHeader
     state.stepStart = nextStepStart
-    if (surface !== undefined) surface.commit(state)
-    state.anchor = nextAnchor
-  }
-
-  /** Validate one surface operation and return its allocation-light commit. */
-  private _prepareSurfaceMutation(
-    session: Session,
-    state: ReplayState,
-    event: SurfaceEvent,
-  ): PreparedSurfaceMutation {
-    const tokens = this._estimateSurfaceEvent(session, event)
-    const op = event.surfaceOp
-    if (op === 'append') {
-      return {
-        tokens,
-        commit(target) {
-          target.surface.push({ seq: event.seq, tokens })
-          target.surfaceTokens += tokens
-        },
-      }
-    }
-
-    const startIdx = state.surface.findIndex(node => node.seq === op.start)
-    const endIdx = state.surface.findIndex(node => node.seq === op.end)
-    if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
-      throw new Error(
-        `token meter: replace at seq ${event.seq} has invalid current range ${op.start}-${op.end}`,
-      )
+    if (surface !== undefined) {
+      state.surface = surface.nodes
+      state.surfaceTokens += surface.deltaTokens
     }
-    const removedTokens = state.surface
-      .slice(startIdx, endIdx + 1)
-      .reduce((total, node) => total + node.tokens, 0)
-    return {
-      tokens,
-      commit(target) {
-        target.surface.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, tokens })
-        target.surfaceTokens += tokens - removedTokens
-      },
-    }
-  }
-
-  /** Price one current surface event exactly as it projects to a request. */
-  private _estimateSurfaceEvent(session: Session, event: SurfaceEvent): number {
-    const message = session.deriveEventMessage(event)
-    return message === null ? 0 : this.estimateMessage(message)
+    state.anchor = nextAnchor
   }
 
   /**
@@ -355,46 +306,7 @@ export class TokenMeterService extends Service {
       assembler.push(sourceEvent.data.chunk)
     }
     const providerContent = assembler.blocks()
-    return providerContent.length === 0 ? 0 : this._estimateContent(providerContent) + ROLE_OVERHEAD
-  }
-
-  /** Price content blocks recursively under the fixed density heuristic. */
-  private _estimateContent(blocks: readonly ContentBlock[]): number {
-    let tokens = 0
-    for (const block of blocks) {
-      switch (block.type) {
-        case 'text':
-        case 'reasoning':
-          tokens += Math.ceil(block.text.length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
-          break
-        case 'tool-call':
-          tokens += Math.ceil(block.name.length / CHARS_PER_TOKEN)
-            + Math.ceil(block.arguments.length / CHARS_PER_TOKEN)
-            + BLOCK_OVERHEAD
-          break
-        case 'tool-result':
-          tokens += this._estimateContent(block.content) + BLOCK_OVERHEAD
-          break
-        default:
-          // ContentBlockMap is merge-extensible; unknown blocks retain a
-          // conservative structural JSON price under the fixed heuristic.
-          tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN)
-      }
-    }
-    return tokens
-  }
-
-  /** Price the canonical non-surface request envelope. */
-  private _estimateHeader(header: EpochHeader | undefined): number {
-    if (header === undefined) return 0
-    let tokens = 0
-    if (header.system !== undefined) {
-      tokens += Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD
-    }
-    if (header.tools !== undefined && header.tools.length > 0) {
-      tokens += Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
-    }
-    return tokens
+    return providerContent.length === 0 ? 0 : estimateContent(providerContent) + ROLE_OVERHEAD
   }
 }
 

packages/llm/token-meter/src/invariant.ts

@@ -17,9 +17,14 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: token estimates are per-call outputs and the private
  * session cache is invalidated at its event mutation boundary. The package's
- * projection does expose an observation stream, but its schema fixes the JSON
- * payload and its pure fold replaces same-step samples; totals need not be
- * monotone when a final usage sample corrects an earlier chunk.
+ * three projections do expose observation streams, but their schemas fix the
+ * JSON payloads; the usage folds replace same-step samples, so totals need not
+ * be monotone when a final sample corrects an earlier chunk, and the
+ * composition fold prices through the same `estimate.ts` heuristic as the
+ * measurement service and subtracts producer-logged shadow prices derived
+ * from that service's own nodes, which makes its message figure equal
+ * `measure().surfaceTokens` by construction rather than by a relation worth
+ * observing at runtime.
  */
 const install: InvariantInstaller = () => {}
 

packages/llm/token-meter/src/projection.ts

@@ -20,13 +20,12 @@ export interface TokenUsageProjection {
 /**
  * Approximate context occupancy for a status display.
  *
- * The two fields, when present, are deliberately NOT one atomic request
- * observation: `pressureTokens` is the newest provider-reported prompt size,
- * `contextWindow` the newest recorded route capacity. Switching models can
- * therefore pair a fresh capacity with the previous route's pressure until the
- * next request reports usage. This is an intentional trade — the value is a
- * user-facing reference, not a billing or gating input. See the token-meter
- * README for the full rationale.
+ * The fields, when present, are deliberately NOT one atomic request
+ * observation: each is a last-wins record of a different moment. Switching
+ * models can therefore pair a fresh capacity with the previous route's
+ * pressure until the next request reports usage. This is an intentional trade
+ * — the value is a user-facing reference, not a billing or gating input. See
+ * the token-meter README for the full rationale.
  */
 export interface ContextPressureProjection {
   /**
@@ -35,15 +34,44 @@ export interface ContextPressureProjection {
    * grow as the current turn streams. Absent until a provider reports usage.
    */
   pressureTokens?: number
+  /**
+   * What the NEXT request's prompt would cost: {@link pressureTokens} plus the
+   * heuristic repricing of everything the surface gained or lost since that
+   * sample. Only the delta is estimated, so the figure stays anchored to the
+   * provider while still reacting the moment a compaction shadows a span —
+   * which `pressureTokens` alone cannot do, since compaction reports no usage
+   * of its own. Absent until a provider reports usage.
+   */
+  projectedTokens?: number
   /** Newest recorded route capacity; absent when no adapter advertised one. */
   contextWindow?: number
 }
 
+/**
+ * Heuristic composition of the next request's context: what the prompt is
+ * made of, not what it costs. All three figures use the meter's fixed
+ * density estimate, so they will not sum to the provider-anchored
+ * `projectedTokens`: the estimator systematically underprices CJK text and
+ * JSON schemas, which is exactly the error the anchoring in
+ * {@link ContextPressureProjection.projectedTokens} keeps out of the occupancy
+ * figure. Present these as approximations of composition, never as a total.
+ */
+export interface ContextBreakdownProjection {
+  /** Heuristic tokens of the newest request envelope's system prompt; 0 before any request. */
+  systemTokens: number
+  /** Heuristic tokens of the newest request envelope's tool schemas; 0 before any request. */
+  toolsTokens: number
+  /** Heuristic tokens of the current model-visible conversation surface. */
+  messageTokens: number
+}
+
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionMap {
     /** Provider-reported usage accumulated across the complete durable log. */
     tokenUsage: TokenUsageProjection
     /** Newest request pressure paired with the newest known route capacity. */
     contextPressure: ContextPressureProjection
+    /** Heuristic system/tools/message composition of the next request. */
+    contextBreakdown: ContextBreakdownProjection
   }
 }

packages/llm/token-meter/src/surface-fold.ts

@@ -0,0 +1,64 @@
+/**
+ * The measurement service's positional surface fold: the per-node priced
+ * surface `measure()` serves and compaction plans against. The projection
+ * units deliberately do NOT share this fold — their state must stay O(1)
+ * for the persisted checkpoint, so they ride `surface-projection.ts`'s
+ * shadow-price protocol instead. The two stay in agreement by construction:
+ * both price through `estimate.ts`, and every logged shadow price is derived
+ * from THIS fold's nodes by the replace producer.
+ *
+ * @module @deepseek-ai/dsh-token-meter/surface-fold
+ */
+
+import { deriveEventMessage } from '@deepseek-ai/dsh-session'
+import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
+import type { TokenSurfaceNode } from './types.ts'
+import { estimateMessage } from './estimate.ts'
+
+/** One surface event's placement and cost against the surface preceding it. */
+export interface SurfaceTokenFold {
+  /** Heuristic price of the event's own message; 0 when it derives none. */
+  readonly tokens: number
+  /** The surface after the event, detached from the input. */
+  readonly nodes: TokenSurfaceNode[]
+  /** Signed change in the surface total: `tokens` minus anything shadowed. */
+  readonly deltaTokens: number
+}
+
+/**
+ * Fold one surface event onto a priced surface.
+ *
+ * Total and allocation-fresh: the caller assigns the result rather than
+ * mutating in place, so a throw here leaves the caller's state untouched and
+ * the same malformed event fails identically on every retry.
+ * @param nodes - the priced surface preceding this event, in model-visible order.
+ * @param event - the surface event to place.
+ * @returns the event's price, the next surface, and the signed total delta.
+ * @throws when a replacement names a range absent from `nodes` — committed
+ *   logs are surface-validated at append time, so an unresolvable range is log
+ *   corruption and must fail loud rather than skip the event.
+ */
+export function foldSurfaceTokens(
+  nodes: readonly TokenSurfaceNode[],
+  event: SurfaceEvent,
+): SurfaceTokenFold {
+  const message = deriveEventMessage(event)
+  const tokens = message === null ? 0 : estimateMessage(message)
+  const op = event.surfaceOp
+  if (op === 'append') {
+    return { tokens, nodes: [...nodes, { seq: event.seq, tokens }], deltaTokens: tokens }
+  }
+  const startIdx = nodes.findIndex(node => node.seq === op.start)
+  const endIdx = nodes.findIndex(node => node.seq === op.end)
+  if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+    throw new Error(
+      `token surface: replace at seq ${event.seq} has invalid current range ${op.start}-${op.end}`,
+    )
+  }
+  const removed = nodes
+    .slice(startIdx, endIdx + 1)
+    .reduce((total, node) => total + node.tokens, 0)
+  const next = [...nodes]
+  next.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, tokens })
+  return { tokens, nodes: next, deltaTokens: tokens - removed }
+}

packages/llm/token-meter/src/surface-projection.ts

@@ -0,0 +1,84 @@
+/**
+ * The O(1) surface-token fold shared by the token-meter projection units.
+ *
+ * A projection state must stay bounded — the persisted projection cache
+ * checkpoints every unit's whole state, so carrying the priced surface
+ * (one node per model-visible message) would grow a checkpoint without
+ * bound over the session's life. Instead, replacements ride the compact
+ * seam's shadow-price protocol: the metering event immediately before a
+ * surface `replace` (`compact/summary` or `compact/prune`) states the
+ * heuristic price of the exact replaced range, so the fold keeps a running
+ * total plus at most one pending claim and never retains per-node prices.
+ * The counts are exact by construction: producers derive them from the same
+ * fixed estimator this module prices appends with.
+ *
+ * @module @deepseek-ai/dsh-token-meter/surface-projection
+ */
+
+import { deriveEventMessage, isSurfaceEvent } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+// Type-only: the `compact/*` SessionEventMap merges (shadow-price events).
+import type {} from '@deepseek-ai/dsh-compact'
+import { estimateMessage } from './estimate.ts'
+
+/**
+ * One armed shadow price: the heuristic tokens of the surface range the
+ * IMMEDIATELY following event replaces. Plain JSON — it is part of the
+ * persisted unit state while armed.
+ */
+export interface ShadowPriceClaim {
+  /** Declared inclusive first surface-node seq of the priced range. */
+  start: number
+  /** Declared inclusive last surface-node seq of the priced range. */
+  end: number
+  /** Heuristic tokens of the priced range under the fixed estimator. */
+  tokens: number
+}
+
+/** One event's effect on a running surface-token total. */
+export interface SurfaceTokensFold {
+  /** Signed change in the surface total; 0 for events off the surface. */
+  readonly deltaTokens: number
+  /** Claim to carry into the next event; undefined when none survives. */
+  readonly claim: ShadowPriceClaim | undefined
+}
+
+/**
+ * Fold one committed event onto a running surface-token total.
+ *
+ * A shadow-price event arms a claim; any other event expires it, and a
+ * surface `replace` must consume a claim naming its exact range — the
+ * producers append the metering event and the replacement synchronously
+ * adjacent, so a surviving claim always prices the very next event.
+ * @param claim - the claim armed by the immediately preceding event, if any.
+ * @param event - the next committed session event.
+ * @returns the signed token delta and the claim state after this event.
+ * @throws when a replacement arrives without a claim for its exact range —
+ *   every in-repo replace producer meters its replacement, so an unpriced
+ *   replacement is a shadow-price contract violation and must fail loud
+ *   rather than let the total drift.
+ */
+export function foldSurfaceProjection(
+  claim: ShadowPriceClaim | undefined,
+  event: SessionEvent,
+): SurfaceTokensFold {
+  if (event.type === 'compact/summary' || event.type === 'compact/prune') {
+    const { shadowedRange, shadowedTokenCount } = event.data
+    return {
+      deltaTokens: 0,
+      claim: { start: shadowedRange.start, end: shadowedRange.end, tokens: shadowedTokenCount },
+    }
+  }
+  if (!isSurfaceEvent(event)) return { deltaTokens: 0, claim: undefined }
+  const message = deriveEventMessage(event)
+  const tokens = message === null ? 0 : estimateMessage(message)
+  const op = event.surfaceOp
+  if (op === 'append') return { deltaTokens: tokens, claim: undefined }
+  if (claim === undefined || claim.start !== op.start || claim.end !== op.end) {
+    throw new Error(
+      `token surface: replace at seq ${event.seq} over range ${op.start}-${op.end} has no adjacent shadow price`
+      + (claim === undefined ? '' : ` (armed claim covers ${claim.start}-${claim.end})`),
+    )
+  }
+  return { deltaTokens: tokens - claim.tokens, claim: undefined }
+}

packages/llm/token-meter/src/types.ts

@@ -6,7 +6,7 @@
 
 import type { TokenUsage } from '@deepseek-ai/dsh-llm'
 
-export type { ContextPressureProjection, TokenUsageProjection } from './projection.ts'
+export type { ContextBreakdownProjection, ContextPressureProjection, TokenUsageProjection } from './projection.ts'
 
 /** Token-meter plugin configuration; the fixed estimator has no settings. */
 export type TokenMeterConfig = Record<string, never>

packages/llm/token-meter/src/usage-projection.ts

@@ -4,8 +4,11 @@
 
 import { z } from 'zod'
 import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type { ContextPressureProjection, TokenUsageProjection } from './projection.ts'
+import { foldSurfaceProjection } from './surface-projection.ts'
+import type { ShadowPriceClaim } from './surface-projection.ts'
 
 interface UsageSample {
   turn: number
@@ -60,6 +63,7 @@ const projectionSchema = z.object({
 // `number | undefined` where the interface declares absent-or-number fields.
 const pressureSchema = z.object({
   pressureTokens: z.number().int().nonnegative().optional(),
+  projectedTokens: z.number().int().nonnegative().optional(),
   contextWindow: z.number().int().positive().optional(),
 }).strict() as unknown as z.ZodType<ContextPressureProjection>
 
@@ -67,6 +71,29 @@ const pressureSchema = z.object({
 const pressureFrom = (usage: TokenUsage): number =>
   usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
 
+/** The usage a chunk or finalized message reports for its step, if any. */
+const usageOf = (event: SessionEvent): TokenUsage | undefined =>
+  event.type === 'assistant/chunk' && event.data.chunk.type === 'usage'
+    ? event.data.chunk.usage
+    : event.type === 'assistant/message'
+      ? event.data.usage
+      : undefined
+
+/**
+ * Context-occupancy state: the two independent last-wins records plus the
+ * O(1) running surface total needed to carry the newest sample forward.
+ */
+interface ContextPressureState {
+  contextWindow?: number
+  pressureTokens?: number
+  /** Running heuristic total over the current surface ({@link foldSurfaceProjection}). */
+  surfaceTokens: number
+  /** {@link surfaceTokens} at the newest usage sample; absent until one lands. */
+  sampledSurfaceTokens?: number
+  /** Shadow price armed by the immediately preceding metering event. */
+  claim?: ShadowPriceClaim
+}
+
 /**
  * Token-meter's session projection unit.
  *
@@ -115,39 +142,64 @@ ProjectionDefinition<'tokenUsage', TokenUsageState> = {
 /**
  * Token-meter's context-occupancy projection unit.
  *
- * Two independent last-wins slots: the newest usage sample supplies the
+ * Independent last-wins slots: the newest usage sample supplies the provider
  * numerator, the newest `request/context` record the denominator. Both are
  * whole values, so replay order alone decides the result and no cross-field
  * consistency is claimed — the pair is explicitly not one atomic request
  * observation (see {@link ContextPressureProjection}).
  *
- * The numerator is prompt-side only, so it holds still while a turn streams
- * and steps forward once the next request reports its usage.
+ * `pressureTokens` is prompt-side only, so it holds still while a turn streams
+ * and steps forward once the next request reports its usage. Because nothing
+ * but a request reports usage, it also cannot see a compaction: the fold
+ * therefore carries a running surface total alongside it and publishes
+ * `projectedTokens` — the sample plus the surface's signed movement since it
+ * was taken — so occupancy answers for the next request rather than the last
+ * one. The total rides {@link foldSurfaceProjection}, so the state stays O(1)
+ * and a replacement shrinks it by its logged shadow price. A usage sample is
+ * stamped BEFORE the same event joins the surface, so an `assistant/message`
+ * anchors against the surface its own request saw.
  */
 export const contextPressureProjectionDefinition:
-ProjectionDefinition<'contextPressure', ContextPressureProjection> = {
+ProjectionDefinition<'contextPressure', ContextPressureState> = {
   key: 'contextPressure',
   schema: pressureSchema,
-  init: () => ({}),
+  init: () => ({ surfaceTokens: 0 }),
   apply: (state, event) => {
+    const fold = foldSurfaceProjection(state.claim, event)
+    let next = state
     if (event.type === 'request/context') {
       const contextWindow = event.data.contextWindow
-      if (contextWindow === state.contextWindow) return state
-      if (contextWindow !== undefined) return { ...state, contextWindow }
-      const { contextWindow: _removed, ...withoutContextWindow } = state
-      return withoutContextWindow
+      if (contextWindow !== state.contextWindow) {
+        if (contextWindow !== undefined) {
+          next = { ...next, contextWindow }
+        } else {
+          const { contextWindow: _removed, ...withoutContextWindow } = next
+          next = withoutContextWindow
+        }
+      }
+    }
+    const usage = usageOf(event)
+    if (usage !== undefined) {
+      const pressureTokens = pressureFrom(usage)
+      if (pressureTokens !== next.pressureTokens || next.sampledSurfaceTokens !== next.surfaceTokens) {
+        next = { ...next, pressureTokens, sampledSurfaceTokens: next.surfaceTokens }
+      }
+    }
+    if (fold.deltaTokens !== 0) {
+      next = { ...next, surfaceTokens: next.surfaceTokens + fold.deltaTokens }
     }
-    const usage = event.type === 'assistant/chunk' && event.data.chunk.type === 'usage'
-      ? event.data.chunk.usage
-      : event.type === 'assistant/message'
-        ? event.data.usage
-        : undefined
-    if (usage === undefined) return state
-    const pressureTokens = pressureFrom(usage)
-    return pressureTokens === state.pressureTokens
-      ? state
-      : { ...state, pressureTokens }
+    // A defined fold.claim is always freshly built, so presence decides claim
+    // bookkeeping: no claim before or after this event leaves `next` as is.
+    if (state.claim === undefined && fold.claim === undefined) return next
+    const { claim: _expired, ...withoutClaim } = next
+    return fold.claim === undefined ? withoutClaim : { ...withoutClaim, claim: fold.claim }
   },
-  view: state => state,
-  stateVersion: 2,
+  view: ({ contextWindow, pressureTokens, surfaceTokens, sampledSurfaceTokens }) => ({
+    ...contextWindow === undefined ? {} : { contextWindow },
+    ...pressureTokens === undefined ? {} : { pressureTokens },
+    ...pressureTokens === undefined || sampledSurfaceTokens === undefined
+      ? {}
+      : { projectedTokens: Math.max(0, pressureTokens + surfaceTokens - sampledSurfaceTokens) },
+  }),
+  stateVersion: 4,
 }

packages/llm/token-meter/tests/context-breakdown-projection.spec.ts

@@ -0,0 +1,307 @@
+// contextBreakdown projection: heuristic system/tools/message composition,
+// plus the shared estimator's pricing branches.
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
+import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
+import {
+  estimateContent,
+  estimateHeader,
+  estimateMessage,
+  estimateSystemTokens,
+  estimateToolsTokens,
+} from '../src/estimate.ts'
+
+const CONFIG = { provider: 'test', model: 'test-model' }
+
+const TOOLS: ToolSchema[] = [{
+  name: 'bash',
+  description: 'run a command',
+  parameters: { type: 'object', properties: {} },
+}]
+
+async function harness(): Promise<{ ctx: Context; session: Session }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionProjectionRegistry)
+  await ctx.plugin(TokenMeterService)
+  return { ctx, session: ctx.sessions.create() }
+}
+
+const projected = (ctx: Context, session: Session): ContextBreakdownProjection => {
+  const value = ctx.sessionProjections.snapshot(session).values.contextBreakdown
+  if (value === undefined) throw new Error('contextBreakdown projection is not registered')
+  return value
+}
+
+function appendUser(session: Session, text: string): number {
+  return session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' }).seq
+}
+
+/**
+ * Meter one upcoming replacement the way compact-basic does: price the
+ * replaced span from the measurement service's own nodes and log the
+ * shadow-price event directly before the replace.
+ */
+function appendSummaryMeter(ctx: Context, session: Session, start: number, end: number): void {
+  const nodes = ctx.tokenMeter.measure(session).nodes
+  const startIdx = nodes.findIndex(node => node.seq === start)
+  const endIdx = nodes.findIndex(node => node.seq === end)
+  const shadowed = nodes.slice(startIdx, endIdx + 1)
+  session.append('compact/summary', {
+    summary: [{ type: 'text', text: 'summary' }],
+    shadowedRange: { start, end },
+    shadowedSeqs: shadowed.map(node => node.seq),
+    shadowedTokenCount: shadowed.reduce((total, node) => total + node.tokens, 0),
+    provider: 'mock',
+    model: 'mock',
+  })
+}
+
+describe('contextBreakdown session projection', () => {
+  it('serves zeros for an empty log', async () => {
+    const { ctx, session } = await harness()
+    expect(projected(ctx, session)).toEqual({ systemTokens: 0, toolsTokens: 0, messageTokens: 0 })
+  })
+
+  it('prices the newest envelope last-wins and pushes no change for a restated one', async () => {
+    const { ctx, session } = await harness()
+    session.append('request/header', {
+      header: { config: CONFIG, system: 'You are terse.', tools: TOOLS },
+      reason: 'initial',
+    })
+    expect(projected(ctx, session)).toEqual({
+      systemTokens: estimateSystemTokens({ config: CONFIG, system: 'You are terse.' }),
+      toolsTokens: estimateToolsTokens({ config: CONFIG, tools: TOOLS }),
+      messageTokens: 0,
+    })
+
+    const changed: string[] = []
+    ctx.sessionProjections.onChanged((_session, key) => { changed.push(key) })
+    session.append('request/header', {
+      header: { config: CONFIG, system: 'You are terse.', tools: TOOLS },
+      reason: 'change',
+    })
+    session.append('todo/write', { todos: [] })
+    expect(changed).not.toContain('contextBreakdown')
+
+    // A system-less, tool-less envelope prices back to zero.
+    session.append('request/header', { header: { config: CONFIG }, reason: 'change' })
+    expect(projected(ctx, session)).toEqual({ systemTokens: 0, toolsTokens: 0, messageTokens: 0 })
+  })
+
+  it('sums surface appends and skips an empty-content assistant message', async () => {
+    const { ctx, session } = await harness()
+    appendUser(session, 'abcd')
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      message: createMessage({
+        role: 'assistant',
+        content: [],
+        source: { kind: 'model', provider: 'mock', model: 'mock' },
+      }),
+      usage: { inputTokens: 9, outputTokens: 0 },
+    }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    session.append('step/end', { turn: 1, step: 1 })
+    // 'abcd' prices to 9 (1 text + 4 block + 4 role); the usage-only assistant
+    // message derives to no transcript entry and adds nothing.
+    expect(projected(ctx, session).messageTokens).toBe(9)
+  })
+
+  it('shrinks the message figure when a metered replacement compacts the surface', async () => {
+    const { ctx, session } = await harness()
+    const first = appendUser(session, 'before compaction, a longer message')
+    const second = appendUser(session, 'and a second entry')
+    const summary = createUserMessage({
+      content: [{ type: 'text', text: 'summary' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    })
+    appendSummaryMeter(ctx, session, first, second)
+    session.append('user/message', summary, {
+      surfaceOp: { op: 'replace', start: first, end: second },
+      sourceEventSeqs: [first, second],
+    })
+    expect(projected(ctx, session).messageTokens).toBe(estimateMessage(summary))
+  })
+
+  it('keeps the message figure equal to the service surface across appends and a compaction', async () => {
+    const { ctx, session } = await harness()
+    // The panel's composition rows and `measure()` answer the same question in
+    // the same vocabulary; one shared fold is what makes that true.
+    const agree = (): number => {
+      const messageTokens = projected(ctx, session).messageTokens
+      expect(messageTokens).toBe(ctx.tokenMeter.measure(session).surfaceTokens)
+      return messageTokens
+    }
+    session.append('request/header', {
+      header: { config: CONFIG, system: 'You are terse.', tools: TOOLS },
+      reason: 'initial',
+    })
+    expect(agree()).toBe(0)
+
+    const question = appendUser(session, 'a first question, long enough to price above zero')
+    session.append('step/start', { turn: 1, step: 1 })
+    const answer = session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      message: createMessage({
+        role: 'assistant',
+        content: [{ type: 'text', text: 'a considered answer' }],
+        source: { kind: 'model', provider: 'mock', model: 'mock' },
+      }),
+      usage: { inputTokens: 40, outputTokens: 7 },
+    }, { surfaceOp: 'append', sourceEventSeqs: [] }).seq
+    session.append('step/end', { turn: 1, step: 1 })
+    const grown = agree()
+    expect(grown).toBeGreaterThan(0)
+
+    appendSummaryMeter(ctx, session, question, answer)
+    // The armed shadow price must not move the published figure by itself.
+    expect(agree()).toBe(grown)
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'summary' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }), {
+      surfaceOp: { op: 'replace', start: question, end: answer },
+      sourceEventSeqs: [question, answer],
+    })
+    expect(agree()).toBeLessThan(grown)
+  })
+
+  it('fails loud on a replacement without an adjacent matching shadow price', () => {
+    const definition = contextBreakdownProjectionDefinition
+    const replace = (start: number, end: number): SessionEvent => ({
+      type: 'user/message',
+      seq: 9,
+      time: 0,
+      data: createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }),
+      surfaceOp: { op: 'replace', start, end },
+      sourceEventSeqs: [start, end],
+    } as unknown as SessionEvent)
+    const append = (seq: number): SessionEvent => ({
+      type: 'user/message',
+      seq,
+      time: 0,
+      data: createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }),
+      surfaceOp: 'append',
+    } as unknown as SessionEvent)
+    const meter = (start: number, end: number, seq: number): SessionEvent => ({
+      type: 'compact/prune',
+      seq,
+      time: 0,
+      data: { shadowedRange: { start, end }, shadowedSeqs: [start, end], shadowedTokenCount: 5 },
+    } as unknown as SessionEvent)
+    let state = definition.init()
+    state = definition.apply(state, append(1))
+    state = definition.apply(state, append(3))
+    // No metering event at all.
+    expect(() => definition.apply(state, replace(1, 3))).toThrow('no adjacent shadow price')
+    // A claim for a different range does not price this replacement.
+    const mismatched = definition.apply(state, meter(1, 1, 8))
+    expect(() => definition.apply(mismatched, replace(1, 3))).toThrow('no adjacent shadow price')
+    // A claim expires after one intervening event instead of lingering.
+    let expired = definition.apply(state, meter(1, 3, 8))
+    expired = definition.apply(expired, { type: 'todo/write', seq: 9, time: 0, data: { todos: [] } } as unknown as SessionEvent)
+    expect(() => definition.apply(expired, replace(1, 3))).toThrow('no adjacent shadow price')
+    // The armed claim prices exactly the next event's matching replacement.
+    const armed = definition.apply(state, meter(1, 3, 8))
+    expect(definition.view(definition.apply(armed, replace(1, 3))).messageTokens)
+      .toBe(definition.view(state).messageTokens - 5 + estimateMessage(
+        createUserMessage({ content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }),
+      ))
+  })
+
+  it('keeps the persisted checkpoint O(1) as the surface grows and compacts', async () => {
+    const { ctx, session } = await harness()
+    const first = appendUser(session, 'the first of many messages')
+    for (let index = 0; index < 24; index += 1) appendUser(session, `message number ${index} with some text`)
+    const last = appendUser(session, 'the last message before compaction')
+    const stateKeys = (): string[] => {
+      const row = ctx.sessionProjections.checkpoint(session)['contextBreakdown']
+      if (row === undefined) throw new Error('contextBreakdown checkpoint row is missing')
+      return Object.keys(row.val as Record<string, unknown>).sort()
+    }
+    // Growth adds no per-node bookkeeping to the durable state.
+    expect(stateKeys()).toEqual(['messageTokens', 'systemTokens', 'toolsTokens'])
+    const shadowed = session.surface.nodes.slice(
+      session.surface.nodes.indexOf(first),
+      session.surface.nodes.indexOf(last) + 1,
+    )
+    appendSummaryMeter(ctx, session, first, last)
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'summary' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }), {
+      surfaceOp: { op: 'replace', start: first, end: last },
+      sourceEventSeqs: [...shadowed],
+    })
+    expect(stateKeys()).toEqual(['messageTokens', 'systemTokens', 'toolsTokens'])
+    expect(projected(ctx, session).messageTokens)
+      .toBe(ctx.tokenMeter.measure(session).surfaceTokens)
+  })
+
+  it('restores from a JSON checkpoint and unregisters with the token-meter fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionProjectionRegistry)
+    const meterFiber = await ctx.plugin(TokenMeterService)
+    const session = ctx.sessions.create()
+    session.append('request/header', {
+      header: { config: CONFIG, system: 'You are terse.' },
+      reason: 'initial',
+    })
+    appendUser(session, 'abcd')
+    const checkpoint = JSON.parse(JSON.stringify(
+      ctx.sessionProjections.checkpoint(session),
+    )) as ReturnType<typeof ctx.sessionProjections.checkpoint>
+
+    await meterFiber.dispose()
+    expect(ctx.sessionProjections.snapshot(session).values).not.toHaveProperty('contextBreakdown')
+
+    await ctx.plugin(TokenMeterService)
+    expect(ctx.sessionProjections.viewCheckpoint(checkpoint).contextBreakdown).toEqual({
+      systemTokens: estimateSystemTokens({ config: CONFIG, system: 'You are terse.' }),
+      toolsTokens: 0,
+      messageTokens: 9,
+    })
+  })
+})
+
+describe('shared estimator', () => {
+  it('prices every content-block shape under the fixed heuristic', () => {
+    expect(estimateContent([{ type: 'text', text: 'abcd' }])).toBe(5)
+    expect(estimateContent([{ type: 'reasoning', text: 'abcdefgh' }] as ContentBlock[])).toBe(6)
+    expect(estimateContent([{ type: 'tool-call', id: 'c' as never, name: 'bash', arguments: '{"a":1}' }])).toBe(7)
+    expect(estimateContent([{
+      type: 'tool-result', toolCallId: 'c' as never,
+      content: [{ type: 'text', text: 'abcd' }],
+    }])).toBe(9)
+    const unknown = { type: 'mystery', payload: 'abc' } as unknown as ContentBlock
+    expect(estimateContent([unknown])).toBe(4 + Math.ceil(JSON.stringify(unknown).length / 4))
+  })
+
+  it('prices envelope parts independently and absent parts to zero', () => {
+    expect(estimateSystemTokens(undefined)).toBe(0)
+    expect(estimateSystemTokens({ config: CONFIG })).toBe(0)
+    expect(estimateSystemTokens({ config: CONFIG, system: 'abcdefgh' })).toBe(6)
+    expect(estimateToolsTokens(undefined)).toBe(0)
+    expect(estimateToolsTokens({ config: CONFIG, tools: [] })).toBe(0)
+    expect(estimateToolsTokens({ config: CONFIG, tools: TOOLS }))
+      .toBe(Math.ceil(JSON.stringify(TOOLS).length / 4) + 4)
+    expect(estimateHeader(undefined)).toBe(0)
+    expect(estimateHeader({ config: CONFIG, system: 'abcdefgh', tools: TOOLS }))
+      .toBe(6 + Math.ceil(JSON.stringify(TOOLS).length / 4) + 4)
+  })
+})

packages/llm/token-meter/tests/token-usage-projection.spec.ts

@@ -70,6 +70,26 @@ const projected = (ctx: Context, session: Session): TokenUsageProjection => {
   return value
 }
 
+/**
+ * Meter one upcoming replacement the way compact-basic does: price the
+ * replaced span from the measurement service's own nodes and log the
+ * shadow-price event directly before the replace.
+ */
+function appendSummaryMeter(ctx: Context, session: Session, start: number, end: number): void {
+  const nodes = ctx.tokenMeter.measure(session).nodes
+  const startIdx = nodes.findIndex(node => node.seq === start)
+  const endIdx = nodes.findIndex(node => node.seq === end)
+  const shadowed = nodes.slice(startIdx, endIdx + 1)
+  session.append('compact/summary', {
+    summary: [{ type: 'text', text: 'summary' }],
+    shadowedRange: { start, end },
+    shadowedSeqs: shadowed.map(node => node.seq),
+    shadowedTokenCount: shadowed.reduce((total, node) => total + node.tokens, 0),
+    provider: 'mock',
+    model: 'mock',
+  })
+}
+
 describe('tokenUsage session projection', () => {
   it('serves zero buckets for an empty log', async () => {
     const { ctx, session } = await harness()
@@ -184,6 +204,7 @@ describe('tokenUsage session projection', () => {
       content: [{ type: 'text', text: 'before compaction' }],
       source: { kind: 'user' },
     }), { surfaceOp: 'append' })
+    appendSummaryMeter(ctx, session, before.seq, before.seq)
     session.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'compacted' }],
       source: { kind: 'plugin', plugin: 'test' },
@@ -235,6 +256,34 @@ function recordContext(session: Session, model: string, contextWindow?: number):
   })
 }
 
+/** Append one model-visible user turn and return its surface seq. */
+function appendUser(session: Session, text: string): number {
+  return session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' }).seq
+}
+
+/** Append one finalized assistant turn carrying its provider usage. */
+function appendAssistant(
+  session: Session,
+  text: string,
+  usage: TokenUsage,
+  turn: number,
+  step: number,
+): number {
+  return session.append('assistant/message', {
+    turn,
+    step,
+    message: createMessage({
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      source: { kind: 'model', provider: 'mock', model: 'mock' },
+    }),
+    usage,
+  }, { surfaceOp: 'append', sourceEventSeqs: [] }).seq
+}
+
 describe('contextPressure session projection', () => {
   it('serves no pressure or capacity for an empty log', async () => {
     const { ctx, session } = await harness()
@@ -277,9 +326,13 @@ describe('contextPressure session projection', () => {
     startStep(session, 1, 1)
     recordContext(session, 'small', 64_000)
     usageChunk(session, { inputTokens: 100, outputTokens: 10 }, 1, 1)
-    expect(pressure(ctx, session)).toEqual({ pressureTokens: 100, contextWindow: 64_000 })
+    expect(pressure(ctx, session)).toEqual({
+      pressureTokens: 100, projectedTokens: 100, contextWindow: 64_000,
+    })
     recordContext(session, 'large', 256_000)
-    expect(pressure(ctx, session)).toEqual({ pressureTokens: 100, contextWindow: 256_000 })
+    expect(pressure(ctx, session)).toEqual({
+      pressureTokens: 100, projectedTokens: 100, contextWindow: 256_000,
+    })
   })
 
   it('removes an older capacity when the newest route advertises none', async () => {
@@ -288,7 +341,7 @@ describe('contextPressure session projection', () => {
     recordContext(session, 'small', 64_000)
     usageChunk(session, { inputTokens: 100, outputTokens: 10 }, 1, 1)
     recordContext(session, 'unknown')
-    expect(pressure(ctx, session)).toEqual({ pressureTokens: 100 })
+    expect(pressure(ctx, session)).toEqual({ pressureTokens: 100, projectedTokens: 100 })
   })
 
   it('pushes no change for unrelated events or a restated capacity', async () => {
@@ -319,7 +372,7 @@ describe('contextPressure session projection', () => {
     const checkpoint = JSON.parse(JSON.stringify(
       ctx.sessionProjections.checkpoint(session),
     )) as ReturnType<typeof ctx.sessionProjections.checkpoint>
-    expect(checkpoint.contextPressure?.ver).toBe(2)
+    expect(checkpoint.contextPressure?.ver).toBe(4)
 
     await meterFiber.dispose()
     expect(ctx.sessionProjections.snapshot(session).values).not.toHaveProperty('contextPressure')
@@ -327,7 +380,62 @@ describe('contextPressure session projection', () => {
     await ctx.plugin(TokenMeterService)
     expect(ctx.sessionProjections.viewCheckpoint(checkpoint).contextPressure).toEqual({
       pressureTokens: 42,
+      projectedTokens: 42,
       contextWindow: 64_000,
     })
   })
+
+  it('carries the sample forward over surface growth and a compaction', async () => {
+    const { ctx, session } = await harness()
+    recordContext(session, 'large', 128_000)
+    const question = appendUser(session, 'a first question worth a few tokens')
+    startStep(session, 1, 1)
+    // The provider prices the prompt its request actually carried; the sample
+    // must anchor against the surface as of that request, not after the
+    // assistant message joins it.
+    const answer = appendAssistant(session, 'an answer of some length', { inputTokens: 900, outputTokens: 20 }, 1, 1)
+    session.append('step/end', { turn: 1, step: 1 })
+    const afterTurn = pressure(ctx, session)
+    expect(afterTurn.pressureTokens).toBe(900)
+    // The assistant message landed after the sample, so it already shows.
+    expect(afterTurn.projectedTokens).toBeGreaterThan(900)
+
+    const grown = appendUser(session, 'a follow-up question that grows the surface further')
+    const beforeCompaction = pressure(ctx, session).projectedTokens
+    expect(beforeCompaction).toBeGreaterThan(afterTurn.projectedTokens!)
+
+    // Compaction reports no usage of its own, so `pressureTokens` cannot move;
+    // the projected figure must shrink anyway — the defect this field fixes.
+    appendSummaryMeter(ctx, session, question, grown)
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'summary' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }), {
+      surfaceOp: { op: 'replace', start: question, end: grown },
+      sourceEventSeqs: [question, answer, grown],
+    })
+    const compacted = pressure(ctx, session)
+    expect(compacted.pressureTokens).toBe(900)
+    expect(compacted.projectedTokens).toBeLessThan(beforeCompaction!)
+  })
+
+  it('clamps a projection that heuristic error drove below zero', async () => {
+    const { ctx, session } = await harness()
+    recordContext(session, 'large', 128_000)
+    const question = appendUser(session, 'a question long enough to outprice the sample'.repeat(4))
+    startStep(session, 1, 1)
+    // A provider sample far below the heuristic price of what it replaced:
+    // shadowing that span subtracts more than the sample holds.
+    appendAssistant(session, 'ok', { inputTokens: 3, outputTokens: 1 }, 1, 1)
+    session.append('step/end', { turn: 1, step: 1 })
+    appendSummaryMeter(ctx, session, question, question)
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: '.' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }), {
+      surfaceOp: { op: 'replace', start: question, end: question },
+      sourceEventSeqs: [question],
+    })
+    expect(pressure(ctx, session).projectedTokens).toBe(0)
+  })
 })

packages/llm/token-meter/tsconfig.json

@@ -23,6 +23,9 @@
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../compact/compact"
+    },
     {
       "path": "../../session-projection/session-projection"
     },

pnpm-lock.yaml

@@ -2366,6 +2366,9 @@ importers:
       '@cordisjs/plugin-loader':
         specifier: workspace:^
         version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../compact
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -2375,6 +2378,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-token-meter':
+        specifier: workspace:^
+        version: link:../../llm/token-meter
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -3860,6 +3866,9 @@ importers:
         specifier: ^4.4.3
         version: 4.4.3
     devDependencies:
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants