@zhushanwen/pi-session-reader 0.6.1 → 0.8.0

package/src/discovery/session-header.ts

@@ -1,44 +1,28 @@
-import { open, type FileHandle } from 'node:fs/promises'
-import { closeSync, openSync, readSync } from 'node:fs'
+import {
+  readFirstJsonlLine,
+  readFirstJsonlLineSync,
+  type SessionHeader,
+} from '@zhushanwen/session-core'
 
 /**
- * [ext-simplify-18 D5] session 文件首行 header 读取的包内单源（原 subagents.ts / find.ts
- * 两份 async 副本 + tool-handler.ts 一份 sync 副本合一）。不进 shared——跨包第二消费方
- * 不存在（runtime 侧首行读取是另一形态 + 分层禁反向 import，设计负面清单同口径）。
+ * [session-reader-shared-core Phase 1] session 文件首行 header 读取的包内单源（原
+ * subagents.ts / find.ts 两份 async 副本 + tool-handler.ts 一份 sync 副本合一后的单源）。
+ *
+ * 字节原语（buffer 管理/续读/CRLF/空文件）已收敛至基座 `readFirstJsonlLine`（sync/async
+ * 双形态）——本模块只剩两件 reader 私有事：
+ * ① **header 谓词薄包装**（G4 红线，设计 §5 Phase 0）：reader 仅要求 `type==='session'`
+ *    且 `id` 为 string，cwd/parentSession 可缺。runtime 侧「id+cwd 非空」严谓词是不同的
+ *    行为契约（缺 cwd 的 header 在 reader 候选集必须可见），谓词语义绝不统一进基座；
+ * ② **错误分流薄包装**：旧副本契约是「任何失败都视为无 header → undefined/null」，基座
+ *    原语 IO 错误上抛（错误分类留给有消费方的调用侧），reader 无错误分类消费方，catch-all
+ *    收敛回旧契约。
  */
 
-/** session header（首行 type==='session' entry 的消费子集）。 */
-export interface SessionHeader {
-  id: string
-  cwd?: string
-  parentSession?: string
-}
+export type { SessionHeader }
 
 /**
- * 首行读取 buffer 上限。header 超 8KB 的极端情况会截断致 parse 失败（parseSessionHeader
- * 返回 null）——session header（id/cwd/parentSession）实测 < 300 字节，8KB 约 27 倍余量。
+ * 解析 header 首行为 SessionHeader（谓词薄包装）。非 session 行/缺 id/坏 JSON → null。
  */
-export const HEADER_READ_BYTES = 8192
-
-/** 读文件首行（header）。定长 8KB 一次 read；空文件/读失败返回 undefined。 */
-export async function readSessionHeaderFirstLine(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(() => {})
-  }
-}
-
-/** 解析 header 首行为 SessionHeader。非 session 行/缺 id → null。 */
 export function parseSessionHeader(line: string | undefined): SessionHeader | null {
   if (!line) return null
   let raw: unknown
@@ -56,48 +40,25 @@ export function parseSessionHeader(line: string | undefined): SessionHeader | nu
   return h
 }
 
