@zhushanwen/pi-goal 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,423 +1,200 @@
 /**
- * Pi /goal Extension — Codex-style persistent goal-driven autonomous loop
+ * Pi /goal Extension — 工厂入口（重构后架构）
  *
- * 功能：
- * - 持久化目标设定，支持 pause/resume/clear/update
- * - Evidence-based completion（完成任务必须提供具体证据）
- * - Token 预算 + 时间预算（含 70%/90% 预警）
- * - Blocked 状态检测（连续 stall 自动阻塞）
- * - Steering 模板化（continuation / budget-limit / objective-updated）
- * - 任务清单追踪
+ * 注册 command / events，全部委托 adapters 层。
+ * __goalInit 内部调 service.createGoal（FR-4.1）。
  *
- * 健壮性保障：
- * - goalId snapshot 防止旧回调操作新 goal
- * - 时间累计统一由 persistState 管理，无双写
- * - before_agent_start 注入 context，agent_end 负责 continuation（预算检查/进度评估/续跑）
- * - deserializeState 向后兼容旧格式
- * - isProcessing 防重入（agent_end 重入时直接返回）
+ * 架构（D-21 双路径 + Ports/Adapters）：
+ * - engine/：零 Pi 依赖的纯状态机（goal/budget/types）
+ * - ports.ts：机器可检查的能力边界
+ * - adapters/ports.ts：Pi → ServicePorts 桥接（单一构造点）
+ * - service.ts：事件入口协调器（applyEvent）
+ * - adapters/：Pi 桥接（command-adapter / event-adapter / ports）
+ * - projection/：渲染（widget / prompts）
+ *
+ * FR-4.2/D-16：ctx 必填，移除 lastCtx 模块级可变状态。
+ * FR-6.4：移除 hasPendingInjection。
+ * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 守卫，在 event-adapter）。
  */
 
-import type { CustomEntry, ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
-import { type Static } from "typebox";
 
-import { handleAgentEnd } from "./agent-end-handler";
-import { handleBeforeAgentStart } from "./before-agent-start-handler";
-import { handleGoalCommand } from "./command-handler";
-import {
-	MAX_HISTORY_ENTRIES,
-} from "./constants";
+import { handleGoalCommand } from "./adapters/command-adapter";
 import {
-	createInitialState,
-	deserializeState,
-	getCompletedCount,
-	isActiveStatus,
-	isTerminalStatus,
-	type GoalExternalInit,
-} from "./state";
-import {
-	executeGoalAction,
-	type GoalManagerDetails,
-	GoalManagerParams,
-	type GoalSession,
-	HISTORY_ENTRY_TYPE,
-	isGoalEntry,
-	isStaleContextError,
-	persistGoalState,
-	updateWidget,
-} from "./tool-handler";
-import { toSingleLine } from "./widget";
-
-// ── Local Interfaces (avoid `any` on Pi callback/event signatures) ────
+	handleAgentEnd,
+	handleAgentStart,
+	handleBeforeAgentStart,
+	handleMessageEnd,
+	handleSessionStart,
+	handleTurnEnd,
+} from "./adapters/event-adapter";
+import { registerGoalControlTool } from "./adapters/goal-control-adapter";
+import { buildPorts } from "./adapters/ports";
+import { createGoal } from "./service";
+import { createGoalSession, type GoalSession } from "./session";
+
+// ── Local Interfaces (Like*Event — 避免 any on Pi callback/event signatures) ────
 
-/** Fields accessed from BeforeAgentStartEvent */
 interface BeforeAgentStartLikeEvent {
 	type: "before_agent_start";
 	prompt: string;
 	systemPrompt: string;
 }
 
-/** Fields accessed from TurnEndEvent */
 interface TurnEndLikeEvent {
 	type: "turn_end";
 	turnIndex: number;
 }
 
