pi-plans 0.2.0 → 0.3.1

package/src/subagent.ts

@@ -9,16 +9,21 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+export type SubagentTranscriptEntryType = "assistant-text" | "thinking" | "tool-call" | "tool-result";
+
 export type SubagentProgressEvent =
 	| { type: "process"; phase: "started" | "exited"; code?: number }
-	| { type: "turn"; phase: "start" | "end" }
-	| { type: "message"; phase: "start" | "update" | "end"; role: string; text: string }
+	| { type: "turn"; phase: "start" | "end"; turnIndex?: number }
 	| {
-			type: "tool";
+			type: "transcript";
 			phase: "start" | "update" | "end";
-			toolCallId: string;
-			toolName: string;
-			detail: string;
+			entryType: SubagentTranscriptEntryType;
+			key: string;
+			text: string;
+			update: "append" | "replace";
+			streaming: boolean;
+			toolCallId?: string;
+			toolName?: string;
 			isError?: boolean;
 	  }
 	| { type: "stderr"; text: string };
@@ -72,12 +77,13 @@ export function getPiInvocation(args: string[]): { command: string; args: string
 
 interface MessageLike {
 	role: string;
-	content?: Array<{ type: string; text?: string; thinking?: string }> | string;
+	content?: unknown;
 	model?: string;
 }
 
 interface RawSubagentEvent {
 	type?: unknown;
+	turnIndex?: unknown;
 	message?: MessageLike;
 	toolCallId?: unknown;
 	toolName?: unknown;
@@ -88,6 +94,42 @@ interface RawSubagentEvent {
 	assistantMessageEvent?: unknown;
 }
 
+function formatValue(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (value === undefined) return "";
+	if (value && typeof value === "object") {
+		const content = (value as { content?: unknown }).content;
+		if (Array.isArray(content)) {
+			const text = content
+				.map((part) => {
+					if (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string") {
+						return (part as { text: string }).text;
+					}
+					return formatValue(part);
+				})
+				.filter(Boolean)
+				.join("\n");
+			if (text) return text;
+		}
+	}
+	try {
+		return JSON.stringify(value, null, 2) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+
+function messageText(message: MessageLike | undefined, kind: "text" | "thinking" = "text"): string {
+	if (!Array.isArray(message?.content)) return typeof message?.content === "string" && kind === "text" ? message.content : "";
+	return message.content
+		.filter((part) => part && typeof part === "object" && (part as { type?: unknown }).type === kind)
+		.map((part) => {
+			const value = part as { text?: unknown; thinking?: unknown };
+			return typeof value.text === "string" ? value.text : typeof value.thinking === "string" ? value.thinking : "";
+		})
+		.join("\n");
+}
+
 function finalOutput(messages: MessageLike[]): string {
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const message = messages[i];
@@ -99,29 +141,91 @@ function finalOutput(messages: MessageLike[]): string {
 	return "";
 }
 
-function messageText(message: MessageLike | undefined, kind: "text" | "thinking" = "text"): string {
-	if (!message?.content) return "";
-	if (typeof message.content === "string") return kind === "text" ? message.content : "";
-	return message.content
-		.filter((part) => part.type === kind)
-		.map((part) => (kind === "thinking" ? part.thinking ?? part.text ?? "" : part.text ?? ""))
-		.join("\n");
+interface TranscriptEventOptions {
+	toolCallId?: string;
+	toolName?: string;
+	isError?: boolean;
 }
 
-function messageEventText(value: unknown): string {
-	if (!value || typeof value !== "object") return "";
-	const event = value as { delta?: unknown; content?: unknown };
-	return typeof event.delta === "string" ? event.delta : typeof event.content === "string" ? event.content : "";
+function transcriptEvent(
+	phase: "start" | "update" | "end",
+	entryType: SubagentTranscriptEntryType,
+	key: string,
+	text: string,
+	update: "append" | "replace",
+	streaming: boolean,
+	options: TranscriptEventOptions = {},
+): SubagentProgressEvent {
+	return { type: "transcript", phase, entryType, key, text, update, streaming, ...options };
 }
 
-function preview(value: unknown, maxLength = 240): string {
-	if (typeof value === "string") return value.slice(0, maxLength);
-	if (value === undefined) return "";
-	try {
-		const text = JSON.stringify(value);
-		return text ? text.slice(0, maxLength) : "";
-	} catch {
-		return String(value).slice(0, maxLength);
+function messageContentEvents(message: MessageLike | undefined, phase: "start" | "end"): SubagentProgressEvent[] {
+	if (message?.role !== "assistant" || !Array.isArray(message.content)) return [];
+	return message.content.flatMap((part, index) => {
+		if (!part || typeof part !== "object") return [];
+		const value = part as { type?: unknown; text?: unknown; thinking?: unknown; id?: unknown; name?: unknown; arguments?: unknown };
+		if (value.type === "text" && typeof value.text === "string") {
+			return [transcriptEvent(phase, "assistant-text", `content:${index}`, value.text, "replace", phase !== "end")];
+		}
+		if (value.type === "thinking") {
+			const text = typeof value.thinking === "string" ? value.thinking : typeof value.text === "string" ? value.text : "";
+			return [transcriptEvent(phase, "thinking", `content:${index}`, text, "replace", phase !== "end")];
+		}
+		if (value.type === "toolCall") {
+			return [transcriptEvent(phase, "tool-call", `content:${index}`, formatValue(value.arguments), "replace", phase !== "end", {
+				toolCallId: typeof value.id === "string" ? value.id : undefined,
+				toolName: typeof value.name === "string" ? value.name : undefined,
+			})];
+		}
+		return [];
+	});
+}
+
+function assistantUpdateEvents(event: RawSubagentEvent): SubagentProgressEvent[] {
+	const update = event.assistantMessageEvent;
+	if (!update || typeof update !== "object") return messageContentEvents(event.message, "end");
+	const value = update as {
+		type?: unknown;
+		contentIndex?: unknown;
+		delta?: unknown;
+		content?: unknown;
+		id?: unknown;
+		toolName?: unknown;
+		toolCall?: { id?: unknown; name?: unknown; arguments?: unknown };
+	};
+	const type = typeof value.type === "string" ? value.type : "";
+	const index = typeof value.contentIndex === "number" ? value.contentIndex : 0;
+	const key = `content:${index}`;
+	switch (type) {
+		case "text_start":
+			return [transcriptEvent("start", "assistant-text", key, "", "replace", true)];
+		case "text_delta":
+			return [transcriptEvent("update", "assistant-text", key, typeof value.delta === "string" ? value.delta : "", "append", true)];
+		case "text_end":
+			return [transcriptEvent("end", "assistant-text", key, typeof value.content === "string" ? value.content : "", "replace", false)];
+		case "thinking_start":
+			return [transcriptEvent("start", "thinking", key, "", "replace", true)];
+		case "thinking_delta":
+			return [transcriptEvent("update", "thinking", key, typeof value.delta === "string" ? value.delta : "", "append", true)];
+		case "thinking_end":
+			return [transcriptEvent("end", "thinking", key, typeof value.content === "string" ? value.content : "", "replace", false)];
+		case "toolcall_start":
+			return [transcriptEvent("start", "tool-call", key, "", "replace", true, {
+				toolCallId: typeof value.id === "string" ? value.id : undefined,
+				toolName: typeof value.toolName === "string" ? value.toolName : undefined,
+			})];
+		case "toolcall_delta":
+			return [transcriptEvent("update", "tool-call", key, typeof value.delta === "string" ? value.delta : "", "append", true, {
+				toolCallId: typeof value.id === "string" ? value.id : undefined,
+				toolName: typeof value.toolName === "string" ? value.toolName : undefined,
+			})];
+		case "toolcall_end":
+			return [transcriptEvent("end", "tool-call", key, formatValue(value.toolCall?.arguments), "replace", false, {
+				toolCallId: typeof value.toolCall?.id === "string" ? value.toolCall.id : typeof value.id === "string" ? value.id : undefined,
+				toolName: typeof value.toolCall?.name === "string" ? value.toolCall.name : typeof value.toolName === "string" ? value.toolName : undefined,
+			})];
+		default:
+			return [];
 	}
 }
 
@@ -130,45 +234,43 @@ function preview(value: unknown, maxLength = 240): string {
  * protocol consumed by the refinement overlay. Unknown events are ignored so
  * adding progress support cannot make result parsing version-fragile.
  */
-export function normalizeSubagentEvent(value: unknown): SubagentProgressEvent | undefined {
-	if (!value || typeof value !== "object") return undefined;
+export function normalizeSubagentEvent(value: unknown): SubagentProgressEvent[] {
+	if (!value || typeof value !== "object") return [];
 	const event = value as RawSubagentEvent;
-	if (typeof event.type !== "string") return undefined;
-
-	if (event.type === "turn_start") return { type: "turn", phase: "start" };
-	if (event.type === "turn_end") return { type: "turn", phase: "end" };
+	if (typeof event.type !== "string") return [];
 
-	if (event.type === "message_start" || event.type === "message_update" || event.type === "message_end") {
-		if (!event.message && !event.assistantMessageEvent) return undefined;
-		const role = event.message?.role ?? "assistant";
-		return {
-			type: "message",
-			phase: event.type.slice("message_".length) as "start" | "update" | "end",
-			role,
-			text: messageText(event.message) || messageEventText(event.assistantMessageEvent),
-		};
+	if (event.type === "turn_start") {
+		return [{ type: "turn", phase: "start", ...(typeof event.turnIndex === "number" ? { turnIndex: event.turnIndex } : {}) }];
+	}
+	if (event.type === "turn_end") {
+		return [{ type: "turn", phase: "end", ...(typeof event.turnIndex === "number" ? { turnIndex: event.turnIndex } : {}) }];
 	}
 
-	const toolEvent =
-		event.type === "tool_execution_start"
-			? "start"
-			: event.type === "tool_execution_update"
-				? "update"
-				: event.type === "tool_execution_end" || event.type === "tool_result_end"
-					? "end"
-					: null;
-	if (toolEvent) {
-		return {
-			type: "tool",
-			phase: toolEvent,
-			toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : "unknown",
-			toolName: typeof event.toolName === "string" ? event.toolName : "tool",
-			detail: preview(event.args ?? event.partialResult ?? event.result),
-			...(typeof event.isError === "boolean" ? { isError: event.isError } : {}),
-		};
+	if (event.type === "message_start") return messageContentEvents(event.message, "start");
+	if (event.type === "message_update") return assistantUpdateEvents(event);
+	if (event.type === "message_end") return messageContentEvents(event.message, "end");
+
+	if (event.type === "tool_execution_start") {
+		return [transcriptEvent("start", "tool-call", `tool:${String(event.toolCallId ?? "unknown")}`, formatValue(event.args), "replace", true, {
+			toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : undefined,
+			toolName: typeof event.toolName === "string" ? event.toolName : undefined,
+		})];
+	}
+	if (event.type === "tool_execution_update") {
+		return [transcriptEvent("update", "tool-result", `tool:${String(event.toolCallId ?? "unknown")}`, formatValue(event.partialResult), "replace", true, {
+			toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : undefined,
+			toolName: typeof event.toolName === "string" ? event.toolName : undefined,
+		})];
+	}
+	if (event.type === "tool_execution_end") {
+		return [transcriptEvent("end", "tool-result", `tool:${String(event.toolCallId ?? "unknown")}`, formatValue(event.result), "replace", false, {
+			toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : undefined,
+			toolName: typeof event.toolName === "string" ? event.toolName : undefined,
+			isError: typeof event.isError === "boolean" ? event.isError : undefined,
+		})];
 	}
 
-	return undefined;
+	return [];
 }
 
 function emitProgress(options: SubagentOptions, event: SubagentProgressEvent): void {
@@ -179,7 +281,7 @@ function emitProgress(options: SubagentOptions, event: SubagentProgressEvent): v
 	}
 }
 
-const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 
 export async function runPiSubagent(options: SubagentOptions): Promise<SubagentResult> {
 	const tools = options.tools ?? ["read", "grep", "find", "ls"];
@@ -204,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;
@@ -240,7 +343,7 @@ export async function runPiSubagent(options: SubagentOptions): Promise<SubagentR
 					return;
 				}
 				const progress = normalizeSubagentEvent(event);
-				if (progress) emitProgress(options, progress);
+				for (const progressEvent of progress) emitProgress(options, progressEvent);
 				if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
 					messages.push(event.message);
 				}

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("  ");
+}

package/tests/analyze-refs.test.ts

@@ -0,0 +1,265 @@
+/** Tests for the analyze_refs tool: gates, batching, records, failure contract. */
+
+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 * as url from "node:url";
+import { after, before, describe, it } from "node:test";
+import { registerAnalyzeRefsTool } from "../tools/analyze-refs.ts";
+import { initState, setRole, startRun, readActive } from "../src/state.ts";
+
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+
+let tmpRoot: string;
+
+before(() => {
+	tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-analyze-refs-"));
+});
+
+after(() => {
+	fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+function mkWorkdir(name: string): string {
+	const dir = path.join(tmpRoot, name);
+	fs.mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function fakePiScript(body: string): string {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-fake-pi-"));
+	const script = path.join(dir, "fake-pi.mjs");
+	fs.writeFileSync(
+		script,
+		[
+			'const emit = (event) => process.stdout.write(JSON.stringify(event) + "\\n");',
+			'emit({ type: "turn_start" });',
+			`async function main() { ${body} }`,
+			"await main();",
+		].join("\n"),
+	);
+	return script;
+}
+
+function withFakePi(scriptPath: string): () => void {
+	const previousScript = process.argv[1];
+	process.argv[1] = scriptPath;
+	return () => {
+		process.argv[1] = previousScript;
+	};
+}
+
+interface CapturedTool {
+	execute: (toolCallId: string, params: unknown, signal: AbortSignal | undefined, onUpdate: unknown, ctx: unknown) => Promise<{ content: Array<{ type: string; text: string }>; details: any }>;
+}
+
+function loadTool(): CapturedTool {
+	let captured: CapturedTool | undefined;
+	const pi = {
+		registerTool: (definition: unknown) => {
+			captured = definition as CapturedTool;
+		},
+	};
+	registerAnalyzeRefsTool(pi as any, ROOT);
+	assert.ok(captured, "registerTool was not called");
+	return captured!;
+}
+
+function headlessCtx(workdir: string): unknown {
+	return { cwd: workdir };
+}
+
+function subagentLines(workdir: string): Array<any> {
+	const active = readActive(workdir);
+	assert.ok(active, "expected an active run");
+	const file = path.join(active.run_dir, "subagents.jsonl");
+	if (!fs.existsSync(file)) return [];
+	return fs
+		.readFileSync(file, "utf8")
+		.trim()
+		.split("\n")
+		.filter(Boolean)
+		.map((line) => JSON.parse(line));
+}
+
+describe("analyze_refs gates", () => {
+	it("refuses when no pi-plans state exists", async () => {
+		const workdir = mkWorkdir("gates-no-state");
+		const tool = loadTool();
+		await assert.rejects(
+			tool.execute("c1", { refs: [{ id: "ref-1", localPath: "." }] }, undefined, undefined, headlessCtx(workdir)),
+			/no pi-plans state found/,
+		);
+	});
+
+	it("refuses with role-setting guidance when reviewer mode is invalid", async () => {
+		const workdir = mkWorkdir("gates-bad-mode");
+		initState(workdir);
+		const configPath = path.join(workdir, ".git", "pi_plans", "config.json");
+		const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+		config.reviewer.mode = "bogus";
+		fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+		const tool = loadTool();
+		await assert.rejects(
+			tool.execute("c1", { refs: [{ id: "ref-1", localPath: "." }] }, undefined, undefined, headlessCtx(workdir)),
+			/reviewer role mode is missing or invalid/,
+		);
+	});
+
+	it("refuses current-session reviewer mode with a switch-to-delegated message", async () => {
+		const workdir = mkWorkdir("gates-current-session");
+		initState(workdir);
+		setRole(workdir, { role: "reviewer", mode: "current-session" });
+		const tool = loadTool();
+		await assert.rejects(
+			tool.execute("c1", { refs: [{ id: "ref-1", localPath: "." }] }, undefined, undefined, headlessCtx(workdir)),
+			/current-session.*delegated-subagent/s,
+		);
+	});
+
+	it("refuses with confirmation guidance when the reviewer model is unconfirmed", async () => {
+		const workdir = mkWorkdir("gates-unconfirmed");
+		initState(workdir);
+		setRole(workdir, { role: "reviewer", mode: "delegated-subagent" });
+		const tool = loadTool();
+		await assert.rejects(
+			tool.execute("c1", { refs: [{ id: "ref-1", localPath: "." }] }, undefined, undefined, headlessCtx(workdir)),
+			/model was never confirmed/,
+		);
+	});
+});
+
+describe("analyze_refs fanout", () => {
+	it("spawns one lane per ref in batches of at most 3, records spawns, and returns sections", async () => {
+		const workdir = mkWorkdir("fanout");
+		initState(workdir);
+		setRole(workdir, { role: "reviewer", mode: "delegated-subagent", modelSelector: "fake/model", confirmed: true });
+		startRun(workdir, { topic: "refs", skill: "plan-with-refs", requestText: "x" });
+
+		const refs = [1, 2, 3, 4, 5].map((n) => {
+			const dir = path.join(workdir, `refs`, `repo-${n}`);
+			fs.mkdirSync(dir, { recursive: true });
+			fs.writeFileSync(path.join(dir, "README.md"), `ref ${n}`);
+			return { id: `ref-${n}`, localPath: dir, title: `Ref ${n}`, url: "https://example.com", kind: "project" };
+		});
+
+		const restore = withFakePi(
+			fakePiScript(
+				`const task = process.argv.filter((arg) => arg.startsWith("Task: ")).pop() ?? "";\n` +
+					`emit({ type: "message_end", message: { role: "assistant", model: "fake/model", content: [{ type: "text", text: "ANALYSIS from " + process.cwd().split("/").pop() + "\\n" + task }] } });`,
+			),
+		);
+		const tool = loadTool();
+		try {
+			const result = await tool.execute("c1", { refs, context: "pi-plans repo" }, undefined, undefined, headlessCtx(workdir));
+			const text = result.content[0]!.text;
+			for (let n = 1; n <= 5; n += 1) {
+				assert.ok(text.includes(`### pi-plans-refs-`), "missing section header");
+				assert.ok(text.includes(`ANALYSIS from repo-${n}`), `missing per-ref cwd output for repo-${n}`);
+				assert.ok(text.includes(`Reference id: ref-${n}`), `brief must carry the ref id for repo-${n}`);
+			}
+			assert.ok(text.includes("Target repo context: pi-plans repo"), "brief must carry the target repo context");
+			assert.ok(text.includes("## Evidence Gaps"), "brief must carry the seven-section contract");
+			assert.match(text, /Persist: paste each reference's analysis into REF_ANALYSIS\.md/);
+			assert.equal(result.details.batches, 2, "five refs must run as two batches");
+			assert.equal(result.details.role, "ref-analyst");
+
+			const spawns = subagentLines(workdir);
+			assert.equal(spawns.length, 5);
+			assert.ok(spawns.every((spawn: any) => spawn.role === "ref-analyst"));
+			assert.equal(spawns[0].model, "fake/model");
+			const names = spawns.map((spawn: any) => spawn.name).sort();
+			for (let n = 1; n <= 5; n += 1) {
+				assert.ok(names.some((name: string) => name.endsWith(`-ref-${n}`)), `missing spawn name ref-${n}`);
+			}
+		} finally {
+			restore();
+		}
+	});
+
+	it("section-fails missing ref directories without aborting the rest", async () => {
+		const workdir = mkWorkdir("fanout-missing");
+		initState(workdir);
+		setRole(workdir, { role: "reviewer", mode: "delegated-subagent", modelSelector: "fake/model", confirmed: true });
+		startRun(workdir, { topic: "refs-missing", skill: "plan-with-refs", requestText: "x" });
+
+		const good = path.join(workdir, "refs", "good");
+		fs.mkdirSync(good, { recursive: true });
+		const refs = [
+			{ id: "ref-1", localPath: path.join(workdir, "refs", "does-not-exist") },
+			{ id: "ref-2", localPath: good },
+		];
+
+		const restore = withFakePi(
+			fakePiScript(
+				`emit({ type: "message_end", message: { role: "assistant", model: "fake/model", content: [{ type: "text", text: "OK analysis" }] } });`,
+			),
+		);
+		const tool = loadTool();
+		try {
+			const result = await tool.execute("c1", { refs }, undefined, undefined, headlessCtx(workdir));
+			const text = result.content[0]!.text;
+			assert.match(text, /ref-1[^\n]*— FAILED\nreference directory not found:/);
+			assert.match(text, /OK analysis/);
+			const failed = result.details.outputs.find((output: any) => output.refId === "ref-1");
+			assert.equal(failed.ok, false);
+		} finally {
+			restore();
+		}
+	});
+
+	it("throws when every ref fails", async () => {
+		const workdir = mkWorkdir("fanout-all-failed");
+		initState(workdir);
+		setRole(workdir, { role: "reviewer", mode: "delegated-subagent", modelSelector: "fake/model", confirmed: true });
+		const tool = loadTool();
+		await assert.rejects(
+			tool.execute(
+				"c1",
+				{ refs: [{ id: "ref-1", localPath: path.join(workdir, "missing-a") }, { id: "ref-2", localPath: path.join(workdir, "missing-b") }] },
+				undefined,
+				undefined,
+				headlessCtx(workdir),
+			),
+			/all reference analysis subagents failed/,
+		);
+	});
+
+	it("pins the per-batch overlay lifecycle (open before spawn, close in finally, cap 3)", () => {
+		const source = fs.readFileSync(path.join(ROOT, "tools", "analyze-refs.ts"), "utf8");
+		assert.equal((source.match(/new RefineOverlayController\("refs"/g) ?? []).length, 1, "controller must be constructed per batch inside the loop");
+		assert.match(source, /overlay\?\.open\(refineOverlayContext\(ctx\), modelLabel\)/);
+		assert.match(source, /await overlay\?\.close\(\);/);
+		assert.match(source, /const BATCH_SIZE = 3;/);
+		assert.ok(source.indexOf("overlay?.open(") < source.indexOf("await overlay?.close();"), "open must precede close");
+	});
+
+	it("skips recording without an active run (adhoc) and still succeeds", async () => {
+		const workdir = mkWorkdir("adhoc");
+		initState(workdir);
+		setRole(workdir, { role: "reviewer", mode: "delegated-subagent", modelSelector: "fake/model", confirmed: true });
+		const refDir = path.join(workdir, "refs", "solo");
+		fs.mkdirSync(refDir, { recursive: true });
+
+		const restore = withFakePi(
+			fakePiScript(
+				`emit({ type: "message_end", message: { role: "assistant", model: "fake/model", content: [{ type: "text", text: "adhoc analysis" }] } });`,
+			),
+		);
+		const tool = loadTool();
+		try {
+			const result = await tool.execute("c1", { refs: [{ id: "ref-1", localPath: refDir }] }, undefined, undefined, headlessCtx(workdir));
+			assert.match(result.content[0]!.text, /### pi-plans-refs-adhoc-ref-1/);
+			assert.equal(readActive(workdir), null);
+			const ledger = path.join(workdir, ".git", "pi_plans", "runs");
+			const runs = fs.existsSync(ledger) ? fs.readdirSync(ledger) : [];
+			const spawnFiles = runs.flatMap((run) =>
+				fs.existsSync(path.join(ledger, run, "subagents.jsonl")) ? [fs.readFileSync(path.join(ledger, run, "subagents.jsonl"), "utf8")] : [],
+			);
+			assert.equal(spawnFiles.join("").trim(), "", "adhoc calls must not record spawns");
+		} finally {
+			restore();
+		}
+	});
+});