@zhushanwen/pi-goal 0.2.0 → 0.4.0

package/src/__tests__/index.test.ts

@@ -0,0 +1,119 @@
+/**
+ * index.ts 测试 — 工厂入口 + 跨扩展 API（pi.__goalInit）
+ *
+ * 覆盖 T1.8 (NFR-AC-8)：__goalInit 忽略 tasks 参数（tasks 废弃，D-16/FR-4 双轨消除）。
+ * 设计保证：__goalInit 签名仅 (objective, budget, ctx)，结构上无法接收 tasks。
+ *
+ * 用最小 fake pi + fake ctx 实例化 goalExtension 工厂，再调 pi.__goalInit。
+ */
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import goalExtension from "../index";
+
+// ── Minimal fake pi / ctx ─────────────────────────────
+
+interface FactoryFixture {
+	pi: ExtensionAPI & { __goalInit?: (...args: never[]) => unknown };
+	ctx: ExtensionContext;
+	states: unknown[];
+	history: unknown[];
+	sendUser: unknown[];
+}
+
+/** 工厂所需的最小 pi：registerCommand/registerTool/on/registerMessageRenderer + appendEntry/sendMessage/sendUserMessage */
+function makeFactoryFixture(): FactoryFixture {
+	const states: unknown[] = [];
+	const history: unknown[] = [];
+	const sendUser: unknown[] = [];
+	const pi = {
+		registerCommand: () => {},
+		registerTool: () => {},
+		on: () => {},
+		registerMessageRenderer: () => {},
+		appendEntry(customType: string, data?: unknown): void {
+			if (customType === "goal-history") history.push(data);
+			else states.push(data);
+		},
+		sendMessage: () => {},
+		sendUserMessage(content: unknown): void {
+			sendUser.push(content);
+		},
+	} as unknown as ExtensionAPI & { __goalInit?: (...args: never[]) => unknown };
+
+	const ctx = {
+		hasUI: true,
+		signal: { aborted: false } as AbortSignal,
+		getContextUsage: () => null,
+		ui: {
+			notify: () => {},
+			setStatus: () => {},
+			setWidget: () => {},
+			theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
+		},
+		sessionManager: { getEntries: () => [], getBranch: () => undefined },
+	} as unknown as ExtensionContext;
+
+	return { pi, ctx, states, history, sendUser };
+}
+
+// ── pi.__goalInit（NFR-AC-8 / T1.8）──────────────────
+
+describe("pi.__goalInit — tasks 参数废弃（NFR-AC-8 / T1.8）", () => {
+	it("工厂实例化后 __goalInit 存在且为函数", () => {
+		const { pi } = makeFactoryFixture();
+		goalExtension(pi);
+		expect(typeof pi.__goalInit).toBe("function");
+	});
+
+	it("正常调用 → 创建 goal（返回 true + 持久化 state）", () => {
+		const { pi, ctx, states } = makeFactoryFixture();
+		goalExtension(pi);
+		const ok = (pi.__goalInit as (o: string, b: unknown, c: ExtensionContext) => boolean)(
+			"build feature X",
+			undefined,
+			ctx,
+		);
+		expect(ok).toBe(true);
+		expect(states.length).toBeGreaterThanOrEqual(1); // appendState 调用
+		const persisted = states[0] as { objective?: string };
+		expect(persisted.objective).toBe("build feature X");
+	});
+
+	it("ctx 缺失 → 返回 false（创建失败，不 throw）", () => {
+		// FR-4.2/D-16: ctx 必填
+		const { pi } = makeFactoryFixture();
+		goalExtension(pi);
+		const init = pi.__goalInit as (o: string, b: unknown, c: unknown) => boolean;
+		expect(() => init("obj", undefined, undefined)).not.toThrow();
+		expect(init("obj", undefined, undefined)).toBe(false);
+	});
+
+	it("已有 active goal → 返回 false（拒绝重复创建）", () => {
+		const { pi, ctx } = makeFactoryFixture();
+		goalExtension(pi);
+		const init = pi.__goalInit as (o: string, b: unknown, c: ExtensionContext) => boolean;
+		expect(init("first goal", undefined, ctx)).toBe(true);
+		// 再创建 → 已有 active，拒绝
+		expect(init("second goal", undefined, ctx)).toBe(false);
+	});
+
+	it("传入 tasks（第 4 参数）→ 不 throw、不接收（结构保证：签名只取前 3 参）", () => {
+		// NFR-AC-8 核心断言：tasks 废弃后，即便调用方误传 tasks 也不影响创建。
+		// __goalInit 签名 (objective, budget, ctx) 不含 tasks 参数位，
+		// JS 多余实参被静默忽略，TS 层签名也不暴露 tasks。
+		const { pi, ctx, states } = makeFactoryFixture();
+		goalExtension(pi);
+		const init = pi.__goalInit as (...args: unknown[]) => boolean;
+		// 误传第 4 参 tasks（模拟旧调用方残留）→ 不 throw + 创建成功 + tasks 被忽略
+		const strayTasks = [{ id: 1, text: "legacy task" }];
+		let ok = false;
+		expect(() => {
+			ok = init("obj with stray tasks", undefined, ctx, strayTasks);
+		}).not.toThrow();
+		expect(ok).toBe(true);
+		// 创建的 state 不含 tasks 字段（tasks 被忽略）
+		const persisted = states[states.length - 1] as { tasks?: unknown };
+		expect(persisted.tasks).toBeUndefined();
+	});
+});