-/** readSessionHeaderIdSync 读首行的 buffer 上限。session header 实测 < 300 字节，4KB 足够。 */
-const SYNC_HEADER_READ_BYTES = 4096
+/** 读文件首行（header）薄包装：基座原语 + IO 失败收敛 undefined（空文件基座已返 undefined）。 */
+export async function readSessionHeaderFirstLine(path: string): Promise<string | undefined> {
+  try {
+    return await readFirstJsonlLine(path)
+  } catch {
+    return undefined
+  }
+}
 
 /**
  * 同步读 session 文件首行 header，返回 type==='session' 的 id。
- *
- * 任何异常（文件不存在/空文件/解析失败/type 不符）返回 undefined。与 async 版
- * readSessionHeaderFirstLine/parseSessionHeader 同构（定长 buffer 读首行 + JSON.parse +
- * type 校验），但用同步 fs API（resolveSessionId 内仅调用 1 次，同步开销可接受），
- * 窗口取 4KB（仅取 id）——sync 形态与窗口差异是刻意的调用上下文适配，独立常量、
- * 不与 async 版 8KB 强行统一。
+ * 任何失败（文件不存在/空文件/解析失败/type 不符）→ undefined（旧 sync 副本契约不变）。
  */
 export function readSessionHeaderIdSync(filePath: string): string | undefined {
-  let fd: number | undefined
+  let line: string | undefined
   try {
-    fd = openSync(filePath, 'r')
-    const buf = Buffer.alloc(SYNC_HEADER_READ_BYTES)
-    const bytesRead = readSync(fd, buf, 0, SYNC_HEADER_READ_BYTES, 0)
-    if (bytesRead === 0) return undefined
-    const text = buf.subarray(0, bytesRead).toString('utf8')
-    const nl = text.indexOf('\n')
-    const line = nl === -1 ? text : text.slice(0, nl)
-    let raw: unknown
-    try {
-      raw = JSON.parse(line)
-    } catch {
-      return undefined
-    }
-    if (typeof raw !== 'object' || raw === null) return undefined
-    const o = raw as Record<string, unknown>
-    if (o.type !== 'session' || typeof o.id !== 'string') return undefined
-    return o.id
+    line = readFirstJsonlLineSync(filePath)
   } catch {
     return undefined
-  } finally {
-    if (fd !== undefined) {
-      try {
-        closeSync(fd)
-      } catch {
-        // closeSync 失败：fd 可能已无效，header 数据已读取，关闭失败不影响结果（best-effort）
-        void fd
-      }
-    }
   }
+  return parseSessionHeader(line)?.id
 }

package/src/discovery/subagents.ts

@@ -1,9 +1,10 @@
 import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import { join, basename } from 'node:path'
-import type { Entry } from '../core/parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 import type { Family, SessionRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
+import { listZcodeManifests } from './zcode-manifest.js'
 import { resolveSessionRoots, type SessionFileMeta } from './roots.js'
 import { parseSessionHeader, readSessionHeaderFirstLine } from './session-header.js'
 import { resolveWorkflows } from './workflows.js'
@@ -54,7 +55,13 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
   if (!scan.sessionIdToPath.has(sessionId)) {
     throw new Error(await formatSessionNotFound(sessionId, agentDir))
   }
-  const index = buildFamilyIndex(scan.headers, scan.identities, scan.fileStats)
+  // U9 family 接线（design session-reader-shared-core §5 Phase 3 单元三）：zcode 节点
+  // 并入 subagentsByRoot（D5-1 判据在 core 层 buildZcodeSubagentsByRoot）——**纯追加**，
+  // pi 现路径（listRecordManifests/isRecordManifest/appendOrphanIdentities）零改动；
+  // zcode manifest 无 sessionFile 键本就被 isRecordManifest 整条丢弃（F21），与 pi 扫描
+  // 结果集天然不相交，两条来源互不污染。枚举失败容错内置（根不存在 → 空数组不报错）。
+  const zcodeNodes = await listZcodeManifests(agentDir)
+  const index = buildFamilyIndex(scan.headers, scan.identities, scan.fileStats, zcodeNodes)
   const family = resolveFamily(sessionId, index)
 
   // ---- 6. workflows（enrichRefs 回填已删除，ext-simplify-04 U4/E2：fileName/cwd 占位

package/src/discovery/whitelist.ts

