pi-plans 0.1.0 → 0.1.2

package/tests/exec.test.ts

@@ -7,44 +7,126 @@ import * as path from "node:path";
 import { after, before, describe, it } from "node:test";
 import {
 	applyDoneMarkers,
+	applyImplMarkers,
+	buildExecutionCompactionResult,
+	buildPlanningCompactionResult,
 	completeExecution,
+	consumePendingExecutionFlush,
+	consumePlanningCompactionResumeGuard,
 	consumePendingPanelSync,
+	drainExecutionFlush,
 	executionContextMessage,
+	filterExecutionResumeMessages,
+	filterPlanningResumeMessages,
 	getExecution,
+	handleExecutionBeforeCompact,
+	handleExecutionCompact,
+	handleExecutionCompactFailed,
+	handlePlanningBeforeCompact,
+	handlePlanningCompact,
+	handlePlanningCompactFailed,
 	isExecutionComplete,
+	PLANNING_PLAN_WRITTEN_CUSTOM_TYPE,
+	PLANNING_RUN_START_CUSTOM_TYPE,
+	refreshPlanningCompactionCooldown,
+	requestPlanningCompaction,
 	restoreFromSession,
+	shouldTriggerPlanningCompaction,
+	ensureExecutionModelActive,
 	startExecution,
+	recordExecutionTurn,
+	registerExecutionTurnHandlers,
 	stopExecution,
+	chooseExecutionModelSelection,
 	toggleExecutionPanelView,
+	updateStatusWidget,
 } from "../src/exec.ts";
 import type { CheckItem } from "../src/plan.ts";
