@zhushanwen/pi-session-reader 0.11.0 → 0.13.0

package/src/discovery/archive-match.ts

@@ -0,0 +1,84 @@
+/**
+ * [session-archive D7] 归档片段匹配编排 + 归档态 ToolResult 构造。
+ *
+ * 独立模块的原因（不并入 archive-ledger.ts）：匹配复用 find.ts 的
+ * normalizeUuidKey（uuid 归一化口径单一源，§6.7 子决策 1），而 archive-ledger
+ * 被 roots.ts 单向消费——并入会构成 archive-ledger→find→roots→archive-ledger
+ * 的值级循环 import。本模块依赖方向：find（纯函数）+ archive-ledger（扫描/
+ * 渲染）+ tool-handler（仅 type import，同 tool-format 先例），无环。
+ *
+ * 消费方：tool-handler 的 resolveByFragment（归档回退层）与 result-action
+ * （archivedResult）、tool-format 的 resolveNonOkResult（multi 消歧与归档态的
+ * 统一 non-ok 分发）。
+ */
+import { normalizeUuidKey } from './find.js'
+import {
+  formatArchivedDisambiguation,
+  formatArchivedText,
+  resolveArchiveDir,
+  scanArchiveLedgers,
+  type ArchiveLedgerEntry,
+} from './archive-ledger.js'
+import type { ToolResult } from '../tool-handler.js'
+
+/** 归档命中的两支形态（ResolveResult 对应支的结构子集）。 */
+export type ArchiveResolve =
+  | { kind: 'archived'; archive: ArchiveLedgerEntry }
+  | { kind: 'archived-multi'; query: string; entries: ArchiveLedgerEntry[] }
+
+/**
+ * 归档簿记片段匹配：sessionId（等值/子串/归一化，复用 find 的 normalizeUuidKey
+ * 两级口径）+ 簿记 name（名称片段的免解压数据源，D3）。归档根不存在/无簿记 →
+ * 空数组（无匹配路径零变化）。
+ */
+export async function matchArchiveLedgers(
+  query: string,
+  agentDir: string,
+): Promise<ArchiveLedgerEntry[]> {
+  const archiveRoot = resolveArchiveDir(agentDir)
+  const entries = await scanArchiveLedgers(archiveRoot)
+  const nq = normalizeUuidKey(query)
+  return entries.filter((e) => {
+    if (e.sessionId === query) return true
+    if (e.sessionId.includes(query)) return true
+    if (nq.length > 0 && normalizeUuidKey(e.sessionId).includes(nq)) return true
+    return e.name !== undefined && e.name.includes(query)
+  })
+}
+
+/**
+ * 归档回退层的解析入口（resolveByFragment 在场零命中后调用）：单命中 →
+ * archived；多命中 → archived-multi（消歧）；无簿记命中 → undefined（落 F1）。
+ */
+export async function resolveArchiveFragment(
+  query: string,
+  agentDir: string,
+): Promise<ArchiveResolve | undefined> {
+  const hits = await matchArchiveLedgers(query, agentDir)
+  if (hits.length === 1) {
+    return { kind: 'archived', archive: hits[0]! }
+  }
+  if (hits.length > 1) {
+    return { kind: 'archived-multi', query, entries: hits }
+  }
+  return undefined
+}
+
+/**
+ * 归档命中的统一 ToolResult（单条 + 多命中消歧）：正文 = archive-ledger 两态
+ * 渲染（头部标注 + 摘要 turns + 尾注 / staging 占位），不读压缩体（D7）。details
+ * 顶层 `archived: true` 供程序化消费方一眼区分归档态与常规结果。
+ */
+export function archivedResult(resolved: ArchiveResolve): ToolResult {
+  return resolved.kind === 'archived'
+    ? {
+        content: [{ type: 'text', text: formatArchivedText(resolved.archive) }],
+        details: { archived: true, entry: resolved.archive },
+      }
+    : {
+        content: [
+          { type: 'text', text: formatArchivedDisambiguation(resolved.query, resolved.entries) },
+        ],
+        details: { archived: true, candidates: resolved.entries },
+      }
+}

package/src/discovery/entry-anchor.ts

