@zhushanwen/pi-system-prompt-trace 0.1.0

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

@@ -0,0 +1,293 @@
+/**
+ * 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() 下
+ * - pi 用 Proxy 假体：捕获 on 注册的 handler 与 appendEntry 落点；handler 以 SDK 双参契约
+ *   (event, ctx) 驱动；ctx 只需 index.ts 实际消费的字段（getSystemPrompt + sessionManager.getSessionId）
+ * - switchStash 是模块级单例：beforeEach vi.resetModules 隔离用例；同 it 内二次 dynamic import
+ *   模拟「switch 重建 extension runtime + 同进程模块缓存延续」的真实链路
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+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";
+
+const P1 = "wiring prompt\nline-1";
+const P2 = "wiring prompt\nline-1\nline-2-added";
+
+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 {
+	customType: string;
+	data: unknown;
+}
+
+interface WiringHarness {
+	pi: ExtensionAPI;
+	handlers: Map<string, RecordedHandler>;
+	entries: RecordedEntry[];
+}
+
+/** Proxy 假体 pi：捕获 on 注册的 handler 与 appendEntry 落点（其余成员 no-op）。 */
+function createWiringHarness(): WiringHarness {
+	const handlers = new Map<string, RecordedHandler>();
+	const entries: RecordedEntry[] = [];
+	const pi = new Proxy<ExtensionAPI>({} as ExtensionAPI, {
+		get(_target: unknown, prop: string | symbol): unknown {
+			if (prop === "on") {
+				return (event: string, handler: RecordedHandler): void => {
+					handlers.set(event, handler);
+				};
+			}
+			if (prop === "appendEntry") {
+				return (customType: string, data?: unknown): void => {
+					entries.push({ customType, data });
+				};
+			}
+			return (): void => undefined;
+		},
+	});
+	return { pi, handlers, entries };
+}
+
+/** ctx 最小形状（index.ts 实际消费：getSystemPrompt + sessionManager.getSessionId；cwd 是 SDK 契约字段）。 */
+function createCtx(getPrompt: () => string, sessionId: string): Record<string, unknown> {
+	return {
+		cwd: "/home/user/project",
+		getSystemPrompt: getPrompt,
+		sessionManager: { getSessionId: () => sessionId },
+	};
+}
+
+/** 以 SDK 双参契约 (event, ctx) 驱动已注册 handler。 */
+async function emit(h: WiringHarness, event: string, payload: unknown, ctx: unknown): Promise<void> {
+	const handler = h.handlers.get(event);
+	if (handler === undefined) throw new Error(`handler for "${event}" not registered`);
+	await handler(payload, ctx);
+}
+
+/** 模拟 pi 落盘形状的留痕 entry（供 previousSessionFile / targetSessionFile 直读路径）。 */
+function writeSessionEntry(filePath: string, data: SystemPromptTraceEntryData): void {
+	writeFileSync(
+		filePath,
+		JSON.stringify({ type: "custom", customType: SYSTEM_PROMPT_CUSTOM_TYPE, data }) + "\n",
+	);
+}
+
+/** resetModules 后重新加载 index.ts；同 it 内二次调用拿同一模块实例（switchStash 共享）。 */
+async function loadExtension(): Promise<(pi: ExtensionAPI) => void> {
+	const mod = await import("../index.js");
+	return mod.default;
+}
+
+/** 取第 index 条 entry data（运行时 guard，拒绝 wiring 产出畸形 entry）。 */
+function entryData(h: WiringHarness, index: number): SystemPromptTraceEntryData {
+	const data = h.entries[index]?.data;
+	if (!isSystemPromptTraceEntryData(data)) {
+		throw new Error(`entry data shape invalid: ${JSON.stringify(data)}`);
+	}
+	return data;
+}
+
+let rootDir = "";
+
+beforeEach(() => {
+	rootDir = mkdtempSync(join(tmpdir(), "spt-wiring-"));
+	agentDirRef.current = rootDir;
+	vi.resetModules();
+});
+
+afterEach(() => {
+	rmSync(rootDir, { recursive: true, force: true });
+});
+
+describe("index.ts wiring SDK 契约", () => {
+	it("注册恰好三个事件 handler（session_start / session_before_switch / turn_start）", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		ext(h.pi);
+		expect([...h.handlers.keys()].sort()).toEqual([
+			"session_before_switch",
+			"session_start",
+			"turn_start",
+		]);
+	});
+
+	it("startup（无 previousSessionFile）→ 首 turn 写 initial v1（appendEntry 形状 + 基线落 getAgentDir）；prompt 变化写 change v2 带 diff 摘要", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		ext(h.pi);
+		let prompt = P1;
+		const ctx = createCtx(() => prompt, "sess-w1");
+
+		await emit(h, "session_start", { type: "session_start", reason: "startup" }, ctx);
+		await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
+		expect(h.entries).toHaveLength(1);
+		expect(h.entries[0]?.customType).toBe(SYSTEM_PROMPT_CUSTOM_TYPE);
+		expect(entryData(h, 0)).toMatchObject({
+			version: 1,
+			reason: "initial",
+			fullText: P1,
+			charCount: P1.length,
+			hash: computePromptHash(P1),
+		});
+		expect(readPersistedBaseline(join(agentDirRef.current, BASELINE_FILENAME), "sess-w1")).toMatchObject({
+			hash: computePromptHash(P1),
+			version: 1,
+		});
+
+		prompt = P2;
+		await emit(h, "turn_start", { type: "turn_start", turnIndex: 1, timestamp: 0 }, ctx);
+		expect(h.entries).toHaveLength(2);
+		const change = entryData(h, 1);
+		expect(change).toMatchObject({ version: 2, reason: "change", hash: computePromptHash(P2) });
+		expect(change.parentVersionDiffSummary).toContain("+1 -0 lines");
+	});
+
+	it("fork（previousSessionFile 为 string）→ 直读该文件作基线；hash 未变不写、仅刷新自持久化基线版本", async () => {
+		const prevFile = join(rootDir, "prev-session.jsonl");
+		writeSessionEntry(prevFile, {
+			version: 3,
+			hash: computePromptHash(P1),
+			reason: "change",
+			fullText: P1,
+			charCount: P1.length,
+		});
+
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		ext(h.pi);
+		const ctx = createCtx(() => P1, "sess-w-fork");
+		await emit(
+			h,
+			"session_start",
+			{ type: "session_start", reason: "fork", previousSessionFile: prevFile },
+			ctx,
+		);
+		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("session_before_switch（targetSessionFile 为 string）→ 模块级 stash 跨 runtime 传递；新 runtime resume + hash 未变 → 不写", async () => {
+		const targetFile = join(rootDir, "target-session.jsonl");
+		writeSessionEntry(targetFile, {
+			version: 2,
+			hash: computePromptHash(P1),
+			reason: "resume",
+			fullText: P1,
+			charCount: P1.length,
+		});
+
+		// 旧 runtime：before_switch 直读目标文件 → stash（该 handler 只消费 event）
+		const oldExt = await loadExtension();
+		const oldH = createWiringHarness();
+		oldExt(oldH.pi);
+		await emit(
+			oldH,
+			"session_before_switch",
+			{ type: "session_before_switch", reason: "resume", targetSessionFile: targetFile },
+			undefined,
+		);
+
+		// switch 重建 runtime：同进程模块缓存延续 → switchStash 传递基线
+		const newExt = await loadExtension();
+		const newH = createWiringHarness();
+		newExt(newH.pi);
+		const ctx = createCtx(() => P1, "sess-w-switch");
+		await emit(newH, "session_start", { type: "session_start", reason: "resume" }, ctx);
+		await emit(newH, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
+		expect(newH.entries).toHaveLength(0);
+	});
+
+	it("stash 基线 hash 与当前不同 → 新 runtime 写 resume 续接版本，diff 摘要 parent 全文来自目标文件", async () => {
+		const targetFile = join(rootDir, "target-session.jsonl");
+		writeSessionEntry(targetFile, {
+			version: 2,
+			hash: computePromptHash(P1),
+			reason: "resume",
+			fullText: P1,
+			charCount: P1.length,
+		});
+
+		const oldExt = await loadExtension();
+		const oldH = createWiringHarness();
+		oldExt(oldH.pi);
+		await emit(
+			oldH,
+			"session_before_switch",
+			{ type: "session_before_switch", reason: "resume", targetSessionFile: targetFile },
+			undefined,
+		);
+
+		const newExt = await loadExtension();
+		const newH = createWiringHarness();
+		newExt(newH.pi);
+		const ctx = createCtx(() => P2, "sess-w-switch2");
+		await emit(newH, "session_start", { type: "session_start", reason: "resume" }, ctx);
+		await emit(newH, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
+
+		expect(newH.entries).toHaveLength(1);
+		const entry = entryData(newH, 0);
+		expect(entry).toMatchObject({ version: 3, reason: "resume", hash: computePromptHash(P2) });
+		expect(entry.parentVersionDiffSummary).toContain("+1 -0 lines");
+	});
+
+	it("session_before_switch 无 targetSessionFile → 不读文件；resume 兜底必写 v1", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		ext(h.pi);
+		await emit(h, "session_before_switch", { type: "session_before_switch", reason: "new" }, undefined);
+		const ctx = createCtx(() => P1, "sess-w6");
+		await emit(h, "session_start", { type: "session_start", reason: "resume" }, ctx);
+		await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, ctx);
+
+		expect(h.entries).toHaveLength(1);
+		expect(entryData(h, 0)).toMatchObject({
+			version: 1,
+			reason: "resume",
+			hash: computePromptHash(P1),
+		});
+	});
+
+	it("getSystemPrompt 抛错 → handler 吞掉不写 entry（留痕是诊断旁路，不影响 agent 主流程）", async () => {
+		const ext = await loadExtension();
+		const h = createWiringHarness();
+		ext(h.pi);
+		const boomCtx = createCtx(() => {
+			throw new Error("prompt boom");
+		}, "sess-w7");
+
+		let logged = 0;
+		const errSpy = vi.spyOn(console, "error").mockImplementation(() => {
+			logged++;
+		});
+		try {
+			await emit(h, "session_start", { type: "session_start", reason: "startup" }, boomCtx);
+			await emit(h, "turn_start", { type: "turn_start", turnIndex: 0, timestamp: 0 }, boomCtx);
+		} finally {
+			errSpy.mockRestore();
+		}
+		expect(h.entries).toHaveLength(0);
+		expect(logged).toBe(1);
+	});
+});

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

