pi-plans 0.3.0 → 0.3.2

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,
@@ -59,6 +60,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 +85,7 @@ function makeHarness(workdir: string): Harness {
 		current: { provider: "p", id: "m" },
 		thinking: "high",
 		userMessages: [],
+		userMessageOptions: [],
 	};
 	let contextPercent: number | null = 0;
 	const registryModels = [
@@ -113,8 +116,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 +273,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 +1456,11 @@ function makePreparation(reason: "manual" | "threshold" | "overflow", previousSu
 		settings: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000 },
 	};
 }
+
+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/goal-wait.test.ts

@@ -0,0 +1,269 @@
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, describe, it } from "node:test";
+import {
+	GOAL_WAIT_CUSTOM_TYPE, filterGoalWaitMessages, getExecution, noteCompactionStarted,
+	registerExecutionTurnHandlers, restoreFromSession, startExecution, stopExecution,
+} from "../src/exec.ts";
+import { executeCommand, executeHandoff, setCurrentApi } from "../tools/execute-plan.ts";
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-goal-wait-"));
+after(() => fs.rmSync(root, { recursive: true, force: true }));
+let serial = 0;
+
+async function setup(mode = "tui") {
+	const cwd = path.join(root, String(++serial));
+	fs.mkdirSync(cwd);
+	const planPath = path.join(cwd, "PLAN_v1.md");
+	fs.writeFileSync(planPath, "## Verifier Checklist\n- [ ] `VC-001` first\n- [ ] `VC-002` second\n");
+	const handlers = new Map<string, Array<(event: any, ctx: any) => any>>();
+	const messages: any[] = [];
+	const entries: any[] = [];
+	const notices: string[] = [];
+	const pending: unknown[] = [];
+	let idle = true;
+	let status = "";
+	const ctx: any = {
+		cwd, mode, hasUI: mode === "tui" || mode === "rpc", sessionManager: {},
+		isIdle: () => idle, hasPendingMessages: () => pending.length > 0,
+		ui: { setStatus: (_key: string, s: string) => { status = s; },
+			notify: (s: string) => notices.push(s), theme: { fg: (_c: string, s: string) => s },
+			confirm: async () => { throw new Error("same-plan resume must not re-enter handoff"); } },
+	};
+	const pi: any = {
+		on: (name: string, handler: any) => handlers.set(name, [...(handlers.get(name) ?? []), handler]),
+		appendEntry: (customType: string, data: unknown) => entries.push({ type: "custom", customType, data: structuredClone(data) }),
+		sendUserMessage: () => { throw new Error("goal-wait must not impersonate a user"); },
+		sendMessage: (message: any, options: any) => {
+			messages.push({ ...message, options });
+			if (message.customType === GOAL_WAIT_CUSTOM_TYPE && options?.triggerTurn) idle = false;
+		},
+	};
+	registerExecutionTurnHandlers(pi);
+	setCurrentApi(pi);
+	await startExecution(pi, ctx, planPath, [
+		{ id: "VC-001", text: "first", done: false }, { id: "VC-002", text: "second", done: false },
+	]);
+	const emit = async (name: string, event = {}) => {
+		for (const handler of handlers.get(name) ?? []) await handler(event, ctx);
+	};
+	const begin = async () => { idle = false; await emit("agent_start"); };
+	const turn = async (text = "working", stopReason = "stop") => emit("turn_end", {
+		message: { role: "assistant", stopReason, content: [{ type: "text", text },
+			...(stopReason === "toolUse" ? [{ type: "toolCall", id: "call", name: "read", arguments: {} }] : [])],
+			usage: { input: 10, output: 5 } }, toolResults: [],
+	});
+	const settle = async () => { idle = true; await emit("agent_settled"); };
+	const run = async (text = "working", stopReason = "stop") => { await begin(); await turn(text, stopReason); await settle(); };
+	return { pi, ctx, planPath, messages, entries, notices, pending, emit, begin, turn, settle, run,
+		wakes: () => messages.filter(m => m.customType === GOAL_WAIT_CUSTOM_TYPE),
+		status: () => status, setIdle: (value: boolean) => { idle = value; } };
+}
+
+describe("goal-wait settled lifecycle", () => {
+	it("never queues on ten tool turns and never wakes after completion", async () => {
+		const h = await setup();
+		await h.begin();
+		for (let i = 0; i < 10; i++) await h.turn("working", "toolUse");
+		assert.equal(h.wakes().length, 0);
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		await h.turn("[DONE:VC-001] [DONE:VC-002]");
+		await h.settle();
+		await h.settle();
+		assert.equal(getExecution(), null);
+		assert.equal(h.wakes().length, 0);
+		assert.equal(h.messages.filter(m => m.customType === "pi-plans-complete").length, 1);
+	});
+
+	for (const mode of ["tui", "rpc"]) {
+		it(`${mode}: sends one hidden fresh wake and deduplicates settled`, async () => {
+			const h = await setup(mode);
+			await h.run("[DONE:VC-001]");
+			await h.settle();
+			const [wake] = h.wakes();
+			assert.equal(h.wakes().length, 1);
+			assert.equal(wake.display, false);
+			assert.equal(wake.options.triggerTurn, true);
+			assert.match(wake.content, /1\/2 verifier items done/);
+			assert.match(wake.content, /- `VC-002` second/);
+			assert.doesNotMatch(wake.content, /- `VC-001` first/);
+			assert.deepEqual(filterGoalWaitMessages([wake]), [wake]);
+			assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		});
+	}
+
+	for (const mode of ["print", "json"]) {
+		it(`${mode}: tracks markers without any automatic wake`, async () => {
+			const h = await setup(mode);
+			await h.run("[DONE:VC-001]");
+			assert.equal(getExecution()?.items[0].done, true);
+			await h.run("failed", "error");
+			await h.run("[DONE:VC-002]");
+			assert.equal(h.wakes().length, 0);
+			assert.equal(getExecution(), null);
+			assert.equal(h.messages.find(m => m.customType === "pi-plans-complete").options.triggerTurn, false);
+		});
+	}
+
+	for (const gate of ["busy", "pending", "inFlight", "resumeGuard", "pendingFollowUpPrompt", "lifecycle"]) {
+		it(`does not send or count when ${gate} owns continuation`, async () => {
+			const h = await setup();
+			await h.begin();
+			await h.turn();
+			h.setIdle(gate !== "busy");
+			if (gate === "pending") h.pending.push("user message", { customType: "another-extension" });
+			else if (gate === "lifecycle") noteCompactionStarted(h.ctx, undefined);
+			else if (gate !== "busy") h.ctx.sessionManager.__executionCompaction = { [gate]: gate === "pendingFollowUpPrompt" ? "follow-up" : true };
+			const original = structuredClone(h.pending);
+			await h.emit("agent_settled");
+			assert.equal(h.wakes().length, 0);
+			assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+			assert.deepEqual(h.pending, original);
+			if (gate === "busy") {
+				await h.settle();
+				assert.equal(h.wakes().length, 1, "a busy notification must not consume the real settled cycle");
+			}
+		});
+	}
+
+	for (const stopReason of ["error", "aborted"]) {
+		it(`${stopReason}: pauses once and only genuine input resumes`, async () => {
+			const h = await setup();
+			await h.run("failed", stopReason);
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			await h.settle();
+			assert.equal(h.notices.length, 1);
+			await h.emit("input", { source: "extension" });
+			await h.emit("before_agent_start");
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			assert.equal(h.wakes().length, 0);
+			await h.emit("input", { source: "rpc" });
+			assert.equal(getExecution()?.goalWait?.paused, false);
+			assert.equal(h.wakes().length, 0, "input is already owned by Pi");
+			await h.run();
+			assert.equal(h.wakes().length, 1);
+		});
+	}
+
+	it("leaves retries to Pi and refuses unknown or intentional tool termination", async () => {
+		const h = await setup();
+		await h.begin();
+		await h.turn("retryable failure", "error");
+		await h.emit("agent_end");
+		assert.equal(h.wakes().length, 0);
+		assert.equal(getExecution()?.goalWait?.paused, false);
+		await h.turn("recovered");
+		await h.settle();
+		assert.equal(h.wakes().length, 1);
+		for (const reason of ["toolUse", "length", "unknown"]) await h.run("intentional stop", reason);
+		assert.equal(h.wakes().length, 1);
+	});
+
+	for (const [text, count, field] of [["working", 3, "noProgressRounds"], ["waiting for CI", 6, "waitRounds"]] as const) {
+		it(`pauses at ${count} ${field} settled cycles, not intermediate turns`, async () => {
+			const h = await setup();
+			for (let i = 1; i <= count; i++) {
+				await h.begin();
+				for (let j = 0; j < 4; j++) await h.turn("tool work", "toolUse");
+				assert.equal(getExecution()?.goalWait?.[field], i - 1);
+				await h.turn(text);
+				await h.settle();
+				await h.settle();
+				assert.equal(getExecution()?.goalWait?.[field], i);
+			}
+			assert.equal(h.wakes().length, count - 1);
+			assert.equal(getExecution()?.goalWait?.paused, true);
+			assert.match(h.status(), /goal-wait paused/);
+		});
+	}
+
+	it("real progress resets both nonzero counters through registered handlers", async () => {
+		const h = await setup();
+		await h.run();
+		await h.run("waiting for tests");
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 1);
+		assert.equal(getExecution()?.goalWait?.waitRounds, 1);
+		await h.run("[DONE:VC-001]");
+		assert.equal(getExecution()?.goalWait?.noProgressRounds, 0);
+		assert.equal(getExecution()?.goalWait?.waitRounds, 0);
+		const persisted = h.entries.filter(e => e.customType === "pi-plans-exec").at(-1).data;
+		assert.equal(persisted.items[0].done, true);
+		assert.equal(persisted.goalWait.noProgressRounds, 0);
+	});
+
+	it("same-plan explicit handoff resumes without losing verified progress", async () => {
+		const h = await setup();
+		await h.run("[DONE:VC-001]");
+		await h.run("cancelled", "aborted");
+		const ex = getExecution()!;
+		const before = structuredClone(ex);
+		const outcome = await executeCommand(h.ctx, h.planPath);
+		assert.equal(outcome.status, "executing");
+		assert.equal(getExecution(), ex);
+		assert.deepEqual(ex.items, before.items);
+		assert.deepEqual(ex.usage, before.usage);
+		assert.equal(ex.startedAt, before.startedAt);
+		assert.equal(ex.goalWait?.paused, false);
+		assert.equal(h.wakes().length, 2);
+		await executeCommand(h.ctx, h.planPath);
+		assert.equal(h.wakes().length, 2);
+		await assert.rejects(executeHandoff(h.ctx, h.planPath), /must not re-enter handoff/);
+		const other = path.join(h.ctx.cwd, "PLAN_v2.md");
+		fs.copyFileSync(h.planPath, other);
+		await assert.rejects(executeCommand(h.ctx, other), /must not re-enter handoff/);
+	});
+
+	it("a paused command during another run preserves its next settled opportunity", async () => {
+		const h = await setup();
+		await h.run("interrupted", "aborted");
+		await h.begin();
+		const outcome = await executeCommand(h.ctx, h.planPath);
+		assert.equal(outcome.status, "executing");
+		assert.equal(getExecution()?.goalWait?.paused, false);
+		assert.equal(h.wakes().length, 0, "busy command must not enqueue a kick");
+		await h.turn("still incomplete");
+		await h.settle();
+		assert.equal(h.wakes().length, 1);
+	});
+
+	it("restore preserves pause and counters but cannot replay a wake", async () => {
+		const h = await setup();
+		for (let i = 0; i < 3; i++) await h.run();
+		const oldWake = h.wakes().at(-1);
+		const before = structuredClone(getExecution()?.goalWait);
+		await restoreFromSession(h.pi, h.ctx, h.entries);
+		await h.settle();
+		assert.deepEqual(getExecution()?.goalWait, before);
+		assert.equal(h.wakes().length, 2);
+		assert.deepEqual(filterGoalWaitMessages([oldWake]), []);
+	});
+
+	for (const exit of ["stop", "complete", "replacement", "shutdown"]) {
+		it(`${exit} invalidates wake identity without filtering user messages`, async () => {
+			const h = await setup();
+			await h.run();
+			const wake = h.wakes()[0];
+			if (exit === "stop") await stopExecution(h.pi, h.ctx, "test");
+			if (exit === "complete") await h.turn("[DONE:VC-001] [DONE:VC-002]");
+			if (exit === "replacement") await startExecution(h.pi, h.ctx, h.planPath, [{ id: "VC-003", text: "new", done: false }]);
+			if (exit === "shutdown") await h.emit("session_shutdown");
+			await h.settle();
+			const user = { role: "user", content: "Goal wait: this is my text" };
+			const other = { customType: "another-extension", content: "continue" };
+			assert.deepEqual(filterGoalWaitMessages([wake, user, other]), [user, other]);
+			assert.equal(h.wakes().length, 1);
+		});
+	}
+
+	it("a synchronous dispatch failure pauses once instead of leaving a retry lock", async () => {
+		const h = await setup();
+		h.pi.sendMessage = () => { throw new Error("dispatch failed"); };
+		await h.run();
+		await h.settle();
+		assert.equal(getExecution()?.goalWait?.paused, true);
+		assert.match(h.notices[0], /dispatch failed/);
+		assert.equal(h.notices.length, 1);
+	});
+});

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 });