pi-plans 0.2.0 → 0.3.1

package/src/guard.ts

@@ -7,7 +7,7 @@
 
 import * as os from "node:os";
 import * as path from "node:path";
-import { getRun, readActive, resolveStateRootOrNull } from "./state.ts";
+import { getRun, loadConfig, readActive, resolveStateRootOrNull } from "./state.ts";
 
 const GUARDED_TOOLS = new Set(["write", "edit"]);
 const GUARDED_STATUSES = new Set(["planning", "accepted"]);
@@ -31,6 +31,19 @@ export function planningWriteBlockReason(input: GuardInput): string | null {
 	const allowedRoots = [stateRoot, active.artifact_dir, path.join(os.homedir(), ".cache", "pi-plans")].filter(
 		(root): root is string => root !== null,
 	);
+	// A configured refs root (plan-with-refs downloads) is writable while planning.
+	if (stateRoot !== null) {
+		try {
+			const config = loadConfig(stateRoot);
+			if (config.refs_root) {
+				allowedRoots.push(
+					path.isAbsolute(config.refs_root) ? config.refs_root : path.resolve(input.workdir, config.refs_root),
+				);
+			}
+		} catch {
+			/* config read failed: no extra root */
+		}
+	}
 	const allowed = allowedRoots.some((root) => target === root || target.startsWith(`${root}${path.sep}`));
 	if (allowed) return null;
 

package/src/refine-prompts.ts

@@ -30,6 +30,23 @@ Authority boundary: read-only analysis only. Do not edit, write, delete, commit,
 Evidence: inspect the repository with read, grep, find, and ls before judging the plan.${lensLine}${focusLine}${contextLine}`;
 }
 
+/** Shared header for the post-execution implementation review: the
+ * accepted plan is the contract, the IMPLEMENTATION in the worktree is
+ * under review. Findings must anchor to the plan's goals/acceptance
+ * criteria and explicitly assess delivery maturity. */
+function buildImplementationSharedHeader(role: "reviewer" | "criticizer", opts: RefinePromptInput): string {
+	const lensLine = role === "reviewer" && opts.lens ? `\nReview lens: ${opts.lens}.` : "";
+	const focusLine = opts.focus ? `\n\nSpecific concerns from the main agent: ${opts.focus}` : "";
+	const contextLine = opts.context ? `\n\nContext: ${opts.context}` : "";
+	return `Goal: ${role === "reviewer" ? "review the implemented result in the worktree against the plan" : "stress-test the implemented result's assumptions"}.
+
+Target: ${opts.planPath} (the accepted plan; the IMPLEMENTATION in the worktree is under review)
+
+Authority boundary: read-only analysis only. Do not edit, write, delete, commit, push, or spawn subagents.
+
+Evidence: inspect the repository with read, grep, find, and ls before judging the implementation. Judge the implementation against the plan's goals, verifier checklist, and acceptance criteria. Explicitly assess delivery maturity: did the executor ship a minimal MVP only, or refine for long-term growth (no stopgaps, long-term architectural decisions, missing tests, technical debt, production readiness)? Calibrate severity accordingly. Out-of-scope improvement ideas are low severity by default and must not be forced into findings.${lensLine}${focusLine}${contextLine}`;
+}
+
 export function reviewerLanes(count: number): ReviewerLane[] {
 	if (count === 3) return [...REVIEWER_LENSES];
 	if (count === 2) return [...REVIEWER_LENSES.slice(0, 2)];
@@ -68,3 +85,95 @@ Plan file: ${opts.planPath}
 ${opts.planText}
 ---8<--- END PLAN CONTENT ---8<---`;
 }
+
+export function buildImplementationReviewerTask(opts: RefinePromptInput): string {
+	return `${buildImplementationSharedHeader("reviewer", opts)}
+
+Success criteria: return evidence-backed findings or explicitly say the implementation holds up.
+
+Output: Markdown, highest severity first. For each finding use this shape:
+- \`F-###\` — severity: high | medium | low; affected plan IDs (e.g. R-001, I-003) or files; evidence: repo path/command that proves it; impact; recommended fix; suggested disposition (accept | reject | needs-discussion).
+
+Surface at most five high-priority findings; list lower-severity findings after them. If the implementation holds up, say so explicitly and list what you checked.
+
+Plan file: ${opts.planPath}
+
+---8<--- PLAN CONTENT ---8<---
+${opts.planText}
+---8<--- END PLAN CONTENT ---8<---`;
+}
+
+export interface RefAnalystTaskInput {
+	refId: string;
+	localPath: string;
+	title?: string;
+	url?: string;
+	kind?: string;
+	context?: string;
+	languageTag?: string | null;
+}
+
+const REF_ANALYST_SECTIONS = [
+	"Overview",
+	"Key Mechanisms And Design Tradeoffs",
+	"Adoptable Ideas For The Target Repo",
+	"Pitfalls And Anti-Patterns",
+	"Evidence Citations",
+	"Coverage",
+	"Evidence Gaps",
+] as const;
+
+export function refAnalystSections(): readonly string[] {
+	return REF_ANALYST_SECTIONS;
+}
+
+/** Task brief for the plan-with-refs per-reference analysis subagent. */
+export function buildRefAnalystTask(opts: RefAnalystTaskInput): string {
+	const titleLine = opts.title ? `\nTitle: ${opts.title}` : "";
+	const urlLine = opts.url ? `\nURL: ${opts.url}` : "";
+	const kindLine = opts.kind ? `\nKind: ${opts.kind}` : "";
+	const contextLine = opts.context ? `\n\nTarget repo context: ${opts.context}` : "";
+	const languageLine = opts.languageTag
+		? `\n\nWrite all prose in the language with BCP47 tag "${opts.languageTag}". Keep file paths, identifiers, and code snippets verbatim.`
+		: "";
+	const template = REF_ANALYST_SECTIONS.map((section) => `## ${section}`).join("\n\n(empty)\n\n");
+	return `Goal: deep-read this downloaded reference and extract what the target repository should adopt from it.
+
+Reference id: ${opts.refId}${titleLine}${urlLine}${kindLine}
+Local path (your working directory): ${opts.localPath}
+
+Authority boundary: read-only analysis only. Do not edit, write, delete, commit, push, or spawn subagents. Stay inside the reference directory.
+
+Evidence: inspect the reference with read, grep, find, and ls before judging it. Cite files as <relative-path>:<line> for every claim; quote only what you verified.${contextLine}${languageLine}
+
+Success criteria: a structured analysis the main agent can paste into REF_ANALYSIS.md and turn into adoption questions.
+
+Output: Markdown with exactly these seven top-level sections, in this order:
+
+${template}
+
+Section contracts:
+- Overview: what the reference is, its scope, maturity, and license (when discoverable).
+- Key Mechanisms And Design Tradeoffs: the mechanisms that make it work and the tradeoffs they embody.
+- Adoptable Ideas For The Target Repo: concrete, portable ideas ranked by expected value; name the target-repo surface each would touch.
+- Pitfalls And Anti-Patterns: what to avoid when borrowing; failure modes the reference itself documents or exhibits.
+- Evidence Citations: the file:line references backing the claims above.
+- Coverage: which parts of the reference you actually read versus skipped.
+- Evidence Gaps: what you could not determine from the reference alone.`;
+}
+
+export function buildImplementationCriticizerTask(opts: RefinePromptInput): string {
+	return `${buildImplementationSharedHeader("criticizer", opts)}
+
+Success criteria: return concrete, answerable questions only; never rewrite the plan or the implementation.
+
+Output: Markdown in exactly this shape:
+1. A summary of your core criticism in at most three sentences, highlighting the single most important point.
+2. Then at most five adaptive questions, numbered, each with one line of why it matters. Questions must be answerable by a user with repo access — never rhetorical. Stop earlier if the implementation genuinely holds.
+
+Plan file: ${opts.planPath}
+
+---8<--- PLAN CONTENT ---8<---
+${opts.planText}
+---8<--- END PLAN CONTENT ---8<---`;
+}

