pi-plans 0.1.0 → 0.1.2

package/tests/execution-panel.test.ts

@@ -111,23 +111,47 @@ describe("execution panel helpers", () => {
 		const execution: any = {
 			planPath: "/tmp/PLAN_v1.md",
 			items: [{ id: "VC-001", text: "item", done: false }],
+			startedAt: "2026-08-29T00:00:00Z",
+			usage: { inToks: 0, outToks: 0 },
 			panel: createExecutionPanelState(),
 		};
 		const factories: unknown[] = [];
+		const statuses: Array<string | undefined> = [];
+		let renderRequests = 0;
 		const theme = { fg: (_color: string, text: string) => `\u001b[38;5;2m${text}\u001b[39m`, strikethrough: (text: string) => text };
-		const ctx = { ui: { setWidget: (_key: string, factory: any) => void factories.push(factory) } } as any;
+		const ctx = {
+			ui: {
+				setWidget: (_key: string, factory: any) => void factories.push(factory),
+				setStatus: (_key: string, value: string | undefined) => void statuses.push(value),
+				theme: { fg: (_color: string, text: string) => text },
+			},
+		} as any;
 
+		// Collapsed execution renders no widget — the footer owns the ⌛ line.
 		refreshExecutionPanel(ctx, execution);
-		refreshExecutionPanel(ctx, execution); // second pass must only invalidate
-		assert.equal(factories.length, 1, "factory re-registered on refresh");
-
-		const widget = (factories[0] as any)({}, theme);
-		assert.equal(widget.render(80).length, 1, "collapsed render should be a single line");
+		refreshExecutionPanel(ctx, execution); // idempotent while collapsed
+		assert.equal(factories.length, 0);
+		assert.match(String(statuses.at(-1)), /⌛ plans 0\/1/);
 
+		// Expanding registers the detail widget exactly once and clears the
+		// footer ⌛ line (the panel renders its own header).
 		toggleExpanded(execution);
 		refreshExecutionPanel(ctx, execution);
 		assert.equal(factories.length, 1);
-		assert.ok(widget.render(80).length > 1, "invalidate did not pick up expanded state");
+		assert.equal(statuses.at(-1), undefined, "expanded must clear the footer ⌛ line");
+		const widget = (factories[0] as any)({ requestRender: () => { renderRequests += 1; } }, theme);
+		const expandedLines = widget.render(80);
+		assert.match(expandedLines[0] ?? "", /⌛ plans 0\/1/, "panel header must be the first line");
+		assert.ok(expandedLines.length >= 1, "expanded render should list items");
+
+		refreshExecutionPanel(ctx, execution); // same host: reuse, no re-register
+		assert.equal(factories.length, 1);
+		assert.equal(renderRequests, 1, "same-host refresh must request a TUI render");
+		execution.items[0]!.done = true;
+		refreshExecutionPanel(ctx, execution);
+		assert.equal(factories.length, 1);
+		assert.equal(renderRequests, 2, "expanded progress refresh must request a TUI render");
+		assert.match(widget.render(80)[0] ?? "", /⌛ plans 1\/1/, "refresh must invalidate the live widget cache");
 
 		// Clearing releases the slot so a future run registers afresh.
 		refreshExecutionPanel(ctx, null);
@@ -166,6 +190,8 @@ describe("execution panel width safety", () => {
 	it("renders every expanded checklist line inside the terminal width", () => {
 		const execution: any = {
 			planPath: "/tmp/PLAN_v1.md",
+			startedAt: "2026-08-29T00:00:00Z",
+			usage: { inToks: 0, outToks: 0 },
 			items: [
 				{
 					id: "VC-001",
@@ -180,7 +206,17 @@ describe("execution panel width safety", () => {
 		toggleExpanded(execution);
 
 		let factory: ((tui: unknown, theme: unknown) => any) | undefined;
-		refreshExecutionPanel({ ui: { setWidget: (_key: string, f: any) => void (factory = f) } } as any, execution);
+		const statuses: Array<string | undefined> = [];
+		refreshExecutionPanel(
+			{
+				ui: {
+					setWidget: (_key: string, f: any) => void (factory = f),
+					setStatus: (_key: string, value: string | undefined) => void statuses.push(value),
+					theme: { fg: (_color: string, text: string) => text },
+				},
+			} as any,
+			execution,
+		);
 		const widget = factory!({}, styledTheme);
 
 		let sawEllipsis = false;

package/tests/plan.test.ts

@@ -5,7 +5,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { after, before, describe, it } from "node:test";
-import { latestPlanVersion, nextPlanVersionPath, parseChecklist, scanDoneMarkers } from "../src/plan.ts";
+import { latestPlanVersion, nextPlanVersionPath, parseChecklist, parseImplItems, resolveImplStatuses, scanDoneMarkers, scanImplMarkers, shortImplDescription, extractCoverage } from "../src/plan.ts";
 
 const PLAN = `# PLAN_v1 - demo
 
@@ -103,3 +103,86 @@ describe("nextPlanVersionPath", () => {
 		assert.equal(next.path, path.join(empty, "PLAN_v1.md"));
 	});
 });
+
+describe("implementation items", () => {
+	const IMPL_PLAN = `# PLAN_v1 - demo
+
+## Implementation Items
+
+- \`I-001\`: Add state helpers in src/exec.ts; evaluate percent and coverage. Details follow:
+  - nested sub-bullet ignored
+- \`I-002\`: Wire the turn_end trigger and status bar.
+- not an item line
+- \`I-001\`: duplicate id ignored
+
+## Verifier Checklist
+
+- [ ] \`VC-001\` covers \`I-001\` and \`I-002\`; pass condition: tests green; metric: 0 fail.
+- [ ] \`VC-002\` covers \`I-002\`; pass condition: lint clean; metric: zero findings.
+`;
+
+	it("parses strict top-level single-line items and ignores continuations", () => {
+		const items = parseImplItems(IMPL_PLAN);
+		assert.equal(items.length, 2);
+		assert.equal(items[0]?.id, "I-001");
+		// First line only: the multi-line body and nested sub-bullet are ignored.
+		assert.match(items[0]!.text, /^Add state helpers/);
+		assert.doesNotMatch(items[0]!.text, /nested/);
+		assert.equal(items[1]?.id, "I-002");
+	});
+
+	it("returns empty without an Implementation Items section", () => {
+		assert.equal(parseImplItems("# no items here\n- `I-001`: orphan\n").length, 0);
+	});
+
+	it("shortens descriptions at sentence or semicolon boundaries and caps length", () => {
+		assert.equal(shortImplDescription("Add helpers; evaluate percent. Then more."), "Add helpers");
+		assert.equal(shortImplDescription("First sentence. Second one."), "First sentence.");
+		const long = "x".repeat(120);
+		assert.equal(shortImplDescription(long).length, 80);
+		assert.match(shortImplDescription(long), /…$/);
+	});
+
+	it("extracts coverage refs before the first semicolon only", () => {
+		assert.deepEqual(extractCoverage("`VC-001` covers `I-001` and `I-002`; pass: `I-003` mentioned late"), ["I-001", "I-002"]);
+		assert.deepEqual(extractCoverage("no coverage clause here"), []);
+	});
+
+	it("scans impl markers", () => {
+		assert.deepEqual(scanImplMarkers("[I-001:implemented] then [I-002:validating] and [I-003:done]"), [
+			{ id: "I-001", state: "implemented" },
+			{ id: "I-002", state: "validating" },
+		]);
+	});
+
+	it("resolves the status matrix with vc-passed > marker > derivation", () => {
+		const items = parseChecklist(IMPL_PLAN);
+		const implItems = parseImplItems(IMPL_PLAN);
+
+		// No markers, nothing done: frontier I-001 implementing, I-002 pending.
+		assert.deepEqual(resolveImplStatuses(implItems, items, undefined), {
+			"I-001": "implementing",
+			"I-002": "pending",
+		});
+
+		// Explicit marker wins over derivation.
+		assert.deepEqual(resolveImplStatuses(implItems, items, { "I-002": "implemented" }), {
+			"I-001": "implementing",
+			"I-002": "implemented",
+		});
+
+		// Some covering VC done without a marker: deriving validating.
+		items[1]!.done = true;
+		assert.deepEqual(resolveImplStatuses(implItems, items, {}), {
+			"I-001": "implementing",
+			"I-002": "validating",
+		});
+
+		// All covering VCs done → vc-passed beats the marker.
+		items[0]!.done = true;
+		assert.deepEqual(resolveImplStatuses(implItems, items, { "I-002": "validating" }), {
+			"I-001": "vc-passed",
+			"I-002": "vc-passed",
+		});
+	});
+});

package/tests/plans.test.ts

@@ -0,0 +1,36 @@
+/** Tests for the plans tool source wiring. */
+
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as url from "node:url";
+import { describe, it } from "node:test";
+
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+
+function readPlansSource(): string {
+	return fs.readFileSync(path.join(ROOT, "tools", "plans.ts"), "utf8");
+}
+
+describe("plans tool source", () => {
+	it("declares artifactRootSource in PlansParams", () => {
+		const source = readPlansSource();
+		const start = source.indexOf("const PlansParams = Type.Object({");
+		const end = source.indexOf("});", start);
+		assert.ok(start >= 0, "missing PlansParams block start");
+		assert.ok(end >= 0, "missing PlansParams block end");
+
+		const params = source.slice(start, end);
+		assert.match(params, /artifactRootSource:\s*Type\.Optional/);
+		assert.match(params, /executionModelSelector:\s*Type\.Optional/);
+		assert.match(params, /executionModelSource:\s*Type\.Optional/);
+	});
+
+	it("keeps the plans handler wired to artifact root and execution model actions", () => {
+		const source = readPlansSource();
+		assert.match(source, /import \{[\s\S]*setArtifactRoot,[\s\S]*setExecutionModel,[\s\S]*\} from "\.\.\/src\/state\.ts";/);
+		assert.match(source, /case "set-artifact-root"/);
+		assert.match(source, /case "set-execution-model"/);
+		assert.match(source, /params\.artifactRootSource/);
+	});
+});

package/tests/state.test.ts

@@ -13,6 +13,7 @@ import {
 	recordDecision,
 	setLanguage,
 	setArtifactRoot,
+	setExecutionModel,
 	setRole,
 	setRunStatus,
 	showConfig,
@@ -68,6 +69,7 @@ describe("init", () => {
 		assert.equal(config.reviewer.mode, "delegated-subagent");
 		assert.equal(config.reviewer.confirmed_at, null);
 		assert.equal(config.criticizer.confirmed_at, null);
+		assert.equal(config.execution.model_selector, null);
 		assert.equal(config.artifact_root, "./docs/pi-plans");
 		assert.equal(config.artifact_root_source, "unset");
 		assert.equal(config.artifact_root_updated_at, null);
@@ -194,6 +196,64 @@ describe("runs", () => {
 		assert.equal(getRun(workdir, run.run_id)?.status, "accepted");
 		assert.throws(() => setRunStatus(workdir, run.run_id, "bogus"), StateError);
 	});
+
+	it("invokes the onStart callback exactly once when startRun succeeds", () => {
+		const workdir = mkWorkdir("onstart");
+		git(workdir, "init", "-q");
+		const calls: string[] = [];
+		const { run } = startRun(workdir, {
+			topic: "marker demo",
+			skill: "plan-normal",
+			requestText: "x",
+			onStart: (current) => {
+				calls.push(current.run_id);
+			},
+		});
+		assert.deepEqual(calls, [run.run_id]);
+	});
+
+	it("does not invoke the onStart callback when startRun throws", () => {
+		const workdir = mkWorkdir("onstart-throw");
+		git(workdir, "init", "-q");
+		const calls: string[] = [];
+		assert.throws(() =>
+			startRun({
+				workdir: path.resolve(workdir),
+				artifact_root: "./docs/pi-plans",
+				artifact_root_source: "user",
+				artifact_root_updated_at: new Date().toISOString(),
+				schema: 1,
+				language: { tag: null, source: "unset", updated_at: null },
+				reviewer: { mode: "delegated-subagent", model_selector: null, name_prefix: "pi-plans-reviewer", confirmed_at: null },
+				criticizer: { mode: "delegated-subagent", model_selector: null, name_prefix: "pi-plans-criticizer", confirmed_at: null },
+				execution: { model_selector: null, source: "unset", updated_at: null },
+			}, {
+				topic: "" as string,
+				skill: "plan-normal",
+				requestText: "x",
+				onStart: () => calls.push("called"),
+			} as any),
+		);
+		assert.equal(calls.length, 0);
+	});
+});
+
+describe("execution model config", () => {
+	it("roundtrips the selector and clears on inherit", () => {
+		const workdir = mkWorkdir("exec-model");
+		git(workdir, "init", "-q");
+		initState(workdir);
+		assert.equal(readConfig(workdir).execution.model_selector, null);
+
+		setExecutionModel(workdir, { modelSelector: "zai/glm-5.3-flash:high", source: "user" });
+		assert.equal(readConfig(workdir).execution.model_selector, "zai/glm-5.3-flash:high");
+		assert.equal(readConfig(workdir).execution.source, "user");
+		assert.equal(showConfig(workdir).execution.model_selector, "zai/glm-5.3-flash:high");
+
+		setExecutionModel(workdir, { modelSelector: "inherit", source: "user" });
+		assert.equal(readConfig(workdir).execution.model_selector, null);
+		assert.equal(readConfig(workdir).execution.source, "user");
+	});
 });
 
 describe("set-role invariants", () => {

package/tools/execute-plan.ts

@@ -8,9 +8,26 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { startExecution } from "../src/exec.ts";
-import { latestPlanVersion, parseChecklist } from "../src/plan.ts";
-import { normalizeWorkdir, readActive } from "../src/state.ts";
+import {
+	chooseExecutionModelSelection,
+	snapshotCurrentModelSelector,
+	startExecution,
+	type ExecutionModelState,
+} from "../src/exec.ts";
+import { extractCoverage, latestPlanVersion, parseChecklist, parseImplItems } from "../src/plan.ts";
+import { loadConfig, normalizeWorkdir, readActive, resolveStateRootOrNull, setExecutionModel, type ExecutionConfig } from "../src/state.ts";
+
+function loadExecutionModelConfig(workdir: string): ExecutionConfig {
+	const root = resolveStateRootOrNull(workdir);
+	if (!root) {
+		return { model_selector: null, source: "unset", updated_at: null };
+	}
+	try {
+		return loadConfig(root).execution;
+	} catch {
+		return { model_selector: null, source: "unset", updated_at: null };
+	}
+}
 
 const ExecutePlanParams = Type.Object({
 	planPath: Type.Optional(
@@ -55,13 +72,15 @@ export async function executeHandoff(
 		return { status: "error", message: `Plan file not found: ${planPath}` };
 	}
 
-	const items = parseChecklist(fs.readFileSync(planPath, "utf8"));
+	const planText = fs.readFileSync(planPath, "utf8");
+	const items = parseChecklist(planText);
 	if (items.length === 0) {
 		return {
 			status: "error",
 			message: `${planPath} has no parsable \`## Verifier Checklist\` with \`- [ ] \`VC-###\` ...\` items. Fix the plan before execution.`,
 		};
 	}
+	const implItems = parseImplItems(planText);
 
 	if (!ctx.hasUI) {
 		return {
@@ -80,12 +99,33 @@ export async function executeHandoff(
 		return { status: "declined", message: "User declined execution. Stay in planning; ask how to proceed.", planPath };
 	}
 
-	startExecution(getCurrentApi(), ctx, planPath, items);
+	const configuredExecution = loadExecutionModelConfig(workdir);
+	let modelState: ExecutionModelState | undefined;
+	const planningSelector = snapshotCurrentModelSelector(ctx);
+	const selection = await chooseExecutionModelSelection(
+		ctx,
+		"Execution model",
+		configuredExecution,
+		async (selector) => {
+			await setExecutionModel(workdir, { modelSelector: selector, source: "user" });
+		},
+	);
+	if (!selection) {
+		return { status: "error", message: "No usable execution model; execution cancelled." };
+	}
+	if (configuredExecution.source === "unset" || configuredExecution.model_selector !== null) {
+		modelState = { planningSelector, executionSelector: selection.selector };
+	}
+
+	await startExecution(getCurrentApi(), ctx, planPath, items, modelState, implItems);
+	const countedImpls = implItems.filter((impl) => items.some((item) => extractCoverage(item.text).includes(impl.id)));
+	const modelNote = modelState ? ` Execution model: ${modelState.executionSelector}.` : "";
+	const scopeNote = countedImpls.length ? ` Tracking ${countedImpls.length} implementation item(s).` : "";
 	return {
 		status: "executing",
 		planPath,
 		itemCount: items.length,
-		message: `Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].`,
+		message: `Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].${scopeNote}${modelNote}`,
 	};
 }
 

package/tools/plans.ts

@@ -15,6 +15,7 @@ import {
 	recordSubagent,
 	resolveStateRootOrNull,
 	setArtifactRoot,
+	setExecutionModel,
 	setLanguage,
 	setRunStatus,
 	setRole,
@@ -31,6 +32,7 @@ const PlansParams = Type.Object({
 			"show",
 			"set-language",
 			"set-artifact-root",
+			"set-execution-model",
 			"set-role",
 			"start-run",
 			"set-status",
@@ -50,6 +52,10 @@ const PlansParams = Type.Object({
 	languageSource: Type.Optional(StringEnum(["user", "auto"] as const)),
 	artifactRoot: Type.Optional(Type.String({ description: "set-artifact-root: planning docs root, e.g. ./docs/pi-plans" })),
 	artifactRootSource: Type.Optional(StringEnum(["user", "auto"] as const)),
+	executionModelSelector: Type.Optional(
+		Type.String({ description: "set-execution-model: exact provider/model selector, or 'inherit' to clear" }),
+	),
+	executionModelSource: Type.Optional(StringEnum(["user", "auto"] as const)),
 	role: Type.Optional(StringEnum(["reviewer", "criticizer"] as const)),
 	mode: Type.Optional(StringEnum(["delegated-subagent", "current-session"] as const)),
 	modelSelector: Type.Optional(
@@ -96,12 +102,25 @@ const PlansParams = Type.Object({
 	),
 });
 
+// Module-level reference so the start-run action can append a session entry
+// (pi-plans-run-start) at the moment the planning run begins. The ExtensionAPI
+// itself is not in scope for `startRun`, mirroring `setCurrentApi` in
+// tools/execute-plan.ts.
+let runStartAppender: ((runId: string, artifactDir: string) => void) | null = null;
+
+export function setRunStartAppender(appender: ((runId: string, artifactDir: string) => void) | null): void {
+	runStartAppender = appender;
+}
+
 export function registerPlansTool(pi: ExtensionAPI): void {
+	setRunStartAppender((runId, artifactDir) => {
+		pi.appendEntry("pi-plans-run-start", { runId, artifactDir });
+	});
 	pi.registerTool({
 		name: "plans",
 		label: "Plans",
 		description:
-			"Manage pi-plans planning state in the target workspace: init/show config, set language and planning docs root plus reviewer/criticizer roles, start planning runs, record decisions/refs/subagents, and update run status. State lives in .git/pi_plans/ inside the resolved git common dir. Actions: init, show, set-language, set-artifact-root, set-role, start-run, set-status, record-decision, record-ref, record-subagent.",
+			"Manage pi-plans planning state in the target workspace: init/show config, set language and planning docs root plus execution/reviewer/criticizer roles, start planning runs, record decisions/refs/subagents, and update run status. State lives in .git/pi_plans/ inside the resolved git common dir. Actions: init, show, set-language, set-artifact-root, set-execution-model, set-role, start-run, set-status, record-decision, record-ref, record-subagent.",
 		promptSnippet: "Manage pi-plans planning state, runs, and ledgers",
 		parameters: PlansParams,
 
@@ -137,6 +156,17 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 						result = { config: updated.config, stateRoot: updated.stateRoot, notices: updated.notices };
 						break;
 					}
+					case "set-execution-model": {
+						if (!params.executionModelSelector || !params.executionModelSource) {
+							throw new StateError("set-execution-model requires executionModelSelector and executionModelSource");
+						}
+						const updated = setExecutionModel(workdir, {
+							modelSelector: params.executionModelSelector,
+							source: params.executionModelSource,
+						});
+						result = { config: updated.config, stateRoot: updated.stateRoot, notices: updated.notices };
+						break;
+					}
 					case "set-role": {
 						if (!params.role) throw new StateError("set-role requires role");
 						const updated = setRole(workdir, {
@@ -157,6 +187,9 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 							topic: params.topic,
 							skill: params.skill,
 							requestText: params.requestText,
+							onStart: (run) => {
+								runStartAppender?.(run.run_id, run.artifact_dir);
+							},
 						});
 						break;
 					}