@zhushanwen/pi-session-reader 0.11.0 → 0.12.0

package/src/__tests__/zcode-manifest.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { tmpdir } from 'node:os'
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, dirname } from 'node:path'
 
 import { readZcodeManifest, listZcodeManifests } from '../discovery/zcode-manifest.js'
 import { findZcodeEntryAnchor } from '../discovery/entry-anchor.js'
@@ -10,10 +10,10 @@ import { findZcodeEntryAnchor } from '../discovery/entry-anchor.js'
 // 变体 M（设计 §4 场景 1a）：zcode manifest 直读（§3.1 第①步主路径）+ 枚举（family 用）。
 //
 // fixture 对齐 F21 磁盘真实形态：zcode manifest **无 sessionFile 键**
-// （投影函数照写 sessionFile: undefined，JSON.stringify 丢键）、engine:'zcode'、
+// （派生视图函数照写 sessionFile: undefined，JSON.stringify 丢键）、engine:'zcode'、
 // engineHandle.sessionRef 双键齐。
 //
-// 单元边界：只测「认出 zcode manifest + 提取锚」；白名单闸 / 错误码映射（U9）、
+// 单元边界：只测「认出 zcode manifest + 提取锚」；白名单门禁 / 错误码映射（U9）、
 // entry 兜底定位语义（U7 已交付）不在本文件展开。
 // ============================================================
 
@@ -21,9 +21,13 @@ const DB_PATH = '/data/agent/engines/zcode/session-db/db.sqlite'
 
 let agentDir: string
 
