Session-only hit evidenceRead points to offset=0, useless for long sessions

[catoncat]

Problem

PR #82 给 find --json 加了 evidenceRead 字段:message hit 建议 read-range(用 matchSeq 定位),session-only hit 建议 read-page。message hit 的 evidenceRead 真实有效(6/6 agent 在真实数据测试中都成功用它拿到了关键证据)。

但 session-only hit 的 evidenceRead 固定指向 read-page offset=0 limit=40,对长 session 基本是空操作——读到的 40 条开头消息跟触发 session-level match 的 compact/summary/reasoning 文本完全无关。

这违反了 issue #72 的设计目标("Assemble evidence for session-only recall hits without adding a top-level command")。当前实现只是机械地给了个 read-page 命令,没有尝试定位到实际触发 match 的内容对应的 message 区间。

Local Evidence

真实数据复现(来自 4566 sessions / 247K messages 的库):

1. pi session,86 条 message:

   • find "sherlog memory review" 的 ⚡ Bolt: optimize message array traversal in session parsing #2 hit 是 pi session pi:019ede1c-a229-71b9-9d40-cc79a60dac65(matchSource=session,因 compact_text 命中)
   • evidenceRead 返回 read-page offset=0 limit=40
   • 跑出来读到的是 "hi" / "你好,我在。当前在 mom 仓库,可以帮你查环境..." ——跟 "sherlog memory review" 完全无关

2. codex session,66 条 message(Agent 4 独立复现):

   • session 019dbe80-9fe3-74a2-bd4d-1cf195c86fc2(matchSource=session)
   • evidenceRead 返回 read-page offset=0 limit=40
   • 前 40 条是会话开头寒暄和上下文恢复,不是触发 match 的内容

3. 设计源头 session(019dbe80 seq 6,2026-04-24):
   设计者当时写的是:

   "find 输出必须区分 matchSource = message | session。如果是 session-level 命中,不要假造 matchSeq;可以给 snippet 和建议 read-page,或再做轻量原文证据 scan 找真实 anchor。"

   设计时就知道应该"找真实 anchor",但最终实现选了简单的 offset=0。这是有意识的妥协,但缺了 follow-up。

Current Implementation

src/evidence-read.ts:buildEvidenceReadAction():

if (result.matchSeq === null) {
  return {
    kind: "read-page",
    reason: "session_level_match",
    offset: 0,                    // ← 固定 0
    limit: 40,                    // ← 固定 40
    argv: [..., "read-page", sessionRef, "--offset", "0", "--limit", "40"],
  };
}

session-only hit 的 matchSeq 永远是 null(因为 matchSource=session 表示命中来自 title/summary/compact/reasoning_text 等 session-level 字段,不是某条具体 message)。当前实现直接放弃定位,从 offset=0 开始读。

Impact

6 个 agent 在真实数据上的交互测试中,凡是遇到 session-only hit 的场景,都遇到了这个问题:

• Agent 3:找 arXiv 论文起点的 session hit,read-page offset=0 读到无关开头
• Agent 4:整个任务就是找这个缺陷的讨论,实测复现并验证了缺陷

对短 session(<20 message)offset=0 可能偶然有用(前 40 条覆盖整个 session)。但对长 session(几十条以上),这个功能基本没用——agent 拿到 40 条无关内容后,还得自己决定怎么翻页,失去了 evidenceRead "自动给出最佳读法"的意义。

Suggested Approaches

几个可选方向(不互斥,可组合):

1. 基于 session-level match source 猜 anchor:session-level hit 知道是哪个字段命中的(compact_text / reasoning_summary_text / title / summary_text)。可以给 compact_text 命中的 session 建议从 compact 对应的时间段附近开始读(如果能记录 compact 的 approximate message seq)。

2. 轻量原文证据 scan:Assemble evidence for session-only recall hits without adding a top-level command #72 原始设计里提到的"再做轻量原文证据 scan 找真实 anchor"。在 evidenceRead 阶段对 session 的 messages 做一次轻量 scan(用 query terms 匹配 message content),找到最相关的 message seq,用它作为 read-range 的 anchor。这比 read-page offset=0 精准得多。

3. 至少给 read-page 加 smart offset:如果不想做 scan,至少可以基于 session 的 messageCount 给一个"中间偏后"的 offset(用户记忆里更近的对话通常更相关),或者给多个 read-page 建议(开头/中间/结尾)让 agent 选。

4. 标记 evidenceRead 为 "best_guess":在 evidenceRead 里加一个 confidence 字段,message hit 标 high,session hit 标 low,让 agent 知道这个读法不精确、可能需要自己翻页。

What This Is Not

• 不是要假造 matchSeq(matchSeq=null 是正确的,因为 session-level 命中确实没有具体 message 锚点)
• 不是要加新 top-level command(保持 Assemble evidence for session-only recall hits without adding a top-level command #72 的约束,只用现有 find/read-range/read-page)
• 不是要回到 find --bundle 老路

Related

• PR Integrate sherlog memory review roadmap work #82:introduces the evidenceRead feature(this issue tracks the session-only hit limitation)
• Issue Assemble evidence for session-only recall hits without adding a top-level command #72:original design intent for session-only evidence assembly
• Issue Make query profile scoring real, or remove the stale abstraction #71:query-profile scoring(this issue is separate;Make query profile scoring real, or remove the stale abstraction #71's scoring changes don't help session-only hit evidence)
• 设计源头 session:019dbe80-9fe3-74a2-bd4d-1cf195c86fc2 seq 6(2026-04-24,"或再做轻量原文证据 scan 找真实 anchor")

trace: cxs_session_only_evidence_read_followup_20260626T084500Z

[catoncat]

Fix Posted

Fixed in commit 0411613 on branch agent/sherlog-memory-review-stack (sealed as intent int_0fbb61ad).

What changed

buildEvidenceReadAction now returns read-range --query <query> for session-only hits (instead of read-page offset=0). This lets resolveAnchorSeq use searchTopHitInSession to locate the real evidence anchor inside the session transcript.

When the query finds no message hits (e.g. session-level match from compact/summary with different wording), resolveAnchorSeq falls back to seq=0 instead of throwing — no worse than the old behavior.

Verified

• 213/213 tests pass (3 new tests in evidence-read.test.ts)
• 6/6 acceptance gate fixtures pass (session-only-compact-context updated to expect read-range)
• Real data: session-only hits now return read-range --query instead of read-page offset=0

Known limitation

When session-level hits come from compact/summary text, the query terms may not appear verbatim in raw messages (e.g. compact says "ranking weights" but messages only say "ranking"). In these cases FTS returns 0 hits and we fall back to seq=0. A deeper fix would search with individual terms or fuzzy match, but that is out of scope for this issue.