@zhushanwen/pi-session-reader 0.3.0 → 0.4.0

package/src/discovery/subagents.ts

@@ -4,7 +4,7 @@ import { join, basename } from 'node:path'
 import type { Entry } from '../core/parser.js'
 import type { Family, SessionRef, SubagentRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
-import { listMainSessions, listSubagentSessions } from './roots.js'
+import { listMainSessions, listSubagentSessions, type SessionFileMeta } from './roots.js'
 import { resolveWorkflows } from './workflows.js'
 
 /**
@@ -20,7 +20,8 @@ import { resolveWorkflows } from './workflows.js'
  *   M2 用 subagent 文件首行 header.id（真实 session id）替换之，使 SubagentRef.sessionId
  *   是真实 id，Q1 隔代关联仍用 data.rootSessionId（不变）。
  * - cleanedUp：subagent 文件被 30 天 TTL GC 后，identity（在文件尾）一并消失。唯一残留痕迹
- *   是 records/<sa-id>.json manifest（subagent 创建时写入，持久存在）。故 manifest 是孤儿/
+ *   是 records/<sa-id>.json manifest（终态 finalize 或 sync 批落标出口写入——subagent
+ *   创建时不写，两写点均先于 30 天 GC 落盘，故 GC 后必残留）。manifest 是孤儿/
  *   cleanedUp 的来源（design §3.3 D-7 "records/*.json manifest 作孤儿补充"）。
  * - workflows：M1 resolveFamily 恒返回 []。M2 在此单独读目标 session 的 workflow-state-link
  *   custom entry → link.data.path（wf-state 文件绝对路径）→ 从文件尾向头找首个非空且
@@ -33,26 +34,77 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
   // manifest 主路径：alive 文件的 meta.path 命中索引 → 透 task/slug/model/status/sessionFile 全字段。
   // 索引未命中（场景 A：嵌套 subagent 的 manifest 不在当前 agentDir，11.5%）走 P-fallback 回退 identity。
   const manifests = await listRecordManifests(agentDir)
-  const manifestBySessionFile = new Map<string, RecordManifest>()
-  for (const m of manifests) manifestBySessionFile.set(m.sessionFile, m)
+  const manifestBySessionFile = indexManifestsBySessionFile(manifests)
 
-  // ---- 1. main sessions：首行 header → byId/childrenOf 素材 + fileStats + 路径反查 ----
-  const mainMetas = await listMainSessions(agentDir)
-  const headers: Entry[] = []
-  const fileStats = new Map<string, { mtime: number; size: number }>()
+  // ---- 1-3. 逐阶段扫描（main → subagent → 孤儿 manifest），累积器显式传递 ----
+  const scan: FamilyFsScan = {
+    headers: [],
+    identities: [],
+    fileStats: new Map(),
+    sessionIdToPath: new Map(),
+    pathToRef: new Map(),
+    aliveSubPaths: new Set(),
+  }
+  await collectMainSessions(agentDir, scan)
+  await collectSubagentIdentities(agentDir, manifestBySessionFile, scan)
+  appendOrphanIdentities(manifests, scan)
+
+  // ---- 4-5. build index + resolve（sessionId 不在 byId → resolveFamily 抛 Error）----
+  if (!scan.sessionIdToPath.has(sessionId)) {
+    throw new Error(
+      `session "${sessionId}" not found under ${agentDir}/sessions — ` +
+        `no main session file whose first-line header id matches. ` +
+        `Verify the sessionId or agentDir; for partial uuid, use findSessions first.`,
+    )
+  }
+  const index = buildFamilyIndex(scan.headers, scan.identities, scan.fileStats)
+  const family = resolveFamily(sessionId, index)
+
+  // ---- 6. 补 M1 占位字段（fileName / subagent cwd）+ workflows ----
+  enrichRefs(family, scan.pathToRef)
+  family.workflows = await resolveWorkflows(sessionId, scan.sessionIdToPath, scan.pathToRef)
+
+  return family
+}
+
+// ============================================================
+// buildFamilyFromFs 扫描阶段 helpers（各阶段显式传入累积器，插入顺序 = 原实现顺序）
+// ============================================================
+
+/** buildFamilyFromFs 各扫描阶段的共享累积器（主函数创建，各阶段 helper 显式传入并写入） */
+interface FamilyFsScan {
+  /** main session headers（buildFamilyIndex byId/childrenOf 素材） */
+  headers: Entry[]
+  /** subagent identity entries（步骤 2 富化 + 步骤 3 孤儿） */
+  identities: Entry[]
+  /** sessionId → { mtime, size }（buildFamilyIndex 存活判定素材） */
+  fileStats: Map<string, { mtime: number; size: number }>
   /** sessionId → 真实文件路径，供 workflows 找目标文件 + enrich 补 fileName */
-  const sessionIdToPath = new Map<string, string>()
+  sessionIdToPath: Map<string, string>
   /** path → 完整 SessionRef（含真实 cwd/fileName/mtime/size），供 enrich + workflow calls 反查 */
-  const pathToRef = new Map<string, SessionRef>()
+  pathToRef: Map<string, SessionRef>
+  /** 已扫描到的 subagent 文件路径集合，供 manifest 孤儿判定（alive 则跳过 manifest） */
+  aliveSubPaths: Set<string>
+}
+
+/** manifest 按 sessionFile 建索引（alive 文件的 meta.path 命中 → 走 manifest 主路径） */
+function indexManifestsBySessionFile(manifests: RecordManifest[]): Map<string, RecordManifest> {
+  const manifestBySessionFile = new Map<string, RecordManifest>()
+  for (const m of manifests) manifestBySessionFile.set(m.sessionFile, m)
+  return manifestBySessionFile
+}
 
+/** 步骤 1：main sessions —— 首行 header → headers + fileStats + 路径反查 */
+async function collectMainSessions(agentDir: string, scan: FamilyFsScan): Promise<void> {
+  const mainMetas = await listMainSessions(agentDir)
   for (const meta of mainMetas) {
     const h = parseHeaderLine(await readFirstLine(meta.path))
     if (!h) continue // 非 session/坏 header → 跳过（不入 byId）
     const entry: Entry = { type: 'session', id: h.id, parentId: null, cwd: h.cwd ?? '' }
     if (h.parentSession) entry.parentSession = h.parentSession
-    headers.push(entry)
-    fileStats.set(h.id, { mtime: meta.mtime, size: meta.size })
-    sessionIdToPath.set(h.id, meta.path)
+    scan.headers.push(entry)
+    scan.fileStats.set(h.id, { mtime: meta.mtime, size: meta.size })
+    scan.sessionIdToPath.set(h.id, meta.path)
     const ref: SessionRef = {
       sessionId: h.id,
       fileName: meta.path,
@@ -61,17 +113,47 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
       cwd: h.cwd ?? '',
     }
     if (h.parentSession) ref.parentSession = h.parentSession
-    pathToRef.set(meta.path, ref)
+    scan.pathToRef.set(meta.path, ref)
+  }
+}
+
+/** identity data 组装（manifest 主，TC-u4-manifest-enrich）：透 task/slug/model/status/sessionFile 全字段 */
+function manifestIdentityData(manifest: RecordManifest): Record<string, unknown> {
+  return {
+    rootSessionId: manifest.rootSessionId,
+    slug: manifest.slug ?? '', // slug 兼容旧 manifest（缺→空串兜底，m0 契约）
+    task: manifest.task,
+    agent: manifest.agentName, // 同语义异名：manifest.agentName ↔ identity.data.agent
+    model: manifest.model,
+    status: manifest.status,
+    sessionFile: manifest.sessionFile,
+  }
+}
+
+/** identity data 组装（P-fallback，ES-p-fallback-no-manifest）：identity 回退取 task/slug/agent */
+function fallbackIdentityData(
+  meta: SessionFileMeta,
+  ident: TailIdentity,
+): Record<string, unknown> {
+  return {
+    rootSessionId: ident.rootSessionId,
+    slug: ident.slug,
+    task: ident.task,
+    agent: ident.agent,
+    // model/status 不可回退（identity 无，探针 15/15），留 undefined
+    sessionFile: meta.path,
   }
+}
 
-  // ---- 2. subagent sessions：首行 header（真实 id）+ manifest 主/identity 回退 → 富字段 identity ----
+/** 步骤 2：subagent sessions —— 首行 header（真实 id）+ manifest 主/identity 回退 → 富字段 identity */
+async function collectSubagentIdentities(
+  agentDir: string,
+  manifestBySessionFile: Map<string, RecordManifest>,
+  scan: FamilyFsScan,
+): Promise<void> {
   // U4 数据流：manifest 命中透全字段；未命中 P-fallback 读尾行 identity 取 task/slug/agent
   //（model/status 不可回退，留 undefined）；无 manifest 无 identity（运行中/异常）跳过。
   const subMetas = await listSubagentSessions(agentDir)
-  const identities: Entry[] = []
-  /** 已扫描到的 subagent 文件路径集合，供 manifest 孤儿判定（alive 则跳过 manifest） */
-  const aliveSubPaths = new Set<string>()
-
   for (const meta of subMetas) {
     const h = parseHeaderLine(await readFirstLine(meta.path))
     if (!h) continue // 非 session/坏 header → 无真实 session id，无法 id 修正，跳过
@@ -79,46 +161,30 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
     // header 可解析即视为 alive（MF-3）：identity 在文件尾行、完成时才写入，运行中的 subagent
     // 无 identity。若此处跳过，步骤 3 会把活文件（含其 manifest）当孤儿收编 → cleanedUp=true，
     // family 把活着的 subagent 显示成 [已清理]，真实 sessionId 永远无法关联。
-    aliveSubPaths.add(meta.path)
+    scan.aliveSubPaths.add(meta.path)
 
     // identity data 组装：manifest 主路径或 P-fallback identity 回退，二选一
     const manifest = manifestBySessionFile.get(meta.path)
     let data: Record<string, unknown>
     if (manifest) {
-      // manifest 主（TC-u4-manifest-enrich）：透 task/slug/model/status/sessionFile 全字段
-      data = {
-        rootSessionId: manifest.rootSessionId,
-        slug: manifest.slug ?? '', // slug 兼容旧 manifest（缺→空串兜底，m0 契约）
-        task: manifest.task,
-        agent: manifest.agentName, // 同语义异名：manifest.agentName ↔ identity.data.agent
-        model: manifest.model,
-        status: manifest.status,
-        sessionFile: manifest.sessionFile,
-      }
+      data = manifestIdentityData(manifest)
     } else {
       // P-fallback（ES-p-fallback-no-manifest）：读尾行 identity 回退取 task/slug/agent
       const ident = await readTailIdentity(meta.path, meta.size)
       if (!ident) continue // 无 identity（ES-p-fallback-no-identity，运行中/异常）→ 跳过
-      data = {
-        rootSessionId: ident.rootSessionId,
-        slug: ident.slug,
-        task: ident.task,
-        agent: ident.agent,
-        // model/status 不可回退（identity 无，探针 15/15），留 undefined
-        sessionFile: meta.path,
-      }
+      data = fallbackIdentityData(meta, ident)
     }
     // id 修正：entry.id 用真实 header.id 替换 sa-xxx 占位
-    identities.push({
+    scan.identities.push({
       type: 'custom',
       id: realId,
       parentId: null,
       customType: 'subagent-identity',
       data,
     })
-    fileStats.set(realId, { mtime: meta.mtime, size: meta.size })
-    sessionIdToPath.set(realId, meta.path)
-    pathToRef.set(meta.path, {
+    scan.fileStats.set(realId, { mtime: meta.mtime, size: meta.size })
+    scan.sessionIdToPath.set(realId, meta.path)
+    scan.pathToRef.set(meta.path, {
       sessionId: realId,
       fileName: meta.path,
       mtime: meta.mtime,
@@ -126,15 +192,20 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
       cwd: h.cwd ?? '',
     })
   }
+}
 
-  // ---- 3. records manifest → 孤儿（cleanedUp，ES-orphan-manifest）----
-  // manifest 在 subagent 创建时写入，.jsonl 被 GC 后仍残留。alive 的（sessionFile 已在步骤 2
-  // 扫到）跳过；未扫到的 = 文件已 GC → 孤儿。用 manifest 完整富字段填 SubagentRef，
-  // sessionFile 保留 manifest 的 GC 路径（不置空，供 LLM 知晓原位置），cleanedUp 由
-  // buildFamilyIndex 的 !fileStats.has(ident.id) 判 true（ident.id=manifest.id 不在 fileStats）。
+/**
+ * 步骤 3：records manifest → 孤儿（cleanedUp，ES-orphan-manifest）。
+ * manifest 由终态 finalize / sync 批落标出口写入（创建时不写），.jsonl 被 GC 后仍
+ * 残留。alive 的（sessionFile 已在步骤 2
+ * 扫到）跳过；未扫到的 = 文件已 GC → 孤儿。用 manifest 完整富字段填 SubagentRef，
+ * sessionFile 保留 manifest 的 GC 路径（不置空，供 LLM 知晓原位置），cleanedUp 由
+ * buildFamilyIndex 的 !fileStats.has(ident.id) 判 true（ident.id=manifest.id 不在 fileStats）。
+ */
+function appendOrphanIdentities(manifests: RecordManifest[], scan: FamilyFsScan): void {
   for (const m of manifests) {
-    if (aliveSubPaths.has(m.sessionFile)) continue
-    identities.push({
+    if (scan.aliveSubPaths.has(m.sessionFile)) continue
+    scan.identities.push({
       type: 'custom',
       id: m.id,
       parentId: null,
@@ -151,23 +222,6 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
       },
     })
   }
-
-  // ---- 4-5. build index + resolve（sessionId 不在 byId → resolveFamily 抛 Error）----
-  if (!sessionIdToPath.has(sessionId)) {
-    throw new Error(
-      `session "${sessionId}" not found under ${agentDir}/sessions — ` +
-        `no main session file whose first-line header id matches. ` +
-        `Verify the sessionId or agentDir; for partial uuid, use findSessions first.`,
-    )
-  }
-  const index = buildFamilyIndex(headers, identities, fileStats)
-  const family = resolveFamily(sessionId, index)
-
-  // ---- 6. 补 M1 占位字段（fileName / subagent cwd）+ workflows ----
-  enrichRefs(family, pathToRef)
-  family.workflows = await resolveWorkflows(sessionId, sessionIdToPath, pathToRef)
-
-  return family
 }
 
 // ============================================================
@@ -221,6 +275,15 @@ function parseHeaderLine(line: string | undefined): SessionHeader | null {
   return h
 }
 
+/** readTailIdentity 的成功返回形状（rootSessionId 必有，其余存在才带） */
+type TailIdentity = {
+  rootSessionId: string
+  slug: string
+  task?: string
+  agent?: string
+  parentRecordId?: string
+}
+
 /**
  * 读 subagent 文件尾部（最后 64KB）找 subagent-identity entry，返回 rootSessionId + slug + task + agent。
  *
@@ -238,54 +301,36 @@ function parseHeaderLine(line: string | undefined): SessionHeader | null {
 export async function readTailIdentity(
   path: string,
   size?: number,
-): Promise<
-  | { rootSessionId: string; slug: string; task?: string; agent?: string; parentRecordId?: string }
-  | undefined
-> {
-  // size 未传时内部 stat 获取（execution-tree.ts 复用时无 size）
-  let resolvedSize = size
-  if (resolvedSize === undefined) {
-    try {
-      resolvedSize = (await stat(path)).size
-    } catch {
-      return undefined // 文件不存在/读失败 → undefined
-    }
-  }
+): Promise<TailIdentity | undefined> {
+  const resolvedSize = await resolveTailSize(path, size)
+  if (resolvedSize === undefined) return undefined // 文件不存在/读失败 → undefined
   if (resolvedSize === 0) return undefined
+  const text = await readTailText(path, resolvedSize)
+  if (text === undefined) return undefined
+  const line = extractTailIdentityLine(text, resolvedSize)
+  if (line === undefined) return undefined
+  return parseTailIdentityLine(line)
+}
+
+/** 尾读 size 解析：size 未传时内部 stat 获取（execution-tree.ts 复用时无 size）；stat 失败 → undefined */
+async function resolveTailSize(path: string, size?: number): Promise<number | undefined> {
+  if (size !== undefined) return size
+  try {
+    return (await stat(path)).size
+  } catch {
+    return undefined // 文件不存在/读失败 → undefined
+  }
+}
+
+/** 读文件尾部 min(64KB, size) 字节为文本；打开/读取失败 → undefined */
+async function readTailText(path: string, resolvedSize: number): Promise<string | undefined> {
   let fh: FileHandle | undefined
   try {
     fh = await open(path, 'r')
     const len = Math.min(TAIL_READ_BYTES, resolvedSize)
     const buf = Buffer.alloc(len)
     await fh.read(buf, 0, len, Math.max(0, resolvedSize - len))
-    const text = buf.toString('utf8')
-    const idx = text.lastIndexOf('subagent-identity')
-    if (idx < 0) return undefined
-    // 行首若在读窗口外（identity 行 > 64KB，整行塞不下）→ 无法可靠解析，跳过
-    const lineStartSearch = text.lastIndexOf('\n', idx)
-    if (lineStartSearch < 0 && resolvedSize > len) return undefined
-    const start = lineStartSearch < 0 ? 0 : lineStartSearch + 1
-    let end = text.indexOf('\n', idx)
-    if (end < 0) end = text.length
-    const line = text.slice(start, end)
-    let raw: unknown
-    try {
-      raw = JSON.parse(line)
-    } catch {
-      return undefined
-    }
-    const data = (raw as Record<string, unknown> | undefined)?.data as
-      | Record<string, unknown>
-      | undefined
-    if (!data || typeof data.rootSessionId !== 'string') return undefined
-    return {
-      rootSessionId: data.rootSessionId,
-      slug: typeof data.slug === 'string' ? data.slug : '',
-      task: typeof data.task === 'string' ? data.task : undefined,
-      agent: typeof data.agent === 'string' ? data.agent : undefined,
-      parentRecordId:
-        typeof data.parentRecordId === 'string' ? data.parentRecordId : undefined,
-    }
+    return buf.toString('utf8')
   } catch {
     return undefined
   } finally {
@@ -293,6 +338,45 @@ export async function readTailIdentity(
   }
 }
 
+/**
+ * 从尾窗文本定位最后一个 subagent-identity 标记所在行（多次重写时取最新）。
+ * 无标记 / 行首在读窗口外（identity 行 > 64KB，整行塞不下）→ undefined。
+ */
+function extractTailIdentityLine(text: string, resolvedSize: number): string | undefined {
+  const idx = text.lastIndexOf('subagent-identity')
+  if (idx < 0) return undefined
+  const len = Math.min(TAIL_READ_BYTES, resolvedSize)
+  // 行首若在读窗口外（identity 行 > 64KB，整行塞不下）→ 无法可靠解析，跳过
+  const lineStartSearch = text.lastIndexOf('\n', idx)
+  if (lineStartSearch < 0 && resolvedSize > len) return undefined
+  const start = lineStartSearch < 0 ? 0 : lineStartSearch + 1
+  let end = text.indexOf('\n', idx)
+  if (end < 0) end = text.length
+  return text.slice(start, end)
+}
+
+/** identity 行 → 富字段结果；JSON 损坏 / 缺 rootSessionId → undefined */
+function parseTailIdentityLine(line: string): TailIdentity | undefined {
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return undefined
+  }
+  const data = (raw as Record<string, unknown> | undefined)?.data as
+    | Record<string, unknown>
+    | undefined
+  if (!data || typeof data.rootSessionId !== 'string') return undefined
+  return {
+    rootSessionId: data.rootSessionId,
+    slug: typeof data.slug === 'string' ? data.slug : '',
+    task: typeof data.task === 'string' ? data.task : undefined,
+    agent: typeof data.agent === 'string' ? data.agent : undefined,
+    parentRecordId:
+      typeof data.parentRecordId === 'string' ? data.parentRecordId : undefined,
+  }
+}
+
 // ============================================================
 // records manifest（孤儿 / cleanedUp 来源）
 // ============================================================
@@ -301,7 +385,7 @@ export interface RecordManifest {
   id: string
   rootSessionId: string
   agentName?: string
-  /** subagent session.jsonl 绝对路径（创建时写入；文件 GC 后路径仍残留） */
+  /** subagent session.jsonl 绝对路径（manifest 写入时快照；文件 GC 后路径仍残留） */
   sessionFile: string
   /** subagent 任务文本（探针 20/20 全有；旧 manifest 缺→undefined） */
   task?: string
@@ -343,8 +427,8 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
 
 /**
  * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
- * /JSON 损坏）跳过，不中断扫描。
+ * 每个 manifest 由终态 finalize 或 sync 批落标出口写入（创建时不写），持久存在即使
+ * .jsonl 被 GC。坏 manifest（缺必填字段/JSON 损坏）跳过，不中断扫描。
  */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
   const root = join(agentDir, 'subagents')

package/src/discovery/workflows.ts

@@ -34,42 +34,57 @@ export function extractCallSessionFiles(snap: unknown): string[] {
   const out: string[] = []
   if (typeof snap !== 'object' || snap === null) return out
   const s = snap as Record<string, unknown>
-  const isNew = s.v === 'wf-run-v1' || s.v === 'wf-run-v2'
-  let callsRaw: unknown
-  if (isNew) {
-    const state = s.state
-    callsRaw =
-      typeof state === 'object' && state !== null
-        ? (state as Record<string, unknown>).calls
-        : undefined
-  } else {
-    callsRaw = s.callCache
-  }
+  const isNew = isNewSnapshotFormat(s)
+  const callsRaw = extractCallsRaw(s, isNew)
   if (!Array.isArray(callsRaw)) return out
   for (const c of callsRaw) {
     if (typeof c !== 'object' || c === null) continue
-    const co = c as Record<string, unknown>
-    // NEW: call 本身；OLD: {key, value}，取 value
-    const item: Record<string, unknown> = isNew
-      ? co
-      : typeof co.value === 'object' && co.value !== null
-        ? (co.value as Record<string, unknown>)
-        : co
-    const sf = item.sessionFile
-    if (typeof sf === 'string') {
-      out.push(sf)
-      continue
-    }
-    const result = item.result
-    const sf2 =
-      typeof result === 'object' && result !== null
-        ? (result as Record<string, unknown>).sessionFile
-        : undefined
-    if (typeof sf2 === 'string') out.push(sf2)
+    const item = resolveCallItem(c as Record<string, unknown>, isNew)
+    const sf = extractSessionFileFromItem(item)
+    if (sf !== undefined) out.push(sf)
   }
   return out
 }
 
+/** 快照是否为 NEW 格式（v="wf-run-v1"/"wf-run-v2"，读取面形状一致） */
+function isNewSnapshotFormat(s: Record<string, unknown>): boolean {
+  return s.v === 'wf-run-v1' || s.v === 'wf-run-v2'
+}
+
+/** 按格式取 calls 原始集合：NEW 读 state.calls（state 守卫后取），OLD 读顶层 callCache */
+function extractCallsRaw(s: Record<string, unknown>, isNew: boolean): unknown {
+  if (isNew) {
+    const state = s.state
+    return typeof state === 'object' && state !== null
+      ? (state as Record<string, unknown>).calls
+      : undefined
+  }
+  return s.callCache
+}
+
+/**
+ * 单条 call 归一为可取 sessionFile 的对象：
+ * NEW: call 本身；OLD: {key, value}，取 value（value 非对象时回退 call 本身，容错脏数据）
+ */
+function resolveCallItem(co: Record<string, unknown>, isNew: boolean): Record<string, unknown> {
+  if (isNew) return co
+  const value = co.value
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : co
+}
+
+/** 从归一后的 call 对象提 sessionFile：顶层优先，回退 result.sessionFile；均缺 → undefined */
+function extractSessionFileFromItem(item: Record<string, unknown>): string | undefined {
+  const sf = item.sessionFile
+  if (typeof sf === 'string') return sf
+  const result = item.result
+  const sf2 =
+    typeof result === 'object' && result !== null
+      ? (result as Record<string, unknown>).sessionFile
+      : undefined
+  if (typeof sf2 === 'string') return sf2
+  return undefined
+}
+
 /**
  * 读 wf-state 文件，从尾向头找首个 trim 非空且 JSON.parse 成功的行，返回解析后的原始对象。
  *

package/src/index.ts

@@ -21,16 +21,27 @@ import { createSessionCommand } from './tui/session-command.js'
 
 const SessionReadSchema = Type.Object({
   action: StringEnum(
-    ['find', 'family', 'outline', 'expand', 'detail', 'search', 'export', 'extract', 'workflow'],
+    [
+      'find',
+      'family',
+      'outline',
+      'expand',
+      'detail',
+      'search',
+      'export',
+      'extract',
+      'workflow',
+      'result',
+    ],
     {
       description:
-        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail).',
+        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail), result (fetch a subagent session final result text — same content as its completion notice; session = single id or comma-separated batch of at most 10, optional limit caps chars per item).',
     },
   ),
   session: Type.Optional(
     Type.String({
       description:
-        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow. # prefix auto-stripped.',
+        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow/result. result also accepts a comma-separated list of up to 10 ids. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
@@ -91,7 +102,10 @@ const SessionReadSchema = Type.Object({
     }),
   ),
   limit: Type.Optional(
-    Type.Number({ description: 'find/search: max results. Default 20.' }),
+    Type.Number({
+      description:
+        'find/search: max results. Default 20. result: max chars per item, default 8000 (overlong text truncated with a pointer to the full file).',
+    }),
   ),
   what: Type.Optional(
     StringEnum(
@@ -129,12 +143,13 @@ const guidelines = [
   'family traces fork parents/children, subagent sessions, and workflow runs.',
   'extract what=<type> to pull user messages / commands / files / commits / tool results across turns (optional tool= filter for commands/tool-results).',
   "workflow action to see workflow run overviews (status/budget/steps). Each step's call sessionId can jump to outline/detail for deep reading.",
+  "result action to fetch a subagent's final result text (same content as its completion notice): session takes a single sa-id/uuid/path or a comma-separated batch of at most 10; optional limit caps chars per item (default 8000, truncated items carry a pointer to the full file).",
   'Errors carry a 👉 recovery hint—follow it to retry in one step.',
 ]
 
 // ---- 工具 description（design §3.4，照搬措辞）----
 
-const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
+const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Ten actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail), result (fetch a subagent session final result text, same content as its completion notice; single id or comma-separated batch ≤10, optional limit chars per item default 8000). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
 
 /**
  * 已注册过 TUI provider/command 的 pi 实例集合。