@zhushanwen/pi-session-reader 0.11.0 → 0.13.0

package/src/discovery/zcode-manifest.ts

@@ -2,6 +2,7 @@ import { readFile, readdir } from 'node:fs/promises'
 import { statSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { resolveSessionStoreRoot, listSessionStorePartitions } from './roots.js'
 import type { ZcodeAnchor } from './entry-anchor.js'
 import type { ZcodeFamilyNode } from '../core/family.js'
 
@@ -9,9 +10,9 @@ import type { ZcodeFamilyNode } from '../core/family.js'
  * zcode manifest 直读与枚举（design session-reader-shared-core §3.1 第①步 / D5 / D5-1）。
  *
  * 背景（F21）：pi 路径的 `isRecordManifest` 三必填含 `sessionFile`，而 zcode manifest
- * 落盘时该键被 JSON.stringify 丢弃（subagent-core record-store-rebuild.ts:665/725 投影
+ * 落盘时该键被 JSON.stringify 丢弃（subagent-core record-store-rebuild.ts:665/725 派生视图
  * 照写 `sessionFile: undefined`）→ `listRecordManifests` 对 zcode manifest 恒返回 []。
- * 本单元另开一条**不经过该守卫**的独立路径：
+ * 本单元另开一条**不经过该检查**的独立路径：
  * - **定点直读**（`readZcodeManifest`）：manifest 文件名由 sa-id 完全确定（写侧
  *   `path.join(recordsDir, \`${record.id}.json\`)`，manifest-store.ts:141/153），按确定性
  *   文件名 `<sa-id>.json` 在 `<agentDir>/subagents/<cwd>/records/` 下**窄 walk（命中即止，
@@ -24,7 +25,7 @@ import type { ZcodeFamilyNode } from '../core/family.js'
  * `listRecordManifests`（subagents.ts）一行不改——pi manifest 仍走原扫描路径，本单元
  * 的谓词**不走** isRecordManifest。判别规则与 runtime `transcriptAnchorOf` 同构
  * （F8：`engine === 'zcode'` 第一判据 + sessionRef 双键齐）。用 `engine` 判别而非
- * 「engineHandle 存在性」的理由见 D5 被否项 ②（pi record 提升后 engineHandle 仍持久化，
+ * 「engineHandle 存在性」的理由见 D5 不采用项 ②（pi record 提升后 engineHandle 仍持久化，
  * 存在性判别会误路由）。
  */
 
@@ -43,7 +44,7 @@ export interface ZcodeManifestRecord extends ZcodeFamilyNode {
 /**
  * anchor-missing 的缺失键归因（§3.4：缺失键名进结构化日志——engineHandle 整体缺席 /
  * 缺 sessionRef / 缺 sessionId / 缺 dbPath 归因不同：整体缺席多为旧版本产物，缺
- * sessionId 多为引擎未回调 onHandleReady，缺 dbPath 多为写入面截断）。entry 兜底侧
+ * sessionId 多为引擎未回调 onHandleReady，缺 dbPath 多为写侧截断）。entry 兜底侧
  * 的同构分类（tool-handler classifyIncompleteEntryAnchor）复用本类型单源。
  */
 export type ZcodeAnchorMissingReason =
@@ -67,7 +68,7 @@ export type ZcodeManifestLookup =
   | { kind: 'not-zcode' }
   | { kind: 'anchor-missing'; reason: ZcodeAnchorMissingReason }
 
-/** manifest 顶层 JSON 的读取视图（守卫输入） */
+/** manifest 顶层 JSON 的读取视图（检查输入） */
 type ManifestJson = Record<string, unknown>
 
 function asObject(v: unknown): ManifestJson | undefined {
@@ -125,7 +126,7 @@ function richFieldsOf(m: ManifestJson): ManifestRichFields {
   return out
 }
 
-/** stat 存在性（任意路径无安全面——D5-1 只查「文件在不在」，不开库） */
+/** stat 存在性（任意路径无安全侧——D5-1 只查「文件在不在」，不开库） */
 function fileExists(p: string): boolean {
   try {
     statSync(p)
@@ -161,7 +162,13 @@ function toZcodeManifestRecord(m: ManifestJson): ZcodeManifestRecord | undefined
   }
 }
 
-/** `<agentDir>/subagents` 布局常量（与写侧 path-encoding/manifest-store 布局对齐） */
+/**
+ * [session-store-layout-inversion D6/单新根] zcode manifest 读侧 = session 存储树分区
+ * 固定位置 `<root>/<rootSessionId>/subagents/records/`（根推导与分区枚举复用 roots.ts
+ * 的 resolveSessionStoreRoot / listSessionStorePartitions——同包单源防漂移）。旧布局
+ * `<agentDir>/subagents/<cwdSlug>/records/` 不再读写（D6 存量不迁移不读取——旧 zcode
+ * record 从 agent 面消失是 D6 取舍清单明示项）。
+ */
 const SUBAGENTS_DIR = 'subagents'
 const RECORDS_DIR = 'records'
 
@@ -196,22 +203,16 @@ export async function readZcodeManifest(
   agentDir: string,
   saId: string,
 ): Promise<ZcodeManifestLookup> {
-  const root = join(agentDir, SUBAGENTS_DIR)
-  let slugs: DirentLike[]
-  try {
-    slugs = await readdir(root, { withFileTypes: true })
-  } catch {
-    return { kind: 'not-zcode' } // subagents 根不存在/不可读 → 无 manifest
-  }
-  for (const e of slugs) {
-    if (!e.isDirectory()) continue
-    const file = join(root, e.name, RECORDS_DIR, `${saId}.json`)
+  const root = resolveSessionStoreRoot(agentDir)
+  const partitions = await listSessionStorePartitions(root)
+  for (const part of partitions) {
+    const file = join(root, part, SUBAGENTS_DIR, RECORDS_DIR, `${saId}.json`)
     let raw: string
     try {
       // 命中即止：只读这一个文件（文件名由 sa-id 确定），坏内容同样终止（见 parseManifestLookup）
       raw = await readFile(file, 'utf8')
     } catch {
-      continue // 该 cwd 目录下无此 manifest → 下一候选目录
+      continue // 该分区无此 manifest → 下一候选分区
     }
     return parseManifestLookup(raw)
   }
@@ -236,17 +237,11 @@ interface DirentLike {
  * family 是列表视图，单节点不可达不炸整屏（D5-1 GC 语义）。
  */
 export async function listZcodeManifests(agentDir: string): Promise<ZcodeManifestRecord[]> {
-  const root = join(agentDir, SUBAGENTS_DIR)
+  const root = resolveSessionStoreRoot(agentDir)
   const out: ZcodeManifestRecord[] = []
-  let slugs: DirentLike[]
-  try {
-    slugs = await readdir(root, { withFileTypes: true })
-  } catch {
-    return out // 根不存在/不可读 → 空（无 zcode 节点，不报错）
-  }
+  const slugs = await listSessionStorePartitions(root)
   for (const slug of slugs) {
-    if (!slug.isDirectory()) continue
-    const recordsDir = join(root, slug.name, RECORDS_DIR)
+    const recordsDir = join(root, slug, SUBAGENTS_DIR, RECORDS_DIR)
     let files: DirentLike[]
     try {
       files = await readdir(recordsDir, { withFileTypes: true })

package/src/doctor.ts

@@ -93,6 +93,9 @@ function renderDoctor(
       // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数（实扫）；
       // 被去重根已在上方提前返回
       facts.push('未扫描（subagent 根默认不扫，includeSubagents:true 开启）')
+    } else if (r.kind === 'archive') {
+      // [session-archive D7] 归档根计数 = 簿记数（非 .jsonl 文件数，措辞按实名）
+      facts.push(`${r.fileCount} 归档单元`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
     } else {
       facts.push(`${r.fileCount} 文件`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
     }

package/src/extract.ts

@@ -347,7 +347,7 @@ function collectCommitCandidates(
   return { high, low }
 }
 
-/** 收口阶段：去重，高置信优先，同 hash 保留首次。 */
+/** 收尾阶段：去重，高置信优先，同 hash 保留首次。 */
 function dedupeCommits(high: CommitItem[], low: CommitItem[]): CommitItem[] {
   const seen = new Set<string>()
   const items: CommitItem[] = []

package/src/index.ts

@@ -156,9 +156,12 @@ const guidelines = [
   // 工具内指向本工具的交叉引用，非本清单的锚）。
   'Progressive reading: outline (~1500 tokens) → expand (one turn) → detail; defaults omit toolResult/thinking noise.',
   'find first (uuid fragment / name); TUI #references are full uuids. Never read raw .jsonl—use this tool.',
-  // zcode 路由（U9）对 LLM 的唯一可见面：sa-id 输入自动路由，无需任何参数；首遇
+  // zcode 路由（U9）对 LLM 的唯一可见部分：sa-id 输入自动路由，无需任何参数；首遇
   // zcode_* 错误码前先有背景预告。
   'sa- ids route transparently to pi or zcode engine sessions; sess_ prefixed ids are not accepted—use the completion-notice sa- id.',
+  // [session-archive D7] 归档态硬契约的 LLM 侧预告：引用已归档 session 只得摘要
+  //（返回头部显式标注「已归档」），恢复完整历史是用户操作。
+  'Archived sessions return summary-only views (marked 已归档/archived)—for full history, ask the user to restore the session.',
   'Errors carry a 👉 recovery hint—follow it to retry.',
   'Unsure about host environment or session roots? Run action:"doctor".',
 ]
@@ -250,7 +253,7 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
   //
   // addAutocompleteProvider 挂在 ctx.ui（非 ExtensionAPI），setup 入口无 ctx，
   // 只能在 event handler 里拿——session_start 是最早且每 session 触发的 event。
-  // once-guard + ctx.mode 守卫 + typeof 运行时守卫三重防护。
+	// once-guard + ctx.mode 检查 + typeof 运行时检查三重防护。
   //
   // 2026-08-10 重构：数据源从全盘 findSessions(agentDir) 换为 SessionManager.listAll(ctx.sessionManager.getSessionDir())。
   // getSessionDir() 返回当前 session 的目录（encoded cwd），listAll 只扫该目录 →

package/src/no-match.ts

@@ -62,6 +62,13 @@ function buildSelfCheckLines(roots: SessionRoot[]): string[] {
       continue
     }
     const count = r.fileCount ?? r.files.length
+    // [session-archive D2 U2] 归档根不计入 find 候选集合计（find 只迭代在场 .jsonl，
+    // 归档根 files 恒空、fileCount = 簿记数——计入则「候选集非空」陈述失真）；
+    // 措辞对齐 doctor 的「N 归档单元」实名（区别于 .jsonl 文件计数）。
+    if (r.kind === 'archive') {
+      lines.push(`  [${r.kind}]`.padEnd(F1_ROOT_LABEL_PAD) + `${r.path}：${count} 归档单元`)
+      continue
+    }
     totalFiles += count
     lines.push(`  [${r.kind}]`.padEnd(F1_ROOT_LABEL_PAD) + `${r.path}：${count} 文件`)
   }
@@ -117,8 +124,15 @@ function formatSuggestionLines(suggestions: NoMatchSuggestion[], query: string):
   return lines
 }
 
-/** ③ 正确做法四条 + ④ 封死 shell 绕行（纯静态文案）。 */
-function guidanceLines(): string[] {
+/**
+ * ③ 正确做法四条 + ④ 封死 shell 绕行（纯静态文案）。
+ *
+ * [session-archive D7] archiveHint：归档根存在且有簿记时由 formatNoMatch 追加第
+ * 五条（目标可能已归档的引用指引）——find 结果不含归档条目，归档引用通道是深读
+ * action 的 session 参数（resolveByFragment 的归档回退层）。无归档目录 → 空数组，
+ * 文案零变化。
+ */
+function guidanceLines(archiveHint: string[] = []): string[] {
   return [
     '',
     '正确做法：',
@@ -126,6 +140,7 @@ function guidanceLines(): string[] {
     `  - 已知文件路径时直接传绝对路径：session_read { action:"outline", session:"<绝对路径>.jsonl" }`,
     `  - 截断/过期 id 用更短前缀：session_read { action:"find", query:"<更短前缀>" }`,
     `  - 想先看环境与根目录状态：session_read { action:"doctor" }`,
+    ...archiveHint,
     '',
     '不要用 shell find/ls/rg 搜 session 目录，不要 cat/read 原始 .jsonl —— session_read 是唯一入口。',
   ]
@@ -147,15 +162,25 @@ function guidanceLines(): string[] {
  * ③「正确做法」四条：标题/keyword、绝对路径 outline、更短前缀、doctor。
  * ④ 最后一行封死 shell 绕行：find/ls/rg 搜 session 目录、cat/read 原始 .jsonl 均禁止。
  *
- * 无「👉 用 recent 看全量」误导指引（recent 候选对写错的 uuid 无自纠价值，§6.7 被否项）。
+ * 无「👉 用 recent 看全量」误导指引（recent 候选对写错的 uuid 无自纠价值，§6.7 不采用项）。
  */
 export function formatNoMatch(query: string, roots: SessionRoot[]): string {
+  // [session-archive D7] 归档指引（条件行）：归档根存在且簿记非空才出现——自检行
+  // 已列 [archive] 根计数，此处补「怎么引用」的动作指引，find→深读链路对归档
+  // session 不断链。无归档目录的 roots 不含 archive 根，guidanceLines 零变化。
+  const archiveRoot = roots.find((r) => r.kind === 'archive' && r.dedupedInto === undefined)
+  const archiveHint =
+    archiveRoot !== undefined && (archiveRoot.fileCount ?? 0) > 0
+      ? [
+          `  - 目标可能已归档：直接用 session 参数引用（返回归档摘要），如 session_read { action:"outline", session:"<名称片段或id>" }`,
+        ]
+      : []
   return [
     `无匹配 session："${query}"`,
     '',
     ...buildSelfCheckLines(roots),
     '',
     ...formatSuggestionLines(collectSuggestions(query, roots), query),
-    ...guidanceLines(),
+    ...guidanceLines(archiveHint),
   ].join('\n')
 }

package/src/result-action.ts

@@ -17,6 +17,7 @@
  */
 import type { Entry, ParseResult } from '@zhushanwen/session-core'
 import { textBlockParts } from './core/render.js'
+import { archivedResult } from './discovery/archive-match.js'
 import type { MatchedSession } from './discovery/find.js'
 import { listRecordManifests, type RecordManifest } from './discovery/subagents.js'
 import { err, requireStr, SESSION_ID_PREFIX_LEN, stripHash } from './handler-utils.js'
@@ -31,7 +32,7 @@ const RESULT_DEFAULT_LIMIT = 8000
 /** result 批量条目分隔符（与 notifier 批通知 "\n\n---\n\n" join 同款）。 */
 const RESULT_BATCH_SEPARATOR = '\n\n---\n\n'
 
-/** result action 对 tool-handler 文件私有 helper 的注入面（入口分发处 per-call 构造）。 */
+/** result action 对 tool-handler 文件私有 helper 的注入点（入口分发处 per-call 构造）。 */
 export interface ResultActionDeps {
   resolveSessionId(
     rawSession: string | undefined,
@@ -208,6 +209,11 @@ export async function doResult(
   for (const id of ids) {
     const resolved = await deps.resolveSessionId(id, 'result', agentDir, params.source, prefetchedManifests)
     if (resolved.kind === 'multi') return deps.disambiguate(resolved.query, resolved.candidates)
+    // [session-archive D7] 片段命中归档 session：完整正文不可读，统一返回归档态摘要
+    //（构造与渲染收敛在 archive-match 的 archivedResult，与 tool-handler 同一出口）
+    if (resolved.kind === 'archived' || resolved.kind === 'archived-multi') {
+      return archivedResult(resolved)
+    }
     const { entries } = await deps.safeParse(resolved.fileName)
     const text = extractFinalAssistantText(entries)
     if (text.length === 0) {

package/src/search-across.ts

@@ -137,7 +137,7 @@ export function collectSearchHits(
   return hits
 }
 
-/** search 收口阶段：结果文本组装（header 标注降级/scope/截断 + 逐行命中列表）。 */
+/** search 收尾阶段：结果文本组装（header 标注降级/scope/截断 + 逐行命中列表）。 */
 export function formatSearchText(
   pattern: string,
   degraded: boolean,
@@ -196,7 +196,7 @@ interface CrossSearchSkipped {
   sizeBytes?: number
 }
 
-/** 跨会话检索 details（程序化消费/测试断言面）。 */
+/** 跨会话检索 details（程序化消费/测试断言范围）。 */
 export interface CrossSearchDetails {
   pattern: string
   scope: NonNullable<SessionReadParams['scope']>
@@ -355,7 +355,7 @@ interface CrossSearchOptions {
   byteBudget?: number
 }
 
-/** 缺省值收口后的检索参数（各缺省值与旧内联 `opts?.** ?? 常量` 逐一对应）。 */
+/** 缺省值收尾后的检索参数（各缺省值与旧内联 `opts?.** ?? 常量` 逐一对应）。 */
 interface CrossSearchResolvedOptions {
   scope: NonNullable<SessionReadParams['scope']>
   limit: number

package/src/tool-format.ts

@@ -1,11 +1,11 @@
 /**
  * session_read 各 action 的输出文本渲染（max-lines 拆分轮从 tool-handler.ts 机械
- * 提取，零行为变更）：错误面 message（ES1/ES2 + zcode 七码 + 开库/查询期错误映射）+
+ * 提取，零行为变更）：错误范围 message（ES1/ES2 + zcode 七码 + 开库/查询期错误映射）+
  * content 文本（find/outline/expand/detail/family）+ entry 可读文本 + F2 消歧与
  * find 零匹配的 ToolResult 包装。纯字符串/纯渲染函数，不触 fs（findNoMatch 的
  * roots 由调用方传入）。
  *
- * 导出面：SQLITE_DRIVER_UNSUPPORTED_MARK / ZCODE_DB_MISSING_MARK /
+ * 导出清单：SQLITE_DRIVER_UNSUPPORTED_MARK / ZCODE_DB_MISSING_MARK /
  * zcodeReadErrorMessage（测试契约锚消费方直接 import 本模块）。logger 用同名
  * getLogger('session-reader')——按名缓存单例，与 tool-handler 侧同一实例，
  * warn/error 落同一 appendEntry/文件日志通道。ToolResult 等公共类型留
@@ -33,7 +33,8 @@ import {
 import type { Family } from './core/family.js'
 import { SESSION_ID_PREFIX_LEN, rangeLabel } from './handler-utils.js'
 import { formatNoMatch } from './no-match.js'
-import type { ToolResult } from './tool-handler.js'
+import { archivedResult } from './discovery/archive-match.js'
+import type { ResolveResult, ToolResult } from './tool-handler.js'
 
 // 结构化日志通道（zcodeReadErrorMessage 的降级/TOCTOU warn）：getLogger 按名缓存
 // 单例，与 tool-handler 侧调用取同一实例，appendEntry/文件日志行为不变。
@@ -84,7 +85,7 @@ export function formatSaIdNotFound(saId: string): string {
 }
 
 // ---------------------------------------------------------------------------
-// zcode 错误面（U9，design §3.4 七码 + 👉 逐行；错误码标识入 message 供机器识别，
+// zcode 错误范围（U9，design §3.4 七码 + 👉 逐行；错误码标识入 message 供机器识别，
 // 形态对齐 §3.1 失败路径示例 `[zcode_db_path_forbidden] …`）
 // ---------------------------------------------------------------------------
 
@@ -131,7 +132,7 @@ function formatZcodeSchemaDrift(observed: string | undefined): string {
 
 /**
  * bun 驱动探测失败（§3.4 表第 8 行理论态）的 message：宿主既无 bun:sqlite 也无
- * node:sqlite——zcode action 整体降级为本错误面（fail-fast + 日志），pi 链路不受影响。
+ * node:sqlite——zcode action 整体降级为本错误范围（fail-fast + 日志），pi 链路不受影响。
  * 错误码字面量为实施期命名（设计该行未定码名，形态对齐七码 `[zcode_*]` 惯例）。
  */
 function formatZcodeHostUnsupported(detail: string): string {
@@ -145,8 +146,8 @@ function formatZcodeHostUnsupported(detail: string): string {
 /**
  * sqlite 驱动探测失败的消息特征（zcode-session-source sqlite-driver.ts 探测失败的
  * 错误消息契约；该包不导出专用错误子类，reader 侧按消息特征单列识别——跨包漂移
- * 由 zcode-routing.test.ts 的源文本契约测试守卫：sqlite-driver 源文不再含本子串即红）。
- * 导出面仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
+ * 由 zcode-routing.test.ts 的源文本契约测试检查：sqlite-driver 源文不再含本子串即红）。
+ * 导出范围仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
  */
 export const SQLITE_DRIVER_UNSUPPORTED_MARK = '不支持 node:sqlite'
 
@@ -154,17 +155,17 @@ export const SQLITE_DRIVER_UNSUPPORTED_MARK = '不支持 node:sqlite'
  * 库文件缺失的消息特征（zcode-session-source sqlite-access.ts `openZcodeSessionDb`
  * 开头 existsSync 失败抛普通 Error「db 文件不存在：<dbPath>」的消息契约锚点）。该包
  * 不导出专用错误子类，reader 侧按消息特征单列识别——落 §3.4 第 4 行
- * `zcode_db_unreadable`（不误标 schema_drift）。生产路径上白名单闸
+ * `zcode_db_unreadable`（不误标 schema_drift）。生产路径上白名单门禁
  * （assertZcodeDbPathAllowed 第 1 段）已先行拦掉绝大多数缺失，此处命中的是两段
- * existsSync 之间的 TOCTOU 理论窗口（闸通过后开库前文件被删）。跨包漂移由
- * zcode-routing.test.ts 的源文本契约测试守卫（SQLITE_DRIVER_UNSUPPORTED_MARK 同范式）。
- * 导出面仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
+ * existsSync 之间的 TOCTOU 理论窗口（门禁通过后开库前文件被删）。跨包漂移由
+ * zcode-routing.test.ts 的源文本契约测试检查（SQLITE_DRIVER_UNSUPPORTED_MARK 同范式）。
+ * 导出范围仅测试消费（契约锚 + 映射测试引用同值，禁测试内硬编码副本）。
  */
 export const ZCODE_DB_MISSING_MARK = 'db 文件不存在'
 
 /**
- * 开库/查询期错误 → §3.4 错误面映射（SqliteUnreadableError / schema drift / 驱动探测失败 / 库缺失 / 其余）。
- * 导出面仅测试消费（L4 包装形态的映射契约直测，zcode-routing.test.ts）。
+ * 开库/查询期错误 → §3.4 错误范围映射（SqliteUnreadableError / schema drift / 驱动探测失败 / 库缺失 / 其余）。
+ * 导出范围仅测试消费（L4 包装形态的映射契约直测，zcode-routing.test.ts）。
  */
 export function zcodeReadErrorMessage(e: unknown, agentDir: string): string {
   if (e instanceof SqliteUnreadableError) {
@@ -229,6 +230,16 @@ export function disambiguate(query: string, candidates: MatchedSession[]): ToolR
   return { content: [{ type: 'text', text }], details: { ambiguous: true, candidates } }
 }
 
+/**
+ * ResolveResult 非 ok 支的统一分发（[session-archive D7] 归并点）：multi → 既有
+ * F2 消歧；archived / archived-multi → 归档态返回（archive-match 两支渲染，不读
+ * 压缩体）。8 个 do* 的「multi 消歧 + 归档短路」重复分支收敛到本函数单一出口。
+ */
+export function resolveNonOkResult(resolved: Exclude<ResolveResult, { kind: 'ok' }>): ToolResult {
+  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  return archivedResult(resolved)
+}
+
 // ---------------------------------------------------------------------------
 // 文本渲染（content）
 // ---------------------------------------------------------------------------