pi-bro 0.18.1 → 0.19.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.19.1] - 2026-09-30
+
+### Fixed
+
+- Always enforce Bro's restrictive content policy on generated HTML, including when model output contains a permissive policy or CSP-looking comment (#69).
+- Isolate smoke-test temporary artifacts and block real backend CLIs during offline tests. Order settings mutations by RPC acknowledgements instead of fixed sleeps, and support spaces in settings-test checkout paths (#70).
+
+## [0.19.0] - 2026-09-25
+
+### Added
+
+- Support for OpenAI Codex CLI (`codex`) across all features: explain, show, BTW, and advisor. Explain and show run under a read-only sandbox with ephemeral session handling; BTW continues natively via `resume` across both conversation-only and full-permission modes; advisor runs in the workspace with sandbox bypassed. Supports seeded models `gpt-5.5` and `gpt-5.4` plus custom model IDs, and reasoning efforts `low`, `medium`, `high`, `xhigh`.
+- Support for Meta Muse Code (`muse`) across all features: explain, show, BTW, and advisor. Explain and show run in a scratch directory with approval, non-shell write, and shell disabled; BTW continues natively via `--session-id` across `/mode` switches; advisor runs in the workspace with `--yolo`. Supports seeded models `muse-spark-1.3-contributor` and `muse-spark-1.3` plus custom model IDs, and reasoning efforts `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (omitted for model default).
+- Configuration modal support in `/bro config` for Codex and Muse, including atomic model selection, custom model ID inputs, and dynamic reasoning effort dropdowns.
+- Doctor diagnostic checks for Codex (version and `codex login status` authentication probe) and Muse (version probe).
+
 ## [0.18.1] - 2026-09-30
 
 ### Fixed

package/README.md

@@ -5,13 +5,16 @@ plain-language explanation — or open a separate side conversation with
 `/bro btw` — without adding anything to your main agent's context.
 
 `pi-bro` is an extension for [Earendil Pi](https://github.com/earendil-works/pi).
+Experimental [PiG 0.3.0 compatibility](docs/pig-compatibility.md) uses the same npm package and requires Node.js. See the compatibility notes for verified coverage and the PiG RPC tool-exclusion limitation.
 It opens explanations in a separate modal and runs them through a CLI backend
 you already have installed and signed in to. Explain, show, BTW, and the
-advisor all work on all three backends:
+advisor all work across five backends:
 
 - [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`) — the default for new settings
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
 - Grok Build (`grok`)
+- [Codex CLI](https://github.com/openai/codex) (`codex`)
+- Meta Muse Code (`muse`)
 
 You only need the backend(s) you select; Agy is the default, not a requirement.
 
@@ -25,7 +28,7 @@ for the default). Then install Bro:
 pi install npm:pi-bro
 ```
 
-Restart Pi or run `/reload`. If you use Claude Code or Grok instead of Agy,
+Restart Pi or run `/reload`. If you use Claude Code, Grok, Codex, or Muse instead of Agy,
 choose it in `/bro config` (for everything, or per feature). Then try:
 
 ```text
@@ -686,6 +689,9 @@ feature. Failed checks explain what to fix.
 - **Claude Code**: installed version and configured authentication.
 - **Grok**: installed version only; authentication and connectivity are not
   verified.
+- **Codex**: installed version and configured authentication.
+- **Muse**: installed version only; authentication and connectivity are not
+  verified.
 
 Doctor never sends source text or runs a model completion. A successful check
 confirms the setup but cannot guarantee that a later provider request will
@@ -729,7 +735,7 @@ Bro reads the file again before each request, so manual edits apply next time.
   Omitted overrides inherit `default`.
 - `effort` must be one the backend offers (`default` omits it and lets the
   model decide). Agy selections are normalized against Agy's installed model
-  catalog. Claude and Grok accept seeded or custom model IDs; a model/effort
+  catalog. Claude, Grok, Codex, and Muse accept seeded or custom model IDs; a model/effort
   combination the account does not support fails with the backend's own error
   instead of silently falling back.
 - `mode` is `brief`, `balanced` (the default), or `faithful`. `showTurns` is
@@ -751,19 +757,27 @@ data under their own settings and policies.
 | **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
 | **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
 | **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
+| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed |
+| **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) |
 
 - Grok always runs with its sandbox off and permissions bypassed; its tools,
   hooks, skills, plugins, and MCP may remain available. "Answer only from the
   supplied context" is a request, not an enforced restriction.
