From 40fd9c23952057cab8fab4718e463adf63ba010f Mon Sep 17 00:00:00 2001
From: svtter <svtter@qq.com>
Date: Fri, 31 Jul 2026 14:10:56 +0800
Subject: [PATCH 1/5] feat(version-chain): HTML content diff between adjacent
 versions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

在版本链基础上补齐 HTML 行级 diff——补全"v2 到底改了什么"这个最直接的问。
用户在预览页版本时间线侧栏点"Show HTML diff"即可看到相邻版本的红绿行。

算法层 (internal/session/htmldiff.go, 纯函数无依赖)
- LCS 动态规划, DiffLines 输出 LineOp{Kind: Equal|Add|Delete, Text, OldNo, NewNo}
- 修改 = 先 delete 后 add (符合 unified diff 习惯)
- MaxDiffLines=10000 保护: 超阈值返回跳过哨兵, 不让 O(n*m) DP 拖垮请求
- SplitLines 去尾空行, Summarize 计数

数据层 (internal/session/version.go)
- DiffSessionHTML(fromSID, toSID): store.Get 两份 -> os.ReadFile 离盘 diff
- 项目首个读 session 内容进内存的代码, 沿用 store.Get + StoredEntryFile 模式
- 文件缺失降级为空内容而非报错 (老 session 无文件)

服务端 (internal/server/server.go)
- GET /api/sessions/{id}/diff?from=vN&to=vM: {id} 是链上任意 session
- 返回 {fromVersion, toVersion, lines:[{kind,text,oldNo,newNo}], summary:{added,removed}}
- 跨链/越界/from==to/缺参数 -> 400; 不存在/软删 -> 404

预览页注入 (internal/live/inject.go)
- versionDrawer 每个 (有前驱的) 版本项加 "Show HTML diff" 按钮
- 点击懒加载 diff 接口, 红绿行内联展开
- 连续 equal 行折叠为 "⋯ N unchanged ⋯", 只保留改动行
- 前驱解析兼容软删空洞 (v1,v3 -> v3 diff vs v1)
- 按钮旁显示 +a −b 摘要, 再点折叠

约束
- 不引入任何新依赖 (LCS 手写 ~60 行, 正面回应 version-chain Non-Goals 的"无 diff 库")
- 不修改任何 DB schema (diff 纯计算, 结果不入库)
- 现有 GET /chain 响应逐字段不变 (diff 走独立按需接口)
- 老 session 文件缺失降级为空 diff

OpenSpec: openspec/changes/html-content-diff/ (D19-D23, 修改 version-chain capability)

测试: go test ./... 全绿 (新增 ~30 个), go vet 无警告,
openspec validate 通过, 端到端冒烟通过 (增删改行正确识别 + 预览页注入)
---
 internal/live/inject.go                       | 108 +++++++-
 internal/server/server.go                     | 149 +++++++++++
 internal/server/server_test.go                | 222 ++++++++++++++++
 internal/session/htmldiff.go                  | 151 +++++++++++
 internal/session/htmldiff_test.go             | 250 ++++++++++++++++++
 internal/session/version.go                   |  57 ++++
 internal/session/version_test.go              | 165 ++++++++++++
 .../changes/html-content-diff/.openspec.yaml  |   2 +
 openspec/changes/html-content-diff/design.md  |  77 ++++++
 .../changes/html-content-diff/proposal.md     |  33 +++
 .../specs/version-chain/spec.md               |  79 ++++++
 openspec/changes/html-content-diff/tasks.md   |  35 +++
 12 files changed, 1326 insertions(+), 2 deletions(-)
 create mode 100644 internal/session/htmldiff.go
 create mode 100644 internal/session/htmldiff_test.go
 create mode 100644 openspec/changes/html-content-diff/.openspec.yaml
 create mode 100644 openspec/changes/html-content-diff/design.md
 create mode 100644 openspec/changes/html-content-diff/proposal.md
 create mode 100644 openspec/changes/html-content-diff/specs/version-chain/spec.md
 create mode 100644 openspec/changes/html-content-diff/tasks.md

diff --git a/internal/live/inject.go b/internal/live/inject.go
index 13152f2..134b950 100644
--- a/internal/live/inject.go
+++ b/internal/live/inject.go
@@ -170,6 +170,17 @@ const versionDrawerCSS = `<style>
 .sth-version-loading,.sth-version-empty,.sth-version-error{font-size:13px!important;color:#999!important;padding:8px 0!important;margin:0!important}
 .sth-version-error{color:#dc2626!important}
 .sth-version-retry{margin-top:8px!important;padding:6px 12px!important;border:1px solid #d6d1c6!important;border-radius:6px!important;background:#f2efe6!important;cursor:pointer!important;font-size:13px!important}
+.sth-version-diffbtn{margin-top:6px!important;padding:4px 10px!important;border:1px solid #d6d1c6!important;border-radius:6px!important;background:#f2efe6!important;cursor:pointer!important;font-size:12px!important;color:#444!important;font-family:inherit!important}
+.sth-version-diffbtn:hover{background:#e8e2d2!important}
+.sth-version-diffbtn .badge{color:#15803d!important;font-weight:600!important;margin-left:2px!important}
+.sth-version-diffbtn .badge .rm{color:#b91c1c!important}
+.sth-version-htmldiff{margin-top:8px!important;border:1px solid #eee!important;border-radius:6px!important;overflow:auto!important;max-height:320px!important;font-family:ui-monospace,SFMono-Regular,Menlo,monospace!important;font-size:11px!important;line-height:1.5!important;background:#fafafa!important}
+.sth-version-htmldiff-empty{padding:8px 10px!important;color:#999!important;font-size:12px!important;font-family:-apple-system,"Segoe UI",sans-serif!important}
+.sth-version-htmldiff .hunk{display:block!important;white-space:pre!important;padding:0 8px!important}
+.sth-version-htmldiff .hunk.add{background:#dcfce7!important;color:#15803d!important}
+.sth-version-htmldiff .hunk.del{background:#fee2e2!important;color:#b91c1c!important;text-decoration:line-through!important;text-decoration-color:#b91c1c66!important}
+.sth-version-htmldiff .hunk.ctx{color:#999!important}
+.sth-version-htmldiff .hunk.skip{color:#bbb!important;font-style:italic!important;background:#f5f5f5!important}
 </style>`
 
 const versionDrawerHTML = `<div id="sth-version-btn" title="Version timeline" style="display:none">v?</div>
@@ -239,12 +250,23 @@ const versionDrawerJS = `<script>
     // Newest first for the timeline UI.
     var versions=data.versions.slice().sort(function(a,b){return b.versionNo-a.versionNo;});
     for(var j=0;j<versions.length;j++){
-      html+=item(versions[j],byVersion[versions[j].versionNo]);
+      // Predecessor (by version_no, not array index): the largest version_no
+      // strictly smaller than this one among live versions. In the
+      // newest-first array that is the next entry, but compute it explicitly
+      // so soft-delete gaps (v1, v3) still link v3 -> v1.
+      var prevNo=0;
+      for(var k=0;k<versions.length;k++){
+        if(versions[k].versionNo<versions[j].versionNo && versions[k].versionNo>prevNo){
+          prevNo=versions[k].versionNo;
+        }
+      }
+      html+=item(versions[j],byVersion[versions[j].versionNo],prevNo);
     }
     html+='</div>';
     content.innerHTML=html;
+    wireDiffButtons();
   }
