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

package/src/presentation.ts

@@ -1,10 +1,59 @@
-import { Text } from "@earendil-works/pi-tui";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import {
+	getMarkdownTheme,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { readPlanFile } from "./plan-file.js";
 import type { PlanModeState } from "./state.js";
 
 const STATUS_KEY = "plan-mode";
 const PLAN_WIDGET_KEY = "plan-mode-plan";
+export const PLAN_CARD_ENTRY_TYPE = "plan-mode-card";
+
+type PlanCardData = { title: string; plan: string };
+
+/**
+ * Persisted entry data is input, not a guarantee.
+ *
+ * The renderer runs against whatever is on disk, which may predate a field, be
+ * truncated by a partial write, or have been hand-edited. Pi contains a
+ * renderer throw as an inline `[plan-mode-card] renderer failed: …` box —
+ * survivable, but a needlessly ugly way to say "this card is old".
+ */
+function planCardData(value: unknown): PlanCardData | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const { title, plan } = value as { title?: unknown; plan?: unknown };
+	return typeof title === "string" && typeof plan === "string"
+		? (value as PlanCardData)
+		: undefined;
+}
+
+/**
+ * The completed-plan card, as a display-only session entry.
+ *
+ * A custom *entry* rather than a message, which is what buys the property a
+ * message could not: Pi maps a `custom` entry to no context messages at all
+ * and skips it during compaction, so the plan stays visible and restorable in
+ * the transcript while never entering model context and never costing a
+ * compaction budget. The model gets a one-line `Plan saved to <path>.` from
+ * `plan_mode_complete` instead, and reads the durable file when it implements.
+ *
+ * pi-loop's approval card is the same mechanism for the same reason
+ * (`packages/pi-loop/src/presentation.ts`).
+ */
+export function registerPlanModeCardRenderer(pi: ExtensionAPI): void {
+	pi.registerEntryRenderer(PLAN_CARD_ENTRY_TYPE, (entry) => {
+		const data = planCardData(entry.data);
+		if (!data) return new Text("Plan card unavailable.", 0, 0);
+		return new Markdown(
+			`**${data.title}**\n\n${data.plan}`,
+			0,
+			0,
+			getMarkdownTheme(),
+		);
+	});
+}
 
 /**
  * The one thing both surfaces render.
@@ -20,9 +69,9 @@ const PLAN_WIDGET_KEY = "plan-mode-plan";
  * 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;
@@ -152,14 +201,7 @@ export function showPlanModePlan(
 	plan: string,
 ) {
 	try {
-		pi.sendMessage(
-			{
-				customType: "proposed-plan",
-				content: `**${title}**\n\n${plan}`,
-				display: true,
-			},
-			{ triggerTurn: false },
-		);
+		pi.appendEntry<PlanCardData>(PLAN_CARD_ENTRY_TYPE, { title, plan });
 	} catch (error: unknown) {
 		const detail = error instanceof Error ? error.message : String(error);
 		ctx.ui.notify(`Unable to show completed plan: ${detail}`, "error");

package/src/prompt.ts

@@ -41,9 +41,29 @@ const QUESTION_TOOL_PROFILES: Record<string, QuestionToolProfile> = {
  *
  * The default keeps the exported function callable with no arguments and keeps
  * a standalone `pi-plan-mode` install reading exactly as it did before.
+ *
+ * Passing `null` builds the headless variant: no interactive question tool is
+ * active in that session, so naming one would tell the model to call a tool it
+ * cannot see. It asks in plain text instead.
  */
