@zhushanwen/pi-session-reader 0.11.0 → 0.12.0

package/src/discovery/subagents.ts

@@ -1,11 +1,11 @@
 import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
-import { join, basename } from 'node:path'
+import { join } from 'node:path'
 import type { Entry } from '@zhushanwen/session-core'
 import type { Family, SessionRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
 import { listZcodeManifests } from './zcode-manifest.js'
-import { resolveSessionRoots, type SessionFileMeta } from './roots.js'
+import { resolveSessionRoots, resolveSessionStoreRoot, resolveStoreSubagentRecordsDir, listSessionStorePartitions, type SessionFileMeta } from './roots.js'
 import { parseSessionHeader, readSessionHeaderFirstLine } from './session-header.js'
 import { resolveWorkflows } from './workflows.js'
 
@@ -186,7 +186,8 @@ async function collectSubagentIdentities(
   // U4 数据流：manifest 命中透全字段；未命中 P-fallback 读尾行 identity 取 task/slug/agent
   //（model/status 不可回退，留 undefined）；无 manifest 无 identity（运行中/异常）跳过。
   // A3（ext-simplify-04）：直调 resolveSessionRoots（原 listSubagentSessions 薄包装已删除）
-  //——agentDir 信号包下 [subagent] 根 = <agentDir>/subagents（常量推导，恒唯一）
+  //——[subagent] 根 = session 存储树（[session-store-layout-inversion] 单新根，常量
+  // 推导，恒唯一；扫描定向探各 sid 分区的 subagents/sessions/）。
   const subMetas =
     (await resolveSessionRoots({ agentDir })).find((r) => r.kind === 'subagent')?.files ?? []
   for (const meta of subMetas) {
@@ -418,31 +419,37 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
 }
 
 /**
- * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 由终态 finalize 或 sync 批落标出口写入（创建时不写），持久存在即使
+ * 扫描 records/*.json —— subagent 注册清单（读侧单新根，[session-store-layout-inversion]
+ * D6 裁决：旧布局存量原位保留、不再读写——旧 record 从 agent 面 result/find 消失是该
+ * 裁决取舍清单明示项，不做旧根兼容扫描）。
+ * 每个 manifest 由终态 finalize 或 rebuildIndexes 投影写入（创建时不写），持久存在即使
  * .jsonl 被 GC。坏 manifest（缺必填字段/JSON 损坏）跳过，不中断扫描。
+ *
+ * 单新根：`<dataDir>/ext-sessions`（dataDir = dirname(agentDir)，布局 B agentDir =
+ * `<dataDir>/agent`；树根段镜像 shared SESSION_STORE_DIR_SEGMENT，对拍机检锚点 =
+ * scripts/check-artifact-dir-formula-sync.mjs 域 9）。新布局 records 在
+ * `<root>/<sid>/subagents/records/`（分区键 = rootSessionId，嵌套派发全层同值——
+ * 嵌套 subagent 的 manifest 同落根会话分区，固定位置扫描完整覆盖）。扫描剪枝：
+ * `<root>/` 一级只进 isPiSessionId 形态目录（不进 logs/attachments 等大目录），每个
+ * sid 分区内只探 subagents/records/ 固定位置，不整树递归。根不存在时静默空读。
  */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
-  const root = join(agentDir, 'subagents')
+  const storeRoot = resolveSessionStoreRoot(agentDir)
   const out: RecordManifest[] = []
-  async function walk(dir: string): Promise<void> {
+  for (const sid of await listSessionStorePartitions(storeRoot)) {
+    const recordsDir = resolveStoreSubagentRecordsDir(agentDir, sid)
     let entries
     try {
-      entries = await readdir(dir, { withFileTypes: true })
+      entries = await readdir(recordsDir, { withFileTypes: true })
     } catch {
-      return // 目录不存在/无权限 → 静默返回
+      continue // 该分区无 records/（无 subagent 的会话）→ 静默跳过
     }
     for (const e of entries) {
-      const full = join(dir, e.name)
-      if (e.isDirectory()) {
-        await walk(full)
-      } else if (e.isFile() && e.name.endsWith('.json') && basename(dir) === 'records') {
-        const m = await tryReadManifest(full)
-        if (m) out.push(m)
-      }
+      if (!e.isFile() || !e.name.endsWith('.json')) continue
+      const m = await tryReadManifest(join(recordsDir, e.name))
+      if (m) out.push(m)
     }
   }
-  await walk(root)
   return out
 }
 

package/src/discovery/whitelist.ts

@@ -16,8 +16,8 @@ import { zcodeImportDbAllowlist } from '@zhushanwen/zcode-session-source'
  *
  * **检查顺序铁律（§3.4 三段递进，实现与测试双锚定）**：存在性先于路径——
  * `existsSync` 为 false 报 `zcode_db_unreadable`（库文件不存在）而非
- * `zcode_db_path_forbidden`，避免把「只是还没落库」误报成安全事件（forbidden 是
- * 安全面错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
+ * `zcode_db_path_forbidden`，避免把「只是还没写入仓库」误报成安全事件（forbidden 是
+ * 安全侧错误，语义更重、更惊扰 agent）。存在才 realpath 后与派生允许集合精确比对。
  * 开库（第 3 段）由调用方在本闸通过后进行。
  *
  * **TOCTOU 残留（设计 §3.4 显式登记，不在本梯队硬化）**：realpath 之后仍按原
@@ -72,10 +72,10 @@ export function formatZcodeDbPathForbidden(dbPath: string): string {
  * 白名单闸（第 1 段存在性 → 第 2 段路径；通过才允许开库）。
  *
  * @throws Error（消费侧映射为 zcode_db_unreadable / zcode_db_path_forbidden，
- *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误面）
+ *         消息即 §3.4 的 👉 指引文案——tool-handler 直接 throw 给 pi 错误范围）
  */
 export function assertZcodeDbPathAllowed(dbPath: string, agentDir: string): void {
-  // 第 1 段 存在性（先于路径——「还没落库」不是安全事件）
+	// 第 1 段 存在性（先于路径——「还没写入仓库」不是安全事件）
   if (!existsSync(dbPath)) {
     throw new Error(formatZcodeDbUnreadable(dirname(agentDir), `（库文件不存在：${dbPath}）`))
   }

package/src/discovery/workflows.ts

@@ -17,7 +17,7 @@ import { extractSessionIdFromFilename } from './subagents.js'
 //   ——家族链数据源同 record 流，无第二承载位）；旧后缀锚点（.events.jsonl 形态）=
 //   历史实体（[D1] 历史数据处置：旧两件不读）→ calls=[] 仅 run 存在性兜底。
 //   历史格式条目（v1 全量快照 / workflow-state-link 指针）不识别、静默从发现链消失
-//   （不拒读、不报错）——run 侧 v1 读面已删除（ADR-0095，同 record 侧裁决：项目未
+//   （不拒读、不报错）——run 侧 v1 读侧已删除（ADR-0095，同 record 侧裁决：项目未
 //   上线无历史数据，不迁移不兼容）。
 // - readRunSnapshot：读 wf-state 文件尾向找首个可解析行，返回原始对象（unknown，格式
 //   收窄交 core 层）。唯一消费方 = tool-handler workflow 概览的快照链分支。
@@ -82,16 +82,16 @@ function sessionRefFromPath(path: string, pathToRef: Map<string, SessionRef>): S
 }
 
 // ============================================================
-// workflow-record 条目契约（v2 注册条目判别——本地字面量 + 测试守卫漂移）
+// workflow-record 条目契约（v2 注册条目判别——本地字面量 + 测试检查漂移）
 // ============================================================
 
 /**
  * `workflow-record` custom entry 的 customType 值。
  *
  * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core
- * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖面不引
+ * workflow-record-entry.ts 的 WORKFLOW_RECORD_CUSTOM_TYPE。reader 生产依赖范围不引
  * subagent-core（同 entry-anchor.ts 的协议字面量模式），两侧漂移由 workflow.test.ts
- * 的跨包断言守卫。
+ * 的跨包断言检查。
  */
 const WORKFLOW_RECORD_CUSTOM_TYPE = 'workflow-record'
 
@@ -102,7 +102,7 @@ const WORKFLOW_RECORD_ENTRY_V2 = 2
  * run record 流文件名尾段（`<runId>.record.jsonl`）。写侧 subagent-core
  * RUN_EVENTS_SUFFIX 同值（[D1] record 单源后缀）——v2 注册条目的
  * recordPath 锚点后缀判定用（新锚点直读 record 流；旧 `.events.jsonl` 锚点 =
- * 历史实体分流），本地持有 + 测试守卫漂移。
+ * 历史实体分流），本地持有 + 测试检查漂移。
  */
 export const RUN_RECORD_STREAM_SUFFIX = '.record.jsonl'
 
@@ -142,7 +142,7 @@ function collectRegisteredRecordPaths(entries: readonly Entry[]): RegisteredReco
 /**
  * [D16③] recordPath 后缀分流：`.record.jsonl` 锚点 = 新形态（record 流直读）；
  * 其余（含旧 `.events.jsonl` 锚点）= 历史实体（[D1] 历史数据处置——旧两件不读
- * 不写，历史 run 从发现链数据面退空即预期行为）。
+ * 不写，历史 run 从发现链的数据中退空即预期行为）。
  */
 function isNewRecordStreamAnchor(recordPath: string): boolean {
   return recordPath.endsWith(RUN_RECORD_STREAM_SUFFIX)
@@ -155,7 +155,7 @@ interface AgentSettledSessionFileView {
   result: { sessionFile: string }
 }
 
-/** [extractRecordStreamSessionFiles 守卫] 单帧是否为携带非空 result.sessionFile
+/** [extractRecordStreamSessionFiles 检查] 单帧是否为携带非空 result.sessionFile
  *  的 agent-settled 帧：逐字段 typeof 校验（type → taskIndex → result →
  *  sessionFile），不过关 = 宽容跳过（与 readRunSnapshot 同容忍度）。 */
 function isAgentSettledSessionFileFrame(v: unknown): v is AgentSettledSessionFileView {
@@ -194,7 +194,7 @@ export function extractRecordStreamSessionFiles(content: string): string[] {
 /**
  * 读目标 session 文件全文，从 workflow-record v2 注册条目构造 WorkflowRef[]
  * （单档发现链——v1 快照条目与 workflow-state-link 指针条目不再识别，历史 run
- * 从发现链数据面退空即预期行为，见 ADR-0095）。同一 runId 的多条目后写覆盖
+ * 从发现链的数据中退空即预期行为，见 ADR-0095）。同一 runId 的多条目后写覆盖
  * （条目顺序 = 时间顺序，取最新锚点）。
  *
  * **签名与返回值结构（WorkflowRef[]{runId,stateFile,calls:SessionRef[]}）不变**

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/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,7 +156,7 @@ 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.',
   'Errors carry a 👉 recovery hint—follow it to retry.',
@@ -250,7 +250,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

@@ -147,7 +147,7 @@ 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 {
   return [

package/src/result-action.ts

@@ -31,7 +31,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,

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 等公共类型留
@@ -84,7 +84,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 +131,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 +145,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 +154,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) {

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 索引解析低层小工具）。
@@ -26,7 +26,7 @@
  */
 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'
@@ -102,7 +102,7 @@ import {
   extractUserMessages,
   type ExtractWhat,
 } from './extract.js'
-// 同轮拆分的渲染域模块（format* 纯函数簇，含 zcode 错误面 message 与
+// 同轮拆分的渲染域模块（format* 纯函数簇，含 zcode 错误范围 message 与
 // zcodeReadErrorMessage 错误映射）：运行时依赖方向本模块 → tool-format，
 // tool-format 对本模块仅 type import（ToolResult），无循环。
 import {
@@ -132,7 +132,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')
@@ -267,7 +267,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 +287,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 +299,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 +391,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: '' }
     }
@@ -501,8 +501,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 +515,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 +545,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()
@@ -912,7 +912,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,
@@ -972,8 +972,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 +1004,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' ||
@@ -1109,7 +1117,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 +1139,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)
@@ -1391,7 +1399,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