@zhushanwen/pi-session-reader 0.7.0 → 0.8.1

package/src/discovery/entry-anchor.ts

@@ -35,11 +35,23 @@ export interface ZcodeAnchor {
  */
 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'`
- * - `data.v === 1`（schema 版本守卫，不认识的版本跳过而非猜测——写侧 record-entry.ts v 注释同口径）
+ * - 版本/判别键二选一（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 判别）
@@ -49,10 +61,26 @@ function zcodeAnchorOfEntry(entry: Entry, saId: string): ZcodeAnchor | undefined
   const data: unknown = entry.data
   if (typeof data !== 'object' || data === null) return undefined
   const d = data as Record<string, unknown>
-  if (d.v !== 1 || d.id !== saId) return undefined
-  const handle: unknown = d.engineHandle
-  if (typeof handle !== 'object' || handle === null) return undefined
-  const ref: unknown = (handle as Record<string, unknown>).sessionRef
+  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
@@ -68,6 +96,9 @@ function zcodeAnchorOfEntry(entry: Entry, saId: string): ZcodeAnchor | undefined
  * 「主 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 优先），不跨文件合并。

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)

package/src/discovery/workflows.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { basename } from 'node:path'
-import { parseSessionContent } from '@zhushanwen/session-core'
+import { parseSessionContent, type Entry } from '@zhushanwen/session-core'
 import type { SessionRef, WorkflowRef } from '../core/family.js'
 import { extractSessionIdFromFilename } from './subagents.js'
 
@@ -9,10 +9,22 @@ import { extractSessionIdFromFilename } from './subagents.js'
 // ============================================================
 //
 // 本文件持有 workflow run 的发现与 sessionFile 提取逻辑（IO 适配层）：
-// - resolveWorkflows：读目标 session 的 workflow-state-link custom entry → 每个 link 的
-//   wf-state 文件 → 提 calls 的 sessionFile → SessionRef[]。返回 WorkflowRef[]（family.workflows 腿）。
+// - resolveWorkflows：三档发现链（按 runId 合并，高档条目在即用高档）——
+//   ① v2 journalPath 主源（[D16③] 发现链重锚：journalPath 锚点语义 = record 流路径）：
+//     workflow-record v2 注册条目的 journalPath 指向 <runId>.record.jsonl（[D1] record
+//     单源事件流），发现链读 record 流行自提 calls——sessionFile 取 agent-settled 帧
+//     result 全文携带的 sessionFile（[D1] 载荷表：result 全文入事件，AgentResult
+//     自带 sessionFile 字段——家族链数据源同 record 流，无第二承载位）；旧后缀锚点
+//     （.events.jsonl 形态）= 历史实体（[D1] 历史数据处置：旧两件不读）→ calls=[]
+//     仅 run 存在性兜底；
+//   ② v1 快照层：workflow-record v1 快照条目（W17~W1 期间创建的 run——快照是全量的，
+//     直接从 snapshot.calls 提 sessionFile，家族链数据完整）；
+//   ③ 旧指针 fallback：workflow-state-link 指针条目（W17 前的 run，照旧读 link 指向的
+//     wf-state 文件）。
 // - readRunSnapshot：读 wf-state 文件尾向找首个可解析行，返回原始对象（unknown，格式收窄交 core 层）。
 // - extractCallSessionFiles：从快照对象提 calls 的 sessionFile 绝对路径数组（NEW/OLD 双格式）。
+// - extractRecordStreamSessionFiles：[D16③] 从 record 事件流提 calls 的 sessionFile
+//   （agent-settled 帧 result.sessionFile——活跃 run 与已收编 run 同源可用）。
 // - sessionRefFromPath：sessionFile 路径 → SessionRef（命中 pathToRef 取完整，否则文件名提取最小 ref）。
 //
 // 分层约定（w5 TC-wf-core-pure-logic）：IO 全在 discovery/，core/workflow.ts 的
@@ -133,13 +145,185 @@ function sessionRefFromPath(path: string, pathToRef: Map<string, SessionRef>): S
   }
 }
 
