@zhushanwen/pi-session-reader 0.1.0 → 0.2.0

package/src/core/workflow.ts

@@ -0,0 +1,329 @@
+// ============================================================
+// workflow 概览解析与渲染（w5 新增，纯逻辑零 IO）
+// ============================================================
+//
+// 本文件消费 discovery/workflows.ts 的 readRunSnapshot（返 unknown 原始快照对象），
+// 把 unknown 类型化为 WorkflowOverview（NEW v='wf-run-v1' / OLD 无 v 双格式分支），
+// 再渲染为人类可读文本。零 IO：parseRunSnapshot/renderWorkflowOverview 喂 mock 即可单测
+//（w5 TC-wf-core-pure-logic，对齐 session-reader core/* 纯逻辑约定）。
+//
+// 不 import @zhushanwen/pi-subagent-workflow 的 RunSnapshot 类型——跨包类型耦合会使上游
+// 升版连带编译期影响本扩展；且上游类型只描述 NEW，OLD 仍需自处理（TC-wf-snapshot-version-union）。
+// session-reader 作为纯读取者，按字段存在性 + v 标记分支做「结构化快照」式解析，与上游解耦。
+
+// ---- 类型守卫 helpers ----
+
+/** unknown → Record<string, unknown> 守卫（非对象或 null → false）。 */
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null
+}
+
+/** 字符串截断（超 max 加省略号）。概览预览用，全文走 detail。 */
+function truncate(s: string, max: number): string {
+  return s.length <= max ? s : s.slice(0, max) + '…'
+}
+
+/** contentPreview 截断长度（概览预览，全文走 detail）。 */
+const CONTENT_PREVIEW_MAX = 120
+/** step 行 call sessionId 显示截断长度（uuid 前缀段，LLM 可读）。 */
+const SESSION_ID_PREVIEW_MAX = 12
+
+// ---- 数据模型（对齐 m2 slice DM-WorkflowBudget/DM-WorkflowStep/DM-WorkflowOverview）----
+
+/** wf-state budget 尽力提取（OLD budget 结构可能不全，缺字段 undefined）。 */
+export interface WorkflowBudget {
+  /** NEW state.budget.usedTokens / OLD budget.usedTokens */
+  usedTokens?: number
+  /** NEW state.budget.usedCost */
+  usedCost?: number
+  /** NEW state.budget.totalCallCount */
+  totalCallCount?: number
+  /** NEW state.budget.maxTokens */
+  maxTokens?: number
+  /** NEW state.budget.maxCost */
+  maxCost?: number
+  /** NEW state.budget.maxTimeMs */
+  maxTimeMs?: number
+}
+
+/** workflow 单步（NEW call / OLD callCache entry）。 */
+export interface WorkflowStep {
+  /** NEW call.id / OLD callCache 顺序索引 */
+  index: number
+  /** NEW call.status / OLD 推测（有 sessionFile 或 content → 'done'，否则 'pending'） */
+  status: 'pending' | 'running' | 'done'
+  /** NEW call.opts.description */
+  description?: string
+  /** NEW call.opts.model */
+  model?: string
+  /** NEW call.opts.thinkingLevel */
+  thinkingLevel?: string
+  /** NEW call.attempts / OLD 无 → undefined */
+  attempts?: number
+  /** NEW call.result.durationMs / OLD value.result.durationMs */
+  durationMs?: number
+  /** call.sessionId 或 result.sessionId（LLM 跳 outline/detail 的 id 入口） */
+  sessionId?: string
+  /** call.sessionFile 或 result.sessionFile（LLM 跳 outline/detail 的绝对路径入口，OLD 多数为 undefined） */
+  sessionFile?: string
+  /** result.content 截断前 120 字（概览预览，全文走 detail） */
+  contentPreview?: string
+}
+
+/** workflow run 概览（parseRunSnapshot 输出 / renderWorkflowOverview 输入）。 */
+export interface WorkflowOverview {
+  /** WorkflowRef.runId 透传（与 family.workflows 对齐，不读 snapshot.runId 避免 OLD 不一致） */
+  runId: string
+  /** WorkflowRef.stateFile 透传 */
+  stateFile: string
+  /** NEW state.status / OLD 顶层 status */
+  status: string
+  /** 格式标记（渲染/调试用） */
+  version: 'wf-run-v1' | 'legacy'
+  /** NEW spec.scriptName / spec.name / OLD name */
+  script?: string
+  /** NEW meta.startedAt / OLD startedAt（统一 string） */
+  startedAt?: string
+  /** NEW meta.completedAt */
+  completedAt?: string
+  /** NEW state.reason */
+  reason?: string
+  /** NEW state.error */
+  error?: string
+  budget: WorkflowBudget
+  steps: WorkflowStep[]
+}
+
+// ---- 解析 helpers（call/cache entry → WorkflowStep）----
+
+/** 把 budget 原始对象收窄为 WorkflowBudget（各字段类型校验，非 number → undefined）。 */
+function mapBudget(b: Record<string, unknown>): WorkflowBudget {
+  return {
+    usedTokens: typeof b.usedTokens === 'number' ? b.usedTokens : undefined,
+    usedCost: typeof b.usedCost === 'number' ? b.usedCost : undefined,
+    totalCallCount: typeof b.totalCallCount === 'number' ? b.totalCallCount : undefined,
+    maxTokens: typeof b.maxTokens === 'number' ? b.maxTokens : undefined,
+    maxCost: typeof b.maxCost === 'number' ? b.maxCost : undefined,
+    maxTimeMs: typeof b.maxTimeMs === 'number' ? b.maxTimeMs : undefined,
+  }
+}
+
+/** NEW state.calls[] 单项 → WorkflowStep。sessionFile/sessionId 顶层优先回退 result。 */
+function mapCallToStep(call: unknown, fallbackIndex: number): WorkflowStep {
+  if (!isRecord(call)) return { index: fallbackIndex, status: 'pending' }
+  const opts = isRecord(call.opts) ? call.opts : {}
+  const result = isRecord(call.result) ? call.result : {}
+
+  const index = typeof call.id === 'number' ? call.id : fallbackIndex
+  const rawStatus = typeof call.status === 'string' ? call.status : ''
+  const status: WorkflowStep['status'] =
+    rawStatus === 'done' || rawStatus === 'running' || rawStatus === 'pending'
+      ? rawStatus
+      : 'pending'
+
+  const sessionFile =
+    typeof call.sessionFile === 'string'
+      ? call.sessionFile
+      : typeof result.sessionFile === 'string'
+        ? result.sessionFile
+        : undefined
+  const sessionId =
+    typeof call.sessionId === 'string'
+      ? call.sessionId
+      : typeof result.sessionId === 'string'
+        ? result.sessionId
+        : undefined
+  const content = typeof result.content === 'string' ? result.content : undefined
+
+  return {
+    index,
+    status,
+    description: typeof opts.description === 'string' ? opts.description : undefined,
+    model: typeof opts.model === 'string' ? opts.model : undefined,
+    thinkingLevel: typeof opts.thinkingLevel === 'string' ? opts.thinkingLevel : undefined,
+    attempts: typeof call.attempts === 'number' ? call.attempts : undefined,
+    durationMs: typeof result.durationMs === 'number' ? result.durationMs : undefined,
+    sessionId,
+    sessionFile,
+    contentPreview: content !== undefined ? truncate(content, CONTENT_PREVIEW_MAX) : undefined,
+  }
+}
+
+/** OLD callCache[] 单项 {key, value} → WorkflowStep。status 推测，content 优先 result 回退 value。 */
+function mapCacheEntryToStep(entry: unknown, index: number): WorkflowStep {
+  if (!isRecord(entry)) return { index, status: 'pending' }
+  const value = isRecord(entry.value) ? entry.value : {}
+  const result = isRecord(value.result) ? value.result : {}
+
+  // sessionFile: value.sessionFile 或 value.result.sessionFile（OLD 多数缺失，探针 112 文件 0）
+  const sessionFile =
+    typeof value.sessionFile === 'string'
+      ? value.sessionFile
+      : typeof result.sessionFile === 'string'
+        ? result.sessionFile
+        : undefined
+  const sessionId =
+    typeof value.sessionId === 'string'
+      ? value.sessionId
+      : typeof result.sessionId === 'string'
+        ? result.sessionId
+        : undefined
+  // content：真实 OLD 数据 value.content（wf-skip-ok）与测试 fixture value.result.content 并存
+  const content =
+    typeof result.content === 'string'
+      ? result.content
+      : typeof value.content === 'string'
+        ? value.content
+        : undefined
+  // OLD 无 status 字段：有 sessionFile 或非空 content → done，否则 pending
+  //（空 content 如 wf-skip-ok 的 '' 不算完成标志，对齐 TC-w5-parse-old expected status='pending'；
+  // content 仍提取为 contentPreview=''）
+  const hasContent = content !== undefined && content.length > 0
+  const status: WorkflowStep['status'] =
+    sessionFile !== undefined || hasContent ? 'done' : 'pending'
+
+  return {
+    index,
+    status,
+    durationMs: typeof result.durationMs === 'number' ? result.durationMs : undefined,
+    sessionId,
+    sessionFile,
+    contentPreview: content !== undefined ? truncate(content, CONTENT_PREVIEW_MAX) : undefined,
+  }
+}
+
+// ---- parseRunSnapshot（unknown → WorkflowOverview | null）----
+
+/**
+ * 把 readRunSnapshot 返回的原始快照对象类型化为 WorkflowOverview（纯逻辑零 IO）。
+ *
+ * 分支（C-parserunsnapshot-dualformat，TC-wf-snapshot-version-union）：
+ * - 非对象 → null（调用方跳过，ES-wf-snapshot-unparseable）
+ * - NEW (snapshot.v === 'wf-run-v1')：state.* / meta.* / spec.*
+ * - OLD (无 v，有 callCache 数组或顶层 status)：顶层 status/budget/startedAt + callCache
+ * - 既非 NEW 也非 OLD → null（未来版本 wf-run-v2 / 异构内容）
+ *
+ * runId/stateFile 透传参数（不读 snapshot.runId，保证与 family.workflows 一致，避免 OLD 顶层
+ * runId 可信度低的不一致）。零 any（全程 typeof/Array.isArray/isRecord 守卫收窄）。
+ */
+export function parseRunSnapshot(
+  snapshot: unknown,
+  runId: string,
+  stateFile: string,
+): WorkflowOverview | null {
+  if (!isRecord(snapshot)) return null
+
+  // NEW 格式（v === 'wf-run-v1'）
+  if (snapshot.v === 'wf-run-v1') {
+    const state = isRecord(snapshot.state) ? snapshot.state : {}
+    const meta = isRecord(snapshot.meta) ? snapshot.meta : {}
+    const spec = isRecord(snapshot.spec) ? snapshot.spec : {}
+    const callsRaw = Array.isArray(state.calls) ? state.calls : []
+    return {
+      runId,
+      stateFile,
+      status: typeof state.status === 'string' ? state.status : '',
+      version: 'wf-run-v1',
+      script:
+        typeof spec.scriptName === 'string'
+          ? spec.scriptName
+          : typeof spec.name === 'string'
+            ? spec.name
+            : undefined,
+      startedAt: typeof meta.startedAt === 'string' ? meta.startedAt : undefined,
+      completedAt: typeof meta.completedAt === 'string' ? meta.completedAt : undefined,
+      reason: typeof state.reason === 'string' ? state.reason : undefined,
+      error: typeof state.error === 'string' ? state.error : undefined,
+      budget: mapBudget(isRecord(state.budget) ? state.budget : {}),
+      steps: callsRaw.map((c, i) => mapCallToStep(c, i)),
+    }
+  }
+
+  // OLD 格式（无 v，有 callCache 数组或顶层 status 字符串）
+  if (Array.isArray(snapshot.callCache) || typeof snapshot.status === 'string') {
+    const callCacheRaw = Array.isArray(snapshot.callCache) ? snapshot.callCache : []
+    return {
+      runId,
+      stateFile,
+      status: typeof snapshot.status === 'string' ? snapshot.status : '',
+      version: 'legacy',
+      script: typeof snapshot.name === 'string' ? snapshot.name : undefined,
+      startedAt: typeof snapshot.startedAt === 'string' ? snapshot.startedAt : undefined,
+      budget: mapBudget(isRecord(snapshot.budget) ? snapshot.budget : {}),
+      steps: callCacheRaw.map((c, i) => mapCacheEntryToStep(c, i)),
+    }
+  }
+
+  return null
+}
+
+// ---- renderWorkflowOverview（WorkflowOverview → 人类可读文本）----
+
+/**
+ * 渲染 WorkflowOverview 为人类可读文本（纯逻辑零 IO）。
+ *
+ * 输出结构（IF-renderWorkflowOverview）：
+ * - 头行：`run: <runId> [status] (script?) started=<ISO> completed?=<ISO> reason?`
+ * - budget 行：`budget: used=<tokens>tok $<cost> calls=<n> / max=<tokens>tok $<cost> <timeMs>ms`
+ *   （缺省字段省略，不输出 undefined 字面量）
+ * - steps 块每行：`  #<index> [status] <description> · model=<model> · <durationMs>ms ·
+ *   attempts=<n> · call=<sessionId截断> <sessionFile>`
+ *   sessionFile 缺则标 `（无 sessionFile，OLD 格式未持久化）`（TC-wf-step-sessionfile-link）
+ * - error 行（如有 state.error）
+ *
+ * 每个 step 的 call sessionId/sessionFile 是 LLM 跳 outline/detail 的入口（m0 resolveSessionId
+ * 三形态：sessionId/绝对路径/sa-id 均可深读）。多 run 场景由 doWorkflow 循环拼接多段（w6）。
+ */
+export function renderWorkflowOverview(overview: WorkflowOverview): string {
+  const lines: string[] = []
+
+  // 头行
+  const headParts = [`run: ${overview.runId}`, `[${overview.status}]`]
+  if (overview.script) headParts.push(`(${overview.script})`)
+  if (overview.startedAt) headParts.push(`started=${overview.startedAt}`)
+  if (overview.completedAt) headParts.push(`completed=${overview.completedAt}`)
+  if (overview.reason) headParts.push(`reason=${overview.reason}`)
+  lines.push(headParts.join(' '))
+
+  // budget 行（缺字段省略）
+  const budgetParts: string[] = ['budget:']
+  if (overview.budget.usedTokens !== undefined) budgetParts.push(`used=${overview.budget.usedTokens}tok`)
+  if (overview.budget.usedCost !== undefined) budgetParts.push(`$${overview.budget.usedCost}`)
+  if (overview.budget.totalCallCount !== undefined) budgetParts.push(`calls=${overview.budget.totalCallCount}`)
+  const hasMax =
+    overview.budget.maxTokens !== undefined ||
+    overview.budget.maxCost !== undefined ||
+    overview.budget.maxTimeMs !== undefined
+  if (hasMax) {
+    const maxParts: string[] = ['/ max=']
+    if (overview.budget.maxTokens !== undefined) maxParts.push(`${overview.budget.maxTokens}tok`)
+    if (overview.budget.maxCost !== undefined) maxParts.push(`$${overview.budget.maxCost}`)
+    if (overview.budget.maxTimeMs !== undefined) maxParts.push(`${overview.budget.maxTimeMs}ms`)
+    budgetParts.push(maxParts.join(''))
+  }
+  lines.push(budgetParts.join(' '))
+
+  // steps 块
+  for (const step of overview.steps) {
+    const stepParts = [`  #${step.index}`, `[${step.status}]`]
+    if (step.description) stepParts.push(step.description)
+    const tail: string[] = []
+    if (step.model) tail.push(`model=${step.model}`)
+    if (step.durationMs !== undefined) tail.push(`${step.durationMs}ms`)
+    if (step.attempts !== undefined) tail.push(`attempts=${step.attempts}`)
+    if (step.sessionId) tail.push(`call=${truncate(step.sessionId, SESSION_ID_PREVIEW_MAX)}`)
+    let line = stepParts.join(' ')
+    if (tail.length > 0) line += ' · ' + tail.join(' · ')
+    if (step.sessionFile) {
+      line += ' ' + step.sessionFile
+    } else {
+      line += ' （无 sessionFile，OLD 格式未持久化）'
+    }
+    lines.push(line)
+  }
+
+  // error 行
+  if (overview.error) lines.push(`error: ${overview.error}`)
+
+  return lines.join('\n')
+}

