pi-bro 0.19.5 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.21.0] - 2026-10-04
+
+### Added
+
+- `bro-preferences.md`: tell Bro about yourself and how you like answers. Bro adds it, JSON-quoted and labelled, to every explain, `/bro show`, and `/bro btw` prompt alongside its own instructions; the advisor never receives it. Preferences can change wording, tone, technical depth, and the answer language (code, commands, paths, names, and numbers stay verbatim). In Show they change only wording and language. Per-run choices (the mode, **M**, a Show steering query, a BTW question) win over them, and Bro's source rules, Show's hard rules, and BTW access mode always apply. Blank or missing preferences leave every prompt byte-identical to 0.20.0 (#94).
+- `/bro preferences` edits the file (**Ctrl+S** save, **Ctrl+K** delete, **Ctrl+C** copy, **Esc** close). Without a file it opens with unsaved starter text that restates the old built-in audience and brief wording. Saves are checked against the 4,000-character limit, and an oversize file still opens so it can be trimmed (#94).
+- The modal header shows `· prefs` when preferences shaped an explanation, drawing, or BTW turn; `/bro open` keeps the result's tag (#94).
+
+### Changed
+
+- Modes, **M**, and the source guard now always apply; nothing disables them (#94).
+- Preferences over 4,000 characters stop explain, Show, and BTW with an actionable error before any backend call instead of being truncated. `/bro doctor` replaces its Prompt check with a Preferences check, and `/bro help` shows the preferences status (#94).
+- When preferences change mid-thread, the next BTW turn starts a fresh native session reseeded with the quoted thread, on every backend, so old preferences don't linger in the backend's history (#94).
+
+### Removed
+
+- **Breaking:** `bro-prompt.md` is no longer read. It was a full replacement template for the explain prompt that disabled modes, **M**, and the source guard and did not affect Show or BTW. Bro does not migrate, rename, or delete it. Move what you want to keep into `/bro preferences`, and use `/bro mode brief` for the original ELI-simpleton instruction (#94).
+
+## [0.20.0] - 2026-10-04
+
+### Added
+
+- Press **M** in an explanation modal to re-simplify the captured source in the next explain mode (brief → balanced → faithful). The switch applies to that explanation only: the saved mode is unchanged, **R** and `/bro open` keep the shown mode, and a second press while Bro is working cancels and skips ahead. The header now names the mode; **M** is hidden for Show, Doctor, and custom prompts.
+
+### Changed
+
+- `/bro btw` now tells the model who it is writing for: a tired reader who needs the point first, in plain words, at a length that fits the question, in the language they asked in. The guidance describes the reader and the goal rather than a fixed template. In full-permission mode, answers say which points were checked in the workspace.
+
 ## [0.19.5] - 2026-10-01
 
 ### Changed

package/README.md

@@ -56,7 +56,8 @@ installing it, use `pi -e npm:pi-bro`.
 | Recent session turns | `/bro show` | Draws the last turns' conversation text as shapes instead of prose (tool calls, tool results, reasoning, and images are omitted). |
 | Any of the above, auto-detected | `/bro <input>` | Routes a lone URL to the webpage reader, an existing workspace file with a supported extension to the document reader, and anything else to pasted text. |
 
-Pressing **R** simplifies the captured source again. These commands capture a
+Pressing **R** simplifies the captured source again in the mode shown, and
+**M** re-simplifies it in the next mode. These commands capture a
 new source: `/bro text`, `/bro file`, `/bro url`, and `/bro show`. Giving `/bro` a URL, path, or
 text directly captures a new source the same way.
 
@@ -71,8 +72,9 @@ text directly captures a new source the same way.
 | `/bro url <url>` | Explain one public, text-based webpage. |
 | `/bro open` | Reopen the latest explanation without calling the simplifier again. |
 | `/bro show [n-turns] [query]` | Draw recent session turns (default last 1) as shapes instead of prose, from user and assistant conversation text only — tool calls, tool results, reasoning, and images are omitted. An optional query steers what the shapes focus on, with or without a leading turn count. |
-| `/bro doctor` | Check Bro's settings, prompt, and each selected backend, with the effective backend/model/effort per feature. |
+| `/bro doctor` | Check Bro's settings, preferences, and each selected backend, with the effective backend/model/effort per feature. |
 | `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
+| `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](#preferences). |
 | `/bro config` | Open an interactive settings screen for the shared default backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor) overrides. |
 | `/bro btw [question]` | Open a side conversation in a modal, seeded with recent main-session context. Starts conversation-only; type `/mode` inside to toggle full permission (read and edit the workspace) without losing the thread. |
 | `/bro advisor` | Quick notice of whether the executor's `bro_advisor` tool is available right now, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`. |
@@ -90,8 +92,10 @@ Giving `/bro` the input directly works the same way:
 ## Explanation modes
 
 Bro treats the source as data, rejects embedded instructions, preserves its
-language, and avoids adding facts, advice, or conclusions in every mode. Choose
-a persistent mode with `/bro mode`:
+language (unless your [preferences](#preferences) name another), and avoids
+adding facts, advice, or conclusions in every mode. Choose
+a persistent mode with `/bro mode`, or press **M** in an explanation to try the
+next mode without saving it:
 
 - **`brief`**: Uses the original audience-led ELI-simpleton prompt with no fixed
   word target.
@@ -105,13 +109,19 @@ a persistent mode with `/bro mode`:
 - **Mouse wheel / trackpad**: Scroll in regular or fullscreen mode
 - **↑ / ↓**: Scroll in any mode
 - **C**: Copy the complete explanation
-- **R**: Simplify the captured source or run the current Doctor check again
+- **R**: Simplify the captured source again in the mode shown, or run the
+  current Doctor check again
+- **M**: Re-simplify the captured source in the next mode (brief → balanced →
+  faithful → brief). It applies to this explanation only and does not change
+  the mode saved by `/bro mode`; pressing it again while Bro is working skips
+  ahead
 - **O**: Open the HTML diagram when a show reply contains one
 - **Esc**: Close the modal, or cancel while Bro is working
 
 The modal header shows the model and reasoning effort the explanation or
-drawing used (`default` when the model's own effort applies); `/bro open`
-keeps the original label.
+drawing used (`default` when the model's own effort applies), followed by the
+explanation mode, and `prefs` when your [preferences](#preferences) shaped the
+result; `/bro open` keeps the original labels, mode, and tag.
 
 Bro temporarily captures mouse input while its modal is open. Native mouse
 selection may be unavailable or visually extend outside the modal depending on
@@ -123,7 +133,9 @@ your terminal mode; press **C** to copy the complete explanation reliably.
 `/bro btw` opens a separate multi-turn conversation in a modal, so you can ask
 a quick side question while the main agent keeps working. It runs through the
 selected backend and never adds anything to Pi's conversation unless you
-explicitly insert it into the editor.
+explicitly insert it into the editor. Bro writes for a tired reader: the point
+first, in plain words, at a length that fits the question, in the language you
+asked in.
 
 - `/bro btw <question>` asks immediately; `/bro btw` opens an empty thread.
   Reopening keeps the thread and its mode.
@@ -232,7 +244,9 @@ assistant conversation text, including every intermediate assistant message in
 a turn — tool calls, tool results, reasoning, and images never leave the
 session. It runs the same backend-specific model call and shows the result
 in the same modal, never touching your conversation. `/bro show` uses its own
-draw prompt; the explanation modes and `bro-prompt.md` do not affect it.
+draw prompt; the explanation modes do not affect it. Your
+[preferences](#preferences) can change only its wording and language, never
+which shapes it draws or its rules.
 
 Because the draw model only ever sees conversation text, its shapes reflect
 what was *reported* in the conversation — what the assistant said it did or
@@ -684,7 +698,7 @@ it as a PDF, then use `/bro file <path>`.
 ## Check your setup
 
 Run `/bro doctor` when Bro is newly installed or something is not working. It
-checks Bro's settings and prompt, then probes only the backends some feature
+checks Bro's settings and preferences, then probes only the backends some feature
 actually selects, and reports the effective backend/model/effort for each
 feature. Failed checks explain what to fix.
 
@@ -707,8 +721,9 @@ and any per-capability (explain/show/btw/advisor) overrides, the explanation
 mode, and the default show turn count. Changes save immediately. Esc inside a
 picker cancels that pick; Esc on the settings screen closes it, keeping
 whatever was already saved. A failed save (for example, a read-only file) is
-shown inline. `/bro mode` changes the mode directly, and `/bro help` shows the
-active settings and file path.
+shown inline. `/bro mode` changes the mode directly (**M** in an explanation
+tries another mode without saving it), and `/bro help` shows the active settings
+and file path.
 
 Settings live in this user-editable file, created when the extension loads
 (under `$PI_CODING_AGENT_DIR` instead when that is set):
@@ -799,41 +814,66 @@ When resolving turn count for `/bro show`:
 1. **Command argument**: an explicit count like `/bro show 3` or `/bro show 1 query` overrides for that run.
 2. **Saved setting**: `showTurns` (defaults to 1).
 
-When resolving the explanation prompt (`explain` capability only):
-1. **Custom prompt**: a valid `~/.pi/agent/bro-prompt.md` (or `$PI_CODING_AGENT_DIR/bro-prompt.md`) completely overrides all built-in modes.
-2. **Saved mode**: `mode` in `bro-settings.json` (defaults to `balanced`).
-3. `bro-prompt.md` applies only to `/bro`, `/bro text`, `/bro file`, and `/bro url`; it does not affect `/bro show`, `/bro btw`, or `bro_advisor`.
+When shaping an answer, each part has one owner:
 
-## Custom prompt
+| Part | Decided by |
+| --- | --- |
+| Bro's source rules: quoted source treated as data, no added facts, Show's traceability rules, BTW access mode | Built in; nothing overrides them |
+| How much of the source an explanation keeps | The mode: **M** for one explanation, otherwise the saved `mode` |
+| What a Show drawing focuses on | The steering query |
+| Who the answer is for: wording, tone, depth, and answer language | Your [preferences](#preferences), otherwise Bro's built-in defaults |
 
-Bro uses a built-in prompt by default. To use your own, create:
+## Preferences
 
-```text
-~/.pi/agent/bro-prompt.md
-```
+Tell Bro about yourself and how you like answers. Bro adds what you write to
+every explain, `/bro show`, and `/bro btw` prompt as a labelled section,
+alongside its own instructions. It never replaces them: modes, **M**, and the
+source rules keep working. The advisor never receives your preferences; use
+`/bro advisor-steer` for it.
 
-Your prompt must include `{{response}}` exactly once. For example:
+Run `/bro preferences` to edit them: **Ctrl+S** saves, **Ctrl+K** deletes the
+file, **Ctrl+C** copies, and **Esc** closes without saving. The first time,
+the editor opens with this starter text, which is not saved until you press
+**Ctrl+S**:
 
 ```md
-Explain this in plain English in no more than 200 words.
-Keep important warnings and next steps.
-
-Text to explain:
-{{response}}
+## About me
+I'm an overworked white-collar worker, and so are my colleagues. By the end of a
+hard day our brains are fried and we can only handle simple language, no matter
+how sharp we are at our best.
+
+## How I like answers
+- Explain it like I'm a simpleton: plain, everyday words.
+- Go easy on analogies. No forced ones.
 ```
 
-Bro re-reads this file every time you simplify, so your edits take effect
-immediately without reloading Pi. Bro never creates or modifies this file.
-Existing valid custom prompts continue working unchanged.
+You can also edit the file directly (under `$PI_CODING_AGENT_DIR` instead when
+that is set):
+
+```text
+~/.pi/agent/bro-preferences.md
+```
 
-A valid custom prompt fully overrides all built-in mode instructions.
-`/bro show` is separate: it always uses its own built-in draw prompt and
-ignores `bro-prompt.md`. `/bro
-mode` still changes the saved mode, but that mode remains inactive while
-`bro-prompt.md` exists. Remove or rename `bro-prompt.md` to use the saved
-built-in mode again. If the custom prompt is invalid—for example, it has no
-`{{response}}` placeholder or has more than one—Bro blocks the explanation;
-run `/bro doctor` for the exact problem.
+- **Free-form**: no placeholder or structure is required. Bro re-reads the
+  file on every request, so edits apply next time. A missing or empty file
+  means no preferences, and Bro's prompts are then exactly the built-in ones.
+- **What preferences can change**: wording, tone, technical depth, length in
+  BTW, and the answer language. If you name a language, code, commands, paths,
+  names, and numbers still stay exactly as written. In `/bro show`,
+  preferences only change wording and language. A per-run choice (the mode,
+  **M**, a Show steering query, or what a BTW question asks for) wins over a
+  standing preference.
+- **Limit**: 4,000 characters, because the text goes with every request. A
+  longer file stops explain, Show, and BTW with an error until you trim it;
+  Bro never cuts it silently. `/bro doctor` reports the problem, and the
+  editor still opens the file so you can fix it.
+- **BTW threads**: when your preferences change, the next side question starts
+  a fresh backend session that is caught up on the thread, so old preferences
+  don't linger.
+
+`bro-prompt.md`, the full prompt template from earlier versions, is no longer
+read. Move what you want to keep into `/bro preferences`, and choose
+`/bro mode brief` for the original ELI-simpleton instruction.
 
 
 ## Privacy and safety
@@ -846,6 +886,9 @@ run `/bro doctor` for the exact problem.
   seeded main-session conversation text (plus earlier turns when a native
   session is reseeded) to the selected backend. In full permission mode the
   side agent can additionally read and edit the workspace.
+- **Preferences**: `bro-preferences.md` is sent with every explain, Show,
+  and BTW request to the selected backend. It is never sent to the advisor or
+  to Pi's main model.
 - **Advisor requests**: `bro_advisor` sends the executor agent's system
   instructions, active tool list (excluding `bro_advisor`), ordered
   conversation history including tool calls and tool results (unlike Show,

package/backend.ts

@@ -2,7 +2,6 @@ import { type ChildProcess, spawn } from "node:child_process";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createInterface } from "node:readline";
 
 // Shared internal execution boundary for all four Bro features (explain, show, btw, advisor).
 // This implements docs/plans/2026-09-22-shared-backend-design.md for Agy (all features) and the
@@ -126,15 +125,20 @@ const DEFAULT_KILL_ESCALATION_MS = 5_000;
 export function beginAttempt(child: ChildProcess, signal: AbortSignal, deadlineMs: number, killEscalationMs: number): Attempt {
 	let cause: StopCause | undefined;
 	let killTimer: ReturnType<typeof setTimeout> | undefined;
+	let isClosed = false;
 	let finishClose: (value: { code: number | null; exitSignal: NodeJS.Signals | null }) => void;
 	const closed = new Promise<{ code: number | null; exitSignal: NodeJS.Signals | null }>((resolve) => {
-		finishClose = resolve;
-		child.once("close", (code, exitSignal) => resolve({ code, exitSignal }));
+		finishClose = (val) => {
+			isClosed = true;
+			resolve(val);
+		};
+		child.once("close", (code, exitSignal) => finishClose({ code, exitSignal }));
 	});
 
 	const stop = (next: StopCause) => {
 		if (cause) return; // latched: the first stop cause wins
 		cause = next;
+		if (isClosed) return;
 		killAgyGroup(child, "SIGTERM");
 		killTimer = setTimeout(() => {
 			killAgyGroup(child, "SIGKILL");
@@ -270,7 +274,6 @@ async function executeArgvPrint(
 		let partial = "";
 		let final = "";
 		let conversationId = request.continuation?.id;
-		let parseError: string | undefined;
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -285,44 +288,31 @@ async function executeArgvPrint(
 			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;
-				try {
-					if (isBtw) {
-						const parsed = parseBtwAgyLine(line);
-						if (parsed.conversationId) conversationId = parsed.conversationId;
-						if (parsed.error) {
-							parseError = parsed.error;
-							attempt.stop("protocol");
-							break;
-						}
-						if (parsed.delta) {
-							partial += parsed.delta;
-							onProgress?.({ kind: "text", text: partial });
-						}
-						if (parsed.result !== undefined) final = parsed.result;
-					} else {
-						const parsed = parseExplainLine(line);
-						if (parsed.delta) {
-							partial += parsed.delta;
-							onProgress?.({ kind: "text", text: partial });
-						}
-						if (parsed.result !== undefined) final = parsed.result;
-					}
-				} catch (error) {
-					parseError = errorMessage(error);
-					attempt.stop("protocol");
-					break;
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			if (isBtw) {
+				const parsed = parseBtwAgyLine(line);
+				if (parsed.conversationId) conversationId = parsed.conversationId;
+				if (parsed.error) throw new Error(parsed.error);
+				if (parsed.delta) {
+					partial += parsed.delta;
+					onProgress?.({ kind: "text", text: partial });
+				}
+				if (parsed.result !== undefined) final = parsed.result;
+			} else {
+				const parsed = parseExplainLine(line);
+				if (parsed.delta) {
+					partial += parsed.delta;
+					onProgress?.({ kind: "text", text: partial });
 				}
+				if (parsed.result !== undefined) final = parsed.result;
 			}
-		} finally {
-			lines.close();
-		}
+		};
+
+		const finishFraming = frameStdoutLines(child, attempt, "Agy", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const parseError = finishFraming();
 		attempt.dispose();
 		const cause = attempt.causeOf();
 
@@ -348,8 +338,69 @@ async function executeArgvPrint(
 }
 
 // Guards only against a single runaway line with no newline (a protocol break, not a real
-// response size) -- agy's real NDJSON lines are far smaller than this.
-const ADVISOR_MAX_STDOUT_LINE_CHARS = 2_000_000;
+// response size) -- real NDJSON lines across all backends are far smaller than this.
+export const MAX_STDOUT_LINE_CHARS = 2_000_000;
+
+export function frameStdoutLines(
+	child: ChildProcess,
+	attempt: Attempt,
+	backendName: string,
+	onLine: (line: string) => void,
+): () => string | undefined {
+	const oversize = `${backendName} emitted a stdout line over ${MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
+	let buffer = "";
+	let protocolError: string | undefined;
+
+	const fail = (message: string) => {
+		protocolError ??= message;
+		buffer = "";
+		attempt.stop("protocol");
+	};
+
+	child.stdout?.setEncoding("utf8");
+
+	child.stdout?.on("error", (error) => {
+		fail(`${backendName} stdout error: ${errorMessage(error)}`);
+	});
+
+	child.stdout?.on("data", (chunk: string) => {
+		if (attempt.causeOf()) return;
+		const parts = (buffer + chunk).split(/\r?\n/);
+		buffer = parts.pop() ?? "";
+
+		const pendingLen = buffer.endsWith("\r") ? buffer.length - 1 : buffer.length;
+		if (pendingLen > MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > MAX_STDOUT_LINE_CHARS)) {
+			return fail(oversize);
+		}
+
+		for (const line of parts) {
+			if (attempt.causeOf()) return;
+			if (!line.trim()) continue;
+			try {
+				onLine(line);
+			} catch (error) {
+				return fail(errorMessage(error));
+			}
+		}
+	});
+
+	return (): string | undefined => {
+		if (!attempt.causeOf() && buffer.trim()) {
+			const line = buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+			if (line.length > MAX_STDOUT_LINE_CHARS) {
+				fail(oversize);
+			} else if (line.trim()) {
+				try {
+					onLine(line);
+				} catch (error) {
+					fail(errorMessage(error));
+				}
+			}
+		}
+		buffer = "";
+		return protocolError;
+	};
+}
 
 type AdvisorAgyEvent = {
 	event?: string;
@@ -417,9 +468,7 @@ async function executeAdvisorStdin(
 	let stderr = "";
 	let final: string | undefined;
 	let terminalError: string | undefined;
-	let protocolError: string | undefined;
 	let sawTerminal = false;
-	let stdoutBuffer = "";
 
 	child.stderr?.setEncoding("utf8");
 	child.stderr?.on("data", (chunk: string) => {
@@ -455,37 +504,11 @@ async function executeAdvisorStdin(
 		}
 	};
 
-	child.stdout?.setEncoding("utf8");
-	child.stdout?.on("data", (chunk: string) => {
-		stdoutBuffer += chunk;
-		const parts = stdoutBuffer.split(/\r?\n/);
-		stdoutBuffer = parts.pop() ?? "";
-		if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-			protocolError ??= `Agy emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-			stdoutBuffer = "";
-			attempt.stop("protocol");
-			return;
-		}
-		for (const line of parts) {
-			try {
-				handleLine(line);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-				attempt.stop("protocol");
-				return;
-			}
-		}
-	});
+	const finishFraming = frameStdoutLines(child, attempt, "Agy", handleLine);
 
 	const { code, exitSignal } = await attempt.closed;
+	const protocolError = finishFraming();
 	attempt.dispose();
-	if (stdoutBuffer.trim() && !sawTerminal) {
-		try {
-			handleLine(stdoutBuffer);
-		} catch (error) {
-			protocolError ??= errorMessage(error);
-		}
-	}
 
 	const cause = attempt.causeOf();
 	if (cause === "cancelled") return { status: "cancelled", message: "Canceled." };
@@ -587,8 +610,6 @@ async function executeClaude(
 		let partial = "";
 		let final: string | undefined;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 		let initSessionId: string | undefined;
 		let resultSessionId: string | undefined;
 
@@ -623,6 +644,7 @@ async function executeClaude(
 			}
 			if (isAdvisor && topLevel && event.type === "assistant" && Array.isArray(event.message?.content)) {
 				for (const block of event.message.content as Array<{ type?: unknown; name?: unknown; text?: unknown }>) {
+					if (attempt.causeOf()) break;
 					const label =
 						block?.type === "tool_use" && typeof block.name === "string"
 							? block.name.trim()
@@ -653,37 +675,11 @@ async function executeClaude(
 			}
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Claude emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Claude", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial || undefined;
 		const cause = attempt.causeOf();
@@ -815,8 +811,6 @@ async function executeGrok(
 		let resultSessionId: string | undefined;
 		let final: string | undefined;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -869,6 +863,7 @@ async function executeGrok(
 			}
 			if (isAdvisor && event.type === "assistant" && Array.isArray(message?.content)) {
 				for (const block of message.content as Array<{ type?: unknown; name?: unknown; text?: unknown }>) {
+					if (attempt.causeOf()) break;
 					const label =
 						block?.type === "tool_use" && typeof block.name === "string"
 							? block.name.trim()
@@ -904,37 +899,11 @@ async function executeGrok(
 			terminalError ??= `Grok failed: ${detail}`;
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Grok emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Grok", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial ? { partialText: partial } : {};
 		const cause = attempt.causeOf();
@@ -1076,8 +1045,6 @@ async function executeCodex(
 		let final: string | undefined;
 		let sawTerminal = false;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -1133,37 +1100,11 @@ async function executeCodex(
 			}
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Codex emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Codex", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial ? { partialText: partial } : {};
 		const cause = attempt.causeOf();
@@ -1279,8 +1220,6 @@ async function executeMuse(
 		let final: string | undefined;
 		let sawTerminal = false;
 		let terminalError: string | undefined;
-		let protocolError: string | undefined;
-		let stdoutBuffer = "";
 
 		child.stderr?.setEncoding("utf8");
 		child.stderr?.on("data", (chunk: string) => {
@@ -1358,37 +1297,11 @@ async function executeMuse(
 			}
 		};
 
-		child.stdout?.setEncoding("utf8");
-		child.stdout?.on("data", (chunk: string) => {
-			stdoutBuffer += chunk;
-			const parts = stdoutBuffer.split(/\r?\n/);
-			stdoutBuffer = parts.pop() ?? "";
-			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
-				protocolError ??= `Muse emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
-				stdoutBuffer = "";
-				attempt.stop("protocol");
-				return;
-			}
-			for (const line of parts) {
-				try {
-					handleLine(line);
-				} catch (error) {
-					protocolError ??= errorMessage(error);
-					attempt.stop("protocol");
-					return;
-				}
-			}
-		});
+		const finishFraming = frameStdoutLines(child, attempt, "Muse", handleLine);
 
 		const { code, exitSignal } = await attempt.closed;
+		const protocolError = finishFraming();
 		attempt.dispose();
-		if (stdoutBuffer.trim()) {
-			try {
-				handleLine(stdoutBuffer);
-			} catch (error) {
-				protocolError ??= errorMessage(error);
-			}
-		}
 
 		const partialText = partial ? { partialText: partial } : {};
 		const cause = attempt.causeOf();