+// ============================================================
+// workflow-record 条目契约（三档发现链的条目判别——本地字面量 + 测试守卫漂移）
+// ============================================================
+
 /**
- * 读目标 session 文件全文，解析 workflow-state-link custom entries，构造 WorkflowRef[]。
- * 同一 runId 的多个 link（workflow 多次更新产生）按 runId 去重，取最新 link（path 相同）。
+ * `workflow-record` custom entry 的 customType 值。
  *
- * 内部用 readRunSnapshot + extractCallSessionFiles 组合替代原 readWorkflowCallSessionFiles
- *（w5 迁移，行为等价）。**签名与返回值结构（WorkflowRef[]{runId,stateFile,calls:SessionRef[]}）
- * 完全不变**（C-resolveworkflows-signature，保 m1 已冻结交付的消费者）。
+ * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core
+ * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖面不引
+ * subagent-core（同 entry-anchor.ts 的协议字面量模式），两侧漂移由 workflow.test.ts
+ * 的跨包断言守卫。
+ */
+const WORKFLOW_RECORD_CUSTOM_TYPE = 'workflow-record'
+
+/** v2 条目 data 的认识版本词表（W1 起 = 2；写侧 WORKFLOW_RECORD_ENTRY_VERSION 同值）。 */
+const WORKFLOW_RECORD_ENTRY_V2 = 2
+
+/**
+ * run record 流文件名尾段（`<runId>.record.jsonl`）。写侧 subagent-core
+ * RUN_EVENT_JOURNAL_SUFFIX 同值（[D1] record 单源后缀）——v2 注册条目的
+ * journalPath 锚点后缀判定用（新锚点直读 record 流；旧 `.events.jsonl` 锚点 =
+ * 历史实体分流），本地持有 + 测试守卫漂移。
+ */
+export const RUN_RECORD_STREAM_SUFFIX = '.record.jsonl'
+
+/** 单遍扫描 entries 的三档收集结果（档内同 runId 后写覆盖前写，跨档优先级见 resolveWorkflows）。 */
+interface WorkflowEntryTiers {
+  /** ① v2 注册条目：runId → journalPath 锚点（W1+ 的 run）。 */
+  v2ByRunId: Map<string, string>
+  /** ② v1 快照条目：runId → 全量快照对象（W17~W1 期间创建的 run）。 */
+  v1ByRunId: Map<string, unknown>
+  /** ③ 旧指针条目：runId → link path（W17 前的 run）。 */
+  linkByRunId: Map<string, { runId: string; path: string }>
+  /** runId 首见序（输出稳定序——条目在 session 文件中的出现顺序）。 */
+  runIdOrder: string[]
+}
+
+/**
+ * 单遍扫描 entries 按三档形态分桶（纯收集，无 IO）：
+ * - workflow-record v2 注册条目：`v === 2` ∧ `kind === 'registered'` ∧ runId/journalPath
+ *   均非空 string（终态条目不携带 journalPath，非发现链数据源，不收集）；
+ * - workflow-record v1 快照条目：`v === 1` ∧ snapshot 为对象 ∧ `snapshot.runId` 为
+ *   string（runId 在快照内——entry data 顶层无 runId 字段）；
+ * - workflow-state-link 指针条目：现状判别。
+ */
+function collectWorkflowEntryTiers(entries: readonly Entry[]): WorkflowEntryTiers {
+  const tiers: WorkflowEntryTiers = {
+    v2ByRunId: new Map(),
+    v1ByRunId: new Map(),
+    linkByRunId: new Map(),
+    runIdOrder: [],
+  }
+  const seen = new Set<string>()
+  const noteRunId = (runId: string): void => {
+    if (!seen.has(runId)) {
+      seen.add(runId)
+      tiers.runIdOrder.push(runId)
+    }
+  }
+  for (const e of entries) {
+    const data = e.data as Record<string, unknown> | undefined
+    if (e.customType === WORKFLOW_RECORD_CUSTOM_TYPE && data !== undefined) {
+      collectWorkflowRecordEntryTier(tiers, noteRunId, data)
+      continue
+    }
+    // legacy 指针档字面量：常量 SSOT 在 subagent-core（WORKFLOW_STATE_LINK_CUSTOM_TYPE，
+    // orchestration/workflow-record-entry.ts）。reader 生产依赖面不引 subagent-core
+    // （包架构裁决，同 entry-anchor.ts 的协议字面量模式），保持本地镜像，值等价由
+    // __tests__/workflow.test.ts 跨包契约守卫断言锚定。
+    if (e.customType === 'workflow-state-link') {
+      collectWorkflowStateLinkTier(tiers, noteRunId, data)
+    }
+  }
+  return tiers
+}
+
+/** [collectWorkflowEntryTiers 拆分] workflow-record 条目两代分流（v2 注册 / v1 快照）。 */
+function collectWorkflowRecordEntryTier(
+  tiers: WorkflowEntryTiers,
+  noteRunId: (runId: string) => void,
+  data: Record<string, unknown>,
+): void {
+  if (data.v === WORKFLOW_RECORD_ENTRY_V2 && data.kind === 'registered') {
+    const runId = data.runId
+    const journalPath = data.journalPath
+    if (typeof runId === 'string' && runId !== '' && typeof journalPath === 'string' && journalPath !== '') {
+      tiers.v2ByRunId.set(runId, journalPath)
+      noteRunId(runId)
+    }
+  } else if (data.v === 1 && typeof data.snapshot === 'object' && data.snapshot !== null) {
+    const snapshotRunId = (data.snapshot as Record<string, unknown>).runId
+    if (typeof snapshotRunId === 'string' && snapshotRunId !== '') {
+      tiers.v1ByRunId.set(snapshotRunId, data.snapshot)
+      noteRunId(snapshotRunId)
+    }
+  }
+}
+
+/** [collectWorkflowEntryTiers 拆分] workflow-state-link 指针条目（后写覆盖前写——取最新 link）。 */
+function collectWorkflowStateLinkTier(
+  tiers: WorkflowEntryTiers,
+  noteRunId: (runId: string) => void,
+  data: Record<string, unknown> | undefined,
+): void {
+  const runId = data?.runId
+  const path = data?.path
+  if (typeof runId === 'string' && typeof path === 'string') {
+    tiers.linkByRunId.set(runId, { runId, path }) // 后写覆盖前写（取最新 link）
+    noteRunId(runId)
+  }
+}
+
+/**
+ * [D16③] journalPath 后缀分流：`.record.jsonl` 锚点 = 新形态（record 流直读）；
+ * 其余（含旧 `.events.jsonl` 锚点）= 历史实体（[D1] 历史数据处置——旧两件不读
+ * 不写，历史 run 从发现链数据面退空即预期行为）。
+ */
+function isNewRecordStreamAnchor(journalPath: string): boolean {
+  return journalPath.endsWith(RUN_RECORD_STREAM_SUFFIX)
+}
+
+/** agent-settled 帧的最小消费视图（record 流宽容解析只消费 taskIndex 与
+ *  result.sessionFile 两字段，其余载荷不读取）。 */
+interface AgentSettledSessionFileView {
+  taskIndex: number
+  result: { sessionFile: string }
+}
+
+/** [extractRecordStreamSessionFiles 守卫] 单帧是否为携带非空 result.sessionFile
+ *  的 agent-settled 帧：逐字段 typeof 校验（type → taskIndex → result →
+ *  sessionFile），不过关 = 宽容跳过（与 readRunSnapshot 同容忍度）。 */
+function isAgentSettledSessionFileFrame(v: unknown): v is AgentSettledSessionFileView {
+  if (typeof v !== 'object' || v === null) return false
+  const rec = v as Record<string, unknown>
+  if (rec.type !== 'agent-settled' || typeof rec.taskIndex !== 'number') return false
+  const result: unknown = rec.result
+  if (typeof result !== 'object' || result === null) return false
+  const sessionFile: unknown = (result as Record<string, unknown>).sessionFile
+  return typeof sessionFile === 'string' && sessionFile !== ''
+}
+
+/**
+ * [D16③] record 事件流 → calls 的 sessionFile 绝对路径数组：逐行宽容解析
+ * （跳过坏行/空行——与 readRunSnapshot 同容忍度），agent-settled 帧（含
+ * result 全文）按 taskIndex 归位——首见生效（重试波多帧时终局帧 result 后到
+ * 覆盖，与 fold 后到覆盖语义一致）。
+ */
+export function extractRecordStreamSessionFiles(content: string): string[] {
+  const byIndex = new Map<number, string>()
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch {
+      continue // 坏行（截断行）跳过
+    }
+    if (!isAgentSettledSessionFileFrame(parsed)) continue
+    byIndex.set(parsed.taskIndex, parsed.result.sessionFile)
+  }
+  return [...byIndex.entries()].sort((a, b) => a[0] - b[0]).map(([, sf]) => sf)
+}
+
+/**
+ * 读目标 session 文件全文，按三档发现链构造 WorkflowRef[]（D10 断链修复：W17 前/
+ * W17~W1/W1+ 三类 run 全部有发现通道）。同一 runId 的多条目按 runId 去重取档内
+ * 最新（后写覆盖）；跨档优先级 = v2 注册条目 > v1 快照条目 > 旧指针——一个 run 只
+ * 以一种形态写条目（创建时点决定），跨档同 runId 是坏数据防御，高档在即用高档。
+ *
+ * **签名与返回值结构（WorkflowRef[]{runId,stateFile,calls:SessionRef[]}）完全不变**
+ * （C-resolveworkflows-signature，保 m1 已冻结交付的消费者）。三档的 stateFile 语义：
+ * - v2 档：stateFile = journalPath 本身（record 流路径——[D16③] 锚点语义重定义，
+ *   D1 后 v2 条目携带的锚点即 record 事件流文件）；record 流直读提 calls
+ *   （agent-settled.result.sessionFile），流被清理/不可读 → calls=[]（run 存在性
+ *   兜底）；
+ * - v1 档：空串（v1 快照条目不携带 state 路径，快照数据直接从条目提 calls；概览
+ *   消费面 readRunSnapshot('') 自然落「快照不可读」跳过，家族链 calls 不受影响）；
+ * - 旧指针档：link 的 path（现状）。
  */
 export async function resolveWorkflows(
   sessionId: string,
@@ -155,23 +339,49 @@ export async function resolveWorkflows(
     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 tiers = collectWorkflowEntryTiers(entries)
   const workflows: WorkflowRef[] = []
-  for (const { runId, path } of linkByRunId.values()) {
-    const snap = await readRunSnapshot(path)
+  for (const runId of tiers.runIdOrder) {
+    const journalPath = tiers.v2ByRunId.get(runId)
+    if (journalPath !== undefined) {
+      // ① v2 档（[D16③] 重锚）：journalPath = record 流路径——新后缀锚点直读流提
+      // calls（agent-settled.result.sessionFile）；旧后缀锚点 = 历史实体（[D1]
+      // 不读旧两件）→ calls=[] 仅 run 存在性兜底。
+      let sessionFiles: string[] = []
+      if (isNewRecordStreamAnchor(journalPath)) {
+        let content: string | undefined
+        try {
+          content = await readFile(journalPath, 'utf8')
+        } catch {
+          content = undefined // 流被保留期清理/不可读 → calls=[]（run 存在性兜底）
+        }
+        sessionFiles = content === undefined ? [] : extractRecordStreamSessionFiles(content)
+      }
+      workflows.push({
+        runId,
+        stateFile: journalPath,
+        calls: sessionFiles.map((sf) => sessionRefFromPath(sf, pathToRef)),
+      })
+      continue
+    }
+    const snapshot = tiers.v1ByRunId.get(runId)
+    if (snapshot !== undefined) {
+      // ② v1 快照档：快照全量在场，直接提 calls（W17~W1 中间档恢复）
+      workflows.push({
+        runId,
+        stateFile: '',
+        calls: extractCallSessionFiles(snapshot).map((sf) => sessionRefFromPath(sf, pathToRef)),
+      })
+      continue
+    }
+    // ③ 旧指针档：现状（link path → wf-state 文件）
+    const link = tiers.linkByRunId.get(runId)
+    if (link === undefined) continue
+    const snap = await readRunSnapshot(link.path)
     const sessionFiles = snap === undefined ? [] : extractCallSessionFiles(snap)
     workflows.push({
-      runId,
-      stateFile: path,
+      runId: link.runId,
+      stateFile: link.path,
       calls: sessionFiles.map((sf) => sessionRefFromPath(sf, pathToRef)),
     })
   }

package/src/tool-handler.ts

@@ -58,7 +58,7 @@ import {
   parseSessionFile,
   type ParseResult,
 } from '@zhushanwen/session-core'
-import { parseRunSnapshot, renderWorkflowOverview, type WorkflowOverview } from './core/workflow.js'
+import { parseRunRecordStream, parseRunSnapshot, renderWorkflowOverview, type WorkflowOverview } from './core/workflow.js'
 import { buildTreeView } from './core/tree.js'
 import { segmentTurns } from './core/turns.js'
 import { renderOutline, renderExpand, renderDetail, type OutlineOptions } from './core/render.js'
@@ -335,9 +335,9 @@ async function resolveSaIdRoute(
 /**
  * 候选文件里该 sa-id 的 `subagent-record` entry 若「在场但锚不完整」，返回缺失归因
  *（§3.4 zcode_anchor_missing 的 entry 形态触发 + 日志归因；记录完全不在场返回
- * undefined）。entry 级判定（五关过滤 + D5 engine 判别 + 锚完整性链）在
- * zcode-anchor-classify.ts 的 firstIncompleteAnchorReason，本函数只做文件扫描 I/O
- *（读失败跳过该文件，首个命中归因即终止扫描）。
+ * undefined）。entry 级判定（v1 快照 / v2 终态条双版本门 + D5 engine 判别 + 锚完整
+ * 性链）在 zcode-anchor-classify.ts 的 firstIncompleteAnchorReason，本函数只做文件
+ * 扫描 I/O（读失败跳过该文件，首个命中归因即终止扫描）。
  */
 async function classifyIncompleteEntryAnchor(
   candidateFiles: readonly string[],
@@ -1098,7 +1098,8 @@ interface SkippedRun {
 /**
  * workflow：workflow run 概览（design §3.4 workflow，m2 IF-doWorkflow）。
  *
- * 流程：① resolveSessionId（multi 走 disambiguate）→ ② 读目标 session 的 workflow-state-link
+ * 流程：① resolveSessionId（multi 走 disambiguate）→ ② 读目标 session 的 workflow 条目三档
+ * 发现链（v2 注册条目 record 流主源 > v1 快照 > 旧 workflow-state-link 指针）
  * → ③ 无 run → ES-wf-no-runs（提示+👉family，不抛错）→ ④ runId 过滤，无匹配 →
  * ES-wf-runid-not-found（列候选+👉，不抛错）→ ⑤ 逐 run readRunSnapshot+parseRunSnapshot，
  * 不可读/不可解析 → skippedRuns（不中断其他 run，ES-wf-snapshot-read-fail/unparseable）
@@ -1116,6 +1117,81 @@ interface SkippedRun {
  * step 的 call sessionId/sessionFile 是 LLM 跳 outline/detail 的入口（m0 resolveSessionId
  * 三形态复用：sessionId/绝对路径/sa-id 均可深读，TC-wf-step-sessionfile-link）。
  */
+
+/** [doWorkflow 拆分] 单 run 概览产出（⑤⑥ 的逐 run 半边）：record 流直读档与快照档分流，
+ * 产出聚合进 ctx 四容器（runs/runIds/skippedRuns/contentParts）。 */
+async function renderSingleWorkflowRun(
+  wf: WorkflowRef,
+  ctx: {
+    runs: WorkflowOverview[]
+    runIds: string[]
+    skippedRuns: SkippedRun[]
+    contentParts: string[]
+  },
+): Promise<void> {
+  // [D16③] 概览链换源：v2 档的 stateFile = record 流路径（journalPath 锚点语义
+  // 重定义）——直读流经 parseRunRecordStream 概览（[D2] 三态 status；空流/读失败
+  // 投影 running，活跃 run 概览不退化为 skipped——红线）。record 后缀以外的
+  // stateFile（v1 快照档空串 / 旧指针档 link path）走原快照链。
+  if (wf.stateFile.endsWith('.record.jsonl')) {
+    await renderRunFromRecordStream(wf, ctx)
+    return
+  }
+  const snap = await readRunSnapshot(wf.stateFile)
+  if (snap === undefined) {
+    // ES-wf-snapshot-read-fail：文件不存在/读失败/全行不可解析 → 跳过，不中断其他 run
+    skipRun(ctx, wf, 'snapshot-unreadable', '快照不可读')
+    return
+  }
+  const overview = parseRunSnapshot(snap, wf.runId, wf.stateFile)
+  if (overview === null) {
+    // ES-wf-snapshot-unparseable：对象既非 NEW 也非 OLD → 跳过
+    skipRun(ctx, wf, 'snapshot-unparseable', '快照格式不可识别')
+    return
+  }
+  ctx.runs.push(overview)
+  ctx.runIds.push(wf.runId)
+  ctx.contentParts.push(renderWorkflowOverview(overview))
+}
+
+/** [renderSingleWorkflowRun 拆分] record 流直读档（读失败 → 空流解析，running 兜底不 skipped）。 */
+async function renderRunFromRecordStream(
+  wf: WorkflowRef,
+  ctx: {
+    runs: WorkflowOverview[]
+    runIds: string[]
+    skippedRuns: SkippedRun[]
+    contentParts: string[]
+  },
+): Promise<void> {
+  let content: string | undefined
+  try {
+    content = await readFile(wf.stateFile, 'utf8')
+  } catch {
+    content = undefined // 流被清理/不可读 → 空流解析（running 兜底，不 skipped）
+  }
+  const overview = parseRunRecordStream(content, wf.runId, wf.stateFile)
+  ctx.runs.push(overview)
+  ctx.runIds.push(wf.runId)
+  ctx.contentParts.push(renderWorkflowOverview(overview))
+}
+
+/** [renderSingleWorkflowRun 拆分] 跳过登记（不中断其他 run）。 */
+function skipRun(
+  ctx: {
+    runs: WorkflowOverview[]
+    runIds: string[]
+    skippedRuns: SkippedRun[]
+    contentParts: string[]
+  },
+  wf: WorkflowRef,
+  reason: SkippedRun['reason'],
+  label: string,
+): void {
+  ctx.skippedRuns.push({ runId: wf.runId, stateFile: wf.stateFile, reason })
+  ctx.contentParts.push(`run ${wf.runId}: ${label}（stateFile=${wf.stateFile}）已跳过`)
+}
+
 async function doWorkflow(
   params: SessionReadParams,
   agentDir: string,
@@ -1180,23 +1256,7 @@ async function doWorkflow(
   const contentParts: string[] = []
 
   for (const wf of selected) {
-    const snap = await readRunSnapshot(wf.stateFile)
-    if (snap === undefined) {
-      // ES-wf-snapshot-read-fail：文件不存在/读失败/全行不可解析 → 跳过，不中断其他 run
-      skippedRuns.push({ runId: wf.runId, stateFile: wf.stateFile, reason: 'snapshot-unreadable' })
-      contentParts.push(`run ${wf.runId}: 快照不可读（stateFile=${wf.stateFile}）已跳过`)
-      continue
-    }
-    const overview = parseRunSnapshot(snap, wf.runId, wf.stateFile)
-    if (overview === null) {
-      // ES-wf-snapshot-unparseable：对象既非 NEW 也非 OLD → 跳过
-      skippedRuns.push({ runId: wf.runId, stateFile: wf.stateFile, reason: 'snapshot-unparseable' })
-      contentParts.push(`run ${wf.runId}: 快照格式不可识别（stateFile=${wf.stateFile}）已跳过`)
-      continue
-    }
-    runs.push(overview)
-    runIds.push(wf.runId)
-    contentParts.push(renderWorkflowOverview(overview))
+    await renderSingleWorkflowRun(wf, { runs, runIds, skippedRuns, contentParts })
   }
 
   const details: WorkflowDetails = { runs, runIds }

package/src/zcode-anchor-classify.ts

@@ -1,19 +1,28 @@
 /**
  * [§3.5 entry 兜底归因] zcode subagent-record「在场但锚不完整」的缺失归因判定
- *（classifyIncompleteEntryAnchor 的 entry 级纯逻辑提取，metrics-gate 复杂度偿还，
- * 判定语义零变化；文件扫描与 readFile I/O 留在 tool-handler.ts）。零 I/O 纯函数，
- * 可完全单测。
+ *（classifyIncompleteEntryAnchor 的 entry 级纯逻辑提取；文件扫描与 readFile I/O
+ * 留在 tool-handler.ts）。零 I/O 纯函数，可完全单测。
  *
- * 判定与 entry-anchor.ts 的 zcodeAnchorOfEntry 双键判据同构，协议字面量同值
- *（写侧 subagent-core record-entry.ts SUBAGENT_RECORD_CUSTOM_TYPE，漂移由
- * entry-anchor.test.ts 守卫）。
+ * 判定与 entry-anchor.ts 的 zcodeAnchorOfEntry 双键判据同构（v1 快照 / v2 终态条
+ * 双版本门），协议字面量同值（写侧 subagent-core record-entry.ts
+ * SUBAGENT_RECORD_CUSTOM_TYPE，漂移由 entry-anchor.test.ts 守卫）。
  */
 import type { Entry } from '@zhushanwen/session-core'
 import type { ZcodeAnchorMissingReason } from './discovery/zcode-manifest.js'
 
 /**
- * 目标 sa-id 的 zcode 形态 subagent-record data：type/customType/v=1/id/engine 五关
- * 全过才返回。engine 判别（D5）在此——`d.engine !== 'zcode'` 的记录（pi 形态：
+ * v2 条目 data 的认识版本词表（W1 起 = 2）。与写侧 subagent-core
+ * SUBAGENT_RECORD_ENTRY_VERSION 同值——本地持有 + entry-anchor.test.ts 跨包断言
+ * 守卫漂移（生产依赖面不引 subagent-core，同 entry-anchor.ts 的协议字面量模式）。
+ */
+const SUBAGENT_RECORD_ENTRY_V2 = 2
+
+/**
+ * 目标 sa-id 的 zcode 形态 subagent-record data：type/customType/版本关/id/engine
+ * 全过才返回。版本关（W1 v2 学习，entry-anchor.ts zcodeAnchorOfEntry 同口径）：
+ * v1 全量快照（`d.v === 1`，兼容读面）或 v2 终态条（`d.v === 2` ∧
+ * `d.kind === 'settled'`——engineHandle 只在终态条，registered 不携带不归因）。
+ * engine 判别（D5）在此——`d.engine !== 'zcode'` 的记录（pi 形态：
  * engine 缺省、sessionRef 无 dbPath）不是「zcode 锚不完整」，返回 undefined 跳过
  * 不归因：误归因 missing-dbPath 会把「pi record 先于 manifest settle 落盘」的正常
  * 窗口错报成 zcode_anchor_missing（旧版本产物指引不适用）；正确归因 = undefined
@@ -24,7 +33,12 @@ function zcodeRecordDataOf(entry: Entry, saId: string): Record<string, unknown>
   const data: unknown = entry.data
   if (typeof data !== 'object' || data === null) return undefined
   const d = data as Record<string, unknown>
-  if (d.v !== 1 || d.id !== saId) return undefined
+  if (d.id !== saId) return undefined
+  if (d.v === SUBAGENT_RECORD_ENTRY_V2) {
+    if (d.kind !== 'settled') return undefined
+  } else if (d.v !== 1) {
+    return undefined
+  }
   if (d.engine !== 'zcode') return undefined
   return d
 }

package/src/__tests__/real-data.ts

@@ -1,96 +0,0 @@
-import { existsSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-/**
- * 真实 pi agent 数据常量 + 存在性探测（MF-1：CI 无本机 ~/.pi/agent 目录，
- * 依赖真实数据的用例必须 skipIf 守卫，否则 CI `pnpm extensions:test` 必红）。
- *
- * 用法：测试文件 `import { REAL_AGENT_DIR, HAS_E6 } from './real-data.js'`，
- * 真实数据用例套 `it.skipIf(!HAS_X)` / `describe.skipIf(!HAS_X)`；
- * fixture 用例保持无条件跑。
- *
- * 本文件无 .test.ts 后缀，vitest include 只收集 `src/__tests__/` 下以 .test.ts 结尾的文件，不收集本文件。
- */
-
-/** 真实 pi agent 目录（pi 官方家目录布局，随宿主 homedir 推导），用于集成测试。 */
-export const REAL_AGENT_DIR = join(homedir(), '.pi', 'agent')
-
-/**
- * 全量扫描类真实数据用例的统一超时标定（90s）。
- *
- * 这类用例遍历本机 ~/.pi/agent 全量会话语料（实测 4600+ 文件），空载单用例已需 6-10s；
- * 38 包并行全量测试时 CPU/IO 争抢可降速 3-4 倍，30s 标定必假红。90s ≈ 空载 9 倍余量，
- * 仍能兜住真正的挂死。仅用于遍历全量语料的用例（findSessions / buildFamilyFromFs /
- * resolveSessionRoots 等）；读已知单文件的用例不需要放宽。
- */
-export const REAL_DATA_TIMEOUT_MS = 90_000
-
-/** 5.4MB / 32 turn / 1204 entry 的真实 session（feat-plugin-arch-3 目录）。 */
-export const E6 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'
-/** 真实 fork 家族根（fork 子代 019fe632，隔代 subagent 019fe635 挂在 019fe632 下）。 */
-export const FAM = '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7'
-
-/**
- * E6 的完整文件路径（parser/turns/render 直接 parseSessionFile 用）。
- * 按 sid 运行时定位而非硬编码宿主 workspace 目录名：真实文件挂在哪个 slug 目录随采集机器而异，
- * 硬编码会绑死本机路径形态；定位不到时回落相对布局，由下方 HAS_REAL_SESSION 守卫 skip。
- */
-export const REAL_SESSION = (() => {
-  const fallback = join(REAL_AGENT_DIR, 'sessions', `2026-05-28T03-17-12-844Z_${E6}.jsonl`)
-  if (!existsSync(REAL_AGENT_DIR)) return fallback
-  try {
-    return (
-      execSync(
-        `find ${REAL_AGENT_DIR}/sessions -name '*${E6}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
-        { encoding: 'utf8' },
-      ).trim() || fallback
-    )
-  } catch {
-    return fallback
-  }
-})()
-
-/** 同步探测真实 session 文件是否存在（不存在则 skip，避免在无该数据的机器上硬失败）。 */
-export function hasRealSession(sid: string): boolean {
-  if (!existsSync(REAL_AGENT_DIR)) return false
-  try {
-    return (
-      execSync(
-        `find ${REAL_AGENT_DIR}/sessions -name '*${sid}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
-        { encoding: 'utf8' },
-      ).trim().length > 0
-    )
-  } catch {
-    return false
-  }
-}
-
-/**
- * 同步探测真实数据中任意 session 文件存在（main sessions/ 与 subagents/ 双目录）。
- * 与 hasRealSession 的区别：subagent session 文件位于 subagents/<cwd>/sessions/ 下，
- * hasRealSession 只扫主 sessions/ 目录扫不到。用于对活跃数据目录中具体文件（如 fork
- * 子代/隔代 subagent）存在性的守卫探测。
- */
-export function hasAnyRealSession(fragment: string): boolean {
-  if (!existsSync(REAL_AGENT_DIR)) return false
-  try {
-    return (
-      execSync(
-        `find ${REAL_AGENT_DIR}/sessions ${REAL_AGENT_DIR}/subagents -name '*${fragment}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
-        { encoding: 'utf8' },
-      ).trim().length > 0
-    )
-  } catch {
-    return false
-  }
-}
-
-export const HAS_REAL_AGENT_DIR = existsSync(REAL_AGENT_DIR)
-export const HAS_REAL_SUBAGENTS_DIR = existsSync(join(REAL_AGENT_DIR, 'subagents'))
-export const HAS_REAL_SESSION = existsSync(REAL_SESSION)
-export const HAS_E6 = hasRealSession(E6)
-export const HAS_FAM = hasRealSession(FAM)
-/** tool-handler 的 handleSessionRead 套件同时依赖 E6 + FAM。 */
-export const HAS_REAL = HAS_E6 && HAS_FAM