gentle-pi 4.3.0 → 4.5.0

package/lib/image-attachments.ts

@@ -0,0 +1,150 @@
+import type { ImageContent } from "@earendil-works/pi-ai";
+import { getImageDimensions, type ImageDimensions } from "@earendil-works/pi-tui";
+import type { ClipboardImage } from "./clipboard-image.ts";
+
+// Pasted images live in the draft as atomic `[Image#N]` chips (gentle-shell#2464).
+// The bytes stay in memory: a chip deleted from the draft is never sent, and
+// the chips still in the text become real image attachments on submit.
+//
+// The token has no whitespace on purpose: Pi's word motions, word deletion and
+// word wrap treat any segment containing a space as whitespace unless it is
+// one of Pi's own paste markers, so `[Image #1]` would be skipped and eaten
+// together with the word before it.
+
+export const IMAGE_TOKEN_PATTERN = /\[Image#(\d+)\]/g;
+
+export interface ImageAttachment {
+	id: number;
+	token: string;
+	mimeType: string;
+	byteLength: number;
+	base64: string;
+	dimensions?: ImageDimensions;
+}
+
+export interface SubmittedImages {
+	text: string;
+	images: ImageContent[];
+	/** Chips the active model cannot receive; their tokens become a plain note. */
+	omitted: number;
+}
+
+export interface TextSpan { start: number; end: number }
+
+interface Segment { segment: string; index: number; input: string }
+
+export function imageToken(id: number): string {
+	return `[Image#${id}]`;
+}
+
+export class ImageAttachments {
+	private readonly entries = new Map<number, ImageAttachment>();
+	// Never reset: Pi's prompt history keeps the raw submitted text, so a
+	// reused id would let a recalled `[Image#1]` bind to a different image.
+	private counter = 0;
+
+	get size(): number { return this.entries.size; }
+
+	has(id: number): boolean { return this.entries.has(id); }
+
+	add(image: ClipboardImage): ImageAttachment {
+		const id = ++this.counter;
+		const base64 = Buffer.from(image.bytes).toString("base64");
+		const attachment: ImageAttachment = {
+			id,
+			token: imageToken(id),
+			mimeType: image.mimeType,
+			byteLength: image.bytes.length,
+			base64,
+			dimensions: getImageDimensions(base64, image.mimeType) ?? undefined,
+		};
+		this.entries.set(id, attachment);
+		return attachment;
+	}
+
+	/** Registered chips in the order they appear in `text`, each once. */
+	referenced(text: string): ImageAttachment[] {
+		const seen = new Set<number>();
+		const result: ImageAttachment[] = [];
+		for (const match of text.matchAll(IMAGE_TOKEN_PATTERN)) {
+			const id = Number(match[1]);
+			const attachment = this.entries.get(id);
+			if (!attachment || seen.has(id)) continue;
+			seen.add(id);
+			result.push(attachment);
+		}
+		return result;
+	}
+
+	/**
+	 * Resolve a submitted draft. Returns undefined when it holds no registered
+	 * chip, so ordinary prompts pass through untouched.
+	 *
+	 * Pi can run input handlers after the editor already holds a new draft
+	 * (a prompt queued during compaction), so only chips the current draft
+	 * still shows survive; everything else, sent or deleted, is released.
+	 */
+	submit(text: string, modelAcceptsImages: boolean, currentDraft = ""): SubmittedImages | undefined {
+		const attachments = this.referenced(text);
+		const keep = new Set(this.referenced(currentDraft).map((attachment) => attachment.id));
+		for (const id of [...this.entries.keys()]) if (!keep.has(id)) this.entries.delete(id);
+		if (attachments.length === 0) return undefined;
+		if (modelAcceptsImages) {
+			return { text, images: attachments.map((attachment) => ({ type: "image", data: attachment.base64, mimeType: attachment.mimeType })), omitted: 0 };
+		}
+		const ids = new Set(attachments.map((attachment) => attachment.id));
+		const noted = text.replace(IMAGE_TOKEN_PATTERN, (token, id: string) => ids.has(Number(id)) ? `${token.slice(0, -1)} omitted: the current model does not accept images]` : token);
+		return { text: noted, images: [], omitted: attachments.length };
+	}
+
+	/** Drop every pending image; numbering keeps counting up. */
+	clear(): void {
+		this.entries.clear();
+	}
+
+	/** Character spans of the registered chips in `text`. */
+	spans(text: string): TextSpan[] {
+		if (this.entries.size === 0 || !text.includes("[Image#")) return [];
+		const spans: TextSpan[] = [];
+		for (const match of text.matchAll(IMAGE_TOKEN_PATTERN)) {
+			if (this.entries.has(Number(match[1]))) spans.push({ start: match.index, end: match.index + match[0].length });
+		}
+		return spans;
+	}
+
+	/**
+	 * Merge every registered chip into one segment, so cursor movement, word
+	 * wrap and deletion treat it as a single unit (one Backspace removes it).
+	 * Segments that already span several graphemes, such as Pi's own paste
+	 * markers, pass through unchanged.
+	 */
+	segment(text: string, segments: Iterable<Segment>): Iterable<Segment> {
+		const spans = this.spans(text);
+		if (spans.length === 0) return segments;
+		const merged: Segment[] = [];
+		let span = 0;
+		for (const segment of segments) {
+			while (span < spans.length && spans[span]!.end <= segment.index) span++;
+			const current = spans[span];
+			if (current && segment.index >= current.start && segment.index < current.end) {
+				if (segment.index === current.start) merged.push({ segment: text.slice(current.start, current.end), index: current.start, input: text });
+				continue;
+			}
+			merged.push(segment);
+		}
+		return merged;
+	}
+}
+
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** `png · 1280×720 · 84 KB`: the chip's description when no preview is drawn. */
+export function describeAttachment(attachment: Pick<ImageAttachment, "mimeType" | "byteLength" | "dimensions">): string {
+	const format = attachment.mimeType.replace(/^image\//, "").replace("jpeg", "jpg");
+	const size = attachment.dimensions ? `${attachment.dimensions.widthPx}×${attachment.dimensions.heightPx}` : undefined;
+	return [format, size, formatBytes(attachment.byteLength)].filter(Boolean).join(" · ");
+}

package/lib/inprocess-reviewer.ts

@@ -153,6 +153,36 @@ function isTextContent(part: { type?: unknown }): part is TextContent {
 	return part.type === "text";
 }
 
+/** Completion diagnostics are facts only; never copy provider text, errors, or payloads. */
+function emptyOutputEvidence(model: Model<Api>, assistant: AssistantMessage): Record<string, unknown> {
+	const evidence: Record<string, unknown> = { reviewerModel: `${model.provider}/${model.id}`.slice(0, 512) };
+	if (["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"].includes(assistant.stopReason)) {
+		evidence.stopReason = assistant.stopReason;
+	}
+	const addCounter = (target: Record<string, number>, key: string, value: unknown) => {
+		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) target[key] = value;
+	};
+	const usage: Record<string, number> = {};
+	for (const key of ["input", "output", "reasoning", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+		addCounter(usage, key, assistant.usage?.[key]);
+	}
+	if (Object.keys(usage).length > 0) evidence.usage = usage;
+	const text = assistant.content.filter(isTextContent);
+	const thinking = assistant.content.filter((part) => part.type === "thinking");
+	const content: Record<string, number> = {};
+	addCounter(content, "blocks", assistant.content.length);
+	addCounter(content, "textBlocks", text.length);
+	addCounter(content, "thinkingBlocks", thinking.length);
+	if (text.every((part) => typeof part.text === "string")) {
+		addCounter(content, "textChars", text.reduce((sum, part) => sum + part.text.length, 0));
+	}
+	if (thinking.every((part) => typeof part.thinking === "string")) {
+		addCounter(content, "thinkingChars", thinking.reduce((sum, part) => sum + part.thinking.length, 0));
+	}
+	evidence.content = content;
+	return evidence;
+}
+
 /**
  * Mirrors pi's main-loop OpenCode attribution condition exactly
  * (core/provider-attribution.js#getSessionHeaders): the model's provider is
@@ -329,10 +359,11 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 
 	const text = assistant.content.filter(isTextContent).map((part) => part.text).join("");
 	if (text.length === 0) {
+		const evidence = emptyOutputEvidence(model, assistant);
 		return refuse(
 			INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT,
-			`Reviewer produced no text for ${request.routingKey} (stopReason: ${assistant.stopReason}).`,
-			{ stopReason: assistant.stopReason, ...(assistant.errorMessage === undefined ? {} : { errorMessage: assistant.errorMessage }) },
+			`Reviewer produced no text for ${request.routingKey} (stopReason: ${evidence.stopReason ?? "unknown"}).`,
+			evidence,
 		);
 	}
 

package/lib/jobs-sidebar-state.ts

@@ -2,10 +2,23 @@
 export const JOBS_SIDEBAR_EVENT = "gentle-ai:jobs-sidebar";
 export const JOBS_STATUS_KEY = "gentle-jobs";
 
+const COLLAPSE_KEY_DEFAULT = "ctrl+shift+j";
+
+export function jobsCollapseKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_JOBS_KEY?.trim();
+	if (value === undefined) return COLLAPSE_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}
+
 export interface RunningJobDisplay {
 	id: string;
 	label: string;
 	startedAt: number;
+	// Finished-tail fields; optional so older publishers that only list running
+	// jobs keep validating (the Agents-card pattern: results linger briefly).
+	status?: "exited" | "stopped" | "failed";
+	endedAt?: number;
+	exitCode?: number | null;
 }
 
 export interface JobsSidebarSnapshot {
@@ -14,7 +27,13 @@ export interface JobsSidebarSnapshot {
 
 export function isJobsSidebarSnapshot(value: unknown): value is JobsSidebarSnapshot {
 	if (!value || typeof value !== "object" || !Array.isArray((value as JobsSidebarSnapshot).jobs)) return false;
-	return (value as JobsSidebarSnapshot).jobs.every((job) => job && typeof job === "object" &&
-		typeof job.id === "string" && job.id.length > 0 && typeof job.label === "string" &&
-		typeof job.startedAt === "number" && Number.isFinite(job.startedAt));
+	return (value as JobsSidebarSnapshot).jobs.every((job) => {
+		if (!job || typeof job !== "object") return false;
+		if (typeof job.id !== "string" || job.id.length === 0 || typeof job.label !== "string") return false;
+		if (typeof job.startedAt !== "number" || !Number.isFinite(job.startedAt)) return false;
+		if (job.status !== undefined && job.status !== "exited" && job.status !== "stopped" && job.status !== "failed") return false;
+		if (job.endedAt !== undefined && (typeof job.endedAt !== "number" || !Number.isFinite(job.endedAt))) return false;
+		if (job.exitCode !== undefined && typeof job.exitCode !== "number" && job.exitCode !== null) return false;
+		return true;
+	});
 }

package/lib/jobs-widget.ts

@@ -0,0 +1,112 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { JOB_GLYPH, formatJobDuration } from "./background-jobs-tools.ts";
+import type { RunningJobDisplay } from "./jobs-sidebar-state.ts";
+import { paintHoverable } from "./shell-hover.ts";
+import { CARD_TONE, panelInnerWidth, renderCard, type CardTheme, type CardTone } from "./shell-card.ts";
+import { sanitizeTerminalText } from "./terminal-theme.ts";
+
+// Gentle Jobs widget: the sidebar card for this session's background jobs.
+// Reads the running-job display snapshot only (id, label, startedAt), the same
+// data the Status card used to print, so drawing it costs nothing per event.
+// One row per job: glyph, label, elapsed right-aligned. Jobs are transient —
+// the card paints nothing while no job runs, and the overlay (/gentle:jobs)
+// stays the full view with stop controls and output tails.
+
+export const JOBS_GLYPH = JOB_GLYPH;
+
+// Finished jobs linger like the Agents card's results: newest 3 for a minute,
+// so an exit is visible long enough to read before the card empties itself.
+export const JOBS_FINISHED_TTL_MS = 60_000;
+const MAX_FINISHED = 3;
+
+export interface JobsWidgetOptions {
+	collapsed: boolean;
+	collapseKey?: string;
+	// Paint the clickable "▾ Collapse" / "▸ Expand" control in the header, the
+	// same control the Agents and Todos cards carry.
+	collapseControl?: boolean;
+	hovered?: boolean;
+}
+
+const GLYPH_ROLE = "accent";
+const NAME_ROLE = "text";
+const META_ROLE = "dim";
+const GLYPH_GAP = "  ";
+const ELLIPSIS = "…";
+
+// Running jobs newest first, matching the /gentle:jobs running group and the
+// old Status group this card replaces; finished tails follow, newest first.
+export function widgetJobs(jobs: readonly RunningJobDisplay[], now: number): RunningJobDisplay[] {
+	const running = jobs.filter((job) => job.status === undefined).sort((a, b) => b.startedAt - a.startedAt);
+	const finished = jobs.filter((job) => job.status !== undefined && now - (job.endedAt ?? 0) < JOBS_FINISHED_TTL_MS)
+		.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0)).slice(0, MAX_FINISHED);
+	return [...running, ...finished];
+}
+
+function clean(text: string): string {
+	return sanitizeTerminalText(text).replace(/\s+/g, " ");
+}
+
+function clip(text: string, width: number): string {
+	if (width <= 0) return "";
+	if (visibleWidth(text) <= width) return text;
+	// Plain clip, mirroring the status bar: pi's truncateToWidth wraps the
+	// result in resets, which would end up inside a painted segment.
+	let clipped = "";
+	for (const char of text) {
+		if (visibleWidth(clipped + char) > width - 1) break;
+		clipped += char;
+	}
+	return `${clipped}${ELLIPSIS}`;
+}
+
+// The /gentle:jobs glyph roles: running keeps the spinner, exits mirror the
+// overlay's outcome marks.
+function glyph(job: RunningJobDisplay): [string, string] {
+	if (job.status === "stopped") return ["–", "dim"];
+	if (job.status === "failed") return ["✗", "error"];
+	if (job.status === "exited") return job.exitCode === 0 ? ["✓", "success"] : ["✗", "error"];
+	return [JOBS_GLYPH, GLYPH_ROLE];
+}
+
+function counts(jobs: readonly RunningJobDisplay[]): string {
+	const running = jobs.filter((job) => job.status === undefined).length;
+	const finished = jobs.length - running;
+	const parts: string[] = [];
+	if (running > 0) parts.push(running === 1 ? "1 running" : `${running} running`);
+	if (finished > 0) parts.push(finished === 1 ? "1 finished" : `${finished} finished`);
+	return parts.join(" · ");
+}
+
+/** The tone the card paints, so a host can locate its header row. */
+export function jobsCardTone(_jobs: readonly RunningJobDisplay[]): CardTone {
+	return CARD_TONE.INFO;
+}
+
+export function renderJobsCard(jobs: readonly RunningJobDisplay[], theme: CardTheme, width: number, now: number, options: JobsWidgetOptions): string[] {
+	const shown = widgetJobs(jobs, now);
+	if (shown.length === 0) return [];
+	const tone = jobsCardTone(shown);
+	const inner = panelInnerWidth(theme, width, tone);
+	const listed = options.collapsed ? [shown[0]!] : shown;
+	const body = listed.map((job) => {
+		// A finished row freezes its elapsed at the end; a running one ticks.
+		const [mark, role] = glyph(job);
+		const elapsed = formatJobDuration(Math.max(0, (job.status === undefined ? now : job.endedAt ?? now) - job.startedAt));
+		const label = clip(clean(job.label), Math.max(0, inner - visibleWidth(elapsed) - GLYPH_GAP.length - 1));
+		const head = `${theme.fg(role, mark)}${GLYPH_GAP}${theme.fg(NAME_ROLE, label)}`;
+		const tail = theme.fg(META_ROLE, " ".repeat(Math.max(1, inner - visibleWidth(head) - visibleWidth(elapsed))) + elapsed);
+		return `${head}${tail}`;
+	});
+	if (options.collapsed && shown.length > 1) body.push(theme.fg(META_ROLE, `${ELLIPSIS} ${shown.length - 1} more`));
+	const icon = options.collapsed ? "▸" : "▾";
+	const control = `${icon} ${width >= 28 ? (options.collapsed ? "Expand" : "Collapse") : ""}`.trimEnd();
+	const title = options.collapseControl ? `Jobs ${paintHoverable(theme, control, options.hovered ?? false, "accent")}` : "Jobs";
+	const hint = options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : undefined;
+	return renderCard(
+		{ title, subtitle: counts(shown), body, tone, glyph: JOBS_GLYPH },
+		theme,
+		width,
+		{ expanded: true, hint, panel: true },
+	);
+}

package/lib/nan-provider.ts

@@ -57,6 +57,8 @@ const CHAT_MODELS: NanChatModelConfig[] = ([
 	{
 		id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", input: ["text", "image"], contextWindow: 1_000_000,
 		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP, maxTokens: 16_384,
+		// NaN's DeepSeek route enforces this field, not max_completion_tokens.
+		compat: { maxTokensField: "max_tokens" },
 	},
 	{
 		id: "glm5.3-flash", name: "GLM 5.3 Flash", input: ["text", "image"], contextWindow: 1_000_000,
@@ -96,6 +98,7 @@ function cloneModel(model: NanChatModelConfig): NanChatModelConfig {
 		input: [...model.input],
 		cost: { ...model.cost },
 		thinkingLevelMap: model.thinkingLevelMap ? { ...model.thinkingLevelMap } : undefined,
+		...(model.compat ? { compat: { ...model.compat } } : {}),
 	};
 }
 

package/lib/native-review-cli.ts

@@ -202,10 +202,10 @@ export interface NativeReviewModeResult {
 // stream while still succeeding. That last qualifier is what keeps this list
 // honest: v2.4.0 deleted reviewConsentSkippedDefaultProvenance ("Reviews are
 // on by default; this was never explicitly chosen. ..."), which used to ride
-// with the skip notice whenever the resolved mode source was `default`. Under
-// opt-in receipt-driven development a default-source clone is refused long
-// before the consent ceremony runs, so the pinned binary can no longer emit
-// that line and it is removed here rather than left as dead tolerance. Multi-
+// with the skip notice whenever the resolved mode source was `default`. Reviews
+// are on by default again since gentle-ai v4.0.0, but the pinned binary no
+// longer has that function and cannot emit the line, so it is removed here
+// rather than left as dead tolerance. Multi-
 // line stderr is still expected in principle — these are separate Fprintln
 // calls, never one joined string — which is why membership is per line.
 export const REVIEW_CONSENT_NOTICES = Object.freeze([
@@ -1090,6 +1090,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b.
 	// No new negotiated capability identity is asserted.
 	"4.2.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.3.1 repeats 4.2.0: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2, and the provider contract
+	// stays at 1.4.0, with published tarball SHA-256
+	// 58450471280aeb357443d6a28c819132d8c8eb78dd25b12bac64296b2f8c27c2.
+	// The v4.3.0 tag has no release and is never pinned.
+	// No new negotiated capability identity is asserted.
+	"4.3.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {

package/lib/notification-audio-native.ts

@@ -8,6 +8,14 @@
  * worker as a Node child with fixed literal flags and a scrubbed environment.
  * Linux only; macOS/Windows never spawn. No real audio, no real Pulse stream
  * beyond the worker's own fake-test sockets; there is no physical-playback claim.
+ *
+ * Playback persistence: plays share ONE long-lived `serve` worker per bridge
+ * instance (line-delimited JSON over stdin, one bounded envelope per play).
+ * A crashed worker is replaced by a fresh spawn on the next play; abort,
+ * timeout, a malformed serve line and `dispose()` all SIGKILL it once and
+ * settle only on `close`. Requests are serialized through the worker with a
+ * bounded pending queue. Teardown is the owner's `dispose()` (session shutdown),
+ * plus the worker's own stdin-EOF exit when the owner process dies.
  */
 import { spawn } from "node:child_process";
 import type { EventEmitter } from "node:events";
@@ -21,18 +29,21 @@ const MAX_STDERR = 4096;
 const DEFAULT_PROBE_TIMEOUT_MS = 1200;
 /** 10 s maximum validated duration plus a 1 s termination margin; must outlive every accepted sound. */
 const DEFAULT_PLAY_TIMEOUT_MS = 11000;
+/** Bounded pending plays per serve worker (1 active + queue), mirroring the repo's small caps. */
+const MAX_PENDING_PLAYS = 8;
 
 export interface NativePulseProbeResult { readonly available: boolean; readonly formats: readonly ("wav")[]; }
 export interface NativePulseSpawnOptions {
 	readonly shell: false;
 	readonly windowsHide: true;
 	readonly detached: false;
-	readonly stdio: readonly ["ignore", "pipe", "pipe"];
+	readonly stdio: readonly ("ignore" | "pipe")[];
 	readonly env: NodeJS.ProcessEnv;
 }
 export interface NativePulseChild {
 	stdout: EventEmitter | null;
 	stderr: EventEmitter | null;
+	stdin: { write(chunk: string): boolean } | null;
 	kill(signal: string): boolean;
 	once(event: string, listener: (...args: unknown[]) => void): EventEmitter;
 }
@@ -49,6 +60,25 @@ export interface NativePulseOptions {
 
 interface Envelope { schema?: unknown; ok?: unknown; available?: unknown; formats?: unknown; played?: unknown; }
 interface RunResult { readonly stdout: string; readonly stderr: string; readonly aborted: boolean; readonly timedOut: boolean; }
+/** One queued/active play through the persistent serve worker. */
+interface ServeRequest {
+	readonly snapshot: string;
+	readonly signal: AbortSignal | undefined;
+	readonly resolve: () => void;
+	readonly reject: (error: Error) => void;
+	timer?: ReturnType<typeof setTimeout> | number;
+	onAbort?: () => void;
+	aborted: boolean;
+	timedOut: boolean;
+	settled: boolean;
+}
+interface ServeWorker {
+	readonly child: NativePulseChild;
+	line: string;
+	active?: ServeRequest;
+	readonly queued: ServeRequest[];
+	dead: boolean;
+}
 
 /** Distinct from other native failures so the owner can treat a false permit as "not started". */
 export class NativePulseNotPermittedError extends Error {
@@ -58,9 +88,8 @@ export class NativePulseNotPermittedError extends Error {
 function unrefTimer(handle: ReturnType<typeof setTimeout> | number): void { (handle as { unref?: () => void }).unref?.(); }
 function abortError(): Error { const error = new Error("Native pulse: aborted"); error.name = "AbortError"; return error; }
 function defaultSpawn(executable: string, args: string[], options: NativePulseSpawnOptions): NativePulseChild {
-	const stdio: ("ignore" | "pipe")[] = ["ignore", "pipe", "pipe"];
-	// SAFETY: Node's ChildProcess exposes stdout/stderr/once/kill compatible with the narrower NativePulseChild interface; the cast only bridges that structural narrowing.
-	return spawn(executable, args, { ...options, stdio }) as unknown as NativePulseChild;
+	// SAFETY: Node's ChildProcess exposes stdout/stderr/stdin/once/kill compatible with the narrower NativePulseChild interface; the cast only bridges that structural narrowing.
+	return spawn(executable, args, { ...options, stdio: [...options.stdio] }) as unknown as NativePulseChild;
 }
 function parseEnvelope(stdout: string): Envelope | undefined {
 	const text = stdout.trim();
@@ -78,6 +107,7 @@ export class NativePulsePlayer {
 	private readonly setTimer: NonNullable<NativePulseOptions["setTimeout"]>;
 	private readonly clearTimer: NonNullable<NativePulseOptions["clearTimeout"]>;
 	private formats: readonly ("wav")[] = [];
+	private worker?: ServeWorker;
 
 	constructor(options: NativePulseOptions = {}) {
 		this.options = { ...options };
@@ -107,10 +137,9 @@ export class NativePulsePlayer {
 	}
 
 	/** Spawns synchronously; resolves ONLY on the child `close` event (never exit/error/kill). */
-	private run(mode: "probe" | "play", snapshot: string | undefined, signal: AbortSignal | undefined, timeoutMs: number): Promise<RunResult> {
+	private run(signal: AbortSignal | undefined, timeoutMs: number): Promise<RunResult> {
 		return new Promise<RunResult>(resolve => {
-			const args = [...FIXED_NODE_FLAGS, this.workerPath(), mode];
-			if (snapshot !== undefined) args.push(snapshot);
+			const args = [...FIXED_NODE_FLAGS, this.workerPath(), "probe"];
 			const child = (this.options.spawn ?? defaultSpawn)(process.execPath, args, {
 				shell: false, windowsHide: true, detached: false, stdio: ["ignore", "pipe", "pipe"], env: this.childEnv(),
 			});
@@ -142,21 +171,128 @@ export class NativePulsePlayer {
 	/** Offline/malformed/unsupported probe resolves unavailable; it never throws private IPC. */
 	async probe(signal?: AbortSignal): Promise<NativePulseProbeResult> {
 		if (!this.supportsTarget() || signal?.aborted) { this.formats = []; return { available: false, formats: [] }; }
-		const result = await this.run("probe", undefined, signal, this.options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
+		const result = await this.run(signal, this.options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
 		const parsed = result.aborted || result.timedOut ? { available: false, formats: [] as const } : this.parseProbe(result.stdout);
 		this.formats = parsed.available ? ["wav"] : [];
 		return parsed;
 	}
 
-	/** `gate` (permit or predicate) runs synchronously before spawn; false means no child at all. */
+	/** Spawns or reuses the persistent `serve` worker. A dead worker is replaced by a fresh spawn. */
+	private ensureWorker(): ServeWorker {
+		if (this.worker && !this.worker.dead) return this.worker;
+		const child = (this.options.spawn ?? defaultSpawn)(process.execPath, [...FIXED_NODE_FLAGS, this.workerPath(), "serve"], {
+			shell: false, windowsHide: true, detached: false, stdio: ["pipe", "pipe", "pipe"], env: this.childEnv(),
+		});
+		const worker: ServeWorker = { child, line: "", queued: [], dead: false };
+		this.worker = worker;
+		child.stdout?.on("data", chunk => this.onServeStdout(worker, chunk));
+		child.stderr?.on("data", () => { /* drained: a full stderr pipe must never stall the worker */ });
+		child.once("close", () => this.closeWorker(worker));
+		child.once("error", () => { /* Node emits close after spawn errors; keep waiting */ });
+		return worker;
+	}
+
+	private armGuards(request: ServeRequest): void {
+		const timer = this.setTimer(() => { request.timedOut = true; this.killWorker(); },
+			this.options.playTimeoutMs ?? DEFAULT_PLAY_TIMEOUT_MS);
+		unrefTimer(timer);
+		request.timer = timer;
+		request.onAbort = () => { request.aborted = true; this.killWorker(); };
+		request.signal?.addEventListener("abort", request.onAbort, { once: true });
+		if (request.signal?.aborted) request.onAbort();
+	}
+
+	private settleSuccess(request: ServeRequest): void {
+		if (request.settled) return;
+		request.settled = true;
+		if (request.timer !== undefined) this.clearTimer(request.timer);
+		if (request.onAbort) request.signal?.removeEventListener("abort", request.onAbort);
+		request.resolve();
+	}
+
+	/** Private failure: aborted requests reject with the abort error, everything else with the generic one. */
+	private settleFailure(request: ServeRequest): void {
+		if (request.settled) return;
+		request.settled = true;
+		if (request.timer !== undefined) this.clearTimer(request.timer);
+		if (request.onAbort) request.signal?.removeEventListener("abort", request.onAbort);
+		request.reject(request.aborted ? abortError() : new Error("Native pulse playback failed"));
+	}
+
+	/** SIGKILL once; the pending plays settle on the child `close` event (never exit/error/kill). */
+	private killWorker(): void {
+		const worker = this.worker;
+		if (!worker || worker.dead) return;
+		worker.dead = true;
+		try { worker.child.kill("SIGKILL"); } catch { /* close still settles every pending play */ }
+	}
+
+	private closeWorker(worker: ServeWorker): void {
+		worker.dead = true;
+		if (this.worker === worker) this.worker = undefined;
+		for (const request of [worker.active, ...worker.queued]) if (request) this.settleFailure(request);
+		worker.active = undefined;
+		worker.queued.length = 0;
+	}
+
+	private dispatch(worker: ServeWorker, request: ServeRequest): void {
+		if (worker.dead) { this.settleFailure(request); return; }
+		worker.active = request;
+		const stdin = worker.child.stdin;
+		if (!stdin) { this.killWorker(); return; }
+		try { stdin.write(`${JSON.stringify({ schema: NATIVE_PULSE_SCHEMA, op: "play", path: request.snapshot })}\n`); }
+		catch { this.killWorker(); }
+	}
+
+	private onServeStdout(worker: ServeWorker, chunk: unknown): void {
+		worker.line += String(chunk);
+		for (;;) {
+			const index = worker.line.indexOf("\n");
+			if (index === -1) break;
+			const line = worker.line.slice(0, index);
+			worker.line = worker.line.slice(index + 1);
+			const envelope = parseEnvelope(line);
+			if (!envelope) { this.killWorker(); return; } // Protocol violation: `close` settles every pending play.
+			const request = worker.active;
+			worker.active = undefined;
+			if (envelope.ok === true && envelope.played === true) { if (request) this.settleSuccess(request); }
+			else if (request) this.settleFailure(request); // A private ok:false leaves the worker serviceable.
+			const next = worker.queued.shift();
+			if (next) this.dispatch(worker, next);
+		}
+		if (worker.line.length > MAX_STDOUT) this.killWorker(); // Unterminated envelope line over the bound.
+	}
+
+	/** `gate` (permit or predicate) runs synchronously before any spawn/write; false means no child at all.
+	 *  Plays serialize through one persistent worker; extras wait in a bounded queue. */
 	async play(snapshot: string, signal?: AbortSignal, gate?: (() => boolean) | { permit(): boolean }): Promise<void> {
 		if (!this.supportsTarget()) throw new Error("Native pulse: unsupported platform");
 		if (signal?.aborted) throw abortError();
 		const permitted = typeof gate === "function" ? gate() : gate?.permit();
 		if (permitted === false) throw new NativePulseNotPermittedError();
-		const result = await this.run("play", snapshot, signal, this.options.playTimeoutMs ?? DEFAULT_PLAY_TIMEOUT_MS);
-		if (result.aborted) throw abortError();
-		const envelope = parseEnvelope(result.stdout);
-		if (result.timedOut || !envelope || envelope.ok !== true || envelope.played !== true) throw new Error("Native pulse playback failed");
+		return new Promise<void>((resolve, reject) => {
+			const worker = this.ensureWorker();
+			const request: ServeRequest = { snapshot, signal, resolve, reject, aborted: false, timedOut: false, settled: false };
+			if (worker.active) {
+				if (worker.queued.length >= MAX_PENDING_PLAYS) { reject(new Error("Native pulse: too many pending plays")); return; }
+				this.armGuards(request);
+				worker.queued.push(request);
+				return;
+			}
+			this.armGuards(request);
+			this.dispatch(worker, request);
+		});
+	}
+
+	/** Owner teardown: SIGKILL the persistent worker once and settle every pending play. */
+	dispose(): void {
+		const worker = this.worker;
+		this.worker = undefined;
+		if (!worker) return;
+		worker.dead = true;
+		try { worker.child.kill("SIGKILL"); } catch { /* the child is already gone */ }
+		for (const request of [worker.active, ...worker.queued]) if (request) this.settleFailure(request);
+		worker.active = undefined;
+		worker.queued.length = 0;
 	}
 }

package/lib/notification-audio.ts

@@ -157,6 +157,8 @@ export interface NativeAudioBackend {
 	probe(signal?: AbortSignal): Promise<{ available: boolean; formats: readonly NotificationAudioFormat[] }>;
 	getNativeFormats(): readonly NotificationAudioFormat[];
 	play(snapshot: string, signal?: AbortSignal, gate?: (() => boolean) | { permit(): boolean }): Promise<void>;
+	/** Optional owner teardown: a persistent native worker (Linux pulse) kills its child. */
+	dispose?(): void;
 }
 interface DiscoveredSystem { executable: string; formats: readonly NotificationAudioFormat[]; }
 interface Discovery { native: readonly NotificationAudioFormat[]; system?: DiscoveredSystem; }
@@ -240,6 +242,8 @@ export class NotificationPlayer {
 		}
 		return undefined;
 	}
+	/** Owner teardown: disposes the native backend, killing a persistent worker if one exists. */
+	dispose(): void { this.native.dispose?.(); }
 	async play(sound: Exclude<NotificationSound, null>, signal: AbortSignal, permit: PlaybackPermit): Promise<void> {
 		if (signal.aborted) return;
 		const discovered = await this.discover();