@zhushanwen/pi-goal 0.2.0 → 0.4.0

package/src/__tests__/stale-checker.test.ts

@@ -0,0 +1,78 @@
+/**
+ * event-adapter 并发保护辅助函数测试（TC-3）
+ *
+ * 直接测试 makeStaleChecker / acquireProcessing / releaseProcessing 的快照语义，
+ * 非间接覆盖。重点：makeStaleChecker 在 state=null 时 snapshot=undefined，
+ * 后续任何新 goal 均视为 stale。
+ */
+import { describe, expect, it } from "vitest";
+
+import { acquireProcessing, makeStaleChecker, releaseProcessing } from "../adapters/event-handlers/shared";
+import { createGoalState } from "../engine/goal";
+import { createGoalSession } from "../session";
+
+describe("makeStaleChecker", () => {
+	it("snapshot 时 state=null → 后续新 goal 视为 stale", () => {
+		const session = createGoalSession();
+		// state 为 null 时 snapshot goalId = undefined
+		const checkStale = makeStaleChecker(session);
+		// 后续出现新 goal（goalId 有值）
+		session.state = createGoalState("new goal");
+		expect(checkStale()).toBe(true); // undefined !== "goal-xxx" → stale
+	});
+
+	it("snapshot 时有 goal → 同 goalId 返回 false（未 stale）", () => {
+		const session = createGoalSession();
+		session.state = createGoalState("current");
+		const snapshotId = session.state.goalId;
+		const checkStale = makeStaleChecker(session);
+		// 后续 mutate 但 goalId 不变
+		session.state.currentTurnIndex = 99;
+		expect(checkStale()).toBe(false);
+		expect(session.state.goalId).toBe(snapshotId); // 确认 goalId 未变
+	});
+
+	it("snapshot 时有 goal → goalId 变更后视为 stale（被新 goal 覆盖）", () => {
+		const session = createGoalSession();
+		session.state = createGoalState("old goal");
+		const checkStale = makeStaleChecker(session);
+		expect(checkStale()).toBe(false); // 初始未 stale
+		// 模拟新 goal 覆盖（createGoalState 生成新 goalId）
+		session.state = createGoalState("new goal overwrote");
+		expect(checkStale()).toBe(true); // goalId 变了 → stale
+	});
+
+	it("state 被清空（null）后 → 视为 stale", () => {
+		const session = createGoalSession();
+		session.state = createGoalState("then cleared");
+		const checkStale = makeStaleChecker(session);
+		expect(checkStale()).toBe(false);
+		session.state = null; // clearGoalSession 清空
+		expect(checkStale()).toBe(true);
+	});
+});
+
+describe("acquireProcessing / releaseProcessing", () => {
+	it("首次 acquire → true 并设置 isProcessing", () => {
+		const session = createGoalSession();
+		expect(session.isProcessing).toBe(false);
+		expect(acquireProcessing(session)).toBe(true);
+		expect(session.isProcessing).toBe(true);
+	});
+
+	it("已占用时再 acquire → false（防重入）", () => {
+		const session = createGoalSession();
+		expect(acquireProcessing(session)).toBe(true); // 首次成功
+		expect(acquireProcessing(session)).toBe(false); // 重入拒绝
+		expect(acquireProcessing(session)).toBe(false); // 再入仍拒绝
+	});
+
+	it("release 后可再次 acquire", () => {
+		const session = createGoalSession();
+		acquireProcessing(session);
+		expect(session.isProcessing).toBe(true);
+		releaseProcessing(session);
+		expect(session.isProcessing).toBe(false);
+		expect(acquireProcessing(session)).toBe(true); // 释放后可重新获取
+	});
+});

package/src/__tests__/stubs/pi-sdk.ts

@@ -0,0 +1,16 @@
+/**
+ * Pi SDK stub for vitest — 提供运行时 mock，避免 import 真实的 Pi 包
+ */
+
+// StringEnum: 返回 values 的 union type 的 runtime 值（简化为第一个元素）
+export function StringEnum<T extends readonly string[]>(values: T, _options?: Record<string, unknown>): T[number] {
+	return values[0] as T[number];
+}
+
+// Text: pi-tui 的渲染节点 stub（goal-control-adapter renderCall/renderResult 返回值）
+export class Text {
+	constructor(_content: unknown, _x: number, _y: number) {}
+}
+
+// Pi SDK types used in import chains — re-export as empty
+export {};