@@ -29,16 +29,16 @@ export interface ZcodeAnchor {
  * `subagent-record` custom entry 的 customType 值。
  *
  * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core record-entry.ts 的
- * SUBAGENT_RECORD_CUSTOM_TYPE。reader 生产依赖面不引 subagent-core（该包是
+ * SUBAGENT_RECORD_CUSTOM_TYPE。reader 生产依赖范围不引 subagent-core（该包是
  * devDependency + vitest alias 形态），故按协议字符串本地持有；两侧漂移由
- * entry-anchor.test.ts 的跨包断言守卫。
+ * entry-anchor.test.ts 的跨包断言检查。
  */
 const SUBAGENT_RECORD_CUSTOM_TYPE = 'subagent-record'
 
 /**
  * v2 条目 data 的认识版本词表（W1 起 = 2）。与写侧 subagent-core
- * SUBAGENT_RECORD_ENTRY_VERSION 同值、同「本地持有 + 测试守卫漂移」模式——写侧
- * 再升 v3 时本守卫先红，提醒评估新版本的锚读取面。
+ * SUBAGENT_RECORD_ENTRY_VERSION 同值、同「本地持有 + 测试检查漂移」模式——写侧
+ * 再升 v3 时本检查先红，提醒评估新版本的锚读取范围。
  */
 const SUBAGENT_RECORD_ENTRY_V2 = 2
 
@@ -46,7 +46,7 @@ const SUBAGENT_RECORD_ENTRY_V2 = 2
  * 从单条 entry 提取 zcode 锚。形状校验窄而严，任一不满足 = 该条不算命中（返回
  * undefined，调用方继续扫——缺键条目不遮蔽更早的完整条目）：
  * - `type === 'custom'` ∧ `customType === 'subagent-record'`
- * - 版本/判别键（schema 版本守卫，不认识的版本跳过而非猜测——写侧
+ * - 版本/判别键（schema 版本检查，不认识的版本跳过而非猜测——写侧
  *   record-entry.ts classifySubagentRecordEntryData v2-only 同口径）：
  *   `data.v === 2` ∧ `data.kind === 'settled'`（W1 注册/终态两条小条目——
  *   **锚只取自终态条**：registered 条目不携带 engineHandle，且设计 D1 裁决

package/src/discovery/find.ts

@@ -354,6 +354,9 @@ async function loadTitleIndex(ctx: MetadataContext): Promise<Map<string, Session
     if (root.dedupedInto !== undefined) continue
     if (!root.exists) continue // guard：仅对存在的根调用
     if (!isFlatRoot(root)) continue // 策略 ②：含子目录根跳过 listAll
+    // [session-archive D7] 归档根不是标题数据源（listAll 只看一层 .jsonl，归档根
+    // 第一层是 encodeCwd 目录恒空手而归）——跳过多余调用
+    if (root.kind === 'archive') continue
     push(root.path)
   }
 
@@ -433,6 +436,14 @@ async function matchCandidates(
   }
   // 第一级 uuid 片段匹配（sessionId 或文件路径含 query）——cheap，已有 header。
   // 零命中才进入第二级（互斥回退，非合并排序，§6.7 子决策 1）。
+  // [session-store-layout-inversion] 完整 id 精确等值短路：存储树分区目录名 =
+  // rootSessionId（`<root>/<rootSessionId>/subagents/sessions/<sid>.jsonl`），根会话 id
+  // 会出现在其全部 subagent 候选的路径里——不短路则完整 id 直查根会话被伪 multi 消歧。
+  // 等值命中是 includes 命中的子集，短路只消伪 multi 不减真召回。
+  const exactIdHits = candidates.filter((c) => c.ref.sessionId === query)
+  if (exactIdHits.length > 0) {
+    return exactIdHits.map((c) => ({ ...c }))
+  }
   const exactHits = candidates.filter(
     (c) => c.ref.sessionId.includes(query) || c.meta.path.includes(query),
   )
