@oh-my-pi/pi-coding-agent 16.1.13 → 16.1.15

package/src/tts/tts-client.ts

@@ -1,8 +1,17 @@
-import * as path from "node:path";
-import { $env, isBunTestRuntime, isCompiledBinary, logger, workerHostEntry } from "@oh-my-pi/pi-utils";
-import type { Subprocess } from "bun";
-import { settings } from "../config/settings";
-import { tinyWorkerEnvOverlay } from "../tiny/title-client";
+import { logger } from "@oh-my-pi/pi-utils";
+import {
+	createUnavailableWorker,
+	createWorkerHandle,
+	createWorkerSubprocess,
+	logWorkerMessage,
+	type RefCountedWorkerHandle,
+	resolveWorkerSpawnCmd,
+	SMOKE_TEST_TIMEOUT_MS,
+	type SpawnedSubprocess,
+	smokeTestWorker,
+	spawnWorkerOrUnavailable,
+} from "../subprocess/worker-client";
+import { tinyWorkerEnv } from "../tiny/title-client";
 import { safeSend } from "../utils/ipc";
 import { isTtsLocalModelKey, type TtsLocalModelKey } from "./models";
 import type { TtsProgressEvent, TtsWorkerInbound, TtsWorkerOutbound } from "./tts-protocol";
@@ -13,22 +22,6 @@ export interface TtsAudio {
 	sampleRate: number;
 }
 
-/**
- * Abstraction over the TTS subprocess. The runtime implementation is a Bun child
- * process so `onnxruntime-node`'s NAPI finalizer never runs inside the main agent
- * address space — that destructor segfaults Bun during shutdown (issue #1606).
- */
-interface WorkerHandle {
-	send(message: TtsWorkerInbound): void;
-	onMessage(handler: (message: TtsWorkerOutbound) => void): () => void;
-	onError(handler: (error: Error) => void): () => void;
-	/** Re-reference the subprocess so a pending request keeps the parent event loop alive. */
-	ref(): void;
-	/** Drop the reference once the worker is idle so it never blocks process exit. */
-	unref(): void;
-	terminate(): Promise<void>;
-}
-
 type PendingRequest =
 	| { kind: "synthesize"; modelKey: TtsLocalModelKey; resolve: (audio: TtsAudio | null) => void }
 	| { kind: "download"; modelKey: TtsLocalModelKey; resolve: (ok: boolean) => void }
@@ -134,128 +127,30 @@ class AudioChunkChannel {
 	}
 }
 
-// Cold-starting the worker from a compiled binary (decompress + module graph load)
-// is slow on contended CI runners; the probe only proves the worker spawns and
-// ponges, so a generous bound removes flakes without weakening the check.
-const SMOKE_TEST_TIMEOUT_MS = 30_000;
-
 /**
  * Hidden subcommand on the main CLI that boots the TTS worker in the spawned
  * subprocess. Kept in sync with the dispatch in `cli.ts` (Main-owned).
  */
 export const TTS_WORKER_ARG = "__omp_worker_tts";
 
