fix(tui,host): project the human transcript from append-origin events

The terminal and history pagination both treated the model-visible surface as
the human transcript. A landed compaction replacement therefore erased the
conversation it summarized — messages the reader had already seen — and a
model-only replacement copy consumed a page's `maxMessages` quota, which could
also split a compaction's provenance from the replacement citing it.

`dsh-session` now exports the marker split `isAppendSurfaceEvent` /
`isReplacementSurfaceEvent`. The terminal replays append-origin surface events,
keeps a shadowed step's tool cards paired through its append-origin assistant
message, and renders one dim marker where a compaction landed; the checkpoint is
recognized through the compaction seam's `isCompactCheckpointSource` contract,
not the shape of the replacement. `session.history` counts only append-origin
human messages. Everything model-facing keeps reading `session.surface`.

.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.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-07-29-human-transcript-append-origin.md
+2026-07-29-human-transcript-append-origin.md: 51602148810b0c400ec7b0f7996b37dd666bf93f
+2026-07-29-human-transcript-append-origin.zh.md: 77e9a691f06978ac6875e8f4330d96ecca23a1b5

.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md

@@ -0,0 +1,47 @@
+# Agent Note: The human transcript projects append-origin events
+
+Status: implemented
+
+English | [中文](2026-07-29-human-transcript-append-origin.zh.md)
+
+## Problem
+
+The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message`, `assistant/message`, and `steering/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only provenance and the replacement that cites it.
+
+Nothing was lost from the log. `Session.events` still held every original message and full tool result; the surface only decides what the model is sent next. The defect was entirely in the projection.
+
+## Decision
+
+Model and human projections are separate, and the event's own marker decides which one an event belongs to. `dsh-session` exports the marker split `isAppendSurfaceEvent(event)` and `isReplacementSurfaceEvent(event)` over the two `SurfaceOp` variants, from the browser-safe `surface` module. Append-origin events are the durable source for a transcript; replacement copies stay model-only. Everything that must send exactly what the model sees — `deriveMessages`, token accounting, the compaction backends, tool pairing, injected-context liveness, cross-session reference projection — keeps reading `session.surface`.
+
+The terminal replays the transcript from append-origin surface events and keeps a shadowed step's tool cards paired through `transcriptToolCallIds`, which reads the append-origin `assistant/message` rather than surface membership. A landed compaction contributes one dim `… earlier context was compacted …` row at its own log position: the marker reports where the model stopped seeing that history instead of erasing it. The framed checkpoint payload never renders, and the replay and live paths share one rule, so a compaction that arrives live and the same log replayed after resume produce the same transcript.
+
+A checkpoint is recognized through the compaction seam's own contract — `isCompactCheckpointSource`, the backend-independent marker `CompactService` requires on the replacement user message — so the terminal depends on the declared vocabulary, not on the shape of the replacement. `dsh-session-reference` already consumes that predicate to project another session's log; this is the same question asked by a different reader. Other replacements are silent: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary in the conversation.
+
+`session.history` counts only append-origin human messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` provenance stays on the page of the replacement that cites it.
+
+No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required.
+
+## Deferred
+
+The browser client still builds its conversation from the model surface through `FoldAdapter`, so compaction still collapses web history to a single context row. The same predicate is the fix there, together with an append-order transcript projection and a marker component; that work is a separate change against `packages/client/runtime` and `packages/client/ui-conversation`. Rendering compaction *progress* — a terminal indicator while a compaction runs — needs the bracket-first ordering that the queued manual `/compact` work introduces, and is likewise out of scope here.
+
+## Alternatives considered
+
+**Recognize a checkpoint by shape (a replacement `user/message`).** Rejected: it reads a coincidence of today's producers instead of a declared contract, and any future producer that replaces a range with a user message would silently inherit the compaction marker. The seam already publishes `COMPACT_CHECKPOINT_SOURCE` precisely so consumers can recognize a checkpoint independently of the backend.
+
+**Keep rendering the checkpoint as an injected-context card.** Rejected: the framed checkpoint is an instruction envelope written for the model, not human conversation content. Showing it while hiding the history it replaced inverts what the reader needs.
+
+**Persist a second display transcript.** Rejected: the append-only log already contains the authoritative source material, so a parallel record buys nothing and adds migration and consistency work.
+
+**Derive the marker from the `compact/*` bracket instead of the checkpoint.** Rejected for the transcript: the bracket is a pair of time-point markers around an operation, while the transcript needs the position where the surface actually changed. The bracket is the right source for progress and duration, which this change does not render.
+
+**Classify events by re-folding the log, as `session-query` does for search (`current` / `shadowed` / `log-only`).** Rejected: a fold answers a whole-log question, while a projection asks a per-event one that the event's own marker already answers in constant time.
+
+## Consequences
+
+Compaction no longer erases terminal history; a session compacted several times shows one marker per landed compaction, in log order. Pagination pages can carry more raw events than before, because quota is spent only on messages a human or model actually produced.
+
+`dsh-tui` gains a dependency on the `dsh-compact` seam for one pure predicate, mirroring `dsh-session-reference`'s existing use. The terminal still needs no compaction backend at runtime.
+
+Two behaviors changed with their tests. The surface-replacement terminal test previously pinned erasure ("hides shadowed tool calls") and now pins preservation plus exactly one marker, including a pruned result copy, a regenerated assistant message, and a foreign plugin's replacement all rendering nothing. The compaction snapshot scenario wrote a `workspace-context` source while claiming to pin compaction; it now writes a real checkpoint source, and its three fixtures are re-recorded to show the preserved prompt, the full tool card, and the marker.

.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md

@@ -0,0 +1,47 @@
+# Agent Note: 人类可读记录投影追加来源的事件
+
+Status: implemented
+
+[English](2026-07-29-human-transcript-append-origin.md) | 中文
+
+## Problem
+
+终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message`、`assistant/message` 和 `steering/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
+
+日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。
+
+## Decision
+
+模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是记录的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。
+
+终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且回放路径与实时路径共用同一条规则，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。
+
+检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+
+`session.history` 只把追加来源的人类消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
+
+持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
+
+## Deferred
+
+浏览器客户端仍通过 `FoldAdapter` 从模型 surface 构建会话，因此压缩在 Web 端仍会把历史折叠成一行上下文。那里的修复用的是同一个谓词，另需按追加顺序的记录投影与一个标记组件；该工作是针对 `packages/client/runtime` 与 `packages/client/ui-conversation` 的独立变更。渲染压缩*进度*——压缩运行期间的终端指示——需要排队式手动 `/compact` 工作引入的“先开括号”顺序，同样不在本次范围内。
+
+## Alternatives considered
+
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的契约，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+
+**继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
+
+**持久化第二份展示用记录。** 被否决：仅追加的日志已经包含权威源材料，平行记录换不来任何东西，反而增加迁移与一致性工作。
+
+**用 `compact/*` 括号而不是检查点来推导标记。** 就记录而言被否决：括号是围绕一次操作的一对时间点标记，而记录需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
+
+**像 `session-query` 为搜索所做的那样重新折叠日志来分类事件（`current`／`shadowed`／`log-only`）。** 被否决：折叠回答的是整份日志的问题，而投影问的是逐事件的问题，事件自身的标记已能以常数时间给出答案。
+
+## Consequences
+
+压缩不再抹掉终端历史；被压缩多次的会话会按日志顺序显示每次落地压缩对应的一行标记。分页的每一页可以携带比以前更多的原始事件，因为额度只花在人类或模型真正产生的消息上。
+
+`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` 接缝的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
+
+两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（“隐藏被遮蔽的工具调用”），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture，以显示被保留的提示、完整的工具卡片和那行标记。

.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.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 .agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
-2026-07-17-dedicated-full-screen-tui-front-door.md: a3f3d6b51e85ad20218ce5aebf526bd96946be55
-2026-07-17-dedicated-full-screen-tui-front-door.zh.md: 6a0c2f12815e9418a2b5bcb237d3db3616ccd133
+2026-07-17-dedicated-full-screen-tui-front-door.md: 7cc09652a7033c216e3835d33dc9e4a623666259
+2026-07-17-dedicated-full-screen-tui-front-door.zh.md: c5bb6e54e89ec3d1e0e7d2229a120ad158d1f9bc

.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.md

@@ -20,7 +20,7 @@ The selected front door receives the exact generated or resumed `SessionId` used
 
 ### Session projection and interaction
 
-The TUI rebuilds the transcript from the active `session.surface` and reprojects it whenever an event carries a `surfaceOp`, so resumed and compacted history matches the model-visible conversation. It renders Markdown text and reasoning, including fenced code with hidden Markdown markers, a dim optional language label, and a code-colored body, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. Pending chunks and tool calls update the same components that completed events settle.
+The TUI rebuilds the transcript from the append-origin session events, so resumed history keeps every message the reader already saw; a compacted range stays readable behind one marker instead of matching the model-visible conversation ([append-origin transcript](../bug-fix/2026-07-29-human-transcript-append-origin.md)). It renders Markdown text and reasoning, including fenced code with hidden Markdown markers, a dim optional language label, and a code-colored body, token totals, the latest `todo/write` plan, and tool cards produced through each tool definition's `presentCall` and `presentResult` methods. Long card bodies retain a configurable head/tail preview with the hidden-line count; one terminal control expands or collapses every card. Pending chunks and tool calls update the same components that completed events settle.
 
 Editor input calls `agent.send()` while idle and `agent.steer()` while a turn is running. Cancellation, reasoning visibility, tool-card expansion, redraw, transcript clearing, and exit are terminal-only controls. `/exit` and `/quit` share the same exit path: they cancel an active turn, wait for idle, and then restore and close the terminal. The idle footer derives context occupancy from `tokenMeter` and shows the selected model and explicit reasoning effort; during a run, elapsed activity and the Escape interrupt hint replace that summary. `/status` remains available in either state and appends a detailed terminal-only snapshot: session identity and timestamps, selected model, reasoning effort/default state and reasoning visibility, lifecycle counts folded from the event log, the same deduplicated usage buckets and KV-cache rate as the footer, and context use from `tokenMeter` plus the selected model's advertised capacity. The plugin registers the shared `userInteraction` provider and presents queued questions in a wide bottom-left keyboard panel with batch progress, numbered options, and aligned descriptions; the panel's controls hint lists only actions meaningful for the current option count, omitting navigation when exactly one option is shown; agent behavior and answer logging remain owned by their existing services.
 
@@ -47,6 +47,6 @@ The implemented [TUI terminal-state snapshot Agent Note](../testing/2026-07-18-t
 
 - Interactive terminal work has a stateful Markdown, card, plan, and question interface with no second terminal protocol to keep aligned.
 - The TUI carries a pi-tui dependency and a strict TTY requirement; non-TTY deployments use the Headless app or a structured protocol.
-- Session projection makes resume and compaction consistent with the durable conversation, but one configured session owns the transcript and editor.
+- Session projection makes resume consistent with the durable conversation, but one configured session owns the transcript and editor.
 - Tool packages extend terminal cards through their existing presentation methods without adding tool-specific branches to the TUI.
 - Model and reasoning-effort selection use adapter-advertised metadata without turning catalog membership into request validation; unused selections are not durable state.

.agents/notes/implemented/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md

@@ -20,7 +20,7 @@ DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README
 
 ### 会话投影与交互
 
-TUI 从活跃的 `session.surface` 重建 transcript（文本记录），并在事件携带 `surfaceOp` 时重新投影，因此恢复或压缩后的历史与模型可见会话保持一致。TUI 渲染 Markdown 文本与推理（其中围栏代码块隐藏 Markdown 标记、保留一个暗色的可选语言标签，并使用代码配色的正文）、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。
+TUI 从追加来源的会话事件重建 transcript（文本记录），因此恢复后的历史会保留读者已经看到的每条消息；被压缩的范围不再与模型可见会话保持一致，而是留在一行标记之后仍可阅读（[追加来源的 transcript](../bug-fix/2026-07-29-human-transcript-append-origin.md)）。TUI 渲染 Markdown 文本与推理（其中围栏代码块隐藏 Markdown 标记、保留一个暗色的可选语言标签，并使用代码配色的正文）、token 用量、最新 `todo/write` 计划，以及各工具定义通过 `presentCall` 和 `presentResult` 方法生成的工具卡片。较长的工具卡片正文会保留可配置的头尾预览，并显示隐藏行数；一个终端控制可以展开或收起全部卡片。进行中的分片与工具调用会更新同一组组件，随后由完成事件收束状态。
 
 agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调用 `agent.steer()`。取消、推理显隐、工具卡片展开、重绘、清空 transcript 和退出都只是终端控制。`/exit` 和 `/quit` 共用同一条退出路径：先取消进行中的轮次，等待 agent 空闲，然后恢复并关闭终端。空闲态页脚根据 `tokenMeter` 得出上下文占用率，并显示所选模型和显式选定的推理强度；agent 运行期间，该摘要会替换为带已用时长的活动指示和 Escape 中断提示。`/status` 在这两种状态下均可用，并会追加一份仅在终端显示的详细快照，其中包括会话标识与时间戳、所选模型、推理强度（或默认状态）及推理显隐状态、从事件日志归并得出的生命周期计数、与页脚一致的去重用量分项和 KV 缓存命中率，以及 `tokenMeter` 给出的上下文用量和所选模型公布的容量。插件注册共享的 `userInteraction` 提供方，在左下角宽幅键盘操作面板中呈现排队的问题，面板显示批次进度、带编号的选项和对齐的描述；面板的操作提示只列出在当前选项数量下有意义的操作，仅有一个选项时不显示导航项；agent 行为和答案日志仍由既有服务负责。
 
@@ -47,6 +47,6 @@ agent 空闲时，编辑器输入调用 `agent.send()`；轮次运行中则调
 
 - 交互式终端拥有带状态的 Markdown、卡片、计划和提问界面，无需再对齐第二套终端协议。
 - TUI 会引入 pi-tui 依赖并严格要求 TTY；非 TTY 部署使用 Headless app 或结构化协议。
-- 会话投影使恢复和压缩与持久会话保持一致，但只有一个已配置会话拥有 transcript 和编辑器。
+- 会话投影使恢复与持久会话保持一致，但只有一个已配置会话拥有 transcript 和编辑器。
 - 工具包通过既有呈现方法扩展终端卡片，无需在 TUI 中增加工具专用分支。
 - 模型和推理强度选择使用适配器公布的元数据，但不会把目录成员关系变成请求校验；未使用的选择不属于持久化状态。

docs/cordis-catalog/services.md

@@ -2174,7 +2174,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi
 abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
 ```
 
-Source: [`packages/ui/tui/src/index.ts:247`](../../packages/ui/tui/src/index.ts)
+Source: [`packages/ui/tui/src/index.ts:250`](../../packages/ui/tui/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 

docs/module-graph.md

@@ -837,6 +837,7 @@ flowchart TD
   pkg_tui --> pkg_agent
   pkg_tui --> pkg_agent_loop
   pkg_tui --> pkg_commands
+  pkg_tui --> pkg_compact
   pkg_tui --> pkg_goal
   pkg_tui --> pkg_invariants
   pkg_tui --> pkg_llm
@@ -1114,7 +1115,7 @@ flowchart TD
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |

packages/core/session/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/core/session/README.md
-README.md: a9b6905dcf2b8ef1f75595e567273f7a3150a412
-README.zh.md: f1a5e97e32d1ad1abcd6ad96e6c621af9972e989
+README.md: 9fa6cf5251d480be9d2388bdb32393fa2827168c
+README.zh.md: 5170d5d4b362a0f19ff6953e1636adef9aa7e8b8

packages/core/session/README.md

@@ -60,6 +60,7 @@ Providers stream token-sized deltas, so a raw log stores hundreds of `assistant/
 - `SessionSurface` — the readonly live `nodes` and `replaceGeneration` projection exposed by `session.surface`; candidate validation remains private to `Session`.
 - `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, replacements that fail to cite every shadowed surface entry, and a `tool/result` replacement that changes anything except one current result's `content`; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache.
 - `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
+- `isAppendSurfaceEvent(event)` / `isReplacementSurfaceEvent(event)` — split a formed surface event by marker variant. Append-origin events are the durable source for a human transcript, which is not the model-visible surface: a landed replacement shadows the range it summarizes, so projecting a transcript from `session.surface` erases conversation the reader already saw. Consumers that must send exactly what the model sees keep reading `session.surface`.
 
 ### Request-header reconstruction (`request-header.ts`)
 

packages/core/session/README.zh.md

@@ -60,6 +60,7 @@
 - `SessionSurface`：实时只读 `nodes` 和 `replaceGeneration` 投影，由 `session.surface` 暴露；候选校验仍由 `Session` 私有。
 - `foldSurface(events)`：回放规范 surface 契约，得到脱离的当前事件序列与实际替换范围。同一趟处理会拒绝不连续序号、错位或畸形元数据、空或重复溯源信息、来源并非更早事件、无效位置范围，以及没有引用所有已遮蔽 surface 条目的替换。如果一个 `tool/result` 替换修改了当前某个结果的 `content` 之外的任何内容，也会被拒绝；`SurfaceManager` 共享该原子状态转换，但只保留自己的增量序列缓存。
 - `isSurfaceEvent(event)`／`isSurfaceEligibleType(type)`：前者将 `SessionEvent` 收窄为形态完整的 surface 事件；后者在校验种子或已加载日志时，检测缺少标记的可进入 surface 事件。
+- `isAppendSurfaceEvent(event)`／`isReplacementSurfaceEvent(event)`：按标记变体拆分形态完整的 surface 事件。追加来源的事件是人类可读记录（transcript）的持久来源，而该记录并非模型可见的 surface：已落地的替换会遮蔽它所概括的范围，因此从 `session.surface` 投影记录会抹掉读者已经看到的对话。必须准确发送模型所见内容的消费方仍继续读取 `session.surface`。
 
 ### 请求头重建（`request-header.ts`）
 

packages/core/session/src/index.ts

@@ -27,7 +27,7 @@ export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from '
 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, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
+export { foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
 /**

packages/core/session/src/surface.ts

@@ -37,6 +37,36 @@ export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
   return (event as SessionEvent<SurfaceEventType>).surfaceOp !== undefined
 }
 
+/**
+ * Narrow an event to an append-origin surface event: one that entered the
+ * surface at its own log position and was never itself a replacement copy.
+ *
+ * The model-visible surface deliberately shadows replaced ranges, so it is the
+ * wrong source for a human transcript — a landed replacement would erase
+ * conversation the user already saw. Append-origin events are that transcript's
+ * durable source material; replacement copies stay model-only.
+ * @param event - event to test.
+ * @returns true when the event appended to the surface tail.
+ */
+export function isAppendSurfaceEvent(
+  event: SessionEvent,
+): event is SurfaceEvent & { surfaceOp: 'append' } {
+  return isSurfaceEvent(event) && event.surfaceOp === 'append'
+}
+
+/**
+ * Narrow an event to a surface replacement: a node that shadowed an existing
+ * surface range instead of appending to the tail. The counterpart of
+ * {@link isAppendSurfaceEvent} over the two {@link SurfaceOp} variants.
+ * @param event - event to test.
+ * @returns true when the event replaced a surface range.
+ */
+export function isReplacementSurfaceEvent(
+  event: SessionEvent,
+): event is SurfaceEvent & { surfaceOp: { op: 'replace'; start: number; end: number } } {
+  return isSurfaceEvent(event) && event.surfaceOp !== 'append'
+}
+
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
   /** Seq of the event that replaced the prior surface range. */

