@zhushanwen/pi-session-reader 0.4.0 → 0.5.0

package/src/discovery/roots.ts

@@ -1,6 +1,7 @@
-import { readdir, stat } from 'node:fs/promises'
+import { readdir, stat, realpath } from 'node:fs/promises'
 import type { Dirent } from 'node:fs'
-import { join } from 'node:path'
+import { join, basename, dirname } from 'node:path'
+import { performance } from 'node:perf_hooks'
 
 /**
  * M2 discovery 发现层：文件系统扫描（design §3.3 D-5 首行扫描策略的文件定位部分）。
@@ -8,7 +9,226 @@ import { join } from 'node:path'
  * agentDir 注入：本模块所有函数接收 `agentDir: string` 参数，**不调用** `getAgentDir()`
  *（pi SDK，调用留到 M3 tool-adapter 层）。故本模块零 pi 依赖，仅 node:fs + 相对
  * import M1 core，可完全单测。
+ *
+ * U1（design 2026-09-10 §6.1/§7B）：新增 `resolveSessionRoots(signals)` —— 信号包 →
+ * 带来源标签的候选根列表，逐根扫描、按 realpath 去重（同路径只扫一次，保留最高优先级
+ * kind 标签）。B 收缩（design §6.13）：布局对齐后无 `[env]` 信号，`[default]` 为主根。
+ * 旧签名 `listMainSessions`/`listSubagentSessions` 保留为薄包装（内部构造只含 agentDir
+ * 的信号包 → main 源退化为 `[default]`+`[legacy]` 两根），存量调用（find.ts /
+ * subagents.ts）不破。
+ */
+
+// ============================================================
+// 候选根契约（U1 foundation：后续 doctor / find / family 共享）
+// ============================================================
+
+/** 发现层信号包（index.ts 采集，全部可降级；本模块只消费不采集） */
+export interface SessionRootSignals {
+  /** pi agent 数据目录（两宿主均成立；B 后 xyz-agent = `<dataDir>/agent`） */
+  agentDir: string
+  /**
+   * 宿主已解析的 live session 目录（`ctx.sessionManager.getSessionDir()`，§6.1 信号 1）。
+   * 缺失/undefined 时走三根降级（`[default]`+`[legacy]`+`[subagent]`，§7B 要点 2）。
+   */
+  liveSessionDir?: string
+}
+
+/** 候选根来源标签；kind 优先级 live > default > legacy > subagent（§6.1 信号序） */
+export type SessionRootKind = 'live' | 'default' | 'legacy' | 'subagent'
+
+/** main 源 = 主 session 根（live/default/legacy）；subagent 源 = subagent 会话根 */
+export type SessionRootSource = 'main' | 'subagent'
+
+/** 候选根（含扫描结果）。id 恒等于 kind：去重后每 kind 至多一个根，作 doctor 表行键。 */
+export interface SessionRoot {
+  id: SessionRootKind
+  kind: SessionRootKind
+  /** 规范化后的绝对路径（`[live]` 已剥 encodeCwd 层） */
+  path: string
+  source: SessionRootSource
+  /** 目录是否存在（不存在的根仍列出——doctor 表「存在」列与三根降级可见性需要） */
+  exists: boolean
+  /** 扫描所得 .jsonl 数（= files.length）；未扫描（被去重）时 undefined */
+  fileCount?: number
+  /** 本根 scanJsonlRecursive 耗时 ms；未扫描时 undefined */
+  scanMs?: number
+  /** 扫描所得文件列表（design §7B 要点 8「本就在返回值里」）；未扫描时空数组 */
+  files: SessionFileMeta[]
+  /**
+   * realpath 与更高优先级根同路径 → 指向保留根的 id，本根未扫描（doctor 渲染
+   * 「与 N 同路径，已去重」注记的依据，§7B 要点 4）。
+   */
+  dedupedInto?: SessionRootKind
+  /**
+   * 本根数据来自调用方注入缓存（resolveSessionRoots options.cache 命中）：fileCount/
+   * scanMs/exists 取缓存值，files 恒空数组——消费方不得把 cached 根的 files 当实扫
+   * 结果（u8 追加：doctor「同一数据源两处渲染」统一走 resolveSessionRoots，缓存语义
+   * 由调用方注入，§6.3）。
+   */
+  cached?: boolean
+}
+
+/** 各根固定子目录名（常量推导，不来自信号——§6.1 信号 5） */
+const SESSIONS_DIRNAME = 'sessions'
+const SUBAGENTS_DIRNAME = 'subagents'
+
+/**
+ * `[live]` 规范化（§6.1/§7B 要点 3）：`getSessionDir()` 在纯 pi 返回按 cwd 编码的子目录
+ *（`<agentDir>/sessions/--Users-x--`），在 xyz-agent 覆盖态返回根本身。判据：basename
+ * 匹配 encodeCwd 形态（`--` 开头 `--` 结尾，实证见 `~/.pi/agent/sessions/` 全部子目录
+ * 与 real-data.ts）则取 dirname，否则取自身。
  */