-/** Subset of AgentMessage.usage accessed in message_end handler */
-interface LikeUsage {
-	input?: number;
-	output?: number;
-	cacheRead?: number;
-	totalTokens?: number;
-}
-
-/** Fields accessed from MessageEndEvent */
 interface MessageEndLikeEvent {
 	type: "message_end";
 	message: {
 		role: string;
-		usage?: LikeUsage;
+		usage?: { input?: number; output?: number; cacheRead?: number; totalTokens?: number };
 	};
 }
 
-/** Fields accessed from AgentEndEvent */
 interface AgentEndLikeEvent {
 	type: "agent_end";
 	messages: unknown[];
 }
 
-/** Fields accessed from SessionStartEvent */
 interface SessionStartLikeEvent {
 	type: "session_start";
 	reason: string;
 }
 
-/** Shape of CustomMessage passed to registerMessageRenderer */
 interface LikeCustomMessage {
 	customType: string;
 	content: string | unknown;
 }
 
-/** Options bag for registerMessageRenderer callback */
 interface LikeMessageRenderOptions {
 	expanded: boolean;
 }
 
-/** Result shape accessed in renderResult */
-interface LikeToolResult {
-	content: Array<{ type: string; text?: string }>;
-	details?: GoalManagerDetails;
-}
-
-/** Options bag for renderResult callback */
-interface LikeToolRenderResultOptions {
-	expanded: boolean;
-}
-
-// ── State Reconstruction ─────────────────────────────
-
-function reconstructGoalState(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext): void {
-	session.state = null;
-	const entries = ctx.sessionManager.getEntries();
-
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i]!;
-		if (isGoalEntry(entry)) {
-			const data = entry.data as Record<string, unknown> | undefined;
-			if (data) {
-				try {
-					session.state = deserializeState(data);
-				} catch {
-					session.state = null;
-				}
-			}
-			break;
-		}
-	}
-
-	if (!session.state) return;
-
-	// 非终态 → 恢复为 active
-	if (!isTerminalStatus(session.state.status) && session.state.status !== "paused") {
-		session.state.status = "active";
-		session.state.timeStartedAt = Date.now();
-	}
-
-	// Entry GC — 标记旧的 goal-state entries
-	const goalEntryIndices: number[] = [];
-	let latestFound = false;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		if (isGoalEntry(entry)) {
-			if (!latestFound) latestFound = true;
-			else goalEntryIndices.push(i);
-		}
-	}
-	for (const idx of goalEntryIndices) {
-		entries.splice(idx, 1);
-	}
-
-	// Goal-history entry GC
-	const historyIndices: number[] = [];
-	for (let i = 0; i < entries.length; i++) {
-		const entry = entries[i]!;
-		if (entry.type === "custom" && (entry as CustomEntry).customType === HISTORY_ENTRY_TYPE) {
-			historyIndices.push(i);
-		}
-	}
-	if (historyIndices.length > MAX_HISTORY_ENTRIES) {
-		const toDelete = historyIndices.slice(0, historyIndices.length - MAX_HISTORY_ENTRIES);
-		for (let i = toDelete.length - 1; i >= 0; i--) {
-			entries.splice(toDelete[i]!, 1);
-		}
-	}
-}
-
 // ── Extension Factory ─────────────────────────────────
 
 export default function goalExtension(pi: ExtensionAPI) {
-	const session: GoalSession = {
-		state: null,
-		tasksCompletedAtAgentStart: 0,
-		hasPendingInjection: false,
-		isProcessing: false, // P1-3: 防重入
-	};
-
-	// Capture latest ctx for external API (initializeGoalFromExternal needs it for persistGoalState)
-	let lastCtx: ExtensionContext | undefined;
-
-	pi.registerTool({
-		name: "goal_manager",
-		label: "Goal Manager",
-		description:
-			"Goal mode task manager. This tool is only available after starting a goal via the /goal command. AI cannot trigger it proactively. If Goal mode is not active, calling this tool will error." +
-			"\n\nAvailable actions:" +
-			"\n- create_tasks: Decompose the objective into a task list (call once at goal start). Each task description must be a one-line summary (max 60 chars), no newlines or markdown" +
-			"\n- add_tasks: Append new tasks to the existing list (when omissions are discovered). Each task description must be a one-line summary (max 60 chars), no newlines or markdown" +
-			"\n- update_tasks: Batch update task statuses (completed requires evidence, cancelled does not block goal completion)" +
-			"\n- list_tasks: View progress and remaining budget" +
-			"\n- complete_goal: Mark the objective as achieved (all tasks must be completed + evidence)" +
-			"\n- cancel_goal: Cancel the current goal (use when user wants to exit/stop)" +
-			"\n- report_blocked: Report being blocked (use when encountering unsolvable issues)" +
-			"\n- add_subtasks: Add subtasks to a specified task (params: taskId, texts[]). Use this instead of todo tool in Goal mode" +
-			"\n- update_subtasks: Batch update subtask statuses (params: taskId, subUpdates[])" +
-			"\n- delete_subtasks: Delete subtasks from a specified task (params: taskId, subIds[])",
-		promptSnippet: "Manage task list, completion status, and exit for /goal mode",
-		promptGuidelines: [
-			"[Workflow] After receiving the objective, the first step must be create_tasks to decompose. Do not re-call if task list already exists",
-			"[Format] Each task description must be a one-line summary, max 60 chars. No newlines, markdown, or detailed parameter lists — those go in execution phase. Example: 'Fix hook-registry dedup logic' not 'Fix hook-registry dedup + transport-execute enhancementConfig guard + failover-loop ...'",
-			"[Append] When discovering omissions during execution, use add_tasks to append — do not re-call create_tasks",
-			"[Completion] After completing a task, call update_tasks with status=completed and provide evidence (e.g. 'test X passed', 'file F created')",
-			"[Goal completion] Only call complete_goal when all tasks are completed with overall evidence",
-			"[Exit] When user says 'stop', 'exit', 'cancel', '不用了', '结束', etc. indicating they don't want to continue, immediately call cancel_goal — do not guide them through complete_goal",
-			"[Blocked] When encountering unsolvable technical issues, call report_blocked with the reason",
-			"[Progress] Use list_tasks anytime to check remaining tasks and budget",
-			"[Cancel] To cancel a task, use update_tasks with status=cancelled. Cancelled tasks do not block goal completion",
-			"[Forbidden] Do not mark tasks as completed without evidence, and do not call complete_goal without evidence",
-			"[Forbidden] Do not force task completion when the user explicitly wants to exit — call cancel_goal directly",
-			"[Forbidden] Do not re-call create_tasks to overwrite existing incomplete tasks — use add_tasks to append",
-			"[Subtask] For fine-grained step tracking in Goal mode, use add_subtasks — do not use the todo tool",
-		],
-		parameters: GoalManagerParams,
+	const session: GoalSession = createGoalSession();
 
-		async execute(_toolCallId: string, params: Static<typeof GoalManagerParams>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
-			lastCtx = ctx;
-			try {
-				// P1-4: 透传 signal
-				return await executeGoalAction(pi, session, params, ctx, signal);
-			} catch (err) {
-				// P1-2: Stale context 检测 — 静默吞掉
-				if (isStaleContextError(err)) {
-					return {
-						content: [{ type: "text" as const, text: "Goal context stale after compact or session replacement." }],
-						isError: true as const,
-					};
-				}
-				const msg = err instanceof Error ? err.message : String(err);
-				const inputSummary = JSON.stringify(params, null, 2); // eslint-disable-line no-magic-numbers -- JSON.stringify indent
-				return {
-					content: [{ type: "text", text: `${msg}\n\nInput: ${inputSummary}` }],
-					isError: true,
-				};
-			}
-		},
-
-		renderCall(args: Static<typeof GoalManagerParams>, theme: Theme) {
-			let text = theme.fg("toolTitle", theme.bold("goal_manager ")) + theme.fg("muted", args.action);
-			if (args.tasks) text += ` ${theme.fg("dim", `(${args.tasks.length} tasks)`)}`;
-			if (args.updates) text += ` ${theme.fg("dim", `(${args.updates.length} updates)`)}`;
-			if (args.taskId !== undefined) text += ` ${theme.fg("accent", `#${args.taskId}`)}`;
-			if (args.texts) text += ` ${theme.fg("dim", `(${args.texts.length} subtasks)`)}`;
-			if (args.subUpdates) text += ` ${theme.fg("dim", `(${args.subUpdates.length} subtask updates)`)}`;
-			if (args.subIds) text += ` ${theme.fg("dim", `del #${args.subIds.join(",")}`)}`;
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result: LikeToolResult, { expanded }: LikeToolRenderResultOptions, theme: Theme) {
-			const details = result.details as GoalManagerDetails | undefined;
-			if (!details || !Array.isArray(details.tasks)) {
-				const text = result.content[0];
-				return new Text(text?.type === "text" ? (text.text ?? "") : "", 0, 0);
-			}
-			const tasks = details.tasks;
-			const completed = tasks.filter((t) => t.status === "completed").length;
-			const summary = theme.fg("success", `✓ ${completed}/${tasks.length} completed`);
-			if (!expanded || tasks.length === 0) {
-				return new Text(summary, 0, 0);
-			}
-			const lines = [summary];
-			for (const t of tasks) {
-				const icon = t.status === "completed"
-					? theme.fg("success", "✓")
-					: t.status === "in_progress"
-						? theme.fg("warning", "●")
-						: t.status === "cancelled"
-							? theme.fg("dim", "✗")
-							: theme.fg("dim", "☐");
-				const descText = toSingleLine(t.description);
-				const desc = (t.status === "completed" || t.status === "cancelled")
-					? theme.fg("dim", descText)
-					: theme.fg("text", descText);
-				lines.push(`  ${icon} ${theme.fg("accent", `#${t.id}`)} ${desc}`);
-			// Subtask items in expanded view
-			if (t.subtasks && t.subtasks.length > 0) {
-				for (const s of t.subtasks) {
-					const subIcon = s.status === "completed"
-						? theme.fg("success", "\u2713")
-						: s.status === "in_progress"
-							? theme.fg("warning", "\u25cf")
-							: theme.fg("dim", "\u25cb");
-					const subText = s.status === "completed" ? theme.fg("dim", s.text) : theme.fg("muted", s.text);
-					lines.push(`    ${subIcon} ${theme.fg("dim", `${t.id}.${s.id}`)} ${subText}`);
-				}
-			}
-		}
-			return new Text(lines.join("\n"), 0, 0);
-		},
-	});
-
-	// ── Command: /goal ─────────────────────────────────
+	// ── Command: /goal ────────────────────────────────
 
 	pi.registerCommand("goal", {
 		description:
-			"Goal-driven mode: /goal <objective> [--tokens N] [--timeout N] [--max-turns N] | /goal pause | /goal resume | /goal clear | /goal update <new-objective> | /goal status | /goal history",
+			"Goal-driven mode: /goal <objective> [--tokens N] [--timeout N] | /goal resume | /goal clear | /goal update <new-objective> | /goal status | /goal history",
 		handler: async (args: string | undefined, ctx: ExtensionCommandContext) => {
 			await handleGoalCommand(pi, session, args, ctx);
 		},
 	});
 
-	// ── Event: before_agent_start ──────────────────────
+	// ── Tool: goal_control（complete / report_blocked，#3 替代已删 goal_manager）──
+
+	registerGoalControlTool(pi, session);
+
+	// ── Events（全部委托 adapters/event-adapter）────────
+
 	pi.on("before_agent_start", async (_event: BeforeAgentStartLikeEvent, ctx: ExtensionContext) => {
-		lastCtx = ctx;
 		return handleBeforeAgentStart(pi, session, ctx);
 	});
 
-	// ── Event: agent_start ─────────────────────────────
-
 	pi.on("agent_start", async () => {
-		if (!session.state || !isActiveStatus(session.state.status)) return;
-		session.tasksCompletedAtAgentStart = getCompletedCount(session.state.tasks);
+		await handleAgentStart(session);
 	});
 
-	// ── Event: turn_end ────────────────────────────────
 	pi.on("turn_end", async (_event: TurnEndLikeEvent, ctx: ExtensionContext) => {
-		if (!session.state) return;
-		session.state.currentTurnIndex++;
-		updateWidget(session, ctx);
+		await handleTurnEnd(pi, session, ctx);
 	});
 
-	// ── Event: message_end (token accounting) ──────────
-	pi.on("message_end", async (event: MessageEndLikeEvent, _ctx: ExtensionContext) => {
-		if (!session.state || !isActiveStatus(session.state.status)) return;
-		if (event.message.role !== "assistant") return;
-
-		const usage = event.message.usage;
-		if (usage) {
-			const input = usage.input ?? 0;
-			const output = usage.output ?? 0;
-			const cacheRead = usage.cacheRead ?? 0;
-			if (input > 0 || output > 0) {
-				session.state.tokensUsed += Math.max(input - cacheRead, 0) + output;
-			} else if (usage.totalTokens) {
-				session.state.tokensUsed += usage.totalTokens;
-			}
-		}
+	pi.on("message_end", async (event: MessageEndLikeEvent, ctx: ExtensionContext) => {
+		await handleMessageEnd(session, ctx, event);
 	});
 
-	// ── Event: agent_end ───────────────────────────────
 	pi.on("agent_end", async (_event: AgentEndLikeEvent, ctx: ExtensionContext) => {
 		await handleAgentEnd(pi, session, ctx);
 	});
 
-	// ── Event: session_start (state reconstruction) ───
 	pi.on("session_start", async (_event: SessionStartLikeEvent, ctx: ExtensionContext) => {
-		lastCtx = ctx;
-		reconstructGoalState(pi, session, ctx);
-		if (session.state) {
-			session.tasksCompletedAtAgentStart = getCompletedCount(session.state.tasks);
-			updateWidget(session, ctx);
-		}
+		await handleSessionStart(pi, session, ctx);
 	});
 
 	// ── Message Renderers ──────────────────────────────
 
-	const goalMessageTypes = [
-		"goal-context",
-		"goal-context-exceeded",
-		"goal-staleness-reminder",
-	];
-
+	const goalMessageTypes = ["goal-context", "goal-context-exceeded"];
 	for (const customType of goalMessageTypes) {
-		pi.registerMessageRenderer(customType, (message: LikeCustomMessage, _options: LikeMessageRenderOptions, theme: Theme) => {
-			const prefix =
-				message.customType === "goal-context-exceeded"
-					? theme.fg("error", "[GOAL Budget] ")
-					: message.customType === "goal-staleness-reminder"
-						? theme.fg("warning", "[GOAL Reminder] ")
+		pi.registerMessageRenderer(
+			customType,
+			(message: LikeCustomMessage, _options: LikeMessageRenderOptions, theme: Theme) => {
+				const prefix =
+					message.customType === "goal-context-exceeded"
+						? theme.fg("error", "[GOAL Budget] ")
 						: theme.fg("accent", "[GOAL] ");
-			const content = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
-			return new Text(prefix + theme.fg("dim", content), 0, 0);
-		});
+				const content =
+					typeof message.content === "string" ? message.content : JSON.stringify(message.content);
+				return new Text(prefix + theme.fg("dim", content), 0, 0);
+			},
+		);
 	}
 
-	// ── External API: initializeGoalFromExternal ──────────
+	// ── External API: __goalInit（FR-4 双轨消除）──────────
 
 	/**
-	 * Allow other extensions (e.g. coding-workflow) to programmatically initialize a goal.
-	 * Skips the /goal command flow — directly creates state + tasks.
-	 * Returns true if initialized, false if goal already active.
+	 * 允许其他扩展（coding-workflow / plan）通过 pi.__goalInit 编程式初始化 goal。
+	 * 内部调 service.createGoal（FR-4.1——与 goal_control create 走同一创建逻辑）。
+	 *
+	 * FR-4.2/D-16: ctx 必填（消除 lastCtx 模块级可变状态）。
+	 * ports 构造复用 adapters/ports.buildPorts（DRY：单一 ports 构造点）。
+	 *
+	 * @param objective 目标描述
+	 * @param budget 预算配置，传 undefined 用默认值
+	 * @param ctx **必填**——调用方的 ExtensionContext。省略会返回 false（创建失败）。
+	 * @param slug 可选短标识（仅 widget 标题 + history 用，不注入 prompt）
+	 * @returns true 创建成功；false 已有 active goal 或 ctx 缺失
 	 */
-	function initializeGoalFromExternal(
+	const api = pi as unknown as Record<string, unknown>;
+	api.__goalInit = (
 		objective: string,
-		tasks: string[],
-		budget?: { tokenBudget?: number; timeBudgetMinutes?: number; maxTurns?: number },
-	): boolean {
-		if (session.state && isActiveStatus(session.state.status)) {
-			return false;
-		}
-
-		session.state = createInitialState(objective, budget);
-		session.tasksCompletedAtAgentStart = 0;
-
-		// Create tasks (same logic as handleCreateTasks)
-		session.state.tasks = tasks.map((desc, i) => ({
-			id: i + 1,
-			description: desc.length > 60 ? desc.slice(0, 57) + "..." : desc,
-			status: "pending" as const,
-			lastUpdatedTurn: session.state!.currentTurnIndex,
-		}));
+		budget: GoalInitBudget | undefined,
+		ctx: ExtensionContext,
+		slug?: string,
+	): boolean => {
+		if (!ctx) return false;
+		return createGoal(session, objective, budget ?? {}, buildPorts(pi, ctx), true, slug);
+	};
+}
 
-		// Persist state so it survives session reconstruction
-		// Note: ctx is captured from the last event handler invocation — acceptable
-		// because initializeGoalFromExternal is called synchronously during tool execution.
-		if (lastCtx) {
-			persistGoalState(pi, session, lastCtx);
-		}
+// ── Cross-extension API 类型（单一 source of truth，API-1）──────────
 
-		return true;
-	}
-
-	// Expose on pi for cross-extension access
-	const api = pi as unknown as Record<string, unknown>;
-	api.__goalInit = initializeGoalFromExternal satisfies GoalExternalInit;
+/**
+ * `pi.__goalInit` 的预算配置形状。
+ *
+ * 跨扩展（coding-workflow / plan）通过 `pi.__goalInit` 编程式初始化 goal 时使用。
+ * 与 `BudgetConfig` 的差异：本类型只暴露外部可设的可选字段，且全部 optional。
+ */
+export interface GoalInitBudget {
+	tokenBudget?: number;
+	timeBudgetMinutes?: number;
 }
+
+/**
+ * `pi.__goalInit` 的规范函数签名（API-1：单一 source of truth）。
+ *
+ * 跨扩展消费者应 import 本类型而非重复声明 inline alias，避免签名 drift：
+ * ```ts
+ * import type { GoalInitFn } from "@zhushanwen/pi-goal";
+ * const goalInit = (pi as unknown as { __goalInit?: GoalInitFn }).__goalInit;
+ * ```
+ *
+ * @param objective 目标描述
+ * @param budget 预算配置，传 undefined 用默认值
+ * @param ctx **必填**——调用方的 ExtensionContext。省略会返回 false（创建失败）。
+ * @param slug 可选短标识（仅 widget 标题 + history 用，不注入 prompt）
+ * @returns true 创建成功；false 已有 active goal 或 ctx 缺失
+ */
+export type GoalInitFn = (
+	objective: string,
+	budget: GoalInitBudget | undefined,
+	ctx: ExtensionContext,
+	slug?: string,
+) => boolean;

package/src/persistence.ts

@@ -0,0 +1,83 @@
+/**
+ * 持久化层 — serialize/deserialize + history entry 构造
+ *
+ * FR-5: 移除旧格式兼容，字段缺失直接 throw（tasks 字段例外——向后兼容忽略）。
+ * 零 Pi 依赖。
+ */
+
+import type { GoalRuntimeState } from "./engine/types";
+import type { GoalHistoryEntry } from "./ports";
+
+// ── 常量 ──────────────────────────────────────────────
+
+export const ENTRY_TYPE = "goal-state";
+export const HISTORY_ENTRY_TYPE = "goal-history";
+
+// ── serialize（深拷贝，纯函数）────────────────────────
+
+export function serializeState(state: GoalRuntimeState): GoalRuntimeState {
+	return {
+		...state,
+		budget: { ...state.budget },
+	};
+}
+
+// ── deserialize（FR-5 严格解析，缺字段 throw）──────────
+
+/**
+ * 反序列化持久化 state。
+ *
+ * 向后兼容：旧 entry 可能含 `tasks` 字段（task CRUD 删除前的格式），此处忽略不 throw。
+ * 其余必填字段缺失仍 throw（FR-5）。
+ */
+export function deserializeState(data: Record<string, unknown>): GoalRuntimeState {
+	const req = <T>(key: string): T => {
+		if (!(key in data) || data[key] === undefined) {
+			throw new Error(`Missing required field: ${key}`);
+		}
+		return data[key] as T;
+	};
+
+	return {
+		goalId: req("goalId"),
+		objective: req("objective"),
+		// slug 用可选解析：旧持久化数据无此字段，不能误用 req()（否则旧数据 throw → state 全丢，GAP-4）
+		slug: data.slug as string | undefined,
+		status: req("status"),
+		tokensUsed: req("tokensUsed"),
+		timeStartedAt: req("timeStartedAt"),
+		timeUsedSeconds: req("timeUsedSeconds"),
+		budget: req("budget"),
+		lastProgressTurn: req("lastProgressTurn"),
+		budgetLimitSteeringSent: req("budgetLimitSteeringSent"),
+		objectiveUpdatedAt: req("objectiveUpdatedAt"),
+		lastBlockerReason: req("lastBlockerReason"),
+		tokenWarning70Sent: req("tokenWarning70Sent"),
+		tokenWarning90Sent: req("tokenWarning90Sent"),
+		timeWarning70Sent: req("timeWarning70Sent"),
+		timeWarning90Sent: req("timeWarning90Sent"),
+		lastTurnTokensUsed: req("lastTurnTokensUsed"),
+		currentTurnIndex: req("currentTurnIndex"),
+		completedAtTurnIndex: data.completedAtTurnIndex as number | undefined,
+	};
+}
+
+// ── makeHistoryEntry ─────────────────────────────────
+
+/**
+ * 从 state 构造 GoalHistoryEntry（纯函数）。
+ *
+ * totalTasks 暂置 0（task CRUD 已删除，#7 注入 todo 进度后可重填）。
+ */
+export function makeHistoryEntry(state: GoalRuntimeState, completedTasks: number): GoalHistoryEntry {
+	return {
+		goalId: state.goalId,
+		objective: state.objective,
+		slug: state.slug,
+		status: state.status,
+		completedTasks,
+		totalTasks: 0,
+		elapsedSeconds: Math.floor(state.timeUsedSeconds),
+		timestamp: Date.now(),
+	};
+}