@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

package/src/tools/todo.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { ToolExample } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
-import { prompt } from "@oh-my-pi/pi-utils";
+import { isRecord, prompt } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import chalk from "chalk";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -18,13 +18,15 @@ import { formatErrorDetail, formatMoreItems, PREVIEW_LIMITS, pluralize } from ".
 // Types
 // =============================================================================
 
-export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 /** Operation names accepted by the todo tool and echoed in successful result details. */
-export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "append" | "view";
+export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view";
 
 export interface TodoItem {
 	content: string;
 	status: TodoStatus;
+	/** When `status === "blocked"`, an optional note on what the task is waiting for. */
+	blocker?: string;
 }
 
 export interface TodoPhase {
@@ -32,6 +34,21 @@ export interface TodoPhase {
 	tasks: TodoItem[];
 }
 
+/** Whether an unknown value is a persisted todo phase. */
+export function isTodoPhase(value: unknown): value is TodoPhase {
+	if (!isRecord(value) || typeof value.name !== "string" || !Array.isArray(value.tasks)) return false;
+	return value.tasks.every(
+		task =>
+			isRecord(task) &&
+			typeof task.content === "string" &&
+			(task.status === "pending" ||
+				task.status === "in_progress" ||
+				task.status === "completed" ||
+				task.status === "abandoned" ||
+				task.status === "blocked"),
+	);
+}
+
 export interface TodoCompletionTransition {
 	phase: string;
 	content: string;
@@ -49,7 +66,9 @@ export interface TodoToolDetails {
 // Schema
 // =============================================================================
 
-const TodoOp = type('"init" | "start" | "done" | "rm" | "drop" | "append" | "view"').describe("operation to apply");
+const TodoOp = type('"init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view"').describe(
+	"operation to apply",
+);
 
 const InitListEntry = type({
 	phase: type("string").describe("phase name"),
@@ -65,6 +84,7 @@ const todoSchema = type({
 	// and both enforce non-empty with op-specific errors. A stray `items: []` on
 	// an op that ignores it (e.g. `view`) must not be a hard schema rejection.
 	"items?": type("string").describe("task content").array().describe("tasks to append"),
+	"reason?": type("string").describe("blocker note (block op)"),
 }).describe("apply a single todo operation");
 
 type TodoParams = TodoSchema;
@@ -89,7 +109,9 @@ function findPhaseByName(phases: TodoPhase[], name: string): TodoPhase | undefin
 }
 
 function cloneTask(task: TodoItem): TodoItem {
-	return { content: task.content, status: task.status };
+	return task.blocker !== undefined
+		? { content: task.content, status: task.status, blocker: task.blocker }
+		: { content: task.content, status: task.status };
 }
 
 function clonePhases(phases: TodoPhase[]): TodoPhase[] {
@@ -256,7 +278,9 @@ export function selectCollapsedTodos<T extends { status: TodoStatus }>(
 	isMatched: (task: T) => boolean,
 	cap: number,
 ): CollapsedTodoSelection<T> {
-	const open = tasks.filter(task => task.status === "pending" || task.status === "in_progress");
+	const open = tasks.filter(
+		task => task.status === "pending" || task.status === "in_progress" || task.status === "blocked",
+	);
 	// No open work: fall back to the closed tasks so a settled phase still
 	// renders (HUD closed-todo persistence). Closed tasks are never active.
 	const base = open.length > 0 ? open : tasks;
@@ -456,6 +480,41 @@ function applyEntry(phases: TodoPhase[], entry: TodoOpEntryValue, errors: string
 			}
 			return phases;
 		}
+		case "block": {
+			if (!entry.task && !entry.phase) {
+				errors.push("block requires a task or phase target");
+				return phases;
+			}
+			// Collapse whitespace runs (incl. newlines) to single spaces: a blocker
+			// note rides on one Markdown checklist line (as a trailing HTML comment)
+			// and one HUD/summary line, so an embedded newline from a multi-line
+			// external error or user question would corrupt the round-trip parse and
+			// the rendered line. Normalizing here keeps every consumer one-line-safe.
+			const reason = entry.reason?.replace(/\s+/g, " ").trim() || undefined;
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				// Only actionable open work can be blocked: blocking a phase must not
+				// reopen completed/abandoned tasks or erase finished progress. An
+				// already-blocked task stays eligible so a later block can refine its
+				// blocker note (e.g. first blocked without a reason, then with one).
+				if (task.status !== "pending" && task.status !== "in_progress" && task.status !== "blocked") continue;
+				task.status = "blocked";
+				task.blocker = reason;
+			}
+			return phases;
+		}
+		case "unblock": {
+			if (!entry.task && !entry.phase) {
+				errors.push("unblock requires a task or phase target");
+				return phases;
+			}
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				if (task.status === "blocked") {
+					task.status = "pending";
+					task.blocker = undefined;
+				}
+			}
+			return phases;
+		}
 		case "rm":
 			return removeTasks(phases, entry, errors);
 		case "append":
@@ -495,6 +554,7 @@ const STATUS_TO_MARKER: Record<TodoStatus, string> = {
 	in_progress: "/",
 	completed: "x",
 	abandoned: "-",
+	blocked: "!",
 };
 
 export function resolveTodoMarkdownPath(input: string, cwd: string): string {
@@ -510,7 +570,12 @@ export function phasesToMarkdown(phases: TodoPhase[]): string {
 		if (i > 0) out.push("");
 		out.push(`# ${phases[i].name}`);
 		for (const task of phases[i].tasks) {
-			out.push(`- [${STATUS_TO_MARKER[task.status]}] ${task.content}`);
+			// A blocked task's reason rides in a trailing HTML comment: invisible in
+			// rendered markdown, unambiguous to parse back (task content can't
+			// contain the comment delimiters), so the note survives `/todo edit` and
+			// export/import round-trips.
+			const blockerNote = task.status === "blocked" && task.blocker ? ` <!-- blocker: ${task.blocker} -->` : "";
+			out.push(`- [${STATUS_TO_MARKER[task.status]}] ${task.content}${blockerNote}`);
 		}
 	}
 	return `${out.join("\n")}\n`;
@@ -525,6 +590,7 @@ const MARKER_TO_STATUS: Record<string, TodoStatus> = {
 	">": "in_progress",
 	"-": "abandoned",
 	"~": "abandoned",
+	"!": "blocked",
 };
 
 /** Parse a Markdown checklist back into todo phases. */
@@ -556,10 +622,18 @@ export function markdownToPhases(md: string): { phases: TodoPhase[]; errors: str
 			const marker = taskMatch[1];
 			const status = MARKER_TO_STATUS[marker];
 			if (!status) {
-				errors.push(`Line ${lineNum + 1}: unknown status marker "[${marker}]" (use [ ], [x], [/], [-])`);
+				errors.push(`Line ${lineNum + 1}: unknown status marker "[${marker}]" (use [ ], [x], [/], [-], [!])`);
 				continue;
 			}
-			currentPhase.tasks.push({ content: taskMatch[2].trim(), status });
+			// Recover a blocked task's reason from its trailing HTML comment (see
+			// phasesToMarkdown), then strip the comment from the visible content.
+			const rawContent = taskMatch[2].trim();
+			const blockerMatch = /^(.*?)\s*<!--\s*blocker:\s*(.*?)\s*-->$/.exec(rawContent);
+			if (status === "blocked" && blockerMatch) {
+				currentPhase.tasks.push({ content: blockerMatch[1].trim(), status, blocker: blockerMatch[2].trim() });
+			} else {
+				currentPhase.tasks.push({ content: rawContent, status });
+			}
 			continue;
 		}
 
@@ -604,6 +678,7 @@ function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false):
 	}
 	// Closed = completed + abandoned, mirroring the per-phase `done` count.
 	const closedAll = tasks.filter(task => task.status === "completed" || task.status === "abandoned").length;
+	const blockedAll = tasks.filter(task => task.status === "blocked").length;
 	// The active phase is the EARLIEST one still holding open work, so the
 	// in-progress pointer can sit in a phase whose successors already have
 	// completed tasks. Detect that "worked ahead" case to explain the
@@ -613,7 +688,9 @@ function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false):
 		(phase, idx) =>
 			idx > currentIdx && phase.tasks.some(task => task.status === "completed" || task.status === "abandoned"),
 	);
