pi-bro 0.19.3 → 0.19.4

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to pi-bro are documented here.
 
+## [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;

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";
@@ -131,6 +132,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" },
@@ -1818,6 +1820,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 +1835,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 +1846,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 +2003,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]!;
@@ -2502,7 +2514,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 +2631,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 +2667,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 +2828,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 +2936,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 +3201,7 @@ class BtwModal implements Focusable {
 	}
 
 	setNotice(notice: string): void {
+		if (this.disposed) return;
 		this.notice = notice;
 		this.tui.requestRender();
 	}
@@ -3253,9 +3266,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 +3288,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 +3296,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 +3438,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 +3647,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 +3773,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 +3793,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.4",
   "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 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"; }