package/src/discovery/find.ts

@@ -1,8 +1,10 @@
 import { createReadStream, type ReadStream } from 'node:fs'
 import { open, type FileHandle } from 'node:fs/promises'
 import { createInterface } from 'node:readline'
+import { basename } from 'node:path'
 import type { SessionRef } from '../core/family.js'
-import { listMainSessions, type SessionFileMeta } from './roots.js'
+import { listMainSessions, listSubagentSessions, type SessionFileMeta } from './roots.js'
+import { listRecordManifests, extractSessionIdFromFilename, type RecordManifest } from './subagents.js'
 
 /**
  * M2 discovery 发现层：按 query 定位 session（design §3.3 D-3 + §3.4 find action）。
@@ -19,7 +21,12 @@ import { listMainSessions, type SessionFileMeta } from './roots.js'
  * agentDir 注入：同 roots.ts，零 pi 依赖（仅 node:fs + 相对 import M1 core）。
  */
 
+/** 候选来源标记（DM1 必填）：main = agentDir/sessions/、subagent = agentDir/subagents/。 */
+export type SessionSource = 'main' | 'subagent'
+
 export interface MatchedSession extends SessionRef {
+  /** 候选来源（DM1 必填标记）：main 或 subagent，按文件所在目录标记 */
+  source: SessionSource
   /** 首条 user message text 截 80 字符（从全文读，不只首行） */
   firstMessagePreview?: string
 }