+- Codex's read-only sandbox is not a tool-free mode: workspace reads and
+  sandboxed commands remain available. Bro does not disable configured MCP
+  servers or web search; their access is governed by Codex configuration.
+- Muse's restricted mode disables write and shell tools and approval prompts,
+  not all tools: workspace reads and web tools remain available without approval.
+  It is not a tool-free or network-isolated mode.
 - Claude's restrictions are tool/configuration settings (with safe mode), not
   an OS sandbox; built-in and managed Claude behavior can remain. Running a
   permission-bypassing mode as root may be rejected by Claude.
 - BTW continues natively: Agy by conversation ID, Claude and Grok by
-  `--resume` of the same session, including across `/mode` switches. An Agy
-  conversation stays bound to the workspace it started in, so after a `/mode`
-  switch — or whenever a thread has turns but no native session ID — Bro starts
-  a fresh native session seeded with the main-session context and every
-  earlier turn.
+  `--resume`, Codex by `resume`, and Muse by `--session-id` of the same session,
+  including across `/mode` switches. An Agy conversation stays bound to the
+  workspace it started in, so after a `/mode` switch — or whenever a thread
+  has turns but no native session ID — Bro starts a fresh native session
+  seeded with the main-session context and every earlier turn.
 - Cancellation, deadlines, and invalid output streams stop the backend's
   process group on POSIX, escalating after a five-second grace period. On
   Windows only the direct child is targeted. Detached shell work or external

package/backend.ts

@@ -15,10 +15,14 @@ export type BackendAccess = "restricted" | "workspace-full";
 export type AgySelection = { model: string; effort?: "low" | "medium" | "high" };
 export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 export const GROK_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
+export const CODEX_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
+export const MUSE_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type BackendSelection =
 	| ({ backend?: "agy" } & AgySelection)
 	| { backend: "claude"; model: string; effort?: (typeof CLAUDE_EFFORTS)[number] }
-	| { backend: "grok"; model: string; effort?: (typeof GROK_EFFORTS)[number] };
+	| { backend: "grok"; model: string; effort?: (typeof GROK_EFFORTS)[number] }
+	| { backend: "codex"; model: string; effort?: (typeof CODEX_EFFORTS)[number] }
+	| { backend: "muse"; model: string; effort?: (typeof MUSE_EFFORTS)[number] };
 export type BackendContinuation = { id: string };
 export type BackendProgress = { kind: "text"; text: string } | { kind: "activity"; label: string; timestamp: number };
 export type BackendOnProgress = (progress: BackendProgress) => void;
@@ -73,7 +77,11 @@ function processStartMessage(processError: NodeJS.ErrnoException, cli = "Agy"):
 			? "Agy could not start. Make sure Agy is installed and on PATH, then run `/bro doctor`."
 			: cli === "Grok"
 				? "Grok could not start. Make sure `grok` is installed and on PATH, then run `/bro doctor`."
-				: "Claude Code could not start. Make sure `claude` is installed and on PATH, then run `/bro doctor`.";
+				: cli === "Codex"
+					? "Codex could not start. Make sure `codex` is installed and on PATH, then run `/bro doctor`."
+					: cli === "Muse"
+						? "Muse could not start. Make sure `muse` is installed and on PATH, then run `/bro doctor`."
+						: "Claude Code could not start. Make sure `claude` is installed and on PATH, then run `/bro doctor`.";
 	}
 	return `${cli} could not start: ${processError.message}\n\nRun \`/bro doctor\` for setup help.`;
 }
@@ -495,7 +503,7 @@ 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", _feature: BackendFeature): boolean {
+export function backendSupports(_backend: "agy" | "claude" | "grok" | "codex" | "muse", _feature: BackendFeature): boolean {
 	return true;
 }
 
@@ -964,6 +972,458 @@ async function executeGrok(
 	}
 }
 