-	lines.push(`Overall: ${closedAll}/${tasks.length} done, ${remainingTasks.length} open.`);
+	lines.push(
+		`Overall: ${closedAll}/${tasks.length} done, ${remainingTasks.length} open${blockedAll > 0 ? `, ${blockedAll} blocked` : ""}.`,
+	);
 	lines.push(
 		`Active phase ${currentIdx + 1}/${phases.length} "${current.name}" (${done}/${current.tasks.length})${
 			workedAhead
@@ -625,7 +702,16 @@ function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false):
 		lines.push(`  ${phase.name}:`);
 		for (const task of phase.tasks) {
 			const checkbox = task.status === "completed" ? "[X]" : "[ ]";
-			const tag = task.status === "in_progress" ? " (in progress)" : task.status === "abandoned" ? " (dropped)" : "";
+			const tag =
+				task.status === "in_progress"
+					? " (in progress)"
+					: task.status === "abandoned"
+						? " (dropped)"
+						: task.status === "blocked"
+							? task.blocker
+								? ` (blocked: ${task.blocker})`
+								: " (blocked)"
+							: "";
 			lines.push(`    - ${checkbox} ${task.content}${tag}`);
 		}
 	}
@@ -845,6 +931,10 @@ function formatTodoLine(
 			return uiTheme.fg("accent", `${prefix}${checkbox.unchecked} ${item.content}`);
 		case "abandoned":
 			return uiTheme.fg("error", `${prefix}${checkbox.unchecked} ${strikethroughText(item.content)}`);
+		case "blocked": {
+			const note = item.blocker ? `blocked: ${item.blocker}` : "blocked";
+			return uiTheme.fg("warning", `${prefix}${checkbox.unchecked} ${item.content} (${note})`);
+		}
 		default:
 			// A pending todo lit by a live subagent match renders accent, matching
 			// the sticky HUD's convention (#5873).

package/src/tools/vibe.ts

@@ -23,7 +23,6 @@ import vibeListDescription from "../prompts/tools/vibe-list.md" with { type: "te
 import vibeSendDescription from "../prompts/tools/vibe-send.md" with { type: "text" };
 import vibeSpawnDescription from "../prompts/tools/vibe-spawn.md" with { type: "text" };
 import vibeWaitDescription from "../prompts/tools/vibe-wait.md" with { type: "text" };
-import { MAIN_AGENT_ID } from "../registry/agent-registry";
 import { oneLineLabel } from "../task/types";
 import { renderStatusLine } from "../tui";
 import {
@@ -93,7 +92,7 @@ export interface VibeToolDetails {
 }
 
 function screensOf(session: ToolSession, ids?: string[]): VibeScreenSnapshot[] {
-	return VibeSessionRegistry.global().screens(session.getAgentId?.() ?? MAIN_AGENT_ID, ids);
+	return VibeSessionRegistry.global().screens(session, ids);
 }
 
 function textResult(text: string, details: VibeToolDetails): AgentToolResult<VibeToolDetails> {

package/src/tools/write.ts

@@ -49,7 +49,14 @@ import {
 } from "./conflict-detect";
 import { invalidateFsScanAfterWrite } from "./fs-cache-invalidation";
 import { type OutputMeta, outputMeta } from "./output-meta";
-import { formatPathRelativeToCwd, isInternalUrlPath, pathTargetsSsh, peelWriteUrlSelector } from "./path-utils";
+import {
+	formatPathRelativeToCwd,
+	isInternalUrlPath,
+	pathTargetsSsh,
+	peelWriteUrlSelector,
+	probeLiteralPathExists,
+	splitPathAndSel,
+} from "./path-utils";
 import { enforcePlanModeWrite, resolvePlanPath, unwrapHashlineHeaderPath } from "./plan-mode-guard";
 import {
 	cachedRenderedString,
@@ -116,6 +123,43 @@ function assertWriteTargetAddressable(target: string, router: InternalUrlRouter)
 	);
 }
 
+/**
+ * Fail closed when a local write target looks like a mis-dispatched read.
+ *
+ * A read-only step that selects `write` instead of `read` passes the full read
+ * expression (`src/foo.tsx:1-260:raw`) as the target. Because a literal colon
+ * filename is legal on POSIX (issue #4618), that request otherwise resolves to
+ * filesystem creation and reports success, leaving a stray zero-byte file the
+ * model cannot recover from — the local analogue of the `xd://` near-miss guard
+ * ({@link assertWriteTargetAddressable}, issue #6123).
+ *
+ * Fires only on the high-confidence combination the report identifies: the tail
+ * parses as a read-tool selector, the literal target is missing, and no content
+ * was supplied. Non-empty content is the escape hatch — it is never blocked, so
+ * a deliberate write to a selector-shaped filename still succeeds. An existing
+ * literal path or an ambiguous stat (`"unknown"`: EACCES, transient I/O) also
+ * passes through so a real file is never shadowed by the guard.
+ */
+function readSelectorForEmptyWrite(target: string, content: string): string | undefined {
+	if (content.length > 0) return undefined;
+	return splitPathAndSel(target).sel;
+}
+
+function throwReadSelectorMisfire(target: string, sel: string): never {
+	throw new ToolError(
+		`write target '${target}' ends with a read-tool selector ':${sel}' and no such file exists — refusing to create a literal file by that name. ` +
+			`If you meant to read it, use read({ path: "${target}" }). ` +
+			`If you truly intend to create this file, pass its contents in \`content\` (a non-empty write is never blocked).`,
+	);
+}
+
+async function assertNotReadSelectorMisfire(target: string, content: string, cwd: string): Promise<void> {
+	const sel = readSelectorForEmptyWrite(target, content);
+	if (sel === undefined) return;
+	if ((await probeLiteralPathExists(target, cwd)) !== "missing") return;
+	throwReadSelectorMisfire(target, sel);
+}
+
 const BULK_DIRECTIVE_RE = /^#?(\d+)\s*[:=]\s*(@ours|@theirs|@base|@both)$/;
 /**
  * The head of a per-id directive line — `<id>:` / `<id>=` (optionally `#`-prefixed),
@@ -576,6 +620,11 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				throw new ToolError(error instanceof Error ? error.message : String(error));
 			}
 		}
+		const writeTarget = `${resolvedArchivePath.archivePath}:${resolvedArchivePath.archiveSubPath}`;
+		const sel = readSelectorForEmptyWrite(writeTarget, content);
+		if (sel !== undefined && !entries.has(resolvedArchivePath.archiveSubPath)) {
+			throwReadSelectorMisfire(writeTarget, sel);
+		}
 		entries.set(resolvedArchivePath.archiveSubPath, content);
 
 		try {
@@ -1159,6 +1208,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				return sqliteResult;
 			}
 
+			await assertNotReadSelectorMisfire(path, cleanContent, this.session.cwd);
 			enforcePlanModeWrite(this.session, path, { op: "create" });
 			const absolutePath = resolvePlanPath(this.session, path);
 			const batchRequest = getLspBatchRequest(context?.toolCall);

package/src/tools/xdev.ts

@@ -60,6 +60,9 @@ export const XDEV_KEEP_TOP_LEVEL: Record<string, true> = {
  */
 export const XDEV_TRANSPORT_TOOLS: Record<string, true> = { read: true, write: true };
 
+/** Controls which mounted-device docs are inlined into the system prompt. */
+export type XdevDocsMode = "inline" | "builtins" | "catalog";
+
 /**
  * Whether an enabled tool is presented under `xd://` (rather than top-level)
  * while the `xd://` transport is active. Discoverable tools mount unless they
@@ -170,6 +173,28 @@ function toolSummary(inst: Tool): string {
 	return firstLine?.trim() ?? inst.label ?? inst.name;
 }
 
+function promptCatalogSummary(inst: Tool, maxLength?: number): string {
+	const summary =
+		toolSummary(inst)
+			.split("\n")
+			.find(line => line.trim().length > 0)
+			?.trim() ?? inst.name;
+	if (maxLength === undefined || summary.length <= maxLength) return summary;
+	return `${summary.slice(0, maxLength).trimEnd()}…`;
+}
+
+/** Compile the `tools.xdevInlineDevices` allowlist once per render, dropping
+ *  non-string entries so malformed user config cannot break prompt builds. */
+function compileInlineGlobs(patterns: readonly string[]): Bun.Glob[] {
+	if (!Array.isArray(patterns)) return [];
+	const globs: Bun.Glob[] = [];
+	for (const pattern of patterns) {
+		if (typeof pattern !== "string" || pattern.length === 0) continue;
+		globs.push(new Bun.Glob(pattern));
+	}
+	return globs;
+}
+
 /** Decode the (possibly partially streamed) inner args JSON string into display args. */
 function decodeInnerArgs(raw: unknown): Record<string, unknown> {
 	if (typeof raw !== "string" || raw.length === 0) return {};
@@ -230,7 +255,13 @@ export class XdevRegistry {
 
 	/** `{name, summary}` pairs for prompt templates and /tools display. */
 	entries(): Array<{ name: string; summary: string }> {
-		return this.list().map(tool => ({ name: tool.name, summary: toolSummary(tool) }));
+		return this.list().map(tool => ({
+			name: tool.name,
+			summary: promptCatalogSummary(
+				tool,
+				this.#dynamic.has(tool.name) ? XdevRegistry.EXTERNAL_DESCRIPTION_CAP : undefined,
+			),
+		}));
 	}
 
 	/** `read xd://` listing with one device per line. */
@@ -273,11 +304,16 @@ export class XdevRegistry {
 	 * Dynamic mounts embed at most {@link EXTERNAL_DESCRIPTION_CAP} description
 	 * chars (schema always intact); `read xd://<tool>` returns the full text.
 	 */
-	docsAll(): string {
+	docsAll(mode: XdevDocsMode = "inline", inlinePatterns: readonly string[] = []): string {
 		const sections: string[] = [];
 		const overflow: Tool[] = [];
+		const inlineGlobs = compileInlineGlobs(inlinePatterns);
 		let used = 0;
 		for (const tool of this.list()) {
+			if (!this.#shouldInline(tool, mode, inlineGlobs)) {
+				overflow.push(tool);
+				continue;
+			}
 			const descriptionCap = this.#dynamic.has(tool.name) ? XdevRegistry.EXTERNAL_DESCRIPTION_CAP : undefined;
 			const docs = renderDocs(tool, "##", descriptionCap);
 			if (docs.length > XdevRegistry.DOCS_PER_DEVICE_CAP || used + docs.length > XdevRegistry.DOCS_TOTAL_BUDGET) {
@@ -291,7 +327,10 @@ export class XdevRegistry {
 			sections.push(
 				[
 					"## Additional devices (docs on demand)",
-					...overflow.map(tool => `- ${XD_URL_PREFIX}${tool.name} — ${toolSummary(tool)}`),
+					...overflow.map(tool => {
+						const maxLength = this.#dynamic.has(tool.name) ? XdevRegistry.EXTERNAL_DESCRIPTION_CAP : undefined;
+						return `- ${XD_URL_PREFIX}${tool.name} — ${promptCatalogSummary(tool, maxLength)}`;
+					}),
 					"",
 					`Read ${XD_URL_PREFIX}<tool> for full docs + JSON schema before first use.`,
 				].join("\n"),
@@ -300,6 +339,31 @@ export class XdevRegistry {
 		return sections.join("\n\n");
 	}
 
+	/** Docs for selected mounted devices under the configured prompt-doc policy. */
+	docsFor(names: Iterable<string>, mode: XdevDocsMode, inlinePatterns: readonly string[] = []): string {
+		const sections: string[] = [];
+		const inlineGlobs = compileInlineGlobs(inlinePatterns);
+		let used = 0;
+		for (const name of names) {
+			const tool = this.get(name);
+			if (!tool || !this.#shouldInline(tool, mode, inlineGlobs)) continue;
+			const descriptionCap = this.#dynamic.has(tool.name) ? XdevRegistry.EXTERNAL_DESCRIPTION_CAP : undefined;
+			const docs = renderDocs(tool, "##", descriptionCap);
+			if (docs.length > XdevRegistry.DOCS_PER_DEVICE_CAP || used + docs.length > XdevRegistry.DOCS_TOTAL_BUDGET)
+				continue;
+			used += docs.length;
+			sections.push(docs);
+		}
+		return sections.join("\n\n");
+	}
+
+	#shouldInline(tool: Tool, mode: XdevDocsMode, inlineGlobs: readonly Bun.Glob[]): boolean {
+		return (
+			mode !== "catalog" &&
+			(mode === "inline" || this.#builtins.has(tool.name) || inlineGlobs.some(glob => glob.match(tool.name)))
+		);
+	}
+
 	#resolve(name: string): Tool {
 		const inst = this.get(name);
 		if (!inst) {

package/src/tts/streaming-player.ts

@@ -31,6 +31,15 @@ const DEFAULT_SAMPLE_RATE = 24_000;
 const LEAD_SECONDS = 0.6;
 /** Output gain applied while ducked (the user is speaking over the assistant). */
 export const DUCK_GAIN = 0.25;
+/**
+ * Cap on streamed PCM retained for the nonzero-exit replay. Past this the
+ * buffer is dropped: the failure being recovered is a short clip that fits the
+ * OS pipe buffer before a broken backend dies, while a backend that consumed
+ * minutes of realtime-paced audio was playing it — replaying a whole long
+ * utterance would duplicate audio, and unbounded retention (~5.8 MB/min at
+ * 24 kHz mono f32) would defeat streaming for long input.
+ */
+const REPLAY_RETENTION_SECONDS = 60;
 
 /** Injection seam for {@link streamingPlayerCommandsFor} — defaults to real PATH/tools lookups. */
 export interface StreamingPlayerLookup {
@@ -89,6 +98,20 @@ export function streamingPlayerCommandsFor(
 	return commands;
 }
 
+/**
+ * Test seams for {@link StreamingAudioPlayer}: override backend discovery and
+ * the per-file fallback so playback logic can be exercised without a real audio
+ * device. Both default to the platform lookup and {@link playAudioFile}.
+ */
+export interface StreamingPlayerOptions {
+	/** Ordered backend commands for a sample rate; defaults to {@link streamingPlayerCommandsFor}. */
+	commandsFor?: (sampleRate: number) => PlayerCommand[];
+	/** Per-file fallback playback; defaults to {@link playAudioFile}. */
+	playAudio?: (wavPath: string, signal: AbortSignal) => Promise<void>;
+	/** Max seconds of streamed PCM retained for the nonzero-exit replay; defaults to {@link REPLAY_RETENTION_SECONDS}. */
+	replayRetentionSeconds?: number;
+}
+
 /**
  * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
  * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
@@ -111,6 +134,18 @@ export class StreamingAudioPlayer {
 	#abortController = new AbortController();
 	#wake: (() => void) | null = null;
 	#drain: Promise<void> = Promise.resolve();
+	readonly #commandsFor: (sampleRate: number) => PlayerCommand[];
+	readonly #playAudio: (wavPath: string, signal: AbortSignal) => Promise<void>;
+	readonly #replayRetentionSec: number;
+	/** Streamed PCM retained for this utterance so a failed backend can be replayed via file playback. */
+	#played: Float32Array[] = [];
+	#playedSec = 0;
+
+	constructor(options: StreamingPlayerOptions = {}) {
+		this.#commandsFor = options.commandsFor ?? (rate => streamingPlayerCommandsFor(process.platform, rate));
+		this.#playAudio = options.playAudio ?? ((wavPath, signal) => playAudioFile(wavPath, { signal }));
+		this.#replayRetentionSec = options.replayRetentionSeconds ?? REPLAY_RETENTION_SECONDS;
+	}
 
 	/** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
 	start(sampleRate: number): void {
@@ -146,6 +181,7 @@ export class StreamingAudioPlayer {
 		if (this.#stopped) return;
 		this.#stopped = true;
 		this.#queue.length = 0;
+		this.#played.length = 0;
 		this.#abortController.abort();
 		this.#signal();
 		try {
@@ -168,7 +204,7 @@ export class StreamingAudioPlayer {
 	 * in-flight chunk.
 	 */
 	#spawnStream(): boolean {
-		this.#candidates ??= streamingPlayerCommandsFor(process.platform, this.#sampleRate);
+		this.#candidates ??= this.#commandsFor(this.#sampleRate);
 		for (let command = this.#candidates.shift(); command; command = this.#candidates.shift()) {
 			const { cmd, args } = command;
 			try {
@@ -213,6 +249,12 @@ export class StreamingAudioPlayer {
 					continue;
 				}
 				if (this.#mode === "stream") {
+					if (this.#playedSec <= this.#replayRetentionSec) {
+						this.#played.push(chunk);
+						this.#playedSec += chunk.length / this.#sampleRate;
+						// Over the cap: drop retention for the rest of the utterance.
+						if (this.#playedSec > this.#replayRetentionSec) this.#played.length = 0;
+					}
 					// Pace writes so the player buffers ~LEAD_SECONDS, no more, keeping
 					// ducking and stop responsive instead of locked behind buffered audio.
 					const ahead = this.#writtenSec - (performance.now() - this.#startedAt) / 1000;
@@ -242,11 +284,27 @@ export class StreamingAudioPlayer {
 				try {
 					await this.#sink?.end();
 				} catch {}
-				if (this.#proc) {
+				const proc = this.#proc;
+				let exitCode: number | null = null;
+				if (proc) {
 					try {
-						await this.#proc.exited;
+						exitCode = await proc.exited;
 					} catch {}
 				}
+				// A streaming backend that exits nonzero never opened its audio
+				// device (e.g. the bundled ffmpeg built without pulse/alsa output).
+				// For a short single-segment clip the pipe write succeeds before
+				// that death and #inputClosed is already set, so neither the
+				// broken-pipe replay nor the early-exit handler advances backends.
+				// Replay the buffered utterance through per-file playback so it
+				// still reaches the speakers.
+				if (!this.#stopped && proc && exitCode !== 0) {
+					this.#mode = "file";
+					for (const chunk of this.#played) {
+						if (this.#stopped) break;
+						await this.#playFile(chunk);
+					}
+				}
 			}
 		} catch (error) {
 			logger.debug("tts: streaming player drain failed", {
@@ -291,7 +349,7 @@ export class StreamingAudioPlayer {
 		const wavPath = path.join(os.tmpdir(), `omp-speech-${Snowflake.next()}.wav`);
 		try {
 			await fs.writeFile(wavPath, encodeWav(this.#scaled(pcm), this.#sampleRate));
-			if (!this.#stopped) await playAudioFile(wavPath, { signal: this.#abortController.signal });
+			if (!this.#stopped) await this.#playAudio(wavPath, this.#abortController.signal);
 		} catch (error) {
 			logger.debug("tts: file playback failed", {
 				error: error instanceof Error ? error.message : String(error),

package/src/tts/vocalizer.ts

@@ -100,6 +100,8 @@ export class Vocalizer {
 	#chain: Promise<void> = Promise.resolve();
 	/** Whether the user is currently speaking; new sessions open ducked. */
 	#ducked = false;
+	/** Active scopes that suppress local TTS while another speech surface owns audio. */
+	#suspensions = 0;
 	/** Available rewrite slots; blocks queue when exhausted. */
 	#rewriteSlots = MAX_REWRITES_IN_FLIGHT;
 	#slotWaiters: Array<() => void> = [];
@@ -114,6 +116,21 @@ export class Vocalizer {
 		this.#enhancer = enhancer;
 	}
 
+	/**
+	 * Suppress new vocalization until the returned idempotent release function runs.
+	 * Existing synthesis and playback stop immediately; nested scopes release independently.
+	 */
+	suspend(): () => void {
+		this.#suspensions += 1;
+		this.clear();
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.#suspensions = Math.max(0, this.#suspensions - 1);
+		};
+	}
+
 	/**
 	 * Stream a delta of assistant text into the pipeline. No-op when
 	 * vocalization is disabled. The synthesis session (worker, player) is only
@@ -123,7 +140,7 @@ export class Vocalizer {
 	 * pipeline (enhanced vs mechanical) is latched per utterance.
 	 */
 	pushDelta(text: string): void {
-		if (!settings.get("speech.enabled")) return;
+		if (this.#suspensions > 0 || !settings.get("speech.enabled")) return;
 		if (!text) return;
 		if (this.#enhanced || (!this.#speakable && this.#enhancer && settings.get("speech.enhanced"))) {
 			this.#pushEnhanced(text);