gentle-pi 4.2.0 → 4.4.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/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

@@ -119,7 +119,8 @@ export interface NativeReviewCli {
 	// Read-only risk assessment (gentle-ai#4295, landing in parallel with
 	// gentle-pi#662). Same plain-versioned shape as reviewMode/reviewStatus:
 	// an older binary without the verb, or any other process/decode failure,
-	// rejects the returned promise -- callers fail closed to `high` risk.
+	// rejects the returned promise -- callers report the tier as `unassessable`, which informs
+	// the verification plan but never adds an independent verifier by itself.
 	assess?(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1>;
 }
 
@@ -201,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([
@@ -1082,6 +1083,20 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// b04b6b75d1a446c942a816fbf92932d16f8c3d3001f93159dee2a92bbf2ebe44.
 	// No new negotiated capability identity is asserted.
 	"4.1.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 }),
+	// v4.2.0 repeats 4.1.1: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2. The provider contract moved
+	// from 1.3.0 to 1.4.0 (routing/pi.md, gentle-ai#5536), with published
+	// tarball SHA-256
+	// 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();

package/lib/notification-pulse-worker.ts

@@ -3,8 +3,18 @@
  * owned Node child (`node --experimental-strip-types --max-old-space-size=32`)
  * and speaks a single bounded JSON envelope on stdout:
  *   probe -> { schema, ok, available, formats }
- *   play  -> { schema, ok, played }
- * Failures are private: a generic `{ schema, ok:false }` and a nonzero exit.
+ * Serve protocol (persistent mode): line-delimited JSON requests on stdin,
+ *   `{ schema, op: "play", path }`, answered by one bounded
+ *   `{ schema, ok, played }` envelope per play on stdout. Requests carry a
+ *   snapshot PATH reference, not inline bytes: the worker re-reads the owner's
+ *   private snapshot with the same bounded nofollow `readSnapshot()` on every
+ *   play, so the fail-closed validation of snapshots is preserved verbatim and
+ *   no audio bytes ever cross the stdio channel (request lines stay tiny and
+ *   bounded). Protocol violations crash the worker with a nonzero exit and the
+ *   owner respawns it on the next play; stdin EOF (owner death) exits cleanly
+ *   and an idle worker self-retires, so teardown needs no owner round trip.
+ * Failures are private: a generic `{ schema, ok:false }` and, for protocol
+ * violations, a nonzero exit.
  * It reads only argv, the environment and the owner-supplied snapshot; no SDK,
  * UI, extension, config-owner, cookie-content logging or OS audio surface.
  */
@@ -15,18 +25,25 @@ import { playPulseWav } from "./notification-pulse-stream.ts";
 
 const SCHEMA = "gentle.audio.pulse/v1";
 const MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+/** Request lines carry only a schema/op/path triple; anything longer is a protocol violation. */
+const MAX_REQUEST_BYTES = 4096;
+/** Bounded request backlog; an overflow is a protocol violation (crash, owner restarts). */
+const MAX_PENDING_REQUESTS = 16;
+/** An idle worker self-retires so one owner process never accumulates workers; unref'd, never busy. */
+const SERVE_IDLE_EXIT_MS = 60000;
 
 function emit(payload: Record<string, unknown>): void {
 	process.stdout.write(`${JSON.stringify({ schema: SCHEMA, ...payload })}\n`);
 }
 
-/** Re-read the trusted owner snapshot with the same bounded nofollow pattern. */
-async function readSnapshot(path: string): Promise<Buffer> {
+/** Re-read the trusted owner snapshot with the same bounded nofollow pattern.
+ *  `buffer` is a caller-owned scratch space so persistent serving never
+ *  reallocates the 2 MiB read window per play; the returned bytes are a copy. */
+async function readSnapshot(path: string, buffer: Buffer): Promise<Buffer> {
 	const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
 	try {
 		const stat = await handle.stat();
 		if (!stat.isFile() || stat.size < 44 || stat.size > MAX_SNAPSHOT_BYTES) throw new Error("invalid snapshot");
-		const buffer = Buffer.alloc(MAX_SNAPSHOT_BYTES + 1);
 		const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
 		if (bytesRead !== stat.size) throw new Error("invalid snapshot");
 		return Buffer.from(buffer.subarray(0, bytesRead));
@@ -35,6 +52,63 @@ async function readSnapshot(path: string): Promise<Buffer> {
 	}
 }
 
+/** Protocol violation: one generic envelope so the waiting owner settles, then a crash. */
+function crash(): never {
+	emit({ ok: false });
+	process.exit(1);
+}
+
+async function serve(): Promise<void> {
+	const buffer = Buffer.alloc(MAX_SNAPSHOT_BYTES + 1);
+	const queue: string[] = [];
+	let running = false;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	const armIdle = () => {
+		clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => { if (queue.length === 0 && !running) process.exit(0); }, SERVE_IDLE_EXIT_MS);
+		idleTimer.unref?.();
+	};
+	const runOne = async (line: string): Promise<void> => {
+		let request: { schema?: unknown; op?: unknown; path?: unknown };
+		try {
+			const parsed: unknown = JSON.parse(line);
+			if (typeof parsed !== "object" || parsed === null) return crash();
+			request = parsed as { schema?: unknown; op?: unknown; path?: unknown };
+		} catch { return crash(); }
+		if (request.schema !== SCHEMA || request.op !== "play" || typeof request.path !== "string" || request.path.length === 0) return crash();
+		try {
+			const bytes = await readSnapshot(request.path, buffer);
+			await playPulseWav(bytes, undefined, { clientOptions: { env: process.env } });
+			emit({ ok: true, played: true });
+		} catch { emit({ ok: false }); } // A private play failure leaves the healthy worker serviceable.
+	};
+	const drain = async (): Promise<void> => {
+		if (running) return;
+		running = true;
+		while (queue.length > 0) { const line = queue.shift()!; armIdle(); await runOne(line); }
+		running = false;
+		armIdle();
+	};
+	process.stdin.setEncoding("utf8");
+	let text = "";
+	process.stdin.on("data", (chunk: string) => {
+		armIdle();
+		text += chunk;
+		for (;;) {
+			const index = text.indexOf("\n");
+			if (index === -1) break;
+			const line = text.slice(0, index);
+			text = text.slice(index + 1);
+			if (line.length > MAX_REQUEST_BYTES || queue.push(line) > MAX_PENDING_REQUESTS) crash();
+		}
+		if (text.length > MAX_REQUEST_BYTES) crash(); // Unterminated request line over the bound.
+		void drain();
+	});
+	process.stdin.on("end", () => process.exit(0));
+	process.stdin.on("error", () => process.exit(1));
+	armIdle();
+}
+
 async function main(): Promise<void> {
 	const mode = process.argv[2];
 	if (mode === "probe") {
@@ -46,21 +120,11 @@ async function main(): Promise<void> {
 		}
 		return;
 	}
-	if (mode === "play") {
-		const snapshot = process.argv[3];
-		if (snapshot === undefined) { emit({ ok: false }); process.exitCode = 1; return; }
-		try {
-			const bytes = await readSnapshot(snapshot);
-			await playPulseWav(bytes, undefined, { clientOptions: { env: process.env } });
-			emit({ ok: true, played: true });
-		} catch {
-			emit({ ok: false });
-			process.exitCode = 1;
-		}
+	if (mode === "serve") {
+		await serve();
 		return;
 	}
-	emit({ ok: false });
-	process.exitCode = 1;
+	crash();
 }
 
 await main();