@zhushanwen/pi-session-reader 0.6.0 → 0.7.0

package/src/__tests__/zcode-whitelist.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  assertZcodeDbPathAllowed,
+  zcodeDbAllowlistFor,
+} from '../discovery/whitelist.js'
+
+// ============================================================
+// P-whitelist（design session-reader-shared-core §3.3 D5 / §3.4 检查顺序 / 附录 A）：
+// 派生白名单在 taiji dataDir 布局下精确命中隔离库。
+//
+// 布局（mkdtemp 自建自删）：root/agent = agentDir（dirname = dataDir root），
+// root/engines/zcode/session-db/db.sqlite = 隔离库。测试内手拼路径段是**测试对
+// 派生正确性的唯一验证手段**（生产 src 禁手拼，段单源 = SDK ZCODE_ISOLATED_DB_
+// SEGMENTS 经 zcode-session-source zcodeImportDbAllowlist 引用）。
+//
+// 检查顺序铁律断言：存在性（不存在 → unreadable）先于路径（集合外 → forbidden）——
+// 集合外且不存在的路径必须报 unreadable 而非 forbidden（场景 5 ④ 顺序断言的单元锚）。
+// ============================================================
+
+const ISOLATED_DB_SEGMENTS = ['engines', 'zcode', 'session-db', 'db.sqlite']
+
+let root: string
+let agentDir: string
+let isolatedDbPath: string
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'zcode-whitelist-test-'))
+  agentDir = join(root, 'agent')
+  mkdirSync(agentDir, { recursive: true })
+  isolatedDbPath = join(root, ...ISOLATED_DB_SEGMENTS)
+})
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+})
+
+describe('zcodeDbAllowlistFor：tmp dataDir 布局精确命中隔离库（P-whitelist）', () => {
+  it('第一项 = zcodeIsolatedDbPath(dirname(agentDir))，集合共两项（隔离库 + 宿主库）', () => {
+    const allow = zcodeDbAllowlistFor(agentDir)
+    expect(allow).toHaveLength(2)
+    // 精确命中：手拼段与派生结果逐字节相等（同源常量 + 同一 join 派生式的行为锚）
+    expect(allow[0]).toBe(isolatedDbPath)
+  })
+
+  it('realpath 对齐：agentDir 经 symlink 到达（macOS /var → /private/var 形态）仍命中', () => {
+    // tmpdir 本身在 macOS 即 symlink 链（/var → /private/var）：mkdtemp 产物 realpath
+    // 后 ≠ 字面串。允许集合与 dbPath 同经 realpath 归一（whitelist.ts realOf），
+    // 两侧一致归一后比对 = 命中。isolatedDbPath 真实存在才有 realpath 归一输入。
+    mkdirSync(join(root, ...ISOLATED_DB_SEGMENTS.slice(0, -1)), { recursive: true })
+    writeFileSync(isolatedDbPath, '', 'utf8')
+    expect(() => assertZcodeDbPathAllowed(isolatedDbPath, agentDir)).not.toThrow()
+  })
+
+  it('纯 pi 宿主边界（D5）：agentDir 无对应 dataDir 布局时集合外路径照常拒绝', () => {
+    const outside = join(root, 'somewhere-else', 'db.sqlite')
+    mkdirSync(join(root, 'somewhere-else'), { recursive: true })
+    writeFileSync(outside, '', 'utf8')
+    expect(() => assertZcodeDbPathAllowed(outside, agentDir)).toThrow('zcode_db_path_forbidden')
+  })
+})
+
+describe('assertZcodeDbPathAllowed：检查顺序三段递进（存在性先于路径）', () => {
+  it('第 1 段存在性：白名单内路径但文件不存在 → zcode_db_unreadable（不误报 forbidden）', () => {
+    expect(() => assertZcodeDbPathAllowed(isolatedDbPath, agentDir)).toThrow(
+      'zcode_db_unreadable',
+    )
+  })
+
+  it('第 1 段先于第 2 段：集合外且文件不存在的路径 → 仍是 unreadable（不是 forbidden）', () => {
+    const outsideMissing = join(root, 'nowhere', 'evil.sqlite')
+    expect(() => assertZcodeDbPathAllowed(outsideMissing, agentDir)).toThrow(
+      'zcode_db_unreadable',
+    )
+  })
+
+  it('第 2 段路径：存在但集合外 → zcode_db_path_forbidden（安全面错误语义更重）', () => {
+    const outside = join(root, 'evil.sqlite')
+    writeFileSync(outside, '', 'utf8')
+    try {
+      assertZcodeDbPathAllowed(outside, agentDir)
+      expect.unreachable('should have thrown')
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain('zcode_db_path_forbidden')
+      expect(msg).toContain(outside)
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('通过闸（集合内且存在）→ 不抛错（开库由调用方进行）', () => {
+    mkdirSync(join(root, ...ISOLATED_DB_SEGMENTS.slice(0, -1)), { recursive: true })
+    writeFileSync(isolatedDbPath, '', 'utf8')
+    expect(() => assertZcodeDbPathAllowed(isolatedDbPath, agentDir)).not.toThrow()
+  })
+
+  it('unreadable 指引含动态推导的隔离库路径与 -wal 告诫（§3.4 文案）', () => {
+    try {
+      assertZcodeDbPathAllowed(isolatedDbPath, agentDir)
+      expect.unreachable('should have thrown')
+    } catch (e) {
+      const msg = (e as Error).message
+      expect(msg).toContain(isolatedDbPath)
+      expect(msg).toContain('-wal')
+      expect(msg).toContain('👉')
+    }
+  })
+
+  it('宿主库第二项 = join(homedir(), SDK 宿主段)（存量兼容锚点，不在本梯队触碰）', () => {
+    const allow = zcodeDbAllowlistFor(agentDir)
+    // 第二项是 homedir 派生的宿主库（真实 HOME 下的 .zcode/cli/db/db.sqlite 形态）——
+    // 测试不触碰真实文件，只断言其位于集合且 ≠ 隔离库项
+    expect(allow[1]).not.toBe(allow[0])
+    expect(allow[1].startsWith(homedir())).toBe(true)
+  })
+})

package/src/core/execution-tree.ts

@@ -437,7 +437,9 @@ export async function buildExecutionTree(
       sessionId: rootSessionId,
       // MF-1：main root 携带 sessionFile（调用方传入），否则 attachWorkflowChildren 对无
       // sessionFile 节点直接 return，main 自身发起的 workflow run 永远进不了执行树。
-      sessionFile: mainSessionFile,
+      // falsy 归一为 undefined：调用方的「路径不可得」哨兵是空串（zcode family 路由
+      // 反查未命中），root 节点 details 不携带 sessionFile:"" 这类非路径占位值。
+      sessionFile: mainSessionFile || undefined,
       depth: 0,
       rootSessionId,
       children: [],

package/src/core/family.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 /**
  * 家族索引与解析（design §3.3 D-7）。
@@ -78,6 +78,74 @@ export interface FamilyIndex {
   fileStats: Map<string, { mtime: number; size: number }>
 }
 
+// ---- zcode 节点（design session-reader-shared-core §3.3 D5-1）----
+
+/**
+ * zcode subagent 节点的判据输入视图（discovery 层 zcode-manifest.ts 枚举产出，
+ * core 层零 IO 消费）。扁平化：dbPath 取自 manifest engineHandle.sessionRef.dbPath
+ * （zcode 锚），dbFileExists 由 discovery 枚举时 statSync 预计算——stat 只查存在性
+ * **不开库**（D5-1：静息态 CANTOPEN 会把活会话误判已 GC，且列表视图每节点开库的
+ * 成本不该付；库内 session 已被 zcode GC 的情形由 read 路径 zcode_session_not_found
+ * 权威承接，列表视图保持廉价是本判据的设计核心）。
+ */
+export interface ZcodeFamilyNode {
+  /** record id（= sa-id，manifest 文件名 stem）。作 SubagentRef.sessionId（pi 孤儿链同款：entry.id = manifest.id） */
+  id: string
+  /** subagent 的发起 session id（subagentsByRoot 挂载键，与 pi identity.data.rootSessionId 同语义） */
+  rootSessionId: string
+  /** slug 标签（discovery 组装时已兜底 m.slug ?? m.agentName ?? ''，与 pi 孤儿链同款） */
+  slug: string
+  /** agent 类型名 */
+  agentName?: string
+  task?: string
+  model?: string
+  status?: string
+  /** zcode 锚的库路径（engineHandle.sessionRef.dbPath；枚举谓词已保证非空 string） */
+  dbPath: string
+  /** 库文件存在性（discovery 枚举时 statSync 预计算；D5-1 第二判据的唯一输入） */
+  dbFileExists: boolean
+}
+
+/**
+ * zcode 节点 → subagentsByRoot（D5-1 判据落地）。
+ *
+ * 判据（两项、不开库）：**锚可解析 ∧ 库文件存在 → cleanedUp=false；缺一 → true**。
+ * 「锚可解析」在枚举层已构造性成立（listZcodeManifests 谓词 = engine==='zcode' ∧
+ * sessionRef 双键齐，未通过的记录不产出）——core 层只需消费 dbFileExists。
+ *
+ * 与 pi 节点**刻意不同构**（D5-1 显式声明）：pi 判据 = fileStats JSONL 文件存在性
+ * （buildSubagentsByRoot 的 !fileStats.has(ident.id)）；zcode 节点住在 SQLite 库里、
+ * 没有 JSONL 文件，「文件在不在」对它是无效判据。二者不互相回归。
+ */
+export function buildZcodeSubagentsByRoot(
+  nodes: readonly ZcodeFamilyNode[],
+): Map<string, SubagentRef[]> {
+  const byRoot = new Map<string, SubagentRef[]>()
+  for (const n of nodes) {
+    const ref: SubagentRef = {
+      // zcode 节点无 subagent session 文件，sessionId 用 record id（pi 孤儿链同款占位）
+      sessionId: n.id,
+      rootSessionId: n.rootSessionId,
+      slug: n.slug,
+      fileName: '', // 占位空串（family 路径不回填，与 pi 一致）
+      mtime: 0, // 无 JSONL 文件可 stat，恒 0（占位约定，见文件头注释）
+      sizeBytes: 0,
+      cwd: '',
+      // D5-1：锚可解析（枚举谓词已过）∧ 库文件存在 → false；缺一 → true（GC 语义）
+      cleanedUp: !n.dbFileExists,
+      task: n.task,
+      agentName: n.agentName,
+      model: n.model,
+      status: n.status,
+      // sessionFile 不设：zcode 无 session.jsonl（pi 孤儿保留 GC 路径，zcode 无路径可保留）
+    }
+    const list = byRoot.get(n.rootSessionId)
+    if (list) list.push(ref)
+    else byRoot.set(n.rootSessionId, [ref])
+  }
+  return byRoot
+}
+
 // ---- 类型守卫：从 unknown 的 entry.data 提取 subagent identity 字段 ----
 
 /**
@@ -225,6 +293,8 @@ function buildSubagentsByRoot(
  * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
  * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
  * - fileStats 原样存入 index，供 cleanedUp 判断
+ * - zcodeNodes（可选，U6）→ zcode subagent 节点并入 subagentsByRoot（D5-1 判据，
+ *   与 pi 判据不同构；不传 = pi 行为逐字节不变——零涟漪）
  *
  * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
  * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
@@ -233,10 +303,19 @@ export function buildFamilyIndex(
   headers: Entry[],
   subagentIdentities: Entry[],
   fileStats: Map<string, { mtime: number; size: number }>,
+  zcodeNodes?: readonly ZcodeFamilyNode[],
 ): FamilyIndex {
   const byId = buildById(headers, fileStats)
   const childrenOf = buildChildrenOf(headers, byId)
   const subagentsByRoot = buildSubagentsByRoot(subagentIdentities, fileStats)
+  if (zcodeNodes !== undefined && zcodeNodes.length > 0) {
+    const zcodeByRoot = buildZcodeSubagentsByRoot(zcodeNodes)
+    for (const [rootId, refs] of zcodeByRoot) {
+      const existing = subagentsByRoot.get(rootId)
+      if (existing) existing.push(...refs)
+      else subagentsByRoot.set(rootId, refs)
+    }
+  }
   return { byId, childrenOf, subagentsByRoot, fileStats }
 }
 

package/src/core/render.ts

@@ -1,4 +1,5 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
+import { BYTES_PER_KB } from './units.js'
 import { extractToolCalls, formatToolCallSummary, type ToolCallInfo } from './toolcall.js'
 import type { Turn } from './turns.js'
 import type { TreeView } from './tree.js'
@@ -7,8 +8,6 @@ import type { TreeView } from './tree.js'
 // 模块常量（渲染口径：截断宽度 / 换算基数 / 降级档位）
 // ---------------------------------------------------------------------------
 
-/** bytes→KB 换算基数（omitted 字节 / read 结果规模的 KB 显示）。 */
-const BYTES_PER_KB = 1024
 /** userBrief 截断字符数（TurnBrief.userBrief 文档口径「截 60 字符」）。 */
 const USER_BRIEF_MAX_CHARS = 60
 /** assistantBrief 截断字符数（TurnBrief.assistantBrief 文档口径「截 80 字符」）。 */

package/src/core/toolcall.ts

@@ -6,9 +6,10 @@
  *   message.toolCalls 顶层字段从未存在——v1 render.ts 读 toolCalls 恒返 [] 是 O1 要修的 bug。
  * - arguments 始终是 object（10 工具 100%）；string 形态做 JSON.parse 兜底（失败返 {}），防御历史/异类实现。
  * - toolResult.message 自带 toolName + toolCallId（515/515，全部匹配 toolCall.id），
- *   parser.ts 已 additive 透出这两个字段，O2/O3 据此精确关联取参数。
+ *   Entry 接口（session-core 基座）已 additive 透出这两个字段，O2/O3 据此精确关联取参数。
  */
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
+import { BYTES_PER_KB } from './units.js'
 
 // ---------------------------------------------------------------------------
 // 模块常量（参数摘要的截断宽度 / 换算基数）
@@ -20,8 +21,6 @@ const BASH_CMD_MAX_CHARS = 60
 const SUBAGENT_TASK_MAX_CHARS = 40
 /** 未知工具 arguments JSON 摘要截断字符数。 */
 const ARGS_JSON_MAX_CHARS = 50
-/** bytes→KB 换算基数（write content 的 KB 显示）。 */
-const BYTES_PER_KB = 1024
 
 /** 单次工具调用信息（从 assistant content 的 toolCall block 提取）。 */
 export interface ToolCallInfo {

package/src/core/tree.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 export interface TreeView {
   /** root → leaf 的 id 序列（pi 重开视角的当前对话线，design D-2） */

package/src/core/turns.ts

@@ -1,4 +1,4 @@
-import type { Entry } from './parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 /**
  * 一轮对话（design §3.5 算法 3 的分段产物，冻结接口）。

package/src/core/units.ts

@@ -0,0 +1,14 @@
+/**
+ * 字节量纲换算基数（本包内 KB/MB 换算的唯一来源）。
+ *
+ * 本包是独立 npm 发布的 pi extension（仅依赖 pi-ext-guards），不 import taiji 内部
+ * workspace 包（@taiji/shared 的 BYTES_PER_MB 单点不含本包）——量纲基数本地定义，
+ * 数值对齐由注释锚定（1MB = 1024×1024）。三个消费域（render 的 omitted 标记 /
+ * toolcall 的 write 摘要 / search-across 的预算与人性化格式化）共用本单点，
+ * 避免同值常量在本包内多份分裂。
+ */
+
+/** bytes→KB 换算基数（omitted 字节 / read 结果规模 / write content 的 KB 显示）。 */
+export const BYTES_PER_KB = 1024
+/** bytes→MB 换算基数（跨会话检索预算与人性化格式化）。 */
+export const BYTES_PER_MB = BYTES_PER_KB * BYTES_PER_KB

package/src/discovery/entry-anchor.ts

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises'
+
+import { parseSessionContent, type Entry } from '@zhushanwen/session-core'
+
+/**
+ * zcode 锚的 entry 兜底定位（设计 session-reader-shared-core §3.1 第②步）。
+ *
+ * 定位链第②层：zcode manifest 直读（第①层，zcode-manifest.ts）缺位/残缺时，
+ * 在候选主 session 文件里按 sa-id 扫 `subagent-record` custom entry，取其
+ * `engineHandle.sessionRef`（zcode 形态 = `{sessionId, dbPath}`）。
+ *
+ * 边界承载（设计四要素登记）：本函数只认「候选文件列表」，越界语义（不做根内
+ * 全扫、liveSessionDir 优先排序）由调用方构造候选集时决定——第一梯队只传
+ * liveSessionDir 内的主 session 文件，越界查询返回 not-found 信号（undefined，
+ * 调用方映射 `zcode_record_not_found` 错误码，§3.4）。
+ */
+
+/**
+ * zcode 锚（zcode 引擎自描述定位符的 zcode 形态）。与 manifest 直读产出的锚同形；
+ * `sessionRef` 写侧整体透传不枚举内部键（subagent-core record-entry.ts
+ * engineHandle.sessionRef 注释），本单元按 zcode 形态校验并窄化为双键。
+ */
+export interface ZcodeAnchor {
+  sessionId: string
+  dbPath: string
+}
+
+/**
+ * `subagent-record` custom entry 的 customType 值。
+ *
+ * 磁盘 JSONL 协议字符串（跨侧契约）：写侧单源 = subagent-core record-entry.ts 的
+ * SUBAGENT_RECORD_CUSTOM_TYPE。reader 生产依赖面不引 subagent-core（该包是
+ * devDependency + vitest alias 形态），故按协议字符串本地持有；两侧漂移由
+ * entry-anchor.test.ts 的跨包断言守卫。
+ */
+const SUBAGENT_RECORD_CUSTOM_TYPE = 'subagent-record'
+
+/**
+ * 从单条 entry 提取 zcode 锚。形状校验窄而严，任一不满足 = 该条不算命中（返回
+ * undefined，调用方继续扫——缺键条目不遮蔽更早的完整条目）：
+ * - `type === 'custom'` ∧ `customType === 'subagent-record'`
+ * - `data.v === 1`（schema 版本守卫，不认识的版本跳过而非猜测——写侧 record-entry.ts v 注释同口径）
+ * - `data.id === saId`（record id 即 sa-id，record-access.ts `sa-${uuid}`）
+ * - `engineHandle.sessionRef.sessionId` / `.dbPath` 均为非空 string（F8 双键齐判据的
+ *   锚字段部分；pi record 的 sessionRef 无 dbPath → 天然不命中，无需 engine 判别）
+ */
+function zcodeAnchorOfEntry(entry: Entry, saId: string): ZcodeAnchor | undefined {
+  if (entry.type !== 'custom' || entry.customType !== SUBAGENT_RECORD_CUSTOM_TYPE) return undefined
+  const data: unknown = entry.data
+  if (typeof data !== 'object' || data === null) return undefined
+  const d = data as Record<string, unknown>
+  if (d.v !== 1 || d.id !== saId) return undefined
+  const handle: unknown = d.engineHandle
+  if (typeof handle !== 'object' || handle === null) return undefined
+  const ref: unknown = (handle as Record<string, unknown>).sessionRef
+  if (typeof ref !== 'object' || ref === null) return undefined
+  const r = ref as Record<string, unknown>
+  const { sessionId, dbPath } = r
+  if (typeof sessionId !== 'string' || sessionId === '') return undefined
+  if (typeof dbPath !== 'string' || dbPath === '') return undefined
+  return { sessionId, dbPath }
+}
+
+/**
+ * 在候选主 session 文件里按 sa-id 定位 zcode 锚。
+ *
+ * 取条语义（设计 §2.5 裁决，subagent-core collectLastRecordEntries 逐字同构——
+ * 「主 session 全文 → 每 id 末条 record data」，record-store-rebuild.ts:212-227）：
+ * 同一 sa-id 每次状态迁移写一条全量快照 entry 且 sessionRef 每轮覆写（F16），故
+ * 同文件内后条覆盖前条 = 文件顺序末条。**禁止另创取首条/合并语义**（附录 B-6）。
+ *
+ * 多候选文件：按候选列表顺序逐文件扫，文件内有命中锚（含末条裁决后）即止——
+ * 候选顺序 = 调用方声明的优先级（liveSessionDir 优先），不跨文件合并。
+ *
+ * 行级容错：逐行解析由基座 parseSessionContent 承担（坏行跳过继续、末行半行记
+ * lastLinePartial 不中断）——best-effort，不因一行坏 JSON 失败整文件。
+ *
+ * 候选文件读失败（不存在/不可读）= 该候选无命中，跳过继续下一候选；本函数契约
+ * 是「锚或 not-found」，IO 错误同样收敛到 not-found 信号（调用方映射错误码），
+ * 不向上抛。
+ *
+ * 读取用 node:fs/promises 的 async readFile——本函数跑在 pi 扩展进程内，同步
+ * readFileSync 全文读入会阻塞事件循环（同函数族 classifyIncompleteEntryAnchor
+ * 同形态；对照 readSessionHeaderIdSync 只在首行 4KB 有界读时才允许同步）。
+ *
+ * @returns 命中的锚；所有候选均未命中（或全部候选不可读）→ undefined（not-found 信号）
+ */
+export async function findZcodeEntryAnchor(
+  candidateFiles: readonly string[],
+  saId: string,
+): Promise<ZcodeAnchor | undefined> {
+  for (const file of candidateFiles) {
+    let content: string
+    try {
+      content = await readFile(file, 'utf8')
+    } catch {
+      continue
+    }
+    const { entries } = parseSessionContent(content)
+    let anchor: ZcodeAnchor | undefined
+    for (const entry of entries) {
+      const hit = zcodeAnchorOfEntry(entry, saId)
+      if (hit !== undefined) anchor = hit
+    }
+    if (anchor !== undefined) return anchor
+  }
+  return undefined
+}

package/src/discovery/env.ts

@@ -12,35 +12,35 @@ import { dirname } from 'node:path'
  * 齐备），不 import roots.ts 的信号类型，避免并行单元耦合；接线层分别组装两种信号包。
  *
  * 信号可靠性依据（design §4.4 活体实测表，非推断）：
- * - XYZ_AGENT_EXT_LOG 单独使用可靠性「中」——runtime 无条件注入，但
- *   ENV_WHITELIST_PREFIXES 含裸 `XYZ_` 前缀，用户 shell 里的同名变量会透传进任何进程；
+ * - TAIJI_AGENT_EXT_LOG 单独使用可靠性「中」——runtime 无条件注入，但
+ *   ENV_WHITELIST_PREFIXES 含裸 `TAIJI_` 前缀，用户 shell 里的同名变量会透传进任何进程；
  * - PI_CODING_AGENT_DIR 单独使用可靠性「中」——pi 原生变量，裸 pi 用户也可能自设，
- *   但其值形态是 xyz-agent 专属约定：`<*>/.xyz-agent*` 目录后接 `/agent`；
- * - XYZ_AGENT_PACKAGED **不可用**——在 SPAWN_ENV_OUTBOUND_DENY_LIST 被剥除
+ *   但其值形态是 taiji 专属约定：`<*>/.taiji*` 目录后接 `/agent`；
+ * - TAIJI_AGENT_PACKAGED **不可用**——在 SPAWN_ENV_OUTBOUND_DENY_LIST 被剥除
  *  （§4.4 在案结论），故不引入该信号，防后人重蹈。
  * 因此托管判定必须是双信号合取：任一信号单独成立只判 standalone-pi，
  * 透传/自设污染提示写入 evidence。
  */
 
-/** xyz-agent 托管信号 1：runtime 无条件注入的 extension 日志开关（恒 '1'） */
-export const XYZ_AGENT_EXT_LOG_ENV = 'XYZ_AGENT_EXT_LOG'
-/** xyz-agent 托管信号 2：pi agentDir 注入变量；其**值形态**是 xyz-agent 专属约定 */
+/** taiji 托管信号 1：runtime 无条件注入的 extension 日志开关（恒 '1'） */
+export const TAIJI_AGENT_EXT_LOG_ENV = 'TAIJI_AGENT_EXT_LOG'
+/** taiji 托管信号 2：pi agentDir 注入变量；其**值形态**是 taiji 专属约定 */
 export const PI_CODING_AGENT_DIR_ENV = 'PI_CODING_AGENT_DIR'
 /** 数据目录推导首选：runtime getDataDir() 的权威注入值 */
-export const XYZ_AGENT_DATA_DIR_ENV = 'XYZ_AGENT_DATA_DIR'
+export const TAIJI_AGENT_DATA_DIR_ENV = 'TAIJI_AGENT_DATA_DIR'
 
 /** 托管信号 1 的唯一合法值（注释「托管语义恒为 '1'」） */
 const EXT_LOG_MANAGED_VALUE = '1'
 
-// xyz-agent agentDir 值形态（§6.2 双形态兼容——迁移窗口期 B 前后两种布局并存）：
-// - B 后新布局：`<*>/.xyz-agent*` 目录后接 `/agent`（一层）
-// - B 前旧布局：`<*>/.xyz-agent*` 目录后接 `/pi/agent`（两层）
-// `.xyz-agent*` = 以 `.xyz-agent` 开头的目录段（prod `.xyz-agent` / dev `.xyz-agent-dev`）。
-// 三条正则都要求匹配到路径末尾（`$`），调用前输入先经 normalizeXyzPath 剥尾斜杠。
+// taiji agentDir 值形态（§6.2 双形态兼容——迁移窗口期 B 前后两种布局并存）：
+// - B 后新布局：`<*>/.taiji*` 目录后接 `/agent`（一层）
+// - B 前旧布局：`<*>/.taiji*` 目录后接 `/pi/agent`（两层）
+// `.taiji*` = 以 `.taiji` 开头的目录段（prod `.taiji` / dev `.taiji-dev`）。
+// 三条正则都要求匹配到路径末尾（`$`），调用前输入先经 normalizeTaijiPath 剥尾斜杠。
 // （用行注释：形态文本含星号斜杠序列，写进块注释会提前终止注释。）
-const AGENT_DIR_SHAPE_ANY = /(^|\/)\.xyz-agent[^/]*\/(pi\/)?agent$/
-const AGENT_DIR_SHAPE_OLD = /(^|\/)\.xyz-agent[^/]*\/pi\/agent$/
-const AGENT_DIR_SHAPE_NEW = /(^|\/)\.xyz-agent[^/]*\/agent$/
+const AGENT_DIR_SHAPE_ANY = /(^|\/)\.taiji[^/]*\/(pi\/)?agent$/
+const AGENT_DIR_SHAPE_OLD = /(^|\/)\.taiji[^/]*\/pi\/agent$/
+const AGENT_DIR_SHAPE_NEW = /(^|\/)\.taiji[^/]*\/agent$/
 
 /**
  * 打包形态判据（§6.2：bundle 路径判发行形态；无法判定 → null 不猜）。
@@ -56,7 +56,7 @@ const MACOS_PACKAGED_PATTERN = /\.app\/Contents\/Resources\/extensions\//
 const REPO_STAGED_PATTERN = /(^|\/)apps\/electron\/resources\/extensions\//
 const WIN_LINUX_PACKAGED_PATTERN = /(^|\/)resources\/extensions\//
 
-export type EnvironmentKind = 'xyz-agent' | 'standalone-pi'
+export type EnvironmentKind = 'taiji' | 'standalone-pi'
 export type Distribution = 'packaged' | 'dev' | null
 
 export interface EnvironmentSignals {
@@ -71,19 +71,19 @@ export interface EnvironmentSignals {
 export interface DetectedEnvironment {
   kind: EnvironmentKind
   distribution: Distribution
-  /** 托管时的 xyz-agent 数据目录；standalone-pi 恒 undefined */
+  /** 托管时的 taiji 数据目录；standalone-pi 恒 undefined */
   dataDir?: string
   /** 每条命中/未命中信号的原文 + 判定依据，恒非空（§6.2：判定可被证据推翻，非黑盒断言） */
   evidence: string[]
 }
 
 /** 形态匹配前的归一化：Windows 分隔符 → `/`，剥尾部斜杠 */
-function normalizeXyzPath(p: string): string {
+function normalizeTaijiPath(p: string): string {
   return p.replace(/\\/g, '/').replace(/\/+$/, '')
 }
 
-function matchesXyzAgentAgentDir(value: string): boolean {
-  return AGENT_DIR_SHAPE_ANY.test(normalizeXyzPath(value))
+function matchesTaijiAgentDir(value: string): boolean {
+  return AGENT_DIR_SHAPE_ANY.test(normalizeTaijiPath(value))
 }
 
 /** distribution 判定，判定行写入 evidence */
@@ -110,19 +110,19 @@ function detectDistribution(bundleUrl: string | undefined, evidence: string[]):
 }
 
 /**
- * 托管时的数据目录推导：XYZ_AGENT_DATA_DIR 优先（runtime 注入的权威值，与
+ * 托管时的数据目录推导：TAIJI_AGENT_DATA_DIR 优先（runtime 注入的权威值，与
  * getDataDir() 同源），缺失时按布局形态从 PI_CODING_AGENT_DIR 剥层。来源写入 evidence。
  */
 function deriveDataDir(env: Record<string, string | undefined>, evidence: string[]): string | undefined {
-  const dataDirEnv = env[XYZ_AGENT_DATA_DIR_ENV]
+  const dataDirEnv = env[TAIJI_AGENT_DATA_DIR_ENV]
   if (dataDirEnv) {
-    evidence.push(`数据目录：'${dataDirEnv}'（来源：${XYZ_AGENT_DATA_DIR_ENV}）`)
+    evidence.push(`数据目录：'${dataDirEnv}'（来源：${TAIJI_AGENT_DATA_DIR_ENV}）`)
     return dataDirEnv
   }
   const agentDirEnv = env[PI_CODING_AGENT_DIR_ENV]
   if (agentDirEnv) {
-    const normalized = normalizeXyzPath(agentDirEnv)
-    // 旧形态更长，先判：`.xyz-agent*/pi/agent` → 剥 pi/agent 两层
+    const normalized = normalizeTaijiPath(agentDirEnv)
+    // 旧形态更长，先判：`.taiji*/pi/agent` → 剥 pi/agent 两层
     if (AGENT_DIR_SHAPE_OLD.test(normalized)) {
       const dataDir = dirname(dirname(normalized))
       evidence.push(`数据目录：'${dataDir}'（来源：${PI_CODING_AGENT_DIR_ENV} 剥 pi/agent 两层，B 前旧布局）`)
@@ -134,7 +134,7 @@ function deriveDataDir(env: Record<string, string | undefined>, evidence: string
       return dataDir
     }
   }
-  evidence.push(`数据目录：无法推导（${XYZ_AGENT_DATA_DIR_ENV} 未设置且 ${PI_CODING_AGENT_DIR_ENV} 形态不可剥层）`)
+  evidence.push(`数据目录：无法推导（${TAIJI_AGENT_DATA_DIR_ENV} 未设置且 ${PI_CODING_AGENT_DIR_ENV} 形态不可剥层）`)
   return undefined
 }
 
@@ -146,16 +146,16 @@ function pushExtLogEvidence(
 ): void {
   evidence.push(
     extLogHit
-      ? `${XYZ_AGENT_EXT_LOG_ENV}='${extLog}' → 命中`
-      : `${XYZ_AGENT_EXT_LOG_ENV}=${extLog === undefined ? '<未设置>' : `'${extLog}'`} → 未命中（要求值为 '1'）`,
+      ? `${TAIJI_AGENT_EXT_LOG_ENV}='${extLog}' → 命中`
+      : `${TAIJI_AGENT_EXT_LOG_ENV}=${extLog === undefined ? '<未设置>' : `'${extLog}'`} → 未命中（要求值为 '1'）`,
   )
 }
 
-/** 信号 2 的形态标注（§6.2 双形态兼容：B 前旧布局 / B 后新布局 / 非 xyz-agent 形态）。 */
+/** 信号 2 的形态标注（§6.2 双形态兼容：B 前旧布局 / B 后新布局 / 非 taiji 形态）。 */
 function describeAgentDirShape(normalized: string): string {
   if (AGENT_DIR_SHAPE_OLD.test(normalized)) return 'B 前旧布局 pi/agent'
   if (AGENT_DIR_SHAPE_NEW.test(normalized)) return 'B 后新布局 agent'
-  return '非 xyz-agent 形态'
+  return '非 taiji 形态'
 }
 
 /** 信号 2 evidence 行（未设置 → 未命中；有值 → 形态匹配与否 + 形态标注）。 */
@@ -168,19 +168,19 @@ function pushAgentDirEvidence(
     evidence.push(`${PI_CODING_AGENT_DIR_ENV}=<未设置> → 未命中`)
     return
   }
-  const shape = describeAgentDirShape(normalizeXyzPath(agentDirEnv))
+  const shape = describeAgentDirShape(normalizeTaijiPath(agentDirEnv))
   evidence.push(
-    `${PI_CODING_AGENT_DIR_ENV}='${agentDirEnv}' → ${agentDirHit ? `形态匹配（${shape}）` : `形态不匹配（${shape}，要求 <*>/.xyz-agent*/agent）`}`,
+    `${PI_CODING_AGENT_DIR_ENV}='${agentDirEnv}' → ${agentDirHit ? `形态匹配（${shape}）` : `形态不匹配（${shape}，要求 <*>/.taiji*/agent）`}`,
   )
 }
 
 /** 判定行：托管（双信号合取成立）/ standalone-pi（孤置信号点名，提示透传/自设污染）。 */
 function judgedEvidenceLine(extLogHit: boolean, agentDirHit: boolean): string {
   if (extLogHit && agentDirHit) {
-    return `判定：xyz-agent 托管（${XYZ_AGENT_EXT_LOG_ENV}='1' 且 ${PI_CODING_AGENT_DIR_ENV} 形态匹配，双信号合取成立）`
+    return `判定：taiji 托管（${TAIJI_AGENT_EXT_LOG_ENV}='1' 且 ${PI_CODING_AGENT_DIR_ENV} 形态匹配，双信号合取成立）`
   }
   const orphaned: string[] = []
-  if (extLogHit) orphaned.push(XYZ_AGENT_EXT_LOG_ENV)
+  if (extLogHit) orphaned.push(TAIJI_AGENT_EXT_LOG_ENV)
   if (agentDirHit) orphaned.push(PI_CODING_AGENT_DIR_ENV)
   const orphanNote =
     orphaned.length > 0
@@ -192,8 +192,8 @@ function judgedEvidenceLine(extLogHit: boolean, agentDirHit: boolean): string {
 /**
  * 判定当前宿主环境（design §6.2）。
  *
- * 托管（xyz-agent）= 合取：`XYZ_AGENT_EXT_LOG === '1'` **且** `PI_CODING_AGENT_DIR`
- * 值匹配 xyz-agent 形态（`<*>/.xyz-agent*` 目录后接 `/agent`；B 前旧布局接
+ * 托管（taiji）= 合取：`TAIJI_AGENT_EXT_LOG === '1'` **且** `PI_CODING_AGENT_DIR`
+ * 值匹配 taiji 形态（`<*>/.taiji*` 目录后接 `/agent`；B 前旧布局接
  * `/pi/agent` 同样接受）。任一信号单独成立 → standalone-pi，evidence 点名孤置
  * 信号（透传污染提示）。
  * evidence 恒非空：每条命中/未命中信号的原文都在列，让 agent 能核对并推翻判定。
@@ -205,19 +205,19 @@ export function detectEnvironment(signals: EnvironmentSignals): DetectedEnvironm
   const evidence: string[] = []
   const { env } = signals
 
-  // 信号 1：XYZ_AGENT_EXT_LOG === '1'
-  const extLog = env[XYZ_AGENT_EXT_LOG_ENV]
+  // 信号 1：TAIJI_AGENT_EXT_LOG === '1'
+  const extLog = env[TAIJI_AGENT_EXT_LOG_ENV]
   const extLogHit = extLog === EXT_LOG_MANAGED_VALUE
   pushExtLogEvidence(evidence, extLog, extLogHit)
 
   // 信号 2：PI_CODING_AGENT_DIR 值形态
   const agentDirEnv = env[PI_CODING_AGENT_DIR_ENV]
-  const agentDirHit = agentDirEnv !== undefined && matchesXyzAgentAgentDir(agentDirEnv)
+  const agentDirHit = agentDirEnv !== undefined && matchesTaijiAgentDir(agentDirEnv)
   pushAgentDirEvidence(evidence, agentDirEnv, agentDirHit)
   evidence.push(`agentDir='${signals.agentDir}' → pi getAgentDir() 透传记录`)
 
   const managed = extLogHit && agentDirHit
-  const kind: EnvironmentKind = managed ? 'xyz-agent' : 'standalone-pi'
+  const kind: EnvironmentKind = managed ? 'taiji' : 'standalone-pi'
   evidence.push(judgedEvidenceLine(extLogHit, agentDirHit))
 
   const distribution = detectDistribution(signals.bundleUrl, evidence)

package/src/discovery/find.ts

@@ -327,7 +327,7 @@ function isFlatRoot(root: SessionRoot): boolean {
  * 加载标题元数据索引（u11）。仅 keyword 路径调用（惰性触发：uuid 精确/归一化两级零命中
  * 且 query 非纯 hex 才到达此处，§6.6 调用策略 ①）。
  *
- * 窄化目标（策略 ②，按序）：未剥层 liveSessionDir 本身（xyz-agent 下即平铺主根；纯 pi 下
+ * 窄化目标（策略 ②，按序）：未剥层 liveSessionDir 本身（taiji 下即平铺主根；纯 pi 下
  * 即当前 cwd 目录，小）+ 实扫结果无子目录的候选根。两条 guard：
  * - 仅对存在的根/目录调用（root.exists / stat liveSessionDir），且永传非空串——pi 的
  *   listAll 对空串 falsy 走默认全盘分支（数千项 / 秒级，hash-provider.ts 空参灾难先例）；

package/src/discovery/roots.ts

@@ -24,7 +24,7 @@ import { performance } from 'node:perf_hooks'
 
 /** 发现层信号包（index.ts 采集，全部可降级；本模块只消费不采集） */
 export interface SessionRootSignals {
-  /** pi agent 数据目录（两宿主均成立；B 后 xyz-agent = `<dataDir>/agent`） */
+  /** pi agent 数据目录（两宿主均成立；B 后 taiji = `<dataDir>/agent`） */
   agentDir: string
   /**
    * 宿主已解析的 live session 目录（`ctx.sessionManager.getSessionDir()`，§6.1 信号 1）。
@@ -66,7 +66,7 @@ const SUBAGENTS_DIRNAME = 'subagents'
 
 /**
  * `[live]` 规范化（§6.1/§7B 要点 3）：`getSessionDir()` 在纯 pi 返回按 cwd 编码的子目录
- *（`<agentDir>/sessions/--Users-x--`），在 xyz-agent 覆盖态返回根本身。判据：basename
+ *（`<agentDir>/sessions/--Users-x--`），在 taiji 覆盖态返回根本身。判据：basename
  * 匹配 encodeCwd 形态（`--` 开头 `--` 结尾，实证见 `~/.pi/agent/sessions/` 全部子目录
  * 与 real-data.ts）则取 dirname，否则取自身。
  */