pi-bro 0.20.0 → 0.22.0

package/backend.ts

@@ -2,16 +2,18 @@ import { type ChildProcess, spawn } from "node:child_process";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createInterface } from "node:readline";
 
-// Shared internal execution boundary for all four Bro features (explain, show, btw, advisor).
-// This implements docs/plans/2026-09-22-shared-backend-design.md for Agy (all features) and the
-// Claude Code CLI (all features) and the Grok CLI (all features): it owns CLI selection, process invocation, progress/outcome normalization, continuation, and
-// single-attempt cleanup. Feature code (bro.ts) keeps retries, UI, source/session capture and
-// settings.
+// Shared internal execution boundary for explain, show, btw, advisor, and review.
+// This implements docs/plans/2026-09-22-shared-backend-design.md across all supported backends
+// (Agy, Claude Code, Grok, Codex, Muse): it owns CLI selection, process invocation,
+// progress/outcome normalization, continuation, and single-attempt cleanup. Feature code
+// keeps retries, UI, source/session capture and settings.
 
-export type BackendFeature = "explain" | "show" | "btw" | "advisor";
+export type BackendFeature = "explain" | "show" | "btw" | "advisor" | "review";
 export type BackendAccess = "restricted" | "workspace-full";
+export function reviewBackendError(backend: string): string | undefined {
+	if (backend !== "claude" && backend !== "muse") return "Guided Review requires Claude or Muse for file-only inspection. Set the review backend in /bro config; saved reviews remain readable.";
+}
 export type AgySelection = { model: string; effort?: "low" | "medium" | "high" };
 export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 export const GROK_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
@@ -91,8 +93,8 @@ function unexpectedSignalMessage(exitSignal: NodeJS.Signals | null, cli = "Agy")
 }
 
 // Sends to the whole POSIX process group when possible so a misbehaving grandchild dies too, not
