magic-agent 1.0.3 → 1.0.49

package/internal/cli/sessionlog.go

@@ -13,8 +13,17 @@ package cli
 //      否则一次 EIO 就把流式变成报错（结果链就是 magic-agent 退 = 插件 SSE 收尾 = 用户界面卡死）。
 //   2. **最多一次重发**：每条事件写一次；不重试，不重读。不重试是因为重写会污染 seq 序列
 //      （历史接口靠 seq 游标），且消息内容重复展示 = 体验差。
-//   3. **session_id 未知前也能暂存**：不同引擎在流的不同位置暴露 session_id（init / assistant / result），
-//      而最早的 thinking / tool_use 事件可能先到。开文件必须 lazy —— 拿到 id 再开。
+//   3. **session_id 未知也先落盘**（2026-10-15 改）：不同引擎在流的不同位置暴露
+//      session_id（init / assistant / result），最早的 thinking / tool_use 可能先到。
+//      此前是「拿到 id 才开文件」，于是三件事一起坏掉：
+//        · id 之前的事件全留在内存 buffer 里（上限 64 条，超了丢）；
+//        · 引擎**整轮都不给 id** 的形态（dsh 的 headless 回退轮）收工时 buffer 直接丢光 ——
+//          `--save-history` 白开，磁盘上一个字节都没有（静默失败）；
+//        · 正在跑的会话在别的客户端眼里「有记录、没内容」：文件还不知道叫什么名字，
+//          `/desk/session/<id>/messages` 读出来永远是空历史。
+//      现在：core 在 beginSession 时就拿到 run_id → 立刻落到 `<run_id>.jsonl`；
+//      引擎的 session_id 到达后**改名**成 `<session_id>.jsonl`（终名，见 renameTo）。
+//      读侧用 session.ResolveLogID 把 run_id 翻成 session_id，两个名字都读得到。
 //
 // 落盘动作走 goroutine + buffered channel：调用方 (onEvent) 只做「塞进 channel 即返回」，
 // IO 慢的副作用不会传到流路径。
