pi-plans 0.3.1 → 0.3.3

package/src/exec.ts

@@ -8,6 +8,8 @@
  */
 
 import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 import type {
 	CompactionResult,
 	ExtensionAPI,
@@ -24,6 +26,7 @@ import {
 	entryCurrentIMarkers,
 	formatVccCompactionStats,
 	loadVccSettings,
+	PLANNING_PREPLAN_COMPACT_HINT,
 	scaffoldVccSettings,
 	shouldScheduleAutoContinue,
 	type CompactionEntryLike,
@@ -33,13 +36,35 @@ import {
 	type VccCompactionBuildResult,
 	type VccCompactionStats,
 } from "./compaction.ts";
-import { getRun, readActive, resolveStateRootOrNull, setRunStatus, utcNow } from "./state.ts";
+import { getRun, readActive, resolveStateRootOrNull, setRunStatus, StateError, utcNow } from "./state.ts";
+import { bindRun, resolveActiveRun } from "./run-context.ts";
+import { OwnershipError } from "./run-ownership.ts";
+import {
+	applyExecutionApproved,
+	applyExecutionCompleted,
+	applyExecutionHeadChanged,
+	applyExecutionProgress,
+	applyExecutionStopped,
+	applyQuestionAsked,
+	applyReviewRoundStarted,
+	createCheckpoint,
+	loadCheckpoint,
+	mutateCheckpoint,
+	StaleCheckpointError,
+	planIdentityOf,
+	resolveHeadAt,
+	resolveWorktreeRoot,
+	sha256File,
+	type ExecutionApproval,
+} from "./workflow-state.ts";
 import { graphBlockForExecutor } from "./code-graph/prompts.ts";
 import { resolveGraphMode } from "./code-graph/mode.ts";
-import { TERMINATION_QUESTION, TERMINATION_OPTIONS, renderTerminationOptions } from "./termination-prompt.ts";
+import { TERMINATION_QUESTION, TERMINATION_OPTIONS, TERMINATION_RECORDING_INSTRUCTIONS, renderTerminationOptions } from "./termination-prompt.ts";
 import {
 	extractCoverage,
 	latestPlanVersion,
+	parseChecklist,
+	parseImplItems,
 	resolveImplStatuses,
 	scanDoneMarkers,
 	scanImplMarkers,
@@ -76,6 +101,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;
@@ -104,6 +155,105 @@ export function getExecution(): ExecState | null {
 	return execution;
 }
 
+export interface CheckpointExecutionLoad {
+	status: "loaded" | "no-execution" | "plan-missing" | "plan-mismatch" | "no-checkpoint" | "corrupt";
+	planPath?: string;
+	doneVcIds?: string[];
+	reverifyAll?: boolean;
+	pausedReason?: string;
+	error?: string;
+}
+
+/**
+ * Shared restore primitive (I-005/I-006): load the executing state from a run
+ * checkpoint into THIS session. Authorization is kept only when the recorded
+ * approval matches the current plan digest; a HEAD change keeps the
+ * authorization but re-verifies previously verified VCs (D-011/F-001).
+ * F-002: the loaded state is persisted to the current session IMMEDIATELY so
+ * session_start/session_tree restore paths cannot silently clear it.
+ */
+export function loadExecutionFromCheckpoint(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	runId: string,
+): CheckpointExecutionLoad {
+	const load = loadCheckpoint(ctx.cwd, runId);
+	if (load.status === "missing") return { status: "no-checkpoint" };
+	if (load.status === "corrupt") return { status: "corrupt", error: load.error };
+	const cp = load.checkpoint;
+	if (!cp.execution || cp.phase !== "executing") return { status: "no-execution" };
+	const planPath = cp.plan?.path;
+	if (!planPath || !fs.existsSync(planPath)) {
+		return { status: "plan-missing", error: planPath ? `plan file vanished: ${planPath}` : "checkpoint has no plan identity" };
+	}
+	const planText = fs.readFileSync(planPath, "utf8");
+	// F-002 (implementation review): the recorded plan identity is over BYTES —
+	// an in-place edit at the same path must not inherit the authorization or
+	// the verified VCs. Refuse the load and require a fresh handoff.
+	if (sha256File(planPath) !== cp.plan.sha256) {
+		return {
+			status: "plan-mismatch" as const,
+			error: `plan file changed since the approval record (${planPath}); re-approve via /plans-execute before executing`,
+		};
+	}
+	const items = parseChecklist(planText);
+	if (items.length === 0) {
+		return { status: "plan-missing", error: `${planPath} has no parsable verifier checklist` };
+	}
+	const implItems = parseImplItems(planText);
+	const doneIds = new Set(cp.execution.doneVcIds);
+	// D-011/F-001: an unchanged plan digest keeps the recorded authorization;
+	// a changed HEAD under it forces re-verification of previously verified VCs.
+	// F-006 (implementation review): an approval without a resolvable HEAD
+	// recorded an unverifiable code state — re-verify instead of trusting.
+	const headNow = resolveHeadAt(ctx.cwd);
+	const headUnverifiable = cp.execution.approval === null || cp.execution.approval.headAtApproval === null;
+	const headChanged =
+		cp.execution.approval !== null &&
+		cp.execution.approval.headAtApproval !== null &&
+		cp.execution.approval.headAtApproval !== headNow;
+	const reverifyAll = cp.execution.reverifyAll === true || headChanged || headUnverifiable;
+	if (!reverifyAll) {
+		for (const item of items) {
+			if (doneIds.has(item.id)) item.done = true;
+		}
+	}
+	execution = {
+		planPath,
+		items,
+		startedAt: utcNow(),
+		usage: { inToks: cp.execution.usage.inToks, outToks: cp.execution.usage.outToks },
+		implItems,
+		implStatus: { ...cp.execution.implStatus },
+		currentI: cp.execution.currentI,
+		goalWait: {
+			noProgressRounds: 0,
+			waitRounds: 0,
+			lastMarkers: null,
+			paused: cp.execution.pausedReason !== undefined,
+			pausedReason: cp.execution.pausedReason,
+		},
+	};
+	executionRunId = runId;
+	bindRun(ctx.sessionManager, ctx.cwd, runId);
+	resetGoalWaitRuntime(ctx);
+	pendingExecutionFlush = false; // restored state: no inherited flush debt
+	resetExecutionCompactionState(ctx);
+	if (headChanged) {
+		withExecutionCheckpoint(ctx, (current) => applyExecutionHeadChanged(current));
+	}
+	if (execution.goalWait) execution.goalWait.lastMarkers = goalWaitSnapshot();
+	persist(pi); // F-002: immediate session snapshot
+	updateStatusWidget(ctx);
+	return {
+		status: "loaded",
+		planPath,
+		doneVcIds: [...doneIds],
+		reverifyAll,
+		pausedReason: cp.execution.pausedReason,
+	};
+}
+
 const EXECUTION_COMPACTION_RESUME_MESSAGE = "Continue execution.";
 
 interface ExecutionCompactionState {
@@ -228,7 +378,7 @@ export function updateStatusWidget(ctx: ExtensionContext): void {
 		ctx.ui.setStatus("pi-plans", ctx.ui.theme.fg("accent", line));
 		return;
 	}
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (active) {
 		// Idle indicator depends on the run's lifecycle, not just its existence:
 		// done reads as finished, abandoned as closed, stopped/accepted as paused.
@@ -275,6 +425,24 @@ function persist(pi: ExtensionAPI): void {
 	});
 }
 
+/** Checkpoint bookkeeping for the executing run; best-effort for legacy runs
+ * without checkpoints (their cross-session resume degrades to R-008 rules). */
+function withExecutionCheckpoint(ctx: ExtensionContext, mutator: (cp: import("./workflow-state.ts").WorkflowCheckpoint) => import("./workflow-state.ts").WorkflowCheckpoint): void {
+	if (!execution) return;
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
+	if (!active || active.run_id !== executionRunId) return;
+	try {
+		mutateCheckpoint(ctx.cwd, active.run_id, mutator);
+	} catch (error) {
+		// F-005 (implementation review): ownership loss and revision staleness
+		// must stop the advance, not vanish into the catch block.
+		if (error instanceof OwnershipError || error instanceof StaleCheckpointError) throw error;
+		/* legacy run or corrupt checkpoint: session snapshot still carries the loop */
+	}
+}
+
+let executionRunId: string | null = null;
+
 export async function startExecution(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -286,11 +454,44 @@ 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);
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
+	executionRunId = active?.run_id ?? null;
 	if (active) {
+		bindRun(ctx.sessionManager, ctx.cwd, active.run_id);
+		// I-005: durable approval evidence — run + plan digest + HEAD at
+		// approval (D-003/D-011). Sets phase executing via the state machine.
+		try {
+			const load = loadCheckpoint(ctx.cwd, active.run_id);
+			if (load.status === "missing") {
+				createCheckpoint(ctx.cwd, { runId: active.run_id, originWorkdir: ctx.cwd, workdir: ctx.cwd });
+			}
+			const approval: ExecutionApproval = {
+				plan: planIdentityOf(path.resolve(planPath), 1),
+				worktree: resolveWorktreeRoot(ctx.cwd) ?? path.resolve(ctx.cwd),
+				headAtApproval: resolveHeadAt(ctx.cwd),
+				approvedAt: utcNow(),
+			};
+			mutateCheckpoint(ctx.cwd, active.run_id, (cp) => {
+				// Plan refinement may not have recorded the plan identity yet.
+				const withPlan = cp.plan === null ? { ...cp, plan: approval.plan } : cp;
+				// The checkpoint may not carry accept-execute (legacy flow);
+				// approval here came from the explicit handoff confirmation.
+				const aligned = withPlan.nextAction === "accept-execute"
+					? withPlan
+					: { ...withPlan, nextAction: "accept-execute" as const };
+				return applyExecutionApproved(aligned, approval);
+			});
+		} catch (error) {
+			// F-002 (implementation review): a plan-digest mismatch between the
+			// recorded checkpoint plan and the approval must fail closed and
+			// visibly — never silently execute without durable approval.
+			if (error instanceof StateError && /does not match/.test(error.message)) throw error;
+			/* legacy/corrupt checkpoint: run status still transitions below */
+		}
 		try {
 			setRunStatus(ctx.cwd, active.run_id, "executing");
 		} catch {
@@ -320,10 +521,30 @@ export function recordExecutionTurn(
 		execution.usage.inToks += usage.input;
 		execution.usage.outToks += usage.output;
 	}
+	// I-005: mirror progress into the run checkpoint so a different session
+	// can resume with the verified VC/I set (R-004).
+	withExecutionCheckpoint(_ctx, (cp) =>
+		applyExecutionProgress(cp, {
+			doneVcIds: execution!.items.filter((item) => item.done).map((item) => item.id),
+			implStatus: implStatusSnapshot(),
+			currentI: execution!.currentI,
+			usage: usage ? { inToks: usage.input, outToks: usage.output } : undefined,
+		}),
+	);
 	requestExecutionFlush(pi, _ctx);
 	updateStatusWidget(_ctx);
 }
 
+function implStatusSnapshot(): Record<string, string> {
+	const snapshot: Record<string, string> = {};
+	if (!execution?.implItems) return snapshot;
+	for (const item of execution.implItems) {
+		const state = execution.implStatus?.[item.id];
+		if (state) snapshot[item.id] = state;
+	}
+	return snapshot;
+}
+
 export function registerExecutionTurnHandlers(
 	pi: ExtensionAPI,
 	onTurnEnd?: (ctx: ExtensionContext) => Promise<void> | void,
@@ -331,6 +552,31 @@ 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;
+		executionRunId = 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 +585,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 +594,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 +612,6 @@ export function registerExecutionTurnHandlers(
 		}
 		if (getExecution() && isExecutionComplete()) {
 			await completeExecution(pi, ctx);
-		} else if (getExecution()) {
-			maybeGoalWaitFollowUp(pi, ctx, text);
 		}
 		await onTurnEnd?.(ctx);
 	});
@@ -373,7 +622,7 @@ const EXECUTION_RESUME_CUSTOM_TYPE = "pi-plans-exec-resume";
 function activeVccSettings(ctx: ExtensionContext, phase: PiPlansCompactionPhase): { settings: PiPlansVccSettings; runId: string; artifactDir: string } | null {
 	const stateRoot = resolveStateRootOrNull(ctx.cwd);
 	if (!stateRoot) return null;
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (!active) return null;
 	const run = getRun(ctx.cwd, active.run_id);
 	if (!run) return null;
@@ -492,7 +741,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;
@@ -569,6 +817,49 @@ export const PLANNING_RUN_START_CUSTOM_TYPE = "pi-plans-run-start";
 export const PLANNING_PLAN_WRITTEN_CUSTOM_TYPE = "pi-plans-plan-written";
 const PLANNING_RESUME_CUSTOM_TYPE = "pi-plans-plan-resume";
 
+// ---------------------------------------------------------------------------
+// Pre-plan compaction: right after `plans start-run` creates a new planning
+// run, the extension triggers one VCC compaction so the new plan starts on a
+// lean context (LLM reasoning degrades with longer context; see PLAN
+// preplan-compact). The pending flag is session-scoped and opportunistic: it
+// is set by the start-run tool case and consumed by the plans tool_result
+// hook in index.ts, which requests the extension-context compact action and
+// resumes planning exactly once regardless of success or failure.
+// ---------------------------------------------------------------------------
+
+export { PLANNING_PREPLAN_COMPACT_HINT };
+export const PLANNING_PREPLAN_RESUME_CUSTOM_TYPE = "pi-plans-preplan-resume";
+
+interface PrePlanCompactPending {
+	runId: string;
+}
+
+export function markPrePlanCompactPending(ctx: ExtensionContext, runId: string): void {
+	const session = ctx.sessionManager as unknown as { __piPlansPrePlanCompact?: PrePlanCompactPending | null };
+	session.__piPlansPrePlanCompact = { runId };
+}
+
+export function consumePrePlanCompactPending(ctx: ExtensionContext): PrePlanCompactPending | null {
+	const session = ctx.sessionManager as unknown as { __piPlansPrePlanCompact?: PrePlanCompactPending | null };
+	const pending = session.__piPlansPrePlanCompact ?? null;
+	session.__piPlansPrePlanCompact = null;
+	return pending;
+}
+
+/** Hidden resume message after the pre-plan compaction settles (success or
+ *  failure): Pi's manual compaction never continues the aborted turn, so the
+ *  planning workflow is continued exactly once from here. */
+export function sendPrePlanCompactResume(pi: ExtensionAPI): void {
+	pi.sendMessage?.(
+		{
+			customType: PLANNING_PREPLAN_RESUME_CUSTOM_TYPE,
+			content: "Continue planning.",
+			display: false,
+		},
+		{ triggerTurn: true },
+	);
+}
+
 interface PlanningCompactionState {
 	inFlight: boolean;
 	resumeGuard: boolean;
@@ -698,8 +989,11 @@ export function refreshPlanningCompactionCooldown(_ctx: ExtensionContext): void
 }
 
 export function requestPlanningCompaction(_ctx: ExtensionContext): void {
-	// Proactive pi-plans compaction is intentionally disabled. Manual,
+	// Generic proactive pi-plans compaction is intentionally disabled. Manual,
 	// threshold, and overflow compactions are handled by session_before_compact.
+	// The single exception is the pre-plan compaction: index.ts requests the
+	// extension-context compact action from the plans tool_result hook right
+	// after start-run (see PLANNING_PREPLAN_COMPACT_HINT).
 }
 
 function buildPlanningVccResult(event: SessionBeforeCompactEvent, ctx: ExtensionContext): VccCompactionBuildResult | null {
@@ -833,7 +1127,7 @@ export function handlePlanningCompactFailed(pi: ExtensionAPI, ctx: ExtensionCont
 }
 
 export function filterPlanningResumeMessages<T extends { customType?: string }>(messages: T[]): T[] {
-	return messages.filter((message) => message.customType !== PLANNING_RESUME_CUSTOM_TYPE);
+	return messages.filter((message) => message.customType !== PLANNING_RESUME_CUSTOM_TYPE && message.customType !== PLANNING_PREPLAN_RESUME_CUSTOM_TYPE);
 }
 
 export async function stopExecution(pi: ExtensionAPI, ctx: ExtensionContext, reason: string): Promise<void> {
@@ -842,7 +1136,11 @@ export async function stopExecution(pi: ExtensionAPI, ctx: ExtensionContext, rea
 	// Final synchronous write: drain any deferred flush and land the last snapshot.
 	pendingExecutionFlush = false;
 	persist(pi);
+	// Checkpoint first: withExecutionCheckpoint guards on the live execution.
+	withExecutionCheckpoint(ctx, (cp) => applyExecutionStopped(cp, reason));
 	execution = null;
+	executionRunId = null;
+	goalWaitRuntime = null;
 	pi.appendEntry("pi-plans-exec-cleared", { reason });
 	pi.sendMessage(
 		{
@@ -852,7 +1150,7 @@ export async function stopExecution(pi: ExtensionAPI, ctx: ExtensionContext, rea
 		},
 		{ triggerTurn: false },
 	);
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (active) {
 		try {
 			setRunStatus(ctx.cwd, active.run_id, "stopped");
@@ -909,13 +1207,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 +1233,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 +1303,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);
 }
 
-/** Any external input re-kicks a paused goal-wait (clears pause and counters). */
-export function resumeGoalWaitIfPaused(pi: ExtensionAPI, ctx: ExtensionContext): void {
+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));
+}
+
+/** 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> {
@@ -1021,7 +1348,11 @@ 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;
+	// Checkpoint first (live-execution guard), then clear the session state.
+	withExecutionCheckpoint(ctx, (cp) => applyExecutionCompleted(cp));
 	execution = null;
+	executionRunId = 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
@@ -1043,7 +1374,7 @@ export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext)
 	if (interactive) {
 		pi.appendEntry("pi-plans-ameliorate", { planPath, phase: "goal-started", rounds: null, currentRound: 0 });
 	}
-	const active = readActive(ctx.cwd);
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
 	if (active) {
 		try {
 			setRunStatus(ctx.cwd, active.run_id, "done");
@@ -1059,7 +1390,7 @@ export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext)
  * implementation-review loop. Termination options are single-sourced from
  * src/termination-prompt.ts (shared with the ask_choice trailing branch). */
 export const AMELIORATION_PROMPT_TEXT = `---
-Goal-running continuation: immediately ask the user now via ask_choice (autoComplete: false, in the session language) the termination question: "${TERMINATION_QUESTION}" Options (recommended first): ${renderTerminationOptions()}. Then keep running the implementation-review loop without asking whether to continue; the goal-wait option keeps the loop running until no unpassed VCs remain.`;
+Goal-running continuation: immediately ask the user now via ask_choice (autoComplete: false, in the session language) the termination question: "${TERMINATION_QUESTION}" Options (recommended first): ${renderTerminationOptions()}. ${TERMINATION_RECORDING_INSTRUCTIONS} Then keep running the implementation-review loop without asking whether to continue; the goal-wait option keeps the loop running until no unpassed VCs remain.`;
 
 /** Injection text for before_agent_start while executing. */
 export function executionContextMessage(ctx: ExtensionContext): string | null {
@@ -1111,6 +1442,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 +1501,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) {