@zhushanwen/pi-session-reader 0.1.0

package/src/discovery/roots.ts

@@ -0,0 +1,92 @@
+import { readdir, stat } from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * M2 discovery 发现层：文件系统扫描（design §3.3 D-5 首行扫描策略的文件定位部分）。
+ *
+ * agentDir 注入：本模块所有函数接收 `agentDir: string` 参数，**不调用** `getAgentDir()`
+ *（pi SDK，调用留到 M3 tool-adapter 层）。故本模块零 pi 依赖，仅 node:fs + 相对
+ * import M1 core，可完全单测。
+ */
+
+export interface SessionFileMeta {
+  /** 绝对路径 */
+  path: string
+  mtime: number
+  size: number
+}
+
+/**
+ * main sessions 扫描时整体跳过的子目录名。
+ * `workflow-state` 目录存放 workflow 运行状态文件（wf-*.jsonl，首行 `{"v":"wf-run-v1"...}`），
+ * 非 session 文件——属 family 腿独立处理（design §3.3 D-7），扫描 main sessions 时排除，
+ * 否则会把 wf 文件误收为 session（且 find.ts 读其首行 header 时会因 type≠session 被丢弃，
+ * 在此排除可避免这批无效首行扫描）。
+ */
+const SKIP_DIRS_MAIN = new Set(['workflow-state'])
+
+/**
+ * 文件名是否为待收的 session .jsonl。
+ * `.jsonl.finalized` 不以 `.jsonl` 结尾，故 `endsWith('.jsonl')` 天然排除之
+ *（design §3.3 D-7 Q2：finalized 是已完成态快照副本，与 .jsonl 同 base name 并存，不收）。
+ */
+function isSessionJsonl(name: string): boolean {
+  return name.endsWith('.jsonl')
+}
+
+/**
+ * 递归扫描 rootDir 下所有 .jsonl 文件（排除 .finalized），返回绝对路径 + mtime + size。
+ * `skipDirs` 命名的目录整体跳过。目录不存在/无权限 → 返回空数组，不抛错（design §2 坏路径容错）。
+ */
+async function scanJsonlRecursive(
+  rootDir: string,
+  skipDirs: Set<string>,
+): Promise<SessionFileMeta[]> {
+  const results: SessionFileMeta[] = []
+
+  async function walk(currentDir: string): Promise<void> {
+    let entries: Dirent[]
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true })
+    } catch {
+      return // 目录不存在/无权限 → 静默返回（容错，listXxxSessions 契约要求不抛错）
+    }
+    for (const entry of entries) {
+      const full = join(currentDir, entry.name)
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue
+        await walk(full)
+      } else if (entry.isFile() && isSessionJsonl(entry.name)) {
+        try {
+          const s = await stat(full)
+          results.push({ path: full, mtime: s.mtimeMs, size: s.size })
+        } catch {
+          // 文件并发删除等致 stat 失败 → 跳过（不中断整体扫描）
+        }
+      }
+    }
+  }
+
+  await walk(rootDir)
+  return results
+}
+
+/**
+ * 列出 agentDir/sessions/ 下所有主 session 文件。
+ * 递归扫描子目录（cwd 编码目录如 --Users-foo--），glob *.jsonl，排除 *.jsonl.finalized
+ *（design §3.3 D-7 Q2）；跳过 workflow-state 子目录（workflow 运行状态文件，非 session）。
+ */
+export async function listMainSessions(agentDir: string): Promise<SessionFileMeta[]> {
+  return scanJsonlRecursive(join(agentDir, 'sessions'), SKIP_DIRS_MAIN)
+}
+
+/**
+ * 列出 agentDir/subagents/ 下所有 subagent session 文件（同样排除 .finalized）。
+ * 结构：subagents/<cwd编码>/sessions/*.jsonl。records/ 子目录（.json manifest）无 .jsonl，
+ * 天然不被误收。
+ */
+export async function listSubagentSessions(agentDir: string): Promise<SessionFileMeta[]> {
+  return scanJsonlRecursive(join(agentDir, 'subagents'), new Set())
+}
+

package/src/discovery/subagents.ts

