pi-plans 0.3.1 → 0.3.2

package/README.md

@@ -119,7 +119,7 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | VCC compact | Active planning/execution compaction uses deterministic, no-LLM VCC-style summaries when Pi core emits manual `/compact`, threshold, or overflow events. Summaries use five bracket sections plus a brief transcript, keep a smart recent tail, support `keep:N`, and write VCC details/stats without adding `/pi-vcc` commands. |
 | Visible Refiner overlay | Delegated reviewer/criticizer subagents surface as a named public overlay in the TUI — one `Reviewer`/`Criticizer` panel with per-lane tool progress, full streaming transcript with follow-bottom scroll, Tab-pane focus, retention until the user presses `Esc` after completion, and clean cancelled/timed-out vs completed states. `reviewers: 3` renders three equal-height panes inside the same overlay |
 | Tracked execution | Checklist injected each turn; `[DONE:VC-xxx]` markers drive completion; implementation items report progress with `[I-xxx:implemented]` / `[I-xxx:validating]` markers; the bottom status bar shows lifecycle, `x/y` progress, elapsed time, and input/output token usage in real time |
-| Goal-wait continuation | While execution is active, a turn that ends with unpassed VCs gets an automatic light follow-up (`🔁 goal-wait` in the status bar) — the worker keeps going, and rounds blocked on an external event poll via the taught `waiting for` backoff instead of stopping. Guard rails: 3 consecutive no-progress rounds, or 6 waiting rounds, pause the continuation (`⏸ goal-wait paused (reason)` in the status bar); any new input or `/plans-execute` re-kicks it, and `/plans-stop` always terminates |
+| Goal-wait continuation | In TUI/RPC, only a fully settled agent with unpassed VCs and no pending input or compaction gets one hidden wake carrying the latest checklist. Tool turns never queue reminders or consume guard rounds. The status bar shows progress; 3 no-progress cycles or 6 waiting cycles pause continuation. User interruption and final model errors also pause it. Only genuine user input or `/plans-execute` resumes; extension messages cannot. Print/JSON single-shot sessions track progress without automatic wakes. `/plans-stop` terminates execution |
 | Execution handoff | The accepted plan resumes in the current session model; no separate model selection is performed. |
 | Execution-phase compaction | Pi core owns scheduling; pi-plans maps the active plan path, current `I-###`, implementation IDs, and remaining `VC-###` checklist into the VCC sections. The old current-I proactive trigger and model-generated summary path are removed. |
 | Planning-phase compaction | During `run.status=planning` with no active execution, pi-plans maps active run, artifact directory, latest plan path from session entries, and observed current-I markers into the VCC sections. Without an active planning run, compaction returns to Pi core. |