+export function normalizeLiveSessionDir(liveSessionDir: string): string {
+  const base = basename(liveSessionDir)
+  return base.startsWith('--') && base.endsWith('--')
+    ? dirname(liveSessionDir)
+    : liveSessionDir
+}
+
+/**
+ * 从信号包推导候选根（未扫描骨架），数组序 = 优先级序（§6.1）。
+ * `[subagent]` 恒在（常量推导）；`[live]` 仅在信号存在时出现。
+ */
+function sessionRootSpecs(signals: SessionRootSignals): SessionRoot[] {
+  // 空 agentDir 防御：派生式会退化为 cwd 相对路径（'sessions'/'./sessions'），可能扫到
+  // 进程 cwd 下的无关目录——宁缺毋错（§11.14 空 agentDir 自举由宿主层兜底）
+  if (signals.agentDir.length === 0) return []
+  const specs: SessionRoot[] = []
+  if (signals.liveSessionDir !== undefined && signals.liveSessionDir.length > 0) {
+    specs.push(spec('live', 'main', normalizeLiveSessionDir(signals.liveSessionDir)))
+  }
+  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)))
+  return specs
+}
+
+function spec(id: SessionRootKind, source: SessionRootSource, path: string): SessionRoot {
+  return { id, kind: id, source, path, exists: false, files: [] }
+}
+
+/** realpath 解析失败（目录不存在等）→ 回退字面路径作去重键（同字面路径仍可去重） */
+async function safeRealpath(path: string): Promise<string> {
+  try {
+    return await realpath(path)
+  } catch {
+    return path
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const SKIP_DIRS_NONE = new Set<string>()
+
+// ============================================================
+// 扫描 options（u8 追加：doctor「同一数据源两处渲染，不重复实现探测」§6.3——
+// doctor 经 options 驱动 subagent 根不扫与进程内缓存，本模块不内置 TTL/mtime
+// 失效逻辑，缓存语义全部由调用方注入的句柄定义）
+// ============================================================
+
+/** 缓存条目载荷（扫描统计快照；失效判定所需元数据由缓存实现方自持，不进本契约） */
+export interface SessionRootCacheEntry {
+  exists: boolean
+  fileCount: number
+  scanMs: number
+}
+
+/**
+ * 根扫描的进程内缓存句柄（调用方注入）。get 返回 undefined = 未命中（含调用方判定
+ * TTL 到期/目录 mtime 变化后自行淘汰）→ 本模块实扫并 set 回写；命中 → 直接以缓存值
+ * 构造根（cached: true，files 恒空数组）。get/set 允许同步或异步实现。
+ */
+export interface SessionRootCache {
+  get(key: string): Promise<SessionRootCacheEntry | undefined> | SessionRootCacheEntry | undefined
+  set(key: string, value: SessionRootCacheEntry): void | Promise<void>
+}
+
+/** resolveSessionRoots 扫描行为选项（全部可选，缺省 = 既有行为零变化） */
+export interface SessionRootScanOptions {
+  /**
+   * subagent 根扫描模式：`'scan'`（默认，现行为——递归扫出文件数）| `'stat'`
+   *（doctor 默认形态 §6.3——只做存在性检查，fileCount/scanMs 恒 undefined，
+   * 不产缓存条目）。subagent 根在纯 pi 下可达数千文件，doctor 可能被反复询问。
+   */
+  subagents?: 'scan' | 'stat'
+  /** 根扫描缓存句柄（见 SessionRootCache）。缺省 = 每次实扫（find 路径永不传）。 */
+  cache?: SessionRootCache
+}
+
+/**
+ * 解析候选根并逐根扫描（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 契约）。
+ *
+ * options（u8 追加，全部缺省安全）：`subagents:'stat'` 让 subagent 根只做存在性检查；
+ * `cache` 提供进程内缓存句柄（命中即不实扫，cached 根 files 恒空）——cache 命中优先于
+ * 一切实扫，`set` 仅在实扫后回写（命中不回写）。find/F1 路径恒不传 options（自检行
+ * 计数必须取本次实扫，§7B 要点 8 PS-14）。
+ */
+export async function resolveSessionRoots(
+  signals: SessionRootSignals,
+  options?: SessionRootScanOptions,
+): Promise<SessionRoot[]> {
+  const subagentMode = options?.subagents ?? 'scan'
+  const out: SessionRoot[] = []
+  const byRealPath = new Map<string, SessionRoot>()
+  for (const candidate of sessionRootSpecs(signals)) {
+    const key = await safeRealpath(candidate.path)
+    const kept = byRealPath.get(key)
+    if (kept) {
+      // 同 realpath：不扫描，标注归属（exists 与保留根同目录，必然一致）
+      out.push({ ...candidate, exists: kept.exists, dedupedInto: kept.id })
+      continue
+    }
+    if (candidate.source === 'subagent' && subagentMode === 'stat') {
+      // doctor 默认形态（§6.3）：只列路径与可扫性，不产文件数、不入缓存
+      out.push({ ...candidate, exists: await pathExists(candidate.path) })
+      continue
+    }
+    const cached = options?.cache ? await options.cache.get(candidate.path) : undefined
+    if (cached) {
+      // 命中：缓存值即数据源（不实扫、不回写）；files 恒空——消费方不得当实扫结果
+      const root: SessionRoot = {
+        ...candidate,
+        exists: cached.exists,
+        fileCount: cached.fileCount,
+        scanMs: cached.scanMs,
+        cached: true,
+      }
+      byRealPath.set(key, root)
+      out.push(root)
+      continue
+    }
+    const skipDirs = candidate.source === 'main' ? SKIP_DIRS_MAIN : SKIP_DIRS_NONE
+    const t0 = performance.now()
+    const files = await scanJsonlRecursive(candidate.path, skipDirs)
+    const scanMs = performance.now() - t0
+    const exists = await pathExists(candidate.path)
+    if (options?.cache) {
+      await options.cache.set(candidate.path, { exists, fileCount: files.length, scanMs })
+    }
+    const root: SessionRoot = {
+      ...candidate,
+      exists,
+      fileCount: files.length,
+      scanMs,
+      files,
+    }
+    byRealPath.set(key, root)
+    out.push(root)
+  }
+  return out
+}
 
 export interface SessionFileMeta {
   /** 绝对路径 */
@@ -76,20 +296,28 @@ async function scanJsonlRecursive(
 }
 
 /**
- * 列出 agentDir/sessions/ 下所有主 session 文件。
+ * 旧签名薄包装（U1，design §7B 要点 7）：内部构造只含 agentDir 的信号包，main 源退化为
+ * 「`[default]`+`[legacy]`」两根并集。工具运行路径后续单元改走 resolveSessionRoots 新签名，
+ * 本包装仅为存量调用（find.ts / subagents.ts）与外部深 import 保持不破。
+ *
  * 递归扫描子目录（cwd 编码目录如 --Users-foo--），glob *.jsonl，排除 *.jsonl.finalized
  *（design §3.3 D-7 Q2）；跳过 workflow-state 子目录（workflow 运行状态文件，非 session）。
  */
 export async function listMainSessions(agentDir: string): Promise<SessionFileMeta[]> {
-  return scanJsonlRecursive(join(agentDir, 'sessions'), SKIP_DIRS_MAIN)
+  const roots = await resolveSessionRoots({ agentDir })
+  return roots
+    .filter((r) => r.source === 'main' && r.dedupedInto === undefined)
+    .flatMap((r) => r.files)
 }
 
 /**
- * 列出 agentDir/subagents/ 下所有 subagent session 文件（同样排除 .finalized）。
- * 结构：subagents/<cwd编码>/sessions/*.jsonl。records/ 子目录（.json manifest）无 .jsonl，
- * 天然不被误收。
+ * 旧签名薄包装：agentDir 信号包下 `[subagent]` 根 = `<agentDir>/subagents`（常量推导），
+ * 行为与旧实现等价。结构：subagents/<cwd编码>/sessions/*.jsonl。records/ 子目录
+ *（.json manifest）无 .jsonl，天然不被误收。
  */
 export async function listSubagentSessions(agentDir: string): Promise<SessionFileMeta[]> {
-  return scanJsonlRecursive(join(agentDir, 'subagents'), new Set())
+  const roots = await resolveSessionRoots({ agentDir })
+  const sub = roots.find((r) => r.kind === 'subagent')
+  return sub?.files ?? []
 }
 

package/src/discovery/subagents.ts

@@ -4,7 +4,7 @@ import { join, basename } from 'node:path'
 import type { Entry } from '../core/parser.js'
 import type { Family, SessionRef, SubagentRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
-import { listMainSessions, listSubagentSessions, type SessionFileMeta } from './roots.js'
+import { listMainSessions, listSubagentSessions, resolveSessionRoots, type SessionFileMeta } from './roots.js'
 import { resolveWorkflows } from './workflows.js'
 
 /**
@@ -51,11 +51,7 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
 
   // ---- 4-5. build index + resolve（sessionId 不在 byId → resolveFamily 抛 Error）----
   if (!scan.sessionIdToPath.has(sessionId)) {
-    throw new Error(
-      `session "${sessionId}" not found under ${agentDir}/sessions — ` +
-        `no main session file whose first-line header id matches. ` +
-        `Verify the sessionId or agentDir; for partial uuid, use findSessions first.`,
-    )
+    throw new Error(await formatSessionNotFound(sessionId, agentDir))
   }
   const index = buildFamilyIndex(scan.headers, scan.identities, scan.fileStats)
   const family = resolveFamily(sessionId, index)
@@ -71,6 +67,28 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
 // buildFamilyFromFs 扫描阶段 helpers（各阶段显式传入累积器，插入顺序 = 原实现顺序）
 // ============================================================
 
+/**
+ * not-found 错误文案：列出实际扫描过的 main 候选根（U1 并入部分，design §6.1 自证能力
+ * ——「没有这条 session」与「根配错了」必须可区分，错误信息携带发现层内部状态）。
+ * 仅失败路径调用，额外一次 resolveSessionRoots 的扫描成本可接受；根过滤条件与
+ * collectMainSessions 实扫集合一致（listMainSessions = agentDir 信号包下未去重的 main 根）。
+ */
+async function formatSessionNotFound(sessionId: string, agentDir: string): Promise<string> {
+  const mainRoots = (await resolveSessionRoots({ agentDir })).filter(
+    (r) => r.source === 'main' && r.dedupedInto === undefined,
+  )
+  const lines = mainRoots.map((r) => {
+    const state = r.exists ? `${r.fileCount} file(s)` : 'not exists'
+    return `  - ${r.path} [${r.kind}] ${state}`
+  })
+  return (
+    `session "${sessionId}" not found. Scanned ${mainRoots.length} main candidate root(s):\n` +
+    `${lines.join('\n')}\n` +
+    `No main session file whose first-line header id matches. ` +
+    `Verify the sessionId or agentDir; for partial uuid, use findSessions first.`
+  )
+}
+
 /** buildFamilyFromFs 各扫描阶段的共享累积器（主函数创建，各阶段 helper 显式传入并写入） */
 interface FamilyFsScan {
   /** main session headers（buildFamilyIndex byId/childrenOf 素材） */

package/src/doctor.ts

@@ -0,0 +1,262 @@
+/**
+ * doctor action（u8：design 2026-09-10 §6.2/§6.3/§6.4/§7B 要点 2/4/5/8 + §6.11 U14b 段）。
+ *
+ * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）：环境判定 + 根表渲染 +
+ * doctor 扫描缓存 + 旧布局残留 glob 探测。SessionReadSignals（u3 信号包超集）随域迁移，
+ * tool-handler re-export 保持导出面不变（index.ts / 单测白盒 import 路径不变）。
+ * statDirMtimeOrNull / DOCTOR_CACHE_TTL_MS 供留守的 u11 metadata 缓存复用（一并导出）。
+ */
+import { existsSync } from 'node:fs'
+import { readdir, stat } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { detectEnvironment, type DetectedEnvironment } from './discovery/env.js'
+import {
+  resolveSessionRoots,
+  type SessionRoot,
+  type SessionRootCache,
+  type SessionRootCacheEntry,
+  type SessionRootSignals,
+} from './discovery/roots.js'
+import type { SessionReadParams, ToolResult } from './tool-handler.js'
+
+/**
+ * doctor 所需环境信号：u3 信号包（SessionRootSignals）的超集，index.ts execute 补采
+ * env/bundleUrl。env 属宿主信号（detectEnvironment 契约），与根信号分属两个注入接口，
+ * 在 handler 层合流；两字段可选——缺省时 doctor 按「空 env / bundleUrl 缺失」降级
+ *（kind=standalone-pi、distribution=null），根表照常输出。
+ */
+export interface SessionReadSignals extends SessionRootSignals {
+  /** process.env 快照（doctor 环境判定，design §6.2；缺省按空 env 降级） */
+  env?: Record<string, string | undefined>
+  /** extension 模块 import.meta.url（doctor 发行形态判定；缺省 distribution=null 不猜） */
+  bundleUrl?: string
+}
+
+/**
+ * doctor 扫描缓存（进程内，keyed by 根字面路径；Map 生命周期 = pi 进程生命周期，
+ * 即「进程生命周期兜底上限」）。失效 = 秒级 TTL 到期 **或** 根目录 mtime 变化（任一）。
+ *
+ * 以 SessionRootCache 句柄注入 resolveSessionRoots（§6.3「同一数据源两处渲染」——根
+ * 骨架/去重/扫描全在 roots.ts，doctor 只注入缓存与 subagent 扫描模式）；TTL/mtime
+ * 失效判定全在本侧实现，roots.ts 不内置。**仅 doctor 消费——find 一律不读缓存**
+ *（§7B 要点 8）：find 恒不传 options；若 find 读缓存，最坏形态是 PS-14（首条
+ * assistant 前 main 根 0 文件被缓存，之后每次都把「根解析正常」误报成「主根为空」）
+ * ——正是本设计要消灭的错误归因。
+ */
+interface DoctorCacheEntry extends SessionRootCacheEntry {
+  /** 写入时刻（Date.now()），TTL 判定用 */
+  cachedAt: number
+  /** 根目录 mtime(ms)；目录不存在为 null（存在性翻转即失效） */
+  dirMtimeMs: number | null
+}
+
+const doctorScanCache = new Map<string, DoctorCacheEntry>()
+// §7.5 豁免（development-guide.md「纯性能缓存豁免」）：TTL 纯性能缓存，jiti 双路径加载
+// 分裂成两份仅多一次 miss 重扫，无正确性影响，不升级 globalThis 单例。
+
+/** doctor 根表来源标签列宽（最长 `[subagent]` 10 字符 + 1 对齐间距，§5.1 表格形态）。 */
+const DOCTOR_ROOT_LABEL_PAD = 11
+
+/** 缓存 TTL（秒级，§6.3）。mtime 是主失效通道；TTL 兜「子目录内增删不改变根 mtime」的陈旧面。 */
+export const DOCTOR_CACHE_TTL_MS = 5000
+
+/** stat 根目录 mtime；不存在返回 null（与缓存条目的 null 比对 = 存在性未翻转）。 */
+export async function statDirMtimeOrNull(path: string): Promise<number | null> {
+  try {
+    return (await stat(path)).mtimeMs
+  } catch (err) {
+    // 目录不存在是 doctor 的常态输入（三根降级形态），非异常——void 同 roots.ts 容错
+    void err
+    return null
+  }
+}
+
+/** doctor 侧缓存句柄：get 做失效判定（未命中即删除条目），set 快照 mtime 与写入时刻。 */
+const doctorRootCache: SessionRootCache = {
+  async get(key) {
+    const hit = doctorScanCache.get(key)
+    if (hit === undefined) return undefined
+    if (Date.now() - hit.cachedAt >= DOCTOR_CACHE_TTL_MS) {
+      doctorScanCache.delete(key)
+      return undefined
+    }
+    if ((await statDirMtimeOrNull(key)) !== hit.dirMtimeMs) {
+      doctorScanCache.delete(key)
+      return undefined
+    }
+    return { exists: hit.exists, fileCount: hit.fileCount, scanMs: hit.scanMs }
+  },
+  async set(key, value) {
+    doctorScanCache.set(key, {
+      ...value,
+      cachedAt: Date.now(),
+      dirMtimeMs: await statDirMtimeOrNull(key),
+    })
+  },
+}
+
+/** 旧布局残留条目（§6.11 U14b doctor 侧独立 glob 探测）。 */
+/** 旧布局残留探测单条命中（doctor 与 u14b 启动探测同源判据，§6.11）。 */
+export interface PiLayoutLeftover {
+  path: string
+  kind: 'backup' | 'unmigrated'
+}
+
+/**
+ * 旧布局残留独立 glob 探测（§6.11 v9.1）。基点 = dirname(agentDir)（xyz-agent 下 =
+ * `<dataDir>`，纯 pi 下 = `~/.pi`）；`pi/`（未迁移）与 `pi.backup-v2-` 前缀目录（迁移备份）
+ * 都不在任何候选根推导式内（[legacy] 够不到带时间戳的备份名与 pi/ 层），故须独立探测。
+ *
+ * 形态判据（与 u14b 启动探测 / u14a 脚本 0a 同源）：目录下含 `agent/` 或 `sessions/`
+ * 子目录才算残留——防纯 pi 宿主下任意来源的 `~/.pi/pi/` 目录误报。读探测，每次现查
+ * 不入缓存（两次 readdir 成本可忽略，缓存只服务扫盘贵的根）。
+ */
+async function detectPiLayoutLeftovers(
+  agentDir: string,
+): Promise<{ base: string; hits: PiLayoutLeftover[] }> {
+  const base = dirname(agentDir)
+  if (agentDir.length === 0) return { base, hits: [] }
+  let names: string[]
+  try {
+    names = (await readdir(base, { withFileTypes: true }))
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+  } catch {
+    return { base, hits: [] }
+  }
+  const hits: PiLayoutLeftover[] = []
+  for (const name of names) {
+    const isUnmigrated = name === 'pi'
+    const isBackup = name.startsWith('pi.backup-v2-')
+    if (!isUnmigrated && !isBackup) continue
+    const dir = join(base, name)
+    // 形态判据：含 agent/ 或 sessions/ 子目录（迁移备份必含其一——备份即原 pi/ 改名）
+    if (!existsSync(join(dir, 'agent')) && !existsSync(join(dir, 'sessions'))) continue
+    hits.push({ path: dir, kind: isBackup ? 'backup' : 'unmigrated' })
+  }
+  return { base, hits }
+}
+
+/**
+ * doctor：环境判定 + 根表 + 事实型诊断 + legacy 非空告警 + 旧布局残留探测。
+ *
+ * 诊断结论只陈述事实（「最高优先级 main 根 N 文件」），禁止「真的没有 session」类
+ * 归因断言（§7B 要点 5 / §3.3 教训）；env/bundleUrl 信号缺失时环境判定按降级输出，
+ * 根表照常（§7B 要点 2 同款降级哲学）。
+ */
+export async function doDoctor(
+  params: SessionReadParams,
+  signals: SessionReadSignals,
+): Promise<ToolResult> {
+  const environment = detectEnvironment({
+    env: signals.env ?? {},
+    ...(signals.bundleUrl !== undefined ? { bundleUrl: signals.bundleUrl } : {}),
+    agentDir: signals.agentDir,
+  })
+  const roots = await resolveSessionRoots(signals, {
+    // subagent 根默认只 stat（§6.3 成本控制：只列路径与可扫性）；includeSubagents:true
+    // 才扫（走同一缓存句柄）。find/F1 路径恒不传 options——不读缓存（§7B 要点 8）。
+    subagents: params.includeSubagents === true ? 'scan' : 'stat',
+    cache: doctorRootCache,
+  })
+  const leftovers = await detectPiLayoutLeftovers(signals.agentDir)
+  return renderDoctor(roots, environment, leftovers)
+}
+
+/**
+ * doctor action 的 details 契约（与兄弟 action 命名接口同构：tool-handler WorkflowDetails /
+ * search-across CrossSearchDetails 先例）——消费侧测试直 import 本类型，不再自建局部镜像。
+ */
+export interface DoctorDetails {
+  environment: DetectedEnvironment
+  roots: SessionRoot[]
+  leftovers: PiLayoutLeftover[]
+  globBase: string
+}
+
+/**
+ * 渲染 doctor 输出（§5.1 形态）：环境判定 + evidence + 会话根表（来源标签/路径/存在/
+ * 文件数/扫描耗时/去重注记）+ 事实型诊断 + legacy 非空告警 + 旧布局残留（命中才出现）。
+ */
+function renderDoctor(
+  roots: SessionRoot[],
+  environment: DetectedEnvironment,
+  leftovers: { base: string; hits: PiLayoutLeftover[] },
+): ToolResult {
+  const lines: string[] = []
+
+  // 环境判定行 + evidence（§6.2：判定可被证据推翻，非黑盒断言；evidence 恒非空）
+  lines.push(
+    `环境判定：${environment.kind === 'xyz-agent' ? 'xyz-agent（托管）' : 'standalone-pi'}` +
+      ` · 发行形态：${environment.distribution ?? '未知（不猜）'}`,
+  )
+  if (environment.dataDir !== undefined) lines.push(`数据目录：${environment.dataDir}`)
+  lines.push('依据：')
+  for (const e of environment.evidence) lines.push(`  - ${e}`)
+
+  // 会话根表（按优先级）
+  lines.push('')
+  lines.push('会话根（按优先级）：')
+  roots.forEach((r, i) => {
+    lines.push(`  ${i + 1}. ${`[${r.kind}]`.padEnd(DOCTOR_ROOT_LABEL_PAD)} ${r.path}`)
+    if (r.dedupedInto !== undefined) {
+      const keptIndex = roots.findIndex((k) => k.kind === r.dedupedInto) + 1
+      lines.push(`     与 ${keptIndex} 同路径，已去重`)
+      return
+    }
+    const facts = [r.exists ? '存在' : '不存在']
+    if (r.fileCount === undefined) {
+      // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数
+      //（实扫或缓存命中）；被去重根已在上方提前返回
+      facts.push('未扫描（subagent 根默认不扫，includeSubagents:true 开启）')
+    } else {
+      facts.push(`${r.fileCount} 文件`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
+    }
+    if (r.cached === true) facts.push('缓存命中')
+    facts.push(r.source === 'main' ? 'main' : 'subagent')
+    lines.push(`     ${facts.join(' · ')}`)
+  })
+
+  // 事实型诊断（§7B 要点 5）：列表内首个 main 根即最高优先级 main 根（去重只移除后位根，
+  // 首位根恒有计数——实扫或缓存命中）。0 文件也是事实——首条 assistant 前 jsonl 不落盘
+  //（PS-14），不做归因。
+  lines.push('')
+  const firstMain = roots.find((r) => r.source === 'main')
+  if (firstMain === undefined) {
+    lines.push('诊断：无候选根（agentDir 为空，未派生任何根）。')
+  } else {
+    lines.push(
+      `诊断：最高优先级 main 根 [${firstMain.kind}] ${firstMain.path}：${firstMain.fileCount ?? 0} 文件。`,
+    )
+  }
+
+  // legacy 非空告警（§6.1/§5.1：判据 = 非空才告警；与主根同路径被去重 → 不告警）
+  const legacy = roots.find((r) => r.kind === 'legacy')
+  if (legacy !== undefined && legacy.dedupedInto === undefined && (legacy.fileCount ?? 0) > 0) {
+    lines.push(
+      `告警：[legacy] 根 ${legacy.path} 非空（${legacy.fileCount} 文件）——该位置已作为候选根纳入 find。`,
+    )
+  }
+
+  // 旧布局残留（§6.11：命中才列，附同一迁移指引）
+  if (leftovers.hits.length > 0) {
+    lines.push('')
+    lines.push(`旧布局残留探测（基点 ${leftovers.base}）：`)
+    for (const h of leftovers.hits) {
+      lines.push(
+        `  - ${h.path}（${h.kind === 'backup' ? '迁移备份 pi.backup-v2-*' : '未迁移旧布局 pi/'}）`,
+      )
+    }
+    lines.push('  👉 关闭应用后运行 scripts/migrate-pi-layout-v2.mjs 完成迁移。')
+  }
+
+  return {
+    content: [{ type: 'text', text: lines.join('\n') }],
+    details: {
+      environment,
+      roots,
+      leftovers: leftovers.hits,
+      globBase: leftovers.base,
+    } satisfies DoctorDetails,
+  }
+}