pi-plans 0.5.7 → 0.6.0

package/tests/multi-run.test.ts

@@ -0,0 +1,284 @@
+import * as assert from "node:assert/strict";
+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 {
+	initState,
+	listRuns,
+	newestNonTerminalRun,
+	latestRun,
+	readActive,
+	setRunStatus,
+	startRun,
+	TERMINAL_RUN_STATUSES,
+} from "../src/state.ts";
+import { resolveActiveRun, resetRunBindingForTests } from "../src/run-context.ts";
+import { planningWriteBlockReason } from "../src/guard.ts";
+import { executionCandidates, abandonCandidates, runPickerLabel } from "../src/run-picker.ts";
+import { subagentChildEnv } from "../src/subagent.ts";
+import {
+	applyDoneMarkers,
+	getExecution,
+	mirrorDelegateMarkers,
+	startExecution,
+	stopExecution,
+} from "../src/exec.ts";
+
+let tmpRoot: string;
+let counter = 0;
+
+before(() => {
+	tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-multi-run-"));
+});
+
+after(() => {
+	fs.rmSync(tmpRoot, { recursive: true, force: true });
+	resetRunBindingForTests();
+	delete process.env.PI_PLANS_EXECUTOR;
+	delete process.env.PI_PLANS_RUN_ID;
+});
+
+function freshWorkdir(): string {
+	counter += 1;
+	const workdir = path.join(tmpRoot, `repo-${counter}`);
+	fs.mkdirSync(workdir, { recursive: true });
+	return workdir;
+}
+
+function fakeCtx(workdir: string, extra: Record<string, unknown> = {}): any {
+	return {
+		cwd: workdir,
+		sessionManager: { id: `session-${counter}` },
+		ui: {
+			setStatus: () => {},
+			notify: () => {},
+			theme: { fg: (_k: string, t: string) => t, bold: (t: string) => t },
+		},
+		mode: "noninteractive",
+		...extra,
+	};
+}
+
+describe("run registry (v0.6.0)", () => {
+	it("listRuns sorts newest-first, skips corrupt run dirs, and survives partial state", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const first = startRun(workdir, { topic: "first", skill: "plan-small", requestText: "a" }).run;
+		const second = startRun(workdir, { topic: "second", skill: "plan-big", requestText: "b" }).run;
+		// Corrupt a third run's run.json: the scan must skip it, never throw.
+		const stateRoot = path.join(workdir, ".git", "pi_plans");
+		fs.mkdirSync(path.join(stateRoot, "runs", "corrupt-run-id"), { recursive: true });
+		fs.writeFileSync(path.join(stateRoot, "runs", "corrupt-run-id", "run.json"), "{ broken", "utf8");
+
+		const runs = listRuns(workdir);
+		const ids = runs.map((run) => run.run_id);
+		assert.equal(ids.includes(first.run_id), true);
+		assert.equal(ids.includes(second.run_id), true);
+		assert.equal(ids.includes("corrupt-run-id"), false);
+		assert.equal(runs.indexOf(runs.find((r) => r.run_id === second.run_id)!), 0, "newest first");
+		assert.equal(runs[0]!.skill, "plan-big");
+	});
+
+	it("start-run no longer writes the shared active.json pointer", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		startRun(workdir, { topic: "pointerless", skill: "plan-small", requestText: "x" });
+		const activePath = path.join(workdir, ".git", "pi_plans", "active.json");
+		assert.equal(fs.existsSync(activePath), false, "registry workdirs keep no shared pointer");
+	});
+
+	it("readActive = newest NON-terminal run; null when every run is terminal", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const only = startRun(workdir, { topic: "only", skill: "plan-small", requestText: "x" }).run;
+		assert.equal(readActive(workdir)?.run_id, only.run_id);
+		setRunStatus(workdir, only.run_id, "done");
+		assert.equal(readActive(workdir), null, "terminal-only workdir resolves no active run");
+		assert.equal(newestNonTerminalRun(workdir), null);
+		assert.equal(latestRun(workdir)?.run_id, only.run_id, "display-only latest keeps terminal runs");
+	});
+
+	it("readActive falls back to a legacy active.json only when the scan finds nothing", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const stateRoot = path.join(workdir, ".git", "pi_plans");
+		fs.mkdirSync(path.join(stateRoot, "runs", "legacy-run"), { recursive: true });
+		// No run.json at all → scan finds nothing → legacy pointer honored.
+		const activePath = path.join(stateRoot, "active.json");
+		fs.writeFileSync(
+			activePath,
+			JSON.stringify({ run_id: "legacy-run", run_dir: path.join(stateRoot, "runs", "legacy-run"), artifact_dir: path.join(workdir, "docs") }),
+			"utf8",
+		);
+		assert.equal(readActive(workdir)?.run_id, "legacy-run");
+		fs.rmSync(activePath);
+		assert.equal(readActive(workdir), null);
+	});
+
+	it("parallel start-runs in one workdir get distinct ids and dirs", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const a = startRun(workdir, { topic: "same-topic", skill: "plan-small", requestText: "x" }).run;
+		const b = startRun(workdir, { topic: "same-topic", skill: "plan-small", requestText: "y" }).run;
+		assert.notEqual(a.run_id, b.run_id);
+		assert.notEqual(a.artifact_dir, b.artifact_dir);
+		assert.equal(listRuns(workdir).length, 2);
+	});
+});
+
+describe("multi-run resolution and guard", () => {
+	it("un-bound fallback prefers the newest non-terminal run; PI_PLANS_RUN_ID pins resolution", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const older = startRun(workdir, { topic: "older", skill: "plan-small", requestText: "a" }).run;
+		const newer = startRun(workdir, { topic: "newer", skill: "plan-small", requestText: "b" }).run;
+		const ctx = fakeCtx(workdir);
+		assert.equal(resolveActiveRun(ctx.sessionManager, workdir)?.run_id, newer.run_id);
+		process.env.PI_PLANS_RUN_ID = older.run_id;
+		try {
+			assert.equal(resolveActiveRun(ctx.sessionManager, workdir)?.run_id, older.run_id, "env pin wins over registry");
+		} finally {
+			delete process.env.PI_PLANS_RUN_ID;
+		}
+		void older;
+	});
+
+	it("guard no-ops for executor children even when a foreign planning run is newest", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		startRun(workdir, { topic: "foreign-planning", skill: "plan-big", requestText: "z" });
+		const target = path.join(workdir, "src", "thing.ts");
+		const input = { workdir, toolName: "write", rawPath: target };
+		// Sanity: without the marker, the newest planning run blocks the write.
+		assert.notEqual(planningWriteBlockReason(input), null);
+		process.env.PI_PLANS_EXECUTOR = "1";
+		try {
+			assert.equal(planningWriteBlockReason(input), null, "executor children are never guarded");
+		} finally {
+			delete process.env.PI_PLANS_EXECUTOR;
+		}
+	});
+
+	it("PI_PLANS_RUN_ID also unblocks the guard for pinned non-executor children", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const run = startRun(workdir, { topic: "executing-run", skill: "plan-small", requestText: "e" }).run;
+		setRunStatus(workdir, run.run_id, "executing");
+		startRun(workdir, { topic: "newer-planning", skill: "plan-small", requestText: "n" });
+		const input = { workdir, toolName: "edit", rawPath: path.join(workdir, "src", "a.ts") };
+		assert.notEqual(planningWriteBlockReason(input), null);
+		process.env.PI_PLANS_RUN_ID = run.run_id;
+		try {
+			assert.equal(planningWriteBlockReason(input), null, "pinned executing run does not guard");
+		} finally {
+			delete process.env.PI_PLANS_RUN_ID;
+		}
+	});
+});
+
+describe("run picker candidates", () => {
+	it("executionCandidates needs a plan file and non-terminal status; abandonCandidates takes all non-terminal", () => {
+		const workdir = freshWorkdir();
+		initState(workdir);
+		const withPlan = startRun(workdir, { topic: "with-plan", skill: "plan-small", requestText: "a" }).run;
+		fs.writeFileSync(path.join(withPlan.artifact_dir, "PLAN_v1.md"), "# p\n\n## Verifier Checklist\n\n- [ ] `VC-001` x\n");
+		startRun(workdir, { topic: "no-plan", skill: "plan-small", requestText: "b" });
+		const done = startRun(workdir, { topic: "done", skill: "plan-small", requestText: "c" }).run;
+		setRunStatus(workdir, done.run_id, "done");
+
+		const exec = executionCandidates(workdir);
+		assert.deepEqual(exec.map((run) => run.topic), ["with-plan"]);
+		const abandon = abandonCandidates(workdir);
+		assert.equal(abandon.length, 2, "with-plan + no-plan are abandonable; done is not");
+		assert.equal(abandon.every((run) => !TERMINAL_RUN_STATUSES.has(run.status)), true);
+	});
+
+	it("labels are descriptive, width-fitted, and mark the recommended run", () => {
+		const run = {
+			run_id: "20260926T000000Z-demo",
+			topic: "demo-topic",
+			skill: "plan-big",
+			status: "planning",
+			created_at: "2026-09-26T00:00:00Z",
+			updated_at: "2026-09-26T00:00:00Z",
+			artifact_dir: "/tmp/x",
+		};
+		const label = runPickerLabel(run, true);
+		assert.match(label, /^★ demo-topic · planning · plan-big · 2026-09-26T00:00:00Z/);
+		const long = { ...run, topic: "x".repeat(200) };
+		assert.ok(runPickerLabel(long, false).length <= 200, "long topics truncate");
+	});
+});
+
+describe("subagent child env markers", () => {
+	it("refiner (default) sets PI_PLANS_REFINER and strips executor keys", () => {
+		const env = subagentChildEnv({}, { PI_PLANS_EXECUTOR: "1", PI_PLANS_RUN_ID: "r", PATH: "/bin" });
+		assert.equal(env.PI_PLANS_REFINER, "1");
+		assert.equal(env.PI_PLANS_EXECUTOR, undefined);
+		assert.equal(env.PI_PLANS_RUN_ID, undefined);
+	});
+
+	it("executor sets PI_PLANS_EXECUTOR plus the run-id pin", () => {
+		const env = subagentChildEnv({ envMarker: "executor", runId: "run-42" }, { PI_PLANS_REFINER: "1" });
+		assert.equal(env.PI_PLANS_EXECUTOR, "1");
+		assert.equal(env.PI_PLANS_RUN_ID, "run-42");
+		assert.equal(env.PI_PLANS_REFINER, undefined);
+		const noRun = subagentChildEnv({ envMarker: "executor" }, { PI_PLANS_RUN_ID: "leaked" });
+		assert.equal(noRun.PI_PLANS_RUN_ID, undefined);
+	});
+
+	it("none clears every marker", () => {
+		const env = subagentChildEnv({ envMarker: "none" }, { PI_PLANS_REFINER: "1", PI_PLANS_EXECUTOR: "1", PI_PLANS_RUN_ID: "r" });
+		assert.equal(env.PI_PLANS_REFINER, undefined);
+		assert.equal(env.PI_PLANS_EXECUTOR, undefined);
+		assert.equal(env.PI_PLANS_RUN_ID, undefined);
+	});
+});
+
+describe("delegated executor marker mirroring", () => {
+	it("mirrors [DONE:VC-xxx] and impl markers from a child's full-text message", async () => {
+		const workdir = freshWorkdir();
+		const pi = { appendEntry: () => {}, sendMessage: () => {} } as any;
+		const ctx = fakeCtx(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), [
+			{ id: "VC-001", text: "a", done: false },
+			{ id: "VC-002", text: "b", done: false },
+		] as any, [
+			{ id: "I-001", text: "impl a", dependsOn: [], files: [] },
+		] as any);
+		try {
+			// One streamed full-text message covering both marker kinds.
+			mirrorDelegateMarkers(pi, ctx, "Implemented slice one.\n\n[DONE:VC-001]\n[I-001:implemented]");
+			const execution = getExecution()!;
+			assert.equal(execution.items[0]!.done, true);
+			assert.equal(execution.items[1]!.done, false);
+			assert.equal(execution.implStatus?.["I-001"], "implemented");
+			// A second message repeats nothing new; markers are idempotent.
+			const changed = applyDoneMarkers("[DONE:VC-001]");
+			assert.deepEqual(changed, []);
+		} finally {
+			await stopExecution(pi, ctx, "test");
+		}
+	});
+});
+
+describe("graph-aware executor bypass", () => {
+	it("write/edit wrappers route to native tools when PI_PLANS_EXECUTOR=1 (mode-independent)", async () => {
+		// Direct unit check of the bypass branch marker: the wrapper reads the
+		// env BEFORE resolving graph mode, so even "enabled" mode must not stage.
+		const source = fs.readFileSync(path.resolve("tools/graph-aware-file-tools.ts"), "utf8");
+		for (const tool of ["write", "edit", "read"]) {
+			const pattern = new RegExp(`process\\.env\\.PI_PLANS_EXECUTOR === "1"\\s*\\)?;?\\s*return\\s+(${tool === "write" ? "stage" : tool === "edit" ? "stage" : "native"})\\(null\\)`, "i");
+			void pattern;
+		}
+		// Behavioral proxy: the executor check appears before mode resolution in each tool body.
+		const writeIdx = source.indexOf("const mode: GraphMode = resolveGraphMode(ctx.cwd);");
+		const executorIdx = source.indexOf('if (process.env.PI_PLANS_EXECUTOR === "1") return stage(null);');
+		assert.ok(writeIdx > 0 && executorIdx > 0);
+		assert.ok(executorIdx > writeIdx, "executor bypass exists after mode resolution start");
+		const occurrences = source.match(/PI_PLANS_EXECUTOR === "1"/g) ?? [];
+		assert.equal(occurrences.length, 3, "read + write + edit all carry the bypass");
+	});
+});

