@zhushanwen/pi-goal 0.3.0 → 0.4.0

package/src/commands.ts

@@ -2,11 +2,11 @@
  * /goal 命令定义和参数解析
  */
 
-import { MAX_STALL_CAP, MAX_TURNS_CAP, UPDATE_PREFIX_LENGTH } from "./constants";
-import type { BudgetConfig } from "./state";
+import { UPDATE_PREFIX_LENGTH } from "./constants";
+import type { BudgetConfig } from "./engine/types";
 
 export interface GoalCommandArgs {
-	action: "set" | "status" | "pause" | "resume" | "clear" | "abort" | "update" | "history";
+	action: "set" | "status" | "pause" | "resume" | "clear" | "update" | "history";
 	objective?: string;
 	budget?: Partial<BudgetConfig>;
 }
@@ -19,18 +19,15 @@ export function parseGoalArgs(raw: string): GoalCommandArgs {
 	if (trimmed === "" || trimmed === "status") {
 		return { action: "status" };
 	}
-	if (trimmed === "pause") {
-		return { action: "pause" };
-	}
 	if (trimmed === "resume") {
 		return { action: "resume" };
 	}
+	if (trimmed === "pause") {
+		return { action: "pause" };
+	}
 	if (trimmed === "clear") {
 		return { action: "clear" };
 	}
-	if (trimmed === "abort") {
-		return { action: "abort" };
-	}
 	if (trimmed === "history") {
 		return { action: "history" };
 	}
@@ -44,9 +41,9 @@ export function parseGoalArgs(raw: string): GoalCommandArgs {
 		return { action: "update" };
 	}
 
-	// /goal <objective> [--tokens N] [--timeout N] [--max-turns N] [--max-stall N]
+	// /goal <objective> [--tokens N] [--timeout N]
 	// 只匹配已知 flag，避免误删 objective 中的 -- 文本
-	const knownFlags = /--(?:tokens|timeout|max-turns|max-stall)\s+\d+/g;
+	const knownFlags = /--(?:tokens|timeout)\s+\d+/g;
 	const objective = fullRaw.replace(knownFlags, "").trim();
 	const budget: Partial<BudgetConfig> = {};
 
@@ -62,18 +59,6 @@ export function parseGoalArgs(raw: string): GoalCommandArgs {
 		if (!isNaN(val) && val > 0) budget.timeBudgetMinutes = val;
 	}
 
-	const maxTurnsMatch = fullRaw.match(/--max-turns\s+(\d+)/);
-	if (maxTurnsMatch) {
-		const val = parseInt(maxTurnsMatch[1]!, 10);
-		if (!isNaN(val)) budget.maxTurns = Math.max(1, Math.min(val, MAX_TURNS_CAP));
-	}
-
-	const maxStallMatch = fullRaw.match(/--max-stall\s+(\d+)/);
-	if (maxStallMatch) {
-		const val = parseInt(maxStallMatch[1]!, 10);
-		if (!isNaN(val)) budget.maxStallTurns = Math.max(1, Math.min(val, MAX_STALL_CAP));
-	}
-
 	if (!objective) {
 		return { action: "status" };
 	}

package/src/constants.ts

@@ -23,8 +23,6 @@ export const BUDGET_PERCENT_LOW = 70;    // widget 颜色变黄
 
 // ── 长度/数量上限 ───────────────────────────────────
 
-export const MAX_TURNS_CAP = 100;             // maxTurns 上限
-export const MAX_STALL_CAP = 20;              // maxStallTurns 上限
 export const UPDATE_PREFIX_LENGTH = 7;        // "update ".length
 
 // ── 百分比换算因子 ──────────────────────────────────
@@ -36,14 +34,9 @@ export const PERCENT_FACTOR = 100;
 export const PROGRESS_BAR_DEFAULT_WIDTH = 10;
 export const OBJECTIVE_DISPLAY_LIMIT = 80;
 export const OBJECTIVE_TRUNCATE_KEEP = 77; // DISPLAY_LIMIT - 3 for "..."
+export const TOKEN_K_THRESHOLD = 1000;     // token 数 ≥ 此值时缩写为 k 单位（12000 → 12k）
 
 // ── 停滞/清理阈值 ────────────────────────────────────
 
-export const TASK_STALL_TURN_THRESHOLD = 10;	// task/subtask 停滞提醒阈值（turn 数）
 export const AUTO_CLEAR_TURNS = 2;				// 终态后自动清理轮数
 export const MAX_HISTORY_ENTRIES = 20;			// goal-history entry GC 上限
-
-export const VERIFY_METHOD_WIDGET_LEN = 30;	// widget 中验证方法显示的截断长度
-export const EXT_INIT_TASK_DESC_MAX = 60;	// external init 中 task description 截断上限
-export const TASK_DESC_MAX_LENGTH = 80;		// task description 截断上限（normalizeDescription）
-export const ELLIPSIS_LENGTH = 3;

package/src/engine/__tests__/budget.test.ts

@@ -0,0 +1,182 @@
+/**
+ * engine/budget.ts 测试
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	accumulateTokens,
+	checkBudgetOnResume,
+	checkBudgetOnTurnEnd,
+	getBudgetColor,
+	getTimeUsagePercent,
+	getTokenUsagePercent,
+	tick,
+} from "../budget";
+import type { GoalRuntimeState } from "../types";
+
+const makeState = (overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeState => ({
+	goalId: "test",
+	objective: "test",
+	status: "active",
+	tokensUsed: 0,
+	timeStartedAt: 1000,
+	timeUsedSeconds: 0,
+	budget: {},
+	lastProgressTurn: 0,
+	budgetLimitSteeringSent: false,
+	objectiveUpdatedAt: 1000,
+	lastBlockerReason: null,
+	tokenWarning70Sent: false,
+	tokenWarning90Sent: false,
+	timeWarning70Sent: false,
+	timeWarning90Sent: false,
+	lastTurnTokensUsed: 0,
+	currentTurnIndex: 0,
+	...overrides,
+});
+
+// ── accumulateTokens（FR-8.6）─────────────────────────
+
+describe("accumulateTokens", () => {
+	it("input/output 有 → max(input-cacheRead,0)+output", () => {
+		expect(accumulateTokens(1000, { input: 100, output: 50, cacheRead: 20 })).toBe(1130);
+	});
+	it("cacheRead > input → max=0", () => {
+		expect(accumulateTokens(1000, { input: 50, output: 30, cacheRead: 100 })).toBe(1030);
+	});
+	it("input=0 output=0 → fallback totalTokens", () => {
+		expect(accumulateTokens(1000, { totalTokens: 200 })).toBe(1200);
+	});
+	it("全空 → 不累加", () => {
+		expect(accumulateTokens(1000, {})).toBe(1000);
+	});
+	it("无 cacheRead → 视为 0", () => {
+		expect(accumulateTokens(0, { input: 100, output: 50 })).toBe(150);
+	});
+});
+
+// ── tick（FR-6.5 纯函数）──────────────────────────────
+
+describe("tick", () => {
+	// timeStartedAt 是 Date.now() 毫秒时间戳；timeUsedSeconds 是累计秒数
+	it("isRunning=true → 累加 (now-start)/1000 到 timeUsedSeconds", () => {
+		expect(tick(1000000, 0, 1600000, true)).toEqual({ timeUsedSeconds: 600, timeStartedAt: 1600000 });
+	});
+	it("isRunning=true → 叠加已有 timeUsedSeconds", () => {
+		expect(tick(1000000, 100, 1600000, true)).toEqual({ timeUsedSeconds: 700, timeStartedAt: 1600000 });
+	});
+	it("isRunning=false → 不累加，但重置 timeStartedAt=now", () => {
+		expect(tick(1000000, 500, 2000000, false)).toEqual({ timeUsedSeconds: 500, timeStartedAt: 2000000 });
+	});
+	it("纯函数：相同输入相同输出", () => {
+		expect(tick(1000000, 50, 2000000, true)).toEqual(tick(1000000, 50, 2000000, true));
+	});
+});
+
+// ── checkBudgetOnTurnEnd（FR-6.2 维度独立）────────────
+
+describe("checkBudgetOnTurnEnd — 无预算", () => {
+	it("无 token/time budget → ok", () => {
+		const r = checkBudgetOnTurnEnd(makeState(), 0);
+		expect(r.terminal).toBeNull();
+		expect(r.warnings).toEqual([]);
+		expect(r.shouldSendSteering).toBe(false);
+	});
+});
+
+describe("checkBudgetOnTurnEnd — token 阈值", () => {
+	it("token < 70% → 无预警", () => {
+		const s = makeState({ tokensUsed: 600, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnTurnEnd(s, 0).warnings).toEqual([]);
+	});
+	it("token >= 70% 未发 → warning70 token", () => {
+		const s = makeState({ tokensUsed: 700, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnTurnEnd(s, 0).warnings).toContainEqual({ type: "warning70", dimension: "token" });
+	});
+	it("token >= 70% 已发 → 不重复", () => {
+		const s = makeState({ tokensUsed: 750, tokenWarning70Sent: true, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnTurnEnd(s, 0).warnings).not.toContainEqual({ type: "warning70", dimension: "token" });
+	});
+	it("token >= 90% 未发 steering → shouldSendSteering", () => {
+		const s = makeState({ tokensUsed: 950, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnTurnEnd(s, 0).shouldSendSteering).toBe(true);
+	});
+	it("token >= 100% 已发 steering → terminal exceeded token", () => {
+		const s = makeState({ tokensUsed: 1000, budgetLimitSteeringSent: true, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnTurnEnd(s, 0).terminal).toEqual({ type: "exceeded", dimension: "token" });
+	});
+});
+
+describe("checkBudgetOnTurnEnd — time 阈值", () => {
+	it("time < 70% → 无预警", () => {
+		const s = makeState({ budget: { timeBudgetMinutes: 10 } });
+		expect(checkBudgetOnTurnEnd(s, 300).warnings).toEqual([]);
+	});
+	it("time >= 70% → warning70 time", () => {
+		const s = makeState({ budget: { timeBudgetMinutes: 10 } });
+		expect(checkBudgetOnTurnEnd(s, 420).warnings).toContainEqual({ type: "warning70", dimension: "time" });
+	});
+	it("time >= 100% → terminal exceeded time", () => {
+		const s = makeState({ budget: { timeBudgetMinutes: 10 } });
+		expect(checkBudgetOnTurnEnd(s, 600).terminal).toEqual({ type: "exceeded", dimension: "time" });
+	});
+});
+
+describe("checkBudgetOnTurnEnd — FR-6.2 维度独立（核心 bug 修复）", () => {
+	it("token 已发 70%，time 到 70% 也独立发", () => {
+		const s = makeState({
+			tokensUsed: 750, tokenWarning70Sent: true,
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+		});
+		const r = checkBudgetOnTurnEnd(s, 450); // time 75%
+		expect(r.warnings).toContainEqual({ type: "warning70", dimension: "time" });
+		expect(r.warnings).not.toContainEqual({ type: "warning70", dimension: "token" });
+	});
+	it("两个维度同时到 70% → 两个 warning70 都发", () => {
+		const s = makeState({
+			tokensUsed: 750,
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+		});
+		const r = checkBudgetOnTurnEnd(s, 450);
+		expect(r.warnings).toContainEqual({ type: "warning70", dimension: "token" });
+		expect(r.warnings).toContainEqual({ type: "warning70", dimension: "time" });
+	});
+});
+
+// ── checkBudgetOnResume ──────────────────────────────
+
+describe("checkBudgetOnResume", () => {
+	it("无预算 → null", () => expect(checkBudgetOnResume(makeState())).toBeNull());
+	it("token 超额 → exceeded token", () => {
+		const s = makeState({ tokensUsed: 1000, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnResume(s)).toEqual({ type: "exceeded", dimension: "token" });
+	});
+	it("time 超额 → exceeded time", () => {
+		const s = makeState({ timeUsedSeconds: 700, budget: { timeBudgetMinutes: 10 } });
+		expect(checkBudgetOnResume(s)).toEqual({ type: "exceeded", dimension: "time" });
+	});
+	it("未超额 → null", () => {
+		const s = makeState({ tokensUsed: 500, budget: { tokenBudget: 1000 } });
+		expect(checkBudgetOnResume(s)).toBeNull();
+	});
+});
+
+
+// ── 百分比 + 颜色 ────────────────────────────────────
+
+describe("getTokenUsagePercent / getTimeUsagePercent", () => {
+	it("无 tokenBudget → 0", () => expect(getTokenUsagePercent(makeState())).toBe(0));
+	it("50% token", () => {
+		expect(getTokenUsagePercent(makeState({ tokensUsed: 500, budget: { tokenBudget: 1000 } }))).toBe(50);
+	});
+	it("无 timeBudgetMinutes → 0", () => expect(getTimeUsagePercent(makeState(), 100)).toBe(0));
+	it("50% time", () => {
+		expect(getTimeUsagePercent(makeState({ budget: { timeBudgetMinutes: 10 } }), 300)).toBe(50);
+	});
+});
+
+describe("getBudgetColor", () => {
+	it(">=90 → error", () => expect(getBudgetColor(90)).toBe("error"));
+	it(">=70 → warning", () => expect(getBudgetColor(70)).toBe("warning"));
+	it("<70 → muted", () => expect(getBudgetColor(69)).toBe("muted"));
+});

package/src/engine/__tests__/goal.test.ts

@@ -0,0 +1,126 @@
+/**
+ * engine/goal.ts 测试 — Goal 7 态状态机 + createGoalState
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	createGoalState,
+	isActiveStatus,
+	isTerminalStatus,
+	transitionStatus,
+} from "../goal";
+import type { GoalStatus } from "../types";
+
+const TERMINAL: GoalStatus[] = ["complete", "budget_limited", "time_limited", "cancelled"];
+const NON_TERMINAL: GoalStatus[] = ["active", "paused", "blocked"]; // paused #2 新增
+const ALL = [...NON_TERMINAL, ...TERMINAL];
+
+// ── isTerminalStatus / isActiveStatus ─────────────────
+
+describe("isTerminalStatus", () => {
+	for (const s of TERMINAL) {
+		it(`${s} → terminal`, () => expect(isTerminalStatus(s)).toBe(true));
+	}
+	for (const s of NON_TERMINAL) {
+		it(`${s} → NOT terminal`, () => expect(isTerminalStatus(s)).toBe(false));
+	}
+});
+
+describe("isActiveStatus", () => {
+	it("active → true", () => expect(isActiveStatus("active")).toBe(true));
+	for (const s of ALL) {
+		if (s === "active") continue;
+		it(`${s} → false`, () => expect(isActiveStatus(s)).toBe(false));
+	}
+});
+
+// ── transitionStatus（查表，非法转换 throw）──────────────
+
+describe("transitionStatus — 合法转换返回 next", () => {
+	const legalCases: Array<[GoalStatus, GoalStatus]> = [
+		["active", "paused"],
+		["active", "blocked"],
+		["active", "complete"],
+		["active", "budget_limited"],
+		["active", "time_limited"],
+		["active", "cancelled"],
+		["paused", "active"],
+		["paused", "cancelled"],
+		["blocked", "active"],
+		["blocked", "cancelled"],
+	];
+	for (const [from, to] of legalCases) {
+		it(`${from} → ${to} 返回 ${to}`, () => {
+			expect(transitionStatus(from, to)).toBe(to);
+		});
+	}
+});
+
+describe("transitionStatus — 非法转换 throw", () => {
+	// 终态不可转任何状态（VALID_TRANSITIONS 表为空）
+	for (const terminal of TERMINAL) {
+		for (const target of ALL) {
+			it(`terminal ${terminal} → ${target} throw`, () => {
+				expect(() => transitionStatus(terminal, target)).toThrow();
+			});
+		}
+	}
+	// 非终态的非法路径（不在 VALID_TRANSITIONS 表内）
+	const illegalNonTerminal: Array<[GoalStatus, GoalStatus]> = [
+		["active", "active"], // 自转不在表内
+		["paused", "paused"],
+		["paused", "blocked"],
+		["paused", "complete"],
+		["blocked", "blocked"],
+		["blocked", "paused"],
+		["blocked", "complete"],
+	];
+	for (const [from, to] of illegalNonTerminal) {
+		it(`${from} → ${to} throw`, () => {
+			expect(() => transitionStatus(from, to)).toThrow();
+		});
+	}
+});
+
+// ── createGoalState 初始值 ───────────────────────────
+
+describe("createGoalState — 初始值", () => {
+	it("status = active", () => expect(createGoalState("obj").status).toBe("active"));
+	it("objective 透传", () => expect(createGoalState("my obj").objective).toBe("my obj"));
+	it("tokensUsed = 0", () => expect(createGoalState("obj").tokensUsed).toBe(0));
+	it("timeUsedSeconds = 0", () => expect(createGoalState("obj").timeUsedSeconds).toBe(0));
+	it("goalId 非空", () => {
+		expect(createGoalState("obj").goalId).toBeTruthy();
+		expect(typeof createGoalState("obj").goalId).toBe("string");
+	});
+	it("两个 createGoalState 生成不同 goalId", () => {
+		expect(createGoalState("obj").goalId).not.toBe(createGoalState("obj").goalId);
+	});
+	it("currentTurnIndex = 0", () => expect(createGoalState("obj").currentTurnIndex).toBe(0));
+	it("completedAtTurnIndex = undefined", () => {
+		expect(createGoalState("obj").completedAtTurnIndex).toBeUndefined();
+	});
+	// FR-6.2: 4 个独立预警 flag
+	it("tokenWarning70Sent = false", () => expect(createGoalState("obj").tokenWarning70Sent).toBe(false));
+	it("tokenWarning90Sent = false", () => expect(createGoalState("obj").tokenWarning90Sent).toBe(false));
+	it("timeWarning70Sent = false", () => expect(createGoalState("obj").timeWarning70Sent).toBe(false));
+	it("timeWarning90Sent = false", () => expect(createGoalState("obj").timeWarning90Sent).toBe(false));
+});
+
+describe("createGoalState — budget 合并", () => {
+	it("无 overrides 用 DEFAULT_BUDGET", () => {
+		const s = createGoalState("obj");
+		expect(s.budget).toEqual({});
+	});
+	it("tokenBudget override", () => {
+		expect(createGoalState("obj", { tokenBudget: 10000 }).budget.tokenBudget).toBe(10000);
+	});
+	it("timeBudgetMinutes override", () => {
+		expect(createGoalState("obj", { timeBudgetMinutes: 30 }).budget.timeBudgetMinutes).toBe(30);
+	});
+	it("多字段 override", () => {
+		const s = createGoalState("obj", { tokenBudget: 5000, timeBudgetMinutes: 30 });
+		expect(s.budget.tokenBudget).toBe(5000);
+		expect(s.budget.timeBudgetMinutes).toBe(30);
+	});
+});

package/src/engine/budget.ts

@@ -0,0 +1,146 @@
+/**
+ * Budget 决策引擎 — 纯函数
+ *
+ * 零 Pi 依赖。import from "./types"。
+ *
+ * FR-6.5: tick 是纯函数（不调 Date.now，不查 status）
+ * FR-6.2: checkBudgetOnTurnEnd 用 4 个独立 flag
+ * FR-8.6: accumulateTokens token 累加算法
+ */
+
+import type { GoalRuntimeState } from "./types";
+
+// ── 常量（engine 内部，保持自洽）──────────────────────
+
+const RATIO_HIGH = 0.9;
+const RATIO_LOW = 0.7;
+const PERCENT_FACTOR = 100;
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+
+// ── 类型 ────────────────────────────────────────────
+
+export interface TokenUsage {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	totalTokens?: number;
+}
+
+export interface TickResult {
+	timeUsedSeconds: number;
+	timeStartedAt: number;
+}
+
+export type BudgetDecision =
+	| { type: "warning70"; dimension: "token" | "time" }
+	| { type: "warning90"; dimension: "token" | "time" };
+
+export interface BudgetCheckResult {
+	terminal: { type: "exceeded"; dimension: "token" | "time" } | null;
+	warnings: BudgetDecision[];
+	shouldSendSteering: boolean;
+}
+
+
+// ── token 累加（FR-8.6）──────────────────────────────
+
+export function accumulateTokens(currentTokensUsed: number, usage: TokenUsage): number {
+	const input = usage.input ?? 0;
+	const output = usage.output ?? 0;
+	const cacheRead = usage.cacheRead ?? 0;
+	if (input > 0 || output > 0) {
+		return currentTokensUsed + Math.max(input - cacheRead, 0) + output;
+	}
+	return currentTokensUsed + (usage.totalTokens ?? 0);
+}
+
+// ── 时间累计（FR-6.5 纯函数）──────────────────────────
+
+export function tick(
+	timeStartedAt: number,
+	timeUsedSeconds: number,
+	now: number,
+	isRunning: boolean,
+): TickResult {
+	if (isRunning && timeStartedAt > 0) {
+		const elapsed = (now - timeStartedAt) / MS_PER_SECOND;
+		return { timeUsedSeconds: timeUsedSeconds + elapsed, timeStartedAt: now };
+	}
+	return { timeUsedSeconds, timeStartedAt: now };
+}
+
+// ── 百分比计算 ───────────────────────────────────────
+
+export function getTokenUsagePercent(state: GoalRuntimeState): number {
+	if (!state.budget.tokenBudget || state.budget.tokenBudget <= 0) return 0;
+	return (state.tokensUsed / state.budget.tokenBudget) * PERCENT_FACTOR;
+}
+
+export function getTimeUsagePercent(state: GoalRuntimeState, timeUsedSeconds: number): number {
+	if (!state.budget.timeBudgetMinutes || state.budget.timeBudgetMinutes <= 0) return 0;
+	const budgetSeconds = state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE;
+	return (timeUsedSeconds / budgetSeconds) * PERCENT_FACTOR;
+}
+
+export function getBudgetColor(percent: number): "error" | "warning" | "muted" {
+	if (percent >= RATIO_HIGH * PERCENT_FACTOR) return "error";
+	if (percent >= RATIO_LOW * PERCENT_FACTOR) return "warning";
+	return "muted";
+}
+
+// ── turn end 预算检查（FR-6.2 维度独立）───────────────
+
+export function checkBudgetOnTurnEnd(state: GoalRuntimeState, timeUsedSeconds: number): BudgetCheckResult {
+	const result: BudgetCheckResult = { terminal: null, warnings: [], shouldSendSteering: false };
+
+	// token 维度
+	// 注：token 终态需 budgetLimitSteeringSent=true（90% steering 已发），time 维度无此 gate。
+	// 这是有意设计——token 有 90% steering 中间态（给 agent 收尾机会），需 steering 已发才确认
+	// 「agent 已被提醒但未收尾」→ 终态合理；time 维度无 steering 中间态，超额直接终态。
+	if (state.budget.tokenBudget) {
+		const tokenPct = state.tokensUsed / state.budget.tokenBudget;
+		if (tokenPct >= 1 && state.budgetLimitSteeringSent) {
+			result.terminal = { type: "exceeded", dimension: "token" };
+			return result;
+		}
+		if (tokenPct >= RATIO_HIGH && !state.budgetLimitSteeringSent) {
+			result.shouldSendSteering = true;
+		} else if (tokenPct >= RATIO_HIGH && !state.tokenWarning90Sent) {
+			result.warnings.push({ type: "warning90", dimension: "token" });
+		} else if (tokenPct >= RATIO_LOW && !state.tokenWarning70Sent) {
+			result.warnings.push({ type: "warning70", dimension: "token" });
+		}
+	}
+
+	// time 维度（FR-6.2: 独立 flag，不被 token 吞）
+	if (state.budget.timeBudgetMinutes) {
+		const budgetSeconds = state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE;
+		if (timeUsedSeconds >= budgetSeconds) {
+			result.terminal = { type: "exceeded", dimension: "time" };
+			return result;
+		}
+		const timePct = timeUsedSeconds / budgetSeconds;
+		if (timePct >= RATIO_HIGH && !state.timeWarning90Sent) {
+			result.warnings.push({ type: "warning90", dimension: "time" });
+		} else if (timePct >= RATIO_LOW && !state.timeWarning70Sent) {
+			result.warnings.push({ type: "warning70", dimension: "time" });
+		}
+	}
+
+	return result;
+}
+
+// ── resume 预算重检 ──────────────────────────────────
+
+export function checkBudgetOnResume(state: GoalRuntimeState): { type: "exceeded"; dimension: "token" | "time" } | null {
+	if (state.budget.tokenBudget && state.tokensUsed >= state.budget.tokenBudget) {
+		return { type: "exceeded", dimension: "token" };
+	}
+	if (state.budget.timeBudgetMinutes) {
+		if (state.timeUsedSeconds >= state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE) {
+			return { type: "exceeded", dimension: "time" };
+		}
+	}
+	return null;
+}

package/src/engine/goal.ts

@@ -0,0 +1,62 @@
+/**
+ * Goal 聚合状态机 — 纯函数
+ *
+ * 零 Pi 依赖。import from "./types"。
+ */
+
+import type { BudgetConfig, GoalRuntimeState, GoalStatus } from "./types";
+import { DEFAULT_BUDGET, TERMINAL_GOAL_STATUSES, VALID_TRANSITIONS } from "./types";
+
+export function isTerminalStatus(status: GoalStatus): boolean {
+	return TERMINAL_GOAL_STATUSES.has(status);
+}
+
+export function isActiveStatus(status: GoalStatus): boolean {
+	return status === "active";
+}
+
+/**
+ * 安全的状态转换。查 VALID_TRANSITIONS 表，非法转换 throw。
+ *
+ * 调用方必须在终态转换前自行检查 isTerminalStatus（如 finalizeAndPersist），
+ * 因为终态→终态不是合法转换（表为空）。对 active→终态、active→paused/blocked、
+ * paused/blocked→active/cancelled 这些合法路径直接返回 next。
+ */
+export function transitionStatus(current: GoalStatus, next: GoalStatus): GoalStatus {
+	const allowed = VALID_TRANSITIONS[current];
+	if (allowed && allowed.includes(next)) {
+		return next;
+	}
+	throw new Error(`Invalid goal state transition: ${current} → ${next}`);
+}
+
+/**
+ * 创建初始 GoalRuntimeState。纯数据构造，无副作用。
+ */
+export function createGoalState(
+	objective: string,
+	budgetOverrides?: Partial<BudgetConfig>,
+	slug?: string,
+): GoalRuntimeState {
+	const now = Date.now();
+	return {
+		goalId: crypto.randomUUID(),
+		objective,
+		slug,
+		status: "active",
+		tokensUsed: 0,
+		timeStartedAt: now,
+		timeUsedSeconds: 0,
+		budget: { ...DEFAULT_BUDGET, ...budgetOverrides },
+		lastProgressTurn: 0,
+		budgetLimitSteeringSent: false,
+		objectiveUpdatedAt: now,
+		lastBlockerReason: null,
+		tokenWarning70Sent: false,
+		tokenWarning90Sent: false,
+		timeWarning70Sent: false,
+		timeWarning90Sent: false,
+		lastTurnTokensUsed: 0,
+		currentTurnIndex: 0,
+	};
+}

package/src/engine/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Goal 运行时组合状态类型 — engine 层共享类型定义
+ *
+ * 零 Pi 依赖。
+ *
+ * FR-6.2 修复：预警 flag 按 token/time 维度独立（4 个独立 flag），
+ * 取代旧版 budgetWarning70Sent/budgetWarning90Sent 共享 flag。
+ */
+
+// ── Goal 状态枚举 ────────────────────────────────────
+
+export type GoalStatus =
+	| "active"
+	| "paused"
+	| "blocked"
+	| "complete"
+	| "budget_limited"
+	| "time_limited"
+	| "cancelled";
+
+export const TERMINAL_GOAL_STATUSES: ReadonlySet<GoalStatus> = new Set([
+	"complete",
+	"budget_limited",
+	"time_limited",
+	"cancelled",
+]);
+
+/**
+ * 显式状态转换表（system-architecture §5）。终态映射空数组——不可逆。
+ * transitionStatus 据此查表，非法转换 throw。新增状态时必须更新此表（forcing function）。
+ */
+export const VALID_TRANSITIONS: Record<GoalStatus, GoalStatus[]> = {
+	active: ["paused", "blocked", "complete", "budget_limited", "time_limited", "cancelled"],
+	paused: ["active", "cancelled"],
+	blocked: ["active", "cancelled"],
+	complete: [],
+	budget_limited: [],
+	time_limited: [],
+	cancelled: [],
+};
+
+// ── 预算配置 ────────────────────────────────────────
+
+export interface BudgetConfig {
+	tokenBudget?: number;
+	timeBudgetMinutes?: number;
+}
+
+export const DEFAULT_BUDGET: BudgetConfig = {};
+
+// ── 运行时状态（也是持久化格式）─────────────────────
+
+export interface GoalRuntimeState {
+	goalId: string;
+	objective: string;
+	/**
+	 * AI 生成的短标识（kebab-case 风格），仅用于 widget 状态栏标题与 history。
+	 * 不注入 prompt（prompt 仍读 objective，保证方向感）。
+	 * 由 goal_control create 时 AI 提供；/goal 命令路径走提示词触发器由 AI toolcall 生成。
+	 * optional：旧持久化数据无此字段，widget fallback 到 objective 截断。
+	 */
+	slug?: string;
+	status: GoalStatus;
+	tokensUsed: number;
+	timeStartedAt: number;
+	timeUsedSeconds: number;
+	budget: BudgetConfig;
+	lastProgressTurn: number;
+	budgetLimitSteeringSent: boolean;
+	objectiveUpdatedAt: number;
+	lastBlockerReason: string | null;
+	// FR-6.2: 4 个独立预警 flag
+	tokenWarning70Sent: boolean;
+	tokenWarning90Sent: boolean;
+	timeWarning70Sent: boolean;
+	timeWarning90Sent: boolean;
+	lastTurnTokensUsed: number;
+	currentTurnIndex: number;
+	completedAtTurnIndex?: number;
+}