pi-plans 0.5.7 → 0.6.0

package/skills/plan-with-refs/SKILL.md

@@ -16,10 +16,10 @@ Read `../../references/pi-planning-workflow.md` and `../../references/state-and-
 1. Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.
 2. Create the `.git/pi_plans` run state and planning artifact directory once the topic is clear (`plans` action `start-run`).
 3. Search proactively for related projects, articles, papers, docs, and prior art. Prefer a websearch skill when installed; otherwise use bash tools such as `curl` or `gh` when already available.
-4. Before the first download, check `refs_root` in `.git/pi_plans/config.json` (`plans` action `show`). If it is unset, ask exactly one `ask_choice` question — recommended `.git/pi-plans/refs/` (inside the git dir, never tracked), second `./refs/`, third `~/.cache/pi-plans/refs/` — and persist with `plans` (`set-refs-root`); this question does not count against the planning-question limit. Then download or clone at least 3 credible references before writing `PLAN_v1.md`, under the configured refs root (create per-ref subdirectories). Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
-5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.
+4. Before the first download, check `refs_root` in `.git/pi_plans/config.json` (`plans` action `show`). If it is unset, ask exactly one `ask_choice` question — recommended `.git/pi-plans/refs/` (inside the git dir, never tracked), second `./refs/`, third `~/.cache/pi-plans/refs/` — with each option's `description` set to `✓ <advantage> / ✗ <drawback>` in the configured language, kept terse, and persist with `plans` (`set-refs-root`); this question does not count against the planning-question limit. Then download at least 3 credible references across at least 2 distinct origins before writing `PLAN_v1.md`, under the configured refs root (one subdirectory per reference — `analyze_refs` requires directories). References are NOT limited to GitHub repositories: papers (e.g. arXiv), engineering blog posts, and documentation sites are first-class, and theoretical references count exactly as much as implementation references. A download is qualified per medium: repo = clone (full working tree); paper = the full text (arXiv HTML preferred, else the PDF with extracted text into `paper.txt`/`paper.md`; an abstract alone never qualifies); blog/docs site = the full-article readable markdown saved locally (single-page posts are fine — they ARE the source; only fragments or teasers fail). Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
+5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind (`project` for repos, `paper` for papers, `article` for blog posts, `docs` for documentation sites), retrieval method, date accessed, local path, coverage, and evidence gaps.
 6. For every reference, run the `analyze_refs` tool (required path — it replaces manual structured reads): one independent read-only subagent per reference deep-reads it and returns structured sections (Overview / Key Mechanisms And Design Tradeoffs / Adoptable Ideas For The Target Repo / Pitfalls And Anti-Patterns / Evidence Citations / Coverage / Evidence Gaps). Paste each analysis into `REF_ANALYSIS.md` and fill `coverage` and `gaps` in `refs.jsonl` via `plans` (`record-ref`) before asking adoption questions.
-7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both). Batch one reference's adoption questions into a single `questions: [...]` form call.
+7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both). Every option you write carries a `description` of `✓ <advantage> / ✗ <drawback>` in the configured language, kept terse — adoption choices trade a real gain against a real cost, so state both. Batch one reference's adoption questions into a single `questions: [...]` form call.
 8. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.
 9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement round. Then the merged accept/execute question (ask_choice with `autoComplete: false`: ✓ Accept & execute now / Accept, don't execute yet / another round) and the `execute_plan` tool.
 

package/skills/planning/SKILL.md

@@ -19,4 +19,4 @@ Use this skill when a task is planning-related but the right specialist is not o
 
 ## Pi Setup
 
-Use the same language, `ask_choice`, `refine`, reviewer, criticizer, Auto-complete, and `.git/pi_plans` rules as the selected specialist skill and the shared workflow. Questions prefer the 0.4.0 batch form: one `ask_choice` call with `questions: [...]` (2-8) opens a tabbed multiple-choice form; scope confirmation and execution handoff stay single-question with `autoComplete: false`.
+Use the same language, `ask_choice`, `refine`, reviewer, criticizer, Auto-complete, and `.git/pi_plans` rules as the selected specialist skill and the shared workflow — including the per-option `✓ <advantage> / ✗ <drawback>` descriptions, which every option you write carries in the configured language, kept terse. Questions prefer the 0.4.0 batch form: one `ask_choice` call with `questions: [...]` (2-8) opens a tabbed multiple-choice form; scope confirmation and execution handoff stay single-question with `autoComplete: false`.

package/src/config-command.ts

@@ -7,7 +7,7 @@ interface ModelLike {
 	id?: unknown;
 }
 
-interface ConfigCommandContext {
+export interface ConfigCommandContext {
 	cwd: string;
 	hasUI: boolean;
 	model?: unknown;
@@ -34,7 +34,7 @@ function cancelled<T>(reason: "user" | "invalid" = "user"): ChoiceResult<T> {
 	return { cancelled: true, reason };
 }
 
-function modelSelectorOf(value: unknown): string | null {
+export function modelSelectorOf(value: unknown): string | null {
 	if (!value || typeof value !== "object") return null;
 	const model = value as ModelLike;
 	if (typeof model.provider !== "string" || typeof model.id !== "string") return null;
@@ -42,7 +42,12 @@ function modelSelectorOf(value: unknown): string | null {
 	return `${model.provider}/${model.id}`;
 }
 
-function collectModelSelectors(ctx: ConfigCommandContext, currentSelector: string | null): string[] {
+/**
+ * Merge the session-visible model selectors (ctx.model + ctx.scopedModels +
+ * the model registry), deduped, EXCLUDING `currentSelector` — the result is a
+ * switch-target list (v0.6.0 delegated-execution model picker reuses this).
+ */
+export function collectModelSelectors(ctx: ConfigCommandContext, currentSelector: string | null): string[] {
 	const selectors: string[] = [];
 	const push = (selector: string | null): void => {
 		if (!selector) return;

package/src/exec.ts

@@ -36,9 +36,11 @@ import {
 	type VccCompactionBuildResult,
 	type VccCompactionStats,
 } from "./compaction.ts";
-import { getRun, lintPlanIntoNotices, readActive, resolveStateRootOrNull, setRunStatus, StateError, utcNow } from "./state.ts";
+import { TERMINAL_RUN_STATUSES, getRun, latestRun, lintPlanIntoNotices, loadConfig, readActive, resolveStateRootOrNull, setRunStatus, StateError, utcNow } from "./state.ts";
 import { execChrome, resolveUiLanguage, type UiLanguage } from "./ui-language.ts";
 import { bindRun, resolveActiveRun } from "./run-context.ts";
+import { runPiSubagent, type SubagentProgressEvent } from "./subagent.ts";
+import { RefineOverlayController, refineOverlayContext } from "./refine-ui.ts";
 import { OwnershipError } from "./run-ownership.ts";
 import {
 	applyExecutionApproved,
@@ -110,6 +112,10 @@ export interface ExecState {
 	uiLanguage?: UiLanguage;
 	currentI?: string;
 	goalWait?: GoalWaitState;
+	/** v0.6.0: set while a delegated executor child owns the implementation.
+	 * Persisted subset only (modelSelector + startedAt); the AbortController is
+	 * runtime state kept in delegatedRuntime, never persisted. */
+	delegate?: { modelSelector: string; startedAt: string };
 }
 
 /**
@@ -283,6 +289,19 @@ export function loadExecutionFromCheckpoint(
 	resetGoalWaitRuntime(ctx);
 	pendingExecutionFlush = false; // restored state: no inherited flush debt
 	resetExecutionCompactionState(ctx);
+	// v0.6.0 orphaned-delegate detection: a restart never carries a live child.
+	// If the checkpoint/session carries delegate state, surface it so the user
+	// knows the previous executor died mid-run (VC state is intact, resumable).
+	if (cp.execution.delegate) {
+		try {
+			ctx.ui.notify?.(
+				`pi-plans: the previous delegated executor (${cp.execution.delegate.modelSelector}) did not finish before this session ended. Verified VC state is preserved; resume with /plans-execute.`,
+				"warning",
+			);
+		} catch {
+			/* notification is best-effort */
+		}
+	}
 	if (headChanged) {
 		withExecutionCheckpoint(ctx, (current) => applyExecutionHeadChanged(current));
 	}
@@ -463,7 +482,13 @@ let loopPanelRegistered = false;
 function implReviewLoopState(
 	ctx: ExtensionContext,
 ): { topic: string; review: { terminationCondition?: string; reviewerCount?: number; completedRounds: number } } | null {
-	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd);
+	// v0.6.0: resolveActiveRun only returns NON-TERMINAL runs, but this state
+	// is by definition attached to a DONE run — fall back to the newest run of
+	// any status (display-only) when the active resolution is null.
+	const active = resolveActiveRun(ctx.sessionManager, ctx.cwd) ?? (() => {
+		const latest = latestRun(ctx.cwd);
+		return latest === null ? null : { run_id: latest.run_id, artifact_dir: latest.artifact_dir };
+	})();
 	if (!active) return null;
 	if (getRun(ctx.cwd, active.run_id)?.status !== "done") return null;
 	const load = loadCheckpoint(ctx.cwd, active.run_id);
@@ -564,7 +589,10 @@ export function updateStatusWidget(ctx: ExtensionContext): void {
 	if (active) {
 		// Idle indicator depends on the run's lifecycle, not just its existence:
 		// done reads as finished, abandoned as closed, stopped/accepted as paused.
-		const status = getRun(ctx.cwd, active.run_id)?.status;
+		// v0.6.0: resolveActiveRun only returns NON-TERMINAL runs; for the pure
+		// display line below, fall back to the newest run of any status so a
+		// finished workdir still shows its last run's outcome.
+		const status = getRun(ctx.cwd, active.run_id)?.status ?? latestRun(ctx.cwd)?.status;
 		if (status === "done") {
 			// D-3/D-015: while the implementation-review loop is live (checkpoint
 			// still in the implementation-review phase), the status line mirrors
@@ -599,6 +627,24 @@ export function updateStatusWidget(ctx: ExtensionContext): void {
 		}
 		// unknown status: no indicator.
 	}
+	// Terminal-only workdir: resolveActiveRun is null, but the display line
+	// still reports the newest run's outcome (done/abandoned, plus its live
+	// implementation-review loop).
+	const terminalLatest = latestRun(ctx.cwd);
+	if (terminalLatest && TERMINAL_RUN_STATUSES.has(terminalLatest.status)) {
+		if (terminalLatest.status === "done") {
+			const loop = implReviewLoopState(ctx);
+			if (loop) {
+				const line = formatImplReviewLoopSummaryLine(deriveImplReviewLoopModel(loop.topic, loop.review));
+				ctx.ui.setStatus("pi-plans", ctx.ui.theme.fg("accent", line));
+				return;
+			}
+			ctx.ui.setStatus("pi-plans", ctx.ui.theme.fg("success", `🎯 plans: ${terminalLatest.run_id} (done)`));
+		} else {
+			ctx.ui.setStatus("pi-plans", ctx.ui.theme.fg("error", `🚫 plans: ${terminalLatest.run_id}`));
+		}
+		return;
+	}
 	ctx.ui.setStatus("pi-plans", undefined);
 }
 
@@ -614,6 +660,7 @@ function persist(pi: ExtensionAPI): void {
 		implWarning: execution.implWarning ?? null,
 		currentI: execution.currentI,
 		goalWait: execution.goalWait,
+		delegate: execution.delegate ?? null,
 	});
 }
 
@@ -641,6 +688,7 @@ export async function startExecution(
 	planPath: string,
 	items: CheckItem[],
 	implItems?: ImplItem[],
+	opts?: StartExecutionOptions,
 ): Promise<void> {
 	execution = {
 		planPath,
@@ -721,6 +769,189 @@ export async function startExecution(
 		},
 		{ triggerTurn: false },
 	);
+	// Delegated runtime (v0.6.0): one executor child implements the whole plan
+	// while this tool call blocks; the parent mirrors VC progress from the
+	// child's streamed assistant messages (R-9..R-12).
+	updateStatusWidget(ctx);
+	if (opts?.runtime && opts.runtime !== "current-session") {
+		await runDelegatedExecution(pi, ctx, opts.runtime.modelSelector, opts.signal);
+	}
+}
+
+/** Where a chosen execution runs: this session, or a delegated executor child. */
+export type ExecutionRuntime = "current-session" | { modelSelector: string };
+
+export interface StartExecutionOptions {
+	/** "current-session" (default) or a delegated executor model selector. */
+	runtime?: ExecutionRuntime;
+	/** Tool-call abort signal, threaded into the delegated child. */
+	signal?: AbortSignal;
+}
+
+/** Default delegated executor timeout when config omits executor_timeout_minutes. */
+const DELEGATE_DEFAULT_TIMEOUT_MINUTES = 60;
+void DELEGATE_DEFAULT_TIMEOUT_MINUTES;
+
+/** Live AbortController for the delegated executor child (runtime-only state). */
+let delegatedRuntime: AbortController | null = null;
+
+/** Abort the delegated executor child, if one is running (used by /plans-stop). */
+export function abortDelegatedExecutor(): boolean {
+	if (delegatedRuntime === null) return false;
+	delegatedRuntime.abort();
+	return true;
+}
+
+function executorAgentPrompt(): string {
+	try {
+		const agentPath = new URL("../agents/executor.md", import.meta.url);
+		return fs.readFileSync(agentPath, "utf8");
+	} catch {
+		return "You are a delegated plan executor in the pi-plans workflow. Implement the accepted plan autonomously and emit [DONE:VC-xxx] markers in your replies as verifier items pass.";
+	}
+}
+
+function delegatedExecutorTimeoutMs(): number | undefined {
+	try {
+		const stateRoot = resolveStateRootOrNull(process.cwd());
+		if (stateRoot === null) return undefined;
+		const minutes = loadConfig(stateRoot).executor_timeout_minutes;
+		if (typeof minutes !== "number" || minutes <= 0) return undefined;
+		return minutes * 60 * 1000;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Delegated execution (R-9..R-12): spawn ONE executor child for the whole
+ * plan (write-capable tools, chosen model, PI_PLANS_EXECUTOR=1 + pinned run
+ * id), stream its progress into the overlay, parse full-text assistant
+ * messages for [DONE:VC-xxx]/[I-xxx] markers, and on exit verify the
+ * remaining items. Abort/timeout → stopExecution (stopped, resumable);
+ * clean exit with items left → stay executing (resumable under either
+ * runtime); clean exit complete → normal completion flow.
+ */
+async function runDelegatedExecution(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	modelSelector: string,
+	parentSignal: AbortSignal | undefined,
+): Promise<void> {
+	if (!execution) return;
+	const controller = new AbortController();
+	delegatedRuntime = controller;
+	const relayAbort = () => controller.abort();
+	if (parentSignal?.aborted) controller.abort();
+	else parentSignal?.addEventListener("abort", relayAbort, { once: true });
+	const lang = resolveUiLanguage(ctx.cwd);
+	const overlay = ctx.mode === "tui" ? new RefineOverlayController("executor", [{ id: "executor" }], relayAbort, lang) : undefined;
+	if (overlay) {
+		try {
+			overlay.open(refineOverlayContext(ctx), modelSelector);
+		} catch {
+			/* overlay is best-effort; the blocking call itself must not fail */
+		}
+	}
+	execution.delegate = { modelSelector, startedAt: utcNow() };
+	withExecutionCheckpoint(ctx, (cp) => applyExecutionProgress(cp, { delegate: execution?.delegate ?? null }));
+	persist(pi);
+	const runId = executionRunId;
+	const remainingAtStart = execution.items.filter((item) => !item.done).map((item) => item.id);
+	const task = [
+		`Implement the accepted plan at ${execution.planPath} (workdir: ${ctx.cwd}).`,
+		"Read the plan file first; it is the source of truth for scope, sequencing, and verification steps.",
+		remainingAtStart.length > 0
+			? `Verifier items still open: ${remainingAtStart.join(", ")}. Emit [DONE:VC-xxx] markers in your replies as each item's stated evidence passes.`
+			: "All verifier items already passed; verify the plan end-to-end and report.",
+		execution.implItems?.length
+			? `Implementation items: ${execution.implItems.map((item) => item.id).join(", ")} — emit [I-###:implemented]/[I-###:validating] markers as you progress.`
+			: "",
+		"Finish with the structured summary your system prompt specifies.",
+	]
+		.filter((line) => line !== "")
+		.join("\n");
+	let result: Awaited<ReturnType<typeof runPiSubagent>>;
+	try {
+		result = await runPiSubagent({
+			systemPrompt: executorAgentPrompt(),
+			task,
+			cwd: ctx.cwd,
+			model: modelSelector,
+			tools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+			envMarker: "executor",
+			runId: runId ?? undefined,
+			signal: controller.signal,
+			timeoutMs: delegatedExecutorTimeoutMs(),
+			onProgress: (event: SubagentProgressEvent) => {
+				try {
+					overlay?.update("executor", event);
+			} catch {
+				/* display must not fail the child runner */
+			}
+			if (
+					event.type === "transcript"
+					&& event.phase === "end"
+					&& event.entryType === "assistant-text"
+					&& typeof event.text === "string"
+			) {
+					mirrorDelegateMarkers(pi, ctx, event.text);
+			}
+			},
+		});
+	} finally {
+		delegatedRuntime = null;
+		try {
+			await overlay?.close();
+		} catch {
+			/* best-effort */
+		}
+		parentSignal?.removeEventListener("abort", relayAbort);
+	}
+	if (!result.ok) {
+		const reason = result.timedOut
+			? `delegated executor timed out (${result.errorMessage ?? "no output"})`
+			: result.cancelled || controller.signal.aborted
+				? "delegated executor aborted by user"
+				: `delegated executor failed: ${result.errorMessage ?? "unknown error"}${result.stderr ? `; stderr: ${result.stderr.slice(0, 500)}` : ""}`;
+		await stopExecution(pi, ctx, reason);
+		return;
+	}
+	// Clean exit: land any markers from the final output text, then verify.
+	mirrorDelegateMarkers(pi, ctx, result.output);
+	if (isExecutionComplete()) {
+		await completeExecution(pi, ctx);
+		return;
+	}
+	// Items remain: keep the run executing (resumable via /plans-execute under
+	// either runtime); the delegate bookkeeping is cleared so restarts do not
+	// treat this as an orphaned child.
+	if (execution) {
+		execution.delegate = undefined;
+		withExecutionCheckpoint(ctx, (cp) => applyExecutionProgress(cp, { delegate: null }));
+		persist(pi);
+	}
+	const remaining = execution?.items.filter((item) => !item.done).map((item) => item.id) ?? [];
+	pi.sendMessage(
+		{
+			customType: "pi-plans-exec-delegate-exit",
+			content: `**pi-plans: delegated executor exited with items remaining** — ${remaining.join(", ") || "(none)"}. Run stays executing; resume with /plans-execute (either runtime). Executor summary:\n${result.output.slice(0, 2000)}`,
+			display: true,
+		},
+		{ triggerTurn: false },
+	);
+	ctx.ui.notify?.(`Delegated executor exited; ${remaining.length} verifier item(s) remain. Resume with /plans-execute.`, "warning");
+	updateStatusWidget(ctx);
+}
+
+/** Apply VC/I markers parsed from a delegated child's full-text message. Exported for tests. */
+export function mirrorDelegateMarkers(pi: ExtensionAPI, ctx: ExtensionContext, text: string): void {
+	const changedVc = applyDoneMarkers(text);
+	const changedImpl = applyImplMarkers(text);
+	applyCurrentIMarker(text);
+	if (changedVc.length === 0 && changedImpl.length === 0) return;
+	withExecutionCheckpoint(ctx, (cp) => applyExecutionProgress(cp));
+	persist(pi);
 	updateStatusWidget(ctx);
 }
 