-/** 在 <agentDir>/subagents/<slug>/records/ 下写一个 manifest 文件（手写 JSON 字符串，忠实控制键） */
-function writeManifest(slug: string, name: string, content: string): string {
-  const recordsDir = join(agentDir, 'subagents', slug, 'records')
+/**
+ * 在存储树分区 <root>/<sid>/subagents/records/ 下写一个 manifest 文件（手写 JSON 字符串，
+ * 忠实控制键）。[session-store-layout-inversion D6/单新根] 新布局无 cwd-slug 层，
+ * slug 参数消亡（保留签名兼容既有调用点，弃用改名 _slug）；分区名固定合法 sid。
+ */
+function writeManifest(_slug: string, name: string, content: string): string {
+  const recordsDir = join(dirname(agentDir), 'ext-sessions', 'root-session-test', 'subagents', 'records')
   mkdirSync(recordsDir, { recursive: true })
   const file = join(recordsDir, name)
   writeFileSync(file, content, 'utf8')
@@ -73,7 +77,10 @@ function recordLine(saId: string, sessionRef: Record<string, string>): string {
 }
 
 beforeEach(() => {
-  agentDir = mkdtempSync(join(tmpdir(), 'zcode-manifest-test-'))
+  // agentDir 两层化（<mkdtemp>/agent）：存储树推导 = dirname(agentDir)/ext-sessions，
+  // 单层直接当 agentDir 会把扫描根泄到 tmpdir 公共层（跨测试污染——先例 reaper/family-zcode 同修）
+  agentDir = join(mkdtempSync(join(tmpdir(), 'zcode-manifest-test-')), 'agent')
+  mkdirSync(agentDir, { recursive: true })
 })
 afterEach(() => {
   rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
@@ -353,12 +360,13 @@ describe('listZcodeManifests 枚举（family 节点列表来源）', () => {
     expect(manifests.find((m) => m.id === 'sa-s2')?.slug).toBe('worker') // agentName 兜底
   })
 
-  it('subagents 根不存在 → 空数组（不报错；单节点不可达不炸整屏）', async () => {
-    const bareDir = mkdtempSync(join(tmpdir(), 'zcode-manifest-bare-'))
+  it('存储树根不存在 → 空数组（不报错；单节点不可达不炸整屏）', async () => {
+    // agentDir 两层化：扫描根 = dirname(agentDir)/ext-sessions（mkdtemp 私有层内，防公共层污染）
+    const bareDir = join(mkdtempSync(join(tmpdir(), 'zcode-manifest-bare-')), 'agent')
     try {
       expect(await listZcodeManifests(bareDir)).toEqual([])
     } finally {
-      rmSync(bareDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+      rmSync(dirname(bareDir), { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
     }
   })
 })

package/src/__tests__/zcode-routing.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import { tmpdir } from 'node:os'
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, dirname } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
 import { Check } from 'typebox/value'
 
@@ -16,7 +16,7 @@ import sessionReaderExtension from '../index.js'
 import { setPiHandle } from '@zhushanwen/pi-extension-logger'
 
 // ============================================================
-// U9 路由 + 白名单闸 + 错误面集成测试（design session-reader-shared-core
+// U9 路由 + 白名单闸 + 错误范围集成测试（design session-reader-shared-core
 // §3.1 三层定位链 / §3.4 七码 + 检查顺序三段递进 / §4 场景 1a 变体 M/E +
 // 场景 2 family + 场景 5 八类失败 + 场景 3 pi 零回归 + D4 schema 零变化）。
 //
@@ -53,8 +53,8 @@ beforeEach(() => {
   mkdirSync(agentDir, { recursive: true })
   mkdirSync(liveDir, { recursive: true })
   dbPath = join(root, ...ISOLATED_DB_SEGMENTS)
-  // 结构化日志捕获：logger.warn 走 appendEntry 通道（不进 LLM 可见面——本文件同时
-  // 是「降级留痕不进 LLM 可见面」契约的断言面）。测试后清注入防跨文件泄漏。
+  // 结构化日志捕获：logger.warn 走 appendEntry 通道（不进 LLM 可见部分——本文件同时
+  // 是「降级留痕不进 LLM 可见部分」契约的断言范围）。测试后清注入防跨文件泄漏。
   appendEntries = vi.fn()
   setPiHandle({ appendEntry: appendEntries } as unknown as Parameters<typeof setPiHandle>[0])
 })
@@ -135,7 +135,7 @@ function assistantMsg(
 
 /**
  * 建真实 fixture 隔离库（WAL + session/message/part/schema_migration 四表，行形态 =
- * zcode-session-source helpers 同款宿主 schema 0.16.5 消费面子集）。
+ * zcode-session-source helpers 同款宿主 schema 0.16.5 消费方子集）。
  * 测试进程跑 node（node:sqlite 可用）；生产读链的驱动选择在 source 包内。
  */
 function createZcodeDb(path: string, schemaVersion = '0.16.5', sessions: SessionRows[] = []): void {
@@ -175,7 +175,9 @@ function writeZcodeManifest(
   saId: string,
   opts: { sessionRef?: Record<string, string>; omitEngineHandle?: boolean; engine?: string | true } = {},
 ): void {
-  const recordsDir = join(agentDir, 'subagents', 'proj-slug', 'records')
+  // [session-store-layout-inversion D6/单新根] records 读侧 = 存储树分区固定位置
+  // <root>/<rootSid>/subagents/records/（旧根 <agentDir>/subagents 不再读写）。
+  const recordsDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'records')
   mkdirSync(recordsDir, { recursive: true })
   const m: Record<string, unknown> = {
     id: saId,
@@ -210,8 +212,8 @@ function recordLine(entryId: string, saId: string, sessionRef: Record<string, st
 
 /**
  * pi 形态的 subagent-record custom entry 行（回归 A1 instrument）：engine 键缺省 +
- * sessionRef 无 dbPath——subagent-core record-entry.ts 的 pi 投影形态（engineHandle
- * 可选、sessionRef 整体透传不枚举内部键；最小可信子集，跨包漂移由 entry-anchor.test 守卫）。
+ * sessionRef 无 dbPath——subagent-core record-entry.ts 的 pi 派生视图形态（engineHandle
+ * 可选、sessionRef 整体透传不枚举内部键；最小可信子集，跨包漂移由 entry-anchor.test 检查）。
  */
 function piRecordLine(entryId: string, saId: string): string {
   return JSON.stringify({
@@ -220,7 +222,7 @@ function piRecordLine(entryId: string, saId: string): string {
     id: entryId,
     parentId: null,
     data: {
-      // 登记 §3.3：条目面 = v2 族——pi 形态 = 注册条（身份）+ 终态条（engineHandle 半键）。
+      // 登记 §3.3：条目范围 = v2 族——pi 形态 = 注册条（身份）+ 终态条（engineHandle 半键）。
       v: 2,
       kind: 'settled',
       id: saId,
@@ -260,7 +262,7 @@ function writeRootSessionFile(): void {
 
 /** pi manifest + pi subagent session 文件（pi 穿插断言用；engine 缺省 = pi 存量形态）。 */
 function writePiFixture(): void {
-  const subDir = join(agentDir, 'subagents', 'pi-slug', 'sessions')
+  const subDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'sessions')
   mkdirSync(subDir, { recursive: true })
   const piSession = join(subDir, '019e6c96-pi-sub-agent-00000000004a4.jsonl')
   writeFileSync(
@@ -272,7 +274,7 @@ function writePiFixture(): void {
     ].join('\n') + '\n',
     'utf8',
   )
-  const recordsDir = join(agentDir, 'subagents', 'pi-slug', 'records')
+  const recordsDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'records')
   mkdirSync(recordsDir, { recursive: true })
   writeFileSync(
     join(recordsDir, 'sa-pi-1.json'),
@@ -433,7 +435,7 @@ describe('场景 5 八类失败（§3.4 表逐行 + 检查顺序三段递进）'
     await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
       'zcode_anchor_missing',
     )
-    // 归因进结构化日志不进 LLM 可见面（§3.4）：缺失键名可区分（missing-dbPath）
+    // 归因进结构化日志不进 LLM 可见部分（§3.4）：缺失键名可区分（missing-dbPath）
     expect(logCallsWithReason('missing-dbPath')).toBeGreaterThanOrEqual(1)
   })
 
@@ -521,14 +523,14 @@ describe('场景 5 八类失败（§3.4 表逐行 + 检查顺序三段递进）'
 })
 
 // ---------------------------------------------------------------------------
-// 驱动探测失败的错误面契约（跨包漂移守卫 + L4 包装形态映射）
+// 驱动探测失败的错误契约（跨包漂移检查 + L4 包装形态映射）
 // ---------------------------------------------------------------------------
 
-describe('驱动探测失败错误面：跨包契约 + L4 包装形态映射', () => {
+describe('驱动探测失败错误范围：跨包契约 + L4 包装形态映射', () => {
   it('跨包契约：SQLITE_DRIVER_UNSUPPORTED_MARK 子串在 zcode-session-source sqlite-driver 源文内（漂移即红）', () => {
     // 驱动探测错误无专用错误类型（该包不导出子类），reader 按消息特征识别——mark 与
     // sqlite-driver 源内错误字面量的绑定由本测试机器锚定（entry-anchor.test.ts 协议
-    // 字面量跨包漂移守卫同范式）：源文措辞变更不再含 mark → host_unsupported 面死亡，红。
+    // 字面量跨包漂移检查同范式）：源文措辞变更不再含 mark → host_unsupported 契约死亡，红。
     const source = readFileSync(
       new URL('../../../../../packages/zcode-session-source/src/sqlite-driver.ts', import.meta.url),
       'utf8',
@@ -689,7 +691,7 @@ describe('pi 穿插不受影响：同 fixture 内 pi 会话读取与 zcode 调
 /** `session_read` 输入 schema 的 JSON 序列化快照（防无意漂移的逐字节锚）。
  *
  * 快照锚的意图 = 无意漂移拦截（参数增删 / 文案改动即红，迫使有意确认）；
- * 有意的声明面压缩须同批重新生成快照。当前快照 = tool-declaration-slimming
+ * 有意的声明侧压缩须同批重新生成快照。当前快照 = tool-declaration-slimming
  * U-A1 压缩终态（D1 三层分工：action 功能语义唯一承载点 = 枚举 description；
  * 工具 description 只留定位 + 边界；guidelines 只留纪律）。重新生成：
  * tsx 起 extension 捕获 registerTool 的 parameters 后 JSON.stringify。
@@ -748,12 +750,12 @@ describe('session_read schema 快照（D4：不加任何工具参数，逐字节
 
 describe('session_read 锚词保留清单（D2：guidelines 纪律逐词锚定）', () => {
   // SCHEMA_SNAPSHOT 只逐字节锚 parameters schema，不覆盖 guidelines——本块是
-  // guidelines 锚词的机器防线：弱模型回归（P7/PB-weak）后对本工具声明面的
+  // guidelines 锚词的机器防线：弱模型回归（P7/PB-weak）后对本工具声明侧的
   // 再压缩 / 措辞改动，逐词红灯迫使有意确认。清单与 index.ts 注释登记一致：
   //   1. "Progressive reading"   —— 阅读纪律 outline → expand → detail
   //   2. "Never read raw .jsonl" —— 禁直读原始 session 文件
-  //   3. "sa- ids route"         —— zcode 路由对 LLM 的唯一可见面（U9）
-  //   4. "👉 recovery hint"      —— 错误面恢复指针契约
+  //   3. "sa- ids route"         —— zcode 路由对 LLM 的唯一可见部分（U9）
+  //   4. "👉 recovery hint"      —— 错误范围恢复指针契约
   //   5. "doctor"                —— 环境自检入口（另被上方快照 action 枚举间接锚定）
   it('guidelines 5 锚词逐个在位（缺一词即红）', () => {
     const registerTool = vi.fn()

package/src/__tests__/zcode-whitelist.test.ts

@@ -77,7 +77,7 @@ describe('assertZcodeDbPathAllowed：检查顺序三段递进（存在性先于
     )
   })
 
-  it('第 2 段路径：存在但集合外 → zcode_db_path_forbidden（安全面错误语义更重）', () => {
+  it('第 2 段路径：存在但集合外 → zcode_db_path_forbidden（安全侧错误语义更重）', () => {
     const outside = join(root, 'evil.sqlite')
     writeFileSync(outside, '', 'utf8')
     try {

package/src/core/family.ts

@@ -38,7 +38,7 @@ export interface SubagentRef extends SessionRef {
   task?: string
   /** agent 类型名（manifest.agentName，P-fallback 时 identity.data.agent；同语义异名） */
   agentName?: string
-  /** 模型 id（仅 manifest 有；P-fallback 时 undefined）。仅 details 可见，不进文本渲染（D2②：展示面只取 status/agentName/task） */
+  /** 模型 id（仅 manifest 有；P-fallback 时 undefined）。仅 details 可见，不进文本渲染（D2②：展示侧只取 status/agentName/task） */
   model?: string
   /** 终态 completed/failed/running（仅 manifest 有；P-fallback 时 undefined） */
   status?: string
@@ -60,7 +60,7 @@ export interface Family {
   forks: SessionRef[]
   /** 含隔代（design §3.3 D-7 Q1：对 fork 链每个节点查 subagentsByRoot 合并） */
   subagents: SubagentRef[]
-  /** M1 恒返回 []，workflow 腿需读 workflow-state 文件（IO）归 M2 */
+  /** M1 恒返回 []，workflow 路径需读 workflow-state 文件（IO）归 M2 */
   workflows: WorkflowRef[]
 }
 
@@ -146,12 +146,12 @@ export function buildZcodeSubagentsByRoot(
   return byRoot
 }
 
-// ---- 类型守卫：从 unknown 的 entry.data 提取 subagent identity 字段 ----
+// ---- 类型检查：从 unknown 的 entry.data 提取 subagent identity 字段 ----
 
 /**
  * identity 尾行 data 结构（读取视图，DM-IdentityData）。
  *
- * 守卫只强制 rootSessionId+slug（m0 契约），其余富字段全 optional——由 buildFamilyFromFs
+ * 检查只强制 rootSessionId+slug（m0 契约），其余富字段全 optional——由 buildFamilyFromFs
  * 按 manifest 主/P-fallback 回退路径组装时决定是否填入（manifest 主填全，P-fallback
  * 只填 task/agent/sessionFile，model/status 缺）。
  */
@@ -178,7 +178,7 @@ interface SubagentIdentityData {
 function isSubagentIdentityData(v: unknown): v is SubagentIdentityData {
   if (typeof v !== 'object' || v === null) return false
   const obj = v as Record<string, unknown>
-  // 守卫放宽：只校验 rootSessionId+slug 必填（m0 契约），task/agent/model/status/sessionFile optional
+	// 检查放宽：只校验 rootSessionId+slug 必填（m0 契约），task/agent/model/status/sessionFile optional
   return typeof obj.rootSessionId === 'string' && typeof obj.slug === 'string'
 }
 
@@ -380,7 +380,7 @@ export function resolveFamily(sessionId: string, index: FamilyIndex): Family {
     }
   }
 
-  // 5. workflows：M1 恒 []，workflow 腿需读 workflow-state 文件（IO）归 M2
+  // 5. workflows：M1 恒 []，workflow 路径需读 workflow-state 文件（IO）归 M2
   const workflows: WorkflowRef[] = []
 
   return { root, parents, forks, subagents, workflows }

package/src/core/render.ts

@@ -79,7 +79,7 @@ export interface OutlineOptions {
 }
 
 // ---------------------------------------------------------------------------
-// content 类型守卫与提取（message.content 是 unknown，design §3.4）
+// content 类型检查与提取（message.content 是 unknown，design §3.4）
 // ---------------------------------------------------------------------------
 
 interface ContentBlock {
@@ -454,7 +454,7 @@ export function renderOutline(
   const allBranches = options?.allBranches ?? false
   const granularity = options?.granularity ?? 'turn'
 
-  // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据面）；行与轮次计数走对话集
+  // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据）；行与轮次计数走对话集
   const parsedBytes = leafParsedBytes(turns)
   const leafEntryCount = turns.reduce((s, t) => s + t.entries.length, 0)
   // totalEntries = leaf + 旁支子树 + 孤儿；totalBytes 无原始文件字节数（签名不含 ParseResult），

package/src/core/toolcall.ts

@@ -69,7 +69,7 @@ function coerceArgs(raw: unknown): Record<string, unknown> {
 /**
  * 从 entry.message.content 的 `{type:"toolCall"}` block 提取工具调用列表。
  *
- * content 是 unknown 做类型守卫；非数组或无 toolCall block 返 []。
+ * content 是 unknown 做类型检查；非数组或无 toolCall block 返 []。
  * 仅纳入 id + name 均为 string 的 block（O2 靠 id 关联 toolResult，O1 靠 name 聚合；
  * 缺 id 的块无法关联，缺 name 无法摘要，跳过——实测 0 缺失）。
  */

package/src/core/workflow.ts

@@ -15,7 +15,7 @@
 
 import { isRecord } from '@zhushanwen/pi-ext-guards'
 
-// ---- 类型守卫 helpers ----
+// ---- 类型检查 helpers ----
 
 /** unknown → string 收窄（非 string → undefined）。快照可选字符串字段的统一入口。 */
 function strOr(v: unknown): string | undefined {
@@ -74,9 +74,9 @@ export interface WorkflowOverview {
   runId: string
   /** WorkflowRef.stateFile 透传 */
   stateFile: string
-  /** NEW state.status / OLD 顶层 status / record 流投影（[D2] 三态：running | interrupted | done） */
+  /** NEW state.status / OLD 顶层 status / record 流派生视图（[D2] 三态：running | interrupted | done） */
   status: string
-  /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
+  /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读侧形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
   version: 'wf-run-v1' | 'wf-run-v2' | 'legacy'
   /** NEW spec.scriptName / spec.name / OLD name */
   script?: string
@@ -222,12 +222,12 @@ function parseLegacyRunSnapshot(
  *
  * 分支（C-parserunsnapshot-dualformat，TC-wf-snapshot-version-union）：
  * - 非对象 → null（调用方跳过，ES-wf-snapshot-unparseable）
- * - NEW (snapshot.v === 'wf-run-v1' 或 'wf-run-v2'，读取面形状一致)：state.* / meta.* / spec.*
+ * - NEW (snapshot.v === 'wf-run-v1' 或 'wf-run-v2'，读侧形状一致)：state.* / meta.* / spec.*
  * - OLD (无 v，有 callCache 数组或顶层 status)：顶层 status/budget/startedAt + callCache
  * - 既非 NEW 也非 OLD → null（未来版本（如 wf-run-v3）/ 异构内容）
  *
  * runId/stateFile 透传参数（不读 snapshot.runId，保证与 family.workflows 一致，避免 OLD 顶层
- * runId 可信度低的不一致）。零 any（全程 typeof/Array.isArray/isRecord 守卫收窄）。
+ * runId 可信度低的不一致）。零 any（全程 typeof/Array.isArray/isRecord 检查收窄）。
  */
 export function parseRunSnapshot(
   snapshot: unknown,
@@ -236,7 +236,7 @@ export function parseRunSnapshot(
 ): WorkflowOverview | null {
   if (!isRecord(snapshot)) return null
 
-  // NEW 格式（v === 'wf-run-v1' || 'wf-run-v2'，v2 读取面形状兼容 v1）
+  // NEW 格式（v === 'wf-run-v1' || 'wf-run-v2'，v2 读侧形状兼容 v1）
   const v = snapshot.v
   if (v === 'wf-run-v1' || v === 'wf-run-v2') {
     return parseNewRunSnapshot(snapshot, v, runId, stateFile)
@@ -331,7 +331,7 @@ interface RecordStreamLine {
   [key: string]: unknown
 }
 
-/** 流解析产物：run 装配面（runId 透传 + stateFile=record 流路径）。 */
+/** 流解析产物：run 装配侧（runId 透传 + stateFile=record 流路径）。 */
 interface RecordStreamFold {
   workflowName?: string
   startedAt?: number
@@ -371,7 +371,7 @@ function parseRecordStreamLine(line: string): RecordStreamLine | undefined {
  *   sessionId——家族链跳转入口）；
  * - run-interrupted：[D2] 中断转移 → status 'interrupted'（非终局）；
  * - run-resumed：[D2] 复活转移 → 清中断标记（status 回 running——lifecycle fold
- *   投影语义：run-resumed 是 interrupted → running 的转移证据，跳过会使 resume
+ *   派生视图语义：run-resumed 是 interrupted → running 的转移证据，跳过会使 resume
  *   续跑期间的概览停在 interrupted 直至终局）；
  * - run-settled：终局帧 → status 'done' + outcome（done/failed/cancelled/time_limited）；
  * - 其余（phase-started / phase-settled）：跳过（状态机转移不进概览文本——phase 分组展示
@@ -445,7 +445,7 @@ function applyAgentSettledToFold(
   })
 }
 
-/** [parseRunRecordStream 拆分] status 三态投影（[D2]）：终局帧 > 中断转移 > running（空流也 running——活跃兜底）。 */
+/** [parseRunRecordStream 拆分] status 三态派生视图（[D2]）：终局帧 > 中断转移 > running（空流也 running——活跃兜底）。 */
 function projectRecordStreamStatus(fold: RecordStreamFold): {
   status: string
   reason: string | undefined

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

@@ -433,6 +433,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 +634,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

@@ -64,6 +64,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
@@ -90,7 +152,10 @@ 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)))
   return specs
 }
 
@@ -120,7 +185,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）：每次调用实扫，本模块不再持有任何缓存语义）
 // ============================================================
 
@@ -139,11 +204,12 @@ export interface SessionRootScanOptions {
  *
  * 优先级 live > default > legacy > subagent；按 realpath 去重：同路径多信号只扫一次，
  * 保留最高优先级 kind 标签，被去重的根以 `dedupedInto` 标注（不产生 fileCount/scanMs）。
- * 逐根复用 scanJsonlRecursive（main 源跳 workflow-state；subagent 源不跳）。单根失败
+ * 逐根扫描：main 源整树递归（跳 workflow-state）；subagent 源 = 存储树定向扫描
+ *（[session-store-layout-inversion] 单新根，见 scanStoreSubagentJsonl）。单根失败
  * （不存在/无权限）→ 空结果继续，不抛错（沿用 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(
@@ -166,9 +232,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 +264,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 +280,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 坏路径容错）。