pi-bro 0.21.0 → 0.22.0

package/config-ui.ts

@@ -0,0 +1,325 @@
+import {
+	type Component,
+	type SelectItem,
+	type SettingItem,
+	Container,
+	Input,
+	SelectList,
+	SettingsList,
+	Text,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import {
+	type ExtensionCommandContext,
+	getSelectListTheme,
+	getSettingsListTheme,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type AgyModelFamily,
+	type BroSettings,
+	type Capability,
+	type ExternalBackend,
+	CAPABILITIES,
+	CAPABILITY_LABELS,
+	EXTERNAL_BACKENDS,
+	applyEffortChange,
+	applyModelChange,
+	capabilityBackend,
+	capabilityOverride,
+	capabilityPair,
+	effortDisplay,
+	resolveModelEffort,
+	withCapabilityOverride,
+} from "./settings.ts";
+import { BRO_MODES, parseBroMode } from "./prompt.ts";
+import { errorMessage } from "./util.ts";
+
+export type Theme = ExtensionCommandContext["ui"]["theme"];
+export type TuiLike = {
+	readonly mode: "regular" | "fullscreen";
+	readonly terminal?: { rows?: number; columns?: number; write?: (data: string) => void };
+	requestRender(): void;
+};
+
+const SHOW_TURNS_PRESETS = [1, 2, 3, 5, 8];
+
+function showTurnsValues(current: number): string[] {
+	return [...new Set([...SHOW_TURNS_PRESETS, current])].sort((a, b) => a - b).map(String);
+}
+
+// Testable core: takes settings/catalog/persist as plain arguments so smoke tests can drive
+// the exact interaction (submenus, cancel, cycling, save failure) without a real Agy process
+// or settings file. showBroConfigModal in bro.ts wires this to the real ctx/pi/filesystem.
+export function createConfigModal(
+	initialSettings: BroSettings,
+	families: AgyModelFamily[],
+	persistSettings: (settings: BroSettings) => Promise<void>,
+): (tui: TuiLike, theme: Theme, keybindings: unknown, done: (value?: void) => void) => Component & { dispose?(): void } {
+	return (tui, theme, _keybindings, done) => {
+		let settings = initialSettings;
+		// The last settings actually confirmed on disk. A failed save reverts `settings` (and the
+		// whole displayed row set) back to this, so the screen never shows state that doesn't exist.
+		let savedSettings = initialSettings;
+		// Only one persistSettings call is ever in flight. A change that arrives while one is
+		// already running is coalesced into `queued` (overwriting any earlier queued change) rather
+		// than firing a second concurrent write — this is what keeps writes serialized and makes
+		// sure the on-disk file always converges on the latest intent instead of a stale one that
+		// happened to finish last.
+		let saving = false;
+		let queued: BroSettings | undefined;
+		// Esc while a save is in flight must not close past an unshown result: it requests a close
+		// that only actually happens once the in-flight (and any coalesced) save has settled, and
+		// only if it succeeded — a failure cancels the pending close so its notice stays visible.
+		let closeRequested = false;
+
+		const modelPicker = (current: string, pickerDone: (value?: string) => void, capability?: Capability) => {
+			const defaultResolved = resolveModelEffort({ model: settings.model, effort: settings.effort }, families);
+			const options: SelectItem[] = [
+				...(capability ? [{ value: "__default__", label: `Default (${defaultResolved.family?.label ?? settings.model})` }] : []),
+				...families.map((family) => ({
+					value: family.id,
+					label: `${family.label}${family.efforts.length ? "" : " · fixed effort"}`,
+				})),
+				// Alternative CLI entries stay last so existing Agy keyboard navigation is unaffected.
+				...Object.values(EXTERNAL_BACKENDS).flatMap((meta) =>
+					meta.models.map((model) => ({
+						value: `${meta.prefix}${model.id}`,
+						label: `${model.label} · ${meta.name}`,
+					})),
+				),
+			];
+			for (const meta of Object.values(EXTERNAL_BACKENDS)) {
+				options.push({ value: `__${meta.name}_custom__`, label: `${meta.label} · custom model ID…` });
+			}
+			const input = new Input();
+			let enteringBackend: ExternalBackend | undefined;
+			input.onSubmit = (value) => {
+				if (value.trim() && enteringBackend) {
+					const meta = EXTERNAL_BACKENDS[enteringBackend];
+					pickerDone(`${meta.prefix}${value.trim()}`);
+				}
+			};
+			const picker = new SelectList(options, Math.min(options.length, 8), getSelectListTheme());
+			const selectedIndex = capability && current === "Default" ? 0 : options.findIndex((option) => option.value === current);
+			picker.setSelectedIndex(Math.max(0, selectedIndex));
+			picker.onSelect = (item) => {
+				const custom = (Object.keys(EXTERNAL_BACKENDS) as ExternalBackend[]).find((b) => item.value === `__${b}_custom__`);
+				if (custom) { enteringBackend = custom; tui.requestRender(); }
+				else pickerDone(item.value);
+			};
+			picker.onCancel = () => pickerDone();
+			const customLabel = () => enteringBackend ? EXTERNAL_BACKENDS[enteringBackend].label : "";
+			return {
+				render: (width: number) => enteringBackend ? [`${customLabel()} model ID (Enter saves, Esc cancels)`, ...input.render(width)] : picker.render(width),
+				invalidate: () => { picker.invalidate(); input.invalidate(); },
+				handleInput: (data: string) => {
+					if (enteringBackend && matchesKey(data, "escape")) pickerDone();
+					else if (enteringBackend) input.handleInput(data);
+					else picker.handleInput(data);
+				},
+			};
+		};
+
+		const modelItem: SettingItem = { id: "model", label: "Default model", currentValue: settings.model, submenu: modelPicker };
+		const effortItem: SettingItem = { id: "effort", label: "Default effort", currentValue: "" };
+		const modeItem: SettingItem = { id: "mode", label: "Explain mode", currentValue: settings.mode, values: [...BRO_MODES] };
+		const showTurnsItem: SettingItem = {
+			id: "showTurns",
+			label: "Show turns",
+			currentValue: String(settings.showTurns),
+			values: showTurnsValues(settings.showTurns),
+		};
+		const capabilityItems = Object.fromEntries(
+			CAPABILITIES.map((capability) => [
+				capability,
+				{
+					model: {
+						id: `${capability}Model`,
+						label: `${CAPABILITY_LABELS[capability]} model`,
+						currentValue: "Default",
+						submenu: (current: string, pickerDone: (value?: string) => void) => modelPicker(current, pickerDone, capability),
+					} as SettingItem,
+					effort: {
+						id: `${capability}Effort`,
+						label: `${CAPABILITY_LABELS[capability]} effort`,
+						currentValue: "",
+					} as SettingItem,
+				},
+			]),
+		) as Record<Capability, { model: SettingItem; effort: SettingItem }>;
+
+		function refresh(): void {
+			const defaultBackend = settings.backend ?? "agy";
+			const def = resolveModelEffort({ backend: settings.backend, model: settings.model, effort: settings.effort }, families);
+			modelItem.currentValue =
+				defaultBackend in EXTERNAL_BACKENDS
+					? `${EXTERNAL_BACKENDS[defaultBackend as ExternalBackend].prefix}${settings.model}`
+					: (def.family?.id ?? settings.model);
+			effortItem.currentValue = effortDisplay(def, defaultBackend);
+			effortItem.values =
+				defaultBackend in EXTERNAL_BACKENDS
+					? ["default", ...EXTERNAL_BACKENDS[defaultBackend as ExternalBackend].efforts]
+					: def.family?.efforts.length
+						? [...def.family.efforts]
+						: undefined;
+			modeItem.currentValue = settings.mode;
+			showTurnsItem.currentValue = String(settings.showTurns);
+			showTurnsItem.values = showTurnsValues(settings.showTurns);
+
+			for (const capability of CAPABILITIES) {
+				const override = capabilityOverride(settings, capability);
+				const backend = capabilityBackend(settings, capability);
+				const resolved = resolveModelEffort(capabilityPair(settings, capability), families);
+				const rows = capabilityItems[capability];
+				rows.model.currentValue = !override
+					? "Default"
+					: backend in EXTERNAL_BACKENDS
+						? `${EXTERNAL_BACKENDS[backend as ExternalBackend].prefix}${override.model}`
+						: (resolved.family?.id ?? override.model);
+				rows.effort.currentValue = effortDisplay(resolved, backend);
+				rows.effort.values =
+					backend in EXTERNAL_BACKENDS
+						? ["default", ...EXTERNAL_BACKENDS[backend as ExternalBackend].efforts]
+						: resolved.family?.efforts.length
+							? [...resolved.family.efforts]
+							: undefined;
+			}
+		}
+		refresh();
+
+		const items: SettingItem[] = [
+			modelItem,
+			effortItem,
+			modeItem,
+			showTurnsItem,
+			...CAPABILITIES.flatMap((capability) => [capabilityItems[capability].model, capabilityItems[capability].effort]),
+		];
+
+		const noticeText = new Text("");
+
+		function runSave(toSave: BroSettings): void {
+			saving = true;
+			void persistSettings(toSave)
+				.then(() => {
+					savedSettings = toSave;
+					noticeText.setText("");
+				})
+				.catch((error: unknown) => {
+					// Restore the last state that is actually on disk: showing the failed, unsaved
+					// value would let the screen claim a setting that doesn't really exist.
+					settings = savedSettings;
+					queued = undefined;
+					closeRequested = false;
+					refresh();
+					noticeText.setText(theme.fg("warning", `Could not save settings: ${errorMessage(error)}. Reverted to the last saved settings.`));
+				})
+				.finally(() => {
+					saving = false;
+					tui.requestRender();
+					if (queued !== undefined) {
+						const next = queued;
+						queued = undefined;
+						runSave(next);
+					} else if (closeRequested) {
+						closeRequested = false;
+						done(undefined);
+					}
+				});
+		}
+
+		function persist(toSave: BroSettings): void {
+			if (saving) {
+				queued = toSave;
+				return;
+			}
+			runSave(toSave);
+		}
+
+		const onChange = (id: string, newValue: string) => {
+			if (id === "model") {
+				const current = { backend: settings.backend, model: settings.model, effort: settings.effort };
+				const next = applyModelChange(current, newValue, families);
+				if (!next) return;
+				if (next.backend === undefined) {
+					const { backend: _dropped, ...rest } = settings;
+					settings = { ...rest, model: next.model, effort: next.effort };
+				} else {
+					settings = { ...settings, backend: next.backend, model: next.model, effort: next.effort };
+				}
+			} else if (id === "effort") {
+				const current = { backend: settings.backend, model: settings.model, effort: settings.effort };
+				const next = applyEffortChange(current, newValue, families);
+				if (!next) return;
+				settings = { ...settings, model: next.model, effort: next.effort };
+			} else if (id === "mode") {
+				const mode = parseBroMode(newValue);
+				if (!mode) return;
+				settings = { ...settings, mode };
+			} else if (id === "showTurns") {
+				const turns = Number(newValue);
+				if (!Number.isInteger(turns) || turns < 1) return;
+				settings = { ...settings, showTurns: turns };
+			} else {
+				const capability = CAPABILITIES.find((item) => id === `${item}Model` || id === `${item}Effort`);
+				if (!capability) return;
+				if (id === `${capability}Model`) {
+					if (newValue === "__default__") {
+						settings = withCapabilityOverride(settings, capability, undefined);
+					} else {
+						const current = capabilityPair(settings, capability);
+						const next = applyModelChange(current, newValue, families);
+						if (!next) return;
+						settings = withCapabilityOverride(settings, capability, next);
+					}
+				} else {
+					const existing = capabilityOverride(settings, capability);
+					const current = existing ?? {
+						backend: capabilityBackend(settings, capability) === "agy" ? undefined : capabilityBackend(settings, capability),
+						model: settings.model,
+						effort: capabilityPair(settings, capability).effort,
+					};
+					const next = applyEffortChange(current, newValue, families);
+					if (!next) return;
+					settings = withCapabilityOverride(settings, capability, next);
+				}
+			}
+			refresh();
+			tui.requestRender();
+			persist(settings);
+		};
+
+		const requestClose = () => {
+			if (saving) {
+				closeRequested = true;
+				return;
+			}
+			done(undefined);
+		};
+
+		const settingsList = new SettingsList(items, Math.min(items.length + 2, 18), getSettingsListTheme(), onChange, requestClose);
+		const container = new Container();
+		container.addChild(new Text(theme.fg("accent", theme.bold("Bro · config"))));
+		container.addChild(new Text(theme.fg("dim", "Shared defaults, with optional overrides per capability")));
+		container.addChild(settingsList);
+		container.addChild(noticeText);
+		container.addChild(new Text(theme.fg("dim", "↑/↓ navigate · Enter select/change · Esc back/close")));
+
+		return {
+			render: (w: number) => {
+				const inner = Math.max(1, w - 4);
+				const border = (left: string, right: string) => theme.fg("border", left + "─".repeat(inner + 2) + right);
+				return [border("┌", "┐"), ...container.render(inner).map(line => {
+					const text = truncateToWidth(line, inner, "");
+					return theme.fg("border", "│") + " " + text + " ".repeat(Math.max(0, inner - visibleWidth(text))) + " " + theme.fg("border", "│");
+				}), border("└", "┘")];
+			},
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				settingsList.handleInput?.(data);
+				tui.requestRender();
+			},
+		};
+	};
+}

