@oh-my-pi/pi-coding-agent 16.0.2 → 16.0.3

package/src/session/session-dump-format.ts

@@ -1,11 +1,28 @@
 /**
- * Plain-text / markdown session formatting (same shape as /dump clipboard export).
+ * Plain-text / markdown session formatting for `/dump` and `/advisor dump raw`.
+ *
+ * Renders a prelude (system prompt, model/thinking config, tool inventory)
+ * followed by the message history as per-message markdown headings: `## User`,
+ * `## Assistant` (with `<thinking>` blocks and `### Tool Call: <name>` + YAML
+ * args), `### Tool Result: <name>`, and the execution/summary sections.
  */
 import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Model, ToolExample, TSchema } from "@oh-my-pi/pi-ai";
-import { getDialectDefinition, renderToolInventory } from "@oh-my-pi/pi-ai/dialect";
-import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
-import { convertToLlm } from "./messages";
+import { INTENT_FIELD } from "@oh-my-pi/pi-agent-core";
+import type { AssistantMessage, Model, ToolExample, TSchema } from "@oh-my-pi/pi-ai";
+import { renderDelimitedThinking, renderToolInventory } from "@oh-my-pi/pi-ai/dialect";
+import { YAML } from "bun";
+import { canonicalizeMessage } from "../utils/thinking-display";
+import {
+	type BashExecutionMessage,
+	type BranchSummaryMessage,
+	bashExecutionToText,
+	type CompactionSummaryMessage,
+	type CustomMessage,
+	type FileMentionMessage,
+	type HookMessage,
+	type PythonExecutionMessage,
+	pythonExecutionToText,
+} from "./messages";
 
 /** Minimal tool shape for dump output (matches AgentTool fields used by formatSessionDumpText). */
 export interface SessionDumpToolInfo {
@@ -23,12 +40,25 @@ export interface FormatSessionDumpTextOptions {
 	tools?: readonly SessionDumpToolInfo[];
 }
 
-/**
- * Format messages and session metadata as markdown/plain text (same as AgentSession.formatSessionAsText / /dump).
- */
-export function formatSessionDumpText(options: FormatSessionDumpTextOptions): string {
+interface InventoryTool {
+	name: string;
+	description: string;
+	parameters: TSchema;
+	examples?: readonly ToolExample[];
+}
+
+function toInventoryTools(tools: readonly SessionDumpToolInfo[]): InventoryTool[] {
+	return tools.map(tool => ({
+		name: tool.name,
+		description: tool.description,
+		parameters: tool.parameters as TSchema,
+		examples: tool.examples,
+	}));
+}
+
+/** System prompt + model/thinking config + tool inventory — shared by both transcript styles. */
+function renderDumpHeader(options: FormatSessionDumpTextOptions, inventoryTools: readonly InventoryTool[]): string[] {
 	const lines: string[] = [];
-	const definition = getDialectDefinition(preferredDialect(options.model?.id ?? ""));
 
 	const systemPrompt = options.systemPrompt?.filter(prompt => prompt.length > 0) ?? [];
 	if (systemPrompt.length > 0) {
@@ -43,28 +73,142 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 	}
 
 	const model = options.model;
-	const thinkingLevel = options.thinkingLevel;
 	lines.push("## Configuration\n");
 	lines.push(`Model: ${model ? `${model.provider}/${model.id}` : "(not selected)"}`);
-	lines.push(`Thinking Level: ${thinkingLevel ?? ""}`);
+	lines.push(`Thinking Level: ${options.thinkingLevel ?? ""}`);
 	lines.push("\n");
 
-	const tools = options.tools ?? [];
-	const inventoryTools = tools.map(tool => ({
-		name: tool.name,
-		description: tool.description,
-		parameters: tool.parameters as TSchema,
-		examples: tool.examples,
-	}));
 	if (inventoryTools.length > 0) {
 		lines.push("## Available Tools\n");
-		lines.push(renderToolInventory(inventoryTools, options.model?.id ?? ""));
+		lines.push(renderToolInventory(inventoryTools, model?.id ?? ""));
 		lines.push("\n");
 	}
 
-	lines.push("## Transcript\n");
-	lines.push(definition.renderTranscript(convertToLlm([...options.messages]), { tools: inventoryTools }));
-	lines.push("\n");
+	return lines;
+}
+
+/** Append the legacy per-message markdown-heading transcript (the pre-16.x `/dump` body). */
+function appendMarkdownTranscript(lines: string[], messages: readonly AgentMessage[]): void {
+	for (const msg of messages) {
+		if (msg.role === "user" || msg.role === "developer") {
+			lines.push(msg.role === "developer" ? "## Developer\n" : "## User\n");
+			if (typeof msg.content === "string") {
+				lines.push(msg.content);
+			} else {
+				for (const c of msg.content) {
+					if (c.type === "text") lines.push(c.text);
+					else if (c.type === "image") lines.push("[Image]");
+				}
+			}
+			lines.push("\n");
+		} else if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			lines.push("## Assistant\n");
+			for (const c of assistantMsg.content) {
+				if (c.type === "text") {
+					lines.push(c.text);
+				} else if (c.type === "thinking") {
+					const thinking = canonicalizeMessage(c.thinking);
+					if (thinking.length === 0) continue;
+					// Unwrap any literal `<thinking>` envelope already present in the
+					// block (e.g. Opus 4.5 — issue #2700) so the dump never nests tags.
+					lines.push(`${renderDelimitedThinking("<thinking>", "</thinking>", thinking)}\n`);
+				} else if (c.type === "toolCall") {
+					lines.push(`### Tool Call: ${c.name}`);
+					const rawArgs = c.arguments as Record<string, unknown> | undefined;
+					if (rawArgs && typeof rawArgs === "object") {
+						const intent = rawArgs[INTENT_FIELD];
+						if (typeof intent === "string" && intent.trim().length > 0) {
+							for (const line of intent.split("\n")) lines.push(`// ${line}`);
+						}
+						const args: Record<string, unknown> = {};
+						let hasArgs = false;
+						for (const key in rawArgs) {
+							if (key === INTENT_FIELD) continue;
+							args[key] = rawArgs[key];
+							hasArgs = true;
+						}
+						if (hasArgs) {
+							lines.push("```yaml");
+							lines.push(YAML.stringify(args, null, 2).trimEnd());
+							lines.push("```\n");
+						}
+					}
+				}
+			}
+			lines.push("");
+		} else if (msg.role === "toolResult") {
+			lines.push(`### Tool Result: ${msg.toolName}`);
+			if (msg.isError) lines.push("(error)");
+			for (const c of msg.content) {
+				if (c.type === "text") {
+					lines.push("```");
+					lines.push(c.text);
+					lines.push("```");
+				} else if (c.type === "image") {
+					lines.push("[Image output]");
+				}
+			}
+			lines.push("");
+		} else if (msg.role === "bashExecution") {
+			const bashMsg = msg as BashExecutionMessage;
+			if (!bashMsg.excludeFromContext) {
+				lines.push("## Bash Execution\n");
+				lines.push(bashExecutionToText(bashMsg));
+				lines.push("\n");
+			}
+		} else if (msg.role === "pythonExecution") {
+			const pythonMsg = msg as PythonExecutionMessage;
+			if (!pythonMsg.excludeFromContext) {
+				lines.push("## Python Execution\n");
+				lines.push(pythonExecutionToText(pythonMsg));
+				lines.push("\n");
+			}
+		} else if (msg.role === "custom" || msg.role === "hookMessage") {
+			const customMsg = msg as CustomMessage | HookMessage;
+			lines.push(`## ${customMsg.customType}\n`);
+			if (typeof customMsg.content === "string") {
+				lines.push(customMsg.content);
+			} else {
+				for (const c of customMsg.content) {
+					if (c.type === "text") lines.push(c.text);
+					else if (c.type === "image") lines.push("[Image]");
+				}
+			}
+			lines.push("\n");
+		} else if (msg.role === "branchSummary") {
+			const branchMsg = msg as BranchSummaryMessage;
+			lines.push("## Branch Summary\n");
+			lines.push(`(from branch: ${branchMsg.fromId})\n`);
+			lines.push(branchMsg.summary);
+			lines.push("\n");
+		} else if (msg.role === "compactionSummary") {
+			const compactMsg = msg as CompactionSummaryMessage;
+			lines.push("## Compaction Summary\n");
+			lines.push(`(${compactMsg.tokensBefore} tokens before compaction)\n`);
+			lines.push(compactMsg.summary);
+			lines.push("\n");
+		} else if (msg.role === "fileMention") {
+			const fileMsg = msg as FileMentionMessage;
+			lines.push("## File Mention\n");
+			for (const file of fileMsg.files) {
+				lines.push(`<file path="${file.path}">`);
+				if (file.content) lines.push(file.content);
+				if (file.image) lines.push("[Image attached]");
+				lines.push("</file>\n");
+			}
+			lines.push("\n");
+		}
+	}
+}
 
+/**
+ * Format messages and session metadata as markdown/plain text (same as
+ * AgentSession.formatSessionAsText / /dump).
+ */
+export function formatSessionDumpText(options: FormatSessionDumpTextOptions): string {
+	const inventoryTools = toInventoryTools(options.tools ?? []);
+	const lines = renderDumpHeader(options, inventoryTools);
+	appendMarkdownTranscript(lines, options.messages);
 	return lines.join("\n").trim();
 }

package/src/session/session-entries.ts

@@ -124,6 +124,10 @@ export interface SessionInitEntry extends SessionEntryBase {
 	tools: string[];
 	/** Output schema if structured output was requested */
 	outputSchema?: unknown;
+	/** Spawn allowlist the subagent ran with ("" = none, "*" = any, else CSV); absent on pre-spawns files. */
+	spawns?: string;
+	/** The agent's `readSummarize` setting (`false` = read summarization disabled); absent uses the session default. */
+	readSummarize?: boolean;
 }
 
 /** Mode change entry - tracks agent mode transitions (e.g. plan mode). */

package/src/session/session-history-format.ts

@@ -26,6 +26,8 @@ export interface HistoryFormatOptions {
 	includeThinking?: boolean;
 	/** Render tool intent comment before tool call lines. */
 	includeToolIntent?: boolean;
+	/** Render watched-session roles as inline `**agent**:` / `**user**:` labels (collapsing consecutive same-role messages) instead of `## ` headings, so a primary transcript embedded inside an advisor turn stays visually distinct. */
+	watchedRoles?: boolean;
 }
 
 /** Max length of the primary-arg summary inside `→ tool(...)` lines. */
@@ -125,7 +127,7 @@ function toolCallLine(
 	const intent = includeToolIntent ? args?.[INTENT_FIELD] : undefined;
 	if (typeof intent === "string" && intent.trim()) {
 		const formattedIntent = oneLine(intent, 80);
-		return `# ${formattedIntent}\n${base}`;
+		return `// ${formattedIntent}\n${base}`;
 	}
 	return base;
 }
@@ -191,6 +193,11 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 		}
 	}
 	const consumed = new Set<string>();