package/src/guard.ts

@@ -7,12 +7,17 @@
 
 import * as os from "node:os";
 import * as path from "node:path";
-import { getRun, loadConfig, readActive, resolveStateRootOrNull } from "./state.ts";
 import { activeInfoById } from "./run-context.ts";
+import { getRun, loadConfig, readActive, resolveStateRootOrNull } from "./state.ts";
 
 const GUARDED_TOOLS = new Set(["write", "edit"]);
 const GUARDED_STATUSES = new Set(["planning", "accepted"]);
 
+/** True when running inside a delegated executor child (PI_PLANS_EXECUTOR=1). */
+export function isExecutorChild(): boolean {
+	return process.env.PI_PLANS_EXECUTOR === "1";
+}
+
 export interface GuardInput {
 	workdir: string;
 	toolName: string;
@@ -24,10 +29,19 @@ export interface GuardInput {
 /** Returns a block reason when the write must be blocked, or null when allowed. */
 export function planningWriteBlockReason(input: GuardInput): string | null {
 	if (!GUARDED_TOOLS.has(input.toolName)) return null;
+	// Delegated executor children write natively with the parent's approval
+	// already recorded — the guard must never block them, even when another
+	// session's planning run is the newest non-terminal run in the workdir.
+	if (isExecutorChild()) return null;
+	// Executor children also pin their run via PI_PLANS_RUN_ID; honor it for
+	// any child that is not marked executor (defense in depth).
+	const envRunId = typeof process.env.PI_PLANS_RUN_ID === "string" ? process.env.PI_PLANS_RUN_ID.trim() : "";
 	const active =
-		input.activeRunId !== undefined && input.activeRunId !== null
-			? activeInfoById(input.workdir, input.activeRunId)
-			: readActive(input.workdir);
+		envRunId !== ""
+			? activeInfoById(input.workdir, envRunId)
+			: input.activeRunId !== undefined && input.activeRunId !== null
+				? activeInfoById(input.workdir, input.activeRunId)
+				: readActive(input.workdir);
 	if (!active) return null;
 	const run = getRun(input.workdir, active.run_id);
 	if (!run || !GUARDED_STATUSES.has(run.status)) return null;
@@ -53,5 +67,5 @@ export function planningWriteBlockReason(input: GuardInput): string | null {
 	const allowed = allowedRoots.some((root) => target === root || target.startsWith(`${root}${path.sep}`));
 	if (allowed) return null;
 
-	return `pi-plans: active planning run "${active.run_id}" is read-only outside planning artifacts. Allowed write roots: ${allowedRoots.join(", ")}. Finish planning and get execution approval (execute_plan tool or /plans-execute), or abandon the run (/plans-abandon).`;
+	return `pi-plans: active planning run "${active.run_id}" is read-only outside planning artifacts (this session is not bound to it; if you are operating on a different run, bind it via /resume-plans or pick the run explicitly). Allowed write roots: ${allowedRoots.join(", ")}. Finish planning and get execution approval (execute_plan tool or /plans-execute), or abandon the run (/plans-abandon).`;
 }

package/src/refine-prompts.ts

@@ -144,7 +144,7 @@ Local path (your working directory): ${opts.localPath}
 
 Authority boundary: read-only analysis only. Do not edit, write, delete, commit, push, or spawn subagents. Stay inside the reference directory.
 
-Evidence: inspect the reference with read, grep, find, and ls before judging it. Cite files as <relative-path>:<line> for every claim; quote only what you verified.${contextLine}${languageLine}
+Evidence: inspect the reference with read, grep, find, and ls before judging it. Cite evidence for every claim in the medium's format — code: <relative-path>:<line>; papers: section/theorem/table numbers with a short quote; blogs/docs: the heading or quoted passage. Quote only what you verified. Medium-aware deep-read: repos go through entry points, core modules, tests, and configuration; papers through claims, method, limitations, and experiments; blogs/docs through technique, measurements, and caveats. Theoretical grounding counts — an algorithm, a formal property, or a measured tradeoff is as adoptable as an implementation pattern.${contextLine}${languageLine}
 
 Success criteria: a structured analysis the main agent can paste into REF_ANALYSIS.md and turn into adoption questions.
 
@@ -157,7 +157,7 @@ Section contracts:
 - Key Mechanisms And Design Tradeoffs: the mechanisms that make it work and the tradeoffs they embody.
 - Adoptable Ideas For The Target Repo: concrete, portable ideas ranked by expected value; name the target-repo surface each would touch.
 - Pitfalls And Anti-Patterns: what to avoid when borrowing; failure modes the reference itself documents or exhibits.
-- Evidence Citations: the file:line references backing the claims above.
+- Evidence Citations: the evidence references backing the claims above (file:line for code; section/theorem/table + quote for papers; heading/quote for blogs and docs).
 - Coverage: which parts of the reference you actually read versus skipped.
 - Evidence Gaps: what you could not determine from the reference alone.`;
 }

package/src/refine-ui-state.ts

@@ -1,6 +1,6 @@
 import type { SubagentProgressEvent, SubagentResult } from "./subagent.ts";
 
-export type RefineOverlayRole = "reviewer" | "criticizer" | "refs";
+export type RefineOverlayRole = "reviewer" | "criticizer" | "refs" | "executor";
 export type RefineLaneStatus = "queued" | "running" | "complete" | "failed" | "cancelled";
 export type RefineTranscriptEntryType = "assistant-text" | "thinking" | "tool-call" | "tool-result" | "diagnostic";
 

package/src/refine-ui.ts

@@ -166,7 +166,7 @@ function summaryFor(role: RefineOverlayRole, lanes: RefineLaneState[], modelLabe
 	const complete = lanes.filter((lane) => lane.status === "complete").length;
 	const terminal = lanes.filter((lane) => ["complete", "failed", "cancelled"].includes(lane.status)).length;
 	const running = lanes.filter((lane) => lane.status === "running").length;
-	const title = role === "reviewer" ? "Reviewer" : role === "refs" ? "Refs" : "Criticizer";
+	const title = role === "reviewer" ? "Reviewer" : role === "refs" ? "Refs" : role === "executor" ? "Executor" : "Criticizer";
 	const visibleTitle = modelLabel ? `${title} (${modelLabel})` : title;
 	const state = terminal === lanes.length ? "done" : running > 0 ? `${running} running` : "queued";
 	return `${visibleTitle} · ${complete}/${lanes.length} done · ${state}`;

package/src/resume-command.ts

@@ -17,7 +17,7 @@ import * as fs from "node:fs";
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { loadExecutionFromCheckpoint } from "./exec.ts";
-import { bindRun } from "./run-context.ts";
+import { bindRun, boundRunId } from "./run-context.ts";
 import { acquireOwnership, OwnershipError, releaseOwnership } from "./run-ownership.ts";
 import { loadConfig, resolveStateRootOrNull, setRunStatus, updateRunWorkdir } from "./state.ts";
 import {
@@ -73,7 +73,11 @@ async function run(pi: ExtensionAPI, ctx: ExtensionContext, baseDir: string): Pr
 		return;
 	}
 
-	let candidate = pickDefaultCandidate(ctx.cwd, candidates);
+	// v0.6.0 (D-1): a session-bound resumable run resumes directly; the
+	// active-pointer auto-win is gone — ambiguity opens the descriptive form.
+	const bound = boundRunId(ctx.sessionManager, ctx.cwd);
+	const boundCandidate = bound ? candidates.find((candidate) => candidate.runId === bound) ?? null : null;
+	let candidate = boundCandidate ?? pickDefaultCandidate(ctx.cwd, candidates);
 	if (candidate === null) {
 		const labels = candidates.map((entry, index) => {
 			const cross = entry.crossWorktree ? " · cross-worktree" : "";

package/src/resume.ts

@@ -9,7 +9,7 @@
 import * as fs from "node:fs";
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
-import { getRun, readActive, resolveStateRootOrNull, runDirPath, type RunInfo } from "./state.ts";
+import { getRun, listRuns, readActive, resolveStateRootOrNull, runDirPath, type RunInfo } from "./state.ts";
 import { loadCheckpoint, mutateCheckpoint, type WorkflowCheckpoint } from "./workflow-state.ts";
 
 export interface ResumeCandidate {
@@ -81,22 +81,17 @@ function planVersionOf(checkpoint: WorkflowCheckpoint | null, run: RunInfo): num
 /**
  * Enumerate resumable runs for the repo containing `workdir`. Corrupt
  * checkpoints are surfaced (not hidden) so the command can report them;
- * read errors never abort discovery of other runs.
+ * read errors never abort discovery of other runs. v0.6.0: enumeration is
+ * driven by the filesystem-derived registry (`listRuns`) so ordering and
+ * corrupt-run tolerance match every other multi-run surface.
  */
 export function listResumeCandidates(workdir: string): ResumeCandidate[] {
 	const stateRoot = resolveStateRootOrNull(workdir);
 	if (stateRoot === null) return [];
-	const runsDir = path.join(stateRoot, "runs");
-	if (!existsSync(runsDir)) return [];
 	const active = readActive(workdir);
 	const candidates: ResumeCandidate[] = [];
-	let entries: string[] = [];
-	try {
-		entries = fs.readdirSync(runsDir);
-	} catch {
-		return [];
-	}
-	for (const runId of entries) {
+	for (const summary of listRuns(workdir)) {
+		const runId = summary.run_id;
 		const run = getRun(workdir, runId);
 		if (!run) continue;
 		const runDir = runDirPath(workdir, runId);
@@ -130,7 +125,7 @@ export function listResumeCandidates(workdir: string): ResumeCandidate[] {
 			updatedAt: checkpoint?.updatedAt ?? run.updated_at,
 		});
 	}
-	// Active pointer first (priority, not exclusivity), then newest updated.
+	// Newest updated first; the active run (registry hint) gets priority.
 	candidates.sort((a, b) => {
 		const aActive = active?.run_id === a.runId ? 1 : 0;
 		const bActive = active?.run_id === b.runId ? 1 : 0;
@@ -140,14 +135,17 @@ export function listResumeCandidates(workdir: string): ResumeCandidate[] {
 	return candidates;
 }
 
-/** Pick the default candidate: active-unfinished first, else unique candidate (D-001). */
+/**
+ * Pick the default candidate (v0.6.0 D-1): the SESSION BINDING is resolved by
+ * the command (it owns the SessionManager); here a unique candidate goes
+ * direct and everything else is ambiguous — the active-pointer auto-win is
+ * gone (multi-run workdirs must not silently pick the registry hint).
+ */
 export function pickDefaultCandidate(workdir: string, candidates: ResumeCandidate[]): ResumeCandidate | null {
+	void workdir;
 	if (candidates.length === 0) return null;
-	const active = readActive(workdir);
-	const activeCandidate = active ? candidates.find((candidate) => candidate.runId === active.run_id) ?? null : null;
-	if (activeCandidate !== null) return activeCandidate;
 	if (candidates.length === 1) return candidates[0]!;
-	return null; // ambiguous: the command must ask
+	return null; // ambiguous: the command must ask (binding first, then form)
 }
 
 export interface DecisionLedgerEntry {

package/src/run-context.ts

@@ -10,7 +10,7 @@
  */
 
 import * as path from "node:path";
-import { getRun, readActive, runDirPath, type ActiveInfo } from "./state.ts";
+import { getRun, newestNonTerminalRun, readActive, runDirPath, type ActiveInfo } from "./state.ts";
 
 interface RunBinding {
 	runId: string;
@@ -54,11 +54,19 @@ export function activeInfoById(workdir: string, runId: string): ActiveInfo | nul
 }
 
 /**
- * Resolve the run this session should attribute work to. A session-bound
- * run always wins; sessions without a binding keep the legacy
- * shared-pointer behavior.
+ * Resolve the run this session should attribute work to. Resolution order:
+ * 1. `PI_PLANS_RUN_ID` env (delegated executor children — deterministic even
+ *    when several runs are active concurrently);
+ * 2. the session binding (a session-bound run always wins);
+ * 3. registry fallback: the newest non-terminal run (`readActive` shim), or
+ *    null when every run is terminal.
  */
 export function resolveActiveRun(session: unknown, workdir: string): ActiveInfo | null {
+	const envRunId = process.env.PI_PLANS_RUN_ID;
+	if (typeof envRunId === "string" && envRunId.trim() !== "") {
+		const pinned = activeInfoById(workdir, envRunId.trim());
+		if (pinned !== null) return pinned;
+	}
 	if (session !== undefined && session !== null) {
 		const runId = boundRunId(session, workdir);
 		if (runId !== null) {