@zhushanwen/pi-system-prompt-trace 0.1.5 → 0.1.7

package/README.md

@@ -31,19 +31,24 @@ appendEntry("xyz:system-prompt", {
 |---|---|---|
 | startup / new | initial | 定案 |
 | resume | resume | 定案 |
-| fork / reload | resume | 暂定，待 P2 探针实测定（A13） |
+| fork / reload | resume | 定案（M0 探针 P2 实测：fork 档读源文件最后留痕，落盘 reason 维持 resume；执行记录见设计 §6.5） |
 
-存在任一 hash 基线（见下）时，首个 turn 写 `resume`（无论 session_start reason）。
+存在 hash 基线（见下）且 prompt 未变时，首个 turn 不写（去重）；需写时（hash 已变）恒写 `resume`（无论 session_start reason）。
 
-## 跨重启 hash 基线四路径（优先级从高到低，权威实现见 `src/trace.ts` onSessionStart）
+## 跨重启 hash 基线三档（优先级从高到低，权威实现见 `src/trace.ts` onSessionStart）
 
 1. **进程内 resume（stash）**：`session_before_switch.targetSessionFile` 直读目标 session 文件，取最后一条留痕
    entry 的 hash/version/fullText。switch 会 teardown 并重建 extension runtime，该基线经模块级 stash 跨 runtime 传递。
-2. **fork**：`session_start.previousSessionFile` 直读源 session 文件（暂定语义，待 P2 探针实测定）。
-3. **自持久化小文件**：`<agentDir>/system-prompt-trace-baseline.json`（sessionId → hash/version），原子写入，
-   保留最近 64 个 session。app 重启直 spawn resume / reload 等没有 switch 事件的链路由此恢复基线。
-4. **兜底必写**：三路都 miss（无任何基线）时，首个 turn 无论 session_start reason 必写一条——
-   startup/new → `initial`，resume/fork/reload → `resume`（宁可多写不可漏记）。
+2. **fork**：`session_start.previousSessionFile` 直读源 session 文件，取源文件最后一条留痕（D2 v5 定案——
+   常态 /fork 时点 fork 新文件未落盘，不可直读新文件；源文件缺失/未落盘/读取失败 → 视为无基线）。
+3. **直读当前 session 文件**：`ctx.sessionManager.getSessionFile()` 直读 JSONL 最后一条留痕，覆盖 reload /
+   重启直 spawn resume / new 兜底等没有 switch 事件的链路（文件不存在或无留痕 → 视为无基线）。
+
+原第三档「自持久化小文件 system-prompt-trace-baseline.json」已随 ext-simplify-02 删除——终态唯一持久化源 =
+session JSONL 自身；存量文件成为无读写方孤儿，可安全手动删除（含 `*.tmp_*` 残留）。
+
+三档都 miss（无任何基线）时兜底必写：首个 turn 无论 session_start reason 必写一条——
+startup/new → `initial`，resume/fork/reload → `resume`（宁可多写不可漏记）。
 
 ## 注册状态
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt-trace",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "System prompt trace extension: appends xyz:system-prompt entries to the session JSONL whenever the effective system prompt is established or changes",
   "type": "module",
   "main": "index.ts",
@@ -33,7 +33,8 @@
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.1"
+    "@zhushanwen/pi-ext-guards": "0.4.0",
+    "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/__tests__/baseline.a12.test.ts

@@ -1,33 +1,35 @@
 /**
  * A12 hash 基线跨重启恢复（spec：.cw-specs/trace-ext.json；设计 D2 复审 N2 / plan §2.1）。
  *
- * 四路径（优先级从高到低，口径同 trace.ts onSessionStart）：
+ * 三档（优先级从高到低，口径同 trace.ts onSessionStart，设计 D1/D2 v5）：
  * 1. 进程内 resume：session_before_switch.targetSessionFile 直读目标文件取上一版 hash
  *    （switch 重建 extension runtime，基线经模块级 stash 传递——用「新闭包 + 共享 stash」模拟）
- * 2. fork：previousSessionFile 直读源 session 文件（暂定语义，本文件未覆盖）
- * 3. app 重启直 spawn resume：agentDir 自持久化小文件（此链路无 switch 事件、reason=startup）
- * 4. 兜底：三路都读不到 → 任意 reason 必写一条（startup/new→initial，resume/fork/reload→resume）
+ * 2. fork：previousSessionFile 直读源 session 文件最后留痕（设计 D2 v5 定案——常态 /fork
+ *    时点 fork 新文件未落盘，直读不可靠）
+ * 3. 直读档：ctx.getSessionFile() 直读当前 session 文件（app 重启直 spawn resume / reload——
+ *    此链路无 switch 事件、reason=startup；文件未落盘 / 无留痕 → null）
+ * 4. 兜底：三档都读不到 → 任意 reason 必写一条（startup/new→initial，resume/fork/reload→resume）
  *
  * 用真实临时目录 + 真实 fs 函数（非 mock 投影）；appendEntry 同步模拟 pi appendCustomEntry
  * 的落盘形状（session-manager.ts）。
  */
 import { appendFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import {
-	BASELINE_FILENAME,
-	readLastPromptFromSessionFile,
-	readPersistedBaseline,
-	writePersistedBaseline,
-} from "../baseline.js";
-import { computePromptHash, createSystemPromptTrace } from "../trace.js";
+import { readLastPromptFromSessionFile } from "../baseline.js";
+import { createSystemPromptTrace } from "../trace.js";
 import type { SystemPromptTrace, TraceContext, TraceEnv } from "../trace.js";
 import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
 import type { SystemPromptTraceEntryData, SwitchStash } from "../types.js";
 
+// trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
+const computePromptHash = (text: string): string =>
+	createHash("sha256").update(text, "utf-8").digest("hex");
+
 const P1 = "base prompt\nline-1";
 const P2 = "base prompt\nline-1\nline-2-added";
 
@@ -36,14 +38,13 @@ interface FsHarness {
 	ctx: TraceContext;
 	stash: SwitchStash;
 	sessionFile: string;
-	baselineFile: string;
 	entries: SystemPromptTraceEntryData[];
 	setPrompt(text: string): void;
-	/** 真实链路中 new/fork 的新 session 有全新 id（fake ctx 不能固定 id，否则旧基线误命中） */
-	setSessionId(id: string): void;
+	/** 真实链路中 new/fork 的新 session 有全新 id 与全新（未落盘的）文件；切换 ctx 指向并返回新文件路径 */
+	openNewSession(id: string): string;
 	/** 模拟 extension runtime 重建（switchSession teardown + createRuntime 重跑 factory：新闭包，共享 stash 与文件） */
 	newLogic(): SystemPromptTrace;
-	/** 读 sessionFile 的非空行（模拟 pi 落盘结果核对） */
+	/** 读当前 session 文件的非空行（模拟 pi 落盘结果核对） */
 	sessionLines(): string[];
 }
 
@@ -54,45 +55,49 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-	rmSync(rootDir, { recursive: true, force: true });
+	rmSync(rootDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
-function makeHarness(initialPrompt: string): FsHarness {
+function makeHarness(initialPrompt: string, opts?: { noSessionFile?: boolean }): FsHarness {
 	const dir = join(rootDir, `sess-${Math.random().toString(36).slice(2)}`);
 	mkdirSync(dir, { recursive: true });
 	const sessionFile = join(dir, "session.jsonl");
-	const baselineFile = join(dir, BASELINE_FILENAME);
 	const entries: SystemPromptTraceEntryData[] = [];
 	let prompt = initialPrompt;
 	let sessionId = "sess-a12";
+	// 真实链路中 getSessionFile() 指向当前 session 的文件（首条 assistant 前 pi 未 flush，
+	// 文件可能不存在——appendEntry 的 append 模式会自建，与 pi 的延迟落盘行为等价可接受）
+	let currentSessionFile: string | undefined = opts?.noSessionFile === true ? undefined : sessionFile;
 	const stash: SwitchStash = { pending: null };
 
 	const env: TraceEnv = {
-		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath, "target-file"),
-		readPersistedBaseline: (sessionId) => readPersistedBaseline(baselineFile, sessionId),
-		writePersistedBaseline: (sessionId, hash, version) =>
-			writePersistedBaseline(baselineFile, sessionId, hash, version),
+		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath),
 	};
 
 	const ctx: TraceContext = {
 		getSystemPrompt: () => prompt,
 		getSessionId: () => sessionId,
+		getSessionFile: () => currentSessionFile,
 		appendEntry: (customType, data) => {
 			if (!isSystemPromptTraceEntryData(data)) {
 				throw new Error(`entry data shape invalid: ${JSON.stringify(data)}`);
 			}
-			// 模拟 pi appendCustomEntry 落盘形状（session-manager.ts）
-			appendFileSync(
-				sessionFile,
-				JSON.stringify({
-					type: "custom",
-					customType,
-					data,
-					id: `e${entries.length + 1}`,
-					parentId: null,
-					timestamp: new Date().toISOString(),
-				}) + "\n",
-			);
+			// 纯内存 session（getSessionFile() undefined，pi 首条 assistant 前 _persist 未 flush）：
+			// entry 只进内存，不落文件——与 pi appendCustomEntry 内存先行、延迟落盘的行为等价
+			if (currentSessionFile !== undefined) {
+				// 模拟 pi appendCustomEntry 落盘形状（session-manager.ts）
+				appendFileSync(
+					currentSessionFile,
+					JSON.stringify({
+						type: "custom",
+						customType,
+						data,
+						id: `e${entries.length + 1}`,
+						parentId: null,
+						timestamp: new Date().toISOString(),
+					}) + "\n",
+				);
+			}
 			entries.push(data);
 		},
 	};
@@ -104,18 +109,21 @@ function makeHarness(initialPrompt: string): FsHarness {
 		ctx,
 		stash,
 		sessionFile,
-		baselineFile,
 		entries,
 		setPrompt: (text) => {
 			prompt = text;
 		},
-		setSessionId: (id) => {
+		openNewSession: (id) => {
+			const file = join(dir, `${id}.jsonl`);
 			sessionId = id;
+			currentSessionFile = file;
+			return file;
 		},
 		newLogic: makeLogic,
 		sessionLines: () => {
+			if (currentSessionFile === undefined) return [];
 			try {
-				return readFileSync(sessionFile, "utf-8").split("\n").filter((l) => l.trim() !== "");
+				return readFileSync(currentSessionFile, "utf-8").split("\n").filter((l) => l.trim() !== "");
 			} catch {
 				return [];
 			}
@@ -158,24 +166,22 @@ describe("A12 hash 基线跨重启恢复", () => {
 		expect(h.entries[1]?.parentVersionDiffSummary).toContain("+1 -0 lines");
 	});
 
-	it("路径 3（app 重启直 spawn）：自持久化小文件命中且 hash 未变 → 不写（reason=startup、无 switch 事件）", () => {
+	it("直读档（app 重启直 spawn resume）：getSessionFile() 目标文件命中且 hash 未变 → 不写（reason=startup、无 switch 事件）", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);
-		h.logic.onTurnStart(h.ctx); // v1 initial + 基线小文件已写
-		expect(readPersistedBaseline(h.baselineFile, "sess-a12")).toMatchObject({
-			hash: computePromptHash(P1),
-			version: 1,
-		});
+		h.logic.onTurnStart(h.ctx); // v1 initial（落 sessionFile）
+		expect(h.entries).toHaveLength(1);
 
-		// app 重启：全新闭包 + 空 stash（无 before_switch 可用）
+		// app 重启直启：全新闭包 + 空 stash（无 before_switch 可用）；getSessionFile() 指向同一文件
+		//（pi 直启 resume 时 sessionManager open 的目标文件），直读最后留痕命中
 		const logic2 = h.newLogic();
-		expect(logic2).toBeDefined();
 		logic2.onSessionStart("startup", undefined, h.ctx);
 		logic2.onTurnStart(h.ctx);
 		expect(h.entries).toHaveLength(1);
+		expect(h.sessionLines()).toHaveLength(1);
 	});
 
-	it("路径 3（app 重启直 spawn）：基线命中但 prompt 已变 → 写 resume v2（无 parent 全文，diff 摘要缺省）", () => {
+	it("直读档（app 重启直 spawn resume）：基线命中但 prompt 已变 → 写 resume v2，diff 摘要来自直读留痕 fullText（persisted 时代的数据层缺口已修复）", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);
 		h.logic.onTurnStart(h.ctx); // v1
@@ -186,22 +192,23 @@ describe("A12 hash 基线跨重启恢复", () => {
 		logic2.onTurnStart(h.ctx);
 		expect(h.entries).toHaveLength(2);
 		// 基线存在 → 该 session 已有历史版本 → resume（而非 initial 重新计数）
-		expect(h.entries[1]).toMatchObject({ version: 2, reason: "resume" });
-		expect(h.entries[1]?.parentVersionDiffSummary).toBeUndefined();
+		expect(h.entries[1]).toMatchObject({ version: 2, reason: "resume", hash: computePromptHash(P2) });
+		// 直读档基线含 fullText → parentVersionDiffSummary 不再缺省（F1 修复）
+		expect(h.entries[1]?.parentVersionDiffSummary).toContain("+1 -0 lines");
 	});
 
-	it("路径 4（兜底）：三路基线都读不到且 reason=resume → 必写一条", () => {
-		const h = makeHarness(P1);
-		h.logic.onSessionStart("resume", undefined, h.ctx); // 无 stash、无小文件
+	it("路径 4（兜底）：三档基线都读不到（getSessionFile 未落盘返回 undefined）且 reason=resume → 必写一条", () => {
+		const h = makeHarness(P1, { noSessionFile: true });
+		h.logic.onSessionStart("resume", undefined, h.ctx); // 无 stash、getSessionFile() undefined
 		h.logic.onTurnStart(h.ctx);
 		expect(h.entries).toHaveLength(1);
 		expect(h.entries[0]).toMatchObject({ version: 1, reason: "resume" });
 	});
 
-	it("基线小文件损坏 → 视为无基线，resume 必写一条", () => {
+	it("直读档：session 文件损坏 → 视为无基线，resume 必写一条", () => {
 		const h = makeHarness(P1);
-		writeFileSync(h.baselineFile, "{ not valid json");
-		h.logic.onSessionStart("resume", undefined, h.ctx);
+		writeFileSync(h.sessionFile, "{ not valid json\n");
+		h.logic.onSessionStart("resume", undefined, h.ctx); // 无 stash；直读损坏行全部跳过 → null
 		h.logic.onTurnStart(h.ctx);
 		expect(h.entries).toHaveLength(1);
 		expect(h.entries[0]).toMatchObject({ version: 1, reason: "resume" });
@@ -227,28 +234,64 @@ describe("A12 hash 基线跨重启恢复", () => {
 		h.logic.onSessionBeforeSwitch("resume", h.sessionFile); // switch 随后被取消，无 session_start 消费
 		expect(h.stash.pending).not.toBeNull();
 
-		// 之后用户开了全新 session：新 sessionId + reason=new → stash 被消费但不采用，从 v1 重新计数
+		// 之后用户开了全新 session：新 sessionId + 全新未落盘文件 → stash 被消费但不采用，
+		// 直读档 miss（新文件不存在），从 v1 重新计数
 		const logic2 = h.newLogic();
-		h.setSessionId("sess-a12-new");
+		h.openNewSession("sess-a12-new");
 		logic2.onSessionStart("new", undefined, h.ctx);
 		logic2.onTurnStart(h.ctx);
 		expect(h.entries).toHaveLength(2);
 		expect(h.entries[1]).toMatchObject({ version: 1, reason: "initial" });
 	});
 
-	it("fork（暂定语义，待 P2 实测定）：previousSessionFile 直读作基线，hash 未变不写", () => {
+	it("fork（设计 D2 v5 定案）：previousSessionFile 直读源文件最后留痕作基线，hash 未变不写", () => {
 		const h = makeHarness(P1);
 		h.logic.onSessionStart("startup", undefined, h.ctx);
 		h.logic.onTurnStart(h.ctx); // v1（落进 h.sessionFile）
 
-		// pi 原生 fork 不经 session_before_switch：基线来自 session_start.previousSessionFile（新 sessionId 无持久化基线）
+		// pi 原生 fork 不经 session_before_switch：基线来自 session_start.previousSessionFile；
+		// fork 新 session 是全新 id 与未落盘的新文件（常态 /fork 时点新文件不 flush，M0 探针实证）
+		h.openNewSession("sess-a12-fork");
 		const logic2 = h.newLogic();
-		h.setSessionId("sess-a12-fork");
 		logic2.onSessionStart("fork", h.sessionFile, h.ctx);
 		logic2.onTurnStart(h.ctx);
 		expect(h.entries).toHaveLength(1);
 	});
 
+	it("fork（V6 第二步）：fork 基线命中确立 current 后配置回变 → 写 change，version 自源留痕续接 +1，diff 相对源留痕 fullText", () => {
+		// 源 session 预置两条留痕：v1（配置 A prompt）→ v2（配置 B prompt）
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx); // v1 initial（A）
+		h.setPrompt(P2);
+		h.logic.onTurnStart(h.ctx); // v2 change（B）
+		expect(h.entries).toHaveLength(2);
+
+		// fork 新 session：新闭包 + 空 stash → fork 档直读源文件最后留痕 v2 作基线
+		h.openNewSession("sess-a12-fork-change");
+		const logic2 = h.newLogic();
+		logic2.onSessionStart("fork", h.sessionFile, h.ctx);
+		logic2.onTurnStart(h.ctx); // prompt 仍 B：hash 命中源留痕 → 不写，仅确立 current（沿用上一用例语义）
+		expect(h.entries).toHaveLength(2);
+		expect(h.sessionLines()).toHaveLength(0); // fork 新文件零留痕
+
+		// 配置回变（B → A）：current 已由 fork 基线命中确立 → 后续 turn 变化走 change 分支
+		//（而非 resume——resume 仅用于 session_start 后基线重确立的首 turn）
+		h.setPrompt(P1);
+		logic2.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(3);
+		expect(h.entries[2]).toMatchObject({
+			version: 3, // 源最后留痕 v2 + 1
+			reason: "change", // 非 resume / 非 initial
+			hash: computePromptHash(P1),
+			fullText: P1,
+		});
+		// diff 相对源留痕 v2 的 fullText（B）：P2 → P1 为删 1 行（"+N -M lines" 头形态）
+		expect(h.entries[2]?.parentVersionDiffSummary).toContain("+0 -1 lines");
+		// fork 新文件恰好落盘这一条留痕
+		expect(h.sessionLines()).toHaveLength(1);
+	});
+
 	it("readLastPromptFromSessionFile：损坏行跳过、取最后一条有效留痕；文件缺失 → null", () => {
 		const scanDir = mkdtempSync(join(rootDir, "scan-"));
 		const file = join(scanDir, "s.jsonl");
@@ -263,19 +306,11 @@ describe("A12 hash 基线跨重启恢复", () => {
 			data: { version: 2, hash: "hash-v2", reason: "change", fullText: "new text", charCount: 8 },
 		};
 		writeFileSync(file, [JSON.stringify(entryV1), "{ broken json", JSON.stringify(entryV2), ""].join("\n"));
-		expect(readLastPromptFromSessionFile(file, "target-file")).toMatchObject({
+		expect(readLastPromptFromSessionFile(file)).toMatchObject({
 			hash: "hash-v2",
 			version: 2,
 			fullText: "new text",
-			source: "target-file",
 		});
-		expect(readLastPromptFromSessionFile(join(scanDir, "missing.jsonl"), "target-file")).toBeNull();
-	});
-
-	it("自持久化小文件读写回路：write 后 read 命中同 session；其他 session → null", () => {
-		const file = join(rootDir, "baseline.json");
-		writePersistedBaseline(file, "sid-1", "hash-x", 3);
-		expect(readPersistedBaseline(file, "sid-1")).toEqual({ hash: "hash-x", version: 3, source: "persisted" });
-		expect(readPersistedBaseline(file, "sid-other")).toBeNull();
+		expect(readLastPromptFromSessionFile(join(scanDir, "missing.jsonl"))).toBeNull();
 	});
 });

package/src/__tests__/index-wiring.test.ts

@@ -2,15 +2,16 @@
  * index.ts wiring SDK 契约测试（Gate-1.6 覆盖缺口：wiring 层 0%；round1 review「wiring 层无 SDK 契约测试」）。
  *
  * mock 边界（对齐 subagent-workflow index 测试先例）：
- * - @earendil-works/pi-coding-agent 只 mock getAgentDir（指向临时目录）——baseline.ts 走真实 fs，
- *   从而验证 wiring 把基线小文件真的落在 getAgentDir() 下
+ * - baseline.ts 走真实 fs（previousSessionFile / getSessionFile 直读路径用真实临时文件）
  * - pi 用 Proxy 假体：捕获 on 注册的 handler 与 appendEntry 落点；handler 以 SDK 双参契约
- *   (event, ctx) 驱动；ctx 只需 index.ts 实际消费的字段（getSystemPrompt + sessionManager.getSessionId）
+ *   (event, ctx) 驱动；ctx 只需 index.ts 实际消费的字段（getSystemPrompt + sessionManager 的
+ *   getSessionId / getSessionFile）
  * - @zhushanwen/pi-extension-logger mock 三导出（getLogger / createLogger / setPiHandle），
  *   setPiHandle 捕获 factory 注入（D3 接线契约），logger 方法收集供吞错断言
  * - switchStash 是模块级单例：beforeEach vi.resetModules 隔离用例；同 it 内二次 dynamic import
  *   模拟「switch 重建 extension runtime + 同进程模块缓存延续」的真实链路
  */
+import { createHash } from "node:crypto";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -19,11 +20,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { BASELINE_FILENAME, readPersistedBaseline } from "../baseline.js";
-import { computePromptHash } from "../trace.js";
 import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
 import type { SystemPromptTraceEntryData } from "../types.js";
 
+// trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
+const computePromptHash = (text: string): string =>
+	createHash("sha256").update(text, "utf-8").digest("hex");
+
 const P1 = "wiring prompt\nline-1";
 const P2 = "wiring prompt\nline-1\nline-2-added";
 
@@ -37,12 +40,6 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	setPiHandle: setPiHandleMock,
 }))
 
-const agentDirRef = vi.hoisted(() => ({ current: "" }));
-
-vi.mock("@earendil-works/pi-coding-agent", () => ({
-	getAgentDir: () => agentDirRef.current,
-}));
-
 type RecordedHandler = (event: unknown, ctx: unknown) => Promise<void> | void;
 
 interface RecordedEntry {
@@ -78,12 +75,20 @@ function createWiringHarness(): WiringHarness {
 	return { pi, handlers, entries };
 }
 
-/** ctx 最小形状（index.ts 实际消费：getSystemPrompt + sessionManager.getSessionId；cwd 是 SDK 契约字段）。 */
-function createCtx(getPrompt: () => string, sessionId: string): Record<string, unknown> {
+/** ctx 最小形状（index.ts 实际消费：getSystemPrompt + sessionManager 的 getSessionId/getSessionFile；cwd 是 SDK 契约字段）。
+ * getSessionFile 缺省 undefined（新 session 未落盘）；需要指向真实文件时传 getSessionFileOverride。 */
+function createCtx(
+	getPrompt: () => string,
+	sessionId: string,
+	getSessionFileOverride?: () => string | undefined,
+): Record<string, unknown> {
 	return {
 		cwd: "/home/user/project",
 		getSystemPrompt: getPrompt,
-		sessionManager: { getSessionId: () => sessionId },
+		sessionManager: {
+			getSessionId: () => sessionId,
+			getSessionFile: getSessionFileOverride ?? ((): string | undefined => undefined),
+		},
 	};
 }
 
@@ -121,12 +126,11 @@ let rootDir = "";
 
 beforeEach(() => {
 	rootDir = mkdtempSync(join(tmpdir(), "spt-wiring-"));
-	agentDirRef.current = rootDir;
 	vi.resetModules();
 });
 
 afterEach(() => {
-	rmSync(rootDir, { recursive: true, force: true });
+	rmSync(rootDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 });
 
 describe("index.ts wiring SDK 契约", () => {
@@ -153,7 +157,7 @@ describe("index.ts wiring SDK 契约", () => {
 		expect(injected).toBe(h.pi);
 	});
 
-	it("startup（无 previousSessionFile）→ 首 turn 写 initial v1（appendEntry 形状 + 基线落 getAgentDir）；prompt 变化写 change v2 带 diff 摘要", async () => {
+	it("startup（无 previousSessionFile、session 未落盘）→ 首 turn 写 initial v1（appendEntry 形状）；prompt 变化写 change v2 带 diff 摘要", async () => {
 		const ext = await loadExtension();
 		const h = createWiringHarness();
 		ext(h.pi);
@@ -171,10 +175,7 @@ describe("index.ts wiring SDK 契约", () => {
 			charCount: P1.length,
 			hash: computePromptHash(P1),
 		});
-		expect(readPersistedBaseline(join(agentDirRef.current, BASELINE_FILENAME), "sess-w1")).toMatchObject({
-			hash: computePromptHash(P1),
-			version: 1,
-		});
+		// 自持久化基线小文件已随 persisted 子系统删除（设计目标 2）：无 agentDir 落盘面，仅 session JSONL
 
 		prompt = P2;
 		await emit(h, "turn_start", { type: "turn_start", turnIndex: 1, timestamp: 0 }, ctx);
@@ -184,7 +185,7 @@ describe("index.ts wiring SDK 契约", () => {
 		expect(change.parentVersionDiffSummary).toContain("+1 -0 lines");
 	});
 
-	it("fork（previousSessionFile 为 string）→ 直读该文件作基线；hash 未变不写、仅刷新自持久化基线版本", async () => {
+	it("fork（previousSessionFile 为 string）→ 直读该文件最后留痕作基线（D2 v5 定案）；hash 未变不写", async () => {
 		const prevFile = join(rootDir, "prev-session.jsonl");
 		writeSessionEntry(prevFile, {
 			version: 3,
@@ -207,9 +208,52 @@ describe("index.ts wiring SDK 契约", () => {
 		await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
 
 		expect(h.entries).toHaveLength(0);
-		expect(
-			readPersistedBaseline(join(agentDirRef.current, BASELINE_FILENAME), "sess-w-fork"),
-		).toMatchObject({ version: 3 });
+	});
+
+	it("fork 的 previousSessionFile 三态防御：字段缺失 / 源文件未落盘 / 读取失败 → 基线 null → resume v1 兜底", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		ext(h.pi);
+		// 态 1 判据强化（R5-F2）：getSessionFile() 可读且带留痕（version 5，hash = P1）——
+		// 若 fork 缺失 previousSessionFile 时 fall-through 直读档，基线命中 P1 → 首 turn
+		// 不写 entry（下方三 entry 断言即失败）；D2 语义（fork 只认 previousSessionFile，
+		// 缺失即 null，不落直读档）下必写 resume v1。
+		const readableFile = join(rootDir, "readable-session.jsonl");
+		writeSessionEntry(readableFile, {
+			version: 5,
+			hash: computePromptHash(P1),
+			reason: "change",
+			fullText: P1,
+			charCount: P1.length,
+		});
+		const ctxFallbackReadable = createCtx(() => P1, "sess-w-fork-def", () => readableFile);
+		const ctx = createCtx(() => P1, "sess-w-fork-def");
+
+		// 态 1：字段缺失（in-memory fork 且源 sessionFile 为 undefined）——即便
+		// getSessionFile() 可读带留痕，fork 档也不落直读档
+		await emit(h, "session_start", { type: "session_start", reason: "fork" }, ctxFallbackReadable);
+		await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctxFallbackReadable);
+		// 态 2：源文件未落盘（源会话尚无 assistant 即 fork，首条 assistant 前 pi _persist 不落盘）
+		await emit(
+			h,
+			"session_start",
+			{ type: "session_start", reason: "fork", previousSessionFile: join(rootDir, "not-flushed.jsonl") },
+			ctx,
+		);
+		await emit(h, "turn_start", { type: "turn_start", turnIndex: 1, timestamp: 0 }, ctx);
+		// 态 3：读取失败（路径指向目录，readFileSync EISDIR）
+		await emit(
+			h,
+			"session_start",
+			{ type: "session_start", reason: "fork", previousSessionFile: rootDir },
+			ctx,
+		);
+		await emit(h, "turn_start", { type: "turn_start", turnIndex: 2, timestamp: 0 }, ctx);
+
+		expect(h.entries).toHaveLength(3);
+		expect(entryData(h, 0)).toMatchObject({ version: 1, reason: "resume", hash: computePromptHash(P1) });
+		expect(entryData(h, 1)).toMatchObject({ version: 1, reason: "resume" });
+		expect(entryData(h, 2)).toMatchObject({ version: 1, reason: "resume" });
 	});
 
 	it("session_before_switch（targetSessionFile 为 string）→ 模块级 stash 跨 runtime 传递；新 runtime resume + hash 未变 → 不写", async () => {

package/src/__tests__/trace.a11.test.ts

@@ -6,17 +6,24 @@
  *   首个 turn_start 写 initial/resume
  * - hash 去重：相同不重写；变化写 change 且 parentVersionDiffSummary 生成
  * - SessionStartEvent.reason 原生 5 值（startup/reload/new/resume/fork）的落盘映射：
- *   initial←startup/new、resume←resume 定案；fork/reload 暂按 resume（待 P2 实测定，A13 探针固化后更新）
+ *   initial←startup/new、resume←resume/fork/reload（设计 D2 v5 定案：fork 基线取源文件
+ *   最后留痕、reload 为同 session 运行时重建，均属重开语义）
  *
  * 本文件用内存 fake env（文件系统路径的跨重启恢复归 A12）。
  */
+import { createHash } from "node:crypto";
+
 import { describe, expect, it } from "vitest";
 
-import { computePromptHash, createSystemPromptTrace } from "../trace.js";
+import { createSystemPromptTrace } from "../trace.js";
 import type { SystemPromptTrace, TraceContext, TraceEnv } from "../trace.js";
 import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "../types.js";
 import type { SystemPromptTraceEntryData, SwitchStash } from "../types.js";
 
+// trace.ts 的 computePromptHash 已收敛为包内私有（无外部消费方）；测试本地同款实现计算期望值。
+const computePromptHash = (text: string): string =>
+	createHash("sha256").update(text, "utf-8").digest("hex");
+
 const P1 = "You are a coding agent.\nFollow AGENTS.md.";
 const P2 = "You are a coding agent.\nFollow AGENTS.md.\n[Available Models] glm-5.1 / ds-flash";
 
@@ -34,15 +41,14 @@ function makeHarness(initialPrompt: string): Harness {
 	const entries: SystemPromptTraceEntryData[] = [];
 	let prompt = initialPrompt;
 	const stash: SwitchStash = { pending: null };
-	// A11 不涉文件路径：三路基线全部 miss，隔离验证时机/去重/映射逻辑
+	// A11 不涉文件路径：三档基线全部 miss（直读 / fork prev 文件路径均不可读），隔离验证时机/去重/映射逻辑
 	const env: TraceEnv = {
 		readLastPromptFromFile: () => null,
-		readPersistedBaseline: () => null,
-		writePersistedBaseline: () => {},
 	};
 	const ctx: TraceContext = {
 		getSystemPrompt: () => prompt,
 		getSessionId: () => "sess-a11",
+		getSessionFile: () => undefined,
 		appendEntry: (customType, data) => {
 			expect(customType).toBe(SYSTEM_PROMPT_CUSTOM_TYPE);
 			if (!isSystemPromptTraceEntryData(data)) {
@@ -140,7 +146,7 @@ describe("A11 留痕时机与去重", () => {
 		expect(h.entries[2]).toMatchObject({ version: 3, reason: "change", hash: computePromptHash(P1) });
 	});
 
-	describe("reason 5 值映射（fork/reload 待 P2 实测定）", () => {
+	describe("reason 5 值映射（设计 D2 v5 定案）", () => {
 		it("定案映射：startup/new → initial；resume → resume", () => {
 			const hStartup = makeHarness(P1);
 			hStartup.logic.onSessionStart("startup", undefined, hStartup.ctx);
@@ -156,10 +162,10 @@ describe("A11 留痕时机与去重", () => {
 			expect(hResume.entries[0]?.reason).toBe("resume");
 		});
 
-		// 【待 P2 实测定】fork/reload 的落盘 reason 暂按 resume（fork 新文件携带源 session 历史
-		// entry、版本链延续；reload 是同 session 的 extension 运行时重建——语义上都更接近「重开」）。
-		// A13 探针（pi CLI 实测 resume 链路 reason 值）固化后更新本断言与 mapReasonForFirstWrite。
-		it("暂定映射：fork/reload → resume（P2 实测后固化，届时同步更新此断言）", () => {
+		// 定案（设计 D2 v5，M0 探针回炉后）：fork/reload → resume。fork 基线取源文件最后留痕
+		// （previousSessionFile 缺失/不可读 → null 走本映射兜底）；reload 是同 session 的
+		// extension 运行时重建——两者语义上都是「重开」而非「首建」。
+		it("定案映射：fork/reload → resume（previousSessionFile 存在但 env 全 miss 时同样兜底）", () => {
 			const hFork = makeHarness(P1);
 			hFork.logic.onSessionStart("fork", "/prev/session.jsonl", hFork.ctx);
 			hFork.logic.onTurnStart(hFork.ctx);
@@ -169,13 +175,5 @@ describe("A11 留痕时机与去重", () => {
 			expect(hFork.entries[0]?.reason).toBe("resume");
 			expect(hReload.entries[0]?.reason).toBe("resume");
 		});
-
-		it("未知 reason（untyped extension 场景）按 startup → initial", () => {
-			const h = makeHarness(P1);
-			h.logic.onSessionStart("garbage-value", undefined, h.ctx);
-			h.logic.onTurnStart(h.ctx);
-			expect(h.entries).toHaveLength(1);
-			expect(h.entries[0]?.reason).toBe("initial");
-		});
 	});
 });

package/src/baseline.ts

@@ -1,48 +1,28 @@
 /**
- * 跨重启基线的文件系统侧实现（四路径口径，见 trace.ts onSessionStart 解析优先级：
- * 路径 1 stash 直读 / 路径 2 fork prev 直读的读，与路径 3 自持久化小文件的读和写）。
+ * 跨重启基线的文件系统侧实现（三档口径，见 trace.ts onSessionStart 解析优先级：
+ * 档 1 stash 直读 / 档 2 fork 事件 previousSessionFile 直读 / 档 3 getSessionFile() 直读）。
  *
- * - readLastPromptFromSessionFile：直读 session JSONL（进程内 resume 的 targetSessionFile、
- *   fork 暂定的 previousSessionFile），倒序找最后一条 xyz:system-prompt 留痕 entry。
- * - readPersistedBaseline / writePersistedBaseline：agentDir 自持久化小文件
- *   （app 重启直 spawn resume / reload 等无 switch 事件链路的唯一基线来源），原子写入。
+ * readLastPromptFromSessionFile 是三档统一的读取入口：直读 session JSONL
+ * （进程内 resume 的 targetSessionFile、fork 的 previousSessionFile、reload / 直启 resume
+ * 的 getSessionFile() 目标文件），倒序找最后一条 xyz:system-prompt 留痕 entry。
  *
- * 所有函数不抛错：读失败返回 null、写失败 logger.error 后静默——基线丢失的代价只是
+ * 所有函数不抛错：读失败返回 null——基线丢失的代价只是
  * 下次 resume 多写一条留痕（设计 D2 已接受），不允许影响 agent 主流程。
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { readFileSync } from "node:fs";
 
-import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { isRecord } from "@zhushanwen/pi-ext-guards";
 
-const logger = getLogger("pi-system-prompt-trace");
-import { isRecord, isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "./types.js";
+import { isSystemPromptTraceEntryData, SYSTEM_PROMPT_CUSTOM_TYPE } from "./types.js";
 import type { PromptBaseline } from "./types.js";
 
-/** 自持久化基线文件名（位于 pi agentDir 下）。 */
-export const BASELINE_FILENAME = "system-prompt-trace-baseline.json";
-
-/** 基线 map 保留的 session 数上限（按 updatedAt 保留最近 N 个，防多 session 长期使用无限增长）。 */
-const MAX_BASELINE_SESSIONS = 64;
-
-interface PersistedBaselineEntry {
-	hash: string;
-	version: number;
-	updatedAt: string;
-}
-
-interface PersistedBaselineFile {
-	schemaVersion: 1;
-	sessions: Record<string, PersistedBaselineEntry>;
-}
-
 /**
  * 解析单行 session JSONL 为留痕 entry data（运行时 guard；任何形状不符 / JSON 损坏返回 null）。
  * pi 落盘形状：{"type":"custom","customType":"xyz:system-prompt","data":{...},...}
  * （session-manager.ts:1122 appendCustomEntry）。
  */
-export function parseTraceEntryData(line: string): { hash: string; version: number; fullText: string } | null {
+function parseTraceEntryData(line: string): { hash: string; version: number; fullText: string } | null {
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(line);
@@ -60,10 +40,7 @@ export function parseTraceEntryData(line: string): { hash: string; version: numb
  * 倒序扫描 session JSONL，取最后一条留痕 entry 作基线。
  * 文件缺失 / 全部损坏 / 无留痕 entry（旧 session 先于本 extension）→ null。
  */
-export function readLastPromptFromSessionFile(
-	sessionFilePath: string,
-	source: "target-file" | "previous-session-file",
-): PromptBaseline | null {
+export function readLastPromptFromSessionFile(sessionFilePath: string): PromptBaseline | null {
 	let content: string;
 	try {
 		content = readFileSync(sessionFilePath, "utf-8");
@@ -76,126 +53,8 @@ export function readLastPromptFromSessionFile(
 		if (line === "") continue;
 		const parsed = parseTraceEntryData(line);
 		if (parsed !== null) {
-			return { hash: parsed.hash, version: parsed.version, fullText: parsed.fullText, source };
+			return { hash: parsed.hash, version: parsed.version, fullText: parsed.fullText };
 		}
 	}
 	return null;
 }
-
-/** 读自持久化基线小文件。文件缺失 / JSON 损坏 / 形状不符 → null（视为无基线）。 */
-export function readPersistedBaseline(baselineFilePath: string, sessionId: string): PromptBaseline | null {
-	let raw: string;
-	try {
-		raw = readFileSync(baselineFilePath, "utf-8");
-	} catch {
-		return null;
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-	if (!isRecord(parsed)) return null;
-	const sessions = parsed["sessions"];
-	if (!isRecord(sessions)) return null;
-	if (!Object.hasOwn(sessions, sessionId)) return null;
-	const entry = sessions[sessionId];
-	if (!isRecord(entry)) return null;
-	const hash = entry["hash"];
-	const version = entry["version"];
-	if (typeof hash !== "string" || typeof version !== "number") return null;
-	return { hash, version, source: "persisted" };
-}
-
-/**
- * 写自持久化基线（read-modify-write + 临时文件原子 rename）。
- *
- * 并发语义：session pool 下多个 pi 进程共享同一 agentDir，RMW 竞态按 last-writer-wins
- * 容忍（丢的是某 session 的基线 → 下次 resume 走兜底多写一条，设计 D2 已接受）；
- * 原子 rename 保证读方永远不会看到半截 JSON。跨进程共享豁免锁论证 + tmp 唯一化登记于
- * data-source-registry.md §6（PR #186 MF2）。
- */
-
-// ── 原子写 tmp 唯一化（对齐 quota-providers cache.ts / ext-config W4 同款）──
-// 固定名 `<path>.tmp` 在多 pi 进程并发写时可碰撞互相截断；后缀 = pid + 36 进制随机段，
-// 保证写方间名字空间不相交。
-const TMP_RANDOM_BASE = 36;
-const TMP_RANDOM_SLICE_START = 2; // 跳过 Math.random 字符串的 "0." 前缀
-const TMP_RANDOM_SLICE_END = 10;
-function uniqueTmpPath(filePath: string): string {
-	return `${filePath}.tmp_${process.pid}_${Math.random()
-		.toString(TMP_RANDOM_BASE)
-		.slice(TMP_RANDOM_SLICE_START, TMP_RANDOM_SLICE_END)}`;
-}
-
-export function writePersistedBaseline(
-	baselineFilePath: string,
-	sessionId: string,
-	hash: string,
-	version: number,
-): void {
-	try {
-		const file = loadBaselineFileForWrite(baselineFilePath);
-		file.sessions[sessionId] = { hash, version, updatedAt: new Date().toISOString() };
-		pruneSessions(file.sessions);
-		mkdirSync(dirname(baselineFilePath), { recursive: true });
-		const tmpPath = uniqueTmpPath(baselineFilePath);
-		try {
-			writeFileSync(tmpPath, JSON.stringify(file, null, "\t") + "\n");
-			renameSync(tmpPath, baselineFilePath);
-		} catch (err) {
-			// 唯一名不自覆盖：写/rename 抛错的残留 tmp 须显式清理后重抛（registry §6 本文件
-			// 条目；对齐 quota-providers atomicWriteJson）；清理失败不掩盖原错误
-			try {
-				if (existsSync(tmpPath)) unlinkSync(tmpPath);
-			} catch (cleanupErr) {
-				// 清理失败仅残留一个小文件，原错误优先上抛
-				void cleanupErr;
-			}
-			throw err;
-		}
-	} catch (e) {
-		// best-effort 降级：基线写失败只影响下次 app 重启 resume 的去重（多写一条留痕，
-		// 设计 D2 已接受），不阻断 agent 主流程；logger.error → appendEntry 持久化供排查
-		logger.error("write baseline failed", { detail: String(e) });
-	}
-}
-
-/** 读现有基线文件供改写；读不到 / 损坏 → 空文件重开（逐 entry 校验，垃圾 entry 直接丢弃）。 */
-function loadBaselineFileForWrite(baselineFilePath: string): PersistedBaselineFile {
-	try {
-		const parsed: unknown = JSON.parse(readFileSync(baselineFilePath, "utf-8"));
-		if (!isRecord(parsed)) return emptyBaselineFile();
-		const sessions = parsed["sessions"];
-		if (!isRecord(sessions)) return emptyBaselineFile();
-		const clean: Record<string, PersistedBaselineEntry> = {};
-		for (const key of Object.keys(sessions)) {
-			const v = sessions[key];
-			if (!isRecord(v)) continue;
-			const hash = v["hash"];
-			const version = v["version"];
-			const updatedAt = v["updatedAt"];
-			if (typeof hash === "string" && typeof version === "number" && typeof updatedAt === "string") {
-				clean[key] = { hash, version, updatedAt };
-			}
-		}
-		return { schemaVersion: 1, sessions: clean };
-	} catch {
-		return emptyBaselineFile();
-	}
-}
-
-function emptyBaselineFile(): PersistedBaselineFile {
-	return { schemaVersion: 1, sessions: {} };
-}
-
-/** 超出上限时按 updatedAt 保留最近的 session（原地裁剪）。 */
-function pruneSessions(sessions: Record<string, PersistedBaselineEntry>): void {
-	const keys = Object.keys(sessions);
-	if (keys.length <= MAX_BASELINE_SESSIONS) return;
-	keys.sort((a, b) => sessions[b].updatedAt.localeCompare(sessions[a].updatedAt));
-	for (const key of keys.slice(MAX_BASELINE_SESSIONS)) {
-		delete sessions[key];
-	}
-}

package/src/index.ts

@@ -1,45 +1,26 @@
 /**
  * pi extension wiring：把 ExtensionContext 适配进 trace.ts 状态机并订阅三个事件。
  *
- * 事件宽松类型（参考 rename-session TurnEndLikeEvent 先例）：pi 的 on() 重载对严格事件类型
- * 做参数逆变匹配，收窄字段的本地接口更稳；字段在逻辑侧运行时归一化（normalizeSessionStartReason）。
+ * 事件直接标注 SDK 具名类型（与同组 msg-id-mapper / system-prompt 的既有风格一致）：
+ * pi 的 on() 按事件名重载，handler 参数即 SDK 事件类型。SDK reason 枚举演进时
+ * mapReasonForFirstWrite 的 switch 在编译期报 non-exhaustive（负防腐），不再有运行时静默归一。
  */
 
-import { join } from "node:path";
-
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	SessionBeforeSwitchEvent,
+	SessionStartEvent,
+	TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
 
 import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 
-import {
-	BASELINE_FILENAME,
-	readLastPromptFromSessionFile,
-	readPersistedBaseline,
-	writePersistedBaseline,
-} from "./baseline.js";
+import { readLastPromptFromSessionFile } from "./baseline.js";
 import { createSystemPromptTrace } from "./trace.js";
 import type { TraceContext, TraceEnv } from "./trace.js";
 import type { SwitchStash } from "./types.js";
 
-interface SessionStartLikeEvent {
-	type: "session_start";
-	reason: string;
-	previousSessionFile?: string;
-}
-
-interface SessionBeforeSwitchLikeEvent {
-	type: "session_before_switch";
-	reason: string;
-	targetSessionFile?: string;
-}
-
-interface TurnStartLikeEvent {
-	type: "turn_start";
-	turnIndex: number;
-	timestamp: number;
-}
-
 // 模块级单例：session_before_switch（旧 runtime）→ session_start（新 runtime）之间传递
 // targetSessionFile 直读基线。switch 会 teardown 并重建 extension runtime，闭包状态不跨
 // runtime 存活（见 types.ts SwitchStash 注释），只有模块缓存在进程内延续。
@@ -51,28 +32,24 @@ function toTraceContext(pi: ExtensionAPI, ctx: ExtensionContext): TraceContext {
 		getSystemPrompt: () => ctx.getSystemPrompt(),
 		appendEntry: (customType, data) => pi.appendEntry(customType, data),
 		getSessionId: () => ctx.sessionManager.getSessionId(),
+		getSessionFile: () => ctx.sessionManager.getSessionFile(),
 	};
 }
 
 export default function systemPromptTraceExtension(pi: ExtensionAPI): void {
 	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle）。缺此注入时
-	// trace/baseline 中 logger.error 的 appendEntry 通道是 no-op，生产默认完全静默——
+	// trace 中 logger.error 的 appendEntry 通道是 no-op，生产默认完全静默——
 	// 此前全包从未注入（文本-实现漂移审查 D3 补接线，恢复注释声称的持久化语义）。
 	// 测试环境无真实 globalPi 消费方时调用本身安全（存引用，不触发 appendEntry）。
 	setPiHandle(pi);
 
-	const baselineFilePath = join(getAgentDir(), BASELINE_FILENAME);
-
 	const env: TraceEnv = {
-		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath, "target-file"),
-		readPersistedBaseline: (sessionId) => readPersistedBaseline(baselineFilePath, sessionId),
-		writePersistedBaseline: (sessionId, hash, version) =>
-			writePersistedBaseline(baselineFilePath, sessionId, hash, version),
+		readLastPromptFromFile: (filePath) => readLastPromptFromSessionFile(filePath),
 	};
 
 	const logic = createSystemPromptTrace(env, switchStash);
 
-	pi.on("session_start", async (event: SessionStartLikeEvent, ctx: ExtensionContext) => {
+	pi.on("session_start", async (event: SessionStartEvent, ctx: ExtensionContext) => {
 		logic.onSessionStart(
 			event.reason,
 			typeof event.previousSessionFile === "string" ? event.previousSessionFile : undefined,
@@ -80,14 +57,14 @@ export default function systemPromptTraceExtension(pi: ExtensionAPI): void {
 		);
 	});
 
-	pi.on("session_before_switch", async (event: SessionBeforeSwitchLikeEvent) => {
+	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent) => {
 		logic.onSessionBeforeSwitch(
 			event.reason,
 			typeof event.targetSessionFile === "string" ? event.targetSessionFile : undefined,
 		);
 	});
 
-	pi.on("turn_start", async (_event: TurnStartLikeEvent, ctx: ExtensionContext) => {
+	pi.on("turn_start", async (_event: TurnStartEvent, ctx: ExtensionContext) => {
 		logic.onTurnStart(toTraceContext(pi, ctx));
 	});
 }

package/src/trace.ts

@@ -12,18 +12,15 @@
 
 import { createHash } from "node:crypto";
 
+import type { SessionStartEvent } from "@earendil-works/pi-coding-agent";
+
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 const logger = getLogger("pi-system-prompt-trace");
 import { summarizePromptDiff } from "./diff.js";
-import {
-	mapReasonForFirstWrite,
-	normalizeSessionStartReason,
-	SYSTEM_PROMPT_CUSTOM_TYPE,
-} from "./types.js";
+import { mapReasonForFirstWrite, SYSTEM_PROMPT_CUSTOM_TYPE } from "./types.js";
 import type {
 	PromptBaseline,
-	SessionStartReason,
 	SwitchStash,
 	SystemPromptTraceEntryData,
 	TraceReason,
@@ -34,17 +31,21 @@ export interface TraceContext {
 	getSystemPrompt(): string;
 	appendEntry(customType: string, data: unknown): void;
 	getSessionId(): string;
+	/** 当前 session 文件路径（pi sessionManager.getSessionFile()；首条 assistant 落盘前可能 undefined）。 */
+	getSessionFile(): string | undefined;
 }
 
-/** 文件系统侧依赖（wiring 用真实 fs + agentDir；测试注入临时目录实现）。 */
+/** 文件系统侧依赖（wiring 用真实 fs；测试注入临时目录实现）。 */
 export interface TraceEnv {
 	readLastPromptFromFile(filePath: string): PromptBaseline | null;
-	readPersistedBaseline(sessionId: string): PromptBaseline | null;
-	writePersistedBaseline(sessionId: string, hash: string, version: number): void;
 }
 
 export interface SystemPromptTrace {
-	onSessionStart(reason: string, previousSessionFile: string | undefined, ctx: TraceContext): void;
+	onSessionStart(
+		reason: SessionStartEvent["reason"],
+		previousSessionFile: string | undefined,
+		ctx: TraceContext,
+	): void;
 	onSessionBeforeSwitch(reason: string, targetSessionFile: string | undefined): void;
 	onTurnStart(ctx: TraceContext): void;
 }
@@ -56,12 +57,12 @@ interface CurrentPrompt {
 	fullText: string;
 }
 
-export function computePromptHash(text: string): string {
+function computePromptHash(text: string): string {
 	return createHash("sha256").update(text, "utf-8").digest("hex");
 }
 
 export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): SystemPromptTrace {
-	let sessionStartReason: SessionStartReason | null = null;
+	let sessionStartReason: SessionStartEvent["reason"] | null = null;
 	let baseline: PromptBaseline | null = null;
 	let current: CurrentPrompt | null = null;
 
@@ -84,29 +85,29 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 			data.parentVersionDiffSummary = summarizePromptDiff(parentFullText, text);
 		}
 		ctx.appendEntry(SYSTEM_PROMPT_CUSTOM_TYPE, data);
-		// 落盘成功后才刷新自持久化基线（app 重启直 spawn resume / reload 的唯一基线来源，设计 D2 路径 3）
-		env.writePersistedBaseline(ctx.getSessionId(), hash, version);
 	};
 
 	return {
 		onSessionStart(reason, previousSessionFile, ctx) {
-			sessionStartReason = normalizeSessionStartReason(reason);
+			sessionStartReason = reason;
 			current = null;
-			// 基线解析（设计 D2 跨重启四路径，优先级从高到低）：
-			// 1. session_before_switch 直读目标文件（进程内 resume；stash 为模块级单例，跨 runtime 传递）
-			// 2. fork 的 previousSessionFile 直读【暂定语义，待 P2 实测定】
-			// 3. agentDir 自持久化小文件（app 重启直 spawn resume / reload——这两种链路没有 switch 事件）
+			// 基线解析（设计 D1/D2 v5 三档，优先级从高到低）：
+			// 1. stash：session_before_switch 直读目标文件（进程内 resume；stash 为模块级单例，跨 runtime 传递）
+			// 2. fork 档：读事件 previousSessionFile（源 session 文件）最后留痕——常态 /fork 时点
+			//    fork 新文件未落盘（M0 探针实证），直读不可靠；缺失/未落盘/读取失败 → null
+			// 3. 直读档：ctx.getSessionFile() 指向当前 session 文件（覆盖 reload / 直启 resume /
+			//    new 兜底；文件不存在或无留痕 → null）
 			// 4. 全 miss → null：首个 turn 按 reason 映射写 initial/resume（resume 必写 = 兜底路径）
 			// stash 无论是否采用都消费：cancelled switch 的残留基线不允许污染下一次 session_start
 			const stashed = stash.pending;
 			stash.pending = null;
 			if (stashed !== null && sessionStartReason === "resume") {
 				baseline = stashed;
-			} else if (sessionStartReason === "fork" && previousSessionFile !== undefined) {
-				const fromPrev = env.readLastPromptFromFile(previousSessionFile);
-				baseline = fromPrev === null ? null : { ...fromPrev, source: "previous-session-file" };
+			} else if (sessionStartReason === "fork") {
+				baseline = previousSessionFile !== undefined ? env.readLastPromptFromFile(previousSessionFile) : null;
 			} else {
-				baseline = env.readPersistedBaseline(ctx.getSessionId());
+				const sessionFile = ctx.getSessionFile();
+				baseline = sessionFile === undefined ? null : env.readLastPromptFromFile(sessionFile);
 			}
 		},
 
@@ -133,10 +134,8 @@ export function createSystemPromptTrace(env: TraceEnv, stash: SwitchStash): Syst
 				}
 				// 本 session_start 周期的首个 turn_start
 				if (baseline !== null && baseline.hash === hash) {
-					// 跨重启基线命中且未变化：不写，但确立 current 供后续 turn 继续对比；
-					// 顺带刷新自持久化基线（updatedAt 续命 + 小文件丢失时自愈）
+					// 跨重启基线命中且未变化：不写，但确立 current 供后续 turn 继续对比
 					current = { version: baseline.version, hash, fullText: text };
-					env.writePersistedBaseline(ctx.getSessionId(), hash, baseline.version);
 					return;
 				}
 				// 必写：有基线 → resume（该 session 已有历史版本，这是重开点的快照，version 续接）；

package/src/types.ts

@@ -5,12 +5,12 @@
  * 数据形状见 SystemPromptTraceEntryData。
  */
 
+import { isRecord } from "@zhushanwen/pi-ext-guards";
+import type { SessionStartEvent } from "@earendil-works/pi-coding-agent";
+
 /** 留痕 entry 的 customType（xyz: 前缀 = xyz-agent 自定义命名空间）。 */
 export const SYSTEM_PROMPT_CUSTOM_TYPE = "xyz:system-prompt";
 
-/** pi SessionStartEvent.reason 原生 5 值（pi 源码 core/extensions/types.ts:565）。 */
-export type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork";
-
 /** 落盘 reason 枚举（initial/resume/change，对齐 DSH request/header 语义，设计 D2）。 */
 export type TraceReason = "initial" | "resume" | "change";
 
@@ -25,18 +25,16 @@ export interface SystemPromptTraceEntryData {
 	fullText: string;
 	/** fullText.length（UTF-16 码元数）。 */
 	charCount: number;
-	/** 与上一版的行级 diff 摘要；无 parent 全文（自持久化基线只有 hash/首条）时缺省。 */
+	/** 与上一版的行级 diff 摘要；首条留痕（无 parent）时缺省。 */
 	parentVersionDiffSummary?: string;
 }
 
-/** 跨重启恢复的 hash 基线。 */
+/** 跨重启恢复的 hash 基线（三档解析统一产自 session JSONL 留痕 entry 直读）。 */
 export interface PromptBaseline {
 	hash: string;
 	version: number;
-	/** 从 session 文件留痕 entry 直读时有值（可生成 diff 摘要）；自持久化小文件只有 hash+version。 */
+	/** 留痕 entry 直读恒有值（可生成 diff 摘要）。 */
 	fullText?: string;
-	/** 基线来源（四路径口径，见 trace.ts onSessionStart 的解析优先级）。 */
-	source: "target-file" | "previous-session-file" | "persisted";
 }
 
 /**
@@ -49,11 +47,6 @@ export interface SwitchStash {
 	pending: PromptBaseline | null;
 }
 
-/** 运行时类型 guard（taste/no-unsafe-cast：断言必须有运行时 guard，这里干脆不用断言）。 */
-export function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /** 留痕 entry data 的运行时 guard（读 JSONL / 测试断言复用）。 */
 export function isSystemPromptTraceEntryData(value: unknown): value is SystemPromptTraceEntryData {
 	if (!isRecord(value)) return false;
@@ -72,32 +65,19 @@ export function isSystemPromptTraceEntryData(value: unknown): value is SystemPro
 	);
 }
 
-const SESSION_START_REASONS: readonly SessionStartReason[] = [
-	"startup",
-	"reload",
-	"new",
-	"resume",
-	"fork",
-];
-
-/** 事件侧 reason 归一化：untyped extension 传入非 5 值时按 startup 处理（最保守：无基线则 initial）。 */
-export function normalizeSessionStartReason(raw: string): SessionStartReason {
-	return SESSION_START_REASONS.find((r) => r === raw) ?? "startup";
-}
-
 /**
  * 无基线时 SessionStartEvent.reason → 落盘 reason 的映射（A11）。
  *
  * - startup / new → initial（新 session 首建快照）
  * - resume → resume（重开快照）
- * - fork / reload → resume【暂定，待 P2 实测定（A13 探针），测试显式标注】：
- *   fork 的新文件携带源 session 的历史 entry（版本链延续，且 xyz-agent 的 fork 实际经
- *   switchSession 走 resume 链路），reload 是同 session 的 extension 运行时重建——
- *   两者语义上都更接近「重开」而非「首建」。
+ * - fork / reload → resume（设计 D2 v5 定案）：fork 基线取源文件最后留痕（previousSessionFile，
+ *   缺失/未落盘/读取失败 → null 走本映射兜底）；reload 是同 session 的 extension 运行时重建——
+ *   两者语义上都是「重开」而非「首建」。
  *
- * 注意：只要恢复了任一 hash 基线，首个 turn 一律写 resume（见 trace.ts），不走本映射。
+ * 注意：基线恢复且 hash 未变 → 不写（去重）；需写时（hash 已变）恒为 resume，不走本映射
+ * （见 trace.ts onTurnStart）。
  */
-export function mapReasonForFirstWrite(reason: SessionStartReason): TraceReason {
+export function mapReasonForFirstWrite(reason: SessionStartEvent["reason"]): TraceReason {
 	switch (reason) {
 		case "startup":
 		case "new":