pi-pr-review 1.7.1 → 1.8.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.7.1"
+  ".": "1.8.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.8.0](https://github.com/10ego/pi-pr-review/compare/v1.7.1...v1.8.0) (2026-07-14)
+
+
+### Features
+
+* add live subagent focus viewer ([#17](https://github.com/10ego/pi-pr-review/issues/17)) ([44f1020](https://github.com/10ego/pi-pr-review/commit/44f102067e974ca2a723611c6882019bac6dbb9c))
+
 ## [1.7.1](https://github.com/10ego/pi-pr-review/compare/v1.7.0...v1.7.1) (2026-07-14)
 
 

package/README.md

@@ -69,6 +69,31 @@ A review uses five focused passes by default:
 
 `--full` adds a convention and maintainability pass (`medium`). Large multi-file diffs are split by whole-file boundaries and reviewed in parallel. If the extension is unavailable, the prompt falls back to the current Pi session model.
 
+## Focus running reviewers
+
+While a review is running in the interactive TUI, open the live read-only subagent view with:
+
+```text
+/pr-review-focus
+```
+
+`Ctrl+Alt+R` opens the same view without entering a command. The viewer keeps the parent review running and does not switch Pi sessions or attach an interactive terminal to a child process.
+
+Viewer controls:
+
+| Key | Action |
+|---|---|
+| `Tab` / `Right` | Focus the next pass. |
+| `Shift+Tab` / `Left` | Focus the previous pass. |
+| `Up` / `Down` | Scroll one line. |
+| `PageUp` / `PageDown` | Scroll one page. |
+| `Home` / `End` | Jump to the start or resume following live output. |
+| `Esc` | Return to the main thread without cancelling the review. |
+
+The view shows pass status, attempt/model, tool names and completion state, and bounded assistant output. It never stores the pass objective, input context, captured diff, raw child events, tool arguments, tool results, or stderr. Assistant text is sanitized and capped at 48 KiB per pass and 256 KiB across the active review; older text is evicted with an on-screen marker. State exists only in memory for the active session/cwd-bound `/pr-review` generation and is synchronously purged on completion, cancellation, replacement, or session/tree lifecycle changes.
+
+The viewer intentionally cannot send prompts, steering, or follow-ups to reviewers. It is unavailable in print, JSON, and RPC modes and outside an active user-initiated `/pr-review` loop.
+
 ## Configure models
 
 `/pr-review-config` opens an interactive settings menu in the TUI. Use `/pr-review-config show` for a text summary or `key=value` arguments for direct changes.

package/extensions/index.ts

@@ -1,11 +1,13 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ReviewLoopCoordinator } from "../lib/pr-review-loop.ts";
 import registerPrReviewSubagents from "./pr-review-subagent.ts";
+import registerReviewFocus from "./pr-review-focus.ts";
 import registerReviewTable from "./review-table.ts";
 
 /** Register the package behind one shared, session-scoped review-loop authority. */
 export default function registerPrReview(pi: ExtensionAPI) {
 	const loopCoordinator = new ReviewLoopCoordinator(pi);
 	registerPrReviewSubagents(pi, loopCoordinator);
+	registerReviewFocus(pi, loopCoordinator);
 	registerReviewTable(pi, loopCoordinator);
 }

package/extensions/pr-review-focus.ts

@@ -0,0 +1,265 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	matchesKey,
+	truncateToWidth,
+	type TUI,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import type {
+	ReviewFocusPassSnapshot,
+	ReviewFocusSnapshot,
+} from "../lib/pr-review-focus.ts";
+import { ReviewLoopCoordinator } from "../lib/pr-review-loop.ts";
+
+const SHORTCUT = "ctrl+alt+r" as const;
+
+function statusIcon(status: ReviewFocusPassSnapshot["status"]): string {
+	switch (status) {
+		case "queued": return "○";
+		case "running": return "◉";
+		case "retrying": return "↻";
+		case "completed": return "✓";
+		case "failed": return "✗";
+		case "aborted": return "■";
+	}
+}
+
+function statusColor(status: ReviewFocusPassSnapshot["status"]): "muted" | "warning" | "success" | "error" {
+	switch (status) {
+		case "queued": return "muted";
+		case "running":
+		case "retrying": return "warning";
+		case "completed": return "success";
+		case "failed":
+		case "aborted": return "error";
+	}
+}
+
+export class ReviewFocusView implements Component {
+	private snapshot: ReviewFocusSnapshot;
+	private selectedIndex = 0;
+	private scrollTop = 0;
+	private followTail = true;
+	private unsubscribe?: () => void;
+	private closed = false;
+
+	constructor(
+		private readonly tui: Pick<TUI, "requestRender" | "terminal">,
+		private readonly theme: Theme,
+		initial: ReviewFocusSnapshot,
+		private readonly done: () => void,
+	) {
+		this.snapshot = initial;
+	}
+
+	setUnsubscribe(unsubscribe: (() => void) | undefined): void {
+		this.unsubscribe = unsubscribe;
+	}
+
+	update(snapshot: ReviewFocusSnapshot | undefined): void {
+		if (!snapshot) {
+			this.close();
+			return;
+		}
+		const selectedKey = this.snapshot.passes[this.selectedIndex]?.key;
+		this.snapshot = snapshot;
+		if (selectedKey) {
+			const nextIndex = snapshot.passes.findIndex((pass) => pass.key === selectedKey);
+			this.selectedIndex = nextIndex >= 0 ? nextIndex : Math.min(this.selectedIndex, Math.max(0, snapshot.passes.length - 1));
+		} else {
+			this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, snapshot.passes.length - 1));
+		}
+		this.tui.requestRender();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.close();
+			return;
+		}
+		if (matchesKey(data, "tab") || matchesKey(data, "right")) {
+			this.selectRelative(1);
+			return;
+		}
+		if (matchesKey(data, "shift+tab") || matchesKey(data, "left")) {
+			this.selectRelative(-1);
+			return;
+		}
+		if (matchesKey(data, "up")) {
+			this.followTail = false;
+			this.scrollTop = Math.max(0, this.scrollTop - 1);
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.followTail = false;
+			this.scrollTop++;
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "pageUp")) {
+			this.followTail = false;
+			this.scrollTop = Math.max(0, this.scrollTop - this.pageSize());
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "pageDown")) {
+			this.followTail = false;
+			this.scrollTop += this.pageSize();
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "home")) {
+			this.followTail = false;
+			this.scrollTop = 0;
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "end")) {
+			this.followTail = true;
+			this.tui.requestRender();
+		}
+	}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(20, width);
+		const height = Math.max(8, (this.tui.terminal.rows ?? 24) - 2);
+		const passes = this.snapshot.passes;
+		const pass = passes[this.selectedIndex];
+		const lines: string[] = [];
+		lines.push(truncateToWidth(this.theme.fg("accent", this.theme.bold("PR Review Focus")), safeWidth, "…", true));
+
+		if (!pass) {
+			lines.push(truncateToWidth(this.theme.fg("muted", "No reviewer passes have started yet."), safeWidth, "…", true));
+			lines.push("");
+			while (lines.length < height - 1) lines.push("");
+			lines.push(truncateToWidth(this.theme.fg("dim", "Esc return to main thread"), safeWidth, "…", true));
+			return lines;
+		}
+
+		const index = `${this.selectedIndex + 1}/${passes.length}`;
+		const state = `${statusIcon(pass.status)} ${pass.status}`;
+		lines.push(truncateToWidth(
+			`${this.theme.fg("accent", `[${index}] ${pass.label}`)} ${this.theme.fg("muted", `(${pass.tier})`)} ${this.theme.fg(statusColor(pass.status), state)}`,
+			safeWidth,
+			"…",
+			true,
+		));
+		const attempt = pass.attempt > 0 ? `attempt ${pass.attempt}` : "waiting to start";
+		const model = pass.model ? ` · ${pass.model}` : "";
+		lines.push(truncateToWidth(this.theme.fg("dim", `${attempt}${model}`), safeWidth, "…", true));
+		lines.push(this.theme.fg("dim", "─".repeat(Math.max(1, safeWidth))));
+
+		const body: string[] = [];
+		if (pass.tools.length > 0) {
+			body.push(this.theme.fg("muted", "Tool activity"));
+			for (const tool of pass.tools) {
+				const icon = tool.status === "running" ? "…" : tool.status === "completed" ? "✓" : "✗";
+				const color = tool.status === "running" ? "warning" : tool.status === "completed" ? "success" : "error";
+				body.push(`  ${this.theme.fg(color, icon)} ${this.theme.fg("toolOutput", tool.name)}`);
+			}
+			body.push("");
+		}
+		body.push(this.theme.fg("muted", "Assistant output"));
+		if (pass.evictedBytes > 0) {
+			body.push(this.theme.fg("warning", `… ${pass.evictedBytes} earlier UTF-8 bytes evicted by viewer limits …`));
+		}
+		const output = pass.assistantText || (pass.status === "queued" ? "(queued)" : "(waiting for assistant output…)");
+		for (const outputLine of wrapTextWithAnsi(output, Math.max(1, safeWidth - 2))) {
+			body.push(`  ${this.theme.fg("toolOutput", outputLine)}`);
+		}
+		if (this.snapshot.droppedPasses > 0) {
+			body.push("");
+			body.push(this.theme.fg("warning", `${this.snapshot.droppedPasses} older pass record(s) evicted`));
+		}
+
+		const footerRows = 2;
+		const viewportRows = Math.max(1, height - lines.length - footerRows);
+		const maxScroll = Math.max(0, body.length - viewportRows);
+		if (this.followTail) this.scrollTop = maxScroll;
+		else this.scrollTop = Math.min(this.scrollTop, maxScroll);
+		const visible = body.slice(this.scrollTop, this.scrollTop + viewportRows);
+		for (const line of visible) lines.push(truncateToWidth(line, safeWidth, "…", true));
+		while (lines.length < height - footerRows) lines.push("");
+		const scroll = maxScroll > 0 ? ` · lines ${this.scrollTop + 1}-${Math.min(body.length, this.scrollTop + viewportRows)}/${body.length}` : "";
+		lines.push(truncateToWidth(this.theme.fg("dim", `Tab/←/→ pass · ↑/↓/PgUp/PgDn scroll${scroll}`), safeWidth, "…", true));
+		lines.push(truncateToWidth(this.theme.fg("dim", "Esc return to main thread · viewer is read-only"), safeWidth, "…", true));
+		return lines;
+	}
+
+	invalidate(): void {
+		this.tui.requestRender();
+	}
+
+	dispose(): void {
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+	}
+
+	private pageSize(): number {
+		return Math.max(1, (this.tui.terminal.rows ?? 24) - 10);
+	}
+
+	private selectRelative(delta: number): void {
+		const count = this.snapshot.passes.length;
+		if (count === 0) return;
+		this.selectedIndex = (this.selectedIndex + delta + count) % count;
+		this.scrollTop = 0;
+		this.followTail = true;
+		this.tui.requestRender();
+	}
+
+	private close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.dispose();
+		this.done();
+	}
+}
+
+export default function registerReviewFocus(
+	pi: ExtensionAPI,
+	loopCoordinator: ReviewLoopCoordinator,
+): void {
+	const open = async (ctx: ExtensionContext): Promise<void> => {
+		const mode = (ctx as ExtensionContext & { mode?: string }).mode;
+		if (!ctx.hasUI || (mode !== undefined && mode !== "tui") || typeof ctx.ui.custom !== "function") {
+			ctx.ui.notify("/pr-review-focus is available only in the interactive TUI", "warning");
+			return;
+		}
+		const initial = loopCoordinator.focusSnapshot(ctx);
+		if (!initial) {
+			ctx.ui.notify("No active user-initiated /pr-review loop to focus", "warning");
+			return;
+		}
+
+		await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+			const view = new ReviewFocusView(tui, theme, initial, done);
+			const unsubscribe = loopCoordinator.subscribeFocus(ctx, (snapshot) => view.update(snapshot));
+			view.setUnsubscribe(unsubscribe);
+			if (!unsubscribe) queueMicrotask(() => view.update(undefined));
+			return view;
+		});
+	};
+
+	pi.registerCommand("pr-review-focus", {
+		description: "Focus the live read-only output of running /pr-review subagents",
+		handler: async (args, ctx) => {
+			if ((args ?? "").trim()) {
+				ctx.ui.notify("Usage: /pr-review-focus", "warning");
+				return;
+			}
+			await open(ctx);
+		},
+	});
+
+	pi.registerShortcut(SHORTCUT, {
+		description: "Focus running PR review subagents",
+		handler: open,
+	});
+}