+type CodexEvent = {
+	type?: unknown;
+	thread_id?: unknown;
+	item?: {
+		id?: unknown;
+		type?: unknown;
+		text?: unknown;
+		message?: unknown;
+		content?: unknown;
+		command?: unknown;
+		cmd?: unknown;
+		path?: unknown;
+		pattern?: unknown;
+		query?: unknown;
+	};
+	error?: { message?: unknown };
+	message?: unknown;
+};
+
+function extractCodexItemText(item: CodexEvent["item"]): string | undefined {
+	if (!item) return undefined;
+	if (typeof item.text === "string") return item.text;
+	if (typeof item.message === "string") return item.message;
+	if (typeof item.content === "string") return item.content;
+	return undefined;
+}
+
+function codexActivityFromEvent(event: CodexEvent): string | undefined {
+	const item = event.item;
+	if (!item || item.type === "reasoning") return undefined;
+	if (event.type === "item.started" || event.type === "item.completed") {
+		if (item.type !== "agent_message") {
+			const itemType = typeof item.type === "string" ? item.type : "item";
+			const candidate = [item.command, item.cmd, item.path, item.pattern, item.query]
+				.find((v) => typeof v === "string" && v.trim());
+			const preview = typeof candidate === "string" ? candidate.replace(/\s+/g, " ").trim() : "";
+			return `${itemType}${preview ? ` ${preview}` : ""}`;
+		}
+		if (item.type === "agent_message") {
+			const text = extractCodexItemText(item);
+			return text?.split("\n").find((line) => line.trim())?.trim();
+		}
+	}
+	return undefined;
+}
+
+async function executeCodex(
+	request: BackendRequest,
+	selection: { model: string; effort?: string },
+	signal: AbortSignal,
+	onProgress: BackendOnProgress | undefined,
+	killEscalationMs: number,
+	deadlineMsOverride: number | undefined,
+): Promise<BackendOutcome> {
+	const isAdvisor = request.feature === "advisor";
+	const isBtw = request.feature === "btw";
+	const full = request.access === "workspace-full";
+	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = isAdvisor ? "Codex returned no advice." : isBtw ? "Codex returned no answer for the side question." : "Codex returned no final explanation.";
+
+	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+	const runDirectory = isAdvisor || isBtw ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	if (signal.aborted) {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+		return { status: "cancelled", message: "Canceled." };
+	}
+
+	try {
+		const permissionArgs = full ? ["--dangerously-bypass-approvals-and-sandbox"] : ["--sandbox", "read-only"];
+		const resume = isBtw && request.continuation;
+		const args = [
+			"exec",
+			...permissionArgs,
+			...(resume ? ["resume"] : []),
+			"--json",
+			"--skip-git-repo-check",
+			...(!isBtw ? ["--ephemeral"] : []),
+			"--model",
+			selection.model,
+			...(selection.effort ? ["-c", `model_reasoning_effort="${selection.effort}"`] : []),
+			...(resume ? [request.continuation!.id, "-"] : ["--", "-"]),
+		];
+
+		const child = spawn("codex", args, {
+			cwd: runDirectory ?? request.cwd,
+			stdio: ["pipe", "pipe", "pipe"],
+			windowsHide: true,
+			detached: process.platform !== "win32",
+		});
+
+		const attempt = beginAttempt(child, signal, deadlineMs, killEscalationMs);
+		let processError: Error | undefined;
+		let stderr = "";
+		let partial = "";
+		let threadId: string | undefined;
+		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) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			processError = error;
+		});
+		child.stdin?.on("error", () => {
+			// codex exiting before reading stdin is reported through the close/error path.
+		});
+		child.stdin?.end(request.prompt);
+
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			let event: CodexEvent;
+			try {
+				event = JSON.parse(line) as CodexEvent;
+			} catch {
+				throw new Error("Codex emitted invalid JSON output.");
+			}
+			if (event.type === "thread.started" && typeof event.thread_id === "string") {
+				threadId = event.thread_id;
+			}
+			if (event.type === "error") {
+				terminalError ??= `Codex error: ${typeof event.message === "string" && event.message.trim() ? event.message.trim() : "unknown error"}`;
+				return;
+			}
+			if (event.type === "turn.failed") {
+				sawTerminal = true;
+				const err = event.error as { message?: unknown } | undefined;
+				terminalError ??= `Codex failed: ${typeof err?.message === "string" && err.message.trim() ? err.message.trim() : "turn failed"}`;
+				return;
+			}
+			if (event.type === "turn.completed") {
+				sawTerminal = true;
+				return;
+			}
+			const item = event.item;
+			if (isAdvisor && (event.type === "item.started" || event.type === "item.completed")) {
+				const activity = codexActivityFromEvent(event);
+				if (activity) onProgress?.({ kind: "activity", label: activity, timestamp: Date.now() });
+			}
+			if (event.type === "item.completed" && item?.type === "agent_message") {
+				const text = extractCodexItemText(item);
+				if (text !== undefined) {
+					final = text;
+					if (!isAdvisor) {
+						partial += `${partial ? "\n\n" : ""}${text}`;
+						onProgress?.({ kind: "text", text: partial });
+					}
+				}
+			}
+		};
+
+		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 { code, exitSignal } = await attempt.closed;
+		attempt.dispose();
+		if (stdoutBuffer.trim()) {
+			try {
+				handleLine(stdoutBuffer);
+			} catch (error) {
+				protocolError ??= errorMessage(error);
+			}
+		}
+
+		const partialText = partial ? { partialText: partial } : {};
+		const cause = attempt.causeOf();
+		if (cause === "cancelled") return { status: "cancelled", message: "Canceled.", ...partialText };
+		if (cause === "timeout") return { status: "timeout", message: `Codex timed out ${timeoutVerb}. Run \`/bro doctor\` for setup help.`, ...partialText };
+		if (protocolError) return { status: "failure", message: withDoctor(protocolError), ...partialText };
+		if (processError) return { status: "failure", message: processStartMessage(processError as NodeJS.ErrnoException, "Codex") };
+		if (exitSignal || code === null) return { status: "failure", message: unexpectedSignalMessage(exitSignal, "Codex"), ...partialText };
+		if (terminalError) return { status: "failure", message: withDoctor(terminalError), ...partialText };
+		if (code !== 0) {
+			const detail = stderr.trim();
+			return {
+				status: "failure",
+				message: detail
+					? `Codex could not ${action}: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: `Codex could not ${action}. Make sure \`codex\` is installed and signed in, then run \`/bro doctor\`.`,
+				...partialText,
+			};
+		}
+		if (!sawTerminal) {
+			return { status: "failure", message: withDoctor(`Codex exited without a terminal result event${stderr.trim() ? `: ${stderr.trim()}` : "."}`), ...partialText };
+		}
+		const text = final?.trim();
+		if (!text) return { status: "failure", message: withDoctor(emptyTextMessage), ...partialText };
+		if (!isBtw) return { status: "success", text };
+		if (!threadId || (request.continuation && threadId !== request.continuation.id)) {
+			return {
+				status: "failure",
+				message: withDoctor(`Codex reported an inconsistent session id (expected ${request.continuation?.id ?? "one id"}, got ${threadId ?? "none"}).`),
+				...partialText,
+			};
+		}
+		return { status: "success", text, continuation: { id: threadId } };
+	} finally {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+type MuseEnvelope = {
+	schema_version?: unknown;
+	payload_type?: unknown;
+	stream?: { kind?: unknown; id?: unknown };
+	payload?: {
+		kind?: unknown;
+		command_id?: unknown;
+		run_stream?: { kind?: unknown; id?: unknown };
+		text?: unknown;
+		reason?: unknown;
+		correlation_facts?: { tool_name?: unknown };
+		event?: { message?: unknown };
+		command?: unknown;
+		path?: unknown;
+		file_path?: unknown;
+		query?: unknown;
+	};
+};
+
+async function executeMuse(
+	request: BackendRequest,
+	selection: { model: string; effort?: string },
+	signal: AbortSignal,
+	onProgress: BackendOnProgress | undefined,
+	killEscalationMs: number,
+	deadlineMsOverride: number | undefined,
+): Promise<BackendOutcome> {
+	const isAdvisor = request.feature === "advisor";
+	const isBtw = request.feature === "btw";
+	const full = request.access === "workspace-full";
+	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = isAdvisor ? "Muse returned no advice." : isBtw ? "Muse returned no answer for the side question." : "Muse returned no final explanation.";
+
+	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+	const promptDirectory = await mkdtemp(join(tmpdir(), "pi-bro-muse-"));
+	let runDirectory: string | undefined;
+
+	try {
+		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+		const promptFile = join(promptDirectory, "prompt.txt");
+		await writeFile(promptFile, request.prompt, { encoding: "utf8", mode: 0o600 });
+		if (!isAdvisor && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+		const workspace = runDirectory ?? request.cwd!;
+
+		const args = [
+			"exec",
+			"--json",
+			"--provider", "meta",
+			"--workspace", workspace,
+			...(!isBtw ? ["--no-session-log"] : []),
+			...(full ? ["--yolo"] : ["--disable-approval", "--disable-write", "--disable-shell"]),
+			...(isBtw && request.continuation ? ["--session-id", request.continuation.id] : []),
+			"--model", selection.model,
+			...(selection.effort ? ["--reasoning-effort", selection.effort] : []),
+			"--prompt-file", promptFile,
+		];
+
+		const child = spawn("muse", args, {
+			cwd: workspace,
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+			detached: process.platform !== "win32",
+		});
+
+		const attempt = beginAttempt(child, signal, deadlineMs, killEscalationMs);
+		let processError: Error | undefined;
+		let stderr = "";
+		let partial = "";
+		let rootCommandId: string | undefined;
+		let rootRunId: string | undefined;
+		let sessionId: string | undefined;
+		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) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			processError = error;
+		});
+
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			let envelope: MuseEnvelope;
+			try {
+				envelope = JSON.parse(line) as MuseEnvelope;
+			} catch {
+				throw new Error("Muse emitted invalid JSON output.");
+			}
+			const payload = envelope.payload;
+			if (envelope.stream?.kind === "session" && typeof envelope.stream.id === "string") {
+				if (!sessionId) sessionId = envelope.stream.id;
+			}
+			if (envelope.payload_type === "runtime.command.accepted") {
+				if (!rootCommandId && typeof payload?.command_id === "string") {
+					rootCommandId = payload.command_id;
+				}
+				return;
+			}
+			if (!rootRunId && (envelope.payload_type === "session.run.linked" || envelope.payload_type === "run.lifecycle.started")) {
+				const runStream = payload?.run_stream;
+				if (runStream?.kind === "run" && typeof runStream.id === "string") {
+					if (rootCommandId === undefined || payload?.command_id === rootCommandId) {
+						rootRunId = runStream.id;
+						if (envelope.stream?.kind === "session" && typeof envelope.stream.id === "string") {
+							sessionId = envelope.stream.id;
+						}
+					}
+				}
+				return;
+			}
+			const runStream = payload?.run_stream;
+			const isRoot = rootRunId !== undefined && runStream?.kind === "run" && runStream.id === rootRunId;
+
+			if (isAdvisor) {
+				if (envelope.payload_type === "tool.result") {
+					const facts = payload?.correlation_facts as { tool_name?: unknown } | undefined;
+					const toolName = typeof facts?.tool_name === "string" && facts.tool_name ? facts.tool_name : "tool";
+					const candidate = [payload?.text, payload?.command, payload?.path, payload?.file_path, payload?.query]
+						.find((v) => typeof v === "string" && v.trim());
+					const preview = typeof candidate === "string" ? candidate.replace(/\s+/g, " ").trim() : "";
+					const label = `${toolName}${preview ? ` ${preview}` : ""}`;
+					onProgress?.({ kind: "activity", label, timestamp: Date.now() });
+				} else if (envelope.payload_type === "task.lifecycle.status") {
+					const event = payload?.event as { message?: unknown } | undefined;
+					if (typeof event?.message === "string" && event.message.trim()) {
+						onProgress?.({ kind: "activity", label: event.message.trim(), timestamp: Date.now() });
+					}
+				}
+			} else if (isRoot && envelope.payload_type === "run.output.delta") {
+				if (typeof payload?.text === "string" && payload.text) {
+					partial += payload.text;
+					onProgress?.({ kind: "text", text: partial });
+				}
+			}
+
+			if (!isRoot) return;
+			if (envelope.payload_type === "run.terminal.completed") {
+				sawTerminal = true;
+				if (typeof payload?.text === "string") {
+					final = payload.text;
+				}
+			} else if (envelope.payload_type === "run.terminal.failed") {
+				sawTerminal = true;
+				const reason = typeof payload?.reason === "string" && payload.reason.trim() ? payload.reason.trim() : "run did not complete";
+				terminalError ??= `Muse failed: ${reason}`;
+			}
+		};
+
+		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 { code, exitSignal } = await attempt.closed;
+		attempt.dispose();
+		if (stdoutBuffer.trim()) {
+			try {
+				handleLine(stdoutBuffer);
+			} catch (error) {
+				protocolError ??= errorMessage(error);
+			}
+		}
+
+		const partialText = partial ? { partialText: partial } : {};
+		const cause = attempt.causeOf();
+		if (cause === "cancelled") return { status: "cancelled", message: "Canceled.", ...partialText };
+		if (cause === "timeout") return { status: "timeout", message: `Muse timed out ${timeoutVerb}. Run \`/bro doctor\` for setup help.`, ...partialText };
+		if (protocolError) return { status: "failure", message: withDoctor(protocolError), ...partialText };
+		if (processError) return { status: "failure", message: processStartMessage(processError as NodeJS.ErrnoException, "Muse") };
+		if (exitSignal || code === null) return { status: "failure", message: unexpectedSignalMessage(exitSignal, "Muse"), ...partialText };
+		if (terminalError) return { status: "failure", message: withDoctor(terminalError), ...partialText };
+		if (code !== 0) {
+			const detail = stderr.trim();
+			return {
+				status: "failure",
+				message: detail
+					? `Muse could not ${action}: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: `Muse could not ${action}. Make sure \`muse\` is installed and signed in, then run \`/bro doctor\`.`,
+				...partialText,
+			};
+		}
+		if (!sawTerminal) {
+			return { status: "failure", message: withDoctor(`Muse exited without a terminal result event${stderr.trim() ? `: ${stderr.trim()}` : "."}`), ...partialText };
+		}
+		const text = final?.trim();
+		if (!text) return { status: "failure", message: withDoctor(emptyTextMessage), ...partialText };
+		if (!isBtw) return { status: "success", text };
+		if (!sessionId || (request.continuation && sessionId !== request.continuation.id)) {
+			return {
+				status: "failure",
+				message: withDoctor(`Muse reported an inconsistent session id (expected ${request.continuation?.id ?? "one id"}, got ${sessionId ?? "none"}).`),
+				...partialText,
+			};
+		}
+		return { status: "success", text, continuation: { id: sessionId } };
+	} finally {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+		await rm(promptDirectory, { recursive: true, force: true });
+	}
+}
+
 // Single-attempt executor shared by all four features. Never retries (retries are feature-owned,
 // e.g. advisor's 3-attempt backoff in bro.ts); never spawns a pre-aborted request; on cancellation,
 // host deadline, or a protocol failure, stops the whole POSIX process group (SIGTERM, then SIGKILL