@@ -0,0 +1,87 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { zcodeImportDbAllowlist } from '@zhushanwen/zcode-session-source'
+
+/**
+ * zcode 会话库白名单闸（design session-reader-shared-core §3.1 第③步 / §3.3 D5 /
+ * §3.4 检查顺序 / 探针 P-whitelist）。
+ *
+ * dbPath 来自 session 数据（manifest engineHandle.sessionRef / 主 session custom
+ * entry），是**不可信输入**（会话文件可被构造）——开库前必须过本闸，白名单是必需
+ * 闸而非可选优化。集合与 runtime 导入侧 `zcodeImportDbAllowlist(dataDir)` **同源
+ * 同形**：隔离库（现役）+ 宿主库（存量兼容）两项，路径段单源 = 该函数内部引用的
+ * `@zhushanwen/subagent-engine-sdk` zcode-db-paths 常量（跨侧契约根，禁手拼字面量
+ * 段——SDK 头注「两侧必须同源推导，禁止各自拼字符串漂移」）。
+ *
+ * **检查顺序铁律（§3.4 三段递进，实现与测试双锚定）**：存在性先于路径——
+ * `existsSync` 为 false 报 `zcode_db_unreadable`（库文件不存在）而非
+ * `zcode_db_path_forbidden`，避免把「只是还没落库」误报成安全事件（forbidden 是
+ * 安全面错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
+ * 开库（第 3 段）由调用方在本闸通过后进行。
+ *
+ * **TOCTOU 残留（设计 §3.4 显式登记，不在本梯队硬化）**：realpath 之后仍按原
+ * dbPath 开库，两步间存在理论竞态窗口；利用它需攻击者具备同用户写权限，而同用户
+ * 权限下本就可直接读该库——实测方向安全，fd 复用/O_NOFOLLOW 属纵深防御非实际威胁面。
+ *
+ * **realpath 对齐**：dbPath 与集合项都经 realpath 归一后再比对（realpath 失败——
+ * 竞态删除/权限——按原串参与）。taiji 生产布局（`~/.taiji` 下无 symlink）两者等价；
+ * macOS 临时目录（`/var` → `/private/var`）等 symlink 环境下不对齐会把合法库误判
+ * 集合外，P-whitelist 单测按 tmp dataDir 布局锚定此语义。
+ */
+
+/** symlink 归一（失败按原串——不存在的路径进不了比对成功分支，由调用方顺序保证）。 */
+function realOf(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+/**
+ * dbPath 的派生允许集合（realpath 对齐后）：`zcodeIsolatedDbPath(dirname(agentDir))`
+ * + `hostZcodeDbPath()`。F11：taiji 下 agentDir = `<dataDir>/agent` →
+ * dirname(agentDir) = dataDir，与引擎侧/导入侧的隔离库推导同一 dataDir。纯 pi 宿主
+ * （agentDir 退化为 `~/.pi/...`）下隔离库项恒不可达且不存在 taiji 派生的 zcode 锚
+ * （D5「纯 pi 宿主边界」），无害，不需特例分支。
+ */
+export function zcodeDbAllowlistFor(agentDir: string): readonly string[] {
+  return zcodeImportDbAllowlist(dirname(agentDir)).map(realOf)
+}
+
+/** `zcode_db_unreadable` 的 👉 恢复指引（§3.4 表逐行；隔离库路径运行时动态推导）。 */
+export function formatZcodeDbUnreadable(dataDir: string, detail: string): string {
+  const isolated = zcodeImportDbAllowlist(dataDir)[0]
+  return (
+    `[zcode_db_unreadable] zcode 会话库不可读（恢复阶梯 L1-L3 均未成功）。${detail}\n` +
+    `👉 使原目录可写，或把库连 -wal/-shm 一起拷回白名单内原路径（隔离库 = ${isolated}）后重试。\n` +
+    `⚠️ 告诫：缺 -wal 的库未 checkpoint 的已提交数据可能已丢——这是写者未干净退出造成的既成事实，非恢复引入；完整性以连 -wal 一起拷贝为准。`
+  )
+}
+
+/** `zcode_db_path_forbidden` 的 👉 恢复指引（§3.4 表逐行）。 */
+export function formatZcodeDbPathForbidden(dbPath: string): string {
+  return (
+    `[zcode_db_path_forbidden] 该会话引用的 zcode 库路径不在允许范围：${dbPath}\n` +
+    `👉 在 taiji 内打开原会话读取，或用会话导入对话框导入后读取。`
+  )
+}
+
+/**
+ * 白名单闸（第 1 段存在性 → 第 2 段路径；通过才允许开库）。
+ *
+ * @throws Error（消费侧映射为 zcode_db_unreadable / zcode_db_path_forbidden，
+ *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误面）
+ */
+export function assertZcodeDbPathAllowed(dbPath: string, agentDir: string): void {
+  // 第 1 段 存在性（先于路径——「还没落库」不是安全事件）
+  if (!existsSync(dbPath)) {
+    throw new Error(formatZcodeDbUnreadable(dirname(agentDir), `（库文件不存在：${dbPath}）`))
+  }
+  // 第 2 段 路径（存在才 realpath 比对；TOCTOU 残留见文件头注）
+  const allowed = zcodeDbAllowlistFor(agentDir)
+  if (!allowed.includes(realOf(dbPath))) {
+    throw new Error(formatZcodeDbPathForbidden(dbPath))
+  }
+}

package/src/discovery/workflows.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { basename } from 'node:path'
-import { parseSessionContent } from '../core/parser.js'
+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)),
     })
   }