@zhushanwen/pi-session-reader 0.11.0 → 0.13.0

package/src/tool-handler.ts

@@ -11,7 +11,7 @@
  * 域模块拆分（max-lines 拆分轮机械提取，零行为变更，result-action.ts 先例同型）：
  *   result-action.ts（result）/ doctor.ts（doctor + SessionReadSignals）/
  *   search-across.ts（search 管线 + u12 跨会话）/ extract.ts（extract 预设）/
- *   tool-format.ts（各 action 输出文本渲染 + 错误面 message + F2 消歧与
+ *   tool-format.ts（各 action 输出文本渲染 + 错误范围 message + F2 消歧与
  *   find 零匹配包装）/ no-match.ts（F1 自检行）/ zcode-anchor-classify.ts（entry
  *   兜底归因的 entry 级纯判定）/ handler-utils.ts（pad/err/
  *   stripHash/requireStr/SESSION_ID_PREFIX_LEN/turn 索引解析低层小工具）。
@@ -20,13 +20,15 @@
  * 本模块 re-export 供 index.ts 生产消费）。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
- * 原样传播给 pi——pi-agent-core 只对 execute throw 置 isError:true（返回值里的 isError
- * 字段被丢弃，agent-loop.js:453-483）。handler 可抛（纯逻辑可测）。
+ * 原样传播给 pi——execute throw → agent-loop catch 置 isError:true（pi-agent-core dist/
+ * agent-loop.js executePreparedToolCall，1.0.0 实读 catch :581-588；1.0.0 起正常 return 的
+ * isError 也被尊重——:579 isError: result.isError === true，0.84.4 才硬编码 false——本包
+ * 失败恒走 throw，行为不变）。handler 可抛（纯逻辑可测）。
  * 例外：F2 多匹配与 F1 find 零匹配「不视为错误」，返回消歧/提示结果而非抛错。
  */
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
-import { join, isAbsolute } from 'node:path'
+import { join, dirname, isAbsolute } from 'node:path'
 import { homedir } from 'node:os'
 import { toErrorMessage } from '@zhushanwen/pi-ext-guards'
 import { getLogger } from '@zhushanwen/pi-extension-logger'
@@ -38,6 +40,10 @@ import {
   type SessionMetadataEntry,
   type SessionMetadataProvider,
 } from './discovery/find.js'
+import {
+  resolveArchiveFragment,
+  type ArchiveResolve,
+} from './discovery/archive-match.js'
 import { resolveSessionRoots } from './discovery/roots.js'
 import { readSessionHeaderIdSync } from './discovery/session-header.js'
 import { findZcodeEntryAnchor, type ZcodeAnchor } from './discovery/entry-anchor.js'
@@ -102,7 +108,7 @@ import {
   extractUserMessages,
   type ExtractWhat,
 } from './extract.js'
-// 同轮拆分的渲染域模块（format* 纯函数簇，含 zcode 错误面 message 与
+// 同轮拆分的渲染域模块（format* 纯函数簇，含 zcode 错误范围 message 与
 // zcodeReadErrorMessage 错误映射）：运行时依赖方向本模块 → tool-format，
 // tool-format 对本模块仅 type import（ToolResult），无循环。
 import {
@@ -122,6 +128,7 @@ import {
   formatZcodeRecordNotFound,
   formatZcodeSessionNotFound,
   isToolResultSummary,
+  resolveNonOkResult,
   zcodeReadErrorMessage,
 } from './tool-format.js'
 import { doDoctor, type SessionReadSignals } from './doctor.js'
@@ -132,7 +139,7 @@ import { firstIncompleteAnchorReason } from './zcode-anchor-classify.js'
 export type { SessionReadSignals }
 
 // zcode 读链的结构化日志（「事后排查」通道：degradations 留痕 / L2-L3 恢复成功 /
-// anchor-missing 归因——§3.4 可观测性 + P2 降级隔离契约 F13，均不进 LLM 可见面）。
+// anchor-missing 归因——§3.4 可观测性 + P2 降级隔离契约 F13，均不进 LLM 可见部分）。
 // pi handle 由 index.ts 初始化时 setPiHandle 注入（appendEntry 通道）；未注入时
 // warn/error 降级文件日志，双开关缺省 no-op（纯 pi 独立用户零行为影响）。
 const logger = getLogger('session-reader')
@@ -215,6 +222,13 @@ export type ResolveResult =
       zcodeAnchor?: ZcodeAnchor
     }
   | { kind: 'multi'; query: string; candidates: MatchedSession[] }
