@hank-warren/pi-plan-mode 0.1.0 → 1.0.0

package/src/plan-action-controller.ts

@@ -14,9 +14,9 @@ interface PlanActionControllerOptions {
 	getState(): PlanModeState;
 	captureLifecycle(): MenuLifecycle;
 	statusText(): string;
-	implementationOutcome(): string;
+	planPathLine(): string | undefined;
 	getExportDestination(ctx: ExtensionContext): PlanExportDestination;
-	show(ctx: ExtensionContext): void;
+	show(ctx: ExtensionContext): void | Promise<void>;
 	finalize(ctx: ExtensionContext): void;
 	implementHere(ctx: ExtensionContext): void | Promise<void>;
 	implementFresh(ctx: ExtensionContext, isCurrent: () => boolean): void | Promise<void>;
@@ -26,11 +26,8 @@ interface PlanActionControllerOptions {
 		signal: AbortSignal,
 		isCurrent: () => boolean,
 	): Promise<boolean>;
-	settings(ctx: ExtensionContext, signal: AbortSignal, isCurrent: () => boolean): Promise<boolean>;
-	save(ctx: ExtensionContext): void;
 	stay(ctx: ExtensionContext): void;
 	exitReady(ctx: ExtensionContext): void;
-	clearSaved(ctx: ExtensionContext): void;
 }
 
 export function createPlanActionController(options: PlanActionControllerOptions) {
@@ -38,25 +35,6 @@ export function createPlanActionController(options: PlanActionControllerOptions)
 		options.implementFresh(ctx, () => lifecycle.isCurrent() && !signal.aborted);
 
 	return {
-		async showSaved(ctx: ExtensionContext) {
-			const lifecycle = options.captureLifecycle();
-			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
-			const ui = await options.loadInteractiveUi();
-			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
-			await ui.showSavedPlanMenu(ctx, {
-				statusText: options.statusText(),
-				implementationOutcome: options.implementationOutcome,
-				getExportDestination: () => options.getExportDestination(ctx),
-				signal: lifecycle.signal,
-				isCurrent: lifecycle.isCurrent,
-				show: () => options.show(ctx),
-				implementHere: () => options.implementHere(ctx),
-				implementFresh: (signal) => freshAction(ctx, lifecycle, signal),
-				exportPlan: (path, signal) => options.exportPlan(ctx, path, signal, lifecycle.isCurrent),
-				settings: (signal) => options.settings(ctx, signal, lifecycle.isCurrent),
-				clear: () => options.clearSaved(ctx),
-			});
-		},
 		async showCurrent(ctx: ExtensionContext) {
 			if (!ctx.hasUI) {
 				ctx.ui.notify(options.statusText(), "info");
@@ -68,8 +46,8 @@ export function createPlanActionController(options: PlanActionControllerOptions)
 			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
 			await ui.showPlanModeMenu(ctx, {
 				statusText: options.statusText(),
-				hasReadyPlan: options.getState().latestPlan !== undefined,
-				implementationOutcome: options.implementationOutcome,
+				hasReadyPlan: options.getState().awaitingAction,
+				planPathLine: options.planPathLine(),
 				getExportDestination: () => options.getExportDestination(ctx),
 				...lifecycle,
 				show: () => options.show(ctx),
@@ -77,7 +55,6 @@ export function createPlanActionController(options: PlanActionControllerOptions)
 				implementHere: () => options.implementHere(ctx),
 				implementFresh: (signal) => freshAction(ctx, lifecycle, signal),
 				exportPlan: (path, signal) => options.exportPlan(ctx, path, signal, lifecycle.isCurrent),
-				save: () => options.save(ctx),
 				stay: () => options.stay(ctx),
 				exit: () => options.exitReady(ctx),
 			});
@@ -89,12 +66,11 @@ export function createPlanActionController(options: PlanActionControllerOptions)
 			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
 			await ui.showReadyPlanMenu(ctx, {
 				...lifecycle,
-				implementationOutcome: options.implementationOutcome,
+				planPathLine: options.planPathLine(),
 				getExportDestination: () => options.getExportDestination(ctx),
 				implementHere: () => options.implementHere(ctx),
 				implementFresh: (signal) => freshAction(ctx, lifecycle, signal),
 				exportPlan: (path, signal) => options.exportPlan(ctx, path, signal, lifecycle.isCurrent),
-				save: () => options.save(ctx),
 				stay: () => undefined,
 				exit: () => options.exitReady(ctx),
 			});

package/src/plan-action-menus.ts

@@ -9,20 +9,19 @@ interface MenuLifecycle {
 
 const IMPLEMENTATION_CONTEXT_LINES = [
 	"Implement here keeps this planning conversation.",
-	"Start fresh transfers only the approved plan to a new session.",
+	"Start fresh opens a new session that reads the same plan file.",
 ] as const;
 
 interface PlanMenuOptions extends MenuLifecycle {
 	statusText: string;
 	hasReadyPlan: boolean;
-	implementationOutcome(): string;
+	planPathLine?: string;
 	getExportDestination: PlanExportDestinationProvider;
-	show(): void;
+	show(): void | Promise<void>;
 	finalize(): void;
 	implementHere(): void | Promise<void>;
 	implementFresh(signal: AbortSignal): void | Promise<void>;
 	exportPlan(path: string, signal: AbortSignal): Promise<boolean>;
-	save(): void;
 	stay(): void;
 	exit(): void;
 }
@@ -35,7 +34,6 @@ export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuO
 		| "implement-here"
 		| "implement-fresh"
 		| "export"
-		| "save"
 		| "stay"
 		| "exit";
 	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
@@ -47,7 +45,10 @@ export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuO
 				lines: [
 					options.statusText,
 					...(options.hasReadyPlan
-						? [...IMPLEMENTATION_CONTEXT_LINES, options.implementationOutcome()]
+						? [
+								...IMPLEMENTATION_CONTEXT_LINES,
+								...(options.planPathLine ? [options.planPathLine] : []),
+							]
 						: []),
 				],
 				items: options.hasReadyPlan
@@ -62,12 +63,11 @@ export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuO
 							{
 								id: "implement-fresh",
 								label: "Start fresh and implement",
-								description: "Open a new linked session; transfer only the approved plan.",
+								description: "Open a new linked session that reads the same plan file.",
 								action: "implement-fresh",
 								busyLabel: "Starting fresh implementation session…",
 							},
 							{ id: "export", label: "Export plan…", to: "export" },
-							{ id: "save", label: "Save for later", action: "save" },
 							{ id: "stay", label: "Stay in Plan mode", action: "stay" },
 							{ id: "exit", label: "Discard plan and exit", action: "exit" },
 						]
@@ -82,7 +82,7 @@ export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuO
 		},
 		actions: {
 			show: async () => {
-				options.show();
+				await options.show();
 				return { kind: "close" };
 			},
 			finalize: async () => {
@@ -99,10 +99,6 @@ export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuO
 			},
 			export: async ({ value, signal }) =>
 				(await options.exportPlan(value ?? "", signal)) ? { kind: "close" } : { kind: "rejected" },
-			save: async () => {
-				options.save();
-				return { kind: "close" };
-			},
 			stay: async () => {
 				options.stay();
 				return { kind: "close" };
@@ -121,26 +117,28 @@ export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuO
 }
 
 interface ReadyPlanMenuOptions extends MenuLifecycle {
-	implementationOutcome(): string;
+	planPathLine?: string;
 	getExportDestination: PlanExportDestinationProvider;
 	implementHere(): void | Promise<void>;
 	implementFresh(signal: AbortSignal): void | Promise<void>;
 	exportPlan(path: string, signal: AbortSignal): Promise<boolean>;
-	save(): void;
 	stay(): void;
 	exit(): void;
 }
 
 export async function showReadyPlanMenu(ctx: ExtensionContext, options: ReadyPlanMenuOptions) {
 	type Screen = "ready" | "export";
-	type Action = "implement-here" | "implement-fresh" | "export" | "save" | "stay" | "exit";
+	type Action = "implement-here" | "implement-fresh" | "export" | "stay" | "exit";
 	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
 		start: "ready",
 		screens: {
 			ready: () => ({
 				kind: "actions",
 				title: "Proposed plan ready. What next?",
-				lines: [...IMPLEMENTATION_CONTEXT_LINES, options.implementationOutcome()],
+				lines: [
+					...IMPLEMENTATION_CONTEXT_LINES,
+					...(options.planPathLine ? [options.planPathLine] : []),
+				],
 				items: [
 					{
 						id: "implement-here",
@@ -151,12 +149,11 @@ export async function showReadyPlanMenu(ctx: ExtensionContext, options: ReadyPla
 					{
 						id: "implement-fresh",
 						label: "Start fresh and implement",
-						description: "Open a new linked session; transfer only the approved plan.",
+						description: "Open a new linked session that reads the same plan file.",
 						action: "implement-fresh",
 						busyLabel: "Starting fresh implementation session…",
 					},
 					{ id: "export", label: "Export plan…", to: "export" },
-					{ id: "save", label: "Save for later", action: "save" },
 					{ id: "stay", label: "Stay in Plan mode", action: "stay" },
 					{ id: "exit", label: "Discard plan and exit", action: "exit" },
 				],
@@ -175,10 +172,6 @@ export async function showReadyPlanMenu(ctx: ExtensionContext, options: ReadyPla
 			},
 			export: async ({ value, signal }) =>
 				(await options.exportPlan(value ?? "", signal)) ? { kind: "close" } : { kind: "rejected" },
-			save: async () => {
-				options.save();
-				return { kind: "close" };
-			},
 			stay: async () => {
 				options.stay();
 				return { kind: "close" };

package/src/plan-export.ts

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { type ExtensionContext, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { readPlanFile } from "./plan-file.js";
 import { DEFAULT_PLAN_EXPORT_PATH } from "./settings.js";
 import type { PlanModeState } from "./state.js";
 
@@ -23,6 +24,10 @@ export interface PlanExportLifecycle {
 	finishReady?(): void;
 }
 
+/**
+ * Export copies the durable plan file to a user-chosen path. The plan is read
+ * from disk at export time, so a hand-edited plan exports as edited.
+ */
 export async function exportStoredPlan(
 	state: PlanModeState,
 	requestedPath: string | undefined,
@@ -30,10 +35,7 @@ export async function exportStoredPlan(
 	lifecycle?: PlanExportLifecycle,
 	defaultPath = DEFAULT_PLAN_EXPORT_PATH,
 ) {
-	const plan =
-		(state.enabled ? state.latestPlan : undefined)?.trim() ??
-		state.savedPlan?.plan.trim() ??
-		state.activeImplementation?.plan.trim();
+	const plan = state.planPath ? await readPlanFile(state.planPath) : undefined;
 	if (!plan) {
 		const error = new Error(
 			"No completed plan is available to export. Use /plan finalize when planning is complete.",
@@ -65,8 +67,7 @@ export async function exportStoredPlan(
 	}
 
 	if (!isCurrent()) return false;
-	const finishedReady =
-		state.enabled && Boolean(state.latestPlan?.trim()) && lifecycle?.finishReady !== undefined;
+	const finishedReady = state.enabled && state.awaitingAction && lifecycle?.finishReady !== undefined;
 	if (finishedReady) lifecycle.finishReady?.();
 	const detail = finishedReady ? " Plan mode disabled." : "";
 	ctx.ui.notify(safeNotification(`Plan exported to ${result.path}.${detail}`), "info");
@@ -82,12 +83,13 @@ export async function exportPlanToFile(
 	defaultPath = DEFAULT_PLAN_EXPORT_PATH,
 ): Promise<PlanExportResult> {
 	const path = resolvePlanExportPath(requestedPath, cwd, defaultPath);
+	const contents = plan.endsWith("\n") ? plan : `${plan}\n`;
 	await withFileMutationQueue(path, async () => {
 		throwIfCancelled(signal, isCurrent);
 		await mkdir(dirname(path), { recursive: true });
 		throwIfCancelled(signal, isCurrent);
 		try {
-			await writeFile(path, `${plan}\n`, { encoding: "utf8", flag: "wx" });
+			await writeFile(path, contents, { encoding: "utf8", flag: "wx" });
 		} catch (error: unknown) {
 			if (isNodeError(error) && error.code === "EEXIST") {
 				throw new Error(

package/src/plan-file.ts

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+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 MAX_PLAN_BYTES = 1024 * 1024;
+
+/**
+ * The durable plan file is the plan. Session state stores only its path, so a
+ * plan survives compaction, resume, and hand-editing without ever being copied
+ * into model context.
+ */
+export function plansDirectory() {
+	return join(getAgentDir(), PLANS_DIRECTORY);
+}
+
+/**
+ * Session ids come from Pi and are normally uuid-like, but they reach a
+ * filesystem path here: constrain them to a safe basename so a hostile or
+ * unusual id cannot escape the plans directory.
+ */
+export function planFilePathForSession(sessionId: string | undefined) {
+	return join(plansDirectory(), `${safeSessionSegment(sessionId)}.md`);
+}
+
+function safeSessionSegment(sessionId: string | undefined) {
+	const normalized = (sessionId ?? "").trim().replace(/[^\w.-]/gu, "-");
+	const trimmed = normalized.replace(/^[.-]+/u, "").slice(0, 128);
+	// In-memory sessions have no id; fall back to a stable per-process name so
+	// the plan still persists for the lifetime of the session.
+	return trimmed || `session-${process.pid}`;
+}
+
+/**
+ * Atomic same-directory temp + rename, matching how settings are published, so
+ * a concurrent reader never observes a partially written plan.
+ */
+export async function writePlanFile(path: string, plan: string): Promise<void> {
+	const contents = plan.endsWith("\n") ? plan : `${plan}\n`;
+	if (Buffer.byteLength(contents, "utf8") > MAX_PLAN_BYTES) {
+		throw new Error(`plan exceeds ${MAX_PLAN_BYTES} bytes`);
+	}
+	const directory = dirname(path);
+	await mkdir(directory, { recursive: true });
+	const temporaryPath = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+	try {
+		await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
+		await rename(temporaryPath, path);
+	} finally {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+}
+
+/**
+ * Always read from disk. The user may hand-edit the plan while implementation
+ * is under way, and that edit must be what the agent and every command see.
+ */
+export async function readPlanFile(path: string): Promise<string | undefined> {
+	let handle: Awaited<ReturnType<typeof open>>;
+	try {
+		handle = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+	} catch {
+		return undefined;
+	}
+	try {
+		const stats = await handle.stat();
+		if (!stats.isFile() || stats.size > MAX_PLAN_BYTES) return undefined;
+		const contents = await handle.readFile({ encoding: "utf8" });
+		return contents.trim() ? contents : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		await handle.close().catch(() => 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,116 +1,56 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export interface PlanLaunchTool {
-	name: string;
-	description: string;
-	searchText: string;
-	disabled: boolean;
-	disabledReason?: string;
-}
-
-interface PlanLaunchMenuOptions {
+export interface PlanLaunchMenuOptions {
 	statusText: string;
-	toolSummary(selectedNames: ReadonlySet<string>): string;
-	getSelectedNames(): ReadonlySet<string>;
-	tools: readonly PlanLaunchTool[];
 	signal: AbortSignal;
 	isCurrent(): boolean;
-	initialScreen?: "main" | "tools";
 	start(signal: AbortSignal): void;
-	startWithTools(toolNames: string[], signal: AbortSignal): void;
 	settings(signal: AbortSignal): Promise<boolean>;
 }
 
+const HOW_IT_WORKS_LINES = [
+	"Plan mode is for research and design, not implementation.",
+	"Explore the codebase, ask decision questions, then finish with plan_mode_complete.",
+	"The plan is written to a durable file that survives compaction and can be hand-edited.",
+	"Built-in edit, write, and update_plan are blocked while planning.",
+	"All other tools stay exactly as configured; command safety is left to your permission extension.",
+	"When the plan is ready: implement here, or start a fresh session that reads the same file.",
+] as const;
+
 export async function showPlanLaunchMenu(ctx: ExtensionContext, options: PlanLaunchMenuOptions) {
-	type Screen = "main" | "tools" | "help";
-	type Action = "start" | "toggle-tool" | "start-with-tools" | "settings";
-	const selectedNames = new Set(options.getSelectedNames());
-	let draftChanged = false;
+	type Screen = "main" | "how";
+	type Action = "start" | "settings";
 	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
-		start: options.initialScreen ?? "main",
+		start: "main",
 		screens: {
 			main: () => ({
 				kind: "actions",
 				title: "Plan mode",
-				lines: [options.statusText, options.toolSummary(selectedNames)],
+				lines: [options.statusText],
 				items: [
 					{ id: "start", label: "Start Plan mode", action: "start" },
-					{ id: "tools", label: "Choose tools, then start…", to: "tools" },
 					{ id: "settings", label: "Settings", action: "settings" },
-					{ id: "help", label: "How Plan mode works", to: "help" },
+					{ id: "how", label: "How Plan mode works", to: "how" },
 				],
 				hint: "close",
 			}),
-			tools: () => ({
-				kind: "multiSelect",
-				title: "Choose Plan-mode tools",
-				lines: [
-					"Changes apply only when you start Plan mode.",
-					"Non-built-in tools run at user risk.",
-				],
-				enableSearch: true,
-				viewportSize: 10,
-				items: options.tools.map((tool) => ({
-					id: tool.name,
-					label: tool.name,
-					description: tool.description,
-					searchText: tool.searchText,
-					selected: selectedNames.has(tool.name),
-					disabled: tool.disabled,
-					disabledReason: tool.disabledReason,
-				})),
-				action: "toggle-tool",
-				actions: [
-					{
-						id: "start-with-tools",
-						label: "Done — start Plan mode",
-						action: "start-with-tools",
-					},
-				],
-				hint: "back",
-			}),
-			help: () => ({
+			how: () => ({
 				kind: "detail",
 				title: "How Plan mode works",
-				lines: [
-					"Plan mode uses read-only exploration to understand the project before implementation.",
-					"The agent can ask important decision questions, then returns a complete implementation-ready plan.",
-					"File mutation stays blocked until you explicitly choose to implement the completed plan.",
-				],
+				lines: [...HOW_IT_WORKS_LINES],
 				hint: "back",
 			}),
 		},
 		actions: {
 			start: async ({ signal }) => {
-				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
 				options.start(signal);
 				return { kind: "close" };
 			},
-			"toggle-tool": async ({ itemId, selected, signal }) => {
-				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
-				const tool = options.tools.find((candidate) => candidate.name === itemId);
-				if (!tool || tool.disabled) return { kind: "rejected" };
-				if (selected) selectedNames.add(tool.name);
-				else selectedNames.delete(tool.name);
-				draftChanged = true;
-				return { kind: "stay" };
-			},
-			"start-with-tools": async ({ signal }) => {
-				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
-				options.startWithTools(Array.from(selectedNames), signal);
-				return { kind: "close" };
-			},
 			settings: async ({ signal }) => {
-				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
 				const close = await options.settings(signal);
 				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
-				if (close) return { kind: "close" };
-				if (!draftChanged) {
-					selectedNames.clear();
-					for (const name of options.getSelectedNames()) selectedNames.add(name);
-				}
-				return { kind: "stay" };
+				return close ? { kind: "close" } : { kind: "stay" };
 			},
 		},
 	});