feat(desktop): unify sparse transcript paging with turn virtualization

[Astro-Han]

Problem

Desktop keeps transcript memory and IPC bounded by loading durable messages in byte-limited ranges. The renderer also keeps the DOM bounded through turn virtualization.

These two mechanisms currently stop at different boundaries:

• DesktopTranscriptReplica owns only the currently resident durable range. Loading around a target replaces that range.
• The renderer turn virtualizer derives its logical turns only from resident messages.
• The prompt rail uses a separate sampled landmark index that can span the complete conversation.

As a result, navigating to an unloaded prompt replaces the visible transcript range. Durable messages outside that range remain stored, but their logical positions disappear from the renderer until another range is loaded. #3880 makes this state understandable, but the product should ideally present one continuous conversation without exposing resident versus non-resident history.

The 512 KiB range limit is a transport and memory budget, not a conversation limit. Increasing it would only move the threshold.

Desired outcome

Users can navigate one continuous logical transcript, including unloaded history, while message bodies, renderer state, IPC, and mounted DOM remain bounded.

Loading or evicting a content page must not remove its logical place from the conversation or make other durable turns appear deleted.

Suggested architecture boundary

• Runtime Host and storage remain the only durable transcript authority.
• Preserve the existing bounded transcript page protocol and Main/Renderer cache budgets.
• Expose a lightweight, pageable logical turn-position index across the conversation. It should carry only the identity and ordering needed for layout and navigation, not duplicate message bodies.
• Let the renderer virtualizer operate on those logical positions and represent unloaded ranges as gaps or spacers.
• Load message bodies around the viewport, overscan window, and explicit navigation target.
• Evict content pages without removing their logical positions.
• Preserve the scroll anchor while estimated gaps are replaced by measured content.
• Keep sampled prompt landmarks as a navigation projection, not a second transcript or layout authority.

The exact protocol shape should follow the closest existing paging and virtualization seams. This issue does not require introducing another transcript store or retaining the complete transcript in Renderer memory.

Acceptance criteria

• Jumping from the live tail to an unloaded old or intermediate prompt loads the target without presenting the conversation as a different standalone range.
• Returning to the tail preserves the same logical transcript and live-tail behavior.
• Page loading and eviction preserve scroll position and scrollbar continuity.
• Mounted transcript DOM remains bounded by the existing turn-window budget.
• Main and Renderer content caches remain within their existing byte budgets.
• Active-overlay to durable-message handoff remains correct at the live tail.
• Keyboard and screen-reader navigation work across loaded and unloaded ranges.
• Copy/export reads from the complete data model rather than only the mounted or resident window.
• Regression coverage includes a transcript larger than twice the range budget and navigation between tail, intermediate, and old ranges.

Alternatives considered

• Increase the 512 KiB range budget: postpones the same discontinuity to a larger transcript.
• Retain several disconnected resident ranges: adds another cache representation without providing one stable logical layout.
• Explain resident ranges only in the UI: fix(desktop): clarify partial transcript ranges #3880 correctly improves the current behavior, but the user still has to understand an internal paging state.

Related work

• perf(desktop): make session data flow incremental and bounded #2913 tracks the broader bounded and incremental Desktop data-flow work.
• bug(desktop): sparse history range makes persisted prompts appear missing #3875 describes how sparse history can make durable prompts appear missing.
• fix(desktop): clarify partial transcript ranges #3880 clarifies the partial-range state under the current architecture and provides a useful large-transcript regression fixture.

@Sun-GLiang, if you are interested, this would be a natural architectural follow-up to #3880. The current PR does not need to expand to include it.

This issue was prepared with Codex under maintainer direction after reviewing the current transcript paging and virtualization boundaries. The maintainer owns the problem definition and proposed direction.

简体中文

问题

Desktop 通过按字节限制的范围加载来控制 transcript 的内存和 IPC 使用，同时通过 turn virtualization 控制挂载的 DOM 数量。

目前这两套机制停在了不同的边界：

• DesktopTranscriptReplica 只拥有当前驻留的持久化范围，围绕新目标加载时会替换这个范围。
• Renderer turn virtualizer 只能根据当前驻留的消息建立逻辑 turns。
• Prompt rail 使用另一份可以覆盖整段对话的抽样 landmark index。

因此，导航到未加载的 prompt 时，当前可见的 transcript 范围会被替换。范围外的持久化消息仍保存在 storage 中，但它们的逻辑位置会暂时从 Renderer 中消失。#3880 正确解释了这个状态，但理想的产品体验应该是一条连续的对话，不需要向用户暴露驻留和未驻留历史的区别。

512 KiB 是传输和内存预算，不是对话历史上限。提高这个数值只会把问题推迟到更大的 transcript。

目标结果

用户可以在一条连续的逻辑 transcript 中导航，包括尚未加载的历史；与此同时，消息正文、Renderer state、IPC 和已挂载 DOM 仍保持有界。

