@zhushanwen/pi-session-reader 0.11.0 → 0.12.0

package/src/__tests__/family.test.ts

@@ -228,7 +228,7 @@ describe('resolveFamily - 错误', () => {
 // ============================================================
 // U4: SubagentRef 富字段（manifest 主 / P-fallback identity 回退）
 // 验证 buildFamilyIndex 从 identity entry.data 读 task/agent/model/status/sessionFile
-// 填 SubagentRef，异名映射（data.agent → agentName），守卫放宽（只校验 rootSessionId+slug）。
+// 填 SubagentRef，异名映射（data.agent → agentName），检查放宽（只校验 rootSessionId+slug）。
 // ============================================================
 
 describe('U4: SubagentRef 富字段（buildFamilyIndex 透传）', () => {
@@ -276,7 +276,7 @@ describe('U4: SubagentRef 富字段（buildFamilyIndex 透传）', () => {
     expect(sub?.status).toBeUndefined()
   })
 
-  it('TC-u4-pfallback-no-identity: data 缺 rootSessionId → 守卫拒掉，不入 subagentsByRoot，不抛错', () => {
+  it('TC-u4-pfallback-no-identity: data 缺 rootSessionId → 检查拒掉，不入 subagentsByRoot，不抛错', () => {
     // 模拟无 identity（运行中/异常，尾行是 message 非 identity）：data 只有 slug 无 rootSessionId
     const noRoot: Entry = {
       type: 'custom',
@@ -287,7 +287,7 @@ describe('U4: SubagentRef 富字段（buildFamilyIndex 透传）', () => {
     }
     const index = buildFamilyIndex([header(ROOT)], [noRoot], makeStats([ROOT]))
 
-    // 守卫拒掉 → 不入 subagentsByRoot
+    // 检查拒掉 → 不入 subagentsByRoot
     expect(index.subagentsByRoot.size).toBe(0)
     // resolveFamily 不抛错，subagents 空
     const family = resolveFamily(ROOT, index)
@@ -331,7 +331,7 @@ describe('U4: SubagentRef 富字段（buildFamilyIndex 透传）', () => {
     expect(sub?.sessionFile).toBeUndefined()
   })
 
-  it('isSubagentIdentityData 守卫放宽：富字段部分缺失/全缺都通过（只校验 rootSessionId+slug）', () => {
+  it('isSubagentIdentityData 检查放宽：富字段部分缺失/全缺都通过（只校验 rootSessionId+slug）', () => {
     const identities = [
       subagentIdentityRich(SUB, ROOT, 's1', { task: 'only-task' }), // 部分富字段
       subagentIdentity(SUB2, ROOT, 's2'), // 完全无富字段（旧 manifest 形态）

package/src/__tests__/find.test.ts

@@ -3,6 +3,10 @@ import { tmpdir } from 'node:os'
 import { mkdtemp, mkdir, writeFile, rm, utimes } from 'node:fs/promises'
 import { join } from 'node:path'
 import { findSessions } from '../discovery/find.js'
+import {
+  resolveStoreSubagentSessionsDir,
+  resolveStoreSubagentRecordsDir,
+} from '../discovery/roots.js'
 import { FIX_E6 } from './fixtures.js'
 
 /**
@@ -131,21 +135,31 @@ async function makeSubagentSession(
 }
 
 describe('findSessions', () => {
+  let root: string
   let agentDir: string
   let slugDir: string
-  /** subagent fixture 目录（模拟 subagents/<cwd编码>/sessions/ 结构，resolveSessionRoots [subagent] 根扫描路径） */
+  /**
+   * subagent fixture 目录（[session-store-layout-inversion] 新布局存储树
+   * `<root>/<rootSessionId>/subagents/sessions/`，resolveSessionRoots [subagent] 根
+   * 定向扫描路径；分区键取 FIX_SID，生产同源推导函数落盘）。
+   */
   let saDir: string
 
   let recordsDir: string
 
+  /** 存储树分区 sid fixture（合法 pi sid 形态）。 */
+  const FIX_SID = '0aaaaaaa-bbbb-7ccc-dddd-0000000000f1'
+
   beforeEach(async () => {
-    agentDir = await mkdtemp(join(tmpdir(), 'find-test-'))
+    // 生产拓扑复刻（布局 B）：agentDir = <dataDir>/agent
+    root = await mkdtemp(join(tmpdir(), 'find-test-'))
+    agentDir = join(root, 'agent')
     slugDir = join(agentDir, 'sessions', '--Users-demo--')
-    saDir = join(agentDir, 'subagents', '--Users-demo--', 'sessions')
-    recordsDir = join(agentDir, 'subagents', '--Users-demo--', 'records')
+    saDir = resolveStoreSubagentSessionsDir(agentDir, FIX_SID)
+    recordsDir = resolveStoreSubagentRecordsDir(agentDir, FIX_SID)
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('uuid 片段匹配正确的 session（sessionId 含 query）', async () => {
@@ -359,6 +373,37 @@ describe('findSessions', () => {
     expect(matches[0].fileName).toContain('subagents')
   })
 
+  it('D6 单新根锚定：旧布局 <agentDir>/subagents 造 subagent 会话 → find 不发现（存量不可见）', async () => {
+    await makeSession(slugDir, { name: 'm.jsonl', id: 'main-shared', cwd: '/demo' })
+    // 旧布局存量原位保留（D6 裁决：不迁移、不再读写）
+    const legacyDir = join(agentDir, 'subagents', '--Users-demo--', 'sessions')
+    await makeSession(legacyDir, { name: 's-legacy.jsonl', id: 'sub-legacy', cwd: '/demo' })
+
+    const { matches } = await findSessions('shared', agentDir)
+    expect(matches.map((m) => m.sessionId)).toEqual(['main-shared'])
+  })
+
+  it('存储树分区目录名（= rootSessionId）不把根会话 id 的完整 id 查询吸成伪 multi', async () => {
+    // 新布局路径 `<root>/<rootSessionId>/subagents/sessions/<subId>.jsonl` 含根会话 id——
+    // 完整 id 查询若走路径子串匹配会同时命中 subagent 候选（伪 multi 消歧）。
+    // 精确等值短路：完整 id 直查恒精确命中（find.ts [session-store-layout-inversion]）。
+    const rootId = '0aaaaaaa-bbbb-7ccc-dddd-0000000000q1'
+    const subId = '0aaaaaaa-bbbb-7ccc-dddd-0000000000q2'
+    await makeSession(slugDir, { name: `${rootId}.jsonl`, id: rootId, cwd: '/demo' })
+    await makeSession(resolveStoreSubagentSessionsDir(agentDir, rootId), {
+      name: `${subId}.jsonl`,
+      id: subId,
+      cwd: '/demo',
+    })
+
+    // 完整 id：精确等值直返，不被 subagent 路径里的分区 id 误吸
+    const exact = await findSessions(rootId, agentDir)
+    expect(exact.matches.map((m) => m.sessionId)).toEqual([rootId])
+    // 真片段查询：路径维度命中仍然保留（按路径片段定位文件的能力不回退）
+    const fragment = await findSessions('0000000000q', agentDir)
+    expect(fragment.matches.map((m) => m.sessionId).sort()).toEqual([rootId, subId].sort())
+  })
+
   it("recent 也尊重 source 过滤（含不传 source 时两侧按 mtime 混合倒序）", async () => {
     const mainPath = await makeSession(slugDir, { name: 'm.jsonl', id: 'r-main', cwd: '/demo' })
     const subPath = await makeSession(saDir, { name: 's.jsonl', id: 'r-sub', cwd: '/demo' })

package/src/__tests__/index.test.ts

@@ -11,9 +11,9 @@ import { Check } from 'typebox/value'
  * mock pi/ctx（as unknown as ExtensionAPI），测：
  * 1. execute 错误路径 throw（W4：pi 只对 execute throw 置 isError:true——agent-loop
  *    丢弃返回值里的 isError 字段，「错误轮被标成功」契约守护）
- * 2. session_start handler 的 ctx.mode!=='tui' 守卫
+ * 2. session_start handler 的 ctx.mode!=='tui' 检查
  * 3. registeredPis WeakSet 去重：同 pi 二次 session_start 不重复注册；不同 pi 可注册
- * 4. typeof ctx.ui.addAutocompleteProvider 运行时守卫（ui 缺方法 → 跳过，不崩）
+ * 4. typeof ctx.ui.addAutocompleteProvider 运行时检查（ui 缺方法 → 跳过，不崩）
  * 5. registerCommand + addAutocompleteProvider 组装（tui 模式下各注册一次）
  * 6. TypeBox schema 与 SessionReadParams 对齐：合法 params 过、非法 action/scope 拒
  * 7. U3 信号包采集降级：sessionManager 缺 getSessionDir 方法 / getSessionDir 抛错 →
@@ -271,7 +271,7 @@ describe('sessionReaderExtension - session_start TUI 注册', () => {
     expect(fake2.registerCommand).toHaveBeenCalledTimes(1)
   })
 
-  it('ctx.ui 无 addAutocompleteProvider（typeof 守卫）→ 跳过注册不崩', () => {
+  it('ctx.ui 无 addAutocompleteProvider（typeof 检查）→ 跳过注册不崩', () => {
     const fake = makeFakePi()
     sessionReaderExtension(fake.pi as unknown as ExtensionAPI)
     const { ctx } = makeFakeCtx({ withUi: false })

package/src/__tests__/rebuild-manifest-dual-write.test.ts

@@ -1,15 +1,15 @@
 // 跨包集成（[U4c / G4-S5③] record 持久化收敛 P4c 验收锚点）：
-// subagent-core 重建/终态写面产出的 manifest → session-reader identity 投影不降级。
+// subagent-core 重建/终态写侧产出的 manifest → session-reader identity 派生视图不降级。
 //
 // 断言链（设计 subagent-record-persistence-consolidation D5 前向兼容判定 + S5③）：
 //   1. manifest 被人为删除（S5 缓存可丢场景）→ subagent-core RecordStore.rebuildIndexes
 //      全量重建 → session-reader listRecordManifests 重新可见；
-//   2. 重建窗口前后，session-reader identity 投影的输入字段集（rootSessionId/slug/
+//   2. 重建窗口前后，session-reader identity 派生视图的输入字段集（rootSessionId/slug/
 //      task/agentName/model/status/sessionFile/parentRecordId）逐字段一致——双写过渡
-//      字段（executionStatus）在场且不被本包消费（旧 status 三态投影继续生效）；
+//      字段（executionStatus）在场且不被本包消费（旧 status 三态派生视图继续生效）；
 //   3. 重建源 = 事件流折叠 + identity entry（[③ .state 退场] 后终态位消失）——
 //      身份/富字段逐字段保真；legacy status 不再保真 closed（重建单规则恒 idle +
-//      无 closedReason → derivedManifestRecord 如实投影 legacy "running"，终态语义
+//      无 closedReason → derivedManifestRecord 如实派生 legacy "running"，终态语义
 //      由 record-settled 事件帧承载）。
 //
 // 形态同 cross-package-subagent-core.test.ts：subagent-core 真实 tmpdir 产出磁盘
@@ -32,7 +32,7 @@ import { listRecordManifests, type RecordManifest } from '../discovery/subagents
 
 const ROOT_SESSION = 'root-dual-write'
 
-/** session-reader identity 投影（manifestIdentityData）消费的字段集——重建窗口
+/** session-reader identity 派生视图（manifestIdentityData）消费的字段集——重建窗口
  *  前后必须逐字段一致（降级 = 任一字段缺失/漂移）。 */
 function identityView(m: RecordManifest) {
   return {
@@ -49,15 +49,21 @@ function identityView(m: RecordManifest) {
 }
 
 describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → session-reader 投影不降级', () => {
+  let dataDir: string
   let agentDir: string
   let sessionsDir: string
   let recordsDir: string
   let childFile: string
 
   beforeEach(() => {
-    agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sr-rebuild-dualwrite-'))
-    sessionsDir = getSubagentSessionDir(agentDir, agentDir)
-    recordsDir = getSubagentRecordsDir(agentDir, agentDir)
+    // 生产拓扑复刻（[session-store-layout-inversion 域 9]）：agentDir = <dataDir>/agent
+    //（session-reader 的 agentDir 语义），subagent-core 写侧经新公式落存储树
+    // <dataDir>/ext-sessions/<rootSid>/subagents/——listRecordManifests 双根扫描的新根
+    //（dirname(agentDir)/ext-sessions）与写侧落点相遇
+    dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sr-rebuild-dualwrite-'))
+    agentDir = path.join(dataDir, 'agent')
+    sessionsDir = getSubagentSessionDir(ROOT_SESSION, dataDir)
+    recordsDir = getSubagentRecordsDir(ROOT_SESSION, dataDir)
     fs.mkdirSync(sessionsDir, { recursive: true })
     fs.mkdirSync(recordsDir, { recursive: true })
 
@@ -95,11 +101,11 @@ describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → sessio
   })
 
   afterEach(() => {
-    fs.rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    fs.rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
-  it('S5③: manifest 删除 → rebuildIndexes 重建 → identity 投影字段集前后一致（双写字段在场）', async () => {
-    // ── 初始 manifest：subagent-core 终态写面（markFinalized）真实产出 ──
+  it('S5③: manifest 删除 → rebuildIndexes 重建 → identity 派生视图字段集前后一致（双写字段在场）', async () => {
+    // ── 初始 manifest：subagent-core 终态写侧（markFinalized）真实产出 ──
     const record = createRecord('sa-dw', {
       agent: 'worker',
       model: 'prov/m1',
@@ -119,7 +125,8 @@ describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → sessio
       closedReason: 'gc' as const,
       endedAt: 2000,
     })
-    const writer = new RecordStore(sessionsDir, undefined, undefined, recordsDir)
+    // [u-subagent dir 晚绑定] RecordStore 构造 = 目录取值函数（非目录字符串）
+    const writer = new RecordStore(() => sessionsDir, undefined, undefined, () => recordsDir)
     expect(writer.markFinalized(record, 'gc')).toBe(true)
     writer.dispose()
 
@@ -127,9 +134,9 @@ describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → sessio
     expect(before).toBeDefined()
     const viewBefore = identityView(before!)
 
-    // 双写过渡字段在写面就位（本包不消费，但前向兼容锚要求其在场）。
+    // 双写过渡字段在写侧就位（本包不消费，但前向兼容锚要求其在场）。
     // [U2 两态] executionStatus 是内部权威词汇（running|idle 两态，终态概念删除）
-    // → 终态化后恒 'idle'；status 旧三态是 session-reader 直读投影（永久保留）→ 'closed'。
+    // → 终态化后恒 'idle'；status 旧三态是 session-reader 直读派生视图（永久保留）→ 'closed'。
     const rawBefore = JSON.parse(fs.readFileSync(path.join(recordsDir, 'sa-dw.json'), 'utf-8')) as Record<string, unknown>
     expect(rawBefore.executionStatus).toBe('idle')
     expect(rawBefore.status).toBe('closed')
@@ -138,15 +145,15 @@ describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → sessio
     for (const f of fs.readdirSync(recordsDir)) fs.rmSync(path.join(recordsDir, f))
     expect((await listRecordManifests(agentDir)).filter((m) => m.id === 'sa-dw')).toHaveLength(0)
 
-    const rebuilder = new RecordStore(sessionsDir, undefined, undefined, recordsDir)
+    const rebuilder = new RecordStore(() => sessionsDir, undefined, undefined, () => recordsDir)
     expect(rebuilder.rebuildIndexes()).toBe(1)
     rebuilder.dispose()
 
-    // ── session-reader 视角：重建后 identity 投影不降级 ──
+    // ── session-reader 视角：重建后 identity 派生视图不降级 ──
     const after = (await listRecordManifests(agentDir)).find((m) => m.id === 'sa-dw')
     expect(after).toBeDefined()
     // 字段集保真（身份/富字段逐字段一致）；仅 legacy status 按 ③ 后重建语义如实
-    // 投影 running（终态权威 = 事件流 record-settled 帧，磁盘重建无 closedReason 载体）。
+    // 派生 running（终态权威 = 事件流 record-settled 帧，磁盘重建无 closedReason 载体）。
     expect(identityView(after!)).toEqual({ ...viewBefore, status: 'running' })
 
     const rawAfter = JSON.parse(fs.readFileSync(path.join(recordsDir, 'sa-dw.json'), 'utf-8')) as Record<string, unknown>
@@ -156,10 +163,10 @@ describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → sessio
     expect(rawAfter.closedReason).toBeUndefined()
   })
 
-  it('惰性通道：查询面（collectRecords）补建的 manifest 同样可被本包读取投影', async () => {
-    // 不经终态写面（无 manifest 初始形态）：磁盘 record 只有 identity + 无 sidecar
+  it('惰性通道：查询结果（collectRecords）补建的 manifest 同样可被本包读取派生视图', async () => {
+    // 不经终态写侧（无 manifest 初始形态）：磁盘 record 只有 identity + 无 sidecar
     // → 查询触发惰性补建。
-    const store = new RecordStore(sessionsDir, undefined, undefined, recordsDir)
+    const store = new RecordStore(() => sessionsDir, undefined, undefined, () => recordsDir)
     expect(store.collectRecords(10).map((r) => r.id)).toContain('sa-dw')
     store.dispose()
 
@@ -172,8 +179,8 @@ describe('跨包集成：subagent-core rebuildIndexes 重建 manifest → sessio
     expect(found!.sessionFile).toBe(childFile)
     expect(found!.parentRecordId).toBe('sa-parent')
     // 双写过渡字段（[U3 重建单规则] 无 sidecar 重建一律 idle：executionStatus 如实
-    // 投影两态词汇；legacy status 经桥接判据派生——无 closedReason 遗留位的 idle
-    // 投影 "running"（session-reader 视角的活跃成员，§3.2.8 下行映射）。
+    // 派生两态词汇；legacy status 经桥接判据派生——无 closedReason 遗留位的 idle
+    // 派生 "running"（session-reader 视角的活跃成员，§3.2.8 下行映射）。
     const raw = JSON.parse(fs.readFileSync(path.join(recordsDir, 'sa-dw.json'), 'utf-8')) as Record<string, unknown>
     expect(raw.executionStatus).toBe('idle')
     expect(raw.status).toBe('running')

package/src/__tests__/render.test.ts

@@ -254,7 +254,7 @@ describe('renderOutline', () => {
     expect(result.stats.totalTurns).toBe(2)
     // T 序号 = 原 turn.index（expand/detail 的入口地址稳定，折叠不重编号）
     expect(result.turns.map((b) => b.index)).toEqual([1, 3])
-    // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据面）：2+1+1+1 = 5
+    // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据）：2+1+1+1 = 5
     expect(result.stats.totalEntries).toBe(5)
   })
 
@@ -459,7 +459,7 @@ describe('renderDetail', () => {
   })
 })
 
-// 测试内联的类型守卫镜像（验证 renderDetail 剥离效果，不依赖 render 内部导出）
+// 测试内联的类型检查镜像（验证 renderDetail 剥离效果，不依赖 render 内部导出）
 function extractTextForTest(content: unknown): string {
   if (typeof content === 'string') return content
   if (Array.isArray(content)) {

package/src/__tests__/result.test.ts

@@ -4,6 +4,10 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { handleSessionRead, type SessionReadParams } from '../tool-handler.js'
 import { extractFinalAssistantText } from '../result-action.js'
+import {
+  resolveStoreSubagentSessionsDir,
+  resolveStoreSubagentRecordsDir,
+} from '../discovery/roots.js'
 
 /**
  * U6 result action 测试（design subagent-sync-collect §3.1.3 + impl-plan U6）。
@@ -22,9 +26,11 @@ import { extractFinalAssistantText } from '../result-action.js'
  * 一致的前置，A4 取回门）。
  */
 
-// ---- fixture 工具（合成 subagent session，同 tool-handler.test.ts makeFixtureSubagent 结构）----
+// ---- fixture 工具（合成 subagent session，同 tool-handler.test.ts makeFixtureSubagent 结构；
+// [session-store-layout-inversion] 新布局存储树，分区键 = manifest.rootSessionId 常量）----
 
-const SLUG = '--demo-cwd--'
+/** 存储树分区 sid fixture（合法 pi sid 形态；与 makeSubagent 内 manifest.rootSessionId 同值）。 */
+const FIX_ROOT_SID = '0aaaaaaa-bbbb-7ccc-dddd-0000000000r1'
 
 interface SubagentFixture {
   saId: string
@@ -45,9 +51,10 @@ function assistantEntry(id: string, content: unknown): unknown {
 }
 
 async function makeSubagent(dir: string, f: SubagentFixture): Promise<string> {
-  const sessionFile = join(dir, 'subagents', SLUG, 'sessions', `${f.realId}.jsonl`)
+  const sessionsDir = resolveStoreSubagentSessionsDir(dir, FIX_ROOT_SID)
+  const sessionFile = join(sessionsDir, `${f.realId}.jsonl`)
   if (f.sessionFileExists !== false) {
-    await mkdir(join(dir, 'subagents', SLUG, 'sessions'), { recursive: true })
+    await mkdir(sessionsDir, { recursive: true })
     const header = JSON.stringify({ type: 'session', id: f.realId, cwd: '/demo' })
     const task = JSON.stringify({
       type: 'message',
@@ -58,13 +65,13 @@ async function makeSubagent(dir: string, f: SubagentFixture): Promise<string> {
     const lines = [header, task, ...(f.entries ?? []).map((e) => JSON.stringify(e))]
     await writeFile(sessionFile, lines.join('\n') + '\n')
   }
-  const recordsDir = join(dir, 'subagents', SLUG, 'records')
+  const recordsDir = resolveStoreSubagentRecordsDir(dir, FIX_ROOT_SID)
   await mkdir(recordsDir, { recursive: true })
   await writeFile(
     join(recordsDir, `${f.saId}.json`),
     JSON.stringify({
       id: f.saId,
-      rootSessionId: 'root-session-1',
+      rootSessionId: FIX_ROOT_SID,
       agentName: 'explorer',
       sessionFile,
     }),
@@ -120,13 +127,15 @@ describe('extractFinalAssistantText（同源语义白盒）', () => {
 // ---- result action 黑盒（fixture：sa-id manifest 反查主路径） ----
 
 describe('result action（U6）', () => {
-  let dir: string
+  let dataDir: string
+  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻）
 
   beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'session-reader-result-'))
+    dataDir = await mkdtemp(join(tmpdir(), 'session-reader-result-'))
+    dir = join(dataDir, 'agent')
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('1. 单 id：返回纯正文（无包装），details 带元数据（sessionId=header 真实 id）', async () => {
@@ -250,7 +259,7 @@ describe('result action（U6）', () => {
     )
     expect(cut.content[0]?.text).toBe(
       'abcde\n\n[truncated 5 of 10 chars — full text: read ' +
-        `${join(dir, 'subagents', SLUG, 'sessions', `${realId}.jsonl`)}` +
+        `${join(resolveStoreSubagentSessionsDir(dir, FIX_ROOT_SID), `${realId}.jsonl`)}` +
         ', or session_read { action:"detail", session:"sa-lim" }]',
     )
     const exact = await handleSessionRead(
@@ -267,7 +276,7 @@ describe('result action（U6）', () => {
     }
   })
 
-  it('6. 不存在 id：sa-id 无 manifest → zcode_record_not_found（U9 统一错误面）；uuid 片段零匹配 → 无匹配 session', async () => {
+  it('6. 不存在 id：sa-id 无 manifest → zcode_record_not_found（U9 统一错误范围）；uuid 片段零匹配 → 无匹配 session', async () => {
     await expect(
       handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, { agentDir: dir }),
     ).rejects.toThrow(/zcode_record_not_found/)

package/src/__tests__/roots.test.ts

@@ -4,6 +4,8 @@ import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
 import { join, dirname } from 'node:path'
 import {
   resolveSessionRoots,
+  resolveSessionStoreRoot,
+  resolveStoreSubagentSessionsDir,
   normalizeLiveSessionDir,
   type SessionRoot,
   type SessionRootSignals,
@@ -38,6 +40,9 @@ async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n
 /** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾） */
 const SLUG = '--Users-foo--'
 
+/** taiji 用例的存储树分区 sid fixture（合法 pi sid 形态）。 */
+const TAIJI_SID = '0aaaaaaa-bbbb-7ccc-dddd-0000000000t1'
+
 describe('main 根过滤（原 listMainSessions 等价式，A3 退役后保覆盖）', () => {
   let dir: string
 
@@ -124,24 +129,26 @@ describe('main 根过滤（原 listMainSessions 等价式，A3 退役后保覆
   })
 })
 
-describe('subagent 根选择（原 listSubagentSessions 等价式，A3 退役后保覆盖）', () => {
-  let dir: string
+describe('subagent 根选择（原 listSubagentSessions 等价式，A3 退役后保覆盖；[session-store-layout-inversion] 单新根）', () => {
+  let dataDir: string
+  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻）
 
   beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'roots-sub-test-'))
+    dataDir = await mkdtemp(join(tmpdir(), 'roots-sub-test-'))
+    dir = join(dataDir, 'agent')
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
-  it('扫描 subagents/<slug>/sessions/*.jsonl，排除 .finalized', async () => {
-    const slug = '--Users-foo--'
-    await mkdir(join(dir, 'subagents', slug, 'sessions'), { recursive: true })
-    await writeFile(join(dir, 'subagents', slug, 'sessions', 'c.jsonl'), '{"type":"session"}\n')
-    await writeFile(
-      join(dir, 'subagents', slug, 'sessions', 'c.jsonl.finalized'),
-      '{"type":"session"}\n',
-    )
+  /** 存储树分区 sid fixture（合法 pi sid 形态）。 */
+  const SID_P = '0aaaaaaa-bbbb-7ccc-dddd-0000000000p1'
+
+  it('扫描存储树 <root>/<sid>/subagents/sessions/*.jsonl，排除 .finalized', async () => {
+    const sessionsDir = resolveStoreSubagentSessionsDir(dir, SID_P)
+    await mkdir(sessionsDir, { recursive: true })
+    await writeFile(join(sessionsDir, 'c.jsonl'), '{"type":"session"}\n')
+    await writeFile(join(sessionsDir, 'c.jsonl.finalized'), '{"type":"session"}\n')
 
     const result = await subagentSessionFiles(dir)
     expect(result).toHaveLength(1)
@@ -149,21 +156,47 @@ describe('subagent 根选择（原 listSubagentSessions 等价式，A3 退役后
     expect(result[0].path.endsWith('.finalized')).toBe(false)
   })
 
-  it('records/ 子目录（.json manifest）不被误收', async () => {
-    const slug = '--Users-foo--'
-    await mkdir(join(dir, 'subagents', slug, 'records'), { recursive: true })
-    await mkdir(join(dir, 'subagents', slug, 'sessions'), { recursive: true })
-    await writeFile(join(dir, 'subagents', slug, 'records', 'manifest.json'), '{}\n')
-    await writeFile(join(dir, 'subagents', slug, 'sessions', 'sub.jsonl'), '{"type":"session"}\n')
+  it('records/ 子目录（.json manifest）不被误收（同分区固定位置只探 sessions/）', async () => {
+    const { resolveStoreSubagentRecordsDir } = await import('../discovery/roots.js')
+    await mkdir(resolveStoreSubagentRecordsDir(dir, SID_P), { recursive: true })
+    const sessionsDir = resolveStoreSubagentSessionsDir(dir, SID_P)
+    await mkdir(sessionsDir, { recursive: true })
+    await writeFile(join(resolveStoreSubagentRecordsDir(dir, SID_P), 'manifest.json'), '{}\n')
+    await writeFile(join(sessionsDir, 'sub.jsonl'), '{"type":"session"}\n')
 
     const result = await subagentSessionFiles(dir)
     expect(result).toHaveLength(1)
     expect(result[0].path.endsWith('sub.jsonl')).toBe(true)
   })
 
-  it('无 subagents 目录返回 []，不抛错', async () => {
+  it('非会话分区目录（isPiSessionId 不过）剪枝跳过，不进 subagent 根候选', async () => {
+    // 非法分区名（前导 - 违反首字符规则；btw 虚拟 id 冒号形态同拒）
+    for (const bogus of ['-bogus', 'btw:0aaa']) {
+      const bogusDir = join(resolveSessionStoreRoot(dir), bogus, 'subagents', 'sessions')
+      await mkdir(bogusDir, { recursive: true })
+      await writeFile(join(bogusDir, 'x.jsonl'), '{"type":"session"}\n')
+    }
+    const okDir = resolveStoreSubagentSessionsDir(dir, SID_P)
+    await mkdir(okDir, { recursive: true })
+    await writeFile(join(okDir, 'ok.jsonl'), '{"type":"session"}\n')
+
+    const result = await subagentSessionFiles(dir)
+    expect(result).toHaveLength(1)
+    expect(result[0]!.path.endsWith('ok.jsonl')).toBe(true)
+  })
+
+  it('无存储树目录返回 []，不抛错', async () => {
     await expect(subagentSessionFiles(dir)).resolves.toEqual([])
   })
+
+  it('D6 单新根锚定：旧布局 <agentDir>/subagents 造会话文件不被扫描（存量不可见）', async () => {
+    // 旧布局存量原位保留（D6 裁决：不迁移、不再读写）
+    const legacyDir = join(dir, 'subagents', '--legacy-cwd--', 'sessions')
+    await mkdir(legacyDir, { recursive: true })
+    await writeFile(join(legacyDir, 'legacy.jsonl'), '{"type":"session"}\n')
+
+    expect(await subagentSessionFiles(dir)).toEqual([])
+  })
 })
 
 // ============================================================
@@ -222,7 +255,8 @@ const HOST_CASES: HostCase[] = [
       const agentDir = join(dataDir, 'agent')
       await writeJsonl(join(agentDir, 'sessions', SLUG, 'x.jsonl'))
       await writeJsonl(join(dataDir, 'sessions', 'old.jsonl')) // 旧旧布局迁移残留（§6.13 U1 行）
-      await writeJsonl(join(agentDir, 'subagents', SLUG, 'sessions', 's.jsonl'))
+      // [session-store-layout-inversion] subagent 会话在新布局存储树（生产同源推导落盘）
+      await writeJsonl(join(resolveStoreSubagentSessionsDir(agentDir, TAIJI_SID), 's.jsonl'))
       return { agentDir, signals: { agentDir, liveSessionDir: join(agentDir, 'sessions') } }
     },
     verify({ agentDir, tmp }, roots) {
@@ -273,11 +307,12 @@ describe('resolveSessionRoots', () => {
       const { agentDir, signals } = await build(tmp)
       const roots = await resolveSessionRoots(signals)
 
-      // ④ subagent 根恒在（常量推导，不来自任何信号，§6.1 信号 5）
+      // ④ subagent 根恒在（常量推导，不来自任何信号，§6.1 信号 5）；
+      // [session-store-layout-inversion] 根 = session 存储树（dirname(agentDir)/ext-sessions）
       const sub = roots.find((r) => r.kind === 'subagent')
       expect(sub).toBeDefined()
       expect(sub!.source).toBe('subagent')
-      expect(sub!.path).toBe(join(agentDir, 'subagents'))
+      expect(sub!.path).toBe(resolveSessionStoreRoot(agentDir))
 
       // ⑤ 已扫描根 fileCount/scanMs 恒填充且与 files 一致；被去重根不产生扫描统计
       for (const r of roots) {
@@ -389,8 +424,11 @@ describe('resolveSessionRoots options（u8：subagents 模式）', () => {
     const agentDir = join(tmp, 'agent')
     await mkdir(join(agentDir, 'sessions', SLUG), { recursive: true })
     await writeFile(join(agentDir, 'sessions', SLUG, 'a.jsonl'), '{"type":"session"}\n')
-    await mkdir(join(agentDir, 'subagents', SLUG, 'sessions'), { recursive: true })
-    await writeFile(join(agentDir, 'subagents', SLUG, 'sessions', 's.jsonl'), '{"type":"session"}\n')
+    await mkdir(resolveStoreSubagentSessionsDir(agentDir, '0aaaaaaa-bbbb-7ccc-dddd-0000000000o1'), { recursive: true })
+    await writeFile(
+      join(resolveStoreSubagentSessionsDir(agentDir, '0aaaaaaa-bbbb-7ccc-dddd-0000000000o1'), 's.jsonl'),
+      '{"type":"session"}\n',
+    )
     return { tmp, agentDir }
   }
 
@@ -428,8 +466,8 @@ describe('resolveSessionRoots options（u8：subagents 模式）', () => {
   })
 
   it('重复调用每次实扫（无缓存）：两次结果独立完整，files 恒非空实扫值', async () => {
-    // 原三个 cache 用例（set 回写 / 命中优先 / stat × cache）随缓存注入面删除
-    // （ext-simplify-04 U3）；本用例钉死删除后契约——不存在任何缓存层
+    // 原三个 cache 用例（set 回写 / 命中优先 / stat × cache）随缓存注入点删除
+    // （ext-simplify-04 U3）；本用例固定删除后契约——不存在任何缓存层
     const { tmp, agentDir } = await buildMinimalFixture()
     try {
       const first = await resolveSessionRoots({ agentDir })