package/src/__tests__/service.test.ts

@@ -0,0 +1,317 @@
+/**
+ * service.ts 测试 — 用 fake ports（内存实现 ports.ts 接口）
+ *
+ * FR-7.2: service 层测试，不 import Pi SDK
+ */
+import { describe, expect, it } from "vitest";
+
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import { applyEvent, createGoal, finalizeGoal, persistAndUpdate, type ServicePorts } from "../service";
+import { createGoalSession } from "../session";
+
+// ── Fake Ports ───────────────────────────────────────
+
+function makeFakePorts(): ServicePorts & {
+	states: GoalRuntimeState[];
+	history: unknown[];
+} {
+	const states: GoalRuntimeState[] = [];
+	const history: unknown[] = [];
+	return {
+		states,
+		history,
+		persistence: {
+			appendState: (s) => {
+				states.push(s);
+			},
+			appendHistory: (e) => {
+				history.push(e);
+			},
+		},
+		ui: {
+			setWidget: () => {},
+			setStatus: () => {},
+			notify: () => {},
+			hasUI: true,
+			// ThemeLike 直接成员（widget 经 asTheme 取出，见 projection/widget.ts）
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		},
+		messaging: {
+			sendContextMessage: () => {},
+			sendUserMessage: () => {},
+		},
+		session: {
+			getEntries: () => [],
+			getContextUsage: () => null,
+			signal: undefined,
+		},
+	};
+}
+
+const makeState = (): GoalRuntimeState => createGoalState("test");
+
+// ── createGoal 测试 ──────────────────────────────────
+
+describe("createGoal — 唯一创建入口", () => {
+	it("成功创建：state 构造 + persist", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+		const ok = createGoal(session, "my objective", {}, ports, false);
+		expect(ok).toBe(true);
+		expect(session.state).not.toBeNull();
+		expect(session.state!.objective).toBe("my objective");
+		expect(ports.states.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it("已有 active goal → 拒绝创建（返回 false）", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+		createGoal(session, "first", {}, ports, false);
+		const ok = createGoal(session, "second", {}, ports, false);
+		expect(ok).toBe(false);
+		expect(session.state!.objective).toBe("first"); // 保持原 goal
+	});
+
+	it("终态 goal → 允许创建（覆盖）", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+		session.state = makeState();
+		session.state.status = "complete"; // 终态
+		const ok = createGoal(session, "new", {}, ports, false);
+		expect(ok).toBe(true);
+		expect(session.state.objective).toBe("new");
+	});
+});
+
+// ── finalizeGoal — history 写入矩阵 ──────────────────
+
+describe("finalizeGoal — history 写入矩阵", () => {
+	it("complete → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "complete", ports, { completedTasks: 1 });
+		expect(ports.history.length).toBe(1);
+		expect((ports.history[0] as { status: string }).status).toBe("complete");
+		expect(state.completedAtTurnIndex).toBe(state.currentTurnIndex);
+	});
+
+	it("cancelled → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "cancelled", ports, { completedTasks: 0 });
+		expect(ports.history.length).toBe(1);
+	});
+
+	it("budget_limited → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "budget_limited", ports, { completedTasks: 2 });
+		expect(ports.history.length).toBe(1);
+	});
+
+	it("time_limited → 写 history", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		finalizeGoal(state, "time_limited", ports, { completedTasks: 0 });
+		expect(ports.history.length).toBe(1);
+	});
+
+	it("终态 goal 再 finalize → throw（查表非法转换）", () => {
+		const ports = makeFakePorts();
+		const state = makeState();
+		state.status = "complete";
+		// transitionStatus 查表：终态不可转，调用方须先 isTerminalStatus 守卫
+		expect(() => finalizeGoal(state, "cancelled", ports, { completedTasks: 0 })).toThrow();
+		expect(state.status).toBe("complete");
+	});
+});
+
+// ── applyEvent — 简单事件（路径 B）────────────────────
+
+describe("applyEvent — 简单事件", () => {
+	it("message_end 累加 assistant token（FR-8.6）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", {
+			message: {
+				role: "assistant",
+				usage: { input: 100, output: 50, cacheRead: 20 },
+			},
+		}, makeFakePorts());
+		// accumulateTokens: max(100 - 20, 0) + 50 = 130
+		expect(session.state.tokensUsed).toBe(before + 130);
+	});
+
+	it("message_end 忽略非 assistant 消息", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", {
+			message: { role: "user", usage: { input: 100, output: 50 } },
+		}, makeFakePorts());
+		expect(session.state.tokensUsed).toBe(before);
+	});
+
+	it("message_end 缺 usage → 不变", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", { message: { role: "assistant" } }, makeFakePorts());
+		expect(session.state.tokensUsed).toBe(before);
+	});
+
+	it("回归#1: message_end 非 active（blocked）→ 不累加 token（FR-8.6 G-R2-001）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		session.state.status = "blocked"; // 非 active
+		const before = session.state.tokensUsed;
+		applyEvent(session, "message_end", {
+			message: {
+				role: "assistant",
+				usage: { input: 100, output: 50, cacheRead: 20 },
+			},
+		}, makeFakePorts());
+		// 回归修复：blocked 状态不累加 token（原 bug：缺 isActiveStatus 守卫）
+		expect(session.state.tokensUsed).toBe(before);
+	});
+
+	it("turn_end → currentTurnIndex++ + updateWidget effect", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const before = session.state.currentTurnIndex;
+		const effects = applyEvent(session, "turn_end", {}, makeFakePorts());
+		expect(session.state.currentTurnIndex).toBe(before + 1);
+		expect(effects).toContainEqual({ kind: "updateWidget" });
+	});
+
+	it("agent_start → 无副作用（task 已移除）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const effects = applyEvent(session, "agent_start", {}, makeFakePorts());
+		expect(effects).toEqual([]);
+	});
+
+	it("session.state=null → 返回空 effects", () => {
+		const session = createGoalSession();
+		const effects = applyEvent(session, "turn_end", {}, makeFakePorts());
+		expect(effects).toEqual([]);
+	});
+
+	it("未知事件 → 返回空 effects（不报错）", () => {
+		const session = createGoalSession();
+		session.state = makeState();
+		const effects = applyEvent(session, "unknown_event", {}, makeFakePorts());
+		expect(effects).toEqual([]);
+	});
+});
+
+// ── persistAndUpdate — #5 budget 终态检查（事件路径单一检查点，NFR F2）──
+
+describe("persistAndUpdate — #5 budget 终态检查（事件路径单一检查点）", () => {
+	it("active + token 超额（steering 已发）→ status 转 budget_limited + 写 history", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0, // 关闭时间累计，保证 tick 不额外累加
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000, // >= tokenBudget
+			budgetLimitSteeringSent: true, // token terminal 要求 steering 已发
+		};
+		const ports = makeFakePorts();
+		const stale = persistAndUpdate(session, ports);
+
+		expect(stale).toBe(false);
+		expect(session.state!.status).toBe("budget_limited");
+		expect(ports.history.length).toBe(1); // FR-8.7: 终态写 history
+		expect((ports.history[0] as { status: string }).status).toBe("budget_limited");
+	});
+
+	it("token 终态分支不重复 appendState（finalizeAndPersist 已含持久化）", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000,
+			budgetLimitSteeringSent: true,
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+		// 仅 finalizeAndPersist 内部 1 次 appendState，不再走正常 appendState
+		expect(ports.states.length).toBe(1);
+	});
+
+	it("active + time 超额 → status 转 time_limited + 写 history", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { timeBudgetMinutes: 10 },
+			timeUsedSeconds: 600, // >= 10*60
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+
+		expect(session.state!.status).toBe("time_limited");
+		expect(ports.history.length).toBe(1);
+		expect((ports.history[0] as { status: string }).status).toBe("time_limited");
+	});
+
+	it("非 active（blocked）→ 不触发 budget 检查，保持 blocked", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "blocked",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000, // 已超额，但 blocked 不检查
+			budgetLimitSteeringSent: true,
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+
+		expect(session.state!.status).toBe("blocked"); // 未变
+		expect(ports.history.length).toBe(0); // blocked 不写 history
+		expect(ports.states.length).toBe(1); // 走正常 appendState 路径
+	});
+
+	it("active 但未超额 → 正常 persist（无终态、无 history）", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 100, // 未超额
+		};
+		const ports = makeFakePorts();
+		persistAndUpdate(session, ports);
+
+		expect(session.state!.status).toBe("active"); // 未变
+		expect(ports.history.length).toBe(0);
+		expect(ports.states.length).toBe(1); // 正常 appendState
+	});
+
+	it("终态处理后 checkStale 触发 → 返回 true（status 已转终态）", () => {
+		const session = createGoalSession();
+		session.state = {
+			...makeState(),
+			status: "active",
+			timeStartedAt: 0,
+			budget: { tokenBudget: 1000 },
+			tokensUsed: 1000,
+			budgetLimitSteeringSent: true,
+		};
+		const ports = makeFakePorts();
+		const stale = persistAndUpdate(session, ports, () => true);
+		expect(stale).toBe(true);
+		// finalizeAndPersist 已执行，status 已转终态
+		expect(session.state!.status).toBe("budget_limited");
+	});
+});