@@ -984,10 +1444,30 @@ export async function execute(
 	) return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 	const backend = (selection as { backend?: unknown }).backend;
 	// An explicit tag guard: a stale or corrupt runtime tag must fail, never fall through to Agy.
-	if (backend !== undefined && backend !== "agy" && backend !== "claude" && backend !== "grok") {
-		return { status: "failure", message: `Unknown backend ${JSON.stringify(backend)}: pick Agy, Claude or Grok in \`/bro config\`.` };
+	if (backend !== undefined && backend !== "agy" && backend !== "claude" && backend !== "grok" && backend !== "codex" && backend !== "muse") {
+		return { status: "failure", message: `Unknown backend ${JSON.stringify(backend)}: pick Agy, Claude, Grok, Codex or Muse in \`/bro config\`.` };
 	}
 	const killEscalationMs = options?.killEscalationMs ?? DEFAULT_KILL_ESCALATION_MS;
+	if (selection.backend === "codex") {
+		// Codex btw always runs (and resumes) in the caller's workspace, even restricted.
+		if (request.feature === "btw" && !request.cwd?.trim()) {
+			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
+		}
+		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !CODEX_EFFORTS.includes(selection.effort))) {
+			return { status: "failure", message: "Unsupported Codex selection: check the model and effort (low, medium, high or xhigh)." };
+		}
+		return executeCodex(request, selection, signal, onProgress, killEscalationMs, options?.deadlineMs);
+	}
+	if (selection.backend === "muse") {
+		// Muse btw always runs (and resumes) in the caller's workspace, even restricted.
+		if (request.feature === "btw" && !request.cwd?.trim()) {
+			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
+		}
+		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !MUSE_EFFORTS.includes(selection.effort))) {
+			return { status: "failure", message: "Unsupported Muse selection: check the model and effort (minimal, low, medium, high, xhigh or max)." };
+		}
+		return executeMuse(request, selection, signal, onProgress, killEscalationMs, options?.deadlineMs);
+	}
 	if (selection.backend === "grok") {
 		// Grok btw always runs (and resumes) in the caller's workspace, even restricted.
 		if (request.feature === "btw" && !request.cwd?.trim()) {