-  function item(v,diff){
+  function item(v,diff,prevVersionNo){
     var cls=v.current?'sth-version-item sth-version-current':'sth-version-item';
     var h='<div class="'+cls+'">';
     h+='<a class="sth-version-link" href="/s/'+encodeURIComponent(v.sessionId)+'/">v'+v.versionNo+(v.current?' (current)':'')+'</a>';
@@ -253,9 +275,91 @@ const versionDrawerJS = `<script>
     }
     h+='<div class="sth-version-created">'+escapeHtml(v.createdAt||'')+'</div>';
     h+=diffHtml(diff);
+    // HTML content diff button: only when this version has a live predecessor.
+    if(prevVersionNo>0){
+      h+='<button class="sth-version-diffbtn" data-from="'+prevVersionNo+'" data-to="'+v.versionNo+'">Show HTML diff <span class="badge"></span></button>';
+      h+='<div class="sth-version-htmldiff" data-target="v'+v.versionNo+'" style="display:none"></div>';
+    }
     h+='</div>';
     return h;
   }
+  // wireDiffButtons attaches click handlers to every Show HTML diff button in
+  // the rendered timeline. Clicking fetches the diff once and expands it into
+  // the sibling .sth-version-htmldiff container; clicking again collapses it.
+  function wireDiffButtons(){
+    var buttons=content.querySelectorAll('.sth-version-diffbtn');
+    for(var i=0;i<buttons.length;i++){
+      (function(b){
+        b.addEventListener('click',function(){
+          var container=b.nextElementSibling;
+          if(!container||!container.classList.contains('sth-version-htmldiff')){return;}
+          if(container.getAttribute('data-loaded')==='1'){
+            // Toggle collapse/expand.
+            var open=container.style.display!=='none';
+            container.style.display=open?'none':'block';
+            b.firstChild.nodeValue=open?'Show HTML diff ':'Hide HTML diff ';
+            return;
+          }
+          container.style.display='block';
+          container.innerHTML='<div class="sth-version-htmldiff-empty">Diffing...</div>';
+          var from=b.getAttribute('data-from'),to=b.getAttribute('data-to');
+          fetch('/api/sessions/'+encodeURIComponent(sid)+'/diff?from='+encodeURIComponent(from)+'&to='+encodeURIComponent(to),{credentials:'same-origin'})
+            .then(function(r){if(!r.ok){throw new Error('HTTP '+r.status);}return r.json();})
+            .then(function(data){
+              container.setAttribute('data-loaded','1');
+              container.innerHTML=renderHtmlDiff(data);
+              b.firstChild.nodeValue='Hide HTML diff ';
+              var badge=b.querySelector('.badge');
+              if(badge){badge.innerHTML=formatBadge(data.summary);}
+            })
+            .catch(function(err){
+              container.innerHTML='<div class="sth-version-htmldiff-empty">Failed: '+escapeHtml(String(err))+'</div>';
+            });
+        });
+      })(buttons[i]);
+    }
+  }
+  // renderHtmlDiff turns a diffResponse into collapsed HTML: equal runs are
+  // elided into a single "… N unchanged …" skip line so additions/deletions
+  // stay visible without scrolling through hundreds of context lines.
+  function renderHtmlDiff(data){
+    if(!data||!data.lines||data.lines.length===0){
+      return '<div class="sth-version-htmldiff-empty">No changes.</div>';
+    }
+    var out=[];
+    var ctxRun=0;
+    function flushCtx(){
+      if(ctxRun>0){
+        out.push('<span class="hunk skip">  ⋯ '+ctxRun+' unchanged line'+(ctxRun===1?'':'s')+' ⋯</span>');
+        ctxRun=0;
+      }
+    }
+    for(var i=0;i<data.lines.length;i++){
+      var l=data.lines[i];
+      if(l.kind==='equal'){
+        ctxRun++;
+      }else{
+        flushCtx();
+        if(l.kind==='add'){
+          out.push('<span class="hunk add">+ '+escapeHtml(l.text)+'</span>');
+        }else if(l.kind==='delete'){
+          out.push('<span class="hunk del">- '+escapeHtml(l.text)+'</span>');
+        }
+      }
+    }
+    flushCtx();
+    if(out.length===0){
+      return '<div class="sth-version-htmldiff-empty">No changes.</div>';
+    }
+    return out.join('');
+  }
+  function formatBadge(summary){
+    if(!summary){return '';}
+    var parts=[];
+    if(summary.added){parts.push('+'+summary.added);}
+    if(summary.removed){parts.push('<span class="rm">−'+summary.removed+'</span>');}
+    return parts.length?' '+parts.join(' '):'';
+  }
   function diffHtml(diff){
     if(!diff){return '';}
     var parts=[];
diff --git a/internal/server/server.go b/internal/server/server.go
index 6e5c58b..b393603 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -740,6 +740,8 @@ func (s *Server) routes() http.Handler {
 			s.handleGetPeers(w, r)
 		case r.Method == http.MethodGet && hasPrefixSuffix(r.URL.Path, "/api/sessions/", "/chain"):
 			s.handleGetChain(w, r)
+		case r.Method == http.MethodGet && hasPrefixSuffix(r.URL.Path, "/api/sessions/", "/diff"):
+			s.handleGetDiff(w, r)
 		case r.Method == http.MethodGet && hasPrefixSuffix(r.URL.Path, "/api/sessions/", "/download"):
 			s.handleDownloadSession(w, r)
 		case r.Method == http.MethodDelete && isExactSessionPath(r.URL.Path):
@@ -1931,6 +1933,153 @@ func (s *Server) handleGetChain(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// diffLine is one line of an HTML content diff, with a stable kind token for
+// JSON consumers ("equal" / "add" / "delete") alongside the 1-based line
+// numbers in each document (0 when N/A).
+type diffLine struct {
+	Kind  string `json:"kind"`
+	Text  string `json:"text"`
+	OldNo int    `json:"oldNo"`
+	NewNo int    `json:"newNo"`
+}
+
+// diffResponse is the payload of GET /api/sessions/{id}/diff?from=vN&to=vM.
+// Lines is the full line-level diff in reading order; Summary gives additive
+// counts so the UI can render a "+a −b" hint without scanning the slice.
+type diffResponse struct {
+	FromVersion int         `json:"fromVersion"`
+	ToVersion   int         `json:"toVersion"`
+	Lines       []diffLine  `json:"lines"`
+	Summary     diffSummary `json:"summary"`
+}
+
+type diffSummary struct {
+	Added   int `json:"added"`
+	Removed int `json:"removed"`
+}
+
+// handleGetDiff computes a line-level HTML content diff between two versions
+// of the same chain. The {id} in the path identifies any session in the chain
+// (used to resolve chain membership + ownership); from / to are 1-based
+// version numbers of the same chain. Cross-chain or out-of-range version
+// numbers yield 400; a missing or soft-deleted session yields 404.
+func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
+	defer r.Body.Close()
+	sessionID, ok := extractSessionIDFromMetaPath(r.URL.Path, "/api/sessions/", "/diff")
+	if !ok {
+		writeJSONError(w, http.StatusBadRequest, "Invalid session ID.")
+		return
+	}
+
+	_, found, err := s.requireSession(sessionID)
+	if err != nil {
+		writeJSONError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	if !found {
+		writeJSONError(w, http.StatusNotFound, "Session not found.")
+		return
+	}
+	if !s.requireOwner(w, r, sessionID) {
+		return
+	}
+
+	fromVer, toVer, bad := parseDiffVersions(r)
+	if bad != "" {
+		writeJSONError(w, http.StatusBadRequest, bad)
+		return
+	}
+
+	// Resolve the chain via the requested session; this also enforces the
+	// soft-delete visibility rule (404 on deleted sessions).
+	_, versions, err := s.store.GetChainOfSession(sessionID)
+	if err != nil {
+		if errors.Is(err, session.ErrSessionNotFound) {
+			writeJSONError(w, http.StatusNotFound, "Session not found.")
+			return
+		}
+		writeJSONError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	fromSID, ok := versionSessionID(versions, fromVer)
+	if !ok {
+		writeJSONError(w, http.StatusBadRequest, "from version not found in this chain.")
+		return
+	}
+	toSID, ok := versionSessionID(versions, toVer)
+	if !ok {
+		writeJSONError(w, http.StatusBadRequest, "to version not found in this chain.")
+		return
+	}
+	if fromSID == toSID {
+		writeJSONError(w, http.StatusBadRequest, "from and to versions must differ.")
+		return
+	}
+
+	ops, err := s.store.DiffSessionHTML(fromSID, toSID)
+	if err != nil {
+		if errors.Is(err, session.ErrSessionNotFound) {
+			writeJSONError(w, http.StatusNotFound, "Session not found.")
+			return
+		}
+		writeJSONError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	lines := make([]diffLine, 0, len(ops))
+	for _, op := range ops {
+		lines = append(lines, diffLine{
+			Kind:  op.KindString(),
+			Text:  op.Text,
+			OldNo: op.OldNo,
+			NewNo: op.NewNo,
+		})
+	}
+	summary := session.Summarize(ops)
+
+	writeJSON(w, http.StatusOK, diffResponse{
+		FromVersion: fromVer,
+		ToVersion:   toVer,
+		Lines:       lines,
+		Summary: diffSummary{
+			Added:   summary.Added,
+			Removed: summary.Removed,
+		},
+	})
+}
+
+// parseDiffVersions reads the from / to query params as positive integers.
+// Returns a human-readable error string (empty when OK).
+func parseDiffVersions(r *http.Request) (from, to int, errMsg string) {
+	q := r.URL.Query()
+	fromStr := strings.TrimSpace(q.Get("from"))
+	toStr := strings.TrimSpace(q.Get("to"))
+	if fromStr == "" || toStr == "" {
+		return 0, 0, "Both 'from' and 'to' version numbers are required."
+	}
+	f, err := strconv.Atoi(fromStr)
+	if err != nil || f < 1 {
+		return 0, 0, "'from' must be a positive integer version number."
+	}
+	t, err := strconv.Atoi(toStr)
+	if err != nil || t < 1 {
+		return 0, 0, "'to' must be a positive integer version number."
+	}
+	return f, t, ""
+}
+
+// versionSessionID finds the session id for a given version number within a
+// chain's version list. Returns ok=false when no live version matches.
+func versionSessionID(versions []session.ChainVersion, versionNo int) (string, bool) {
+	for _, v := range versions {
+		if v.VersionNo == versionNo {
+			return v.SessionID, true
+		}
+	}
+	return "", false
+}
+
 func (s *Server) handleDeleteSession(w http.ResponseWriter, r *http.Request) {
 	sessionID := strings.TrimPrefix(r.URL.Path, "/api/sessions/")
 
diff --git a/internal/server/server_test.go b/internal/server/server_test.go
index b43c357..bc0bd90 100644
--- a/internal/server/server_test.go
+++ b/internal/server/server_test.go
@@ -1704,3 +1704,225 @@ func TestGetChainSoftDeletedRequestReturns404(t *testing.T) {
 		t.Fatalf("expected 404 for soft-deleted session, got %d body=%s", resp.StatusCode, body)
 	}
 }
+
+// createChainedSessionWithFile is createChainedSession but the entry HTML is a
+// real on-disk file, so the diff endpoint can read actual content. The file
+// is written under a fresh temp dir; the session's StoredEntryFile points at it.
+func createChainedSessionWithFile(t *testing.T, store *session.Store, htmlContent, project, category string, tags ...string) string {
+	t.Helper()
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "index.html")
+	if err := os.WriteFile(path, []byte(htmlContent), 0o644); err != nil {
+		t.Fatalf("write index.html: %v", err)
+	}
+	s, err := store.CreateUploaded("index.html", path)
+	if err != nil {
+		t.Fatalf("CreateUploaded: %v", err)
+	}
+	if len(tags) > 0 {
+		if err := store.AddTags(s.ID, tags...); err != nil {
+			t.Fatalf("AddTags: %v", err)
+		}
+	}
+	if category != "" {
+		if err := store.SetCategory(s.ID, category); err != nil {
+			t.Fatalf("SetCategory: %v", err)
+		}
+	}
+	if project != "" {
+		if err := store.SetProject(s.ID, project); err != nil {
+			t.Fatalf("SetProject: %v", err)
+		}
+	}
+	if _, _, err := store.LinkToChain(s.ID, project, "index.html", ""); err != nil {
+		t.Fatalf("LinkToChain: %v", err)
+	}
+	return s.ID
+}
+
+func TestGetDiffSuccess(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	// v1 and v2 share (project, entry file); v2 adds one line.
+	createChainedSessionWithFile(t, store, "<html>\n<body>\n<h1>v1</h1>\n</body>\n</html>\n", "proj", "cat")
+	v2 := createChainedSessionWithFile(t, store, "<html>\n<body>\n<h1>v1</h1>\n<p>v2 line</p>\n</body>\n</html>\n", "proj", "cat")
+
+	srv, err := New("127.0.0.1", 0, store, "", 0, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := srv.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = srv.Stop(ctx)
+	}()
+
+	resp, err := http.Get(srv.Origin() + "/api/sessions/" + v2 + "/diff?from=1&to=2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, body)
+	}
+
+	var result diffResponse
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		t.Fatal(err)
+	}
+	if result.FromVersion != 1 || result.ToVersion != 2 {
+		t.Fatalf("version mismatch: from=%d to=%d", result.FromVersion, result.ToVersion)
+	}
+	if result.Summary.Added != 1 || result.Summary.Removed != 0 {
+		t.Fatalf("expected +1 −0; got %+v", result.Summary)
+	}
+	if len(result.Lines) == 0 {
+		t.Fatal("expected non-empty lines")
+	}
+	// The added line must carry the v2 paragraph text.
+	var added diffLine
+	for _, l := range result.Lines {
+		if l.Kind == "add" {
+			added = l
+		}
+	}
+	if added.Text != "<p>v2 line</p>" {
+		t.Fatalf("added line text = %q, want %q", added.Text, "<p>v2 line</p>")
+	}
+	if added.OldNo != 0 || added.NewNo == 0 {
+		t.Fatalf("added line line numbers wrong: old=%d new=%d", added.OldNo, added.NewNo)
+	}
+}
+
+func TestGetDiffMissingParams(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<p>x</p>\n", "proj", "cat")
+
+	srv, err := New("127.0.0.1", 0, store, "", 0, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := srv.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = srv.Stop(ctx)
+	}()
+
+	// Missing 'to'.
+	resp, err := http.Get(srv.Origin() + "/api/sessions/" + v1 + "/diff?from=1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 for missing 'to', got %d", resp.StatusCode)
+	}
+
+	// Non-numeric.
+	resp, err = http.Get(srv.Origin() + "/api/sessions/" + v1 + "/diff?from=abc&to=1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 for non-numeric from, got %d", resp.StatusCode)
+	}
+}
+
+func TestGetDiffVersionOutOfRange(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<p>x</p>\n", "proj", "cat")
+	createChainedSessionWithFile(t, store, "<p>y</p>\n", "proj", "cat")
+
+	srv, err := New("127.0.0.1", 0, store, "", 0, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := srv.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = srv.Stop(ctx)
+	}()
+
+	// Version 99 doesn't exist in this 2-version chain.
+	resp, err := http.Get(srv.Origin() + "/api/sessions/" + v1 + "/diff?from=1&to=99")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 for out-of-range version, got %d", resp.StatusCode)
+	}
+}
+
+func TestGetDiffSameVersionRejected(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<p>x</p>\n", "proj", "cat")
+
+	srv, err := New("127.0.0.1", 0, store, "", 0, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := srv.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = srv.Stop(ctx)
+	}()
+
+	resp, err := http.Get(srv.Origin() + "/api/sessions/" + v1 + "/diff?from=1&to=1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 for from==to, got %d", resp.StatusCode)
+	}
+}
+
+func TestGetDiffNotFound(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	srv, err := New("127.0.0.1", 0, store, "", 0, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := srv.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = srv.Stop(ctx)
+	}()
+
+	resp, err := http.Get(srv.Origin() + "/api/sessions/nonexistent/diff?from=1&to=2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+}
diff --git a/internal/session/htmldiff.go b/internal/session/htmldiff.go
new file mode 100644
index 0000000..77f2061
--- /dev/null
+++ b/internal/session/htmldiff.go
@@ -0,0 +1,151 @@
+package session
+
+import "strings"
+
+// LineOpKind classifies a single line in a line-level diff.
+type LineOpKind int
+
+const (
+	LineEqual  LineOpKind = iota
+	LineAdd               // present in the new version only
+	LineDelete            // present in the old version only
+)
+
+// LineOp is one line of a diff between two multi-line texts. OldNo / NewNo
+// are 1-based line numbers in the old / new document respectively; the one
+// that does not apply (e.g. OldNo for an added line) is left as 0.
+type LineOp struct {
+	Kind  LineOpKind `json:"kind"`
+	Text  string     `json:"text"`
+	OldNo int        `json:"oldNo"`
+	NewNo int        `json:"newNo"`
+}
+
+// KindString returns a stable, human-readable single-letter code for JSON
+// consumers that prefer "equal"/"add"/"delete" tokens over an int.
+func (op LineOp) KindString() string {
+	switch op.Kind {
+	case LineAdd:
+		return "add"
+	case LineDelete:
+		return "delete"
+	default:
+		return "equal"
+	}
+}
+
+// MaxDiffLines guards against pathological inputs. Above this many lines in
+// either side, the LCS dynamic program (O(n*m) time and memory) becomes
+// expensive; DiffLines returns a single sentinel op instead so callers can
+// render a "too large to diff" notice without blocking. The threshold is
+// generous for hand-authored / agent-generated HTML (typically < 2000 lines).
+const MaxDiffLines = 10000
+
+// DiffTooLarge is returned as the sole LineOp when either input exceeds
+// MaxDiffLines. Its Kind is LineEqual so callers treating the slice as a list
+// of ops can still iterate; the Text carries an explanatory message.
+const DiffTooLargeText = "[diff skipped: file exceeds MaxDiffLines]"
+
+// DiffLines computes a line-level diff between oldLines and newLines using the
+// classic LCS dynamic-programming algorithm, then walks the DP table to emit
+// a sequence of LineOps in reading order (deletions before insertions when
+// they share a context line). The result is pure: no I/O, no Store state.
+//
+// Either input being empty is handled naturally (an empty old side makes
+// every new line an addition, and vice versa). Inputs exceeding MaxDiffLines
+// on either side yield DiffTooLarge.
+func DiffLines(oldLines, newLines []string) []LineOp {
+	if len(oldLines) > MaxDiffLines || len(newLines) > MaxDiffLines {
+		return []LineOp{{Kind: LineEqual, Text: DiffTooLargeText}}
+	}
+
+	n, m := len(oldLines), len(newLines)
+
+	// dp[i][j] = length of LCS of oldLines[i:] and newLines[j:].
+	// Using (n+1) x (m+1) so dp[n][m] = 0 is the empty-base case.
+	dp := make([][]int, n+1)
+	for i := range dp {
+		dp[i] = make([]int, m+1)
+	}
+	for i := n - 1; i >= 0; i-- {
+		for j := m - 1; j >= 0; j-- {
+			if oldLines[i] == newLines[j] {
+				dp[i][j] = dp[i+1][j+1] + 1
+			} else if dp[i+1][j] >= dp[i][j+1] {
+				dp[i][j] = dp[i+1][j]
+			} else {
+				dp[i][j] = dp[i][j+1]
+			}
+		}
+	}
+
+	ops := make([]LineOp, 0, n+m)
+	i, j := 0, 0
+	oldNo, newNo := 1, 1
+	for i < n && j < m {
+		if oldLines[i] == newLines[j] {
+			ops = append(ops, LineOp{Kind: LineEqual, Text: oldLines[i], OldNo: oldNo, NewNo: newNo})
+			i++
+			j++
+			oldNo++
+			newNo++
+		} else if dp[i+1][j] >= dp[i][j+1] {
+			// Deleting oldLines[i] keeps the longer remaining common subsequence.
+			ops = append(ops, LineOp{Kind: LineDelete, Text: oldLines[i], OldNo: oldNo})
+			i++
+			oldNo++
+		} else {
+			ops = append(ops, LineOp{Kind: LineAdd, Text: newLines[j], NewNo: newNo})
+			j++
+			newNo++
+		}
+	}
+	// Drain the tail: remaining old lines are deletions, remaining new lines additions.
+	for i < n {
+		ops = append(ops, LineOp{Kind: LineDelete, Text: oldLines[i], OldNo: oldNo})
+		i++
+		oldNo++
+	}
+	for j < m {
+		ops = append(ops, LineOp{Kind: LineAdd, Text: newLines[j], NewNo: newNo})
+		j++
+		newNo++
+	}
+
+	return ops
+}
+
+// SplitLines splits text into lines, preserving content but dropping the
+// trailing newline. A trailing empty element is trimmed so that "a\nb\n" and
+// "a\nb" produce the same two lines (HTML files conventionally end with a
+// newline; that should not register as an extra blank line in the diff).
+func SplitLines(text string) []string {
+	if text == "" {
+		return nil
+	}
+	lines := strings.Split(text, "\n")
+	if len(lines) > 0 && lines[len(lines)-1] == "" {
+		lines = lines[:len(lines)-1]
+	}
+	return lines
+}
+
+// DiffSummary is the additive counts of a diff's LineOps.
+type DiffSummary struct {
+	Added   int `json:"added"`
+	Removed int `json:"removed"`
+}
+
+// Summarize counts added / removed lines across ops. Equal lines are ignored.
+func Summarize(ops []LineOp) DiffSummary {
+	var s DiffSummary
+	for _, op := range ops {
+		switch op.Kind {
+		case LineAdd:
+			s.Added++
+		case LineDelete:
+			s.Removed++
+		}
+	}
+	return s
+}
diff --git a/internal/session/htmldiff_test.go b/internal/session/htmldiff_test.go
new file mode 100644
index 0000000..1a6952c
--- /dev/null
+++ b/internal/session/htmldiff_test.go
@@ -0,0 +1,250 @@
+package session
+
+import (
+	"strings"
+	"testing"
+)
+
+func opsSummary(ops []LineOp) (equal, added, deleted int) {
+	for _, op := range ops {
+		switch op.Kind {
+		case LineEqual:
+			equal++
+		case LineAdd:
+			added++
+		case LineDelete:
+			deleted++
+		}
+	}
+	return
+}
+
+func TestDiffLines_IdenticalInputsAreAllEqual(t *testing.T) {
+	t.Parallel()
+	old := []string{"<html>", "<body>", "</body>", "</html>"}
+	ops := DiffLines(old, old)
+
+	eq, add, del := opsSummary(ops)
+	if add != 0 || del != 0 {
+		t.Fatalf("identical input should have no add/del; got add=%d del=%d", add, del)
+	}
+	if eq != len(old) {
+		t.Fatalf("expected %d equal ops, got %d", len(old), eq)
+	}
+	for i, op := range ops {
+		if op.Text != old[i] {
+			t.Fatalf("op %d text = %q, want %q", i, op.Text, old[i])
+		}
+		if op.OldNo != i+1 || op.NewNo != i+1 {
+			t.Fatalf("op %d line numbers = old=%d new=%d, want %d", i, op.OldNo, op.NewNo, i+1)
+		}
+	}
+}
+
+func TestDiffLines_PureAddition(t *testing.T) {
+	t.Parallel()
+	ops := DiffLines([]string{"a", "c"}, []string{"a", "b", "c"})
+
+	eq, add, del := opsSummary(ops)
+	if add != 1 || del != 0 || eq != 2 {
+		t.Fatalf("expected 1 add / 0 del / 2 eq; got add=%d del=%d eq=%d", add, del, eq)
+	}
+	// The added line should carry the inserted text and the new 1-based number.
+	var inserted LineOp
+	for _, op := range ops {
+		if op.Kind == LineAdd {
+			inserted = op
+		}
+	}
+	if inserted.Text != "b" {
+		t.Fatalf("inserted text = %q, want %q", inserted.Text, "b")
+	}
+	if inserted.NewNo != 2 {
+		t.Fatalf("inserted NewNo = %d, want 2", inserted.NewNo)
+	}
+	if inserted.OldNo != 0 {
+		t.Fatalf("inserted OldNo should be 0, got %d", inserted.OldNo)
+	}
+}
+
+func TestDiffLines_PureDeletion(t *testing.T) {
+	t.Parallel()
+	ops := DiffLines([]string{"a", "b", "c"}, []string{"a", "c"})
+
+	eq, add, del := opsSummary(ops)
+	if add != 0 || del != 1 || eq != 2 {
+		t.Fatalf("expected 0 add / 1 del / 2 eq; got add=%d del=%d eq=%d", add, del, eq)
+	}
+	var removed LineOp
+	for _, op := range ops {
+		if op.Kind == LineDelete {
+			removed = op
+		}
+	}
+	if removed.Text != "b" {
+		t.Fatalf("removed text = %q, want %q", removed.Text, "b")
+	}
+	if removed.OldNo != 2 {
+		t.Fatalf("removed OldNo = %d, want 2", removed.OldNo)
+	}
+}
+
+func TestDiffLines_ModificationIsDelThenAdd(t *testing.T) {
+	t.Parallel()
+	// Changing the middle line: old has "old", new has "new" in the same slot.
+	ops := DiffLines([]string{"a", "old", "c"}, []string{"a", "new", "c"})
+
+	eq, add, del := opsSummary(ops)
+	if add != 1 || del != 1 || eq != 2 {
+		t.Fatalf("expected 1 add / 1 del / 2 eq; got add=%d del=%d eq=%d", add, del, eq)
+	}
+	// Expect ordering: equal a, delete old, add new, equal c.
+	wantKinds := []LineOpKind{LineEqual, LineDelete, LineAdd, LineEqual}
+	if len(ops) != len(wantKinds) {
+		t.Fatalf("expected %d ops, got %d", len(wantKinds), len(ops))
+	}
+	for i, want := range wantKinds {
+		if ops[i].Kind != want {
+			t.Fatalf("op %d kind = %v, want %v (full: %+v)", i, ops[i].Kind, want, ops)
+		}
+	}
+}
+
+func TestDiffLines_ReconstructsBothSides(t *testing.T) {
+	t.Parallel()
+	// Property test: replaying equal+delete ops yields old; equal+add yields new.
+	old := []string{"<html>", "<head>", "<title>x</title>", "</head>", "<body>", "</body>", "</html>"}
+	new := []string{"<html>", "<head>", "<title>y</title>", "<meta charset='utf-8'>", "</head>", "<body>", "</body>", "</html>"}
+	ops := DiffLines(old, new)
+
+	var rebuiltOld, rebuiltNew strings.Builder
+	for _, op := range ops {
+		switch op.Kind {
+		case LineEqual:
+			rebuiltOld.WriteString(op.Text + "\n")
+			rebuiltNew.WriteString(op.Text + "\n")
+		case LineDelete:
+			rebuiltOld.WriteString(op.Text + "\n")
+		case LineAdd:
+			rebuiltNew.WriteString(op.Text + "\n")
+		}
+	}
+	// Join with "\n" plus trailing "\n" to match the builder's concatenation.
+	wantOld := strings.Join(old, "\n") + "\n"
+	wantNew := strings.Join(new, "\n") + "\n"
+	if rebuiltOld.String() != wantOld {
+		t.Fatalf("reconstructed old mismatch:\ngot:  %q\nwant: %q", rebuiltOld.String(), wantOld)
+	}
+	if rebuiltNew.String() != wantNew {
+		t.Fatalf("reconstructed new mismatch:\ngot:  %q\nwant: %q", rebuiltNew.String(), wantNew)
+	}
+}
+
+func TestDiffLines_EmptyInputs(t *testing.T) {
+	t.Parallel()
+	// Both empty -> no ops.
+	if ops := DiffLines(nil, nil); len(ops) != 0 {
+		t.Fatalf("empty/empty should yield no ops; got %d", len(ops))
+	}
+	// Empty old -> everything added.
+	ops := DiffLines(nil, []string{"a", "b"})
+	if len(ops) != 2 || ops[0].Kind != LineAdd || ops[1].Kind != LineAdd {
+		t.Fatalf("empty old should yield 2 adds; got %+v", ops)
+	}
+	// Empty new -> everything deleted.
+	ops = DiffLines([]string{"a", "b"}, nil)
+	if len(ops) != 2 || ops[0].Kind != LineDelete || ops[1].Kind != LineDelete {
+		t.Fatalf("empty new should yield 2 deletes; got %+v", ops)
+	}
+}
+
+func TestDiffLines_CompletelyDifferent(t *testing.T) {
+	t.Parallel()
+	old := []string{"x", "y", "z"}
+	new := []string{"p", "q", "r"}
+	ops := DiffLines(old, new)
+
+	eq, add, del := opsSummary(ops)
+	if eq != 0 || add != 3 || del != 3 {
+		t.Fatalf("expected 0 eq / 3 add / 3 del; got eq=%d add=%d del=%d", eq, add, del)
+	}
+}
+
+func TestDiffLines_TooLargeIsSkipped(t *testing.T) {
+	t.Parallel()
+	huge := make([]string, MaxDiffLines+1)
+	for i := range huge {
+		huge[i] = "line"
+	}
+	ops := DiffLines(huge, []string{"a"})
+	if len(ops) != 1 {
+		t.Fatalf("expected 1 sentinel op for too-large input; got %d", len(ops))
+	}
+	if ops[0].Text != DiffTooLargeText {
+		t.Fatalf("expected sentinel text %q, got %q", DiffTooLargeText, ops[0].Text)
+	}
+
+	// Exactly at the threshold is still diffed.
+	atLimit := make([]string, MaxDiffLines)
+	big := DiffLines(atLimit, atLimit)
+	if len(big) != MaxDiffLines {
+		t.Fatalf("input at limit should still be diffed; got %d ops", len(big))
+	}
+}
+
+func TestSplitLines_TrailingNewlineHandled(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in   string
+		want []string
+	}{
+		{"", nil},
+		{"a", []string{"a"}},
+		{"a\nb", []string{"a", "b"}},
+		{"a\nb\n", []string{"a", "b"}},       // trailing newline dropped
+		{"a\nb\n\n", []string{"a", "b", ""}}, // interior blank line preserved
+	}
+	for _, c := range cases {
+		got := SplitLines(c.in)
+		if len(got) != len(c.want) {
+			t.Fatalf("SplitLines(%q) = %v, want %v", c.in, got, c.want)
+		}
+		for i := range got {
+			if got[i] != c.want[i] {
+				t.Fatalf("SplitLines(%q)[%d] = %q, want %q", c.in, i, got[i], c.want[i])
+			}
+		}
+	}
+}
+
+func TestSummarize(t *testing.T) {
+	t.Parallel()
+	ops := []LineOp{
+		{Kind: LineEqual},
+		{Kind: LineAdd},
+		{Kind: LineAdd},
+		{Kind: LineDelete},
+	}
+	s := Summarize(ops)
+	if s.Added != 2 || s.Removed != 1 {
+		t.Fatalf("expected added=2 removed=1; got %+v", s)
+	}
+}
+
+func TestLineOpKindString(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		kind LineOpKind
+		want string
+	}{
+		{LineEqual, "equal"},
+		{LineAdd, "add"},
+		{LineDelete, "delete"},
+	}
+	for _, c := range cases {
+		op := LineOp{Kind: c.kind}
+		if got := op.KindString(); got != c.want {
+			t.Fatalf("KindString(%v) = %q, want %q", c.kind, got, c.want)
+		}
+	}
+}
diff --git a/internal/session/version.go b/internal/session/version.go
index 2edc7eb..e6ae4fe 100644
--- a/internal/session/version.go
+++ b/internal/session/version.go
@@ -3,6 +3,7 @@ package session
 import (
 	"database/sql"
 	"errors"
+	"os"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -392,3 +393,59 @@ func chainVersionFrom(sessionID string, sess Session, meta DocumentMetadata, ver
 		CreatedAt: sess.CreatedAtISO(),
 	}
 }
+
+// DiffSessionHTML computes a line-level diff between the entry HTML of two
+// sessions by reading each session's StoredEntryFile off disk. It is the
+// first code in the codebase to read uploaded session content into memory;
+// it reuses the established store.Get → StoredEntryFile access pattern.
+//
+// Missing or unreadable files are treated as empty content (not an error):
+// legacy sessions created without on-disk files, or whose upload dir was
+// cleared, still produce a valid (one-sided) diff rather than failing. This
+// graceful degradation keeps the diff endpoint usable across mixed data.
+//
+// Either session being absent from the store returns ErrSessionNotFound.
+// The result is never nil: callers can safely len()/range over it.
+func (s *Store) DiffSessionHTML(fromSessionID, toSessionID string) ([]LineOp, error) {
+	fromSess, found, err := s.Get(fromSessionID)
+	if err != nil {
+		return nil, err
+	}
+	if !found {
+		return nil, ErrSessionNotFound
+	}
+	toSess, found, err := s.Get(toSessionID)
+	if err != nil {
+		return nil, err
+	}
+	if !found {
+		return nil, ErrSessionNotFound
+	}
+
+	oldText := readSessionHTML(fromSess)
+	newText := readSessionHTML(toSess)
+
+	ops := DiffLines(SplitLines(oldText), SplitLines(newText))
+	if ops == nil {
+		ops = []LineOp{}
+	}
+	return ops, nil
+}
+
+// readSessionHTML reads the session's entry HTML, returning "" for any I/O
+// failure so the caller can diff against an empty document. StoredEntryFile
+// is preferred (the on-disk upload path) and falls back to EntryFile.
+func readSessionHTML(sess Session) string {
+	path := sess.StoredEntryFile
+	if path == "" {
+		path = sess.EntryFile
+	}
+	if path == "" {
+		return ""
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return string(data)
+}
diff --git a/internal/session/version_test.go b/internal/session/version_test.go
index 542ddf3..ab20bae 100644
--- a/internal/session/version_test.go
+++ b/internal/session/version_test.go
@@ -2,6 +2,7 @@ package session
 
 import (
 	"errors"
+	"os"
 	"path/filepath"
 	"sort"
 	"testing"
@@ -443,3 +444,167 @@ func equalStringSlice(a, b []string) bool {
 
 // guard against unused import if filepath becomes unused in future edits.
 var _ = filepath.Base
+
+// writeSessionHTML creates a real on-disk HTML file in a temp dir and returns
+// its absolute path, so DiffSessionHTML can actually read content. The dir is
+// cleaned via t.TempDir().
+func writeSessionHTML(t *testing.T, name, content string) string {
+	t.Helper()
+	dir := t.TempDir()
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write %s: %v", name, err)
+	}
+	return path
+}
+
+// createChainedSessionWithFile is createLinkedSession but the entry file is a
+// real on-disk HTML file (so DiffSessionHTML has content to read). Returns the
+// session id.
+func createChainedSessionWithFile(t *testing.T, store *Store, htmlContent, project, category string, tags ...string) string {
+	t.Helper()
+	path := writeSessionHTML(t, "index.html", htmlContent)
+	sess, err := store.CreateUploaded("index.html", path)
+	if err != nil {
+		t.Fatalf("CreateUploaded: %v", err)
+	}
+	if len(tags) > 0 {
+		if err := store.AddTags(sess.ID, tags...); err != nil {
+			t.Fatalf("AddTags: %v", err)
+		}
+	}
+	if category != "" {
+		if err := store.SetCategory(sess.ID, category); err != nil {
+			t.Fatalf("SetCategory: %v", err)
+		}
+	}
+	if project != "" {
+		if err := store.SetProject(sess.ID, project); err != nil {
+			t.Fatalf("SetProject: %v", err)
+		}
+	}
+	if _, _, err := store.LinkToChain(sess.ID, project, "index.html", ""); err != nil {
+		t.Fatalf("LinkToChain: %v", err)
+	}
+	return sess.ID
+}
+
+func TestDiffSessionHTML_DetectsAddedLines(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<html>\n<body>\n<h1>old</h1>\n</body>\n</html>\n", "proj", "cat")
+	v2 := createChainedSessionWithFile(t, store, "<html>\n<body>\n<h1>old</h1>\n<p>new para</p>\n</body>\n</html>\n", "proj", "cat")
+
+	ops, err := store.DiffSessionHTML(v1, v2)
+	if err != nil {
+		t.Fatalf("DiffSessionHTML: %v", err)
+	}
+	eq, add, del := opsSummary(ops)
+	if del != 0 {
+		t.Fatalf("expected 0 deletions for pure addition; got %d (ops=%+v)", del, ops)
+	}
+	if add != 1 {
+		t.Fatalf("expected 1 added line; got %d (ops=%+v)", add, ops)
+	}
+	if eq == 0 {
+		t.Fatal("expected at least one equal line for shared context")
+	}
+	var added LineOp
+	for _, op := range ops {
+		if op.Kind == LineAdd {
+			added = op
+		}
+	}
+	if added.Text != "<p>new para</p>" {
+		t.Fatalf("added text = %q, want %q", added.Text, "<p>new para</p>")
+	}
+}
+
+func TestDiffSessionHTML_DetectsModifiedAndDeletedLines(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<h1>a</h1>\n<h2>b</h2>\n<h3>c</h3>\n", "proj", "cat")
+	v2 := createChainedSessionWithFile(t, store, "<h1>A</h1>\n<h3>c</h3>\n", "proj", "cat")
+
+	ops, err := store.DiffSessionHTML(v1, v2)
+	if err != nil {
+		t.Fatalf("DiffSessionHTML: %v", err)
+	}
+	_, add, del := opsSummary(ops)
+	if add != 1 || del != 2 {
+		t.Fatalf("expected add=1 del=2; got add=%d del=%d (ops=%+v)", add, del, ops)
+	}
+}
+
+func TestDiffSessionHTML_IdenticalFilesYieldAllEqual(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	content := "<html>\n<body>\nhi\n</body>\n</html>\n"
+	v1 := createChainedSessionWithFile(t, store, content, "proj", "cat")
+	v2 := createChainedSessionWithFile(t, store, content, "proj", "cat")
+
+	ops, err := store.DiffSessionHTML(v1, v2)
+	if err != nil {
+		t.Fatalf("DiffSessionHTML: %v", err)
+	}
+	_, add, del := opsSummary(ops)
+	if add != 0 || del != 0 {
+		t.Fatalf("identical files should have no add/del; got add=%d del=%d", add, del)
+	}
+}
+
+func TestDiffSessionHTML_MissingFileDegradesToEmpty(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<p>real</p>\n", "proj", "cat")
+	v2Sess, err := store.CreateUploaded("index.html", filepath.Join(t.TempDir(), "never-written.html"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := store.SetProject(v2Sess.ID, "proj"); err != nil {
+		t.Fatal(err)
+	}
+
+	ops, err := store.DiffSessionHTML(v1, v2Sess.ID)
+	if err != nil {
+		t.Fatalf("missing file should not error; got %v", err)
+	}
+	_, add, del := opsSummary(ops)
+	if add != 0 || del != 1 {
+		t.Fatalf("expected add=0 del=1 for missing v2 file; got add=%d del=%d (ops=%+v)", add, del, ops)
+	}
+}
+
+func TestDiffSessionHTML_UnknownSessionReturnsNotFound(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "<p>x</p>\n", "proj", "cat")
+
+	if _, err := store.DiffSessionHTML(v1, "nonexistent"); !errors.Is(err, ErrSessionNotFound) {
+		t.Fatalf("expected ErrSessionNotFound for unknown to-session; got %v", err)
+	}
+	if _, err := store.DiffSessionHTML("nonexistent", v1); !errors.Is(err, ErrSessionNotFound) {
+		t.Fatalf("expected ErrSessionNotFound for unknown from-session; got %v", err)
+	}
+}
+
+func TestDiffSessionHTML_NeverNil(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+	v1 := createChainedSessionWithFile(t, store, "", "proj", "cat")
+	v2 := createChainedSessionWithFile(t, store, "", "proj", "cat")
+
+	ops, err := store.DiffSessionHTML(v1, v2)
+	if err != nil {
+		t.Fatalf("DiffSessionHTML: %v", err)
+	}
+	if ops == nil {
+		t.Fatal("expected non-nil ops slice even for empty input")
+	}
+}
diff --git a/openspec/changes/html-content-diff/.openspec.yaml b/openspec/changes/html-content-diff/.openspec.yaml
new file mode 100644
index 0000000..ffa710f
--- /dev/null
+++ b/openspec/changes/html-content-diff/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-31
diff --git a/openspec/changes/html-content-diff/design.md b/openspec/changes/html-content-diff/design.md
new file mode 100644
index 0000000..33bed2e
--- /dev/null
+++ b/openspec/changes/html-content-diff/design.md
@@ -0,0 +1,77 @@
+## Context
+
+`version-chain-sessions`（D14–D18）落地了版本链：`(project, entry_file basename, owner)` 自动归链、`GET /api/sessions/{id}/chain`、预览页时间线侧栏、相邻版本**元数据** diff（D17 明确把 HTML 内容 diff 排除在外，列为"留作下一版独立 capability"）。
+
+本期就是这个"下一版"。现有相关实现要点（决策参照）：
+
+- `Store.Get(sid).StoredEntryFile` 给出 session 入口 HTML 的**绝对磁盘路径**（`store.go` 的 `CreateUploaded` 从 `os.MkdirTemp(uploadRoot, "session-*")` 构建）。同链的多个 session 是 `uploadRoot` 下的兄弟 `session-*` 目录，互相独立可读。
+- 但此前**没有任何代码把 session 内容读进内存**——preview 走 `http.ServeFile`、download 走 `io.Copy` 进 zip、live reload 走 fsnotify。本期是首个 `os.ReadFile(session.StoredEntryFile)` 的地方。
+- `inject.go` 的 `InjectMiddleware` 已成熟：缓冲 `/s/` 响应、对 `text/html` 在 `</head>` 前注入。peers drawer 与 version drawer 共享 `drawerBytes` 注入路径。version drawer 的 `item()` / `render()` 已是现成模板。
+- 项目对依赖的态度：**反复声明"无新依赖偏好"**（`support-password-login` D8、`version-chain` Non-Goals 明确写"无 diff 库"）。但偏好可破——bcrypt / websocket / fsnotify 都是正当理由才加的。
+- 决策号续接：上一版止于 D18，本期从 **D19** 起号。
+- `go.mod`：`go 1.24.1`，无任何 diff 库（sergi/go-diff、pmezard/difflib 均不在依赖图）。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 在时间线侧栏点开任意相邻版本对，看到 HTML 行级 diff（新增行 / 删除行），让"v2 改了什么"可读。
+- 零新依赖：LCS 手写，正面回应上一版"无 diff 库"Non-Goal。
+- 向后兼容：chain 接口逐字段不变；diff 走独立按需接口；老 session 文件缺失降级而非报错。
+- 大文件安全：超阈值输入返回跳过哨兵，不让 O(n*m) DP 拖垮请求。
+
+**Non-Goals:**
+- 不做词级 / 字符级 diff——行级已能回答"改了哪块"，词级需分词 + 标签边界处理，性价比低。
+- 不做 DOM 树 diff——需引 `golang.org/x/net/html`，破坏无新依赖约束；且 agent 产物行级 diff 已足够结构化。
+- 不做全屏并排对比预览——需 iframe 沙箱 + 并排布局，工程量大；侧栏内联展开已能看改动概览。
+- 不做跨任意两个版本的 diff——本期仅相邻版本（时间线上每个版本对它的直接前驱）；任意版本对比留待 UI 反馈。
+- 不做 diff 持久化 / 缓存——diff 是纯计算，每次请求即时算，永远反映当前文件状态（live reload 改了文件后 diff 自动更新）。
+- 不在 CLI 暴露 `sth diff`——diff 是浏览器侧可视化能力，CLI 用户用 `git diff` 等工具更顺手。
+
+## Decisions
+
+### D19: diff 粒度——行级 LCS，手写，无依赖
+**选择**：`DiffLines(old, new []string) []LineOp` 用经典 LCS 动态规划（O(n*m) 时间和内存，`dp[i][j]` = 后缀 LCS 长度），输出 `LineOp{Kind: Equal|Add|Delete, Text, OldNo, NewNo}`。修改表现为"先 delete 旧行再 add 新行"（LCS 的自然结果，与 unified diff 习惯一致）。纯 stdlib，~60 行 Go。
+**理由**：(1) agent 产出的 HTML 通常是结构化的（每行一个标签/一段文案），行级 diff 已能精确定位"哪块改了"。(2) LCS 是最经典、最可控、最可测的 diff 算法，无需引入第三方库——这直接化解了上一版 Non-Goals 的"无 diff 库"约束，是本期得以落地的关键。(3) 修改=先删后增符合 unified diff 直觉，前端按 `kind` 染色即可。
+**备选**：(a) 词级 diff（diffmatchpatch 风格）——否决，需分词 + HTML 标签边界处理复杂，且对"改了哪块"这个核心问题的边际收益低于行级；(b) DOM 树 diff——否决，需引 `golang.org/x/net/html`，破坏无新依赖约束；(c) 引 `sergi/go-diff` / `pmezard/difflib`——否决，上一版 Non-Goals 明确写了"无 diff 库"，且 LCS 手写成本可控。
+
+### D20: 渲染方式——时间线侧栏内联展开，上下文折叠
+**选择**：版本时间线侧栏每个（有前驱的）版本项加"Show HTML diff"按钮，点击懒加载 diff 接口、红绿行内联展开进 `.sth-version-htmldiff` 容器。**相等的上下文行折叠为单行 `⋯ N unchanged ⋯`**，只保留改动行 ± 紧邻上下文（本期实现是"完全折叠连续 equal 行为一条 skip 行"，不留 hunk 上下文——见 D22 取舍）。按钮旁显示 `+a −b` 摘要。再点折叠。
+**理由**：侧栏只有 340px 宽，若展示全部 equal 行会被上下文淹没，改动行反而找不到。折叠 equal 行让改动一目了然——这是 GitHub PR diff 的核心交互模式（hunk 折叠），但在侧栏这个尺寸下我们做得更激进：连续 equal 直接合成一条 skip 行。与现有元数据 diff 同位置（`item()` 内、metadata diff 之下），体验一致。
+**备选**：(a) 全屏并排对比（左 v2 右 v3 iframe）——否决，需 iframe 沙箱防 XSS + 并排布局，工程量大，且跳出预览上下文丢失"我在看 v3"的位置感；(b) 只在 CLI 输出 unified diff——否决，没用上预览页生态，且 agent 产物在浏览器看比终端看更直观。
+
+### D21: 获取方式——独立按需 `GET /diff` 接口，不污染 chain 接口
+**选择**：新增 `GET /api/sessions/{id}/diff?from=vN&to=vM`，点哪个版本对才拉那个 diff。chain 接口（`GET /chain`）响应逐字段不变。
+**理由**：chain 接口现在很轻（纯 DB 查询 + 内存 set diff），每次开侧栏都调一次。若把 HTML diff 塞进 chain 响应，每次开侧栏都要读 N 个版本的磁盘文件做 N 次 LCS——绝大多数版本用户根本不会展开。独立按需接口让"开侧栏"和"看某个 diff"的成本分离：前者恒定，后者按需。这也保持了 chain 接口的向后兼容（逐字段不变）。
+**`{id}` 的语义**：path 里的 `{id}` 是链上**任意** session（用于解析链归属 + owner 校验），`from/to` 是同链版本号。这样从任何一个版本预览页都能拉同链任意相邻对的 diff，无需先定位"链主 session"。
+**备选**：合并进 chain 接口一次性返回所有相邻 diff——否决，见上；每次开侧栏读 N 次磁盘 + N 次 LCS，浪费且延迟高。
+
+### D22: 大文件保护——超 `MaxDiffLines` 返回跳过哨兵
+**选择**：`MaxDiffLines = 10000`。任一侧超阈值时 `DiffLines` 返回单条 `LineOp{Kind: Equal, Text: DiffTooLargeText}`（`[diff skipped: file exceeds MaxDiffLines]`），前端原样渲染为一条灰色 skip 行。**恰好等于阈值仍正常 diff**。
+**理由**：LCS 是 O(n*m) DP，两个 10000 行文件 = 10^8 单元格 × 8 字节 int ≈ 800MB 内存 + 秒级 CPU，会拖垮请求。10000 行对 agent 产物（通常 < 2000 行）是极宽松的上限，正常用例永远触不到；真触到时跳过比卡死好。阈值是常量，将来按需调整。
+**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离）——对大文件更快但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过。
+
+### D23: diff 不入库——纯即时计算
+**选择**：`DiffSessionHTML` 每次调用都读两份文件 + 算 LCS，结果**不写 DB**。
+**理由**：(1) diff 结果体积大（每个版本对可能是几百行 LineOp），入库会让 sessions.db 膨胀且增加 schema 复杂度。(2) live reload（`realtime-html-update`）可能改了磁盘文件，即时计算永远反映**当前**文件状态，缓存反而会过期。(3) 按需接口（D21）+ LCS 足够快（正常文件 < 10ms），没有缓存的真实收益。
+**备选**：(a) diff 结果存表 + 文件 mtime 失效——否决，schema 膨胀 + 失效逻辑复杂 + 收益小；(b) 内存 LRU 缓存——否决，live reload 下缓存失效语义复杂，且单机 QPS 极低（一个人看 diff），无收益。
+
+## Risks / Trade-offs
+
+- **行级 diff 对"同行内小改"显示粗糙**：一行里改一个字，行级 diff 显示为"删整行 + 加整行"，看不出具体改了哪个字。→ 接受：本期目标是"改了哪块"而非"改了哪个字"；词级 diff 留作 Non-Goal。用户看到整行变更已足够定位。
+- **折叠 equal 行丢失 hunk 上下文**：连续 equal 行合成一条 skip 行，改动行周围没有紧邻的上下文行。→ 接受 + 可演进：侧栏窄，留 hunk 上下文会让改动被挤到屏幕外；当前"全折叠"最清晰。若用户反馈需要上下文，下版加"展开上下文"按钮（数据已在 `lines` 里，前端改动即可）。
+- **首个读 session 内容进内存的代码**：此前所有访问都走流式（ServeFile / io.Copy）。`os.ReadFile` 把整个 HTML 读进内存。→ 缓解：有 `MaxDiffLines` 保护，正常 HTML < 200KB，远低于任何内存压力。
+- **跨链 / 越界 version 号的处理**：`from/to` 必须是 `{id}` 所在链的合法 live version 号。→ 用 `GetChainOfSession` 拿 versions 列表校验，非法返回 400（清晰的客户端错误，不泄露内部链结构）。
+
+## Migration Plan
+
+1. 升级二进制 → 重启服务。
+2. 无 schema 变更（diff 纯计算），无数据迁移。
+3. 既有版本链立即获得 diff 能力：任意多版本链的预览页时间线侧栏自动出现"Show HTML diff"按钮。
+4. 老 session（无磁盘文件 / 文件被清）点 diff 会得到空 diff（"No changes."），不报错。
+5. **回滚**：删除新增的路由 case 与注入的 CSS/JS 即可降级为"无内容 diff"；chain 接口与时间线侧栏的元数据 diff 不受影响。
+
+## Open Questions
+
+- 是否需要"展开上下文"（在折叠的 skip 行点击展开 N 行 equal 上下文）？本期 Non-Goal，等用户反馈。数据已在 API 响应里，纯前端改动。
+- 是否要做跨任意版本（v1 vs v3，跳过 v2）的 diff？本期 Non-Goal（仅相邻），但 API 的 `from/to` 设计已支持任意对，只是 UI 当前只暴露相邻——前端改动即可启用。
+- 大文件阈值 10000 是否合适？等真实 agent 产物的行数分布数据再校准。
diff --git a/openspec/changes/html-content-diff/proposal.md b/openspec/changes/html-content-diff/proposal.md
new file mode 100644
index 0000000..c4ee873
--- /dev/null
+++ b/openspec/changes/html-content-diff/proposal.md
@@ -0,0 +1,33 @@
+## Why
+
+`version-chain-sessions` 已经把同产物的多次迭代串成 v1→v2→v3，并在预览页注入了版本时间线侧栏 + 相邻版本**元数据** diff（tags/category/project）。但用户最直接的下一个问题——"v2 的 HTML 到底改了哪几行"——还答不上。
+
+现在的 diff 只停留在 metadata 层面。对 agent 反复迭代的 HTML 产物，真正能解释"这一版改了什么"的是内容本身：新增了一个图表、改了某段文案、删了一列。元数据 diff 摸不到这些。这是版本链功能的"灵魂补全"——链化是骨架，内容 diff 才让时间线真正可读。
+
+需要在版本链之上补一层 HTML 行级 diff，让用户在时间线侧栏点开任意相邻版本就能看到红绿行，且**不引入新依赖、不破坏现有 chain 接口**。
+
+## What Changes
+
+- 新增纯函数行级 diff 算法（LCS 动态规划）于 `internal/session/htmldiff.go`，输出 `[]LineOp{Kind, Text, OldNo, NewNo}`。对超过 `MaxDiffLines`（10000 行）的输入返回跳过哨兵，避免 O(n*m) DP 拖垮请求。
+- 新增 `Store.DiffSessionHTML(fromSessionID, toSessionID)`：读两份 `StoredEntryFile` 离盘 diff（项目首个把 session 内容读进内存的代码，沿用 `store.Get` + `StoredEntryFile` 模式）；文件缺失降级为空内容而非报错。
+- 新增 `GET /api/sessions/{id}/diff?from=vN&to=vM`：`{id}` 是链上任意 session（用于解析链 + owner），`from/to` 是同链 1-based 版本号；返回 `{fromVersion, toVersion, lines:[{kind,text,oldNo,newNo}], summary:{added,removed}}`。跨链 / 越界 / from==to → 400。
+- 预览页版本时间线侧栏每个（有前驱的）版本项加"Show HTML diff"按钮：点击懒加载 diff 接口，红绿行内联展开；相等的上下文行折叠为"⋯ N unchanged ⋯"避免淹没改动；按钮旁显示 `+a −b` 摘要；再点折叠。
+- **不修改任何 DB schema**：diff 是纯计算，结果不入库。
+- **不引入任何新依赖**：LCS 手写，正面回应 `version-chain-sessions` Non-Goals 中的"无 diff 库"。
+- **向后兼容硬约束**：现有 `GET /api/sessions/{id}/chain` 响应逐字段不变（diff 走独立接口）；老 session 文件缺失时 diff 降级为空；不破坏现有 send/list/search/preview/chain 路径。
+
+## Capabilities
+
+### Modified Capabilities
+- `version-chain`: 在已落地的版本链（自动链化、时间线侧栏、元数据 diff）之上，新增相邻版本 HTML 内容的行级 diff 接口与时间线内联渲染。链化、链查询、元数据 diff 语义不变。
+
+<!-- 不新增 capability，本次是对 version-chain 能力的增量扩展（与元数据 diff 平行的"内容 diff"维度）。 -->
+
+## Impact
+
+- **数据层 / 算法**（`internal/session/`）：新增 `htmldiff.go`（`LineOp` / `LineOpKind` / `DiffLines` / `SplitLines` / `Summarize` / `MaxDiffLines` / `DiffTooLargeText`，纯函数无 Store 依赖）；`version.go` 新增 `DiffSessionHTML` + `readSessionHTML`（首个读 session 内容进内存的代码）。
+- **服务端**（`internal/server/`）：`server.go` 的 `routes()` switch 在 `/chain` 与 `/diff`（新增）之间插入 case；新增 `handleGetDiff` + `diffLine` / `diffResponse` / `diffSummary` 类型 + `parseDiffVersions` / `versionSessionID` 辅助函数。
+- **注入**（`internal/live/`）：`inject.go` 的 `versionDrawerCSS` 新增 `.sth-version-diffbtn` / `.sth-version-htmldiff` / `.hunk.{add,del,ctx,skip}` 规则；`versionDrawerJS` 的 `item()` 加 diff 按钮 + 容器，新增 `wireDiffButtons` / `renderHtmlDiff` / `formatBadge` 函数，`render()` 计算每个版本的前驱版本号。
+- **CLI**：无改动（diff 是浏览器侧能力，不在 CLI 暴露）。
+- **依赖**：**不新增任何依赖**。LCS 手写 ~60 行 Go，正面回应上一版 Non-Goals 的"无 diff 库"——这正是本期得以落地的关键（行级 diff 算法成熟、可控、可测，无需引入第三方库）。
+- **测试**：新增 `internal/session/htmldiff_test.go`（LCS 正确性 / 空 / 相同 / 全异 / 修改=先删后增 / 大文件保护 / SplitLines / Summarize / KindString）；`version_test.go` 增测 `DiffSessionHTML`（增删改 / 相同 / 文件缺失降级 / 未知 session / 非 nil）；`server_test.go` 增测 `TestGetDiffSuccess` / `TestGetDiffMissingParams` / `TestGetDiffVersionOutOfRange` / `TestGetDiffSameVersionRejected` / `TestGetDiffNotFound`。现有测试不改动即过。
diff --git a/openspec/changes/html-content-diff/specs/version-chain/spec.md b/openspec/changes/html-content-diff/specs/version-chain/spec.md
new file mode 100644
index 0000000..6fbcb99
--- /dev/null
+++ b/openspec/changes/html-content-diff/specs/version-chain/spec.md
@@ -0,0 +1,79 @@
+## ADDED Requirements
+
+### Requirement: HTML 内容 diff 接口
+The system SHALL expose `GET /api/sessions/{sessionId}/diff?from={vN}&to={vM}` computing a line-level diff between the entry HTML of two versions in the same chain. The `{sessionId}` in the path identifies any session in the chain (used to resolve chain membership and ownership); `from` and `to` are 1-based version numbers of live versions within that chain.
+
+The diff SHALL be computed by a longest-common-subsequence algorithm over the lines of each version's stored entry HTML file, producing an ordered list of line operations each classified as `equal`, `add`, or `delete`, with 1-based line numbers in the old (`oldNo`) and new (`newNo`) documents (0 when not applicable). The response SHALL include an additive summary (`added`, `removed` counts).
+
+The endpoint SHALL respect session ownership identically to the chain endpoint. When either version number does not correspond to a live version in the chain, or `from` equals `to`, or a parameter is missing or non-positive, the system SHALL return `400`. When the path session does not exist or is soft-deleted, the system SHALL return `404`.
+
+The diff computation SHALL be bounded: when either input exceeds a fixed line threshold, the system SHALL return a single sentinel line indicating the diff was skipped, rather than attempting the O(n*m) computation.
+
+#### Scenario: 相邻版本的内容 diff
+- **WHEN** a client requests `GET /api/sessions/<v2-id>/diff?from=1&to=2` for a two-version chain where v2 added one line
+- **THEN** the response status is `200`
+- **AND** `lines` contains one entry with `kind: "add"` carrying the added line's text and a positive `newNo`
+- **AND** `summary.added` is at least 1 and `summary.removed` is 0
+- **AND** `fromVersion` is 1 and `toVersion` is 2
+
+#### Scenario: 缺少 from 或 to 参数返回 400
+- **WHEN** a client requests `GET /api/sessions/<id>/diff?from=1` (missing `to`)
+- **THEN** the response status is `400`
+
+#### Scenario: 版本号越界返回 400
+- **WHEN** a client requests `from=1&to=99` on a chain with only two live versions
+- **THEN** the response status is `400`
+
+#### Scenario: from 等于 to 返回 400
+- **WHEN** a client requests `from=1&to=1`
+- **THEN** the response status is `400`
+
+#### Scenario: 不存在的 session 返回 404
+- **WHEN** a client requests `GET /api/sessions/nonexistent/diff?from=1&to=2`
+- **THEN** the response status is `404`
+
+#### Scenario: 软删 session 返回 404
+- **WHEN** the path session has been soft-deleted
+- **THEN** the response status is `404` (consistent with the chain endpoint's soft-delete visibility rule)
+
+#### Scenario: 老 session 文件缺失时降级为空内容
+- **WHEN** a version's stored entry file is missing from disk (legacy session or cleared uploads)
+- **THEN** the diff does not error
+- **AND** the missing side is treated as empty content (its lines register as deletions or additions relative to the other side)
+
+#### Scenario: 超大文件跳过 diff
+- **WHEN** either version's entry HTML exceeds the line threshold
+- **THEN** the response status is `200`
+- **AND** `lines` contains a single sentinel entry indicating the diff was skipped due to size
+
+### Requirement: 时间线 HTML diff 内联渲染
+The system SHALL inject, into the version-timeline drawer of each preview page, a "Show HTML diff" control on every timeline item that has a live predecessor version. Activating the control SHALL lazily fetch the content diff between the item and its predecessor and render it inline within the drawer, with added lines styled distinctly from removed lines, and consecutive unchanged lines collapsed so changes remain visible without scrolling.
+
+The predecessor SHALL be resolved as the live version with the largest version number strictly smaller than the current item's, so that soft-delete gaps (e.g. v1, v3 with v2 removed) still link v3 to v1. When a version has no live predecessor, no diff control SHALL be rendered.
+
+#### Scenario: 有前驱的版本显示 diff 按钮
+- **WHEN** the timeline renders a version that has a live predecessor
+- **THEN** a "Show HTML diff" button is visible on that timeline item
+- **AND** the button carries the predecessor and current version numbers
+
+#### Scenario: 无前驱的版本不显示 diff 按钮
+- **WHEN** the timeline renders the oldest live version (no predecessor)
+- **THEN** no "Show HTML diff" button is rendered on that item
+
+#### Scenario: 点击按钮懒加载并展开 diff
+- **WHEN** the user clicks the "Show HTML diff" button
+- **THEN** the diff endpoint is fetched for that version pair
+- **AND** the result renders inline with added and removed lines visually distinguished
+- **AND** consecutive unchanged lines are collapsed into a summary line rather than displayed individually
+
+#### Scenario: 再次点击折叠
+- **WHEN** the user clicks an already-expanded diff button again
+- **THEN** the diff content is collapsed without re-fetching
+
+#### Scenario: 软删空洞跳到更早前驱
+- **WHEN** a chain has live versions v1 and v3 (v2 soft-deleted)
+- **THEN** the v3 timeline item's "Show HTML diff" button compares v3 against v1
+
+#### Scenario: diff 拉取失败显示错误
+- **WHEN** the diff fetch returns a non-200 status or network error
+- **THEN** the inline container shows an error message and does not crash the timeline
diff --git a/openspec/changes/html-content-diff/tasks.md b/openspec/changes/html-content-diff/tasks.md
new file mode 100644
index 0000000..f77bf21
--- /dev/null
+++ b/openspec/changes/html-content-diff/tasks.md
@@ -0,0 +1,35 @@
+## 1. 算法层（internal/session/htmldiff.go）
+- [x] 1.1 定义 `LineOpKind`（Equal/Add/Delete）、`LineOp{Kind, Text, OldNo, NewNo}`、`KindString()`。
+- [x] 1.2 实现 `DiffLines(old, new []string) []LineOp`：LCS 动态规划（`dp[i][j]` 后缀 LCS），回溯生成 equal/add/delete 序列，修改=先 delete 后 add；1-based 行号。
+- [x] 1.3 实现 `SplitLines(text)`：按 `\n` 切，去尾空行（让 `"a\n"` 与 `"a"` 等价）。
+- [x] 1.4 实现 `Summarize(ops) DiffSummary{Added, Removed}`。
+- [x] 1.5 定义 `MaxDiffLines=10000` + `DiffTooLargeText`，超阈值返回单条哨兵 op；恰好等于阈值仍 diff。
+- [x] 1.6 `internal/session/htmldiff_test.go`：相同/纯增/纯删/修改=先删后增/重建双端性质校验/空输入/全异/大文件保护/SplitLines 尾换行/Summarize/KindString。
+
+## 2. 数据层（internal/session/version.go）
+- [x] 2.1 实现 `DiffSessionHTML(fromSessionID, toSessionID) ([]LineOp, error)`：`store.Get` 两份 → `os.ReadFile(StoredEntryFile)` → `DiffLines(SplitLines(...))`；任一 session 不存在返 `ErrSessionNotFound`；结果永不为 nil。
+- [x] 2.2 `readSessionHTML(sess)`：`StoredEntryFile` 优先，回退 `EntryFile`；任何 I/O 错误返空串（降级，老 session 无文件不报错）。
+- [x] 2.3 `version_test.go` 增测：增删改检测 / 相同文件全 equal / 文件缺失降级 / 未知 session 返 NotFound / 结果非 nil（用 `t.TempDir()` 写真实文件 + 新 helper `createChainedSessionWithFile`）。
+
+## 3. 服务端（internal/server/server.go）
+- [x] 3.1 `routes()` 在 `/chain` 后插入 `GET /api/sessions/{id}/diff` case（`hasPrefixSuffix` + `isExactSessionPath` 顺序）。
+- [x] 3.2 定义 `diffLine{Kind, Text, OldNo, NewNo}` / `diffResponse{FromVersion, ToVersion, Lines, Summary}` / `diffSummary{Added, Removed}`。
+- [x] 3.3 实现 `handleGetDiff`：`extractSessionIDFromMetaPath` / `requireSession` / `requireOwner` / `parseDiffVersions` / `GetChainOfSession` 解析链 / `versionSessionID` 校验 from/to 在同链 / `DiffSessionHTML` / 组装响应。
+- [x] 3.4 `parseDiffVersions`：from/to 必须为正整数，缺失/非数字→400；`versionSessionID`：按 versionNo 在 versions 里找 sessionId，找不到→400；from==to→400。
+- [x] 3.5 `server_test.go` 增测：`TestGetDiffSuccess`（验证 lines + summary + added 文本）/ `TestGetDiffMissingParams` / `TestGetDiffVersionOutOfRange` / `TestGetDiffSameVersionRejected` / `TestGetDiffNotFound`（用新 helper `createChainedSessionWithFile` 写真实文件）。
+
+## 4. 预览页注入（internal/live/inject.go）
+- [x] 4.1 `versionDrawerCSS` 新增：`.sth-version-diffbtn`（按钮 + badge）/ `.sth-version-htmldiff`（容器，monospace + max-height 滚动）/ `.hunk.add|.del|.ctx|.skip`（绿/红/灰/折叠样式），沿用 `!important` + `#sth-version-*` 命名空间。
+- [x] 4.2 `versionDrawerJS` 的 `render()`：计算每个版本的前驱 version_no（最大且严格小于当前 live version_no，兼容软删空洞 v1,v3）。
+- [x] 4.3 `item(v, diff, prevVersionNo)`：有前驱时渲染 `<button class="sth-version-diffbtn" data-from data-to>Show HTML diff</button>` + 空 `.sth-version-htmldiff` 容器。
+- [x] 4.4 `wireDiffButtons()`：点击按钮 → fetch `/api/sessions/{id}/diff?from&to` → 渲染进容器；首次拉取后标 `data-loaded`，再点切换展开/折叠 + 按钮文案。
+- [x] 4.5 `renderHtmlDiff(data)`：连续 equal 行折叠为单条 `⋯ N unchanged ⋯` skip 行，只保留 add/del；空改动显示 "No changes."。
+- [x] 4.6 `formatBadge(summary)`：按钮 badge 显示 `+a −b`。
+- [x] 4.7 `escapeHtml` 复用（diff 行文本先 escape 再包 `<span class="hunk">`，不产生 XSS）。
+
+## 5. 文档与校验
+- [x] 5.1 撰写 OpenSpec change：`openspec/changes/html-content-diff/` 全套（`.openspec.yaml` / `proposal.md` / `design.md` D19–D23 / `tasks.md` / `specs/version-chain/spec.md`）。
+- [x] 5.2 `go test ./...` 全绿。
+- [x] 5.3 `go vet ./...` 无警告。
+- [x] 5.4 `openspec validate html-content-diff` 通过。
+- [ ] 5.5 PR 合并后执行 `openspec archive html-content-diff`（跟随项目惯例，可批量整理时一并归档）。

From 47e68965c1f503ca5276867a4da96ecb259e7d54 Mon Sep 17 00:00:00 2001
From: svtter <svtter@qq.com>
Date: Sun, 2 Aug 2026 12:43:29 +0800
Subject: [PATCH 2/5] fix(version-chain): surface "diff too large" via explicit
 TooLarge flag (#84)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit 评审 (Major): renderHtmlDiff 把 DiffLines 返回的"超大文件跳过"
哨兵 (单条 LineOp{Kind: Equal, Text: DiffTooLargeText}) 当成普通 equal 行
折叠进了 "⋯ 1 unchanged line ⋯", 用户永远看不到"diff skipped"提示,
大文件点 diff 看起来像"没改动", 违背 design.md D22。

修法 (采用评审推荐的 robust 方案, 非 magic string 匹配):
- diffResponse 新增显式 TooLarge bool 字段
- handleGetDiff 由 len(ops)==1 && ops[0].Text==DiffTooLargeText 计算
- renderHtmlDiff 优先判 data.tooLarge -> 渲染 .hunk.skip 行

测试: 新增 TestGetDiffTooLargeFilesSkipped, 构造 MaxDiffLines+1 行输入,
断言 tooLarge=true / 单条哨兵 / summary 归零。
go test ./... 全绿, go vet 无警告, openspec validate 通过。
---
 internal/live/inject.go                     |  6 +++
 internal/server/server.go                   | 10 ++++
 internal/server/server_test.go              | 56 +++++++++++++++++++++
 openspec/changes/html-content-diff/tasks.md |  4 ++
 4 files changed, 76 insertions(+)

diff --git a/internal/live/inject.go b/internal/live/inject.go
index 134b950..63d103e 100644
--- a/internal/live/inject.go
+++ b/internal/live/inject.go
@@ -326,6 +326,12 @@ const versionDrawerJS = `<script>
     if(!data||!data.lines||data.lines.length===0){
       return '<div class="sth-version-htmldiff-empty">No changes.</div>';
     }
+    // Explicit "diff skipped: input too large" signal from the server. Render
+    // the sentinel verbatim as a skip hunk rather than letting the generic
+    // equal-line collapsing logic swallow it into "N unchanged lines".
+    if(data.tooLarge){
+      return '<span class="hunk skip">'+escapeHtml(data.lines[0].text)+'</span>';
+    }
     var out=[];
     var ctxRun=0;
     function flushCtx(){
diff --git a/internal/server/server.go b/internal/server/server.go
index b393603..7ae3276 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -1946,11 +1946,16 @@ type diffLine struct {
 // diffResponse is the payload of GET /api/sessions/{id}/diff?from=vN&to=vM.
 // Lines is the full line-level diff in reading order; Summary gives additive
 // counts so the UI can render a "+a −b" hint without scanning the slice.
+// TooLarge is true when either input exceeded MaxDiffLines and the diff was
+// skipped: Lines then carries a single explanatory sentinel line and Summary
+// is zeroed. The UI branches on TooLarge rather than sniffing the sentinel
+// text, so the contract is explicit and locale-independent.
 type diffResponse struct {
 	FromVersion int         `json:"fromVersion"`
 	ToVersion   int         `json:"toVersion"`
 	Lines       []diffLine  `json:"lines"`
 	Summary     diffSummary `json:"summary"`
+	TooLarge    bool        `json:"tooLarge"`
 }
 
 type diffSummary struct {
@@ -2037,6 +2042,10 @@ func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
 		})
 	}
 	summary := session.Summarize(ops)
+	// DiffLines signals "input too large" by returning a single sentinel op
+	// carrying DiffTooLargeText; surface it as an explicit boolean so the UI
+	// does not have to match a magic string.
+	tooLarge := len(ops) == 1 && ops[0].Text == session.DiffTooLargeText
 
 	writeJSON(w, http.StatusOK, diffResponse{
 		FromVersion: fromVer,
@@ -2046,6 +2055,7 @@ func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
 			Added:   summary.Added,
 			Removed: summary.Removed,
 		},
+		TooLarge: tooLarge,
 	})
 }
 
diff --git a/internal/server/server_test.go b/internal/server/server_test.go
index bc0bd90..0f1b38a 100644
--- a/internal/server/server_test.go
+++ b/internal/server/server_test.go
@@ -1926,3 +1926,59 @@ func TestGetDiffNotFound(t *testing.T) {
 		t.Fatalf("expected 404, got %d", resp.StatusCode)
 	}
 }
+
+// TestGetDiffTooLargeFilesSkipped is the regression guard for the CodeRabbit
+// finding: when either input exceeds MaxDiffLines, the response carries an
+// explicit tooLarge=true flag (rather than silently looking like "no changes"),
+// and the UI can branch on the boolean instead of sniffing a magic string.
+func TestGetDiffTooLargeFilesSkipped(t *testing.T) {
+	t.Parallel()
+
+	store := newTestStore(t)
+
+	// Build HTML files just past the MaxDiffLines threshold. DiffLines checks
+	// the threshold before allocating the DP table, so this stays fast.
+	big := make([]byte, 0, (session.MaxDiffLines+1)*6)
+	for i := 0; i <= session.MaxDiffLines; i++ {
+		big = append(big, "<div></div>\n"...)
+	}
+	createChainedSessionWithFile(t, store, string(big), "proj", "cat")
+	v2 := createChainedSessionWithFile(t, store, string(big), "proj", "cat")
+
+	srv, err := New("127.0.0.1", 0, store, "", 0, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := srv.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = srv.Stop(ctx)
+	}()
+
+	resp, err := http.Get(srv.Origin() + "/api/sessions/" + v2 + "/diff?from=1&to=2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, body)
+	}
+
+	var result diffResponse
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		t.Fatal(err)
+	}
+	if !result.TooLarge {
+		t.Fatalf("expected tooLarge=true for input exceeding MaxDiffLines; got %+v", result)
+	}
+	if len(result.Lines) != 1 {
+		t.Fatalf("expected 1 sentinel line; got %d", len(result.Lines))
+	}
+	if result.Summary.Added != 0 || result.Summary.Removed != 0 {
+		t.Fatalf("expected zero summary for skipped diff; got %+v", result.Summary)
+	}
+}
diff --git a/openspec/changes/html-content-diff/tasks.md b/openspec/changes/html-content-diff/tasks.md
index f77bf21..76f25e6 100644
--- a/openspec/changes/html-content-diff/tasks.md
+++ b/openspec/changes/html-content-diff/tasks.md
@@ -33,3 +33,7 @@
 - [x] 5.3 `go vet ./...` 无警告。
 - [x] 5.4 `openspec validate html-content-diff` 通过。
 - [ ] 5.5 PR 合并后执行 `openspec archive html-content-diff`（跟随项目惯例，可批量整理时一并归档）。
+
+## 6. PR review 修复（#84 CodeRabbit 评审）
+- [x] 6.1 `renderHtmlDiff` 把"diff 太大"哨兵当普通 equal 行折叠（Major）：`diffResponse` 新增显式 `TooLarge bool` 字段，`handleGetDiff` 由 `len(ops)==1 && ops[0].Text==DiffTooLargeText` 计算；前端 `renderHtmlDiff` 优先判 `data.tooLarge` 渲染为 `.hunk.skip` 行，不靠 magic string。
+- [x] 6.2 新增 `TestGetDiffTooLargeFilesSkipped`：构造 `MaxDiffLines+1` 行输入，断言响应 `tooLarge=true`、`lines` 单条哨兵、`summary` 归零。

From 8628e1a82d6bde99c0520dc39c27f7ffcea535b7 Mon Sep 17 00:00:00 2001
From: svtter <svtter@qq.com>
Date: Mon, 3 Aug 2026 20:00:25 +0800
Subject: [PATCH 3/5] fix(version-chain): decouple TooLarge signal from op text
 via DiffResult (#84)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit 第二轮评审 (Minor): 上一轮修复让 handleGetDiff 用
len(ops)==1 && ops[0].Text==DiffTooLargeText 推断 TooLarge, 但这会把内容
恰好等于 DiffTooLargeText 的合法单行 HTML 文档误判为"太大跳过"——正是
上一轮评审自己警告的 magic-string 反模式, 我只在前端避免了, 后端计算
boolean 时又踩回去了。

根因: "太大"是输入规模的属性, 不应从内容文本推断。

修法 (把信号从 op 文本彻底解耦):
- DiffLines 改返回 DiffResult{Ops []LineOp, TooLarge bool}
- DiffSessionHTML 透传 DiffResult (不再返回裸 []LineOp)
- handleGetDiff 直接用 result.TooLarge, 不再读任何文本
- 前端 renderHtmlDiff 已判 data.tooLarge, 无需改动

回归测试:
- TestDiffLines_SentinelTextContentIsNotMisclassified: 两份内容等于
  DiffTooLargeText 的相同单行文档, 断言 TooLarge=false 且为普通 equal op
- TestDiffLines_TooLargeIsSkipped 改用 result.TooLarge 断言

文档同步: design.md D22 重写为"显式 TooLarge 字段而非文本推断";
spec.md 新增"内容等于哨兵文本不被误判" scenario; tasks.md 第 6 节更新。

go test ./... 全绿, go vet 无警告, openspec validate 通过。
---
 internal/server/server.go                     | 17 +++---
 internal/session/htmldiff.go                  | 36 +++++++++----
 internal/session/htmldiff_test.go             | 54 +++++++++++++------
 internal/session/version.go                   | 22 ++++----
 internal/session/version_test.go              | 23 ++++----
 openspec/changes/html-content-diff/design.md  |  7 +--
 .../specs/version-chain/spec.md               | 12 ++++-
 openspec/changes/html-content-diff/tasks.md   |  5 +-
 8 files changed, 113 insertions(+), 63 deletions(-)

diff --git a/internal/server/server.go b/internal/server/server.go
index 7ae3276..59f7a17 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -2022,7 +2022,7 @@ func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	ops, err := s.store.DiffSessionHTML(fromSID, toSID)
+	result, err := s.store.DiffSessionHTML(fromSID, toSID)
 	if err != nil {
 		if errors.Is(err, session.ErrSessionNotFound) {
 			writeJSONError(w, http.StatusNotFound, "Session not found.")
@@ -2032,8 +2032,8 @@ func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	lines := make([]diffLine, 0, len(ops))
-	for _, op := range ops {
+	lines := make([]diffLine, 0, len(result.Ops))
+	for _, op := range result.Ops {
 		lines = append(lines, diffLine{
 			Kind:  op.KindString(),
 			Text:  op.Text,
@@ -2041,11 +2041,7 @@ func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
 			NewNo: op.NewNo,
 		})
 	}
-	summary := session.Summarize(ops)
-	// DiffLines signals "input too large" by returning a single sentinel op
-	// carrying DiffTooLargeText; surface it as an explicit boolean so the UI
-	// does not have to match a magic string.
-	tooLarge := len(ops) == 1 && ops[0].Text == session.DiffTooLargeText
+	summary := session.Summarize(result.Ops)
 
 	writeJSON(w, http.StatusOK, diffResponse{
 		FromVersion: fromVer,
@@ -2055,7 +2051,10 @@ func (s *Server) handleGetDiff(w http.ResponseWriter, r *http.Request) {
 			Added:   summary.Added,
 			Removed: summary.Removed,
 		},
-		TooLarge: tooLarge,
+		// TooLarge is propagated verbatim from the diff layer's explicit
+		// signal rather than inferred from op text, so a legitimate document
+		// whose content equals DiffTooLargeText is not misclassified.
+		TooLarge: result.TooLarge,
 	})
 }
 
diff --git a/internal/session/htmldiff.go b/internal/session/htmldiff.go
index 77f2061..c1fdfc9 100644
--- a/internal/session/htmldiff.go
+++ b/internal/session/htmldiff.go
@@ -36,16 +36,29 @@ func (op LineOp) KindString() string {
 
 // MaxDiffLines guards against pathological inputs. Above this many lines in
 // either side, the LCS dynamic program (O(n*m) time and memory) becomes
-// expensive; DiffLines returns a single sentinel op instead so callers can
-// render a "too large to diff" notice without blocking. The threshold is
-// generous for hand-authored / agent-generated HTML (typically < 2000 lines).
+// expensive; DiffLines signals TooLarge in its DiffResult instead of running
+// the computation, so callers can render a "too large to diff" notice without
+// blocking. The threshold is generous for hand-authored / agent-generated
+// HTML (typically < 2000 lines).
 const MaxDiffLines = 10000
 
-// DiffTooLarge is returned as the sole LineOp when either input exceeds
-// MaxDiffLines. Its Kind is LineEqual so callers treating the slice as a list
-// of ops can still iterate; the Text carries an explanatory message.
+// DiffTooLargeText is the explanatory text placed in the sole sentinel op when
+// DiffResult.TooLarge is true. It is purely informational; the TooLarge
+// boolean — not this string — is the authoritative signal, so a legitimate
+// one-line document whose content happens to equal this string is not
+// misclassified.
 const DiffTooLargeText = "[diff skipped: file exceeds MaxDiffLines]"
 
+// DiffResult is the return value of DiffLines. Ops is the ordered line-level
+// diff (empty when TooLarge is true, in which case a single explanatory
+// sentinel op is still appended so UIs that ignore TooLarge degrade sanely).
+// TooLarge is the explicit, content-independent "input exceeded MaxDiffLines"
+// signal.
+type DiffResult struct {
+	Ops      []LineOp
+	TooLarge bool
+}
+
 // DiffLines computes a line-level diff between oldLines and newLines using the
 // classic LCS dynamic-programming algorithm, then walks the DP table to emit
 // a sequence of LineOps in reading order (deletions before insertions when
@@ -53,10 +66,13 @@ const DiffTooLargeText = "[diff skipped: file exceeds MaxDiffLines]"
 //
 // Either input being empty is handled naturally (an empty old side makes
 // every new line an addition, and vice versa). Inputs exceeding MaxDiffLines
-// on either side yield DiffTooLarge.
-func DiffLines(oldLines, newLines []string) []LineOp {
+// on either side yield DiffResult{TooLarge: true} with a single sentinel op.
+func DiffLines(oldLines, newLines []string) DiffResult {
 	if len(oldLines) > MaxDiffLines || len(newLines) > MaxDiffLines {
-		return []LineOp{{Kind: LineEqual, Text: DiffTooLargeText}}
+		return DiffResult{
+			Ops:      []LineOp{{Kind: LineEqual, Text: DiffTooLargeText}},
+			TooLarge: true,
+		}
 	}
 
 	n, m := len(oldLines), len(newLines)
@@ -112,7 +128,7 @@ func DiffLines(oldLines, newLines []string) []LineOp {
 		newNo++
 	}
 
-	return ops
+	return DiffResult{Ops: ops}
 }
 
 // SplitLines splits text into lines, preserving content but dropping the
diff --git a/internal/session/htmldiff_test.go b/internal/session/htmldiff_test.go
index 1a6952c..0b5e4b7 100644
--- a/internal/session/htmldiff_test.go
+++ b/internal/session/htmldiff_test.go
@@ -22,7 +22,7 @@ func opsSummary(ops []LineOp) (equal, added, deleted int) {
 func TestDiffLines_IdenticalInputsAreAllEqual(t *testing.T) {
 	t.Parallel()
 	old := []string{"<html>", "<body>", "</body>", "</html>"}
-	ops := DiffLines(old, old)
+	ops := DiffLines(old, old).Ops
 
 	eq, add, del := opsSummary(ops)
 	if add != 0 || del != 0 {
@@ -43,7 +43,7 @@ func TestDiffLines_IdenticalInputsAreAllEqual(t *testing.T) {
 
 func TestDiffLines_PureAddition(t *testing.T) {
 	t.Parallel()
-	ops := DiffLines([]string{"a", "c"}, []string{"a", "b", "c"})
+	ops := DiffLines([]string{"a", "c"}, []string{"a", "b", "c"}).Ops
 
 	eq, add, del := opsSummary(ops)
 	if add != 1 || del != 0 || eq != 2 {
@@ -69,7 +69,7 @@ func TestDiffLines_PureAddition(t *testing.T) {
 
 func TestDiffLines_PureDeletion(t *testing.T) {
 	t.Parallel()
-	ops := DiffLines([]string{"a", "b", "c"}, []string{"a", "c"})
+	ops := DiffLines([]string{"a", "b", "c"}, []string{"a", "c"}).Ops
 
 	eq, add, del := opsSummary(ops)
 	if add != 0 || del != 1 || eq != 2 {
@@ -92,7 +92,7 @@ func TestDiffLines_PureDeletion(t *testing.T) {
 func TestDiffLines_ModificationIsDelThenAdd(t *testing.T) {
 	t.Parallel()
 	// Changing the middle line: old has "old", new has "new" in the same slot.
-	ops := DiffLines([]string{"a", "old", "c"}, []string{"a", "new", "c"})
+	ops := DiffLines([]string{"a", "old", "c"}, []string{"a", "new", "c"}).Ops
 
 	eq, add, del := opsSummary(ops)
 	if add != 1 || del != 1 || eq != 2 {
@@ -115,7 +115,7 @@ func TestDiffLines_ReconstructsBothSides(t *testing.T) {
 	// Property test: replaying equal+delete ops yields old; equal+add yields new.
 	old := []string{"<html>", "<head>", "<title>x</title>", "</head>", "<body>", "</body>", "</html>"}
 	new := []string{"<html>", "<head>", "<title>y</title>", "<meta charset='utf-8'>", "</head>", "<body>", "</body>", "</html>"}
-	ops := DiffLines(old, new)
+	ops := DiffLines(old, new).Ops
 
 	var rebuiltOld, rebuiltNew strings.Builder
 	for _, op := range ops {
@@ -143,16 +143,16 @@ func TestDiffLines_ReconstructsBothSides(t *testing.T) {
 func TestDiffLines_EmptyInputs(t *testing.T) {
 	t.Parallel()
 	// Both empty -> no ops.
-	if ops := DiffLines(nil, nil); len(ops) != 0 {
+	if ops := DiffLines(nil, nil).Ops; len(ops) != 0 {
 		t.Fatalf("empty/empty should yield no ops; got %d", len(ops))
 	}
 	// Empty old -> everything added.
-	ops := DiffLines(nil, []string{"a", "b"})
+	ops := DiffLines(nil, []string{"a", "b"}).Ops
 	if len(ops) != 2 || ops[0].Kind != LineAdd || ops[1].Kind != LineAdd {
 		t.Fatalf("empty old should yield 2 adds; got %+v", ops)
 	}
 	// Empty new -> everything deleted.
-	ops = DiffLines([]string{"a", "b"}, nil)
+	ops = DiffLines([]string{"a", "b"}, nil).Ops
 	if len(ops) != 2 || ops[0].Kind != LineDelete || ops[1].Kind != LineDelete {
 		t.Fatalf("empty new should yield 2 deletes; got %+v", ops)
 	}
@@ -162,7 +162,7 @@ func TestDiffLines_CompletelyDifferent(t *testing.T) {
 	t.Parallel()
 	old := []string{"x", "y", "z"}
 	new := []string{"p", "q", "r"}
-	ops := DiffLines(old, new)
+	ops := DiffLines(old, new).Ops
 
 	eq, add, del := opsSummary(ops)
 	if eq != 0 || add != 3 || del != 3 {
@@ -176,19 +176,41 @@ func TestDiffLines_TooLargeIsSkipped(t *testing.T) {
 	for i := range huge {
 		huge[i] = "line"
 	}
-	ops := DiffLines(huge, []string{"a"})
-	if len(ops) != 1 {
-		t.Fatalf("expected 1 sentinel op for too-large input; got %d", len(ops))
+	result := DiffLines(huge, []string{"a"})
+	if !result.TooLarge {
+		t.Fatal("expected TooLarge=true for input exceeding MaxDiffLines")
 	}
-	if ops[0].Text != DiffTooLargeText {
-		t.Fatalf("expected sentinel text %q, got %q", DiffTooLargeText, ops[0].Text)
+	if len(result.Ops) != 1 {
+		t.Fatalf("expected 1 sentinel op for too-large input; got %d", len(result.Ops))
+	}
+	if result.Ops[0].Text != DiffTooLargeText {
+		t.Fatalf("expected sentinel text %q, got %q", DiffTooLargeText, result.Ops[0].Text)
 	}
 
 	// Exactly at the threshold is still diffed.
 	atLimit := make([]string, MaxDiffLines)
 	big := DiffLines(atLimit, atLimit)
-	if len(big) != MaxDiffLines {
-		t.Fatalf("input at limit should still be diffed; got %d ops", len(big))
+	if big.TooLarge {
+		t.Fatal("input at limit should not be flagged TooLarge")
+	}
+	if len(big.Ops) != MaxDiffLines {
+		t.Fatalf("input at limit should still be diffed; got %d ops", len(big.Ops))
+	}
+}
+
+// TestDiffLines_SentinelTextContentIsNotMisclassified is the regression guard
+// for the CodeRabbit finding: a legitimate document whose single line equals
+// DiffTooLargeText must NOT be reported as TooLarge. TooLarge is an explicit
+// signal from the diff layer based on input size, never inferred from content.
+func TestDiffLines_SentinelTextContentIsNotMisclassified(t *testing.T) {
+	t.Parallel()
+	// Two identical single-line documents whose content is the sentinel text.
+	result := DiffLines([]string{DiffTooLargeText}, []string{DiffTooLargeText})
+	if result.TooLarge {
+		t.Fatalf("legitimate content equal to DiffTooLargeText must not be flagged TooLarge; got %+v", result)
+	}
+	if len(result.Ops) != 1 || result.Ops[0].Kind != LineEqual {
+		t.Fatalf("expected a single equal op for identical sentinel-text docs; got %+v", result.Ops)
 	}
 }
 
diff --git a/internal/session/version.go b/internal/session/version.go
index e6ae4fe..cf99bce 100644
--- a/internal/session/version.go
+++ b/internal/session/version.go
@@ -405,31 +405,33 @@ func chainVersionFrom(sessionID string, sess Session, meta DocumentMetadata, ver
 // graceful degradation keeps the diff endpoint usable across mixed data.
 //
 // Either session being absent from the store returns ErrSessionNotFound.
-// The result is never nil: callers can safely len()/range over it.
-func (s *Store) DiffSessionHTML(fromSessionID, toSessionID string) ([]LineOp, error) {
+// The returned DiffResult carries both the ordered ops and an explicit
+// TooLarge flag (set when either input exceeded MaxDiffLines) so callers do
+// not have to infer "too large" from op text.
+func (s *Store) DiffSessionHTML(fromSessionID, toSessionID string) (DiffResult, error) {
 	fromSess, found, err := s.Get(fromSessionID)
 	if err != nil {
-		return nil, err
+		return DiffResult{}, err
 	}
 	if !found {
-		return nil, ErrSessionNotFound
+		return DiffResult{}, ErrSessionNotFound
 	}
 	toSess, found, err := s.Get(toSessionID)
 	if err != nil {
-		return nil, err
+		return DiffResult{}, err
 	}
 	if !found {
-		return nil, ErrSessionNotFound
+		return DiffResult{}, ErrSessionNotFound
 	}
 
 	oldText := readSessionHTML(fromSess)
 	newText := readSessionHTML(toSess)
 
-	ops := DiffLines(SplitLines(oldText), SplitLines(newText))
-	if ops == nil {
-		ops = []LineOp{}
+	result := DiffLines(SplitLines(oldText), SplitLines(newText))
+	if result.Ops == nil {
+		result.Ops = []LineOp{}
 	}
-	return ops, nil
+	return result, nil
 }
 
 // readSessionHTML reads the session's entry HTML, returning "" for any I/O
diff --git a/internal/session/version_test.go b/internal/session/version_test.go
index ab20bae..b9c5e5a 100644
--- a/internal/session/version_test.go
+++ b/internal/session/version_test.go
@@ -496,10 +496,11 @@ func TestDiffSessionHTML_DetectsAddedLines(t *testing.T) {
 	v1 := createChainedSessionWithFile(t, store, "<html>\n<body>\n<h1>old</h1>\n</body>\n</html>\n", "proj", "cat")
 	v2 := createChainedSessionWithFile(t, store, "<html>\n<body>\n<h1>old</h1>\n<p>new para</p>\n</body>\n</html>\n", "proj", "cat")
 
-	ops, err := store.DiffSessionHTML(v1, v2)
+	result, err := store.DiffSessionHTML(v1, v2)
 	if err != nil {
 		t.Fatalf("DiffSessionHTML: %v", err)
 	}
+	ops := result.Ops
 	eq, add, del := opsSummary(ops)
 	if del != 0 {
 		t.Fatalf("expected 0 deletions for pure addition; got %d (ops=%+v)", del, ops)
@@ -528,13 +529,13 @@ func TestDiffSessionHTML_DetectsModifiedAndDeletedLines(t *testing.T) {
 	v1 := createChainedSessionWithFile(t, store, "<h1>a</h1>\n<h2>b</h2>\n<h3>c</h3>\n", "proj", "cat")
 	v2 := createChainedSessionWithFile(t, store, "<h1>A</h1>\n<h3>c</h3>\n", "proj", "cat")
 
-	ops, err := store.DiffSessionHTML(v1, v2)
+	result, err := store.DiffSessionHTML(v1, v2)
 	if err != nil {
 		t.Fatalf("DiffSessionHTML: %v", err)
 	}
-	_, add, del := opsSummary(ops)
+	_, add, del := opsSummary(result.Ops)
 	if add != 1 || del != 2 {
-		t.Fatalf("expected add=1 del=2; got add=%d del=%d (ops=%+v)", add, del, ops)
+		t.Fatalf("expected add=1 del=2; got add=%d del=%d (ops=%+v)", add, del, result.Ops)
 	}
 }
 
@@ -546,11 +547,11 @@ func TestDiffSessionHTML_IdenticalFilesYieldAllEqual(t *testing.T) {
 	v1 := createChainedSessionWithFile(t, store, content, "proj", "cat")
 	v2 := createChainedSessionWithFile(t, store, content, "proj", "cat")
 
-	ops, err := store.DiffSessionHTML(v1, v2)
+	result, err := store.DiffSessionHTML(v1, v2)
 	if err != nil {
 		t.Fatalf("DiffSessionHTML: %v", err)
 	}
-	_, add, del := opsSummary(ops)
+	_, add, del := opsSummary(result.Ops)
 	if add != 0 || del != 0 {
 		t.Fatalf("identical files should have no add/del; got add=%d del=%d", add, del)
 	}
@@ -569,13 +570,13 @@ func TestDiffSessionHTML_MissingFileDegradesToEmpty(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	ops, err := store.DiffSessionHTML(v1, v2Sess.ID)
+	result, err := store.DiffSessionHTML(v1, v2Sess.ID)
 	if err != nil {
 		t.Fatalf("missing file should not error; got %v", err)
 	}
-	_, add, del := opsSummary(ops)
+	_, add, del := opsSummary(result.Ops)
 	if add != 0 || del != 1 {
-		t.Fatalf("expected add=0 del=1 for missing v2 file; got add=%d del=%d (ops=%+v)", add, del, ops)
+		t.Fatalf("expected add=0 del=1 for missing v2 file; got add=%d del=%d (ops=%+v)", add, del, result.Ops)
 	}
 }
 
@@ -600,11 +601,11 @@ func TestDiffSessionHTML_NeverNil(t *testing.T) {
 	v1 := createChainedSessionWithFile(t, store, "", "proj", "cat")
 	v2 := createChainedSessionWithFile(t, store, "", "proj", "cat")
 
-	ops, err := store.DiffSessionHTML(v1, v2)
+	result, err := store.DiffSessionHTML(v1, v2)
 	if err != nil {
 		t.Fatalf("DiffSessionHTML: %v", err)
 	}
-	if ops == nil {
+	if result.Ops == nil {
 		t.Fatal("expected non-nil ops slice even for empty input")
 	}
 }
diff --git a/openspec/changes/html-content-diff/design.md b/openspec/changes/html-content-diff/design.md
index 33bed2e..99ae4f0 100644
--- a/openspec/changes/html-content-diff/design.md
+++ b/openspec/changes/html-content-diff/design.md
@@ -45,10 +45,11 @@
 **`{id}` 的语义**：path 里的 `{id}` 是链上**任意** session（用于解析链归属 + owner 校验），`from/to` 是同链版本号。这样从任何一个版本预览页都能拉同链任意相邻对的 diff，无需先定位"链主 session"。
 **备选**：合并进 chain 接口一次性返回所有相邻 diff——否决，见上；每次开侧栏读 N 次磁盘 + N 次 LCS，浪费且延迟高。
 
-### D22: 大文件保护——超 `MaxDiffLines` 返回跳过哨兵
-**选择**：`MaxDiffLines = 10000`。任一侧超阈值时 `DiffLines` 返回单条 `LineOp{Kind: Equal, Text: DiffTooLargeText}`（`[diff skipped: file exceeds MaxDiffLines]`），前端原样渲染为一条灰色 skip 行。**恰好等于阈值仍正常 diff**。
+### D22: 大文件保护——超 `MaxDiffLines` 返回显式 `TooLarge` 信号
+**选择**：`MaxDiffLines = 10000`。任一侧超阈值时 `DiffLines` 返回 `DiffResult{Ops: [单条哨兵], TooLarge: true}`——`TooLarge` 是**显式结构化字段**，不依赖 op 文本。`DiffSessionHTML` 透传 `DiffResult`，`handleGetDiff` 直接用 `result.TooLarge` 设响应的 `tooLarge` 字段，前端 `renderHtmlDiff` 优先判 `data.tooLarge` 渲染为灰色 skip 行。**恰好等于阈值仍正常 diff**（`TooLarge=false`）。
 **理由**：LCS 是 O(n*m) DP，两个 10000 行文件 = 10^8 单元格 × 8 字节 int ≈ 800MB 内存 + 秒级 CPU，会拖垮请求。10000 行对 agent 产物（通常 < 2000 行）是极宽松的上限，正常用例永远触不到；真触到时跳过比卡死好。阈值是常量，将来按需调整。
-**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离）——对大文件更快但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过。
+**为何 `TooLarge` 是字段而非文本推断**：若用 `ops[0].Text == DiffTooLargeText` 判断，一个内容恰好等于 `[diff skipped: file exceeds MaxDiffLines]` 的合法单行 HTML 文档（如讲解本功能的文档站）会被误判为"太大跳过"。`TooLarge` 作为显式字段彻底根除这类内容碰撞——"太大"是输入规模的属性，与内容无关。
+**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离）——对大文件更快但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过；(c) 用哨兵 op 文本作为信号——否决，内容碰撞风险（见上）。
 
 ### D23: diff 不入库——纯即时计算
 **选择**：`DiffSessionHTML` 每次调用都读两份文件 + 算 LCS，结果**不写 DB**。
diff --git a/openspec/changes/html-content-diff/specs/version-chain/spec.md b/openspec/changes/html-content-diff/specs/version-chain/spec.md
index 6fbcb99..ba036ea 100644
--- a/openspec/changes/html-content-diff/specs/version-chain/spec.md
+++ b/openspec/changes/html-content-diff/specs/version-chain/spec.md
@@ -7,7 +7,7 @@ The diff SHALL be computed by a longest-common-subsequence algorithm over the li
 
 The endpoint SHALL respect session ownership identically to the chain endpoint. When either version number does not correspond to a live version in the chain, or `from` equals `to`, or a parameter is missing or non-positive, the system SHALL return `400`. When the path session does not exist or is soft-deleted, the system SHALL return `404`.
 
-The diff computation SHALL be bounded: when either input exceeds a fixed line threshold, the system SHALL return a single sentinel line indicating the diff was skipped, rather than attempting the O(n*m) computation.
+The diff computation SHALL be bounded: when either input exceeds a fixed line threshold, the system SHALL set the response's `tooLarge` flag to `true` and include a single explanatory line, rather than attempting the O(n*m) computation. The `tooLarge` flag is the authoritative signal of the skip condition; a legitimate document whose content happens to match the explanatory text SHALL NOT be misclassified as too large.
 
 #### Scenario: 相邻版本的内容 diff
 - **WHEN** a client requests `GET /api/sessions/<v2-id>/diff?from=1&to=2` for a two-version chain where v2 added one line
@@ -44,7 +44,15 @@ The diff computation SHALL be bounded: when either input exceeds a fixed line th
 #### Scenario: 超大文件跳过 diff
 - **WHEN** either version's entry HTML exceeds the line threshold
 - **THEN** the response status is `200`
-- **AND** `lines` contains a single sentinel entry indicating the diff was skipped due to size
+- **AND** the response's `tooLarge` field is `true`
+- **AND** `lines` contains a single explanatory entry indicating the diff was skipped due to size
+- **AND** `summary.added` and `summary.removed` are both `0`
+
+#### Scenario: 内容等于哨兵文本的合法文档不被误判
+- **WHEN** a version's entry HTML is a single line whose text equals the skip-explanatory message
+- **AND** neither input exceeds the line threshold
+- **THEN** the response's `tooLarge` field is `false`
+- **AND** the line is treated as ordinary content (an `equal` op when both sides match)
 
 ### Requirement: 时间线 HTML diff 内联渲染
 The system SHALL inject, into the version-timeline drawer of each preview page, a "Show HTML diff" control on every timeline item that has a live predecessor version. Activating the control SHALL lazily fetch the content diff between the item and its predecessor and render it inline within the drawer, with added lines styled distinctly from removed lines, and consecutive unchanged lines collapsed so changes remain visible without scrolling.
diff --git a/openspec/changes/html-content-diff/tasks.md b/openspec/changes/html-content-diff/tasks.md
index 76f25e6..f55f257 100644
--- a/openspec/changes/html-content-diff/tasks.md
+++ b/openspec/changes/html-content-diff/tasks.md
@@ -35,5 +35,6 @@
 - [ ] 5.5 PR 合并后执行 `openspec archive html-content-diff`（跟随项目惯例，可批量整理时一并归档）。
 
 ## 6. PR review 修复（#84 CodeRabbit 评审）
-- [x] 6.1 `renderHtmlDiff` 把"diff 太大"哨兵当普通 equal 行折叠（Major）：`diffResponse` 新增显式 `TooLarge bool` 字段，`handleGetDiff` 由 `len(ops)==1 && ops[0].Text==DiffTooLargeText` 计算；前端 `renderHtmlDiff` 优先判 `data.tooLarge` 渲染为 `.hunk.skip` 行，不靠 magic string。
-- [x] 6.2 新增 `TestGetDiffTooLargeFilesSkipped`：构造 `MaxDiffLines+1` 行输入，断言响应 `tooLarge=true`、`lines` 单条哨兵、`summary` 归零。
+- [x] 6.1 `renderHtmlDiff` 把"diff 太大"哨兵当普通 equal 行折叠（Major，第一轮）：`diffResponse` 新增显式 `TooLarge bool` 字段；前端 `renderHtmlDiff` 优先判 `data.tooLarge` 渲染为 `.hunk.skip` 行。
+- [x] 6.2 `handleGetDiff` 用文本推断 `TooLarge` 会被内容恰好等于 `DiffTooLargeText` 的合法单行文件误判（Minor，第二轮）：把"太大"信号从 op 文本解耦——`DiffLines` 改返回 `DiffResult{Ops, TooLarge}`，`DiffSessionHTML` 透传 `DiffResult`，`handleGetDiff` 直接用 `result.TooLarge` 不再读文本。
+- [x] 6.3 新增 `TestDiffLines_SentinelTextContentIsNotMisclassified`（算法层碰撞回归）+ `TestGetDiffTooLargeFilesSkipped`（HTTP 层 tooLarge 字段）。

From 912e6029e2d7f14b98396d3562954395bb33fd60 Mon Sep 17 00:00:00 2001
From: svtter <svtter@qq.com>
Date: Mon, 10 Aug 2026 10:20:40 +0800
Subject: [PATCH 4/5] fix(version-chain): bound LCS table by cell budget, fix
 DiffResult comment (#84)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit 第三轮评审 (Major + Minor):

#3 (Major) cell 预算——单侧 MaxDiffLines 挡不住两侧各大的乘积爆炸
  原来只检查 len > MaxDiffLines (单侧 10000), 但两个各 10000 行的输入
  (10001)^2 ≈ 10^8 cells ≈ 800MB 会被放行分配, 是真实 DoS 向量。
  修法: 新增 MaxDiffCells=5e7 (~400MB 上限), 在分配 DP 表前检查
  (n+1)*(m+1), int64 乘法避免 32 位溢出。两道检查 (单侧短路 + cell 预算)
  都在分配前。tooLargeResult() helper 统一 TooLarge 形态。

#4 (Minor) DiffResult.Ops 注释自相矛盾
  原文"empty when TooLarge is true"与"含 1 哨兵 op"矛盾, 改为
  "TooLarge 时含 1 哨兵 op"。

测试: TestDiffLines_TooLargeIsSkipped 拆三个子测试:
  - 单侧超 MaxDiffLines -> TooLarge
  - 两个各 MaxDiffLines -> 被 cell 预算拦 (新行为回归)
  - cells 内的大 pair (1000x1000) -> 仍正常 diff

文档: design.md D22 重写为"双层预算"; spec.md 补双预算描述;
tasks.md 第 6 节更新。

go test ./... 全绿, go vet 无警告, openspec validate 通过。
---
 internal/session/htmldiff.go                  | 61 ++++++++++-----
 internal/session/htmldiff_test.go             | 74 +++++++++++++------
 openspec/changes/html-content-diff/design.md  | 12 ++-
 .../specs/version-chain/spec.md               |  2 +-
 openspec/changes/html-content-diff/tasks.md   |  3 +
 5 files changed, 105 insertions(+), 47 deletions(-)

diff --git a/internal/session/htmldiff.go b/internal/session/htmldiff.go
index c1fdfc9..985ae75 100644
--- a/internal/session/htmldiff.go
+++ b/internal/session/htmldiff.go
@@ -34,14 +34,22 @@ func (op LineOp) KindString() string {
 	}
 }
 
-// MaxDiffLines guards against pathological inputs. Above this many lines in
-// either side, the LCS dynamic program (O(n*m) time and memory) becomes
-// expensive; DiffLines signals TooLarge in its DiffResult instead of running
-// the computation, so callers can render a "too large to diff" notice without
-// blocking. The threshold is generous for hand-authored / agent-generated
-// HTML (typically < 2000 lines).
+// MaxDiffLines is a per-side fast short-circuit: any single input beyond
+// this many lines is rejected before the LCS computation even considers the
+// other side. It exists so a pathologically long document cannot reach the
+// cell-budget check below with an already-huge dimension.
 const MaxDiffLines = 10000
 
+// MaxDiffCells bounds the total DP table size (cells ≈ (n+1)*(m+1)). The LCS
+// algorithm allocates one int per cell, so this is effectively a memory
+// budget: MaxDiffCells int cells ≈ MaxDiffCells*8 bytes. 5e7 cells ≈ 400 MiB
+// is a generous ceiling that still admits large real-world documents
+// (e.g. 5000x5000 = 2.5e7 cells ≈ 200 MiB) while preventing the two-sides-
+// each-at-MaxDiffLines case (1e8 cells ≈ 800 MiB) from ever allocating.
+// Per-side MaxDiffLines alone does not catch that case, since each side is
+// individually within the per-side limit.
+const MaxDiffCells = 50_000_000
+
 // DiffTooLargeText is the explanatory text placed in the sole sentinel op when
 // DiffResult.TooLarge is true. It is purely informational; the TooLarge
 // boolean — not this string — is the authoritative signal, so a legitimate
@@ -50,32 +58,47 @@ const MaxDiffLines = 10000
 const DiffTooLargeText = "[diff skipped: file exceeds MaxDiffLines]"
 
 // DiffResult is the return value of DiffLines. Ops is the ordered line-level
-// diff (empty when TooLarge is true, in which case a single explanatory
-// sentinel op is still appended so UIs that ignore TooLarge degrade sanely).
-// TooLarge is the explicit, content-independent "input exceeded MaxDiffLines"
-// signal.
+// diff. When TooLarge is true, Ops contains exactly one explanatory sentinel
+// op so UIs that ignore TooLarge degrade sanely. TooLarge is the explicit,
+// content-independent "input exceeded the per-side or cell budget" signal.
 type DiffResult struct {
 	Ops      []LineOp
 	TooLarge bool
 }
 
+// tooLargeResult is the single TooLarge DiffResult returned by DiffLines for
+// every rejection path (per-side limit or cell budget), so the sentinel shape
+// stays consistent and callers never branch on which guard fired.
+func tooLargeResult() DiffResult {
+	return DiffResult{
+		Ops:      []LineOp{{Kind: LineEqual, Text: DiffTooLargeText}},
+		TooLarge: true,
+	}
+}
+
 // DiffLines computes a line-level diff between oldLines and newLines using the
 // classic LCS dynamic-programming algorithm, then walks the DP table to emit
 // a sequence of LineOps in reading order (deletions before insertions when
 // they share a context line). The result is pure: no I/O, no Store state.
 //
 // Either input being empty is handled naturally (an empty old side makes
-// every new line an addition, and vice versa). Inputs exceeding MaxDiffLines
-// on either side yield DiffResult{TooLarge: true} with a single sentinel op.
+// every new line an addition, and vice versa). Inputs are rejected with
+// DiffResult{TooLarge: true} (and a single sentinel op) when either side
+// exceeds MaxDiffLines or when the DP table would exceed MaxDiffCells.
 func DiffLines(oldLines, newLines []string) DiffResult {
-	if len(oldLines) > MaxDiffLines || len(newLines) > MaxDiffLines {
-		return DiffResult{
-			Ops:      []LineOp{{Kind: LineEqual, Text: DiffTooLargeText}},
-			TooLarge: true,
-		}
+	n := len(oldLines)
+	m := len(newLines)
+	// Per-side fast short-circuit: rejects a single huge input before the
+	// (cheap but still allocating) multiplication.
+	if n > MaxDiffLines || m > MaxDiffLines {
+		return tooLargeResult()
+	}
+	// Cell budget: bounds the (n+1)*(m+1) DP table memory. Checked before the
+	// table is allocated so an over-budget pair never pays for the allocation.
+	// int64 avoids overflow on 32-bit platforms when both sides are large.
+	if int64(n+1)*int64(m+1) > MaxDiffCells {
+		return tooLargeResult()
 	}
-
-	n, m := len(oldLines), len(newLines)
 
 	// dp[i][j] = length of LCS of oldLines[i:] and newLines[j:].
 	// Using (n+1) x (m+1) so dp[n][m] = 0 is the empty-base case.
diff --git a/internal/session/htmldiff_test.go b/internal/session/htmldiff_test.go
index 0b5e4b7..e14f65a 100644
--- a/internal/session/htmldiff_test.go
+++ b/internal/session/htmldiff_test.go
@@ -172,30 +172,58 @@ func TestDiffLines_CompletelyDifferent(t *testing.T) {
 
 func TestDiffLines_TooLargeIsSkipped(t *testing.T) {
 	t.Parallel()
-	huge := make([]string, MaxDiffLines+1)
-	for i := range huge {
-		huge[i] = "line"
-	}
-	result := DiffLines(huge, []string{"a"})
-	if !result.TooLarge {
-		t.Fatal("expected TooLarge=true for input exceeding MaxDiffLines")
-	}
-	if len(result.Ops) != 1 {
-		t.Fatalf("expected 1 sentinel op for too-large input; got %d", len(result.Ops))
-	}
-	if result.Ops[0].Text != DiffTooLargeText {
-		t.Fatalf("expected sentinel text %q, got %q", DiffTooLargeText, result.Ops[0].Text)
-	}
 
-	// Exactly at the threshold is still diffed.
-	atLimit := make([]string, MaxDiffLines)
-	big := DiffLines(atLimit, atLimit)
-	if big.TooLarge {
-		t.Fatal("input at limit should not be flagged TooLarge")
-	}
-	if len(big.Ops) != MaxDiffLines {
-		t.Fatalf("input at limit should still be diffed; got %d ops", len(big.Ops))
-	}
+	t.Run("per-side limit rejects huge single input", func(t *testing.T) {
+		t.Parallel()
+		huge := make([]string, MaxDiffLines+1)
+		for i := range huge {
+			huge[i] = "line"
+		}
+		result := DiffLines(huge, []string{"a"})
+		if !result.TooLarge {
+			t.Fatal("expected TooLarge=true for input exceeding MaxDiffLines")
+		}
+		if len(result.Ops) != 1 {
+			t.Fatalf("expected 1 sentinel op for too-large input; got %d", len(result.Ops))
+		}
+		if result.Ops[0].Text != DiffTooLargeText {
+			t.Fatalf("expected sentinel text %q, got %q", DiffTooLargeText, result.Ops[0].Text)
+		}
+	})
+
+	t.Run("cell budget rejects two at-limit inputs", func(t *testing.T) {
+		t.Parallel()
+		// Each side individually fits MaxDiffLines, but (MaxDiffLines+1)^2
+		// exceeds MaxDiffCells, so the cell budget must reject the pair
+		// rather than allocating ~800 MiB.
+		atLimit := make([]string, MaxDiffLines)
+		result := DiffLines(atLimit, atLimit)
+		if !result.TooLarge {
+			t.Fatal("two inputs each at MaxDiffLines should be rejected by the cell budget")
+		}
+	})
+
+	t.Run("cell budget admits large-but-feasible pair", func(t *testing.T) {
+		t.Parallel()
+		// A pair whose (n+1)^2 is well under MaxDiffCells but large enough to
+		// exercise the budget check. 1000x1000 = ~1M cells, fast and clearly
+		// feasible. The point is to show the cell budget is not so tight that
+		// ordinary large documents get rejected.
+		n := 1000
+		a := make([]string, n)
+		b := make([]string, n)
+		for i := range a {
+			a[i] = "same"
+			b[i] = "same"
+		}
+		result := DiffLines(a, b)
+		if result.TooLarge {
+			t.Fatalf("%dx%d diff should fit cell budget and not be flagged TooLarge", n, n)
+		}
+		if len(result.Ops) != n {
+			t.Fatalf("expected %d equal ops; got %d", n, len(result.Ops))
+		}
+	})
 }
 
 // TestDiffLines_SentinelTextContentIsNotMisclassified is the regression guard
diff --git a/openspec/changes/html-content-diff/design.md b/openspec/changes/html-content-diff/design.md
index 99ae4f0..327d3ce 100644
--- a/openspec/changes/html-content-diff/design.md
+++ b/openspec/changes/html-content-diff/design.md
@@ -45,11 +45,15 @@
 **`{id}` 的语义**：path 里的 `{id}` 是链上**任意** session（用于解析链归属 + owner 校验），`from/to` 是同链版本号。这样从任何一个版本预览页都能拉同链任意相邻对的 diff，无需先定位"链主 session"。
 **备选**：合并进 chain 接口一次性返回所有相邻 diff——否决，见上；每次开侧栏读 N 次磁盘 + N 次 LCS，浪费且延迟高。
 
-### D22: 大文件保护——超 `MaxDiffLines` 返回显式 `TooLarge` 信号
-**选择**：`MaxDiffLines = 10000`。任一侧超阈值时 `DiffLines` 返回 `DiffResult{Ops: [单条哨兵], TooLarge: true}`——`TooLarge` 是**显式结构化字段**，不依赖 op 文本。`DiffSessionHTML` 透传 `DiffResult`，`handleGetDiff` 直接用 `result.TooLarge` 设响应的 `tooLarge` 字段，前端 `renderHtmlDiff` 优先判 `data.tooLarge` 渲染为灰色 skip 行。**恰好等于阈值仍正常 diff**（`TooLarge=false`）。
-**理由**：LCS 是 O(n*m) DP，两个 10000 行文件 = 10^8 单元格 × 8 字节 int ≈ 800MB 内存 + 秒级 CPU，会拖垮请求。10000 行对 agent 产物（通常 < 2000 行）是极宽松的上限，正常用例永远触不到；真触到时跳过比卡死好。阈值是常量，将来按需调整。
+### D22: 大文件保护——双层预算（单侧行数 + 总单元格）返回显式 `TooLarge` 信号
+**选择**：两道预算检查，都在分配 DP 表之前。
+- `MaxDiffLines = 10000`：**单侧**快速短路。任一侧超此值直接返 `TooLarge`，避免一个巨大输入还没到乘法就先耗资源。
+- `MaxDiffCells = 50_000_000`：**总单元格**预算，`(n+1)*(m+1)` 超此值返 `TooLarge`。这一层挡住了"两侧各在单侧限内、但乘积爆炸"的情形——最典型就是两个各 10000 行的输入：`(10001)^2 ≈ 10^8 cells ≈ 800MB`，单侧检查放行，cell 预算拦截。`int64` 乘法避免 32 位平台溢出。
+
+任一检查触发都返回 `DiffResult{Ops: [单条哨兵], TooLarge: true}`，`tooLargeResult()` 统一形态。`TooLarge` 是**显式结构化字段**，不依赖 op 文本。`DiffSessionHTML` 透传 `DiffResult`，`handleGetDiff` 直接用 `result.TooLarge`，前端 `renderHtmlDiff` 优先判 `data.tooLarge`。
+**理由**：LCS 是 O(n*m) DP，单侧限只能挡"一边过大"，挡不住"两边都大但各自合法"。800MB 分配对请求处理是真实 DoS 向量（评审第三轮抓到）。cell 预算 5e7 ≈ 400MB 上限对 agent 产物（通常 < 2000 行，cells < 4M）极宽松，真实用例永远触不到，但把最坏情形从 800MB 压到 400MB 且永不超。
 **为何 `TooLarge` 是字段而非文本推断**：若用 `ops[0].Text == DiffTooLargeText` 判断，一个内容恰好等于 `[diff skipped: file exceeds MaxDiffLines]` 的合法单行 HTML 文档（如讲解本功能的文档站）会被误判为"太大跳过"。`TooLarge` 作为显式字段彻底根除这类内容碰撞——"太大"是输入规模的属性，与内容无关。
-**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离）——对大文件更快但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过；(c) 用哨兵 op 文本作为信号——否决，内容碰撞风险（见上）。
+**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离，线性空间）——对大文件更快且省内存，但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过；(c) 用哨兵 op 文本作为信号——否决，内容碰撞风险（见上）；(d) 只靠单侧 `MaxDiffLines`——否决，挡不住两侧各大的乘积爆炸（本决策的核心）。
 
 ### D23: diff 不入库——纯即时计算
 **选择**：`DiffSessionHTML` 每次调用都读两份文件 + 算 LCS，结果**不写 DB**。
diff --git a/openspec/changes/html-content-diff/specs/version-chain/spec.md b/openspec/changes/html-content-diff/specs/version-chain/spec.md
index ba036ea..70ecb41 100644
--- a/openspec/changes/html-content-diff/specs/version-chain/spec.md
+++ b/openspec/changes/html-content-diff/specs/version-chain/spec.md
@@ -7,7 +7,7 @@ The diff SHALL be computed by a longest-common-subsequence algorithm over the li
 
 The endpoint SHALL respect session ownership identically to the chain endpoint. When either version number does not correspond to a live version in the chain, or `from` equals `to`, or a parameter is missing or non-positive, the system SHALL return `400`. When the path session does not exist or is soft-deleted, the system SHALL return `404`.
 
-The diff computation SHALL be bounded: when either input exceeds a fixed line threshold, the system SHALL set the response's `tooLarge` flag to `true` and include a single explanatory line, rather than attempting the O(n*m) computation. The `tooLarge` flag is the authoritative signal of the skip condition; a legitimate document whose content happens to match the explanatory text SHALL NOT be misclassified as too large.
+The diff computation SHALL be bounded by two budgets checked before the DP table is allocated: a per-side line threshold, and a total cell threshold (`(n+1)*(m+1)`) that catches the case where both sides are individually within the per-side limit but their product would still allocate an unsafe amount of memory. When either budget is exceeded, the system SHALL set the response's `tooLarge` flag to `true` and include a single explanatory line, rather than attempting the O(n*m) computation. The `tooLarge` flag is the authoritative signal of the skip condition; a legitimate document whose content happens to match the explanatory text SHALL NOT be misclassified as too large.
 
 #### Scenario: 相邻版本的内容 diff
 - **WHEN** a client requests `GET /api/sessions/<v2-id>/diff?from=1&to=2` for a two-version chain where v2 added one line
diff --git a/openspec/changes/html-content-diff/tasks.md b/openspec/changes/html-content-diff/tasks.md
index f55f257..1d57b68 100644
--- a/openspec/changes/html-content-diff/tasks.md
+++ b/openspec/changes/html-content-diff/tasks.md
@@ -38,3 +38,6 @@
 - [x] 6.1 `renderHtmlDiff` 把"diff 太大"哨兵当普通 equal 行折叠（Major，第一轮）：`diffResponse` 新增显式 `TooLarge bool` 字段；前端 `renderHtmlDiff` 优先判 `data.tooLarge` 渲染为 `.hunk.skip` 行。
 - [x] 6.2 `handleGetDiff` 用文本推断 `TooLarge` 会被内容恰好等于 `DiffTooLargeText` 的合法单行文件误判（Minor，第二轮）：把"太大"信号从 op 文本解耦——`DiffLines` 改返回 `DiffResult{Ops, TooLarge}`，`DiffSessionHTML` 透传 `DiffResult`，`handleGetDiff` 直接用 `result.TooLarge` 不再读文本。
 - [x] 6.3 新增 `TestDiffLines_SentinelTextContentIsNotMisclassified`（算法层碰撞回归）+ `TestGetDiffTooLargeFilesSkipped`（HTTP 层 tooLarge 字段）。
+- [x] 6.4 LCS 表分配前加 cell 预算 `MaxDiffCells`（第三轮 Major）：单侧 `MaxDiffLines` 只挡单侧超限，两个各 10000 行的输入 `(10001)^2` ≈ 800MB 仍会分配。新增 `MaxDiffCells=5e7` 兜底 `(n+1)*(m+1)` 乘积，分配前检查，`tooLargeResult()` 统一 TooLarge 形态。
+- [x] 6.5 `TestDiffLines_TooLargeIsSkipped` 拆三个子测试：单侧超限 / 两个 at-limit 被 cell 预算拦 / cells 内的大 pair 仍 diff。
+- [x] 6.6 修正 `DiffResult.Ops` 注释（Minor）：原文"empty when TooLarge"与"含 1 哨兵 op"自相矛盾，改为"TooLarge 时含 1 哨兵 op"。

From d463110fc8d0ac2648adb7db85afe1aaac718a78 Mon Sep 17 00:00:00 2001
From: svtter <svtter@qq.com>
Date: Sat, 15 Aug 2026 19:58:17 +0800
Subject: [PATCH 5/5] fix(version-chain): calibrate MaxDiffCells for concurrent
 diffs, sync D19 (#84)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit 第四轮评审 (Major + Minor):

#5 (Major) 并发 LCS 内存——预算按单请求而非并发总量校准
  diff handler 并发: handleGetDiff -> DiffSessionHTML 不经 DB 锁
  (SetMaxOpenConns(1) 管不到纯内存计算), N 个在途 diff 各占
  MaxDiffCells*8 字节。原 5e7 = 400MB/请求, 几个请求重叠即耗尽典型内存。
  修法 (选"降预算"而非信号量——sth 是本地预览服务器, 低概率场景
  不值同步复杂度): MaxDiffCells 5e7 -> 1e7 (80MB/请求, ~10 并发
  ~800MB), 对真实用例仍极宽松 (2000x2000=4e6 cells 已远超典型产物)。
  新增 TestDiffLines_ConcurrentLargeDiffsBounded: 8 goroutine 混合
  feasible/over-budget 对, 断言并发下预算逻辑正确且无竞态。

#6 (Minor) D19 与 D22 的 API 契约不一致
  D19 仍写 DiffLines 返回 []LineOp (旧契约), 与 D22 的 DiffResult 矛盾。
  D19 改述为 DiffResult{Ops, TooLarge}, 补备选项 (d) 否决裸 []LineOp+
  哨兵 op 的缘由; D22 重写"按并发校准"章节 (含为何不选信号量)。

go test ./... 全绿 (-count=1), go vet 无警告, openspec validate 通过。
---
 internal/session/htmldiff.go                 | 17 +++---
 internal/session/htmldiff_test.go            | 55 ++++++++++++++++++++
 openspec/changes/html-content-diff/design.md | 15 +++---
 openspec/changes/html-content-diff/tasks.md  |  2 +
 4 files changed, 75 insertions(+), 14 deletions(-)

diff --git a/internal/session/htmldiff.go b/internal/session/htmldiff.go
index 985ae75..1481fea 100644
--- a/internal/session/htmldiff.go
+++ b/internal/session/htmldiff.go
@@ -42,13 +42,16 @@ const MaxDiffLines = 10000
 
 // MaxDiffCells bounds the total DP table size (cells ≈ (n+1)*(m+1)). The LCS
 // algorithm allocates one int per cell, so this is effectively a memory
-// budget: MaxDiffCells int cells ≈ MaxDiffCells*8 bytes. 5e7 cells ≈ 400 MiB
-// is a generous ceiling that still admits large real-world documents
-// (e.g. 5000x5000 = 2.5e7 cells ≈ 200 MiB) while preventing the two-sides-
-// each-at-MaxDiffLines case (1e8 cells ≈ 800 MiB) from ever allocating.
-// Per-side MaxDiffLines alone does not catch that case, since each side is
-// individually within the per-side limit.
-const MaxDiffCells = 50_000_000
+// budget: MaxDiffCells int cells ≈ MaxDiffCells*8 bytes on 64-bit builds.
+//
+// The budget is sized for CONCURRENT requests: diff handlers run in parallel
+// (they take no store lock — diffing is pure in-memory work), so N in-flight
+// diffs can allocate up to N * MaxDiffCells*8 bytes simultaneously. 1e7 cells
+// ≈ 80 MiB per request keeps even ~10 concurrent large diffs within ~800 MiB,
+// while still admitting any realistic agent-generated document (2000x2000 =
+// 4e6 cells ≈ 32 MiB is already far beyond typical HTML). The earlier 5e7
+// (≈ 400 MiB) budget left too little headroom once several requests overlap.
+const MaxDiffCells = 10_000_000
 
 // DiffTooLargeText is the explanatory text placed in the sole sentinel op when
 // DiffResult.TooLarge is true. It is purely informational; the TooLarge
diff --git a/internal/session/htmldiff_test.go b/internal/session/htmldiff_test.go
index e14f65a..750a269 100644
--- a/internal/session/htmldiff_test.go
+++ b/internal/session/htmldiff_test.go
@@ -1,6 +1,7 @@
 package session
 
 import (
+	"fmt"
 	"strings"
 	"testing"
 )
@@ -298,3 +299,57 @@ func TestLineOpKindString(t *testing.T) {
 		}
 	}
 }
+
+// TestDiffLines_ConcurrentLargeDiffsBounded is the regression guard for the
+// CodeRabbit concurrency finding: diff handlers run in parallel (no store
+// lock), so the per-request cell budget is the only bound on collective
+// memory. This test hammers DiffLines with several goroutines each diffing
+// a pair at the budget ceiling (and beyond it), asserting every result is
+// correct and the process stays healthy. It cannot observe peak RSS from Go,
+// but it proves the budget logic is race-free under concurrency and that
+// concurrent feasible pairs all succeed.
+func TestDiffLines_ConcurrentLargeDiffsBounded(t *testing.T) {
+	t.Parallel()
+
+	// Feasible pair: side length chosen so (n+1)^2 sits just under budget.
+	feasible := 2000 // (2001)^2 ≈ 4e6 cells < 1e7
+	if int64(feasible+1)*int64(feasible+1) > MaxDiffCells {
+		t.Fatalf("test setup wrong: %d exceeds cell budget", feasible)
+	}
+	a := make([]string, feasible)
+	b := make([]string, feasible)
+	for i := range a {
+		a[i] = "same"
+		b[i] = "same"
+	}
+
+	// Over-budget pair: both sides at MaxDiffLines.
+	atLimit := make([]string, MaxDiffLines)
+
+	const goroutines = 8
+	errs := make(chan error, goroutines*2)
+	for g := 0; g < goroutines; g++ {
+		go func(which int) {
+			if which%2 == 0 {
+				res := DiffLines(a, b)
+				if res.TooLarge || len(res.Ops) != feasible {
+					errs <- fmt.Errorf("goroutine %d: feasible pair wrong: tooLarge=%v ops=%d", which, res.TooLarge, len(res.Ops))
+				} else {
+					errs <- nil
+				}
+			} else {
+				res := DiffLines(atLimit, atLimit)
+				if !res.TooLarge {
+					errs <- fmt.Errorf("goroutine %d: over-budget pair should be TooLarge", which)
+				} else {
+					errs <- nil
+				}
+			}
+		}(g)
+	}
+	for i := 0; i < goroutines; i++ {
+		if err := <-errs; err != nil {
+			t.Fatal(err)
+		}
+	}
+}
diff --git a/openspec/changes/html-content-diff/design.md b/openspec/changes/html-content-diff/design.md
index 327d3ce..662d104 100644
--- a/openspec/changes/html-content-diff/design.md
+++ b/openspec/changes/html-content-diff/design.md
@@ -30,9 +30,9 @@
 ## Decisions
 
 ### D19: diff 粒度——行级 LCS，手写，无依赖
-**选择**：`DiffLines(old, new []string) []LineOp` 用经典 LCS 动态规划（O(n*m) 时间和内存，`dp[i][j]` = 后缀 LCS 长度），输出 `LineOp{Kind: Equal|Add|Delete, Text, OldNo, NewNo}`。修改表现为"先 delete 旧行再 add 新行"（LCS 的自然结果，与 unified diff 习惯一致）。纯 stdlib，~60 行 Go。
-**理由**：(1) agent 产出的 HTML 通常是结构化的（每行一个标签/一段文案），行级 diff 已能精确定位"哪块改了"。(2) LCS 是最经典、最可控、最可测的 diff 算法，无需引入第三方库——这直接化解了上一版 Non-Goals 的"无 diff 库"约束，是本期得以落地的关键。(3) 修改=先删后增符合 unified diff 直觉，前端按 `kind` 染色即可。
-**备选**：(a) 词级 diff（diffmatchpatch 风格）——否决，需分词 + HTML 标签边界处理复杂，且对"改了哪块"这个核心问题的边际收益低于行级；(b) DOM 树 diff——否决，需引 `golang.org/x/net/html`，破坏无新依赖约束；(c) 引 `sergi/go-diff` / `pmezard/difflib`——否决，上一版 Non-Goals 明确写了"无 diff 库"，且 LCS 手写成本可控。
+**选择**：`DiffLines(old, new []string) DiffResult` 用经典 LCS 动态规划（O(n*m) 时间和内存，`dp[i][j]` = 后缀 LCS 长度）。`DiffResult` 携带两个字段：`Ops []LineOp`（有序行级 diff，每个 op 是 `LineOp{Kind: Equal|Add|Delete, Text, OldNo, NewNo}`）与 `TooLarge bool`（输入超出预算的显式跳过信号，详见 D22——为什么它是字段而非从 op 文本推断）。修改表现为"先 delete 旧行再 add 新行"（LCS 的自然结果，与 unified diff 习惯一致）。纯 stdlib，~60 行 Go。`DiffSessionHTML` 与 `handleGetDiff` 均透传 `DiffResult`，`tooLargeResult()` 统一 TooLarge 形态。
+**理由**：(1) agent 产出的 HTML 通常是结构化的（每行一个标签/一段文案），行级 diff 已能精确定位"哪块改了"。(2) LCS 是最经典、最可控、最可测的 diff 算法，无需引入第三方库——这直接化解了上一版 Non-Goals 的"无 diff 库"约束，是本期得以落地的关键。(3) 修改=先删后增符合 unified diff 直觉，前端按 `kind` 染色即可。(4) 返回结构体（而非裸 `[]LineOp`）让"太大跳过"成为一等信号，调用方无需从 op 列表形态猜测（D22 的内容碰撞教训）。
+**备选**：(a) 词级 diff（diffmatchpatch 风格）——否决，需分词 + HTML 标签边界处理复杂，且对"改了哪块"这个核心问题的边际收益低于行级；(b) DOM 树 diff——否决，需引 `golang.org/x/net/html`，破坏无新依赖约束；(c) 引 `sergi/go-diff` / `pmezard/difflib`——否决，上一版 Non-Goals 明确写了"无 diff 库"，且 LCS 手写成本可控；(d) 返回裸 `[]LineOp` 用哨兵 op 表示"太大"——否决，迫使调用方匹配 magic string，内容碰撞风险（D22 详述）。
 
 ### D20: 渲染方式——时间线侧栏内联展开，上下文折叠
 **选择**：版本时间线侧栏每个（有前驱的）版本项加"Show HTML diff"按钮，点击懒加载 diff 接口、红绿行内联展开进 `.sth-version-htmldiff` 容器。**相等的上下文行折叠为单行 `⋯ N unchanged ⋯`**，只保留改动行 ± 紧邻上下文（本期实现是"完全折叠连续 equal 行为一条 skip 行"，不留 hunk 上下文——见 D22 取舍）。按钮旁显示 `+a −b` 摘要。再点折叠。
@@ -45,15 +45,16 @@
 **`{id}` 的语义**：path 里的 `{id}` 是链上**任意** session（用于解析链归属 + owner 校验），`from/to` 是同链版本号。这样从任何一个版本预览页都能拉同链任意相邻对的 diff，无需先定位"链主 session"。
 **备选**：合并进 chain 接口一次性返回所有相邻 diff——否决，见上；每次开侧栏读 N 次磁盘 + N 次 LCS，浪费且延迟高。
 
-### D22: 大文件保护——双层预算（单侧行数 + 总单元格）返回显式 `TooLarge` 信号
+### D22: 大文件保护——双层预算（单侧行数 + 总单元格），按并发请求量校准
 **选择**：两道预算检查，都在分配 DP 表之前。
 - `MaxDiffLines = 10000`：**单侧**快速短路。任一侧超此值直接返 `TooLarge`，避免一个巨大输入还没到乘法就先耗资源。
-- `MaxDiffCells = 50_000_000`：**总单元格**预算，`(n+1)*(m+1)` 超此值返 `TooLarge`。这一层挡住了"两侧各在单侧限内、但乘积爆炸"的情形——最典型就是两个各 10000 行的输入：`(10001)^2 ≈ 10^8 cells ≈ 800MB`，单侧检查放行，cell 预算拦截。`int64` 乘法避免 32 位平台溢出。
+- `MaxDiffCells = 10_000_000`：**总单元格**预算，`(n+1)*(m+1)` 超此值返 `TooLarge`。这一层挡住了"两侧各在单侧限内、但乘积爆炸"的情形——最典型就是两个各 10000 行的输入：`(10001)^2 ≈ 10^8 cells ≈ 800MB`，单侧检查放行，cell 预算拦截。`int64` 乘法避免 32 位平台溢出。
 
 任一检查触发都返回 `DiffResult{Ops: [单条哨兵], TooLarge: true}`，`tooLargeResult()` 统一形态。`TooLarge` 是**显式结构化字段**，不依赖 op 文本。`DiffSessionHTML` 透传 `DiffResult`，`handleGetDiff` 直接用 `result.TooLarge`，前端 `renderHtmlDiff` 优先判 `data.tooLarge`。
-**理由**：LCS 是 O(n*m) DP，单侧限只能挡"一边过大"，挡不住"两边都大但各自合法"。800MB 分配对请求处理是真实 DoS 向量（评审第三轮抓到）。cell 预算 5e7 ≈ 400MB 上限对 agent 产物（通常 < 2000 行，cells < 4M）极宽松，真实用例永远触不到，但把最坏情形从 800MB 压到 400MB 且永不超。
+**理由**：LCS 是 O(n*m) DP，单侧限只能挡"一边过大"，挡不住"两边都大但各自合法"。800MB 分配对请求处理是真实 DoS 向量（评审第三轮抓到）。
+**按并发校准预算**（评审第四轮）：diff handler 是**并发**的——`handleGetDiff` 调 `DiffSessionHTML` 不经 DB（diff 是纯内存计算，`SetMaxOpenConns(1)` 的单写者模型管不到它），N 个在途 diff 请求可同时各占 `MaxDiffCells*8` 字节。因此预算必须按"N 个并发请求的总量"校准，而非"单请求最大"：1e7 cells ≈ 80MB/请求，即使 ~10 个并发大 diff 也只 ~800MB，对任何部署 sth 的机器都是安全水位；而此前的 5e7（≈400MB/请求）在几个请求重叠时就会耗尽典型机器内存。1e7 对真实用例依然极宽松（2000x2000 = 4e6 cells ≈ 32MB 已远超典型 agent 产物）。**不选信号量/全局锁**：sth 是单人/小团队本地预览服务器，为极低概率的并发场景引入同步原语违背项目极简风格；把预算校准到"并发总量安全"是同等安全、零复杂度的解法。`TestDiffLines_ConcurrentLargeDiffsBounded` 并发回归测试守护此行为。
 **为何 `TooLarge` 是字段而非文本推断**：若用 `ops[0].Text == DiffTooLargeText` 判断，一个内容恰好等于 `[diff skipped: file exceeds MaxDiffLines]` 的合法单行 HTML 文档（如讲解本功能的文档站）会被误判为"太大跳过"。`TooLarge` 作为显式字段彻底根除这类内容碰撞——"太大"是输入规模的属性，与内容无关。
-**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离，线性空间）——对大文件更快且省内存，但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过；(c) 用哨兵 op 文本作为信号——否决，内容碰撞风险（见上）；(d) 只靠单侧 `MaxDiffLines`——否决，挡不住两侧各大的乘积爆炸（本决策的核心）。
+**备选**：(a) Myers 算法（O((n+m)·d)，d=编辑距离，线性空间）——对大文件更快且省内存，但实现复杂得多，与 D19"手写可控"的基调冲突，且 agent 产物行数远低于阈值，不值得；(b) 超阈值时只 diff 头尾 N 行——否决，语义混乱，不如明确跳过；(c) 用哨兵 op 文本作为信号——否决，内容碰撞风险（见上）；(d) 只靠单侧 `MaxDiffLines`——否决，挡不住两侧各大的乘积爆炸；(e) 信号量/全局锁限制并发 diff——否决，为低概率场景引入同步复杂度，预算校准已等效（见上）；(f) 保持 5e7 大预算——否决，未考虑并发总量（评审第四轮）。
 
 ### D23: diff 不入库——纯即时计算
 **选择**：`DiffSessionHTML` 每次调用都读两份文件 + 算 LCS，结果**不写 DB**。
diff --git a/openspec/changes/html-content-diff/tasks.md b/openspec/changes/html-content-diff/tasks.md
index 1d57b68..9a1c103 100644
--- a/openspec/changes/html-content-diff/tasks.md
+++ b/openspec/changes/html-content-diff/tasks.md
@@ -41,3 +41,5 @@
 - [x] 6.4 LCS 表分配前加 cell 预算 `MaxDiffCells`（第三轮 Major）：单侧 `MaxDiffLines` 只挡单侧超限，两个各 10000 行的输入 `(10001)^2` ≈ 800MB 仍会分配。新增 `MaxDiffCells=5e7` 兜底 `(n+1)*(m+1)` 乘积，分配前检查，`tooLargeResult()` 统一 TooLarge 形态。
 - [x] 6.5 `TestDiffLines_TooLargeIsSkipped` 拆三个子测试：单侧超限 / 两个 at-limit 被 cell 预算拦 / cells 内的大 pair 仍 diff。
 - [x] 6.6 修正 `DiffResult.Ops` 注释（Minor）：原文"empty when TooLarge"与"含 1 哨兵 op"自相矛盾，改为"TooLarge 时含 1 哨兵 op"。
+- [x] 6.7 `MaxDiffCells` 按并发校准（第四轮 Major）：diff handler 并发（不经 DB 锁），N 个在途请求各占 `MaxDiffCells*8` 字节；5e7（400MB/请求）在请求重叠时耗尽内存。降到 1e7（80MB/请求，~10 并发 ~800MB），对真实用例仍极宽松；不引信号量（低概率场景不值同步复杂度）。新增 `TestDiffLines_ConcurrentLargeDiffsBounded` 并发回归。
+- [x] 6.8 D19 与 D22 的 API 契约统一（第四轮 Minor）：D19 原写 `DiffLines` 返回 `[]LineOp`（旧契约），与 D22 的 `DiffResult` 矛盾。D19 改述为返回 `DiffResult{Ops, TooLarge}` 并补充备选项 (d)（裸 `[]LineOp` + 哨兵 op 被否决的缘由）。