packages/core/session/tests/surface.spec.ts

@@ -4,6 +4,8 @@ import {
   Session,
   SessionId,
   foldSurface,
+  isAppendSurfaceEvent,
+  isReplacementSurfaceEvent,
   isSurfaceEligibleType,
   isSurfaceEvent,
 } from '@deepseek-ai/dsh-session'
@@ -861,6 +863,40 @@ describe('surface type guards', () => {
     expect(isSurfaceEligibleType(markerless.type)).toBe(true)
     expect(isSurfaceEvent(markerless)).toBe(false)
   })
+
+  it('splits surface events into append-origin and replacement by their marker', () => {
+    const s = surfaceSession()
+    s.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }], source: { kind: 'plugin', plugin: 'compact' },
+    }), { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] })
+    const appended = s.events.find(e => e.type === 'user/message')!
+    const replacement = s.events.at(-1)!
+
+    expect(isAppendSurfaceEvent(appended)).toBe(true)
+    expect(isReplacementSurfaceEvent(appended)).toBe(false)
+    expect(isAppendSurfaceEvent(replacement)).toBe(false)
+    expect(isReplacementSurfaceEvent(replacement)).toBe(true)
+  })
+
+  it('rejects log-only and markerless events from both marker guards', () => {
+    const s = surfaceSession()
+    const turnStart = s.events.find(e => e.type === 'turn/start')!
+    // A surface-eligible type whose mandatory marker is absent has no origin at
+    // all: it never entered the surface.
+    const markerless: SessionEvent = {
+      type: 'user/message',
+      seq: 0,
+      time: 0,
+      data: createUserMessage({
+        content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
+      }),
+    }
+
+    expect(isAppendSurfaceEvent(turnStart)).toBe(false)
+    expect(isReplacementSurfaceEvent(turnStart)).toBe(false)
+    expect(isAppendSurfaceEvent(markerless)).toBe(false)
+    expect(isReplacementSurfaceEvent(markerless)).toBe(false)
+  })
 })
 
 describe('SurfaceManager.replaceGeneration', () => {

packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: ca4471454f5be5d3fcba38ce665d4fb3fbd85e74
-README.zh.md: 953539e1198a52b2bf7cdd9ca1b0d263cc2ae6f9
+README.md: 190e7f8d36f74bfd7232cc5b4dbb937f265ef1d5
+README.zh.md: 9fb9d24412e950b0648cd07c4b5c73aa0174405c

packages/host/apiproxy/README.md

@@ -10,6 +10,8 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ
 
 The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
 
+`session.history` pages on append-origin human-message boundaries: `maxMessages` counts `user/message`, `assistant/message`, and `steering/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
+
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
 Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.

packages/host/apiproxy/README.zh.md

@@ -10,6 +10,8 @@
 
 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。
 
+`session.history` 按追加来源的人类消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message`、`assistant/message` 和 `steering/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。

packages/host/apiproxy/src/api-proxy.ts

@@ -14,6 +14,7 @@ import type {
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { MessageId, MessageSource } from '@deepseek-ai/dsh-llm'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
@@ -57,14 +58,17 @@ import { openNativePath } from './native-path-opener.ts'
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
 
-/** Surface message event types (the pagination counting unit). */
+/** Human message event types (the pagination counting unit). */
 const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
 
 /**
- * Message-boundary pagination: count maxMessages surface messages backwards from
- * the window tail; the cut is the starting seq of the oldest message group
- * (chunks group via sourceEventSeqs — never cut mid-message). The tail page
- * naturally includes the in-progress partial.
+ * Message-boundary pagination: count maxMessages append-origin human messages
+ * backwards from the window tail. Replacement copies are model-only, so they
+ * consume no quota; the page stays one contiguous raw range, which keeps a
+ * compaction's log-only provenance on the same page as its replacement. The cut
+ * is the starting seq of the oldest message group (chunks group via
+ * sourceEventSeqs — never cut mid-message). The tail page naturally includes the
+ * in-progress partial.
  */
 function paginate(
   events: readonly SessionEvent[],
@@ -76,7 +80,7 @@ function paginate(
   let cut = 0
   for (let i = window.length - 1; i >= 0; i--) {
     const event = window[i] as SessionEvent
-    if (!MESSAGE_TYPES.has(event.type)) continue
+    if (!MESSAGE_TYPES.has(event.type) || !isAppendSurfaceEvent(event)) continue
     count++
     const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs
     const groupStart = sources !== undefined && sources.length > 0 ? Math.min(event.seq, ...sources) : event.seq

packages/host/apiproxy/src/api/sessions.ts

@@ -176,9 +176,11 @@ export interface SessionsApi {
   Promise<RpcResponse<{ sessionId: SessionId }>>
 
   /**
-   * Reads a window of history events; page boundaries align to message boundaries: one page =
-   * all raw events owned by a whole number of messages (including their chunk / tool events),
-   * never cut mid-message. The tail page (beforeSeq absent) additionally carries the in-flight
+   * Reads a window of history events; page boundaries align to append-origin human-message
+   * boundaries: one page = all raw events owned by a whole number of such messages (including
+   * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no
+   * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail
+   * page (beforeSeq absent) additionally carries the in-flight
    * partial — chunk events already emitted for the last unfinalized message.
    * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
    * presenter produced one, evaluated against the registry at pagination time); the client

packages/host/apiproxy/tests/api-proxy-view.spec.ts

@@ -14,7 +14,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
-import { CallId, createToolResultMessage } from '@deepseek-ai/dsh-llm'
+import { CallId, createMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
@@ -35,6 +35,35 @@ function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'pr
   })
 }
 
+/** Append a production-shaped human prompt to the session surface. */
+function appendUserText(session: Session, text: string): SessionEvent {
+  return session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text }], source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+}
+
+/** Append a production-shaped assistant message to the session surface. */
+function appendAssistantText(session: Session, text: string, step: number): SessionEvent {
+  return session.append('assistant/message', {
+    turn: 1,
+    step,
+    message: createMessage({
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      source: { kind: 'model', provider: 'p', model: 'm' },
+    }),
+  }, { surfaceOp: 'append' })
+}
+
+/**
+ * Append a plugin-owned log-only event. The host proxy is projection-only, so it
+ * declares no compaction vocabulary; the cast writes the real event shape without
+ * depending on the owning package.
+ */
+function appendExtension(session: Session, type: string, data: unknown): SessionEvent {
+  return (session.append as unknown as (type: string, data: unknown) => SessionEvent)(type, data)
+}
+
 async function harness(): Promise<{ ctx: Context }> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -207,6 +236,55 @@ describe('mux live view computation', () => {
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
   })
 
+  it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const session = ctx.sessions.create()
+    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const first = appendUserText(session, 'first prompt')
+    appendAssistantText(session, 'first reply', 1)
+    const third = appendUserText(session, 'second prompt')
+    appendAssistantText(session, 'second reply', 2)
+    const shadowed = [...session.surface.nodes]
+    // A compaction transaction: log-only provenance immediately followed by the
+    // replacement that shadows the range.
+    const summary = appendExtension(session, 'compact/summary', {
+      summary: [{ type: 'text', text: 'summary' }],
+      shadowedRange: { start: shadowed[0], end: shadowed.at(-1) },
+      shadowedSeqs: shadowed,
+      shadowedTokenCount: 0,
+      provider: 'p',
+      model: 'm',
+    })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: '<context_checkpoint>summary</context_checkpoint>' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }), {
+      surfaceOp: { op: 'replace', start: shadowed[0] as number, end: shadowed.at(-1) as number },
+      sourceEventSeqs: [...shadowed, summary.seq],
+    })
+
+    const response = await api.sessions.history({
+      rpcId: RpcId('t-hist-compact'),
+      payload: { sessionId: session.id, maxMessages: 2 },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    const page = response.result.value.events.map(entry => entry.event)
+    // Two append-origin messages fill the page even though a replacement copy of
+    // the same event type sits in the window: the copy is model-only.
+    const messages = page.filter(event => event.type === 'user/message' || event.type === 'assistant/message')
+    expect(messages.map(event => event.seq)).toEqual([third.seq, third.seq + 1, third.seq + 3])
+    expect(page.some(event => event.seq === first.seq)).toBe(false)
+    expect(response.result.value.hasMore).toBe(true)
+    // The range stays contiguous, so the checkpoint's provenance is readable on
+    // the same page as the checkpoint itself.
+    const summaryIndex = page.findIndex(event => event.seq === summary.seq)
+    expect(summaryIndex).toBeGreaterThan(-1)
+    expect(page[summaryIndex + 1]?.seq).toBe(summary.seq + 1)
+    expect(page.map(event => event.seq)).toEqual(page.map((_event, index) => third.seq + index))
+  })
+
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
     const { ctx } = await harness()
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })

packages/ui/tui/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/ui/tui/README.md
-README.md: 0b358520b863f0b9ee7a128cf4807f582fc46d8d
-README.zh.md: 7e89197bd82d16dfbabeb715e953275e2f6dd68b
+README.md: c6542cf5383e46f43024782c89e364c92a4c518e
+README.zh.md: 7fbdaace128f779abf27de9042cd13b85ceef37f

packages/ui/tui/README.md

@@ -12,7 +12,7 @@ This package owns interactive terminal presentation and input only. It injects `
 
 After terminal startup succeeds, the package provides the terminal-local `ctx.tui` extension service. A plugin that injects it can call `openOverlay()` with a component factory and constrained layout options; the host exposes the viewport, semantic theme, display-text escaping, redraw, close, and a lifetime signal, but not the pi-tui tree, terminal, focus controller, or overlay handle. Plugin overlays, the model selector, and user questions share one FIFO modal queue. Each request is an effect of the calling plugin fiber, so unload removes queued work or closes visible work before cleanup settles; terminal shutdown unloads dependents before stopping pi-tui. Overlay state is not logged or replayed. Component code is trusted and may render ANSI styling, but must pass untrusted text through `host.display()`. The [interactive-extension Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md) owns the boundary and rejected alternatives.
 
-The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the standing `todo/write` plan above the editor (cleared on the next `turn/start`), and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes `<session title> — <configured title>`. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelInfo()` context for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode plus the current model and any explicitly selected reasoning effort; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. Surface replacement events rebuild the transcript so compacted history does not reappear.
+The TUI rebuilds resumed history from the append-origin session events, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the standing `todo/write` plan above the editor (cleared on the next `turn/start`), and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes `<session title> — <configured title>`. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelInfo()` context for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode plus the current model and any explicitly selected reasoning effort; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. A surface replacement never rewrites the rendered transcript: the conversation it shadows stays readable, and a landed compaction checkpoint adds one dim `… earlier context was compacted …` marker at its log position, so the terminal reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies — a pruned tool result, a regenerated assistant message — render nothing.
 
 An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label differs from the session's host directory. The override changes only the footer label; tools continue to use the session `cwd`.
 

packages/ui/tui/README.zh.md

@@ -12,7 +12,7 @@ DeepSeek Harness agent（智能体）的交互式终端入口，基于 [`@earend
 
 终端成功启动后，本包会提供终端本地的 `ctx.tui` 扩展服务。注入该服务的插件可以使用组件工厂和受限布局选项调用 `openOverlay()`；宿主会公开 viewport、语义化主题、显示文本转义、重绘、关闭和生命周期信号，但不公开 pi-tui 树、终端、焦点控制器或 overlay 句柄。插件 overlay、模型选择器和用户问题共用一个 FIFO 模态队列。每个请求都是调用方插件 fiber 的 effect，因此卸载会移除排队工作，或在清理结算前关闭可见工作；终端关闭会先卸载依赖项，再停止 pi-tui。Overlay 状态不会记录或回放。组件代码受信任，可以渲染 ANSI 样式，但必须通过 `host.display()` 处理不受信任文本。[交互式扩展 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md)持有该边界和未采用的替代方案。
 
-TUI 从活跃会话表层重建已恢复历史，渲染 Markdown 响应与 reasoning，将每个工具的 `presentCall` / `presentResult` 意图应用到终端、diff 或通用卡片，把站立的 `todo/write` 计划保留在编辑器上方（下一个 `turn/start` 时清空），并在左下方宽键盘面板中展示 `ctx.userInteraction` 问题，包含进度、编号选项和对齐说明。最新记录的会话标题成为 header 副标题；标题不存在时使用 `welcome`，终端窗口标题则变为 `<session title> — <configured title>`。持久 `llm/retry` 事件会撤回失败步骤的实时 chunk，并在 transcript（文本记录）中渲染计划重试次数、延迟和失败；成功、耗尽与取消随后通过普通会话事件结算。Footer 会对每个已记录模型步骤的用量只计一次，包括失败尝试；对于没有用量 chunk 的日志，以已提交消息的用量回退。其空闲视图会将 token-meter 压力与 `ctx.llm.resolveModelInfo()` 为当前路由返回的上下文容量进行比较；适配器没有容量元数据时显示 `context unknown`，并显示工具卡片模式、当前模型，以及任何显式选择的推理强度。Agent 运行时，这些摘要会替换为已经过工作时间指示器和 `esc interrupt`。表层替换事件会重建 transcript，使经过压缩（compaction）的历史不会再次出现。
+TUI 从追加来源的会话事件重建已恢复历史，渲染 Markdown 响应与 reasoning，将每个工具的 `presentCall` / `presentResult` 意图应用到终端、diff 或通用卡片，把站立的 `todo/write` 计划保留在编辑器上方（下一个 `turn/start` 时清空），并在左下方宽键盘面板中展示 `ctx.userInteraction` 问题，包含进度、编号选项和对齐说明。最新记录的会话标题成为 header 副标题；标题不存在时使用 `welcome`，终端窗口标题则变为 `<session title> — <configured title>`。持久 `llm/retry` 事件会撤回失败步骤的实时 chunk，并在 transcript（文本记录）中渲染计划重试次数、延迟和失败；成功、耗尽与取消随后通过普通会话事件结算。Footer 会对每个已记录模型步骤的用量只计一次，包括失败尝试；对于没有用量 chunk 的日志，以已提交消息的用量回退。其空闲视图会将 token-meter 压力与 `ctx.llm.resolveModelInfo()` 为当前路由返回的上下文容量进行比较；适配器没有容量元数据时显示 `context unknown`，并显示工具卡片模式、当前模型，以及任何显式选择的推理强度。Agent 运行时，这些摘要会替换为已经过工作时间指示器和 `esc interrupt`。表层替换从不重写已渲染的 transcript：被它遮蔽的对话仍可阅读，而已落地的压缩（compaction）检查点会在其日志位置添加一行暗色 `… earlier context was compacted …` 标记，因此终端报告的是模型从何处起不再看到那段历史，而不是把它抹掉。仅供模型使用的替换副本——被裁剪的工具结果、重新生成的 assistant 消息——不渲染任何内容。
 
 如果逻辑工作区标签与会话宿主目录不同，嵌入方可以提供 `TuiRuntime.formatCwd`。该覆盖只改变 footer 标签；工具仍使用会话 `cwd`。
 

packages/ui/tui/package.json

@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-agent-loop": "^0.0.1",
     "@deepseek-ai/dsh-commands": "^0.0.1",
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-llm-retry": "^0.0.1",
@@ -73,6 +74,7 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",

packages/ui/tui/src/chat/helpers.ts

@@ -1,6 +1,6 @@
 /**
  * Zero-state helpers for the interactive chat channel: prompt-directory and
- * Git-branch formatting, surface/tool-call derivations over the session log,
+ * Git-branch formatting, transcript/tool-call derivations over the session log,
  * session-reference context cards, the placeholder editor, and banner-reveal
  * timing constants. None of these close over channel state.
  * @module @deepseek-ai/dsh-tui/chat/helpers
@@ -15,7 +15,9 @@ import {
   truncateToWidth,
   visibleWidth,
 } from '@earendil-works/pi-tui'
-import type { Session } from '@deepseek-ai/dsh-session'
+import { isCompactCheckpointSource } from '@deepseek-ai/dsh-compact'
+import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 
 /** Editor that shows a placeholder without making it editable content. */
 export class HintEditor extends Editor {
@@ -83,24 +85,16 @@ export function gitBranch(cwd: string): string | undefined {
 }
 
 /**
- * Sequence numbers currently visible on the session surface.
- * @param session - session whose surface nodes to read.
- * @returns the set of visible event sequence numbers.
- */
-export function activeSurfaceSeqs(session: Session): Set<number> {
-  return new Set(session.surface.nodes)
-}
-
-/**
- * Tool-call ids whose owning assistant message is on the active surface.
+ * Tool-call ids whose owning assistant message is append-origin, so its tool
+ * cards stay paired in the transcript after a replacement shadowed the message
+ * on the model surface.
  * @param session - session whose events to scan.
- * @param active - sequence numbers currently on the surface.
- * @returns the set of active tool-call ids.
+ * @returns the set of transcript tool-call ids.
  */
-export function activeToolCallIds(session: Session, active: ReadonlySet<number>): Set<string> {
+export function transcriptToolCallIds(session: Session): Set<string> {
   const ids = new Set<string>()
   for (const event of session.events) {
-    if (event.type !== 'assistant/message' || !active.has(event.seq)) continue
+    if (event.type !== 'assistant/message' || !isAppendSurfaceEvent(event)) continue
     for (const block of event.data.message.content) {
       if (block.type === 'tool-call') ids.add(block.id)
     }
@@ -108,6 +102,22 @@ export function activeToolCallIds(session: Session, active: ReadonlySet<number>)
   return ids
 }
 
+/**
+ * Whether an event is a landed compaction checkpoint. Recognition goes through
+ * {@link isCompactCheckpointSource} — the compaction seam's backend-independent
+ * contract for the source every backend stamps on its replacement user message —
+ * rather than the shape of the replacement. Other replacements (a pruned
+ * `tool/result`, a regenerated `assistant/message`) rewrite one node for the
+ * model and mark no boundary in the conversation.
+ * @param event - event to test.
+ * @returns true when the event compacted a surface range.
+ */
+export function isCompactCheckpoint(event: SessionEvent): boolean {
+  return event.type === 'user/message'
+    && isCompactCheckpointSource(event.data.source)
+    && isReplacementSurfaceEvent(event)
+}
+
 /**
  * Read a session-reference context card's display labels from an event source.
  * @param source - event source to inspect.

packages/ui/tui/src/index.ts

@@ -35,6 +35,9 @@ import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import {
+  isAppendSurfaceEvent,
+  isReplacementSurfaceEvent,
+  isSurfaceEligibleType,
   SessionId,
   type SessionEvent,
   type UserMessage,
@@ -118,14 +121,14 @@ import {
 } from './chat/skill-invocation.ts'
 import { ReferenceAutocompleteProvider } from './chat/autocomplete.ts'
 import {
-  activeSurfaceSeqs,
-  activeToolCallIds,
   BANNER_REVEAL_INTERVAL_MS,
   BANNER_REVEAL_STEPS,
   formatCwd,
   gitBranch,
   HintEditor,
+  isCompactCheckpoint,
   sessionReferenceCard,
+  transcriptToolCallIds,
 } from './chat/helpers.ts'
 import {
   createModelController,
@@ -268,6 +271,13 @@ export const inject = ['agents', 'sessions', 'commands', 'userInteraction', 'too
 /** Model guidance for path-only file references selected through the TUI. */
 export const FILE_REFERENCE_PROMPT = 'Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.'
 
+/**
+ * Transcript row standing in for one compacted range. The conversation the
+ * compaction replaced stays rendered above it: the marker reports where the
+ * model stopped seeing that history, not that the history is gone.
+ */
+const COMPACTION_MARKER = '… earlier context was compacted …'
+
 interface RunningStatus {
   turn: number | undefined
   timer: ReturnType<typeof setInterval>
@@ -816,6 +826,17 @@ export function createTuiChat(
     }
   }
 
+  const renderCompactionMarker = (): void => {
+    chat.addChild(new Spacer(1))
+    chat.addChild(new Text(palette.dim(COMPACTION_MARKER), 0, 0))
+  }
+
+  /**
+   * Replay the human transcript from the append-only log. The model-visible
+   * surface shadows compacted ranges, so it is not the source here: every
+   * append-origin message stays rendered, and a replacement contributes at most
+   * the compaction marker at its own log position.
+   */
   const rebuildTranscript = (populateHistory: boolean): void => {
     chat.clear()
     toolCards.clear()
@@ -823,15 +844,13 @@ export function createTuiChat(
     contextCards.clear()
     streaming = undefined
     todo.update([])
-    const active = activeSurfaceSeqs(agent.session)
-    const activeCalls = activeToolCallIds(agent.session, active)
+    const transcriptCalls = transcriptToolCallIds(agent.session)
     for (const event of agent.session.events) {
-      const isSurface = event.type === 'user/message'
-        || event.type === 'assistant/message'
-        || event.type === 'tool/result'
-        || event.type === 'steering/message'
-      if (isSurface && !active.has(event.seq)) continue
-      if (event.type === 'tool/call' && !activeCalls.has(event.data.callId)) continue
+      if (isSurfaceEligibleType(event.type) && !isAppendSurfaceEvent(event)) {
+        if (isCompactCheckpoint(event)) renderCompactionMarker()
+        continue
+      }
+      if (event.type === 'tool/call' && !transcriptCalls.has(event.data.callId)) continue
       renderEvent(event, { addHistory: populateHistory, renderChunks: false })
     }
     requestRender()
@@ -1438,8 +1457,11 @@ export function createTuiChat(
     recordEventUsage(tokens, event)
     if (event.type === 'turn/start' && runningStatus !== undefined) runningStatus.turn = event.data.turn
     if (event.type === 'assistant/message' && streaming?.isSettled()) streaming = undefined
-    if ('surfaceOp' in event && typeof event.surfaceOp === 'object') {
-      rebuildTranscript(false)
+    // A replacement mutates only the model surface, so the rendered transcript
+    // keeps what it already showed; a landed summary checkpoint adds its marker.
+    if (isReplacementSurfaceEvent(event)) {
+      if (isCompactCheckpoint(event)) renderCompactionMarker()
+      requestRender()
       return
     }
     renderEvent(event, { addHistory: false, renderChunks: true })

packages/ui/tui/tests/snapshots/surface-after-compaction-narrow.expected.txt

@@ -1,7 +1,7 @@
-terminal 44x18 buffer=normal length=18 base=0 viewport=0
+terminal 44x18 buffer=normal length=24 base=6 viewport=6
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=7 viewportRow=14 bufferRow=14
+cursor hidden column=7 viewportRow=17 bufferRow=23
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-magenta bold
@@ -13,25 +13,39 @@ buffer
 3| <blank>
 4| "Assistant                                   "
   style 0-8 fg=bright-magenta bold underline
-5| "Model wait 0.0s                             "
+5| <blank>
+6| "You                                         "
+  style 0-2 fg=bright-magenta bold underline
+7| "Old prompt with a long line that exercises  "
+8| "wrapping and stays visible after compaction."
+9| <blank>
+10| "● Tool / bash / Run the coverage gate"
+  style 0-36 fg=green
+11| "$ pnpm run test:coverage                    "
+  style 0-23 dim
+12| "/workspace/project                          "
+  style 0-17 dim
+13| "packages/ui/tui 100%                        "
+  style 0-19 dim
+14| "… +1 lines (Ctrl+O to expand)               "
+  style 0-28 dim
+15| "1 test skipped                              "
+  style 0-13 dim
+16| "coverage complete                           "
+  style 0-16 dim
+17| "[exit 0]                                    "
+  style 0-7 dim
+18| "Model wait 0.0s                             "
   style 0-14 dim
-6| <blank>
-7| "Context · workspace-context"
-  style 0-26 dim
-8| "Additional instructions from:               "
-  style 0-43 dim
-9| "nested/AGENTS.md                            "
-  style 0-15 dim
-10| "                                            "
-11| "Render workspace context XML clearly.       "
-  style 0-36 dim
-12| <blank>
-13| "/workspace/project (tui-staging)  deepseek-v"
+19| <blank>
+20| "… earlier context was compacted …           "
+  style 0-32 dim
+21| <blank>
+22| "/workspace/project (tui-staging)  deepseek-v"
   style 0-17 fg=bright-magenta bold
   style 18-31 dim
   style 34-43 dim
-14| " dsh >                                      "
+23| " dsh >                                      "
   style 1-3 fg=bright-magenta bold
   style 5-6 dim
   style 7-7 inverse
-15-17| <blank>

packages/ui/tui/tests/snapshots/surface-after-compaction-wide.expected.txt

@@ -1,7 +1,7 @@
 terminal 104x30 buffer=normal length=30 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=7 viewportRow=13 bufferRow=13
+cursor hidden column=7 viewportRow=22 bufferRow=22
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-magenta bold
@@ -13,25 +13,41 @@ buffer
 3| <blank>
 4| "Assistant                                                                                               "
   style 0-8 fg=bright-magenta bold underline
-5| "Model wait 0.0s                                                                                         "
+5| <blank>
+6| "You                                                                                                     "
+  style 0-2 fg=bright-magenta bold underline
+7| "Old prompt with a long line that exercises wrapping and stays visible after compaction.                 "
+8| <blank>
+9| "● Tool / bash / Run the coverage gate"
+  style 0-36 fg=green
+10| "$ pnpm run test:coverage                                                                                "
+  style 0-23 dim
+11| "/workspace/project                                                                                      "
+  style 0-17 dim
+12| "packages/ui/tui 100%                                                                                    "
+  style 0-19 dim
+13| "… +1 lines (Ctrl+O to expand)                                                                           "
+  style 0-28 dim
+14| "1 test skipped                                                                                          "
+  style 0-13 dim
+15| "coverage complete                                                                                       "
+  style 0-16 dim
+16| "[exit 0]                                                                                                "
+  style 0-7 dim
+17| "Model wait 0.0s                                                                                         "
   style 0-14 dim
-6| <blank>
-7| "Context · workspace-context"
-  style 0-26 dim
-8| "Additional instructions from: nested/AGENTS.md                                                          "
-  style 0-45 dim
-9| "                                                                                                        "
-10| "Render workspace context XML clearly.                                                                   "
-  style 0-36 dim
-11| <blank>
-12| "/workspace/project (tui-staging)  deepseek-v4-flash  ↑0 ↓0  0% context"
+18| <blank>
+19| "… earlier context was compacted …                                                                       "
+  style 0-32 dim
+20| <blank>
+21| "/workspace/project (tui-staging)  deepseek-v4-flash  ↑0 ↓0  0% context"
   style 0-17 fg=bright-magenta bold
   style 18-31 dim
   style 34-50 dim
   style 53-57 dim
   style 60-69 dim
-13| " dsh >                                                                                                  "
+22| " dsh >                                                                                                  "
   style 1-3 fg=bright-magenta bold
   style 5-6 dim
   style 7-7 inverse
-14-29| <blank>
+23-29| <blank>

packages/ui/tui/tests/snapshots/surface-before-compaction.expected.txt

@@ -1,7 +1,7 @@
 terminal 80x24 buffer=normal length=24 base=0 viewport=0
 lifecycle started=1 stopped=0 progress=inactive
 title "DSH snapshot"
-cursor hidden column=7 viewportRow=20 bufferRow=20
+cursor hidden column=7 viewportRow=21 bufferRow=21
 buffer
 0| " DEEPSEEK HARNESS"
   style 1-8 fg=bright-magenta bold
@@ -16,35 +16,36 @@ buffer
 5| <blank>
 6| "You                                                                             "
   style 0-2 fg=bright-magenta bold underline
-7| "Old prompt with a long line that exercises wrapping before compaction.          "
-8| <blank>
-9| "● Tool / bash / Run the coverage gate"
+7| "Old prompt with a long line that exercises wrapping and stays visible after     "
+8| "compaction.                                                                     "
+9| <blank>
+10| "● Tool / bash / Run the coverage gate"
   style 0-36 fg=green
-10| "$ pnpm run test:coverage                                                        "
+11| "$ pnpm run test:coverage                                                        "
   style 0-23 dim
-11| "/workspace/project                                                              "
+12| "/workspace/project                                                              "
   style 0-17 dim
-12| "packages/ui/tui 100%                                                            "
+13| "packages/ui/tui 100%                                                            "
   style 0-19 dim
-13| "… +1 lines (Ctrl+O to expand)                                                   "
+14| "… +1 lines (Ctrl+O to expand)                                                   "
   style 0-28 dim
-14| "1 test skipped                                                                  "
+15| "1 test skipped                                                                  "
   style 0-13 dim
-15| "coverage complete                                                               "
+16| "coverage complete                                                               "
   style 0-16 dim
-16| "[exit 0]                                                                        "
+17| "[exit 0]                                                                        "
   style 0-7 dim
-17| "Model wait 0.0s                                                                 "
+18| "Model wait 0.0s                                                                 "
   style 0-14 dim
-18| <blank>
-19| "/workspace/project (tui-staging)  deepseek-v4-flash  ↑0 ↓0  0% context"
+19| <blank>
+20| "/workspace/project (tui-staging)  deepseek-v4-flash  ↑0 ↓0  0% context"
   style 0-17 fg=bright-magenta bold
   style 18-31 dim
   style 34-50 dim
   style 53-57 dim
   style 60-69 dim
-20| " dsh >                                                                          "
+21| " dsh >                                                                          "
   style 1-3 fg=bright-magenta bold
   style 5-6 dim
   style 7-7 inverse
-21-23| <blank>
+22-23| <blank>

packages/ui/tui/tests/tui.snapshot.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it, vi } from 'vitest'
 import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
+import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
 import { createUserMessage, CallId, type ContentBlock , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
 import { SessionId, type JsonValue, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
@@ -684,7 +685,7 @@ describe('TUI terminal-state snapshots', () => {
     await disposeSnapshot(harness)
   })
 
-  it('pins compaction surface replacement and narrow-to-wide reflow', async () => {
+  it('pins preserved history, the compaction marker, and narrow-to-wide reflow', async () => {
     // Freeze the clock: the timing header hides zero-duration buckets, so a
     // real-clock millisecond tick between the fixture appends and the render
     // would flip `Tools 0.0s` in and out of the pinned header.
@@ -696,7 +697,7 @@ describe('TUI terminal-state snapshots', () => {
       tools: ADVANCED_CARD_TOOLS,
       beforeMount(session) {
         const user = session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping before compaction.' }],
+          content: [{ type: 'text', text: 'Old prompt with a long line that exercises wrapping and stays visible after compaction.' }],
           source: { kind: 'user' },
         }), { surfaceOp: 'append' })
         const assistant = session.append('assistant/message', {
@@ -717,7 +718,7 @@ describe('TUI terminal-state snapshots', () => {
           step: 1,
           message: createToolResultMessage({
             callId: CallId('old-tool'),
-            content: [{ type: 'text', text: 'obsolete output that must disappear' }],
+            content: [{ type: 'text', text: 'tool output that stays readable after compaction' }],
             isError: false,
           }),
         }, { surfaceOp: 'append' })
@@ -732,9 +733,9 @@ describe('TUI terminal-state snapshots', () => {
       harness.session.append('user/message', createUserMessage({
         content: [{
           type: 'text',
-          text: '<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nRender workspace context XML clearly.\n</system-reminder>',
+          text: '<context_checkpoint>\nModel-only summary payload that must never reach the transcript.\n</context_checkpoint>',
         }],
-        source: { kind: 'plugin', plugin: 'workspace-context' },
+        source: COMPACT_CHECKPOINT_SOURCE,
       }), {
         surfaceOp: { op: 'replace', start: replacementStart, end: replacementEnd },
         sourceEventSeqs: replacementSources,

packages/ui/tui/tests/tui.spec.ts

@@ -16,6 +16,7 @@ import { createUserMessage,
 } from '@deepseek-ai/dsh-llm'
 import { GOAL_CHANGE_VERSION, GoalId, renderGoalChange, type GoalSnapshotChangeMeta } from '@deepseek-ai/dsh-goal'
 import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands'
+import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
 import SessionStore, { SessionId, type JsonValue, type SessionEvent, type SessionHeader, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { SessionRecord } from '@deepseek-ai/dsh-session-query'
 import SkillService, { type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
@@ -4365,10 +4366,10 @@ describe('tool cards and surface replay', () => {
     await dispose(result)
   })
 
-  it('rebuilds after a surface replacement and hides shadowed tool calls', async () => {
+  it('keeps append-origin history and marks a landed compaction, live and on rebuild', async () => {
     const result = await setup({ tools })
     appendUser(result.session, 'old prompt')
-    const assistant = result.session.append('assistant/message', {
+    result.session.append('assistant/message', {
       turn: 1,
       step: 1,
       message: createMessage({
@@ -4391,21 +4392,116 @@ describe('tool cards and surface replay', () => {
         isError: false,
       }),
     }, { surfaceOp: 'append' })
-    const start = result.session.surface.nodes[0] as number
-    result.session.append('user/message', createUserMessage({
-      content: [{ type: 'text', text: 'summary replacement' }],
-      source: { kind: 'plugin', plugin: 'compact' },
+    // Result pruning rewrites one node's content in place: model-only, and no
+    // boundary in the conversation, so the terminal keeps the full output.
+    const originalResult = toolResult.data.message.content[0]
+    result.session.append('tool/result', {
+      ...toolResult.data,
+      message: freezeMessage({
+        ...toolResult.data.message,
+        content: [{ ...originalResult, content: [{ type: 'text', text: 'pruned result copy' }] }] as [typeof originalResult],
+      }),
+    }, {
+      surfaceOp: { op: 'replace', start: toolResult.seq, end: toolResult.seq },
+      sourceEventSeqs: [toolResult.seq],
+    })
+    const nodes = [...result.session.surface.nodes]
+    const checkpoint = result.session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: '<context_checkpoint>model-only summary payload</context_checkpoint>' }],
+      source: COMPACT_CHECKPOINT_SOURCE,
     }), {
-      surfaceOp: { op: 'replace', start, end: toolResult.seq },
-      sourceEventSeqs: [start, assistant.seq, toolResult.seq],
+      surfaceOp: { op: 'replace', start: nodes[0] as number, end: nodes.at(-1) as number },
+      sourceEventSeqs: nodes,
     })
+    // A regenerated assistant message replaces one node without summarizing
+    // anything, so it marks no boundary either.
+    const generic = result.session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      message: createMessage({
+        role: 'assistant',
+        content: [{ type: 'text', text: 'generic replacement copy' }],
+        source: {
+          kind: 'model',
+          ...{ provider: 'mock', model: 'deepseek-v4-flash' },
+        },
+      }),
+    }, { surfaceOp: { op: 'replace', start: checkpoint.seq, end: checkpoint.seq }, sourceEventSeqs: [checkpoint.seq] })
+    // Only a checkpoint carrying the compaction seam's source marks a boundary:
+    // another plugin replacing a node is model-only.
+    result.session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'foreign plugin replacement copy' }],
+      source: { kind: 'plugin', plugin: 'other' },
+    }), { surfaceOp: { op: 'replace', start: generic.seq, end: generic.seq }, sourceEventSeqs: [generic.seq] })
     await tick()
 
     result.terminal.resize(89)
     await tick()
-    const lastFullRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J'))
-    expect(lastFullRender).toContain('summary replacement')
-    expect(lastFullRender).not.toContain('old output')
+    const liveRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J'))
+    expect(liveRender).toContain('old prompt')
+    // The shadowed step keeps its card: one call row, one full result, no
+    // second card from the pruned copy.
+    expect(liveRender.split('$ printf hello')).toHaveLength(2)
+    expect(liveRender).toContain('third')
+    expect(liveRender.split('[exit 0]')).toHaveLength(2)
+    expect(liveRender.split('… earlier context was compacted …')).toHaveLength(2)
+    expect(liveRender).not.toContain('model-only summary payload')
+    expect(liveRender).not.toContain('generic replacement copy')
+    expect(liveRender).not.toContain('foreign plugin replacement copy')
+
+    // Ctrl+R rebuilds the transcript from the log; the replayed projection
+    // matches what the live appends produced, including the shadowed assistant
+    // message's tool card.
+    result.terminal.send('\x12')
+    await tick()
+    result.terminal.resize(90)
+    await tick()
+    const replayRender = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J'))
+    expect(replayRender).toContain('old prompt')
+    expect(replayRender.split('$ printf hello')).toHaveLength(2)
+    expect(replayRender).toContain('third')
+    expect(replayRender.split('[exit 0]')).toHaveLength(2)
+    expect(replayRender.split('… earlier context was compacted …')).toHaveLength(2)
+    expect(replayRender).not.toContain('model-only summary payload')
+    expect(replayRender).not.toContain('generic replacement copy')
+    expect(replayRender).not.toContain('foreign plugin replacement copy')
+    await dispose(result)
+  })
+
+  it('replays a stored compaction as preserved history plus its marker', async () => {
+    const result = await setup({
+      beforeMount(session) {
+        appendUser(session, 'prompt before compaction')
+        session.append('assistant/message', {
+          turn: 1,
+          step: 1,
+          message: createMessage({
+            role: 'assistant',
+            content: [{ type: 'text', text: 'reply before compaction' }],
+            source: {
+              kind: 'model',
+              ...{ provider: 'mock', model: 'deepseek-v4-flash' },
+            },
+          }),
+        }, { surfaceOp: 'append' })
+        const nodes = [...session.surface.nodes]
+        session.append('user/message', createUserMessage({
+          content: [{ type: 'text', text: '<context_checkpoint>stored model-only payload</context_checkpoint>' }],
+          source: COMPACT_CHECKPOINT_SOURCE,
+        }), {
+          surfaceOp: { op: 'replace', start: nodes[0] as number, end: nodes.at(-1) as number },
+          sourceEventSeqs: nodes,
+        })
+      },
+    })
+    result.terminal.resize(89)
+    await tick()
+
+    const mounted = result.terminal.output.slice(result.terminal.output.lastIndexOf('\x1b[2J'))
+    expect(mounted).toContain('prompt before compaction')
+    expect(mounted).toContain('reply before compaction')
+    expect(mounted.split('… earlier context was compacted …')).toHaveLength(2)
+    expect(mounted).not.toContain('stored model-only payload')
     await dispose(result)
   })
 })

packages/ui/tui/tsconfig.json

@@ -53,6 +53,9 @@
     {
       "path": "../commands"
     },
+    {
+      "path": "../../compact/compact"
+    },
     {
       "path": "../../skill/skill"
     },

pnpm-lock.yaml

@@ -4987,6 +4987,9 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../commands
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../../goal/goal