+	// In watched mode, consecutive same-role messages collapse under one label
+	// (the watched agent emits one assistant message per tool call, so otherwise
+	// every call repeats `**agent**:`). Cleared whenever a
+	// non-role-labeled line is emitted so the next turn re-labels.
+	let lastWatchedLabel: string | undefined;
 
 	for (const msg of typed) {
 		switch (msg.role) {
@@ -198,7 +205,17 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 			case "developer": {
 				const text = contentToText(msg.content);
 				if (!text.trim()) break;
-				lines.push(`## ${msg.role}`, "", text, "");
+				if (opts?.watchedRoles) {
+					const label = `**${msg.role}**:`;
+					if (lastWatchedLabel === label) {
+						lines.push(text, "");
+					} else {
+						lines.push(label, text, "");
+						lastWatchedLabel = label;
+					}
+				} else {
+					lines.push(`## ${msg.role}`, "", text, "");
+				}
 				break;
 			}
 			case "assistant": {
@@ -217,45 +234,62 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 					// redactedThinking elided entirely (no readable text)
 				}
 				if (body.length === 0) break;
-				lines.push("## assistant", "", ...body, "");
+				if (opts?.watchedRoles) {
+					const label = "**agent**:";
+					if (lastWatchedLabel === label) {
+						lines.push(...body, "");
+					} else {
+						lines.push(label, ...body, "");
+						lastWatchedLabel = label;
+					}
+				} else {
+					lines.push("## assistant", "", ...body, "");
+				}
 				break;
 			}
 			case "toolResult": {
 				// Normally consumed by its toolCall; orphans (e.g. truncated history) get their own line.
 				if (consumed.has(msg.toolCallId)) break;
 				lines.push(toolCallLine(msg.toolName, undefined, msg, opts?.includeToolIntent), "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 			case "bashExecution": {
 				const bashMsg = msg as BashExecutionMessage;
 				if (bashMsg.excludeFromContext) break;
 				lines.push(executionLine("bash", bashMsg.command, bashMsg), "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 			case "pythonExecution": {
 				const pythonMsg = msg as PythonExecutionMessage;
 				if (pythonMsg.excludeFromContext) break;
 				lines.push(executionLine("python", pythonMsg.code, pythonMsg), "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 			case "custom":
 			case "hookMessage": {
 				lines.push(customOneLiner(msg as CustomMessage | HookMessage), "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 			case "branchSummary": {
 				const branchMsg = msg as BranchSummaryMessage;
 				lines.push(`[branch] from ${branchMsg.fromId}: ${oneLine(branchMsg.summary)}`, "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 			case "compactionSummary": {
 				const compactMsg = msg as CompactionSummaryMessage;
 				lines.push(`[compaction] ${oneLine(compactMsg.summary)}`, "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 			case "fileMention": {
 				const fileMsg = msg as FileMentionMessage;
 				lines.push(`[file-mention] ${oneLine(fileMsg.files.map(f => f.path).join(", "))}`, "");
+				lastWatchedLabel = undefined;
 				break;
 			}
 		}

package/src/session/session-manager.ts

@@ -71,6 +71,27 @@ function artifactsDirectoryFor(sessionFile: string | undefined): string | null {
 	return sessionFile ? sessionFile.slice(0, -JSONL_SUFFIX_LENGTH) : null;
 }
 
+/**
+ * Resolve a breadcrumb's recorded session file to its interactive root. Subagent
+ * (and other artifact) sessions live inside a parent session's artifacts dir —
+ * `<parent>.jsonl` strips its suffix to `<parent>/`, and a child writes
+ * `<parent>/<agentId>.jsonl`. A breadcrumb that points at such a child — a
+ * pre-fix poisoned crumb left by a subagent that opened in the parent's TTY, or
+ * any nested artifact — must resolve back up to the top-level session so
+ * `--continue` resumes the real conversation instead of a subagent transcript.
+ */
+function resolveBreadcrumbToInteractiveRoot(sessionFile: string): string {
+	let current = path.resolve(sessionFile);
+	// Walk up while the containing dir is itself a session's artifacts dir
+	// (`<dir>.jsonl` exists). Capped to defend against pathological layouts.
+	for (let depth = 0; depth < 8; depth++) {
+		const parentSessionFile = `${path.dirname(current)}.jsonl`;
+		if (!fs.existsSync(parentSessionFile)) return current;
+		current = parentSessionFile;
+	}
+	return current;
+}
+
 function emptyUsageStatistics(): UsageStatistics {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, premiumRequests: 0, cost: 0 };
 }
@@ -462,7 +483,7 @@ export class SessionManager {
 	 * bytes in the kernel page cache, so the file is software-crash durable.
 	 */
 	#rewriteSynchronously(): void {
-		if (!this.#persist || !this.#sessionFile) return;
+		if (!this.#persist || !this.#sessionFile || !this.#shouldHaveSessionFile()) return;
 
 		try {
 			const body = this.#fileBody();
@@ -931,8 +952,10 @@ export class SessionManager {
 	async close(): Promise<void> {
 		if (!this.#persist) return;
 		await this.#scheduleDiskWork(async () => {
+			const hadWriter = this.#writer !== undefined;
 			await this.#closeWriterHandle();
-			this.#fileIsCurrent = true;
+			if (hadWriter || (this.#sessionFile && this.#storage.existsSync(this.#sessionFile)))
+				this.#fileIsCurrent = true;
 		});
 		if (this.#diskFailure) throw this.#diskFailure;
 	}
@@ -1157,7 +1180,14 @@ export class SessionManager {
 		return entry.id;
 	}
 
-	appendSessionInit(init: { systemPrompt: string; task: string; tools: string[]; outputSchema?: unknown }): string {
+	appendSessionInit(init: {
+		systemPrompt: string;
+		task: string;
+		tools: string[];
+		outputSchema?: unknown;
+		spawns?: string;
+		readSummarize?: boolean;
+	}): string {
 		const entry: SessionInitEntry = { type: "session_init", ...this.#freshEntryFields(), ...init };
 		this.#recordEntry(entry);
 		return entry.id;
@@ -1528,17 +1558,74 @@ export class SessionManager {
 		filePath: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
-		options?: { initialCwd?: string },
+		options?: { initialCwd?: string; suppressBreadcrumb?: boolean },
 	): Promise<SessionManager> {
 		const loaded = await loadEntriesFromFile(filePath, storage);
 		const header = loaded.find(entry => entry.type === "session") as SessionHeader | undefined;
 		const cwd = header?.cwd ?? options?.initialCwd ?? getProjectDir();
 		const dir = sessionDir ?? path.dirname(path.resolve(filePath));
 		const manager = new SessionManager(cwd, dir, true, storage);
+		manager.#suppressBreadcrumb = options?.suppressBreadcrumb === true;
 		await manager.setSessionFile(filePath);
 		return manager;
 	}
 
+	/**
+	 * Lock-free peek for cold subagent revival: returns the recorded working
+	 * directory (session header) and the latest `session_init` contract (system
+	 * prompt / tools / output schema) WITHOUT taking the single-writer lock that
+	 * {@link open} acquires — the caller re-opens for the actual revive. Returns
+	 * null when the file can't be read; `init` is null for files written before
+	 * `session_init` was recorded (no faithful contract to rebuild from).
+	 */
+	static async peekSessionInit(
+		filePath: string,
+		storage: SessionStorage = new FileSessionStorage(),
+	): Promise<{
+		cwd: string;
+		init: {
+			systemPrompt: string;
+			task: string;
+			tools: string[];
+			outputSchema?: unknown;
+			spawns?: string;
+			readSummarize?: boolean;
+		} | null;
+	} | null> {
+		let loaded: FileEntry[];
+		try {
+			loaded = await loadEntriesFromFile(filePath, storage);
+		} catch {
+			return null;
+		}
+		// A missing/empty file has no usable session — nothing to revive from.
+		if (loaded.length === 0) return null;
+		const header = loaded.find(entry => entry.type === "session") as SessionHeader | undefined;
+		let init: {
+			systemPrompt: string;
+			task: string;
+			tools: string[];
+			outputSchema?: unknown;
+			spawns?: string;
+			readSummarize?: boolean;
+		} | null = null;
+		for (let index = loaded.length - 1; index >= 0; index--) {
+			const entry = loaded[index];
+			if (entry.type === "session_init") {
+				init = {
+					systemPrompt: entry.systemPrompt,
+					task: entry.task,
+					tools: entry.tools,
+					outputSchema: entry.outputSchema,
+					readSummarize: entry.readSummarize,
+					spawns: entry.spawns,
+				};
+				break;
+			}
+		}
+		return { cwd: header?.cwd ?? getProjectDir(), init };
+	}
+
 	/** Continue the most recent session, or create a new one if none exists. */
 	static async continueRecent(
 		cwd: string,
@@ -1551,6 +1638,9 @@ export class SessionManager {
 		let chosenSession: string | null | undefined;
 
 		if (breadcrumb) {
+			// Recover stale crumbs: a subagent open (pre-fix) may have pointed this
+			// terminal's breadcrumb at an artifact child; resume the parent instead.
+			breadcrumb.sessionFile = resolveBreadcrumbToInteractiveRoot(breadcrumb.sessionFile);
 			const breadcrumbCwd = path.resolve(breadcrumb.cwd);
 			if (breadcrumbCwd === resolvedCwd) {
 				chosenSession = breadcrumb.sessionFile;

package/src/slash-commands/builtin-registry.ts

@@ -547,17 +547,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		name: "dump",
 		description: "Copy session transcript to clipboard",
 		acpDescription: "Return full transcript as plain text",
-		inlineHint: "[raw]",
 		allowArgs: true,
-		handle: async (command, runtime) => {
-			const isRaw = command.args.trim().toLowerCase() === "raw";
-			const text = runtime.session.formatSessionAsText({ compact: !isRaw });
+		handle: async (_command, runtime) => {
+			const text = runtime.session.formatSessionAsText();
 			await runtime.output(text || "No messages to dump yet.");
 			return commandConsumed();
 		},
-		handleTui: (command, runtime) => {
-			const isRaw = command.args.trim().toLowerCase() === "raw";
-			runtime.ctx.handleDumpCommand(isRaw);
+		handleTui: (_command, runtime) => {
+			runtime.ctx.handleDumpCommand();
 			runtime.ctx.editor.setText("");
 		},
 	},

package/src/stt/asr-client.ts

@@ -314,6 +314,12 @@ export class SttClient {
 		const worker = this.#ensureWorker();
 		const id = String(++this.#nextRequestId);
 		const { promise, resolve, reject } = Promise.withResolvers<string>();
+		// `stop()` is normally the only awaiter of `promise`, but with model loading
+		// now deferred to the stream, a load failure (or early worker error) can
+		// reject it before the caller stops — attach a benign handler so that never
+		// surfaces as an unhandled rejection. stop()/await still observes the
+		// rejection through the original promise.
+		void promise.catch(() => {});
 		const signal = options.signal;
 		let settled = false;
 		const onAbort = (): void => handle.cancel();

package/src/stt/downloader.ts

@@ -39,12 +39,12 @@ export interface SttDownloadProgress {
 }
 
 /**
- * Whether the selected model is already present in the local cache. For
+ * Whether the selected model is fully present in the local cache. For
  * transformers.js Whisper tiers a complete download leaves `config.json` plus
- * the `onnx/` weight files (a bare `config.json` from an interrupted fetch reads
- * as not-cached); for sherpa-onnx tiers every model file (encoder/decoder/joiner
- * + tokens) must be present (`.part` sidecars from an interrupted fetch are
- * ignored).
+ * matching `encoder*.onnx` and `decoder*.onnx` shards under `onnx/` (a partial
+ * fetch with only one shard, or a bare `config.json`, reads as not-cached); for
+ * sherpa-onnx tiers every model file (encoder/decoder/joiner + tokens) must be
+ * present (`.part` sidecars from an interrupted fetch are ignored).
  */
 export async function isSttModelCached(key: string): Promise<boolean> {
 	const spec = resolveSttModelSpec(key);
@@ -63,8 +63,15 @@ export async function isSttModelCached(key: string): Promise<boolean> {
 	try {
 		const root = await fs.readdir(repoDir);
 		if (!root.includes("config.json")) return false;
+		// Whisper tiers are encoder-decoder: a complete download leaves both an
+		// `encoder*.onnx` and a `decoder*.onnx` (the dtype suffix varies). Require
+		// both rather than any single `.onnx`, so an interrupted fetch that landed
+		// only one shard reads as not-cached and the caller takes the foreground
+		// download path with progress instead of silently fetching mid-recording.
 		const onnxFiles = await fs.readdir(path.join(repoDir, "onnx")).catch(() => [] as string[]);
-		return onnxFiles.some(file => file.endsWith(".onnx"));
+		const hasEncoder = onnxFiles.some(file => file.startsWith("encoder") && file.endsWith(".onnx"));
+		const hasDecoder = onnxFiles.some(file => file.startsWith("decoder") && file.endsWith(".onnx"));
+		return hasEncoder && hasDecoder;
 	} catch {
 		return false;
 	}

package/src/stt/stt-controller.ts

@@ -4,10 +4,11 @@ import * as path from "node:path";
 import { logger, Snowflake } from "@oh-my-pi/pi-utils";
 import { settings } from "../config/settings";
 import { type SttStreamHandle, sttClient } from "./asr-client";
-import { ensureSTTDependencies } from "./downloader";
+import { downloadSttModel, isSttModelCached } from "./downloader";
 import { resolveSttModelSpec } from "./models";
 import {
 	detectRecorder,
+	ensureRecorder,
 	type RecordingHandle,
 	type StreamingRecordingHandle,
 	startRecording,
@@ -36,7 +37,7 @@ interface Editor {
 
 export class STTController {
 	#state: SttState = "idle";
-	#depsResolved = false;
+	#resolvedModelKey: string | null = null;
 	#toggling = false;
 	#stopAfterStart = false;
 	#disposed = false;
@@ -92,15 +93,39 @@ export class STTController {
 	}
 
 	async #ensureDeps(options: ToggleOptions): Promise<boolean> {
-		if (this.#depsResolved) return true;
+		const modelKey = resolveSttModelSpec(settings.get("stt.modelName") as string | undefined).key;
+		// Keyed on the model rather than a one-shot flag: switching stt.modelName
+		// mid-session must re-run preflight so an uncached new tier downloads here
+		// (with progress) instead of blocking silently at stop.
+		if (this.#resolvedModelKey === modelKey) return true;
 		try {
-			options.showStatus("Checking STT dependencies...");
-			await ensureSTTDependencies({
-				modelName: settings.get("stt.modelName") as string | undefined,
-				onProgress: p => options.showStatus(p.stage + (p.percent != null ? ` (${p.percent}%)` : "")),
-			});
-			options.showStatus("");
-			this.#depsResolved = true;
+			// Only clear the status line if we actually wrote to it: the cached
+			// fast path (recorder on PATH, model present) emits nothing, so an
+			// unconditional clear would be a stray write.
+			let wroteStatus = false;
+			const status = (msg: string): void => {
+				wroteStatus = true;
+				options.showStatus(msg);
+			};
+			// A recorder is required to capture audio; startRecording /
+			// startStreamingRecording only *detect* a recorder and throw when none
+			// exists, so provision one here. Instant when sox/ffmpeg/arecord is on
+			// PATH — only a first-run static-ffmpeg download actually blocks.
+			await ensureRecorder(p => status(p.stage + (p.percent != null ? ` (${p.percent}%)` : "")));
+			// Loading the multi-hundred-MB speech model into the worker is what made
+			// the old "Checking STT dependencies…" step slow. Don't pay it before
+			// recording: when the weights are already cached, start now and warm the
+			// model in the background — the stream/transcribe paths load it on demand
+			// (memoized in the worker) and it is hot by the time recording stops.
+			// Only a genuine first-use download blocks, with explicit progress, so we
+			// never record silently against missing weights.
+			if (await isSttModelCached(modelKey)) {
+				this.#warmModel(modelKey);
+			} else {
+				await downloadSttModel(modelKey, p => status(`Downloading speech model ${p.label} (${p.percent}%)`));
+			}
+			if (wroteStatus) options.showStatus("");
+			this.#resolvedModelKey = modelKey;
 			return true;
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : "Failed to setup STT dependencies";
@@ -110,6 +135,22 @@ export class STTController {
 		}
 	}
 
+	/** Warm the speech model in the worker without blocking recording. The worker
+	 *  memoizes the load, so the stream/transcribe path reuses it and the model is
+	 *  hot by the time recording stops. Only called when the weights are already
+	 *  cached, so no network fetch happens. On load failure (corrupt cache, OOM,
+	 *  runtime install) invalidate the resolved key so the next toggle re-runs
+	 *  preflight and retries instead of skipping it forever. */
+	#warmModel(modelKey: string): void {
+		void downloadSttModel(modelKey).catch(err => {
+			// Guard against a concurrent model switch clobbering a newer resolution.
+			if (!this.#disposed && this.#resolvedModelKey === modelKey) this.#resolvedModelKey = null;
+			logger.debug("stt: background model warmup failed", {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		});
+	}
+
 	async #start(editor: Editor, options: ToggleOptions): Promise<void> {
 		if (!(await this.#ensureDeps(options))) return;
 		// Live transcription needs a recorder that can pipe PCM; the Windows
@@ -334,6 +375,6 @@ export class STTController {
 			this.#tempFile = null;
 		}
 		this.#state = "idle";
-		this.#depsResolved = false;
+		this.#resolvedModelKey = null;
 	}
 }