package/src/refine-ui-helpers.ts

@@ -9,8 +9,32 @@
 
 const ELLIPSIS = "…";
 
-export function visibleWidth(text: string): number {
-	if (!text) return 0;
+/**
+ * ECMA-48 CSI sequence: ESC [ parameter bytes (0x30-0x3F), intermediate bytes
+ * (0x20-0x2F), final byte (0x40-0x7E). Matched atomically so styling payloads
+ * never leak into width math and are never split mid-sequence.
+ */
+const CSI_PATTERN = /\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g;
+
+interface AnsiPart {
+	kind: "csi" | "text";
+	value: string;
+}
+
+function splitAnsi(text: string): AnsiPart[] {
+	const parts: AnsiPart[] = [];
+	let last = 0;
+	for (const match of text.matchAll(CSI_PATTERN)) {
+		const start = match.index ?? 0;
+		if (start > last) parts.push({ kind: "text", value: text.slice(last, start) });
+		parts.push({ kind: "csi", value: match[0] });
+		last = start + match[0].length;
+	}
+	if (last < text.length) parts.push({ kind: "text", value: text.slice(last) });
+	return parts;
+}
+
+function graphemeWidth(text: string): number {
 	let width = 0;
 	for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
 		const cp = segment.segment.codePointAt(0) ?? 0;
@@ -26,6 +50,16 @@ export function visibleWidth(text: string): number {
 	return width;
 }
 
+export function visibleWidth(text: string): number {
+	if (!text) return 0;
+	let width = 0;
+	for (const part of splitAnsi(text)) {
+		if (part.kind === "csi") continue; // escape sequences render at zero width
+		width += graphemeWidth(part.value);
+	}
+	return width;
+}
+
 export function truncateToWidth(text: string, maxWidth: number, ellipsis = ELLIPSIS): string {
 	const measured = visibleWidth(text);
 	if (measured <= maxWidth) return text;
@@ -33,12 +67,25 @@ export function truncateToWidth(text: string, maxWidth: number, ellipsis = ELLIP
 	const target = Math.max(0, maxWidth - ellipsisWidth);
 	let result = "";
 	let used = 0;
-	for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
-		const w = visibleWidth(segment.segment);
-		if (used + w > target) break;
-		result += segment.segment;
-		used += w;
+	let exhausted = false;
+	for (const part of splitAnsi(text)) {
+		if (part.kind === "csi") {
+			if (!exhausted) result += part.value; // keep styling runs intact; never split them
+			continue;
+		}
+		for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(part.value)) {
+			const w = visibleWidth(segment.segment);
+			if (used + w > target) {
+				exhausted = true;
+				break;
+			}
+			result += segment.segment;
+			used += w;
+		}
 	}
+	// A kept open SGR (its reset lived past the cut) must not bleed into the
+	// ellipsis or anything rendered after this string.
+	if (exhausted && result.includes("\x1b[")) result += "\x1b[0m";
 	return ellipsis ? `${result}${ellipsis}` : result;
 }
 
@@ -53,19 +100,25 @@ export function wrapTextWithAnsi(text: string, maxWidth: number): string[] {
 		if (word === "") continue;
 		const wordWidth = visibleWidth(word);
 		if (wordWidth > maxWidth) {
-			// Hard split a single overlong word.
+			// Hard split a single overlong word (ANSI-aware: CSI runs are zero-width and atomic).
 			if (current) { lines.push(current); current = ""; currentWidth = 0; }
 			let buffer = "";
 			let bufferWidth = 0;
-			for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(word)) {
-				const w = visibleWidth(segment.segment);
-				if (bufferWidth + w > maxWidth) {
-					lines.push(buffer);
-					buffer = segment.segment;
-					bufferWidth = w;
-				} else {
-					buffer += segment.segment;
-					bufferWidth += w;
+			for (const part of splitAnsi(word)) {
+				if (part.kind === "csi") {
+					buffer += part.value;
+					continue;
+				}
+				for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(part.value)) {
+					const w = visibleWidth(segment.segment);
+					if (bufferWidth + w > maxWidth) {
+						lines.push(buffer);
+						buffer = segment.segment;
+						bufferWidth = w;
+					} else {
+						buffer += segment.segment;
+						bufferWidth += w;
+					}
 				}
 			}
 			if (buffer) { lines.push(buffer); buffer = ""; bufferWidth = 0; }
@@ -86,4 +139,4 @@ export function wrapTextWithAnsi(text: string, maxWidth: number): string[] {
 
 export function matchesEscape(data: string): boolean {
 	return data === "\x1b" || data === "\x1b\x1b" || /^(\x1b\[\??\d*[A-Za-z])|(\x1bO[A-Za-z])$/.test(data);
-}
+}

package/src/refine-ui-state.ts

@@ -1,7 +1,18 @@
 import type { SubagentProgressEvent, SubagentResult } from "./subagent.ts";
 
-export type RefineOverlayRole = "reviewer" | "criticizer";
+export type RefineOverlayRole = "reviewer" | "criticizer" | "refs";
 export type RefineLaneStatus = "queued" | "running" | "complete" | "failed" | "cancelled";
+export type RefineTranscriptEntryType = "assistant-text" | "thinking" | "tool-call" | "tool-result" | "diagnostic";
+
+export interface RefineTranscriptEntry {
+	id: string;
+	type: RefineTranscriptEntryType;
+	text: string;
+	streaming: boolean;
+	toolCallId?: string;
+	toolName?: string;
+	isError?: boolean;
+}
 
 export interface RefineLaneState {
 	id: string;
@@ -9,11 +20,11 @@ export interface RefineLaneState {
 	status: RefineLaneStatus;
 	phase: string;
 	detail: string;
-}
-
-function shorten(text: string, maxLength: number): string {
-	const normalized = text.replace(/\s+/g, " ").trim();
-	return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 3)}...` : normalized;
+	transcript: RefineTranscriptEntry[];
+	currentTurnIndex: number;
+	scrollOffset: number;
+	followTranscript: boolean;
+	viewportHeight: number;
 }
 
 export function statusLabel(status: RefineLaneStatus): string {
@@ -31,6 +42,56 @@ export function statusLabel(status: RefineLaneStatus): string {
 	}
 }
 
+function transcriptId(lane: RefineLaneState, event: Extract<SubagentProgressEvent, { type: "transcript" }>): string {
+	return `${lane.currentTurnIndex}:${event.key}`;
+}
+
+function phaseForEntry(event: Extract<SubagentProgressEvent, { type: "transcript" }>): string {
+	switch (event.entryType) {
+		case "assistant-text":
+			return "responding";
+		case "thinking":
+			return "thinking";
+		case "tool-call":
+			return event.toolName ? `tool: ${event.toolName}` : "tool call";
+		case "tool-result":
+			return event.toolName ? `result: ${event.toolName}` : "tool result";
+		case "diagnostic":
+			return "diagnostic";
+	}
+}
+
+function applyTranscriptEvent(lane: RefineLaneState, event: Extract<SubagentProgressEvent, { type: "transcript" }>): void {
+	const id = transcriptId(lane, event);
+	let entry = lane.transcript.find((candidate) => candidate.id === id);
+	if (!entry && event.entryType === "tool-call" && event.toolCallId) {
+		entry = lane.transcript.find((candidate) => candidate.type === "tool-call" && candidate.toolCallId === event.toolCallId);
+	}
+	if (!entry) {
+		entry = { id, type: event.entryType, text: "", streaming: event.streaming };
+		lane.transcript.push(entry);
+	}
+	if (event.update === "append") entry.text += event.text;
+	else entry.text = event.text;
+	entry.streaming = event.streaming;
+	if (event.toolCallId !== undefined) entry.toolCallId = event.toolCallId;
+	if (event.toolName !== undefined) entry.toolName = event.toolName;
+	if (event.isError !== undefined) entry.isError = event.isError;
+	lane.detail = entry.text;
+	lane.status = "running";
+	lane.phase = phaseForEntry(event);
+}
+
+function applyDiagnostic(lane: RefineLaneState, text: string): void {
+	if (!text) return;
+	const id = `${lane.currentTurnIndex}:diagnostic`;
+	const existing = lane.transcript.find((entry) => entry.id === id);
+	if (existing) existing.text += text;
+	else lane.transcript.push({ id, type: "diagnostic", text, streaming: true });
+	lane.detail = text;
+	lane.phase = "diagnostic";
+}
+
 export function applyRefineProgress(lane: RefineLaneState, event: SubagentProgressEvent): void {
 	if (lane.status === "complete" || lane.status === "failed" || lane.status === "cancelled") return;
 
@@ -39,40 +100,45 @@ export function applyRefineProgress(lane: RefineLaneState, event: SubagentProgre
 			lane.phase = event.phase === "started" ? "starting" : "exiting";
 			return;
 		case "turn":
-			lane.status = "running";
-			lane.phase = event.phase === "start" ? "thinking" : "waiting";
+			if (event.phase === "start") {
+				lane.status = "running";
+				lane.phase = "thinking";
+				lane.currentTurnIndex = event.turnIndex ?? lane.currentTurnIndex + 1;
+			} else {
+				lane.phase = "waiting";
+			}
 			return;
-		case "message":
-			lane.status = "running";
-			lane.phase = event.role === "assistant" ? "responding" : event.role;
-			if (event.text) lane.detail = shorten(event.text, 180);
-			return;
-		case "tool":
-			lane.status = "running";
-			lane.phase = `tool: ${event.toolName}`;
-			if (event.detail) lane.detail = shorten(event.detail, 180);
+		case "transcript":
+			applyTranscriptEvent(lane, event);
 			return;
 		case "stderr":
-			lane.phase = "diagnostic";
-			if (event.text) lane.detail = shorten(event.text, 180);
+			applyDiagnostic(lane, event.text);
 			return;
 	}
 }
 
 export function applyRefineResult(lane: RefineLaneState, result: SubagentResult): void {
+	const finalText = result.output || result.errorMessage || result.stderr || "";
+	const finalEntry = [...lane.transcript].reverse().find((entry) => entry.type === "assistant-text");
+	if (finalText) {
+		if (finalEntry) {
+			finalEntry.text = finalText;
+			finalEntry.streaming = false;
+		} else {
+			lane.transcript.push({ id: `${lane.currentTurnIndex}:result`, type: "assistant-text", text: finalText, streaming: false });
+		}
+	}
+	lane.detail = finalText;
 	if (result.ok) {
 		lane.status = "complete";
 		lane.phase = "complete";
-		lane.detail = shorten(result.output, 180);
 		return;
 	}
 	if (result.cancelled) {
 		lane.status = "cancelled";
 		lane.phase = "cancelled";
-		lane.detail = shorten(result.errorMessage ?? "Subagent was aborted", 180);
 		return;
 	}
 	lane.status = "failed";
 	lane.phase = result.timedOut ? "timed out" : "failed";
-	lane.detail = shorten((result.errorMessage ?? result.stderr) || "Subagent failed", 180);
 }