内容页面的加载或淘汰不能移除它在对话中的逻辑位置，也不能让其他持久化 turns 看起来像被删除。

建议的架构边界

• Runtime Host 和 storage 继续作为 transcript 唯一的持久化权威。
• 保留现有的有界 transcript page protocol 和 Main/Renderer 缓存预算。
• 提供覆盖整段对话、可分页的轻量逻辑 turn position index。它只携带布局和导航所需的身份与顺序，不复制消息正文。
• Renderer virtualizer 基于这些逻辑位置工作，把未加载范围表示成 gap 或 spacer。
• 围绕 viewport、overscan window 和明确的导航目标加载消息正文。
• 淘汰内容页面时不移除其逻辑位置。
• 用实际内容替换估算 gap 时保持滚动锚点稳定。
• 抽样 prompt landmarks 继续只负责导航，不成为第二份 transcript 或布局权威。

具体协议形态应该扩展现有的 paging 和 virtualization seam。这个 issue 不要求增加另一份 transcript store，也不要求在 Renderer 内存中保留完整 transcript。

验收标准

• 从 live tail 跳到未加载的较早或中间 prompt 时，可以加载目标，但不会把对话表现成另一段独立范围。
• 返回 tail 时仍处于同一条逻辑 transcript 中，并保持正常 live-tail 行为。
• 页面加载和淘汰期间保持滚动位置与 scrollbar 连续。
• 已挂载 transcript DOM 继续受现有 turn-window 预算限制。
• Main 和 Renderer 内容缓存继续遵守现有字节预算。
• Live tail 的 active-overlay 到 durable-message handoff 保持正确。
• 键盘和 screen reader 可以跨已加载与未加载范围导航。
• Copy/export 从完整数据模型读取，而不是只读取已挂载或驻留窗口。
• 回归测试包含大于两倍 range budget 的 transcript，以及 tail、中间和较早范围之间的导航。

考虑过的替代方案

• 提高 512 KiB range budget： 只会把同样的断层推迟到更大的 transcript。
• 同时保留多个不连续的驻留范围： 增加另一种缓存表示，但没有提供稳定、统一的逻辑布局。
• 只在 UI 中解释驻留范围： fix(desktop): clarify partial transcript ranges #3880 正确改善了当前行为，但用户仍然需要理解内部的分页状态。

相关工作

• perf(desktop): make session data flow incremental and bounded #2913 跟踪 Desktop 有界、增量数据流的整体工作。
• bug(desktop): sparse history range makes persisted prompts appear missing #3875 描述 sparse history 如何让持久化 prompt 看起来像是丢失。
• fix(desktop): clarify partial transcript ranges #3880 在当前架构下解释 partial-range 状态，并提供了有价值的大 transcript 回归 fixture。

@Sun-GLiang，如果你有兴趣，这会是 #3880 很自然的架构后续。当前 PR 不需要扩大范围来包含这项工作。

本 issue 由 Codex 在维护者指示下，根据当前 transcript paging 与 virtualization 边界的审查结果整理。问题定义和建议方向由维护者负责。

[Sun-GLiang]

Thank you for your invitation. I will continue to promote this work.

[Sun-GLiang]

take

[Sun-GLiang]

English

Additional regression scenario: large first turn with an active live tail

This was the condition under which the original bug was first observed and would be useful to preserve as an explicit acceptance/regression case.

Given:

• the transcript is larger than the bounded range budget;
• the first turn is large enough to consume most or all of the historical resident range;
• intermediate turns are durable but non-resident;
• the final turn is still streaming through the active overlay.

After navigating from the live tail to the first turn, the current Renderer projection can effectively become:

resident durable range: Turn 1
active overlay:         Turn N
non-resident history:   Turn 2 ... Turn N-1

Because logical turns are derived from resident messages plus the active overlay, the Renderer can make Turn 1 and Turn N appear adjacent. The intermediate durable turns are still present in storage, but their logical positions disappear along with their non-resident bodies.

The unified logical turn-position model should instead preserve:

Turn 1        loaded historical content
Turn 2...N-1  unloaded logical positions / gaps
Turn N        active overlay at the live tail

Suggested regression coverage:

1. Start with a transcript larger than twice the range budget, with a large first turn and an active final turn.
2. Navigate from the live tail to the first turn while streaming continues.
3. Verify that intermediate durable turns retain logical positions and that the first and active final turns never become logically adjacent.
4. Navigate or scroll back to the live tail.
5. Complete the active-overlay-to-durable handoff and verify stable identity/order, no duplication, no missing turns, and no scroll jump.

This is part of the same paging/virtualization boundary problem, but explicitly covering it would protect the original discovery condition.

简体中文

补充回归场景：超大的首个 turn 与仍处于 active 状态的 live tail

