pi-plans 0.3.0 → 0.3.1

package/tests/exec.test.ts

@@ -6,6 +6,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { after, before, describe, it } from "node:test";
 import {
+	AMELIORATION_PROMPT_TEXT,
 	applyDoneMarkers,
 	applyImplMarkers,
 	applyCurrentIMarker,
@@ -19,6 +20,7 @@ import {
 	filterExecutionResumeMessages,
 	filterPlanningResumeMessages,
 	getExecution,
+	resumeGoalWaitIfPaused,
 	handleExecutionBeforeCompact,
 	handleExecutionCompact,
 	handleExecutionTurnCompaction,
@@ -35,6 +37,7 @@ import {
 	refreshPlanningCompactionCooldown,
 	requestPlanningCompaction,
 	restoreFromSession,
+	resetGoalWaitTurnFlags,
 	shouldTriggerPlanningCompaction,
 	startExecution,
 	recordExecutionTurn,
@@ -59,6 +62,7 @@ interface Recorded {
 	current: { provider: string; id: string } | null;
 	thinking: string | null;
 	userMessages: string[];
+	userMessageOptions: Array<Record<string, unknown> | null>;
 	compacts?: { customInstructions?: string }[];
 }
 
@@ -83,6 +87,7 @@ function makeHarness(workdir: string): Harness {
 		current: { provider: "p", id: "m" },
 		thinking: "high",
 		userMessages: [],
+		userMessageOptions: [],
 	};
 	let contextPercent: number | null = 0;
 	const registryModels = [
@@ -113,8 +118,9 @@ function makeHarness(workdir: string): Harness {
 		sendMessage: (message: { customType: string; content: string }, options?: { triggerTurn?: boolean }) => {
 			recorded.messages.push({ ...message, options });
 		},
-		sendUserMessage: async (content: string) => {
+		sendUserMessage: async (content: string, options?: Record<string, unknown>) => {
 			recorded.userMessages.push(content);
+			recorded.userMessageOptions.push(options ?? null);
 		},
 		setModel: async (model: { provider: string; id: string }) => {
 			recorded.models.push({ provider: model.provider, id: model.id });
@@ -269,7 +275,8 @@ describe("execution loop", () => {
 		const completeMessage = recorded.messages.find((message) => message.customType === "pi-plans-complete");
 		assert.ok(completeMessage);
 		assert.match(completeMessage.content, /Goal-running continuation/);
-		assert.match(completeMessage.content, /termination condition of the implementation-review loop/);
+		assert.match(completeMessage.content, /How should the implementation-review loop terminate\?/);
+		assert.match(completeMessage.content, /goal wait: continue until no unpassed VCs remain/);
 		assert.doesNotMatch(completeMessage.content, /Run a post-execution amelioration round/);
 		assert.equal(completeMessage.options?.triggerTurn, true);
 		const ameliorateEntry = recorded.entries.find((entry) => entry.customType === "pi-plans-ameliorate");
@@ -1451,3 +1458,139 @@ function makePreparation(reason: "manual" | "threshold" | "overflow", previousSu
 		settings: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 },
 	};
 }
+
+describe("execution goal-wait continuation", () => {
+	// Fresh per-turn continuation flags, mirroring the before_agent_start reset.
+	const setup = (workdir: string) => {
+		resetGoalWaitTurnFlags();
+		const harness = makeHarness(workdir);
+		registerExecutionTurnHandlers(harness.pi);
+		return harness;
+	};
+
+	it("sends a goal-wait followUp when a turn ends with unpassed VCs", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx, recorded, emit } = setup(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+		recorded.userMessages.length = 0;
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "still working" }] } });
+		assert.equal(recorded.userMessages.length, 1);
+		assert.match(recorded.userMessages[0], /Goal wait: 1\/1 verifier items still open/);
+		assert.match(recorded.userMessages[0], /\`VC-001\`/);
+		assert.equal(recorded.userMessageOptions.at(-1)?.deliverAs, "followUp");
+		assert.match(recorded.status ?? "", /goal-wait · 无进展 1\/3 · 等待 0\/6/);
+	});
+
+	it("sends the goal-wait followUp in headless sessions too", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx, recorded, emit } = setup(workdir);
+		(ctx as any).hasUI = false;
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+		recorded.userMessages.length = 0;
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "still working" }] } });
+		assert.equal(recorded.userMessages.length, 1);
+		assert.match(recorded.userMessages[0], /Goal wait: 1\/1 verifier items still open/);
+	});
+
+	it("does not goal-wait when every VC is done (completion path)", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx, recorded, emit } = setup(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+		recorded.userMessages.length = 0;
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "done [DONE:VC-001]" }] } });
+		assert.equal(recorded.userMessages.length, 0);
+		assert.ok(recorded.messages.some((message) => message.customType === "pi-plans-complete"));
+	});
+
+	it("skips goal-wait while any compaction continuation flag is active", async () => {
+		const variants = [
+			{ inFlight: true, resumeGuard: false, pendingFollowUpPrompt: null },
+			{ inFlight: false, resumeGuard: true, pendingFollowUpPrompt: null },
+			{ inFlight: false, resumeGuard: false, pendingFollowUpPrompt: "compaction follow-up" },
+		];
+		for (const flags of variants) {
+			const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+			const { pi, ctx, recorded, emit } = setup(workdir);
+			await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+			(ctx.sessionManager as any).__executionCompaction = { ...flags, cooldownActive: false };
+			recorded.userMessages.length = 0;
+			await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "working" }] } });
+			assert.equal(recorded.userMessages.length, 0, `flags ${JSON.stringify(flags)} must skip goal-wait`);
+		}
+	});
+
+	it("pauses after 3 no-progress rounds and resumes on kick", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx, recorded, emit } = setup(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+		recorded.userMessages.length = 0;
+		for (let round = 0; round < 3; round++) {
+			await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "still working" }] } });
+		}
+		assert.equal(getExecution()?.goalWait?.paused, true);
+		assert.equal(recorded.userMessages.length, 2, "third quiet round must not queue another followUp");
+		assert.ok(recorded.notifies.some((entry) => /goal-wait paused/.test(entry.message)));
+		assert.match(recorded.status ?? "", /⏸ goal-wait paused/);
+
+		resumeGoalWaitIfPaused(pi, ctx);
+		assert.equal(getExecution()?.goalWait?.paused, false);
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "progress [DONE:VC-001]" }] } });
+		assert.match(recorded.userMessages.at(-1) ?? "", /Goal wait/);
+	});
+
+	it("waiting rounds are exempt until the sixth quiet waiting round", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx, recorded, emit } = setup(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001"));
+		for (let round = 1; round <= 5; round++) {
+			await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: `waiting for CI (${round})` }] } });
+			assert.equal(getExecution()?.goalWait?.paused, false, `round ${round} must not pause`);
+		}
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "waiting for CI (6)" }] } });
+		assert.equal(getExecution()?.goalWait?.paused, true);
+		assert.ok(recorded.notifies.some((entry) => /waiting without progress for 6 rounds/.test(entry.message)));
+	});
+
+	it("progress resets both guard counters", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx, emit } = makeHarness(workdir);
+		await startExecution(pi, ctx, path.join(workdir, "PLAN_v1.md"), items("VC-001", "VC-002"));
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "working" }] } });
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "working" }] } });
+		await emit("turn_end", { message: { role: "assistant", content: [{ type: "text", text: "progress [DONE:VC-001]" }] } });
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		assert.equal(getExecution()?.goalWait?.waitRounds, 0);
+	});
+
+	it("keeps goal-wait counters across restore", async () => {
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+		const { pi, ctx } = setup(workdir);
+		const planPath = path.join(workdir, "PLAN_v1.md");
+		fs.writeFileSync(planPath, "# plan");
+		const snapshot = {
+			planPath,
+			items: items("VC-001"),
+			startedAt: "2026-08-25T00:00:00Z",
+			usage: { inToks: 0, outToks: 0 },
+			implItems: [],
+			implStatus: {},
+			goalWait: { noProgressRounds: 2, waitRounds: 1, lastMarkers: null, paused: false },
+		};
+		const entries = [
+			{ type: "custom", customType: "pi-plans-exec", data: snapshot },
+			{ type: "message", message: { role: "assistant", content: [{ type: "text", text: "no new progress this turn" }] } },
+		];
+		await restoreFromSession(pi, ctx, entries as any);
+		// Replay advanced the marker snapshot past the persisted baseline → counters reset (D-010).
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		assert.equal(getExecution()?.goalWait?.waitRounds, 0);
+	});
+});
+
+describe("amelioration termination prompt", () => {
+	it("recommends goal-wait first and keeps the round options", () => {
+		assert.match(AMELIORATION_PROMPT_TEXT, /goal wait: continue until no unpassed VCs remain/);
+		assert.match(AMELIORATION_PROMPT_TEXT, /until no high-severity finding \(hard cap 5 rounds\)/);
+		assert.match(AMELIORATION_PROMPT_TEXT, /How should the implementation-review loop terminate\?/);
+	});
+});

package/tests/guard.test.ts

@@ -6,7 +6,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { after, before, describe, it } from "node:test";
 import { planningWriteBlockReason } from "../src/guard.ts";
-import { initState, setRunStatus, startRun } from "../src/state.ts";
+import { initState, setRefsRoot, setRunStatus, startRun } from "../src/state.ts";
 
 let tmpRoot: string;
 
@@ -61,6 +61,32 @@ describe("planning write guard", () => {
 		assert.equal(planningWriteBlockReason({ workdir, toolName: "write", rawPath: "src/main.ts" }), null);
 	});
 
+	it("allows writes under a configured refs_root and stays strict without one", () => {
+		const workdir = path.join(tmpRoot, "refs-root-guard");
+		fs.mkdirSync(workdir);
+		initState(workdir);
+		startRun(workdir, { topic: "refs guard", skill: "plan-with-refs", requestText: "x" });
+
+		// Without a configured refs_root, ./refs/ writes stay blocked.
+		assert.ok(planningWriteBlockReason({ workdir, toolName: "write", rawPath: "./refs/paper.md" }));
+
+		setRefsRoot(workdir, "./refs", "user");
+		assert.equal(planningWriteBlockReason({ workdir, toolName: "write", rawPath: "./refs/paper.md" }), null);
+		assert.equal(
+			planningWriteBlockReason({ workdir, toolName: "edit", rawPath: path.join(workdir, "refs", "notes.md") }),
+			null,
+		);
+		// The refs root does not open up the whole worktree.
+		assert.ok(planningWriteBlockReason({ workdir, toolName: "write", rawPath: "src/main.ts" }));
+
+		// The .git/pi-plans/refs (hyphenated) recommendation is covered by an absolute entry too.
+		setRefsRoot(workdir, ".git/pi-plans/refs", "user");
+		assert.equal(
+			planningWriteBlockReason({ workdir, toolName: "write", rawPath: ".git/pi-plans/refs/repo-a/" }),
+			null,
+		);
+	});
+
 	it("is inactive without an active run", () => {
 		const workdir = path.join(tmpRoot, "no-run");
 		fs.mkdirSync(workdir);

package/tests/plans.test.ts

@@ -34,4 +34,14 @@ describe("plans tool source", () => {
 		assert.doesNotMatch(source, /case "set-execution-model"/);
 		assert.match(source, /params\.artifactRootSource/);
 	});
+
+	it("declares refsRootSource and wires the set-refs-root action plus ref-analyst role", () => {
+		const source = readPlansSource();
+		assert.match(source, /refsRoot:\s*Type\.Optional/);
+		assert.match(source, /refsRootSource:\s*Type\.Optional/);
+		assert.match(source, /import \{[\s\S]*setRefsRoot,[\s\S]*\} from "\.\.\/src\/state\.ts";/);
+		assert.match(source, /case "set-refs-root"/);
+		assert.match(source, /params\.refsRootSource/);
+		assert.match(source, /"reviewer", "criticizer", "ref-analyst"/);
+	});
 });

package/tests/refine-prompts.test.ts

@@ -2,7 +2,7 @@ import * as assert from "node:assert/strict";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { describe, it } from "node:test";
-import { buildCriticizerTask, buildImplementationCriticizerTask, buildImplementationReviewerTask, buildReviewerTask, reviewerLanes } from "../src/refine-prompts.ts";
+import { buildCriticizerTask, buildImplementationCriticizerTask, buildImplementationReviewerTask, buildRefAnalystTask, buildReviewerTask, refAnalystSections, reviewerLanes } from "../src/refine-prompts.ts";
 
 describe("reviewerLanes", () => {
 	it("uses stable lane ids for the big-plan fanout", () => {
@@ -34,6 +34,40 @@ describe("buildReviewerTask", () => {
 	});
 });
 
+describe("buildRefAnalystTask", () => {
+	it("carries the seven-section contract, ref metadata, and language instruction", () => {
+		const text = buildRefAnalystTask({
+			refId: "ref-1",
+			localPath: "/cache/refs/some-repo",
+			title: "Some Repo",
+			url: "https://github.com/x/some-repo",
+			kind: "project",
+			context: "pi-plans extension",
+			languageTag: "zh-Hans",
+		});
+
+		assert.match(text, /Reference id: ref-1/);
+		assert.match(text, /Title: Some Repo/);
+		assert.match(text, /URL: https:\/\/github\.com\/x\/some-repo/);
+		assert.match(text, /Local path \(your working directory\): \/cache\/refs\/some-repo/);
+		assert.match(text, /Authority boundary: read-only analysis only\./);
+		assert.match(text, /Target repo context: pi-plans extension/);
+		assert.match(text, /BCP47 tag "zh-Hans"/);
+		for (const section of refAnalystSections()) {
+			assert.ok(text.includes(`## ${section}`), `missing section: ${section}`);
+		}
+		assert.equal(refAnalystSections().length, 7);
+	});
+
+	it("omits optional lines when metadata is absent", () => {
+		const text = buildRefAnalystTask({ refId: "ref-2", localPath: "/tmp/r" });
+		assert.doesNotMatch(text, /Title:/);
+		assert.doesNotMatch(text, /URL:/);
+		assert.doesNotMatch(text, /Kind:/);
+		assert.doesNotMatch(text, /BCP47 tag/);
+	});
+});
+
 describe("buildCriticizerTask", () => {
 	it("asks for short adversarial questions only", () => {
 		const text = buildCriticizerTask({

package/tests/refine-ui.test.ts

@@ -127,6 +127,40 @@ describe("refine overlay viewport", () => {
 		assert.ok(lines.some((line) => line.includes("output")));
 	});
 
+	it("renders the Refs title for the refs role and keeps legacy titles distinct", () => {
+		const refs = new RefineOverlayComponent(
+			fakeTheme,
+			"refs",
+			[readyLane("ref-1", "ref-1", "analysis output")],
+			() => {},
+			undefined,
+			"zai/glm-5.3-flash:high",
+		);
+		const refLines = refs.render(120);
+		assert.ok(refLines.some((line) => line.includes("Refs (zai/glm-5.3-flash:high)")));
+		assert.ok(refLines.every((line) => !line.includes("Criticizer") && !line.includes("Reviewer")));
+
+		const reviewer = new RefineOverlayComponent(
+			fakeTheme,
+			"reviewer",
+			[readyLane("lane-1", "general", "ok")],
+			() => {},
+			undefined,
+			"m1",
+		);
+		assert.ok(reviewer.render(120).some((line) => line.includes("Reviewer (m1)")));
+
+		const criticizer = new RefineOverlayComponent(
+			fakeTheme,
+			"criticizer",
+			[readyLane("lane-1", "criticizer", "ok")],
+			() => {},
+			undefined,
+			"m2",
+		);
+		assert.ok(criticizer.render(120).some((line) => line.includes("Criticizer (m2)")));
+	});
+
 	it("renders model-aware titles and footer hints", () => {
 		const lanes = [
 			readyLane("lane-1", "correctness", "correctness output"),

package/tests/state.test.ts

@@ -13,6 +13,7 @@ import {
 	recordDecision,
 	setLanguage,
 	setArtifactRoot,
+	setRefsRoot,
 	setRole,
 	setRunStatus,
 	showConfig,
@@ -72,6 +73,37 @@ describe("init", () => {
 		assert.equal(config.artifact_root, "./docs/pi-plans");
 		assert.equal(config.artifact_root_source, "unset");
 		assert.equal(config.artifact_root_updated_at, null);
+		assert.equal(config.refs_root, null);
+		assert.equal(config.refs_root_source, "unset");
+		assert.equal(config.refs_root_updated_at, null);
+	});
+
+	it("normalizes old configs missing the refs_root trio", () => {
+		const workdir = mkWorkdir("refs-root-normalize");
+		initState(workdir);
+		const configPath = path.join(commonDir(workdir), "pi_plans", "config.json");
+		const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+		delete config.refs_root;
+		delete config.refs_root_source;
+		delete config.refs_root_updated_at;
+		fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+		const updated = initState(workdir);
+		assert.equal(updated.config.refs_root, null);
+		assert.equal(updated.config.refs_root_source, "unset");
+		assert.equal(updated.config.refs_root_updated_at, null);
+		assert.equal(readConfig(workdir).refs_root, null);
+	});
+
+	it("setRefsRoot persists the trio", () => {
+		const workdir = mkWorkdir("refs-root-set");
+		initState(workdir);
+		setRefsRoot(workdir, ".git/pi-plans/refs", "user");
+		assert.equal(readConfig(workdir).refs_root, ".git/pi-plans/refs");
+		assert.equal(readConfig(workdir).refs_root_source, "user");
+		assert.ok(typeof readConfig(workdir).refs_root_updated_at === "string");
+		const shown = showConfig(workdir);
+		assert.equal(shown.refs_root, ".git/pi-plans/refs");
+		assert.equal(shown.refs_root_source, "user");
 	});
 
 	it("migrates legacy artifact roots to ./docs/pi-plans", () => {

package/tests/subagent.test.ts

@@ -60,6 +60,28 @@ describe("subagent runner lifecycle", () => {
 		assert.equal(result.turns, 1);
 	});
 
+	it("marks refiner children with PI_PLANS_REFINER=1", async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-fake-pi-env-"));
+		const script = path.join(dir, "fake-pi-env.mjs");
+		fs.writeFileSync(
+			script,
+			[
+				'const emit = (event) => process.stdout.write(JSON.stringify(event) + "\\n");',
+				'emit({ type: "message_end", message: { role: "assistant", model: "fake/model", content: [{ type: "text", text: "marker=" + String(process.env.PI_PLANS_REFINER) }] } });',
+			].join("\n"),
+		);
+		const previousScript = process.argv[1];
+		process.argv[1] = script;
+		try {
+			const result = await runPiSubagent({ systemPrompt: "p", task: "env", cwd: process.cwd(), timeoutMs: 2000 });
+			assert.equal(result.ok, true);
+			assert.equal(result.output, "marker=1");
+		} finally {
+			process.argv[1] = previousScript;
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
 	it("returns a cancelled result after aborting the child", async () => {
 		const abort = new AbortController();
 		const promise = withFakePi("slow", { signal: abort.signal, timeoutMs: 2000 });