@zhushanwen/pi-session-reader 0.1.0 → 0.2.0

package/src/discovery/subagents.ts

@@ -1,11 +1,11 @@
-import { readFile, readdir, open } from 'node:fs/promises'
+import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import { join, basename } from 'node:path'
 import type { Entry } from '../core/parser.js'
-import { parseSessionContent } from '../core/parser.js'
-import type { Family, SessionRef, SubagentRef, WorkflowRef } from '../core/family.js'
+import type { Family, SessionRef, SubagentRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
 import { listMainSessions, listSubagentSessions } from './roots.js'
+import { resolveWorkflows } from './workflows.js'
 
 /**
  * [M2 discovery] 从文件系统构建某 session 的完整家族（IO 适配层）。
@@ -28,6 +28,13 @@ import { listMainSessions, listSubagentSessions } from './roots.js'
  * @throws sessionId 不在任意 main session header → Error（M3 tool-adapter 层转 F1 恢复指引）
  */
 export async function buildFamilyFromFs(sessionId: string, agentDir: string): Promise<Family> {
+  // ---- 0. record manifest 索引（U4：sessionFile → manifest，供 alive 扫描查富字段）----
+  // 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)
+
   // ---- 1. main sessions：首行 header → byId/childrenOf 素材 + fileStats + 路径反查 ----
   const mainMetas = await listMainSessions(agentDir)
   const headers: Entry[] = []
@@ -56,7 +63,9 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
     pathToRef.set(meta.path, ref)
   }
 
-  // ---- 2. subagent sessions：首行 header（真实 id）+ 尾行 identity → 修正 identity ----
+  // ---- 2. subagent sessions：首行 header（真实 id）+ manifest 主/identity 回退 → 富字段 identity ----
+  // 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） */
@@ -69,17 +78,42 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
     // header 可解析即视为 alive（MF-3）：identity 在文件尾行、完成时才写入，运行中的 subagent
     // 无 identity。若此处跳过，步骤 3 会把活文件（含其 manifest）当孤儿收编 → cleanedUp=true，
     // family 把活着的 subagent 显示成 [已清理]，真实 sessionId 永远无法关联。
-    // 注意：sessionIdToPath/pathToRef 仍需 identity（依赖 realId 的 rootSessionId/slug）。
     aliveSubPaths.add(meta.path)
-    const ident = await readTailIdentity(meta.path, meta.size)
-    if (!ident) continue // 无 identity → 无法确定 rootSessionId（不完整/坏 session），跳过
-    // id 修正：entry.id 用真实 header.id 替换 sa-xxx 占位。data.rootSessionId/slug 原样保留。
+
+    // 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,
+      }
+    } 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,
+      }
+    }
+    // id 修正：entry.id 用真实 header.id 替换 sa-xxx 占位
     identities.push({
       type: 'custom',
       id: realId,
       parentId: null,
       customType: 'subagent-identity',
-      data: { rootSessionId: ident.rootSessionId, slug: ident.slug },
+      data,
     })
     fileStats.set(realId, { mtime: meta.mtime, size: meta.size })
     sessionIdToPath.set(realId, meta.path)
@@ -92,11 +126,11 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
     })
   }
 
-  // ---- 3. records manifest → 孤儿（cleanedUp）----
+  // ---- 3. records manifest → 孤儿（cleanedUp，ES-orphan-manifest）----
   // manifest 在 subagent 创建时写入，.jsonl 被 GC 后仍残留。alive 的（sessionFile 已在步骤 2
-  // 扫到）跳过；未扫到的 = 文件已 GC → 孤儿，ident.id 用 manifest.id（sa-xxx），不进 fileStats
-  // → buildFamilyIndex 的 !fileStats.has(ident.id) 判 cleanedUp=true。
-  const manifests = await listRecordManifests(agentDir)
+  // 扫到）跳过；未扫到的 = 文件已 GC → 孤儿。用 manifest 完整富字段填 SubagentRef，
+  // sessionFile 保留 manifest 的 GC 路径（不置空，供 LLM 知晓原位置），cleanedUp 由
+  // buildFamilyIndex 的 !fileStats.has(ident.id) 判 true（ident.id=manifest.id 不在 fileStats）。
   for (const m of manifests) {
     if (aliveSubPaths.has(m.sessionFile)) continue
     identities.push({
@@ -104,8 +138,16 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
       id: m.id,
       parentId: null,
       customType: 'subagent-identity',
-      // 孤儿的真实 slug 随文件 GC 丢失，用 manifest.agentName 兜底（agent 类型名，非 task 标签）
-      data: { rootSessionId: m.rootSessionId, slug: m.agentName ?? '' },
+      data: {
+        rootSessionId: m.rootSessionId,
+        // 孤儿 slug 随文件 GC 丢失：优先 manifest.slug，回退 agentName（agent 类型名），再兜底空串
+        slug: m.slug ?? m.agentName ?? '',
+        task: m.task,
+        agent: m.agentName, // 同语义异名映射
+        model: m.model,
+        status: m.status,
+        sessionFile: m.sessionFile,
+      },
     })
   }
 
