@zhushanwen/pi-session-reader 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -18,7 +18,7 @@
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "0.6.0"
+    "@zhushanwen/subagent-core": "0.7.1"
   },
   "files": [
     "index.ts",

package/src/__tests__/env.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect } from 'vitest'
+import {
+  detectEnvironment,
+  XYZ_AGENT_EXT_LOG_ENV,
+  PI_CODING_AGENT_DIR_ENV,
+  XYZ_AGENT_DATA_DIR_ENV,
+  type EnvironmentSignals,
+} from '../discovery/env.js'
+
+/**
+ * U2 环境判定单测（design §6.2 / §4.4）。detectEnvironment 是纯函数：
+ * 全部信号为构造的字面量字符串，无任何 fs / 真实数据目录触碰。
+ */
+
+/** 构造信号包的基线：agentDir 用假路径，不指向任何真实目录 */
+function signals(overrides: Partial<EnvironmentSignals> = {}): EnvironmentSignals {
+  return {
+    env: {},
+    agentDir: '/tmp/nonexistent-fixture/.pi/agent',
+    ...overrides,
+  }
+}
+
+describe('detectEnvironment 托管合取判定', () => {
+  it('双信号齐备 + B 后新布局 <dataDir>/agent → xyz-agent（packaged）', () => {
+    const r = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent/agent',
+        },
+        bundleUrl:
+          'file:///Applications/TaiJi.app/Contents/Resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
+      }),
+    )
+    expect(r.kind).toBe('xyz-agent')
+    expect(r.distribution).toBe('packaged')
+    expect(r.dataDir).toBe('/Users/u/.xyz-agent')
+  })
+
+  it('双信号齐备 + B 前旧布局 <dataDir>/pi/agent → xyz-agent（迁移窗口期双形态兼容）', () => {
+    const r = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent-dev/pi/agent',
+        },
+        bundleUrl: 'file:///Users/u/Code/xyz-agent/extensions/universal/session-reader/src/index.ts',
+      }),
+    )
+    expect(r.kind).toBe('xyz-agent')
+    expect(r.distribution).toBe('dev')
+    expect(r.dataDir).toBe('/Users/u/.xyz-agent-dev')
+  })
+
+  it('透传污染反例 1：仅 XYZ_AGENT_EXT_LOG=1（PI_CODING_AGENT_DIR 未设）→ standalone-pi，evidence 点名孤置信号', () => {
+    const r = detectEnvironment(
+      signals({ env: { [XYZ_AGENT_EXT_LOG_ENV]: '1' } }),
+    )
+    expect(r.kind).toBe('standalone-pi')
+    expect(r.dataDir).toBeUndefined()
+    const joined = r.evidence.join('\n')
+    expect(joined).toContain(`${XYZ_AGENT_EXT_LOG_ENV}='1' → 命中`)
+    expect(joined).toContain('单独成立不合取')
+    expect(joined).toContain(XYZ_AGENT_EXT_LOG_ENV)
+  })
+
+  it('透传污染反例 2：仅 XYZ_AGENT_EXT_LOG=1 且 PI_CODING_AGENT_DIR 为裸 pi 形态 → standalone-pi', () => {
+    const r = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/home/u/.pi/agent',
+        },
+      }),
+    )
+    expect(r.kind).toBe('standalone-pi')
+    expect(r.evidence.join('\n')).toContain('形态不匹配')
+  })
+
+  it('透传污染反例 3：仅 PI_CODING_AGENT_DIR 形态匹配（EXT_LOG 未设）→ standalone-pi，evidence 点名孤置信号', () => {
+    const r = detectEnvironment(
+      signals({
+        env: { [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent/agent' },
+      }),
+    )
+    expect(r.kind).toBe('standalone-pi')
+    expect(r.dataDir).toBeUndefined()
+    const joined = r.evidence.join('\n')
+    expect(joined).toContain('形态匹配')
+    expect(joined).toContain('单独成立不合取')
+    expect(joined).toContain(PI_CODING_AGENT_DIR_ENV)
+  })
+
+  it('XYZ_AGENT_EXT_LOG 非 1 值（如 0 / true）不构成命中', () => {
+    for (const value of ['0', 'true', '']) {
+      const r = detectEnvironment(
+        signals({
+          env: {
+            [XYZ_AGENT_EXT_LOG_ENV]: value,
+            [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent/agent',
+          },
+        }),
+      )
+      expect(r.kind, `EXT_LOG='${value}' 不应判托管`).toBe('standalone-pi')
+    }
+  })
+
+  it('形态防误报：无点前缀 xyz-agent、嵌套浅段不匹配', () => {
+    for (const dir of ['/home/u/xyz-agent/agent', '/home/u/.xyz/agent', '/.pi/agent']) {
+      const r = detectEnvironment(
+        signals({
+          env: {
+            [XYZ_AGENT_EXT_LOG_ENV]: '1',
+            [PI_CODING_AGENT_DIR_ENV]: dir,
+          },
+        }),
+      )
+      expect(r.kind, `${dir} 不应判托管`).toBe('standalone-pi')
+    }
+  })
+})
+
+describe('detectEnvironment distribution（bundle 路径三态）', () => {
+  it('.app/Contents/Resources/extensions/ → packaged', () => {
+    const r = detectEnvironment(
+      signals({
+        bundleUrl:
+          'file:///Applications/TaiJi.app/Contents/Resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
+      }),
+    )
+    expect(r.distribution).toBe('packaged')
+  })
+
+  it('Windows/Linux 安装资源目录 resources/extensions/ → packaged', () => {
+    const r = detectEnvironment(
+      signals({
+        bundleUrl:
+          'file:///C:/Users/u/AppData/Local/Programs/taiji/resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
+      }),
+    )
+    expect(r.distribution).toBe('packaged')
+  })
+
+  it('仓库路径（源码与 dev staged 资源根两种）→ dev，staged 根不被误判 packaged', () => {
+    for (const url of [
+      'file:///Users/u/Code/xyz-agent/extensions/universal/session-reader/src/index.ts',
+      'file:///Users/u/Code/xyz-agent/apps/electron/resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
+    ]) {
+      const r = detectEnvironment(signals({ bundleUrl: url }))
+      expect(r.distribution, `${url} 应判 dev`).toBe('dev')
+    }
+  })
+
+  it('bundleUrl 缺失 → null（不猜）', () => {
+    const r = detectEnvironment(signals({}))
+    expect(r.distribution).toBeNull()
+    expect(r.evidence.join('\n')).toContain('无法判定')
+  })
+})
+
+describe('detectEnvironment dataDir 推导', () => {
+  it('托管：XYZ_AGENT_DATA_DIR 优先于 PI_CODING_AGENT_DIR 剥层', () => {
+    const r = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/pi/agent',
+          [XYZ_AGENT_DATA_DIR_ENV]: '/data/.xyz-agent',
+        },
+      }),
+    )
+    expect(r.kind).toBe('xyz-agent')
+    expect(r.dataDir).toBe('/data/.xyz-agent')
+    expect(r.evidence.join('\n')).toContain(`来源：${XYZ_AGENT_DATA_DIR_ENV}`)
+  })
+
+  it('托管：无 DATA_DIR 时按布局剥层——新布局剥一层、旧布局剥两层', () => {
+    const newLayout = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/agent',
+        },
+      }),
+    )
+    expect(newLayout.dataDir).toBe('/data/.xyz-agent')
+
+    const oldLayout = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/pi/agent',
+        },
+      }),
+    )
+    expect(oldLayout.dataDir).toBe('/data/.xyz-agent')
+  })
+
+  it('standalone：即使 XYZ_AGENT_DATA_DIR 被设置也恒 undefined', () => {
+    const r = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_DATA_DIR_ENV]: '/data/.xyz-agent',
+        },
+      }),
+    )
+    expect(r.kind).toBe('standalone-pi')
+    expect(r.dataDir).toBeUndefined()
+  })
+})
+
+describe('detectEnvironment evidence', () => {
+  const scenarios: Array<[string, EnvironmentSignals]> = [
+    ['全信号缺失', signals({})],
+    ['托管全信号', signals({
+      env: {
+        [XYZ_AGENT_EXT_LOG_ENV]: '1',
+        [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/agent',
+        [XYZ_AGENT_DATA_DIR_ENV]: '/data/.xyz-agent',
+      },
+      bundleUrl:
+        'file:///Applications/TaiJi.app/Contents/Resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
+    })],
+    ['EXT_LOG 孤置', signals({ env: { [XYZ_AGENT_EXT_LOG_ENV]: '1' } })],
+    ['agentDir 孤置', signals({ env: { [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/agent' } })],
+    ['bundleUrl 缺失', signals({})],
+  ]
+
+  it('各场景 evidence 恒非空', () => {
+    for (const [name, s] of scenarios) {
+      const r = detectEnvironment(s)
+      expect(r.evidence.length, `${name} 场景 evidence 不应为空`).toBeGreaterThan(0)
+    }
+  })
+
+  it('每条信号的原文（命中与否）都在 evidence 中', () => {
+    const r = detectEnvironment(
+      signals({
+        env: {
+          [XYZ_AGENT_EXT_LOG_ENV]: '0',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/pi/agent',
+        },
+        agentDir: '/data/.xyz-agent/pi/agent',
+      }),
+    )
+    const joined = r.evidence.join('\n')
+    // 未命中信号：原文 + 未命中注记
+    expect(joined).toContain(`${XYZ_AGENT_EXT_LOG_ENV}='0' → 未命中`)
+    // 命中信号：原文 + 匹配注记
+    expect(joined).toContain(`${PI_CODING_AGENT_DIR_ENV}='/data/.xyz-agent/pi/agent'`)
+    expect(joined).toContain('形态匹配')
+    // 第三条输入：agentDir 透传记录
+    expect(joined).toContain(`agentDir='/data/.xyz-agent/pi/agent'`)
+    // 判定结论行
+    expect(joined).toContain('standalone-pi')
+  })
+})

package/src/__tests__/execution-tree.test.ts

@@ -18,7 +18,7 @@ import { buildExecutionTree, formatExecutionTreeText, type ExecutionTreeNode } f
  * - TC-m3b-cycle-detection：workflow 指针环（A→B→A），visited Set 防环
  * - TC-m3b-single-node：单节点树（无后代，ES5）
  * - TC-m3b-source-priority：parentRecordId 三级数据源优先级（manifest>identity>flat，DM4）
- * - TC-m3b-real-data-guard：本机真实数据 flat 回退（旧机制，skipIf CI 无数据）
+ * - TC-m3b-real-data-guard：本机真实语料解析不抛错、root 定位正确（skipIf CI 无数据）
  */
 
 // ---- fixture 常量（uuid 特征，互不为子串，满足 extractSessionIdFromFilename）----
@@ -692,17 +692,18 @@ describe('buildExecutionTree - fixture', () => {
 // ============================================================
 
 describe.skipIf(!HAS_REAL)('buildExecutionTree - 真实数据守卫', () => {
-  it('TC-m3b-real-data-guard：本机旧机制数据 flat 回退，不抛错，totalNodes>1', async () => {
+  it('TC-m3b-real-data-guard：本机真实语料解析不抛错，root 定位正确', async () => {
     // 取一个真实存在的 main session（FAM 是 fork 家族根）
     const FAM = '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7'
     const tree = await buildExecutionTree(FAM, REAL_AGENT_DIR)
-    // 旧机制：sourceMode='flat-fallback'（全无 parentRecordId）
-    expect(tree.sourceMode).toBe('flat-fallback')
-    // 有 subagent 后代（本机 3610 record，FAM 树非空）
-    expect(tree.totalNodes).toBeGreaterThan(1)
-    // 不抛错（已隐含：到这行说明成功）
+    // [HISTORICAL] 只断言与宿主数据纪元无关的不变量：sourceMode / totalNodes 取决于 FAM
+    // 家族在 subagents/**/records 下的 manifest 存量，会被 pi GC 清空（2026-09-11 实测该
+    // 家族 records/ 已空 → related=[] → sourceMode='precise'、totalNodes=1，原 flat-fallback
+    // + totalNodes>1 断言随数据演化假红）。flat-fallback 语义由 fixture 用例
+    // TC-m3b-flat-fallback 确定性覆盖，不依赖本机可变语料。
     expect(tree.root.type).toBe('main')
     expect(tree.root.sessionId).toBe(FAM)
+    expect(tree.totalNodes).toBeGreaterThanOrEqual(1)
   }, 60000)
 })
 

package/src/__tests__/find.test.ts

@@ -1,9 +1,9 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 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 { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR } from './real-data.js'
+import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR, REAL_DATA_TIMEOUT_MS } from './real-data.js'
 
 /**
  * 建一个假 session 文件：首行 header（type=session，含 id/cwd/parentSession），
@@ -523,7 +523,7 @@ describe('findSessions', () => {
         expect(matches.every((m) => m.source === 'subagent')).toBe(true)
         expect(typeof truncated).toBe('boolean')
       },
-      30000,
+      REAL_DATA_TIMEOUT_MS,
     )
   })
 
@@ -536,7 +536,7 @@ describe('findSessions', () => {
     expect(hit.fileName).toContain('019e6c96')
     expect(hit.mtime).toBeGreaterThan(0)
     expect(hit.sizeBytes).toBeGreaterThan(0)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 
   it.skipIf(!HAS_E6)("真实数据：recent 返回最近 N 个，mtime 倒序，truncated=true", async () => {
     const { matches, truncated } = await findSessions('recent', REAL_AGENT_DIR, { limit: 5 })
@@ -548,7 +548,7 @@ describe('findSessions', () => {
     }
     // 真实 session 文件远多于 5 → 截断
     expect(truncated).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 
   it.skipIf(!HAS_REAL_SUBAGENTS_DIR)(
     "真实数据：source:'subagent' 能找到 completed subagent（§7 场景 1 find 部分）",
@@ -564,6 +564,211 @@ describe('findSessions', () => {
         expect(m.fileName).toContain('subagents')
       }
     },
-    30000,
+    REAL_DATA_TIMEOUT_MS,
   )
 })
+
+// ============================================================
+// u11：标题元数据 metadataProvider 注入（design 2026-09-10 §6.6）
+// 覆盖三条调用策略中的 ①惰性 ②窄化（TTL 缓存句柄在 tool-handler 注入侧，
+// 见 tool-handler.test.ts u11 段）+ 两条 guard + §11.3b 多目录合并语义
+// + 纯 TS 首条 user 降级路径保留。
+// provider 一律注入替身（不真调 pi SessionManager）。
+// ============================================================
+describe('u11 标题元数据（metadataProvider 注入，§6.6）', () => {
+  let root: string
+  let agentDir: string
+  /** 平铺 main 根（xyz-agent 形态：session 直在 sessions/ 下，[default] 根无子目录） */
+  let flatMain: string
+  /** legacy 根（dirname(agentDir)/sessions） */
+  let legacyDir: string
+
+  async function writeSession(
+    dir: string,
+    opts: { name: string; id: string; cwd?: string; firstUserText?: string },
+  ): Promise<string> {
+    await mkdir(dir, { recursive: true })
+    const lines = [JSON.stringify({ type: 'session', id: opts.id, cwd: opts.cwd ?? '/demo' })]
+    if (opts.firstUserText !== undefined) {
+      lines.push(
+        JSON.stringify({
+          type: 'message',
+          id: `${opts.id}-m1`,
+          message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
+        }),
+      )
+    }
+    const path = join(dir, opts.name)
+    await writeFile(path, lines.join('\n') + '\n')
+    return path
+  }
+
+  beforeEach(async () => {
+    // agentDir 挂在 mkdtemp 子目录下，legacy 根（dirname(agentDir)/sessions）仍在
+    // 自建 tmp 树内，不污染共享 tmpdir（也不受其他用例残留影响）
+    root = await mkdtemp(join(tmpdir(), 'find-u11-'))
+    agentDir = join(root, 'agent')
+    flatMain = join(agentDir, 'sessions')
+    legacyDir = join(root, 'sessions')
+  })
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('① 惰性触发：uuid 精确/归一化路径不调 provider（spy 计数 0）', async () => {
+    await writeSession(flatMain, { name: 'a.jsonl', id: '019cafe00001', firstUserText: '无关' })
+    const provider = vi.fn(async () => [])
+    // 精确子串层命中
+    await findSessions('019cafe00001', agentDir, { metadataProvider: provider })
+    expect(provider).not.toHaveBeenCalled()
+    // 归一化层命中（大写变体：精确层大小写敏感 0 命中，norm 层命中后短路）
+    await findSessions('019CAFE00001', agentDir, { metadataProvider: provider })
+    expect(provider).not.toHaveBeenCalled()
+  })
+
+  it('② keyword 路径调用 provider 且标题进匹配（name 命中，preview 取元数据首消息免深读）', async () => {
+    const pathA = await writeSession(flatMain, {
+      name: 'a.jsonl',
+      id: 'title-aaaa',
+      firstUserText: '首消息完全无关',
+    })
+    await writeSession(flatMain, { name: 'b.jsonl', id: 'title-bbbb', firstUserText: '另一个无关会话' })
+    const provider = vi.fn(async (dir: string) =>
+      dir === flatMain
+        ? [
+            {
+              path: pathA,
+              id: 'title-aaaa',
+              cwd: '/demo',
+              name: '福耀玻璃深度研究',
+              modified: new Date('2026-09-01'),
+              firstMessage: '首消息完全无关',
+            },
+          ]
+        : [],
+    )
+    const { matches } = await findSessions('福耀玻璃', agentDir, { metadataProvider: provider })
+    // 平铺存在的 [default] 根被调用，且永传非空串
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    expect(provider.mock.calls[0][0].length).toBeGreaterThan(0)
+    // 标题命中：name 透传 + preview 取元数据 firstMessage
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('title-aaaa')
+    expect(matches[0].name).toBe('福耀玻璃深度研究')
+    expect(matches[0].firstMessagePreview).toBe('首消息完全无关')
+  })
+
+  it('③ 窄化：含子目录根跳过 provider，候选不退出 keyword 匹配（回退首条 user，标题留空）', async () => {
+    // 纯 pi 形态：文件在 encodeCwd 子目录 → [default] 根含子目录 → listAll 跳过
+    await writeSession(join(flatMain, '--Users-demo--'), {
+      name: 'a.jsonl',
+      id: 'nested-aaaa',
+      firstUserText: '重构插件架构 plugin review',
+    })
+    const provider = vi.fn(async () => [])
+    const { matches } = await findSessions('plugin', agentDir, { metadataProvider: provider })
+    expect(provider).not.toHaveBeenCalled()
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('nested-aaaa')
+    expect(matches[0].firstMessagePreview).toContain('plugin')
+    // 标题维度降级留空：「能找到 session」不受影响（§6.6 降级路径）
+    expect(matches[0].name).toBeUndefined()
+  })
+
+  it('④ guard：provider 抛错降级（标题留空 + 不抛，回退首条 user 匹配）', async () => {
+    await writeSession(flatMain, {
+      name: 'a.jsonl',
+      id: 'err-aaaa',
+      firstUserText: '按首条消息命中的文本',
+    })
+    const provider = vi.fn(async () => {
+      throw new Error('listAll boom')
+    })
+    const { matches } = await findSessions('按首条消息命中', agentDir, {
+      metadataProvider: provider,
+    })
+    expect(provider).toHaveBeenCalledTimes(1) // 调用了但抛错
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('err-aaaa')
+    expect(matches[0].name).toBeUndefined()
+    expect(matches[0].firstMessagePreview).toContain('按首条消息命中')
+  })
+
+  it('⑤ 多目录结果合并：按 id 去重、重复取新 modified（§11.3b）', async () => {
+    const pathA = await writeSession(flatMain, {
+      name: 'a.jsonl',
+      id: 'dup-id-0001',
+      firstUserText: '无关',
+    })
+    // legacy 根平铺存在（0 文件也算存在根，isFlatRoot 空集恒真）
+    await mkdir(legacyDir, { recursive: true })
+    const provider = vi.fn(async (dir: string) =>
+      dir === flatMain
+        ? [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '旧标题', modified: 1000 }]
+        : [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '新标题', modified: 2000 }],
+    )
+    const { matches } = await findSessions('新标题', agentDir, { metadataProvider: provider })
+    expect(provider).toHaveBeenCalledTimes(2) // 两个平铺存在的根各一次
+    expect(matches).toHaveLength(1)
+    expect(matches[0].name).toBe('新标题') // 同 id 重复 → 取新 modified 的条目
+    const miss = await findSessions('旧标题', agentDir, { metadataProvider: provider })
+    expect(miss.matches).toHaveLength(0) // 旧条目已按合并规则丢弃
+  })
+
+  it('⑥ guard：仅对存在的根调用且永传非空串（不存在根 / 不存在 liveSessionDir 不调）', async () => {
+    await writeSession(flatMain, { name: 'a.jsonl', id: 'guard-aaaa', firstUserText: '无关' })
+    const provider = vi.fn(async () => [])
+    await findSessions('zzznohit9q', agentDir, {
+      liveSessionDir: join(agentDir, 'no-such-dir'),
+      metadataProvider: provider,
+    })
+    // 仅平铺存在的 [default] 根被调；不存在的 liveSessionDir 与 [legacy] 根均被排除
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    expect(provider.mock.calls.every((c) => typeof c[0] === 'string' && c[0].length > 0)).toBe(true)
+  })
+
+  it('⑥b liveSessionDir 与平铺根同字面路径 → 同目录只调一次（字面路径去重）', async () => {
+    await writeSession(flatMain, { name: 'a.jsonl', id: 'dedup-aaaa', firstUserText: '无关' })
+    const provider = vi.fn(async () => [])
+    await findSessions('zzznohit9q', agentDir, {
+      liveSessionDir: flatMain,
+      metadataProvider: provider,
+    })
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+  })
+
+  it('⑦ recent：仅对 limit 截断后的少数候选补元数据（旧候选所在根不调）', async () => {
+    const pNew1 = await writeSession(flatMain, { name: 'n1.jsonl', id: 'recent-new-1' })
+    const pNew2 = await writeSession(flatMain, { name: 'n2.jsonl', id: 'recent-new-2' })
+    await writeSession(legacyDir, { name: 'o1.jsonl', id: 'recent-old-1' })
+    await writeSession(legacyDir, { name: 'o2.jsonl', id: 'recent-old-2' })
+    const base = Math.floor(Date.now() / 1000)
+    await utimes(pNew1, base + 300, base + 300)
+    await utimes(pNew2, base + 200, base + 200)
+    await utimes(join(legacyDir, 'o1.jsonl'), base + 100, base + 100)
+    await utimes(join(legacyDir, 'o2.jsonl'), base + 50, base + 50)
+    const provider = vi.fn(async (dir: string) =>
+      dir === flatMain
+        ? [
+            { path: pNew1, id: 'recent-new-1', cwd: '/demo', name: '最新标题一', modified: (base + 300) * 1000 },
+            { path: pNew2, id: 'recent-new-2', cwd: '/demo', name: '最新标题二', modified: (base + 200) * 1000 },
+          ]
+        : [],
+    )
+    const { matches, truncated } = await findSessions('recent', agentDir, {
+      limit: 2,
+      metadataProvider: provider,
+    })
+    expect(truncated).toBe(true)
+    expect(matches.map((m) => m.sessionId)).toEqual(['recent-new-1', 'recent-new-2'])
+    // provider 只调最新两个候选所在的平铺根；被截断的 legacy 根候选不触发补元数据
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    // 截断后少数候选补到标题
+    expect(matches[0].name).toBe('最新标题一')
+    expect(matches[1].name).toBe('最新标题二')
+  })
+})