@hank-warren/pi-plan-mode 1.4.0 → 1.6.0

package/src/plan-mode.ts

@@ -1,5 +1,3 @@
-import { watch } from "node:fs";
-import { basename, dirname } from "node:path";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -13,21 +11,20 @@ import {
 	planModeCompleted,
 	renderPlanModeCompletion,
 } from "./completion-tool.js";
-import {
-	isStaleExtensionContextError,
-	onAgentSettled,
-	setPlanThinkingLevel,
-} from "./extension-runtime.js";
+import { isStaleExtensionContextError, onAgentSettled } from "./extension-runtime.js";
 import {
 	formatImplementationHandoff,
 	startFreshImplementationFromState,
 } from "./fresh-implementation.js";
+import { createLifecycle, type LifecycleScope } from "./lifecycle.js";
 import { deletePlanFile, planFilePathForSession, readPlanFile, writePlanFile } from "./plan-file.js";
 import { createPlanActionController } from "./plan-action-controller.js";
 import { createPlanExportController } from "./plan-export-controller.js";
 import {
 	clearPlanModeUi,
 	planModeStatusText as formatPlanModeStatusText,
+	registerPlanModeCardRenderer,
+	showPlanModePlan,
 	showStoredPlan,
 	updatePlanModeUi,
 } from "./presentation.js";
@@ -50,9 +47,11 @@ import {
 	planModeSettingsPath,
 	readPlanModeSettings,
 } from "./settings.js";
-import { type PlanModeState, readLegacyThinkingCapture, restorePlanModeState } from "./state.js";
+import { createSettingsWatcher } from "./settings-watch.js";
+import { type PlanModeState, restorePlanModeState } from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
+const ASK_USER_AVAILABILITY_EVENT = "hank:ask-user:availability";
 /**
  * Plan mode's entire enforcement surface. Everything else — bash, subagents,
  * MCP, and other extension tools — is left to the session's normal permission
@@ -64,46 +63,22 @@ const STATE_ENTRY_TYPE = "plan-mode-state";
  * was once listed here; it was a pre-1.0 upstream tool that no longer exists.)
  */
 const BLOCKED_TOOLS = new Set(["edit", "write"]);
-/**
- * One hand-edit or menu save fans out into several filesystem events (temp file
- * created, renamed into place). Collapsing them into one re-read keeps a save
- * to a single load.
- */
+/** Long enough to collapse one save's burst of filesystem events into one read. */
 const SETTINGS_RELOAD_DEBOUNCE_MS = 75;
 
 /**
- * Which question tool the prompt should name this turn.
- *
- * Detection is by tool NAME only, with no dependency on
- * `@hank-warren/pi-ask-user-question`: any extension registering
- * `ask_user_question` is treated as the preferred implementation. It offers
- * previews, notes, question tabs, digit hotkeys and checkbox multi-select;
- * `plan_mode_question` renders through plain `ctx.ui.select` + `ctx.ui.editor`
- * and has none of them.
- *
- * Evaluated per turn rather than once at mode entry, so the prompt cannot go
- * stale if the tool set changes mid-session.
- */
-function preferredQuestionTool(pi: ExtensionAPI): string {
-	return pi.getActiveTools().includes(ASK_USER_QUESTION_TOOL)
-		? ASK_USER_QUESTION_TOOL
-		: PLAN_MODE_QUESTION_TOOL;
-}
-
-/**
- * Hide `plan_mode_question` from the model whenever the better tool is present,
- * so it never sees two overlapping question tools and cannot call the weaker
- * one. The tool stays *registered* either way, so a historical transcript still
- * resolves it, and a host without `ask_user_question` keeps it fully functional.
+ * Which question tool the prompt may name this turn, read from the tool set
+ * the model will actually see.
  *
- * Idempotent, and writes only when something actually changes: siblings are
- * untouched, and repeated `before_agent_start` events are free.
+ * `null` means neither is active — a headless run, where both interactive
+ * tools are deliberately stripped. Naming one there would send the model after
+ * a tool it cannot call, so the prompt switches to asking in plain text.
  */
