pi-bro 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.22.0] - 2026-10-11
+
+### Fixed
+
+- Persist settings with atomic replacement and mode 0o600 (#84):
+  - Replace direct `writeFile` with atomic sibling write (`.tmp`) and `rename` to prevent settings corruption on failure, crash, or disk full (`ENOSPC`).
+  - Flush writes before replacement (`flush: true`) and clean up temporary files on failure.
+  - Enforce `mode: 0o600` on replaced settings files so permissions are never loosened.
+  - Resolve symlinks via lstat and realpath before replacement to preserve dotfile-managed configuration symlinks, and reject if an existing symlink target cannot be resolved.
+  - Align on-disk state with modal rollback behavior in `/bro config`.
+
+### Added
+
+- Guided Review (#104): open a PR by URL/number in local Pi to automatically get an explanation and quality assessment, captured Git evidence, findings with fix/check suggestions, diffs and optional private questions. Acquisition uses authenticated `gh` outside the active working tree. Findings remain model proposals, not approval or applied changes.
+- Automatic local remembering of questions/drafts/reading position; reopening the same PR restores the captured revision without a model call. Bare `/bro guided-review` lists saved reviews; `resume` remains an alias. Close saves automatically; Stop and close cancels first. Copy finding copies to the system clipboard without submission.
+- Confirmed same-revision regeneration replaces one current guide and preserves original private context; failed/cancelled generation retains it and save errors offer recovery. There is no guide-version UI or prototype-format migration. Review has its own backend override.
+- Bounded live checks demonstrated an unchanged-caller defect and successful regeneration; manual UX accepted. This is not a general accuracy guarantee, live five-backend matrix or complete #104 scope. Notes, examination tracking, branch/update review and feedback delivery are not implemented.
+
+- Durable advisor steering across sessions in `~/.pi/agent/bro-advisor.md` (#97):
+  - Ingest standing priorities from `bro-advisor.md` alongside session steering (`/bro advisor-steer`).
+  - Labeled prompt composition in `buildAdvisorPrompt`: standing priorities appear under `### Standing priorities (durable across sessions)` and session priorities under `### Session priorities (this session only)`.
+  - Session-specific priorities take precedence over standing defaults where they conflict.
+  - Fail-closed validation rejects files > 64 KB and > 4,000 characters before spawning any backend process.
+  - Doctor reports both `Advisor steering (session)` and `Advisor steering (durable)`.
+  - Tool result context line and details track `steeringSources: { durable, session }` while preserving backwards-compatible `steeringIncluded` boolean.
+  - Retries use a frozen prompt snapshot built prior to `runAdvisorWithRetries`.
+  - Clearing session steering leaves durable steering intact.
+
+### Changed
+
+- Doctor treats an unsupported optional review backend as an informational override hint, not a broken installation; healthy Agy/Grok/Codex defaults still report ready.
+- Review is file-only on Claude/Muse: no shell, write or web tools; Agy/Grok/Codex review calls fail closed without switching backend. Other features retain their access behavior.
+- Capture uses depth-1 head/merge-base trees instead of full history; fetch gets a ten-minute bound while evidence stays offline. Interrupted-capture recovery remains.
+- Removed prototype record migrations after one-time backup/normalization of development records; split validation and formatted review modules/tests to the repository tab style.
+
+- Guided Review UX consistency pass: origin-preserving Back, focused-action Enter, topic-filtered findings, pane-aware paging, visible focus/overflow, selected-item previews and compact full-width 36×18 layout. Discussion follows conversation/composer/actions order; save errors have shared retry controls and failed questions have draft-safe explicit edit/resend. Request errors are separate from model answers, streaming follows again at the bottom, and acquisition/resume/close messages give clearer orientation. Current review behavior, controls, access/storage and recovery are documented in the user guide; developer/testing guidance records its implementation rules and verification limits. Review itself has no publication action.
+- Remove dead declarations and stale backend naming (#90):
+  - Enable native TypeScript unused checks (`noUnusedLocals`, `noUnusedParameters`) in `tsconfig.json`.
+  - Remove verified unused declarations across `bro.ts`, `backend.test.ts`, `benchmark/run.ts`, `codex.test.ts`, and `release.test.ts`.
+  - Drop pass-through re-exports from `bro.ts` (`agyFailureMessage`, `agySelection`, `advisorFlagErrorHint`, `parseBtwAgyLine`); tests and consumers import them directly from `backend.ts`.
+  - Rename multi-backend facilities with obsolete Agy prefixes: `runAgyText` -> `runBackendText` in `bro.ts` and `killAgyGroup` -> `killProcessGroup` in `backend.ts`.
+  - Modernize outdated single-backend and pre-extraction comments.
+- Separate Bro responsibilities and unify settings and backend-selection policy (#83):
+  - Extract `settings.ts` (schema, typed `EXTERNAL_BACKENDS` metadata, selection policy, pure transitions, and file persistence).
+  - Extract `sources.ts` (self-contained document text extraction and public web scraping with SSRF protection).
+  - Extract `config-ui.ts` (`/bro config` modal, setting items, and async save serialization).
+  - Extract `util.ts` (shared leaf utility helpers).
+  - Unify legacy flat and v2 settings parsing into one converged validation pipeline in `settings.ts`, eliminating duplicate validation branches.
+  - Initialize clean version 2 settings on fresh installations in `ensureSettingsFile()`.
+  - Share pure state transitions (`applyModelChange`, `applyEffortChange`) across default and capability override rows.
+  - Fix Agy variant model reselection bug where resolved effort from suffixed variants was lost.
+  - Consolidate CLI version probes in `/bro doctor` into a single `checkCliVersion` helper.
+
 ## [0.21.0] - 2026-10-04
 
 ### Added

package/README.md

@@ -1,14 +1,11 @@
 # pi-bro
 
-Turn a dense AI reply, pasted text, local document, or public webpage into a
-plain-language explanation — or open a separate side conversation with
-`/bro btw` — without adding anything to your main agent's context.
+Turn a dense AI reply, pasted text, document or webpage into a plain-language explanation. Ask side questions with `/bro btw`, or understand and assess a PR with `/bro guided-review`. These windows do not add their discussions to your main agent's context.
 
 `pi-bro` is an extension for [Earendil Pi](https://github.com/earendil-works/pi).
 Experimental [PiG 0.3.0 compatibility](docs/pig-compatibility.md) uses the same npm package and requires Node.js. See the compatibility notes for verified coverage and the PiG RPC tool-exclusion limitation.
 It opens explanations in a separate modal and runs them through a CLI backend
-you already have installed and signed in to. Explain, show, BTW, and the
-advisor all work across five backends:
+you already have installed and signed in to. Explain, show, BTW and advisor use five backend adapters. Guided Review generation/questions require Claude or Muse file-only inspection (live verification varies by feature):
 
 - [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`) — the default for new settings
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
@@ -75,7 +72,9 @@ text directly captures a new source the same way.
 | `/bro doctor` | Check Bro's settings, preferences, and each selected backend, with the effective backend/model/effort per feature. |
 | `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
 | `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](#preferences). |
-| `/bro config` | Open an interactive settings screen for the shared default backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor) overrides. |
+| `/bro config` | Open settings for the shared backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor/review) overrides. |
+| `/bro guided-review <PR number or URL>` | Automatically explain and assess a captured PR in local Pi, with source evidence and optional private questions. Opening the same PR restores its saved review. |
+| `/bro guided-review` | List saved reviews; `resume` is an alias. |
 | `/bro btw [question]` | Open a side conversation in a modal, seeded with recent main-session context. Starts conversation-only; type `/mode` inside to toggle full permission (read and edit the workspace) without losing the thread. |
 | `/bro advisor` | Quick notice of whether the executor's `bro_advisor` tool is available right now, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`. |
 | `/bro advisor-steer` | View, edit, save, or clear the one persistent steering brief the advisor always sees. |
@@ -128,6 +127,44 @@ selection may be unavailable or visually extend outside the modal depending on
 your terminal mode; press **C** to copy the complete explanation reliably.
 
 
+## Guided Review
+
+**Open a PR → read and investigate → leave when satisfied.** Bro automatically
+prepares an explanation and quality assessment with captured code, ranked
+findings and suggested fixes/checks. Asking private questions is optional.
+Nothing is automatically applied or posted to GitHub.
+
+```text
+/bro guided-review https://github.com/OWNER/REPO/pull/123
+```
+
+Local Pi interactive mode, Git, authenticated `gh`, and Claude or Muse configured for review
+are required. A new review makes a model call using that backend's account.
+Opening the same PR restores its saved review without another model call.
+Bare `/bro guided-review` lists saved reviews (`resume` is an alias).
+
+Contents holds Overview, topics, Findings, Coverage, Changed files and Your
+questions. Enter opens an item or focuses contextual actions; Enter on a
+highlighted action activates it. Tab changes focus. Esc goes back, then closes
+from Contents. Your work is saved automatically; **Close** leaves normally,
+and **Stop and close** cancels active work before saving and leaving.
+
+Optional conveniences:
+- **Copy finding** copies its text to the system clipboard; nothing is submitted.
+- **Regenerate guide** makes a confirmed model call about the **same captured
+  revision**. Success replaces the guide while retaining original private
+  discussion context; failure keeps it. It does not fetch later commits.
+
+Reopening also keeps the captured revision, even after the author pushes.
+Findings are model suggestions, not approval; citations show real locations,
+not proof of the conclusion. Review uses Claude or Muse file-only inspection: shell, writes and web tools are disabled. Agy/Grok/Codex review requests fail clearly; choose a review override in `/bro config`. Saved reviews remain readable with any selection. Repository text can still mislead the model; tool restrictions are not proof of its conclusions.
+Use `pi --tui-mode fullscreen` for pane-local wheel scrolling.
+
+See the [Guided Review guide](docs/guided-review.md) for controls, calls and
+costs, source freshness, access/privacy, local storage, recovery and current
+scope. Notes, examination tracking, branch/update review and feedback delivery
+are not implemented.
+
 ## Bro btw (side conversation)
 
 `/bro btw` opens a separate multi-turn conversation in a modal, so you can ask
@@ -201,18 +238,21 @@ presence, and backend compatibility (for Agy, a minimum CLI version with an
   return advice, leaving edits to the executor, but that boundary is a
   behavioral prompt instruction rather than an enforced sandbox constraint, so
   treat its findings as advice to verify, not a guaranteed hands-off review.
-- **Steering**: `/bro advisor-steer` opens an editor for one persistent
-  steering brief — e.g. "quick prototype; keep A and B careful, everything
-  else minimal" — that the advisor always reads. **Ctrl+S** saves and keeps
-  the editor open; **Enter** or **Shift+Enter** inserts a newline; **Ctrl+K**
-  clears both the saved brief and draft while staying open; **Ctrl+C** copies
-  the entire current draft, including unsaved edits; and **Esc** closes without
-  saving unsaved edits. The brief is **never added to Pi's conversation or
-  sent to the main model** — the advisor is the only thing that reads it.
-- **Persistence**: the steering brief persists with the Pi session (not
-  globally, not per project) as custom extension data in the session file and
-  is restored on resume or reload. Forking a session inherits it; edits made
-  after the fork are independent of the original branch.
+- **Steering**: The advisor reads standing priorities from `~/.pi/agent/bro-advisor.md`
+  and session-specific priorities from `/bro advisor-steer`.
+  `/bro advisor-steer` opens an editor for one session steering brief — e.g. "quick
+  prototype; keep A and B careful, everything else minimal". Session steering takes
+  precedence over durable standing defaults where they conflict.
+  **Ctrl+S** saves and keeps the editor open; **Enter** or **Shift+Enter** inserts
+  a newline; **Ctrl+K** clears both the saved session brief and draft while staying open;
+  **Ctrl+C** copies the entire current draft, including unsaved edits; and **Esc**
+  closes without saving unsaved edits. Neither steering source is **ever added to Pi's
+  conversation or sent to the main model** — the advisor is the only thing that reads them.
+- **Persistence**: standing defaults persist across all sessions in `~/.pi/agent/bro-advisor.md`.
+  The session steering brief persists with the Pi session as custom extension data in the
+  session file (`bro-advisor-steering`) and is restored on resume or reload. Forking a
+  session inherits session steering; edits made after the fork are independent of the
+  original branch. Clearing session steering leaves durable steering intact.
 - **Retries**: on an invocation failure (not a completed answer — "I need
   more evidence" is a normal result, not a failure), Bro retries with the
   identical snapshot, steering, and question: once after 5 seconds, once more
@@ -717,7 +757,7 @@ succeed.
 ## Settings
 
 Use `/bro config` to review or change the shared default backend/model/effort
-and any per-capability (explain/show/btw/advisor) overrides, the explanation
+and any per-capability (explain/show/btw/advisor/review) overrides, the explanation
 mode, and the default show turn count. Changes save immediately. Esc inside a
 picker cancels that pick; Esc on the settings screen closes it, keeping
 whatever was already saved. A failed save (for example, a read-only file) is
@@ -770,13 +810,13 @@ credentials, and does not copy credentials or rewrite backend configuration.
 Each backend and your model provider may retain sessions, logs, and request
 data under their own settings and policies.
 
-| | Explain / show | BTW conversation-only | BTW full permission | Advisor |
-| --- | --- | --- | --- | --- |
-| **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
-| **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
-| **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
-| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed |
-| **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) |
+| | Explain / show | BTW conversation-only | BTW full permission | Advisor | Guided Review |
+| --- | --- | --- | --- | --- | --- |
+| **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Unavailable; choose Claude/Muse |
+| **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Restricted Read/Grep/Glob only; confined checkout, no persistence |
+| **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Unavailable; choose Claude/Muse |
+| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed | Unavailable; command execution is not allowed for review |
+| **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) | Captured checkout; writes/shell/web disabled, no session log |
 
 - Grok always runs with its sandbox off and permissions bypassed; its tools,
   hooks, skills, plugins, and MCP may remain available. "Answer only from the
@@ -805,7 +845,7 @@ data under their own settings and policies.
 ### Configuration precedence
 
 When resolving backend, model, and reasoning effort:
-1. **Per-capability override**: `overrides.<capability>` (`explain`, `show`, `btw`, or `advisor`) pins that capability's complete selection.
+1. **Per-capability override**: `overrides.<capability>` (`explain`, `show`, `btw`, `advisor`, or `review`) pins that capability's complete selection.
 2. **Shared default**: otherwise the capability inherits `default` (root `model`/`effort` in older flat files).
 3. **Agy catalog normalization**: for Agy selections, Bro maps suffixed variant IDs and handles fixed-effort models.
 4. **Initial file creation only**: `PI_BRO_MODEL` has no effect once the settings file exists.
@@ -826,7 +866,7 @@ When shaping an answer, each part has one owner:
 ## Preferences
 
 Tell Bro about yourself and how you like answers. Bro adds what you write to
-every explain, `/bro show`, and `/bro btw` prompt as a labelled section,
+every explain, `/bro show`, `/bro btw`, and Guided Review prompt as a labelled section,
 alongside its own instructions. It never replaces them: modes, **M**, and the
 source rules keep working. The advisor never receives your preferences; use
 `/bro advisor-steer` for it.
@@ -860,11 +900,11 @@ that is set):
 - **What preferences can change**: wording, tone, technical depth, length in
   BTW, and the answer language. If you name a language, code, commands, paths,
   names, and numbers still stay exactly as written. In `/bro show`,
-  preferences only change wording and language. A per-run choice (the mode,
-  **M**, a Show steering query, or what a BTW question asks for) wins over a
+  preferences only change wording and language. Guided Review also receives preferences for explanation/answer wording; they do not override its evidence or review rules. A per-run choice (the mode,
+  **M**, a Show steering query, or what a BTW/review question asks for) wins over a
   standing preference.
 - **Limit**: 4,000 characters, because the text goes with every request. A
-  longer file stops explain, Show, and BTW with an error until you trim it;
+  longer file stops explain, Show, BTW, and Guided Review with an error until you trim it;
   Bro never cuts it silently. `/bro doctor` reports the problem, and the
   editor still opens the file so you can fix it.
 - **BTW threads**: when your preferences change, the next side question starts
@@ -886,8 +926,9 @@ read. Move what you want to keep into `/bro preferences`, and choose
   seeded main-session conversation text (plus earlier turns when a native
   session is reseeded) to the selected backend. In full permission mode the
   side agent can additionally read and edit the workspace.
+- **Guided Review requests**: PR identity/description, captured diff, relevant private discussion and preferences go to the selected backend, which can inspect captured files using Claude/Muse read-only tools. Main-session context is not attached. Review shell/write/web tools are disabled; Claude file tools are confined with `--restricted`, Muse uses workspace-scoped inspection. Prompt injection can still corrupt conclusions or reveal captured content to the provider; this is not a general confidentiality guarantee. See [Guided Review access and storage](docs/guided-review.md#access-privacy-and-storage).
 - **Preferences**: `bro-preferences.md` is sent with every explain, Show,
-  and BTW request to the selected backend. It is never sent to the advisor or
+  BTW, and Guided Review request to the selected backend. It is never sent to the advisor or
   to Pi's main model.
 - **Advisor requests**: `bro_advisor` sends the executor agent's system
   instructions, active tool list (excluding `bro_advisor`), ordered
@@ -904,10 +945,12 @@ read. Move what you want to keep into `/bro preferences`, and choose
   steering brief to Pi's conversation history or main-agent context. BTW text
   reaches the main editor only through `/insert` or `/insert-all`, and advisor
   results appear as normal tool results in the executor's transcript.
+- **Saved reviews**: Guided Review records, questions, drafts and captured Git source persist under the host's `getAgentDir()/bro-reviews/`. No automatic cleanup or sync is provided; see [storage and removal](docs/guided-review.md#access-privacy-and-storage).
 - **Memory**: the latest explanation (for `/bro open`) and the BTW thread live
   only in process memory and clear when you switch Pi sessions, reload
   extensions, or quit Pi. Backend-native sessions can persist independently.
-  The advisor steering brief is stored as session-scoped extension data
+  Standing advisor priorities are stored in `~/.pi/agent/bro-advisor.md`, and
+  the session steering brief is stored as session-scoped extension data
   (`bro-advisor-steering`) in the session file.
 - **File safety**: `/bro file` reads only regular files whose resolved path is
   inside Pi's current workspace, including after resolving symlinks. Bro's
@@ -925,7 +968,7 @@ read. Move what you want to keep into `/bro preferences`, and choose
   Bro writes it to `/tmp/pi-bro-<uid>/bro-show-<hash>.html` with a restrictive
   Content-Security-Policy, and opens it in your browser only when you press
   **O**. **C** copies the full reply, including the HTML.
-- **Clipboard**: **C**, `/copy`, and `/copy-all` copy text to your system
+- **Clipboard**: **C**, `/copy`, `/copy-all`, and Guided Review's Copy finding copy text to your system
   clipboard, where your operating system or clipboard manager may retain it.
 
 ## Troubleshooting and current limits
@@ -953,8 +996,8 @@ tool before giving it to Bro.
 - HTML diagrams open in your default browser; pressing **O** on a remote or
   headless session with no display reports the failure instead of opening
   anything.
-- Keeps only the latest explanation in memory and does not store history or
-  export directly to files.
+- Explain keeps only the latest result in memory and does not export directly to files. Guided Review separately persists review records and captured source.
+- Guided Review is local-Pi interactive only, keeps its captured revision on reopen, and does not publish, review a branch or fetch later PR changes. See [review recovery and limits](docs/guided-review.md#if-something-goes-wrong).
 - Bro temporarily captures mouse input while its modal is open so mouse-wheel
   and trackpad scrolling work in regular and fullscreen modes. Native mouse
   selection may be unavailable or visually extend outside the Bro window;
@@ -968,7 +1011,7 @@ npm test
 pi --tui-mode fullscreen -e ./bro.ts
 ```
 
-`npm test` uses fake `agy`, `claude`, and `grok` executables and never calls an
+`npm test` uses fake `agy`, `claude`, `grok`, `codex`, and `muse` executables and never calls an
 external model. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the code
 map and invariants, [docs/TESTING.md](docs/TESTING.md) for the manual
 end-to-end checklist, and [docs/README.md](docs/README.md) for the docs index.

package/backend.ts

@@ -3,14 +3,17 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-// 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;
@@ -90,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);
@@ -104,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";
@@ -139,9 +142,9 @@ export function beginAttempt(child: ChildProcess, signal: AbortSignal, deadlineM
 		if (cause) return; // latched: the first stop cause wins
 		cause = next;
 		if (isClosed) return;
-		killAgyGroup(child, "SIGTERM");
+		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();
@@ -229,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." };
 
@@ -257,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]),
 			],
 			{
@@ -565,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." };
@@ -588,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] : []),
@@ -685,7 +691,7 @@ async function executeClaude(
 		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 };
@@ -706,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;
@@ -767,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." };
@@ -780,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(
@@ -1003,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." };
@@ -1172,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-"));
@@ -1186,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!;
 
@@ -1197,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] : []),
@@ -1341,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
@@ -1356,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\`.` };
@@ -1367,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))) {
@@ -1377,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))) {
@@ -1387,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))) {
@@ -1397,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))) {