ultimate-pi 0.13.1 → 0.14.0

package/.pi/extensions/lib/plan-approval/dialog.ts

@@ -1,291 +1,52 @@
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import { formatPlanPacketLines } from "./format-plan.js";
+import { runAskDialog } from "../ask-user/dialog.js";
+import { runAskFallback } from "../ask-user/fallback.js";
+import type { ValidatedAskParams } from "../ask-user/types.js";
+import { formatPlanPacketMarkdown } from "./plan-review.js";
 import type {
 	PlanApprovalDialogResult,
 	ValidatedApprovePlanParams,
 } from "./types.js";
 
-type FocusRegion = "plan" | "options";
-
-interface CustomAnswer {
-	response: { kind: "selection"; selections: string[] };
-}
-
-/** Lines reserved below overlay: harness-live widget + editor + footer. */
-export const PLAN_APPROVAL_BOTTOM_RESERVE_LINES = 11;
-/** Estimate agents widget height when stacking above harness live. */
-export const PLAN_APPROVAL_AGENTS_TOP_RESERVE_LINES = 12;
-export const PLAN_APPROVAL_MIN_VIEWPORT = 6;
-
-export function computePlanViewport(
-	availableHeight: number,
-	chromeLines: number,
-): number {
-	return Math.max(PLAN_APPROVAL_MIN_VIEWPORT, availableHeight - chromeLines);
-}
-
-export function computePlanOverlayMaxHeight(termHeight: number): number {
-	return Math.max(
-		PLAN_APPROVAL_MIN_VIEWPORT + 8,
-		termHeight -
-			PLAN_APPROVAL_BOTTOM_RESERVE_LINES -
-			PLAN_APPROVAL_AGENTS_TOP_RESERVE_LINES,
-	);
-}
+export type RunPlanApprovalDialogOptions = {
+	onMounted?: () => void;
+	hasUI?: boolean;
+};
 