@@ -179,29 +221,48 @@ function parseHeaderLine(line: string | undefined): SessionHeader | null {
 }
 
 /**
- * 读 subagent 文件尾部（最后 64KB）找 subagent-identity entry，返回 rootSessionId + slug。
+ * 读 subagent 文件尾部（最后 64KB）找 subagent-identity entry，返回 rootSessionId + slug + task + agent。
  *
  * identity 在文件尾行（探查确认；design §3.3 D-7 "尾部"）。用 lastIndexOf 定位最后一个
  * subagent-identity 标记（多次重写时取最新），提取该行边界内的 JSON 解析。identity 行
  * 超 64KB（极罕见，实测 1/3430）会截断 → 解析失败 → 返回 undefined（该 subagent 不收）。
+ *
+ * U4 扩展返回 task/agent（P-fallback 富化用）：从 identity.data.task / data.agent 提取，
+ * 存在则带。model/status 在 identity 不存在（探针 15/15 无），P-fallback 时由调用方留 undefined。
+ *
+ * M3b 扩展（IF3 三级数据源 ②）：返回 parentRecordId（identity.data.parentRecordId，新版本
+ * session-runner 才写；当前本机旧数据无此字段→undefined）。size 改 optional——buildFamilyFromFs
+ * 传 size（已有 meta.size 省一次 stat），buildExecutionTree 不传 size（内部 stat 获取）。
  */
-async function readTailIdentity(
+export async function readTailIdentity(
   path: string,
-  size: number,
-): Promise<{ rootSessionId: string; slug: string } | undefined> {
-  if (size === 0) return undefined
+  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
+    }
+  }
+  if (resolvedSize === 0) return undefined
   let fh: FileHandle | undefined
   try {
     fh = await open(path, 'r')
-    const len = Math.min(TAIL_READ_BYTES, size)
+    const len = Math.min(TAIL_READ_BYTES, resolvedSize)
     const buf = Buffer.alloc(len)
-    await fh.read(buf, 0, len, Math.max(0, size - 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 && size > len) return undefined
+    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
@@ -219,6 +280,10 @@ async function readTailIdentity(
     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,
     }
   } catch {
     return undefined
@@ -231,12 +296,28 @@ async function readTailIdentity(
 // records manifest（孤儿 / cleanedUp 来源）
 // ============================================================
 
-interface RecordManifest {
+export interface RecordManifest {
   id: string
   rootSessionId: string
   agentName?: string
   /** subagent session.jsonl 绝对路径（创建时写入；文件 GC 后路径仍残留） */
   sessionFile: string
+  /** subagent 任务文本（探针 20/20 全有；旧 manifest 缺→undefined） */
+  task?: string
+  /** slug 标签（探针 20/20 全有；旧 manifest 缺→undefined） */
+  slug?: string
+  /** 模型 id（探针 20/20 全有；旧 manifest 缺→undefined） */
+  model?: string
+  /** 终态 completed/failed/running（探针 20/20 全有；旧 manifest 缺→undefined） */
+  status?: string
+  /**
+   * 直接父 subagent 的 record id（M3a 落盘镜像；depth=0 顶层 subagent 为 undefined）。
+   *
+   * session-reader 读侧镜像（IF2）：manifest 主路径透出，旧 manifest 缺此字段（undefined）。
+   * isRecordManifest 校验不改（3 必填不变）。buildExecutionTree（core/execution-tree.ts）
+   * 据此建精确父子链，三级数据源优先级 ①（DM4）。
+   */
+  parentRecordId?: string
 }
 
 function isRecordManifest(v: unknown): v is RecordManifest {
@@ -264,7 +345,7 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
   }
 }
 
-async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
+export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
   const root = join(agentDir, 'subagents')
   const out: RecordManifest[] = []
   async function walk(dir: string): Promise<void> {
@@ -289,142 +370,22 @@ async function listRecordManifests(agentDir: string): Promise<RecordManifest[]>
 }
 
 // ============================================================
-// workflow-state 链路（M1 family.workflows 的填充）
+// 文件名 sessionId 提取（find.ts + discovery/workflows.ts 共用 helper）
 // ============================================================
-
-/**
- * 从 wf-state 快照对象提取 calls[].sessionFile（绝对路径数组）。
- *
- * 两种格式（探查确认，本机 371 个 wf 文件）：
- * - NEW (v="wf-run-v1")：state.calls[]，每项顶层 .sessionFile（258 文件 / 1590 sessionFile）
- * - OLD (无 v)：callCache[]=[{key,value}]，value.sessionFile（112 文件 / 0 sessionFile，旧 pi 不持久化）
- */
-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'
-  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
-  }
-  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)
-  }
-  return out
-}
-
-/**
- * 读 wf-state 文件，从最后一个有效快照行提取 calls 的 sessionFile 路径。
- *
- * wf 文件每行是一个完整快照（多行 = 周期性追加，最后一行最新）。从尾向头找首个可解析行。
- */
-async function readWorkflowCallSessionFiles(wfPath: string): Promise<string[]> {
-  let content: string
-  try {
-    content = await readFile(wfPath, 'utf8')
-  } catch {
-    return [] // wf 文件不存在/读失败 → 空 calls（不抛错）
-  }
-  const lines = content.split('\n')
-  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
-  for (let i = lines.length - 1; i >= 0; i--) {
-    if (lines[i].trim() === '') continue
-    try {
-      return extractCallSessionFiles(JSON.parse(lines[i]))
-    } catch {
-      continue // 坏行，试上一行
-    }
-  }
-  return []
-}
+//
+// workflow-state 发现链路（resolveWorkflows / extractCallSessionFiles /
+// readRunSnapshot / sessionRefFromPath）已迁至 discovery/workflows.ts（w5 架构归位，
+// SSOT §6.3 workflow 与 subagent 发现解耦）。本函数被 find.ts + workflows.ts 共用，
+// 故留原位 export。
 
 /** 从文件名（<timestamp>_<sessionId>.jsonl）提取 sessionId；非 uuid 特征返回空串。 */
