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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @hank-warren/pi-plan-mode
 
+## 1.6.0
+
+### Minor Changes
+
+- d0c46a5: Drop two legacy paths that were past their delete-by date:
+
+  - The one-shot repair of a thinking level left raised by a pre-1.3.0 session, and the "thinkingLevel is no longer used" row in the settings menu. An unknown `thinkingLevel` key in `pi-plan-mode.json` is still preserved verbatim on save.
+  - The `plan-mode.json` settings fallback and its "Using legacy…" / "ignored because…" notices. Only `$PI_CODING_AGENT_DIR/pi-plan-mode.json` is read now; a host still on the old filename gets defaults and should rename the file.
+
+  Internally, the settings watcher and the menu/workflow lifecycle moved into their own modules and the state transitions share one helper; nothing else about `/plan` changed. `engines.node` now states Pi's own floor, `>=22.19.0`.
+
 ## 1.5.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Plan mode for Pi: research and design with a durable plan file that survives compaction.",
   "type": "module",
   "keywords": [
@@ -22,7 +22,7 @@
   },
   "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-plan-mode#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.19.0"
   },
   "pi": {
     "extensions": [

package/src/command.ts

@@ -1,4 +1,4 @@
-export interface CommandArgumentCompletion {
+interface CommandArgumentCompletion {
 	value: string;
 	label: string;
 	description?: string;

package/src/completion-tool.ts

@@ -2,10 +2,10 @@ import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown } from "@earendil-works/pi-tui";
 
 export const PLAN_MODE_COMPLETE_TOOL_NAME = "plan_mode_complete";
-export const PLAN_MODE_COMPLETE_VERSION = 1;
-export const PLAN_MODE_MAX_CHARS = 50_000;
+const PLAN_MODE_COMPLETE_VERSION = 1;
+const PLAN_MODE_MAX_CHARS = 50_000;
 
-export type PlanModeCompletionDetails = {
+type PlanModeCompletionDetails = {
 	version: typeof PLAN_MODE_COMPLETE_VERSION;
 	source: typeof PLAN_MODE_COMPLETE_TOOL_NAME;
 	plan: string;
@@ -43,7 +43,7 @@ export function normalizePlanModeCompletion(input: unknown): NormalizePlanModeCo
 	return { ok: true, plan };
 }
 
-export function planFromCompletionDetails(value: unknown) {
+function planFromCompletionDetails(value: unknown) {
 	if (!isRecord(value)) return undefined;
 	if (
 		value.version !== PLAN_MODE_COMPLETE_VERSION ||
@@ -78,7 +78,7 @@ type PlanModeCompletionRenderResult = {
 	details?: unknown;
 };
 
-export function planModeCompletionMarkdown(result: PlanModeCompletionRenderResult) {
+function planModeCompletionMarkdown(result: PlanModeCompletionRenderResult) {
 	const content = result.content
 		.filter((block) => block.type === "text" && typeof block.text === "string")
 		.map((block) => block.text)

package/src/extension-runtime.ts

@@ -1,5 +1,4 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { LegacyThinkingCapture } from "./state.js";
 
 type AgentSettledHandler = (event: unknown, ctx: ExtensionContext) => unknown;
 
@@ -11,16 +10,6 @@ export function onAgentSettled(pi: ExtensionAPI, handler: AgentSettledHandler) {
 	).on("agent_settled", handler);
 }
 
-/**
- * Only the one-shot migration that undoes a pre-1.3.0 thinking-level change
- * still calls this. Plan mode never sets the thinking level otherwise.
- *
- * legacy: delete in 1.4.0
- */
-export function setPlanThinkingLevel(pi: ExtensionAPI, level: LegacyThinkingCapture["previous"]) {
-	(pi.setThinkingLevel as unknown as (level: string) => void)(level);
-}
-
 export function isStaleExtensionContextError(error: unknown) {
 	return (
 		error instanceof Error &&

package/src/fresh-implementation.ts

@@ -5,7 +5,7 @@ import type { PlanModeState } from "./state.js";
 type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
 type ReplacementContext = Parameters<NonNullable<NewSessionOptions["withSession"]>>[0];
 
-export interface FreshImplementationRequest {
+interface FreshImplementationRequest {
 	plan: string;
 	planPath: string;
 	stateEntryType: string;
@@ -18,7 +18,7 @@ interface FreshImplementationFromStateOptions {
 	stateEntryType: string;
 }
 
-export type FreshImplementationResult =
+type FreshImplementationResult =
 	| { kind: "started" }
 	| { kind: "cancelled" }
 	| { kind: "partial" }

package/src/lifecycle.ts

@@ -0,0 +1,79 @@
+/**
+ * A scope captured when deferred work starts: the signal that work should race
+ * against, and the question "is what I was started for still the current
+ * thing?".
+ */
+export interface LifecycleScope {
+	readonly signal: AbortSignal;
+	isCurrent(): boolean;
+}
+
+/**
+ * Two nested generations decide whether deferred Plan-mode work may still act.
+ *
+ * The session generation moves when Pi replaces or shuts down the session: a
+ * menu, a settings reload, or a question left waiting from the previous session
+ * must never write to the new one. The workflow generation moves on every
+ * enter/exit/implement, so a menu opened against one plan cannot act after the
+ * user has moved on — while a settings reload, which belongs to the session
+ * rather than to a plan, is deliberately left alone by it.
+ *
+ * The abort signal is the second half of the same rule: it stops work that is
+ * already blocked on the UI, where a generation check would never be reached.
+ */
+export function createLifecycle() {
+	let sessionGeneration = 0;
+	let workflowGeneration = 0;
+	let controller = new AbortController();
+
+	const sessionScope = (): LifecycleScope => {
+		const session = sessionGeneration;
+		const active = controller;
+		return {
+			signal: active.signal,
+			isCurrent: () => session === sessionGeneration && !active.signal.aborted,
+		};
+	};
+
+	/**
+	 * Ends the current session: everything captured before this call goes stale
+	 * and everything waiting on the signal is aborted with `reason`. The aborted
+	 * signal stays in place, so anything captured *after* it is stale too —
+	 * which is what a shut-down session wants: there is no next session to be
+	 * current for, and a menu opened in that window must refuse to run.
+	 */
+	const endSession = (reason: string) => {
+		sessionGeneration += 1;
+		controller.abort(new DOMException(reason, "AbortError"));
+	};
+
+	return {
+		/** The live session signal, for composing with a caller's own. */
+		get signal() {
+			return controller.signal;
+		},
+		endSession,
+		/**
+		 * Ends the current session and opens the next one, whose scope is
+		 * returned: work started from here races against a fresh signal.
+		 */
+		nextSession(reason: string): LifecycleScope {
+			endSession(reason);
+			controller = new AbortController();
+			return sessionScope();
+		},
+		/** Supersedes menus and prompts opened against the previous plan state. */
+		nextWorkflow() {
+			workflowGeneration += 1;
+		},
+		/** The scope for menu-scale work: stale as soon as either generation moves. */
+		capture(): LifecycleScope {
+			const session = sessionScope();
+			const workflow = workflowGeneration;
+			return {
+				signal: session.signal,
+				isCurrent: () => session.isCurrent() && workflow === workflowGeneration,
+			};
+		},
+	};
+}

package/src/plan-export.ts

@@ -8,7 +8,7 @@ import type { PlanModeState } from "./state.js";
 
 export { DEFAULT_PLAN_EXPORT_PATH };
 
-export interface PlanExportResult {
+interface PlanExportResult {
 	path: string;
 }
 
@@ -17,7 +17,7 @@ export interface PlanExportDestination {
 	resolvedPath: string;
 }
 
-export interface PlanExportLifecycle {
+interface PlanExportLifecycle {
 	signal: AbortSignal;
 	isCurrent(): boolean;
 	getState?(): PlanModeState;
@@ -74,7 +74,7 @@ export async function exportStoredPlan(
 	return true;
 }
 
-export async function exportPlanToFile(
+async function exportPlanToFile(
 	plan: string,
 	requestedPath: string | undefined,
 	cwd: string,
@@ -109,7 +109,7 @@ export function planExportDestination(defaultPath: string, cwd: string): PlanExp
 	};
 }
 
-export function resolvePlanExportPath(
+function resolvePlanExportPath(
 	requestedPath: string | undefined,
 	cwd: string,
 	defaultPath = DEFAULT_PLAN_EXPORT_PATH,

package/src/plan-file.ts

@@ -4,7 +4,7 @@ import { mkdir, open, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export const PLANS_DIRECTORY = "plans";
+const PLANS_DIRECTORY = "plans";
 const MAX_PLAN_BYTES = 1024 * 1024;
 
 /**
@@ -79,7 +79,3 @@ export async function readPlanFile(path: string): Promise<string | undefined> {
 export async function deletePlanFile(path: string): Promise<void> {
 	await unlink(path).catch(() => undefined);
 }
-
-export async function planFileExists(path: string): Promise<boolean> {
-	return (await readPlanFile(path)) !== undefined;
-}

package/src/plan-launch-menu.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export interface PlanLaunchMenuOptions {
+interface PlanLaunchMenuOptions {
 	statusText: string;
 	signal: AbortSignal;
 	isCurrent(): boolean;

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,15 +11,12 @@ 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";
@@ -52,7 +47,8 @@ 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";
@@ -67,11 +63,7 @@ const ASK_USER_AVAILABILITY_EVENT = "hank:ask-user:availability";
  * 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;
 
 /**
@@ -115,12 +107,9 @@ 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;
@@ -166,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),
@@ -179,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);
 		},
 	});
 
@@ -229,20 +216,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 				);
 			}
 
-			const sessionGeneration = menuGeneration;
-			const questionWorkflowGeneration = workflowGeneration;
-			const questionSignal = signal
-				? AbortSignal.any([signal, menuController.signal])
-				: menuController.signal;
+			const menu = lifecycle.capture();
+			const questionSignal = signal ? AbortSignal.any([signal, menu.signal]) : menu.signal;
 			return answerPlanModeQuestions(
 				parsed.questions,
 				ctx,
-				{
-					isCurrent: () =>
-						sessionGeneration === menuGeneration &&
-						questionWorkflowGeneration === workflowGeneration,
-					isEnabled: () => state.enabled,
-				},
+				{ isCurrent: menu.isCurrent, isEnabled: () => state.enabled },
 				questionSignal,
 			);
 		},
@@ -288,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") {
@@ -309,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") {
@@ -322,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) {
@@ -361,76 +339,48 @@ 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 };
@@ -441,9 +391,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	});
 
 	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;
@@ -476,9 +426,7 @@ 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 });
 		}
 		if (state.enabled && !planToolsActivated) activatePlanTools(ctx.hasUI);
 		else reconcilePlanToolSurface(ctx.hasUI);
@@ -513,39 +461,55 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	});
 
 	function enterPlanMode(ctx: ExtensionContext) {
-		workflowGeneration += 1;
+		lifecycle.nextWorkflow();
 		activatePlanTools(ctx.hasUI);
-		state = { ...state, enabled: true, awaitingAction: false };
-		persistState();
-		updateUi(ctx);
+		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) {
@@ -573,10 +537,8 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			throw new Error(`Unable to save the plan to ${planPath}: ${detail}`);
 		}
 		sessionPlanPath = planPath;
-		state = { ...state, planPath, awaitingAction: true };
 		pendingReadyNonce = ++readyPresentationNonce;
-		persistState();
-		updateUi(ctx);
+		setState(ctx, { planPath, awaitingAction: true });
 		showPlanModePlan(pi, ctx, "Proposed Plan", plan);
 		return planPath;
 	}
@@ -616,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),
 		});
 	}
 
@@ -657,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.");
 			},
 		});
 	}
@@ -704,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());

package/src/presentation.ts

@@ -69,9 +69,9 @@ export function registerPlanModeCardRenderer(pi: ExtensionAPI): void {
  * characters do not justify a shared package; a user reading a footer
  * justifies the consistency.
  */
-export type PlanModePhase = "drafting" | "revising" | "ready" | "implementing";
+type PlanModePhase = "drafting" | "revising" | "ready" | "implementing";
 
-export interface PlanModeView {
+interface PlanModeView {
 	phase: PlanModePhase;
 	/** The footer line: plain text with a glyph, no colour. */
 	footer: string;

package/src/question-tool.ts

@@ -2,12 +2,12 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 export const PLAN_MODE_QUESTION_TOOL_NAME = "plan_mode_question";
 
-export type PlanModeQuestionOption = {
+type PlanModeQuestionOption = {
 	label: string;
 	description?: string;
 };
 
-export type PlanModeQuestion = {
+type PlanModeQuestion = {
 	id: string;
 	header: string;
 	question: string;
@@ -184,7 +184,7 @@ export async function answerPlanModeQuestions(
 	return planModeQuestionAnswered(questions, answers);
 }
 
-export async function askPlanModeQuestions(
+async function askPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
 	shouldContinue: () => boolean = () => true,
@@ -243,7 +243,7 @@ function formatPlanModeQuestionChoice(option: PlanModeQuestionOption, index: num
 	return `${index + 1}. ${option.label}${option.description ? ` — ${option.description}` : ""}`;
 }
 
-export function planModeQuestionAnswered(
+function planModeQuestionAnswered(
 	questions: PlanModeQuestion[],
 	answers: PlanModeQuestionAnswer[],
 ) {

package/src/settings-menu.ts

@@ -1,4 +1,3 @@
-import { readFile } from "node:fs/promises";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, type RunMenuResult, runMenu } from "@narumitw/pi-tui-kit";
 import { planExportDestination } from "./plan-export.js";
@@ -16,17 +15,13 @@ import {
 interface SettingsMenuState {
 	kind: "valid" | "invalid";
 	settings: PlanModeSettings;
-	notice?: string;
 	reason?: string;
-	/** The removed `thinkingLevel` key is still in the file. legacy: delete in 1.4.0 */
-	hasLegacyThinkingLevel?: boolean;
 }
 
-export interface PlanModeSettingsMenuOptions {
+interface PlanModeSettingsMenuOptions {
 	signal: AbortSignal;
 	isCurrent(): boolean;
 	settingsPath?: string;
-	legacySettingsPath?: string;
 	readSettings?: (settingsPath?: string) => Promise<PlanModeSettingsLoadResult>;
 	updateSettings?: (
 		patch: PlanModeSettingsPatch,
@@ -49,19 +44,9 @@ export async function showPlanModeSettings(
 	const loadState = async (): Promise<SettingsMenuState> => {
 		const loaded = await readSettings(options.settingsPath);
 		if (loaded.kind === "invalid") {
-			return {
-				kind: "invalid",
-				settings: {},
-				notice: loaded.notice,
-				reason: loaded.reason,
-			};
+			return { kind: "invalid", settings: {}, reason: loaded.reason };
 		}
-		return {
-			kind: "valid",
-			settings: loaded.kind === "loaded" ? loaded.settings : {},
-			notice: loaded.notice,
-			hasLegacyThinkingLevel: await hasLegacyThinkingLevel(settingsPath),
-		};
+		return { kind: "valid", settings: loaded.kind === "loaded" ? loaded.settings : {} };
 	};
 
 	const menu = defineMenu<SettingsMenuState, Screen, Action, ExtensionContext>({
@@ -73,7 +58,7 @@ export async function showPlanModeSettings(
 					: {
 							kind: "settings",
 							title: "Plan Mode Settings",
-							lines: settingsLines(settingsPath, state),
+							lines: settingsLines(settingsPath),
 							items: [
 								{
 									id: "defaultPlanExportPath",
@@ -132,11 +117,7 @@ export async function showPlanModeSettings(
 	) {
 		if (signal.aborted || !options.isCurrent()) return { kind: "rejected" as const };
 		try {
-			const saved = await updateSettings(patch, {
-				settingsPath: options.settingsPath,
-				legacySettingsPath: options.legacySettingsPath,
-				signal,
-			});
+			const saved = await updateSettings(patch, { settingsPath: options.settingsPath, signal });
 			if (options.isCurrent()) options.onSaved(saved);
 			if (signal.aborted || !options.isCurrent()) return { kind: "rejected" as const };
 			actionCtx.ui.notify(successMessage, "info");
@@ -153,35 +134,13 @@ export async function showPlanModeSettings(
 	}
 }
 
-function settingsLines(settingsPath: string, state: SettingsMenuState) {
+function settingsLines(settingsPath: string) {
 	return [
 		`User settings · ${safeTerminalText(settingsPath)}`,
 		"The export destination applies to its next action.",
-		// legacy: delete in 1.4.0
-		...(state.hasLegacyThinkingLevel
-			? [
-					"thinkingLevel is no longer used — thinking is a session setting and Plan mode never changes it.",
-				]
-			: []),
-		...(state.notice ? [safeTerminalText(state.notice)] : []),
 	];
 }
 
-/**
- * The removed key is preserved verbatim on save, so the only way to know it is
- * still there is to look at the file. A read failure simply hides the notice.
- *
- * legacy: delete in 1.4.0
- */
-async function hasLegacyThinkingLevel(settingsPath: string) {
-	try {
-		const parsed: unknown = JSON.parse(await readFile(settingsPath, "utf8"));
-		return typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "thinkingLevel");
-	} catch {
-		return false;
-	}
-}
-
 function invalidScreen(settingsPath: string, state: SettingsMenuState) {
 	return {
 		kind: "detail" as const,
@@ -189,7 +148,6 @@ function invalidScreen(settingsPath: string, state: SettingsMenuState) {
 		lines: [
 			`Invalid settings file. Fix ${safeTerminalText(settingsPath)} before saving.`,
 			safeTerminalText(state.reason ?? "The settings file is invalid."),
-			...(state.notice ? [safeTerminalText(state.notice)] : []),
 		],
 		hint: "back" as const,
 	};

package/src/settings-watch.ts

@@ -0,0 +1,60 @@
+import { watch } from "node:fs";
+import { basename, dirname } from "node:path";
+
+interface SettingsWatcherOptions {
+	/** The settings file to follow; its directory is what actually gets watched. */
+	path: string;
+	debounceMs: number;
+	onChange(): void;
+}
+
+/**
+ * Follows one settings file for out-of-band edits.
+ *
+ * The watch is on the 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. One hand-edit or menu save also fans out
+ * into several filesystem events (temp file created, renamed into place), so
+ * `debounceMs` collapses them into a single `onChange`.
+ */
+export function createSettingsWatcher(options: SettingsWatcherOptions) {
+	const watchedFile = basename(options.path);
+	let watcher: ReturnType<typeof watch> | undefined;
+	let reloadTimer: ReturnType<typeof setTimeout> | undefined;
+
+	const stop = () => {
+		if (reloadTimer) {
+			clearTimeout(reloadTimer);
+			reloadTimer = undefined;
+		}
+		watcher?.close();
+		watcher = undefined;
+	};
+
+	return {
+		start() {
+			stop();
+			try {
+				const started = watch(dirname(options.path), { persistent: false }, (event, changed) => {
+					if (event !== "rename" && event !== "change") return;
+					// A null filename means the platform could not name the entry; reload
+					// rather than miss the edit. The directory holds other churn, so a
+					// named entry that is not ours is ignored.
+					if (changed && changed.toString() !== watchedFile) return;
+					if (reloadTimer) clearTimeout(reloadTimer);
+					reloadTimer = setTimeout(() => {
+						reloadTimer = undefined;
+						options.onChange();
+					}, options.debounceMs);
+				});
+				started.on("error", stop);
+				watcher = started;
+			} catch {
+				// An unwatchable directory only costs the live reload; settings still
+				// load at session start.
+				stop();
+			}
+		},
+		stop,
+	};
+}

package/src/settings.ts

@@ -5,7 +5,6 @@ import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export const PLAN_MODE_SETTINGS_FILE = "pi-plan-mode.json";
-const LEGACY_PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
 const MAX_SETTINGS_BYTES = 64 * 1024;
 export const DEFAULT_PLAN_EXPORT_PATH = "PLAN.md";
 const MAX_PLAN_EXPORT_PATH_LENGTH = 4096;
@@ -18,14 +17,13 @@ export interface PlanModeSettingsPatch {
 }
 export interface UpdatePlanModeSettingsOptions {
 	settingsPath?: string;
-	legacySettingsPath?: string;
 	signal?: AbortSignal;
 	beforeRename?: (temporaryPath: string, settingsPath: string) => Promise<void>;
 }
 export type PlanModeSettingsLoadResult =
-	| { kind: "missing"; notice?: string }
-	| { kind: "invalid"; reason: string; notice?: string }
-	| { kind: "loaded"; settings: PlanModeSettings; notice?: string };
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string }
+	| { kind: "loaded"; settings: PlanModeSettings };
 
 type SettingsDocument = Record<string, unknown>;
 type SettingsSnapshot = {
@@ -39,10 +37,6 @@ export function planModeSettingsPath() {
 	return join(getAgentDir(), PLAN_MODE_SETTINGS_FILE);
 }
 
-function legacyPlanModeSettingsPath() {
-	return join(getAgentDir(), LEGACY_PLAN_MODE_SETTINGS_FILE);
-}
-
 /**
  * Unknown top-level keys are tolerated and preserved on save. Settings removed
  * over time (defaultPlanTools, bashPolicy, safeSubcommands,
@@ -80,34 +74,10 @@ function normalizePlanExportPath(value: unknown) {
 }
 
 export async function readPlanModeSettings(
-	settingsPath?: string,
+	settingsPath = planModeSettingsPath(),
 ): Promise<PlanModeSettingsLoadResult> {
-	if (settingsPath) {
-		await awaitPlanModeSettingsWrites(settingsPath);
-		return (await readSettingsSnapshot(settingsPath)).result;
-	}
-	const canonicalPath = planModeSettingsPath();
-	await awaitPlanModeSettingsWrites(canonicalPath);
-	const canonical = await readSettingsSnapshot(canonicalPath);
-	const legacyPath = legacyPlanModeSettingsPath();
-	if (canonical.result.kind !== "missing") {
-		return (await pathExists(legacyPath))
-			? {
-					...canonical.result,
-					notice: `${LEGACY_PLAN_MODE_SETTINGS_FILE} ignored because ${PLAN_MODE_SETTINGS_FILE} takes precedence.`,
-				}
-			: canonical.result;
-	}
-
-	const legacy = await readSettingsSnapshot(legacyPath);
-	const raced = await readSettingsSnapshot(canonicalPath);
-	if (raced.result.kind !== "missing") return raced.result;
-	return legacy.result.kind === "loaded"
-		? {
-				...legacy.result,
-				notice: `Using legacy ${LEGACY_PLAN_MODE_SETTINGS_FILE}; rename it to ${PLAN_MODE_SETTINGS_FILE}. The legacy file was not modified.`,
-			}
-		: legacy.result;
+	await awaitPlanModeSettingsWrites(settingsPath);
+	return (await readSettingsSnapshot(settingsPath)).result;
 }
 
 export function updatePlanModeSettings(
@@ -115,11 +85,9 @@ export function updatePlanModeSettings(
 	options: UpdatePlanModeSettingsOptions = {},
 ): Promise<PlanModeSettings> {
 	const settingsPath = options.settingsPath ?? planModeSettingsPath();
-	const legacySettingsPath =
-		options.legacySettingsPath ?? (options.settingsPath ? undefined : legacyPlanModeSettingsPath());
 	return enqueueMutation(settingsPath, async () => {
 		options.signal?.throwIfAborted();
-		const current = await readSettingsDocumentForUpdate(settingsPath, legacySettingsPath);
+		const current = await readSettingsDocumentForUpdate(settingsPath);
 		const updated: SettingsDocument = { ...current };
 		if (patch.defaultPlanExportPath === null) delete updated.defaultPlanExportPath;
 		else if (patch.defaultPlanExportPath !== undefined) {
@@ -152,27 +120,12 @@ function enqueueMutation<T>(settingsPath: string, mutation: () => Promise<T>): P
 	return result;
 }
 
-async function readSettingsDocumentForUpdate(
-	settingsPath: string,
-	legacySettingsPath: string | undefined,
-): Promise<SettingsDocument> {
-	const canonical = await readSettingsSnapshot(settingsPath);
-	if (canonical.result.kind === "loaded") return canonical.document ?? {};
-	if (canonical.result.kind === "invalid") {
-		throw invalidSettingsError(settingsPath, canonical.result.reason);
-	}
-	if (!legacySettingsPath) return {};
-
-	const legacy = await readSettingsSnapshot(legacySettingsPath);
-	const raced = await readSettingsSnapshot(settingsPath);
-	if (raced.result.kind === "loaded") return raced.document ?? {};
-	if (raced.result.kind === "invalid") {
-		throw invalidSettingsError(settingsPath, raced.result.reason);
-	}
-	if (legacy.result.kind === "invalid") {
-		throw invalidSettingsError(legacySettingsPath, legacy.result.reason);
+async function readSettingsDocumentForUpdate(settingsPath: string): Promise<SettingsDocument> {
+	const snapshot = await readSettingsSnapshot(settingsPath);
+	if (snapshot.result.kind === "invalid") {
+		throw invalidSettingsError(settingsPath, snapshot.result.reason);
 	}
-	return legacy.document ?? {};
+	return snapshot.result.kind === "loaded" ? (snapshot.document ?? {}) : {};
 }
 
 async function readSettingsSnapshot(settingsPath: string): Promise<SettingsSnapshot> {
@@ -264,16 +217,6 @@ function isSettingsDocument(value: unknown): value is SettingsDocument {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function pathExists(path: string) {
-	try {
-		const handle = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
-		await handle.close();
-		return true;
-	} catch (error: unknown) {
-		return !(isNodeError(error) && error.code === "ENOENT");
-	}
-}
-
 function invalidSettingsError(settingsPath: string, reason: string) {
 	return new Error(`pi-plan-mode settings at ${settingsPath} are invalid: ${reason}`);
 }

package/src/state.ts

@@ -39,42 +39,6 @@ function newestStateEntry(entries: unknown[], stateEntryType: string): SessionEn
 	return undefined;
 }
 
-// legacy: delete in 1.4.0
-const LEGACY_THINKING_LEVELS = [
-	"off",
-	"minimal",
-	"low",
-	"medium",
-	"high",
-	"xhigh",
-	"max",
-] as const;
-
-// legacy: delete in 1.4.0
-export type LegacyThinkingCapture = {
-	previous: (typeof LEGACY_THINKING_LEVELS)[number];
-	applied: (typeof LEGACY_THINKING_LEVELS)[number];
-};
-
-/**
- * Reads the thinking-level capture written by pi-plan-mode <= 1.2.1, so a
- * session interrupted while Plan mode held a raised level can have the user's
- * level put back once. Both halves must be present and valid: a partial or
- * absent capture is nothing to repair.
- *
- * legacy: delete in 1.4.0
- */
-export function readLegacyThinkingCapture(
-	entries: unknown[],
-	stateEntryType: string,
-): LegacyThinkingCapture | undefined {
-	const entry = newestStateEntry(entries, stateEntryType);
-	if (!isRecord(entry?.data)) return undefined;
-	const previous = legacyThinkingLevel(entry.data.previousThinkingLevel);
-	const applied = legacyThinkingLevel(entry.data.appliedThinkingLevel);
-	return previous && applied ? { previous, applied } : undefined;
-}
-
 /**
  * Persisted paths are only trusted when they are absolute and free of NUL, so
  * malformed state can never redirect a read or a delete to a relative target.
@@ -86,14 +50,6 @@ function absolutePath(value: unknown) {
 	return normalized;
 }
 
-// legacy: delete in 1.4.0
-function legacyThinkingLevel(value: unknown): (typeof LEGACY_THINKING_LEVELS)[number] | undefined {
-	return typeof value === "string" &&
-		LEGACY_THINKING_LEVELS.includes(value as (typeof LEGACY_THINKING_LEVELS)[number])
-		? (value as (typeof LEGACY_THINKING_LEVELS)[number])
-		: undefined;
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }