pi-plans 0.3.0 → 0.3.2

package/src/config-command.ts

@@ -71,6 +71,11 @@ function parseArtifactRoot(input: string): string | null {
 	return value ? value : null;
 }
 
+function parseRefsRoot(input: string): string | null {
+	const value = input.trim();
+	return value ? value : null;
+}
+
 function parseModelSelector(input: string): string | null {
 	const value = input.trim();
 	if (!value) return null;
@@ -144,6 +149,24 @@ async function promptArtifactRoot(ctx: ConfigCommandContext, current: string): P
 	return promptMenu(ctx, "Artifact root?", options);
 }
 
+async function promptRefsRoot(ctx: ConfigCommandContext, current: string | null): Promise<ChoiceResult<string>> {
+	const options: Array<MenuOption<string>> = [];
+	if (current) {
+		options.push({ label: `Keep current (${current})`, value: current });
+	}
+	for (const root of [".git/pi-plans/refs", "./refs", "~/.cache/pi-plans/refs"]) {
+		if (root === current) continue;
+		options.push({ label: root, value: root });
+	}
+	options.push({
+		label: "Other...",
+		parse: parseRefsRoot,
+		prompt: "Refs root:",
+		errorMessage: "Refs root cannot be empty.",
+	});
+	return promptMenu(ctx, "Refs root (plan-with-refs downloads)?", options);
+}
+
 async function promptGraphEnabled(ctx: ConfigCommandContext, current: boolean | null): Promise<ChoiceResult<boolean>> {
 	const options: Array<MenuOption<boolean>> = [];
 	if (current === true) {
@@ -219,6 +242,7 @@ function summarizeConfig(config: PlansConfig): string[] {
 		"pi-plans config updated.",
 		`Language: ${config.language.tag ?? "(unset)"}`,
 		`Artifact root: ${config.artifact_root}`,
+		`Refs root: ${config.refs_root ?? "(unset)"}`,
 		`Code graph: ${config.graph_enabled === true ? "enabled" : config.graph_enabled === false ? "disabled" : "unset"}`,
 		`Reviewer: ${config.reviewer.mode} / ${config.reviewer.model_selector ?? "inherit"}`,
 		`Criticizer: ${config.criticizer.mode} / ${config.criticizer.model_selector ?? "inherit"}`,
@@ -251,6 +275,14 @@ export async function configPiPlansCommand(_args: string, ctx: ConfigCommandCont
 			return;
 		}
 
+		const refsRoot = await promptRefsRoot(ctx, current.refs_root);
+		if (refsRoot.cancelled) {
+			if (refsRoot.reason === "user") {
+				ctx.ui.notify("Configuration wizard cancelled. No changes were written.", "warning");
+			}
+			return;
+		}
+
 		const graphEnabled = await promptGraphEnabled(ctx, current.graph_enabled);
 		if (graphEnabled.cancelled) {
 			if (graphEnabled.reason === "user") {
@@ -297,6 +329,9 @@ export async function configPiPlansCommand(_args: string, ctx: ConfigCommandCont
 			config.artifact_root = artifactRoot.value;
 			config.artifact_root_source = "user";
 			config.artifact_root_updated_at = now;
+			config.refs_root = refsRoot.value;
+			config.refs_root_source = "user";
+			config.refs_root_updated_at = now;
 			config.graph_enabled = graphEnabled.value;
 			config.graph_enabled_updated_at = now;
 			config.reviewer = {

package/src/exec.ts

@@ -8,6 +8,7 @@
  */
 
 import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
 import type {
 	CompactionResult,
 	ExtensionAPI,
@@ -36,6 +37,7 @@ import {
 import { getRun, readActive, resolveStateRootOrNull, setRunStatus, utcNow } from "./state.ts";
 import { graphBlockForExecutor } from "./code-graph/prompts.ts";
 import { resolveGraphMode } from "./code-graph/mode.ts";
+import { TERMINATION_QUESTION, TERMINATION_OPTIONS, renderTerminationOptions } from "./termination-prompt.ts";
 import {
 	extractCoverage,
 	latestPlanVersion,
@@ -58,10 +60,49 @@ export interface ExecState {
 	implItems?: ImplItem[];
 	implStatus?: Record<string, ImplMarkerState>;
 	currentI?: string;
+	goalWait?: GoalWaitState;
 }
 
+export interface GoalWaitState {
+	noProgressRounds: number;
+	waitRounds: number;
+	/** Marker/progress snapshot of the last goal-wait round; null = baseline not set. */
+	lastMarkers: string | null;
+	paused: boolean;
+	pausedReason?: string;
+}
+
+const GOAL_WAIT_MAX_NO_PROGRESS = 3;
+const GOAL_WAIT_MAX_WAITING = 6;
+
 let execution: ExecState | null = null;
 
+export const GOAL_WAIT_CUSTOM_TYPE = "pi-plans-goal-wait";
+
+interface GoalWaitRuntime {
+	owner: ExecState;
+	session: ExtensionContext["sessionManager"];
+	handled: boolean;
+	stopReason?: string;
+	text: string;
+	wakeId?: string;
+}
+
+// Dispatch identity belongs to a live session, never to a persisted checklist.
+let goalWaitRuntime: GoalWaitRuntime | null = null;
+
+function resetGoalWaitRuntime(ctx: ExtensionContext): void {
+	goalWaitRuntime = execution
+		? { owner: execution, session: ctx.sessionManager, handled: false, text: "" }
+		: null;
+}
+
+function currentGoalWaitRuntime(ctx: ExtensionContext): GoalWaitRuntime | null {
+	return goalWaitRuntime?.owner === execution && goalWaitRuntime.session === ctx.sessionManager
+		? goalWaitRuntime
+		: null;
+}
+
 // Execution-loop persistence is deferred until the agent settles so turn_end
 // never causes session writes during a streaming run.
 let pendingExecutionFlush = false;
@@ -198,7 +239,14 @@ function formatToks(tokens: number): string {
 
 export function formatExecutionStatusLine(execution: ExecState): string {
 	const progress = computeExecutionProgress(execution);
-	return `⌛ plans ${progress.done}/${progress.total}: spent ${formatElapsed(execution.startedAt)} · ${formatToks(execution.usage.inToks)} in-toks · ${formatToks(execution.usage.outToks)} out-toks`;
+	let line = `⌛ plans ${progress.done}/${progress.total}: spent ${formatElapsed(execution.startedAt)} · ${formatToks(execution.usage.inToks)} in-toks · ${formatToks(execution.usage.outToks)} out-toks`;
+	const goalWait = execution.goalWait;
+	if (goalWait?.paused) {
+		line += ` · ⏸ goal-wait paused (${goalWait.pausedReason ?? "paused"})`;
+	} else if (goalWait && (goalWait.noProgressRounds > 0 || goalWait.waitRounds > 0)) {
+		line += ` · 🔁 goal-wait · 无进展 ${goalWait.noProgressRounds}/3 · 等待 ${goalWait.waitRounds}/6`;
+	}
+	return line;
 }
 
 export function updateStatusWidget(ctx: ExtensionContext): void {
@@ -250,6 +298,7 @@ function persist(pi: ExtensionAPI): void {
 		implItems: execution.implItems,
 		implStatus: execution.implStatus,
 		currentI: execution.currentI,
+		goalWait: execution.goalWait,
 	});
 }
 
@@ -260,7 +309,11 @@ export async function startExecution(
 	items: CheckItem[],
 	implItems?: ImplItem[],
 ): Promise<void> {
-	execution = { planPath, items, startedAt: utcNow(), usage: { inToks: 0, outToks: 0 }, implItems: implItems ?? [], implStatus: {} };
+	execution = { planPath, items, startedAt: utcNow(), usage: { inToks: 0, outToks: 0 }, implItems: implItems ?? [], implStatus: {}, goalWait: { noProgressRounds: 0, waitRounds: 0, lastMarkers: null, paused: false } };
+	// Seed the marker baseline so the first quiet round is counted against a
+	// real snapshot instead of counting unconditionally (F-006).
+	if (execution.goalWait) execution.goalWait.lastMarkers = goalWaitSnapshot();
+	resetGoalWaitRuntime(ctx);
 	pendingExecutionFlush = false; // fresh run: no inherited flush debt
 	resetExecutionCompactionState(ctx);
 	persist(pi);
@@ -306,6 +359,30 @@ export function registerExecutionTurnHandlers(
 	// The turn_end projection does not carry usage; message_end delivers the
 	// full assistant message, so cache it here and consume it per turn.
 	let lastAssistantUsage: { input: number; output: number } | null = null;
+	pi.on("agent_start", async (_event, ctx) => {
+		const runtime = currentGoalWaitRuntime(ctx);
+		if (!runtime) return;
+		runtime.handled = false;
+		runtime.stopReason = undefined;
+		runtime.text = "";
+	});
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const runtime = currentGoalWaitRuntime(ctx);
+		if (runtime) runtime.wakeId = undefined;
+	});
+	pi.on("input", async (event, ctx) => {
+		if (event.source === "interactive" || event.source === "rpc") resumeGoalWaitIfPaused(pi, ctx);
+	});
+	pi.on("agent_settled", async (_event, ctx) => {
+		drainExecutionFlush(pi, ctx);
+		maybeGoalWaitFollowUp(pi, ctx);
+	});
+	pi.on("session_shutdown", async (_event, ctx) => {
+		drainExecutionFlush(pi, ctx);
+		execution = null;
+		goalWaitRuntime = null;
+		lastAssistantUsage = null;
+	});
 	pi.on("message_end", async (event) => {
 		const message = event.message as { role?: string; usage?: { input?: number; output?: number } };
 		if (message?.role === "assistant" && message.usage) {
@@ -314,7 +391,7 @@ export function registerExecutionTurnHandlers(
 	});
 
 	pi.on("turn_end", async (event, ctx) => {
-		const message = event.message as { role?: string; content?: Array<{ type: string; text?: string }> };
+		const message = event.message as { role?: string; stopReason?: string; content?: Array<{ type: string; text?: string }> };
 		if (!message || message.role !== "assistant") {
 			updateStatusWidget(ctx);
 			return;
@@ -323,6 +400,11 @@ export function registerExecutionTurnHandlers(
 			.filter((part) => part.type === "text")
 			.map((part) => part.text ?? "")
 			.join("\n");
+		const runtime = currentGoalWaitRuntime(ctx);
+		if (runtime) {
+			runtime.stopReason = message.stopReason;
+			runtime.text = text;
+		}
 		const changedIds = applyDoneMarkers(text);
 		const changedImpls = applyImplMarkers(text);
 		const changedCurrentI = applyCurrentIMarker(text);
@@ -815,6 +897,7 @@ export async function stopExecution(pi: ExtensionAPI, ctx: ExtensionContext, rea
 	pendingExecutionFlush = false;
 	persist(pi);
 	execution = null;
+	goalWaitRuntime = null;
 	pi.appendEntry("pi-plans-exec-cleared", { reason });
 	pi.sendMessage(
 		{
@@ -881,6 +964,138 @@ export function isExecutionComplete(): boolean {
 	return execution !== null && execution.items.length > 0 && execution.items.every((item) => item.done);
 }
 
+function goalWaitSnapshot(): string {
+	if (!execution) return "";
+	return JSON.stringify({
+		done: execution.items
+			.filter((item) => item.done)
+			.map((item) => item.id)
+			.sort()
+			.join("|"),
+		implStatus: execution.implStatus ?? {},
+		currentI: execution.currentI ?? null,
+	});
+}
+
+function pauseGoalWait(pi: ExtensionAPI, ctx: ExtensionContext, reason: string): void {
+	const ex = getExecution();
+	if (!ex?.goalWait) return;
+	ex.goalWait.paused = true;
+	ex.goalWait.pausedReason = reason;
+	persist(pi);
+	ctx.ui.notify?.(
+		`pi-plans: goal-wait paused (${reason}). Send any message or run /plans-execute to resume.`,
+		"warning",
+	);
+	updateStatusWidget(ctx);
+}
+
+function canWakeExecution(ctx: ExtensionContext, runtime: GoalWaitRuntime): boolean {
+	const compaction = executionCompactionState(ctx);
+	return currentGoalWaitRuntime(ctx) === runtime
+		&& (ctx.mode === "tui" || ctx.mode === "rpc")
+		&& !isExecutionComplete()
+		&& !runtime.owner.goalWait?.paused
+		&& ctx.isIdle()
+		&& !ctx.hasPendingMessages()
+		&& !ctx.signal?.aborted
+		&& !compactionInFlight(ctx, "execution")
+		&& !compaction?.inFlight
+		&& !compaction?.resumeGuard
+		&& compaction?.pendingFollowUpPrompt == null;
+}
+
+function sendGoalWaitWake(pi: ExtensionAPI, ctx: ExtensionContext, runtime: GoalWaitRuntime): boolean {
+	if (!canWakeExecution(ctx, runtime)) return false;
+	try {
+		// Custom messages bypass before_agent_start, so carry fresh execution rules.
+		const content = executionContextMessage(ctx);
+		if (!content) return false;
+		runtime.wakeId = randomUUID();
+		pi.sendMessage({
+			customType: GOAL_WAIT_CUSTOM_TYPE,
+			content,
+			display: false,
+			details: { wakeId: runtime.wakeId },
+		}, { triggerTurn: true });
+		return true;
+	} catch (error) {
+		runtime.wakeId = undefined;
+		pauseGoalWait(pi, ctx, `continuation failed: ${String(error)}`);
+		return false;
+	}
+}
+
+/** Only a fully settled agent run can need an extra wake, never a tool turn. */
+function maybeGoalWaitFollowUp(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	const runtime = currentGoalWaitRuntime(ctx);
+	if (!runtime || runtime.handled || !ctx.isIdle()) return;
+	if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
+	if (runtime.stopReason === "error" || runtime.stopReason === "aborted" || ctx.signal?.aborted) {
+		runtime.handled = true;
+		pauseGoalWait(pi, ctx, runtime.stopReason === "error" ? "agent failed" : "agent interrupted");
+		return;
+	}
+	if (runtime.stopReason !== "stop" || !canWakeExecution(ctx, runtime)) return;
+	runtime.handled = true;
+	const ex = runtime.owner;
+	ex.goalWait ??= { noProgressRounds: 0, waitRounds: 0, lastMarkers: null, paused: false };
+	const goalWait = ex.goalWait;
+	const snapshot = goalWaitSnapshot();
+	const changed = goalWait.lastMarkers !== null && snapshot !== goalWait.lastMarkers;
+	goalWait.lastMarkers = snapshot;
+	if (changed) {
+		goalWait.noProgressRounds = 0;
+		goalWait.waitRounds = 0;
+	} else if (/waiting for/i.test(runtime.text)) {
+		goalWait.waitRounds += 1;
+	} else {
+		goalWait.noProgressRounds += 1;
+	}
+	if (goalWait.noProgressRounds >= GOAL_WAIT_MAX_NO_PROGRESS) {
+		pauseGoalWait(pi, ctx, `no progress in ${goalWait.noProgressRounds} rounds`);
+		return;
+	}
+	if (goalWait.waitRounds >= GOAL_WAIT_MAX_WAITING) {
+		pauseGoalWait(pi, ctx, `waiting without progress for ${goalWait.waitRounds} rounds`);
+		return;
+	}
+	persist(pi);
+	updateStatusWidget(ctx);
+	// No await between the live gate and dispatch: another input cannot interleave.
+	sendGoalWaitWake(pi, ctx, runtime);
+}
+
+export function filterGoalWaitMessages<T extends { customType?: string; details?: unknown }>(messages: T[]): T[] {
+	return messages.filter((message) => message.customType !== GOAL_WAIT_CUSTOM_TYPE
+		|| (goalWaitRuntime?.owner === execution && goalWaitRuntime?.wakeId !== undefined
+			&& (message.details as { wakeId?: unknown } | undefined)?.wakeId === goalWaitRuntime.wakeId));
+}
+
+/** Called only for genuine user input or an explicit same-execution resume. */
+export function resumeGoalWaitIfPaused(pi: ExtensionAPI, ctx: ExtensionContext): boolean {
+	const ex = getExecution();
+	if (!ex?.goalWait?.paused || !currentGoalWaitRuntime(ctx)) return false;
+	ex.goalWait.paused = false;
+	ex.goalWait.pausedReason = undefined;
+	ex.goalWait.noProgressRounds = 0;
+	ex.goalWait.waitRounds = 0;
+	ex.goalWait.lastMarkers = goalWaitSnapshot();
+	persist(pi);
+	updateStatusWidget(ctx);
+	return true;
+}
+
+export function resumeActiveExecution(pi: ExtensionAPI, ctx: ExtensionContext): boolean {
+	if (!resumeGoalWaitIfPaused(pi, ctx)) return false;
+	const runtime = currentGoalWaitRuntime(ctx)!;
+	if (canWakeExecution(ctx, runtime)) {
+		runtime.handled = true;
+		sendGoalWaitWake(pi, ctx, runtime);
+	}
+	return true;
+}
+
 export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
 	if (!execution) return;
 	resetExecutionCompactionState(ctx);
@@ -891,6 +1106,7 @@ export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext)
 	const summary = execution.items.map((item) => `- ✅ \`${item.id}\` ${item.text.split(";")[0]}`).join("\n");
 	const planPath = execution.planPath;
 	execution = null;
+	goalWaitRuntime = null;
 	pi.appendEntry("pi-plans-exec-cleared", { reason: "complete" });
 	// Post-execution goal-running continuation: in interactive sessions, attach
 	// the continuation block and trigger a new turn so the agent immediately
@@ -925,9 +1141,10 @@ export async function completeExecution(pi: ExtensionAPI, ctx: ExtensionContext)
 
 /** Instructions appended to the post-execution completion message in
  * interactive sessions, telling the agent to enter the goal-running
- * implementation-review loop. */
+ * implementation-review loop. Termination options are single-sourced from
+ * src/termination-prompt.ts (shared with the ask_choice trailing branch). */
 export const AMELIORATION_PROMPT_TEXT = `---
-Goal-running continuation: immediately ask the user now via ask_choice (autoComplete: false, in the session language) for the termination condition of the implementation-review loop: until no high-severity finding (hard cap 5 rounds, recommended) / 1 round / 2 rounds / 3 rounds. Then keep running the loop without asking whether to continue: each round calls refine (role: "reviewer", target: "implementation"), accepts findings on evidence, applies fixes, re-runs relevant tests, and repeats until the chosen termination condition or the 5-round cap.`;
+Goal-running continuation: immediately ask the user now via ask_choice (autoComplete: false, in the session language) the termination question: "${TERMINATION_QUESTION}" Options (recommended first): ${renderTerminationOptions()}. Then keep running the implementation-review loop without asking whether to continue; the goal-wait option keeps the loop running until no unpassed VCs remain.`;
 
 /** Injection text for before_agent_start while executing. */
 export function executionContextMessage(ctx: ExtensionContext): string | null {
@@ -979,6 +1196,7 @@ interface SessionEntry {
  */
 export async function restoreFromSession(pi: ExtensionAPI, ctx: ExtensionContext, entries: SessionEntry[]): Promise<void> {
 	pendingExecutionFlush = false; // no flush debt survives a restart
+	goalWaitRuntime = null;
 	resetExecutionCompactionState(ctx);
 	let snapshotIndex = -1;
 	let snapshot: ExecState | null = null;
@@ -1015,6 +1233,9 @@ export async function restoreFromSession(pi: ExtensionAPI, ctx: ExtensionContext
 		implItems: snapshot.implItems ?? [],
 		implStatus: { ...(snapshot.implStatus ?? {}) },
 		currentI: snapshot.currentI ?? inferCurrentI(snapshot.implItems, snapshot.items, snapshot.implStatus),
+		goalWait: snapshot.goalWait
+			? { ...snapshot.goalWait }
+			: { noProgressRounds: 0, waitRounds: 0, lastMarkers: null, paused: false },
 	};
 	for (let i = snapshotIndex + 1; i < entries.length; i++) {
 		const entry = entries[i];
@@ -1034,6 +1255,17 @@ export async function restoreFromSession(pi: ExtensionAPI, ctx: ExtensionContext
 		}
 	}
 	if (execution) {
+		resetGoalWaitRuntime(ctx);
+		// D-010: replay may have advanced progress past the persisted baseline.
+		// Recompute the goal-wait markers; new progress resets the guard counters.
+		if (execution.goalWait) {
+			const markerSnapshot = goalWaitSnapshot();
+			if (markerSnapshot !== execution.goalWait.lastMarkers) {
+				execution.goalWait.lastMarkers = markerSnapshot;
+				execution.goalWait.noProgressRounds = 0;
+				execution.goalWait.waitRounds = 0;
+			}
+		}
 		persist(pi); // refresh snapshot so the next resume has less to rescan
 		if (isExecutionComplete()) {
 			// Completed during the rescan: restore the planning model on the way out.

package/src/guard.ts

@@ -7,7 +7,7 @@
 
 import * as os from "node:os";
 import * as path from "node:path";
-import { getRun, readActive, resolveStateRootOrNull } from "./state.ts";
+import { getRun, loadConfig, readActive, resolveStateRootOrNull } from "./state.ts";
 
 const GUARDED_TOOLS = new Set(["write", "edit"]);
 const GUARDED_STATUSES = new Set(["planning", "accepted"]);
@@ -31,6 +31,19 @@ export function planningWriteBlockReason(input: GuardInput): string | null {
 	const allowedRoots = [stateRoot, active.artifact_dir, path.join(os.homedir(), ".cache", "pi-plans")].filter(
 		(root): root is string => root !== null,
 	);
+	// A configured refs root (plan-with-refs downloads) is writable while planning.
+	if (stateRoot !== null) {
+		try {
+			const config = loadConfig(stateRoot);
+			if (config.refs_root) {
+				allowedRoots.push(
+					path.isAbsolute(config.refs_root) ? config.refs_root : path.resolve(input.workdir, config.refs_root),
+				);
+			}
+		} catch {
+			/* config read failed: no extra root */
+		}
+	}
 	const allowed = allowedRoots.some((root) => target === root || target.startsWith(`${root}${path.sep}`));
 	if (allowed) return null;
 

package/src/refine-prompts.ts

@@ -103,6 +103,65 @@ ${opts.planText}
 ---8<--- END PLAN CONTENT ---8<---`;
 }
 
+export interface RefAnalystTaskInput {
+	refId: string;
+	localPath: string;
+	title?: string;
+	url?: string;
+	kind?: string;
+	context?: string;
+	languageTag?: string | null;
+}
+
+const REF_ANALYST_SECTIONS = [
+	"Overview",
+	"Key Mechanisms And Design Tradeoffs",
+	"Adoptable Ideas For The Target Repo",
+	"Pitfalls And Anti-Patterns",
+	"Evidence Citations",
+	"Coverage",
+	"Evidence Gaps",
+] as const;
+
+export function refAnalystSections(): readonly string[] {
+	return REF_ANALYST_SECTIONS;
+}
+
+/** Task brief for the plan-with-refs per-reference analysis subagent. */
+export function buildRefAnalystTask(opts: RefAnalystTaskInput): string {
+	const titleLine = opts.title ? `\nTitle: ${opts.title}` : "";
+	const urlLine = opts.url ? `\nURL: ${opts.url}` : "";
+	const kindLine = opts.kind ? `\nKind: ${opts.kind}` : "";
+	const contextLine = opts.context ? `\n\nTarget repo context: ${opts.context}` : "";
+	const languageLine = opts.languageTag
+		? `\n\nWrite all prose in the language with BCP47 tag "${opts.languageTag}". Keep file paths, identifiers, and code snippets verbatim.`
+		: "";
+	const template = REF_ANALYST_SECTIONS.map((section) => `## ${section}`).join("\n\n(empty)\n\n");
+	return `Goal: deep-read this downloaded reference and extract what the target repository should adopt from it.
+
+Reference id: ${opts.refId}${titleLine}${urlLine}${kindLine}
+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}
+
+Success criteria: a structured analysis the main agent can paste into REF_ANALYSIS.md and turn into adoption questions.
+
+Output: Markdown with exactly these seven top-level sections, in this order:
+
+${template}
+
+Section contracts:
+- Overview: what the reference is, its scope, maturity, and license (when discoverable).
+- 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.
+- Coverage: which parts of the reference you actually read versus skipped.
+- Evidence Gaps: what you could not determine from the reference alone.`;
+}
+
 export function buildImplementationCriticizerTask(opts: RefinePromptInput): string {
 	return `${buildImplementationSharedHeader("criticizer", opts)}
 

package/src/refine-ui-state.ts

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

package/src/refine-ui.ts

@@ -203,7 +203,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" : "Criticizer";
+	const title = role === "reviewer" ? "Reviewer" : role === "refs" ? "Refs" : "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/state.ts

@@ -43,6 +43,10 @@ export interface PlansConfig {
 	artifact_root: string;
 	artifact_root_source: SettingSource;
 	artifact_root_updated_at: string | null;
+	/** null = never asked; plan-with-refs must ask once (three options) before downloading. */
+	refs_root: string | null;
+	refs_root_source: SettingSource;
+	refs_root_updated_at: string | null;
 	/** null = never asked; the plans tool surfaces a hint so the agent asks once. */
 	graph_enabled: boolean | null;
 	graph_enabled_updated_at: string | null;
@@ -83,6 +87,9 @@ export const DEFAULT_CONFIG: PlansConfig = {
 	artifact_root: DEFAULT_ARTIFACT_ROOT,
 	artifact_root_source: "unset",
 	artifact_root_updated_at: null,
+	refs_root: null,
+	refs_root_source: "unset",
+	refs_root_updated_at: null,
 	graph_enabled: null,
 	graph_enabled_updated_at: null,
 };
@@ -138,7 +145,7 @@ export interface RefEntry {
 }
 
 export interface SubagentEntry {
-	role: "reviewer" | "criticizer";
+	role: "reviewer" | "criticizer" | "ref-analyst";
 	name: string;
 	model?: string | null;
 	session_dir?: string;
@@ -330,6 +337,15 @@ export function setArtifactRoot(workdir: string, artifactRoot: string, source: "
 	return { config, stateRoot, notices };
 }
 
+export function setRefsRoot(workdir: string, refsRoot: string, source: "user" | "auto"): EnsureResult {
+	const { config, stateRoot, notices } = ensureState(workdir);
+	config.refs_root = refsRoot;
+	config.refs_root_source = source;
+	config.refs_root_updated_at = utcNow();
+	atomicWriteJson(path.join(stateRoot, "config.json"), config);
+	return { config, stateRoot, notices };
+}
+
 export function setGraphEnabled(workdir: string, enabled: boolean): EnsureResult {
 	const { config, stateRoot, notices } = ensureState(workdir);
 	config.graph_enabled = enabled;

package/src/subagent.ts

@@ -306,6 +306,7 @@ export async function runPiSubagent(options: SubagentOptions): Promise<SubagentR
 				cwd: options.cwd,
 				shell: false,
 				stdio: ["ignore", "pipe", "pipe"],
+				env: { ...process.env, PI_PLANS_REFINER: "1" },
 			});
 			let buffer = "";
 			let closed = false;

package/src/termination-prompt.ts

@@ -0,0 +1,22 @@
+/**
+ * Single source of truth for the post-execution implementation-review
+ * termination question. Consumed by BOTH the goal-running continuation prompt
+ * (src/exec.ts AMELIORATION_PROMPT_TEXT) and the ask_choice trailing branch
+ * (tools/ask-choice.ts). Pure constants only — no runtime imports, no
+ * execution-loop coupling.
+ */
+
+export const TERMINATION_QUESTION = "How should the implementation-review loop terminate?";
+
+export const TERMINATION_OPTIONS = [
+	"goal wait: continue until no unpassed VCs remain (auto-continue each round)",
+	"until no high-severity finding (hard cap 5 rounds)",
+	"1 round",
+	"2 rounds",
+	"3 rounds",
+] as const;
+
+/** "1. <option>  2. <option> …" — recommended (goal wait) first. */
+export function renderTerminationOptions(): string {
+	return TERMINATION_OPTIONS.map((option, index) => `${index + 1}. ${option}`).join("  ");
+}