package/src/__tests__/stubs/typebox.ts

@@ -0,0 +1,14 @@
+/**
+ * typebox stub for vitest — 只需要 Type.Object/String/Array/Number/Optional/StringEnum 等
+ * 被 tool-handler.ts import 链拉入，测试中不实际调用 schema 验证
+ */
+export const Type = {
+	Object: (_schema: unknown) => ({}),
+	String: (_opts?: unknown) => ({}),
+	Number: (_opts?: unknown) => ({}),
+	Array: (_item: unknown, _opts?: unknown) => ([]),
+	Optional: (_item: unknown) => ({}),
+	Boolean: (_opts?: unknown) => ({}),
+};
+
+export type Static<_T> = Record<string, unknown>;

package/src/adapters/command-adapter.ts

@@ -0,0 +1,360 @@
+/**
+ * /goal 命令适配器 — 子命令 handler（adapters 层）
+ *
+ * 子命令：set / status / pause / resume / clear / update / history
+ * （/goal abort 随 task CRUD 一并废弃）。
+ *
+ * FR-3: pause（active→paused）与 resume（paused/blocked→active）对称设计——
+ *   两者都是非终态「停止」状态，用户控制续跑节奏。
+ *
+ * 状态变更调 service（createGoal / finalizeAndPersist）；
+ * ports 桥接复用 adapters/ports.buildPorts（DRY：单一 ports 构造点）；
+ * FR-8.12: set/resume 后 sendUserMessage 触发 AI。
+ *
+ * adapters 层可 import Pi 类型（桥接 Pi 和 service）。
+ */
+
+import type { CustomEntry, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { parseGoalArgs } from "../commands";
+import {
+	MAX_HISTORY_ENTRIES,
+	OBJECTIVE_DISPLAY_LIMIT,
+	OBJECTIVE_TRUNCATE_KEEP,
+	SECONDS_PER_MINUTE,
+} from "../constants";
+import { checkBudgetOnResume } from "../engine/budget";
+import { isActiveStatus, isTerminalStatus, transitionStatus } from "../engine/goal";
+import type { BudgetConfig } from "../engine/types";
+import { objectiveUpdatedPrompt } from "../projection/prompts";
+import { updateWidget } from "../projection/widget";
+import { finalizeAndPersist, persistState, tickState } from "../service";
+import type { GoalSession } from "../session";
+import { clearGoalSession } from "../session";
+import { buildPorts } from "./ports";
+
+// ── Orchestrator ──────────────────────────────────────
+
+/**
+ * /goal 命令分发器。按 parseGoalArgs 结果路由到子命令 handler。
+ *
+ * 调用方（index.ts 的 command handler）把原始 args 透传到这里。
+ */
+export async function handleGoalCommand(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	args: string | undefined,
+	ctx: ExtensionContext,
+): Promise<void> {
+	const parsed = parseGoalArgs(args ?? "");
+	switch (parsed.action) {
+		case "status":
+			return handleStatus(session, ctx);
+		case "pause":
+			return handlePause(pi, session, ctx);
+		case "resume":
+			return handleResume(pi, session, ctx);
+		case "history":
+			return handleHistory(ctx);
+		case "clear":
+			return handleClear(pi, session, ctx);
+		case "update":
+			return handleUpdate(pi, session, parsed.objective, ctx);
+		case "set":
+			return handleSet(pi, session, parsed.objective ?? "", parsed.budget, ctx);
+	}
+}
+
+// ── /goal status ──────────────────────────────────────
+
+function handleStatus(session: GoalSession, ctx: ExtensionContext): void {
+	if (!session.state) {
+		ctx.ui.notify("Goal mode not active. Use /goal <objective> to start.", "info");
+		return;
+	}
+	const state = session.state;
+	// 回归修复：active goal 显示实时耗时（tick 累加当前运行段后再读）
+	if (isActiveStatus(state.status)) {
+		tickState(state);
+	}
+	const timeMins = Math.floor(state.timeUsedSeconds / SECONDS_PER_MINUTE);
+	const timeSecs = Math.floor(state.timeUsedSeconds % SECONDS_PER_MINUTE);
+	const lines: Array<string | null> = [
+		state.slug ? `Slug: ${state.slug}` : null,
+		`Objective: ${state.objective}`,
+		`Status: ${state.status}`,
+		`Turn: ${state.currentTurnIndex}`,
+		`Time elapsed: ${timeMins}m${timeSecs}s`,
+		state.budget.tokenBudget ? `Token: ${state.tokensUsed}/${state.budget.tokenBudget}` : null,
+		`Goal ID: ${state.goalId}`,
+	];
+	ctx.ui.notify(lines.filter(Boolean).join("\n"), "info");
+}
+
+// ── /goal pause（FR-3 用户暂停）──────────────────────
+
+/**
+ * FR-3: active → paused（用户叫停续跑）。
+ *
+ * 对称设计（与 blocked 行为对称）：两者都是非终态「停止」状态，区别只在触发主体
+ * （paused = 用户，blocked = agent）。都不续跑、不 budget 检查、不注入 context。
+ *
+ * 先 tickState 捕获最后运行段（status 仍 active 才累加），再 transitionStatus。
+ * 复用 handleReportBlocked 的 tick-before-transition 模式（见 goal-control-adapter.ts）。
+ */
+function handlePause(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext): void {
+	if (!session.state) {
+		ctx.ui.notify("Goal mode not active.", "warning");
+		return;
+	}
+	const state = session.state;
+	if (!isActiveStatus(state.status)) {
+		ctx.ui.notify(
+			`Goal is not active (status: ${state.status}). Only an active goal can be paused.`,
+			"warning",
+		);
+		return;
+	}
+	// 先 tickState 累加当前运行段（此时 status 仍为 active）
+	tickState(state);
+	state.status = transitionStatus(state.status, "paused");
+
+	const ports = buildPorts(pi, ctx);
+	persistState(session, ports);
+	updateWidget(session, ports.ui);
+	ctx.ui.notify("Goal paused. Use /goal resume to continue.", "info");
+}
+
+// ── /goal resume ──────────────────────────────────────
+
+function handleResume(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext): void {
+	if (!session.state) {
+		ctx.ui.notify("Goal mode not active.", "warning");
+		return;
+	}
+	const state = session.state;
+	if (isTerminalStatus(state.status)) {
+		ctx.ui.notify(`Goal is in terminal state (${state.status}), cannot resume.`, "warning");
+		return;
+	}
+	// FR-3: resume 支持 paused→active 和 blocked→active（两者对称，都做 budget 重检 + 触发 AI）
+	if (state.status !== "paused" && state.status !== "blocked") {
+		ctx.ui.notify("Goal is not paused or blocked, no need to resume.", "info");
+		return;
+	}
+	state.status = "active";
+	state.timeStartedAt = Date.now();
+
+	const ports = buildPorts(pi, ctx);
+
+	// FR-8.3 G-014: resume 时 budget 重检
+	const resumeCheck = checkBudgetOnResume(state);
+	if (resumeCheck) {
+		const dim = resumeCheck.dimension;
+		// FR-8.7: 走 finalizeAndPersist 写 history（含 tick + transition + history + appendState），
+		// 勿用 transitionStatus + persistState（不写 history，goal 会从 /goal history 凭空消失）
+		finalizeAndPersist(state, dim === "token" ? "budget_limited" : "time_limited", 0, ports);
+		updateWidget(session, ports.ui);
+		ctx.ui.notify(
+			`${dim === "token" ? "Token" : "Time"} budget exhausted, cannot resume. Use /goal clear to reset.`,
+			"warning",
+		);
+		return;
+	}
+	persistState(session, ports);
+	updateWidget(session, ports.ui);
+
+	// FR-8.12 并行模式：resume 后触发 AI 继续
+	const blockerNote = state.lastBlockerReason
+		? `\n\nPrevious blocker: ${state.lastBlockerReason}. Try a different approach.`
+		: "";
+	pi.sendUserMessage(
+		`Goal resumed. Continuing toward the objective.${blockerNote}\n\nObjective: ${state.objective}`,
+		{ deliverAs: "followUp" },
+	);
+}
+
+// ── /goal history ─────────────────────────────────────
+
+interface GoalHistoryData {
+	goalId: string;
+	objective: string;
+	status: string;
+	completedTasks: number;
+	totalTasks: number;
+	elapsedSeconds: number;
+	timestamp: number;
+}
+
+function handleHistory(ctx: ExtensionContext): void {
+	const entries = ctx.sessionManager.getEntries();
+	const historyEntries = entries.filter(
+		(e): e is CustomEntry<GoalHistoryData> =>
+			e.type === "custom" && (e as CustomEntry).customType === "goal-history",
+	);
+
+	if (historyEntries.length === 0) {
+		ctx.ui.notify("No goal history", "info");
+		return;
+	}
+	// FR-8.1 G-006: session append-only（Pi getEntries 返回 filter-copy，无法 splice 旧 entry）。
+	// 显示侧截断为最近 MAX_HISTORY_ENTRIES 条，避免历史无界增长刷屏。
+	const recent = historyEntries.slice(-MAX_HISTORY_ENTRIES);
+	const sorted = [...recent].reverse();
+	const lines: string[] = ["Goal history:\n"];
+	sorted.forEach((entry, i) => {
+		const h = entry.data;
+		if (!h) return;
+		const icon =
+			h.status === "complete"
+				? "✓"
+				: h.status === "cancelled"
+					? "✗"
+					: h.status === "budget_limited"
+						? "⊗"
+						: h.status === "time_limited"
+							? "⏱"
+							: "?";
+		// GAP-5: 标题优先用 slug（紧凑），无 slug fallback objective 截断（旧 entry 兼容）
+		const title = h.slug ?? (h.objective.length > OBJECTIVE_DISPLAY_LIMIT
+			? `${h.objective.slice(0, OBJECTIVE_TRUNCATE_KEEP)}...`
+			: h.objective);
+		const mins = Math.floor(h.elapsedSeconds / SECONDS_PER_MINUTE);
+		const secs = Math.floor(h.elapsedSeconds % SECONDS_PER_MINUTE);
+		lines.push(`${i + 1}. ${icon} ${title}`);
+		lines.push(`   ${mins}m${secs}s | ${h.status}`);
+	});
+	ctx.ui.notify(lines.join("\n"), "info");
+}
+
+// ── /goal clear（强制清）──────────────────────────────
+
+/**
+ * FR-6.3：强制清。直接 cancelled + clearSession。
+ */
+function handleClear(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext): void {
+	if (!session.state) {
+		ctx.ui.notify("Goal mode not active.", "info");
+		return;
+	}
+	const ports = buildPorts(pi, ctx);
+	// transitionStatus 查表终态不可转（engine/goal.ts）：已终态 goal 直接 clearSession
+	if (!isTerminalStatus(session.state.status)) {
+		// FR-3.3: 唯一终态序列入口（tick + finalizeGoal + persist）
+		finalizeAndPersist(session.state, "cancelled", 0, ports);
+	}
+	// FR-8.7: cancelled → 立即 clearSession
+	clearGoalSession(session, ports.ui);
+	ctx.ui.notify("Goal cleared.", "info");
+}
+
+// ── /goal update（重塑）──────────────────────────────
+
+/**
+ * FR-8.4 G-002：重塑（reset）。重置 objective/budget flags/
+ * currentTurnIndex/lastProgressTurn，保留 goalId。
+ * active 状态下向 AI 注入 objective-updated steering。
+ */
+function handleUpdate(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	newObjective: string | undefined,
+	ctx: ExtensionContext,
+): void {
+	if (!session.state) {
+		ctx.ui.notify("Goal mode not active.", "warning");
+		return;
+	}
+	if (!newObjective) {
+		ctx.ui.notify("Usage: /goal update <new-objective>", "warning");
+		return;
+	}
+	const state = session.state;
+	const oldObjective = state.objective;
+	// FR-8.4 G-002: 重塑（重置，保留 goalId）
+	state.objective = newObjective;
+	state.objectiveUpdatedAt = Date.now();
+	state.currentTurnIndex = 0;
+	state.lastProgressTurn = 0;
+	state.budgetLimitSteeringSent = false;
+	state.tokenWarning70Sent = false;
+	state.tokenWarning90Sent = false;
+	state.timeWarning70Sent = false;
+	state.timeWarning90Sent = false;
+	// GAP-6: update 是重塑，旧 slug 已不匹配新 objective → 置空（widget fallback objective 截断）
+	state.slug = undefined;
+	// FR-6.5: 持久化重塑后的状态（persistState 按当前 status tick 累加）+ FR-6.1 widget 刷新
+	const updatePorts = buildPorts(pi, ctx);
+	persistState(session, updatePorts);
+	updateWidget(session, updatePorts.ui);
+	ctx.ui.notify(`Objective updated:\nPrevious: ${oldObjective}\nNew: ${newObjective}`, "info");
+
+	if (isActiveStatus(state.status)) {
+		const ports = buildPorts(pi, ctx);
+		ports.messaging.sendContextMessage(objectiveUpdatedPrompt(state, oldObjective), "steer");
+	}
+}
+
+// ── /goal set（提示词触发器）─────────────────────────
+
+/**
+ * /goal <objective> 改为「提示词触发器」：不直接 createGoal，
+ * 而是 sendUserMessage 引导 AI 调 goal_control create（slug 由 AI 生成）。
+ *
+ * 这样 goal 创建的唯一路径是 goal_control toolcall（统一入口），
+ * slug/objective/budget 都由 AI 在 toolcall 时决定。
+ *
+ * D25 守卫仍在此处预检：非终态旧 goal（active/paused/blocked）→ 拒绝，
+ * 提示 /goal resume 或 /goal clear（避免 AI 在已有未完成 goal 时重复创建）。
+ *
+ * budget flag（--tokens/--timeout）写入消息体，让 AI 原样传给 create。
+ */
+function handleSet(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	objective: string,
+	budgetOverrides: Partial<BudgetConfig> | undefined,
+	ctx: ExtensionContext,
+): void {
+	if (!objective || !objective.trim()) {
+		ctx.ui.notify("Usage: /goal <objective> [--tokens N] [--timeout N]", "warning");
+		return;
+	}
+
+	// #11 / D25: 非终态旧 goal（active/paused/blocked）→ 拒绝（不覆盖、不写 history）
+	if (session.state && !isTerminalStatus(session.state.status)) {
+		ctx.ui.notify(
+			"Goal already active. Use /goal resume to continue or /goal clear to reset.",
+			"warning",
+		);
+		return;
+	}
+
+	// budget 校验（非法值在此拦截，不进入消息体）
+	if (budgetOverrides?.tokenBudget !== undefined && budgetOverrides.tokenBudget <= 0) {
+		ctx.ui.notify("Token budget must be greater than 0.", "warning");
+		return;
+	}
+	if (budgetOverrides?.timeBudgetMinutes !== undefined && budgetOverrides.timeBudgetMinutes <= 0) {
+		ctx.ui.notify("Time budget must be greater than 0.", "warning");
+		return;
+	}
+
+	// 构造引导 AI 创建 goal 的消息（含 objective + 可选 budget）
+	const budgetHints: string[] = [];
+	if (budgetOverrides?.tokenBudget) budgetHints.push(`tokenBudget: ${budgetOverrides.tokenBudget}`);
+	if (budgetOverrides?.timeBudgetMinutes)
+		budgetHints.push(`timeBudgetMinutes: ${budgetOverrides.timeBudgetMinutes}`);
+	const budgetLine = budgetHints.length > 0 ? `\nBudget: ${budgetHints.join(", ")}` : "";
+
+	const message =
+		`Start a new goal with the objective below. Call goal_control(action="create") with:\n` +
+		`- slug: a short kebab-case identifier you generate for this goal\n` +
+		`- objective: the full objective text\n` +
+		(budgetHints.length > 0 ? `- pass through the budget values below as-is\n` : "") +
+		`\nObjective: ${objective.trim()}${budgetLine}`;
+
+	ctx.ui.notify(`Requesting goal start: ${objective.trim()}`, "info");
+	// FR-8.12: 触发 AI（followUp）—— AI 消化后调 goal_control create
+	pi.sendUserMessage(message, { deliverAs: "followUp" });
+}

package/src/adapters/event-adapter.ts

@@ -0,0 +1,17 @@
+/**
+ * Event adapter — 薄路由（#4 拆分后）。
+ *
+ * 6 个事件 handler 拆到 event-handlers/，本文件只做 re-export。
+ * handler 逻辑见各自文件。pi.on 注册在 index.ts（保持不变）。
+ *
+ * 行为等价（#4 验收）：handler 逻辑原样搬迁，仅 persistAndUpdate 签名 ports 化
+ * （见 service.ts）+ turn_end 的 buildPorts 调用从两次收敛为一次。
+ */
+
+export { handleAgentEnd } from "./event-handlers/agent-end";
+export { handleAgentStart } from "./event-handlers/agent-start";
+export { handleBeforeAgentStart } from "./event-handlers/before-agent-start";
+export type { MessageEndLikeEvent } from "./event-handlers/message-end";
+export { handleMessageEnd } from "./event-handlers/message-end";
+export { handleSessionStart } from "./event-handlers/session-start";
+export { handleTurnEnd } from "./event-handlers/turn-end";

package/src/adapters/event-handlers/agent-end.ts

@@ -0,0 +1,177 @@
+/**
+ * 事件 6: agent_end（FR-8.7 + ESC 守卫 + 并发保护）。
+ *
+ * 关键约定：
+ * - FR-8.2 G-021 防重入：session.isProcessing 入口加锁，finally 释放
+ * - FR-8.2 G-020 stale 快照：入口 makeStaleChecker snapshot goalId，每个副作用前 checkStale
+ * - FR-6.7 ESC 守卫（最关键）：ctx.signal?.aborted → 不发 continuation、不做 budget 检查、
+ *   不做任何状态变更，goal 保持 active，等用户下次输入恢复
+ *
+ * #8 后流程：budget 预警/steering → continuation 去抖。
+ * agent_end 只做提醒（warning + steering），不做终态转换。
+ * 终态转换不在 agent_end——由 persistAndUpdate 兜底（#5 范围，单一检查点）。
+ *
+ * 全解耦：不再做 allTasksDone followUp（原依赖 pi.__todoGetList，跨 ext 失效）。
+ * todo 是否全完成由 AI 自行判断（prompt 软建议）。
+ *
+ * ESC 路径：aborted 时直接 return（goal 保持 active）。注意 ESC 守卫在终态/非 active
+ * 检查之后——终态 goal 仍走终态 notify（不被 ESC 影响），非 active 状态直接返回。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { checkBudgetOnTurnEnd } from "../../engine/budget";
+import { isActiveStatus, isTerminalStatus } from "../../engine/goal";
+import {
+	budgetLimitPrompt,
+	continuationPrompt,
+} from "../../projection/prompts";
+import { persistAndUpdate, tickState } from "../../service";
+import type { GoalSession } from "../../session";
+import { buildPorts } from "../ports";
+import { makeStaleChecker } from "./shared";
+
+export async function handleAgentEnd(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+): Promise<void> {
+	if (!session.state || session.isProcessing) return;
+	session.isProcessing = true;
+	try {
+		const checkStale = makeStaleChecker(session);
+		if (checkStale()) return;
+
+		// 终态处理（complete / blocked）
+		if (session.state.status === "complete" || session.state.status === "blocked") {
+			await handleTerminalStateAgentEnd(pi, session, ctx, checkStale);
+			return;
+		}
+		if (!isActiveStatus(session.state.status)) return;
+
+		// FR-6.7 ESC 守卫（最关键）：aborted 时 goal 保持 active，不做任何副作用
+		if (ctx.signal?.aborted) {
+			return;
+		}
+
+		// 预算检查（FR-6.2 维度独立）——先 tick 把当前运行段计入 timeUsedSeconds，
+		// 否则时间预算检测会比实际晚一轮（回归修复）
+		tickState(session.state);
+		const budgetResult = checkBudgetOnTurnEnd(session.state, session.state.timeUsedSeconds);
+		const budgetAction = await handleBudgetChecks(pi, session, ctx, budgetResult, checkStale);
+		if (budgetAction !== "continue") return;
+
+		// continuation 去抖（budget 预警未拦截时）
+		await handleContinuation(pi, session, ctx, checkStale);
+	} finally {
+		session.isProcessing = false;
+	}
+}
+
+/** 终态 agent_end：persist + notify（complete/blocked 各一条消息）。 */
+async function handleTerminalStateAgentEnd(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+	checkStale: () => boolean,
+): Promise<void> {
+	const state = session.state!;
+	if (persistAndUpdate(session, buildPorts(pi, ctx), checkStale)) return;
+	if (state.status === "complete") {
+		ctx.ui.notify(`Objective completed ✓ (${state.currentTurnIndex} turns)`, "info");
+	} else {
+		ctx.ui.notify(
+			"Goal blocked. Use /goal resume to continue or /goal clear to reset.",
+			"warning",
+		);
+	}
+}
+
+type BudgetAction = "continue" | "stop";
+
+/**
+ * FR-6.2 维度独立预算检查（#8 后只做提醒，不做终态）：
+ * - 预警（warning70/warning90）：set flag + notify（不阻塞 continuation）
+ * - 90% steering（shouldSendSteering）：set flag + 发 budgetLimitPrompt（收尾），返回 "stop" 中断 continuation
+ *
+ * 终态转换（budget 耗尽）不在 agent_end，由 persistAndUpdate 兜底（#5 范围，单一检查点）。
+ */
+async function handleBudgetChecks(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+	budgetResult: ReturnType<typeof checkBudgetOnTurnEnd>,
+	checkStale: () => boolean,
+): Promise<BudgetAction> {
+	const state = session.state!;
+
+	// 发送预警（FR-6.2 维度独立：token/time 各有 70/90 flag）
+	for (const w of budgetResult.warnings) {
+		if (w.type === "warning90") {
+			if (w.dimension === "token") state.tokenWarning90Sent = true;
+			else state.timeWarning90Sent = true;
+			ctx.ui.notify(
+				`${w.dimension === "token" ? "Token" : "Time"} budget 90% used — start wrapping up.`,
+				"warning",
+			);
+		} else if (w.type === "warning70") {
+			if (w.dimension === "token") state.tokenWarning70Sent = true;
+			else state.timeWarning70Sent = true;
+			ctx.ui.notify(
+				`${w.dimension === "token" ? "Token" : "Time"} budget 70% used — keep scope in check.`,
+				"info",
+			);
+		}
+	}
+
+	// 90% steering → 收尾
+	if (budgetResult.shouldSendSteering) {
+		state.budgetLimitSteeringSent = true;
+		if (persistAndUpdate(session, buildPorts(pi, ctx), checkStale)) return "stop";
+		buildPorts(pi, ctx).messaging.sendContextMessage(
+			budgetLimitPrompt(state, "token", state.timeUsedSeconds),
+			"steer",
+		);
+		return "stop";
+	}
+
+	if (checkStale()) return "stop";
+	return "continue";
+}
+
+/**
+ * continuation 去抖（budget 预警未拦截时的尾部逻辑）。
+ *
+ * - continuation 去抖：tokenDelta=0（空 turn）不发，只 persist
+ * - 否则 persist + 发 continuationPrompt
+ *
+ * 注：maxTurnsReached / stall 自动终态分支随 #6 删除；budget terminal 分支随 #8 删除。
+ * 终态转换由 persistAndUpdate 兑底（#5 范围，单一检查点）。
+ */
+async function handleContinuation(
+	pi: ExtensionAPI,
+	session: GoalSession,
+	ctx: ExtensionContext,
+	checkStale: () => boolean,
+): Promise<void> {
+	const state = session.state!;
+	if (checkStale()) return;
+
+	// FR-8.6: continuation 去抖（空 turn 不发）
+	const tokenDelta = state.tokensUsed - state.lastTurnTokensUsed;
+	state.lastTurnTokensUsed = state.tokensUsed;
+	if (tokenDelta <= 0) {
+		// 空 turn：只 persist，不发 continuation
+		persistAndUpdate(session, buildPorts(pi, ctx));
+		return;
+	}
+	persistAndUpdate(session, buildPorts(pi, ctx));
+	// 终态守卫：persistAndUpdate 可能把 goal 转为 budget_limited/time_limited 终态。
+	// 此时不应发 continuation（deliverAs:"followUp" 会触发新 turn，让已耗尽预算的 agent 再跑一轮）。
+	if (isTerminalStatus(state.status)) return;
+	// 发 continuation（FR-8.7: 去 debounce 后才发）
+	buildPorts(pi, ctx).messaging.sendContextMessage(
+		continuationPrompt(state, state.timeUsedSeconds),
+		"followUp",
+	);
+}

package/src/adapters/event-handlers/agent-start.ts

@@ -0,0 +1,17 @@
+/**
+ * 事件 1: agent_start（adapters/event-handlers 层）。
+ *
+ * 委托 service.applyEvent("agent_start")。task 已移除，当前无副作用
+ * （#7 注入 todo 进度后可能重填基线逻辑）。
+ *
+ * 无 ESC 守卫（agent_start 是 agent 开始时的信号，此时无 aborted 可能）。
+ * 无 persist / updateWidget。
+ */
+
+import { applyEvent } from "../../service";
+import type { GoalSession } from "../../session";
+
+export async function handleAgentStart(session: GoalSession): Promise<void> {
+	if (!session.state) return;
+	applyEvent(session, "agent_start", undefined);
+}