-function countPlanChromeLines(
+/** Full plan body shown in the transcript before the approval prompt. */
+export function buildPlanApprovalMarkdown(
 	validated: ValidatedApprovePlanParams,
-	displayOptions: ValidatedApprovePlanParams["options"],
-	useOverlay: boolean,
-): number {
-	let chrome = useOverlay ? 2 : 0; // borders
-	chrome += 1; // title
-	if (validated.human_summary) {
-		chrome += validated.human_summary.split("\n").length;
-	}
-	chrome += 1; // blank before plan
-	chrome += 1; // plan label
-	chrome += 1; // blank before options
-	chrome += 1; // options label
-	for (const opt of displayOptions) {
-		chrome += 1;
-		if (opt.description) chrome += 1;
-	}
-	chrome += 1; // blank before hints
-	chrome += 1; // hints
-	return chrome;
+): string {
+	return formatPlanPacketMarkdown(validated.plan_packet, {
+		human_summary: validated.human_summary,
+		status: "draft",
+		research_brief: validated.research_brief,
+	}).trim();
 }
 
-function withTimeout<T>(
-	promise: Promise<T | null>,
-	ms: number | undefined,
-): Promise<T | null> {
-	if (!ms) return promise;
-	return Promise.race([
-		promise,
-		new Promise<null>((resolve) => {
-			setTimeout(() => resolve(null), ms);
-		}),
-	]);
+function toAskParams(
+	validated: ValidatedApprovePlanParams,
+): ValidatedAskParams {
+	return {
+		question: "How would you like to proceed with this harness plan?",
+		context: buildPlanApprovalMarkdown(validated),
+		options: validated.options,
+		allowMultiple: false,
+		allowFreeform: false,
+		// Inline prompt below the plan — no full-screen overlay.
+		displayMode: "inline",
+	};
 }
 
-export type RunPlanApprovalDialogOptions = {
-	onMounted?: () => void;
-};
-
 export async function runPlanApprovalDialog(
 	ui: ExtensionUIContext,
 	validated: ValidatedApprovePlanParams,
 	options?: RunPlanApprovalDialogOptions,
 ): Promise<PlanApprovalDialogResult> {
-	const planLines = formatPlanPacketLines(validated.plan_packet, 100);
-	const displayOptions = validated.options;
-	const useOverlay = validated.displayMode !== "inline";
-	let overlayTermHeight = 24;
-
-	const result = await withTimeout(
-		ui.custom<CustomAnswer | null>(
-			(tui, theme, _kb, done) => {
-				const tuiHeight = (tui as unknown as { height?: number }).height;
-				overlayTermHeight =
-					typeof tuiHeight === "number" && tuiHeight > 10 ? tuiHeight : 24;
-				options?.onMounted?.();
-
-				let scrollOffset = 0;
-				let optionIndex = 0;
-				let focus: FocusRegion = "plan";
-				let cachedLines: string[] | undefined;
-
-				function refresh() {
-					cachedLines = undefined;
-					tui.requestRender();
-				}
-
-				function submitSelection() {
-					const opt = displayOptions[optionIndex];
-					done({
-						response: { kind: "selection", selections: [opt.title] },
-					});
-				}
-
-				function handleInput(data: string) {
-					if (focus === "plan") {
-						if (matchesKey(data, Key.up) || data === "k") {
-							scrollOffset = Math.max(0, scrollOffset - 1);
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.down) || data === "j") {
-							scrollOffset += 1;
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.pageUp)) {
-							scrollOffset = Math.max(0, scrollOffset - 8);
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.pageDown)) {
-							scrollOffset += 8;
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.tab)) {
-							focus = "options";
-							refresh();
-							return;
-						}
-					}
-
-					if (focus === "options") {
-						if (matchesKey(data, Key.up)) {
-							optionIndex = Math.max(0, optionIndex - 1);
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.down)) {
-							optionIndex = Math.min(
-								displayOptions.length - 1,
-								optionIndex + 1,
-							);
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.tab)) {
-							focus = "plan";
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.enter)) {
-							submitSelection();
-							return;
-						}
-					}
-
-					if (matchesKey(data, Key.escape)) {
-						done(null);
-					}
-				}
-
-				function render(width: number): string[] {
-					if (cachedLines) return cachedLines;
-
-					const lines: string[] = [];
-					const add = (s: string) => lines.push(truncateToWidth(s, width));
-					const dims = (tui as { height?: number }).height;
-					const termHeight = typeof dims === "number" && dims > 10 ? dims : 24;
-					const chromeLines = countPlanChromeLines(
-						validated,
-						displayOptions,
-						useOverlay,
-					);
-
-					let availableHeight: number;
-					if (useOverlay) {
-						const overlayMax = computePlanOverlayMaxHeight(termHeight);
-						availableHeight = overlayMax;
-					} else {
-						availableHeight = termHeight - PLAN_APPROVAL_BOTTOM_RESERVE_LINES;
-					}
-					const planViewport = computePlanViewport(
-						availableHeight,
-						chromeLines,
-					);
-
-					if (useOverlay) {
-						add(theme.fg("accent", "─".repeat(width)));
-					}
-
-					add(theme.fg("accent", " Plan approval"));
-					if (validated.human_summary) {
-						for (const line of validated.human_summary.split("\n")) {
-							add(theme.fg("muted", ` ${line}`));
-						}
-					}
-					lines.push("");
-
-					const maxScroll = Math.max(0, planLines.length - planViewport);
-					scrollOffset = Math.min(scrollOffset, maxScroll);
-					const visible = planLines.slice(
-						scrollOffset,
-						scrollOffset + planViewport,
-					);
-					const planLabel =
-						focus === "plan"
-							? theme.fg("accent", " [plan — ↑↓/Pg scroll, Tab → options]")
-							: theme.fg("dim", " [plan]");
-					add(planLabel);
-					for (const line of visible) {
-						add(theme.fg("text", ` ${line}`));
-					}
-					if (planLines.length > planViewport) {
-						add(
-							theme.fg(
-								"dim",
-								` … ${scrollOffset + 1}-${scrollOffset + visible.length} of ${planLines.length}`,
-							),
-						);
-					}
-					lines.push("");
-
-					const optLabel =
-						focus === "options"
-							? theme.fg("accent", " Options (↑↓, Enter, Tab → plan):")
-							: theme.fg("dim", " Options (Tab to focus):");
-					add(optLabel);
-					for (let i = 0; i < displayOptions.length; i++) {
-						const opt = displayOptions[i];
-						const focused = focus === "options" && i === optionIndex;
-						const prefix = focused ? theme.fg("accent", "> ") : "  ";
-						const num = `${i + 1}. `;
-						if (focused) {
-							add(prefix + theme.fg("accent", `${num}${opt.title}`));
-						} else {
-							add(`${prefix}${theme.fg("text", `${num}${opt.title}`)}`);
-						}
-						if (opt.description) {
-							add(`     ${theme.fg("muted", opt.description)}`);
-						}
-					}
-
-					lines.push("");
-					add(theme.fg("dim", " Tab: plan ↔ options • Esc: cancel"));
-
-					if (useOverlay) {
-						add(theme.fg("accent", "─".repeat(width)));
-					}
-
-					cachedLines = lines;
-					return lines;
-				}
-
-				return {
-					render,
-					invalidate: () => {
-						cachedLines = undefined;
-					},
-					handleInput,
-				};
-			},
-			useOverlay
-				? {
-						overlay: true,
-						overlayOptions: () => ({
-							anchor: "bottom-center",
-							width: "100%",
-							margin: { bottom: PLAN_APPROVAL_BOTTOM_RESERVE_LINES },
-							maxHeight: computePlanOverlayMaxHeight(overlayTermHeight),
-						}),
-					}
-				: undefined,
-		),
-		undefined,
-	);
-
-	if (!result) {
-		return { response: null, cancelled: true };
+	options?.onMounted?.();
+	const askParams = toAskParams(validated);
+	if (options?.hasUI === false) {
+		return runAskFallback(ui, askParams);
 	}
-
-	return { response: result.response, cancelled: false };
+	return runAskDialog(ui, askParams);
 }

