@zhushanwen/pi-session-reader 0.6.1 → 0.7.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/discovery/entry-anchor.ts

@@ -0,0 +1,108 @@
+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'
+
+/**
+ * 从单条 entry 提取 zcode 锚。形状校验窄而严，任一不满足 = 该条不算命中（返回
+ * undefined，调用方继续扫——缺键条目不遮蔽更早的完整条目）：
+ * - `type === 'custom'` ∧ `customType === 'subagent-record'`
+ * - `data.v === 1`（schema 版本守卫，不认识的版本跳过而非猜测——写侧 record-entry.ts v 注释同口径）
+ * - `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.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 (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）。
+ *
+ * 多候选文件：按候选列表顺序逐文件扫，文件内有命中锚（含末条裁决后）即止——
+ * 候选顺序 = 调用方声明的优先级（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/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 } from '@zhushanwen/session-core'
 import type { SessionRef, WorkflowRef } from '../core/family.js'
 import { extractSessionIdFromFilename } from './subagents.js'