-function reconcileQuestionTool(pi: ExtensionAPI, preferred: string): void {
-	if (preferred === PLAN_MODE_QUESTION_TOOL) return;
+function preferredQuestionTool(pi: ExtensionAPI): string | null {
 	const active = pi.getActiveTools();
-	if (!active.includes(PLAN_MODE_QUESTION_TOOL)) return;
-	pi.setActiveTools(active.filter((name) => name !== PLAN_MODE_QUESTION_TOOL));
+	if (active.includes(ASK_USER_QUESTION_TOOL)) return ASK_USER_QUESTION_TOOL;
+	if (active.includes(PLAN_MODE_QUESTION_TOOL)) return PLAN_MODE_QUESTION_TOOL;
+	return null;
 }
 
 type InteractiveUi = typeof import("./interactive-ui.js");
@@ -132,13 +107,44 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	let readyPresentationNonce = 0;
 	let pendingReadyNonce: number | undefined;
 	let latestCommandContext: ExtensionCommandContext | undefined;
-	let menuGeneration = 0;
-	let workflowGeneration = 0;
 	let refreshStateBeforeFirstAgentStart = false;
-	let menuController = new AbortController();
-	let settingsWatch: ReturnType<typeof watch> | undefined;
-	let settingsReloadTimer: ReturnType<typeof setTimeout> | undefined;
+	const lifecycle = createLifecycle();
+	let settingsWatcher: ReturnType<typeof createSettingsWatcher> | undefined;
+	let planToolsActivated = false;
+	let currentHasUI = false;
+	let globalQuestionAvailable = false;
 	const persistState = () => pi.appendEntry<PlanModeState>(STATE_ENTRY_TYPE, state);
+
+	const reconcilePlanToolSurface = (hasUI: boolean, availability?: boolean) => {
+		currentHasUI = hasUI;
+		const active = pi.getActiveTools();
+		globalQuestionAvailable = availability ?? (hasUI && active.includes(ASK_USER_QUESTION_TOOL));
+		const wanted = new Set(active);
+		const completeWanted = planToolsActivated;
+		const fallbackWanted = planToolsActivated && hasUI && !globalQuestionAvailable;
+		if (completeWanted) wanted.add(PLAN_MODE_COMPLETE_TOOL_NAME);
+		else wanted.delete(PLAN_MODE_COMPLETE_TOOL_NAME);
+		if (fallbackWanted) wanted.add(PLAN_MODE_QUESTION_TOOL);
+		else wanted.delete(PLAN_MODE_QUESTION_TOOL);
+		const next = [...wanted];
+		if (next.length !== active.length || next.some((name, index) => name !== active[index])) {
+			pi.setActiveTools(next);
+		}
+	};
+	const activatePlanTools = (hasUI: boolean) => {
+		planToolsActivated = true;
+		reconcilePlanToolSurface(hasUI);
+	};
+
+	registerPlanModeCardRenderer(pi);
+	pi.events.on(ASK_USER_AVAILABILITY_EVENT, (payload: unknown) => {
+		const available =
+			typeof payload === "object" && payload !== null &&
+			typeof (payload as { available?: unknown }).available === "boolean"
+				? (payload as { available: boolean }).available
+				: undefined;
+		if (available !== undefined) reconcilePlanToolSurface(currentHasUI, available);
+	});
 	const planExports = createPlanExportController({
 		getState: () => state,
 		getSettings: () => settings,
@@ -149,7 +155,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	const planActions = createPlanActionController({
 		loadInteractiveUi,
 		getState: () => state,
-		captureLifecycle: captureMenuLifecycle,
+		captureLifecycle: () => lifecycle.capture(),
 		statusText: planStatusText,
 		planPathLine: () => (state.planPath ? `Plan file: ${state.planPath}` : undefined),
 		getExportDestination: (ctx) => planExports.getDestination(ctx),
@@ -162,13 +168,11 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		exitReady: (ctx) => {
 			// Same had-plan branching as the /plan exit command: the menu must not
 			// claim a plan was discarded when none was ever completed.
-			const hadPlan = state.planPath !== undefined;
-			void exitPlanMode(ctx).then(() => {
-				ctx.ui.notify(
-					hadPlan ? "Plan mode disabled. Proposed plan discarded." : "Plan mode disabled.",
-					"info",
-				);
-			});
+			const text =
+				state.planPath !== undefined
+					? "Plan mode disabled. Proposed plan discarded."
+					: "Plan mode disabled.";
+			void exitAndNotify(ctx, text);
 		},
 	});
 
@@ -183,12 +187,14 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		label: "Plan question",
 		description:
 			"Ask the user one to three Plan-mode clarification questions with meaningful options, then wait for the answer. Only available while Plan mode is active.",
+		// Kept, now that the tool is staged: this guidance reaches the model only
+		// in a session that has actually entered Plan mode.
 		promptSnippet: "Ask user decision questions while Plan mode is active",
 		promptGuidelines: [
 			"In Plan mode, use plan_mode_question for important preferences, tradeoffs, or assumptions that cannot be discovered from read-only exploration.",
 		],
 		parameters: PLAN_MODE_QUESTION_PARAMS,
-		async execute(_toolCallId, params: unknown, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params: unknown, signal, _onUpdate, ctx) {
 			if (!state.enabled) {
 				return planModeQuestionCancelled(
 					[],
@@ -210,13 +216,14 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 				);
 			}
 
-			const sessionGeneration = menuGeneration;
-			const questionWorkflowGeneration = workflowGeneration;
-			return answerPlanModeQuestions(parsed.questions, ctx, {
-				isCurrent: () =>
-					sessionGeneration === menuGeneration && questionWorkflowGeneration === workflowGeneration,
-				isEnabled: () => state.enabled,
-			});
+			const menu = lifecycle.capture();
+			const questionSignal = signal ? AbortSignal.any([signal, menu.signal]) : menu.signal;
+			return answerPlanModeQuestions(
+				parsed.questions,
+				ctx,
+				{ isCurrent: menu.isCurrent, isEnabled: () => state.enabled },
+				questionSignal,
+			);
 		},
 	});
 
@@ -243,6 +250,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		},
 	});
 
