DSH: Why Opening a Large Cold History Session Can Stall the Whole Web Server — A Systematic Root-Cause Analysis and Optimization Roadmap

[Zn-Dk]

Status: FINAL — ready for community posting (drafted 2026-08-25, finalized 2026-08-27 with T2 measurements).
Working title — adjust per community convention before posting.

What this post is: a synthesis / review of #1550 and the related community efforts (wellorbetter's fork hardening patch, ernel135790's bounded-read patch, dsh-doctor, dsh-session-surgeon, dsh-fast, dsh-session-pruner), plus a staged optimization roadmap — not a duplicate bug report. If you have already read #1550, you can skip straight to §2 Root Cause Analysis for the parts that are new (R2: JSONL has no seek; R4: the projection path bypasses its own cache) and §4 Optimization roadmap for the consolidated plan. Discussion welcome — the goal is to converge on one direction upstream.

中文摘要

DeepSeek Harness(DSH)首次打开一个较大的历史会话(几千条消息、大量 tool 结果,或含损坏提交历史的会话)时,Web 服务可能整体卡死数秒甚至超时。官方社区讨论 #1550(2026-08-14,报告人 wellorbetter,维护者 argszero 已确认)已经记录了这个现象与初步定位。本文不是重复报 bug,而是在 #1550 基础上做一次更系统的根因分析,并把问题从"损坏会话的 availability amplifier"扩展为所有大会话冷加载的通病:

