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

package/src/plan-mode.ts

@@ -1,5 +1,3 @@
-import { watch } from "node:fs";
-import { basename, dirname } from "node:path";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -13,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,10 +47,25 @@ 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";
+/** Label Herdr shows while `plan_mode_question` waits; distinguishes it from an approval. */
+export const HERDR_BLOCKED_LABEL = "plan question";
+
+/**
+ * Tell Herdr this pane is waiting on a human, so a supervising agent in another
+ * pane sees the block instead of reading a stalled turn as progress. Same
+ * contract as pi-auto-permissions' `setHerdrBlocked`, duplicated rather than
+ * imported so Plan Mode has no dependency on the permissions engine. No-op
+ * outside Herdr.
+ */
+function setHerdrBlocked(pi: ExtensionAPI, active: boolean): void {
+	if (process.env.HERDR_ENV !== "1") return;
+	pi.events.emit("herdr:blocked", active ? { active: true, label: HERDR_BLOCKED_LABEL } : { active: false });
+}
 /**
  * Plan mode's entire enforcement surface. Everything else — bash, subagents,
  * MCP, and other extension tools — is left to the session's normal permission
@@ -67,11 +77,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 +121,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 +169,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 +182,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,19 +230,15 @@ 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,
+					isCurrent: menu.isCurrent,
 					isEnabled: () => state.enabled,
+					onBlocked: (active) => setHerdrBlocked(pi, active),
 				},
 				questionSignal,
 			);
@@ -288,7 +285,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 +306,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 +319,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 +357,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 +409,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 +444,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 +479,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 +555,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 +596,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 +626,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 +671,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/prompt.ts

@@ -1,3 +1,25 @@
+import { join } from "node:path";
+
+/**
+ * The plan-craft document: what decision-complete means, why exploration comes
+ * before questions, what separates a question worth asking from one the
+ * repository already answers, and what a finished plan contains.
+ *
+ * It used to ship as a skill. A skill buys one thing an injected pointer
+ * cannot: a description line in every system prompt, so the model could
+ * propose planning unprompted. Across ~220 sessions after it shipped, every
+ * read of the file happened after the Plan Mode prompt was already active —
+ * never off the description — and the model never suggested `/plan` on its
+ * own. So the line was a tax on every session that never planned (~95% of
+ * them) and bought nothing. An absolute path, injected only while Plan Mode
+ * is active, is the same document at zero cost outside it, and a hard path
+ * beats "if it is available".
+ *
+ * Resolved from this module's own location so it survives every install
+ * layout (git, npm, workspace symlink, `npm link`).
+ */
+export const PLAN_CRAFT_DOC = join(import.meta.dirname, "..", "docs", "plan-craft.md");
+
 const PLAN_CONTEXT_MARKER = "[PLAN MODE ACTIVE]";
 
 /** The built-in question tool. Used whenever nothing better is installed. */
@@ -71,7 +93,7 @@ You are in Plan Mode, a collaboration mode for producing a decision-complete imp
 
 ## Mode rules
 
-- Read the pi-plan-mode skill before planning if it is available: it carries the plan-crafting craft — decision-completeness, exploring before asking, question quality, and what a finished plan contains.
+- Before planning, read ${PLAN_CRAFT_DOC}: it carries the plan-crafting craft — decision-completeness, exploring before asking, question quality, and what a finished plan contains.
 - Stay in Plan Mode until a developer or extension explicitly exits it.
 - Treat requests to implement as requests to plan the implementation; do not edit files or carry out the plan.
 - Do not use todo/checklist tooling to track execution progress in Plan Mode; Plan Mode is conversational planning, and the plan itself belongs in plan_mode_complete.

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;
@@ -151,15 +151,32 @@ export function normalizePlanModeQuestionParams(
 export async function answerPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
-	lifecycle: { isCurrent(): boolean; isEnabled(): boolean },
+	lifecycle: {
+		isCurrent(): boolean;
+		isEnabled(): boolean;
+		/**
+		 * Called with `true` while a selector is open and `false` once it closes,
+		 * however it closes. plan-mode.ts forwards this to Herdr so a supervising
+		 * agent in another pane sees "blocked on a human", not "working".
+		 */
+		onBlocked?(active: boolean): void;
+	},
 	signal?: AbortSignal,
 ) {
-	const answers = await askPlanModeQuestions(
-		questions,
-		ctx,
-		() => lifecycle.isCurrent() && lifecycle.isEnabled() && !signal?.aborted,
-		signal,
-	);
+	lifecycle.onBlocked?.(true);
+	let answers: PlanModeQuestionAnswer[] | undefined;
+	try {
+		answers = await askPlanModeQuestions(
+			questions,
+			ctx,
+			() => lifecycle.isCurrent() && lifecycle.isEnabled() && !signal?.aborted,
+			signal,
+		);
+	} finally {
+		// In `finally` so a throw or a session replacement never leaves Herdr
+		// believing this pane is still waiting on someone.
+		lifecycle.onBlocked?.(false);
+	}
 	if (!lifecycle.isCurrent()) {
 		return planModeQuestionCancelled(
 			questions,
@@ -184,7 +201,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 +260,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[],
 ) {