@@ -0,0 +1,470 @@
+import { readFile, readdir, open } 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 { buildFamilyIndex, resolveFamily } from '../core/family.js'
+import { listMainSessions, listSubagentSessions } from './roots.js'
+
+/**
+ * [M2 discovery] 从文件系统构建某 session 的完整家族（IO 适配层）。
+ *
+ * 组合 M1 family 纯逻辑（buildFamilyIndex/resolveFamily）+ 真实文件读取。零 pi 依赖
+ *（node:fs + 相对 import M1 core + M2 roots），同 roots/find，可完全单测。
+ *
+ * 关键衔接点（探查确认，详见各步骤注释）：
+ * - identity 在 subagent 文件 **尾行**（非首行；design §3.3 D-7 "尾部"，实测 019fe635
+ *   的 identity 在 71/71 行）。故 header 读首行、identity 读尾行，两次定长读。
+ * - identity id 修正：M1 用 identity entry.id（=data.id 的 sa-xxx 占位）作 SubagentRef.sessionId。
+ *   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 是孤儿/
+ *   cleanedUp 的来源（design §3.3 D-7 "records/*.json manifest 作孤儿补充"）。
+ * - workflows：M1 resolveFamily 恒返回 []。M2 在此单独读目标 session 的 workflow-state-link
+ *   custom entry → link.data.path（wf-state 文件绝对路径）→ 读该文件最后一行（最新快照）取 calls。
+ *
+ * @throws sessionId 不在任意 main session header → Error（M3 tool-adapter 层转 F1 恢复指引）
+ */
+export async function buildFamilyFromFs(sessionId: string, agentDir: string): Promise<Family> {
+  // ---- 1. main sessions：首行 header → byId/childrenOf 素材 + fileStats + 路径反查 ----
+  const mainMetas = await listMainSessions(agentDir)
+  const headers: Entry[] = []
+  const fileStats = new Map<string, { mtime: number; size: number }>()
+  /** sessionId → 真实文件路径，供 workflows 找目标文件 + enrich 补 fileName */
+  const sessionIdToPath = new Map<string, string>()
+  /** path → 完整 SessionRef（含真实 cwd/fileName/mtime/size），供 enrich + workflow calls 反查 */
+  const pathToRef = new Map<string, SessionRef>()
+
+  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)
+    const ref: SessionRef = {
+      sessionId: h.id,
+      fileName: meta.path,
+      mtime: meta.mtime,
+      sizeBytes: meta.size,
+      cwd: h.cwd ?? '',
+    }
+    if (h.parentSession) ref.parentSession = h.parentSession
+    pathToRef.set(meta.path, ref)
+  }
+
+  // ---- 2. subagent sessions：首行 header（真实 id）+ 尾行 identity → 修正 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 修正，跳过
+    const realId = h.id
+    // 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 原样保留。
+    identities.push({
+      type: 'custom',
+      id: realId,
+      parentId: null,
+      customType: 'subagent-identity',
+      data: { rootSessionId: ident.rootSessionId, slug: ident.slug },
+    })
+    fileStats.set(realId, { mtime: meta.mtime, size: meta.size })
+    sessionIdToPath.set(realId, meta.path)
+    pathToRef.set(meta.path, {
+      sessionId: realId,
+      fileName: meta.path,
+      mtime: meta.mtime,
+      sizeBytes: meta.size,
+      cwd: h.cwd ?? '',
+    })
+  }
+
+  // ---- 3. records manifest → 孤儿（cleanedUp）----
+  // 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)
+  for (const m of manifests) {
+    if (aliveSubPaths.has(m.sessionFile)) continue
+    identities.push({
+      type: 'custom',
+      id: m.id,
+      parentId: null,
+      customType: 'subagent-identity',
+      // 孤儿的真实 slug 随文件 GC 丢失，用 manifest.agentName 兜底（agent 类型名，非 task 标签）
+      data: { rootSessionId: m.rootSessionId, slug: m.agentName ?? '' },
+    })
+  }
+
+  // ---- 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, sessionIdToPath, pathToRef)
+  family.workflows = await resolveWorkflows(sessionId, sessionIdToPath, pathToRef)
+
+  return family
+}
+
+// ============================================================
+// 文件读取 helpers（定长 buffer，避免全文读：subagent 文件均 269KB、总量 ~923MB）
+// ============================================================
+
+/** 首行读取 buffer 上限。session header（id/cwd/parentSession）实测 < 300 字节，8KB 足够。 */
+const HEADER_READ_BYTES = 8192
+/** 尾行 identity 读取 buffer 上限。identity 含完整 task 文本可达数 KB；实测 64KB 覆盖 3203/3430。 */
+const TAIL_READ_BYTES = 65536
+
+/** 读文件首行（header）。定长 8KB 一次 read；空文件/读失败返回 undefined。 */
+async function readFirstLine(path: string): Promise<string | undefined> {
+  let fh: FileHandle | undefined
+  try {
+    fh = await open(path, 'r')
+    const buf = Buffer.alloc(HEADER_READ_BYTES)
+    const { bytesRead } = await fh.read(buf, 0, HEADER_READ_BYTES, 0)
+    if (bytesRead === 0) return undefined
+    const text = buf.subarray(0, bytesRead).toString('utf8')
+    const nl = text.indexOf('\n')
+    return nl === -1 ? text : text.slice(0, nl)
+  } catch {
+    return undefined
+  } finally {
+    await fh?.close().catch(() => {})
+  }
+}
+
+interface SessionHeader {
+  id: string
+  cwd?: string
+  parentSession?: string
+}
+
+/** 解析 header 首行为 SessionHeader。非 session 行/缺 id → null。 */
+function parseHeaderLine(line: string | undefined): SessionHeader | null {
+  if (!line) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return null
+  }
+  if (typeof raw !== 'object' || raw === null) return null
+  const o = raw as Record<string, unknown>
+  if (o.type !== 'session' || typeof o.id !== 'string') return null
+  const h: SessionHeader = { id: o.id }
+  if (typeof o.cwd === 'string') h.cwd = o.cwd
+  if (typeof o.parentSession === 'string') h.parentSession = o.parentSession
+  return h
+}
+
+/**
+ * 读 subagent 文件尾部（最后 64KB）找 subagent-identity entry，返回 rootSessionId + slug。
+ *
+ * identity 在文件尾行（探查确认；design §3.3 D-7 "尾部"）。用 lastIndexOf 定位最后一个
+ * subagent-identity 标记（多次重写时取最新），提取该行边界内的 JSON 解析。identity 行
+ * 超 64KB（极罕见，实测 1/3430）会截断 → 解析失败 → 返回 undefined（该 subagent 不收）。
+ */
+async function readTailIdentity(
+  path: string,
+  size: number,
+): Promise<{ rootSessionId: string; slug: string } | undefined> {
+  if (size === 0) return undefined
+  let fh: FileHandle | undefined
+  try {
+    fh = await open(path, 'r')
+    const len = Math.min(TAIL_READ_BYTES, size)
+    const buf = Buffer.alloc(len)
+    await fh.read(buf, 0, len, Math.max(0, size - 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
+    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 : '',
+    }
+  } catch {
+    return undefined
+  } finally {
+    await fh?.close().catch(() => {})
+  }
+}
+
+// ============================================================
+// records manifest（孤儿 / cleanedUp 来源）
+// ============================================================
+
+interface RecordManifest {
+  id: string
+  rootSessionId: string
+  agentName?: string
+  /** subagent session.jsonl 绝对路径（创建时写入；文件 GC 后路径仍残留） */
+  sessionFile: string
+}
+
+function isRecordManifest(v: unknown): v is RecordManifest {
+  if (typeof v !== 'object' || v === null) return false
+  const o = v as Record<string, unknown>
+  return (
+    typeof o.id === 'string' &&
+    typeof o.rootSessionId === 'string' &&
+    typeof o.sessionFile === 'string'
+  )
+}
+
+/**
+ * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
+ * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
+ * /JSON 损坏）跳过，不中断扫描。
+ */
+/** 读单个 manifest 文件并校验；坏 manifest（JSON 损坏/缺必填字段）返回 undefined。 */
+async function tryReadManifest(path: string): Promise<RecordManifest | undefined> {
+  try {
+    const raw: unknown = JSON.parse(await readFile(path, 'utf8'))
+    return isRecordManifest(raw) ? raw : undefined
+  } catch {
+    return undefined // 坏 manifest 跳过，不中断整体扫描
+  }
+}
+
+async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
+  const root = join(agentDir, 'subagents')
+  const out: RecordManifest[] = []
+  async function walk(dir: string): Promise<void> {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return // 目录不存在/无权限 → 静默返回
+    }
+    for (const e of entries) {
+      const full = join(dir, e.name)
+      if (e.isDirectory()) {
+        await walk(full)
+      } else if (e.isFile() && e.name.endsWith('.json') && basename(dir) === 'records') {
+        const m = await tryReadManifest(full)
+        if (m) out.push(m)
+      }
+    }
+  }
+  await walk(root)
+  return out
+}
+
+// ============================================================
+// workflow-state 链路（M1 family.workflows 的填充）
+// ============================================================
+
+/**
+ * 从 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 []
+}
+
+/** 从文件名（<timestamp>_<sessionId>.jsonl）提取 sessionId；非 uuid 特征返回空串。 */
+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）
+// ============================================================
+
+/**
+ * M1 buildFamilyIndex 设 SessionRef.fileName=''（header 推不出路径）、subagent cwd=''
+ *（identity 无 cwd）。此处用已扫描的真实文件信息补全：alive 的 ref 补 fileName + cwd；
+ * cleanedUp 孤儿（无文件）保持占位。
+ */
+function enrichRefs(
+  family: Family,
+  sessionIdToPath: Map<string, string>,
+  pathToRef: Map<string, SessionRef>,
+): void {
+  // sessionId → 完整 ref（含真实 fileName/cwd），由 pathToRef 反建
+  const bySid = new Map<string, SessionRef>()
+  for (const ref of pathToRef.values()) bySid.set(ref.sessionId, ref)
+
+  const enrichSessionRef = (ref: SessionRef): SessionRef => {
+    const full = bySid.get(ref.sessionId)
+    if (!full) return ref
+    return {
+      ...ref,
+      fileName: full.fileName || ref.fileName,
+      cwd: full.cwd || ref.cwd,
+    }
+  }
+
+  family.root = enrichSessionRef(family.root)
+  family.parents = family.parents.map(enrichSessionRef)
+  family.forks = family.forks.map(enrichSessionRef)
+  family.subagents = family.subagents.map((s) => {
+    const full = bySid.get(s.sessionId)
+    if (!full) return s
+    return {
+      ...s,
+      fileName: full.fileName || s.fileName,
+      cwd: full.cwd || s.cwd,
+    } as SubagentRef
+  })
+  // sessionIdToPath 仅用于类型完整性占位引用，避免未用警告（实际路径信息已在 pathToRef）
+  void sessionIdToPath
+}