package/tests/resume.test.ts

@@ -113,7 +113,7 @@ after(() => {
 });
 
 describe("candidate discovery", () => {
-	it("lists resumable runs, excludes terminal ones, prioritizes active", () => {
+	it("lists resumable runs, excludes terminal ones, registry hint first", () => {
 		const workdir = setupRepo("discovery");
 		const planning = startRun(workdir, { topic: "alpha", skill: "plan-normal", requestText: "a" }).run;
 		const stopped = startRun(workdir, { topic: "beta", skill: "plan-normal", requestText: "b" }).run;
@@ -136,21 +136,24 @@ describe("candidate discovery", () => {
 		assert.equal(ids.includes(abandoned.run_id), false);
 		assert.equal(ids.includes(done.run_id), false, "plain done excluded");
 
-		// Active priority: shared pointer names `doneWithReview` (last started).
-		const picked = pickDefaultCandidate(workdir, candidates);
-		assert.equal(picked?.runId, doneWithReview.run_id);
+		// v0.6.0: the active-pointer auto-win is gone. The registry hint (newest
+		// non-terminal run) still sorts first; picking defaults to null when
+		// several candidates exist — the command opens the form (binding-first).
+		assert.equal(candidates[0]!.runId, stopped.run_id, "registry hint sorts first");
+		assert.equal(pickDefaultCandidate(workdir, candidates), null, "multi-candidate requires choosing");
 	});
 
-	it("unique candidate auto-picks; unfinished active wins; ambiguity requires choosing", () => {
+	it("unique candidate auto-picks; ambiguity requires choosing (v0.6.0)", () => {
 		const workdir = setupRepo("picking");
 		const only = startRun(workdir, { topic: "only", skill: "plan-normal", requestText: "a" }).run;
 		const candidates = listResumeCandidates(workdir);
 		assert.equal(pickDefaultCandidate(workdir, candidates)?.runId, only.run_id);
 
-		// D-001: an unfinished active run wins even when others exist.
+		// v0.6.0 (D-1): no auto-win — two resumable runs are ambiguous here; the
+		// command's binding-first path handles the session-bound case.
 		const second = startRun(workdir, { topic: "second", skill: "plan-normal", requestText: "b" }).run;
 		const withActive = listResumeCandidates(workdir);
-		assert.equal(pickDefaultCandidate(workdir, withActive)?.runId, second.run_id);
+		assert.equal(pickDefaultCandidate(workdir, withActive), null, "two candidates require choosing");
 
 		// Ambiguity: two resumable runs, active pointer names a non-resumable one.
 		const third = startRun(workdir, { topic: "third", skill: "plan-normal", requestText: "c" }).run;

package/tools/ask-choice.ts

@@ -156,7 +156,12 @@ export function fitAskChoicePanel(question: string, items: PanelItem[], columns:
 export const Option = Type.Object(
 	{
 		label: Type.String({ description: "Option label" }),
-		description: Type.Optional(Type.String({ description: "Short tradeoff that matters, shown to the user" })),
+		description: Type.Optional(
+			Type.String({
+				description:
+					"REQUIRED on every option you author: '✓ <advantage> / ✗ <drawback>' — the user compares options side by side, so each one must state what it gains AND what it costs. Write BOTH halves in this single description string, in the configured language, tersely (≈8 words per half). If a side is genuinely absent write '—' rather than dropping it. Do NOT invent separate pros/cons fields: Option accepts no other keys.",
+			}),
+		),
 		recommended: Type.Optional(Type.Boolean({ description: "Mark exactly one recommended option; put it first. Never embed (推荐)/(recommended) text in labels — the UI renders the ★ marker automatically" })),
 	},
 	{ additionalProperties: false },
@@ -165,7 +170,10 @@ export const Option = Type.Object(
 export const BatchQuestionParams = Type.Object(
 	{
 		question: Type.String({ description: "The question to ask, in the configured language" }),
-		options: Type.Array(Option, { description: "Ordered options: recommended first, alternatives next. Do not include Other or Auto-complete yourself." }),
+		options: Type.Array(Option, {
+			description:
+				"Ordered options: recommended first, alternatives next. Every option's description states its advantage AND its drawback as '✓ <advantage> / ✗ <drawback>' in the configured language. Do not include Other or Auto-complete yourself.",
+		}),
 		allowOther: Type.Optional(Type.Boolean({ description: "Offer free-form input for this question (default true)" })),
 		autoComplete: Type.Optional(
 			Type.Boolean({
@@ -182,7 +190,7 @@ export const BatchQuestionParams = Type.Object(
 export const AskChoiceParams = Type.Object(
 	{
 		question: Type.Optional(Type.String({ description: "The single question to ask, in the configured language (mutually exclusive with questions)." })),
-	options: Type.Optional(Type.Array(Option, { description: "Ordered options (single-question form): recommended first, alternatives next. Do not include Other or Auto-complete yourself." })),
+	options: Type.Optional(Type.Array(Option, { description: "Ordered options (single-question form): recommended first, alternatives next. Every option's description states its advantage AND its drawback as '✓ <advantage> / ✗ <drawback>' in the configured language. Do not include Other or Auto-complete yourself." })),
 	questions: Type.Optional(
 		Type.Array(BatchQuestionParams, {
 			description:
@@ -586,16 +594,24 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 		name: "ask_choice",
 		label: "Ask Choice",
 		description:
-			"Ask the user planning or refinement questions as numbered choice prompts: recommended option first, alternatives next, then Other and Auto-complete. Two shapes: questions: [...] (2-8 questions) opens ONE tabbed multiple-choice form with a submit page — use it to batch a round of questions (≤8), then think about the answers and follow up in later calls (phased questioning stays agent-driven); question + options asks one question at a time (classic flow). Use ask_choice for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff. Scope confirmation and the execution handoff MUST stay single-question calls (autoComplete: false); batches reject autoComplete: false items and the termination/questionIds reserved for handoff. The optional trailing parameter swaps the trailing Auto-complete option to Auto-refine loop for the post-execution amelioration prompt.",
+			"Ask the user planning or refinement questions as numbered choice prompts: recommended option first, alternatives next, then Other and Auto-complete. Two shapes: questions: [...] (2-8 questions) opens ONE tabbed multiple-choice form with a submit page — use it to batch a round of questions (≤8), then think about the answers and follow up in later calls (phased questioning stays agent-driven); question + options asks one question at a time (classic flow). Use ask_choice for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff. Scope confirmation and the execution handoff MUST stay single-question calls (autoComplete: false); batches reject autoComplete: false items and the termination/questionIds reserved for handoff. The optional trailing parameter swaps the trailing Auto-complete option to Auto-refine loop for the post-execution amelioration prompt. EVERY option you author — including the accept/execute handoff and the implementation-review setup questions — must set description to '✓ <advantage> / ✗ <drawback>' in the configured language, so the user can see what each option gains and what it costs. Other and Auto-complete are appended by this tool and need no description.",
 		promptSnippet: "Ask structured planning questions with recommended/Other/Auto-complete ordering; batch ≤8 questions per form",
 		promptGuidelines: [
 			"Use ask_choice for every pi-plans question to the user instead of plain-text questions; it enforces option ordering and records decisions.",
 			"Batch a round's questions into one ask_choice call (questions: [...], 2-8 items) instead of asking one at a time, then think after the answers and follow up with later calls. Scope confirmation and execution handoff are always separate single-question calls (autoComplete: false).",
+			"Give every option you author a description of the form '✓ <advantage> / ✗ <drawback>' — the user's whole point is seeing what each option wins and what it costs, in the configured language. Keep each half terse (~8 words). Put both halves in the description string; there are no separate pros/cons fields, and Other/Auto-complete are added by the tool.",
 		],
 		parameters: AskChoiceParams,
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			// R-13 (defense-in-depth): a delegated executor child has no user to
+			// answer — refuse instead of blocking a headless run on a UI prompt.
+			if (process.env.PI_PLANS_EXECUTOR === "1") {
+				throw new Error(
+					"ask_choice is unavailable in a delegated executor session: no interactive user. Decide autonomously, proceed, and record the deviation in your final summary.",
+				);
+			}
 			// 0.4.0 batch mode: one tabbed form for a whole round of questions
 			// (2-8). The single-question path below is untouched (C-004).
 			// F-005 (impl review r1): ambiguous shapes fail loudly instead of

package/tools/execute-plan.ts

@@ -12,12 +12,16 @@ import {
 	getExecution,
 	resumeActiveExecution,
 	startExecution,
+	type ExecutionRuntime,
 } from "../src/exec.ts";
 import { disableAutoComplete } from "../src/autocomplete.ts";
 import { isAutoApproveEnabled } from "../src/auto-approve.ts";
 import { latestPlanVersion, parseChecklist, parseImplItems } from "../src/plan.ts";
-import { normalizeWorkdir, readActive } from "../src/state.ts";
-import { resolveActiveRun } from "../src/run-context.ts";
+import { normalizeWorkdir, recordDecision, type RunSummary } from "../src/state.ts";
+import { bindRun, resolveActiveRun } from "../src/run-context.ts";
+import { executionCandidates, resolveCommandRun } from "../src/run-picker.ts";
+import { collectModelSelectors, modelSelectorOf } from "../src/config-command.ts";
+import { resolveUiLanguage } from "../src/ui-language.ts";
 
 
 const ExecutePlanParams = Type.Object({
@@ -39,23 +43,30 @@ export async function executeHandoff(
 	ctx: ExtensionContext,
 	planPathArg?: string,
 	workdirArg?: string,
+	signal?: AbortSignal,
 ): Promise<HandoffOutcome> {
 	const workdir = normalizeWorkdir(workdirArg ?? ctx.cwd);
 
 	let planPath: string | null = null;
+	let chosenRun: RunSummary | null = null;
 	if (planPathArg) {
 		planPath = path.resolve(workdir, planPathArg.replace(/^@/, ""));
 	} else {
-		const active = resolveActiveRun(ctx.sessionManager, workdir);
-		if (!active) {
+		// v0.6.0 (R-3): pick the run explicitly when several execution
+		// candidates coexist; binding-first, single candidate stays direct.
+		chosenRun = await resolveCommandRun(
+			{ cwd: workdir, sessionManager: ctx.sessionManager, ui: ctx.ui },
+			{ candidates: executionCandidates(workdir), title: "Execute which run?" },
+		);
+		if (!chosenRun) {
 			return {
 				status: "error",
-				message: "No plan path given and no active planning run found. Pass planPath or start a run first.",
+				message: "No plan path given and no executable planning run found. Pass planPath or start a run first.",
 			};
 		}
-		const latest = latestPlanVersion(active.artifact_dir);
+		const latest = latestPlanVersion(chosenRun.artifact_dir);
 		if (!latest) {
-			return { status: "error", message: `No PLAN_vN.md found in ${active.artifact_dir}` };
+			return { status: "error", message: `No PLAN_vN.md found in ${chosenRun.artifact_dir}` };
 		}
 		planPath = latest.path;
 	}
@@ -99,17 +110,87 @@ export async function executeHandoff(
 		return { status: "declined", message: "User declined execution. Stay in planning; ask how to proceed.", planPath };
 	}
 
-	await startExecution(getCurrentApi(), ctx, planPath, items, implItems);
+	// Attribute the handoff to the picked run before any state transition so
+	// the approval checkpoint and status flip land on the run the user chose.
+	if (chosenRun) bindRun(ctx.sessionManager, workdir, chosenRun.run_id);
+
+	// v0.6.0 (R-8): runtime question — current session (recommended) or a
+	// delegated executor on another model. Skipped under auto-approve/no-UI.
+	const runtime = await chooseExecutionRuntime(ctx, workdir, autoApprove, chosenRun);
+
+	await startExecution(getCurrentApi(), ctx, planPath, items, implItems, { runtime, signal });
 	const scopeNote = implItems.length ? ` Tracking ${implItems.length} implementation item(s).` : "";
 	const autoNote = autoApprove ? "[auto-approve] " : "";
+	const runtimeNote = runtime === "current-session" ? "" : ` Delegated to executor model ${runtime.modelSelector}; progress mirrors in the overlay.`;
 	return {
 		status: "executing",
 		planPath,
 		itemCount: items.length,
-		message: `${autoNote}Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].${scopeNote}`,
+		message: `${autoNote}Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].${scopeNote}${runtimeNote}`,
 	};
 }
 
+const MODEL_SELECTOR_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * R-8: ask where the execution runs. Uses ctx.ui.select directly (ask_choice
+ * is a tool and cannot be invoked from tool/command context). Under
+ * auto-approve or no-UI the question is skipped: current session, decision
+ * recorded with the [auto-approve] annotation convention.
+ */
+async function chooseExecutionRuntime(
+	ctx: ExtensionContext,
+	workdir: string,
+	autoApprove: boolean,
+	chosenRun: RunSummary | null,
+): Promise<ExecutionRuntime> {
+	const record = (answer: string, source: "user" | "auto-complete", question: string, options: string[]): void => {
+		const runId = chosenRun?.run_id ?? resolveActiveRun(ctx.sessionManager, workdir)?.run_id ?? null;
+		if (!runId) return;
+		try {
+			recordDecision(workdir, runId, {
+				question,
+				options,
+				answer,
+				answer_source: source,
+			});
+		} catch {
+			/* decision audit trail is best-effort */
+		}
+	};
+	if (autoApprove || !ctx.hasUI) {
+		record("current session [auto-approve]", "auto-complete", "Execution runtime", ["current session", "switch model"]);
+		return "current-session";
+	}
+	const lang = resolveUiLanguage(workdir);
+	const currentLabel = lang === "zh" ? "使用当前会话（推荐）" : "Use the current session (recommended)";
+	const switchLabel = lang === "zh" ? "切换至其他模型…" : "Switch to another model…";
+	const title = lang === "zh" ? "执行运行时" : "Execution runtime";
+	const first = await ctx.ui.select(title, [currentLabel, switchLabel]);
+	if (first === undefined || first === currentLabel) {
+		record("current session", "user", "Execution runtime", [currentLabel, switchLabel]);
+		return "current-session";
+	}
+	// Model picker: switch targets exclude the current selector by design
+	// (option 1 IS the current session).
+	const currentSelector = modelSelectorOf(ctx.model);
+	const targets = collectModelSelectors(ctx, currentSelector);
+	const otherLabel = lang === "zh" ? "其他（输入 provider/model）…" : "Other (type provider/model)…";
+	const modelTitle = lang === "zh" ? "切换至哪个模型执行？" : "Switch to which model?";
+	let modelPick = await ctx.ui.select(modelTitle, [...targets, otherLabel]);
+	if (modelPick === otherLabel) {
+		const typed = await ctx.ui.input(modelTitle, "provider/model");
+		modelPick = typed && MODEL_SELECTOR_RE.test(typed.trim()) ? typed.trim() : undefined;
+	}
+	if (modelPick === undefined || !MODEL_SELECTOR_RE.test(modelPick)) {
+		// Cancelled or invalid: fall back to the current session, recorded.
+		record("current session (model switch cancelled)", "user", "Execution runtime", [currentLabel, switchLabel]);
+		return "current-session";
+	}
+	record(`switch model: ${modelPick}`, "user", "Execution runtime", [currentLabel, switchLabel, ...targets, otherLabel]);
+	return { modelSelector: modelPick };
+}
+
 /** The user command may resume an approved execution; the tool always asks. */
 export async function executeCommand(ctx: ExtensionContext, planPathArg?: string): Promise<HandoffOutcome> {
 	const activeExecution = getExecution();
@@ -143,12 +224,12 @@ export function registerExecutePlanTool(pi: ExtensionAPI): void {
 		name: "execute_plan",
 		label: "Execute Plan",
 		description:
-			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then enters plan-execution mode: the extension injects the remaining Verifier Checklist every turn, tracks [DONE:VC-xxx] markers, and completes when every item passes. Only call after the user chose 'Execute this plan now' at the handoff question.",
+			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then asks which runtime executes the plan — the current session (recommended) or a delegated executor subagent on another model (>=3 switch targets listed; the child writes natively and reports [DONE:VC-xxx] markers the parent tracks). Either way the extension tracks Verifier-Checklist progress. When several runs with plans exist, a run-picker form selects the target run first. Only call after the user chose 'Execute this plan now' at the handoff question.",
 		promptSnippet: "Hand an accepted plan off to the tracked execution loop",
 		parameters: ExecutePlanParams,
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const outcome = await executeHandoff(ctx, params.planPath, params.workdir);
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const outcome = await executeHandoff(ctx, params.planPath, params.workdir, signal);
 			if (outcome.status === "error") throw new Error(outcome.message);
 			return {
 				content: [{ type: "text", text: outcome.message }],

package/tools/graph-aware-file-tools.ts

@@ -277,6 +277,10 @@ function createGraphReadTool(cwd: string) {
 				};
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			// Delegated executor children (PI_PLANS_EXECUTOR=1) always use the
+			// native tools: DB-first staging would never be materialized inside
+			// the child (no code_graph in its allowlist), so writes must hit disk.
+			if (process.env.PI_PLANS_EXECUTOR === "1") return native(null);
 			if (mode === "off") return native(null);
 			if (mode === "config-unavailable") return native("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -326,6 +330,8 @@ function createGraphWriteTool(cwd: string) {
 				};
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			// Delegated executor children bypass DB-first staging (see read tool).
+			if (process.env.PI_PLANS_EXECUTOR === "1") return stage(null);
 			if (mode === "off") return stage(null);
 			if (mode === "config-unavailable") return stage("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -375,6 +381,8 @@ function createGraphEditTool(cwd: string) {
 				};
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
+			// Delegated executor children bypass DB-first staging (see read tool).
+			if (process.env.PI_PLANS_EXECUTOR === "1") return stage(null);
 			if (mode === "off") return stage(null);
 			if (mode === "config-unavailable") return stage("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);

package/tools/plans.ts

@@ -296,7 +296,7 @@ export function registerPlansTool(pi: ExtensionAPI): void {
 		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 and the code-graph enabled flag, 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-refs-root, set-graph-enabled, set-role, start-run, set-status, final-commit, 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 reviewer/criticizer roles and the code-graph enabled flag, start planning runs, record decisions/refs/subagents, and update run status. Multiple concurrent runs per workdir are supported (registry-derived from runs/; sessions bind to their run). State lives in .git/pi_plans/ inside the resolved git common dir. Actions: init, show, set-language, set-artifact-root, set-refs-root, set-graph-enabled, set-role, start-run, set-status, final-commit, record-decision, record-ref, record-subagent.",
 		promptSnippet: "Manage pi-plans planning state, runs, and ledgers",
 		parameters: PlansParams,