+  /**
+   * [session-archive D7] 片段命中归档 session（在场零命中后的归档回退层，两支
+   * 形态见 ArchiveResolve）：消费方（各 do* 的 non-ok 分发 resolveNonOkResult /
+   * result-action）统一返回归档态摘要——不读压缩体，头部显式标注归档态
+   * （agent 区分摘要与完整历史的硬契约）。
+   */
+  | ArchiveResolve
 
 // readSessionHeaderIdSync（同步读首行 header 取 id，resolveSessionId 形态①/②消费）
 // 在 discovery/session-header.ts（基座 readFirstJsonlLineSync 的谓词/降级薄包装，G2 单源）。
@@ -267,7 +281,7 @@ async function resolveSessionId(
 
   // §3.4 第 0 段：sess_ 形态 id 无第一梯队直读入口（agent 从不持有 sess id，F14；
   // 且无 zcode 候选发现，D6）→ zcode_param_invalid。pi 的 session id 是 uuid（无
-  // sess_ 前缀），此检测只改变错误输入的错误面文案。
+  // sess_ 前缀），此检测只改变错误输入的错误范围文案。
   if (session.startsWith('sess_')) {
     throw err(formatZcodeParamInvalid(session))
   }
@@ -287,7 +301,7 @@ async function resolveSessionId(
  *   `resolveByRecordId`（engine 缺省/'pi' 形态，行为与今天逐字节一致）。
  * ③ pi 无命中（今天此处直接 ES2）→ entry 兜底（§3.5 第②层，仅 liveSessionDir 内，
  *   越界显式失败）：命中 → zcode 读链；未命中 → `zcode_record_not_found` + 👉
- *  （§3.4：sa-id 语境的统一错误面——F14 agent 唯一持有的 id 就是 sa-id，指引动作
+ *  （§3.4：sa-id 语境的统一错误范围——F14 agent 唯一持有的 id 就是 sa-id，指引动作
  *   覆盖除 find 指针外的全部恢复路径（find 按 §3.4 刻意不保留）。
  */
 async function resolveSaIdRoute(
@@ -299,7 +313,7 @@ async function resolveSaIdRoute(
 ): Promise<ResolveResult> {
   const zm = await readZcodeManifest(agentDir, session)
   if (zm.kind === 'anchor-missing') {
-    // 归因进结构化日志不进 LLM 可见面（§3.4）：reason 逐键归因（missing-engineHandle /
+    // 归因进结构化日志不进 LLM 可见部分（§3.4）：reason 逐键归因（missing-engineHandle /
     // missing-sessionRef / missing-sessionId / missing-dbPath，见 zcode-manifest.ts）
     logger.warn('zcode manifest anchor-missing', { saId: session, reason: zm.reason })
     throw err(formatZcodeAnchorMissing(session))
@@ -391,7 +405,7 @@ async function resolveZcodeRoute(
     const zcodeNodes = await listZcodeManifests(agentDir)
     const rootSessionId = zcodeNodes.find((n) => n.id === saId)?.rootSessionId
     // 枚举未含该 id（直读命中与枚举之间 manifest 被迁移的极端窗口）→ 退回锚 sessionId，
-    // 后续 byId 查不到走既有 not-found 错误面（不静默伪造家族）
+    // 后续 byId 查不到走既有 not-found 错误范围（不静默伪造家族）
     if (rootSessionId === undefined) {
       return { kind: 'ok', sessionId: anchor.sessionId, fileName: '' }
     }
@@ -467,6 +481,11 @@ async function resolveByRecordId(session: string, agentDir: string, prefetchedMa
  * 形态③：其余片段 → findSessions 透传 source/liveSessionDir 沿用 F1（零匹配）/ F2（多匹配消歧）。
  * liveSessionDir 透传保证片段匹配与 find 同一 roots；F1 自检行同理须含 [live] 根行
  *（否则 [live]≠[default] 环境下自检行看不到最高优先级根，计数失真）。
+ *
+ * [session-archive D7] 归档回退层：在场匹配零命中 → 查归档簿记（archive-match）。
+ * 在场优先保证既有行为零变化（归档 session 不在 sessions/ 扫描范围，「在场零命中」
+ * 与「已归档」对同一 session 互斥成立——D9 不变量 1）；命中归档不走 F1（历史引用
+ * 不断链，D7 方案否决项「agent 完全不可见」）。
  */
 async function resolveByFragment(
   session: string,
@@ -481,6 +500,10 @@ async function resolveByFragment(
   }
   const { matches } = await findSessions(session, agentDir, opts)
   if (matches.length === 0) {
+    // [session-archive D7] 归档回退层：单命中返回归档态、多命中返回归档消歧
+    //（实现与匹配口径在 discovery/archive-match.ts）；无簿记命中落 F1。
+    const archive = await resolveArchiveFragment(session, agentDir)
+    if (archive !== undefined) return archive
     // F1 自检行需要发现层实况：无 options 的 resolveSessionRoots 恒实扫（根扫描无
     // 缓存——doctor 缓存机已删除，ext-simplify-04 U3），与 find 刚完成的扫描同一数据
     // 源（roots.ts 薄包装语义）；信号包同源（liveSessionDir 透传）——findSessions
@@ -501,8 +524,8 @@ async function resolveByFragment(
 /**
  * zcode 锚 → ParseResult（既有 turns/render 管线的统一内容入口）。
  *
- * 检查顺序三段递进（§3.4，实现与测试双锚定）：第 1 段存在性 → 第 2 段路径闸
- * （whitelist.ts）→ 第 3 段开库与查询（四级恢复阶梯 + schema 已知集闸门在
+ * 检查顺序三段递进（§3.4，实现与测试双锚定）：第 1 段存在性 → 第 2 段路径门禁
+ * （whitelist.ts）→ 第 3 段开库与查询（四级恢复阶梯 + schema 已知集门禁在
  * openZcodeSessionDb 单点）。读库发生在 ext 进程内（§3.5 关键论断），不经 taiji。
  */
 async function loadZcodeParsed(anchor: ZcodeAnchor, agentDir: string): Promise<ParseResult> {
@@ -515,7 +538,7 @@ async function loadZcodeParsed(anchor: ZcodeAnchor, agentDir: string): Promise<P
   }
   try {
     // 恢复成功不再是静默事件（§3.4 硬要求）：结构化日志（恢复方式 + db 路径），不进
-    // LLM 可见面。用 warn 而非 debug——L2/L3 是恢复降级路径，语义表 warn=内部降级与
+    // LLM 可见部分。用 warn 而非 debug——L2/L3 是恢复降级路径，语义表 warn=内部降级与
     // 失败（appendEntry 持久化）；debug 缺省 no-op 会让恢复成功重新变回静默事件。
     if (handle.via !== 'L1-direct') {
       logger.warn('zcode session db recovered via recovery ladder', {
@@ -545,7 +568,7 @@ async function loadZcodeParsed(anchor: ZcodeAnchor, agentDir: string): Promise<P
     // converter 保证），totalBytes/skippedLines 恒 0
     return { entries: normalized.entries, totalBytes: 0, skippedLines: 0, lastLinePartial: false }
   } catch (e) {
-    if (e instanceof Error && e.message.startsWith('[zcode_')) throw e // 本函数产出的错误面原样传播
+    if (e instanceof Error && e.message.startsWith('[zcode_')) throw e // 本函数产出的错误范围原样传播
     throw err(zcodeReadErrorMessage(e, agentDir))
   } finally {
     handle.dispose()
@@ -719,7 +742,8 @@ async function doFamily(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
 
   // recursive=true：嵌套执行树（U7/U8）
   if (params.recursive) {
@@ -766,7 +790,8 @@ async function doOutline(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const { entries, totalBytes, skippedLines } = await loadParsed(resolved, agentDir)
   const tree = buildTreeView(entries)
   const turns = segmentTurns(entries, new Set(tree.leafPath))
@@ -802,7 +827,8 @@ async function doExpand(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const turnIdx = parseTurnIndex(requireStr(params.turn, 'turn', 'expand'))
   const { entries } = await loadParsed(resolved, agentDir)
   const tree = buildTreeView(entries)
@@ -835,7 +861,8 @@ async function doDetail(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const range = parseTurnsRange(requireStr(params.turns, 'turns', 'detail'))
   const { entries } = await loadParsed(resolved, agentDir)
   const tree = buildTreeView(entries)
@@ -893,7 +920,8 @@ async function doSearch(
     undefined,
     signals.liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const scope = params.scope ?? 'all'
   const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
   const { entries } = await loadParsed(resolved, agentDir)
@@ -912,7 +940,7 @@ async function doSearch(
 /** export full 模式的 entry 分隔线（'=' 重复）宽度。 */
 const EXPORT_SEPARATOR_LEN = 40
 
-/** export：物化摘要到 <agentDir>/tmp/session-view-<id>.md（design §3.4 export，D-8）。 */
+/** export：物化摘要到 <dataDir>/ext-sessions/<id>/session-view.md（session-store-layout-inversion 域 6；文件名去 sid——sid 已在路径）。 */
 async function doExport(
   params: SessionReadParams,
   agentDir: string,
@@ -927,7 +955,8 @@ async function doExport(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
 
   let text: string
   let label: string
@@ -972,8 +1001,16 @@ async function doExport(
     label = 'outline'
   }
 
-  const outDir = join(agentDir, 'tmp')
-  const outPath = join(outDir, `session-view-${resolved.sessionId}.md`)
+  // [session-store-layout-inversion 域 6] 导出落 session 存储树（<root>/<sid>/session-view.md，
+  // 文件名去 sid——sid 已在路径）：基址 = agentDir 剥一层（taiji dataDir，托管态
+  // PI_CODING_AGENT_DIR = <dataDir>/agent）。session-reader 零 shared 依赖（extension 包
+  // 边界），公式与 shared getSessionViewPath 同字面镜像；sessionId 过 isPiSessionId 同域
+  // 校验（解析器产出的 sid 正常路径恒合法，此处是路径穿越纵深防线）。
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(resolved.sessionId)) {
+    throw err(`导出拒绝：sessionId 形态非法（${resolved.sessionId}）👉 检查 session 参数或用 find 重新定位`)
+  }
+  const outDir = join(dirname(agentDir), 'ext-sessions', resolved.sessionId)
+  const outPath = join(outDir, 'session-view.md')
   await mkdir(outDir, { recursive: true })
   await writeFile(outPath, text, 'utf8')
   const sizeBytes = Buffer.byteLength(text, 'utf8')
@@ -996,7 +1033,7 @@ async function doExport(
 //（max-lines 拆分轮机械提取）；本段保留 F7 what 校验与 doExtract 编排（定位依赖
 // tool-handler 私有的 resolveSessionId/safeParse/segmentTurns）。纯提取，不调 LLM。
 
-/** what 类型守卫（直接比较，避开不安全断言；schema 已校验，此处防御 + 可单测绕过）。 */
+/** what 类型检查（直接比较，避开不安全断言；schema 已校验，此处防御 + 可单测绕过）。 */
 function isExtractWhat(v: unknown): v is ExtractWhat {
   return (
     v === 'user-messages' ||
@@ -1026,7 +1063,8 @@ async function doExtract(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const { entries } = await loadParsed(resolved, agentDir)
   // extract 遍历全量 entry（含旁支/压缩历史），与 outline/expand/detail 的 leaf 视图不同：
   // 素材提取要全量（design §2.3 实测全量 519 toolCall / 26 user / 515 toolResult），
@@ -1109,7 +1147,7 @@ interface SkippedRun {
  * session 会抛「session not found in family index」）——resolveSessionId 已把 session 解析到
  * 真实文件（kind==='ok' 保证文件存在，三形态：绝对路径/sa-id 均 existsSync 校验，片段匹配
  * 来自实际 fs 扫描），直接用 resolved.fileName 构造单条目 sessionIdToPath 调 resolveWorkflows
- *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 传空 Map（单条目链路无其他
+ *（与 buildFamilyFromFs 步骤 6 的 workflow 路径同源）。pathToRef 传空 Map（单条目链路无其他
  * 文件可反查），call 引用 100% 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，
  * 足够 LLM 跳 outline/detail 深读）。
  *
@@ -1131,7 +1169,7 @@ async function renderSingleWorkflowRun(
 ): Promise<void> {
   // [D16③] 概览链换源：v2 档的 stateFile = record 流路径（recordPath 锚点语义
   // 重定义）——直读流经 parseRunRecordStream 概览（[D2] 三态 status；空流/读失败
-  // 投影 running，活跃 run 概览不退化为 skipped——红线）。record 后缀以外的
+	// 映射 running，活跃 run 概览不退化为 skipped——红线）。record 后缀以外的
   // stateFile（v1 快照档空串 / 旧指针档 link path）走原快照链。
   if (wf.stateFile.endsWith('.record.jsonl')) {
     await renderRunFromRecordStream(wf, ctx)
@@ -1205,7 +1243,8 @@ async function doWorkflow(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
 
   let workflows: WorkflowRef[]
   try {
@@ -1391,7 +1430,7 @@ export async function handleSessionRead(
     case 'workflow':
       return doWorkflow(params, agentDir, signals.liveSessionDir)
     case 'result': {
-      // per-call 构造注入面（仅剩 tool-handler 文件私有 helper，纯函数经 handler-utils
+      // per-call 构造注入点（仅剩 tool-handler 文件私有 helper，纯函数经 handler-utils
       // 直接 import——ext-simplify-04 E5）：resolveSessionId 包装把信号包中的
       // liveSessionDir 闭包进解析调用（ResultActionDeps 接口签名固定 5 参，包装保持
       // 同形、末位补传），result 的片段形态与 find/outline 消费同一 roots

package/src/tui/session-command.ts

@@ -77,7 +77,7 @@ export function createSessionCommand(
       const chosen = await ctx.ui.select('选择一个 session 插入 # 引用', labels)
       if (chosen === undefined) return
       // chosen 必属 labels（select 契约返回列表成员或 undefined，后者上一行已拦截），
-      // indexOf 恒命中——不再保留 idx<0 死防御分支
+      // indexOf 恒命中——不再保留 idx<0 永不命中的防御机制分支
       const idx = labels.indexOf(chosen)
       // 选中后插入 # + 完整 uuid（剥 # 算片段，再补 # 插入编辑器）
       const frag = toCandidate(top[idx]).insertText.slice(1)

package/src/zcode-anchor-classify.ts

@@ -5,7 +5,7 @@
  *
  * 判定与 entry-anchor.ts 的 zcodeAnchorOfEntry 双键判据同构（v1 快照 / v2 终态条
  * 双版本门），协议字面量同值（写侧 subagent-core record-entry.ts
- * SUBAGENT_RECORD_CUSTOM_TYPE，漂移由 entry-anchor.test.ts 守卫）。
+ * SUBAGENT_RECORD_CUSTOM_TYPE，漂移由 entry-anchor.test.ts 检查）。
  */
 import type { Entry } from '@zhushanwen/session-core'
 import type { ZcodeAnchorMissingReason } from './discovery/zcode-manifest.js'
@@ -13,7 +13,7 @@ import type { ZcodeAnchorMissingReason } from './discovery/zcode-manifest.js'
 /**
  * v2 条目 data 的认识版本词表（W1 起 = 2）。与写侧 subagent-core
  * SUBAGENT_RECORD_ENTRY_VERSION 同值——本地持有 + entry-anchor.test.ts 跨包断言
- * 守卫漂移（生产依赖面不引 subagent-core，同 entry-anchor.ts 的协议字面量模式）。
+ * 检查漂移（生产依赖范围不引 subagent-core，同 entry-anchor.ts 的协议字面量模式）。
  */
 const SUBAGENT_RECORD_ENTRY_V2 = 2