@@ -137,7 +137,7 @@ Planning artifacts live under `./docs/pi-plans/YYYY-MM-DD-<topic>/` by default (
 | `execute_plan` | Execution handoff: re-confirms with the user and enters extension-managed execution mode |
 | `/plans` | Show config, active run, and execution progress |
 | `/config-pi-plans` | Re-ask workspace defaults for language, artifact root, refs root, code graph, reviewer mode/model, and criticizer mode/model |
-| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`) |
+| `/plans-execute [plan.md]` | Resume a paused active execution without losing verified progress; otherwise enter the explicit execution handoff (defaults to highest `PLAN_vN.md`) |
 | `/update-plan [plan.md] [reason…]` | Interrupt-and-refine: stops execution (if any), returns the run to planning, and directs the agent to revise the plan into `PLAN_vN+1.md` while preserving verified work |
 | `/plans-autocomplete-stop` | Stop the current run's Auto-complete mode and return later planning questions to normal interaction |
 | `/plans-stop` | Stop execution mode |

package/index.ts

@@ -23,6 +23,7 @@ import {
 	drainExecutionFlush,
 	executionContextMessage,
 	filterExecutionResumeMessages,
+	filterGoalWaitMessages,
 	filterPlanningResumeMessages,
 	getExecution,
 	handleExecutionBeforeCompact,
@@ -39,8 +40,6 @@ import {
 	refreshPlanningCompactionCooldown,
 	requestPlanningCompaction,
 	restoreFromSession,
-	resetGoalWaitTurnFlags,
-	resumeGoalWaitIfPaused,
 	stopExecution,
 	updateStatusWidget,
 	shouldTriggerPlanningCompaction,
@@ -69,7 +68,7 @@ import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
 import { configPiPlansCommand } from "./src/config-command.ts";
 import { getRun, loadConfig, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
 import { registerAskChoiceTool } from "./tools/ask-choice.ts";
-import { executeHandoff, registerExecutePlanTool } from "./tools/execute-plan.ts";
+import { executeCommand, registerExecutePlanTool } from "./tools/execute-plan.ts";
 import { registerPlansTool } from "./tools/plans.ts";
 import { registerRefineTool } from "./tools/refine.ts";
 import { registerAnalyzeRefsTool } from "./tools/analyze-refs.ts";
@@ -215,7 +214,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 
 	pi.on("context", (event) => {
 		const filteredExecution = filterExecutionResumeMessages(event.messages as Array<{ customType?: string }>);
-		const messages = filterPlanningResumeMessages(filteredExecution);
+		const messages = filterGoalWaitMessages(filterPlanningResumeMessages(filteredExecution));
 		if (messages.length !== event.messages.length) {
 			return { messages };
 		}
@@ -238,21 +237,11 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		noteCompactionEnded(ctx, event.customInstructions);
 	});
 
-	// Flush points for deferred execution-loop writes: primary drain when the
-	// agent run fully settles, backstop drain at the next run's start (covers
-	// continuation paths that might not emit agent_settled), plus the forced
-	// synchronous flush inside stop/complete.
-	pi.on("agent_settled", async (_event, ctx) => {
-		drainExecutionFlush(pi, ctx);
-	});
-
 	// -----------------------------------------------------------------------
 	// Execution loop: inject remaining checklist each turn, track markers.
 	// -----------------------------------------------------------------------
 	pi.on("before_agent_start", async (_event, ctx) => {
 		drainExecutionFlush(pi, ctx);
-		resetGoalWaitTurnFlags();
-		resumeGoalWaitIfPaused(pi, ctx);
 		const content = executionContextMessage(ctx);
 		if (!content) {
 			if (!getExecution() && shouldTriggerPlanningCompaction(ctx)) {
@@ -388,7 +377,7 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 		description: "Execute handoff: enter tracked execution mode for an accepted plan",
 		handler: async (args, ctx) => {
 			const planPath = args.trim() || undefined;
-			const outcome = await executeHandoff(ctx, planPath);
+			const outcome = await executeCommand(ctx, planPath);
 			ctx.ui.notify(outcome.message, outcome.status === "error" ? "error" : "info");
 		},
 	});
@@ -543,8 +532,11 @@ export default function piPlansExtension(pi: ExtensionAPI): void {
 	// -----------------------------------------------------------------------
 	// Session lifecycle
 	// -----------------------------------------------------------------------
+	pi.on("session_tree", async (_event, ctx) => {
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
+	});
 	pi.on("session_start", async (_event, ctx) => {
-		await restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreFromSession>[2]);
+		await restoreFromSession(pi, ctx, ctx.sessionManager.getBranch() as unknown as Parameters<typeof restoreFromSession>[2]);
 		restoreAutoCompleteFromSession(ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreAutoCompleteFromSession>[1]);
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-plans",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
   "license": "MIT",
   "type": "module",

package/references/pi-planning-workflow.md

@@ -137,6 +137,27 @@ When the user picks `✓ Accept PLAN_vN and execute it now` in the merged questi
 
 If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
 
+### Execution Goal-Wait
+
+In TUI/RPC, automatic goal-wait is evaluated only at `agent_settled`, after
+Pi has finished natural tool continuation, retries, and compaction. The
+extension rechecks that the same execution is active and incomplete, the
+session is idle, and neither pending input nor compaction owns continuation.
+Each eligible settled cycle can send at most one hidden custom message with
+the current execution rules and remaining VC checklist. Tool `turn_end`
+events only update progress; they never prequeue goal-wait reminders.
+
+No-progress and literal `waiting for` counters advance only on eligible
+settled cycles. Real marker progress resets both; thresholds remain 3 and 6.
+User interruption and final model errors also pause continuation. Genuine
+interactive/RPC user input or `/plans-execute` can resume a paused active
+execution without losing verified VCs; extension input cannot unpause it.
+New-plan handoffs and the `execute_plan` tool still require explicit approval.
+Completion, stop, and session replacement invalidate the extension's wake
+identity without clearing user or other-extension queues. Print/JSON
+single-shot sessions keep VC tracking and completion but never auto-wake;
+use RPC for persistent headless execution.
+
 ### Post-Execution Continuation
 
 When execution completes in an interactive session, the completion message attaches a goal-running continuation block and triggers a new agent turn so the model can enter the implementation-review loop immediately. The interactive-only trigger keeps headless sessions silent (no unconsented subagent cost). The same behavior applies on both completion call sites (the normal `turn_end` completion and the `restoreFromSession` recovery path).

package/src/exec.ts

@@ -8,6 +8,7 @@
  */
 
 import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
 import type {
 	CompactionResult,
 	ExtensionAPI,
@@ -76,6 +77,32 @@ const GOAL_WAIT_MAX_WAITING = 6;
 
 let execution: ExecState | null = null;
 
+export const GOAL_WAIT_CUSTOM_TYPE = "pi-plans-goal-wait";
+
+interface GoalWaitRuntime {
+	owner: ExecState;
+	session: ExtensionContext["sessionManager"];
+	handled: boolean;
+	stopReason?: string;
+	text: string;
+	wakeId?: string;
+}
+
+// Dispatch identity belongs to a live session, never to a persisted checklist.
+let goalWaitRuntime: GoalWaitRuntime | null = null;
+
+function resetGoalWaitRuntime(ctx: ExtensionContext): void {
+	goalWaitRuntime = execution
+		? { owner: execution, session: ctx.sessionManager, handled: false, text: "" }
+		: null;
+}
+
+function currentGoalWaitRuntime(ctx: ExtensionContext): GoalWaitRuntime | null {
+	return goalWaitRuntime?.owner === execution && goalWaitRuntime.session === ctx.sessionManager
+		? goalWaitRuntime
+		: null;
+}
+
 // Execution-loop persistence is deferred until the agent settles so turn_end
 // never causes session writes during a streaming run.
 let pendingExecutionFlush = false;
@@ -286,6 +313,7 @@ export async function startExecution(
 	// Seed the marker baseline so the first quiet round is counted against a
 	// real snapshot instead of counting unconditionally (F-006).
 	if (execution.goalWait) execution.goalWait.lastMarkers = goalWaitSnapshot();
+	resetGoalWaitRuntime(ctx);
 	pendingExecutionFlush = false; // fresh run: no inherited flush debt
 	resetExecutionCompactionState(ctx);
 	persist(pi);
@@ -331,6 +359,30 @@ export function registerExecutionTurnHandlers(
 	// The turn_end projection does not carry usage; message_end delivers the
 	// full assistant message, so cache it here and consume it per turn.
 	let lastAssistantUsage: { input: number; output: number } | null = null;
+	pi.on("agent_start", async (_event, ctx) => {
+		const runtime = currentGoalWaitRuntime(ctx);
+		if (!runtime) return;
+		runtime.handled = false;
+		runtime.stopReason = undefined;
+		runtime.text = "";
+	});
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const runtime = currentGoalWaitRuntime(ctx);
+		if (runtime) runtime.wakeId = undefined;
+	});
+	pi.on("input", async (event, ctx) => {
+		if (event.source === "interactive" || event.source === "rpc") resumeGoalWaitIfPaused(pi, ctx);
+	});
+	pi.on("agent_settled", async (_event, ctx) => {
+		drainExecutionFlush(pi, ctx);
+		maybeGoalWaitFollowUp(pi, ctx);
+	});
+	pi.on("session_shutdown", async (_event, ctx) => {
+		drainExecutionFlush(pi, ctx);
+		execution = null;
+		goalWaitRuntime = null;
+		lastAssistantUsage = null;
+	});
 	pi.on("message_end", async (event) => {
 		const message = event.message as { role?: string; usage?: { input?: number; output?: number } };
 		if (message?.role === "assistant" && message.usage) {
@@ -339,7 +391,7 @@ export function registerExecutionTurnHandlers(
 	});
 
 	pi.on("turn_end", async (event, ctx) => {
-		const message = event.message as { role?: string; content?: Array<{ type: string; text?: string }> };
+		const message = event.message as { role?: string; stopReason?: string; content?: Array<{ type: string; text?: string }> };
 		if (!message || message.role !== "assistant") {
 			updateStatusWidget(ctx);
 			return;
@@ -348,6 +400,11 @@ export function registerExecutionTurnHandlers(
 			.filter((part) => part.type === "text")
 			.map((part) => part.text ?? "")
 			.join("\n");
+		const runtime = currentGoalWaitRuntime(ctx);
+		if (runtime) {
+			runtime.stopReason = message.stopReason;
+			runtime.text = text;
+		}
 		const changedIds = applyDoneMarkers(text);
 		const changedImpls = applyImplMarkers(text);
 		const changedCurrentI = applyCurrentIMarker(text);
@@ -361,8 +418,6 @@ export function registerExecutionTurnHandlers(
 		}
 		if (getExecution() && isExecutionComplete()) {
 			await completeExecution(pi, ctx);
-		} else if (getExecution()) {
-			maybeGoalWaitFollowUp(pi, ctx, text);
 		}
 		await onTurnEnd?.(ctx);
 	});
@@ -492,7 +547,6 @@ export async function handleExecutionCompact(pi: ExtensionAPI, ctx: ExtensionCon
 	if (!event.willRetry && stats) {
 		ctx.ui.notify(formatVccCompactionStats(stats), "info");
 		if (followUpPrompt) {
-			compactionFollowUpSentThisTurn = true;
 			await pi.sendUserMessage?.(followUpPrompt);
 		} else if ((event.reason === "threshold" || event.reason === "overflow") && shouldScheduleAutoContinue(continueAfterThresholdCompact, runtimePiVersion(ctx))) {
 			state.resumeGuard = true;
@@ -843,6 +897,7 @@ export async function stopExecution(pi: ExtensionAPI, ctx: ExtensionContext, rea
 	pendingExecutionFlush = false;
 	persist(pi);
 	execution = null;
+	goalWaitRuntime = null;
 	pi.appendEntry("pi-plans-exec-cleared", { reason });
 	pi.sendMessage(
 		{
@@ -909,13 +964,6 @@ export function isExecutionComplete(): boolean {
 	return execution !== null && execution.items.length > 0 && execution.items.every((item) => item.done);
 }
 
-let compactionFollowUpSentThisTurn = false;
-
-/** Reset per-turn continuation flags at the start of a new agent turn. */
-export function resetGoalWaitTurnFlags(): void {
-	compactionFollowUpSentThisTurn = false;
-}
-
 function goalWaitSnapshot(): string {
 	if (!execution) return "";
 	return JSON.stringify({
@@ -942,46 +990,67 @@ function pauseGoalWait(pi: ExtensionAPI, ctx: ExtensionContext, reason: string):
 	updateStatusWidget(ctx);
 }
 
-/**
- * Goal-wait continuation: a turn that ends with unpassed VCs gets one light
- * followUp so the worker keeps going (working, or polling an external event
- * per the taught backoff rules). Skipped when the compaction machinery owns
- * continuation for this turn, and paused entirely by the no-progress guard.
- * Note: the tri-flag check here deliberately runs BEFORE index.ts's
- * handleExecutionTurnCompaction consumes resumeGuard — checking after the
- * one-shot consumption would never observe it.
- */
-function maybeGoalWaitFollowUp(pi: ExtensionAPI, ctx: ExtensionContext, assistantText: string): void {
-	const ex = getExecution();
-	if (!ex) return;
-	ex.goalWait ??= { noProgressRounds: 0, waitRounds: 0, lastMarkers: null, paused: false };
-	const goalWait = ex.goalWait;
-	if (goalWait.paused) {
-		updateStatusWidget(ctx);
-		return;
-	}
+function canWakeExecution(ctx: ExtensionContext, runtime: GoalWaitRuntime): boolean {
 	const compaction = executionCompactionState(ctx);
-	if (compaction && (compaction.inFlight || compaction.pendingFollowUpPrompt != null || compaction.resumeGuard)) {
-		updateStatusWidget(ctx);
-		return;
+	return currentGoalWaitRuntime(ctx) === runtime
+		&& (ctx.mode === "tui" || ctx.mode === "rpc")
+		&& !isExecutionComplete()
+		&& !runtime.owner.goalWait?.paused
+		&& ctx.isIdle()
+		&& !ctx.hasPendingMessages()
+		&& !ctx.signal?.aborted
+		&& !compactionInFlight(ctx, "execution")
+		&& !compaction?.inFlight
+		&& !compaction?.resumeGuard
+		&& compaction?.pendingFollowUpPrompt == null;
+}
+
+function sendGoalWaitWake(pi: ExtensionAPI, ctx: ExtensionContext, runtime: GoalWaitRuntime): boolean {
+	if (!canWakeExecution(ctx, runtime)) return false;
+	try {
+		// Custom messages bypass before_agent_start, so carry fresh execution rules.
+		const content = executionContextMessage(ctx);
+		if (!content) return false;
+		runtime.wakeId = randomUUID();
+		pi.sendMessage({
+			customType: GOAL_WAIT_CUSTOM_TYPE,
+			content,
+			display: false,
+			details: { wakeId: runtime.wakeId },
+		}, { triggerTurn: true });
+		return true;
+	} catch (error) {
+		runtime.wakeId = undefined;
+		pauseGoalWait(pi, ctx, `continuation failed: ${String(error)}`);
+		return false;
 	}
-	if (compactionFollowUpSentThisTurn) {
-		compactionFollowUpSentThisTurn = false; // the compaction path already queued a continuation
-		updateStatusWidget(ctx);
+}
+
+/** Only a fully settled agent run can need an extra wake, never a tool turn. */
+function maybeGoalWaitFollowUp(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	const runtime = currentGoalWaitRuntime(ctx);
+	if (!runtime || runtime.handled || !ctx.isIdle()) return;
+	if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
+	if (runtime.stopReason === "error" || runtime.stopReason === "aborted" || ctx.signal?.aborted) {
+		runtime.handled = true;
+		pauseGoalWait(pi, ctx, runtime.stopReason === "error" ? "agent failed" : "agent interrupted");
 		return;
 	}
+	if (runtime.stopReason !== "stop" || !canWakeExecution(ctx, runtime)) return;
+	runtime.handled = true;
+	const ex = runtime.owner;
+	ex.goalWait ??= { noProgressRounds: 0, waitRounds: 0, lastMarkers: null, paused: false };
+	const goalWait = ex.goalWait;
 	const snapshot = goalWaitSnapshot();
 	const changed = goalWait.lastMarkers !== null && snapshot !== goalWait.lastMarkers;
 	goalWait.lastMarkers = snapshot;
-	if (!changed) {
-		if (/waiting for/i.test(assistantText)) {
-			goalWait.waitRounds += 1;
-		} else {
-			goalWait.noProgressRounds += 1;
-		}
-	} else {
+	if (changed) {
 		goalWait.noProgressRounds = 0;
 		goalWait.waitRounds = 0;
+	} else if (/waiting for/i.test(runtime.text)) {
+		goalWait.waitRounds += 1;
+	} else {
+		goalWait.noProgressRounds += 1;
 	}
 	if (goalWait.noProgressRounds >= GOAL_WAIT_MAX_NO_PROGRESS) {
 		pauseGoalWait(pi, ctx, `no progress in ${goalWait.noProgressRounds} rounds`);
@@ -991,25 +1060,40 @@ function maybeGoalWaitFollowUp(pi: ExtensionAPI, ctx: ExtensionContext, assistan
 		pauseGoalWait(pi, ctx, `waiting without progress for ${goalWait.waitRounds} rounds`);
 		return;
 	}
-	const remaining = ex.items.filter((item) => !item.done);
-	const remainingIds = remaining.map((item) => `\`${item.id}\``).join(", ");
-	pi.sendUserMessage?.(
-		`Goal wait: ${remaining.length}/${ex.items.length} verifier items still open (${remainingIds}). Continue the plan — if blocked on an external event, keep waiting per the backoff rules; otherwise resolve the remaining items.`,
-		{ deliverAs: "followUp" },
-	);
+	persist(pi);
 	updateStatusWidget(ctx);
