@zhushanwen/pi-session-reader 0.3.0 → 0.4.0

package/src/result-action.ts

@@ -0,0 +1,244 @@
+/**
+ * result action（subagent-sync-collect U6：design subagent-sync-collect.md §3.1.3）。
+ *
+ * 从 tool-handler.ts 机械提取（max-lines 拆分轮）：纯移动零行为变更。tool-handler 的
+ * 定位/解析 helper（err/stripHash/requireStr/resolveSessionId/disambiguate/safeParse）
+ * 为文件私有且被其余 9 个 action 共用，不便搬移——经 {@link ResultActionDeps} 注入，
+ * tool-handler.ts 构造 RESULT_ACTION_DEPS 常量传入（构造期绑定，运行时零查找开销）。
+ *
+ * 设计来源：docs/design/subagent-sync-collect.md §3.1.3 ——
+ *   session_read {"action":"result","session":"sa-aaa"}              // 单个
+ *   session_read {"action":"result","session":"sa-aaa,sa-bbb,sa-ccc"} // 批量（≤10）
+ *   → 每条返回该 subagent session 的最终 assistant 正文（与通知 record.result 同源），
+ *     可选 limit 参数（默认 8000 字符/条，超出截断 + 提示读原文件）。
+ * 定位复用既有发现机制（sa-xxx manifest 反查 / uuid 片段 / 路径），不新造目录或文件。
+ */
+import type { Entry, ParseResult } from './core/parser.js'
+import type { MatchedSession } from './discovery/find.js'
+import { listRecordManifests, type RecordManifest } from './discovery/subagents.js'
+import type { ResolveResult, SessionReadAction, SessionReadParams, ToolResult } from './tool-handler.js'
+
+/** result 批量上限（design subagent-sync-collect §3.1.3：一次最多 10 个）。 */
+const RESULT_MAX_BATCH = 10
+
+/** result 单条默认字符上限（design §3.1.3：默认 8000 字符/条）。 */
+const RESULT_DEFAULT_LIMIT = 8000
+
+/** result 批量条目分隔符（与 notifier 批通知 "\n\n---\n\n" join 同款）。 */
+const RESULT_BATCH_SEPARATOR = '\n\n---\n\n'
+
+/** result action 对 tool-handler 私有 helper 的注入面（构造期常量绑定）。 */
+export interface ResultActionDeps {
+  err(message: string): Error
+  stripHash(s: string): string
+  requireStr(val: string | undefined, name: string, action: SessionReadAction): string
+  resolveSessionId(
+    rawSession: string | undefined,
+    action: SessionReadAction,
+    agentDir: string,
+    source?: 'main' | 'subagent',
+    /** S3：批量预取的 manifest 列表（避免逐 id 重复全量扫描）；单 id 不传。 */
+    prefetchedManifests?: RecordManifest[],
+  ): Promise<ResolveResult>
+  disambiguate(query: string, candidates: MatchedSession[]): ToolResult
+  safeParse(fileName: string): Promise<ParseResult>
+  /** 批量头行短 id 截断宽度（tool-handler SESSION_ID_PREFIX_LEN 同源）。 */
+  sessionIdPrefixLen: number
+}
+
+/**
+ * 从 assistant message content 提取纯 text（text 块顺序拼接）。
+ *
+ * 与 record 侧 text_delta 直累积同构：同一 message 内多个 text 块无分隔拼接
+ *（流式 delta 逐段 append），thinking/toolCall 块不入 record.text，此处同样排除。
+ *
+ * [S7 code-simplify 登记] 本包内第 4 个同構「text 块提取」变体（其余三处均在
+ * tool-handler.ts / discovery/find.ts）：messageReadableText（'' join + 占位符）、
+ * extractContentText（'\n' join）、extractTextFromContent（' ' join + 空返 undefined）。
+ * 本变体的 '' 无分隔拼接是 A4 取回逐字节一致锁定的硬理由（对齐 record.result 的
+ * 流式 delta 无分隔累积），不可与带分隔符的变体合并——差异是行为敏感点，勿「顺手统一」。
+ */
+function assistantMessageText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  let out = ''
+  for (const block of content) {
+    if (block !== null && typeof block === 'object') {
+      const o = block as Record<string, unknown>
+      if (o.type === 'text' && typeof o.text === 'string') out += o.text
+    }
+  }
+  return out
+}
+
+/**
+ * 从 session entries 提取最终结果正文（与完成通知 record.result 同源，A4 逐字节一致的前置）。
+ *
+ * 同源语义（packages/subagent-core/src/execution/execution-record.ts getFullText，只读参考）：
+ * record.result = AgentResult.text = getFullText(record) = 全部 assistant turn 文本
+ * filter(非空，空白串按非空) join("\\n\\n")；pi 每 turn_end 对应一条 assistant message
+ *（agent-session.js turn_end 携带 message），故文件侧重建 = 每条 assistant message 的
+ * text 块顺序拼接 → 跨 message 非空过滤 join("\\n\\n")。
+ *
+ * 取「最后一条 user message 之后」的 assistant 文本：one-shot（单 user prompt，
+ * collect:sync 的目标形态）与 join-all 逐字节一致；多轮 chatMode session 对齐
+ * 「最终一轮输出」语义。
+ *
+ * 导出供单测白盒锁定同源重建规则（message 内 '' join / 跨 message '\n\n' join /
+ * thinking 与 toolCall 排除 / 空 text 过滤 / 末 user 边界）。
+ */
+export function extractFinalAssistantText(entries: Entry[]): string {
+  let lastUserIdx = -1
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i]?.message?.role === 'user') {
+      lastUserIdx = i
+      break
+    }
+  }
+  const texts: string[] = []
+  for (let i = lastUserIdx + 1; i < entries.length; i++) {
+    const e = entries[i]
+    if (e?.message?.role !== 'assistant') continue
+    const text = assistantMessageText(e.message.content)
+    if (text.length > 0) texts.push(text)
+  }
+  return texts.join('\n\n')
+}
+
+/** result 单条取回结果（单条 details 与批量 details.items 共用形状）。 */
+interface ResultItem {
+  /** 调用方原始输入（sa-id / uuid 片段 / 路径） */
+  session: string
+  /** 反查到的真实 session id（header id，非 sa- 占位） */
+  sessionId: string
+  /** session .jsonl 绝对路径（截断提示读原文件用） */
+  sessionFile: string
+  /** 全量正文字符数（截断前口径） */
+  totalChars: number
+  truncated: boolean
+  /** 实际展示正文（截断后含尾提示；未截断时 = 全量正文） */
+  text: string
+}
+
+/** result 截断尾提示（design §3.1.3：超出截断 + 提示读原文件）。 */
+/** result 条目截断提示行。
+ *
+ * [S8 code-simplify 口径注] 本函数的 X = **保留**字符数（limit）；而 subagent-core
+ * notifier.ts buildTruncationPointer 同模板的 X = **丢弃**字符数（total - kept）。
+ * 两处措辞同构但口径相反（主 agent 会先后消费两种通知），统一字符串 = 行为变更，
+ * 勿顺手改口径——读本行时先确认在消费哪一侧。
+ * [C6] 英文去 emoji（对齐 notifier 指针行的纯英文形态，adversarial-review-fixes §3.4）。 */
+function formatResultTruncation(
+  raw: string,
+  sessionFile: string,
+  limit: number,
+  totalChars: number,
+): string {
+  return (
+    `\n\n[truncated ${limit} of ${totalChars} chars — ` +
+    `full text: read ${sessionFile}, or session_read { action:"detail", session:"${raw}" }]`
+  )
+}
+
+/**
+ * result 的 limit 解析：缺省 8000；非有限数/非正数报错（schema 已限 Number，此处防御
+ * + 可单测绕过 schema）。向下取整防小数 slice 语义模糊。
+ */
+function resolveResultLimit(raw: number | undefined): number {
+  if (raw === undefined) return RESULT_DEFAULT_LIMIT
+  if (!Number.isFinite(raw) || raw <= 0) {
+    throw new Error(
+      `limit "${String(raw)}" 无效，需为正数。👉 传正整数重试（缺省 ${RESULT_DEFAULT_LIMIT} 字符/条）。`,
+    )
+  }
+  return Math.floor(raw)
+}
+
+/**
+ * result 的 session 列表解析：单 id 或逗号批量（≤10）。
+ * 空条目（如 "sa-a," 或连续逗号）与超限均明确报错（含上限数字与 👉）。
+ */
+function parseResultSessionList(raw: string | undefined, deps: ResultActionDeps): string[] {
+  const trimmed = deps.requireStr(raw, 'session', 'result')
+  const ids = trimmed.split(',').map((s) => deps.stripHash(s.trim()))
+  if (ids.some((id) => id === '')) {
+    throw deps.err(
+      `session 列表含空条目："${trimmed}"。👉 检查逗号分隔格式（如 "sa-aaa,sa-bbb"）重试。`,
+    )
+  }
+  if (ids.length > RESULT_MAX_BATCH) {
+    throw deps.err(
+      `批量取回 ${ids.length} 个 session 超上限：一次最多 ${RESULT_MAX_BATCH} 个。` +
+        `\n👉 分批取回（每批 ≤${RESULT_MAX_BATCH} 个 id）。`,
+    )
+  }
+  return ids
+}
+
+/**
+ * result：取回 subagent session 的最终结果正文（design subagent-sync-collect §3.1.3）。
+ *
+ * 流程：逐 id 走 resolveSessionId 三形态反查（sa-xxx manifest 精确反查 / uuid 片段 /
+ * 绝对路径，multi 走既有 disambiguate）→ safeParse → extractFinalAssistantText
+ *（与通知 record.result 同源）→ limit 截断。定位零新机制，不新造目录或文件。
+ *
+ * content 形态：单 id = 纯正文（无包装，未截断时与 record.result 逐字节一致，A4 取回门）；
+ * 批量 = 每条目 `[i/n] <原始id> (session <短id>)` 头行 + 正文，'\\n\\n---\\n\\n' join。
+ *
+ * 错误路径（明确报错不返空串）：id 无匹配（ES2/F1 风格）、manifest 有但文件不存在
+ *（ES1：GC 或 pi session 延迟写入尚未 flush）、无 assistant 输出（运行中/未写正文）、
+ * 批量超限 / 空条目 / limit 非法。
+ */
+export async function doResult(
+  params: SessionReadParams,
+  agentDir: string,
+  deps: ResultActionDeps,
+): Promise<ToolResult> {
+  const ids = parseResultSessionList(params.session, deps)
+  const limit = resolveResultLimit(params.limit)
+  // S3（code-simplify）：sa- 形态走 manifest 反查，逐 id 调用会重复全量扫 subagents/ 树
+  //（N+1）——批量入口预取一次注入。uuid 片段/路径形态不经 manifest，不预取。
+  const prefetchedManifests = ids.some((id) => id.startsWith('sa-'))
+    ? await listRecordManifests(agentDir)
+    : undefined
+  const items: ResultItem[] = []
+  for (const id of ids) {
+    const resolved = await deps.resolveSessionId(id, 'result', agentDir, params.source, prefetchedManifests)
+    if (resolved.kind === 'multi') return deps.disambiguate(resolved.query, resolved.candidates)
+    const { entries } = await deps.safeParse(resolved.fileName)
+    const text = extractFinalAssistantText(entries)
+    if (text.length === 0) {
+      throw deps.err(
+        `session "${id}" 尚无 assistant 输出（运行中或文件尚未 flush 完整）。` +
+          `\n👉 稍后重试，或用 session_read { action:"outline", session:"${id}" } 看当前进度。`,
+      )
+    }
+    const totalChars = text.length
+    const truncated = totalChars > limit
+    items.push({
+      session: id,
+      sessionId: resolved.sessionId,
+      sessionFile: resolved.fileName,
+      totalChars,
+      truncated,
+      text: truncated
+        ? text.slice(0, limit) + formatResultTruncation(id, resolved.fileName, limit, totalChars)
+        : text,
+    })
+  }
+  if (items.length === 1) {
+    const only = items[0]
+    return {
+      content: [{ type: 'text', text: only.text }],
+      details: { ...only },
+    }
+  }
+  const blocks = items.map(
+    (it, i) =>
+      `[${i + 1}/${items.length}] ${it.session} (session ${it.sessionId.slice(0, deps.sessionIdPrefixLen)}…)\n${it.text}`,
+  )
+  return {
+    content: [{ type: 'text', text: blocks.join(RESULT_BATCH_SEPARATOR) }],
+    details: { count: items.length, items },
+  }
+}