-// just the immediate agy process -- child.kill() alone only ever reaches the immediate child.
-function killAgyGroup(child: ChildProcess, signalName: NodeJS.Signals): void {
+// just the immediate child process -- child.kill() alone only ever reaches the immediate child.
+function killProcessGroup(child: ChildProcess, signalName: NodeJS.Signals): void {
 	if (process.platform !== "win32" && typeof child.pid === "number") {
 		try {
 			process.kill(-child.pid, signalName);
@@ -105,7 +107,7 @@ function killAgyGroup(child: ChildProcess, signalName: NodeJS.Signals): void {
 }
 
 // The three causes that stop an in-flight attempt: user cancellation, the host-imposed deadline,
-// and a protocol failure (malformed/inconsistent Agy output). Exactly one is latched -- the first
+// and a protocol failure (malformed/inconsistent backend output). Exactly one is latched -- the first
 // to occur -- and it is never relabeled by a later signal (e.g. a cancel arriving after a deadline
 // already fired stays a timeout, not a cancellation).
 type StopCause = "cancelled" | "timeout" | "protocol";
@@ -126,18 +128,23 @@ const DEFAULT_KILL_ESCALATION_MS = 5_000;
 export function beginAttempt(child: ChildProcess, signal: AbortSignal, deadlineMs: number, killEscalationMs: number): Attempt {
 	let cause: StopCause | undefined;
 	let killTimer: ReturnType<typeof setTimeout> | undefined;
+	let isClosed = false;
 	let finishClose: (value: { code: number | null; exitSignal: NodeJS.Signals | null }) => void;
 	const closed = new Promise<{ code: number | null; exitSignal: NodeJS.Signals | null }>((resolve) => {
-		finishClose = resolve;
-		child.once("close", (code, exitSignal) => resolve({ code, exitSignal }));
+		finishClose = (val) => {
+			isClosed = true;
+			resolve(val);
+		};
+		child.once("close", (code, exitSignal) => finishClose({ code, exitSignal }));
 	});
 
 	const stop = (next: StopCause) => {
 		if (cause) return; // latched: the first stop cause wins
 		cause = next;
-		killAgyGroup(child, "SIGTERM");
+		if (isClosed) return;
+		killProcessGroup(child, "SIGTERM");
 		killTimer = setTimeout(() => {
-			killAgyGroup(child, "SIGKILL");
+			killProcessGroup(child, "SIGKILL");
 			// Detached descendants (or Windows grandchildren) may retain inherited pipes.
 			// Stop waiting on those pipes after escalation; never promote this stop to success.
 			child.stdin?.destroy();
@@ -225,12 +232,12 @@ async function executeArgvPrint(
 	// stdin protocol rather than risking Linux's per-argument byte limit.
 	const stdinPrompt = Buffer.byteLength(request.prompt, "utf8") >= 120_000;
 	const isBtw = request.feature === "btw";
-	const full = isBtw && request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (isBtw ? (full ? 610_000 : 130_000) : 125_000);
+	const full = request.access === "workspace-full";
+	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
 	const printTimeout = full ? "10m" : "2m";
-	const action = isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = isBtw ? "Agy returned no answer for the side question." : "Agy returned no final explanation.";
+	const action = request.feature === "review" ? "complete the guided review request" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = request.feature === "review" ? "Agy returned no response for Guided Review." : isBtw ? "Agy returned no answer for the side question." : "Agy returned no final explanation.";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
@@ -253,7 +260,7 @@ async function executeArgvPrint(
 				...(selection.effort ? ["--effort", selection.effort] : []),
 				"--print-timeout",
 				printTimeout,
-				...(request.continuation ? ["--conversation", request.continuation.id] : []),
+				...(isBtw && request.continuation ? ["--conversation", request.continuation.id] : []),
 				...(stdinPrompt ? ["--input-format", "stream-json"] : ["--print", request.prompt]),
 			],
 			{
@@ -270,7 +277,6 @@ async function executeArgvPrint(
 		let partial = "";
 		let final = "";
 		let conversationId = request.continuation?.id;
-		let parseError: string | undefined;
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -285,44 +291,31 @@ async function executeArgvPrint(
 			child.stdin?.end(`${JSON.stringify({ event: "user", message: { content: request.prompt } })}\n`);
 		}
 
-		const lines = createInterface({ input: child.stdout!, crlfDelay: Infinity });
-		void attempt.closed.then(() => lines.close());
-		try {
-			for await (const line of lines) {
-				if (!line.trim() || attempt.causeOf()) continue;
-				try {
-					if (isBtw) {
-						const parsed = parseBtwAgyLine(line);
-						if (parsed.conversationId) conversationId = parsed.conversationId;
-						if (parsed.error) {
-							parseError = parsed.error;
-							attempt.stop("protocol");
-							break;
-						}
-						if (parsed.delta) {
-							partial += parsed.delta;
-							onProgress?.({ kind: "text", text: partial });
-						}
-						if (parsed.result !== undefined) final = parsed.result;
-					} else {
-						const parsed = parseExplainLine(line);
-						if (parsed.delta) {
-							partial += parsed.delta;
-							onProgress?.({ kind: "text", text: partial });
-						}
-						if (parsed.result !== undefined) final = parsed.result;
-					}
-				} catch (error) {
-					parseError = errorMessage(error);
-					attempt.stop("protocol");
-					break;
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			if (isBtw) {
+				const parsed = parseBtwAgyLine(line);
+				if (parsed.conversationId) conversationId = parsed.conversationId;
+				if (parsed.error) throw new Error(parsed.error);
+				if (parsed.delta) {
+					partial += parsed.delta;
+					onProgress?.({ kind: "text", text: partial });
 				}
+				if (parsed.result !== undefined) final = parsed.result;
+			} else {
+				const parsed = parseExplainLine(line);
+				if (parsed.delta) {
+					partial += parsed.delta;
+					onProgress?.({ kind: "text", text: partial });
+				}
+				if (parsed.result !== undefined) final = parsed.result;
 			}
-		} finally {
-			lines.close();
-		}
+		};
+
+		const finishFraming = frameStdoutLines(child, attempt, "Agy", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const parseError = finishFraming();
 		attempt.dispose();
 		const cause = attempt.causeOf();
 
@@ -348,8 +341,69 @@ async function executeArgvPrint(
 }
 
 // Guards only against a single runaway line with no newline (a protocol break, not a real
-// response size) -- agy's real NDJSON lines are far smaller than this.
-const ADVISOR_MAX_STDOUT_LINE_CHARS = 2_000_000;
+// response size) -- real NDJSON lines across all backends are far smaller than this.
+export const MAX_STDOUT_LINE_CHARS = 2_000_000;
+
+export function frameStdoutLines(
+	child: ChildProcess,
+	attempt: Attempt,
+	backendName: string,
+	onLine: (line: string) => void,
+): () => string | undefined {
+	const oversize = `${backendName} emitted a stdout line over ${MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
+	let buffer = "";
+	let protocolError: string | undefined;
+
+	const fail = (message: string) => {
+		protocolError ??= message;
+		buffer = "";
+		attempt.stop("protocol");
+	};
+
+	child.stdout?.setEncoding("utf8");
+
+	child.stdout?.on("error", (error) => {
+		fail(`${backendName} stdout error: ${errorMessage(error)}`);
+	});
+
+	child.stdout?.on("data", (chunk: string) => {
+		if (attempt.causeOf()) return;
+		const parts = (buffer + chunk).split(/\r?\n/);
+		buffer = parts.pop() ?? "";
+
+		const pendingLen = buffer.endsWith("\r") ? buffer.length - 1 : buffer.length;
+		if (pendingLen > MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > MAX_STDOUT_LINE_CHARS)) {
+			return fail(oversize);
+		}
+
+		for (const line of parts) {
+			if (attempt.causeOf()) return;
+			if (!line.trim()) continue;
+			try {
+				onLine(line);
+			} catch (error) {
+				return fail(errorMessage(error));
+			}
+		}
+	});
+
+	return (): string | undefined => {
+		if (!attempt.causeOf() && buffer.trim()) {
+			const line = buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+			if (line.length > MAX_STDOUT_LINE_CHARS) {
+				fail(oversize);
+			} else if (line.trim()) {
+				try {
+					onLine(line);
+				} catch (error) {
+					fail(errorMessage(error));
+				}
+			}
+		}
+		buffer = "";
+		return protocolError;
+	};
+}
 
 type AdvisorAgyEvent = {
 	event?: string;
@@ -417,9 +471,7 @@ async function executeAdvisorStdin(
 	let stderr = "";
 	let final: string | undefined;
 	let terminalError: string | undefined;
-	let protocolError: string | undefined;
 	let sawTerminal = false;
-	let stdoutBuffer = "";
 
 	child.stderr?.setEncoding("utf8");
 	child.stderr?.on("data", (chunk: string) => {
@@ -455,37 +507,11 @@ async function executeAdvisorStdin(
 		}
 	};
 
-	child.stdout?.setEncoding("utf8");
-	child.stdout?.on("data", (chunk: string) => {
-		stdoutBuffer += chunk;
-		const parts = stdoutBuffer.split(/\r?\n/);
-		stdoutBuffer = parts.pop() ?? "";
-		if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-			protocolError ??= `Agy emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-			stdoutBuffer = "";
-			attempt.stop("protocol");
-			return;
-		}
-		for (const line of parts) {
-			try {
-				handleLine(line);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-				attempt.stop("protocol");
-				return;
-			}
-		}
-	});
+	const finishFraming = frameStdoutLines(child, attempt, "Agy", handleLine);
 
 	const { code, exitSignal } = await attempt.closed;
+	const protocolError = finishFraming();
 	attempt.dispose();
-	if (stdoutBuffer.trim() && !sawTerminal) {
-		try {
-			handleLine(stdoutBuffer);
-		} catch (error) {
-			protocolError ??= errorMessage(error);
-		}
-	}
 
 	const cause = attempt.causeOf();
 	if (cause === "cancelled") return { status: "cancelled", message: "Canceled." };
@@ -542,12 +568,13 @@ async function executeClaude(
 ): Promise<BackendOutcome> {
 	const isAdvisor = request.feature === "advisor";
 	const isBtw = request.feature === "btw";
+	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
-	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const deadlineMs = deadlineMsOverride ?? (full || inspect ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
-	const runDirectory = isAdvisor || isBtw ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	const runDirectory = full || isBtw || inspect ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
 	if (signal.aborted) {
 		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
 		return { status: "cancelled", message: "Canceled." };
@@ -565,7 +592,9 @@ async function executeClaude(
 				"stream-json",
 				"--verbose",
 				"--include-partial-messages",
-				...(full
+				...(inspect
+					? ["--restricted", "--tools", "Read,Grep,Glob", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--permission-mode", "dontAsk"]
+					: full
 					? ["--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--dangerously-skip-permissions"]
 					: ["--tools", "", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--permission-mode", "dontAsk"]),
 				...(isBtw && request.continuation ? ["--resume", request.continuation.id] : []),
@@ -587,8 +616,6 @@ async function executeClaude(
 		let partial = "";
 		let final: string | undefined;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 		let initSessionId: string | undefined;
 		let resultSessionId: string | undefined;
 
@@ -623,6 +650,7 @@ async function executeClaude(
 			}
 			if (isAdvisor && topLevel && event.type === "assistant" && Array.isArray(event.message?.content)) {
 				for (const block of event.message.content as Array<{ type?: unknown; name?: unknown; text?: unknown }>) {
+					if (attempt.causeOf()) break;
 					const label =
 						block?.type === "tool_use" && typeof block.name === "string"
 							? block.name.trim()
@@ -653,43 +681,17 @@ async function executeClaude(
 			}
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Claude emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Claude", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial || undefined;
 		const cause = attempt.causeOf();
 		if (cause === "cancelled") return { status: "cancelled", message: "Canceled.", partialText };
 		if (cause === "timeout") {
-			const during = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+			const during = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
 			return { status: "timeout", message: `Claude timed out ${during}. Run \`/bro doctor\` for setup help.`, partialText };
 		}
 		if (protocolError) return { status: "failure", message: withDoctor(protocolError), partialText };
@@ -710,7 +712,7 @@ async function executeClaude(
 			return { status: "failure", message: withDoctor(`Claude exited without a result event${stderr.trim() ? `: ${stderr.trim()}` : "."}`), partialText };
 		}
 		const text = final.trim();
-		if (!text) return { status: "failure", message: withDoctor(isBtw ? "Claude returned no answer for the side question." : "Claude returned no final answer."), partialText };
+		if (!text) return { status: "failure", message: withDoctor(request.feature === "review" ? "Claude returned no response for Guided Review." : isBtw ? "Claude returned no answer for the side question." : "Claude returned no final answer."), partialText };
 		if (!isBtw) return { status: "success", text };
 		// btw continuation: the session id must be reported, consistent, and (on resume) unchanged.
 		const sessionId = resultSessionId ?? initSessionId;
@@ -771,10 +773,10 @@ async function executeGrok(
 ): Promise<BackendOutcome> {
 	const isAdvisor = request.feature === "advisor";
 	const isBtw = request.feature === "btw";
-	const deadlineMs = deadlineMsOverride ?? (isAdvisor || (isBtw && request.access === "workspace-full") ? 610_000 : isBtw ? 130_000 : 125_000);
-	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = isAdvisor ? "Grok returned no advice." : isBtw ? "Grok returned no answer for the side question." : "Grok returned no final explanation.";
+	const deadlineMs = deadlineMsOverride ?? (request.access === "workspace-full" ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = request.feature === "review" ? "Grok returned no response for Guided Review." : isAdvisor ? "Grok returned no advice." : isBtw ? "Grok returned no answer for the side question." : "Grok returned no final explanation.";
 	const prompt = request.access === "restricted" ? `${GROK_RESTRICTED_PREFIX}\n\n${request.prompt}` : request.prompt;
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
@@ -784,7 +786,7 @@ async function executeGrok(
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 		const promptFile = join(promptDirectory, "prompt.txt");
 		await writeFile(promptFile, prompt, { encoding: "utf8", mode: 0o600 });
-		if (!isAdvisor && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+		if (request.access !== "workspace-full" && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
 		const child = spawn(
@@ -815,8 +817,6 @@ async function executeGrok(
 		let resultSessionId: string | undefined;
 		let final: string | undefined;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -869,6 +869,7 @@ async function executeGrok(
 			}
 			if (isAdvisor && event.type === "assistant" && Array.isArray(message?.content)) {
 				for (const block of message.content as Array<{ type?: unknown; name?: unknown; text?: unknown }>) {
+					if (attempt.causeOf()) break;
 					const label =
 						block?.type === "tool_use" && typeof block.name === "string"
 							? block.name.trim()
@@ -904,37 +905,11 @@ async function executeGrok(
 			terminalError ??= `Grok failed: ${detail}`;
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Grok emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Grok", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial ? { partialText: partial } : {};
 		const cause = attempt.causeOf();
@@ -1034,12 +1009,12 @@ async function executeCodex(
 	const isBtw = request.feature === "btw";
 	const full = request.access === "workspace-full";
 	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
-	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = isAdvisor ? "Codex returned no advice." : isBtw ? "Codex returned no answer for the side question." : "Codex returned no final explanation.";
+	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = request.feature === "review" ? "Codex returned no response for Guided Review." : isAdvisor ? "Codex returned no advice." : isBtw ? "Codex returned no answer for the side question." : "Codex returned no final explanation.";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
-	const runDirectory = isAdvisor || isBtw ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	const runDirectory = full || isBtw ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
 	if (signal.aborted) {
 		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
 		return { status: "cancelled", message: "Canceled." };
@@ -1076,8 +1051,6 @@ async function executeCodex(
 		let final: string | undefined;
 		let sawTerminal = false;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -1133,37 +1106,11 @@ async function executeCodex(
 			}
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Codex emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Codex", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial ? { partialText: partial } : {};
 		const cause = attempt.causeOf();
@@ -1231,11 +1178,12 @@ async function executeMuse(
 ): Promise<BackendOutcome> {
 	const isAdvisor = request.feature === "advisor";
 	const isBtw = request.feature === "btw";
+	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
-	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = isAdvisor ? "Muse returned no advice." : isBtw ? "Muse returned no answer for the side question." : "Muse returned no final explanation.";
+	const deadlineMs = deadlineMsOverride ?? (full || inspect ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = request.feature === "review" ? "Muse returned no response for Guided Review." : isAdvisor ? "Muse returned no advice." : isBtw ? "Muse returned no answer for the side question." : "Muse returned no final explanation.";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 	const promptDirectory = await mkdtemp(join(tmpdir(), "pi-bro-muse-"));
@@ -1245,7 +1193,7 @@ async function executeMuse(
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 		const promptFile = join(promptDirectory, "prompt.txt");
 		await writeFile(promptFile, request.prompt, { encoding: "utf8", mode: 0o600 });
-		if (!isAdvisor && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+		if (!full && !isBtw && !inspect) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 		const workspace = runDirectory ?? request.cwd!;
 
@@ -1256,6 +1204,7 @@ async function executeMuse(
 			"--workspace", workspace,
 			...(!isBtw ? ["--no-session-log"] : []),
 			...(full ? ["--yolo"] : ["--disable-approval", "--disable-write", "--disable-shell"]),
+			...(inspect ? ["--disable-web-tools", "--no-foreign-personal-context"] : []),
 			...(isBtw && request.continuation ? ["--session-id", request.continuation.id] : []),
 			"--model", selection.model,
 			...(selection.effort ? ["--reasoning-effort", selection.effort] : []),
@@ -1279,8 +1228,6 @@ async function executeMuse(
 		let final: string | undefined;
 		let sawTerminal = false;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -1358,37 +1305,11 @@ async function executeMuse(
 			}
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Muse emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Muse", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial ? { partialText: partial } : {};
 		const cause = attempt.causeOf();
@@ -1428,7 +1349,7 @@ async function executeMuse(
 	}
 }
 
-// Single-attempt executor shared by all four features. Never retries (retries are feature-owned,
+// Single-attempt executor shared by all features. Never retries (retries are feature-owned,
 // e.g. advisor's 3-attempt backoff in bro.ts); never spawns a pre-aborted request; on cancellation,
 // host deadline, or a protocol failure, stops the whole POSIX process group (SIGTERM, then SIGKILL
 // after a bounded grace period) before resolving. `options` is for offline tests only -- production
@@ -1443,10 +1364,15 @@ export async function execute(
 	if (
 		(request.access === "workspace-full" && !request.cwd?.trim()) ||
 		(request.feature === "advisor" && request.access !== "workspace-full") ||
+		(request.feature === "review" && (request.access !== "restricted" || !request.cwd?.trim())) ||
 		((request.feature === "explain" || request.feature === "show") && request.access !== "restricted") ||
 		(request.feature !== "btw" && request.continuation)
 	) return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 	const backend = (selection as { backend?: unknown }).backend;
+	if (request.feature === "review") {
+		const error = reviewBackendError(String(backend ?? "agy"));
+		if (error) return { status: "failure", message: error };
+	}
 	// An explicit tag guard: a stale or corrupt runtime tag must fail, never fall through to Agy.
 	if (backend !== undefined && backend !== "agy" && backend !== "claude" && backend !== "grok" && backend !== "codex" && backend !== "muse") {
 		return { status: "failure", message: `Unknown backend ${JSON.stringify(backend)}: pick Agy, Claude, Grok, Codex or Muse in \`/bro config\`.` };
@@ -1454,7 +1380,7 @@ export async function execute(
 	const killEscalationMs = options?.killEscalationMs ?? DEFAULT_KILL_ESCALATION_MS;
 	if (selection.backend === "codex") {
 		// Codex btw always runs (and resumes) in the caller's workspace, even restricted.
-		if (request.feature === "btw" && !request.cwd?.trim()) {
+		if ((request.feature === "btw" || request.feature === "review") && !request.cwd?.trim()) {
 			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 		}
 		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !CODEX_EFFORTS.includes(selection.effort))) {
@@ -1464,7 +1390,7 @@ export async function execute(
 	}
 	if (selection.backend === "muse") {
 		// Muse btw always runs (and resumes) in the caller's workspace, even restricted.
-		if (request.feature === "btw" && !request.cwd?.trim()) {
+		if ((request.feature === "btw" || request.feature === "review") && !request.cwd?.trim()) {
 			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 		}
 		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !MUSE_EFFORTS.includes(selection.effort))) {
@@ -1474,7 +1400,7 @@ export async function execute(
 	}
 	if (selection.backend === "grok") {
 		// Grok btw always runs (and resumes) in the caller's workspace, even restricted.
-		if (request.feature === "btw" && !request.cwd?.trim()) {
+		if ((request.feature === "btw" || request.feature === "review") && !request.cwd?.trim()) {
 			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 		}
 		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !GROK_EFFORTS.includes(selection.effort))) {
@@ -1484,7 +1410,7 @@ export async function execute(
 	}
 	if (selection.backend === "claude") {
 		// Claude btw always runs (and resumes) in the caller's workspace, even restricted.
-		if (request.feature === "btw" && !request.cwd?.trim()) {
+		if ((request.feature === "btw" || request.feature === "review") && !request.cwd?.trim()) {
 			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 		}
 		if (!selection.model.trim() || (selection.effort !== undefined && !CLAUDE_EFFORTS.includes(selection.effort))) {