+	// No await between the live gate and dispatch: another input cannot interleave.
+	sendGoalWaitWake(pi, ctx, runtime);
+}
+
+export function filterGoalWaitMessages<T extends { customType?: string; details?: unknown }>(messages: T[]): T[] {
+	return messages.filter((message) => message.customType !== GOAL_WAIT_CUSTOM_TYPE
+		|| (goalWaitRuntime?.owner === execution && goalWaitRuntime?.wakeId !== undefined
+			&& (message.details as { wakeId?: unknown } | undefined)?.wakeId === goalWaitRuntime.wakeId));
 }
 
-/** Any external input re-kicks a paused goal-wait (clears pause and counters). */
-export function resumeGoalWaitIfPaused(pi: ExtensionAPI, ctx: ExtensionContext): void {
+/** Called only for genuine user input or an explicit same-execution resume. */
+export function resumeGoalWaitIfPaused(pi: ExtensionAPI, ctx: ExtensionContext): boolean {
 	const ex = getExecution();
-	if (!ex?.goalWait?.paused) return;
+	if (!ex?.goalWait?.paused || !currentGoalWaitRuntime(ctx)) return false;
 	ex.goalWait.paused = false;
 	ex.goalWait.pausedReason = undefined;
 	ex.goalWait.noProgressRounds = 0;
 	ex.goalWait.waitRounds = 0;
+	ex.goalWait.lastMarkers = goalWaitSnapshot();
 	persist(pi);
 	updateStatusWidget(ctx);
+	return true;
+}
+
+export function resumeActiveExecution(pi: ExtensionAPI, ctx: ExtensionContext): boolean {
+	if (!resumeGoalWaitIfPaused(pi, ctx)) return false;
+	const runtime = currentGoalWaitRuntime(ctx)!;
+	if (canWakeExecution(ctx, runtime)) {
+		runtime.handled = true;
+		sendGoalWaitWake(pi, ctx, runtime);
+	}
+	return true;
 }
 
 export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
@@ -1022,6 +1106,7 @@ export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext)
 	const summary = execution.items.map((item) => `- ✅ \`${item.id}\` ${item.text.split(";")[0]}`).join("\n");
 	const planPath = execution.planPath;
 	execution = null;