+	// Registered tools remain available for transcript replay; the active set is
+	// narrowed at session_start rather than here, because Pi refuses action
+	// methods (getActiveTools/setActiveTools) during extension loading.
+
 	pi.registerCommand("plan", {
 		description: "Enter or manage Plan mode",
 		getArgumentCompletions: completePlanArguments,
@@ -256,7 +267,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 					return;
 				}
 				enterPlanMode(ctx);
-				ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
+				notifyEnabled(ctx);
 				return;
 			}
 			if (command === "show") {
@@ -277,8 +288,8 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			}
 			const exportMatch = /^export(?:\s+([\s\S]+))?$/iu.exec(prompt);
 			if (exportMatch) {
-				const lifecycle = captureMenuLifecycle();
-				await planExports.export(exportMatch[1], ctx, lifecycle.signal, lifecycle.isCurrent);
+				const menu = lifecycle.capture();
+				await planExports.export(exportMatch[1], ctx, menu.signal, menu.isCurrent);
 				return;
 			}
 			if (command === "exit" || command === "off") {
@@ -290,8 +301,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 					: hadPlan
 						? "Active implementation plan cleared."
 						: "Plan mode disabled.";
-				await exitPlanMode(ctx);
-				ctx.ui.notify(notification, "info");
+				await exitAndNotify(ctx, notification);
 				return;
 			}
 			if (prompt) {
@@ -329,85 +339,61 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	 * `ctx` to explain why, would be worse than waiting for the next write. A
 	 * genuinely broken file is still reported at the next session start.
 	 */
-	const loadPlanModeSettings = async (generation: number, ctx?: ExtensionContext) => {
+	const loadPlanModeSettings = async (session: LifecycleScope, ctx?: ExtensionContext) => {
 		const loaded = await readRuntimeSettings();
-		if (generation !== menuGeneration || menuController.signal.aborted) return;
+		if (!session.isCurrent()) return;
 		if (loaded.kind === "invalid" && !ctx) return;
 		settings = loaded.kind === "loaded" ? loaded.settings : {};
 		if (!ctx) return;
 		if (loaded.kind === "invalid") {
 			ctx.ui.notify(`pi-plan-mode settings ignored: ${loaded.reason}`, "warning");
 		}
-		if (loaded.notice) ctx.ui.notify(loaded.notice, "warning");
 	};
 
 	const stopPlanModeSettingsWatch = () => {
-		if (settingsReloadTimer) {
-			clearTimeout(settingsReloadTimer);
-			settingsReloadTimer = undefined;
-		}
-		settingsWatch?.close();
-		settingsWatch = undefined;
+		settingsWatcher?.stop();
+		settingsWatcher = undefined;
 	};
 
-	/**
-	 * Watches the settings file's directory rather than the file itself: saves go
-	 * through a temp file and an atomic rename, and a watch bound to the old inode
-	 * would go deaf after the first one.
-	 */
-	const startPlanModeSettingsWatch = (generation: number) => {
+	/** An injected reader is the only source there is, so it is never watched. */
+	const startPlanModeSettingsWatch = (session: LifecycleScope) => {
 		stopPlanModeSettingsWatch();
 		if (dependencies.readSettings) return;
-		const watchedPath = dependencies.settingsPath ?? planModeSettingsPath();
-		const watchedFile = basename(watchedPath);
-		try {
-			const watcher = watch(dirname(watchedPath), { persistent: false }, (event, changedFile) => {
-				if (event !== "rename" && event !== "change") return;
-				// A null filename means the platform could not name the entry; reload
-				// rather than miss the edit. The agent directory holds other churn, so
-				// a named entry that is not ours is ignored.
-				if (changedFile && changedFile.toString() !== watchedFile) return;
-				if (settingsReloadTimer) clearTimeout(settingsReloadTimer);
-				settingsReloadTimer = setTimeout(() => {
-					settingsReloadTimer = undefined;
-					void loadPlanModeSettings(generation);
-				}, SETTINGS_RELOAD_DEBOUNCE_MS);
-			});
-			watcher.on("error", stopPlanModeSettingsWatch);
-			settingsWatch = watcher;
-		} catch {
-			// An unwatchable directory only costs the live reload; settings still
-			// load at session start.
-			stopPlanModeSettingsWatch();
-		}
+		settingsWatcher = createSettingsWatcher({
+			path: dependencies.settingsPath ?? planModeSettingsPath(),
+			debounceMs: SETTINGS_RELOAD_DEBOUNCE_MS,
+			onChange: () => void loadPlanModeSettings(session),
+		});
+		settingsWatcher.start();
 	};
 
 	pi.on("session_start", async (event, ctx) => {
-		const generation = ++menuGeneration;
+		const session = lifecycle.nextSession("Plan-mode session replaced");
+		planToolsActivated = false;
+		currentHasUI = ctx.hasUI;
+		reconcilePlanToolSurface(ctx.hasUI);
 		refreshStateBeforeFirstAgentStart = event.reason === "new";
-		menuController.abort(new DOMException("Plan-mode session replaced", "AbortError"));
-		menuController = new AbortController();
 		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
 		settings = {};
 		sessionPlanPath = resolveSessionPlanPath(ctx);
 		restoreState(ctx);
-		repairLegacyThinkingLevel(ctx);
-		await loadPlanModeSettings(generation, ctx);
-		if (generation !== menuGeneration || menuController.signal.aborted) return;
-		startPlanModeSettingsWatch(generation);
+		await loadPlanModeSettings(session, ctx);
+		if (!session.isCurrent()) return;
+		startPlanModeSettingsWatch(session);
 		const persistFlagActivation = pi.getFlag("plan") === true && !state.enabled;
 		if (persistFlagActivation) {
 			state = { ...state, enabled: true, awaitingAction: state.planPath !== undefined };
 		}
 		if (persistFlagActivation) persistState();
+		if (state.enabled) activatePlanTools(ctx.hasUI);
 		updateUi(ctx);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
-		menuGeneration += 1;
+		// No re-arm: nothing may become current again until a session_start.
+		lifecycle.endSession("Plan-mode session shut down");
 		stopPlanModeSettingsWatch();
-		menuController.abort(new DOMException("Plan-mode session shut down", "AbortError"));
 		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
 		refreshStateBeforeFirstAgentStart = false;
@@ -430,6 +416,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	});
 
 	pi.on("before_agent_start", (event, ctx) => {
+		currentHasUI = ctx.hasUI;
 		if (refreshStateBeforeFirstAgentStart) {
 			refreshStateBeforeFirstAgentStart = false;
 			restoreState(ctx);
@@ -439,15 +426,14 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			// A new turn supersedes the previous ready plan: revision feedback
 			// re-opens planning until another plan_mode_complete arrives.
 			pendingReadyNonce = undefined;
-			state = { ...state, awaitingAction: false };
-			persistState();
-			updateUi(ctx);
+			setState(ctx, { awaitingAction: false });
 		}
-		// Read fresh and write immediately, exactly like pi-ask-user-question's own
-		// reconciler, so the two hooks converge on the same result in either
-		// execution order.
-		const questionTool = preferredQuestionTool(pi);
-		reconcileQuestionTool(pi, questionTool);
+		if (state.enabled && !planToolsActivated) activatePlanTools(ctx.hasUI);
+		else reconcilePlanToolSurface(ctx.hasUI);
+		// A headless run has no legitimate question tool, whatever the active set
+		// still says: pi-ask-user-question strips its own tool on this same hook,
+		// and hook order between the two packages is not ours to depend on.
+		const questionTool = ctx.hasUI ? preferredQuestionTool(pi) : null;
 		if (state.enabled) {
 			return { systemPrompt: `${event.systemPrompt}\n\n${buildPlanModePrompt(questionTool)}` };
 		}
@@ -475,38 +461,55 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	});
 
 	function enterPlanMode(ctx: ExtensionContext) {
-		workflowGeneration += 1;
-		state = { ...state, enabled: true, awaitingAction: false };
-		persistState();
-		updateUi(ctx);
+		lifecycle.nextWorkflow();
+		activatePlanTools(ctx.hasUI);
+		setState(ctx, { enabled: true, awaitingAction: false });
 	}
 
 	function enterPlanModeWithPrompt(prompt: string, ctx: ExtensionContext) {
 		const previousState = state;
 		const wasEnabled = state.enabled;
 		enterPlanMode(ctx);
-		if (!wasEnabled) {
-			ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
-		}
-		if (sendPlanModeUserMessage(prompt, ctx)) return;
-		state = previousState;
-		persistState();
-		updateUi(ctx);
+		if (!wasEnabled) notifyEnabled(ctx);
+		sendOrRevert(prompt, ctx, previousState);
 	}
 
 	async function exitPlanMode(ctx: ExtensionContext, options: { keepPlanFile?: boolean } = {}) {
-		workflowGeneration += 1;
+		lifecycle.nextWorkflow();
 		const planPath = state.planPath;
 		pendingReadyNonce = undefined;
-		state = {
-			...state,
-			enabled: false,
-			planPath: undefined,
-			awaitingAction: false,
-		};
+		setState(ctx, { enabled: false, planPath: undefined, awaitingAction: false });
+		if (planPath && !options.keepPlanFile) await deletePlanFile(planPath);
+	}
+
+	/** Leaves Plan mode and reports it in one step, for menus and /plan alike. */
+	function exitAndNotify(
+		ctx: ExtensionContext,
+		text: string,
+		options: { keepPlanFile?: boolean } = {},
+	) {
+		return exitPlanMode(ctx, options).then(() => ctx.ui.notify(text, "info"));
+	}
+
+	function notifyEnabled(ctx: ExtensionContext) {
+		ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
+	}
+
+	/** State moves as one: what is remembered, what is persisted, what is shown. */
+	function setState(ctx: ExtensionContext, patch: Partial<PlanModeState>) {
+		state = { ...state, ...patch };
 		persistState();
 		updateUi(ctx);
-		if (planPath && !options.keepPlanFile) await deletePlanFile(planPath);
+	}
+
+	/**
+	 * Sends the message a state change exists to produce, and puts the previous
+	 * state back when the session refuses it: a mode switch the model was never
+	 * told about is worse than no switch at all.
+	 */
+	function sendOrRevert(message: string, ctx: ExtensionContext, previousState: PlanModeState) {
+		if (sendPlanModeUserMessage(message, ctx)) return;
+		setState(ctx, previousState);
 	}
 
 	function sendPlanModeUserMessage(message: string, ctx: ExtensionContext) {
@@ -525,20 +528,18 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	 * Writes the durable plan file and marks the plan ready. A write failure
 	 * keeps Plan mode active rather than silently losing the plan.
 	 */
-	async function acceptCompletedPlan(plan: string, ctx: ExtensionContext) {
+	async function acceptCompletedPlan(plan: string, ctx: ExtensionContext): Promise<string> {
 		const planPath = sessionPlanPath ?? resolveSessionPlanPath(ctx);
-		sessionPlanPath = planPath;
 		try {
 			await writePlanFile(planPath, plan);
 		} catch (error: unknown) {
 			const detail = error instanceof Error ? error.message : String(error);
-			ctx.ui.notify(`Unable to save the plan to ${planPath}: ${detail}`, "error");
-			return undefined;
+			throw new Error(`Unable to save the plan to ${planPath}: ${detail}`);
 		}
-		state = { ...state, planPath, awaitingAction: true };
+		sessionPlanPath = planPath;
 		pendingReadyNonce = ++readyPresentationNonce;
-		persistState();
-		updateUi(ctx);
+		setState(ctx, { planPath, awaitingAction: true });
+		showPlanModePlan(pi, ctx, "Proposed Plan", plan);
 		return planPath;
 	}
 
@@ -551,8 +552,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify("Plan mode is not active. Use /plan first.", "warning");
 			return;
 		}
+		// Same rule as the prompt: a headless run has no question tool to name.
+		const questionTool = ctx.hasUI ? preferredQuestionTool(pi) : null;
 		sendPlanModeUserMessage(
-			`Finalize the current implementation plan now. If any material decision remains, use ${preferredQuestionTool(pi)} instead. Otherwise call plan_mode_complete alone as your final action with the complete decision-ready plan.`,
+			`Finalize the current implementation plan now. If any material decision remains, ${
+				questionTool === null ? "ask it in plain text" : `use ${questionTool}`
+			} instead. Otherwise call plan_mode_complete alone as your final action with the complete decision-ready plan.`,
 			ctx,
 		);
 	}
@@ -573,39 +578,28 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			return;
 		}
 
-		workflowGeneration += 1;
+		lifecycle.nextWorkflow();
 		const previousState = state;
 		pendingReadyNonce = undefined;
-		state = {
-			...state,
-			enabled: false,
-			awaitingAction: false,
-			planPath,
-		};
-		persistState();
-		updateUi(ctx);
-
-		if (!sendPlanModeUserMessage(formatImplementationHandoff(planPath), ctx)) {
-			state = previousState;
-			persistState();
-			updateUi(ctx);
-		}
+		setState(ctx, { enabled: false, awaitingAction: false, planPath });
+		sendOrRevert(formatImplementationHandoff(planPath), ctx, previousState);
 	}
 
 	async function showLaunchMenu(ctx: ExtensionContext) {
-		const lifecycle = captureMenuLifecycle();
-		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+		const menu = lifecycle.capture();
+		if (!menu.isCurrent() || menu.signal.aborted) return;
 		const ui = await loadInteractiveUi();
-		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+		if (!menu.isCurrent() || menu.signal.aborted) return;
 		await ui.showPlanLaunchMenu(ctx, {
 			statusText: "Status: Off.",
-			...lifecycle,
+			signal: menu.signal,
+			isCurrent: menu.isCurrent,
 			start: (signal) => {
-				if (signal.aborted || !lifecycle.isCurrent()) return;
+				if (signal.aborted || !menu.isCurrent()) return;
 				enterPlanMode(ctx);
-				ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
+				notifyEnabled(ctx);
 			},
-			settings: (signal) => showSettings(ctx, signal, lifecycle.isCurrent),
+			settings: (signal) => showSettings(ctx, signal, menu.isCurrent),
 		});
 	}
 
@@ -614,27 +608,25 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify(planStatusText(), "info");
 			return;
 		}
