pi-pr-review 1.7.1 → 1.9.0

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.9.0](https://github.com/10ego/pi-pr-review/compare/v1.8.0...v1.9.0) (2026-07-14)
+
+
+### Features
+
+* **review:** add constrained one-shot self-review ([#18](https://github.com/10ego/pi-pr-review/issues/18)) ([ab267c4](https://github.com/10ego/pi-pr-review/commit/ab267c40415731b2fbbea91c5b345153fa7b6132))
+
+## [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

@@ -14,7 +14,7 @@ The default review prioritizes P0–P2 defects and allows up to three minor find
 
 ## Requirements
 
-- Pi `0.77.0` or newer.
+- Pi `0.80.5` or newer (the first release with the terminal `agent_settled` lifecycle event).
 - [`gh`](https://cli.github.com/) installed and authenticated with `gh auth login`.
 - Pi running inside the repository that owns the PR.
 
@@ -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.
@@ -133,6 +158,20 @@ Example:
 
 Tier subprocesses retry configured fallbacks only for retryable quota, rate-limit, or capacity failures. If a tier is unset, it uses the nearest configured tier and then Pi's default model.
 
+## One-shot self-review for top-level tasks
+
+For an eligible long-running coding task started by direct interactive or RPC input, Pi exposes `self_review_subagent` near the end of the task. The tool takes no arguments. Its empty schema is closed with `additionalProperties: false`; the extension—not the caller—fixes the objective, heavy tier, P0–P2-only severity policy, no-minor-hygiene policy, and no-tools isolation.
+
+The permit is bound to one top-level task generation, the Pi session instance, cwd, and canonical Git worktree. Dispatch is additionally bound to the tool-call ID from an assistant `message_end` containing exactly one tool call, `self_review_subagent`; mixed, multiple, or direct unbound dispatches are denied without consuming the reusable task permit. A bound permit is consumed atomically before delta capture, so concurrent or replayed calls are rejected and the tool is hidden immediately. It is never available during `/pr-review`. Low-level `agent_end` events do not revoke it because Pi may still retry, compact, or run queued continuations; unused authority is cleared only at terminal `agent_settled` (or earlier cancellation/session/input boundaries).
+
+The child uses Pi RPC mode with a bounded ten-minute total runtime. Before startup, the host creates a mode-`0700` temporary `PI_CODING_AGENT_DIR`, copies and normalizes the trusted user settings there with retry and compaction disabled, and exposes only validated regular `auth.json`/`models.json` files through controlled symlinks. The same private directory—not the mutable worktree—is the child process cwd, and inherited runtime preload flags (`NODE_OPTIONS` and `BUN_OPTIONS`) are removed. RPC control acknowledgements can therefore persist only to temporary settings. The host attempts synchronous recursive removal after every supervised outcome; unsafe source configuration or cleanup failure fails the call closed. Environment-based authentication otherwise remains inherited, and no credentials are placed in arguments or prompts. The host waits for acknowledgements that automatic compaction and automatic retry are disabled before it submits the sole prompt, and it also aborts on timeout, bounded stdout/stderr overflow, any retry/compaction lifecycle event, or a second `agent_start`. There is no fallback, sharding, extension discovery, tools, publication, or verification behavior.
+
+Self-review is deliberately fail-closed. At extension startup, the host resolves one canonical executable Git from that startup `PATH`; the same absolute executable is bound through clean-baseline capture, permit validation, and delta capture, so later `PATH` changes cannot select repository-controlled Git. The worktree must be clean when the top-level task starts and HEAD must remain unchanged. Baseline capture receives its abort signal immediately, so new input, cancellation, or session/tree navigation can stop even the initial Git inspection. At execution, the host builds a complete bounded diff of Git-visible tracked, staged, and non-ignored untracked changes relative to that starting HEAD. It rejects an empty delta, any changed or dirty submodule, more than 200 status records, more than 4 MiB of diff, a changed session/cwd/worktree/HEAD, or a status change during capture.
+
+The child must return strict JSON containing only a `findings` array. Every finding must pass an exact host-owned schema: P0/P1/P2 severity and matching title/blocking state, concrete impact/trigger/evidence strings, normalized repo-relative changed-line coordinates, side, task/diff relationship flags, and bounded confidence. The host derives changed-line anchors from the captured unified diff and requires each claimed range to lie completely within one changed-line run in one hunk on the exact claimed path and side; binary and no-hunk paths have no valid anchors. Markdown, malformed JSON, extra or missing fields, P3/nits, inconsistent metadata, out-of-delta anchors, and unsafe paths are rejected rather than shown as review results. No findings is `{"findings":[]}`.
+
+This is a practical Git-derived boundary, not a filesystem snapshot or sandbox. Ignored files are not included, and an external process that rewrites ordinary file contents without changing status shape could race capture. Requiring a clean start, rejecting submodule deltas, checking HEAD and status before/after capture, incrementally bounding all output, and failing closed avoids silently presenting a partial oversized delta. The RPC leader starts in a detached POSIX process group; on failure, abort, timeout, or retained descendants, the host sends group TERM then KILL, destroys inherited pipes, and stops waiting after a bounded drain deadline. A descendant that deliberately creates a different process group/session can escape those signals, although it cannot force the host to retain the supervised pipes indefinitely. Use a separate sandbox or snapshot system when stronger filesystem, process, or network isolation is required.
+
 ## Publish to GitHub
 
 Publishing is off by default.
@@ -212,6 +251,8 @@ The verdict is `request_changes` only when a validated P0 or P1 finding exists.
 - Every review tool also checks an in-memory, session- and cwd-bound loop lease before reading review context, running verification, or spawning a reviewer. Hiding the tools is not the only enforcement boundary.
 - Unrelated input, terminal completion, cancellation, session navigation, or tree navigation revokes the lease and aborts in-flight review work. Tools are suspended while a non-open PR waits for confirmation.
 - Reviewer subprocesses start with extension discovery disabled, so they cannot recursively invoke this package's agents or verification tool.
+- `self_review_subagent` has separate one-shot authority for an eligible direct top-level task; it cannot authorize `review_subagent`, `review_subagents`, or `pr_review_verify`, and those permissive schemas remain exclusively behind `ReviewLoopCoordinator`.
+- Self-review execute-time checks are authoritative: visibility alone never grants a permit, and consumption hides the tool before any asynchronous delta or child work.
 - Reviewers receive the captured diff and are instructed not to modify files.
 - The orchestrator does not check out, commit, or push PR code.
 - GitHub writes require `--comment`, an effective `autoPostReviews: true` setting, the model-free `/pr-review-publish` command, or a narrowly matched direct interactive/RPC publish request handled by the extension before an agent turn. `allowStalePublish` controls whether an invocation/config-authorized write may be stale; it does not independently authorize a write.

package/extensions/index.ts

@@ -1,11 +1,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ReviewLoopCoordinator } from "../lib/pr-review-loop.ts";
+import { SelfReviewPermitCoordinator } from "../lib/pr-self-review.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);
-	registerReviewTable(pi, loopCoordinator);
+	const selfReviewCoordinator = new SelfReviewPermitCoordinator(pi, () => !!loopCoordinator.peek());
+	registerPrReviewSubagents(pi, loopCoordinator, selfReviewCoordinator);
+	registerReviewFocus(pi, loopCoordinator);
+	registerReviewTable(pi, loopCoordinator, selfReviewCoordinator);
 }

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