package/src/tool-handler.ts

@@ -4,7 +4,7 @@
  * 分层约定（同 scheduler/cw-tool）：本文件零 pi 依赖——agentDir 作参数注入，
  * 不调用 getAgentDir()，可完全单测；pi 注册与 getAgentDir() 调用在 index.ts。
  *
- * 按 action 分发到 9 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
+ * 按 action 分发到 10 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
@@ -35,6 +35,10 @@ import {
   type ToolResultSummaryEntry,
 } from './core/render.js'
 import type { Family, SessionRef, WorkflowRef } from './core/family.js'
+import { doResult, extractFinalAssistantText, type ResultActionDeps } from './result-action.js'
+
+// result action 主体在 result-action.ts（max-lines 拆分轮机械提取，零行为变更）；
+// 导出面保持不变：extractFinalAssistantText 仍从本模块导出（包内测试白盒导入路径不变）。
 import {
   buildExecutionTree,
   formatExecutionTreeText,
@@ -55,6 +59,7 @@ export type SessionReadAction =
   | 'export'
   | 'extract'
   | 'workflow'
+  | 'result'
 
 export interface SessionReadParams {
   action: SessionReadAction
@@ -185,7 +190,7 @@ function rangeLabel(r: { start: number; end: number }): string {
 // resolveSessionId：片段 → 完整 id（design §3.4 resolveSessionId 辅助）
 // ---------------------------------------------------------------------------
 
-type ResolveResult =
+export type ResolveResult =
   | { kind: 'ok'; sessionId: string; fileName: string }
   | { kind: 'multi'; query: string; candidates: MatchedSession[] }
 
@@ -246,73 +251,87 @@ function expandHome(p: string): string {
 }
 
 /**
- * 把 session 参数解析到唯一完整 id（design §6.1 M0 + U2/U3）。
- *
- * 三形态：
- * - ① 绝对路径 / ~ 前缀 → 展开后读首行 header，sessionId=header 真实 id（文件名仅定位）
- * - ② sa-id 前缀 → listRecordManifests 精确反查，sessionId=sessionFile header id
- *   （禁止降级 record.id——sa- 形态不可当 sessionId，CQ3 决策）
- * - ③ 其余 → findSessions 透传 source 沿用 F1/F2
- *
- * 错误契约（U3）：① 文件不存在/非 .jsonl/header 读不出 → F6 风格；
- * ② sessionFile GC → ES1（manifest 元数据 + 👉）；sa-id 0/>1 命中 → ES2（👉 family）。
- *
- * 仅用于 family/outline/expand/detail/search/export/extract（find action 自行调 findSessions，
- * 零匹配时返回空 + 提示，不抛错）。
+ * 把 session 参数解析到唯一完整 id（design §6.1 M0 + U2/U3）。三形态各拆独立解析器：
+ * resolveBySessionPath（① 绝对路径/~）→ resolveByRecordId（② sa- 前缀）→ resolveByFragment（③ 片段）。
+ * 错误契约（U3）：① 文件不存在/非 .jsonl/header 读不出 → F6 风格；② sessionFile GC → ES1（manifest 元数据 + 👉）；
+ * sa-id 0/>1 命中 → ES2（👉 family）。仅用于 family/outline/expand/detail/search/export/extract/result
+ *（find action 自行调 findSessions，零匹配时返回空 + 提示，不抛错）。
  */
 async function resolveSessionId(
   rawSession: string | undefined,
   action: SessionReadAction,
   agentDir: string,
   source?: 'main' | 'subagent',
+  /** S3（code-simplify）：批量调用方（doResult）预取的 manifest 列表——省去逐 id
+   *  重复全量扫 subagents/ 树（N+1）。单 id 调用点不传，行为零变化。 */
+  prefetchedManifests?: RecordManifest[],
 ): Promise<ResolveResult> {
   const session = stripHash(requireStr(rawSession, 'session', action))
 
   // ① 绝对路径或 ~ 前缀（Windows 盘符由 isAbsolute 处理）
   if (isAbsolute(session) || session === '~' || session.startsWith('~/')) {
-    const expanded = expandHome(session)
-    if (!expanded.endsWith('.jsonl')) {
-      throw err(
-        `读取失败：${session}（非 .jsonl session 文件）。👉 检查文件或换 session。`,
-      )
-    }
-    if (!existsSync(expanded)) {
-      throw err(`读取失败：${session}（文件不存在）。👉 检查文件或换 session。`)
-    }
-    const headerId = readSessionHeaderId(expanded)
-    if (headerId === undefined) {
-      throw err(
-        `读取失败：${session}（首行非合法 session header）。👉 检查文件或换 session。`,
-      )
-    }
-    return { kind: 'ok', sessionId: headerId, fileName: expanded }
+    return resolveBySessionPath(session)
   }
 
   // ② sa-id 前缀 → record manifest 精确反查
   if (session.startsWith('sa-')) {
-    const manifests = await listRecordManifests(agentDir)
-    const hits = manifests.filter((m) => m.id === session)
-    if (hits.length === 0) {
-      throw err(formatSaIdNotFound(session))
-    }
-    if (hits.length > 1) {
-      throw err(formatSaIdAmbiguous(session, hits))
-    }
-    const record = hits[0]
-    if (!existsSync(record.sessionFile)) {
-      throw err(formatSessionGc(record))
-    }
-    const headerId = readSessionHeaderId(record.sessionFile)
-    if (headerId === undefined) {
-      // header 读不出不降级 record.id（sa- 形态不可当 sessionId，CQ3）
-      throw err(
-        `读取失败：${record.sessionFile}（首行非合法 session header）。👉 检查文件或换 session。`,
-      )
-    }
-    return { kind: 'ok', sessionId: headerId, fileName: record.sessionFile }
+    return resolveByRecordId(session, agentDir, prefetchedManifests)
   }
 
   // ③ 其余：findSessions 透传 source 沿用 F1/F2
+  return resolveByFragment(session, agentDir, source)
+}
+
+/** 形态①：绝对路径 / ~ 前缀 → 展开后读首行 header，sessionId=header 真实 id（文件名仅定位）。 */
+function resolveBySessionPath(session: string): ResolveResult {
+  const expanded = expandHome(session)
+  if (!expanded.endsWith('.jsonl')) {
+    throw err(
+      `读取失败：${session}（非 .jsonl session 文件）。👉 检查文件或换 session。`,
+    )
+  }
+  if (!existsSync(expanded)) {
+    throw err(`读取失败：${session}（文件不存在）。👉 检查文件或换 session。`)
+  }
+  const headerId = readSessionHeaderId(expanded)
+  if (headerId === undefined) {
+    throw err(
+      `读取失败：${session}（首行非合法 session header）。👉 检查文件或换 session。`,
+    )
+  }
+  return { kind: 'ok', sessionId: headerId, fileName: expanded }
+}
+
+/**
+ * 形态②：sa-id 前缀 → record manifest 精确反查，sessionId=sessionFile header id
+ *（禁止降级 record.id——sa- 形态不可当 sessionId，CQ3 决策）。批量调用方传预取列表
+ *（S3：避免逐 id 全量重扫）；单 id 调用点现场扫一次。
+ */
+async function resolveByRecordId(session: string, agentDir: string, prefetchedManifests: RecordManifest[] | undefined): Promise<ResolveResult> {
+  const manifests = prefetchedManifests ?? (await listRecordManifests(agentDir))
+  const hits = manifests.filter((m) => m.id === session)
+  if (hits.length === 0) {
+    throw err(formatSaIdNotFound(session))
+  }
+  if (hits.length > 1) {
+    throw err(formatSaIdAmbiguous(session, hits))
+  }
+  const record = hits[0]
+  if (!existsSync(record.sessionFile)) {
+    throw err(formatSessionGc(record))
+  }
+  const headerId = readSessionHeaderId(record.sessionFile)
+  if (headerId === undefined) {
+    // header 读不出不降级 record.id（sa- 形态不可当 sessionId，CQ3）
+    throw err(
+      `读取失败：${record.sessionFile}（首行非合法 session header）。👉 检查文件或换 session。`,
+    )
+  }
+  return { kind: 'ok', sessionId: headerId, fileName: record.sessionFile }
+}
+
+/** 形态③：其余片段 → findSessions 透传 source 沿用 F1（零匹配）/ F2（多匹配消歧）。 */
+async function resolveByFragment(session: string, agentDir: string, source?: 'main' | 'subagent'): Promise<ResolveResult> {
   const opts = { limit: 10, ...(source ? { source } : {}) }
   const { matches } = await findSessions(session, agentDir, opts)
   if (matches.length === 0) {
@@ -766,29 +785,22 @@ async function doDetail(params: SessionReadParams, agentDir: string): Promise<To
 /** search action 的默认命中数上限。 */
 const SEARCH_DEFAULT_LIMIT = 20
 
-/** search：session 内全文检索（design §3.4 search，M3 新实现）。 */
-async function doSearch(
-  params: SessionReadParams,
-  agentDir: string,
-  signal?: AbortSignal,
-): Promise<ToolResult> {
-  const resolved = await resolveSessionId(params.session, 'search', agentDir, params.source)
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
-  const pattern = requireStr(params.pattern, 'pattern', 'search')
-  const scope = params.scope ?? 'all'
-  const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
-  const { entries } = await safeParse(resolved.fileName)
-  const tree = buildTreeView(entries)
-  const turns = segmentTurns(entries, new Set(tree.leafPath))
-  const regex = compilePattern(pattern)
-  // S-3：启发式降级时在 header 标注，避免 LLM 把 0 hit(s) 误读为「无匹配」（静默错数据）
-  const degraded = isCatastrophicPattern(pattern)
-  const hits: Array<{
-    turnIndex: number
-    entryIndex: number
-    role: string
-    matchSnippet: string
-  }> = []
+/** search 单条命中（turn 内 entry 定位 + 角色 + 摘要片段）。 */
+interface SearchHit {
+  turnIndex: number
+  entryIndex: number
+  role: string
+  matchSnippet: string
+}
+
+/** search 扫描阶段：遍历 turns 收集命中；每 turn 前检查 abort（MF-5 尽早退出）。 */
+function collectSearchHits(
+  turns: Turn[],
+  regex: RegExp,
+  scope: NonNullable<SessionReadParams['scope']>,
+  signal: AbortSignal | undefined,
+): SearchHit[] {
+  const hits: SearchHit[] = []
   for (const t of turns) {
     // MF-5：Esc/abort 后 pi 已丢弃本 turn 结果，尽早退出避免继续扫描长 session
     if (signal?.aborted) {
@@ -810,14 +822,46 @@ async function doSearch(
       }
     }
   }
-  const truncated = hits.length > limit
-  const sliced = truncated ? hits.slice(0, limit) : hits
+  return hits
+}
+
+/** search 收口阶段：结果文本组装（header 标注降级/scope/截断 + 逐行命中列表）。 */
+function formatSearchText(
+  pattern: string,
+  degraded: boolean,
+  scope: NonNullable<SessionReadParams['scope']>,
+  sliced: SearchHit[],
+  truncated: boolean,
+): string {
   const lines = sliced.map(
     (h) => `  T${pad(h.turnIndex)} #${h.entryIndex} ${h.role}: ${h.matchSnippet}`,
   )
-  const text = `${sliced.length} hit(s) for /${pattern}/${degraded ? '（已降级为字面子串匹配）' : ''}${
+  return `${sliced.length} hit(s) for /${pattern}/${degraded ? '（已降级为字面子串匹配）' : ''}${
     scope !== 'all' ? ' scope=' + scope : ''
   }${truncated ? ` (truncated, showing first ${sliced.length})` : ''}\n${lines.join('\n')}`
+}
+
+/** search：session 内全文检索（design §3.4 search，M3 新实现）。 */
+async function doSearch(
+  params: SessionReadParams,
+  agentDir: string,
+  signal?: AbortSignal,
+): Promise<ToolResult> {
+  const resolved = await resolveSessionId(params.session, 'search', agentDir, params.source)
+  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  const pattern = requireStr(params.pattern, 'pattern', 'search')
+  const scope = params.scope ?? 'all'
+  const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
+  const { entries } = await safeParse(resolved.fileName)
+  const tree = buildTreeView(entries)
+  const turns = segmentTurns(entries, new Set(tree.leafPath))
+  const regex = compilePattern(pattern)
+  // S-3：启发式降级时在 header 标注，避免 LLM 把 0 hit(s) 误读为「无匹配」（静默错数据）
+  const degraded = isCatastrophicPattern(pattern)
+  const hits = collectSearchHits(turns, regex, scope, signal)
+  const truncated = hits.length > limit
+  const sliced = truncated ? hits.slice(0, limit) : hits
+  const text = formatSearchText(pattern, degraded, scope, sliced, truncated)
   return { content: [{ type: 'text', text }], details: { hits: sliced, truncated } }
 }
 
@@ -1187,8 +1231,16 @@ function extractFiles(turns: Turn[]): ToolResult {
 /** commits 提取的 hash 前后上下文字符数（次路径关键词判定窗口）。 */
 const COMMIT_CONTEXT_CHARS = 30
 
-function extractCommits(turns: Turn[]): ToolResult {
-  // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
+/** commits 预设的单条提取结果（hash + 来源 turn + 置信来源 + 上下文片段）。 */
+interface CommitItem {
+  hash: string
+  turn: number
+  source: 'git-cmd' | 'commit-context'
+  context: string
+}
+
+/** 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）。 */
+function collectBashCommands(turns: Turn[]): Map<string, string> {
   const bashCmds = new Map<string, string>()
   for (const t of turns) {
     for (const e of t.entries) {
@@ -1201,16 +1253,39 @@ function extractCommits(turns: Turn[]): ToolResult {
       }
     }
   }
+  return bashCmds
+}
 
-  type CommitItem = {
-    hash: string
-    turn: number
-    source: 'git-cmd' | 'commit-context'
-    context: string
+/** 单条 toolResult 文本的 hash 提取：git-cmd 全收（高置信），否则按上下文关键词过滤（次路径）。 */
+function matchCommitsInResult(
+  text: string,
+  turnIndex: number,
+  isGitBash: boolean,
+  high: CommitItem[],
+  low: CommitItem[],
+): void {
+  for (const m of text.matchAll(SHORT_HASH_RE)) {
+    const hash = m[0]
+    const idx = m.index ?? 0
+    const ctx = text
+      .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
+      .replace(/\s+/g, ' ')
+      .trim()
+    if (isGitBash) {
+      high.push({ hash, turn: turnIndex, source: 'git-cmd', context: ctx })
+    } else if (COMMIT_CTX_RE.test(ctx)) {
+      low.push({ hash, turn: turnIndex, source: 'commit-context', context: ctx })
+    }
   }
+}
+
+/** 主扫描阶段：遍历 toolResult entry，分类收集高/低置信 commit 候选。 */
+function collectCommitCandidates(
+  turns: Turn[],
+  bashCmds: Map<string, string>,
+): { high: CommitItem[]; low: CommitItem[] } {
   const high: CommitItem[] = []
   const low: CommitItem[] = []
-
   for (const t of turns) {
     for (const e of t.entries) {
       if (e.message?.role !== 'toolResult') continue
@@ -1219,23 +1294,14 @@ function extractCommits(turns: Turn[]): ToolResult {
       if (text === '') continue
       const cmd = msg.toolCallId !== undefined ? bashCmds.get(msg.toolCallId) : undefined
       const isGitBash = msg.toolName === 'bash' && cmd !== undefined && GIT_CMD_RE.test(cmd)
-      for (const m of text.matchAll(SHORT_HASH_RE)) {
-        const hash = m[0]
-        const idx = m.index ?? 0
-        const ctx = text
-          .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
-          .replace(/\s+/g, ' ')
-          .trim()
-        if (isGitBash) {
-          high.push({ hash, turn: t.index, source: 'git-cmd', context: ctx })
-        } else if (COMMIT_CTX_RE.test(ctx)) {
-          low.push({ hash, turn: t.index, source: 'commit-context', context: ctx })
-        }
-      }
+      matchCommitsInResult(text, t.index, isGitBash, high, low)
     }
   }
+  return { high, low }
+}
 
-  // 去重：高置信优先，同 hash 保留首次
+/** 收口阶段：去重，高置信优先，同 hash 保留首次。 */
+function dedupeCommits(high: CommitItem[], low: CommitItem[]): CommitItem[] {
   const seen = new Set<string>()
   const items: CommitItem[] = []
   for (const c of high) {
@@ -1248,6 +1314,14 @@ function extractCommits(turns: Turn[]): ToolResult {
     seen.add(c.hash)
     items.push(c)
   }
+  return items
+}
+
+function extractCommits(turns: Turn[]): ToolResult {
+  // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
+  const bashCmds = collectBashCommands(turns)
+  const { high, low } = collectCommitCandidates(turns, bashCmds)
+  const items = dedupeCommits(high, low)
 
   return renderExtractItems(
     'commits',
@@ -1474,6 +1548,19 @@ async function doWorkflow(params: SessionReadParams, agentDir: string): Promise<
   return { content: [{ type: 'text', text }], details }
 }
 
+/** result action 的注入依赖（构造期绑定本文件私有 helper，运行时零查找开销）。 */
+const RESULT_ACTION_DEPS: ResultActionDeps = {
+  err,
+  stripHash,
+  requireStr,
+  resolveSessionId,
+  disambiguate,
+  safeParse,
+  sessionIdPrefixLen: SESSION_ID_PREFIX_LEN,
+}
+
+export { extractFinalAssistantText }
+
 // ===========================================================================
 // 入口：按 action 分发
 // ===========================================================================
@@ -1510,12 +1597,14 @@ export async function handleSessionRead(
       return doExtract(params, agentDir)
     case 'workflow':
       return doWorkflow(params, agentDir)
+    case 'result':
+      return doResult(params, agentDir, RESULT_ACTION_DEPS)
     default: {
-      // exhaustive guard：switch 覆盖全部 9 action，此处 params.action 收窄为 never；
+      // exhaustive guard：switch 覆盖全部 10 action，此处 params.action 收窄为 never；
       // 仅防御运行时非法 action（schema 正常校验下不可达）
       const exhaustive: never = params.action
       throw err(
-        `未知 action "${JSON.stringify(exhaustive)}"。👉 合法 action: find/family/outline/expand/detail/search/export/extract/workflow。`,
+        `未知 action "${JSON.stringify(exhaustive)}"。👉 合法 action: find/family/outline/expand/detail/search/export/extract/workflow/result。`,
       )
     }
   }