@@ -0,0 +1,181 @@
+/**
+ * A11 留痕时机与去重（spec：.cw-specs/trace-ext.json；设计 D2 / plan §2.1）。
+ *
+ * 覆盖：
+ * - 写入时机：session_start 不写（emit 早于 resources_discover 的 prompt 重建，必误报——设计 D2 校正），
+ *   首个 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 探针固化后更新）
+ *
+ * 本文件用内存 fake env（文件系统路径的跨重启恢复归 A12）。
+ */
+import { describe, expect, it } from "vitest";
+
+import { computePromptHash, 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";
+
+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";
+
+interface Harness {
+	logic: SystemPromptTrace;
+	ctx: TraceContext;
+	stash: SwitchStash;
+	entries: SystemPromptTraceEntryData[];
+	setPrompt(text: string): void;
+	/** 模拟 switchSession 后 extension runtime 重建（新闭包，共享模块级 stash） */
+	newLogic(): SystemPromptTrace;
+}
+
+function makeHarness(initialPrompt: string): Harness {
+	const entries: SystemPromptTraceEntryData[] = [];
+	let prompt = initialPrompt;
+	const stash: SwitchStash = { pending: null };
+	// A11 不涉文件路径：三路基线全部 miss，隔离验证时机/去重/映射逻辑
+	const env: TraceEnv = {
+		readLastPromptFromFile: () => null,
+		readPersistedBaseline: () => null,
+		writePersistedBaseline: () => {},
+	};
+	const ctx: TraceContext = {
+		getSystemPrompt: () => prompt,
+		getSessionId: () => "sess-a11",
+		appendEntry: (customType, data) => {
+			expect(customType).toBe(SYSTEM_PROMPT_CUSTOM_TYPE);
+			if (!isSystemPromptTraceEntryData(data)) {
+				throw new Error(`entry data shape invalid: ${JSON.stringify(data)}`);
+			}
+			entries.push(data);
+		},
+	};
+	const makeLogic = (): SystemPromptTrace => createSystemPromptTrace(env, stash);
+	return {
+		logic: makeLogic(),
+		ctx,
+		stash,
+		entries,
+		setPrompt: (text) => {
+			prompt = text;
+		},
+		newLogic: makeLogic,
+	};
+}
+
+describe("A11 留痕时机与去重", () => {
+	it("session_start 不写（emit 早于 prompt 重建）；首个 turn_start 写 initial v1（hash/fullText/charCount 齐全）", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		expect(h.entries).toHaveLength(0);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(1);
+		const entry = h.entries[0];
+		if (entry === undefined) throw new Error("entry missing");
+		expect(entry).toMatchObject({
+			version: 1,
+			reason: "initial",
+			fullText: P1,
+			charCount: P1.length,
+			hash: computePromptHash(P1),
+		});
+		expect(entry.parentVersionDiffSummary).toBeUndefined();
+	});
+
+	it("new 与 startup 同映射 initial（previousSessionFile 存在也不误作基线）", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("new", "/old/session.jsonl", h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(1);
+		expect(h.entries[0]?.reason).toBe("initial");
+		expect(h.entries[0]?.version).toBe(1);
+	});
+
+	it("resume 无任何基线时兜底必写一条 reason=resume", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("resume", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(1);
+		expect(h.entries[0]).toMatchObject({ version: 1, reason: "resume" });
+	});
+
+	it("hash 相同的后续 turn_start 不重写", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(1);
+	});
+
+	it("prompt 变化写 change v2 且 parentVersionDiffSummary 生成", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx);
+		h.setPrompt(P2);
+		h.logic.onTurnStart(h.ctx);
+		expect(h.entries).toHaveLength(2);
+		const entry = h.entries[1];
+		if (entry === undefined) throw new Error("entry missing");
+		expect(entry).toMatchObject({
+			version: 2,
+			reason: "change",
+			hash: computePromptHash(P2),
+			charCount: P2.length,
+		});
+		expect(entry.parentVersionDiffSummary).toContain("+1 -0 lines");
+		expect(entry.parentVersionDiffSummary).toContain("+ [Available Models]");
+	});
+
+	it("prompt 变回旧值再写 change v3（时间线保留真实历史，只对当前版本去重）", () => {
+		const h = makeHarness(P1);
+		h.logic.onSessionStart("startup", undefined, h.ctx);
+		h.logic.onTurnStart(h.ctx); // v1 initial (P1)
+		h.setPrompt(P2);
+		h.logic.onTurnStart(h.ctx); // v2 change (P2)
+		h.setPrompt(P1);
+		h.logic.onTurnStart(h.ctx); // v3 change (P1)
+		expect(h.entries).toHaveLength(3);
+		expect(h.entries[2]).toMatchObject({ version: 3, reason: "change", hash: computePromptHash(P1) });
+	});
+
+	describe("reason 5 值映射（fork/reload 待 P2 实测定）", () => {
+		it("定案映射：startup/new → initial；resume → resume", () => {
+			const hStartup = makeHarness(P1);
+			hStartup.logic.onSessionStart("startup", undefined, hStartup.ctx);
+			hStartup.logic.onTurnStart(hStartup.ctx);
+			const hNew = makeHarness(P1);
+			hNew.logic.onSessionStart("new", undefined, hNew.ctx);
+			hNew.logic.onTurnStart(hNew.ctx);
+			const hResume = makeHarness(P1);
+			hResume.logic.onSessionStart("resume", undefined, hResume.ctx);
+			hResume.logic.onTurnStart(hResume.ctx);
+			expect(hStartup.entries[0]?.reason).toBe("initial");
+			expect(hNew.entries[0]?.reason).toBe("initial");
+			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 实测后固化，届时同步更新此断言）", () => {
+			const hFork = makeHarness(P1);
+			hFork.logic.onSessionStart("fork", "/prev/session.jsonl", hFork.ctx);
+			hFork.logic.onTurnStart(hFork.ctx);
+			const hReload = makeHarness(P1);
+			hReload.logic.onSessionStart("reload", undefined, hReload.ctx);
+			hReload.logic.onTurnStart(hReload.ctx);
+			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

@@ -0,0 +1,196 @@
+/**
+ * 跨重启基线的文件系统侧实现（设计 D2 三路径中的路径 1/2 的读与路径 2 的写）。
+ *
+ * - readLastPromptFromSessionFile：直读 session JSONL（进程内 resume 的 targetSessionFile、
+ *   fork 暂定的 previousSessionFile），倒序找最后一条 xyz:system-prompt 留痕 entry。
+ * - readPersistedBaseline / writePersistedBaseline：dataDir 自持久化小文件
+ *   （app 重启直 spawn resume 时唯一可用的基线来源），原子写入。
+ *
+ * 所有函数不抛错：读失败返回 null、写失败 console.error 后静默——基线丢失的代价只是
+ * 下次 resume 多写一条留痕（设计 D2 已接受），不允许影响 agent 主流程。
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { isRecord, 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 {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return null;
+	}
+	if (!isRecord(parsed)) return null;
+	if (parsed["type"] !== "custom" || parsed["customType"] !== SYSTEM_PROMPT_CUSTOM_TYPE) return null;
+	const data = parsed["data"];
+	if (!isSystemPromptTraceEntryData(data)) return null;
+	return { hash: data.hash, version: data.version, fullText: data.fullText };
+}
+
+/**
+ * 倒序扫描 session JSONL，取最后一条留痕 entry 作基线。
+ * 文件缺失 / 全部损坏 / 无留痕 entry（旧 session 先于本 extension）→ null。
+ */
+export function readLastPromptFromSessionFile(
+	sessionFilePath: string,
+	source: "target-file" | "previous-session-file",
+): PromptBaseline | null {
+	let content: string;
+	try {
+		content = readFileSync(sessionFilePath, "utf-8");
+	} catch {
+		return null;
+	}
+	const lines = content.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i].trim();
+		if (line === "") continue;
+		const parsed = parseTraceEntryData(line);
+		if (parsed !== null) {
+			return { hash: parsed.hash, version: parsed.version, fullText: parsed.fullText, source };
+		}
+	}
+	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 {
+				// 清理失败仅残留一个小文件，原错误优先上抛
+			}
+			throw err;
+		}
+	} catch (e) {
+		// best-effort 降级：基线写失败只影响下次 app 重启 resume 的去重（多写一条留痕，
+		// 设计 D2 已接受），不阻断 agent 主流程；错误进 pi stdout 随日志落盘供排查
+		console.error("[pi-system-prompt-trace] write baseline failed:", 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];
+	}
+}