@zhushanwen/pi-goal 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",

package/src/action-handlers.ts

@@ -0,0 +1,341 @@
+/**
+ * goal_manager tool 的 action 处理子函数
+ *
+ * 每个 action 一个 ≤60 行的子函数，由 executeGoalAction 调度。
+ * 解决了 P1-6: executeGoalAction ~260 行超过 80 行限制。
+ *
+ * 行为完全不变 —— 仅做代码组织重构。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { Static } from "typebox";
+
+import { SECONDS_PER_MINUTE } from "./constants";
+import {
+	getCompletedCount,
+	getElapsedTimeSeconds,
+	getIncompleteTasks,
+	type GoalRuntimeState,
+	type GoalTask,
+	isTerminalStatus,
+	isTerminalTaskStatus,
+	type Subtask,
+	transitionStatus,
+} from "./state";
+import { formatTaskList } from "./templates";
+import {
+	clearGoalSession,
+	errorResult,
+	type GoalManagerDetails,
+	GoalManagerParams,
+	type GoalSession,
+	makeGoalResult,
+	persistGoalState,
+	writeGoalHistoryEntry,
+} from "./tool-handler";
+
+/** action 处理器签名：所有处理器返回 ToolResult（成功或 errorResult） */
+type ActionResult = ReturnType<typeof makeGoalResult> | {
+	content: Array<{ type: "text"; text: string }>;
+	details: GoalManagerDetails;
+};
+type ActionContext = {
+	pi: ExtensionAPI;
+	session: GoalSession;
+	state: GoalRuntimeState;
+	params: Static<typeof GoalManagerParams>;
+	ctx: ExtensionContext;
+};
+type ActionHandler = (ctx: ActionContext) => ActionResult;
+
+// ── create_tasks ──────────────────────────────────────
+
+export const handleCreateTasks: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (!params.tasks || params.tasks.length === 0) {
+		return errorResult("create_tasks requires a non-empty tasks array");
+	}
+	const existingIncomplete = getIncompleteTasks(state.tasks);
+	if (state.tasks.length > 0 && existingIncomplete.length > 0) {
+		return errorResult(
+			`Already has ${state.tasks.length} tasks (${existingIncomplete.length} incomplete). Use add_tasks to append, or /goal update to re-plan.`,
+		);
+	}
+	state.tasks = params.tasks.map((desc: string, i: number) => ({
+		id: i + 1,
+		description: normalizeDescription(desc),
+		status: "pending" as const,
+		lastUpdatedTurn: state.currentTurnIndex,
+	}));
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session,
+		`Created ${state.tasks.length} tasks:\n${state.tasks.map((t) => `  #${t.id}: ${t.description}`).join("\n")}`,
+	);
+};
+
+// ── add_tasks ─────────────────────────────────────────
+
+export const handleAddTasks: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (!params.tasks || params.tasks.length === 0) {
+		return errorResult("add_tasks requires a non-empty tasks array");
+	}
+	const startId = state.tasks.length > 0
+		? Math.max(...state.tasks.map((t) => t.id)) + 1
+		: 1;
+	const newTasks: GoalTask[] = params.tasks.map((desc: string, i: number) => ({
+		id: startId + i,
+		description: normalizeDescription(desc),
+		status: "pending" as const,
+		lastUpdatedTurn: state.currentTurnIndex,
+	}));
+	state.tasks.push(...newTasks);
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session,
+		`Appended ${newTasks.length} tasks:\n${newTasks.map((t) => `  #${t.id}: ${t.description}`).join("\n")}`,
+	);
+};
+
+// ── update_tasks ──────────────────────────────────────
+
+export const handleUpdateTasks: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (!params.updates || params.updates.length === 0) {
+		return errorResult("update_tasks requires a non-empty updates array");
+	}
+	const validationErr = validateUpdateTasks(state, params.updates);
+	if (validationErr) return validationErr;
+	const results: string[] = [];
+	for (const u of params.updates) {
+		const task = state.tasks.find((t) => t.id === u.taskId)!;
+		const prev = task.status;
+		task.lastUpdatedTurn = state.currentTurnIndex;
+		if (u.status === "completed") {
+			task.status = "completed";
+			task.evidence = u.evidence;
+			results.push(`#${task.id}: ${prev} → completed (${u.evidence})`);
+		} else {
+			task.status = u.status;
+			results.push(`#${task.id}: ${prev} → ${u.status}`);
+		}
+	}
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session, `Updated ${results.length} tasks:\n${results.join("\n")}`);
+};
+
+/** 验证 update_tasks 的所有更新项；返回首个错误或 null。 */
+function validateUpdateTasks(state: GoalRuntimeState, updates: NonNullable<Static<typeof GoalManagerParams>["updates"]>) {
+	const taskIds = updates.map((u: { taskId: number }) => u.taskId);
+	const duplicateIds = taskIds.filter((id: number, i: number) => taskIds.indexOf(id) !== i);
+	if (duplicateIds.length > 0) {
+		return errorResult(`Duplicate taskIds: ${[...new Set(duplicateIds)].join(", ")}`);
+	}
+	for (const u of updates) {
+		const task = state.tasks.find((t) => t.id === u.taskId);
+		if (!task) return errorResult(`Task #${u.taskId} not found`);
+		if (isTerminalTaskStatus(task.status)) {
+			return errorResult(`Task #${task.id} already in terminal state (${task.status}), cannot be changed`);
+		}
+		if (u.status === "completed" && (!u.evidence || u.evidence.trim() === "")) {
+			return errorResult(`Task #${task.id}: completed requires evidence`);
+		}
+	}
+	return null;
+}
+
+// ── list_tasks ────────────────────────────────────────
+
+export const handleListTasks: ActionHandler = ({ state, session }) => {
+	return makeGoalResult(session, formatTaskList(state.tasks));
+};
+
+// ── complete_goal ─────────────────────────────────────
+
+export const handleCompleteGoal: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (!params.evidence || params.evidence.trim() === "") {
+		return errorResult("complete_goal requires evidence — provide concrete proof that the objective has been achieved");
+	}
+	if (state.tasks.length === 0) {
+		return errorResult("Create a task list with create_tasks before completing the goal.");
+	}
+	const incomplete = getIncompleteTasks(state.tasks);
+	if (incomplete.length > 0) {
+		return errorResult(
+			`${incomplete.length} tasks still incomplete: ${incomplete.map((t) => `#${t.id}`).join(", ")}. Complete them first or explain why they don't need completion.`,
+		);
+	}
+	if (getCompletedCount(state.tasks) === 0) {
+		return errorResult("At least one task must be completed. All-cancelled does not count.");
+	}
+	state.status = transitionStatus(state.status, "complete");
+	state.completedAtTurnIndex = state.currentTurnIndex;
+	writeGoalHistoryEntry(pi, session);
+	persistGoalState(pi, session, ctx);
+	const budgetReport = buildBudgetReport(state);
+	return makeGoalResult(session,
+		`Objective completed!\nEvidence: ${params.evidence}\n\n--- Budget Report ---\n${budgetReport.join("\n")}`,
+	);
+};
+
+function buildBudgetReport(state: GoalRuntimeState): string[] {
+	const lines: string[] = [];
+	lines.push(`Total turns: ${state.currentTurnIndex}`);
+	lines.push(`Tasks completed: ${getCompletedCount(state.tasks)}/${state.tasks.length}`);
+	if (state.budget.tokenBudget) {
+		lines.push(`Token usage: ${state.tokensUsed}/${state.budget.tokenBudget}`);
+	}
+	const elapsed = getElapsedTimeSeconds(state);
+	lines.push(`Duration: ${Math.floor(elapsed / SECONDS_PER_MINUTE)}m${Math.floor(elapsed % SECONDS_PER_MINUTE)}s`);
+	return lines;
+}
+
+// ── report_blocked ────────────────────────────────────
+
+export const handleReportBlocked: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (!params.reason || params.reason.trim() === "") {
+		return errorResult("report_blocked requires reason — describe what is blocking you");
+	}
+	state.lastBlockerReason = params.reason;
+	state.status = transitionStatus(state.status, "blocked");
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session, `Blocked reported. Reason: ${params.reason}`);
+};
+
+// ── cancel_goal ───────────────────────────────────────
+
+export const handleCancelGoal: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (isTerminalStatus(state.status)) {
+		return errorResult(`Goal is already in terminal state (${state.status}).`);
+	}
+	const reason = params.cancelReason ?? "User requested cancellation";
+	const goalId = state.goalId;
+	state.status = "cancelled";
+	state.completedAtTurnIndex = state.currentTurnIndex;
+	writeGoalHistoryEntry(pi, session);
+	persistGoalState(pi, session, ctx);
+	clearGoalSession(session, ctx);
+	const cancelDetails: GoalManagerDetails = {
+		action: "cancel",
+		tasks: [] as GoalTask[],
+		goalId,
+		status: "cancelled",
+		_render: {
+			type: "task-list" as const,
+			summary: "Cancelled",
+			data: { items: [], meta: {} },
+		},
+	};
+	return {
+		content: [{ type: "text" as const, text: `Goal cancelled: ${reason}` }],
+		details: cancelDetails,
+	};
+};
+
+// ── add_subtasks ──────────────────────────────────────
+
+export const handleAddSubtasks: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (params.taskId === undefined) return errorResult("add_subtasks requires taskId");
+	if (!params.texts || params.texts.length === 0) {
+		return errorResult("add_subtasks requires a non-empty texts array");
+	}
+	const parentTask = state.tasks.find((t) => t.id === params.taskId);
+	if (!parentTask) return errorResult(`Task #${params.taskId} not found`);
+	if (isTerminalTaskStatus(parentTask.status)) {
+		return errorResult(`Task #${parentTask.id} already in terminal state (${parentTask.status}), cannot add subtask`);
+	}
+	const subtasks = parentTask.subtasks ?? [];
+	const startId = subtasks.length > 0 ? Math.max(...subtasks.map((s) => s.id)) + 1 : 1;
+	const trimmed = params.texts.map((t: string) => t.trim()).filter((t: string) => t.length > 0);
+	if (trimmed.length === 0) return errorResult("texts requires at least one non-empty string");
+	const newSubtasks: Subtask[] = trimmed.map((text: string, i: number) => ({
+		id: startId + i,
+		text,
+		status: "pending" as const,
+		lastUpdatedTurn: state.currentTurnIndex,
+	}));
+	parentTask.subtasks = [...subtasks, ...newSubtasks];
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session,
+		`Added ${newSubtasks.length} subtasks to Task #${parentTask.id}:\n` +
+		newSubtasks.map((s) => `  - #${parentTask.id}.${s.id}: ${s.text}`).join("\n"),
+	);
+};
+
+// ── update_subtasks ───────────────────────────────────
+
+export const handleUpdateSubtasks: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (params.taskId === undefined) return errorResult("update_subtasks requires taskId");
+	if (!params.subUpdates || params.subUpdates.length === 0) {
+		return errorResult("update_subtasks requires a non-empty subUpdates array");
+	}
+	const targetTask = state.tasks.find((t) => t.id === params.taskId);
+	if (!targetTask) return errorResult(`Task #${params.taskId} not found`);
+	if (!targetTask.subtasks || targetTask.subtasks.length === 0) {
+		return errorResult(`Task #${params.taskId} has no subtasks`);
+	}
+	const results: string[] = [];
+	for (const u of params.subUpdates) {
+		const sub = targetTask.subtasks.find((s) => s.id === u.subId);
+		if (!sub) return errorResult(`Subtask #${params.taskId}.${u.subId} not found`);
+		if (sub.status === "completed") {
+			return errorResult(`Subtask #${params.taskId}.${sub.id} already completed, cannot be changed`);
+		}
+		const prev = sub.status;
+		sub.status = u.status;
+		sub.lastUpdatedTurn = state.currentTurnIndex;
+		results.push(`#${params.taskId}.${sub.id}: ${prev} → ${u.status}`);
+	}
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session, `Updated ${results.length} subtasks:\n${results.join("\n")}`);
+};
+
+// ── delete_subtasks ───────────────────────────────────
+
+export const handleDeleteSubtasks: ActionHandler = ({ state, params, pi, session, ctx }) => {
+	if (params.taskId === undefined) return errorResult("delete_subtasks requires taskId");
+	if (!params.subIds || params.subIds.length === 0) {
+		return errorResult("delete_subtasks requires a non-empty subIds array");
+	}
+	const delTask = state.tasks.find((t) => t.id === params.taskId);
+	if (!delTask) return errorResult(`Task #${params.taskId} not found`);
+	if (!delTask.subtasks || delTask.subtasks.length === 0) {
+		return errorResult(`Task #${params.taskId} has no subtasks`);
+	}
+	const uniqueIds = [...new Set(params.subIds)];
+	const missing = uniqueIds.filter((id) => !delTask.subtasks!.some((s) => s.id === id));
+	if (missing.length > 0) {
+		return errorResult(`Subtask ${missing.map((id) => `#${params.taskId}.${id}`).join(", ")} not found`);
+	}
+	delTask.subtasks = delTask.subtasks.filter((s) => !uniqueIds.includes(s.id));
+	if (delTask.subtasks.length === 0) delTask.subtasks = undefined;
+	persistGoalState(pi, session, ctx);
+	return makeGoalResult(session,
+		`Deleted ${uniqueIds.length} subtasks, Task #${params.taskId} has ${delTask.subtasks?.length ?? 0} remaining`,
+	);
+};
+
+// ── Helpers ───────────────────────────────────────────
+
+/** 将 AI 传入的 task description 标准化：去换行、截断 */
+function normalizeDescription(desc: string): string {
+	const singleLine = desc.replace(/\r?\n/g, " ").replace(/\s+/g, " ").trim();
+	const ELLIPSIS_LENGTH = 3;
+	const MAX_TASK_DESC_LENGTH = 80;
+	if (singleLine.length > MAX_TASK_DESC_LENGTH) {
+		return singleLine.slice(0, MAX_TASK_DESC_LENGTH - ELLIPSIS_LENGTH) + "...";
+	}
+	return singleLine;
+}
+
+// ── Action Dispatch Map ──────────────────────────────
+
+/** action 字符串到处理器的映射。executeGoalAction 使用此表进行分发。 */
+export const ACTION_HANDLERS: Record<string, ActionHandler> = {
+	create_tasks: handleCreateTasks,
+	add_tasks: handleAddTasks,
+	update_tasks: handleUpdateTasks,
+	list_tasks: handleListTasks,
+	complete_goal: handleCompleteGoal,
+	report_blocked: handleReportBlocked,
+	cancel_goal: handleCancelGoal,
+	add_subtasks: handleAddSubtasks,
+	update_subtasks: handleUpdateSubtasks,
+	delete_subtasks: handleDeleteSubtasks,
+};

package/src/agent-end-handler.ts

@@ -0,0 +1,304 @@
+/**
+ * agent_end 事件处理子函数
+ *
+ * handleAgentEnd (orchestrator) 按顺序委托到 5 个 ≤20 行子函数：
+ *   1. handleTerminalStateAgentEnd — 终态处理（complete / blocked）
+ *   2. handleBudgetChecks — 预算预警 + 耗尽 + steering
+ *   3. handleAllTasksDone — 全部任务完成 → 提示 complete_goal
+ *   4. handleNoTasksOrMaxTurns — 无任务创建 / 最大轮次
+ *   5. handleStallAndContinuation — Stall 检测 + Normal continuation
+ *
+ * P0-2 修复：将 197 行的大函数拆分为 ≤20 行子函数。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import type { BudgetCheckResult } from "./budget.js";
+import {
+	checkBudgetOnTurnEnd,
+	checkProgress,
+} from "./budget.js";
+import { PERCENT_FACTOR } from "./constants";
+import {
+	getCompletedCount,
+	getIncompleteTasks,
+	isActiveStatus,
+	transitionStatus,
+} from "./state";
+import {
+	budgetLimitPrompt,
+	continuationPrompt,
+} from "./templates";
+import {
+	type GoalSession,
+	persistGoalState,
+	updateWidget,
+	writeGoalHistoryEntry,
+} from "./tool-handler";
+
+// ── Orchestrator ──────────────────────────────────────
+
+/**
+ * agent_end 事件处理主函数
+ *
+ * 关键约定：
+ * - 防重入：session.isProcessing 标志在入口加锁，finally 释放
+ * - 快照检查：snapshotGoalId 防止旧回调操作新 goal
+ * - 所有副作用（persist / widget / notify / sendUserMessage）都通过 checkStale 守卫
+ */
+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;
+		if (session.state.status === "complete" || session.state.status === "blocked") {
+			await handleTerminalStateAgentEnd(pi, session, ctx, checkStale); return;
+		}
+		if (!isActiveStatus(session.state.status)) return;
+		const budgetAction = await handleBudgetChecks(pi, session, ctx, checkBudgetOnTurnEnd(session.state), checkStale);
+		if (budgetAction !== "continue") return;
+		session.state.turnCount++;
+		const progress = checkProgress(session.state, session.tasksCompletedAtAgentStart);
+		const progressAction = handleProgressAndTasks(pi, session, ctx, progress, checkStale);
+		if (progressAction !== "continue") return;
+		await handleStallAndContinuation(pi, session, ctx, progress, checkStale);
+	} finally {
+		session.isProcessing = false;
+	}
+}
+
+/** 构造 stale-check 闭包：在入口快照 goalId，后续可判断是否被新 goal 覆盖。 */
+function makeStaleChecker(session: GoalSession): () => boolean {
+	const snapshotGoalId = session.state?.goalId;
+	return () => !session.state || session.state.goalId !== snapshotGoalId;
+}
+
+// ── Sub-handler 1: 终态 ─────────────────────────────
+
+async function handleTerminalStateAgentEnd(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	checkStale: () => boolean,
+): Promise<void> {
+	const state = session.state!;
+	persistGoalState(pi, session, ctx);
+	if (checkStale()) return;
+	updateWidget(session, ctx);
+	if (state.status === "complete") {
+		ctx.ui.notify(
+			`Objective completed ✓ (${getCompletedCount(state.tasks)}/${state.tasks.length} tasks, ${state.currentTurnIndex} turns)`,
+			"info",
+		);
+	} else {
+		ctx.ui.notify("Goal blocked. Use /goal resume to continue or /goal clear to reset.", "warning");
+	}
+}
+
+// ── Sub-handler 2: 预算检查 ─────────────────────────
+
+type BudgetAction = "continue" | "stop";
+
+async function handleBudgetChecks(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	budgetResult: BudgetCheckResult, checkStale: () => boolean,
+): Promise<BudgetAction> {
+	// 发送预警
+	for (const w of budgetResult.warnings) {
+		if (w.type === "warning90") {
+			session.state!.budgetWarning90Sent = true;
+			ctx.ui.notify(`${w.dimension === "token" ? "Token" : "Time"} budget 90% used — start wrapping up.`, "warning");
+		} else if (w.type === "warning70") {
+			session.state!.budgetWarning70Sent = true;
+			ctx.ui.notify(`${w.dimension === "token" ? "Token" : "Time"} budget 70% used — keep scope in check.`, "info");
+		}
+	}
+	// 预算耗尽 → 终止
+	if (budgetResult.terminal) {
+		const dim = budgetResult.terminal.dimension;
+		session.state!.status = transitionStatus(session.state!.status, dim === "token" ? "budget_limited" : "time_limited");
+		session.state!.completedAtTurnIndex = session.state!.currentTurnIndex;
+		writeGoalHistoryEntry(pi, session);
+		persistGoalState(pi, session, ctx);
+		if (checkStale()) return "stop";
+		updateWidget(session, ctx);
+		ctx.ui.notify(
+			dim === "token"
+				? "Token budget exhausted, Goal terminated."
+				: `Time budget exhausted (${session.state!.budget.timeBudgetMinutes} min), Goal terminated.`,
+			"warning",
+		);
+		return "stop";
+	}
+	// 90% steering → 收尾
+	if (budgetResult.shouldSendSteering) {
+		session.state!.budgetLimitSteeringSent = true;
+		persistGoalState(pi, session, ctx);
+		if (checkStale()) return "stop";
+		updateWidget(session, ctx);
+		pi.sendUserMessage(budgetLimitPrompt(session.state!, "token"), { deliverAs: "steer" });
+		return "stop";
+	}
+	if (checkStale()) return "stop";
+	return "continue";
+}
+
+// ── Sub-handler 3: 进展 + 任务列表 ───────────────────
+
+type ProgressAction = "continue" | "stop";
+
+function handleProgressAndTasks(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	progress: ReturnType<typeof checkProgress>, checkStale: () => boolean,
+): ProgressAction {
+	// 全部任务完成
+	if (progress.allTasksDone) {
+		return handleAllTasksDone(pi, session, ctx, progress, checkStale);
+	}
+	// 无任务创建
+	if (progress.noTasksCreated) {
+		return handleNoTasksOrMaxTurns(pi, session, ctx, progress, checkStale);
+	}
+	// 最大轮次
+	if (progress.maxTurnsReached) {
+		return handleMaxTurnsReached(pi, session, ctx, checkStale);
+	}
+	return "continue";
+}
+
+function handleAllTasksDone(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	progress: ReturnType<typeof checkProgress>, checkStale: () => boolean,
+): ProgressAction {
+	const state = session.state!;
+	if (progress.maxTurnsReached) {
+		state.status = transitionStatus(state.status, "complete");
+		state.completedAtTurnIndex = state.currentTurnIndex;
+		writeGoalHistoryEntry(pi, session);
+		persistGoalState(pi, session, ctx);
+		if (checkStale()) return "stop";
+		updateWidget(session, ctx);
+		ctx.ui.notify(
+			`All tasks completed, Goal auto-closed. (${progress.completedCount}/${progress.totalCount} tasks, ${state.currentTurnIndex} turns)`,
+			"info",
+		);
+		return "stop";
+	}
+	if (progress.budgetTight) {
+		pi.sendUserMessage(
+			`All tasks completed, token budget ${Math.round(state.tokensUsed / state.budget.tokenBudget! * PERCENT_FACTOR)}% used.` +
+			`Call goal_manager's complete_goal now with overall evidence.` +
+			`\n\nObjective: ${state.objective}`,
+			{ deliverAs: "steer" },
+		);
+	} else {
+		pi.sendUserMessage(
+			`All ${progress.totalCount} tasks completed. Call goal_manager's complete_goal with overall evidence.` +
+				`\n\nObjective: ${state.objective}`,
+			{ deliverAs: "followUp" },
+		);
+	}
+	persistGoalState(pi, session, ctx);
+	updateWidget(session, ctx);
+	return "stop";
+}
+
+function handleNoTasksOrMaxTurns(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	progress: ReturnType<typeof checkProgress>, checkStale: () => boolean,
+): ProgressAction {
+	const state = session.state!;
+	if (progress.maxTurnsReached) {
+		state.status = transitionStatus(state.status, "cancelled");
+		state.completedAtTurnIndex = state.currentTurnIndex;
+		writeGoalHistoryEntry(pi, session);
+		persistGoalState(pi, session, ctx);
+		if (checkStale()) return "stop";
+		updateWidget(session, ctx);
+		ctx.ui.notify(
+			`Max turns reached (${state.budget.maxTurns}), LLM did not create task list.`,
+			"warning",
+		);
+		return "stop";
+	}
+	pi.sendUserMessage(
+		`No task list created yet. Call goal_manager's create_tasks immediately to decompose the work into verifiable task steps.` +
+			`\n\nObjective: ${state.objective}`,
+		{ deliverAs: "followUp" },
+	);
+	persistGoalState(pi, session, ctx);
+	updateWidget(session, ctx);
+	return "stop";
+}
+
+function handleMaxTurnsReached(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	checkStale: () => boolean,
+): ProgressAction {
+	const state = session.state!;
+	const incomplete = getIncompleteTasks(state.tasks);
+	state.status = transitionStatus(state.status, "cancelled");
+	state.completedAtTurnIndex = state.currentTurnIndex;
+	writeGoalHistoryEntry(pi, session);
+	persistGoalState(pi, session, ctx);
+	if (checkStale()) return "stop";
+	updateWidget(session, ctx);
+	ctx.ui.notify(
+		`Max turns reached (${state.budget.maxTurns}), ${incomplete.length} tasks still incomplete.`,
+		"warning",
+	);
+	return "stop";
+}
+
+// ── Sub-handler 4: Stall + Continuation ─────────────
+
+async function handleStallAndContinuation(
+	pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext,
+	progress: ReturnType<typeof checkProgress>, checkStale: () => boolean,
+): Promise<void> {
+	const state = session.state!;
+	if (checkStale()) return;
+
+	// Stall 检测
+	updateStallCounter(state, progress.isStalled);
+	if (state.stallCount >= state.budget.maxStallTurns) {
+		markGoalBlocked(pi, session, ctx, checkStale);
+		return;
+	}
+	if (checkStale()) return;
+
+	// 去抖 + Continuation
+	if (!consumeTokensForDebounce(state)) {
+		persistGoalState(pi, session, ctx);
+		updateWidget(session, ctx);
+		return;
+	}
+	persistGoalState(pi, session, ctx);
+	updateWidget(session, ctx);
+	pi.sendUserMessage(continuationPrompt(state), { deliverAs: "followUp" });
+}
+
+/** 更新 stall 计数。stall 时递增，否则重置。 */
+function updateStallCounter(state: { stallCount: number; lastProgressTurn: number; currentTurnIndex: number }, isStalled: boolean): void {
+	if (isStalled) state.stallCount++;
+	else { state.stallCount = 0; state.lastProgressTurn = state.currentTurnIndex; }
+}
+
+/** Stall 超限 → 标记 blocked。 */
+function markGoalBlocked(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionContext, checkStale: () => boolean): void {
+	const state = session.state!;
+	state.status = transitionStatus(state.status, "blocked");
+	persistGoalState(pi, session, ctx);
+	if (checkStale()) return;
+	updateWidget(session, ctx);
+	ctx.ui.notify(
+		`${state.stallCount} consecutive turns without progress, Goal auto-blocked. Use /goal resume to continue or /goal clear to reset.`,
+		"warning",
+	);
+}
+
+/** 去抖检查：返回 true 表示本 turn 有 token 消耗，可以发送 continuation。 */
+function consumeTokensForDebounce(state: { tokensUsed: number; lastTurnTokensUsed: number }): boolean {
+	const tokenDelta = state.tokensUsed - state.lastTurnTokensUsed;
+	state.lastTurnTokensUsed = state.tokensUsed;
+	return tokenDelta > 0;
+}