@zhushanwen/pi-session-reader 0.6.0 → 0.7.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 } from '@zhushanwen/session-core'
 import type { SessionRef, WorkflowRef } from '../core/family.js'
 import { extractSessionIdFromFilename } from './subagents.js'
 

package/src/discovery/zcode-manifest.ts

@@ -0,0 +1,277 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ZcodeAnchor } from './entry-anchor.js'
+import type { ZcodeFamilyNode } from '../core/family.js'
+
+/**
+ * zcode manifest 直读与枚举（design session-reader-shared-core §3.1 第①步 / D5 / D5-1）。
+ *
+ * 背景（F21）：pi 路径的 `isRecordManifest` 三必填含 `sessionFile`，而 zcode manifest
+ * 落盘时该键被 JSON.stringify 丢弃（subagent-core record-store-rebuild.ts:665/725 投影
+ * 照写 `sessionFile: undefined`）→ `listRecordManifests` 对 zcode manifest 恒返回 []。
+ * 本单元另开一条**不经过该守卫**的独立路径：
+ * - **定点直读**（`readZcodeManifest`）：manifest 文件名由 sa-id 完全确定（写侧
+ *   `path.join(recordsDir, \`${record.id}.json\`)`，manifest-store.ts:141/153），按确定性
+ *   文件名 `<sa-id>.json` 在 `<agentDir>/subagents/<cwd>/records/` 下**窄 walk（命中即止，
+ *   不读不解析任何其他 manifest）**→ JSON.parse → `engine === 'zcode'` ∧
+ *   `engineHandle.sessionRef` 双键（sessionId/dbPath 均非空 string）→ 取锚。
+ * - **全量枚举**（`listZcodeManifests`，family 用）：扫同布局下全部 .json，逐条
+ *   parse + 谓词过滤，只返回 zcode 形态（pi manifest / 坏 JSON 跳过）。
+ *
+ * **对 pi 行为零影响（本方案的定义性质）**：`isRecordManifest` / `RecordManifest` /
+ * `listRecordManifests`（subagents.ts）一行不改——pi manifest 仍走原扫描路径，本单元
+ * 的谓词**不走** isRecordManifest。判别规则与 runtime `transcriptAnchorOf` 同构
+ * （F8：`engine === 'zcode'` 第一判据 + sessionRef 双键齐）。用 `engine` 判别而非
+ * 「engineHandle 存在性」的理由见 D5 被否项 ②（pi record 提升后 engineHandle 仍持久化，
+ * 存在性判别会误路由）。
+ */
+
+/**
+ * zcode manifest 的读取记录（枚举产出，family 消费）。
+ *
+ * 富字段（slug/task/model/status/agentName）从 manifest 顶层透传（旧 manifest 缺省
+ * → undefined）；slug 的 `m.slug ?? m.agentName ?? ''` 兜底在枚举组装时完成（与 pi
+ * 孤儿链 appendOrphanIdentities 同款，core 层直接透传）。
+ */
+export interface ZcodeManifestRecord extends ZcodeFamilyNode {
+  /** 写侧盖章的引擎 id（枚举谓词保证 === 'zcode'） */
+  engine: string
+}
+
+/**
+ * anchor-missing 的缺失键归因（§3.4：缺失键名进结构化日志——engineHandle 整体缺席 /
+ * 缺 sessionRef / 缺 sessionId / 缺 dbPath 归因不同：整体缺席多为旧版本产物，缺
+ * sessionId 多为引擎未回调 onHandleReady，缺 dbPath 多为写入面截断）。entry 兜底侧
+ * 的同构分类（tool-handler classifyIncompleteEntryAnchor）复用本类型单源。
+ */
+export type ZcodeAnchorMissingReason =
+  | 'missing-engineHandle'
+  | 'missing-sessionRef'
+  | 'missing-sessionId'
+  | 'missing-dbPath'
+
+/**
+ * 定点直读的结果三态（discriminated result——错误码映射归路由单元 U9，本单元只给
+ * 归因信号，§3.4 检查顺序第 0 段「定位链」）：
+ * - `zcode`：engine==='zcode' ∧ sessionRef 双键齐 → 携带锚，继续 zcode 链（白名单闸 → 开库）；
+ * - `not-zcode`：文件不存在 / 坏 JSON / `engine` 缺省或 `'pi'`（或非 string id）——
+ *   该 sa-id 不是「zcode 单子」，交回调用方走今天的 pi 现路径（sessionFile + JSONL）；
+ * - `anchor-missing`：engine==='zcode' 但 `engineHandle` 整体缺席或 `sessionRef` 缺键
+ *   ——路由映射 `zcode_anchor_missing`（§3.4；缺失键名以 `reason` 逐键归因，由结构化
+ *   日志承载）。
+ */
+export type ZcodeManifestLookup =
+  | { kind: 'zcode'; anchor: ZcodeAnchor }
+  | { kind: 'not-zcode' }
+  | { kind: 'anchor-missing'; reason: ZcodeAnchorMissingReason }
+
+/** manifest 顶层 JSON 的读取视图（守卫输入） */
+type ManifestJson = Record<string, unknown>
+
+function asObject(v: unknown): ManifestJson | undefined {
+  if (typeof v !== 'object' || v === null) return undefined
+  return v as ManifestJson
+}
+
+/** 第一判据：`engine === 'zcode'`（缺省 / 'pi' / 其他引擎均非 zcode 形态） */
+function isZcodeEngine(m: ManifestJson): boolean {
+  return m.engine === 'zcode'
+}
+
+/**
+ * 第二判据：`engineHandle.sessionRef` 双键（sessionId/dbPath）均为非空 string → 锚。
+ * （F8 判据的锚字段部分；pi record 的 sessionRef 无 dbPath → 天然不齐。）
+ */
+function zcodeAnchorOf(m: ManifestJson): ZcodeAnchor | undefined {
+  const handle = asObject(m.engineHandle)
+  if (!handle) return undefined
+  const ref = asObject(handle.sessionRef)
+  if (!ref) return undefined
+  const { sessionId, dbPath } = ref
+  if (typeof sessionId !== 'string' || sessionId === '') return undefined
+  if (typeof dbPath !== 'string' || dbPath === '') return undefined
+  return { sessionId, dbPath }
+}
+
+/**
+ * anchor-missing 的逐键归因（判定顺序与 zcodeAnchorOf 的键序一致——同一键序下
+ * 「首个不满足的键」即归因，两函数对同一 manifest 的 zcode/anchor-missing 判定互洽）。
+ */
+function zcodeAnchorMissingReason(m: ManifestJson): ZcodeAnchorMissingReason {
+  const handle = asObject(m.engineHandle)
+  if (!handle) return 'missing-engineHandle'
+  const ref = asObject(handle.sessionRef)
+  if (!ref) return 'missing-sessionRef'
+  if (typeof ref.sessionId !== 'string' || ref.sessionId === '') return 'missing-sessionId'
+  return 'missing-dbPath'
+}
+
+/** manifest 顶层富字段（旧 manifest 缺省 → undefined，不伪造） */
+interface ManifestRichFields {
+  agentName?: string
+  task?: string
+  model?: string
+  status?: string
+}
+
+function richFieldsOf(m: ManifestJson): ManifestRichFields {
+  const out: ManifestRichFields = {}
+  if (typeof m.agentName === 'string') out.agentName = m.agentName
+  if (typeof m.task === 'string') out.task = m.task
+  if (typeof m.model === 'string') out.model = m.model
+  if (typeof m.status === 'string') out.status = m.status
+  return out
+}
+
+/** stat 存在性（任意路径无安全面——D5-1 只查「文件在不在」，不开库） */
+function fileExists(p: string): boolean {
+  try {
+    statSync(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * manifest JSON → zcode 记录（枚举产出形状）。非 zcode 形态 → undefined。
+ * slug 兜底 m.slug ?? m.agentName ?? ''（与 pi 孤儿链同款）。
+ */
+function toZcodeManifestRecord(m: ManifestJson): ZcodeManifestRecord | undefined {
+  if (!isZcodeEngine(m)) return undefined
+  const anchor = zcodeAnchorOf(m)
+  if (!anchor) return undefined
+  if (typeof m.id !== 'string' || m.id === '') return undefined
+  if (typeof m.rootSessionId !== 'string' || m.rootSessionId === '') return undefined
+  const rich = richFieldsOf(m)
+  const slug = typeof m.slug === 'string' ? m.slug : (rich.agentName ?? '')
+  return {
+    id: m.id,
+    rootSessionId: m.rootSessionId,
+    slug,
+    agentName: rich.agentName,
+    task: rich.task,
+    model: rich.model,
+    status: rich.status,
+    dbPath: anchor.dbPath,
+    dbFileExists: fileExists(anchor.dbPath),
+    engine: 'zcode',
+  }
+}
+
+/** `<agentDir>/subagents` 布局常量（与写侧 path-encoding/manifest-store 布局对齐） */
+const SUBAGENTS_DIR = 'subagents'
+const RECORDS_DIR = 'records'
+
+/**
+ * 逐条解析一个 manifest 文件为三态结果（直读用）。
+ * 坏 JSON / 非 string id → not-zcode（残缺 manifest 交回 pi 现路径——与今天的
+ * tryReadManifest 丢弃行为等价，只是换了显式信号）。
+ */
+function parseManifestLookup(raw: string): ZcodeManifestLookup {
+  let v: unknown
+  try {
+    v = JSON.parse(raw)
+  } catch {
+    return { kind: 'not-zcode' } // 坏 JSON
+  }
+  const m = asObject(v)
+  if (!m || !isZcodeEngine(m)) return { kind: 'not-zcode' } // engine 缺省 / 'pi' / 其他
+  const anchor = zcodeAnchorOf(m)
+  if (!anchor) return { kind: 'anchor-missing', reason: zcodeAnchorMissingReason(m) } // 逐键归因
+  return { kind: 'zcode', anchor }
+}
+
+/**
+ * 定点直读（§3.1 第①步主路径）：按确定性文件名 `<sa-id>.json` 在
+ * `<agentDir>/subagents/<cwd>/records/` 下窄 walk，**命中即止——不读不解析任何其他
+ * manifest**（对比 listRecordManifests 的全量 walk + 逐条 parse）。
+ *
+ * 无会话边界（§3.1）：manifest 文件名由 sa-id 确定性推出，任何会话中都可直读。
+ * 根目录不可读 / 无候选目录 → not-zcode（调用方交回 pi 现路径，与今天行为一致）。
+ */
+export async function readZcodeManifest(
+  agentDir: string,
+  saId: string,
+): Promise<ZcodeManifestLookup> {
+  const root = join(agentDir, SUBAGENTS_DIR)
+  let slugs: DirentLike[]
+  try {
+    slugs = await readdir(root, { withFileTypes: true })
+  } catch {
+    return { kind: 'not-zcode' } // subagents 根不存在/不可读 → 无 manifest
+  }
+  for (const e of slugs) {
+    if (!e.isDirectory()) continue
+    const file = join(root, e.name, RECORDS_DIR, `${saId}.json`)
+    let raw: string
+    try {
+      // 命中即止：只读这一个文件（文件名由 sa-id 确定），坏内容同样终止（见 parseManifestLookup）
+      raw = await readFile(file, 'utf8')
+    } catch {
+      continue // 该 cwd 目录下无此 manifest → 下一候选目录
+    }
+    return parseManifestLookup(raw)
+  }
+  return { kind: 'not-zcode' }
+}
+
+/** readdir(withFileTypes) 条目的最小结构视图（便于类型标注） */
+interface DirentLike {
+  isDirectory(): boolean
+  isFile(): boolean
+  name: string
+}
+
+/**
+ * zcode manifest 全量枚举（family 用，D5-1 的节点列表来源）：扫
+ * `<agentDir>/subagents/<cwd>/records/` 全部 .json，逐条 JSON.parse + 谓词过滤
+ * （engine==='zcode' ∧ sessionRef 双键齐 ∧ id/rootSessionId 非空 string），
+ * 只返回 zcode 形态——**pi manifest 与坏 JSON 直接跳过，不走 isRecordManifest
+ * （那条链零改动）**。每个返回记录已携带 dbFileExists（statSync 预计算）。
+ *
+ * 单条 manifest 不可达（坏 JSON / 残缺 / stat 失败）不中断枚举、不抛异常——
+ * family 是列表视图，单节点不可达不炸整屏（D5-1 GC 语义）。
+ */
+export async function listZcodeManifests(agentDir: string): Promise<ZcodeManifestRecord[]> {
+  const root = join(agentDir, SUBAGENTS_DIR)
+  const out: ZcodeManifestRecord[] = []
+  let slugs: DirentLike[]
+  try {
+    slugs = await readdir(root, { withFileTypes: true })
+  } catch {
+    return out // 根不存在/不可读 → 空（无 zcode 节点，不报错）
+  }
+  for (const slug of slugs) {
+    if (!slug.isDirectory()) continue
+    const recordsDir = join(root, slug.name, RECORDS_DIR)
+    let files: DirentLike[]
+    try {
+      files = await readdir(recordsDir, { withFileTypes: true })
+    } catch {
+      continue // 该 cwd 目录无 records/ → 跳过
+    }
+    for (const f of files) {
+      if (!f.isFile() || !f.name.endsWith('.json')) continue
+      let raw: string
+      try {
+        raw = await readFile(join(recordsDir, f.name), 'utf8')
+      } catch {
+        continue // 单文件读失败 → 跳过
+      }
+      let v: unknown
+      try {
+        v = JSON.parse(raw)
+      } catch {
+        continue // 坏 JSON → 跳过
+      }
+      const m = asObject(v)
+      if (!m) continue
+      const rec = toZcodeManifestRecord(m)
+      if (rec) out.push(rec)
+    }
+  }
+  return out
+}

package/src/doctor.ts

@@ -2,13 +2,10 @@
  * doctor action（u8：design 2026-09-10 §6.2/§6.3/§6.4/§7B 要点 2/4/5/8 + §6.11 U14b 段）。
  *
  * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）：环境判定 + 根表渲染 +
- * 旧布局残留 glob 探测。SessionReadSignals（u3 信号包超集）在域内定义，tool-handler
+ * SessionReadSignals（u3 信号包超集）在域内定义，tool-handler
  * re-export 供 index.ts 生产消费。原 u8 的扫描缓存机已删除（ext-simplify-04 U3）：
  * 每次调用实扫，无缓存命中语义；TTL/mtime 判定随 metadata 缓存留在 tool-handler 侧。
  */
-import { existsSync } from 'node:fs'
-import { readdir } from 'node:fs/promises'
-import { join, dirname } from 'node:path'
 import { detectEnvironment, type DetectedEnvironment } from './discovery/env.js'
 import { resolveSessionRoots, type SessionRoot, type SessionRootSignals } from './discovery/roots.js'
 import type { SessionReadParams, ToolResult } from './tool-handler.js'
@@ -29,52 +26,8 @@ export interface SessionReadSignals extends SessionRootSignals {
 /** doctor 根表来源标签列宽（最长 `[subagent]` 10 字符 + 1 对齐间距，§5.1 表格形态）。 */
 const DOCTOR_ROOT_LABEL_PAD = 11
 
-/** 旧布局残留条目（§6.11 U14b doctor 侧独立 glob 探测）。 */
-/** 旧布局残留探测单条命中（doctor 与 u14b 启动探测同源判据，§6.11）。 */
-export interface PiLayoutLeftover {
-  path: string
-  kind: 'backup' | 'unmigrated'
-}
-
 /**
- * 旧布局残留独立 glob 探测（§6.11 v9.1）。基点 = dirname(agentDir)（xyz-agent 下 =
- * `<dataDir>`，纯 pi 下 = `~/.pi`）；`pi/`（未迁移）与 `pi.backup-v2-` 前缀目录（迁移备份）
- * 都不在任何候选根推导式内（[legacy] 够不到带时间戳的备份名与 pi/ 层），故须独立探测。
- *
- * 形态判据（与 u14b 启动探测 / u14a 脚本 0a 同源）：目录下含 `agent/` 或 `sessions/`
- * 子目录才算残留——防纯 pi 宿主下任意来源的 `~/.pi/pi/` 目录误报。读探测，每次现查
- * 不入缓存（两次 readdir 成本可忽略，缓存只服务扫盘贵的根）。
- *
- * 迁移期支持（A4 登记）：本探测服务于 v2 布局迁移窗口，全量迁移确认后可整段删除。
- */
-async function detectPiLayoutLeftovers(
-  agentDir: string,
-): Promise<{ base: string; hits: PiLayoutLeftover[] }> {
-  const base = dirname(agentDir)
-  if (agentDir.length === 0) return { base, hits: [] }
-  let names: string[]
-  try {
-    names = (await readdir(base, { withFileTypes: true }))
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name)
-  } catch {
-    return { base, hits: [] }
-  }
-  const hits: PiLayoutLeftover[] = []
-  for (const name of names) {
-    const isUnmigrated = name === 'pi'
-    const isBackup = name.startsWith('pi.backup-v2-')
-    if (!isUnmigrated && !isBackup) continue
-    const dir = join(base, name)
-    // 形态判据：含 agent/ 或 sessions/ 子目录（迁移备份必含其一——备份即原 pi/ 改名）
-    if (!existsSync(join(dir, 'agent')) && !existsSync(join(dir, 'sessions'))) continue
-    hits.push({ path: dir, kind: isBackup ? 'backup' : 'unmigrated' })
-  }
-  return { base, hits }
-}
-
-/**
- * doctor：环境判定 + 根表 + 事实型诊断 + legacy 非空告警 + 旧布局残留探测。
+ * doctor：环境判定 + 根表 + 事实型诊断 + legacy 非空告警。
  *
  * 诊断结论只陈述事实（「最高优先级 main 根 N 文件」），禁止「真的没有 session」类
  * 归因断言（§7B 要点 5 / §3.3 教训）；env/bundleUrl 信号缺失时环境判定按降级输出，
@@ -94,8 +47,7 @@ export async function doDoctor(
     // 才扫。无缓存——每次实扫（原缓存机已删，ext-simplify-04 U3，§7B 要点 8 新态）。
     subagents: params.includeSubagents === true ? 'scan' : 'stat',
   })
-  const leftovers = await detectPiLayoutLeftovers(signals.agentDir)
-  return renderDoctor(roots, environment, leftovers)
+  return renderDoctor(roots, environment)
 }
 
 /**
@@ -105,24 +57,21 @@ export async function doDoctor(
 export interface DoctorDetails {
   environment: DetectedEnvironment
   roots: SessionRoot[]
-  leftovers: PiLayoutLeftover[]
-  globBase: string
 }
 
 /**
  * 渲染 doctor 输出（§5.1 形态）：环境判定 + evidence + 会话根表（来源标签/路径/存在/
- * 文件数/扫描耗时/去重注记）+ 事实型诊断 + legacy 非空告警 + 旧布局残留（命中才出现）。
+ * 文件数/扫描耗时/去重注记）+ 事实型诊断 + legacy 非空告警。
  */
 function renderDoctor(
   roots: SessionRoot[],
   environment: DetectedEnvironment,
-  leftovers: { base: string; hits: PiLayoutLeftover[] },
 ): ToolResult {
   const lines: string[] = []
 
   // 环境判定行 + evidence（§6.2：判定可被证据推翻，非黑盒断言；evidence 恒非空）
   lines.push(
-    `环境判定：${environment.kind === 'xyz-agent' ? 'xyz-agent（托管）' : 'standalone-pi'}` +
+    `环境判定：${environment.kind === 'taiji' ? 'taiji（托管）' : 'standalone-pi'}` +
       ` · 发行形态：${environment.distribution ?? '未知（不猜）'}`,
   )
   if (environment.dataDir !== undefined) lines.push(`数据目录：${environment.dataDir}`)
@@ -172,25 +121,11 @@ function renderDoctor(
     )
   }
 
-  // 旧布局残留（§6.11：命中才列，附同一迁移指引）
-  if (leftovers.hits.length > 0) {
-    lines.push('')
-    lines.push(`旧布局残留探测（基点 ${leftovers.base}）：`)
-    for (const h of leftovers.hits) {
-      lines.push(
-        `  - ${h.path}（${h.kind === 'backup' ? '迁移备份 pi.backup-v2-*' : '未迁移旧布局 pi/'}）`,
-      )
-    }
-    lines.push('  👉 关闭应用后运行 scripts/migrate-pi-layout-v2.mjs 完成迁移。')
-  }
-
   return {
     content: [{ type: 'text', text: lines.join('\n') }],
     details: {
       environment,
       roots,
-      leftovers: leftovers.hits,
-      globBase: leftovers.base,
     } satisfies DoctorDetails,
   }
 }