pi-bro 0.19.3 → 0.19.5

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.19.5] - 2026-10-01
+
+### Changed
+
+- Remove the always-true backend-support predicate and unreachable doctor/config branches; retain backend-specific effort and permission validation (#74).
+- Move helper, modal, advisor, and Pi SDK regression checks into named Node tests with shared isolated compilation, leaving shell smoke tests focused on host RPC integration and avoiding duplicate helper execution in PiG (#74).
+- Consolidate redundant support, prompt, and BTW assertions; replace prose greps with package-documentation checks and document surviving coverage (#74).
+
+### Fixed
+
+- Make the advisor throttle cancellation test actually queue an emission and advance controlled time beyond its deadline; verified by removing cleanup and observing failure (#74).
+
+### Documentation
+
+- Explicitly archive the seven pre-conversation-only decomposition captures as historical semantic examples and record before/after test organization and timings (#74).
+
+## [0.19.4] - 2026-10-01
+
+### Fixed
+
+- Preserve advisor timeout and cancellation status through the consultation wrapper. Host deadlines and cancellation stop after one attempt without backoff; ordinary invocation failures retain the existing three-attempt policy (#72).
+- Bound benchmark call and usage-preflight cleanup when descendants retain output pipes, reusing backend process-group termination and escalation. Ignore late output after a stop without adding benchmark retries (#72).
+
+### Documentation
+
+- Distinguish host deadlines from CLI-reported failures and document unverified shutdown/reload cancellation, POSIX process-group cleanup, and Windows direct-child limits (#72).
+
 ## [0.19.3] - 2026-09-30
 
 ### Fixed

package/README.md

@@ -64,7 +64,7 @@ text directly captures a new source the same way.
 
 | Command | Description |
 | --- | --- |
-| `/bro` or `/bro text` | Explain the latest completed assistant response. |
+| `/bro`, `/bro simplify`, or `/bro text` | Explain the latest completed assistant response. |
 | `/bro text <text>` | Explain pasted text. |
 | `/bro <input>` | Explain it directly: a lone URL runs the webpage reader, an existing workspace file with a supported extension runs the document reader, and anything else is pasted text. A quoted path with spaces is routed too when the file exists. |
 | `/bro file <path>` | Explain a workspace-local `.md`, `.markdown`, `.txt`, `.pdf`, or `.docx` file. |
@@ -205,9 +205,12 @@ presence, and backend compatibility (for Agy, a minimum CLI version with an
   more evidence" is a normal result, not a failure), Bro retries with the
   identical snapshot, steering, and question: once after 5 seconds, once more
   after 10 seconds, then returns the backend's own diagnostic — including a
-  context-length error, verbatim — as the failure. Each attempt is capped at
-  10 minutes. Cancelling the tool call aborts immediately and skips any
-  pending retry wait.
+  context-length error, verbatim — as the failure. Host-imposed deadlines and
+  cancellation are terminal: neither starts another attempt or a backoff wait.
+  The advisor CLI is asked to stop at 10 minutes; Bro's host deadline is 610
+  seconds plus bounded process cleanup. A CLI-reported error before that host
+  deadline remains an invocation failure and can be retried.
+  Cancelling the tool call skips any pending retry wait.
 - **Progress and provenance**: while an attempt is running, Bro shows the last
   thing the advisor actually reported — a tool name or a user-facing response
   line, never hidden reasoning — and how long ago it arrived, e.g. `last

package/backend.ts

@@ -123,7 +123,7 @@ const DEFAULT_KILL_ESCALATION_MS = 5_000;
 // protocol failure it signals the whole POSIX process group (SIGTERM, then SIGKILL after
 // `killEscalationMs` if the child or a misbehaving grandchild ignores it). Windows only ever
 // reaches the immediate child directly -- there is no process-tree guarantee there.
-function beginAttempt(child: ChildProcess, signal: AbortSignal, deadlineMs: number, killEscalationMs: number): Attempt {
+export function beginAttempt(child: ChildProcess, signal: AbortSignal, deadlineMs: number, killEscalationMs: number): Attempt {
 	let cause: StopCause | undefined;
 	let killTimer: ReturnType<typeof setTimeout> | undefined;
 	let finishClose: (value: { code: number | null; exitSignal: NodeJS.Signals | null }) => void;
@@ -286,6 +286,7 @@ async function executeArgvPrint(
 		}
 
 		const lines = createInterface({ input: child.stdout!, crlfDelay: Infinity });
+		void attempt.closed.then(() => lines.close());
 		try {
 			for await (const line of lines) {
 				if (!line.trim() || attempt.causeOf()) continue;
@@ -510,12 +511,6 @@ async function executeAdvisorStdin(
 }
 
 
-// Every backend supports every feature. Grok's "restricted" access is a prompt instruction, not
-// enforcement (see GROK_RESTRICTED_PREFIX); Claude's restricted btw runs tool-less.
-export function backendSupports(_backend: "agy" | "claude" | "grok" | "codex" | "muse", _feature: BackendFeature): boolean {
-	return true;
-}
-
 type ClaudeEvent = {
 	type?: unknown;
 	subtype?: unknown;

package/bro.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { hasBroCustomUi, broModalRows, canBroInsertIntoEditor, insertBroDesktopText } from "./ui-capabilities.ts";
 import { createHash } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import { mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
@@ -9,7 +10,7 @@ import { tmpdir } from "node:os";
 import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
-import { Container, Editor, Input, Markdown, SettingsList, SelectList, Text, matchesKey, truncateToWidth, visibleWidth, type Component, type EditorTheme, type Focusable, type SelectItem, type SettingItem, type TUI } from "@earendil-works/pi-tui";
+import { Container, Editor, Input, Markdown, SettingsList, SelectList, Text, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type EditorTheme, type Focusable, type SelectItem, type SettingItem, type TUI } from "@earendil-works/pi-tui";
 import { convertToLlm, copyToClipboard, getAgentDir, getMarkdownTheme, getSelectListTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
 import { Defuddle } from "defuddle/node";
 import { parseHTML } from "linkedom";
@@ -25,7 +26,6 @@ import {
 	GROK_EFFORTS,
 	CODEX_EFFORTS,
 	MUSE_EFFORTS,
-	backendSupports,
 	execute as executeBackend,
 	parseBtwAgyLine,
 	type AgySelection,
@@ -111,7 +111,6 @@ export const MUSE_MODELS = [
 	{ id: "muse-spark-1.3-contributor", label: "Muse Spark 1.3 Contributor" },
 	{ id: "muse-spark-1.3", label: "Muse Spark 1.3" },
 ] as const;
-export { backendSupports as supportsBackend };
 type AgyModelFamily = {
 	id: string;
 	label: string;
@@ -131,6 +130,7 @@ export function setRegularMouseReporting(tui: Pick<TuiLike, "mode" | "terminal">
 }
 
 const COMMANDS = [
+	{ value: "simplify", label: "simplify", description: "Explain the latest completed assistant reply (same as /bro)" },
 	{ value: "text", label: "text", description: "Explain pasted text, or the latest reply when text is omitted" },
 	{ value: "file", label: "file", description: "Explain a local document" },
 	{ value: "url", label: "url", description: "Explain a public webpage" },
@@ -1323,10 +1323,6 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 				continue;
 			}
 			if (backend === "grok") {
-				if (!backendSupports("grok", capability)) {
-					fail(label, `\`${capability}\` is not supported on the Grok backend for this capability. Run \`/bro config\` to give it another backend.`);
-					continue;
-				}
 				if (!isGrokEffort(pair.effort)) {
 					fail(label, `\`${pair.effort}\` is unsupported for grok \`${pair.model}\`. Run \`/bro config\` to fix this.`);
 					continue;
@@ -1340,10 +1336,6 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 				continue;
 			}
 			if (backend === "codex") {
-				if (!backendSupports("codex", capability)) {
-					fail(label, `\`${capability}\` is not supported on the Codex backend for this capability. Run \`/bro config\` to give it another backend.`);
-					continue;
-				}
 				if (!isCodexEffort(pair.effort)) {
 					fail(label, `\`${pair.effort}\` is unsupported for codex \`${pair.model}\`. Run \`/bro config\` to fix this.`);
 					continue;
@@ -1357,10 +1349,6 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 				continue;
 			}
 			if (backend === "muse") {
-				if (!backendSupports("muse", capability)) {
-					fail(label, `\`${capability}\` is not supported on the Muse backend for this capability. Run \`/bro config\` to give it another backend.`);
-					continue;
-				}
 				if (!isMuseEffort(pair.effort)) {
 					fail(label, `\`${pair.effort}\` is unsupported for muse \`${pair.model}\`. Run \`/bro config\` to fix this.`);
 					continue;
@@ -1818,6 +1806,14 @@ export type AdvisorActivityCallback = (label: string, timestamp: number) => void
 // "Transport" for why stdin rather than --print). This function keeps its exact existing
 // signature/throw contract -- it is called directly by tests and by runAdvisorWithRetries below,
 // which owns the 3-attempt retry/backoff policy the backend itself never performs.
+export class TerminalConsultError extends Error {
+	readonly status: "failure" | "cancelled" | "timeout";
+	constructor(status: "failure" | "cancelled" | "timeout", message: string) {
+		super(message);
+		this.status = status;
+	}
+}
+
 export async function runAdvisorConsultation(
 	prompt: string,
 	selection: BackendSelection,
@@ -1825,6 +1821,7 @@ export async function runAdvisorConsultation(
 	signal: AbortSignal,
 	killEscalationMs = 5_000,
 	onActivity?: AdvisorActivityCallback,
+	deadlineMs?: number,
 ): Promise<string> {
 	const outcome = await executeBackend(
 		{ feature: "advisor", prompt, access: "workspace-full", cwd },
@@ -1835,10 +1832,10 @@ export async function runAdvisorConsultation(
 					if (progress.kind === "activity") onActivity(progress.label, progress.timestamp);
 				}
 			: undefined,
-		{ killEscalationMs },
+		{ killEscalationMs, deadlineMs },
 	);
 	if (outcome.status === "success") return outcome.text;
-	throw new Error(outcome.message);
+	throw new TerminalConsultError(outcome.status, outcome.message);
 }
 
 function advisorDelay(ms: number, signal: AbortSignal, onTick?: (remainingMs: number) => void): Promise<void> {
@@ -1992,7 +1989,8 @@ export async function runAdvisorWithRetries(
 		} catch (error) {
 			if (progressTimer) clearInterval(progressTimer);
 			stopActivityThrottle();
-			if (signal.aborted || errorMessage(error) === "Canceled.") throw error;
+			if (signal.aborted || errorMessage(error) === "Canceled." ||
+				(error instanceof TerminalConsultError && error.status !== "failure")) throw error;
 			lastError = error;
 			if (attempt === delays.length) break;
 			const delay = delays[attempt]!;
@@ -2265,7 +2263,7 @@ export function createConfigModal(
 								: backend === "muse"
 									? `${MUSE_OPTION_PREFIX}${override.model}`
 									: (resolved.family?.id ?? override.model);
-				rows.effort.currentValue = backendSupports(backend, capability) ? effortDisplay(resolved, backend) : "unsupported backend";
+				rows.effort.currentValue = effortDisplay(resolved, backend);
 				rows.effort.values =
 					backend === "claude"
 						? ["default", ...CLAUDE_EFFORTS]
@@ -2502,7 +2500,7 @@ export function createConfigModal(
 }
 
 export async function showBroConfigModal(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
-	if (ctx.mode !== "tui") {
+	if (!hasBroCustomUi(ctx)) {
 		ctx.ui.notify("Use /bro config in Pi's interactive UI.", "warning");
 		return;
 	}
@@ -2619,7 +2617,7 @@ export function createAdvisorSteerModal(
 }
 
 export async function showAdvisorSteerModal(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
-	if (ctx.mode !== "tui") {
+	if (!hasBroCustomUi(ctx)) {
 		ctx.ui.notify("Use /bro advisor-steer in Pi's interactive UI.", "warning");
 		return;
 	}
@@ -2655,7 +2653,7 @@ Quick reference. The README is the full user guide: https://github.com/tranhoang
 
 ## Explain and show
 
-- \`/bro\` — explain the latest completed assistant reply
+- \`/bro\` or \`/bro simplify\` — explain the latest completed assistant reply
 - \`/bro text [text]\` — explain pasted text, or the latest reply when text is omitted
 - \`/bro file <path>\` — explain a workspace \`.md\`, \`.markdown\`, \`.txt\`, \`.pdf\`, or \`.docx\` file
 - \`/bro url <url>\` — explain one public webpage
@@ -2816,7 +2814,7 @@ class BroModal implements Focusable {
 	render(width: number): string[] {
 		const dialogWidth = Math.max(24, width);
 		const innerWidth = Math.max(22, dialogWidth - 2);
-		const terminalRows = this.tui.terminal?.rows ?? process.stdout.rows ?? 30;
+		const terminalRows = broModalRows(this.tui, process.stdout.rows);
 		const dialogHeight = Math.min(32, Math.max(7, Math.floor(terminalRows * 0.78)));
 		this.bodyHeight = Math.max(1, dialogHeight - 6);
 
@@ -2924,7 +2922,7 @@ interface BroModalOptions {
 }
 
 async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptions): Promise<void> {
-	if (ctx.mode !== "tui") {
+	if (!hasBroCustomUi(ctx)) {
 		if (options.run && !options.result && options.text === undefined) {
 			const result = await options.run(new AbortController().signal);
 			options.onResult?.(result);
@@ -3189,6 +3187,7 @@ class BtwModal implements Focusable {
 	}
 
 	setNotice(notice: string): void {
+		if (this.disposed) return;
 		this.notice = notice;
 		this.tui.requestRender();
 	}
@@ -3253,9 +3252,16 @@ class BtwModal implements Focusable {
 	render(width: number): string[] {
 		const dialogWidth = Math.max(24, width);
 		const innerWidth = Math.max(22, dialogWidth - 2);
-		const terminalRows = this.tui.terminal?.rows ?? process.stdout.rows ?? 30;
+		const terminalRows = broModalRows(this.tui, process.stdout.rows);
 		const dialogHeight = Math.min(34, Math.max(8, Math.floor(terminalRows * 0.82)));
-		this.bodyHeight = Math.max(1, dialogHeight - 7);
+		const footer = [
+			...wrapTextWithAnsi(this.theme.fg("accent", this.theme.bold("Your message to Bro")), innerWidth),
+			this.input.render(innerWidth)[0] ?? "",
+			...wrapTextWithAnsi(this.running ? "Bro is thinking… · Esc: cancel response" : "Enter: send message · Esc: close panel", innerWidth),
+			...wrapTextWithAnsi("Commands: /mode · /copy · /copy-all · /insert · /insert-all · /clear · /retry", innerWidth),
+			...(this.notice ? wrapTextWithAnsi(this.theme.fg("accent", this.notice), innerWidth) : []),
+		];
+		this.bodyHeight = Math.max(1, dialogHeight - 5 - footer.length);
 
 		const rendered = this.markdown.render(innerWidth);
 		this.maxOffset = Math.max(0, rendered.length - this.bodyHeight);
@@ -3268,12 +3274,6 @@ class BtwModal implements Focusable {
 		const mode = this.theme.fg("dim", " · ") + (this.full ? this.theme.fg("accent", this.theme.bold(btwModeLabel(true))) : this.theme.fg("dim", btwModeLabel(false)));
 		const header = this.theme.fg("accent", this.theme.bold("Bro · btw")) + model + mode + this.theme.fg("dim", scroll);
 
-		const composer = this.input.render(innerWidth)[0] ?? "";
-
-		const controls = this.running
-			? this.theme.fg("dim", "Thinking… · Esc cancel")
-			: this.theme.fg("dim", "Enter ask · Esc close · /mode · /copy · /copy-all · /insert · /insert-all · /clear · /retry");
-
 		const lines = [
 			this.borderLine(innerWidth, "top"),
 			this.frameLine(header, innerWidth),
@@ -3282,8 +3282,7 @@ class BtwModal implements Focusable {
 		for (const line of visible) lines.push(this.frameLine(line, innerWidth));
 		for (let i = visible.length; i < this.bodyHeight; i++) lines.push(this.frameLine("", innerWidth));
 		lines.push(this.ruleLine(innerWidth));
-		lines.push(this.frameLine(composer, innerWidth));
-		lines.push(this.frameLine(this.notice ? this.theme.fg("accent", this.notice) : controls, innerWidth));
+		for (const line of footer) lines.push(this.frameLine(line, innerWidth));
 		lines.push(this.borderLine(innerWidth, "bottom"));
 		return lines;
 	}
@@ -3425,12 +3424,17 @@ async function openBtwModal(
 				}
 			};
 
-			const insert = (all: boolean) => {
+			const insert = async (all: boolean) => {
 				const text = all ? transcript() : (thread.turns.at(-1)?.answer ?? "");
 				if (!text.trim()) {
 					modal.setNotice("Nothing to insert yet.");
 					return;
 				}
+				if (!canBroInsertIntoEditor(ctx)) {
+					const result = await insertBroDesktopText(ctx, text);
+					modal.setNotice(result === "inserted" ? "Inserted into the main editor. Review it before sending." : result === "not_empty" ? "Main editor has a draft or attachment. Clear it first, then insert again." : "Could not confirm insertion. Check the main editor before trying again.");
+					return;
+				}
 				if (ctx.ui.getEditorText().trim()) {
 					modal.setNotice("Main editor has a draft. Edit or clear it first, then insert again.");
 					return;
@@ -3629,6 +3633,11 @@ export default async function bro(pi: ExtensionAPI) {
 			let action = parts[0] ?? "";
 			let value = raw.slice(raw.split(/\s+/, 1)[0]?.length ?? 0).trim();
 
+			if (action === "simplify") {
+				if (value) { ctx.ui.notify("Use /bro simplify for the latest reply, or /bro text <text> for pasted text.", "warning"); return; }
+				action = "";
+			}
+
 			// Removed commands must never fall through to a paid text explanation.
 			if (action === "model" || action === "effort") {
 				ctx.ui.notify(`/bro ${action} was removed. Use /bro config to choose the shared default and per-capability ${action}; use /bro text <text> to explain text.`, "warning");
@@ -3750,7 +3759,7 @@ export default async function bro(pi: ExtensionAPI) {
 					const settings = await readSettings();
 					let selected = parseBroMode(requested);
 					if (!selected) {
-						if (ctx.mode !== "tui") {
+						if (!hasBroCustomUi(ctx)) {
 							ctx.ui.notify("Use /bro mode <brief|balanced|faithful> outside Pi's interactive UI.", "warning");
 							return;
 						}
@@ -3770,7 +3779,7 @@ export default async function bro(pi: ExtensionAPI) {
 			}
 
 			if (action === "btw") {
-				if (ctx.mode !== "tui") {
+				if (!hasBroCustomUi(ctx)) {
 					ctx.ui.notify("Use /bro btw in Pi's interactive UI.", "warning");
 					return;
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.19.3",
+  "version": "0.19.5",
   "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.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,7 @@
   ],
   "files": [
     "bro.ts",
+    "ui-capabilities.ts",
     "backend.ts",
     "prompt.ts",
     "README.md",
@@ -53,7 +54,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && node --test prompt.test.ts backend.test.ts claude.test.ts grok.test.ts codex.test.ts muse.test.ts settings.test.ts show-html.test.ts smoke-rpc.test.ts benchmark/*.test.ts && sh ./smoke-test.sh",
+    "test": "npm run typecheck && 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 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/ui-capabilities.ts

@@ -0,0 +1,35 @@
+/** Local structural contract. This does not extend, patch, or impersonate the upstream Pi API. */
+type UiContext = { mode: string; ui: unknown };
+type DesktopUi = { getDesktopUiCapabilities?: () => unknown };
+
+export function hasBroCustomUi(ctx: UiContext): boolean {
+	if (ctx.mode === "tui") return true;
+	if (ctx.mode !== "rpc" || !ctx.ui || typeof ctx.ui !== "object") return false;
+	const query = (ctx.ui as DesktopUi).getDesktopUiCapabilities;
+	if (typeof query !== "function") return false;
+	try {
+		const value = query.call(ctx.ui);
+		if (!value || typeof value !== "object") return false;
+		const capability = value as { version?: unknown; customTui?: unknown; viewport?: unknown };
+		return capability.version === 1 && capability.customTui === true && capability.viewport === true;
+	} catch { return false; }
+}
+
+/** Read a virtual terminal's actual viewport in desktop mode; preserve terminal behavior elsewhere. */
+export function broModalRows(tui: unknown, terminalRows: number | undefined): number {
+	const rows = tui && typeof tui === "object" ? (tui as { terminal?: { rows?: unknown } }).terminal?.rows : undefined;
+	const candidate = typeof rows === "number" && Number.isFinite(rows) && rows > 0 ? rows : terminalRows;
+	return typeof candidate === "number" && Number.isFinite(candidate) && candidate > 0 ? Math.floor(candidate) : 30;
+}
+
+export async function insertBroDesktopText(ctx: UiContext, text: string): Promise<"inserted" | "not_empty" | "unavailable"> {
+  if (!hasBroCustomUi(ctx) || ctx.mode !== "rpc") return "unavailable";
+  const ui = ctx.ui as DesktopUi & { insertEditorTextIfEmpty?: (text: string) => Promise<"inserted" | "not_empty" | "unavailable"> };
+  try {
+    const caps = ui.getDesktopUiCapabilities?.() as { atomicEditorInsert?: boolean } | undefined;
+    return caps?.atomicEditorInsert === true && ui.insertEditorTextIfEmpty ? await ui.insertEditorTextIfEmpty(text) : "unavailable";
+  } catch { return "unavailable"; }
+}
+
+/** Only terminal mode uses synchronous insertion; Desktop uses insertBroDesktopText instead. */
+export function canBroInsertIntoEditor(ctx: UiContext): boolean { return ctx.mode === "tui"; }