-		const lifecycle = captureMenuLifecycle();
-		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+		const menu = lifecycle.capture();
+		if (!menu.isCurrent() || menu.signal.aborted) return;
 		const ui = await loadInteractiveUi();
-		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+		if (!menu.isCurrent() || menu.signal.aborted) return;
 		await ui.showActiveImplementationMenu(ctx, {
 			statusText: planStatusText(),
 			...(state.planPath ? { planPathLine: `Plan file: ${state.planPath}` } : {}),
 			getExportDestination: () => planExports.getDestination(ctx),
-			signal: lifecycle.signal,
-			isCurrent: lifecycle.isCurrent,
+			signal: menu.signal,
+			isCurrent: menu.isCurrent,
 			show: () => showStoredPlan(pi, ctx, state),
-			exportPlan: (path, signal) => planExports.export(path, ctx, signal, lifecycle.isCurrent),
-			settings: (signal) => showSettings(ctx, signal, lifecycle.isCurrent),
+			exportPlan: (path, signal) => planExports.export(path, ctx, signal, menu.isCurrent),
+			settings: (signal) => showSettings(ctx, signal, menu.isCurrent),
 			startNew: () => {
 				enterPlanMode(ctx);
-				ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
+				notifyEnabled(ctx);
 			},
 			clear: () => {
-				void exitPlanMode(ctx).then(() => {
-					ctx.ui.notify("Active implementation plan cleared.", "info");
-				});
+				void exitAndNotify(ctx, "Active implementation plan cleared.");
 			},
 		});
 	}