package/src/__tests__/session.test.ts

@@ -0,0 +1,220 @@
+/**
+ * session.ts 测试 — reconstructGoalState + isStaleContextError
+ *
+ * 覆盖：
+ * - MF-7: reconstructGoalState 3 条 FR（G-006 entry GC / G-015 强制激活 / G-024 throw→null）
+ * - MF-8: isStaleContextError 5 pattern 匹配（G-010）
+ *
+ * 用 fake SessionPort（内存 entries 数组）。
+ */
+import { describe, expect, it } from "vitest";
+
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import {
+	ENTRY_TYPE,
+	HISTORY_ENTRY_TYPE,
+	makeHistoryEntry,
+	serializeState,
+} from "../persistence";
+import type { SessionEntryLike, SessionPort } from "../ports";
+import {
+	createGoalSession,
+	isStaleContextError,
+	reconstructGoalState,
+	STALE_CONTEXT_PATTERNS,
+} from "../session";
+
+// ── Fake SessionPort ─────────────────────────────────
+
+function makeFakeSessionPort(entries: SessionEntryLike[]): SessionPort {
+	return {
+		// 模拟 Pi SDK filter-copy 语义：返回新数组，避免测试掩盖 splice GC 失效
+		getEntries: () => entries.slice(),
+		getContextUsage: () => null,
+		signal: undefined,
+	};
+}
+
+function makeGoalStateEntry(state: GoalRuntimeState): SessionEntryLike {
+	return { type: "custom", customType: ENTRY_TYPE, data: serializeState(state) };
+}
+
+function makeHistoryEntryWrapper(entry: unknown): SessionEntryLike {
+	return { type: "custom", customType: HISTORY_ENTRY_TYPE, data: entry };
+}
+
+// ── isStaleContextError（MF-8, FR-8.2 G-010）──────────
+
+describe("isStaleContextError (FR-8.2 G-010)", () => {
+	it("5 个 STALE_CONTEXT_PATTERNS 各匹配", () => {
+		for (const pattern of STALE_CONTEXT_PATTERNS) {
+			const err = new Error(`something ${pattern} happened`);
+			expect(isStaleContextError(err)).toBe(true);
+		}
+	});
+
+	it("大小写混合匹配", () => {
+		expect(isStaleContextError(new Error("Context CANCELED"))).toBe(true);
+		expect(isStaleContextError(new Error("ABORTED by user"))).toBe(true);
+	});
+
+	it("非 stale 错误 → false", () => {
+		expect(isStaleContextError(new Error("network timeout"))).toBe(false);
+		expect(isStaleContextError(new Error("permission denied"))).toBe(false);
+	});
+
+	it("字符串输入（非 Error）", () => {
+		expect(isStaleContextError("the context was aborted")).toBe(true);
+		expect(isStaleContextError("random error string")).toBe(false);
+	});
+
+	it("null/undefined 输入 → false（不抛错）", () => {
+		expect(isStaleContextError(null)).toBe(false);
+		expect(isStaleContextError(undefined)).toBe(false);
+	});
+});
+
+// ── reconstructGoalState（MF-7）──────────────────────
+
+describe("reconstructGoalState", () => {
+	it("无 goal-state entry → state=null", () => {
+		const session = createGoalSession();
+		const port = makeFakeSessionPort([]);
+		reconstructGoalState(session, port);
+		expect(session.state).toBeNull();
+	});
+
+	it("有 goal-state entry → 恢复 state", () => {
+		const session = createGoalSession();
+		const state = createGoalState("my objective");
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		expect(session.state).not.toBeNull();
+		expect(session.state!.objective).toBe("my objective");
+	});
+
+	it("G-006: 多个 goal-state entry → 恢复最新（append-only，不 splice）", () => {
+		const session = createGoalSession();
+		const oldState = createGoalState("old");
+		const newState = createGoalState("new");
+		const entries: SessionEntryLike[] = [
+			makeGoalStateEntry(oldState),
+			makeGoalStateEntry(newState), // 最新（在后面）
+		];
+		const port = makeFakeSessionPort(entries);
+		reconstructGoalState(session, port);
+		// 恢复的是最新的
+		expect(session.state!.objective).toBe("new");
+		// append-only：旧 entry 不被删除（splice GC 在生产不生效）
+		const remaining = entries.filter((e) => e.customType === ENTRY_TYPE);
+		expect(remaining).toHaveLength(2);
+	});
+
+	it("G-006: goal-history 超出 20 条仍正确恢复 state（append-only，不 splice）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("active goal");
+		// 插入 25 个 history entry + 1 个 goal-state
+		const entries: SessionEntryLike[] = [];
+		for (let i = 0; i < 25; i++) {
+			entries.push(makeHistoryEntryWrapper({ goalId: `g-${i}`, timestamp: i }));
+		}
+		entries.push(makeGoalStateEntry(state));
+		const port = makeFakeSessionPort(entries);
+		reconstructGoalState(session, port);
+		// append-only：history 不被删除（显示侧截断，splice GC 在生产不生效）
+		const historyRemaining = entries.filter((e) => e.customType === HISTORY_ENTRY_TYPE);
+		expect(historyRemaining).toHaveLength(25);
+		// state 仍正确恢复
+		expect(session.state!.objective).toBe("active goal");
+	});
+
+	it("FR-3: blocked 非终态 → 保持 blocked（崩溃不抹除 agent 叫停状态）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("blocked goal");
+		state.status = "blocked";
+		state.timeStartedAt = 1000; // 旧值
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		// blocked 保持 blocked（不强制 active）
+		expect(session.state!.status).toBe("blocked");
+		// timeStartedAt 不重置（非 active 不重启计时）
+		expect(session.state!.timeStartedAt).toBe(1000);
+	});
+
+	it("FR-3: paused 非终态 → 保持 paused（崩溃不抹除用户叫停状态）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("paused goal");
+		state.status = "paused";
+		state.timeStartedAt = 2000;
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		expect(session.state!.status).toBe("paused");
+		expect(session.state!.timeStartedAt).toBe(2000);
+	});
+
+	it("FR-3: active → 保持 active + 重启计时（timeStartedAt = now）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("active goal");
+		state.timeStartedAt = 1000; // 旧值
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		const before = Date.now();
+		reconstructGoalState(session, port);
+		const after = Date.now();
+		expect(session.state!.status).toBe("active");
+		expect(session.state!.timeStartedAt).toBeGreaterThanOrEqual(before);
+		expect(session.state!.timeStartedAt).toBeLessThanOrEqual(after);
+	});
+
+	it("G-015: 终态保持终态（不强制激活）", () => {
+		const session = createGoalSession();
+		const state = createGoalState("completed goal");
+		state.status = "complete";
+		const port = makeFakeSessionPort([makeGoalStateEntry(state)]);
+		reconstructGoalState(session, port);
+		expect(session.state!.status).toBe("complete");
+	});
+
+	it("G-024: deserialize throw（损坏 data）→ state=null", () => {
+		const session = createGoalSession();
+		// 缺少必填字段 → deserializeState throw
+		const brokenEntry: SessionEntryLike = {
+			type: "custom",
+			customType: ENTRY_TYPE,
+			data: { goalId: "x" }, // 缺大量必填字段
+		};
+		const port = makeFakeSessionPort([brokenEntry]);
+		reconstructGoalState(session, port);
+		expect(session.state).toBeNull();
+	});
+
+	it("data=undefined 的 entry → 跳过（state=null）", () => {
+		const session = createGoalSession();
+		const entry: SessionEntryLike = {
+			type: "custom",
+			customType: ENTRY_TYPE,
+			data: undefined,
+		};
+		const port = makeFakeSessionPort([entry]);
+		reconstructGoalState(session, port);
+		expect(session.state).toBeNull();
+	});
+
+	it("makeHistoryEntry + serializeState 往返一致性", () => {
+		// 验证辅助函数本身正确（makeHistoryEntry 用于 history entry 构造）
+		const state = createGoalState("roundtrip");
+		state.status = "complete";
+		const hist = makeHistoryEntry(state, 5);
+		expect(hist.goalId).toBe(state.goalId);
+		expect(hist.objective).toBe("roundtrip");
+		expect(hist.status).toBe("complete");
+		expect(hist.completedTasks).toBe(5);
+		expect(typeof hist.elapsedSeconds).toBe("number");
+		expect(typeof hist.timestamp).toBe("number");
+		// serializeState 返回深拷贝（修改返回值不影响原 state）
+		const serialized = serializeState(state);
+		expect(serialized.objective).toBe("roundtrip");
+		serialized.status = "cancelled";
+		expect(state.status).toBe("complete"); // 原状态未被修改
+	});
+});