@@ -626,7 +637,7 @@ export interface SessionFileRef {
  *
  * id 取自首行 header（复用 collectCandidates 的首行扫描——与 find 候选、resolveSessionId
  * 同一 id 语义，agent 从 find 输出复制的完整 id 恒能命中；不按文件名反推，避免「文件改名
- * 后与 header id 失配」的误报面）。workflow-state 跳过、坏 header 跳过、被去重根不产候选
+ * 后与 header id 失配」的误报风险）。workflow-state 跳过、坏 header 跳过、被去重根不产候选
  * 均随 collectCandidates 继承。同 id 多根出现（[live] 与 [default] 不去重，V2 语义）时取
  * mtime 新者（与 loadTitleIndex 合并语义一致）。
  *

package/src/discovery/roots.ts

@@ -2,6 +2,11 @@ import { readdir, stat, realpath } from 'node:fs/promises'
 import type { Dirent } from 'node:fs'
 import { join, basename, dirname } from 'node:path'
 import { performance } from 'node:perf_hooks'
+import {
+  resolveArchiveDir,
+  scanArchiveLedgers,
+  type ArchiveLedgerEntry,
+} from './archive-ledger.js'
 
 /**
  * M2 discovery 发现层：文件系统扫描（design §3.3 D-5 首行扫描策略的文件定位部分）。
@@ -33,10 +38,10 @@ export interface SessionRootSignals {
   liveSessionDir?: string
 }
 
-/** 候选根来源标签；kind 优先级 live > default > legacy > subagent（§6.1 信号序） */
-export type SessionRootKind = 'live' | 'default' | 'legacy' | 'subagent'
+/** 候选根来源标签；kind 优先级 live > default > legacy > subagent > archive（§6.1 信号序 + D7 追加） */
+export type SessionRootKind = 'live' | 'default' | 'legacy' | 'subagent' | 'archive'
 
-/** main 源 = 主 session 根（live/default/legacy）；subagent 源 = subagent 会话根 */
+/** main 源 = 主 session 根（live/default/legacy/archive）；subagent 源 = subagent 会话根 */
 export type SessionRootSource = 'main' | 'subagent'
 
 /** 候选根（含扫描结果）。去重后每 kind 至多一个根，kind 即 doctor 表行键。 */
@@ -53,6 +58,12 @@ export interface SessionRoot {
   scanMs?: number
   /** 扫描所得文件列表（design §7B 要点 8「本就在返回值里」）；未扫描时空数组 */
   files: SessionFileMeta[]
+  /**
+   * 归档根（kind='archive'）专属：簿记收集器产出（D7 独立收集契约——收
+   * `.archive.json` 不收 `.jsonl`，故 files 恒空、fileCount = 簿记数）。
+   * 其余根不挂此字段。
+   */
+  archiveEntries?: ArchiveLedgerEntry[]
   /**
    * realpath 与更高优先级根同路径 → 指向保留根的 kind，本根未扫描（doctor 渲染
    * 「与 N 同路径，已去重」注记的依据，§7B 要点 4）。
@@ -64,6 +75,68 @@ export interface SessionRoot {
 const SESSIONS_DIRNAME = 'sessions'
 const SUBAGENTS_DIRNAME = 'subagents'
 
+/**
+ * taiji session 存储树根段（`<dataDir>/ext-sessions/`）。
+ *
+ * session-reader 是 extension 不 import @taiji/shared——本常量是 shared
+ * `SESSION_STORE_DIR_SEGMENT` 的同字面镜像，dataDir 推导先例 = `dirname(agentDir)`
+ * 基址（布局 B `agentDir = <dataDir>/agent`；同 tool-handler doExport 导出落点）。
+ * 字面量一致性由对拍机检锚点 `scripts/check-artifact-dir-formula-sync.mjs`（域 9
+ * session-reader discovery 断言位）锁定，树根段改名时 shared 与此处同批改。
+ */
+const SESSION_STORE_DIR_SEGMENT = 'ext-sessions'
+
+/**
+ * 存储树分区目录名合法性正则（镜像 shared `PI_SESSION_ID_PATTERN`，同域规则：首尾
+ * 字母数字，中间允许 [A-Za-z0-9._-]；禁 `:`——btw 虚拟 id 必拒）。对拍机检锚点同上。
+ *
+ * [session-store-layout-inversion] 存储树扫描（subagent 根 / records manifest）以
+ * 此过滤 `<root>/` 一级目录——既是剪枝也是路径注入防线（目录名即 sessionId）。
+ */
+const PI_SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/
+
+/**
+ * session 存储树根目录（`<dataDir>/ext-sessions/`，dataDir = dirname(agentDir)）。
+ *
+ * 新布局全部 session 维度衍生数据的统一落点（布局权威 = shared getSessionStoreDir，
+ * 本函数是 extension 侧镜像推导）；旧布局 `<agentDir>/subagents` 不再读写（设计裁决
+ * D6：旧布局存量原位保留、不可见）。
+ */
+export function resolveSessionStoreRoot(agentDir: string): string {
+  return join(dirname(agentDir), SESSION_STORE_DIR_SEGMENT)
+}
+
+/** 存储树某根会话分区的 subagent 域目录（`<root>/<rootSessionId>/subagents/`）。 */
+export function resolveStoreSubagentsDir(agentDir: string, rootSessionId: string): string {
+  return join(resolveSessionStoreRoot(agentDir), rootSessionId, SUBAGENTS_DIRNAME)
+}
+
+/** subagent 会话 jsonl 目录（`<root>/<rootSessionId>/subagents/sessions/`）。 */
+export function resolveStoreSubagentSessionsDir(agentDir: string, rootSessionId: string): string {
+  return join(resolveStoreSubagentsDir(agentDir, rootSessionId), 'sessions')
+}
+
+/** ExecutionRecord manifest 目录（`<root>/<rootSessionId>/subagents/records/`）。 */
+export function resolveStoreSubagentRecordsDir(agentDir: string, rootSessionId: string): string {
+  return join(resolveStoreSubagentsDir(agentDir, rootSessionId), 'records')
+}
+
+/**
+ * 枚举存储树 `<root>/` 一级合法会话分区目录名（isPiSessionId 过滤，见
+ * PI_SESSION_ID_PATTERN 注释）。根不存在/无权限 → 空数组，不抛错。
+ */
+export async function listSessionStorePartitions(storeRoot: string): Promise<string[]> {
+  let entries: Dirent[]
+  try {
+    entries = await readdir(storeRoot, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  return entries
+    .filter((e) => e.isDirectory() && PI_SESSION_ID_PATTERN.test(e.name))
+    .map((e) => e.name)
+}
+
 /**
  * `[live]` 规范化（§6.1/§7B 要点 3）：`getSessionDir()` 在纯 pi 返回按 cwd 编码的子目录
  *（`<agentDir>/sessions/--Users-x--`），在 taiji 覆盖态返回根本身。判据：basename
@@ -78,7 +151,8 @@ export function normalizeLiveSessionDir(liveSessionDir: string): string {
 
 /**
  * 从信号包推导候选根（未扫描骨架），数组序 = 优先级序（§6.1）。
- * `[subagent]` 恒在（常量推导）；`[live]` 仅在信号存在时出现。
+ * `[subagent]` 恒在（常量推导）；`[live]` 仅在信号存在时出现；`[archive]` 恒在
+ * 骨架中（D7 第五根，纳入与否由 resolveSessionRoots 按「存在才扫」判定）。
  */
 function sessionRootSpecs(signals: SessionRootSignals): SessionRoot[] {
   // 空 agentDir 防御：派生式会退化为 cwd 相对路径（'sessions'/'./sessions'），可能扫到
@@ -90,7 +164,14 @@ function sessionRootSpecs(signals: SessionRootSignals): SessionRoot[] {
   }
   specs.push(spec('default', 'main', join(signals.agentDir, SESSIONS_DIRNAME)))
   specs.push(spec('legacy', 'main', join(dirname(signals.agentDir), SESSIONS_DIRNAME)))
-  specs.push(spec('subagent', 'subagent', join(signals.agentDir, SUBAGENTS_DIRNAME)))
+  // [session-store-layout-inversion] subagent 根 = 存储树根（`<dataDir>/ext-sessions`），
+  // 扫描在 sid 分区内定向探 subagents/sessions/（scanStoreSubagentJsonl）；旧布局
+  // `<agentDir>/subagents` 不再读（设计裁决 D6：存量原位保留、不可见）。
+  specs.push(spec('subagent', 'subagent', resolveSessionStoreRoot(signals.agentDir)))
+  // [session-archive D7] 第五根 = 归档根（`<agentDir>/archive`，镜像 sessions 平级布局）。
+  // 收集契约与四根不同：不收 .jsonl、收 .archive.json 簿记（见 resolveSessionRoots
+  // 分流与 scanArchiveLedgers）；source=main（归档对象是主 session）。
+  specs.push(spec('archive', 'main', resolveArchiveDir(signals.agentDir)))
   return specs
 }
 
@@ -120,7 +201,7 @@ const SKIP_DIRS_NONE = new Set<string>()
 
 // ============================================================
 // 扫描 options（u8 追加：doctor「同一数据源两处渲染，不重复实现探测」§6.3——
-// doctor 经 options 驱动 subagent 根不扫。原 u8 的进程内缓存注入面已删除
+// doctor 经 options 驱动 subagent 根不扫。原 u8 的进程内缓存注入点已删除
 // （ext-simplify-04 U3）：每次调用实扫，本模块不再持有任何缓存语义）
 // ============================================================
 
@@ -137,13 +218,16 @@ export interface SessionRootScanOptions {
 /**
  * 解析候选根并逐根扫描（design 2026-09-10 §6.1 候选根探测 / §7B 要点 3/4/6）。
  *
- * 优先级 live > default > legacy > subagent；按 realpath 去重：同路径多信号只扫一次，
- * 保留最高优先级 kind 标签，被去重的根以 `dedupedInto` 标注（不产生 fileCount/scanMs）。
- * 逐根复用 scanJsonlRecursive（main 源跳 workflow-state；subagent 源不跳）。单根失败
- * （不存在/无权限）→ 空结果继续，不抛错（沿用 listXxxSessions 契约）。
+ * 优先级 live > default > legacy > subagent > archive；按 realpath 去重：同路径多信号
+ * 只扫一次，保留最高优先级 kind 标签，被去重的根以 `dedupedInto` 标注（不产生
+ * fileCount/scanMs）。逐根扫描：main 源整树递归（跳 workflow-state）；subagent 源 =
+ * 存储树定向扫描（[session-store-layout-inversion] 单新根，见 scanStoreSubagentJsonl）；
+ * archive 源 = 簿记收集器（[session-archive D7] 收 .archive.json 不收 .jsonl，
+ * **存在才纳入**——目录不存在时该根不进返回列表，对无归档目录的环境零行为变化）。
+ * 单根失败（不存在/无权限）→ 空结果继续，不抛错（沿用 listXxxSessions 契约）。
  *
  * options（u8 追加，全部缺省安全）：`subagents:'stat'` 让 subagent 根只做存在性检查。
- * 无缓存——每次调用实扫（原 u8 cache 注入面已删除，ext-simplify-04 U3；find/F1
+ * 无缓存——每次调用实扫（原 u8 cache 注入点已删除，ext-simplify-04 U3；find/F1
  * 自检行计数与 doctor 表计数同取本次实扫，§7B 要点 8）。
  */
 export async function resolveSessionRoots(
@@ -154,6 +238,35 @@ export async function resolveSessionRoots(
   const out: SessionRoot[] = []
   const byRealPath = new Map<string, SessionRoot>()
   for (const candidate of sessionRootSpecs(signals)) {
+    if (candidate.kind === 'archive') {
+      // [session-archive D7] 存在才纳入：目录不存在 → 整根不进返回（备注「目录存在即
+      // 纳入」的逆向——非 taiji/纯 pi 用户无 archive 目录，doctor 表与 F1 自检行零变化）
+      if (!(await pathExists(candidate.path))) continue
+      const key = await safeRealpath(candidate.path)
+      const kept = byRealPath.get(key)
+      if (kept) {
+        // 同 realpath：不扫描，标注归属（与普通根 kept 检查同构——archive kind 优先级
+        // 最低，归档目录与更高优先级根同路径时只保留一根，doctor 表不重复计数；
+        // 漏此检查会既出重复根、又以本根覆盖 byRealPath 致后续根 dedupedInto 失效）
+        out.push({ ...candidate, exists: true, dedupedInto: kept.kind })
+        continue
+      }
+      const t0 = performance.now()
+      const archiveEntries = await scanArchiveLedgers(candidate.path)
+      const scanMs = performance.now() - t0
+      // 归档根不走 scanJsonlRecursive（.jsonl 不收）：files 恒空，fileCount = 簿记数
+      const root: SessionRoot = {
+        ...candidate,
+        exists: true,
+        fileCount: archiveEntries.length,
+        scanMs,
+        files: [],
+        archiveEntries,
+      }
+      byRealPath.set(key, root)
+      out.push(root)
+      continue
+    }
     const key = await safeRealpath(candidate.path)
     const kept = byRealPath.get(key)
     if (kept) {
@@ -166,9 +279,13 @@ export async function resolveSessionRoots(
       out.push({ ...candidate, exists: await pathExists(candidate.path) })
       continue
     }
-    const skipDirs = candidate.source === 'main' ? SKIP_DIRS_MAIN : SKIP_DIRS_NONE
+    // subagent 源 = 存储树定向扫描（sid 分区剪枝，见 scanStoreSubagentJsonl）；
+    // main 源维持整树递归（跳 workflow-state）
     const t0 = performance.now()
-    const files = await scanJsonlRecursive(candidate.path, skipDirs)
+    const files =
+      candidate.source === 'subagent'
+        ? await scanStoreSubagentJsonl(candidate.path)
+        : await scanJsonlRecursive(candidate.path, SKIP_DIRS_MAIN)
     const scanMs = performance.now() - t0
     const exists = await pathExists(candidate.path)
     const root: SessionRoot = {
@@ -194,7 +311,7 @@ export interface SessionFileMeta {
 /**
  * main sessions 扫描时整体跳过的子目录名。
  * `workflow-state` 目录存放 workflow 运行状态文件（wf-*.jsonl，首行 `{"v":"wf-run-v1"|"wf-run-v2"...}`，
- * 版本随 subagent-workflow 快照格式演进，读取侧 v1/v2 兼容），非 session 文件——属 family 腿
+ * 版本随 subagent-workflow 快照格式演进，读取侧 v1/v2 兼容），非 session 文件——属 family 路径
  * 独立处理（design §3.3 D-7），扫描 main sessions 时排除，
  * 否则会把 wf 文件误收为 session（且 find.ts 读其首行 header 时会因 type≠session 被丢弃，
  * 在此排除可避免这批无效首行扫描）。
@@ -210,6 +327,24 @@ function isSessionJsonl(name: string): boolean {
   return name.endsWith('.jsonl')
 }
 
+/**
+ * 存储树 subagent 根定向扫描（[session-store-layout-inversion] 读侧单新根）：
+ * 只探 `<root>/<rootSessionId>/subagents/sessions/` 固定位置。`<root>/` 一级只进
+ * isPiSessionId 形态目录（剪枝：不进 logs/attachments 等大目录，也挡非分区名目录）；
+ * 每 sid 分区内 records/ model-switch/ 不扫（会话文件域独立）。sessions/ 内部维持
+ * 递归 + stat（复用 scanJsonlRecursive，`.finalized` 天然排除）。存储树根或分区目录
+ * 不存在/无权限 → 空结果，不抛错（listXxxSessions 契约）。
+ */
+async function scanStoreSubagentJsonl(storeRoot: string): Promise<SessionFileMeta[]> {
+  const results: SessionFileMeta[] = []
+  for (const sid of await listSessionStorePartitions(storeRoot)) {
+    results.push(
+      ...(await scanJsonlRecursive(join(storeRoot, sid, SUBAGENTS_DIRNAME, 'sessions'), SKIP_DIRS_NONE)),
+    )
+  }
+  return results
+}
+
 /**
  * 递归扫描 rootDir 下所有 .jsonl 文件（排除 .finalized），返回绝对路径 + mtime + size。
  * `skipDirs` 命名的目录整体跳过。目录不存在/无权限 → 返回空数组，不抛错（design §2 坏路径容错）。

package/src/discovery/subagents.ts

@@ -1,11 +1,11 @@
 import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
-import { join, basename } from 'node:path'
+import { join } from 'node:path'
 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 { resolveSessionRoots, resolveSessionStoreRoot, resolveStoreSubagentRecordsDir, listSessionStorePartitions, type SessionFileMeta } from './roots.js'
 import { parseSessionHeader, readSessionHeaderFirstLine } from './session-header.js'
 import { resolveWorkflows } from './workflows.js'
 
@@ -186,7 +186,8 @@ async function collectSubagentIdentities(
   // U4 数据流：manifest 命中透全字段；未命中 P-fallback 读尾行 identity 取 task/slug/agent
   //（model/status 不可回退，留 undefined）；无 manifest 无 identity（运行中/异常）跳过。
   // A3（ext-simplify-04）：直调 resolveSessionRoots（原 listSubagentSessions 薄包装已删除）
-  //——agentDir 信号包下 [subagent] 根 = <agentDir>/subagents（常量推导，恒唯一）
+  //——[subagent] 根 = session 存储树（[session-store-layout-inversion] 单新根，常量
+  // 推导，恒唯一；扫描定向探各 sid 分区的 subagents/sessions/）。
   const subMetas =
     (await resolveSessionRoots({ agentDir })).find((r) => r.kind === 'subagent')?.files ?? []
   for (const meta of subMetas) {
@@ -418,31 +419,37 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
 }
 
 /**
- * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 由终态 finalize 或 sync 批落标出口写入（创建时不写），持久存在即使
+ * 扫描 records/*.json —— subagent 注册清单（读侧单新根，[session-store-layout-inversion]
+ * D6 裁决：旧布局存量原位保留、不再读写——旧 record 从 agent 面 result/find 消失是该
+ * 裁决取舍清单明示项，不做旧根兼容扫描）。
+ * 每个 manifest 由终态 finalize 或 rebuildIndexes 投影写入（创建时不写），持久存在即使
  * .jsonl 被 GC。坏 manifest（缺必填字段/JSON 损坏）跳过，不中断扫描。
+ *
+ * 单新根：`<dataDir>/ext-sessions`（dataDir = dirname(agentDir)，布局 B agentDir =
+ * `<dataDir>/agent`；树根段镜像 shared SESSION_STORE_DIR_SEGMENT，对拍机检锚点 =
+ * scripts/check-artifact-dir-formula-sync.mjs 域 9）。新布局 records 在
+ * `<root>/<sid>/subagents/records/`（分区键 = rootSessionId，嵌套派发全层同值——
+ * 嵌套 subagent 的 manifest 同落根会话分区，固定位置扫描完整覆盖）。扫描剪枝：
+ * `<root>/` 一级只进 isPiSessionId 形态目录（不进 logs/attachments 等大目录），每个
+ * sid 分区内只探 subagents/records/ 固定位置，不整树递归。根不存在时静默空读。
  */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
-  const root = join(agentDir, 'subagents')
+  const storeRoot = resolveSessionStoreRoot(agentDir)
   const out: RecordManifest[] = []
-  async function walk(dir: string): Promise<void> {
+  for (const sid of await listSessionStorePartitions(storeRoot)) {
+    const recordsDir = resolveStoreSubagentRecordsDir(agentDir, sid)
     let entries
     try {
-      entries = await readdir(dir, { withFileTypes: true })
+      entries = await readdir(recordsDir, { withFileTypes: true })
     } catch {
-      return // 目录不存在/无权限 → 静默返回
+      continue // 该分区无 records/（无 subagent 的会话）→ 静默跳过
     }
     for (const e of entries) {
-      const full = join(dir, e.name)
-      if (e.isDirectory()) {
-        await walk(full)
-      } else if (e.isFile() && e.name.endsWith('.json') && basename(dir) === 'records') {
-        const m = await tryReadManifest(full)
-        if (m) out.push(m)
-      }
+      if (!e.isFile() || !e.name.endsWith('.json')) continue
+      const m = await tryReadManifest(join(recordsDir, e.name))
+      if (m) out.push(m)
     }
   }
-  await walk(root)
   return out
 }
 

package/src/discovery/whitelist.ts

@@ -16,8 +16,8 @@ import { zcodeImportDbAllowlist } from '@zhushanwen/zcode-session-source'
  *
  * **检查顺序铁律（§3.4 三段递进，实现与测试双锚定）**：存在性先于路径——
  * `existsSync` 为 false 报 `zcode_db_unreadable`（库文件不存在）而非
- * `zcode_db_path_forbidden`，避免把「只是还没落库」误报成安全事件（forbidden 是
- * 安全面错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
+ * `zcode_db_path_forbidden`，避免把「只是还没写入仓库」误报成安全事件（forbidden 是
+ * 安全侧错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
  * 开库（第 3 段）由调用方在本闸通过后进行。
  *
  * **TOCTOU 残留（设计 §3.4 显式登记，不在本梯队硬化）**：realpath 之后仍按原
@@ -72,10 +72,10 @@ export function formatZcodeDbPathForbidden(dbPath: string): string {
  * 白名单闸（第 1 段存在性 → 第 2 段路径；通过才允许开库）。
  *
  * @throws Error（消费侧映射为 zcode_db_unreadable / zcode_db_path_forbidden，
- *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误面）
+ *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误范围）
  */
 export function assertZcodeDbPathAllowed(dbPath: string, agentDir: string): void {
-  // 第 1 段 存在性（先于路径——「还没落库」不是安全事件）
+	// 第 1 段 存在性（先于路径——「还没写入仓库」不是安全事件）
   if (!existsSync(dbPath)) {
     throw new Error(formatZcodeDbUnreadable(dirname(agentDir), `（库文件不存在：${dbPath}）`))
   }

package/src/discovery/workflows.ts

@@ -17,7 +17,7 @@ import { extractSessionIdFromFilename } from './subagents.js'
 //   ——家族链数据源同 record 流，无第二承载位）；旧后缀锚点（.events.jsonl 形态）=
 //   历史实体（[D1] 历史数据处置：旧两件不读）→ calls=[] 仅 run 存在性兜底。
 //   历史格式条目（v1 全量快照 / workflow-state-link 指针）不识别、静默从发现链消失
-//   （不拒读、不报错）——run 侧 v1 读面已删除（ADR-0095，同 record 侧裁决：项目未
+//   （不拒读、不报错）——run 侧 v1 读侧已删除（ADR-0095，同 record 侧裁决：项目未
 //   上线无历史数据，不迁移不兼容）。
 // - readRunSnapshot：读 wf-state 文件尾向找首个可解析行，返回原始对象（unknown，格式
 //   收窄交 core 层）。唯一消费方 = tool-handler workflow 概览的快照链分支。
@@ -82,16 +82,16 @@ function sessionRefFromPath(path: string, pathToRef: Map<string, SessionRef>): S
 }
 
 // ============================================================
-// workflow-record 条目契约（v2 注册条目判别——本地字面量 + 测试守卫漂移）
+// workflow-record 条目契约（v2 注册条目判别——本地字面量 + 测试检查漂移）
 // ============================================================
 
 /**
  * `workflow-record` custom entry 的 customType 值。
  *
  * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core
- * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖面不引
+ * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖范围不引
  * subagent-core（同 entry-anchor.ts 的协议字面量模式），两侧漂移由 workflow.test.ts
- * 的跨包断言守卫。
+ * 的跨包断言检查。
  */
 const WORKFLOW_RECORD_CUSTOM_TYPE = 'workflow-record'
 
@@ -102,7 +102,7 @@ const WORKFLOW_RECORD_ENTRY_V2 = 2
  * run record 流文件名尾段（`<runId>.record.jsonl`）。写侧 subagent-core
  * RUN_EVENTS_SUFFIX 同值（[D1] record 单源后缀）——v2 注册条目的
  * recordPath 锚点后缀判定用（新锚点直读 record 流；旧 `.events.jsonl` 锚点 =
- * 历史实体分流），本地持有 + 测试守卫漂移。
+ * 历史实体分流），本地持有 + 测试检查漂移。
  */
 export const RUN_RECORD_STREAM_SUFFIX = '.record.jsonl'
 
@@ -142,7 +142,7 @@ function collectRegisteredRecordPaths(entries: readonly Entry[]): RegisteredReco
 /**
  * [D16③] recordPath 后缀分流：`.record.jsonl` 锚点 = 新形态（record 流直读）；
  * 其余（含旧 `.events.jsonl` 锚点）= 历史实体（[D1] 历史数据处置——旧两件不读
- * 不写，历史 run 从发现链数据面退空即预期行为）。
+ * 不写，历史 run 从发现链的数据中退空即预期行为）。
  */
 function isNewRecordStreamAnchor(recordPath: string): boolean {
   return recordPath.endsWith(RUN_RECORD_STREAM_SUFFIX)
@@ -155,7 +155,7 @@ interface AgentSettledSessionFileView {
   result: { sessionFile: string }
 }
 
-/** [extractRecordStreamSessionFiles 守卫] 单帧是否为携带非空 result.sessionFile
+/** [extractRecordStreamSessionFiles 检查] 单帧是否为携带非空 result.sessionFile
  *  的 agent-settled 帧：逐字段 typeof 校验（type → taskIndex → result →
  *  sessionFile），不过关 = 宽容跳过（与 readRunSnapshot 同容忍度）。 */
 function isAgentSettledSessionFileFrame(v: unknown): v is AgentSettledSessionFileView {
@@ -194,7 +194,7 @@ export function extractRecordStreamSessionFiles(content: string): string[] {
 /**
  * 读目标 session 文件全文，从 workflow-record v2 注册条目构造 WorkflowRef[]
  * （单档发现链——v1 快照条目与 workflow-state-link 指针条目不再识别，历史 run
- * 从发现链数据面退空即预期行为，见 ADR-0095）。同一 runId 的多条目后写覆盖
+ * 从发现链的数据中退空即预期行为，见 ADR-0095）。同一 runId 的多条目后写覆盖
  * （条目顺序 = 时间顺序，取最新锚点）。
  *
  * **签名与返回值结构（WorkflowRef[]{runId,stateFile,calls:SessionRef[]}）不变**