-function readTinyModelSetting(path: "providers.tinyModelDevice" | "providers.tinyModelDtype"): string | undefined {
-	try {
-		const value = settings.get(path);
-		return typeof value === "string" ? value : undefined;
-	} catch {
-		// Settings may be uninitialized (e.g. `omp --smoke-test`); fall back to env/default.
-		return undefined;
-	}
-}
-
-/**
- * Env handed to the TTS subprocess. The `PI_TINY_DEVICE` / `PI_TINY_DTYPE` env
- * vars win; otherwise the persisted `providers.tinyModelDevice` /
- * `providers.tinyModelDtype` settings are mapped onto those vars so the
- * subprocess's env-based resolution governs speech the same way it governs the
- * tiny LLM worker.
- */
-function ttsWorkerEnv(): Record<string, string> {
-	const overlay = tinyWorkerEnvOverlay(
-		$env,
-		readTinyModelSetting("providers.tinyModelDevice"),
-		readTinyModelSetting("providers.tinyModelDtype"),
-	);
-	const base = $env as Record<string, string | undefined>;
-	const merged: Record<string, string> = {};
-	for (const key in base) {
-		const value = base[key];
-		if (typeof value === "string") merged[key] = value;
-	}
-	for (const key in overlay) merged[key] = overlay[key];
-	return merged;
-}
-
-interface TtsWorkerSpawnCommand {
-	cmd: string[];
-	cwd?: string;
-}
-
-/**
- * Resolve the command used to relaunch the agent CLI into TTS-worker mode. In a
- * compiled binary the entry point is the binary itself; otherwise re-enter the
- * declared worker-host entry (cwd-relative for reliable Bun IPC), falling back
- * to this package's own `src/cli.ts` when no host entry is declared (bun test).
- */
-function ttsWorkerSpawnCmd(): TtsWorkerSpawnCommand {
-	if (isCompiledBinary()) return { cmd: [process.execPath, TTS_WORKER_ARG] };
-	const hostEntry = workerHostEntry();
-	if (hostEntry) {
-		return { cmd: [process.execPath, path.basename(hostEntry), TTS_WORKER_ARG], cwd: path.dirname(hostEntry) };
-	}
-	const packageRoot = path.resolve(import.meta.dir, "..", "..");
-	return { cmd: [process.execPath, "src/cli.ts", TTS_WORKER_ARG], cwd: packageRoot };
-}
-
-interface SpawnedSubprocess {
-	proc: Subprocess<"ignore", "ignore", "ignore">;
-	inbound: Set<(message: TtsWorkerOutbound) => void>;
-	errors: Set<(error: Error) => void>;
-	/** Flipped to `true` right before the deliberate SIGKILL so `onExit` can tell it apart from a crash. */
-	intentionalExit: { value: boolean };
-}
-
 /**
  * Spawn the TTS worker as a subprocess. Exported for tests and the smoke probe;
  * production callers go through {@link spawnTtsWorker}.
  */