package/extensions/pr-review-subagent.ts

@@ -54,7 +54,12 @@ import {
 	combineAbortSignals,
 	ReviewLoopCoordinator,
 	reviewLoopDeniedResult,
+	type ReviewFocusPublisher,
 } from "../lib/pr-review-loop.ts";
+import {
+	normalizeReviewFocusJsonEvent,
+	ReviewJsonLineDecoder,
+} from "../lib/pr-review-focus.ts";
 import {
 	appendToolPolicyArgs,
 	buildReviewBaseArgs,
@@ -450,12 +455,12 @@ function runReviewSubprocess(
 	input: string,
 	signal: AbortSignal | undefined,
 	onText: (text: string) => void,
+	onEvent?: (event: unknown) => void,
 ): Promise<RunResult> {
 	return new Promise<RunResult>((resolve) => {
 		const messages: Message[] = [];
 		const result: RunResult = { text: "", exitCode: 0, stderr: "", toolElapsedMs: 0 };
 		const startedAt = monotonicNow();
-		let buffer = "";
 		let aborted = false;
 		let closed = false;
 		let killTimer: ReturnType<typeof setTimeout> | undefined;
@@ -481,13 +486,13 @@ function runReviewSubprocess(
 			signal?.removeEventListener("abort", kill);
 		};
 
-		const processLine = (line: string) => {
-			if (!line.trim()) return;
-			let event: { type?: string; message?: Message };
+		const processEvent = (raw: unknown) => {
+			if (!raw || typeof raw !== "object") return;
+			const event = raw as { type?: string; message?: Message };
 			try {
-				event = JSON.parse(line);
+				onEvent?.(event);
 			} catch {
-				return;
+				// Focus observers are non-authoritative and must never change review results.
 			}
 			const now = monotonicNow();
 			result.firstEventMs ??= now - startedAt;
@@ -512,12 +517,8 @@ function runReviewSubprocess(
 			}
 		};
 
-		proc.stdout.on("data", (data) => {
-			buffer += data.toString();
-			const lines = buffer.split("\n");
-			buffer = lines.pop() ?? "";
-			for (const line of lines) processLine(line);
-		});
+		const decoder = new ReviewJsonLineDecoder(processEvent);
+		proc.stdout.on("data", (data) => decoder.push(data.toString()));
 		proc.stderr.on("data", (data) => {
 			result.stderr += data.toString();
 		});
@@ -529,7 +530,7 @@ function runReviewSubprocess(
 		proc.on("close", (code) => {
 			closed = true;
 			cleanupAbort();
-			if (buffer.trim()) processLine(buffer);
+			decoder.end();
 			if (activeTools > 0) {
 				result.toolElapsedMs += monotonicNow() - activeToolsStartedAt;
 				activeTools = 0;
@@ -563,6 +564,7 @@ interface SubagentPassRequest {
 	toolPolicy?: ToolPolicy;
 	majorOnly?: boolean;
 	minorHygiene?: boolean;
+	focusPublisher?: ReviewFocusPublisher;
 }
 
 interface ModelAttemptReport {
@@ -642,6 +644,7 @@ async function runSubagentAttempt(
 	ctx: Pick<ExtensionContext, "cwd">,
 	pass: SubagentPassRequest,
 	attempt: ModelAttempt,
+	attemptOrdinal: number,
 	toolPolicy: ToolPolicy,
 	signal: AbortSignal | undefined,
 	onText?: (text: string) => void,
@@ -669,10 +672,21 @@ async function runSubagentAttempt(
 		if (beforeSpawn && !beforeSpawn()) {
 			throw new Error("The active /pr-review loop ended before the reviewer could start.");
 		}
+		pass.focusPublisher?.publish({ type: "attempt_started", attempt: attemptOrdinal, model: attempt.spec });
 		const invocation = getPiInvocation(args);
-		const result = await runReviewSubprocess(invocation.command, invocation.args, ctx.cwd, task, signal, (text) => {
-			onText?.(text);
-		});
+		const result = await runReviewSubprocess(
+			invocation.command,
+			invocation.args,
+			ctx.cwd,
+			task,
+			signal,
+			(text) => onText?.(text),
+			(event) => {
+				for (const normalized of normalizeReviewFocusJsonEvent(event)) {
+					pass.focusPublisher?.publish(normalized);
+				}
+			},
+		);
 		return { result, notice: noticeForAttempt(pass.tier, attempt), elapsedMs: monotonicNow() - startedAt };
 	} catch (e) {
 		return {
@@ -707,12 +721,14 @@ async function runSubagentPass(
 	let lastResult: RunResult | undefined;
 	let lastNotice = noticeForAttempt(tier, attempts[0]!);
 
-	for (const attempt of attempts) {
+	for (let attemptIndex = 0; attemptIndex < attempts.length; attemptIndex++) {
+		const attempt = attempts[attemptIndex]!;
 		const { result, notice, elapsedMs } = await runSubagentAttempt(
 			config,
 			ctx,
 			pass,
 			attempt,
+			attemptIndex + 1,
 			toolPolicy,
 			signal,
 			onText,
@@ -739,6 +755,7 @@ async function runSubagentPass(
 		});
 
 		if (!failed) {
+			pass.focusPublisher?.publish({ type: "completed" });
 			return {
 				id: pass.id ?? tier,
 				tier,
@@ -760,9 +777,11 @@ async function runSubagentPass(
 		}
 
 		if (!retryable || signal?.aborted) break;
+		pass.focusPublisher?.publish({ type: "retrying" });
 	}
 
 	const final = lastResult ?? { text: "", exitCode: 1, stderr: "", errorMessage: "No model attempts were available.", toolElapsedMs: 0 };
+	pass.focusPublisher?.publish({ type: signal?.aborted || final.stopReason === "aborted" ? "aborted" : "failed" });
 	return {
 		id: pass.id ?? tier,
 		tier,
@@ -1066,7 +1085,7 @@ export default function registerPrReviewSubagents(
 		],
 		parameters: ReviewSubagentParams,
 
-		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const lease = loopCoordinator.acquire(ctx);
 			if (!lease) return reviewLoopDeniedResult("review_subagent");
 			const executionSignal = combineAbortSignals(signal, lease.signal);
@@ -1082,6 +1101,11 @@ export default function registerPrReviewSubagents(
 				};
 			}
 			if (!loopCoordinator.isLeaseActive(lease, ctx)) return reviewLoopDeniedResult("review_subagent");
+			const focusPublisher = loopCoordinator.createFocusPublisher(lease, ctx, {
+				key: `${toolCallId}:single`,
+				label: `${tier} review`,
+				tier,
+			});
 			const config = loadConfig(ctx);
 			const result = await runSubagentPass(
 				config,
@@ -1093,6 +1117,7 @@ export default function registerPrReviewSubagents(
 					toolPolicy: normalizeToolPolicy(params.tool_policy),
 					majorOnly: params.major_only === true,
 					minorHygiene: params.minor_hygiene === true,
+					focusPublisher,
 				},
 				executionSignal,
 				(text) => onUpdate?.({ content: [{ type: "text", text }] }),
@@ -1155,7 +1180,7 @@ export default function registerPrReviewSubagents(
 		],
 		parameters: ReviewSubagentsParams,
 
-		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const lease = loopCoordinator.acquire(ctx);
 			if (!lease) return reviewLoopDeniedResult("review_subagents");
 			const executionSignal = combineAbortSignals(signal, lease.signal);
@@ -1214,7 +1239,7 @@ export default function registerPrReviewSubagents(
 				: loadedContext.context;
 			const majorOnly = params.major_only === true;
 			const minorHygiene = params.minor_hygiene === true;
-			const passes: SubagentPassRequest[] = rawPasses.flatMap((pass, index) => {
+			const passesWithoutFocus: SubagentPassRequest[] = rawPasses.flatMap((pass, index) => {
 				const tier = pass.tier as Tier;
 				const baseId = typeof pass.id === "string" && pass.id.trim() ? pass.id.trim() : `${index + 1}-${tier}`;
 				const baseContext = combineContexts(sharedContext, loadedPassContexts[index]!.context);
@@ -1238,8 +1263,16 @@ export default function registerPrReviewSubagents(
 					? requestedShards.map((shard, shardIndex) => makePass(shard, shardIndex))
 					: [makePass(undefined, 0)];
 			});
-			const maxParallel = normalizeMaxParallel(params.max_parallel, passes.length);
 			if (!loopCoordinator.isLeaseActive(lease, ctx)) return reviewLoopDeniedResult("review_subagents");
+			const passes = passesWithoutFocus.map((pass, index) => ({
+				...pass,
+				focusPublisher: loopCoordinator.createFocusPublisher(lease, ctx, {
+					key: `${toolCallId}:${index}`,
+					label: pass.id ?? `${pass.tier} review`,
+					tier: pass.tier,
+				}),
+			}));
+			const maxParallel = normalizeMaxParallel(params.max_parallel, passes.length);
 			const config = loadConfig(ctx);
 			const batchStartedAt = monotonicNow();