-function extractSessionIdFromFilename(name: string): string {
+export function extractSessionIdFromFilename(name: string): string {
   const noExt = name.replace(/\.jsonl.*$/, '')
   const idx = noExt.lastIndexOf('_')
   const candidate = idx >= 0 ? noExt.slice(idx + 1) : noExt
   return /^[0-9a-f-]{8,}$/i.test(candidate) ? candidate : ''
 }
 
-/**
- * 从 sessionFile 绝对路径反查 SessionRef。优先用已扫描的 pathToRef（含真实 id/cwd/stat）；
- * 找不到（文件 GC/路径迁移）返回 fileName-only 最小 SessionRef（不抛错）。
- */
-function sessionRefFromPath(path: string, pathToRef: Map<string, SessionRef>): SessionRef {
-  const existing = pathToRef.get(path)
-  if (existing) return existing
-  return {
-    sessionId: extractSessionIdFromFilename(basename(path)),
-    fileName: path,
-    mtime: 0,
-    sizeBytes: 0,
-    cwd: '',
-  }
-}
-
-/**
- * 读目标 session 文件全文，解析 workflow-state-link custom entries，构造 WorkflowRef[]。
- * 同一 runId 的多个 link（workflow 多次更新产生）按 runId 去重，取最新 link（path 相同）。
- */
-async function resolveWorkflows(
-  sessionId: string,
-  sessionIdToPath: Map<string, string>,
-  pathToRef: Map<string, SessionRef>,
-): Promise<WorkflowRef[]> {
-  const targetPath = sessionIdToPath.get(sessionId)
-  if (!targetPath) return [] // 兜底（buildFamilyFromFs 已校验 sessionId 存在）
-  let content: string
-  try {
-    content = await readFile(targetPath, 'utf8')
-  } catch {
-    return []
-  }
-  const { entries } = parseSessionContent(content)
-  const linkByRunId = new Map<string, { runId: string; path: string }>()
-  for (const e of entries) {
-    if (e.customType !== 'workflow-state-link') continue
-    const data = e.data as Record<string, unknown> | undefined
-    const runId = data?.runId
-    const path = data?.path
-    if (typeof runId === 'string' && typeof path === 'string') {
-      linkByRunId.set(runId, { runId, path }) // 后写覆盖前写（取最新 link）
-    }
-  }
-  const workflows: WorkflowRef[] = []
-  for (const { runId, path } of linkByRunId.values()) {
-    const sessionFiles = await readWorkflowCallSessionFiles(path)
-    workflows.push({
-      runId,
-      stateFile: path,
-      calls: sessionFiles.map((sf) => sessionRefFromPath(sf, pathToRef)),
-    })
-  }
-  return workflows
-}
-
 // ============================================================
 // enrich：补 M1 占位字段（fileName / subagent cwd）
 // ============================================================

package/src/discovery/workflows.ts

@@ -0,0 +1,162 @@
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { parseSessionContent } from '../core/parser.js'
+import type { SessionRef, WorkflowRef } from '../core/family.js'
+import { extractSessionIdFromFilename } from './subagents.js'
+
+// ============================================================
+// workflow-state 发现链路（w5 从 subagents.ts 物理迁移，架构归位 SSOT §6.3）
+// ============================================================
+//
+// 本文件持有 workflow run 的发现与 sessionFile 提取逻辑（IO 适配层）：
+// - resolveWorkflows：读目标 session 的 workflow-state-link custom entry → 每个 link 的
+//   wf-state 文件 → 提 calls 的 sessionFile → SessionRef[]。返回 WorkflowRef[]（family.workflows 腿）。
+// - readRunSnapshot：读 wf-state 文件尾向找首个可解析行，返回原始对象（unknown，格式收窄交 core 层）。
+// - extractCallSessionFiles：从快照对象提 calls 的 sessionFile 绝对路径数组（NEW/OLD 双格式）。
+// - sessionRefFromPath：sessionFile 路径 → SessionRef（命中 pathToRef 取完整，否则文件名提取最小 ref）。
+//
+// 分层约定（w5 TC-wf-core-pure-logic）：IO 全在 discovery/，core/workflow.ts 的
+// parseRunSnapshot/renderWorkflowOverview 是纯逻辑零 IO（喂 mock 可单测）。readRunSnapshot 返
+// unknown 不收窄——NEW/OLD 双格式的类型化是 core 层 parseRunSnapshot 的职责（TC-wf-snapshot-version-union）。
+//
+// extractSessionIdFromFilename 留在 subagents.ts（find.ts + 导出契约测试直接消费），此处反向 import。
+
+/**
+ * 从 wf-state 快照对象提取 calls[].sessionFile（绝对路径数组）。
+ *
+ * 两种格式（探查确认，本机 371 个 wf 文件）：
+ * - NEW (v="wf-run-v1")：state.calls[]，每项顶层 .sessionFile（258 文件 / 1590 sessionFile）
+ * - OLD (无 v)：callCache[]=[{key,value}]，value.sessionFile（112 文件 / 0 sessionFile，旧 pi 不持久化）
+ */
+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'
+  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
+  }
+  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)
+  }
+  return out
+}
+
+/**
+ * 读 wf-state 文件，从尾向头找首个 trim 非空且 JSON.parse 成功的行，返回解析后的原始对象。
+ *
+ * 拆解自原 readWorkflowCallSessionFiles 的读行职责（w5 TC-wf-core-pure-logic）——后者=读行+
+ * 提 sessionFile 的胶水，迁移后由 readRunSnapshot（读行，返 unknown）+ extractCallSessionFiles
+ * （提 sessionFile）组合替代。返回类型 unknown：IO 层不假设格式，类型收窄交 core/workflow.ts
+ * 的 parseRunSnapshot（C-readrunsnapshot-unknown，TC-wf-snapshot-version-union）。
+ *
+ * 尾向回退策略（沿用原实现，ES-wf-snapshot-partial）：wf 文件是 rewrite 覆盖模式，读撞 rewrite
+ * 中点时末行是半截 JSON（parse 失败）→ 试上一完整行；单行文件半行 → 全失败 → undefined。
+ * 文件不存在/读失败/全行不可解析 → undefined（不抛错，调用方 resolveWorkflows 据此 calls=[]）。
+ */
+export async function readRunSnapshot(wfPath: string): Promise<unknown | undefined> {
+  let content: string
+  try {
+    content = await readFile(wfPath, 'utf8')
+  } catch {
+    return undefined // wf 文件不存在/读失败 → undefined（不抛错）
+  }
+  const lines = content.split('\n')
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].trim() === '') continue
+    try {
+      return JSON.parse(lines[i])
+    } catch {
+      continue // 坏行（含 rewrite 中点半截 JSON），试上一行
+    }
+  }
+  return undefined
+}
+
+/**
+ * 从 sessionFile 绝对路径反查 SessionRef。优先用已扫描的 pathToRef（含真实 id/cwd/stat）；
+ * 找不到（文件 GC/路径迁移）返回 fileName-only 最小 SessionRef（不抛错）。
+ */
+function sessionRefFromPath(path: string, pathToRef: Map<string, SessionRef>): SessionRef {
+  const existing = pathToRef.get(path)
+  if (existing) return existing
+  return {
+    sessionId: extractSessionIdFromFilename(basename(path)),
+    fileName: path,
+    mtime: 0,
+    sizeBytes: 0,
+    cwd: '',
+  }
+}
+
+/**
+ * 读目标 session 文件全文，解析 workflow-state-link custom entries，构造 WorkflowRef[]。
+ * 同一 runId 的多个 link（workflow 多次更新产生）按 runId 去重，取最新 link（path 相同）。
+ *
+ * 内部用 readRunSnapshot + extractCallSessionFiles 组合替代原 readWorkflowCallSessionFiles
+ *（w5 迁移，行为等价）。**签名与返回值结构（WorkflowRef[]{runId,stateFile,calls:SessionRef[]}）
+ * 完全不变**（C-resolveworkflows-signature，保 m1 已冻结交付的消费者）。
+ */
+export async function resolveWorkflows(
+  sessionId: string,
+  sessionIdToPath: Map<string, string>,
+  pathToRef: Map<string, SessionRef>,
+): Promise<WorkflowRef[]> {
+  const targetPath = sessionIdToPath.get(sessionId)
+  if (!targetPath) return [] // 兜底（buildFamilyFromFs 已校验 sessionId 存在）
+  let content: string
+  try {
+    content = await readFile(targetPath, 'utf8')
+  } catch {
+    return []
+  }
+  const { entries } = parseSessionContent(content)
+  const linkByRunId = new Map<string, { runId: string; path: string }>()
+  for (const e of entries) {
+    if (e.customType !== 'workflow-state-link') continue
+    const data = e.data as Record<string, unknown> | undefined
+    const runId = data?.runId
+    const path = data?.path
+    if (typeof runId === 'string' && typeof path === 'string') {
+      linkByRunId.set(runId, { runId, path }) // 后写覆盖前写（取最新 link）
+    }
+  }
+  const workflows: WorkflowRef[] = []
+  for (const { runId, path } of linkByRunId.values()) {
+    const snap = await readRunSnapshot(path)
+    const sessionFiles = snap === undefined ? [] : extractCallSessionFiles(snap)
+    workflows.push({
+      runId,
+      stateFile: path,
+      calls: sessionFiles.map((sf) => sessionRefFromPath(sf, pathToRef)),
+    })
+  }
+  return workflows
+}

