pi-bro 0.19.2 → 0.19.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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
+
+- Send large Agy explain, Show, and BTW prompts over stdin instead of exceeding argument-size limits. Older Agy versions report an upgrade hint rather than silently falling back (#73).
+- Retain newest turns and message tails when bounding Show and BTW context, preserving JSON message framing (#73).
+
 ## [0.19.2] - 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;
@@ -211,8 +211,8 @@ export function parseBtwAgyLine(line: string): { delta?: string; result?: string
 	return { conversationId };
 }
 
-// explain/show and btw all print the prompt as a single --print argv value and read a stream-json
-// result off stdout; only sandbox flag, cwd, timeout, and (btw only) --conversation differ.
+// Explain/show and BTW use argv for small prompts and stdin NDJSON for large
+// prompts; sandbox, cwd, timeout, and continuation semantics stay unchanged.
 async function executeArgvPrint(
 	request: BackendRequest,
 	selection: AgySelection,
@@ -221,6 +221,9 @@ async function executeArgvPrint(
 	killEscalationMs: number,
 	deadlineMsOverride: number | undefined,
 ): Promise<BackendOutcome> {
+	// Keep legacy CLI compatibility for small prompts; large inputs use the advisor's
+	// stdin protocol rather than risking Linux's per-argument byte limit.
+	const stdinPrompt = Buffer.byteLength(request.prompt, "utf8") >= 120_000;
 	const isBtw = request.feature === "btw";
 	const full = isBtw && request.access === "workspace-full";
 	const deadlineMs = deadlineMsOverride ?? (isBtw ? (full ? 610_000 : 130_000) : 125_000);
@@ -251,12 +254,11 @@ async function executeArgvPrint(
 				"--print-timeout",
 				printTimeout,
 				...(request.continuation ? ["--conversation", request.continuation.id] : []),
-				"--print",
-				request.prompt,
+				...(stdinPrompt ? ["--input-format", "stream-json"] : ["--print", request.prompt]),
 			],
 			{
 				cwd: full ? request.cwd : runDirectory,
-				stdio: ["ignore", "pipe", "pipe"],
+				stdio: [stdinPrompt ? "pipe" : "ignore", "pipe", "pipe"],
 				windowsHide: true,
 				detached: process.platform !== "win32",
 			},
@@ -278,7 +280,13 @@ async function executeArgvPrint(
 			processError = error;
 		});
 
+		if (stdinPrompt) {
+			child.stdin?.on("error", () => { /* Report early exits through the close/error path. */ });
+			child.stdin?.end(`${JSON.stringify({ event: "user", message: { content: request.prompt } })}\n`);
+		}
+
 		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;
@@ -327,7 +335,9 @@ async function executeArgvPrint(
 		if (exitSignal || code === null) {
 			return { status: "failure", message: unexpectedSignalMessage(exitSignal), partialText: partial || undefined };
 		}
-		if (code !== 0) return { status: "failure", message: agyFailureMessage(action, { code, killed: false, stderr }) };
+		if (code !== 0) return { status: "failure", message: stdinPrompt && advisorFlagErrorHint(stderr)
+			? withDoctor("Large prompts require Agy 1.1.15+ with stdin support. Run `agy update`. " + stderr.trim())
+			: agyFailureMessage(action, { code, killed: false, stderr }) };
 
 		const text = final.trim();
 		if (!text) return { status: "failure", message: withDoctor(stderr.trim() || emptyTextMessage) };

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" },
@@ -1475,7 +1477,8 @@ function serializeShowTurns(turns: readonly ShowTurn[]): string {
 	return turns.flatMap((turn) => turn.entries).join("\n\n");
 }
 
-export function captureShowTranscript(ctx: ExtensionCommandContext, turnsRequested: number): BroSource | undefined {
+export function captureShowTranscript(ctx: ExtensionCommandContext, turnsRequested: number, maxLength = MAX_TEXT_LENGTH): BroSource | undefined {
+	if (!Number.isSafeInteger(maxLength) || maxLength < 128) throw new Error("Transcript limit must be an integer of at least 128 characters.");
 	const turns: ShowTurn[] = [];
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type !== "message") continue;
@@ -1503,7 +1506,7 @@ export function captureShowTranscript(ctx: ExtensionCommandContext, turnsRequest
 	if (seen === 0) return undefined;
 
 	let text = serializeShowTurns(turns.slice(start));
-	while (text.length > MAX_TEXT_LENGTH && start < turns.length - 1) {
+	while (text.length > maxLength && start < turns.length - 1) {
 		let next = turns.length;
 		for (let index = start + 1; index < turns.length; index += 1) {
 			if (turns[index]!.startsTurn) {
@@ -1515,7 +1518,22 @@ export function captureShowTranscript(ctx: ExtensionCommandContext, turnsRequest
 		start = next;
 		text = serializeShowTurns(turns.slice(start));
 	}
-	if (text.length > MAX_TEXT_LENGTH) text = `${text.slice(0, MAX_TEXT_LENGTH)}\n[… transcript truncated …]`;
+	if (text.length > maxLength) {
+		// Prefer the newest complete messages even within an oversized single turn.
+		const entries = turns.slice(start).flatMap(turn => turn.entries);
+		const notice = "[… earlier messages truncated …]\n";
+		while (entries.length > 1 && entries.join("\n\n").length + notice.length > maxLength) entries.shift();
+		text = entries.join("\n\n");
+		if (text.length + notice.length > maxLength) {
+			const newline = text.indexOf("\n");
+			const header = text.slice(0, newline);
+			const content = JSON.parse(text.slice(newline + 1)) as string;
+			const marker = "[… earlier text truncated …] ";
+			let tail = content.slice(-(maxLength - header.length - marker.length - 8));
+			while (`${header}\n${JSON.stringify(marker + tail)}`.length > maxLength) tail = tail.slice(Math.max(1, Math.floor(tail.length / 10)));
+			text = `${header}\n${JSON.stringify(marker + tail)}`;
+		} else text = notice + text;
+	}
 	const kept = turns.slice(start).filter((turn) => turn.startsTurn).length;
 	return { text: text.trim(), label: `last ${Math.max(1, kept)} turn${kept > 1 ? "s" : ""} · conversation only` };
 }
@@ -1802,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,
@@ -1809,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 },
@@ -1819,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> {
@@ -1976,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]!;
@@ -2486,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;
 	}
@@ -2603,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;
 	}
@@ -2639,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
@@ -2800,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);
 
@@ -2908,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);
@@ -3173,6 +3201,7 @@ class BtwModal implements Focusable {
 	}
 
 	setNotice(notice: string): void {
+		if (this.disposed) return;
 		this.notice = notice;
 		this.tui.requestRender();
 	}
@@ -3237,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);
@@ -3252,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),
@@ -3266,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;
 	}
@@ -3322,10 +3351,7 @@ async function openBtwModal(
 				}
 				if (thread.turns.length === 0) {
 					thread.conversationId = undefined;
-					let context = captureShowTranscript(ctx, BTW_CONTEXT_TURNS)?.text;
-					if (context && context.length > BTW_CONTEXT_MAX) {
-						context = `${context.slice(0, BTW_CONTEXT_MAX)}\n[… context truncated …]`;
-					}
+					const context = captureShowTranscript(ctx, BTW_CONTEXT_TURNS, BTW_CONTEXT_MAX)?.text;
 					thread.context = context;
 				}
 				// Resume natively when possible; otherwise seed the fresh native session with the main-session
@@ -3412,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;
@@ -3616,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");
@@ -3737,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;
 						}
@@ -3757,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.2",
+  "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"; }