@@ -24,8 +33,10 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
@@ -56,9 +67,11 @@ func sessionLogDir() (string, error) {
 //
 // Kind 取自两处，合并成一份词表：
 //   - 引擎事件（internal/agent/stream.go 的 StreamEventKind）：thinking / text /
-//     tool_use / tool_result / ask / turn_end；
+//     tool_use / tool_result / ask / image（助手图片块，Text=data URI）/ turn_end /
+//     notice（过程提示，如 max_tokens 截断）；
 //   - core 自己补的：user（用户提问，见 ask.go runStreamAsk —— 引擎事件里没有它，
-//     但历史缺了它就只剩 agent 单方面说话）、error（失败兜底）。
+//     但历史缺了它就只剩 agent 单方面说话）、command（斜杠命令的开跑/收尾一对，
+//     同在 runStreamAsk 依输入形态合成）、error（失败兜底）。
 //
 // 注意：Thinking 文本可能很大（claude 长思考），Text 可能有工具调用摘要（tool_use），
 // 都直接 JSON 序列化。文件按行追加，断电最坏丢最后一行（不是大问题，流仍在跑）。
@@ -76,14 +89,36 @@ type sessionEvent struct {
 	ToolKind  string            `json:"tool_kind,omitempty"`
 	SessionID string            `json:"session_id,omitempty"`
 	Ask       *agent.AskRequest `json:"ask,omitempty"`
+	/* 状态收敛四元组（2026-10-02）。落盘它们是为了让**历史回放与实时渲染
+	   画出同一种东西**：回放侧不必自己猜「这条消息到哪算完」，
+	   按 (item_id, item_revision) 覆盖即可。缺了它们，历史里每条 text
+	   都只是孤立的增量片段（与实时流同源但无法收敛）。 */
+	ItemID       string `json:"item_id,omitempty"`
+	ItemRevision uint64 `json:"item_revision,omitempty"`
+	Status       string `json:"status,omitempty"`
+	/* Snapshot 是「该 item 到此刻的累积整段」——**只读不写**（2026-10-20）。
+	   写盘时恒为空（见 appendLine）：每条增量都带一份 ⇒ 二次方膨胀
+	   （实测一条会话 1.8GB，95.6% 是它）。
+	   字段保留是为了读**旧档**（2026-10-20 之前写的日志里它是收敛结果）。 */
+	Snapshot string `json:"snapshot,omitempty"`
+	// Error / Reason 异常收尾的原因（仅 turn_failed），与事件流同源。
+	Error  string `json:"error,omitempty"`
+	Reason string `json:"reason,omitempty"`
+	// Attachments 用户提问携带的附件（仅 kind:"user" 有）。引擎事件里没有附件信息
+	// （`image` 事件只对应助手**产出**），所以只有落在这里，历史回放才复原得出
+	// 「那一轮用了哪张图」—— 移动端据此在历史气泡里画出缩略图。
+	Attachments []agent.Attachment `json:"attachments,omitempty"`
 }
 
 // sessionWriter 每条流式调用一个实例；开着就一直 append 到
-// `<dir>/<session_id>.jsonl`，session_id 还没出来时事件先**丢进 buffer**等 id。
+// `<dir>/<session_id>.jsonl` —— session_id 还没出来时先写 `<dir>/<run_id>.jsonl`，
+// 拿到 id 后**改名**（见 write / renameTo）。
 //
-// ⚠️ **不重发**：buffer 等 id 时最多暂存 ~64 条事件；满了就丢（按 round-robin），
-// 并 emit 一行 warning。我们接受这个损失 —— 历史只对「点进去看历史」这件事有用，
-// 极少数早期事件丢了用户察觉不到（call 号还在 SSE 流里）；但「突然不写盘」绝对不行。
+// ⚠️ **不丢内容**（2026-10-15 起）：两道兜底 —— ① 一有 run_id 就先落盘（core 在
+// beginSession 时就有）；② 连 run_id 都没有（登记表开不出来、或纯测试构造）时才进
+// pending buffer（上限 64 条，满了按 ring-buffer 丢并计数）。
+// 曾经只有 ②：引擎整轮不给 id 时整段历史在收工时被丢光，而「正在跑的会话读出来是空的」
+// 是**静默失败** —— 比少几条早期事件糟得多。
 type sessionWriter struct {
 	dir      string
 	runID    uint64
@@ -96,32 +131,76 @@ type sessionWriter struct {
 	file     *os.File
 	w        *bufio.Writer
 	filePath string
+	fileName string        // 当前文件名（不含 .jsonl）；空 = 还没开文件
 	overflow atomic.Uint64 // 被 ring-buffer 丢弃的事件计数（诊断用）
+	// poke 让主 goroutine 催一句「现在按最新名字把文件开出来 / 改名」，
+	// 不必等下一个事件 —— 否则「先 push 了 user 事件、随后才拿到 run_id」
+	// 或「id 刚到手就进入长时间静默」这两种情况下，文件会迟迟不出现。
+	poke chan struct{}
+	// flushTick 周期性把缓冲刷到磁盘（1s）。bufio 要攒满 32KB 才写，
+	// 而「正在跑的会话」必须能被**别的客户端**读到（它们直接读文件）——
+	// 内容一直躺在内存里，读出来就是空历史（静默失败）。见 flush。
+	flushTick *time.Ticker
 
 	// sessionID 跨 goroutine 共享：CLI 的 OnSessionID 写入（流路径），
 	// sw.write 读（写盘 goroutine）。atomic.Pointer[string] 保证可见性。
 	sessionID atomic.Pointer[string]
+	// runIDStr 本次运行的**登记 id**（session.Handle.RunID()），由 CLI 在 beginSession
+	// 之后经 setRunID 写入、写盘 goroutine 读 —— 与 sessionID 同一套可见性做法。
+	runIDStr atomic.Pointer[string]
 }
 
 // newSessionWriter 创建并启动一个 sessionWriter（仅包内测试用，单测不依赖 onSessionID）。
 func newSessionWriter(dir string, runID uint64) *sessionWriter {
 	sw := &sessionWriter{
-		dir:   dir,
-		runID: runID,
-		stop:  make(chan struct{}),
-		done:  make(chan struct{}),
-		in:    make(chan sessionEvent, 128),
+		dir:       dir,
+		runID:     runID,
+		stop:      make(chan struct{}),
+		done:      make(chan struct{}),
+		in:        make(chan sessionEvent, 128),
+		poke:      make(chan struct{}, 1),
+		flushTick: time.NewTicker(time.Second),
 	}
 	initID := ""
 	sw.sessionID.Store(&initID)
+	sw.runIDStr.Store(&initID)
 	go sw.loop()
 	return sw
 }
 
 // setSessionID 由 CLI 端 OnSessionID 调用 —— 流里见到 session_id 就推给 writer。
+// 顺带催一次写盘：名字从 run_id 换成 session_id 要**当场**发生，不能等下一个事件
+// （id 到手后可能长时间没事件，那段时间里按 session_id 去读会读到空文件）。
+//
+// ⚠️ 空 id 直接跳过（与 setRunID 同一口径）：写进空 session_id，name() 就退回 run_id ——
+// 等于把已经改成终名的文件**又改回** run_id。而「只有前几条事件带 id」的引擎形态很常见
+// （CLI 的 onEvent 兜底就是逐事件推的，见 ask.go），这个守卫是必须的。
 func (sw *sessionWriter) setSessionID(id string) {
-	s := id
+	s := strings.TrimSpace(id)
+	if s == "" {
+		return
+	}
 	sw.sessionID.Store(&s)
+	sw.pokeWriter()
+}
+
+// setRunID 由 CLI 在 beginSession 之后调用：把本次运行的登记 id 交给 writer。
+// 有了它，引擎还没吐 session_id 时日志就先落在 <run_id>.jsonl（见 write 的说明）。
+func (sw *sessionWriter) setRunID(id string) {
+	s := strings.TrimSpace(id)
+	if s == "" {
+		return
+	}
+	sw.runIDStr.Store(&s)
+	sw.pokeWriter()
+}
+
+// pokeWriter 非阻塞地催一句写盘 goroutine（poke 满/未初始化都直接返回）。
+func (sw *sessionWriter) pokeWriter() {
+	select {
+	case sw.poke <- struct{}{}:
+	default:
+	}
 }
 
 // currentSessionID 在 sw.write 里读；不可与 OnSessionID 配对交换字段（race）。
@@ -129,6 +208,19 @@ func (sw *sessionWriter) currentSessionID() string {
 	return *sw.sessionID.Load()
 }
 
+// currentRunID 本次运行的登记 id（空 = 登记表没开出来）。
+func (sw *sessionWriter) currentRunID() string {
+	return *sw.runIDStr.Load()
+}
+
+// name 当前该用的日志名：优先 session_id（续接时一开始就是终名），否则退回 run_id。
+func (sw *sessionWriter) name() string {
+	if id := sw.currentSessionID(); id != "" {
+		return id
+	}
+	return sw.currentRunID()
+}
+
 // newSessionWriterAuto 解析目录 + 起 writer。
 // 解析失败：返回 nil + error，让调用方决定「不写盘继续」还是「中断流」。
 func newSessionWriterAuto(dirFn func() (string, error)) (*sessionWriter, error) {
@@ -176,11 +268,12 @@ func (sw *sessionWriter) close() {
 
 // loop 是单 goroutine 的 IO 循环 —— 拉事件、拿会话 id、写盘、刷文件。
 //
-// 顺序的简化：把「拿 session_id」和「打开文件」放在事件处理里。第一条事件没 id
-// → 进 pending；有 id 之后**只**开一次文件并把 pending 也写进去。之后每条事件
-// 直接落盘，不再有"没 id"的问题。
+// 顺序的简化：把「拿 session_id / run_id」和「打开 / 改名文件」都放进 ensureFile，
+// 每次写之前调一次。于是三种时序都对：一开始就知道 id（续接，直接终名）、
+// 先有 run_id 后有 id（改名）、连 run_id 都没有（暂存等名字）。
 func (sw *sessionWriter) loop() {
 	defer close(sw.done)
+	defer sw.flushTick.Stop()
 	defer func() {
 		if sw.w != nil {
 			_ = sw.w.Flush()
@@ -199,34 +292,68 @@ func (sw *sessionWriter) loop() {
 					return
 				}
 			}
+		case <-sw.poke:
+			// 只是「名字变了，把文件开出来 / 改名」——不写事件。
+			sw.ensureFile()
+		case <-sw.flushTick.C:
+			sw.flush()
 		case ev := <-sw.in:
 			sw.write(ev)
 		}
 	}
 }
 
-// write 是单条事件的落盘。id 还没出现就暂存；id 出现后开文件并把暂存的也写进去。
+// flush 把缓冲区写进内核（**不** fsync）：让「还没收尾的会话」在磁盘上就看得见。
+//
+// 为什么必须有（2026-10-15）：bufio 要攒满 32KB 才落盘，而正在跑的会话会被**别的
+// 客户端**直接读文件（/desk/session/<id>/messages、--session-log）—— 内容全在内存里
+// 时它们读出来是空历史，看起来像「这条会话没有内容」。1s 一次 write(2) 的代价可忽略，
+// 也远小于「每行 fsync」。
+func (sw *sessionWriter) flush() {
+	if sw.w != nil {
+		_ = sw.w.Flush()
+	}
+}
+
+// write 是单条事件的落盘：先保证文件是最新名字的那个，再追加一行。
 func (sw *sessionWriter) write(ev sessionEvent) {
-	// 1. 拿到当前 session_id（来自 accumulator；流早期可能为空）。
+	// 1. 拿当前 session_id（每个引擎暴露它的位置不同，早期可能为空）。
 	if ev.SessionID == "" {
 		ev.SessionID = sw.currentSessionID()
 	}
-	if ev.SessionID == "" {
-		// 还没 id：进 pending，等后续事件触发「打开文件」的动作。
-		sw.mu.Lock()
-		if len(sw.pending) < 64 {
-			sw.pending = append(sw.pending, ev)
-		} else {
-			sw.overflow.Add(1)
-		}
-		sw.mu.Unlock()
+	sw.ensureFile()
+	if sw.file == nil {
+		// 连名字都没有（登记表开不出来、或纯测试构造）：暂存等名字。
+		sw.buffer(ev)
 		return
 	}
-	// 2. 还没开文件：开 + 刷 pending。文件路径 = dir/<session_id>.jsonl。
+	sw.appendLine(ev)
+}
+
+// buffer 暂存一条「还没有文件名」的事件；只有 pending 也满时才丢（并计数）。
+func (sw *sessionWriter) buffer(ev sessionEvent) {
+	sw.mu.Lock()
+	if len(sw.pending) < 64 {
+		sw.pending = append(sw.pending, ev)
+	} else {
+		sw.overflow.Add(1)
+	}
+	sw.mu.Unlock()
+}
+
+// ensureFile 保证「该写的文件已打开、且用的是当前该用的名字」：
+//
+//	· 还没开 → 有名字就开，并把暂存的早期事件按序补写（首次不丢）；
+//	· 已经开着但名字过期（期间拿到了 session_id）→ 改名到终名。
+func (sw *sessionWriter) ensureFile() {
 	if sw.file == nil {
-		if err := sw.openFile(ev.SessionID); err != nil {
+		name := sw.name()
+		if name == "" {
+			return
+		}
+		if err := sw.openFile(name); err != nil {
 			// 开不开得出来（磁盘满 / 权限）：本条丢弃，**不抛错**。下一条再来还试。
-			fmt.Fprintf(os.Stderr, "magic-agent: 持久化会话失败（%s）：%v（流继续）\n", ev.SessionID, err)
+			fmt.Fprintf(os.Stderr, "magic-agent: 持久化会话失败（%s）：%v（流继续）\n", name, err)
 			return
 		}
 		// pending 也写进去（首次不丢早期事件）。
@@ -237,26 +364,160 @@ func (sw *sessionWriter) write(ev sessionEvent) {
 		for _, pev := range pend {
 			sw.appendLine(pev)
 		}
+		return
+	}
+	if want := sw.name(); want != "" && want != sw.fileName {
+		sw.renameTo(want)
 	}
-	sw.appendLine(ev)
 }
 
-// openFile 在 <dir> 下创建/追加 <session_id>.jsonl。权限 0600（与 session 登记表一致）。
+// renameTo 把日志文件改名到终名（`<run_id>.jsonl` → `<session_id>.jsonl`）。
+//
+// 关旧文件 → 改名 → 按新名重新 append 打开；每一步失败都只警告、流继续。
+// ⚠️ 终名文件**已经存在**时不能直接 os.Rename —— Unix 下它会静默覆盖，
+// 等于把那条会话已有的历史删掉（续接 / 重跑同一会话时会撞上）。
+// 这种情况改为把内容追加合并进去，再删掉临时名。
+func (sw *sessionWriter) renameTo(name string) {
+	oldPath, newPath := sw.filePath, filepath.Join(sw.dir, name+".jsonl")
+	if sw.w != nil {
+		_ = sw.w.Flush()
+	}
+	if sw.file != nil {
+		_ = sw.file.Close()
+	}
+	sw.file, sw.w, sw.filePath, sw.fileName = nil, nil, "", ""
+	if _, err := os.Stat(newPath); err == nil {
+		appendFileInto(newPath, oldPath)
+	} else if err := os.Rename(oldPath, newPath); err != nil {
+		fmt.Fprintf(os.Stderr, "magic-agent: 会话日志改名失败（%s → %s）：%v（流继续）\n", oldPath, newPath, err)
+	}
+	if err := sw.openFile(name); err != nil {
+		fmt.Fprintf(os.Stderr, "magic-agent: 改名后重新打开会话日志失败（%s）：%v（流继续）\n", newPath, err)
+	}
+}
+
+// appendFileInto 把 src 的内容追加到 dst 末尾，然后删掉 src。
+// 尽力而为：失败（含 dst 打不开）只警告，不改调用方的控制流。
+func appendFileInto(dst, src string) {
+	in, err := os.Open(src)
+	if err != nil {
+		return
+	}
+	defer in.Close()
+	out, err := os.OpenFile(dst, os.O_WRONLY|os.O_APPEND, 0o600)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "magic-agent: 会话日志合并失败（打不开 %s）：%v\n", dst, err)
+		return
+	}
+	defer out.Close()
+	if _, err := io.Copy(out, in); err != nil {
+		fmt.Fprintf(os.Stderr, "magic-agent: 会话日志合并失败（%s → %s）：%v\n", src, dst, err)
+		return
+	}
+	_ = os.Remove(src)
+}
+
+// openFile 在 <dir> 下创建/追加 <name>.jsonl。权限 0600（与 session 登记表一致）。
 //
 // ⚠️ 用 append 模式 + 0600：不截断已有文件（续接同一会话不会重复第一条事件），
 // 权限只有同用户能读 —— 跨用户读自己用 read-only 调用就好了。
-func (sw *sessionWriter) openFile(id string) error {
-	sw.filePath = filepath.Join(sw.dir, id+".jsonl")
+//
+// ⚠️ **seq 要接在文件末尾**（2026-10-16）：这个文件是**跨轮追加**的（同一会话每轮一次
+// 调用 = 一个新进程 = 一个新 writer），而 seq 原先只是「本进程内的行号」，每轮从 1 重来。
+// 于是同一个文件里会出现多条 `seq=1`：
+//
+//	· 客户端回放按 seq 去重（防重复投递）→ 第二轮起的事件被当成重复帧丢掉，
+//	  界面上**只显示第一轮**（移动端实测报障）；
+//	· `--session-log --after <seq>` 的增量续读游标同时失去意义。
+//
+// 所以打开时先把计数器接到文件里已有的最大 seq 之后。
+func (sw *sessionWriter) openFile(name string) error {
+	sw.filePath = filepath.Join(sw.dir, name+".jsonl")
 	f, err := os.OpenFile(sw.filePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
 	if err != nil {
 		return err
 	}
 	sw.file = f
-	sw.w = bufio.NewWriterSize(f, 32*1024) // 32KB 缓冲；写完一行 Flush，由 timer 兜底
+	sw.fileName = name
+	sw.w = bufio.NewWriterSize(f, 32*1024) // 32KB 缓冲；另有 1s 的定时 flush 兜底（见 flush）
+	if n := readMaxSeq(sw.filePath); n > 0 {
+		sw.seq.Store(n)
+	}
 	return nil
 }
 
+// logSeqWindow 往回读的窗口：与文件大小无关地拿到末尾的 seq（正常一条事件远小于它）。
+const logSeqWindow = 1 << 20
+
+// readMaxSeq 读日志文件里**已落盘的最大 seq**（给新 writer 接号用，见 openFile）。
+//
+// 先只看尾部一个窗口；窗口里没有完整行时（例如上一轮最后一条是十几 MB 的 result）
+// 退回整文件扫描。任何失败都返回 0（退化成「从 1 开始」，与旧行为一致，不影响写盘）。
+func readMaxSeq(path string) uint64 {
+	f, err := os.Open(path)
+	if err != nil {
+		return 0
+	}
+	defer f.Close()
+	st, err := f.Stat()
+	if err != nil || st.Size() == 0 {
+		return 0
+	}
+	start := st.Size() - logSeqWindow
+	if start < 0 {
+		start = 0
+	}
+	buf := make([]byte, st.Size()-start)
+	if _, err := f.ReadAt(buf, start); err == nil {
+		if n := lastSeqIn(buf); n > 0 {
+			return n
+		}
+	}
+	// 兜底：整文件扫一遍（窗口里没有可解析的行时才走到这里）。
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return 0
+	}
+	var max uint64
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
+	for sc.Scan() {
+		if n := lastSeqIn(sc.Bytes()); n > max {
+			max = n
+		}
+	}
+	return max
+}
+
+// lastSeqIn 从一段（可能是多行的）字节里找**最后一条**能解析出行号的 JSON。
+// 末尾常是写了一半的行（进程被杀），解析失败跳过即可。
+func lastSeqIn(b []byte) uint64 {
+	lines := strings.Split(string(b), "\n")
+	for i := len(lines) - 1; i >= 0; i-- {
+		line := strings.TrimSpace(lines[i])
+		if line == "" || line[0] != '{' {
+			continue
+		}
+		var ev sessionEvent
+		if json.Unmarshal([]byte(line), &ev) == nil && ev.Seq > 0 {
+			return ev.Seq
+		}
+	}
+	return 0
+}
+
 // appendLine 写一行 JSON。错（写满 / 设备断开）只 log、不 panic、不影响流路径。
+//
+// ⚠️ **落盘不写 snapshot**（2026-10-20）：snapshot 是「该 item 到此刻的累积整段」，
+// 每条增量事件都带一份 ⇒ 长会话二次方膨胀。实测一条会话 18.6 万条事件、
+// 思考流被切成 5799 个碎片：日志 1.8GB，其中 1.83GB（95.6%）是 snapshot，
+// 真正的增量正文只有 16MB。
+//
+// 为什么可以不留：回放侧只用增量 `text` 自己拼
+// （client-ui/shared/conv/09-stream-apply.js 的 appendThinking / appendText），
+// 全仓没有任何消费方读**落盘**的事件级 snapshot。实时流（--stream 的 NDJSON）
+// 仍然照旧带 snapshot —— 那是「按 item 覆盖」的多端同步需要的，与存档是两回事。
+//
+// ⚠️ 字段本身保留（读旧档要认，见 sessionEventFromJSON）：只是不再**写**。
 func (sw *sessionWriter) appendLine(ev sessionEvent) {
 	ev.Seq = sw.seq.Add(1)
 	if ev.At == "" {
@@ -265,6 +526,8 @@ func (sw *sessionWriter) appendLine(ev sessionEvent) {
 	if ev.SessionID == "" {
 		ev.SessionID = sw.currentSessionID()
 	}
+	// 见函数头：累积快照不落盘（只留增量 text + item 收敛三元组）。
+	ev.Snapshot = ""
 	b, err := json.Marshal(ev)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "magic-agent: 会话事件序列化失败：%v（流继续）\n", err)
@@ -275,8 +538,8 @@ func (sw *sessionWriter) appendLine(ev sessionEvent) {
 		fmt.Fprintf(os.Stderr, "magic-agent: 写会话失败：%v（流继续）\n", err)
 		return
 	}
-	// 不每行都 Flush：bufio 攒一批，close 时一次性刷。代价：断电最坏丢一批；
-	// 流路径完全不受影响。disk 也减少 90%+ 的 fsync。
+	// 不每行都 Flush：bufio 攒一批，另有 1s 的定时 flush（见 flush）与收尾的整批刷。
+	// 代价：断电最坏丢一小批；流路径完全不受影响。disk 也减少 90%+ 的 fsync。
 }
 
 // sessionEventFromJSON 把 jsonl 的一行解析成 sessionEvent。
@@ -290,6 +553,23 @@ func sessionEventFromJSON(line []byte) (sessionEvent, error) {
 	return ev, nil
 }
 
+// stripSnapshots 清掉输出里的 snapshot（--session-log-lean）。
+//
+// 为什么可以清：snapshot 是**该 item 到此刻的累积整段**，每条增量事件都带一份，
+// 于是长会话的存档是二次方膨胀（实测一条会话 9.4 万条 thinking 事件 = 283MB 快照，
+// 整份日志 338MB，读一次要 3.7s、序列化出来 354MB）。
+// 而回放侧只用增量 text 自己拼（client-ui/shared/conv/09-stream-apply.js），
+// 全仓没有任何消费方读事件级 snapshot —— 裁掉它不影响画面。
+//
+// ⚠️ 2026-10-20 起**写盘就不写 snapshot 了**（见 appendLine）—— 本函数仍要留着：
+// 磁盘上还有 2026-10-20 之前写的旧档（带累积快照），读它们时得裁，
+// 否则一次 --session-log 就能把几百 MB 灌进内存。
+func stripSnapshots(evs []sessionEvent) {
+	for i := range evs {
+		evs[i].Snapshot = ""
+	}
+}
+
 // ReadSessionLog 读整个 jsonl 到 []sessionEvent，调用方拿去做 UI 渲染或 diff。
 //
 // 顺序：seq 升序；空文件返回 nil。损坏行跳过（warn 一行）—— 历史不能 100% 保证，
@@ -321,5 +601,72 @@ func ReadSessionLogAfter(dir, sessionID string, after uint64) ([]sessionEvent, u
 		func(e sessionEvent) uint64 { return e.Seq }, sessionEventFromJSON)
 }
 
+// ReadSessionLogLean / ReadSessionLogAfterLean 是上面两条的 lean 版：在**解码前**
+// 摘掉 snapshot（见 session.ReadSessionLogLean）。
+//
+// 为什么 CLI 也走这条：`--session-log-lean` 原本是「先全量解析再清空字段」，
+// 283MB 的累积串照样逐条分配 + 反转义（实测读一次 3.7s）。既然输出里本来就不要，
+// 就不该先把它造出来。输出与「先读后删」逐字段一致。
+func ReadSessionLogLean(dir, sessionID string) ([]sessionEvent, error) {
+	if dir == "" {
+		var err error
+		dir, err = sessionLogDir()
+		if err != nil {
+			return nil, err
+		}
+	}
+	return session.ReadSessionLogLean(dir, sessionID, sessionEventFromJSON)
+}
+
+func ReadSessionLogAfterLean(dir, sessionID string, after uint64) ([]sessionEvent, uint64, error) {
+	if dir == "" {
+		var err error
+		dir, err = sessionLogDir()
+		if err != nil {
+			return nil, 0, err
+		}
+	}
+	return session.ReadSessionLogAfterLean(dir, sessionID, after,
+		func(e sessionEvent) uint64 { return e.Seq }, sessionEventFromJSON)
+}
+
+// ReadSessionLogBefore / ReadSessionLogBeforeLean 反向分页读「从文件尾跳过 skip 条后的
+// 一页」（向上翻历史用）。返回 (事件, 下一页游标, 是否还有更早)。
+//
+// ⚠️ 游标是**跳过条数**而非 seq：同一会话每次续跑都是新进程，旧版 writer 的 seq 每轮
+// 从 1 重来，拿 seq 当全局游标跨不过 run 边界（见 session.ReadSessionLogBefore）。
+// 下一页游标由 core 算（含坏行与被页头对齐裁掉的条数），调用方不要自己加。
+//
+// 页头对齐到轮次起点 user：客户端按轮渲染，页头落在轮次中间会让思考/正文各半截。
+//
+// dir 传空 = 用默认历史目录（与 ReadSessionLog 同一口径）。
+func ReadSessionLogBefore(dir, sessionID string, skip uint64, limit int) ([]sessionEvent, uint64, bool, error) {
+	if dir == "" {
+		var err error
+		dir, err = sessionLogDir()
+		if err != nil {
+			return nil, 0, false, err
+		}
+	}
+	return session.ReadSessionLogBefore(dir, sessionID, skip, limit, isTurnStart, sessionEventFromJSON)
+}
+
+func ReadSessionLogBeforeLean(dir, sessionID string, skip uint64, limit int) ([]sessionEvent, uint64, bool, error) {
+	if dir == "" {
+		var err error
+		dir, err = sessionLogDir()
+		if err != nil {
+			return nil, 0, false, err
+		}
+	}
+	return session.ReadSessionLogBeforeLean(dir, sessionID, skip, limit, isTurnStart, sessionEventFromJSON)
+}
+
+// isTurnStart 判一条事件是不是「一轮对话的起点」。历史里只有用户提问是这个角色
+// （引擎事件流里没有 user，由 core 在 runStreamAsk 里补写，见 sessionEvent 的注释）。
+func isTurnStart(ev sessionEvent) bool {
+	return ev.Kind == "user"
+}
+
 // errClosed 表示 writer 已关。push 收到这个就吞掉 —— 不该发生，但保险。
 var errClosed = errors.New("session writer closed")