@zhushanwen/pi-session-reader 0.6.1 → 0.8.0

package/src/__tests__/zcode-whitelist.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  assertZcodeDbPathAllowed,
+  zcodeDbAllowlistFor,
+} from '../discovery/whitelist.js'
+
+// ============================================================
+// P-whitelist（design session-reader-shared-core §3.3 D5 / §3.4 检查顺序 / 附录 A）：
+// 派生白名单在 taiji dataDir 布局下精确命中隔离库。
+//
+// 布局（mkdtemp 自建自删）：root/agent = agentDir（dirname = dataDir root），
+// root/engines/zcode/session-db/db.sqlite = 隔离库。测试内手拼路径段是**测试对
+// 派生正确性的唯一验证手段**（生产 src 禁手拼，段单源 = SDK ZCODE_ISOLATED_DB_
+// SEGMENTS 经 zcode-session-source zcodeImportDbAllowlist 引用）。
+//
+// 检查顺序铁律断言：存在性（不存在 → unreadable）先于路径（集合外 → forbidden）——
+// 集合外且不存在的路径必须报 unreadable 而非 forbidden（场景 5 ④ 顺序断言的单元锚）。
+// ============================================================
+
+const ISOLATED_DB_SEGMENTS = ['engines', 'zcode', 'session-db', 'db.sqlite']
+
+let root: string
+let agentDir: string
+let isolatedDbPath: string
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'zcode-whitelist-test-'))
+  agentDir = join(root, 'agent')
+  mkdirSync(agentDir, { recursive: true })
+  isolatedDbPath = join(root, ...ISOLATED_DB_SEGMENTS)
+})
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+})
+
+describe('zcodeDbAllowlistFor：tmp dataDir 布局精确命中隔离库（P-whitelist）', () => {
+  it('第一项 = zcodeIsolatedDbPath(dirname(agentDir))，集合共两项（隔离库 + 宿主库）', () => {
+    const allow = zcodeDbAllowlistFor(agentDir)
+    expect(allow).toHaveLength(2)
+    // 精确命中：手拼段与派生结果逐字节相等（同源常量 + 同一 join 派生式的行为锚）
+    expect(allow[0]).toBe(isolatedDbPath)
+  })
+
+  it('realpath 对齐：agentDir 经 symlink 到达（macOS /var → /private/var 形态）仍命中', () => {
+    // tmpdir 本身在 macOS 即 symlink 链（/var → /private/var）：mkdtemp 产物 realpath
+    // 后 ≠ 字面串。允许集合与 dbPath 同经 realpath 归一（whitelist.ts realOf），
+    // 两侧一致归一后比对 = 命中。isolatedDbPath 真实存在才有 realpath 归一输入。
+    mkdirSync(join(root, ...ISOLATED_DB_SEGMENTS.slice(0, -1)), { recursive: true })
+    writeFileSync(isolatedDbPath, '', 'utf8')
+    expect(() => assertZcodeDbPathAllowed(isolatedDbPath, agentDir)).not.toThrow()
+  })
+
+  it('纯 pi 宿主边界（D5）：agentDir 无对应 dataDir 布局时集合外路径照常拒绝', () => {
+    const outside = join(root, 'somewhere-else', 'db.sqlite')
+    mkdirSync(join(root, 'somewhere-else'), { recursive: true })
+    writeFileSync(outside, '', 'utf8')
+    expect(() => assertZcodeDbPathAllowed(outside, agentDir)).toThrow('zcode_db_path_forbidden')
+  })
+})
+
+describe('assertZcodeDbPathAllowed：检查顺序三段递进（存在性先于路径）', () => {
+  it('第 1 段存在性：白名单内路径但文件不存在 → zcode_db_unreadable（不误报 forbidden）', () => {
+    expect(() => assertZcodeDbPathAllowed(isolatedDbPath, agentDir)).toThrow(
+      'zcode_db_unreadable',
+    )
+  })
+
+  it('第 1 段先于第 2 段：集合外且文件不存在的路径 → 仍是 unreadable（不是 forbidden）', () => {
+    const outsideMissing = join(root, 'nowhere', 'evil.sqlite')
+    expect(() => assertZcodeDbPathAllowed(outsideMissing, agentDir)).toThrow(
+      'zcode_db_unreadable',
+    )
+  })
+
+  it('第 2 段路径：存在但集合外 → zcode_db_path_forbidden（安全面错误语义更重）', () => {
+    const outside = join(root, 'evil.sqlite')
+    writeFileSync(outside, '', 'utf8')
+    try {
+      assertZcodeDbPathAllowed(outside, agentDir)
+      expect.unreachable('should have thrown')
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('zcode_db_path_forbidden')
+      expect(msg).toContain(outside)
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('通过闸（集合内且存在）→ 不抛错（开库由调用方进行）', () => {
+    mkdirSync(join(root, ...ISOLATED_DB_SEGMENTS.slice(0, -1)), { recursive: true })
+    writeFileSync(isolatedDbPath, '', 'utf8')
+    expect(() => assertZcodeDbPathAllowed(isolatedDbPath, agentDir)).not.toThrow()
+  })
+
+  it('unreadable 指引含动态推导的隔离库路径与 -wal 告诫（§3.4 文案）', () => {
+    try {
+      assertZcodeDbPathAllowed(isolatedDbPath, agentDir)
+      expect.unreachable('should have thrown')
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain(isolatedDbPath)
+      expect(msg).toContain('-wal')
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('宿主库第二项 = join(homedir(), SDK 宿主段)（存量兼容锚点，不在本梯队触碰）', () => {
+    const allow = zcodeDbAllowlistFor(agentDir)
+    // 第二项是 homedir 派生的宿主库（真实 HOME 下的 .zcode/cli/db/db.sqlite 形态）——
+    // 测试不触碰真实文件，只断言其位于集合且 ≠ 隔离库项
+    expect(allow[1]).not.toBe(allow[0])
+    expect(allow[1].startsWith(homedir())).toBe(true)
+  })
+})

package/src/core/execution-tree.ts

@@ -437,7 +437,9 @@ export async function buildExecutionTree(
       sessionId: rootSessionId,
       // MF-1：main root 携带 sessionFile（调用方传入），否则 attachWorkflowChildren 对无
       // sessionFile 节点直接 return，main 自身发起的 workflow run 永远进不了执行树。
-      sessionFile: mainSessionFile,
+      // falsy 归一为 undefined：调用方的「路径不可得」哨兵是空串（zcode family 路由
+      // 反查未命中），root 节点 details 不携带 sessionFile:"" 这类非路径占位值。
+      sessionFile: mainSessionFile || undefined,
       depth: 0,
       rootSessionId,
       children: [],

package/src/core/family.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 /**
  * 家族索引与解析（design §3.3 D-7）。
@@ -78,6 +78,74 @@ export interface FamilyIndex {
   fileStats: Map<string, { mtime: number; size: number }>
 }
 
+// ---- zcode 节点（design session-reader-shared-core §3.3 D5-1）----
+
+/**
+ * zcode subagent 节点的判据输入视图（discovery 层 zcode-manifest.ts 枚举产出，
+ * core 层零 IO 消费）。扁平化：dbPath 取自 manifest engineHandle.sessionRef.dbPath
+ * （zcode 锚），dbFileExists 由 discovery 枚举时 statSync 预计算——stat 只查存在性
+ * **不开库**（D5-1：静息态 CANTOPEN 会把活会话误判已 GC，且列表视图每节点开库的
+ * 成本不该付；库内 session 已被 zcode GC 的情形由 read 路径 zcode_session_not_found
+ * 权威承接，列表视图保持廉价是本判据的设计核心）。
+ */
+export interface ZcodeFamilyNode {
+  /** record id（= sa-id，manifest 文件名 stem）。作 SubagentRef.sessionId（pi 孤儿链同款：entry.id = manifest.id） */
+  id: string
+  /** subagent 的发起 session id（subagentsByRoot 挂载键，与 pi identity.data.rootSessionId 同语义） */
+  rootSessionId: string
+  /** slug 标签（discovery 组装时已兜底 m.slug ?? m.agentName ?? ''，与 pi 孤儿链同款） */
+  slug: string
+  /** agent 类型名 */
+  agentName?: string
+  task?: string
+  model?: string
+  status?: string
+  /** zcode 锚的库路径（engineHandle.sessionRef.dbPath；枚举谓词已保证非空 string） */
+  dbPath: string
+  /** 库文件存在性（discovery 枚举时 statSync 预计算；D5-1 第二判据的唯一输入） */
+  dbFileExists: boolean
+}
+
+/**
+ * zcode 节点 → subagentsByRoot（D5-1 判据落地）。
+ *
+ * 判据（两项、不开库）：**锚可解析 ∧ 库文件存在 → cleanedUp=false；缺一 → true**。
+ * 「锚可解析」在枚举层已构造性成立（listZcodeManifests 谓词 = engine==='zcode' ∧
+ * sessionRef 双键齐，未通过的记录不产出）——core 层只需消费 dbFileExists。
+ *
+ * 与 pi 节点**刻意不同构**（D5-1 显式声明）：pi 判据 = fileStats JSONL 文件存在性
+ * （buildSubagentsByRoot 的 !fileStats.has(ident.id)）；zcode 节点住在 SQLite 库里、
+ * 没有 JSONL 文件，「文件在不在」对它是无效判据。二者不互相回归。
+ */
+export function buildZcodeSubagentsByRoot(
+  nodes: readonly ZcodeFamilyNode[],
+): Map<string, SubagentRef[]> {
+  const byRoot = new Map<string, SubagentRef[]>()
+  for (const n of nodes) {
+    const ref: SubagentRef = {
+      // zcode 节点无 subagent session 文件，sessionId 用 record id（pi 孤儿链同款占位）
+      sessionId: n.id,
+      rootSessionId: n.rootSessionId,
+      slug: n.slug,
+      fileName: '', // 占位空串（family 路径不回填，与 pi 一致）
+      mtime: 0, // 无 JSONL 文件可 stat，恒 0（占位约定，见文件头注释）
+      sizeBytes: 0,
+      cwd: '',
+      // D5-1：锚可解析（枚举谓词已过）∧ 库文件存在 → false；缺一 → true（GC 语义）
+      cleanedUp: !n.dbFileExists,
+      task: n.task,
+      agentName: n.agentName,
+      model: n.model,
+      status: n.status,
+      // sessionFile 不设：zcode 无 session.jsonl（pi 孤儿保留 GC 路径，zcode 无路径可保留）
+    }
+    const list = byRoot.get(n.rootSessionId)
+    if (list) list.push(ref)
+    else byRoot.set(n.rootSessionId, [ref])
+  }
+  return byRoot
+}
+
 // ---- 类型守卫：从 unknown 的 entry.data 提取 subagent identity 字段 ----
 
 /**
@@ -225,6 +293,8 @@ function buildSubagentsByRoot(
  * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
  * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
  * - fileStats 原样存入 index，供 cleanedUp 判断
+ * - zcodeNodes（可选，U6）→ zcode subagent 节点并入 subagentsByRoot（D5-1 判据，
+ *   与 pi 判据不同构；不传 = pi 行为逐字节不变——零涟漪）
  *
  * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
  * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
@@ -233,10 +303,19 @@ export function buildFamilyIndex(
   headers: Entry[],
   subagentIdentities: Entry[],
   fileStats: Map<string, { mtime: number; size: number }>,
+  zcodeNodes?: readonly ZcodeFamilyNode[],
 ): FamilyIndex {
   const byId = buildById(headers, fileStats)
   const childrenOf = buildChildrenOf(headers, byId)
   const subagentsByRoot = buildSubagentsByRoot(subagentIdentities, fileStats)
+  if (zcodeNodes !== undefined && zcodeNodes.length > 0) {
+    const zcodeByRoot = buildZcodeSubagentsByRoot(zcodeNodes)
+    for (const [rootId, refs] of zcodeByRoot) {
+      const existing = subagentsByRoot.get(rootId)
+      if (existing) existing.push(...refs)
+      else subagentsByRoot.set(rootId, refs)
+    }
+  }
   return { byId, childrenOf, subagentsByRoot, fileStats }
 }
 

package/src/core/render.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 import { BYTES_PER_KB } from './units.js'
 import { extractToolCalls, formatToolCallSummary, type ToolCallInfo } from './toolcall.js'
 import type { Turn } from './turns.js'

package/src/core/toolcall.ts

@@ -6,9 +6,9 @@
  *   message.toolCalls 顶层字段从未存在——v1 render.ts 读 toolCalls 恒返 [] 是 O1 要修的 bug。
  * - arguments 始终是 object（10 工具 100%）；string 形态做 JSON.parse 兜底（失败返 {}），防御历史/异类实现。
  * - toolResult.message 自带 toolName + toolCallId（515/515，全部匹配 toolCall.id），
- *   parser.ts 已 additive 透出这两个字段，O2/O3 据此精确关联取参数。
+ *   Entry 接口（session-core 基座）已 additive 透出这两个字段，O2/O3 据此精确关联取参数。
  */
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 import { BYTES_PER_KB } from './units.js'
 
 // ---------------------------------------------------------------------------

package/src/core/tree.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 export interface TreeView {
   /** root → leaf 的 id 序列（pi 重开视角的当前对话线，design D-2） */

package/src/core/turns.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 /**
  * 一轮对话（design §3.5 算法 3 的分段产物，冻结接口）。

package/src/core/workflow.ts

@@ -1,11 +1,13 @@
 // ============================================================
-// workflow 概览解析与渲染（w5 新增，纯逻辑零 IO）
+// workflow 概览解析与渲染（w5 新增 → [D16③] record 流换源）
 // ============================================================
 //
-// 本文件消费 discovery/workflows.ts 的 readRunSnapshot（返 unknown 原始快照对象），
-// 把 unknown 类型化为 WorkflowOverview（NEW v='wf-run-v1'/'wf-run-v2' / OLD 无 v 双格式分支），
-// 再渲染为人类可读文本。零 IO：parseRunSnapshot/renderWorkflowOverview 喂 mock 即可单测
-//（w5 TC-wf-core-pure-logic，对齐 session-reader core/* 纯逻辑约定）。
+// 本文件消费 discovery/workflows.ts 的 readRunSnapshot（v1/旧指针档——返 unknown
+// 原始快照对象，NEW/OLD 双格式分支）与 record 流文本（[D16③] v2 档——journalPath
+// 锚点语义重定义为 record 流路径后的新数据源），把 unknown/事件流行类型化为
+// WorkflowOverview，再渲染为人类可读文本。零 IO：parseRunSnapshot /
+// parseRunRecordStream / renderWorkflowOverview 喂 mock 即可单测（w5
+// TC-wf-core-pure-logic，对齐 session-reader core/* 纯逻辑约定）。
 //
 // 不 import @zhushanwen/pi-subagent-workflow 的 RunSnapshot 类型——跨包类型耦合会使上游
 // 升版连带编译期影响本扩展；且上游类型只描述 NEW，OLD 仍需自处理（TC-wf-snapshot-version-union）。
@@ -72,7 +74,7 @@ export interface WorkflowOverview {
   runId: string
   /** WorkflowRef.stateFile 透传 */
   stateFile: string
-  /** NEW state.status / OLD 顶层 status */
+  /** NEW state.status / OLD 顶层 status / record 流投影（[D2] 三态：running | interrupted | done） */
   status: string
   /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
   version: 'wf-run-v1' | 'wf-run-v2' | 'legacy'
@@ -319,3 +321,191 @@ export function renderWorkflowOverview(overview: WorkflowOverview): string {
   if (overview.error) lines.push(`error: ${overview.error}`)
   return lines.join('\n')
 }
+
+// ---- parseRunRecordStream（[D16③] record 事件流 → WorkflowOverview）----
+
+/** record 事件流逐行宽容解析后的最小行视图（type 判别 + 载荷按需读）。 */
+interface RecordStreamLine {
+  type: unknown
+  ts?: unknown
+  [key: string]: unknown
+}
+
+/** 流解析产物：run 装配面（runId 透传 + stateFile=record 流路径）。 */
+interface RecordStreamFold {
+  workflowName?: string
+  startedAt?: number
+  interrupted?: { errorCode?: string; reason?: string; ts: number }
+  runSettled?: { outcome?: string; reason?: string; ts: number }
+  budgetUsedTokens?: number
+  calls: Map<number, RecordStreamCallFold>
+}
+
+interface RecordStreamCallFold {
+  index: number
+  agentName?: string
+  phase?: string
+  settledOutcome?: string
+  durationMs?: number
+  sessionFile?: string
+  sessionId?: string
+}
+
+function parseRecordStreamLine(line: string): RecordStreamLine | undefined {
+  const trimmed = line.trim()
+  if (trimmed === '') return undefined
+  try {
+    const parsed: unknown = JSON.parse(trimmed)
+    if (typeof parsed === 'object' && parsed !== null) return parsed as RecordStreamLine
+    return undefined
+  } catch {
+    return undefined // 坏行（截断行）跳过
+  }
+}
+
+/**
+ * record 事件流 → WorkflowOverview（[D16③] 概览链换源；[D2]/[D3]/[D4] 词表）：
+ * - run-created：workflowName + startedAt（ISO 换算）；
+ * - agent-started：call 行骨架（agentName / phase / 首见生效）；
+ * - agent-settled：call 终局（outcome/durationMs + result 全文的 sessionFile/
+ *   sessionId——家族链跳转入口）；
+ * - run-interrupted：[D2] 中断转移 → status 'interrupted'（非终局）；
+ * - run-resumed：[D2] 复活转移 → 清中断标记（status 回 running——lifecycle fold
+ *   投影语义：run-resumed 是 interrupted → running 的转移证据，跳过会使 resume
+ *   续跑期间的概览停在 interrupted 直至终局）；
+ * - run-settled：终局帧 → status 'done' + outcome（done/failed/cancelled/time_limited）；
+ * - 其余（phase-started / phase-settled）：跳过（状态机转移不进概览文本——phase 分组展示
+ *   归 format 域，U3 接线）。
+ *
+ * 空流/无终局帧 → status 'running'（活跃 run 概览不退化为 skipped——红线）。
+ */
+/** [parseRunRecordStream 拆分] 单行 fold 归并（rec 已过 parseRecordStreamLine 判形）。 */
+function applyRecordStreamLine(fold: RecordStreamFold, rec: RecordStreamLine): void {
+  if (rec.type === 'run-created') {
+    fold.workflowName = typeof rec.workflowName === 'string' ? rec.workflowName : undefined
+    fold.startedAt = typeof rec.ts === 'number' ? rec.ts : undefined
+  } else if (rec.type === 'agent-started' && typeof rec.taskIndex === 'number') {
+    applyAgentStartedToFold(fold, rec)
+  } else if (rec.type === 'agent-settled' && typeof rec.taskIndex === 'number') {
+    applyAgentSettledToFold(fold, rec)
+  } else if (rec.type === 'run-interrupted' || rec.type === 'run-resumed' || rec.type === 'run-settled') {
+    applyRunTransitionLine(fold, rec)
+  }
+}
+
+/** [applyRecordStreamLine 拆分] run 级转移帧归并（interrupted 置位 / resumed 清除 / settled 落终局）。 */
+function applyRunTransitionLine(fold: RecordStreamFold, rec: RecordStreamLine): void {
+  if (rec.type === 'run-interrupted') {
+    fold.interrupted = {
+      errorCode: typeof rec.errorCode === 'string' ? rec.errorCode : undefined,
+      reason: typeof rec.reason === 'string' ? rec.reason : undefined,
+      ts: typeof rec.ts === 'number' ? rec.ts : 0,
+    }
+  } else if (rec.type === 'run-resumed') {
+    fold.interrupted = undefined
+  } else if (rec.type === 'run-settled') {
+    fold.runSettled = {
+      outcome: typeof rec.outcome === 'string' ? rec.outcome : undefined,
+      reason: typeof rec.reason === 'string' ? rec.reason : undefined,
+      ts: typeof rec.ts === 'number' ? rec.ts : 0,
+    }
+  }
+}
+
+/** [applyRecordStreamLine 拆分] agent-started 归并（已有行不覆盖——首见即权威）。 */
+function applyAgentStartedToFold(
+  fold: RecordStreamFold,
+  rec: RecordStreamLine,
+): void {
+  const taskIndex = rec.taskIndex
+  if (typeof taskIndex !== 'number') return
+  if (fold.calls.has(taskIndex)) return
+  fold.calls.set(taskIndex, {
+    index: taskIndex,
+    agentName: typeof rec.agentName === 'string' ? rec.agentName : undefined,
+    phase: typeof rec.phase === 'string' ? rec.phase : undefined,
+  })
+}
+
+/** [applyRecordStreamLine 拆分] agent-settled 归并（终局字段覆盖，session 锚点取 result 载荷、缺席保留既有）。 */
+function applyAgentSettledToFold(
+  fold: RecordStreamFold,
+  rec: RecordStreamLine,
+): void {
+  const taskIndex = rec.taskIndex
+  if (typeof taskIndex !== 'number') return
+  const existing = fold.calls.get(taskIndex) ?? { index: taskIndex }
+  const result = typeof rec.result === 'object' && rec.result !== null ? (rec.result as Record<string, unknown>) : {}
+  fold.calls.set(taskIndex, {
+    ...existing,
+    settledOutcome: typeof rec.outcome === 'string' ? rec.outcome : undefined,
+    durationMs: typeof rec.durationMs === 'number' ? rec.durationMs : undefined,
+    sessionFile: typeof result.sessionFile === 'string' ? result.sessionFile : existing.sessionFile,
+    sessionId: typeof result.sessionId === 'string' ? result.sessionId : existing.sessionId,
+  })
+}
+
+/** [parseRunRecordStream 拆分] status 三态投影（[D2]）：终局帧 > 中断转移 > running（空流也 running——活跃兜底）。 */
+function projectRecordStreamStatus(fold: RecordStreamFold): {
+  status: string
+  reason: string | undefined
+  completedAt: string | undefined
+  error: string | undefined
+} {
+  if (fold.runSettled !== undefined) {
+    return {
+      status: 'done',
+      reason: fold.runSettled.outcome,
+      completedAt: new Date(fold.runSettled.ts).toISOString(),
+      error: fold.runSettled.outcome === 'failed' ? fold.runSettled.reason ?? fold.runSettled.outcome : undefined,
+    }
+  }
+  if (fold.interrupted !== undefined) {
+    return { status: 'interrupted', reason: undefined, completedAt: undefined, error: fold.interrupted.reason }
+  }
+  return { status: 'running', reason: undefined, completedAt: undefined, error: undefined }
+}
+
+/** [parseRunRecordStream 拆分] call 行 → 概览 steps（index 升序，条件展开保持键缺席语义）。 */
+function foldCallsToOverviewSteps(fold: RecordStreamFold): WorkflowStep[] {
+  return [...fold.calls.values()]
+    .sort((a, b) => a.index - b.index)
+    .map((call) => ({
+      index: call.index,
+      status: call.settledOutcome === undefined ? 'running' : 'done',
+      ...(call.agentName !== undefined ? { description: call.agentName } : {}),
+      ...(call.durationMs !== undefined ? { durationMs: call.durationMs } : {}),
+      ...(call.sessionId !== undefined ? { sessionId: call.sessionId } : {}),
+      ...(call.sessionFile !== undefined ? { sessionFile: call.sessionFile } : {}),
+    }))
+}
+
+export function parseRunRecordStream(
+  content: string | undefined,
+  runId: string,
+  stateFile: string,
+): WorkflowOverview {
+  const fold: RecordStreamFold = { calls: new Map() }
+  for (const line of content?.split('\n') ?? []) {
+    const rec = parseRecordStreamLine(line)
+    if (rec === undefined) continue
+    applyRecordStreamLine(fold, rec)
+  }
+
+  const { status, reason, completedAt, error } = projectRecordStreamStatus(fold)
+  const steps = foldCallsToOverviewSteps(fold)
+
+  return {
+    runId,
+    stateFile,
+    status,
+    version: 'wf-run-v2',
+    ...(fold.workflowName !== undefined ? { script: fold.workflowName } : {}),
+    ...(fold.startedAt !== undefined ? { startedAt: new Date(fold.startedAt).toISOString() } : {}),
+    ...(completedAt !== undefined ? { completedAt } : {}),
+    ...(reason !== undefined ? { reason } : {}),
+    ...(error !== undefined ? { error } : {}),
+    budget: {},
+    steps,
+  }
+}

package/src/discovery/entry-anchor.ts

@@ -0,0 +1,139 @@
+import { readFile } from 'node:fs/promises'
+
+import { parseSessionContent, type Entry } from '@zhushanwen/session-core'
+
+/**
+ * zcode 锚的 entry 兜底定位（设计 session-reader-shared-core §3.1 第②步）。
+ *
+ * 定位链第②层：zcode manifest 直读（第①层，zcode-manifest.ts）缺位/残缺时，
+ * 在候选主 session 文件里按 sa-id 扫 `subagent-record` custom entry，取其
+ * `engineHandle.sessionRef`（zcode 形态 = `{sessionId, dbPath}`）。
+ *
+ * 边界承载（设计四要素登记）：本函数只认「候选文件列表」，越界语义（不做根内
+ * 全扫、liveSessionDir 优先排序）由调用方构造候选集时决定——第一梯队只传
+ * liveSessionDir 内的主 session 文件，越界查询返回 not-found 信号（undefined，
+ * 调用方映射 `zcode_record_not_found` 错误码，§3.4）。
+ */
+
+/**
+ * zcode 锚（zcode 引擎自描述定位符的 zcode 形态）。与 manifest 直读产出的锚同形；
+ * `sessionRef` 写侧整体透传不枚举内部键（subagent-core record-entry.ts
+ * engineHandle.sessionRef 注释），本单元按 zcode 形态校验并窄化为双键。
+ */
+export interface ZcodeAnchor {
+  sessionId: string
+  dbPath: string
+}
+
+/**
+ * `subagent-record` custom entry 的 customType 值。
+ *
+ * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core record-entry.ts 的
+ * SUBAGENT_RECORD_CUSTOM_TYPE。reader 生产依赖面不引 subagent-core（该包是
+ * devDependency + vitest alias 形态），故按协议字符串本地持有；两侧漂移由
+ * entry-anchor.test.ts 的跨包断言守卫。
+ */
+const SUBAGENT_RECORD_CUSTOM_TYPE = 'subagent-record'
+
+/**
+ * v2 条目 data 的认识版本词表（W1 起 = 2）。与写侧 subagent-core
+ * SUBAGENT_RECORD_ENTRY_VERSION 同值、同「本地持有 + 测试守卫漂移」模式——写侧
+ * 再升 v3 时本守卫先红，提醒评估新版本的锚读取面。
+ */
+const SUBAGENT_RECORD_ENTRY_V2 = 2
+
+/**
+ * 从单条 entry 提取 zcode 锚。形状校验窄而严，任一不满足 = 该条不算命中（返回
+ * undefined，调用方继续扫——缺键条目不遮蔽更早的完整条目）：
+ * - `type === 'custom'` ∧ `customType === 'subagent-record'`
+ * - 版本/判别键二选一（schema 版本守卫，不认识的版本跳过而非猜测——写侧
+ *   record-entry.ts classifySubagentRecordEntryData 同口径）：
+ *   - v1：`data.v === 1`（全量快照形态，兼容读面）；
+ *   - v2：`data.v === 2` ∧ `data.kind === 'settled'`（W1 注册/终态两条小条目——
+ *     **锚只取自终态条**：registered 条目不携带 engineHandle，且设计 D1 裁决
+ *     「sessionRef 双键取自终态条」；kind 非法 = unknown-kind 跳过）；
+ * - `data.id === saId`（record id 即 sa-id，record-access.ts `sa-${uuid}`）
+ * - `engineHandle.sessionRef.sessionId` / `.dbPath` 均为非空 string（F8 双键齐判据的
+ *   锚字段部分；pi record 的 sessionRef 无 dbPath → 天然不命中，无需 engine 判别）
+ */
+function zcodeAnchorOfEntry(entry: Entry, saId: string): ZcodeAnchor | undefined {
+  if (entry.type !== 'custom' || entry.customType !== SUBAGENT_RECORD_CUSTOM_TYPE) return undefined
+  const data: unknown = entry.data
+  if (typeof data !== 'object' || data === null) return undefined
+  const d = data as Record<string, unknown>
+  if (d.id !== saId) return undefined
+  if (!isAnchorEligibleRecordEntryVersion(d)) return undefined
+  return extractZcodeSessionRefAnchor(d.engineHandle)
+}
+
+/** [zcodeAnchorOfEntry 拆分] 条目形态判别：v1 全量快照 或 v2 终态条（registered
+ * 条目不携带 engineHandle，且设计 D1 裁决「sessionRef 双键取自终态条」；kind
+ * 非法 = unknown-kind 跳过）。 */
+function isAnchorEligibleRecordEntryVersion(d: Record<string, unknown>): boolean {
+  if (d.v === SUBAGENT_RECORD_ENTRY_V2) {
+    return d.kind === 'settled'
+  }
+  return d.v === 1
+}
+
+/** [zcodeAnchorOfEntry 拆分] engineHandle.sessionRef 双键提取（sessionId/dbPath
+ * 均非空 string 才命中；pi record 的 sessionRef 无 dbPath → 天然不命中）。 */
+function extractZcodeSessionRefAnchor(engineHandle: unknown): ZcodeAnchor | undefined {
+  if (typeof engineHandle !== 'object' || engineHandle === null) return undefined
+  const ref: unknown = (engineHandle as Record<string, unknown>).sessionRef
+  if (typeof ref !== 'object' || ref === null) return undefined
+  const r = ref as Record<string, unknown>
+  const { sessionId, dbPath } = r
+  if (typeof sessionId !== 'string' || sessionId === '') return undefined
+  if (typeof dbPath !== 'string' || dbPath === '') return undefined
+  return { sessionId, dbPath }
+}
+
+/**
+ * 在候选主 session 文件里按 sa-id 定位 zcode 锚。
+ *
+ * 取条语义（设计 §2.5 裁决，subagent-core collectLastRecordEntries 逐字同构——
+ * 「主 session 全文 → 每 id 末条 record data」，record-store-rebuild.ts:212-227）：
+ * 同一 sa-id 每次状态迁移写一条全量快照 entry 且 sessionRef 每轮覆写（F16），故
+ * 同文件内后条覆盖前条 = 文件顺序末条。**禁止另创取首条/合并语义**（附录 B-6）。
+ * W1 v2 双形态下末条锚定语义不变：registered 条目不命中（无 engineHandle），
+ * 「末条」= 最后一条可命中的 v1 快照条或 v2 终态条（v2 settled 条目也随 reopen
+ * 多轮各写一条，后写覆盖前写，与 v1 覆写同构）。
+ *
+ * 多候选文件：按候选列表顺序逐文件扫，文件内有命中锚（含末条裁决后）即止——
+ * 候选顺序 = 调用方声明的优先级（liveSessionDir 优先），不跨文件合并。
+ *
+ * 行级容错：逐行解析由基座 parseSessionContent 承担（坏行跳过继续、末行半行记
+ * lastLinePartial 不中断）——best-effort，不因一行坏 JSON 失败整文件。
+ *
+ * 候选文件读失败（不存在/不可读）= 该候选无命中，跳过继续下一候选；本函数契约
+ * 是「锚或 not-found」，IO 错误同样收敛到 not-found 信号（调用方映射错误码），
+ * 不向上抛。
+ *
+ * 读取用 node:fs/promises 的 async readFile——本函数跑在 pi 扩展进程内，同步
+ * readFileSync 全文读入会阻塞事件循环（同函数族 classifyIncompleteEntryAnchor
+ * 同形态；对照 readSessionHeaderIdSync 只在首行 4KB 有界读时才允许同步）。
+ *
+ * @returns 命中的锚；所有候选均未命中（或全部候选不可读）→ undefined（not-found 信号）
+ */
+export async function findZcodeEntryAnchor(
+  candidateFiles: readonly string[],
+  saId: string,
+): Promise<ZcodeAnchor | undefined> {
+  for (const file of candidateFiles) {
+    let content: string
+    try {
+      content = await readFile(file, 'utf8')
+    } catch {
+      continue
+    }
+    const { entries } = parseSessionContent(content)
+    let anchor: ZcodeAnchor | undefined
+    for (const entry of entries) {
+      const hit = zcodeAnchorOfEntry(entry, saId)
+      if (hit !== undefined) anchor = hit
+    }
+    if (anchor !== undefined) return anchor
+  }
+  return undefined
+}

package/src/discovery/roots.ts

@@ -67,8 +67,7 @@ const SUBAGENTS_DIRNAME = 'subagents'
 /**
  * `[live]` 规范化（§6.1/§7B 要点 3）：`getSessionDir()` 在纯 pi 返回按 cwd 编码的子目录
  *（`<agentDir>/sessions/--Users-x--`），在 taiji 覆盖态返回根本身。判据：basename
- * 匹配 encodeCwd 形态（`--` 开头 `--` 结尾，实证见 `~/.pi/agent/sessions/` 全部子目录
- * 与 real-data.ts）则取 dirname，否则取自身。
+ * 匹配 encodeCwd 形态（`--` 开头 `--` 结尾）则取 dirname，否则取自身。
  */
 export function normalizeLiveSessionDir(liveSessionDir: string): string {
   const base = basename(liveSessionDir)