+import { initState, setExecutionModel, setRunStatus, showConfig, startRun } from "../src/state.ts";
 
 interface Recorded {
 	entries: { type: string; customType?: string; data?: unknown }[];
-	messages: { customType: string; content: string }[];
+	messages: { customType: string; content: string; options?: { triggerTurn?: boolean } }[];
 	status: string | undefined;
+	statusCalls: number;
+	colors: string[];
 	widget?: { key: string; options?: unknown; factory: any };
 	widgetCalls: number;
+	models: { provider: string; id: string }[];
+	thinkingLevels: (string | null)[];
+	notifies: { message: string; severity: string }[];
+	selects: { title: string; options: string[] }[];
+	selectAnswer?: string;
+	current: { provider: string; id: string } | null;
+	thinking: string | null;
+	compacts?: { customInstructions?: string }[];
 }
 
 interface Harness {
 	pi: any;
 	ctx: any;
 	recorded: Recorded;
+	emit: (eventName: string, event: unknown) => Promise<unknown[]>;
 }
 
 function makeHarness(workdir: string): Harness {
-	const recorded: Recorded = { entries: [], messages: [], status: undefined, widgetCalls: 0 };
+	const recorded: Recorded = {
+		entries: [],
+		messages: [],
+		status: undefined,
+		statusCalls: 0,
+		colors: [],
+		widgetCalls: 0,
+		models: [],
+		thinkingLevels: [],
+		notifies: [],
+		selects: [],
+		current: { provider: "p", id: "m" },
+		thinking: "high",
+	};
+	let contextPercent: number | null = 0;
+	const registryModels = [
+		{ provider: "p", id: "m" },
+		{ provider: "prov", id: "other" },
+	];
+	const handlers = new Map<string, Array<(event: unknown, ctx: any) => unknown>>();
+	const emit = async (eventName: string, event: unknown): Promise<unknown[]> => {
+		const results: unknown[] = [];
+		for (const handler of handlers.get(eventName) ?? []) {
+			results.push(await handler(event, ctx));
+		}
+		return results;
+	};
 	const pi = {
+		on: (eventName: string, handler: (event: unknown, ctx: any) => unknown) => {
+			const registered = handlers.get(eventName) ?? [];
+			registered.push(handler);
+			handlers.set(eventName, registered);
+		},
+		registerTool: () => {},
+		registerCommand: () => {},
+		registerShortcut: () => {},
+		registerFlag: () => {},
 		appendEntry: (customType: string, data: unknown) => {
 			recorded.entries.push({ type: "custom", customType, data });
 		},
-		sendMessage: (message: { customType: string; content: string }) => {
-			recorded.messages.push(message);
+		sendMessage: (message: { customType: string; content: string }, options?: { triggerTurn?: boolean }) => {
+			recorded.messages.push({ ...message, options });
+		},
+		sendUserMessage: async () => {},
+		setModel: async (model: { provider: string; id: string }) => {
+			recorded.models.push({ provider: model.provider, id: model.id });
+			recorded.current = { provider: model.provider, id: model.id };
+			return true;
+		},
+		setThinkingLevel: (level: string) => {
+			recorded.thinkingLevels.push(level);
+			recorded.thinking = level;
 		},
 	};
 	const ui = {
 		setStatus: (_key: string, value: string | undefined) => {
+			recorded.statusCalls += 1;
 			recorded.status = value;
 		},
 		setWidget: (key: string, factory: any, options?: unknown) => {
@@ -55,17 +137,53 @@ function makeHarness(workdir: string): Harness {
 			}
 			recorded.widget = { key, options, factory };
 		},
+		notify: (message: string, severity: string) => {
+			recorded.notifies.push({ message, severity });
+		},
+		select: async (title: string, options: string[]) => {
+			recorded.selects.push({ title, options });
+			return recorded.selectAnswer ?? options[0];
+		},
 		theme: {
-			fg: (_color: string, text: string) => text,
+			fg: (color: string, text: string) => {
+				recorded.colors.push(color);
+				return text;
+			},
 			strikethrough: (text: string) => `~~${text}~~`,
 		},
 	};
+	const sessionManager: any = {};
 	const ctx = {
 		cwd: workdir,
 		ui,
 		isIdle: () => true,
+		hasUI: true,
+		scopedModels: [] as Array<{ model: { provider: string; id: string }; thinkingLevel?: string }>,
+		get model() {
+			return recorded.current;
+		},
+		get thinkingLevel() {
+			return recorded.thinking;
+		},
+		modelRegistry: {
+			find: (provider: string, modelId: string) =>
+				registryModels.find((entry) => entry.provider === provider && entry.id === modelId),
+			getAvailable: () => registryModels,
+		},
+		getContextUsage: () =>
+			contextPercent === null
+				? undefined
+				: { tokens: contextPercent * 1000, contextWindow: 100000, percent: contextPercent },
+		compact: (options: { customInstructions?: string }) => {
+			recorded.compacts = recorded.compacts ?? [];
+			recorded.compacts.push(options);
+		},
+		sessionManager,
+		setUsagePercent: (percent: number | null) => {
+			contextPercent = percent;
+		},
 	};
-	return { pi, ctx, recorded };
+	return { pi, ctx, recorded, emit, setUsagePercent: ctx.setUsagePercent } as Harness & { setUsagePercent: (percent: number | null) => void };
 }
 
 function items(...ids: string[]): CheckItem[] {
@@ -91,47 +209,61 @@ describe("execution loop", () => {
 		return workdir;
 	}
 
-	it("tracks done markers and completes", () => {
+	it("tracks done markers and completes", async () => {
 		const workdir = freshWorkdir();
 		const { pi, ctx, recorded } = makeHarness(workdir);
-		startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001", "VC-002"));
-		assert.ok(recorded.widget);
-		assert.equal(recorded.widget?.key, "pi-plans-execution");
-		assert.deepEqual(recorded.widget?.options, { placement: "belowEditor" });
-		const widget = recorded.widget?.factory(
-			{} as any,
-			{ fg: (_color: string, text: string) => text, strikethrough: (text: string) => `~~${text}~~` },
-		);
-		assert.ok(widget);
-		const rendered = widget.render(80);
-		assert.match(rendered[0] ?? "", /alt\+o/);
-		assert.match(rendered[0] ?? "", /📋 plans 0\/2/);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001", "VC-002"));
+
+		// Collapsed by default: progress lives in the bottom status bar (same
+		// layer as the ⛔/⌛ indicators); no panel widget is registered yet.
+		assert.equal(recorded.widget, undefined);
+		assert.match(recorded.status ?? "", /⌛ plans 0\/2: spent \d{2}:\d{2}:\d{2}/);
+		assert.match(recorded.status ?? "", /in-toks/);
+		assert.match(recorded.status ?? "", /out-toks/);
 
 		toggleExecutionPanelView(pi, ctx);
 		assert.ok(recorded.widget);
+		assert.equal(recorded.widget?.key, "pi-plans-execution");
+		assert.deepEqual(recorded.widget?.options, { placement: "belowEditor" });
+		// Expanded: footer ⌛ line is cleared — the panel renders its own header.
+		assert.equal(recorded.status, undefined);
 		const expandedWidget = recorded.widget?.factory(
 			{} as any,
 			{ fg: (_color: string, text: string) => text, strikethrough: (text: string) => `~~${text}~~` },
 		);
 		assert.ok(expandedWidget);
 		const expandedLines = expandedWidget.render(80);
+		// Header line first, then the legacy item list.
+		assert.match(expandedLines[0] ?? "", /⌛ plans 0\/2: spent/);
 		assert.match(expandedLines.join("\n"), /☐/);
+		// Detail view never repeats the keyboard hint.
+		assert.doesNotMatch(expandedLines.join("\n"), /alt\+o/);
 
 		assert.ok(getExecution());
-		assert.match(executionContextMessage()!, /PI-PLANS EXECUTION/);
-		assert.match(executionContextMessage()!, /VC-001/);
+		const rules = executionContextMessage()!;
+		assert.match(rules, /PI-PLANS EXECUTION/);
+		assert.match(rules, /VC-001/);
+		// Seven-principle rule set: representative anchors (PLAN_v2 D-003/D-004).
+		assert.match(rules, /for the long term/);
+		assert.match(rules, /Simplest implementation/);
+		assert.match(rules, /grow the change in layers/);
+		assert.match(rules, /existing dependencies \(docs and types\)/);
+		assert.match(rules, /well-maintained libraries/);
+		assert.match(rules, /clearly separated concerns/);
+		assert.match(rules, /no stopgaps/);
+		assert.doesNotMatch(rules, /ponytail/i);
 
 		assert.deepEqual(applyDoneMarkers("progress… [DONE:VC-001] done"), ["VC-001"]);
 		assert.equal(isExecutionComplete(), false);
 		assert.deepEqual(applyDoneMarkers("final: [DONE:VC-002]"), ["VC-002"]);
 		assert.equal(isExecutionComplete(), true);
 
-		completeExecution(pi, ctx);
+		await completeExecution(pi, ctx);
 		assert.equal(getExecution(), null);
 		assert.ok(recorded.messages.some((message) => message.customType === "pi-plans-complete"));
 	});
 
-	it("restores progress from session entries and rescans messages", () => {
+	it("restores progress from session entries and rescans messages", async () => {
 		const workdir = freshWorkdir();
 		const { pi, ctx, recorded } = makeHarness(workdir);
 		const snapshot = {
@@ -147,7 +279,15 @@ describe("execution loop", () => {
 					"VC-001": {
 						summary: { added: 1, removed: 0, files: 1, paths: ["src/exec.ts"] },
 					},
-				},
+			},
+			},
+			compaction: {
+				inFlight: true,
+				resumeGuard: true,
+				cooldownActive: true,
+				lastAttemptReason: "threshold",
+				lastSuccessfulUsagePercent: 100,
+				lastSuccessfulAt: "2026-08-25T00:01:00Z",
 			},
 		};
 		fs.writeFileSync(snapshot.planPath, "# plan");
@@ -158,9 +298,10 @@ describe("execution loop", () => {
 				message: { role: "assistant", content: [{ type: "text", text: "did [DONE:VC-001]" }] },
 			},
 		];
-		restoreFromSession(pi, ctx, entries as any);
+		await restoreFromSession(pi, ctx, entries as any);
 		const execution = getExecution();
 		assert.ok(execution);
+		assert.equal("compaction" in execution!, false, "legacy scheduler state must not reactivate on restore");
 		assert.ok(recorded.widget);
 		const widget = recorded.widget?.factory(
 			{} as any,
@@ -172,11 +313,11 @@ describe("execution loop", () => {
 		assert.match(rendered.join("\n"), /\+1/);
 
 		const clearedEntries = [...entries, { type: "custom", customType: "pi-plans-exec-cleared", data: {} }];
-		restoreFromSession(pi, ctx, clearedEntries as any);
+		await restoreFromSession(pi, ctx, clearedEntries as any);
 		assert.equal(getExecution(), null);
 	});
 
-	it("ignores restore when the plan file vanished", () => {
+	it("ignores restore when the plan file vanished", async () => {
 		const workdir = freshWorkdir();
 		const { pi, ctx } = makeHarness(workdir);
 		const entries = [
@@ -190,41 +331,198 @@ describe("execution loop", () => {
 				},
 			},
 		];
-		restoreFromSession(pi, ctx, entries as any);
+		await restoreFromSession(pi, ctx, entries as any);
 		assert.equal(getExecution(), null);
 	});
 
-	it("stop clears execution", () => {
+	it("stop clears execution", async () => {
 		const workdir = freshWorkdir();
 		const { pi, ctx } = makeHarness(workdir);
-		startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
-		stopExecution(pi, ctx, "test");
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+		await stopExecution(pi, ctx, "test");
 		assert.equal(getExecution(), null);
 	});
 
-	it("keeps the status bar count-free while executing and points at the panel", () => {
+	it("switches to the execution model and restores the planning model", async () => {
 		const workdir = freshWorkdir();
 		const { pi, ctx, recorded } = makeHarness(workdir);
-		startExecution(pi, ctx, path.join(workdir, "PLAN_v2.md"), items("VC-001", "VC-002"));
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v6.md"), items("VC-001"), {
+			planningSelector: "p/m:high",
+			executionSelector: "prov/other:xhigh",
+		});
 
-		// The below-editor panel owns progress; the status item must be cleared,
-		// never carrying a duplicate “📋 plans x/y” count (regression: double display).
-		assert.equal(recorded.status, undefined);
+		assert.deepEqual(recorded.models, [{ provider: "prov", id: "other" }]);
+		assert.equal(recorded.thinking, "xhigh");
+		assert.match(recorded.status ?? "", /⌛ plans 0\/1/);
+
+		await stopExecution(pi, ctx, "restore-check");
+		assert.equal(recorded.models.at(-1)?.provider, "p");
+		assert.equal(recorded.thinking, "high");
+	});
+
+	it("defers execution model restore until the first agent turn and restores planning model on completion", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded } = makeHarness(workdir);
+		const snapshot = {
+			planPath: path.join(workdir, "PLAN_v7.md"),
+			items: items("VC-001"),
+			startedAt: "2026-08-25T00:00:00Z",
+			modelState: { planningSelector: "p/m:high", executionSelector: "prov/other:xhigh" },
+		};
+		fs.writeFileSync(snapshot.planPath, "# plan");
+		const entries = [{ type: "custom", customType: "pi-plans-exec", data: snapshot }];
+
+		await restoreFromSession(pi, ctx, entries as any);
+		assert.ok(getExecution());
+		assert.deepEqual(recorded.models, []);
+
+		await ensureExecutionModelActive(pi, ctx);
+		assert.deepEqual(recorded.models, [{ provider: "prov", id: "other" }]);
+		assert.equal(recorded.thinking, "xhigh");
+
+		const doneEntries = [
+			...entries,
+			{ type: "message", message: { role: "assistant", content: [{ type: "text", text: "did [DONE:VC-001]" }] } },
+		];
+		await restoreFromSession(pi, ctx, doneEntries as any);
+		assert.equal(getExecution(), null);
+		assert.equal(recorded.models.at(-1)?.provider, "p");
+		assert.equal(recorded.thinking, "high");
+	});
+
+	it("prompts for the execution model when unset and confirms inherit current session model", async () => {
+		const workdir = freshWorkdir();
+		const { ctx, recorded } = makeHarness(workdir);
+		initState(workdir);
+		recorded.selectAnswer = "Inherit current session model";
+		const selection = await chooseExecutionModelSelection(ctx as any, "Execution model", {
+			model_selector: null,
+			source: "unset",
+			updated_at: null,
+		}, async (selector) => {
+			setExecutionModel(workdir, { modelSelector: selector, source: "user" });
+		});
+
+		assert.equal(recorded.selects.length, 1);
+		assert.equal(recorded.selects[0]?.options[0], "Inherit current session model");
+		assert.equal(selection?.selector, "p/m:high");
+		assert.equal(showConfig(workdir).execution.source, "user");
+		assert.equal(showConfig(workdir).execution.model_selector, null);
+	});
+
+	it("does not prompt when the execution model is already confirmed as inherit", async () => {
+		const workdir = freshWorkdir();
+		const { ctx, recorded } = makeHarness(workdir);
+		initState(workdir);
+		setExecutionModel(workdir, { modelSelector: "inherit", source: "user" });
+		const selection = await chooseExecutionModelSelection(ctx as any, "Execution model", showConfig(workdir).execution);
+
+		assert.equal(recorded.selects.length, 0);
+		assert.equal(selection?.selector, "p/m:high");
+	});
+
+	it("continues on the current model with a warning when the selector is unavailable", async () => {
+		const workdir = freshWorkdir();
+		const { ctx, recorded } = makeHarness(workdir);
+		(ctx as any).hasUI = false;
+		const selection = await chooseExecutionModelSelection(ctx as any, "Execution model", {
+			model_selector: "prov/missing:xhigh",
+			source: "user",
+			updated_at: null,
+		});
+
+		assert.equal(selection?.provider, "p");
+		assert.ok(recorded.notifies.some((n) => n.severity === "warning" && n.message.includes("prov/missing")));
+	});
+
+	it("keeps the status bar count-free while executing and points at the panel", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v2.md"), items("VC-001", "VC-002"));
+
+		// Bottom status bar carries the count — the same layer as ⛔/⌛ — so both
+		// execution states read from one consistent place.
+		assert.match(recorded.status ?? "", /⌛ plans 0\/2: spent \d{2}:\d{2}:\d{2}/);
+		assert.match(recorded.status ?? "", /in-toks/);
 
 		const start = recorded.messages.find((message) => message.customType === "pi-plans-exec-start");
 		assert.ok(start);
-		assert.match(start.content, /Progress appears below the editor/);
+		assert.match(start.content, /Progress appears in the bottom status bar/);
 		assert.doesNotMatch(start.content, /footer/);
 
 		applyDoneMarkers("[DONE:VC-001]");
-		completeExecution(pi, ctx);
+		await completeExecution(pi, ctx);
 		assert.equal(getExecution(), null);
+
 	});
 
-	it("defers persistence and widget churn when toggling mid-turn", () => {
+	it("renders the idle indicator by run status", () => {
+		const workdir = freshWorkdir();
+		const { ctx, recorded } = makeHarness(workdir);
+		initState(workdir);
+		const { run } = startRun(workdir, { topic: "demo", skill: "plan-small", requestText: "x" });
+
+		// planning before any PLAN draft exists: 💬 (Q&A phase).
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /💬 plans: /);
+		assert.equal(recorded.colors.at(-1), "muted");
+
+		// Once a draft lands: 📝, kept until execution starts.
+		fs.writeFileSync(path.join(run.artifact_dir, "PLAN_v1.md"), "# plan");
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /📝 plans: /);
+		assert.equal(recorded.colors.at(-1), "muted");
+
+		setRunStatus(workdir, run.run_id, "accepted");
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /⌛ plans: /);
+		assert.equal(recorded.colors.at(-1), "warning");
+
+		setRunStatus(workdir, run.run_id, "stopped");
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /⛔ plans: /);
+		assert.equal(recorded.colors.at(-1), "warning");
+
+		setRunStatus(workdir, run.run_id, "done");
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /🎯 plans: .*\(done\)/);
+		assert.equal(recorded.colors.at(-1), "success");
+
+		setRunStatus(workdir, run.run_id, "abandoned");
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /🚫 plans: /);
+		assert.equal(recorded.colors.at(-1), "error");
+	});
+
+	it("accumulates token usage on token-only and completion turns", async () => {
 		const workdir = freshWorkdir();
 		const { pi, ctx, recorded } = makeHarness(workdir);
-		startExecution(pi, ctx, path.join(workdir, "PLAN_v3.md"), items("VC-001", "VC-002"));
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v5.md"), items("VC-001", "VC-002"));
+
+		recordExecutionTurn(pi, ctx, [], { input: 100, output: 40 });
+		updateStatusWidget(ctx);
+		assert.equal(getExecution()?.usage.inToks, 100);
+		assert.equal(getExecution()?.usage.outToks, 40);
+		assert.match(recorded.status ?? "", /100 in-toks/);
+		assert.match(recorded.status ?? "", /40 out-toks/);
+
+		assert.deepEqual(applyDoneMarkers("[DONE:VC-001]"), ["VC-001"]);
+		recordExecutionTurn(pi, ctx, ["VC-001"], { input: 20, output: 10 });
+		updateStatusWidget(ctx);
+		assert.equal(getExecution()?.usage.inToks, 120);
+		assert.equal(getExecution()?.usage.outToks, 50);
+		assert.equal(getExecution()?.items[0].done, true);
+		assert.match(recorded.status ?? "", /120 in-toks/);
+		assert.match(recorded.status ?? "", /50 out-toks/);
+
+		await stopExecution(pi, ctx, "test-done");
+		assert.equal(getExecution(), null);
+	});
+
+	it("defers persistence and widget churn when toggling mid-turn", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v3.md"), items("VC-001", "VC-002"));
 
 		const entriesBefore = recorded.entries.length;
 		const factoriesBefore = recorded.widgetCalls;
@@ -237,13 +535,590 @@ describe("execution loop", () => {
 		assert.equal(consumePendingPanelSync(), true, "expected a pending panel sync marker");
 		assert.equal(consumePendingPanelSync(), false, "marker should be consumed exactly once");
 
-		// Back to idle: the next toggle persists and syncs, but still reuses the
-		// already-registered factory (cache-drop instead of teardown).
+		// Back to idle: the next toggle persists and syncs without touching the
+		// widget slot because the panel is collapsed again.
 		ctx.isIdle = () => true;
 		assert.equal(toggleExecutionPanelView(pi, ctx), false);
 		assert.ok(recorded.entries.length > entriesBefore, "idle toggle did not persist");
-		assert.equal(recorded.widgetCalls, factoriesBefore, "idle toggle replaced the widget factory");
+		assert.equal(recorded.widgetCalls, factoriesBefore, "collapsed toggle churned the widget registration");
 
-		stopExecution(pi, ctx, "test-done");
+		await stopExecution(pi, ctx, "test-done");
+	});
+
+	it("lets Pi core own execution compaction scheduling and customizes every reason", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, setUsagePercent } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v8.md"), items("VC-001", "VC-002"));
+
+		setUsagePercent(50);
+		const below = handleExecutionBeforeCompact(pi, ctx, {
+			type: "session_before_compact",
+			preparation: makePreparation("threshold", null),
+			branchEntries: [],
+			reason: "threshold",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+		assert.equal(below?.cancel, undefined);
+		assert.ok(below?.compaction, "threshold compaction should remain Pi-core-owned but use the custom summary");
+
+		setUsagePercent(105);
+		const above = handleExecutionBeforeCompact(pi, ctx, {
+			type: "session_before_compact",
+			preparation: makePreparation("threshold", null),
+			branchEntries: [],
+			reason: "threshold",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+		assert.equal(above?.cancel, undefined);
+		assert.ok(above?.compaction);
+
+		const overflow = handleExecutionBeforeCompact(pi, ctx, {
+			type: "session_before_compact",
+			preparation: makePreparation("overflow", null),
+			branchEntries: [],
+			reason: "overflow",
+			willRetry: true,
+			signal: new AbortController().signal,
+		});
+		assert.equal(overflow?.cancel, undefined);
+		assert.ok(overflow?.compaction);
+
+		const manual = handleExecutionBeforeCompact(pi, ctx, {
+			type: "session_before_compact",
+			preparation: makePreparation("manual", null),
+			branchEntries: [],
+			reason: "manual",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+		assert.equal(manual?.cancel, undefined);
+		assert.ok(manual?.compaction);
+
+		await stopExecution(pi, ctx, "test-done");
+	});
+
+	it("does not install an execution threshold trigger in turn_end", () => {
+		const indexSource = fs.readFileSync(path.join(process.cwd(), "index.ts"), "utf8");
+		const execSource = fs.readFileSync(path.join(process.cwd(), "src/exec.ts"), "utf8");
+		const turnEndStart = execSource.indexOf('pi.on("turn_end"');
+		const nextSection = execSource.indexOf("type CompactBranchEntry", turnEndStart);
+		assert.match(indexSource, /registerExecutionTurnHandlers\(pi/);
+		assert.ok(turnEndStart >= 0);
+		assert.ok(nextSection > turnEndStart);
+		assert.doesNotMatch(execSource.slice(turnEndStart, nextSection), /requestExecutionCompaction|shouldTriggerExecutionCompaction|ctx\.compact/);
+	});
+
+	it("queues one non-retry resume, skips overflow retry, and keeps execution after failure", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v9.md"), items("VC-001"));
+
+		const beforeRequests = recorded.compacts?.length ?? 0;
+		handleExecutionCompact(pi, ctx, {
+			type: "session_compact",
+			compactionEntry: { type: "compaction" } as never,
+			fromExtension: true,
+			reason: "threshold",
+			willRetry: false,
+		});
+		const resumes = recorded.messages.filter((message) => message.customType === "pi-plans-exec-resume");
+		assert.equal(resumes.length, 1, "non-retry compaction should queue one hidden resume");
+		assert.equal(resumes[0]?.options?.triggerTurn, true);
+		assert.equal(recorded.compacts?.length ?? 0, beforeRequests, "compaction hook must not invoke ctx.compact");
+
+		handleExecutionCompact(pi, ctx, {
+			type: "session_compact",
+			compactionEntry: { type: "compaction" } as never,
+			fromExtension: true,
+			reason: "overflow",
+			willRetry: true,
+		});
+		assert.equal(
+			recorded.messages.filter((message) => message.customType === "pi-plans-exec-resume").length,
+			1,
+			"overflow retry is owned by Pi core",
+		);
+
+		handleExecutionCompactFailed(pi, ctx, {
+			type: "session_compact_failed",
+			reason: "manual",
+			aborted: false,
+			willRetry: false,
+			fromExtension: true,
+			errorMessage: "boom",
+		});
+		assert.ok(getExecution(), "compaction failure must keep execution active");
+		assert.ok(recorded.notifies.some((note) => note.severity === "warning" && note.message.includes("execution remains active")));
+
+		await stopExecution(pi, ctx, "test-done");
+	});
+
+	it("builds a plan-aware summary with per-item sections and chains the previous summary", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, setUsagePercent } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v10.md"), items("VC-001", "VC-002"));
+
+		applyDoneMarkers("[DONE:VC-001]");
+
+		const previousSummary = "## Goal\nDeliver auto-compact in execution phase.\n\n## Finished Items\n- legacy VC-000 summary";
+		const preparation = makePreparation("threshold", previousSummary);
+		const branchEntries: any[] = [
+			{ id: "exec-start", type: "custom", customType: "pi-plans-exec-start" },
+			{ id: "u-1", type: "message", message: { role: "user", content: [{ type: "text", text: "implement VC-001" }] } },
+			{ id: "a-1", type: "message", message: { role: "assistant", content: [{ type: "text", text: "wrote helper [DONE:VC-001]" }] } },
+			{ id: "u-2", type: "message", message: { role: "user", content: [{ type: "text", text: "implement VC-002" }] } },
+			{ id: "a-2", type: "message", message: { role: "assistant", content: [{ type: "text", text: "almost done" }] } },
+			{ id: "exec-ctx", type: "custom", customType: "pi-plans-exec-context" },
+		];
+		const result = buildExecutionCompactionResult(
+			{
+				type: "session_before_compact",
+				preparation,
+				branchEntries,
+				customInstructions: "keep current task visible",
+				reason: "threshold",
+				willRetry: false,
+				signal: new AbortController().signal,
+			},
+			ctx,
+		);
+		assert.ok(result);
+		assert.match(result!.summary, /## Compact Instructions/);
+		assert.match(result!.summary, /keep current task visible/);
+		assert.match(result!.summary, /## Plan Before This Run/);
+		assert.match(result!.summary, /## Previous Compact Summary/);
+		assert.match(result!.summary, /## Finished VC Items/);
+		assert.match(result!.summary, /### `VC-001`/);
+		assert.match(result!.summary, /## Current Work/);
+		assert.match(result!.summary, /Raw tail preserved from `u-2`/);
+		assert.deepEqual(result!.firstKeptEntryId, "u-2");
+
+		setUsagePercent(110);
+		handleExecutionBeforeCompact(pi, ctx, {
+			type: "session_before_compact",
+			preparation,
+			branchEntries,
+			reason: "threshold",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+
+		await stopExecution(pi, ctx, "test-done");
+	});
+
+	it("filters the hidden resume message out of the LLM context payload", () => {
+		const messages = [
+			{ customType: "user", content: "real prompt" },
+			{ customType: "pi-plans-exec-resume", content: "Continue execution." },
+			{ customType: "pi-plans-plan-resume", content: "Continue planning." },
+			{ customType: "assistant", content: "ok" },
+		];
+		assert.equal(filterExecutionResumeMessages(messages).length, 3);
+		assert.equal(filterPlanningResumeMessages(messages).length, 3);
+	});
+
+	it("planning compaction cuts at plan-written when present and falls back to run-start", () => {
+		const workdir = freshWorkdir();
+		const { ctx } = makeHarness(workdir);
+		initState(workdir);
+		const { run } = startRun(workdir, { topic: "planning compact", skill: "plan-normal", requestText: "demo" });
+		fs.writeFileSync(path.join(run.artifact_dir, "PLAN_v1.md"), "# plan");
+
+		const makePlanningPreparation = (previousSummary: string | null) => ({
+			firstKeptEntryId: "fallback",
+			messagesToSummarize: [],
+			turnPrefixMessages: [],
+			isSplitTurn: false,
+			tokensBefore: 50000,
+			previousSummary,
+			fileOps: { read: [], written: [], edited: [] },
+			settings: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 },
+		});
+
+		// Case A: plan written → cut at next non-internal entry after plan-written; QA section included.
+		const branchEntriesWithPlan = [
+			{ id: "rs", type: "custom", customType: PLANNING_RUN_START_CUSTOM_TYPE, data: { runId: run.run_id, artifactDir: run.artifact_dir } },
+			{ id: "u-1", type: "message", message: { role: "user", content: [{ type: "text", text: "background question?" }] } },
+			{ id: "a-1", type: "message", message: { role: "assistant", content: [{ type: "text", text: "some context" }] } },
+			{ id: "pw", type: "custom", customType: PLANNING_PLAN_WRITTEN_CUSTOM_TYPE, data: { runId: run.run_id, planPath: path.join(run.artifact_dir, "PLAN_v1.md") } },
+			{ id: "u-2", type: "message", message: { role: "user", content: [{ type: "text", text: "review please" }] } },
+		] as any;
+		const withPlan = buildPlanningCompactionResult(
+			{
+				type: "session_before_compact",
+				preparation: makePlanningPreparation(null),
+				branchEntries: branchEntriesWithPlan,
+				reason: "threshold",
+				willRetry: false,
+				signal: new AbortController().signal,
+			},
+			ctx,
+		);
+		assert.ok(withPlan);
+		assert.deepEqual(withPlan!.firstKeptEntryId, "u-2");
+		assert.match(withPlan!.summary, /## Q&A During Planning/);
+		assert.match(withPlan!.summary, /background question?/);
+
+		// Case B: only run-start → cut at first non-internal entry after marker; no QA section.
+		const branchEntriesWithoutPlan = [
+			{ id: "rs", type: "custom", customType: PLANNING_RUN_START_CUSTOM_TYPE, data: { runId: run.run_id, artifactDir: run.artifact_dir } },
+			{ id: "u-1", type: "message", message: { role: "user", content: [{ type: "text", text: "open question" }] } },
+			{ id: "a-1", type: "message", message: { role: "assistant", content: [{ type: "text", text: "thinking out loud" }] } },
+		] as any;
+		const withoutPlan = buildPlanningCompactionResult(
+			{
+				type: "session_before_compact",
+				preparation: makePlanningPreparation(null),
+				branchEntries: branchEntriesWithoutPlan,
+				reason: "manual",
+				willRetry: false,
+				signal: new AbortController().signal,
+			},
+			ctx,
+		);
+		assert.ok(withoutPlan);
+		assert.deepEqual(withoutPlan!.firstKeptEntryId, "u-1");
+		assert.doesNotMatch(withoutPlan!.summary, /## Q&A During Planning/);
+
+		// Case C: no markers → fallback to preparation.firstKeptEntryId and no QA section.
+		const fallback = buildPlanningCompactionResult(
+			{
+				type: "session_before_compact",
+				preparation: makePlanningPreparation("## Previous\nEarlier summary."),
+				branchEntries: [],
+				reason: "threshold",
+				willRetry: false,
+				signal: new AbortController().signal,
+			},
+			ctx,
+		);
+		assert.ok(fallback);
+		assert.deepEqual(fallback!.firstKeptEntryId, "fallback");
+		assert.doesNotMatch(fallback!.summary, /## Q&A During Planning/);
+		assert.match(fallback!.summary, /## Previous Compact Summary/);
+	});
+
+	it("planning hook is gated by run.status=planning and defers to execution hook when execution is running", async () => {
+		const workdir = freshWorkdir();
+		const { ctx, setUsagePercent } = makeHarness(workdir);
+		initState(workdir);
+		const { run } = startRun(workdir, { topic: "planning gate", skill: "plan-small", requestText: "x" });
+
+		setUsagePercent(110);
+		const resultPlanning = handlePlanningBeforeCompact({} as any, ctx as any, {
+			type: "session_before_compact",
+			preparation: {
+				firstKeptEntryId: "fb",
+				messagesToSummarize: [],
+				turnPrefixMessages: [],
+				isSplitTurn: false,
+				tokensBefore: 1,
+				previousSummary: null,
+				fileOps: { read: [], written: [], edited: [] },
+				settings: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 },
+			},
+			branchEntries: [],
+			reason: "threshold",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+		assert.ok(resultPlanning?.compaction || resultPlanning === undefined);
+
+		// Flip status to done; planning hook should refuse.
+		setRunStatus(workdir, run.run_id, "done");
+		setUsagePercent(110);
+		const resultDone = handlePlanningBeforeCompact({} as any, ctx as any, {
+			type: "session_before_compact",
+			preparation: {
+				firstKeptEntryId: "fb",
+				messagesToSummarize: [],
+				turnPrefixMessages: [],
+				isSplitTurn: false,
+				tokensBefore: 1,
+				previousSummary: null,
+				fileOps: { read: [], written: [], edited: [] },
+				settings: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 },
+			},
+			branchEntries: [],
+			reason: "threshold",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+		assert.equal(resultDone, undefined);
+	});
+
+	it("turn_end writes are unconditionally deferred even when isIdle reads true", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded, setUsagePercent } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v11.md"), items("VC-001", "VC-002"));
+		const snapshotCount = () => recorded.entries.filter((e) => e.customType === "pi-plans-exec").length;
+		const baseline = snapshotCount();
+
+		// No isIdle override: the harness default (() => true) IS the real
+		// turn_end reading — this encodes the field regression (60 writes in
+		// 23 minutes) as a permanent zero-write assertion.
+		recordExecutionTurn(pi, ctx, [], { input: 10, output: 5 });
+		setUsagePercent(50);
+		handleExecutionBeforeCompact(pi, ctx, {
+			type: "session_before_compact",
+			preparation: makePreparation("threshold", null),
+			branchEntries: [],
+			reason: "threshold",
+			willRetry: false,
+			signal: new AbortController().signal,
+		});
+		assert.equal(snapshotCount(), baseline, "turn_end wrote session entries despite deferral");
+		// Status line stays real-time while the write is deferred.
+		assert.match(recorded.status ?? "", /10 in-toks/);
+
+		drainExecutionFlush(pi, ctx);
+		assert.equal(snapshotCount(), baseline + 1, "settle flush did not write exactly one snapshot");
+		const last = (recorded.entries.filter((e) => e.customType === "pi-plans-exec").at(-1)?.data ?? {}) as { usage?: { inToks: number } };
+		assert.equal(last.usage?.inToks, 10, "flushed snapshot missing busy-turn usage");
+		drainExecutionFlush(pi, ctx);
+		assert.equal(snapshotCount(), baseline + 1, "second drain wrote again");
+		assert.equal(consumePendingExecutionFlush(), false);
+
+		await stopExecution(pi, ctx, "done");
+	});
+
+	it("stop and complete drain pending writes synchronously with final state", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v12.md"), items("VC-001", "VC-002"));
+		const snapshotCount = () => recorded.entries.filter((e) => e.customType === "pi-plans-exec").length;
+
+		ctx.isIdle = () => false;
+		recordExecutionTurn(pi, ctx, [], { input: 7, output: 3 });
+		const busyCount = snapshotCount();
+
+		await stopExecution(pi, ctx, "force");
+		assert.ok(snapshotCount() > busyCount, "stop did not write the final snapshot");
+		assert.ok(recorded.entries.some((e) => e.customType === "pi-plans-exec-cleared"));
+		const lastStop = (recorded.entries.filter((e) => e.customType === "pi-plans-exec").at(-1)?.data ?? {}) as { usage?: { inToks: number } };
+		assert.equal(lastStop.usage?.inToks, 7, "stop lost the busy-turn usage");
+
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v13.md"), items("VC-001"));
+		ctx.isIdle = () => false;
+		applyDoneMarkers("[DONE:VC-001]");
+		recordExecutionTurn(pi, ctx, ["VC-001"], { input: 1, output: 1 });
+		await completeExecution(pi, ctx);
+		assert.equal(getExecution(), null);
+		const lastComplete = (recorded.entries.filter((e) => e.customType === "pi-plans-exec").at(-1)?.data ?? {}) as { items?: Array<{ done: boolean }> };
+		assert.equal(lastComplete.items?.[0]?.done, true, "completion snapshot missing final done state");
+	});
+
+	it("plans-list groups by implementation item with status tags and strikethrough", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded } = makeHarness(workdir);
+		const implItems = [
+			{ id: "I-001", text: "Add state helpers; evaluate percent." },
+			{ id: "I-002", text: "Wire the turn_end trigger and status bar." },
+			{ id: "I-003", text: "Zero coverage orphan item." },
+		];
+		const vcItems: CheckItem[] = [
+			{ id: "VC-001", text: "`VC-001` covers `I-001`; pass condition: tests", done: false },
+			{ id: "VC-002", text: "`VC-002` covers `I-001` and `I-002`; pass condition: lint", done: false },
+		];
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v14.md"), vcItems, undefined, implItems);
+
+		// Status bar counts by I, excluding the zero-coverage orphan.
+		updateStatusWidget(ctx);
+		assert.match(recorded.status ?? "", /⌛ plans 0\/2: spent/);
+
+		toggleExecutionPanelView(pi, ctx);
+		assert.ok(recorded.widget);
+		// Expanded: footer ⌛ line cleared — the panel renders its own header.
+		assert.equal(recorded.status, undefined);
+		const widget = recorded.widget!.factory(
+			{} as any,
+			{ fg: (_c: string, t: string) => t, strikethrough: (t: string) => `~~${t}~~` },
+		);
+		const lines = widget.render(120).join("\n");
+		assert.match(lines, /⌛ plans 0\/2: spent/);
+		assert.match(lines, /\[Implementing\] I-001: Add state helpers/);
+		assert.match(lines, /\[Pending\] I-002: Wire the turn_end trigger/);
+		assert.match(lines, /\[Pending\] I-003: Zero coverage orphan item/);
+		// Only I status rows — no VC sub-rows in grouped mode.
+		assert.doesNotMatch(lines, /☐/);
+		assert.doesNotMatch(lines, /`VC-001` covers/);
+
+		// Markers move the states; fan-out advances both covered I items.
+		applyImplMarkers("[I-001:implemented]");
+		applyDoneMarkers("[DONE:VC-001]");
+		applyDoneMarkers("[DONE:VC-002]");
+		widget.invalidate();
+		const rendered = widget.render(120).join("\n");
+		assert.match(rendered, /~~\[VC passed\] I-001: Add state helpers~~/);
+		assert.match(rendered, /~~\[VC passed\] I-002: Wire the turn_end trigger and status bar\.~~/);
+
+		// Status bar now counts both I items as passed.
+		updateStatusWidget(ctx);
+		assert.equal(recorded.status, undefined, "expanded panel keeps the footer ⌛ line cleared");
+
+		await stopExecution(pi, ctx, "done");
+		// Panel cleared and execution over: the ⌛ line must not linger.
+		assert.doesNotMatch(recorded.status ?? "", /⌛ plans/);
+	});
+
+	it("updates the status bar in real time on every turn without session writes", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded, setUsagePercent } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v15.md"), items("VC-001", "VC-002"), undefined, [
+			{ id: "I-001", text: "First item." },
+			{ id: "I-002", text: "Second item." },
+		]);
+		const snapshotCount = () => recorded.entries.filter((e) => e.customType === "pi-plans-exec").length;
+		const baseline = snapshotCount();
+
+		recordExecutionTurn(pi, ctx, [], { input: 33, output: 11 });
+		// Real-time: status line already reflects the turn's usage...
+		assert.match(recorded.status ?? "", /33 in-toks/);
+		assert.match(recorded.status ?? "", /⌛ plans 0\/2: spent/);
+		// ...without any session write (anti-jitter preserved).
+		assert.equal(snapshotCount(), baseline);
+
+		setUsagePercent(null);
+		drainExecutionFlush(pi, ctx);
+		assert.equal(snapshotCount(), baseline + 1);
+
+		await stopExecution(pi, ctx, "done");
+	});
+
+	it("syncs progress through the registered message_end and turn_end handlers", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, recorded, emit } = makeHarness(workdir);
+		registerExecutionTurnHandlers(pi);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v19.md"), items("VC-001", "VC-002", "VC-003"));
+
+		// The usage is delivered by message_end and consumed by the following
+		// turn_end, matching Pi's lifecycle contract.
+		await emit("message_end", {
+			message: { role: "assistant", usage: { input: 12, output: 5 } },
+		});
+		await emit("turn_end", {
+			message: { role: "assistant", content: [{ type: "text", text: "verified [DONE:VC-001]" }] },
+		});
+		assert.match(recorded.status ?? "", /⌛ plans 1\/3: spent/);
+		assert.match(recorded.status ?? "", /12 in-toks/);
+		assert.equal(recorded.widgetCalls, 0, "collapsed progress must not touch the widget slot");
+
+		// Expanded progress is updated through the same event handler without
+		// re-registering the live widget.
+		toggleExecutionPanelView(pi, ctx);
+		const renderRequests = { count: 0 };
+		const widget = recorded.widget?.factory(
+			{ requestRender: () => { renderRequests.count += 1; } },
+			{ fg: (_color: string, text: string) => text, strikethrough: (text: string) => text },
+		);
+		assert.ok(widget);
+		assert.match(widget.render(100)[0] ?? "", /⌛ plans 1\/3: spent/);
+		const widgetCalls = recorded.widgetCalls;
+
+		await emit("message_end", {
+			message: { role: "assistant", usage: { input: 8, output: 3 } },
+		});
+		await emit("turn_end", {
+			message: { role: "assistant", content: [{ type: "text", text: "verified [DONE:VC-002]" }] },
+		});
+		assert.equal(recorded.status, undefined, "expanded execution keeps the footer indicator cleared");
+		assert.equal(recorded.widgetCalls, widgetCalls, "progress refresh must reuse the live widget");
+		assert.equal(renderRequests.count, 1, "expanded progress must request a TUI render");
+		assert.match(widget.render(100)[0] ?? "", /⌛ plans 2\/3: spent/);
+
+		await stopExecution(pi, ctx, "event-chain-test");
+	});
+	it("applies impl markers with silent unknown ids and later-overwrite semantics", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v16.md"), items("VC-001"), undefined, [
+			{ id: "I-001", text: "First item." },
+		]);
+
+		assert.deepEqual(applyImplMarkers("[I-999:implemented]"), []); // unknown id silently ignored
+		assert.deepEqual(applyImplMarkers("[I-001:implemented]"), ["I-001"]);
+		assert.deepEqual(applyImplMarkers("[I-001:validating]"), ["I-001"]); // later overwrites
+		assert.equal(getExecution()?.implStatus?.["I-001"], "validating");
+
+		await stopExecution(pi, ctx, "done");
+	});
+
+	it("replays impl markers from post-snapshot messages on restore", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx } = makeHarness(workdir);
+		const snapshot = {
+			planPath: path.join(workdir, "PLAN_v17.md"),
+			items: items("VC-001"),
+			startedAt: "2026-08-29T00:00:00Z",
+			implItems: [{ id: "I-001", text: "First item." }],
+			implStatus: {},
+		};
+		fs.writeFileSync(snapshot.planPath, "# plan");
+		const entries = [
+			{ type: "custom", customType: "pi-plans-exec", data: snapshot },
+			{ type: "message", message: { role: "assistant", content: [{ type: "text", text: "work done [I-001:implemented]" }] } },
+		];
+		await restoreFromSession(pi, ctx, entries as any);
+		assert.equal(getExecution()?.implStatus?.["I-001"], "implemented");
+	});
+
+	it("keeps the injection rules teaching the impl markers", async () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v18.md"), items("VC-001"), undefined, [
+			{ id: "I-001", text: "First item." },
+		]);
+		const rules = executionContextMessage()!;
+		assert.match(rules, /\[I-001:implemented\]/);
+		assert.match(rules, /\[I-001:validating\]/);
+		await stopExecution(pi, ctx, "done");
+	});
+
+	it("planning compaction honors cooldown + resume guard and survives manual /compact", () => {
+		const workdir = freshWorkdir();
+		const { pi, ctx, setUsagePercent, recorded } = makeHarness(workdir);
+		initState(workdir);
+		startRun(workdir, { topic: "planning cooldown", skill: "plan-normal", requestText: "x" });
+
+		setUsagePercent(120);
+		assert.equal(shouldTriggerPlanningCompaction(ctx as any), true);
+		requestPlanningCompaction(ctx as any);
+		// In flight, second trigger ignored.
+		requestPlanningCompaction(ctx as any);
+		assert.equal(shouldTriggerPlanningCompaction(ctx as any), false);
+
+		setUsagePercent(50);
+		handlePlanningCompact(pi as any, ctx as any, {
+			type: "session_compact",
+			compactionEntry: { type: "compaction" } as never,
+			fromExtension: true,
+			reason: "manual",
+			willRetry: false,
+		});
+		const resume = recorded.messages.find((message) => message.customType === "pi-plans-plan-resume");
+		assert.ok(resume);
+		assert.equal(consumePlanningCompactionResumeGuard(ctx as any), true);
+		// Cooldown blocks retrigger while usage is still mid-band.
+		setUsagePercent(95);
+		assert.equal(shouldTriggerPlanningCompaction(ctx as any), false);
+		setUsagePercent(50);
+		refreshPlanningCompactionCooldown(ctx as any);
+		setUsagePercent(120);
+		assert.equal(shouldTriggerPlanningCompaction(ctx as any), true);
 	});
 });
+
+function makePreparation(reason: "manual" | "threshold" | "overflow", previousSummary: string | null): any {
+	return {
+		firstKeptEntryId: "a-2",
+		messagesToSummarize: [],
+		turnPrefixMessages: [],
+		isSplitTurn: false,
+		tokensBefore: 12345,
+		previousSummary,
+		fileOps: { read: [], written: [], edited: [] },
+		settings: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 },
+	};
+}