@@ -153,6 +160,8 @@ function looksLikeUuidFragment(query: string): boolean {
 interface Candidate {
   meta: SessionFileMeta
   ref: SessionRef
+  /** 候选来源（透传到 MatchedSession.source，DM1） */
+  source: SessionSource
 }
 
 interface Matched extends Candidate {
@@ -160,6 +169,115 @@ interface Matched extends Candidate {
   preview?: string
 }
 
+// ============================================================
+// U5：subagent task/slug/agentName 匹配（manifest 索引 + P-fallback identity 回退）
+// ============================================================
+
+/** P-fallback 尾行 identity 读取窗口（同 subagents.ts，task 文本可达数 KB）。 */
+const TAIL_READ_BYTES = 65536
+
+/**
+ * 读 subagent 文件尾部（最后 64KB）找 subagent-identity entry，返回 task/slug/agent。
+ *
+ * find 的 P-fallback 路径（场景 A：subagent 无 manifest，本机 11.5%）：manifest 索引未命中时
+ * 读尾行 identity 取 task/slug/agent 做 query 子串匹配。与 subagents.ts 的 readTailIdentity
+ * 同源（64KB 窗口 + lastIndexOf 定位），但是 find 专用最小版（只取 task/slug/agent，不要
+ * rootSessionId——find 候选已有 header.id）。不导出，不碰 subagents.ts（w3 冻结）。
+ */
+async function readTailIdentityForMatch(
+  path: string,
+  size: number,
+): Promise<{ task?: string; slug?: string; agent?: 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
+    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) return undefined
+    return {
+      task: typeof data.task === 'string' ? data.task : undefined,
+      slug: typeof data.slug === 'string' ? data.slug : undefined,
+      agent: typeof data.agent === 'string' ? data.agent : undefined,
+    }
+  } catch {
+    return undefined
+  } finally {
+    await fh?.close().catch(() => {})
+  }
+}
+
+/**
+ * 建 sessionId→RecordManifest 索引（U5：subagent task/slug/agentName 匹配用）。
+ *
+ * listRecordManifests 一次性读全部 manifest（json 小，几百字节），用 extractSessionIdFromFilename
+ * 从 manifest.sessionFile 文件名提取 sessionId 作 key（与候选 header.id 同源真实 id）。无 subagent
+ * 候选时跳过（避免无谓 IO——TC-find-manifest-index 的 O(1) 查表前提）。
+ */
+async function buildManifestIndex(
+  agentDir: string,
+  hasSubagentCandidates: boolean,
+): Promise<Map<string, RecordManifest>> {
+  if (!hasSubagentCandidates) return new Map()
+  const manifests = await listRecordManifests(agentDir)
+  const index = new Map<string, RecordManifest>()
+  for (const m of manifests) {
+    const sid = extractSessionIdFromFilename(basename(m.sessionFile))
+    if (sid) index.set(sid, m)
+  }
+  return index
+}
+
+/**
+ * subagent 候选元数据匹配（U5）：manifest 命中走 task/slug/agentName 子串；索引未命中（P-fallback，
+ * 场景 A）读尾行 identity 回退匹配 task/slug/agent。
+ *
+ * manifest 命中但不匹配时不再回退 identity——manifest 是权威主表，task/slug/agentName 即其提供，
+ * identity 同源数据回退无新信息（探针 manifest 20/20 全有 task/slug）。manifest 缺某字段（旧 manifest）
+ * 时该字段 undefined，includes 自然 false，不影响其他字段。
+ */
+async function matchSubagentMetadata(
+  candidate: Candidate,
+  query: string,
+  manifestIndex: Map<string, RecordManifest>,
+): Promise<boolean> {
+  const manifest = manifestIndex.get(candidate.ref.sessionId)
+  if (manifest) {
+    return (
+      (manifest.task?.includes(query) ?? false) ||
+      (manifest.slug?.includes(query) ?? false) ||
+      (manifest.agentName?.includes(query) ?? false)
+    )
+  }
+  // P-fallback：manifest 索引未命中 → 读尾行 identity 回退
+  const ident = await readTailIdentityForMatch(candidate.meta.path, candidate.meta.size)
+  if (!ident) return false
+  return (
+    (ident.task?.includes(query) ?? false) ||
+    (ident.slug?.includes(query) ?? false) ||
+    (ident.agent?.includes(query) ?? false)
+  )
+}
+
 /**
  * 按 query 找 session（接口冻结，design §3.4 find action）。
  *
@@ -170,29 +288,46 @@ interface Matched extends Candidate {
 export async function findSessions(
   query: string,
   agentDir: string,
-  opts?: { cwd?: string; limit?: number },
+  opts?: { cwd?: string; limit?: number; source?: SessionSource },
 ): Promise<{ matches: MatchedSession[]; truncated: boolean }> {
   const limit = opts?.limit ?? DEFAULT_LIMIT
   const cwdFilter = opts?.cwd
-  const files = await listMainSessions(agentDir)
+  const sourceFilter = opts?.source
+
+  // 0. 按来源收集文件列表（source 过滤在文件列表层：source==='main' 只扫 sessions/、
+  //    'subagent' 只扫 subagents/、undefined 两者合并——决策二性能意图：不扫被过滤目录）。
+  //    两路目录扫描相互独立 → Promise.allSettled（AGENTS.md：独立请求用 allSettled），
+  //    任一目录不存在（roots.ts 静默返回空数组）不影响另一路。
+  const sources: SessionSource[] =
+    sourceFilter === undefined ? ['main', 'subagent'] : [sourceFilter]
+  const listResults = await Promise.allSettled(
+    sources.map(async (src) => ({
+      src,
+      files: await (src === 'main' ? listMainSessions(agentDir) : listSubagentSessions(agentDir)),
+    })),
+  )
 
-  // 1. 首行扫描所有文件拿 header，建候选 SessionRef（cwd 过滤在此应用）
+  // 1. 首行扫描建候选 SessionRef（cwd 过滤在此应用；按来源打 source 标记）
   const candidates: Candidate[] = []
-  for (const meta of files) {
-    const headerLine = await readFirstLine(meta.path)
-    const header = parseHeader(headerLine)
-    if (!header) continue // 非 session 文件/坏 header → 跳过
-    if (cwdFilter !== undefined && (header.cwd ?? '') !== cwdFilter) continue
-    const ref: SessionRef = {
-      sessionId: header.id,
-      // 完整绝对路径（与 parentSession 同构，便于 family 按 includes(sid) 反查）
-      fileName: meta.path,
-      mtime: meta.mtime,
-      sizeBytes: meta.size,
-      cwd: header.cwd ?? '',
+  for (const r of listResults) {
+    if (r.status !== 'fulfilled') continue
+    const { src, files } = r.value
+    for (const meta of files) {
+      const headerLine = await readFirstLine(meta.path)
+      const header = parseHeader(headerLine)
+      if (!header) continue // 非 session 文件/坏 header → 跳过
+      if (cwdFilter !== undefined && (header.cwd ?? '') !== cwdFilter) continue
+      const ref: SessionRef = {
+        sessionId: header.id,
+        // 完整绝对路径（与 parentSession 同构，便于 family 按 includes(sid) 反查）
+        fileName: meta.path,
+        mtime: meta.mtime,
+        sizeBytes: meta.size,
+        cwd: header.cwd ?? '',
+      }
+      if (header.parentSession) ref.parentSession = header.parentSession
+      candidates.push({ meta, ref, source: src })
     }
-    if (header.parentSession) ref.parentSession = header.parentSession
-    candidates.push({ meta, ref })
   }
 
   // 2. 匹配
@@ -211,9 +346,21 @@ export async function findSessions(
       // query 像 uuid 片段但无匹配 → uuid 写错的可能性高，不对全部候选深读首消息
       matched = []
     } else {
-      // 名称关键词 fallback：读所有候选首消息，预览含 query 入选
+      // 关键词层（U5 扩展）：subagent manifest 元数据 task/slug/agentName（+ P-fallback identity
+      // 回退）与 main/subagent 首消息预览并列匹配，命中任一即入选（TC-find-match-priority）。
+      // - subagent 候选：先查 manifest 索引（命中走元数据子串，未命中 P-fallback 读尾行 identity）；
+      //   元数据命中即入选（preview 留空，第 5 步补读首消息），未命中仍可走首消息 fallback
+      // - main / subagent 元数据未命中：首消息预览 query 子串匹配（m0 现状路径不变）
+      const manifestIndex = await buildManifestIndex(
+        agentDir,
+        candidates.some((c) => c.source === 'subagent'),
+      )
       const keywordHits: Matched[] = []
       for (const c of candidates) {
+        if (c.source === 'subagent' && (await matchSubagentMetadata(c, query, manifestIndex))) {
+          keywordHits.push({ ...c })
+          continue
+        }
         const text = await readFirstUserMessageText(c.meta.path)
         if (text && text.includes(query)) {
           keywordHits.push({ ...c, preview: text.slice(0, PREVIEW_MAX) })
@@ -233,7 +380,7 @@ export async function findSessions(
   // 5. 填 firstMessagePreview（recent/uuid 路径未读，这里对最终 limit 个补读——最多 limit 个 IO）
   const result: MatchedSession[] = []
   for (const m of sliced) {
-    const out: MatchedSession = { ...m.ref }
+    const out: MatchedSession = { ...m.ref, source: m.source }
     if (m.preview !== undefined) {
       out.firstMessagePreview = m.preview
     } else {