package/.pi/extensions/lib/plan-approval/format-plan.ts

@@ -1,94 +1,21 @@
 import type { PlanPacketLike } from "../../../lib/harness-run-context.js";
+import { stringifyYaml } from "../../../lib/harness-yaml.js";
 
-function wrapLine(text: string, width: number): string[] {
-	if (width < 20) return [text];
-	const words = text.split(/\s+/);
-	const lines: string[] = [];
-	let line = "";
-	for (const word of words) {
-		const next = line ? `${line} ${word}` : word;
-		if (next.length > width && line) {
-			lines.push(line);
-			line = word;
-		} else {
-			line = next;
-		}
-	}
-	if (line) lines.push(line);
-	return lines.length > 0 ? lines : [""];
-}
-
-function riskBadge(risk: string | undefined): string {
-	const r = (risk ?? "med").toLowerCase();
-	return `[risk: ${r}]`;
+/** Canonical YAML for plan_packet (same shape as plan-packet.yaml on disk). */
+export function formatPlanPacketYaml(packet: PlanPacketLike): string {
+	return stringifyYaml(packet).trimEnd();
 }
 
+/** Line array for TUI renderers; preserves YAML structure with optional per-line width cap. */
 export function formatPlanPacketLines(
 	packet: PlanPacketLike,
 	width: number,
 ): string[] {
-	const lines: string[] = [];
-	const w = Math.max(40, width - 2);
-	const add = (s: string) => {
-		for (const part of wrapLine(s, w)) lines.push(part);
-	};
-
-	lines.push(`plan_id: ${packet.plan_id ?? "?"}`);
-	lines.push(`task_id: ${packet.task_id ?? "?"}`);
-	lines.push(
-		riskBadge(
-			typeof packet.risk_level === "string" ? packet.risk_level : undefined,
-		),
-	);
-	lines.push("");
-	lines.push("scope:");
-	add(String(packet.scope ?? ""));
-	lines.push("");
-
-	const assumptions = Array.isArray(packet.assumptions)
-		? (packet.assumptions as string[])
-		: [];
-	if (assumptions.length > 0) {
-		lines.push("assumptions:");
-		for (const a of assumptions) {
-			add(`  • ${a}`);
-		}
-		lines.push("");
-	}
-
-	const checks = Array.isArray(packet.acceptance_checks)
-		? (packet.acceptance_checks as string[])
-		: [];
-	if (checks.length > 0) {
-		lines.push("acceptance_checks:");
-		for (let i = 0; i < checks.length; i++) {
-			add(`  ${i + 1}. ${checks[i]}`);
-		}
-		lines.push("");
-	}
-
-	const rollback = packet.rollback_plan as
-		| {
-				rollback_artifacts?: {
-					revert_command?: string;
-					revert_branch?: string;
-					patch_bundle?: string;
-				};
-		  }
-		| undefined;
-	const artifacts = rollback?.rollback_artifacts;
-	if (artifacts) {
-		lines.push("rollback:");
-		if (artifacts.revert_command) {
-			add(`  revert_command: ${artifacts.revert_command}`);
-		}
-		if (artifacts.revert_branch) {
-			add(`  revert_branch: ${artifacts.revert_branch}`);
-		}
-		if (artifacts.patch_bundle) {
-			add(`  patch_bundle: ${artifacts.patch_bundle}`);
-		}
-	}
-
-	return lines;
+	const w = Math.max(40, width);
+	return formatPlanPacketYaml(packet)
+		.split("\n")
+		.map((line) => {
+			if (line.length <= w) return line;
+			return `${line.slice(0, w - 1)}…`;
+		});
 }

package/.pi/extensions/lib/plan-approval/plan-review.ts

@@ -6,7 +6,7 @@ import {
 	type HarnessRunContext,
 	type PlanPacketLike,
 } from "../../../lib/harness-run-context.js";
-import { formatPlanPacketLines } from "./format-plan.js";
+import { formatPlanPacketYaml } from "./format-plan.js";
 import type { PlanResearchBrief } from "./types.js";
 
 export {
@@ -217,7 +217,7 @@ export function formatPlanPacketMarkdown(
 		`- **risk_level:** ${typeof packet.risk_level === "string" ? packet.risk_level : "med"}`,
 	);
 	if (opts?.plan_packet_path) {
-		lines.push(`- **canonical JSON:** \`${opts.plan_packet_path}\``);
+		lines.push(`- **canonical YAML:** \`${opts.plan_packet_path}\``);
 	}
 	lines.push("");
 	if (opts?.human_summary?.trim()) {
@@ -233,15 +233,15 @@ export function formatPlanPacketMarkdown(
 	}
 	lines.push("## Plan packet");
 	lines.push("");
-	lines.push("```text");
-	for (const line of formatPlanPacketLines(packet, 100)) {
+	lines.push("```yaml");
+	for (const line of formatPlanPacketYaml(packet).split("\n")) {
 		lines.push(line);
 	}
 	lines.push("```");
 	lines.push("");
 	if (status === "draft") {
 		lines.push(
-			"Review this file in your editor, then return to the harness TUI to **Approve**, **Request changes**, or **Cancel**.",
+			"Review this plan, then choose **Approve**, **Request changes**, or **Cancel** in the prompt below (same flow as `ask_user`).",
 		);
 	} else if (status === "approved") {
 		lines.push(
@@ -388,6 +388,6 @@ export function formatPlanReviewUserHint(reviewPath: string | null): string {
 	const abs = resolve(reviewPath);
 	return (
 		`Full plan for editor review: ${abs}\n` +
-		`Open this markdown file in VS Code (or your editor), read the scope and acceptance checks, then return to the harness TUI to Approve / Request changes / Cancel.`
+		`Open this markdown file in your editor if you prefer; approval options appear in the harness prompt below.`
 	);
 }

package/.pi/extensions/lib/plan-approval/render.ts

@@ -61,10 +61,16 @@ export function renderHarnessPlanDraft(
 	details: {
 		plan_packet?: PlanPacketLike;
 		human_summary?: string | null;
+		plan_markdown?: string | null;
 	},
 	width: number,
 	theme: Theme,
+	content?: string | null,
 ): string[] {
+	const markdown = content?.trim() || details.plan_markdown?.trim();
+	if (markdown) {
+		return markdown.split("\n").map((line) => truncateToWidth(line, width));
+	}
 	const lines: string[] = [];
 	lines.push(theme.fg("accent", "Harness plan (pending approval)"));
 	if (details.human_summary) {

package/.pi/extensions/lib/plan-approval/validate.ts

@@ -36,7 +36,7 @@ export function validateApprovePlanParams(
 		human_summary: params.human_summary?.trim() || undefined,
 		research_brief: params.research_brief ?? undefined,
 		options,
-		displayMode: params.displayMode ?? "overlay",
+		displayMode: params.displayMode ?? "inline",
 	};
 }
 

package/.pi/extensions/lib/plan-debate-envelope.ts

@@ -51,6 +51,7 @@ export function buildPlanReviewRoundEnvelope(
 		token_usage: { per_agent: Record<string, number>; round_total: number };
 		consensus_delta: number;
 		severity_scores?: PlanReviewRoundDraft["severity_scores"];
+		review_gate_ready?: boolean;
 	};
 } {
 	const participants = (draft.participants ?? [
@@ -79,6 +80,7 @@ export function buildPlanReviewRoundEnvelope(
 			},
 			consensus_delta: draft.consensus_delta ?? 0,
 			severity_scores: draft.severity_scores,
+			review_gate_ready: draft.review_gate_ready,
 		},
 	};
 }

package/.pi/extensions/lib/plan-debate-gate.ts

@@ -0,0 +1,155 @@
+/**
+ * P0 — plan debate artifact + bus gates before approve_plan.
+ */
+
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { planDebateIdForRun } from "./plan-debate-id.js";
+import {
+	getMessengerRoundState,
+	loadMessengerState,
+	messengerRoundDebateReady,
+} from "./plan-messenger.js";
+
+const PLAN_ROUNDS = 4;
+const FOCUS_BY_ROUND = ["spec", "wbs", "schedule", "quality"] as const;
+
+function laneFilesForRound(roundIndex: number): string[] {
+	const n = roundIndex;
+	const lanes = [
+		`artifacts/validation-turn-r${n}.yaml`,
+		`artifacts/adversary-brief-r${n}.yaml`,
+	];
+	if (n === 1) {
+		lanes.unshift(`artifacts/hypothesis-validation-r${n}.yaml`);
+	}
+	if (n === 4) {
+		lanes.push(`artifacts/sprint-audit-r${n}.yaml`);
+	}
+	lanes.push(`artifacts/review-round-r${n}.yaml`);
+	return lanes;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function countJsonlKinds(
+	debateJsonlPath: string,
+): Promise<{ rounds: number; hasConsensus: boolean }> {
+	try {
+		const raw = await readFile(debateJsonlPath, "utf-8");
+		let rounds = 0;
+		let hasConsensus = false;
+		for (const line of raw.split("\n")) {
+			if (!line.trim()) continue;
+			const ev = JSON.parse(line) as { kind?: string };
+			if (ev.kind === "round") rounds += 1;
+			if (ev.kind === "consensus") hasConsensus = true;
+		}
+		return { rounds, hasConsensus };
+	} catch {
+		return { rounds: 0, hasConsensus: false };
+	}
+}
+
+export interface PlanDebateGateResult {
+	ok: boolean;
+	errors: string[];
+	warnings: string[];
+	debateId: string;
+}
+
+export async function validatePlanDebateGate(
+	projectRoot: string,
+	runId: string,
+): Promise<PlanDebateGateResult> {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const debateId = planDebateIdForRun(runId);
+	const runDir = join(projectRoot, ".pi", "harness", "runs", runId);
+	const debatesDir = join(projectRoot, ".pi", "harness", "debates");
+
+	for (let r = 1; r <= PLAN_ROUNDS; r++) {
+		for (const rel of laneFilesForRound(r)) {
+			const abs = join(runDir, rel);
+			if (!(await fileExists(abs))) {
+				errors.push(`missing ${rel}`);
+			}
+		}
+		const roundState = await getMessengerRoundState(runDir, r);
+		const messengerCheck = messengerRoundDebateReady(roundState, r === 4);
+		if (!messengerCheck.ok) {
+			for (const e of messengerCheck.errors) {
+				errors.push(`round ${r} messenger: ${e}`);
+			}
+		}
+	}
+
+	const messenger = await loadMessengerState(runDir);
+	if (!messenger) {
+		errors.push(
+			"debate-messenger/state.json missing — call harness_debate_open",
+		);
+	} else if (messenger.debate_id !== debateId) {
+		errors.push(`messenger debate_id ${messenger.debate_id} !== ${debateId}`);
+	}
+
+	const jsonlPath = join(debatesDir, `${debateId}.jsonl`);
+	const { rounds, hasConsensus } = await countJsonlKinds(jsonlPath);
+	if (rounds < PLAN_ROUNDS) {
+		errors.push(
+			`${debateId}.jsonl has ${rounds}/${PLAN_ROUNDS} round events — use harness_debate_submit_round each round`,
+		);
+	}
+	if (!hasConsensus) {
+		errors.push(
+			`missing consensus on ${debateId} — call harness_debate_consensus`,
+		);
+	}
+
+	const consensusPath = join(debatesDir, `${debateId}.consensus.json`);
+	if (!(await fileExists(consensusPath))) {
+		errors.push(`missing ${debateId}.consensus.json`);
+	} else {
+		try {
+			const raw = await readFile(consensusPath, "utf-8");
+			const packet = JSON.parse(raw) as { policy_decision?: string };
+			if (packet.policy_decision === "block") {
+				errors.push("consensus policy_decision is block — cannot approve");
+			}
+		} catch {
+			errors.push("invalid consensus json");
+		}
+	}
+
+	for (let r = 0; r < FOCUS_BY_ROUND.length; r++) {
+		const focus = FOCUS_BY_ROUND[r];
+		const reviewPath = join(runDir, `artifacts/review-round-r${r + 1}.yaml`);
+		if (await fileExists(reviewPath)) {
+			const raw = await readFile(reviewPath, "utf-8");
+			if (!raw.includes(focus)) {
+				warnings.push(`review-round-r${r + 1} may not match focus ${focus}`);
+			}
+		}
+	}
+
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings,
+		debateId,
+	};
+}
+
+export function isReviewRoundArtifactPath(relPath: string): boolean {
+	return /^artifacts\/review-round-r\d+\.yaml$/i.test(
+		relPath.replace(/\\/g, "/"),
+	);
+}