pi-plans 0.8.0 → 0.8.1

package/tests/exec-review-loop.test.ts

@@ -72,7 +72,7 @@ function freshWorkdir(): { workdir: string; planPath: string; runId: string } {
 	return { workdir, planPath, runId: run.run_id };
 }
 
-function makeCtx(workdir: string, mode: "print" | "tui" = "print", customOpens?: { count: number }) {
+function makeCtx(workdir: string, mode: "print" | "tui" = "print", customOpens?: { count: number }, components?: RefineOverlayComponent[]) {
 	const entries: Array<{ customType: string; data?: unknown; content?: string }> = [];
 	const ctx = {
 		cwd: workdir,
@@ -85,9 +85,12 @@ function makeCtx(workdir: string, mode: "print" | "tui" = "print", customOpens?:
 			setStatus: () => {},
 			setWidget: () => {},
 			theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
-			// Minimal overlay host: counts ui.custom opens (one per controller).
-			custom: () => {
+			// Minimal overlay host: counts ui.custom opens (one per controller)
+			// and captures the rendered component so tests can drive its input.
+			custom: (render: (tui: unknown, theme: unknown, kb: unknown, done: () => void) => { handleInput(data: string): void }) => {
 				if (customOpens) customOpens.count += 1;
+				const component = render({ requestRender() {}, terminal: undefined }, { fg: (_c: string, t: string) => t, bold: (t: string) => t }, undefined, () => {});
+				if (components) components.push(component);
 				return Promise.resolve();
 			},
 		},
@@ -296,14 +299,19 @@ describe("execution-review loop (v0.8)", () => {
 		const ctl = controlledRunner();
 		__setAuditRunnerForTests(ctl.runner);
 		const opens = { count: 0 };
-		const ctx = makeCtx(workdir, "tui", opens);
+		const components: Array<{ handleInput(data: string): void }> = [];
+		const ctx = makeCtx(workdir, "tui", opens, components);
 		await restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
 		assert.equal(opens.count, 1, "the round opened its overlay before spawning");
-		// ESC closed the (one-shot) controller; the reopen shortcut rebuilds it
-		// from engine-held lane state while the round is still in flight.
+		// ESC closed the (one-shot) controller — only THEN may reopen rebuild it
+		// (the anti-stacking guard keeps a second overlay off a live one).
+		components[0]!.handleInput("\x1b");
 		const { reopenReviewOverlay } = await import("../src/exec.ts");
 		reopenReviewOverlay(ctx);
-		assert.equal(opens.count, 2, "reopen builds a fresh controller for the same round");
+		assert.equal(opens.count, 2, "reopen builds a fresh controller for the same round after ESC");
+		// A second reopen while the new controller is live must NOT stack.
+		reopenReviewOverlay(ctx);
+		assert.equal(opens.count, 2, "reopen never stacks a second live overlay");
 		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "done" });
 		await __awaitReviewRoundForTests();
 		// No round in flight → the shortcut is inert.
@@ -329,3 +337,388 @@ describe("execution-review loop (v0.8)", () => {
 		await stopExecution(makeCtx(workdir), "teardown");
 	});
 });
+
+describe("findings-driven fix loop (v0.9)", () => {
+	const finding = (id: string, severity: "high" | "medium" | "low", taskIds: string[], extra: Partial<{ note: string; proposedTask: string }> = {}) => ({
+		id, severity, taskIds, note: extra.note ?? `${id} note`, evidence: "src/lib", raw: `- \` ${id}\` raw`,
+		...(extra.proposedTask ? { proposedTask: extra.proposedTask } : {}),
+	});
+
+	it("all VCs pass but a mapped high finding blocks completion: rollback + exactly one wake + NOT done", async () => {
+		const { workdir, planPath, runId } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "ok but findings", findings: [finding("F-001", "high", ["Task-2"])] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		assert.ok(ex, "high findings never complete the run (liveness)");
+		assert.equal(loadCheckpoint(workdir, runId).checkpoint.phase, "executing");
+		assert.equal(getRun(workdir, runId)?.status, "executing", "back to executing for the fix round");
+		assert.equal(ex.tasks.find((t) => t.id === "Task-2")?.status, "pending", "the high finding's mapped task rolled back");
+		const wakes = ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed");
+		assert.equal(wakes.length, 1, "exactly one wake");
+		assert.match(String(wakes[0].content), /1 high-severity finding/);
+		assert.match(String(wakes[0].content), /F-001/);
+		assert.match(String(wakes[0].content), /Full round report: /, "the wake references the round report path");
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+
+	it("keep-done asymmetry: a pure-high rollback keeps earlier VC passes; a VC-fail rollback invalidates", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		// Round 1: VC-001 passes, VC-002 passes, but F-001 (high) maps to Task-1 —
+		// which VC-001 covers. The high rollback must NOT clear VC-001's done.
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [finding("F-001", "high", ["Task-1"])] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		assert.equal(ex.items.find((i) => i.id === "VC-001")?.done, true, "pure-high rollback keeps the earlier pass");
+		assert.equal(ex.tasks.find((t) => t.id === "Task-1")?.status, "pending", "mapped task reopened");
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+
+		// Contrast: a VC-fail rollback invalidates checks covering the reopened task.
+		const second = freshWorkdir();
+		const ctx2 = await startTerminal(second.planPath, second.workdir);
+		const ctl2 = controlledRunner();
+		__setAuditRunnerForTests(ctl2.runner);
+		const restoring2 = restoreFromSession(ctx2, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl2.resolveRound({ round: 1, passed: ["VC-001"], failed: ["VC-002"], undeterminable: [], report: "r1" });
+		await restoring2;
+		await __awaitReviewRoundForTests();
+		const ex2 = getExecution()!;
+		assert.equal(ex2.items.find((i) => i.id === "VC-001")?.done, true, "unrelated pass kept");
+		assert.equal(ex2.tasks.find((t) => t.id === "Task-2")?.status, "pending", "failed check's task rolled back");
+		await stopExecution(ctx2, "teardown");
+		ctl2.drainAll();
+	});
+
+	it("undeterminable round carrying a high finding still wakes (high wins over self-schedule)", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: [], failed: [], undeterminable: ["VC-001", "VC-002"], report: "unreadable", findings: [finding("F-001", "high", ["Task-1"])] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const wakes = ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed");
+		assert.equal(wakes.length, 1, "the high branch wakes despite all-undeterminable verdicts");
+		const ex = getExecution()!;
+		assert.equal(ex.tasks.find((t) => t.id === "Task-1")?.status, "pending", "mapped task reopened");
+		assert.deepEqual(ex.audit.undeterminable, ["VC-001", "VC-002"], "undeterminable set still recorded");
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+
+	it("an unmapped high appends a plan task (proposed-task applied mechanically) and wakes once", async () => {
+		const { workdir, planPath, runId } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [finding("F-009", "high", [], { proposedTask: "harden the retry budget guard" })] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		const amended = ex.tasks.find((t) => t.id === "Task-3");
+		assert.ok(amended, "the unmapped high gained an appended task");
+		assert.equal(amended.status, "pending");
+		assert.match(amended.title, /fix F-009: harden the retry budget guard/);
+		assert.match(amended.title, /appended by execution review round 1/);
+		const planText = fs.readFileSync(planPath, "utf8");
+		assert.match(planText, /- `Task-3`: fix F-009: harden the retry budget guard/, "the plan file carries the appended bullet");
+		assert.match(planText, /## Verification Checks/, "the plan stays parseable (section intact)");
+		const cp = loadCheckpoint(workdir, runId).checkpoint;
+		assert.ok(cp.execution?.tasks?.["Task-3"], "checkpoint carries the appended task");
+		const wakes = ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed");
+		assert.equal(wakes.length, 1);
+		assert.match(String(wakes[0].content), /Tasks appended to the plan for unmapped findings: Task-3/);
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+
+	it("completion with residual medium/low findings summarizes them in the completion message", async () => {
+		const { workdir, planPath, runId } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "clean", findings: [finding("F-002", "medium", []), finding("F-003", "low", ["Task-1"])] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		assert.equal(getExecution(), null, "no high findings: the run completes");
+		assert.equal(loadCheckpoint(workdir, runId).checkpoint.phase, "completed");
+		const done = ctx.entries.filter((e) => e.customType === "pi-plans-complete");
+		assert.equal(done.length, 1);
+		assert.match(String(done[0].content), /Recorded findings that did not block completion: F-002 \(medium\), F-003 \(low\)/);
+		ctl.drainAll();
+	});
+
+	it("findings persist across the session snapshot and survive the fresh-budget renewal", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001"], failed: [], undeterminable: ["VC-002"], report: "r1", findings: [finding("F-001", "high", ["Task-2"])] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		assert.equal(ex.audit.findings.length, 1, "findings in live state");
+		// The snapshot round-trip: a session restore rebuilds them.
+		const restored = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		await restored;
+		assert.deepEqual(getExecution()!.audit.findings.map((f: { id: string }) => f.id), ["F-001"], "findings survive the session restore");
+		// Renewal: /plans-execute grants a fresh budget and keeps the findings.
+		const { resumeActiveExecution } = await import("../src/exec.ts");
+		// Drive rounds 2-5 through the real path: fix, re-close, settle (restore
+		// is the settle entry in these tests) — the same high persists each time.
+		for (let r = 2; r <= 5; r++) {
+			for (const id of ["Task-1", "Task-2"]) {
+				applyTaskUpdate(getExecution()!.tasks, id, "complete", `fix round ${r}`);
+			}
+			persistTaskProgress(ctx);
+			const settle = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+			await tick();
+			ctl.resolveRound({ round: r, passed: [], failed: [], undeterminable: [], report: `r${r}`, findings: [finding("F-001", "high", ["Task-2"])] } as never);
+			await settle;
+			await __awaitReviewRoundForTests();
+		}
+		// Round 5 committed with the high: the next terminal cycle hits the cap.
+		for (const id of ["Task-1", "Task-2"]) {
+			applyTaskUpdate(getExecution()!.tasks, id, "complete", "post-cap close");
+		}
+		persistTaskProgress(ctx);
+		await restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		const paused = getExecution()!;
+		assert.equal(paused.stall.paused, true, "the cap pause fired");
+		assert.match(String(paused.stall.pausedReason), /high findings: F-001/, "the pause reason names the high findings");
+		assert.match(String(paused.stall.pausedReason), /execution review exhausted 5 rounds/, "the pause prefix phrase survives");
+		// Cancelled rounds burn no budget and loop nowhere — safe to leave the
+		// runner in this mode while checking the renewal semantics.
+		__setAuditRunnerForTests(async () => ({ cancelled: true }) as never);
+		assert.ok(resumeActiveExecution(ctx), "renewal lifts the pause");
+		assert.equal(getExecution()!.audit.rounds, 0, "fresh budget");
+		assert.deepEqual(getExecution()!.audit.findings.map((f: { id: string }) => f.id), ["F-001"], "stable ids carry into the fresh budget");
+		ctl.drainAll();
+		await stopExecution(ctx, "teardown");
+	});
+});
+
+describe("mixed and hygiene rounds (v0.9.1 F-004/F-006/F-007/F-012)", () => {
+	it("a round with a failed check AND a high finding rolls back the union once and wakes exactly once (F-007)", async () => {
+		const { workdir, planPath, runId } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		// VC-001 fails (covers Task-1) and F-001 also maps to Task-1: the union
+		// must dedupe to one reopen of Task-1 plus Task-2 (VC-002 stays passed).
+		ctl.resolveRound({ round: 1, passed: ["VC-002"], failed: ["VC-001"], undeterminable: [], report: "mixed", findings: [{ id: "F-001", severity: "high", taskIds: ["Task-1"], note: "n", evidence: "e", raw: "r" }] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		assert.equal(ex.tasks.find((t) => t.id === "Task-1")?.status, "pending", "Task-1 reopened once by both channels");
+		assert.equal(ex.tasks.find((t) => t.id === "Task-2")?.status, "complete", "the passing check's task stays closed");
+		assert.equal(ex.items.find((i) => i.id === "VC-002")?.done, true, "unrelated pass kept");
+		const wakes = ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed");
+		assert.equal(wakes.length, 1, "one wake for the mixed round");
+		assert.match(String(wakes[0].content), /and failed checks: VC-001/);
+		assert.equal(loadCheckpoint(workdir, runId).checkpoint.phase, "executing");
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+
+	it("a pure VC-fail round keeps the v0.8 lead — never '0 high-severity findings' (F-004)", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001"], failed: ["VC-002"], undeterminable: [], report: "vc2 broken" });
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const wake = ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed");
+		assert.equal(wake.length, 1);
+		assert.doesNotMatch(String(wake[0].content), /0 high-severity finding/);
+		assert.doesNotMatch(String(wake[0].content), /High findings:\n\(none/);
+		assert.match(String(wake[0].content), /round 1 failed\*\* — checks: VC-002/);
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+
+	it("the appended bullet carries its wave tail and sanitizes reviewer text (F-006/F-012)", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [{ id: "F-009", severity: "high", taskIds: [], proposedTask: "harden — the retry; budget guard", note: "n", evidence: "e", raw: "r" }] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		const appended = ex.tasks.find((t) => t.id === "Task-3");
+		assert.ok(appended, "task appended");
+		const planText = fs.readFileSync(planPath, "utf8");
+		const bullet = planText.split("\n").find((l) => l.startsWith("- `Task-3`:"))!;
+		assert.match(bullet, /— wave: \d+$/, "the bullet carries the wave tail");
+		// Re-parse restores the same wave the live tree assigned (not wave 1).
+		const reparse = (await import("../src/plan.ts")).parsePlanTasks(planText);
+		const flat = reparse.tasks.flatMap(function walk(t: { children: unknown[] }) { return [t, ...t.children]; } as never) as never[];
+		const reparsed = flat.find((t: { id: string }) => t.id === "Task-3") as { wave: number; title: string; files: string[] };
+		assert.equal(reparsed.wave, appended.wave, "re-parse restores the live wave");
+		// Sanitized: em dash -> hyphen, ';' -> ',', no forged fields.
+		assert.ok(!/—|—/.test(reparsed.title.split("(appended")[0]), "em dashes sanitized out of the reviewer text");
+		assert.equal(reparsed.files.length, 0, "no fields forged from reviewer text");
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+});
+
+describe("no-report rounds preserve findings (v0.9.1 F-001)", () => {
+	const finding = (id: string) => ({ id, severity: "high" as const, taskIds: ["Task-2"], note: `${id} note`, evidence: "e", raw: "r" });
+
+	it("a spawn-failure round never vacuously completes a run with an unresolved high", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		// Round 1: both VCs pass, one mapped high -> rollback + wake.
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [finding("F-001")] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const wakesAfterR1 = ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed").length;
+		// The executor fixes and re-closes; the settle starts round 2.
+		for (const id of ["Task-1", "Task-2"]) applyTaskUpdate(getExecution()!.tasks, id, "complete", "fixed");
+		persistTaskProgress(ctx);
+		const settle = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		// Round 2's subagent FAILS (null outcome): findings must be preserved,
+		// no completion, no second wake — the loop self-schedules. The inline
+		// settle chain stays pending through the self-scheduled round 3, so
+		// resolve round 3 BEFORE awaiting the settle.
+		ctl.resolveRound(null);
+		await tick();
+		const ex = getExecution()!;
+		assert.ok(ex, "a spawn-failure round never completes the run");
+		assert.deepEqual(ex.audit.findings.map((f: { id: string }) => f.id), ["F-001"], "unresolved findings survive the no-report round");
+		assert.equal(ctx.entries.filter((e) => e.customType === "pi-plans-audit-failed").length, wakesAfterR1, "no extra wake on the no-report round");
+		// Round 3 spawned (self-schedule) and reports the fix — now it completes.
+		ctl.resolveRound({ round: 3, passed: [], failed: [], undeterminable: [], report: "fixed", findings: [] } as never);
+		await settle;
+		await __awaitReviewRoundForTests();
+		assert.equal(getExecution(), null, "a clean re-report completes");
+		ctl.drainAll();
+	});
+
+	it("the two-consecutive-discard synthesis preserves findings instead of clearing them", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [finding("F-001")] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const engine = path.join(workdir, "lib", "engine.js");
+		const discard = () => {
+			fs.writeFileSync(engine, `export const engine = ${Math.random()};\n`, "utf8");
+			const later = new Date(Date.now() + 60_000);
+			fs.utimesSync(engine, later, later);
+		};
+		// Re-close, settle, then two fingerprint discards -> the synthesized
+		// commit must carry the previous findings forward, not wipe them.
+		for (const id of ["Task-1", "Task-2"]) applyTaskUpdate(getExecution()!.tasks, id, "complete", "fixed");
+		persistTaskProgress(ctx);
+		const settle = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		discard();
+		ctl.resolveRound({ round: 2, passed: [], failed: [], undeterminable: ["VC-001", "VC-002"], report: "stale", findings: [finding("F-001")] } as never);
+		await tick();
+		discard();
+		ctl.resolveRound({ round: 2, passed: [], failed: [], undeterminable: ["VC-001", "VC-002"], report: "stale", findings: [finding("F-001")] } as never);
+		await tick();
+		await tick();
+		const ex = getExecution()!;
+		assert.ok(ex, "the synthesis never completes the run");
+		assert.equal(ex.audit.rounds, 2, "the synthesis committed as round 2");
+		assert.deepEqual(ex.audit.findings.map((f: { id: string }) => f.id), ["F-001"], "findings preserved through the discard synthesis");
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+		await settle;
+		await __awaitReviewRoundForTests();
+	});
+});
+
+describe("plan amendment re-stamps the checkpoint identity (v0.9.1 F-002)", () => {
+	it("an amended plan passes /resume-plans instead of plan-mismatch", async () => {
+		const { workdir, planPath, runId } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [{ id: "F-009", severity: "high", taskIds: [], proposedTask: "harden the guard", note: "n", evidence: "e", raw: "r" }] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const ex = getExecution()!;
+		assert.ok(ex.tasks.find((t) => t.id === "Task-3"), "the amendment appended Task-3");
+		// The checkpoint identity now matches the AMENDED file, with provenance.
+		const cp = loadCheckpoint(workdir, runId).checkpoint;
+		const { sha256File } = await import("../src/workflow-state.ts");
+		assert.equal(cp.plan?.sha256, sha256File(planPath), "identity re-stamped to the amended digest");
+		assert.equal(cp.execution?.planAmended?.round, 1);
+		assert.equal(cp.execution?.planAmended?.sha256, sha256File(planPath));
+		// A later resume accepts the amended plan (no plan-mismatch re-approval).
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+		const { loadExecutionFromCheckpoint } = await import("../src/exec.ts");
+		const result = loadExecutionFromCheckpoint(makeCtx(workdir), runId);
+		assert.equal(result.status, "loaded", `resume accepts the amended plan (${result.status})`);
+		assert.deepEqual(result.findings?.map((f) => f.id), ["F-009"], "the load result surfaces unresolved findings for the resume brief (F-005)");
+		await stopExecution(makeCtx(workdir), "post-check teardown");
+	});
+});
+
+describe("executor injection with findings (v0.9)", () => {
+	it("executionContextMessage lists unresolved high findings for the repairing agent", async () => {
+		const { workdir, planPath } = freshWorkdir();
+		const ctx = await startTerminal(planPath, workdir);
+		const ctl = controlledRunner();
+		__setAuditRunnerForTests(ctl.runner);
+		const restoring = restoreFromSession(ctx, [{ type: "custom", customType: "pi-plans-exec", data: getExecution() }]);
+		await tick();
+		ctl.resolveRound({ round: 1, passed: ["VC-001", "VC-002"], failed: [], undeterminable: [], report: "r1", findings: [{ id: "F-001", severity: "high", taskIds: ["Task-2"], note: "loop misses union", evidence: "e", raw: "r" }] } as never);
+		await restoring;
+		await __awaitReviewRoundForTests();
+		const { executionContextMessage } = await import("../src/exec.ts");
+		const msg = executionContextMessage(ctx) ?? "";
+		assert.match(msg, /unresolved high-severity findings/);
+		assert.match(msg, /- F-001 \(Task-2\): loop misses union/);
+		assert.match(msg, /Fix them, then re-close the affected tasks/);
+		await stopExecution(ctx, "teardown");
+		ctl.drainAll();
+	});
+});

package/tests/refine-ui.test.ts

@@ -331,12 +331,12 @@ describe("refine overlay wiring", () => {
 	it("threads the chrome language through both overlay construction sites (issue #3, VC-007)", () => {
 		const refineSource = fs.readFileSync(path.join(process.cwd(), "tools", "refine.ts"), "utf8");
 		assert.match(refineSource, /const overlayLang = uiLanguageFromTag\(config\.language\.tag\)/);
-		assert.match(refineSource, /new RefineOverlayController\("reviewer", lanes, relayAbort, lang\)/);
+		assert.match(refineSource, /new RefineOverlayController\(\s*"reviewer",\s*lanes,\s*relayAbort,\s*lang,/);
 		assert.match(refineSource, /modelLabel,\s*\n\s*overlayLang,/);
 		const refsSource = fs.readFileSync(path.join(process.cwd(), "tools", "analyze-refs.ts"), "utf8");
 		assert.match(
 			refsSource,
-			/new RefineOverlayController\("refs", batch\.map\(\(job\) => \(\{ id: job\.laneId, label: job\.laneId \}\)\), relayAbort, resolveUiLanguage\(workdir\)\)/,
+			/new RefineOverlayController\(\s*"refs",\s*batch\.map\(\(job\) => \(\{ id: job\.laneId, label: job\.laneId \}\)\),\s*relayAbort,\s*resolveUiLanguage\(workdir\),/,
 		);
 	});
 });
@@ -533,4 +533,27 @@ describe("refine overlay kitty and fallback key handling (issue #2)", () => {
 			__clearPiTuiForTests();
 		}
 	});
+
+	it("forwards unhandled keys instead of swallowing them (Ctrl+Shift+T while focused)", () => {
+		// pi-tui routes input ONLY to the focused component (no bubbling), so
+		// an open overlay used to swallow every global shortcut. Unhandled keys
+		// must reach the onUnhandledKey hook so callers can re-dispatch them.
+		const calls: string[] = [];
+		const component = new RefineOverlayComponent(
+			fakeTheme,
+			"auditor",
+			[readyLane("lane-1", "reviewer-1", "output")],
+			() => {},
+			undefined,
+			undefined,
+			"en",
+			(data) => calls.push(data),
+		);
+		// kitty CSI-u form of Ctrl+Shift+T — not an overlay key.
+		component.handleInput("\x1b[84;6u");
+		assert.deepEqual(calls, ["\x1b[84;6u"], "unhandled keys are forwarded");
+		// Handled keys (arrow down) are NOT forwarded.
+		component.handleInput("\x1b[B");
+		assert.deepEqual(calls, ["\x1b[84;6u"], "handled keys stay internal");
+	});
 });

package/tests/workflow-state.test.ts

@@ -482,4 +482,44 @@ describe("blocking budget persistence", () => {
 		const loaded = loadCheckpoint(workdir, runId);
 		assert.equal(loaded.status, "corrupt", "the closed schema is still enforced");
 	});
+	// v0.9: findings ride the same audit slot — same persistence rules.
+
+	it("round-trips findings through the checkpoint validator", () => {
+		const { workdir, runId } = setupRun("findings-roundtrip");
+		const cp = applyExecutionProgress(executingCheckpoint(workdir, runId), {
+			audit: {
+				rounds: 2,
+				lastResult: "highs: F-001",
+				findings: [
+					{ id: "F-001", severity: "high", taskIds: ["Task-2"], note: "broken", evidence: "src/b.ts", raw: "raw line" },
+					{ id: "F-002", severity: "medium", taskIds: [], proposedTask: "tidy", note: "polish", evidence: "e", raw: "r" },
+				],
+			},
+		});
+		mutateCheckpoint(workdir, runId, () => cp);
+		const loaded = loadCheckpoint(workdir, runId);
+		assert.ok(loaded.status === "ok");
+		assert.deepEqual(loaded.checkpoint.execution?.audit?.findings, [
+			{ id: "F-001", severity: "high", taskIds: ["Task-2"], note: "broken", evidence: "src/b.ts", raw: "raw line" },
+			{ id: "F-002", severity: "medium", taskIds: [], proposedTask: "tidy", note: "polish", evidence: "e", raw: "r" },
+		]);
+	});
+
+	it("loads a checkpoint written before findings existed (absent, not corrupt)", () => {
+		const { workdir, runId } = setupRun("findings-legacy");
+		const cp = applyExecutionProgress(executingCheckpoint(workdir, runId), { audit: { rounds: 1, lastResult: "VC-001" } });
+		mutateCheckpoint(workdir, runId, () => cp);
+		const loaded = loadCheckpoint(workdir, runId);
+		assert.ok(loaded.status === "ok", "legacy checkpoint still loads");
+		assert.equal(loaded.checkpoint.execution?.audit?.findings, undefined);
+	});
+
+	it("rejects unknown keys inside a findings record", () => {
+		const { workdir, runId } = setupRun("findings-bad-record");
+		const cp = applyExecutionProgress(executingCheckpoint(workdir, runId), {
+			audit: { rounds: 1, findings: [{ id: "F-001", severity: "high", taskIds: [], note: "n", evidence: "e", raw: "r", bogus: true } as never] },
+		});
+		// Validation runs at write: a malformed findings record never lands.
+		assert.throws(() => mutateCheckpoint(workdir, runId, () => cp), /findings\.0: unexpected key/);
+	});
 });

package/tools/analyze-refs.ts

@@ -15,7 +15,6 @@
 
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { truncateHead } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import * as fs from "node:fs";
@@ -37,6 +36,8 @@ import { resolveActiveRun } from "../src/run-context.ts";
 import { buildRefAnalystTask, type RefAnalystTaskInput } from "../src/refine-prompts.ts";
 import { runPiSubagent, stripFrontmatter } from "../src/subagent.ts";
 import { RefineOverlayController, refineOverlayContext } from "../src/refine-ui.ts";
+import { matchesTerminalKey } from "../src/terminal-keys.ts";
+import { toggleDashboardExpanded } from "../src/exec.ts";
 import { resolveUiLanguage } from "../src/ui-language.ts";
 
 const BATCH_SIZE = 3;
@@ -80,7 +81,7 @@ async function ensureRefAnalystModelReady(
 ): Promise<{ mode: string; model_selector: string | null; thinking_level: string | null; confirmed_at: string | null; name_prefix: string }> {
 	if (role.confirmed_at !== null && role.model_selector !== null) return role as never;
 	let outcome = await runFirstUseFlow(host, role.thinking_level);
-	if (outcome.status === "confirmed" && outcome.model_selector !== null && availableModels(host).length > 0 && findModel(host, outcome.model_selector) === null) {
+	if (outcome.status === "confirmed" && availableModels(host).length > 0 && findModel(host, outcome.modelSelector) === null) {
 		// F-008: a manually entered selector that the registry does not know —
 		// one re-pick, then let spawn-side errors surface precisely.
 		outcome = await runFirstUseFlow(host, outcome.role.thinking_level);
@@ -226,7 +227,16 @@ export function registerAnalyzeRefsTool(ext: ExtensionAPI, baseDir: string): voi
 
 				const overlay =
 					ctx.mode === "tui"
-						? new RefineOverlayController("refs", batch.map((job) => ({ id: job.laneId, label: job.laneId })), relayAbort, resolveUiLanguage(workdir))
+						? new RefineOverlayController(
+							"refs",
+							batch.map((job) => ({ id: job.laneId, label: job.laneId })),
+							relayAbort,
+							resolveUiLanguage(workdir),
+							// Forward the dashboard toggle (no key bubbling in pi-tui).
+							(data) => {
+								if (matchesTerminalKey(data, "ctrl+shift+t")) toggleDashboardExpanded(ctx);
+							},
+						)
 						: undefined;
 				overlay?.open(refineOverlayContext(ctx), modelLabel);
 				try {
@@ -264,9 +274,10 @@ export function registerAnalyzeRefsTool(ext: ExtensionAPI, baseDir: string): voi
 			}
 
 			const combined = sections.join("\n\n---\n\n");
-			const truncation = truncateHead(combined, { maxLines: 2000, maxBytes: 50 * 1024 });
-			let text = truncation.content;
-			if (truncation.truncated) text += `\n\n[Output truncated; full outputs remain in this tool result's details.]`;
+			// v0.8.1: no head-truncation — the full combined analysis flows into the
+		// tool result (and REF_ANALYSIS.md) verbatim; the previous 2000-line/
+		// 50KB cap silently dropped the tail of large reference analyses.
+			const text = combined;
 
 			return {
 				content: [

package/tools/refine.ts

@@ -44,6 +44,8 @@ import { buildReviewerTask, reviewerLanes } from "../src/refine-prompts.ts";
 import { graphBlockForRefiner } from "../src/code-graph/prompts.ts";
 import { runPiSubagent, stripFrontmatter } from "../src/subagent.ts";
 import { RefineOverlayController, refineOverlayContext } from "../src/refine-ui.ts";
+import { matchesTerminalKey } from "../src/terminal-keys.ts";
+import { toggleDashboardExpanded } from "../src/exec.ts";
 
 
 const RefineParams = Type.Object({
@@ -90,10 +92,15 @@ async function ensureReviewerReady(
 ): Promise<{ mode: string; model_selector: string | null; thinking_level: string | null; confirmed_at: string | null; name_prefix: string }> {
 	if (role.mode === "current-session" || reviewerReady(role as never)) return role as never;
 	let outcome: FirstUseOutcome = await runFirstUseFlow(host, role.thinking_level);
-	if (outcome.status === "confirmed" && outcome.model_selector !== null) {
+	if (outcome.status === "confirmed") {
 		// F-008: validate the freshly chosen selector against the registry when
 		// one is present, so a typo'd manual entry fails here, not at spawn.
-		if (availableModels(host).length > 0 && findModel(host, outcome.model_selector) === null) {
+		// (v0.8.1 field-drift fix: the outcome's top-level field is camelCase
+		// `modelSelector` — reading snake_case `model_selector` yielded
+		// undefined, passed the old `!== null` guard, and crashed findModel
+		// with "Cannot read properties of undefined (reading 'indexOf')"
+		// right after the first-use panel confirmed.)
+		if (availableModels(host).length > 0 && findModel(host, outcome.modelSelector) === null) {
 			outcome = await runFirstUseFlow(host, outcome.role.thinking_level);
 		}
 	}
@@ -117,7 +124,19 @@ function setupRefinementExecution(
 	if (parentSignal?.aborted) controller.abort();
 	else parentSignal?.addEventListener("abort", relayAbort, { once: true });
 
-	const overlay = ctx.mode === "tui" ? new RefineOverlayController("reviewer", lanes, relayAbort, lang) : undefined;
+	const overlay = ctx.mode === "tui"
+		? new RefineOverlayController(
+			"reviewer",
+			lanes,
+			relayAbort,
+			lang,
+			// pi-tui has no key bubbling: forward the dashboard toggle so
+			// Ctrl+Shift+T keeps working while the refine overlay holds focus.
+			(data) => {
+				if (matchesTerminalKey(data, "ctrl+shift+t")) toggleDashboardExpanded(ctx);
+			},
+		)
+		: undefined;
 	overlay?.open(refineOverlayContext(ctx), modelLabel);
 
 	return {