这是最初发现该 bug 时的触发条件，建议作为明确的验收和回归测试场景保留下来。

条件如下：

• transcript 大于有界 range budget；
• 第一个 turn 很大，占用历史驻留范围的大部分或全部预算；
• 中间 turns 已持久化，但当前未驻留；
• 最后一个 turn 仍通过 active overlay 流式生成。

从 live tail 跳转到第一个 turn 后，Renderer 当前的投影实际上可能变成：

驻留的 durable range：Turn 1
active overlay：       Turn N
未驻留历史：           Turn 2 ... Turn N-1

由于逻辑 turns 是从驻留消息与 active overlay 推导的，Turn 1 和 Turn N 可能被错误地表现为相邻。中间 turns 仍存在于 storage，但其逻辑位置会随着未驻留正文一起从 Renderer 中消失。

统一后的逻辑 turn-position 模型应当保留：

Turn 1        已加载的历史正文
Turn 2...N-1  未加载的逻辑位置 / gaps
Turn N        位于 live tail 的 active overlay

建议测试：在流式生成期间跳转到超大的首个 turn，验证中间 turn 的逻辑位置始终存在；然后返回 live tail 并完成 active-overlay 到 durable message 的交接，验证顺序与身份稳定、不重复、不缺失且滚动位置不跳动。

[Sun-GLiang]

English

Controlled Desktop E2E reproduction — rerun at 01369b0