-export function buildPlanModePrompt(questionTool: string = PLAN_MODE_QUESTION_TOOL) {
-	const tool = QUESTION_TOOL_PROFILES[questionTool] ?? QUESTION_TOOL_PROFILES[PLAN_MODE_QUESTION_TOOL];
+export function buildPlanModePrompt(questionTool: string | null = PLAN_MODE_QUESTION_TOOL) {
+	const tool =
+		questionTool === null
+			? undefined
+			: (QUESTION_TOOL_PROFILES[questionTool] ??
+				QUESTION_TOOL_PROFILES[PLAN_MODE_QUESTION_TOOL]);
+	const askBullet = tool
+		? `Use ${tool.name} for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. ${tool.bounds} Do not include filler options.`
+		: "This session has no interactive question tool, so ask in plain text: put important preferences, tradeoffs, or assumption locks that non-mutating exploration cannot settle in your reply as 1-3 concise questions with 2-4 meaningful options each. Do not include filler options, and never call a question tool that is not in your tool set.";
+	const declineBullet = tool
+		? `${tool.decline}, do not jump straight to a final plan when the missing answer is high impact. Ask one concise plain-text question or proceed only with a clearly stated low-risk assumption.`
+		: "If the question goes unanswered, do not jump straight to a final plan when the missing answer is high impact. Ask it again more concisely, or proceed only with a clearly stated low-risk assumption recorded in the plan.";
+	const endingBullet = tool
+		? `If a material decision remains, use ${tool.name}. If interactive UI is unavailable, ask one concise plain-text question instead.`
+		: "If a material decision remains, ask one concise plain-text question instead.";
+	const revisionClause = tool
+		? `continue planning with ${tool.name} instead of calling plan_mode_complete`
+		: "continue planning with a plain-text question instead of calling plan_mode_complete";
 	return `${PLAN_CONTEXT_MARKER}
 # Plan Mode (Conversational)
 
@@ -73,14 +93,14 @@ You are in Plan Mode, a collaboration mode for producing a decision-complete imp
 ## Phase 3 — Implementation chat
 
 - Once intent is stable, keep asking until the spec is decision-complete: approach, interfaces, data flow, edge cases/failure modes, testing and acceptance criteria, and any migration or compatibility constraints.
-- Use ${tool.name} for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. ${tool.bounds} Do not include filler options.
-- ${tool.decline}, do not jump straight to a final plan when the missing answer is high impact. Ask one concise plain-text question or proceed only with a clearly stated low-risk assumption.
+- ${askBullet}
+- ${declineBullet}
 
 ## Ending each turn
 
 Every Plan-mode turn that advances or finalizes the plan must end in exactly one of these ways:
 
-- If a material decision remains, use ${tool.name}. If interactive UI is unavailable, ask one concise plain-text question instead.
+- ${endingBullet}
 - If the implementation plan is decision-complete, call plan_mode_complete alone as your final action. Do not call other tools in the same batch and do not emit a normal assistant response after it.
 
 If a follow-up asks only for clarification and does not change or challenge the plan, answer it directly, then call plan_mode_complete alone as the final action with the complete unchanged plan so it remains available for implementation.
@@ -101,7 +121,7 @@ Keep the plan concise, human and agent digestible, and free of open decisions. P
 
 The plan is saved to a durable file, so it survives compaction and can be re-read at any time.
 
-If the user requests revisions after a completed plan, the next plan_mode_complete call must contain a complete replacement, not a delta. If there is not enough information for a complete replacement, continue planning with ${tool.name} instead of calling plan_mode_complete.`;
+If the user requests revisions after a completed plan, the next plan_mode_complete call must contain a complete replacement, not a delta. If there is not enough information for a complete replacement, ${revisionClause}.`;
 }
 
 /**

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;
@@ -152,11 +152,13 @@ export async function answerPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
 	lifecycle: { isCurrent(): boolean; isEnabled(): boolean },
+	signal?: AbortSignal,
 ) {
 	const answers = await askPlanModeQuestions(
 		questions,
 		ctx,
-		() => lifecycle.isCurrent() && lifecycle.isEnabled(),
+		() => lifecycle.isCurrent() && lifecycle.isEnabled() && !signal?.aborted,
+		signal,
 	);
 	if (!lifecycle.isCurrent()) {
 		return planModeQuestionCancelled(
@@ -182,22 +184,26 @@ export async function answerPlanModeQuestions(
 	return planModeQuestionAnswered(questions, answers);
 }
 
-export async function askPlanModeQuestions(
+async function askPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
 	shouldContinue: () => boolean = () => true,
+	signal?: AbortSignal,
 ): Promise<PlanModeQuestionAnswer[] | undefined> {
 	const answers: PlanModeQuestionAnswer[] = [];
 	for (const question of questions) {
+		if (!shouldContinue() || signal?.aborted) return undefined;
 		const choices = question.options.map(formatPlanModeQuestionChoice);
 		const otherChoice = `${question.options.length + 1}. Other (free-form)`;
-		const choice = await ctx.ui.select(`${question.header}: ${question.question}`, [
-			...choices,
-			otherChoice,
-		]);
+		const choice = await raceWithAbort(
+			ctx.ui.select(`${question.header}: ${question.question}`, [...choices, otherChoice]),
+			signal,
+		);
 		if (!shouldContinue() || !choice) return undefined;
 		if (choice === otherChoice) {
-			const customAnswer = (await ctx.ui.editor(question.question, ""))?.trim();
+			const customAnswer = (
+				await raceWithAbort(ctx.ui.editor(question.question, ""), signal)
+			)?.trim();
 			if (!shouldContinue() || !customAnswer) return undefined;
 			answers.push({
 				id: question.id,
@@ -223,11 +229,21 @@ export async function askPlanModeQuestions(
 	return answers;
 }
 
+async function raceWithAbort<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T | undefined> {
+	if (!signal) return operation;
+	if (signal.aborted) return undefined;
+	return new Promise<T | undefined>((resolve, reject) => {
+		const abort = () => resolve(undefined);
+		signal.addEventListener("abort", abort, { once: true });
+		operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
 function formatPlanModeQuestionChoice(option: PlanModeQuestionOption, index: number) {
 	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);
 }