pi-bro 0.23.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,8 @@
     "src/show.ts",
     "src/advisor.ts",
     "src/btw.ts",
+    "src/elevate.ts",
+    "src/elevate-engine.ts",
     "src/explain-modal.ts",
     "src/review.ts",
     "src/review-source.ts",
@@ -56,6 +58,7 @@
     "src/sources.ts",
     "src/config-ui.ts",
     "src/ui-capabilities.ts",
+    "src/modal-kit.ts",
     "src/backend.ts",
     "src/prompt.ts",
     "src/vendor/mermaid.min.js",
@@ -63,9 +66,15 @@
     "CHANGELOG.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
+    "docs/README.md",
+    "docs/getting-started.md",
     "docs/user-guide.md",
     "docs/pig-compatibility.md",
-    "docs/guided-review.md"
+    "docs/guided-review.md",
+    "docs/elevate.md",
+    "docs/examples.md",
+    "docs/features",
+    "docs/reference"
   ],
   "publishConfig": {
     "access": "public"
@@ -74,8 +83,9 @@
     "node": ">=22.19.0"
   },
   "scripts": {
+    "docs:check": "node scripts/check-docs.mjs && node --test test/docs-quality.test.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && node .github/scripts/release-utils.mjs selftest && node --test test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts benchmark/*.test.ts && sh ./test/smoke-test.sh",
+    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/elevate-docs.test.mjs test/elevate.test.ts test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/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/src/advisor.ts

@@ -460,11 +460,11 @@ export function registerAdvisorTool(pi: ExtensionAPI): void {
 		name: ADVISOR_TOOL_NAME,
 		label: "Bro advisor",
 		description:
-			"Consult a fresh, independent process of the configured advisor backend for a second opinion mid-task. It has real, unsandboxed tool access in the current workspace (read files, search, run commands) with permissions auto-approved, and is instructed to investigate before advising and to leave edits to you — that is a behavioral instruction to the advisor, not an enforced restriction, so treat its findings as advice rather than a delegated implementation. You never need to prepare a summary or evidence first: Bro automatically captures your system instructions, active tools, and the conversation so far, plus any human-set steering priorities, and sends them to the advisor.",
+			"Consult a fresh, independent process of the configured advisor backend for a second opinion mid-task. It has real, unsandboxed tool access in the current workspace (read files, search, run commands) with permissions auto-approved, and is instructed to investigate before advising and to leave edits to you — that is a behavioral instruction to the advisor, not an enforced restriction, so treat its findings as advice rather than a delegated implementation. No need to prepare a summary or evidence first: Bro automatically captures your system instructions, active tools, and the conversation so far, plus any human-set steering priorities, and sends them to the advisor.",
 		promptSnippet: "Consult a fresh configured-backend process for a second opinion mid-task; it investigates the workspace itself and returns advice",
 		promptGuidelines: [
-			"Call bro_advisor before or after a non-trivial design or scope decision, or when genuinely uncertain, for a second opinion from a fresh, independent process of the configured advisor backend.",
-			"bro_advisor's question parameter is optional — never delay a call to first prepare a summary or evidence; Bro captures context automatically.",
+			"Use bro_advisor when the user asks for an independent opinion, or when one would likely settle real uncertainty or catch a costly mistake. Routine decisions do not require consultation.",
+			"bro_advisor's question parameter is optional — Bro captures context automatically, so you do not need to prepare a summary or evidence before calling.",
 			"Any human-set steering priorities are applied automatically by bro_advisor; you don't need to relay or repeat them.",
 			"bro_advisor is instructed to only return advice and leave edits to you — that instruction is not enforced, so verify its findings yourself rather than treating them as a completed implementation.",
 		],

package/src/backend.ts

@@ -8,12 +8,28 @@ import { join } from "node:path";
 // (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.
+// For Guided Review (`feature: "review"`), Claude and Muse enforce strict file-only inspection;
+// Agy, Grok, and Codex run inside their own sandbox with shell available, and the UI owns telling
+// the user via `reviewBackendNotice`.
 
 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.";
+// Per-backend truth, not one shared sentence: Codex and Grok have a read-only sandbox, Agy's
+// sandbox only restricts terminal commands and still lets it write inside the project. Kept short
+// enough that the whole notice fits the review window's advisory rows on a narrow terminal.
+export function reviewBackendNotice(backend: "agy" | "claude" | "grok" | "codex" | "muse"): string | undefined {
+	if (backend === "claude" || backend === "muse") return undefined;
+	const sandbox = backend === "agy" ? "sandboxed shell (project writes allowed)" : "sandboxed shell in a read-only sandbox";
+	return `Guided Review on ${backend} uses ${sandbox}, not strict file-only inspection. Claude or Muse is recommended for untrusted PRs.`;
 }
+// One default deadline table for every adapter: workspace-full, Guided Review and the advisor get
+// the long bound; btw the middle one; explain/show the short one.
+export const REVIEW_DEADLINE_MS = 610_000;
+export function backendDeadlineMs(feature: BackendFeature, access: BackendAccess): number {
+	if (access === "workspace-full" || feature === "review") return REVIEW_DEADLINE_MS;
+	return feature === "btw" ? 130_000 : 125_000;
+}
+
 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;
@@ -232,16 +248,17 @@ 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 inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
-	const printTimeout = full ? "10m" : "2m";
-	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.";
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
+	const printTimeout = full || inspect ? "10m" : "2m";
+	const action = inspect ? "complete the guided review request" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = inspect ? "during the guided review request" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = inspect ? "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." };
 
-	const runDirectory = full ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	const runDirectory = full || 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." };
@@ -264,7 +281,7 @@ async function executeArgvPrint(
 				...(stdinPrompt ? ["--input-format", "stream-json"] : ["--print", request.prompt]),
 			],
 			{
-				cwd: full ? request.cwd : runDirectory,
+				cwd: full || inspect ? request.cwd : runDirectory,
 				stdio: [stdinPrompt ? "pipe" : "ignore", "pipe", "pipe"],
 				windowsHide: true,
 				detached: process.platform !== "win32",
@@ -446,7 +463,7 @@ async function executeAdvisorStdin(
 ): Promise<BackendOutcome> {
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
-	const deadlineMs = deadlineMsOverride ?? 610_000;
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
 	const child = spawn(
 		"agy",
 		[
@@ -570,7 +587,7 @@ async function executeClaude(
 	const isBtw = request.feature === "btw";
 	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full || inspect ? 610_000 : isBtw ? 130_000 : 125_000);
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
 	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." };
@@ -751,18 +768,21 @@ export const GROK_RESTRICTED_PREFIX =
 	"Bro restricted mode (a request, not a technical restriction): answer only from the context supplied in this prompt. " +
 	"Do not inspect, read, or write workspace files, run commands, or use web or other external tools unless the user explicitly asks you to in this prompt.";
 
-// Grok runs every feature with all capabilities on (--sandbox off, bypassPermissions, no tool
-// blacklist). explain/show run in a fresh mkdtemp scratch cwd removed afterwards (the Agy pattern);
+// Grok runs explain, show, btw, and advisor with all capabilities on (--sandbox off,
+// bypassPermissions, no tool blacklist); Guided Review (`review`) runs in the caller's workspace
+// under Grok's read-only sandbox (--sandbox read-only, --permission-mode dontAsk).
+// explain/show run in a fresh mkdtemp scratch cwd removed afterwards (the Agy pattern);
 // btw (both accesses) runs in the caller's workspace cwd and continues natively with --resume, whose
-// session keeps the cwd it was created in; the advisor runs fresh in the workspace. Restricted
-// requests get GROK_RESTRICTED_PREFIX. The prompt goes through a private 0600 file in its own
-// mkdtemp directory, removed once the attempt ends.
+// session keeps the cwd it was created in; the advisor and review run fresh in the workspace.
+// Restricted requests other than review get GROK_RESTRICTED_PREFIX (review must be allowed to
+// inspect the captured checkout). The prompt goes through a private 0600 file in its own mkdtemp
+// directory, removed once the attempt ends.
 // Only a top-level terminal `result` with success/is_error false/end_turn is authoritative; the
 // first failure (a failed result or a top-level `error` event, even after a success) is latched.
-// Nested (subagent) frames are ignored. The advisor reports activity labels only; explain/show/btw
-// report top-level text_delta progress, falling back to an assistant message's text blocks only when
-// no delta streamed for it. Thinking is never reported. btw requires init/result session ids to
-// agree (and to equal the resumed id) and returns that id as the continuation.
+// Nested (subagent) frames are ignored. The advisor reports activity labels only; explain/show/btw/review
+// report top-level text_delta progress, falling back to an assistant message's text
+// blocks only when no delta streamed for it. Thinking is never reported. btw requires init/result
+// session ids to agree (and to equal the resumed id) and returns that id as the continuation.
 async function executeGrok(
 	request: BackendRequest,
 	selection: { model: string; effort?: string },
@@ -773,11 +793,13 @@ async function executeGrok(
 ): Promise<BackendOutcome> {
 	const isAdvisor = request.feature === "advisor";
 	const isBtw = request.feature === "btw";
-	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;
+	const inspect = request.feature === "review";
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
+	const action = inspect ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = inspect ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = inspect ? "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.";
+	// Review inspects the captured checkout, so it must not carry the "do not inspect" restriction.
+	const prompt = request.access === "restricted" && !inspect ? `${GROK_RESTRICTED_PREFIX}\n\n${request.prompt}` : request.prompt;
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 	const promptDirectory = await mkdtemp(join(tmpdir(), "pi-bro-grok-"));
@@ -786,16 +808,14 @@ 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 (request.access !== "workspace-full" && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+		if (request.access !== "workspace-full" && !isBtw && !inspect) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
 		const child = spawn(
 			"grok",
 			[
-				"--sandbox",
-				"off",
-				"--permission-mode",
-				"bypassPermissions",
+				// Review never auto-approves: dontAsk denies unpromptable asks instead of bypassing them. Unverified against a local grok CLI; an unsupported flag fails visibly rather than falling back to --sandbox off.
+				...(inspect ? ["--sandbox", "read-only", "--permission-mode", "dontAsk"] : ["--sandbox", "off", "--permission-mode", "bypassPermissions"]),
 				"--output-format",
 				"streaming-messages-json",
 				"--include-partial-messages",
@@ -836,8 +856,14 @@ async function executeGrok(
 			}
 			if (event.parent_tool_use_id !== undefined && event.parent_tool_use_id !== null) return;
 			if (event.type === "system" && event.subtype === "init") {
-				if (event.permissionMode !== "bypassPermissions") {
-					throw new Error("Grok did not apply the required bypassPermissions mode; check Grok policy/configuration.");
+				// Review asks for dontAsk, but `--sandbox read-only` in argv is the real boundary: another
+				// restricting mode is not a downgrade, and only auto-approval means the request was
+				// ignored. Both paths fail closed when the mode is missing, exactly like explain/btw.
+				const escalated = event.permissionMode === "bypassPermissions" || event.permissionMode === "always-approve";
+				if (inspect ? typeof event.permissionMode !== "string" || escalated : event.permissionMode !== "bypassPermissions") {
+					throw new Error(
+						`Grok did not apply the required ${inspect ? "restricted" : "bypassPermissions"} mode; check Grok policy/configuration.`,
+					);
 				}
 				if (typeof event.session_id === "string") initSessionId = event.session_id;
 			}
@@ -1007,14 +1033,15 @@ async function executeCodex(
 ): 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 = 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.";
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
+	const action = inspect ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = inspect ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = inspect ? "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 = full || 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." };
@@ -1180,7 +1207,7 @@ async function executeMuse(
 	const isBtw = request.feature === "btw";
 	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full || inspect ? 610_000 : isBtw ? 130_000 : 125_000);
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
 	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.";
@@ -1369,10 +1396,6 @@ export async function execute(
 		(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\`.` };

package/src/bro.ts

@@ -8,6 +8,7 @@ import {
 	resolveBtwThread,
 } from "./btw.ts";
 import { doctorReport, showBroConfigModal } from "./doctor.ts";
+import { openElevateModal } from "./elevate.ts";
 import {
 	type BroResult,
 	type ModalResult,
@@ -53,6 +54,8 @@ export * from "./show.ts";
 export * from "./advisor.ts";
 export * from "./doctor.ts";
 export * from "./btw.ts";
+export * from "./elevate.ts";
+export * from "./elevate-engine.ts";
 export * from "./explain-modal.ts";
 
 const COMMANDS = [
@@ -67,6 +70,7 @@ const COMMANDS = [
 	{ value: "preferences", label: "preferences", description: "View or edit what Bro knows about you and how you like answers" },
 	{ value: "guided-review", label: "guided-review", description: "Understand and assess a PR with captured code and optional private questions" },
 	{ value: "btw", label: "btw", description: "Open a side conversation (starts conversation-only; /mode toggles full permission)" },
+	{ value: "elevate", label: "elevate", description: "Discover missing expert considerations, then improve a request" },
 	{ value: "config", label: "config", description: "Configure shared defaults and per-capability model/effort overrides" },
 	{ value: "advisor", label: "advisor", description: "Check whether the executor's advisor tool is available right now" },
 	{ value: "advisor-steer", label: "advisor-steer", description: "View, edit, save, or clear the advisor's persistent steering brief" },
@@ -281,6 +285,13 @@ export default async function bro(pi: ExtensionAPI) {
 				return;
 			}
 
+			if (action === "elevate") {
+				if (!hasBroCustomUi(ctx)) { ctx.ui.notify("Use /bro elevate in Pi interactive UI.", "warning"); return; }
+				try { await openElevateModal(ctx, value); }
+				catch (error) { ctx.ui.notify(withDoctor(error), "error"); }
+				return;
+			}
+
 			if (action === "config") {
 				if (parts.length !== 1) {
 					ctx.ui.notify("Use /bro config.", "warning");
@@ -419,6 +430,20 @@ export default async function bro(pi: ExtensionAPI) {
 		},
 	});
 
+	// Registered after /bro and isolated: a shortcut that cannot register must never remove the
+	// working commands. The shortcut can read an unsent draft and uses only context and UI methods
+	// shared by ExtensionContext and ExtensionCommandContext.
+	try {
+		if (typeof pi.registerShortcut === "function") pi.registerShortcut("ctrl+shift+e", {
+			description: "Bro Elevate: improve the current editor draft",
+			handler: async (ctx) => {
+				if (!hasBroCustomUi(ctx)) { ctx.ui.notify("Elevate requires Pi interactive UI.", "warning"); return; }
+				try { await openElevateModal(ctx as import("@earendil-works/pi-coding-agent").ExtensionCommandContext); }
+				catch (error) { ctx.ui.notify(withDoctor(error), "error"); }
+			},
+		});
+	} catch { /* /bro still works; the command is the supported path to Elevate */ }
+
 	// Keep the command available even when Bro cannot create its settings file; Doctor can then explain the problem.
 	await ensureSettingsFile().catch(() => undefined);
 }