-export function createTtsSubprocess(): SpawnedSubprocess {
-	const inbound = new Set<(message: TtsWorkerOutbound) => void>();
-	const errors = new Set<(error: Error) => void>();
-	const intentionalExit = { value: false };
-	const spawnCommand = ttsWorkerSpawnCmd();
-	const proc = Bun.spawn({
-		cmd: spawnCommand.cmd,
-		cwd: spawnCommand.cwd,
-		env: ttsWorkerEnv(),
-		stdin: "ignore",
-		stdout: "ignore",
-		stderr: "ignore",
-		serialization: "advanced",
-		windowsHide: true,
-		ipc(message) {
-			for (const handler of inbound) handler(message as TtsWorkerOutbound);
-		},
-		onExit(_proc, exitCode, signalCode) {
-			if (exitCode === 0) return;
-			if (exitCode === null && intentionalExit.value) return;
-			const reason = exitCode !== null ? `code ${exitCode}` : `signal ${signalCode ?? "unknown"}`;
-			const err = new Error(`tts subprocess exited with ${reason}`);
-			for (const handler of errors) handler(err);
-		},
+export function createTtsSubprocess(): SpawnedSubprocess<TtsWorkerOutbound> {
+	return createWorkerSubprocess<TtsWorkerOutbound>({
+		spawnCommand: resolveWorkerSpawnCmd(TTS_WORKER_ARG),
+		env: tinyWorkerEnv(),
+		exitLabel: "tts subprocess",
 	});
-	// Don't keep the parent event loop alive on an idle worker; the dispose path
-	// calls `terminate()` explicitly. Bun's test runner starves IPC for unref'd
-	// subprocesses, so keep it referenced only under tests.
-	if (!isBunTestRuntime()) proc.unref();
-	return { proc, inbound, errors, intentionalExit };
 }
 
-function wrapSubprocess({ proc, inbound, errors, intentionalExit }: SpawnedSubprocess): WorkerHandle {
+function wrapSubprocess(
+	spawned: SpawnedSubprocess<TtsWorkerOutbound>,
+): RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound> {
+	const { proc } = spawned;
 	return {
-		send(message) {
-			safeSend(proc, message, "tts");
-		},
-		onMessage(handler) {
-			inbound.add(handler);
-			return () => inbound.delete(handler);
-		},
-		onError(handler) {
-			errors.add(handler);
-			return () => errors.delete(handler);
-		},
+		...createWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound>(spawned, message => safeSend(proc, message, "tts")),
 		ref() {
 			try {
 				proc.ref();
@@ -270,79 +165,36 @@ function wrapSubprocess({ proc, inbound, errors, intentionalExit }: SpawnedSubpr
 				// Already gone.
 			}
 		},
-		async terminate() {
-			// SIGKILL: the point of subprocess isolation is that the parent never
-			// runs `onnxruntime-node`'s NAPI finalizer (it crashes Bun on Windows).
-			// Hard-kill instead; the OS reclaims the model memory.
-			intentionalExit.value = true;
-			try {
-				proc.kill("SIGKILL");
-			} catch {
-				// Already gone.
-			}
-		},
 	};
 }
 
-function spawnInlineUnavailableWorker(error: unknown): WorkerHandle {
-	const listeners = new Set<(message: TtsWorkerOutbound) => void>();
-	const errorMessage = error instanceof Error ? error.message : String(error);
-	const emit = (message: TtsWorkerOutbound): void => {
-		for (const listener of listeners) listener(message);
-	};
+function spawnInlineUnavailableWorker(error: unknown): RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound> {
 	return {
-		send(message) {
-			queueMicrotask(() => {
-				if (message.type === "ping") {
-					emit({ type: "pong", id: message.id });
-					return;
-				}
-				emit({ type: "error", id: message.id, error: errorMessage });
-			});
-		},
-		onMessage(handler) {
-			listeners.add(handler);
-			return () => listeners.delete(handler);
-		},
-		onError() {
-			return () => {};
-		},
+		...createUnavailableWorker<TtsWorkerInbound, TtsWorkerOutbound>(error),
 		ref() {},
 		unref() {},
-		async terminate() {
-			listeners.clear();
-		},
 	};
 }
 
-function spawnTtsWorker(): WorkerHandle {
-	try {
-		return wrapSubprocess(createTtsSubprocess());
-	} catch (error) {
-		logger.warn("TTS worker spawn failed; local TTS disabled", {
-			error: error instanceof Error ? error.message : String(error),
-		});
-		return spawnInlineUnavailableWorker(error);
-	}
-}
-
-function logWorkerMessage(message: Extract<TtsWorkerOutbound, { type: "log" }>): void {
-	if (message.level === "debug") logger.debug(message.msg, message.meta);
-	else if (message.level === "warn") logger.warn(message.msg, message.meta);
-	else logger.error(message.msg, message.meta);
+function spawnTtsWorker(): RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound> {
+	return spawnWorkerOrUnavailable(
+		() => wrapSubprocess(createTtsSubprocess()),
+		spawnInlineUnavailableWorker,
+		"TTS worker spawn failed; local TTS disabled",
+	);
 }
 
 export class TtsClient {
-	#worker: WorkerHandle | null = null;
+	#worker: RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound> | null = null;
 	#unsubscribeMessage: (() => void) | null = null;
 	#unsubscribeError: (() => void) | null = null;
 	#pending = new Map<string, PendingRequest>();
 	#progressListeners = new Set<(event: TtsProgressEvent) => void>();
 	#nextRequestId = 0;
 	#refed = false;
-	#spawnWorker: () => WorkerHandle;
+	#spawnWorker: () => RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound>;
 
-	constructor(spawnWorker: () => WorkerHandle = spawnTtsWorker) {
+	constructor(spawnWorker: () => RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound> = spawnTtsWorker) {
 		this.#spawnWorker = spawnWorker;
 	}
 
@@ -400,7 +252,7 @@ export class TtsClient {
 			return { push: () => {}, end: () => {}, chunks: channel.iterator() };
 		}
 
-		let worker: WorkerHandle;
+		let worker: RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound>;
 		try {
 			worker = this.#ensureWorker();
 		} catch (error) {
@@ -505,7 +357,7 @@ export class TtsClient {
 		}
 	}
 
-	#ensureWorker(): WorkerHandle {
+	#ensureWorker(): RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound> {
 		if (this.#worker) return this.#worker;
 		const worker = this.#spawnWorker();
 		this.#worker = worker;
@@ -618,25 +470,5 @@ export async function smokeTestTtsWorker({
 }: {
 	timeoutMs?: number;
 } = {}): Promise<void> {
-	const handle = wrapSubprocess(createTtsSubprocess());
-	const { promise, resolve, reject } = Promise.withResolvers<void>();
-	const timer = setTimeout(() => reject(new Error(`tts worker did not pong within ${timeoutMs}ms`)), timeoutMs);
-	const unsubscribeMessage = handle.onMessage(message => {
-		if (message.type === "pong") {
-			resolve();
-			return;
-		}
-		if (message.type === "log") return;
-		reject(new Error(`tts worker: expected pong, got ${JSON.stringify(message)}`));
-	});
-	const unsubscribeError = handle.onError(reject);
-	try {
-		handle.send({ type: "ping", id: "smoke" } satisfies TtsWorkerInbound);
-		await promise;
-	} finally {
-		clearTimeout(timer);
-		unsubscribeMessage();
-		unsubscribeError();
-		await handle.terminate();
-	}
+	await smokeTestWorker(wrapSubprocess(createTtsSubprocess()), "tts worker", timeoutMs);
 }

package/src/tts/tts-worker.ts

@@ -1,12 +1,16 @@
 import { createRequire } from "node:module";
-import * as path from "node:path";
 import type { ProgressInfo, RawAudio } from "@huggingface/transformers";
+import { ensureRuntimeInstalled, getTinyModelsCacheDir, resolveRuntimeModule } from "@oh-my-pi/pi-utils";
 import {
-	ensureRuntimeInstalled,
-	getTinyModelsCacheDir,
-	installRuntimeModuleResolver,
-	resolveRuntimeModule,
-} from "@oh-my-pi/pi-utils";
+	errorMessage,
+	errorText,
+	installSharpStubResolver,
+	MemoizedRuntime,
+	replayCachedReady,
+	sendLog,
+	sendProgress,
+	TRANSFORMERS_PACKAGE,
+} from "../subprocess/worker-runtime";
 import { resolveTinyModelDevicePreference, type TinyModelDevice, tinyModelDeviceLoadOrder } from "../tiny/device";
 import { resolveTinyModelDtypeOverride, type TinyModelDtype } from "../tiny/dtype";
 import { getTtsLocalModelSpec, resolveTtsVoice, type TtsLocalModelKey, type TtsLocalModelSpec } from "./models";
@@ -17,10 +21,9 @@ import {
 	ONNXRUNTIME_NODE_PACKAGE,
 	ONNXRUNTIME_NODE_VERSION,
 } from "./runtime";
-import type { TtsProgressEvent, TtsTransport, TtsWorkerInbound } from "./tts-protocol";
+import type { TtsTransport, TtsWorkerInbound } from "./tts-protocol";
 
 const TTS_TASK = "text-to-speech";
-const TRANSFORMERS_PACKAGE = "@huggingface/transformers";
 // kokoro-js is NEVER a dependency of the main tree: its transformers@3.8.1 +
 // onnxruntime-node@1.21 graph must not pollute it (1.21 segfaults Bun on session
 // creation). It is lazily `bun install`ed into a side runtime dir on first use,
@@ -89,7 +92,7 @@ interface TransformersEnv {
 
 const models = new Map<TtsLocalModelKey, Promise<KokoroTtsInstance>>();
 let synthesizeQueue = Promise.resolve();
-let kokoroRuntime: Promise<KokoroRuntime> | null = null;
+const kokoroRuntime = new MemoizedRuntime<KokoroRuntime>();
 
 /**
  * In-flight streaming sessions keyed by request id. A session is created on
@@ -107,36 +110,6 @@ interface StreamSession {
 }
 const streamSessions = new Map<string, StreamSession>();
 
-function errorText(error: unknown): string {
-	return error instanceof Error ? (error.stack ?? error.message) : String(error);
-}
-
-function errorMessage(error: unknown): string {
-	return error instanceof Error ? error.message : String(error);
-}
-
-function sendLog(
-	transport: TtsTransport,
-	level: "debug" | "warn" | "error",
-	msg: string,
-	meta?: Record<string, unknown>,
-): void {
-	transport.send({ type: "log", level, msg, meta });
-}
-
-function sendRuntimeInstallProgress(
-	transport: TtsTransport,
-	requestId: string,
-	modelKey: TtsLocalModelKey,
-	status: "initiate" | "download" | "done",
-): void {
-	transport.send({
-		type: "progress",
-		id: requestId,
-		event: { modelKey, status, name: `${KOKORO_PACKAGE}@${KOKORO_VERSION}` },
-	});
-}
-
 /**
  * Map a tiny-model device onto the narrow set `kokoro-js` accepts. The worker
  * always runs `kokoro-js` on Node, where `cpu` (onnxruntime-node) is the only
@@ -165,13 +138,12 @@ function configureTransformers(transformers: TransformersEnv): void {
  * the TTS pipeline is audio-only, so the native image codec transformers eagerly
  * requires is dead weight. Memoized so the runtime loads once per process.
  */
-async function loadKokoroRuntime(
+function loadKokoroRuntime(
 	transport: TtsTransport,
 	requestId: string,
 	modelKey: TtsLocalModelKey,
 ): Promise<KokoroRuntime> {
-	if (kokoroRuntime) return kokoroRuntime;
-	kokoroRuntime = (async () => {
+	return kokoroRuntime.load(async () => {
 		const runtimeDir = await ensureRuntimeInstalled({
 			runtimeDir: getTtsRuntimeDir(),
 			install: {
@@ -180,12 +152,14 @@ async function loadKokoroRuntime(
 				trustedDependencies: [ONNXRUNTIME_NODE_PACKAGE],
 			},
 			probePackage: KOKORO_PACKAGE,
-			onPhase: phase => sendRuntimeInstallProgress(transport, requestId, modelKey, phase),
+			onPhase: phase =>
+				transport.send({
+					type: "progress",
+					id: requestId,
+					event: { modelKey, status: phase, name: `${KOKORO_PACKAGE}@${KOKORO_VERSION}` },
+				}),
 		});
-		const nodeModules = path.join(runtimeDir, "node_modules");
-		const sharpStub = path.join(runtimeDir, "omp-sharp-stub.cjs");
-		await Bun.write(sharpStub, "module.exports = {};\n");
-		installRuntimeModuleResolver({ runtimeNodeModules: nodeModules, stubs: { sharp: sharpStub } });
+		const nodeModules = await installSharpStubResolver(runtimeDir);
 		const kokoroEntry = resolveRuntimeModule(nodeModules, KOKORO_PACKAGE);
 		if (!kokoroEntry) throw new Error(`Unable to resolve ${KOKORO_PACKAGE} in runtime at ${nodeModules}`);
 		const transformersEntry = resolveRuntimeModule(nodeModules, TRANSFORMERS_PACKAGE);
@@ -193,44 +167,7 @@ async function loadKokoroRuntime(
 		const runtimeRequire = createRequire(kokoroEntry);
 		configureTransformers(runtimeRequire(transformersEntry) as TransformersEnv);
 		return runtimeRequire(kokoroEntry) as KokoroRuntime;
-	})().catch(error => {
-		kokoroRuntime = null;
-		throw error;
 	});
-	return kokoroRuntime;
-}
-
-function toProgressEvent(modelKey: TtsLocalModelKey, info: ProgressInfo): TtsProgressEvent {
-	if (info.status === "ready") {
-		return { modelKey, status: info.status, task: info.task, model: info.model };
-	}
-	if (info.status === "progress_total") {
-		return {
-			modelKey,
-			status: info.status,
-			name: info.name,
-			progress: info.progress,
-			loaded: info.loaded,
-			total: info.total,
-			files: info.files,
-		};
-	}
-	if (info.status === "progress") {
-		return {
-			modelKey,
-			status: info.status,
-			name: info.name,
-			file: info.file,
-			progress: info.progress,
-			loaded: info.loaded,
-			total: info.total,
-		};
-	}
-	return { modelKey, status: info.status, name: info.name, file: info.file };
-}
-
-function sendProgress(transport: TtsTransport, id: string, modelKey: TtsLocalModelKey, info: ProgressInfo): void {
-	transport.send({ type: "progress", id, event: toProgressEvent(modelKey, info) });
 }
 
 async function loadModelOnDevice(
@@ -295,19 +232,8 @@ async function loadModel(
 ): Promise<KokoroTtsInstance> {
 	const spec = getTtsLocalModelSpec(modelKey);
 	if (!spec) throw new Error(`Unknown local TTS model: ${modelKey}`);
-	const cached = models.get(modelKey);
-	if (cached) {
-		void cached
-			.then(() => {
-				transport.send({
-					type: "progress",
-					id: requestId,
-					event: { modelKey, status: "ready", task: TTS_TASK, model: spec.repo },
-				});
-			})
-			.catch(() => undefined);
-		return cached;
-	}
+	const cached = replayCachedReady(models, modelKey, transport, requestId, TTS_TASK, spec.repo);
+	if (cached) return cached;
 
 	const runtime = await loadKokoroRuntime(transport, requestId, modelKey);
 	const startedAt = performance.now();

package/src/tui/code-cell.ts

@@ -32,6 +32,13 @@ export interface CodeCellOptions {
 	 */
 	codeTail?: boolean;
 	expanded?: boolean;
+	/**
+	 * Prefix the header with the cell's language icon (resolved through the
+	 * active symbol preset: nerd-font devicon, unicode emoji, or ascii
+	 * shorthand). Opt-in so only the eval kernel renderer labels each cell;
+	 * read/write/browser code cells stay icon-free.
+	 */
+	showLanguage?: boolean;
 	width: number;
 	codeStartLine?: number;
 	codeLineNumbers?: Array<number | null>;
@@ -47,8 +54,12 @@ function getState(status?: CodeCellOptions["status"]): State | undefined {
 }
 
 function formatHeader(options: CodeCellOptions, theme: Theme): { title: string; meta?: string } {
-	const { index, total, title, status, spinnerFrame, duration } = options;
+	const { index, total, title, status, spinnerFrame, duration, language, showLanguage } = options;
 	const parts: string[] = [];
+	if (showLanguage && language) {
+		const langIcon = theme.getLangIconStyled(language);
+		if (langIcon) parts.push(langIcon);
+	}
 	if (status) {
 		const icon = formatStatusIcon(
 			status === "complete"

package/src/utils/file-display-mode.ts

@@ -14,7 +14,7 @@ export interface FileDisplayModeSession {
 	/** Whether the edit tool is available. Hashlines are suppressed without it. */
 	hasEditTool?: boolean;
 	settings: {
-		get(key: "readLineNumbers" | "readHashLines" | "edit.mode"): unknown;
+		get(key: "readLineNumbers" | "edit.mode"): unknown;
 	};
 }
 
@@ -36,8 +36,7 @@ export function resolveFileDisplayMode(
 	const usesHashLineAnchors = editMode === "hashline";
 	const raw = options?.raw === true;
 	const immutable = options?.immutable === true;
-	const hashLines =
-		!raw && !immutable && hasEditTool && usesHashLineAnchors && settings.get("readHashLines") !== false;
+	const hashLines = !raw && !immutable && hasEditTool && usesHashLineAnchors;
 	return {
 		hashLines,
 		lineNumbers: !raw && (hashLines || settings.get("readLineNumbers") === true),

package/src/utils/shell-snapshot.ts

@@ -8,11 +8,72 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { postmortem } from "@oh-my-pi/pi-utils";
+import { logger, postmortem } from "@oh-my-pi/pi-utils";
 
 const cachedSnapshotPaths = new Map<string, string>();
 const SNAPSHOT_TIMEOUT_MS = 2_000;
 
+/**
+ * Characters that force brush's primitive alias expander down a path it does
+ * not implement. brush-core resolves aliases via `value.split_ascii_whitespace()`
+ * (`crates/brush-core-vendored/src/interp.rs:1500`, tracking
+ * https://github.com/reubeno/brush/issues/57): the resulting pieces are dropped
+ * into argv verbatim instead of going through the shell parser. Any alias body
+ * containing subshells `(...)`, pipes `|`, redirections `<` `>`, separators
+ * `;` `&`, or command substitutions `` ` `` turns the first whitespace-split
+ * piece into the command name and produces `command not found: (alias;` style
+ * failures (issue #3234, Fedora's default `which` alias is the canonical case).
+ *
+ * Until brush implements proper alias parsing we drop these from the snapshot;
+ * brush then falls through to whatever lives on `PATH`, which is what the user
+ * actually expected when they invoked `which` / `ls` / etc.
+ */
+const BRUSH_INCOMPATIBLE_ALIAS_BODY = /[()|&;<>`]/;
+
+/** Matches `alias -- NAME='VALUE'` lines emitted by `generateSnapshotScript`. */
+const SNAPSHOT_ALIAS_LINE = /^alias -- ([^\s=]+)='(.*)'\s*$/;
+
+/**
+ * Strip alias definitions brush's whitespace-only expander cannot execute.
+ *
+ * Returns the rewritten snapshot plus the list of dropped alias names so the
+ * caller can surface them in the debug log.
+ */
+export function sanitizeSnapshotForBrush(content: string): { content: string; dropped: string[] } {
+	const dropped: string[] = [];
+	const lines = content.split("\n");
+	const out: string[] = [];
+	for (const line of lines) {
+		const m = line.match(SNAPSHOT_ALIAS_LINE);
+		if (m) {
+			// Decode the bash-quoting escape `'\''` → `'` so we test the real value.
+			const value = m[2].replace(/'\\''/g, "'");
+			if (BRUSH_INCOMPATIBLE_ALIAS_BODY.test(value)) {
+				dropped.push(m[1]);
+				continue;
+			}
+		}
+		out.push(line);
+	}
+	return { content: out.join("\n"), dropped };
+}
+
+/**
+ * Apply {@link sanitizeSnapshotForBrush} to the freshly generated snapshot
+ * file. Best-effort: I/O failures here must not poison `getOrCreateSnapshot`.
+ */
+function scrubSnapshotInPlace(snapshotPath: string): void {
+	try {
+		const raw = fs.readFileSync(snapshotPath, "utf8");
+		const { content, dropped } = sanitizeSnapshotForBrush(raw);
+		if (dropped.length === 0) return;
+		fs.writeFileSync(snapshotPath, content);
+		logger.debug("shell-snapshot: dropped brush-incompatible aliases", { dropped });
+	} catch (err) {
+		logger.debug("shell-snapshot: scrub failed", { err: String(err) });
+	}
+}
+
 function sanitizeSnapshotEnv(env: Record<string, string | undefined>): Record<string, string | undefined> {
 	const sanitized = { ...env };
 	delete sanitized.BASH_ENV;
@@ -169,6 +230,7 @@ export async function getOrCreateSnapshot(
 
 		await child.exited;
 		if (child.exitCode === 0 && fs.existsSync(snapshotPath)) {
+			scrubSnapshotInPlace(snapshotPath);
 			cachedSnapshotPaths.set(cacheKey, snapshotPath);
 			return snapshotPath;
 		}