package/docs/README.md

@@ -1,8 +1,10 @@
 # pi-bro docs
 
 - [README](../README.md) — the user guide (authoritative for behavior).
+- [guided-review.md](guided-review.md) — current Guided Review behavior, optional controls, access/storage and limits.
 - [DEVELOPMENT.md](DEVELOPMENT.md) — code map, settings and BTW continuation model, invariants, test commands.
 - [TESTING.md](TESTING.md) — the manual end-to-end checklist across backends.
+- [dev/README.md](../dev/README.md) — manual review launcher and profile/call precautions (not shipped).
 - [plans/](plans/README.md) — historical design notes and plans; not the current spec.
 - [images/](images/) — screenshots used by the README.
 - [benchmark/README.md](../benchmark/README.md) — the manual, live prompt benchmark.

package/docs/guided-review.md

@@ -0,0 +1,131 @@
+# Guided Review
+
+**Understand and evaluate a PR, without turning your main Pi conversation into a review transcript.**
+
+The normal journey is: **open a PR → read and investigate → leave when satisfied.** Bro automatically prepares both an explanation and a quality assessment. Asking questions is optional. You do not need to copy findings, mark progress or submit feedback to finish.
+
+## Open a review
+
+Requirements: local Pi interactive mode, Git, authenticated GitHub CLI (`gh`), and Claude or Muse configured for review. Run `gh auth status` to check GitHub authentication; `/bro doctor` checks Bro's selected backend setup but does not prove GitHub access or model connectivity.
+
+```text
+/bro guided-review https://github.com/OWNER/REPO/pull/123
+```
+
+A URL works even when your current workspace belongs to a different repository. A PR number alone uses the current GitHub repository:
+
+```text
+/bro guided-review 123
+```
+
+A **new** review captures the PR's base/head commits outside your working tree and automatically makes one model request. Subsequent questions each make another request. Calls use your selected backend CLI's account and billing—not Pi's model account. Bro does not automatically retry a failed generation or switch backends.
+
+For fullscreen mouse scrolling, start Pi with:
+
+```sh
+pi --tui-mode fullscreen
+```
+
+Opening the **same PR again** restores its saved review without another model call. Bare `/bro guided-review` lists saved reviews; `/bro guided-review resume` remains an alias for that list.
+
+**Reopening keeps the captured code.** It does not fetch a new comparison when the author pushes commits. Opening by URL/number checks current metadata and reports newer source, but continues the saved capture. The saved-review picker does not check freshness. Reviewing newer revisions is not implemented.
+
+## Read and investigate
+
+Contents is on the left; reading and contextual actions are on the right. Narrow terminals show one pane at a time. The supported minimum is 36×18; smaller terminals show resize guidance with a working exit.
+
+| Destination | What you get |
+| --- | --- |
+| Overview | Purpose, main concerns and overall assessment |
+| Topics | Short explanations with captured code and related findings |
+| Findings | Ranked concerns, author questions, suggested fixes/checks and evidence |
+| Across the change | Findings that do not belong to one topic, when present |
+| Coverage and limitations | Reported inspection, uncited files, omissions and unverified execution |
+| Changed files | The full changed-file list and one actual diff at a time |
+| Your questions | Private discussions and unsent drafts, including earlier context |
+
+A finding is a proposal, not a proven defect or an applied patch. **No findings is not approval.** Source blocks and diffs come from captured Git objects, not model quotations. Valid citations establish locations; they do not certify the reasoning or complete inspection. Coverage paths and access explanations are model-reported. Suggested tests have not been independently executed by Bro.
+
+The preparation prompt investigates the whole change and relevant unchanged callers/tests before organizing topics. It supplies the first 100,000 diff characters, with an omission marker for larger changes; the backend can inspect the captured checkout beyond that seed. Follow-up questions include at most the latest 12 relevant turns and disclose older omitted discussion. A saved guide without an assessment is explicitly labelled unassessed. Prototype formats are not supported; unreadable files are left unchanged.
+
+The generation header shows observable application stages and elapsed time—not a percentage or invented model checklist.
+
+### Controls
+
+| Control | Behavior |
+| --- | --- |
+| ↑ / ↓ | Select entries or scroll the focused reading area |
+| Page Up / Page Down | Page the focused pane |
+| Enter | Read a destination, open a list item, or focus contextual actions |
+| Enter on a highlighted action | Activate it |
+| Tab / Shift+Tab | Move focus in screen order |
+| Esc | Return to where you came from; from Contents, close |
+| Close | Save automatically and leave |
+| Stop and close | Stop active work, await cancellation, save partial work, then leave |
+
+In fullscreen mode, the wheel scrolls the pane under the pointer without moving its list selection or keyboard focus. Reading an active answer pauses following; deliberately returning to the bottom resumes it. In regular terminal mode, the wheel belongs to terminal scrollback.
+
+## Ask privately, if needed
+
+Choose Ask from a topic, finding, file or Overview. Type in the composer below the discussion. **Enter in the composer sends the question**; leaving without sending retains the draft. Stop response cancels an answer. Stop preparation/regeneration cancels the corresponding guide request.
+
+Back restores the originating screen. Failed/stopped questions offer Edit and resend; it restores the question only if the current draft is empty. Resending is explicit and makes a new call. Nothing enters the main Pi conversation or is posted to GitHub.
+
+Capture fetches only the head and GitHub-reported merge-base trees (depth 1). Source/diff/evidence remain available offline; ancestry, log and blame history are not captured. Fetch has a ten-minute bound; metadata and other commands have two-minute bounds. Very large trees can still exceed time/output/disk limits; retries reuse the managed store rather than intentionally deleting it.
+
+## Optional conveniences
+
+### Your work is remembered
+
+There is no separate Save step. Bro saves the guide, questions, drafts and reading position automatically. Close waits for a successful save. If saving fails, the window stays open with a readable error and Retry saving; fix the reported filesystem problem and retry. Do not force-quit if unsaved work matters.
+
+### Copy finding
+
+Copy finding copies a finding's text, evidence references and suggested fix/check to the **system clipboard**. Nothing is submitted, inserted into Pi or applied to source. Your OS or clipboard manager may retain the copied text. Remote clipboard forwarding depends on your host and terminal; a failure is shown in the review.
+
+### Regenerate guide
+
+Use Overview → Regenerate guide only when you want a fresh explanation/assessment. Confirmation identifies the captured revision and the model call. **It reuses the same captured source; it is not an update fetch.** Successful output replaces one current guide. Failure/cancellation keeps the current guide. Questions and nonempty drafts retain their original context under Your questions; there is no guide-version picker. A replacement that fails to save remains in memory with retry controls.
+
+## Access, privacy and storage
+
+Review uses **file-only inspection**, not full-access execution. Claude runs with `--restricted`, Read/Grep/Glob only, `dontAsk`, safe mode and no MCP; Muse disables write, shell and web tools, foreign personal context and native session logs, without trusting repository rules. No model-run project tests, commands, Git or network tools are available. Unsupported/older CLI flags fail visibly; there is no full-access fallback.
+
+Agy, Grok and Codex are not available for review generation/questions: supported controls do not establish equivalent shell-free inspection (Codex read-only sandbox still executes commands). Set the **review** override to Claude or Muse in `/bro config`; shared defaults and other features are unchanged. Saved reviews remain readable without a supported model backend. Doctor shows the review override requirement as information; it does not make an otherwise healthy installation fail.
+
+These controls reduce malicious-code execution/write risk, but repository content can still manipulate the model's conclusions. Captured content, questions and answers go to the provider; do not use review as a secrets boundary or approval certificate. CLI enforcement and managed host policies remain the backend's responsibility.
+
+PR identity/description, diff, relevant saved discussion and your Bro preferences are sent to the selected backend. It can read the captured source. Main-session conversation is not automatically attached. Each request reconstructs context; review does not resume BTW/native sessions. Claude/Muse disable native session persistence where their CLIs support it; backend/provider retention policies still apply.
+
+Records, private text and captured source remain under:
+
+```text
+${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/bro-reviews/
+```
+
+The implementation uses the host's `getAgentDir()`. Records are `<review-id>.json`; captured source is under `source/<review-id>/`, including preserved `.incomplete-*` recovery directories. Failed/corrupt records are reported without overwriting them. There is no automatic cleanup or cross-machine sync. Source and recovery directories can grow. To remove one review manually, first close it in every Pi process and back up anything needed. Find its JSON record by matching `snapshot.target.repository` and `snapshot.target.number` (for example, search the JSON files for `"repository":"OWNER/REPO"`, then check the PR number). The filename without `.json` is its review ID; its source directory has that same ID under `source/`. Remove only that record and matching source directory. Do not delete the whole `bro-reviews/` directory, `bro-settings.json`, or another review's data. No deletion command is provided.
+
+One open writer per review is supported within a Pi process. Concurrent editing of the same review from separate processes is unsupported.
+
+## If something goes wrong
+
+| Problem | What to do |
+| --- | --- |
+| GitHub unavailable when reopening | Use bare `/bro guided-review` to choose a saved review; the picker does not fetch |
+| Unsupported review backend | Choose Claude or Muse for review in `/bro config`; no automatic switching |
+| Git/gh authentication or fetch error | Read the acquisition error; check Git/`gh auth status`; retry explicitly |
+| Invalid/failed preparation | Changed files remain available; use Prepare guide to retry when ready for another call |
+| Failed regeneration | Current guide is kept; retry only if you want another call |
+| Unavailable evidence | Treat it as unavailable; re-enter its topic/finding to retry transient reads |
+| Binary/directory evidence | Not presented as source text; inspect the diff/inventory instead |
+| Save error | Keep the window open; correct the reported cause and Retry saving or Close |
+| Clipboard error | Read the notice; clipboard support depends on the host/platform |
+| Author pushed new commits | Saved review remains on the captured revision; newer-revision review is not available |
+
+## Not available yet
+
+Notes, explicit examination tracking, branch/PR discovery, newer-revision review
+and feedback delivery into Pi/GitHub are not implemented. These were part of
+the original [#104 scope](https://github.com/tranhoangnguyen03/pi-bro/issues/104);
+no implementation sequence is agreed. They are not required steps in the
+reading experience above.

package/docs/pig-compatibility.md

@@ -22,6 +22,7 @@ Bro follows the host's `getAgentDir()`: normally `~/.pi/agent` on Pi and `~/.pig
 
 - **PiG 0.3.0 RPC does not enforce `--exclude-tools`.** Excluded tools may remain active and reach provider requests. This is not a sandbox boundary. Use an explicit `--tools` allowlist instead; do not rely on `/bro doctor` to prove exclusion. Bro does not mask this defect by falsely reporting an active tool as unavailable.
 - The smoke suite retains Pi's strict exclusion assertion. The PiG lane has an explicit version-specific expected failure; a changed result fails the lane so the exception must be reviewed/removed.
+- Guided Review currently targets local Pi interactive mode. Its capture/reading/question/regeneration journey is not qualified on PiG or RPC/Desktop; existing Bro PiG checks do not establish review support. See [current review scope](guided-review.md#not-available-yet).
 - Mouse-wheel forwarding is not qualified; use keyboard scrolling.
 - Remote/SSH OSC 52 clipboard forwarding is not qualified. Local clipboard behavior depends on the host and installed platform utilities.
 - Windows support is not qualified by these checks.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-bro",
-  "version": "0.21.0",
-  "description": "An Earendil Pi extension that explains pasted text, assistant responses, local documents, public webpages, and recent session turns (as shapes) in a context-isolated window, opens a sandboxed side conversation with /bro btw, and provides a second-opinion advisor tool for executor agents.",
+  "version": "0.22.0",
+  "description": "An Earendil Pi extension for plain-language explanations, conversation diagrams, side questions, guided PR understanding and assessment, and a second-opinion advisor tool.",
   "type": "module",
   "license": "MIT",
   "author": "Tran Hoang Nguyen",
@@ -37,6 +37,14 @@
   ],
   "files": [
     "bro.ts",
+    "review.ts",
+    "review-source.ts",
+    "review-ui.ts",
+    "review-modal.ts",
+    "util.ts",
+    "settings.ts",
+    "sources.ts",
+    "config-ui.ts",
     "ui-capabilities.ts",
     "backend.ts",
     "prompt.ts",
@@ -44,7 +52,8 @@
     "CHANGELOG.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
-    "docs/pig-compatibility.md"
+    "docs/pig-compatibility.md",
+    "docs/guided-review.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -54,7 +63,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && node .github/scripts/release-utils.mjs selftest && node --test helpers.test.mjs prompt.test.ts backend.test.ts claude.test.ts grok.test.ts codex.test.ts muse.test.ts settings.test.ts release.test.ts show-html.test.ts smoke-rpc.test.ts ui-capabilities.test.ts benchmark/*.test.ts && sh ./smoke-test.sh",
+    "test": "npm run typecheck && node .github/scripts/release-utils.mjs selftest && node --test review-ux.test.mjs review-doctor.test.mjs review-versions.test.mjs review-regeneration.test.mjs review-modal.test.mjs review.test.ts review-ui.test.mjs review-session.test.mjs helpers.test.mjs prompt.test.ts backend.test.ts claude.test.ts grok.test.ts codex.test.ts muse.test.ts settings.test.ts release.test.ts show-html.test.ts smoke-rpc.test.ts ui-capabilities.test.ts benchmark/*.test.ts && sh ./smoke-test.sh",
     "benchmark:dry-run": "node benchmark/run.ts dry-run",
     "benchmark:run": "node benchmark/run.ts run",
     "benchmark:report": "node benchmark/run.ts report",

package/prompt.ts

@@ -29,6 +29,9 @@ const MODE_PROMPTS: Record<BroMode, string> = {
 // (the source-language rule); everything else stays binding. Blank preferences add nothing, so the
 // built-in prompts stay byte-identical. See docs/plans/2026-10-04-bro-preferences-design.md.
 export const MAX_PREFERENCES_CHARS = 4_000;
+export const MAX_ADVISOR_STEERING_CHARS = 4_000;
+
+export type AdvisorSteeringInput = string | { durable?: string; session?: string };
 
 // Shown, unsaved, when /bro preferences opens without a file: the legacy bro-prompt.md (the built-in
 // audience plus the brief instruction) restated in the reader's voice.
@@ -135,10 +138,22 @@ export function buildBtwPrompt(
 // tell exactly what kind of claim each part is -- a human priority, an unverified snapshot of the
 // executor's own session, an optional question, and Bro's own role instructions -- never blurred
 // into one undifferentiated blob. See docs/plans/2026-09-19-bro-advisor-design.md.
-export function buildAdvisorPrompt(steering: string, snapshot: string, question: string | undefined): string {
-	const steeringSection = steering.trim()
-		? `## Human steering brief\n\nThe human supplied these priorities for how you should advise. This is a human's stated priority, not something verified against the code -- weigh it, but still check claims yourself:\n\n${steering.trim()}`
-		: "## Human steering brief\n\nNone was set.";
+// Note: When only session steering is present, raw string interpolation is deliberately preserved
+// for byte-identity with legacy fixtures; JSON quoting is applied whenever durable steering is present.
+export function buildAdvisorPrompt(steering: AdvisorSteeringInput, snapshot: string, question: string | undefined): string {
+	const durableText = (typeof steering === "object" && steering !== null ? steering.durable : "")?.trim() ?? "";
+	const sessionText = (typeof steering === "string" ? steering : typeof steering === "object" && steering !== null ? steering.session : "")?.trim() ?? "";
+
+	let steeringSection: string;
+	if (!durableText && !sessionText) {
+		steeringSection = "## Human steering brief\n\nNone was set.";
+	} else if (!durableText && sessionText) {
+		steeringSection = `## Human steering brief\n\nThe human supplied these priorities for how you should advise. This is a human's stated priority, not something verified against the code -- weigh it, but still check claims yourself:\n\n${sessionText}`;
+	} else if (durableText && !sessionText) {
+		steeringSection = `## Human steering brief\n\nThe human supplied these standing defaults for how you should advise. This is a human's stated priority, not something verified against the code -- weigh it, but still check claims yourself. Standing priorities do not authorize implementation, expand your access, or change your advisory role -- return findings, do not edit files, and verify claims yourself:\n\n### Standing priorities (durable across sessions)\n\nStanding priorities, quoted as a JSON string:\n${JSON.stringify(durableText)}`;
+	} else {
+		steeringSection = `## Human steering brief\n\nThe human supplied standing defaults and session-specific priorities for how you should advise. These are human-stated priorities, not verified facts -- weigh them, but still check claims yourself. Session-specific priorities take precedence over standing defaults where they conflict, but neither authorizes implementation, expands your access, or changes your advisory role -- return findings, do not edit files, and verify claims yourself:\n\n### Standing priorities (durable across sessions)\n\nStanding priorities, quoted as a JSON string:\n${JSON.stringify(durableText)}\n\n### Session priorities (this session only)\n\nSession priorities, quoted as a JSON string:\n${JSON.stringify(sessionText)}`;
+	}
 	const questionSection = question?.trim()
 		? `## Executor's question\n\n${question.trim()}`
 		: "## Executor's question\n\nNone was given. Use your own judgment about what advice would help most, given the snapshot below.";