package/src/index.ts

@@ -21,16 +21,16 @@ import { createSessionCommand } from './tui/session-command.js'
 
 const SessionReadSchema = Type.Object({
   action: StringEnum(
-    ['find', 'family', 'outline', 'expand', 'detail', 'search', 'export', 'extract'],
+    ['find', 'family', 'outline', 'expand', 'detail', 'search', 'export', 'extract', 'workflow'],
     {
       description:
-        'Action to perform: find (locate session), family (fork/subagent/workflow relations), 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).',
+        '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).',
     },
   ),
   session: Type.Optional(
     Type.String({
       description:
-        'Session id or uuid fragment (e.g. e6c96). Required for family/outline/expand/detail/search/export. # 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/workflow. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
@@ -83,6 +83,11 @@ const SessionReadSchema = Type.Object({
   cwd: Type.Optional(
     Type.String({ description: 'find: filter by cwd. Optional.' }),
   ),
+  source: Type.Optional(
+    StringEnum(['main', 'subagent'], {
+      description: 'find action: filter by source. "main" = sessions/, "subagent" = subagents/. Default both (merged).',
+    }),
+  ),
   limit: Type.Optional(
     Type.Number({ description: 'find/search: max results. Default 20.' }),
   ),
@@ -99,6 +104,18 @@ const SessionReadSchema = Type.Object({
       description: 'extract action: filter commands/tool-results by tool name (e.g. "bash").',
     }),
   ),
+  runId: Type.Optional(
+    Type.String({
+      description:
+        'workflow action: focus a single run by runId (disambiguate multiple runs). Omit to see all run overviews.',
+    }),
+  ),
+  recursive: Type.Optional(
+    Type.Boolean({
+      description:
+        'family action: return nested execution tree (arbitrary-depth subagent↔workflow-call nesting, precise parentRecordId chain with flat-fallback for legacy records). Default false (flat family).',
+    }),
+  ),
 })
 
 // ---- guidelines（注入 LLM，design §3.4）----
@@ -109,12 +126,13 @@ const guidelines = [
   'outline before detail. Never read raw .jsonl files—use this tool.',
   '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.",
   '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. Eight actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~500 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). Progressive reading: outline → expand → detail. Do NOT use for the current session (use get_messages) 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. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~500 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 (use get_messages) or to edit sessions (pi has /resume /fork).`
 
 /**
  * 已注册过 TUI provider/command 的 pi 实例集合。