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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @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
+
+- c079c51: Keep the completed plan out of model context, stage the Plan tools, and fail honestly when a plan cannot be saved.
+
+  The completed-plan card is a display-only session entry rendered through `registerEntryRenderer` instead of a message, so the plan stays visible and restorable in the transcript while never entering model context or compaction. `plan_mode_complete` returns a one-line `Plan saved to <path>.` pointer; the durable file remains the handoff.
+
+  `plan_mode_complete` now writes the file first and throws when the write fails, rather than reporting success and returning `undefined`. Prior state stays intact and the call is retryable.
+
+  `plan_mode_complete` and the `plan_mode_question` fallback activate when Plan mode is entered or restored, so a session that never plans does not carry their schemas. Ownership of `ask_user_question` is resolved by package directory and read back from the host rather than assumed from the write, and every reconcile is announced on an event, so the fallback no longer depends on hook order between packages. A headless run has no legitimate question tool, so the prompt and the finalize steer switch to a plain-text variant instead of naming a tool that both packages strip.
+
+  `AbortSignal` is wired through the question tool with exactly-once cleanup.
+
 ## 1.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.4.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 ||
@@ -57,7 +57,12 @@ export function planFromCompletionDetails(value: unknown) {
 
 export function planModeCompleted(plan: string, planPath?: string) {
 	return {
-		content: [{ type: "text" as const, text: `**Proposed Plan**\n\n${plan}` }],
+		content: [
+			{
+				type: "text" as const,
+				text: planPath ? `Plan saved to ${planPath}.` : "Plan saved.",
+			},
+		],
 		details: {
 			version: PLAN_MODE_COMPLETE_VERSION,
 			source: PLAN_MODE_COMPLETE_TOOL_NAME,
@@ -73,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;