@zhushanwen/pi-session-reader 0.5.1 → 0.6.1

package/src/__tests__/workflow.test.ts

@@ -30,7 +30,6 @@ const NEW_SNAPSHOT_FIXTURE = {
         opts: {
           prompt: 'Reply with exactly: PROBE-OK',
           model: 'deepseek-router/ds-pro',
-          thinkingLevel: 'high',
           description: 'step-0',
         },
         status: 'done',
@@ -64,7 +63,7 @@ const V2_SNAPSHOT_FIXTURE = {
     calls: [
       {
         id: 0,
-        opts: { prompt: 'task 0', model: 'default', thinkingLevel: 'high', description: 'v2-step-0' },
+        opts: { prompt: 'task 0', model: 'default', description: 'v2-step-0' },
         status: 'done',
         attempts: 1,
         sessionId: '019v2a',
@@ -126,12 +125,10 @@ describe('parseRunSnapshot', () => {
     expect(step.status).toBe('done')
     expect(step.description).toBe('step-0')
     expect(step.model).toBe('deepseek-router/ds-pro')
-    expect(step.thinkingLevel).toBe('high')
     expect(step.attempts).toBe(1)
     expect(step.durationMs).toBe(1234)
     expect(step.sessionId).toBe('019xxx')
     expect(step.sessionFile).toBe('/abs/session.jsonl')
-    expect(step.contentPreview).toBe('PROBE-OK')
   })
 
   it('TC-w5-parse-new-v2：v2 快照（pi-subagent-workflow 8.x 写入）解析非 null，calls sessionFile 读出', () => {
@@ -148,7 +145,6 @@ describe('parseRunSnapshot', () => {
     expect(overview!.steps[0].description).toBe('v2-step-0')
     expect(overview!.steps[1].sessionFile).toBe('/abs/v2-call1.jsonl')
     expect(overview!.steps[1].sessionId).toBe('019v2b')
-    expect(overview!.steps[1].contentPreview).toBe('OK')
   })
 
   it('TC-w5-parse-new-status-unknown：NEW call.status 非 done/running/pending（如 failed）→ step.status=pending', () => {
@@ -174,7 +170,6 @@ describe('parseRunSnapshot', () => {
     expect(step.index).toBe(3)
     expect(step.status).toBe('pending')
     expect(step.description).toBe('step-3')
-    expect(step.contentPreview).toBe('partial')
     expect(step.durationMs).toBe(9)
   })
 
@@ -193,7 +188,6 @@ describe('parseRunSnapshot', () => {
     expect(step.index).toBe(0) // callCache 顺序索引
     expect(step.status).toBe('pending') // content='' 空串不算完成标志 → pending
     expect(step.sessionFile).toBeUndefined() // OLD 未持久化
-    expect(step.contentPreview).toBe('') // value.content='' 仍提取
   })
 
   it('TC-w5-parse-corrupt-nonobject：非对象输入（null/undefined/string/number/array）返回 null', () => {

package/src/core/execution-tree.ts

@@ -59,6 +59,7 @@ export interface ExecutionTreeNode {
   agentName?: string
   slug?: string
   task?: string
+  /** 仅 details 可见，不进文本渲染（formatExecutionTreeText 渲染 status/slug/agentName/task，与 SubagentRef.model 同口径） */
   model?: string
   /** subagent 终态 completed/failed/running（manifest.status） */
   status?: string

package/src/core/family.ts

@@ -6,11 +6,14 @@ import type { Entry } from './parser.js'
  * M1 范围：纯逻辑层。buildFamilyIndex 接收已读入的 entry 数组（不做文件 IO），
  * 文件扫描/首行读取归 M2 discovery 层（roots.ts/find.ts/subagents.ts）。
  *
- * M1 占位约定（M2 discovery 层补全真实值，逻辑不变）：
- * - SessionRef.fileName：session header 推不出文件路径 → 占位空串
+ * 占位约定（原「M2 回填补全」双阶段约定已随 enrichRefs 删除退役，ext-simplify-04 U4/E2
+ * ——回填的 fileName/cwd 零文本读者；SessionRef 类型与 find 路径共享，find 侧两字段有
+ * 真实消费者，字段本身保留）：
+ * - SessionRef.fileName / subagent cwd：family 路径恒为占位空串（session header 推不出
+ *   路径 / identity entry 无 cwd），不再回填
  * - SessionRef.mtime/sizeBytes：从 fileStats 取（M1 key=sessionId），取不到为 0
  * - SubagentRef.sessionId：identity entry 不含 subagent session 的 id → 占位用 entry.id
- * - SubagentRef.cwd：identity entry（custom 类型）无 cwd → 占位空串
+ *   （M2 buildFamilyFromFs 以 header.id 替换为真实 id）
  * - fileStats 的 key：sessionId（M2 实现沿用此 key，cleanedUp 按 sessionId 命中），逻辑通用
  *
  * 隔代关联规则（design §3.3 D-7 Q1）见 resolveFamily 注释。
@@ -35,11 +38,11 @@ export interface SubagentRef extends SessionRef {
   task?: string
   /** agent 类型名（manifest.agentName，P-fallback 时 identity.data.agent；同语义异名） */
   agentName?: string
-  /** 模型 id（仅 manifest 有；P-fallback 时 undefined） */
+  /** 模型 id（仅 manifest 有；P-fallback 时 undefined）。仅 details 可见，不进文本渲染（D2②：展示面只取 status/agentName/task） */
   model?: string
   /** 终态 completed/failed/running（仅 manifest 有；P-fallback 时 undefined） */
   status?: string
-  /** subagent session.jsonl 绝对路径（manifest.sessionFile 或 alive 文件 meta.path） */
+  /** subagent session.jsonl 绝对路径（manifest.sessionFile 或 alive 文件 meta.path）。仅 details 可见，不进文本渲染 */
   sessionFile?: string
 }
 
@@ -118,16 +121,16 @@ function isSubagentIdentityData(v: unknown): v is SubagentIdentityData {
  * 文件名格式 `<timestamp>_<sessionId>.jsonl`，故路径字符串含父 sessionId。
  * 遍历已知 sessionId 做子串匹配反查。
  *
- * 兼容 parentSession 直接就是 sessionId 的简化场景（测试 fixture 常用）。
  * 假设 sessionId 互不为子串（pi 用 UUID，满足）；M2 可优化为 fileName→sessionId
  * 索引反查（O(1)），当前遍历 O(N)，家族索引文件数通常几十到几百，可接受。
+ *（原「parentSession 直接是 sessionId」快路径已删除，ext-simplify-04 A4——生产数据
+ * 恒为文件路径，该分支只服务测试 fixture 简化形态。）
  */
 function resolveParentSessionId(
   parentSession: string | undefined,
   byId: Map<string, SessionRef>,
 ): string | null {
   if (!parentSession) return null
-  if (byId.has(parentSession)) return parentSession // 直接是 sessionId（简化场景）
   for (const sid of byId.keys()) {
     if (parentSession.includes(sid)) return sid
   }
@@ -144,7 +147,7 @@ function buildById(
     const stat = fileStats.get(h.id)
     const ref: SessionRef = {
       sessionId: h.id,
-      fileName: '', // M1 占位：M2 discovery 补真实文件路径
+      fileName: '', // 占位空串：family 路径不回填（enrichRefs 已删除，ext-simplify-04 U4）
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
       cwd: h.cwd ?? '',
@@ -198,7 +201,7 @@ function buildSubagentsByRoot(
       fileName: '', // M1 占位
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
-      cwd: '', // identity entry 无 cwd；M2 从 subagent 文件 header 补
+      cwd: '', // identity entry 无 cwd；family 路径不回填（enrichRefs 已删除，ext-simplify-04 U4）
       // fileStats key=sessionId（buildFamilyFromFs 以 header.id 写入），cleanedUp 按 sessionId 命中
       cleanedUp: !fileStats.has(ident.id),
       // U4 富字段：从 identity data 读（manifest 主/P-fallback 由 buildFamilyFromFs 组装时决定）

package/src/core/render.ts

@@ -1,4 +1,5 @@
 import type { Entry } from './parser.js'
+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 字符」）。 */
@@ -17,7 +16,8 @@ const ASSISTANT_BRIEF_MAX_CHARS = 80
 const ENTRY_BRIEF_MAX_CHARS = 100
 /** turn 索引显示宽度（T013 三位补零）。 */
 const TURN_INDEX_WIDTH = 3
-/** outline 默认 token 预算（OutlineOptions.budget 缺省值）。 */
+/** outline 默认 token 预算（OutlineOptions.budget 缺省值）。生产路径（doOutline/doExport）
+ * 唯一取值：outline 是设计定档的 ~1500 token 全貌 TOC，无按调用方调节的需求。 */
 const OUTLINE_DEFAULT_BUDGET_TOKENS = 2000
 /** token 估算换算基数（chars/4，与 tokenEstimate 口径一致）。 */
 const CHARS_PER_TOKEN = 4
@@ -55,6 +55,11 @@ export interface TurnBrief {
 
 export interface OutlineResult {
   turns: TurnBrief[]
+  /**
+   * 渲染行（E7/D3 行渲染统一）：formatLine 产出、降级与总预算截断后的最终展示行——
+   * 预算度量与工具层展示共用同一份（度量 = 展示 by construction），展示侧不得重建行格式。
+   */
+  lines: string[]
   /** skippedLines：JSON 解析失败/缺结构字段的行数（parser 检测，工具层覆盖精确值；render 层无 ParseResult 恒 0） */
   stats: { totalTurns: number; totalEntries: number; totalBytes: number; parsedBytes: number; skippedLines: number }
   /** chars / 4 近似（与 design P-outline 口径一致） */
@@ -64,7 +69,9 @@ export interface OutlineResult {
 }
 
 export interface OutlineOptions {
-  /** 默认 2000（token） */
+  /** 测试注入缝（E10 定性）：非模型可见参数——session_read schema 无 budget 入参，模型
+   * 无法也无需调节；存在动机 = 测试注入小预算触发降级档用例（砍 assistantBrief / 骨架档）。
+   * 生产路径不传，走 OUTLINE_DEFAULT_BUDGET_TOKENS 默认。 */
   budget?: number
   allBranches?: boolean
   /** 默认 turn；entry = 每 entry 一行不聚合（D-1 兜底，坏 session 调试） */
@@ -101,6 +108,26 @@ function blockThinking(block: ContentBlock): string {
   return ''
 }
 
+/**
+ * E11 共享核：白名单提取 message.content 中 `type==='text'` 块的 text 字段（块 → string[]）。
+ * string content 直取为单元素数组；非 string 非数组返回空数组。join 语义（''/'\n'/' '）
+ * 与空态语义（空串 vs undefined）留在各调用点组合——S7 警告适用：join 差异是行为敏感点，
+ * 不可在共享核合并。消费方：result-action（'' join）/ extract（'\n' join）/ find（' ' join
+ * + 空返 undefined）。
+ */
+export function textBlockParts(content: unknown): string[] {
+  if (typeof content === 'string') return [content]
+  if (!Array.isArray(content)) return []
+  const parts: string[] = []
+  for (const b of content) {
+    if (b !== null && typeof b === 'object') {
+      const o = b as Record<string, unknown>
+      if (o.type === 'text' && typeof o.text === 'string') parts.push(o.text)
+    }
+  }
+  return parts
+}
+
 /** 拼接 text 块文本（排除 thinking / toolCall / tool_use / tool_result 块）。 */
 function extractText(content: unknown): string {
   if (isStringContent(content)) return content
@@ -276,7 +303,7 @@ function findBranchForkPoint(turn: Turn, tree: TreeView): string | undefined {
 }
 
 // ---------------------------------------------------------------------------
-// 行渲染（预算度量依据）
+// 行渲染（预算度量与展示同一份渲染行，E7/D3 行渲染统一）
 // ---------------------------------------------------------------------------
 
 function formatHHMM(timestamp?: string): string {
@@ -292,10 +319,11 @@ export function formatBytesMarker(bytes: number): string {
 }
 
 /**
- * 渲染单行为字符串（用于预算度量与降级判断）。
+ * 渲染单行为字符串（E7 行渲染统一：预算度量与展示同一份渲染行，OutlineResult.lines 的行工厂）。
  * v2 O1：L1 行含 assistantBrief（补 assistant 结论行让 outline 单独可决策，不再逼反复 expand）。
  * level: 0=全有（toolSummary + assistantBrief）/ 1=砍 assistantBrief / 2=再砍 toolSummary（骨架）。
  * userBrief + omittedBytes 骨架永保。assistantBrief 格式 `→ <结论>`，在 toolSummary 后、omitted 前。
+ * 旁支标记 `[旁支 N entries]`（branchSize = 该 forkPoint 下旁支子树 entry 数）。
  */
 function formatLine(b: TurnBrief, level: LineLevel, branchSize?: number): string {
   const parts: string[] = []
@@ -341,7 +369,8 @@ function applyBranchLabels(briefs: TurnBrief[], turns: Turn[], tree: TreeView):
 /**
  * 降级序逐行渲染（design §3.5 算法 1 step3）：level 0 全有；超预算降到 level 1
  * 砍 assistantBrief；仍超降到 level 2 砍 toolSummary（骨架）。
- * 直接改写 brief 的 assistantBrief/toolSummary 字段，返回行缓存。
+ * 直接改写 brief 的 assistantBrief/toolSummary 字段，返回行缓存（E7 后随结果
+ * 返回为 OutlineResult.lines，预算度量与展示同一份）。
  */
 function renderDegradingLines(
   briefs: TurnBrief[],
@@ -408,7 +437,7 @@ export function renderOutline(
   }
 
   if (turns.length === 0) {
-    return { turns: [], stats, tokenEstimate: 0 }
+    return { turns: [], lines: [], stats, tokenEstimate: 0 }
   }
 
   // granularity:entry —— 每 entry 一行，不聚合 turn（D-1 兜底）
@@ -428,11 +457,11 @@ export function renderOutline(
   // 3. 降级序渲染：level 0 全有 → level 1 砍 assistantBrief → level 2 骨架
   const lineCache = renderDegradingLines(briefs, tree, perTurnCharBudget)
 
-  // 4. 总预算截断（从尾部丢弃）
+  // 4. 总预算截断（从尾部丢弃，lines 与 briefs 同步截短）
   const { totalChars, truncated } = truncateToTotalBudget(briefs, lineCache, budget)
 
   const tokenEstimate = Math.ceil(totalChars / CHARS_PER_TOKEN)
-  return { turns: briefs, stats, tokenEstimate, truncated }
+  return { turns: briefs, lines: lineCache, stats, tokenEstimate, truncated }
 }
 
 /** granularity:entry 模式：每 entry 一行 TurnBrief，不聚合，仅总预算截断。 */
@@ -486,6 +515,7 @@ function renderEntryGranularity(
   }
   return {
     turns: briefs,
+    lines,
     stats,
     tokenEstimate: Math.ceil(totalChars / CHARS_PER_TOKEN),
     truncated,
@@ -568,7 +598,7 @@ function stripThinking(content: unknown): unknown {
 
 /**
  * L3 detail 默认摘要态的 toolResult entry（v2 O3：toolResult 不再整条消失，给中间态）。
- * includeToolResult:true 时 renderDetail 返回原 Entry（全文），否则返回此摘要。
+ * includeToolResult:true 时 renderDetail 直接 push 原 Entry（全文态真实路径），否则返回此摘要。
  */
 export interface ToolResultSummaryEntry {
   type: 'toolResultSummary'
@@ -580,8 +610,6 @@ export interface ToolResultSummaryEntry {
   headLines: string
   /** 结果文本总行数 */
   totalLines: number
-  /** 原 toolResult entry（includeToolResult:true 时 renderDetail 改用此返回全文） */
-  fullEntry: Entry
 }
 
 export function renderDetail(
@@ -620,7 +648,6 @@ export function renderDetail(
             summary: formatToolResultSummary(msg.toolName, tc, text),
             headLines,
             totalLines: lines.length,
-            fullEntry: e,
           })
         }
         continue

package/src/core/toolcall.ts

@@ -9,6 +9,7 @@
  *   parser.ts 已 additive 透出这两个字段，O2/O3 据此精确关联取参数。
  */
 import type { Entry } from './parser.js'
+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/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/core/workflow.ts

@@ -11,25 +11,20 @@
 // 升版连带编译期影响本扩展；且上游类型只描述 NEW，OLD 仍需自处理（TC-wf-snapshot-version-union）。
 // session-reader 作为纯读取者，按字段存在性 + v 标记分支做「结构化快照」式解析，与上游解耦。
 
-// ---- 类型守卫 helpers ----
+import { isRecord } from '@zhushanwen/pi-ext-guards'
 
-/** unknown → Record<string, unknown> 守卫（非对象或 null → false）。 */
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null
-}
+// ---- 类型守卫 helpers ----
 
 /** unknown → string 收窄（非 string → undefined）。快照可选字符串字段的统一入口。 */
 function strOr(v: unknown): string | undefined {
   return typeof v === 'string' ? v : undefined
 }
 
-/** 字符串截断（超 max 加省略号）。概览预览用，全文走 detail。 */
+/** 字符串截断（超 max 加省略号）。step 行渲染用。 */
 function truncate(s: string, max: number): string {
   return s.length <= max ? s : s.slice(0, max) + '…'
 }
 
-/** contentPreview 截断长度（概览预览，全文走 detail）。 */
-const CONTENT_PREVIEW_MAX = 120
 /** step 行 call sessionId 显示截断长度（uuid 前缀段，LLM 可读）。 */
 const SESSION_ID_PREVIEW_MAX = 12
 
@@ -61,8 +56,6 @@ export interface WorkflowStep {
   description?: string
   /** NEW call.opts.model */
   model?: string
-  /** NEW call.opts.thinkingLevel */
-  thinkingLevel?: string
   /** NEW call.attempts / OLD 无 → undefined */
   attempts?: number
   /** NEW call.result.durationMs / OLD value.result.durationMs */
@@ -71,8 +64,6 @@ export interface WorkflowStep {
   sessionId?: string
   /** call.sessionFile 或 result.sessionFile（LLM 跳 outline/detail 的绝对路径入口，OLD 多数为 undefined） */
   sessionFile?: string
-  /** result.content 截断前 120 字（概览预览，全文走 detail） */
-  contentPreview?: string
 }
 
 /** workflow run 概览（parseRunSnapshot 输出 / renderWorkflowOverview 输入）。 */
@@ -83,7 +74,7 @@ export interface WorkflowOverview {
   stateFile: string
   /** NEW state.status / OLD 顶层 status */
   status: string
-  /** 格式标记（渲染/调试用）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
+  /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
   version: 'wf-run-v1' | 'wf-run-v2' | 'legacy'
   /** NEW spec.scriptName / spec.name / OLD name */
   script?: string
@@ -138,19 +129,16 @@ function mapCallToStep(call: unknown, fallbackIndex: number): WorkflowStep {
   const index = typeof call.id === 'number' ? call.id : fallbackIndex
   const status = normalizeCallStatus(strOr(call.status) ?? '')
   const refs = pickSessionRefs(call, result)
-  const content = strOr(result.content)
 
   return {
     index,
     status,
     description: strOr(opts.description),
     model: strOr(opts.model),
-    thinkingLevel: strOr(opts.thinkingLevel),
     attempts: typeof call.attempts === 'number' ? call.attempts : undefined,
     durationMs: typeof result.durationMs === 'number' ? result.durationMs : undefined,
     sessionId: refs.sessionId,
     sessionFile: refs.sessionFile,
-    contentPreview: content !== undefined ? truncate(content, CONTENT_PREVIEW_MAX) : undefined,
   }
 }
 
@@ -162,11 +150,11 @@ function mapCacheEntryToStep(entry: unknown, index: number): WorkflowStep {
 
   // sessionFile/sessionId: value.sessionFile 或 value.result.sessionFile（OLD 多数缺失，探针 112 文件 0）
   const refs = pickSessionRefs(value, result)
-  // content：真实 OLD 数据 value.content（wf-skip-ok）与测试 fixture value.result.content 并存
+  // content：真实 OLD 数据 value.content（wf-skip-ok）与测试 fixture value.result.content 并存，
+  // 仅用于 status 推测（A4 死字段删除：contentPreview 已删，不再随 step 输出）
   const content = strOr(result.content) ?? strOr(value.content)
   // OLD 无 status 字段：有 sessionFile 或非空 content → done，否则 pending
-  //（空 content 如 wf-skip-ok 的 '' 不算完成标志，对齐 TC-w5-parse-old expected status='pending'；
-  // content 仍提取为 contentPreview=''）
+  //（空 content 如 wf-skip-ok 的 '' 不算完成标志，对齐 TC-w5-parse-old expected status='pending'）
   const hasContent = content !== undefined && content.length > 0
   const status: WorkflowStep['status'] =
     refs.sessionFile !== undefined || hasContent ? 'done' : 'pending'
@@ -177,7 +165,6 @@ function mapCacheEntryToStep(entry: unknown, index: number): WorkflowStep {
     durationMs: typeof result.durationMs === 'number' ? result.durationMs : undefined,
     sessionId: refs.sessionId,
     sessionFile: refs.sessionFile,
-    contentPreview: content !== undefined ? truncate(content, CONTENT_PREVIEW_MAX) : 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)