1. 全量物化:分页(默认 50 条消息)在 persistence 层之前才发生;冷会话历史请求会先把整个日志读完——readFile 整个文件、解压全部 zstd frame、逐行 JSON.parse、展开 packed chunk——再截取尾部页。maxMessages 只限制返回 payload,不限制任何 IO/解压/解析/校验/物化成本。
2. 主线程阻塞:上述全量解码/重建/投影重放全部在 Node.js 主线程同步执行,一个会话就能让同进程所有请求(包括 GET /)无响应。这是 [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550 事故的直接机制:163MB 工作集、0.95 CPU 秒/2 秒墙钟、3080 端口堆积 CLOSE_WAIT、GET / 超时 10s+。
3. O(n²) surface 折叠:会话重建时 surface 的 replacementRange 用 state.nodes.indexOf 线性扫描节点数组,带 compaction 的大会话折叠为 O(n²)。
4. 投影全量重放:detached 历史路径的投影不走已有缓存,每次尾页都从 seq 0 全量重折叠;与全量物化叠加成双重 O(n)。
5. 无缓存放大:prepared-session LRU 只有 5 个槽,大会话被逐出后重开即重复全量;损坏会话重试无负面缓存,反复全量扫描同一文件。

本机实测(8.84MB 压缩 / 20.2MB JSON / 2.77 万事件 / 2.4 万 zstd 帧的真实日志):冷读一次(读盘+全帧解码+逐行 parse+逐事件快照)约 430ms(private decoder)/ 880ms(public),其中 JSON.parse ~200ms、事件快照 ~148ms、解码 ~78ms——而这只是"取最后 50 条消息"的前置成本。优化方向按性价比分三档:短期(A 尾部索引 sidecar+JSONL seek 冷开 <50ms、B 合并写帧减帧数 10-50x、C detached 投影接 coldSnapshot、D 事件快照按需、E 列表 header 缓存,以及社区 fork 已验证的 writer lease / yield 16ms / revision 负缓存)、中期(F 客户端骨架屏+预取、流式分页、LRU 自适应、list/inspect 隔离)、长期(G 默认 SQLite、存储格式演进、结构化损坏诊断)。预期可将冷开一个 46 万事件会话从 ~9s 降到 <100ms,并结构性消除 #1550 的全局可用性事故。

---

1. Problem Statement

1.1 Community anchor: Discussion #1550

Official discussion #1550 — "[Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server" — reported by wellorbetter on 2026-08-14 and confirmed by maintainer argszero against master, captures the community's first-hand account:

"Opening a cold, very large session calls the persistence inspection path before response pagination is applied. The server therefore decompresses, parses, validates, and materializes the complete event stream ... all on the Node.js main thread."

The incident: with one structurally valid large session plus one session with a committed-seq rollback in the tree, the Web server accepted TCP connections on 127.0.0.1:3080 but GET / timed out; after isolating the two session trees and restarting, it recovered. During the outage: ~163 MB working set, ~0.95 CPU-seconds per 2 wall-clock seconds, and a pile of CLOSE_WAIT sockets on port 3080.

Measured artifacts from #1550:

	Session A (corrupt committed history)	Session B (valid but very large)
compressed size	4.853 MB	6.984 MB
decoded size	16.587 MB	15.971 MB
zstd frames	9,730	21,153
storage records	26,934	27,030
expanded events	461,981	444,316
turns / steps / children	—	50 / 482 / 12
projected surface context	—	~601,559 tokens

argszero's framing is worth quoting verbatim:

"Confirmed against master — and the 'server-wide availability' framing is the important part. This is the availability amplifier of the corruption family ..."

and his layered fix direction: bound the read (seekable/bounded persistence reads that stop at a page boundary instead of decode-everything-then-slice), cheap corruption detection (seq monotonicity at the frame scan level), and isolation (unreadable sessions quarantined at list/inspect time, never entering the full-scan path).

1.2 Why this document is not a duplicate bug report

#1550 was filed with corruption as the trigger and "availability amplifier" as the consequence. This document is a more systematic root-cause analysis plus an optimization roadmap that:

1. Generalizes the trigger: the same full-materialization path hurts every large cold session, corrupt or not — [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550's Session B (structurally valid, 444K events) is the proof. Corruption is a force multiplier, not the only driver.
2. Adds precise, current-source code evidence: [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550 cites api-proxy.ts at commit 47f9438 (lines 1533–1538 / 805–818 / 2242–2259); we traced the same path on current master with exact locations for the persistence backends, the event-rebuild layer, the projection path, and the cache behavior.
3. Adds an end-to-end complexity model: cold read O(bytes) + O(n) event rebuild + O(cells × n) projection re-fold; list O(session count); per-page O(50 × definition count); UI rendering O(window nodes) — with the repo's own perf benchmark (complex-history.perf.ts) as validation.
4. Offers a staged, actionable roadmap (short / mid / long term) that builds on argszero's direction and the ecosystem (dsh-doctor, session doctor discussions) instead of re-listing the same six suggestions.

1.3 Scope and method

• Repository: deepseek-ai/deepseek-harness (current master, inspected 2026-08-25).
• Method: source tracing with exact file:line evidence (see Root Cause Analysis) plus a local measurement on a real 8.84 MB session log (Node v22.22.3, private zstd decoder; see §3); [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550's incident numbers cross-validate the model.
• Out of scope: writer-side corruption mechanics (Bug: 同一会话被两个 dsh 进程并发写入导致会话日志损坏（seq 撞号） #1433/BUG: 同一 DSH_HOME 下多进程并发写同一会话日志，导致 seq 重复、整段历史无法加载 #1452/Bug: corrupt session log after unclean exit — replayed events cause seq gap in committed region, history unrecoverable #1497), offline repair tooling (Add a session doctor and versioned migrations #1518/dsh-doctor: an offline diagnostic for the failure classes this community keeps reporting #1534), plugin landscape (dsh-fast, dsh-session-pruner).

1.4 Community status (as of 2026-08-25)

The issue is live and unfixed upstream. Cross-checking #1550's own source citations against current master shows the same mechanism, with line-number drift only (see §2.2):

#1550 conclusion	cited at commit 47f9438	current master
cold historySourceFor gets full events before pagination	api-proxy.ts:1533-1538	api-proxy.ts:1474-1479
historyPage paginates afterwards	api-proxy.ts:805-818	api-proxy.ts:745-761 / 228-254
readPrefix → readZstdPrefix decodes every frame	session-persistence-jsonl/src/index.ts:310, 348	same lines
per-event structuredClone in adopt	core/session/src/index.ts:1172 (older)	core/session/src/index.ts:192-194
ZSTD_DECODE_YIELD_INTERVAL_MS	500 ms	still 500 ms (index.ts:44) — the #1550 suggestion to lower it to 16 ms was never merged
writer-lease / revision negative-cache	—	absent (no writer-lease.ts; no readFailures cache)

The reporter already prototyped a fix: wellorbetter's fork branch fix/session-history-responsiveness (commit 159c5e4) contains (1) a cross-process writer lease (attacking the #1333/#1452 double-writer root cause), (2) ZSTD_DECODE_YIELD_INTERVAL_MS 500→16 ms so large decodes yield to other requests, and (3) a revision-keyed negative cache (readFailures) so unchanged corrupt artifacts fail immediately instead of re-decoding. argszero's review: all three mechanisms pass their tests (2/2 + 152/152 + 81/81), but the patch does not cover the first valid large session's cold open — it still fully materializes; no bounded/seekable read, and the #1473 boot-block path is untouched. None of it is merged upstream as of 2026-08-25.

The problem is not corruption-only: community member 7889545 reproduced a pure scale case without any corruption — 15 valid sessions (1.8–2.7 MB compressed each / ~300k tokens / 5–7k events) grew the process to ~3 GB heap within 60–90 s of boot with no client interaction; CPU profile ~60 % in structuredClone; heap snapshot 21.6M live objects (assistant/chunk 59 MB, reasoning-delta 38 MB, …). Moving 11 session directories out of sessions/ dropped the heap to ~306 MB. Notably archivedSessionIds does not reduce memory — archived sessions are still fully materialized, just hidden. This shows the materialization surface is not only the history RPC: the adopt path (boot-time and on-demand open) materializes just as eagerly.

---

2. Root Cause Analysis

2.0 The full cold-load path (current master)

session.history (tail page, maxMessages=50)
  └─ historySourceFor()                          api-proxy.ts:1474-1479 (cold → inspectServable)
       └─ inspectApiRemoteSession()              packages/api/remotes/src/agent-lookup.ts:94-111
            ├─ persistence.list()                enumerate all sessions (header-only reads)
            └─ persistence.inspect(sessionId)    coordinator.inspect → prepareCore
                 ├─ backend.loadStored(id)       FULL read: whole file / all event rows
                 ├─ adoptStoredEvents()          per-event legacy migration + snapshot + deep-freeze
                 └─ sessions.prepare(id, seed)   per-event envelope validation + surface validateNext
  └─ historyPage() → paginate(events, maxMessages)   api-proxy.ts:228-254 — slicing AFTER full materialization

Key fact: pagination is applied after the full event array exists. maxMessages limits the returned payload only — it does not bound any I/O, decompression, parsing, validation, or materialization.

2.1 Root cause R1 — Full materialization before pagination

• history RPC → historySourceFor (packages/host/apiproxy/src/api-proxy.ts:2154-2170 → 1474-1479). For a detached (cold) session this goes to inspectApiRemoteSession (packages/api/remotes/src/agent-lookup.ts:94-111), which calls persistence.list() (full enumeration) and persistence.inspect(sessionId).
• inspect → prepareCore (packages/session/session-persistence/src/coordinator.ts:892-931): backend.loadStored(id) loads the entire stored log; adoptStoredEvents (coordinator.ts:560-573) migrates and deep-freezes every event; sessions.prepare(id, { seed: balanced }) rebuilds the Session event-by-event (packages/core/session/src/index.ts:495-548).
• Only afterwards does historyPage() apply paginate(events, beforeSeq, maxMessages) (api-proxy.ts:228-254, 745-761).

Evidence that maxMessages does not bound work: the client requests history immediately on open (client/runtime/src/client/sessions/session.ts:618-648) with PAGE_MESSAGES = 50, yet the host still reads, decodes, parses, validates and materializes all 444K+ events before slicing 50 messages out.

2.2 Root cause R2 — JSONL physical read: whole file + all frames (no seek)

• readStableFile (packages/session/session-persistence-jsonl/src/index.ts:292-304): stat → readFile(whole file) → stat, re-reading on revision change.
• readZstdPrefix (index.ts:348-419): scanZstdFrames scans frame boundaries (header-only, no decompression) then decodes every frame; SessionLogScanner (packages/session/session-persistence-jsonl/src/format.ts:272-378) JSON.parses every line and expands packed chunk rows (chunk-rows.ts:293-328).
• The only yield point is a cooperative scheduler.yield() every 500 ms (index.ts:374-378) — the decode block itself is synchronous on the main thread.
• JSONL has no seek — this is why "pagination does not bound I/O" is a storage-layer fact, not a client/HTTP artifact. loadStoredFrom(fromSeq) is not implemented for JSONL (index.ts:196-197 documents "JSONL is sequential media"); the coordinator's readFromCore (coordinator.ts:841-870) therefore falls back to readStoredPrefix + whole.events.slice(fromSeq) — i.e. full materialization, then slice (coordinator.ts:867-869). Any fromSeq>0 read on JSONL pays the full read/decode/parse cost.
• SQLite does implement loadStoredFrom (packages/session/session-persistence-sqlite/src/store.ts:160-170, bounded suffix read via physicalSpanFrom) — but cold inspect still calls the full loadStored (store.ts:134-151, full-table select-events), so even the SQLite backend fully materializes on cold open; and when a suffix contains legacy shapes, readFromCore (coordinator.ts:859-861) falls back to a full readStoredPrefix anyway.

2.3 Root cause R3 — Per-event rebuild: validation + deep copy + O(n²) surface folding

• Event rebuild (packages/core/session/src/index.ts:508-548): per seed event — snapshotJsonValue (serialize-and-validate), assertSessionEventEnvelope, surfaceManager.validateNext; plus freezeRestoredObject deep-freezing the whole JSON tree iteratively (index.ts:197-210). coordinator.ts:545-557 additionally structuredClones each stored event on the inspect path.
• O(n²) surface folding: replacementRange (packages/core/session/src/surface.ts:337) uses state.nodes.indexOf(op.start) / indexOf(op.end) — a linear scan of the node array per replacement. Sessions with compaction carry many replacements → foldSurface (surface.ts:387-395) becomes O(n²). With ~20K nodes and several indexOf passes, that is hundreds of millions of comparisons (hundreds of ms to seconds).

2.4 Root cause R4 — Projection full re-fold on every history tail page (cache bypass)

• The detached history path computes projections via detachedProjectionsFor → registry.restore({}, events, 0) (api-proxy.ts:810-818): with no checkpoint rows, every registered cell def.init() + re-applies all events — O(cells × n).
• The projection cache coldSnapshot (packages/session/session-projection-cache/src/index.ts:166-196) supports incremental restore from a floor seq — but the history path never uses it; the cache only serves session.list cold rows (api-proxy.ts:798-808). Cold history = full materialization + full projection re-fold (double O(n)).

2.5 Root cause R5 — Amplifiers: 5-slot LRU, no negative cache, main-thread blocking

• DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5 (coordinator.ts:27); a large session evicted from the LRU is re-read in full on reopen (revision re-check via stat).
• No negative cache for corrupt artifacts: repeated UI retries rescan the same file (each retry = full read + decode + parse until the gap is hit).
• All of the above runs synchronously on the Node.js main thread → a single large or corrupt cold session stalls every request on the same process. This is exactly [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550's incident: GET / timed out, CLOSE_WAIT pile-up, 0.95 CPU-s per 2 s wall time.
• The materialization surface is wider than the history RPC. The adopt path (boot-time and on-demand open) materializes just as eagerly: 7889545's pure-scale reproduction (15 valid sessions, no corruption) hit ~3 GB heap with ~60 % CPU in structuredClone and 21.6M live objects, with no client interaction — see §1.4. archivedSessionIds does not reduce this (hidden ≠ unmaterialized).

2.6 What is NOT the bottleneck (client-side counter-evidence)

• The client never renders the whole session at once: first open requests a tail page of 50 messages (session.ts:618-648, PAGE_MESSAGES = 50 at session.ts:32); scrolling triggers loadOlder 50 messages per page (session.ts:380-414). The conversation assembler rebuilds incrementally per window (conversation-assembler.ts:223-248).
• The repo's own benchmark validates the model: apps/web/tests/complex-history.perf.ts — a 500-turn session opens showing only the first ~24 turns, and expanding page-by-page to all 500 turns (2,100 trajectory rows) is the heaviest measured scenario. First-open latency is dominated by the cold host-side inspect, not by UI rendering.
• One genuine client-side gap: ChatView has no virtualization (ChatView.tsx:432-447 order.map renders the whole window; the trajectory view does use @tanstack/react-virtual). This matters only after thousands of messages are expanded, not on first open.

2.7 Complexity model (summary)

Step	Location	Complexity
Cold inspect: file read	jsonl/index.ts:292-304	O(b) bytes
Cold inspect: decode all frames	jsonl/index.ts:348-419	O(b)
Cold inspect: JSON.parse per line	format.ts:347-377	O(storage rows) ≤ n (packed)
Cold inspect: packed-chunk expansion	chunk-rows.ts:293-328	O(n) expanded events
Event rebuild + deep-freeze	coordinator.ts:560-573; core/session/index.ts:495-548	O(n × event size)
Surface fold (compaction)	core/session/src/surface.ts:337, 387-395	O(n²) worst case
Projection re-fold (detached)	api-proxy.ts:810-818; projection/index.ts:420-454	O(cells × n)
Session list	api-proxy.ts:1666-1720; jsonl/index.ts:472-509	O(session count)
History page host-side	api-proxy.ts:228-254, 745-761	O(page events), page ≈ 50 messages
Transport	client/rpc.ts:26-53	O(page payload bytes)
Client window rebuild	conversation-assembler.ts:168-248	O(window events × definitions)
Client render	ChatView.tsx:432-447	O(window nodes)

---

3. Quantified impact (measured & estimated)

3.1 Local measurement (T2, Node v22.22.3, private zstd decoder)

Real largest session log on this machine (8.84 MB compressed / 20.2 MB JSON / 27,698 events / 24,005 zstd frames, avg ~369 B per frame):

• One cold read — readFile + frame scan + decode + per-line JSON.parse + snapshotSessionEvent — measures ~430 ms (private decoder) / ~880 ms (public one-shot fallback).
• Bottleneck breakdown (private decoder):

Stage	Time	Note
readFile	~3 ms	whole file into memory
zstd frame scan + decode	~78 ms	24,005 frames decoded one by one
JSON.parse per line	~200 ms	20.2 MB JSON
snapshotSessionEvent	~148 ms	structuredClone + deep-freeze of 27,698 events
paginate + views	~2 ms	tail 50 messages only — everything before was full
projection full re-fold	~10 ms	repeated on every cold read

• Synthetic 50K-event log: full parse ~340 ms; full projection fold across 5 typical cells ~7 ms (not dominant, but redundant every cold read). Session-list header-only scan of 412 sessions ~42 ms (secondary).

3.2 Cross-validation with #1550 and the complexity model

• The linear parts scale with event count: T2's 27.7K events → parse 200 ms + snapshot 148 ms ≈ 350 ms; extrapolated to [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550's Session A (461,981 events) ≈ ~5.8 s, plus surface folding (O(n²) with compaction) ≈ 4.6 s → ~10 s total, matching both captain's independent estimate (~9.0 s / ~8.6 s for Sessions A/B) and [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550's observed GET / timeout ≈ 10,185 ms (post-isolation: 243 ms).
• A medium session (~5K messages / 50K events) cold-opens in ~1.5 s on the main thread; the 460K-event session takes ~9 s — during which every other request on the same process stalls.
• Everything expensive is unbounded by page size: only paginate+views (~2 ms) and the tail-page projection depend on the 50-message page; read/decode/parse/snapshot cost is O(whole log).

4. Optimization roadmap (staged, prioritized by cost-effectiveness)

T2 ranked the candidates A–G by payoff/cost; the table maps them onto the staged plan (short / mid / long) together with the community-validated items from #1550 and the fork.

#	Direction	Stage	Expected gain	Evidence
A	Tail index sidecar + JSONL seek — per-session incremental index ({seq, byteOffset, frameIndex}) or append-only sidecar; implement loadStoredFrom on JSONL so readFrom(seq) seeks to the tail frames	short	Cold open 430 ms → <50 ms (decode only last ~1% frames ≈ 1.6 ms); biggest single win	T2 §4.A; coordinator's loadStoredFrom hook already exists (coordinator.ts:841-870)
B	Merge write frames — raise writeBatchMaxDelayMs / batch by event count	short	Frame count 24,005 → hundreds (10–50×); decode stage ~78 ms → single-digit ms	T2 §4.B; avg frame 369 B
C	Detached projections via coldSnapshot — detachedProjectionsFor → coldSnapshot incremental instead of restore({}, events, 0)	short	Repeated tail opens ~10 ms → ~0 ms; avoids full re-read	T2 §4.C; cache already exists (session-projection-cache/index.ts:166-196)
D	On-demand event snapshot — freeze only message sub-objects on the read path instead of full structuredClone per event	short	Save ~150 ms per 50K events	T2 §4.D
E	Session-list header cache — cache header scan, invalidate by mtime	short	412-session list ~42 ms → near 0 after warm	T2 §4.E
0	Adopt fork-validated mechanisms (159c5e4) — cross-process writer lease, ZSTD_DECODE_YIELD_INTERVAL_MS 500→16 ms, revision-keyed readFailures negative cache	short	Root-cause fix for double-writer seq conflicts (#1333/#1452); main thread yields during large decodes; corrupt retries never rescan	T1 §9.4; argszero review: tests pass (2/2 + 152/152 + 81/81), but does not fix first-valid-large-session cold open — combine with A
F	Client skeleton + prefetch — render header from list projections, prefetch recent sessions	mid	Perceived latency hides cold open	T2 §4.F
—	Streaming pagination — scan incrementally, stop at page boundary (no full-array filter)	mid	Per-page cost O(page), not O(n)	captain root-cause-summary
—	Adaptive LRU / size-tiered session cache — keep large sessions longer than 5 slots	mid	Fewer repeated full reads	coordinator.ts:27
—	Isolation at list/inspect time — mark unreadable/oversized sessions in listArtifacts, never enter full-scan path	mid	Blast-radius containment for corrupt sessions (echoes argszero #3; offline variant: dsh-doctor)	#1550; #1518/#1534
G	Default SQLite backend — loadStoredFrom seek already implemented; cold read becomes independent of log size	long	Structural fix; JSONL stays for append-friendly workloads	T2 §4.G; sqlite store.ts:160-171
—	Storage format evolution — sharded logs / separate metadata / indexed formats	long	Seekable by construction	captain root-cause-summary
—	Persisted structured corruption diagnostics per artifact revision under $DSH_HOME/logs (session id, record/frame position, expected/actual seq, stack)	long	Operational debuggability	#1550 suggestion 5

Additional #1550-aligned items folded into the plan: frame-level seq-monotonicity scan for fail-fast corruption detection (cheap scan instead of full decode; argszero #2), worker-thread decode/replay for main-thread responsiveness (#1550 suggestion 4, complements 0/yield-16ms).

5. Expected impact

• A (tail index + seek): cold open of the 8.84 MB / 27.7K-event session drops from ~430 ms to < 50 ms; a 460K-event session from ~9 s to < 100 ms (decode only the tail ~1% of frames). This removes the "first valid large session" gap that the fork patch left open.
• B (frame merge): decode stage ~78 ms → single-digit ms (10–50× fewer frames); smaller yield-slice pressure on the main thread.
• C (projection cache): repeated tail-page opens ~10 ms → ~0 ms, and no full re-read for projections.
• D (on-demand snapshot): ~150 ms saved per 50K events on the cold path.
• E (list cache): 412-session list ~42 ms → near-zero after warm; less I/O churn at boot.
• 0 (fork mechanisms): corrupt-session retries no longer rescan (revision-keyed negative cache); main thread yields during large decodes (16 ms slices); cross-process writer conflicts eliminated at the root.
• Combined: first-open latency for large sessions drops from seconds to tens of milliseconds, and the main thread is never blocked for more than a bounded slice → the [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550 availability-amplifier scenario (GET / timeout, CLOSE_WAIT pile-up, 3 GB heap) is structurally eliminated.
• Regression shape (argszero): open a large/corrupt cold session and assert inspect/history returns within a bounded number of decoded frames — or fails fast via a cheap frame-level scan; never full materialization.

6. Open questions

1. Is bounded tail-read the right abstraction, or should the persistence layer expose a frame-index + ranged read API first (smaller but still valuable)?
2. Should the projection cache become the single source of truth for detached history, with correctness invariants documented (floor seq, revision binding)?
3. For SQLite, should cold inspect switch from loadStored to loadStoredFrom + suffix replay as the default? (Requires coordinator contract change.)
4. What is the acceptable regression-test shape? (argszero suggested: open large/corrupt cold session, assert inspect/history returns within a bounded number of decoded frames or fails fast via cheap scan — never full materialization.)
5. Should quarantine become first-class (CLI + API), or stay a diagnostic/tooling concern (dsh-doctor)?
6. Sidecar index consistency: how do the tail-index sidecar and the log stay transactionally consistent (same append transaction? fsync ordering? rebuild-on-mismatch strategy for torn tails)?
7. Frame merging vs. write-behind latency: raising writeBatchMaxDelayMs cuts frame count but delays durability/visibility of new events — what bound is acceptable for interactive sessions?
8. Snapshot laziness: is deep immutability (structuredClone + deep-freeze) required by the shared Session contract for attached sessions, or can the read path freeze only what it hands out?

---

Sources: team T1 code-path report (tmp/20260825/team-t1-code-path.md, incl. §9 community cross-check), T2 perf analysis with local measurements (tmp/20260827/perf-analysis.md, bench-.cjs), captain's source notes & quantification (tmp/20260825/captain-notes.md, quantification.md), official discussion #1550 (raw + quotes). Inspected deepseek-ai/deepseek-harness current master 2026-08-25; finalized 2026-08-27. FINAL — ready for posting.*

[Zn-Dk]

Follow-up: a community "bounded cold-history reads" patch already exists — here's how it maps to this roadmap

While checking #1550, I found that @ernel135790 posted a bounded cold-history reads patch (2026-08-23) that implements a large part of this roadmap's short-term items. Worth aligning explicitly so the discussion doesn't fork into parallel proposals:

What the patch covers (vs. roadmap items)

Roadmap item	Patch status
A. Tail index sidecar + JSONL seek	⚠️ Partially — it adds readHistoryWindow + loadStoredWindow (two-pass streaming scan, memory bounded by historyWindowMaxEvents default 100k) but explicitly defers the persistent frame/message index sidecar ("would bound I/O and CPU, but changes the on-disk layout and write path"). So the memory bound is there; the I/O/CPU bound (decode only the tail ~1% frames) is still open.
C. Detached projections via coldSnapshot	✅ Implemented — detached tail projections are now cached-only (sessionProjectionCache.cachedSnapshot), exactly matching our "projection cache bypass" root cause R4 and roadmap item C.
B. Merge write frames	❌ Not addressed (frame count 24k → hundreds remains open).
D. On-demand event snapshot	❌ Not addressed (per-event structuredClone + deep-freeze on the read path remains).
E. Session-list header cache	❌ Not addressed.
0. Fork mechanisms (writer lease / 16ms yield / negative cache)	❌ Orthogonal — the patch is bounded-read only; the writer-corruption family (#1333/#1433/#1452/#1497) still needs the writer-lease + revision negative cache from wellorbetter's fork.
Worker-thread decode	⚠️ Rejected in the patch (cooperative yields chosen instead) — a reasonable call, but it means a single huge decode still occupies the main thread for the duration of the scan (just yielding between frames).

What the patch adds beyond our roadmap

1. SessionHistoryWindowTooLargeError — a single message group whose sourceEventSeqs span more than historyWindowMaxEvents rejects instead of growing unbounded. Good safety valve we didn't call out explicitly.
2. Attached-session pagination fix — pageSurfaceMessages scans the live event array without copying it (our roadmap only discussed cold paths). The attached path had the same full-copy defect, smaller but real.
3. SQLite keyset pagination — message candidates paged via ORDER BY seq DESC LIMIT ?, decoding only the relevant physical span. Cleaner than our "switch cold inspect to loadStoredFrom" idea — it's purpose-built for history pages.

My take

The patch is a solid memory-bound solution for the short term. The remaining gap is exactly roadmap A's second half: without a persistent frame/message index, every cold open still decodes the whole artifact (CPU/IO-bound, just not memory-bound) — which is what makes a 460K-event session take ~9s even after this patch. So the natural next step after adopting (or cherry-picking) this patch is the index sidecar, plus B (frame merging) to shrink the decode surface further.

Would be great to hear from the maintainers whether readHistoryWindow as shaped here is the direction they'd accept upstream — if so, the index sidecar and frame merging can build on top of it rather than competing.

[xiaoshenming]

感谢点名。划一下边界，避免路线图和离线修文件搅在一起：

dsh-session-surgeon 不改 dsh web 的冷启动物化，也替代不了 bounded-history / 尾部索引。它只在官方 loader 已经拒读（seq gap / torn / 缺 message.id）时，dry-run 修那份 session.jsonl.zstd，或 Web 被坏日志卡死时另开 loopback 扫 header。

大会话但 health=ok 的超时，走你们路线图 / #1550 的补丁，不要对文件 --apply。

[Zn-Dk]

Thanks @xiaoshenming for the clear boundary — and for confirming that healthy-but-large sessions belong on the bounded-read path rather than file surgery. That's exactly the split this post intends:

• Corrupt / unreadable artifact → your surgeon (dry-run repair or loopback header scan before the Web server chokes).
• Large but healthy session → the bounded-read roadmap (this post) / [Bug] Cold history loading fully materializes large/corrupt logs and can stall the entire Web server #1550.

One small overlap worth noting: your loopback "scan header first" approach is conceptually the same trick as roadmap item E (session-list header cache) and argszero's "detect corruption at the cheap scan" — scanning metadata before touching the full artifact. If the maintainers adopt a bounded-read API, your surgeon could also reuse readHistoryWindow/header-scan primitives instead of re-implementing frame walking, which would keep both efforts aligned instead of parallel.

Either way, no --apply needed on our side — this is purely an upstream-design discussion. Cheers for the contribution.