+	goalWaitRuntime = null;
 	pi.appendEntry("pi-plans-exec-cleared", { reason: "complete" });
 	// Post-execution goal-running continuation: in interactive sessions, attach
 	// the continuation block and trigger a new turn so the agent immediately
@@ -1111,6 +1196,7 @@ interface SessionEntry {
  */
 export async function restoreFromSession(pi: ExtensionAPI, ctx: ExtensionContext, entries: SessionEntry[]): Promise<void> {
 	pendingExecutionFlush = false; // no flush debt survives a restart
+	goalWaitRuntime = null;
 	resetExecutionCompactionState(ctx);
 	let snapshotIndex = -1;
 	let snapshot: ExecState | null = null;
@@ -1169,6 +1255,7 @@ export async function restoreFromSession(pi: ExtensionAPI, ctx: ExtensionContext
 		}
 	}
 	if (execution) {
+		resetGoalWaitRuntime(ctx);
 		// D-010: replay may have advanced progress past the persisted baseline.
 		// Recompute the goal-wait markers; new progress resets the guard counters.
 		if (execution.goalWait) {

package/tests/exec-lifecycle.test.ts

@@ -0,0 +1,137 @@
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, describe, it } from "node:test";
+import { InMemoryCredentialStore, createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { createAgentSession, DefaultResourceLoader, initTheme, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import piPlansExtension from "../index.ts";
+import { GOAL_WAIT_CUSTOM_TYPE, getExecution, startExecution } from "../src/exec.ts";
+
+initTheme("dark", false);
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-lifecycle-"));
+after(() => fs.rmSync(root, { recursive: true, force: true }));
+let serial = 0;
+
+async function exercise(mode: "tui" | "rpc" | "print" | "json", needsWake: boolean, commandResume = false) {
+	const cwd = path.join(root, String(++serial));
+	fs.mkdirSync(cwd);
+	const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
+	const modelRuntime = await ModelRuntime.create({
+		credentials: new InMemoryCredentialStore(), modelsPath: null,
+		modelsStorePath: path.join(cwd, "models-store.json"), allowModelNetwork: false, refreshOnCreate: false,
+	});
+	const inputs: any[] = [];
+	let toolCalls = 0;
+	modelRuntime.registerProvider("local-lifecycle-test", {
+		baseUrl: "http://unused.invalid", api: "openai-completions", apiKey: "not-a-real-key",
+		models: [{ id: "fixture", name: "fixture", reasoning: false, input: ["text"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 100000, maxTokens: 1024 }],
+		streamSimple: (model: any, context: any) => {
+			inputs.push(structuredClone({ messages: context.messages, systemPrompt: context.systemPrompt }));
+			const call = inputs.length;
+			assert.ok(call <= 5, "unexpected extra model invocation");
+			const tool = call <= 2;
+			const text = call === 3
+				? needsWake ? "[DONE:VC-001] More verification remains." : "[DONE:VC-001] [DONE:VC-002]"
+				: call === 4 && needsWake ? "[DONE:VC-002]" : "Review awaits explicit user approval.";
+			const message: any = {
+				role: "assistant", api: model.api, provider: model.provider, model: model.id,
+				content: tool ? [
+					...(commandResume && call === 2 ? [{ type: "text", text: "[DONE:VC-001]" }] : []),
+					{ type: "toolCall", id: `call-${call}`, name: "probe", arguments: {} },
+				] : [{ type: "text", text: commandResume && call === 3 ? "Interrupted." : text }],
+				stopReason: tool ? "toolUse" : commandResume && call === 3 ? "aborted" : "stop", timestamp: Date.now(),
+				usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, totalTokens: 15,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+			};
+			const stream = createAssistantMessageEventStream();
+			stream.push({ type: "start", partial: message });
+			if (message.stopReason === "aborted") stream.push({ type: "error", reason: "aborted", error: message });
+			else stream.push({ type: "done", reason: message.stopReason, message });
+			stream.end(message);
+			return stream;
+		},
+	});
+	let beforeAgentStarts = 0;
+	const events: string[] = [];
+	const errors: string[] = [];
+	const loader = new DefaultResourceLoader({
+		cwd, agentDir: path.join(cwd, "agent"), settingsManager,
+		noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true,
+		agentsFilesOverride: () => ({ agentsFiles: [] }), systemPromptOverride: () => "Deterministic test.",
+		extensionFactories: [piPlansExtension, pi => {
+			pi.on("before_agent_start", () => { beforeAgentStarts++; });
+			pi.on("session_start", async (_event, ctx) => {
+				await startExecution(pi, ctx, path.join(cwd, "PLAN_v1.md"), [
+					{ id: "VC-001", text: "first", done: false }, { id: "VC-002", text: "second", done: false },
+				]);
+			});
+		}],
+	});
+	await loader.reload();
+	assert.deepEqual(loader.getExtensions().errors, []);
+	const { session } = await createAgentSession({
+		cwd, agentDir: path.join(cwd, "agent"), modelRuntime,
+		model: modelRuntime.getModel("local-lifecycle-test", "fixture")!, thinkingLevel: "off",
+		resourceLoader: loader, settingsManager, sessionManager: SessionManager.inMemory(cwd), tools: ["probe"],
+		customTools: [{ name: "probe", label: "Probe", description: "Local test probe", parameters: Type.Object({}),
+			execute: async () => { toolCalls++; return { content: [{ type: "text", text: "ok" }], details: {} }; } }],
+	});
+	const unsubscribe = session.subscribe(event => events.push(event.type));
+	try {
+		await session.bindExtensions({
+			mode,
+			...(mode === "tui" || mode === "rpc" ? { uiContext: {
+				setStatus: () => {}, notify: () => {}, theme: { fg: (_c: string, s: string) => s },
+			} as any } : {}),
+			onError: error => errors.push(error.error),
+		});
+		await session.prompt("Implement the test plan.");
+		await session.waitForIdle();
+		if (commandResume) {
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			assert.deepEqual(getExecution()?.items.map(item => item.done), [true, false]);
+			assert.equal(inputs.length, 3);
+			await session.prompt("/plans-execute");
+		}
+		// SDK callers, unlike print mode, own the runtime until all nested wakes settle.
+		await session.waitForIdle();
+		assert.deepEqual(errors, []);
+		assert.deepEqual(session.messages.filter((m: any) => m.role === "assistant" && m.stopReason === "error"), [], "fixture model must run successfully");
+		const wakes = session.messages.filter((m: any) => m.customType === GOAL_WAIT_CUSTOM_TYPE) as any[];
+		assert.equal(toolCalls, 2);
+		assert.equal(beforeAgentStarts, 1, "custom wake must work without before_agent_start");
+		const interactive = mode === "tui" || mode === "rpc";
+		assert.equal(wakes.length, interactive && needsWake ? 1 : 0);
+		assert.equal(inputs.length, interactive ? needsWake ? 5 : 4 : 3);
+		if (interactive && needsWake) {
+			assert.equal(wakes[0].display, false);
+			assert.match(JSON.stringify(inputs[3].messages), /1\/2 verifier items done/);
+			assert.match(wakes[0].content, /- `VC-002` second/);
+			assert.doesNotMatch(wakes[0].content, /- `VC-001` first/);
+		}
+		if (interactive || !needsWake) assert.equal(getExecution(), null);
+		else assert.deepEqual(getExecution()?.items.map(item => item.done), [true, false]);
+		assert.equal(session.pendingMessageCount, 0);
+		assert.equal(events.at(-1), "agent_settled");
+		return { events, calls: inputs.length, wakes: wakes.length };
+	} finally {
+		unsubscribe();
+		session.dispose();
+	}
+}
+
+describe("goal-wait on the real Pi host", () => {
+	it("dispatches the registered /plans-execute command and preserves completed VCs", { timeout: 15000 }, async () => {
+		await exercise("rpc", true, true);
+	});
+	for (const mode of ["tui", "rpc", "print", "json"] as const) {
+		for (const needsWake of [false, true]) {
+			it(`${mode}: tools then ${needsWake ? "incomplete stop" : "completion"}`, { timeout: 15000 }, async () => {
+				await exercise(mode, needsWake);
+			});
+		}
+	}
+});

package/tests/exec.test.ts

@@ -20,7 +20,6 @@ import {
 	filterExecutionResumeMessages,
 	filterPlanningResumeMessages,
 	getExecution,
-	resumeGoalWaitIfPaused,
 	handleExecutionBeforeCompact,
 	handleExecutionCompact,
 	handleExecutionTurnCompaction,
@@ -37,7 +36,6 @@ import {
 	refreshPlanningCompactionCooldown,
 	requestPlanningCompaction,
 	restoreFromSession,
-	resetGoalWaitTurnFlags,
 	shouldTriggerPlanningCompaction,
 	startExecution,
 	recordExecutionTurn,
@@ -1459,134 +1457,6 @@ function makePreparation(reason: "manual" | "threshold" | "overflow", previousSu
 	};
 }
 
-describe("execution goal-wait continuation", () => {
-	// Fresh per-turn continuation flags, mirroring the before_agent_start reset.
-	const setup = (workdir: string) => {
-		resetGoalWaitTurnFlags();
-		const harness = makeHarness(workdir);
-		registerExecutionTurnHandlers(harness.pi);
-		return harness;
-	};
-
-	it("sends a goal-wait followUp when a turn ends with unpassed VCs", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx, recorded, emit } = setup(workdir);
-		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-		recorded.userMessages.length = 0;
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "still working" }] } });
-		assert.equal(recorded.userMessages.length, 1);
-		assert.match(recorded.userMessages[0], /Goal wait: 1\/1 verifier items still open/);
-		assert.match(recorded.userMessages[0], /\`VC-001\`/);
-		assert.equal(recorded.userMessageOptions.at(-1)?.deliverAs, "followUp");
-		assert.match(recorded.status ?? "", /goal-wait · 无进展 1\/3 · 等待 0\/6/);
-	});
-
-	it("sends the goal-wait followUp in headless sessions too", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx, recorded, emit } = setup(workdir);
-		(ctx as any).hasUI = false;
-		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-		recorded.userMessages.length = 0;
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "still working" }] } });
-		assert.equal(recorded.userMessages.length, 1);
-		assert.match(recorded.userMessages[0], /Goal wait: 1\/1 verifier items still open/);
-	});
-
-	it("does not goal-wait when every VC is done (completion path)", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx, recorded, emit } = setup(workdir);
-		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-		recorded.userMessages.length = 0;
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "done [DONE:VC-001]" }] } });
-		assert.equal(recorded.userMessages.length, 0);
-		assert.ok(recorded.messages.some((message) => message.customType === "pi-plans-complete"));
-	});
-
-	it("skips goal-wait while any compaction continuation flag is active", async () => {
-		const variants = [
-			{ inFlight: true, resumeGuard: false, pendingFollowUpPrompt: null },
-			{ inFlight: false, resumeGuard: true, pendingFollowUpPrompt: null },
-			{ inFlight: false, resumeGuard: false, pendingFollowUpPrompt: "compaction follow-up" },
-		];
-		for (const flags of variants) {
-			const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-			const { pi, ctx, recorded, emit } = setup(workdir);
-			await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-			(ctx.sessionManager as any).__executionCompaction = { ...flags, cooldownActive: false };
-			recorded.userMessages.length = 0;
-			await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "working" }] } });
-			assert.equal(recorded.userMessages.length, 0, `flags ${JSON.stringify(flags)} must skip goal-wait`);
-		}
-	});
-
-	it("pauses after 3 no-progress rounds and resumes on kick", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx, recorded, emit } = setup(workdir);
-		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-		recorded.userMessages.length = 0;
-		for (let round = 0; round < 3; round++) {
-			await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "still working" }] } });
-		}
-		assert.equal(getExecution()?.goalWait?.paused, true);
-		assert.equal(recorded.userMessages.length, 2, "third quiet round must not queue another followUp");
-		assert.ok(recorded.notifies.some((entry) => /goal-wait paused/.test(entry.message)));
-		assert.match(recorded.status ?? "", /⏸ goal-wait paused/);
-
-		resumeGoalWaitIfPaused(pi, ctx);
-		assert.equal(getExecution()?.goalWait?.paused, false);
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "progress [DONE:VC-001]" }] } });
-		assert.match(recorded.userMessages.at(-1) ?? "", /Goal wait/);
-	});
-
-	it("waiting rounds are exempt until the sixth quiet waiting round", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx, recorded, emit } = setup(workdir);
-		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-		for (let round = 1; round <= 5; round++) {
-			await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: `waiting for CI (${round})` }] } });
-			assert.equal(getExecution()?.goalWait?.paused, false, `round ${round} must not pause`);
-		}
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "waiting for CI (6)" }] } });
-		assert.equal(getExecution()?.goalWait?.paused, true);
-		assert.ok(recorded.notifies.some((entry) => /waiting without progress for 6 rounds/.test(entry.message)));
-	});
-
-	it("progress resets both guard counters", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx, emit } = makeHarness(workdir);
-		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001", "VC-002"));
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "working" }] } });
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "working" }] } });
-		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "progress [DONE:VC-001]" }] } });
-		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
-		assert.equal(getExecution()?.goalWait?.waitRounds, 0);
-	});
-
-	it("keeps goal-wait counters across restore", async () => {
-		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
-		const { pi, ctx } = setup(workdir);
-		const planPath = path.join(workdir, "PLAN_v1.md");
-		fs.writeFileSync(planPath, "# plan");
-		const snapshot = {
-			planPath,
-			items: items("VC-001"),
-			startedAt: "2026-08-25T00:00:00Z",
-			usage: { inToks: 0, outToks: 0 },
-			implItems: [],
-			implStatus: {},
-			goalWait: { noProgressRounds: 2, waitRounds: 1, lastMarkers: null, paused: false },
-		};
-		const entries = [
-			{ type: "custom", customType: "pi-plans-exec", data: snapshot },
-			{ type: "message", message: { role: "assistant", content: [{ type: "text", text: "no new progress this turn" }] } },
-		];
-		await restoreFromSession(pi, ctx, entries as any);
-		// Replay advanced the marker snapshot past the persisted baseline → counters reset (D-010).
-		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
-		assert.equal(getExecution()?.goalWait?.waitRounds, 0);
-	});
-});
-
 describe("amelioration termination prompt", () => {
 	it("recommends goal-wait first and keeps the round options", () => {
 		assert.match(AMELIORATION_PROMPT_TEXT, /goal wait: continue until no unpassed VCs remain/);

package/tests/goal-wait.test.ts

@@ -0,0 +1,269 @@
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, describe, it } from "node:test";
+import {
+	GOAL_WAIT_CUSTOM_TYPE, filterGoalWaitMessages, getExecution, noteCompactionStarted,
+	registerExecutionTurnHandlers, restoreFromSession, startExecution, stopExecution,
+} from "../src/exec.ts";
+import { executeCommand, executeHandoff, setCurrentApi } from "../tools/execute-plan.ts";
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+after(() => fs.rmSync(root, { recursive: true, force: true }));
+let serial = 0;
+
+async function setup(mode = "tui") {
+	const cwd = path.join(root, String(++serial));
+	fs.mkdirSync(cwd);
+	const planPath = path.join(cwd, "PLAN_v1.md");
+	fs.writeFileSync(planPath, "## Verifier Checklist\n- [ ] `VC-001` first\n- [ ] `VC-002` second\n");
+	const handlers = new Map<string, Array<(event: any, ctx: any) => any>>();
+	const messages: any[] = [];
+	const entries: any[] = [];
+	const notices: string[] = [];
+	const pending: unknown[] = [];
+	let idle = true;
+	let status = "";
+	const ctx: any = {
+		cwd, mode, hasUI: mode === "tui" || mode === "rpc", sessionManager: {},
+		isIdle: () => idle, hasPendingMessages: () => pending.length > 0,
+		ui: { setStatus: (_key: string, s: string) => { status = s; },
+			notify: (s: string) => notices.push(s), theme: { fg: (_c: string, s: string) => s },
+			confirm: async () => { throw new Error("same-plan resume must not re-enter handoff"); } },
+	};
+	const pi: any = {
+		on: (name: string, handler: any) => handlers.set(name, [...(handlers.get(name) ?? []), handler]),
+		appendEntry: (customType: string, data: unknown) => entries.push({ type: "custom", customType, data: structuredClone(data) }),
+		sendUserMessage: () => { throw new Error("goal-wait must not impersonate a user"); },
+		sendMessage: (message: any, options: any) => {
+			messages.push({ ...message, options });
+			if (message.customType === GOAL_WAIT_CUSTOM_TYPE && options?.triggerTurn) idle = false;
+		},
+	};
+	registerExecutionTurnHandlers(pi);
+	setCurrentApi(pi);
+	await startExecution(pi, ctx, planPath, [
+		{ id: "VC-001", text: "first", done: false }, { id: "VC-002", text: "second", done: false },
+	]);
+	const emit = async (name: string, event = {}) => {
+		for (const handler of handlers.get(name) ?? []) await handler(event, ctx);
+	};
+	const begin = async () => { idle = false; await emit("agent_start"); };
+	const turn = async (text = "working", stopReason = "stop") => emit("turn_end", {
+		message: { role: "assistant", stopReason, content: [{ type: "text", text },
+			...(stopReason === "toolUse" ? [{ type: "toolCall", id: "call", name: "read", arguments: {} }] : [])],
+			usage: { input: 10, output: 5 } }, toolResults: [],
+	});
+	const settle = async () => { idle = true; await emit("agent_settled"); };
+	const run = async (text = "working", stopReason = "stop") => { await begin(); await turn(text, stopReason); await settle(); };
+	return { pi, ctx, planPath, messages, entries, notices, pending, emit, begin, turn, settle, run,
+		wakes: () => messages.filter(m => m.customType === GOAL_WAIT_CUSTOM_TYPE),
+		status: () => status, setIdle: (value: boolean) => { idle = value; } };
+}
+
+describe("goal-wait settled lifecycle", () => {
+	it("never queues on ten tool turns and never wakes after completion", async () => {
+		const h = await setup();
+		await h.begin();
+		for (let i = 0; i < 10; i++) await h.turn("working", "toolUse");
+		assert.equal(h.wakes().length, 0);
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		await h.turn("[DONE:VC-001] [DONE:VC-002]");
+		await h.settle();
+		await h.settle();
+		assert.equal(getExecution(), null);
+		assert.equal(h.wakes().length, 0);
+		assert.equal(h.messages.filter(m => m.customType === "pi-plans-complete").length, 1);
+	});
+
+	for (const mode of ["tui", "rpc"]) {
+		it(`${mode}: sends one hidden fresh wake and deduplicates settled`, async () => {
+			const h = await setup(mode);
+			await h.run("[DONE:VC-001]");
+			await h.settle();
+			const [wake] = h.wakes();
+			assert.equal(h.wakes().length, 1);
+			assert.equal(wake.display, false);
+			assert.equal(wake.options.triggerTurn, true);
+			assert.match(wake.content, /1\/2 verifier items done/);
+			assert.match(wake.content, /- `VC-002` second/);
+			assert.doesNotMatch(wake.content, /- `VC-001` first/);
+			assert.deepEqual(filterGoalWaitMessages([wake]), [wake]);
+			assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		});
+	}
+
+	for (const mode of ["print", "json"]) {
+		it(`${mode}: tracks markers without any automatic wake`, async () => {
+			const h = await setup(mode);
+			await h.run("[DONE:VC-001]");
+			assert.equal(getExecution()?.items[0].done, true);
+			await h.run("failed", "error");
+			await h.run("[DONE:VC-002]");
+			assert.equal(h.wakes().length, 0);
+			assert.equal(getExecution(), null);
+			assert.equal(h.messages.find(m => m.customType === "pi-plans-complete").options.triggerTurn, false);
+		});
+	}
+
+	for (const gate of ["busy", "pending", "inFlight", "resumeGuard", "pendingFollowUpPrompt", "lifecycle"]) {
+		it(`does not send or count when ${gate} owns continuation`, async () => {
+			const h = await setup();
+			await h.begin();
+			await h.turn();
+			h.setIdle(gate !== "busy");
+			if (gate === "pending") h.pending.push("user message", { customType: "another-extension" });
+			else if (gate === "lifecycle") noteCompactionStarted(h.ctx, undefined);
+			else if (gate !== "busy") h.ctx.sessionManager.__executionCompaction = { [gate]: gate === "pendingFollowUpPrompt" ? "follow-up" : true };
+			const original = structuredClone(h.pending);
+			await h.emit("agent_settled");
+			assert.equal(h.wakes().length, 0);
+			assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+			assert.deepEqual(h.pending, original);
+			if (gate === "busy") {
+				await h.settle();
+				assert.equal(h.wakes().length, 1, "a busy notification must not consume the real settled cycle");
+			}
+		});
+	}
+
+	for (const stopReason of ["error", "aborted"]) {
+		it(`${stopReason}: pauses once and only genuine input resumes`, async () => {
+			const h = await setup();
+			await h.run("failed", stopReason);
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			await h.settle();
+			assert.equal(h.notices.length, 1);
+			await h.emit("input", { source: "extension" });
+			await h.emit("before_agent_start");
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			assert.equal(h.wakes().length, 0);
+			await h.emit("input", { source: "rpc" });
+			assert.equal(getExecution()?.goalWait?.paused, false);
+			assert.equal(h.wakes().length, 0, "input is already owned by Pi");
+			await h.run();
+			assert.equal(h.wakes().length, 1);
+		});
+	}
+
+	it("leaves retries to Pi and refuses unknown or intentional tool termination", async () => {
+		const h = await setup();
+		await h.begin();
+		await h.turn("retryable failure", "error");
+		await h.emit("agent_end");
+		assert.equal(h.wakes().length, 0);
+		assert.equal(getExecution()?.goalWait?.paused, false);
+		await h.turn("recovered");
+		await h.settle();
+		assert.equal(h.wakes().length, 1);
+		for (const reason of ["toolUse", "length", "unknown"]) await h.run("intentional stop", reason);
+		assert.equal(h.wakes().length, 1);
+	});
+
+	for (const [text, count, field] of [["working", 3, "noProgressRounds"], ["waiting for CI", 6, "waitRounds"]] as const) {
+		it(`pauses at ${count} ${field} settled cycles, not intermediate turns`, async () => {
+			const h = await setup();
+			for (let i = 1; i <= count; i++) {
+				await h.begin();
+				for (let j = 0; j < 4; j++) await h.turn("tool work", "toolUse");
+				assert.equal(getExecution()?.goalWait?.[field], i - 1);
+				await h.turn(text);
+				await h.settle();
+				await h.settle();
+				assert.equal(getExecution()?.goalWait?.[field], i);
+			}
+			assert.equal(h.wakes().length, count - 1);
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			assert.match(h.status(), /goal-wait paused/);
+		});
+	}
+
+	it("real progress resets both nonzero counters through registered handlers", async () => {
+		const h = await setup();
+		await h.run();
+		await h.run("waiting for tests");
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 1);
+		assert.equal(getExecution()?.goalWait?.waitRounds, 1);
+		await h.run("[DONE:VC-001]");
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		assert.equal(getExecution()?.goalWait?.waitRounds, 0);
+		const persisted = h.entries.filter(e => e.customType === "pi-plans-exec").at(-1).data;
+		assert.equal(persisted.items[0].done, true);
+		assert.equal(persisted.goalWait.noProgressRounds, 0);
+	});
+
+	it("same-plan explicit handoff resumes without losing verified progress", async () => {
+		const h = await setup();
+		await h.run("[DONE:VC-001]");
+		await h.run("cancelled", "aborted");
+		const ex = getExecution()!;
+		const before = structuredClone(ex);
+		const outcome = await executeCommand(h.ctx, h.planPath);
+		assert.equal(outcome.status, "executing");
+		assert.equal(getExecution(), ex);
+		assert.deepEqual(ex.items, before.items);
+		assert.deepEqual(ex.usage, before.usage);
+		assert.equal(ex.startedAt, before.startedAt);
+		assert.equal(ex.goalWait?.paused, false);
+		assert.equal(h.wakes().length, 2);
+		await executeCommand(h.ctx, h.planPath);
+		assert.equal(h.wakes().length, 2);
+		await assert.rejects(executeHandoff(h.ctx, h.planPath), /must not re-enter handoff/);
+		const other = path.join(h.ctx.cwd, "PLAN_v2.md");
+		fs.copyFileSync(h.planPath, other);
+		await assert.rejects(executeCommand(h.ctx, other), /must not re-enter handoff/);
+	});
+
+	it("a paused command during another run preserves its next settled opportunity", async () => {
+		const h = await setup();
+		await h.run("interrupted", "aborted");
+		await h.begin();
+		const outcome = await executeCommand(h.ctx, h.planPath);
+		assert.equal(outcome.status, "executing");
+		assert.equal(getExecution()?.goalWait?.paused, false);
+		assert.equal(h.wakes().length, 0, "busy command must not enqueue a kick");
+		await h.turn("still incomplete");
+		await h.settle();
+		assert.equal(h.wakes().length, 1);
+	});
+
+	it("restore preserves pause and counters but cannot replay a wake", async () => {
+		const h = await setup();
+		for (let i = 0; i < 3; i++) await h.run();
+		const oldWake = h.wakes().at(-1);
+		const before = structuredClone(getExecution()?.goalWait);
+		await restoreFromSession(h.pi, h.ctx, h.entries);
+		await h.settle();
+		assert.deepEqual(getExecution()?.goalWait, before);
+		assert.equal(h.wakes().length, 2);
+		assert.deepEqual(filterGoalWaitMessages([oldWake]), []);
+	});
+
+	for (const exit of ["stop", "complete", "replacement", "shutdown"]) {
+		it(`${exit} invalidates wake identity without filtering user messages`, async () => {
+			const h = await setup();
+			await h.run();
+			const wake = h.wakes()[0];
+			if (exit === "stop") await stopExecution(h.pi, h.ctx, "test");
+			if (exit === "complete") await h.turn("[DONE:VC-001] [DONE:VC-002]");
+			if (exit === "replacement") await startExecution(h.pi, h.ctx, h.planPath, [{ id: "VC-003", text: "new", done: false }]);
+			if (exit === "shutdown") await h.emit("session_shutdown");
+			await h.settle();
+			const user = { role: "user", content: "Goal wait: this is my text" };
+			const other = { customType: "another-extension", content: "continue" };
+			assert.deepEqual(filterGoalWaitMessages([wake, user, other]), [user, other]);
+			assert.equal(h.wakes().length, 1);
+		});
+	}
+
+	it("a synchronous dispatch failure pauses once instead of leaving a retry lock", async () => {
+		const h = await setup();
+		h.pi.sendMessage = () => { throw new Error("dispatch failed"); };
+		await h.run();
+		await h.settle();
+		assert.equal(getExecution()?.goalWait?.paused, true);
+		assert.match(h.notices[0], /dispatch failed/);
+		assert.equal(h.notices.length, 1);
+	});
+});

package/tools/execute-plan.ts

@@ -9,6 +9,8 @@ import { Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import {
+	getExecution,
+	resumeActiveExecution,
 	startExecution,
 } from "../src/exec.ts";
 import { disableAutoComplete } from "../src/autocomplete.ts";
@@ -97,6 +99,22 @@ export async function executeHandoff(
 	};
 }
 
+/** The user command may resume an approved execution; the tool always asks. */
+export async function executeCommand(ctx: ExtensionContext, planPathArg?: string): Promise<HandoffOutcome> {
+	const activeExecution = getExecution();
+	const planPath = planPathArg ? path.resolve(ctx.cwd, planPathArg.replace(/^@/, "")) : activeExecution?.planPath;
+	if (activeExecution && planPath && path.resolve(activeExecution.planPath) === path.resolve(planPath)) {
+		const resumed = resumeActiveExecution(getCurrentApi(), ctx);
+		return {
+			status: "executing",
+			planPath,
+			itemCount: activeExecution.items.length,
+			message: resumed ? "Execution resumed; verified progress preserved." : "This plan is already executing.",
+		};
+	}
+	return executeHandoff(ctx, planPathArg);
+}
+
 // The tool registers with the ExtensionAPI in scope; keep a module-level
 // reference so the shared handoff helper can reach appendEntry/sendMessage.
 let currentApi: ExtensionAPI | null = null;