@@ -661,37 +653,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		return result.kind === "closed" && "reason" in result && result.reason === "close";
 	}
 
-	function captureMenuLifecycle() {
-		const sessionGeneration = menuGeneration;
-		const planWorkflowGeneration = workflowGeneration;
-		const controller = menuController;
-		return {
-			signal: controller.signal,
-			isCurrent: () =>
-				sessionGeneration === menuGeneration &&
-				planWorkflowGeneration === workflowGeneration &&
-				!controller.signal.aborted,
-		};
-	}
-
-	/**
-	 * pi-plan-mode <= 1.2.1 raised the thinking level while planning, and because
-	 * `pi.setThinkingLevel` writes through to the user's real settings, a session
-	 * that died before its restore left that change durable. If the newest state
-	 * entry still carries the capture and the live level still equals what Plan
-	 * mode applied, put the user's level back — once. Persisting state in the new
-	 * shape drops the capture, so the next session finds nothing to repair. A
-	 * user who has already moved the level themselves is left alone.
-	 *
-	 * legacy: delete in 1.4.0
-	 */
-	function repairLegacyThinkingLevel(ctx: ExtensionContext) {
-		const legacy = readLegacyThinkingCapture(ctx.sessionManager.getBranch(), STATE_ENTRY_TYPE);
-		if (!legacy || pi.getThinkingLevel() !== legacy.applied) return;
-		setPlanThinkingLevel(pi, legacy.previous);
-		persistState();
-	}
-
 	function resolveSessionPlanPath(ctx: ExtensionContext) {
 		try {
 			return planFilePathForSession(ctx.sessionManager.getSessionId());