I reran the same large-first-turn + active-live-tail experiment at 01369b08248d8b66b6c5a1a6204f9683397a10a1 (fix(desktop): simplify partial history notice (#4140)). All other conditions were kept the same.

The run used an isolated E2E user-data directory and scratch SQLite workspace for every launch; it did not read or modify a developer database. The fixture Session was bound to the fixture Connection through the current llmConnectionId, so the result was not obscured by the legacy-account health banner.

The fixture constructed this durable transcript:

sequence 0-1: Turn 1 request + assistant plan (> 512 KiB)
sequence 2-3: completed Turn 2 request + reply
sequence 4-5: completed Turn 3 request + reply
sequence 6:   Turn 4 request

It then loaded the durable range around sequence 0 and supplied only the Turn 4 assistant response through the active overlay. The Runtime snapshot identified Turn 4 as the running root turn with one active text stream.

Observed state:

durable watermark:          6
resident durable sequences: [0, 1]
hasNewer:                   true
active overlay:             [Turn 4 assistant]

durable turn index:         [Turn 1, Turn 2, Turn 3, Turn 4]
prompt residency:           [true, false, false, false]
Renderer source count:      2
Renderer logical turn ids:  [Turn 1, Turn 4]
mounted turn ids:           [Turn 1, Turn 4]

The result is unchanged from the earlier baseline: the rendered transcript contains the Turn 1 request/reply followed immediately by the Turn 4 assistant overlay. It does not contain the Turn 2 request/reply, the Turn 3 request/reply, or the durable Turn 4 request. Storage and the landmark index still contain all four Turns, but the non-resident Turns have no logical positions in the Renderer virtualizer.

At this commit, the partial-history UI is visibly simpler: the page shows only “正在查看较早的消息” and “返回最新消息”. The legacy “需要选择账号” banner is absent. This improves the notice but does not change the sparse Renderer projection or restore a continuous logical transcript.

The focused Playwright case passed in two independent launches, each with a fresh isolated database and a different generated Host/session identity. The existing transcript replica/range-store verification also remained green (20/20 tests). All temporary fixture hooks and the temporary spec were removed after capture, and the worktree was restored without a commit.

As before, this is controlled state injection at the DesktopTranscriptReplica preparation boundary. It exercises the production Desktop storage index, transcript range store, Renderer, prompt rail, and turn virtualizer, while deliberately not claiming to reproduce every detail of a natural provider-stream lifecycle. The active-overlay condition is established by the replica/runtime probe; this injected seed does not set the final Turn's data-live-streaming DOM attribute at this commit.

简体中文

受控 Desktop E2E 复现实验——基于 01369b0 重跑

我在 01369b08248d8b66b6c5a1a6204f9683397a10a1（fix(desktop): simplify partial history notice (#4140)）上重新运行了同一个“超大首个 turn + 仍处于 active 状态的 live tail”实验，其他条件保持不变。

每次启动都使用独立的 E2E user-data 目录和临时 SQLite workspace，没有读取或修改开发者数据库。Fixture Session 通过当前的 llmConnectionId 绑定到 fixture Connection，因此结果没有受到旧版账号健康提示条的干扰。

Fixture 构造了以下持久化 transcript：

sequence 0-1：Turn 1 请求 + assistant plan（> 512 KiB）
sequence 2-3：已完成的 Turn 2 请求 + 回复
sequence 4-5：已完成的 Turn 3 请求 + 回复
sequence 6：  Turn 4 请求

随后，实验围绕 sequence 0 加载 durable range，并只通过 active overlay 提供 Turn 4 的 assistant 回复。Runtime snapshot 将 Turn 4 标记为正在运行的 root turn，并包含一个 active text stream。

观察到的状态：

durable watermark：          6
驻留 durable sequences：     [0, 1]
hasNewer：                   true
active overlay：             [Turn 4 assistant]

durable turn index：         [Turn 1, Turn 2, Turn 3, Turn 4]
prompt residency：           [true, false, false, false]
Renderer source count：      2
Renderer logical turn ids：  [Turn 1, Turn 4]
mounted turn ids：           [Turn 1, Turn 4]

结果与先前基线一致：渲染后的 transcript 中，Turn 1 的请求/回复之后直接出现 Turn 4 的 assistant overlay。其中没有 Turn 2 的请求/回复、Turn 3 的请求/回复，也没有已持久化的 Turn 4 请求。Storage 和 landmark index 中仍然存在全部四个 Turns，但未驻留 Turns 在 Renderer virtualizer 中没有逻辑位置。

在这个 commit 上，partial-history UI 明显更简洁：页面只显示“正在查看较早的消息”和“返回最新消息”；旧的“需要选择账号”提示条没有出现。这改善了提示方式，但没有改变稀疏的 Renderer 投影，也没有恢复连续的逻辑 transcript。

聚焦的 Playwright 用例在两次独立启动中均通过；每次都使用全新的隔离数据库和不同的动态 Host/session identity。现有 transcript replica/range-store 验证也保持通过（20/20 tests）。截图完成后，所有临时 fixture hooks 和临时 spec 均已移除，worktree 已恢复且没有提交。

与之前相同，本次复现是在 DesktopTranscriptReplica 准备边界注入受控状态。它覆盖了生产实现中的 Desktop storage index、transcript range store、Renderer、prompt rail 和 turn virtualizer，但不声称复现自然 provider streaming 生命周期的每一个细节。Active overlay 条件由 replica/runtime probe 确认；在此 commit 上，这个注入 seed 不会给最终 Turn 设置 data-live-streaming DOM 属性。

[Sun-GLiang]

Implementation plan

I am splitting #4123 into four reviewable changes. The branches are intentionally named without tool-specific prefixes, and each independent foundation PR will start from the same current upstream/main baseline.

Dependency graph

PR-A Turn position index ─┐
                          ├──> PR-C Continuous transcript UI
PR-B Transcript residency ┘

PR-D Complete copy/export ─── independent

#4123 is complete after PR-A, PR-B, PR-C, and PR-D are merged.

PR-A — feat/4123-turn-position-index

• Add a rebuildable, pageable logical Turn-position index.
• Reuse the existing admission/legacy Turn-boundary semantics.
• Maintain the index for new writes and imports.
• Add resumable bounded backfill for existing Sessions.
• Add the compatible session.turn_positions.query operation.
• Cover tail, ordinal, sequence, watermark, legacy, import, and resume cases.

PR-B — feat/4123-transcript-residency

• Merge disjoint transcript ranges instead of replacing the resident range.
• Add LRU eviction and viewport/navigation protection.
• Preserve the existing Main/Renderer byte budgets.
• Coalesce prefetch requests and make explicit navigation latest-wins.
• Preserve live-tail catch-up and active-overlay handoff.

PR-C — feat/4123-continuous-transcript

Depends on PR-A and PR-B.

• Add a bounded sparse Turn-position store.
• Represent unloaded ordinal ranges as estimated gaps.
• Adapt the existing Turn virtualizer instead of introducing another virtual-list implementation.
• Preserve scroll anchors while gaps become measured content.
• Keep Rail/Search jumps stable under rapid navigation.
• Preserve live-tail behavior while reading history.
• Support keyboard and screen-reader navigation across unloaded ranges.
• Add the >2× range-budget and large-first-Turn + active-tail E2E regression.

PR-D — feat/4123-complete-transcript-export

Independent of PR-A/PR-B/PR-C.

• Page the complete transcript from Main at a fixed watermark.
• Share the existing Markdown formatting logic.
• Stream file export without materializing the transcript in Renderer.
• Ensure clipboard copy includes non-resident history.
• Cover early, intermediate, tail, live-append, and paging-failure cases.

Cross-PR acceptance

• Loading or evicting bodies never removes their logical place.
• Scrollbar geometry and visible anchors remain continuous.
• Main/Renderer content caches remain within their current byte budgets.
• Mounted transcript DOM remains within the existing 100-Turn budget.
• Turn-position Renderer state remains bounded.
• Returning to the tail preserves streaming and overlay-to-durable identity.
• Copy/export reads the complete transcript rather than the resident window.

I will edit this comment with PR links and checked items as each slice is opened and merged.