gentle-pi 3.7.0 → 4.1.0

package/lib/notification-pulse-protocol.ts

@@ -0,0 +1,305 @@
+/**
+ * Minimal PulseAudio native-protocol v13 codec: tagstruct primitives plus the
+ * 20-byte pstream frame descriptor. This is an original MIT (repo-licensed)
+ * implementation derived only from the official protocol declaration; no
+ * PulseAudio/LGPL implementation code is copied.
+ *
+ * Protocol reference (read-only, PulseAudio v17.0):
+ *   PROTOCOL; src/pulsecore/native-common.h; src/pulsecore/tagstruct.[ch];
+ *   src/pulsecore/pstream.[ch]; src/pulse/sample.h.
+ *
+ * Pure module: no sockets, no cookies, no clocks, no process, no backend IO.
+ */
+export const NATIVE_PROTOCOL_VERSION = 13;
+export const CONTROL_CHANNEL = 0xffffffff;
+export const MAX_CONTROL_PAYLOAD = 64 * 1024;
+export const MAX_FRAMES_PER_PUSH = 32;
+export const PULSE_FRAME_HEADER_SIZE = 20;
+
+/** Command values are the C enum order of native-common.h (the enum is the wire value). */
+export const PulseCommand = {
+	ERROR: 0, TIMEOUT: 1, REPLY: 2, CREATE_PLAYBACK_STREAM: 3, DELETE_PLAYBACK_STREAM: 4,
+	AUTH: 8, SET_CLIENT_NAME: 9, DRAIN_PLAYBACK_STREAM: 12, GET_SERVER_INFO: 20, REQUEST: 61,
+} as const;
+export type PulseCommand = (typeof PulseCommand)[keyof typeof PulseCommand];
+
+/** Sample format values from sample.h. S24LE/S24BE are packed 24-bit; S24_32* are not. */
+export const PulseSampleFormat = {
+	U8: 0, ALAW: 1, ULAW: 2, S16LE: 3, S16BE: 4, FLOAT32LE: 5, FLOAT32BE: 6,
+	S32LE: 7, S32BE: 8, S24LE: 9, S24BE: 10, S24_32LE: 11, S24_32BE: 12,
+} as const;
+
+export interface PulseSampleSpec { readonly format: number; readonly channels: number; readonly rate: number; }
+export interface PulseFrame {
+	readonly channel: number;
+	readonly offset: bigint;
+	readonly flags: number;
+	readonly payload: Buffer;
+}
+
+const TAG_STRING = 0x74; // 't'
+const TAG_STRING_NULL = 0x4e; // 'N'
+const TAG_U32 = 0x4c; // 'L'
+const TAG_U8 = 0x42; // 'B'
+const TAG_ARBITRARY = 0x78; // 'x'
+const TAG_BOOLEAN_TRUE = 0x31; // '1'
+const TAG_BOOLEAN_FALSE = 0x30; // '0'
+const TAG_USEC = 0x55; // 'U'
+const TAG_SAMPLE_SPEC = 0x61; // 'a'
+const TAG_CHANNEL_MAP = 0x6d; // 'm'
+const TAG_CVOLUME = 0x76; // 'v'
+const TAG_PROPLIST = 0x50; // 'P'
+const NUL = Buffer.from([0]);
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+/** Generic, data-free failure: never echoes field values or cookie/key contents. */
+function fail(message: string): never { throw new Error(`Pulse protocol: ${message}`); }
+
+function appendU32(target: Buffer, value: number, offset: number): void { target.writeUInt32BE(value, offset); }
+
+/** Bounded chainable tagstruct writer. */
+export class PulseTagWriter {
+	private readonly chunks: Buffer[] = [];
+	private size = 0;
+
+	private append(chunk: Buffer): this {
+		if (this.size + chunk.length > MAX_CONTROL_PAYLOAD) fail("tag payload too large");
+		this.size += chunk.length;
+		this.chunks.push(chunk);
+		return this;
+	}
+
+	u32(value: number): this {
+		if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) fail("u32 out of range");
+		const head = Buffer.allocUnsafe(5);
+		head[0] = TAG_U32;
+		appendU32(head, value, 1);
+		return this.append(head);
+	}
+
+	u8(value: number): this {
+		if (!Number.isInteger(value) || value < 0 || value > 0xff) fail("u8 out of range");
+		return this.append(Buffer.from([TAG_U8, value]));
+	}
+
+	string(value: string | null): this {
+		if (value === null) return this.append(Buffer.from([TAG_STRING_NULL]));
+		if (typeof value !== "string" || value.includes("\0")) fail("invalid string");
+		return this.append(Buffer.concat([Buffer.from([TAG_STRING]), Buffer.from(value, "utf8"), NUL]));
+	}
+
+	arbitrary(value: Uint8Array): this {
+		if (!(value instanceof Uint8Array) || value.length > MAX_CONTROL_PAYLOAD) fail("arbitrary out of range");
+		const head = Buffer.allocUnsafe(5);
+		head[0] = TAG_ARBITRARY;
+		appendU32(head, value.length, 1);
+		return this.append(head).append(Buffer.from(value.buffer, value.byteOffset, value.length));
+	}
+
+	boolean(value: boolean): this {
+		if (typeof value !== "boolean") fail("invalid boolean");
+		return this.append(Buffer.from([value ? TAG_BOOLEAN_TRUE : TAG_BOOLEAN_FALSE]));
+	}
+
+	usec(value: bigint): this {
+		if (typeof value !== "bigint" || value < 0n || value > 0xffffffffffffffffn) fail("usec out of range");
+		const head = Buffer.allocUnsafe(9);
+		head[0] = TAG_USEC;
+		head.writeBigUInt64BE(value, 1);
+		return this.append(head);
+	}
+
+	sampleSpec(spec: PulseSampleSpec): this {
+		if (!spec || !Number.isInteger(spec.format) || spec.format < 0 || spec.format > 0xff) fail("invalid sample format");
+		if (!Number.isInteger(spec.channels) || spec.channels < 1 || spec.channels > 0xff) fail("invalid sample channels");
+		if (!Number.isInteger(spec.rate) || spec.rate < 0 || spec.rate > 0xffffffff) fail("invalid sample rate");
+		const body = Buffer.allocUnsafe(7);
+		body[0] = TAG_SAMPLE_SPEC;
+		body[1] = spec.format;
+		body[2] = spec.channels;
+		appendU32(body, spec.rate, 3);
+		return this.append(body);
+	}
+
+	channelMap(positions: readonly number[]): this {
+		if (!Array.isArray(positions) || positions.length < 1 || positions.length > 0xff
+			|| !positions.every(position => Number.isInteger(position) && position >= 0 && position <= 0xff))
+			fail("invalid channel map");
+		return this.append(Buffer.from([TAG_CHANNEL_MAP, positions.length, ...positions]));
+	}
+
+	cvolume(volumes: readonly number[]): this {
+		if (!Array.isArray(volumes) || volumes.length < 1 || volumes.length > 0xff
+			|| !volumes.every(volume => Number.isInteger(volume) && volume >= 0 && volume <= 0xffffffff))
+			fail("invalid cvolume");
+		const body = Buffer.allocUnsafe(2 + volumes.length * 4);
+		body[0] = TAG_CVOLUME;
+		body[1] = volumes.length;
+		volumes.forEach((volume, index) => appendU32(body, volume, 2 + index * 4));
+		return this.append(body);
+	}
+
+	/** Every entry is `string` key + tagged `u32` length + arbitrary raw-length value; `'N'` ends it. */
+	proplist(entries: Iterable<readonly [string, string | Uint8Array]>): this {
+		const seen = new Set<string>();
+		this.append(Buffer.from([TAG_PROPLIST]));
+		for (const [key, value] of entries) {
+			if (typeof key !== "string" || key.length === 0 || /[\x00-\x1f\x7f]/.test(key)) fail("invalid proplist key");
+			if (seen.has(key)) fail("duplicate proplist key");
+			seen.add(key);
+			const bytes = typeof value === "string" ? Buffer.concat([Buffer.from(value, "utf8"), NUL]) : Buffer.from(value);
+			if (bytes.length > MAX_CONTROL_PAYLOAD) fail("proplist value too large");
+			this.string(key);
+			this.u32(bytes.length);
+			this.arbitrary(bytes);
+		}
+		return this.append(Buffer.from([TAG_STRING_NULL]));
+	}
+
+	finish(): Buffer { return Buffer.concat(this.chunks, this.size); }
+}
+
+export function boundedPulseTagWriter(): PulseTagWriter { return new PulseTagWriter(); }
+
+/** Exact-range tagstruct reader; any exhaustion or tag mismatch throws a generic error. */
+export class PulseTagReader {
+	private readonly data: Buffer;
+	private offset = 0;
+
+	constructor(data: Buffer) { this.data = data; }
+
+	private take(count: number): Buffer {
+		if (!Number.isInteger(count) || count < 0 || this.offset + count > this.data.length) fail("read out of range");
+		const slice = this.data.subarray(this.offset, this.offset + count);
+		this.offset += count;
+		return slice;
+	}
+
+	private expect(tag: number): void { if (this.take(1)[0] !== tag) fail("unexpected tag"); }
+
+	u32(): number { this.expect(TAG_U32); return this.take(4).readUInt32BE(0); }
+	u8(): number { this.expect(TAG_U8); return this.take(1)[0]!; }
+
+	string(): string | null {
+		const tag = this.take(1)[0];
+		if (tag === TAG_STRING_NULL) return null;
+		if (tag !== TAG_STRING) fail("unexpected tag");
+		let end = this.offset;
+		while (end < this.data.length && this.data[end] !== 0) end++;
+		if (end >= this.data.length) fail("unterminated string");
+		const bytes = Buffer.from(this.take(end - this.offset));
+		this.take(1); // trailing NUL
+		try { return utf8.decode(bytes); } catch { return fail("invalid UTF-8 string"); }
+	}
+
+	arbitrary(): Buffer {
+		this.expect(TAG_ARBITRARY);
+		const length = this.take(4).readUInt32BE(0);
+		if (length > MAX_CONTROL_PAYLOAD) fail("arbitrary too large");
+		return Buffer.from(this.take(length));
+	}
+
+	boolean(): boolean {
+		const tag = this.take(1)[0];
+		if (tag === TAG_BOOLEAN_TRUE) return true;
+		if (tag === TAG_BOOLEAN_FALSE) return false;
+		return fail("unexpected tag");
+	}
+
+	usec(): bigint { this.expect(TAG_USEC); return this.take(8).readBigUInt64BE(0); }
+
+	sampleSpec(): PulseSampleSpec {
+		this.expect(TAG_SAMPLE_SPEC);
+		const body = this.take(6);
+		return { format: body[0]!, channels: body[1]!, rate: body.readUInt32BE(2) };
+	}
+
+	channelMap(): number[] {
+		this.expect(TAG_CHANNEL_MAP);
+		const channels = this.take(1)[0]!;
+		if (channels === 0) fail("invalid channel map");
+		return [...this.take(channels)];
+	}
+
+	cvolume(): number[] {
+		this.expect(TAG_CVOLUME);
+		const channels = this.take(1)[0]!;
+		if (channels === 0) fail("invalid cvolume");
+		const body = this.take(channels * 4);
+		return Array.from({ length: channels }, (_, index) => body.readUInt32BE(index * 4));
+	}
+
+	proplist(): Map<string, Buffer> {
+		this.expect(TAG_PROPLIST);
+		const entries = new Map<string, Buffer>();
+		for (;;) {
+			const key = this.string();
+			if (key === null) break;
+			const declared = this.u32();
+			const value = this.arbitrary();
+			if (value.length !== declared) fail("proplist length mismatch");
+			if (entries.has(key)) fail("duplicate proplist key");
+			entries.set(key, value);
+		}
+		return entries;
+	}
+
+	assertEOF(): void { if (this.offset !== this.data.length) fail("trailing bytes"); }
+}
+
+export function boundedPulseTagReader(data: Buffer): PulseTagReader { return new PulseTagReader(data); }
+
+/** Control frames carry a tagged payload on channel 0xffffffff; PCM memblocks carry raw bytes. */
+function validateDescriptor(channel: number, offset: bigint, flags: number): void {
+	if (channel === CONTROL_CHANNEL) {
+		if (offset !== 0n) fail("control frame offset must be zero");
+		if (flags !== 0) fail("control frame flags must be zero");
+		return;
+	}
+	if ((flags & 0xff000000) !== 0) fail("unsupported shared-memory frame flags");
+	if ((flags & 0xff) > 2) fail("invalid seek mode");
+}
+
+export function encodePulseFrame(descriptor: { channel: number; offset: bigint; flags: number }, payload: Uint8Array): Buffer {
+	const { channel, offset, flags } = descriptor;
+	if (!Number.isInteger(channel) || channel < 0 || channel > 0xffffffff) fail("invalid channel");
+	if (typeof offset !== "bigint" || offset < 0n || offset > 0xffffffffffffffffn) fail("invalid offset");
+	if (!Number.isInteger(flags) || flags < 0 || flags > 0xffffffff) fail("invalid flags");
+	if (!(payload instanceof Uint8Array) || payload.length < 1 || payload.length > MAX_CONTROL_PAYLOAD) fail("invalid frame payload");
+	validateDescriptor(channel, offset, flags);
+	const header = Buffer.allocUnsafe(PULSE_FRAME_HEADER_SIZE);
+	appendU32(header, payload.length, 0);
+	appendU32(header, channel, 4);
+	appendU32(header, Number(offset >> 32n), 8);
+	appendU32(header, Number(offset & 0xffffffffn), 12);
+	appendU32(header, flags, 16);
+	return Buffer.concat([header, Buffer.from(payload.buffer, payload.byteOffset, payload.length)]);
+}
+
+/** Incremental descriptor decoder: handles fragmented and coalesced frames, bounded per push. */
+export class PulseFrameDecoder {
+	private buffer = Buffer.alloc(0);
+
+	push(chunk: Uint8Array): PulseFrame[] {
+		if (chunk.length > 0) this.buffer = Buffer.concat([this.buffer, Buffer.from(chunk.buffer, chunk.byteOffset, chunk.length)]);
+		const frames: PulseFrame[] = [];
+		for (;;) {
+			if (this.buffer.length < PULSE_FRAME_HEADER_SIZE) break;
+			const length = this.buffer.readUInt32BE(0);
+			const channel = this.buffer.readUInt32BE(4);
+			const offset = (BigInt(this.buffer.readUInt32BE(8)) << 32n) | BigInt(this.buffer.readUInt32BE(12));
+			const flags = this.buffer.readUInt32BE(16);
+			if (length < 1 || length > MAX_CONTROL_PAYLOAD) fail("invalid frame length");
+			validateDescriptor(channel, offset, flags);
+			if (this.buffer.length < PULSE_FRAME_HEADER_SIZE + length) break;
+			const payload = Buffer.from(this.buffer.subarray(PULSE_FRAME_HEADER_SIZE, PULSE_FRAME_HEADER_SIZE + length));
+			this.buffer = this.buffer.subarray(PULSE_FRAME_HEADER_SIZE + length);
+			frames.push({ channel, offset, flags, payload });
+			if (frames.length > MAX_FRAMES_PER_PUSH) fail("too many frames in one push");
+		}
+		if (this.buffer.length > PULSE_FRAME_HEADER_SIZE + MAX_CONTROL_PAYLOAD) fail("frame buffer too large");
+		return frames;
+	}
+}
+
+export function boundedPulseFrameDecoder(): PulseFrameDecoder { return new PulseFrameDecoder(); }

package/lib/notification-pulse-stream.ts

@@ -0,0 +1,213 @@
+/**
+ * PulseAudio native-protocol v13 playback stream for PCM WAV: strict WAV
+ * validation + extraction, CREATE_PLAYBACK_STREAM v13, REQUEST-driven PCM
+ * memblock writes, DRAIN, DELETE. Original MIT (repo-licensed) implementation
+ * derived from the official protocol declaration only; no PulseAudio/LGPL
+ * implementation code is copied.
+ *
+ * Reference (read-only, PulseAudio v17.0): src/pulsecore/protocol-native.c
+ * (CREATE/DRAIN/DELETE, playback_stream_request_bytes), src/pulsecore/pstream.c
+ * (memblock frames), src/pulse/stream.c (write path), PROTOCOL v13. See
+ * odd/tasks/native-audio-backend.md.
+ *
+ * No stream is created here except by an explicit playPulseWav() call; bytes
+ * are validated before any connect/create/PCM. Channel positions are the
+ * standard mono(0)/stereo(1,2) mapping (channelmap.h not in the reference set).
+ */
+import { validateNotificationWav } from "./notification-audio.ts";
+import {
+	MAX_REQUEST_TIMEOUT_MS, PulseClient, loadPulseCookie, resolvePulseCookiePath, type PulseClientOptions,
+} from "./notification-pulse-client.ts";
+import {
+	PulseCommand, PulseSampleFormat, boundedPulseTagWriter, type PulseSampleSpec, type PulseTagReader, type PulseTagWriter,
+} from "./notification-pulse-protocol.ts";
+
+export const MAX_PCM_CHUNK = 64 * 1024;
+/** 10 s maximum validated duration plus a 1 s termination margin; the DRAIN ack can wait for the full sound. */
+export const DEFAULT_PLAYBACK_BUDGET_MS = 11000;
+export const MAX_EARLY_REQUESTS = 32;
+const PA_INVALID_INDEX = 0xffffffff;
+const PA_VOLUME_NORM = 0x10000;
+
+export interface WavPCM {
+	readonly format: number;
+	readonly sampleSpec: PulseSampleSpec;
+	readonly channelMap: readonly number[];
+	readonly data: Buffer;
+	readonly frameSize: number;
+	readonly durationMs: number;
+}
+export interface PulsePlaybackOptions {
+	client?: PulseClient;
+	clientOptions?: PulseClientOptions;
+	adjustLatency?: boolean;
+	budgetMs?: number;
+	requestTimeoutMs?: number;
+}
+
+function pulseFormatForBits(bits: number): number {
+	if (bits === 8) return PulseSampleFormat.U8;
+	if (bits === 16) return PulseSampleFormat.S16LE;
+	if (bits === 24) return PulseSampleFormat.S24LE;
+	if (bits === 32) return PulseSampleFormat.S32LE;
+	throw new Error("Pulse stream: unsupported PCM depth");
+}
+
+/** Validate with the existing strict 9a validator, then extract fmt/data and map to PulseAudio. */
+export function parsePulseWav(bytes: Buffer): WavPCM {
+	const durationMs = validateNotificationWav(bytes);
+	let offset = 12;
+	let bits = 0; let channels = 0; let rate = 0; let data: Buffer | undefined;
+	while (offset + 8 <= bytes.length) {
+		const id = bytes.toString("ascii", offset, offset + 4);
+		const size = bytes.readUInt32LE(offset + 4);
+		const start = offset + 8;
+		if (id === "fmt ") {
+			channels = bytes.readUInt16LE(start + 2);
+			rate = bytes.readUInt32LE(start + 4);
+			bits = bytes.readUInt16LE(start + 14);
+		} else if (id === "data") data = Buffer.from(bytes.subarray(start, start + size));
+		offset = start + size + (size % 2);
+	}
+	if (!data || channels < 1 || channels > 2) throw new Error("Pulse stream: invalid WAV");
+	const format = pulseFormatForBits(bits);
+	const sampleSpec: PulseSampleSpec = Object.freeze({ format, channels, rate });
+	return Object.freeze({
+		format, sampleSpec,
+		channelMap: Object.freeze(channels === 1 ? [0] : [1, 2]),
+		data, frameSize: channels * (bits / 8), durationMs,
+	});
+}
+
+/** CREATE_PLAYBACK_STREAM v13 args: default sink, all seven flags false, corked/muted false, NORM volume. */
+function buildCreateArgs(pcm: WavPCM, adjustLatency: boolean): PulseTagWriter {
+	const volumes = Array.from({ length: pcm.sampleSpec.channels }, () => PA_VOLUME_NORM);
+	return boundedPulseTagWriter()
+		.sampleSpec(pcm.sampleSpec)
+		.channelMap(pcm.channelMap)
+		.u32(PA_INVALID_INDEX)
+		.string(null)
+		.u32(0xffffffff) // maxlength
+		.boolean(false) // corked
+		.u32(0) // tlength
+		.u32(0) // prebuf
+		.u32(0) // minreq
+		.u32(0) // syncid
+		.cvolume(volumes)
+		.boolean(false).boolean(false).boolean(false).boolean(false).boolean(false).boolean(false).boolean(false) // 7 flags
+		.boolean(false) // muted
+		.boolean(adjustLatency)
+		.proplist([["media.name", "gentle-shell notification"], ["media.role", "event"]]);
+}
+
+/** v13 reply: stream/sink indices, missing, buffer attrs, spec, map, device, name, suspended, latency. */
+function parseCreateReply(reader: PulseTagReader, pcm: WavPCM): { streamIndex: number; missing: number } {
+	const streamIndex = reader.u32();
+	reader.u32(); // sink_input index
+	const missing = reader.u32();
+	reader.u32(); reader.u32(); reader.u32(); reader.u32(); // maxlength, tlength, prebuf, minreq
+	const spec = reader.sampleSpec();
+	const map = reader.channelMap();
+	reader.u32(); // sink device index
+	reader.string(); // sink name
+	reader.boolean(); // suspended
+	reader.usec(); // configured sink latency
+	reader.assertEOF();
+	if (spec.format !== pcm.sampleSpec.format || spec.channels !== pcm.sampleSpec.channels || spec.rate !== pcm.sampleSpec.rate)
+		throw new Error("Pulse stream: server sample spec mismatch");
+	if (map.length !== pcm.sampleSpec.channels) throw new Error("Pulse stream: server channel map mismatch");
+	return { streamIndex, missing };
+}
+
+function streamAbortError(): Error { const error = new Error("Pulse stream: aborted"); error.name = "AbortError"; return error; }
+function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal {
+	const list = signals.filter((value): value is AbortSignal => value !== undefined);
+	if (list.length === 0) return new AbortController().signal;
+	if (list.length === 1) return list[0]!;
+	return AbortSignal.any(list);
+}
+function unrefTimer(handle: ReturnType<typeof setTimeout>): void { (handle as { unref?: () => void }).unref?.(); }
+
+/**
+ * Play a validated PCM WAV over an authorized Pulse link. The caller supplies a
+ * connected+authenticated `client`, or clientOptions to own the connection.
+ * Returns after DRAIN and DELETE acks; closes the connection in all paths.
+ */
+export async function playPulseWav(bytes: Buffer, signal?: AbortSignal, options: PulsePlaybackOptions = {}): Promise<void> {
+	const pcm = parsePulseWav(bytes);
+	const ownsClient = options.client === undefined;
+	const clientOptions = options.clientOptions ?? {};
+	const client = options.client ?? new PulseClient(clientOptions);
+	const budgetMs = options.budgetMs ?? DEFAULT_PLAYBACK_BUDGET_MS;
+	const requestMs = Math.min(options.requestTimeoutMs ?? MAX_REQUEST_TIMEOUT_MS, MAX_REQUEST_TIMEOUT_MS);
+	const budget = new AbortController();
+	const budgetTimer = setTimeout(() => budget.abort(new Error("Pulse stream: budget exceeded")), budgetMs);
+	unrefTimer(budgetTimer);
+	const combined = combineSignals(signal, budget.signal);
+	const total = pcm.data.length;
+	const chunkCap = MAX_PCM_CHUNK - (MAX_PCM_CHUNK % pcm.frameSize);
+	let streamIndex: number | undefined;
+	let created = false;
+	let failure: Error | undefined;
+	let demand = 0; let sent = 0;
+	let wake: (() => void) | undefined;
+	const early: Array<{ index: number; bytes: number }> = [];
+	const wakeWaiter = () => { const resolve = wake; wake = undefined; resolve?.(); };
+	const listener = (command: number, reader: PulseTagReader) => {
+		if (command !== PulseCommand.REQUEST) return;
+		let index: number; let wanted: number;
+		try { index = reader.u32(); wanted = reader.u32(); reader.assertEOF(); }
+		catch { failure ??= new Error("Pulse stream: malformed request"); wakeWaiter(); return; }
+		if (streamIndex === undefined) {
+			if (early.length >= MAX_EARLY_REQUESTS) { failure ??= new Error("Pulse stream: too many early requests"); wakeWaiter(); return; }
+			early.push({ index, bytes: wanted }); return;
+		}
+		if (index !== streamIndex) { failure ??= new Error("Pulse stream: unknown stream request"); wakeWaiter(); return; }
+		demand += wanted;
+		wakeWaiter();
+	};
+	const off = client.onEvent(listener);
+	try {
+		if (ownsClient) {
+			await client.connect(combined);
+			const cookie = clientOptions.cookie ?? await loadPulseCookie(resolvePulseCookiePath(clientOptions.env ?? {}), combined);
+			await client.authenticate(cookie, {}, combined);
+		}
+		const reply = await client.request(PulseCommand.CREATE_PLAYBACK_STREAM, buildCreateArgs(pcm, options.adjustLatency === true), combined, requestMs);
+		const createdReply = parseCreateReply(reply, pcm);
+		streamIndex = createdReply.streamIndex;
+		created = true;
+		for (const request of early) { if (request.index !== streamIndex) throw new Error("Pulse stream: unknown stream request"); demand += request.bytes; }
+		demand += createdReply.missing;
+		while (sent < total) {
+			if (failure) throw failure;
+			if (combined.aborted) throw combined.reason instanceof Error ? combined.reason : streamAbortError();
+			const available = Math.min(demand, total - sent);
+			const aligned = available - (available % pcm.frameSize);
+			if (aligned < pcm.frameSize) {
+				await new Promise<void>((resolve, reject) => {
+					const onAbort = () => { wake = undefined; reject(combined.reason instanceof Error ? combined.reason : streamAbortError()); };
+					combined.addEventListener("abort", onAbort, { once: true });
+					wake = () => { combined.removeEventListener("abort", onAbort); resolve(); };
+				});
+				continue;
+			}
+			const chunk = Math.min(aligned, chunkCap);
+			await client.sendDataFrame(streamIndex, pcm.data.subarray(sent, sent + chunk), combined, requestMs);
+			sent += chunk; demand -= chunk;
+		}
+		(await client.request(PulseCommand.DRAIN_PLAYBACK_STREAM, boundedPulseTagWriter().u32(streamIndex), combined, requestMs)).assertEOF();
+		(await client.request(PulseCommand.DELETE_PLAYBACK_STREAM, boundedPulseTagWriter().u32(streamIndex), combined, requestMs)).assertEOF();
+	} catch (error) {
+		failure ??= error as Error;
+		if (created && streamIndex !== undefined) {
+			try { await client.request(PulseCommand.DELETE_PLAYBACK_STREAM, boundedPulseTagWriter().u32(streamIndex), undefined, 500); }
+			catch { /* best effort when the link is still usable */ }
+		}
+		throw failure;
+	} finally {
+		off();
+		clearTimeout(budgetTimer);
+		await client.close();
+	}
+}

package/lib/notification-pulse-worker.ts

@@ -0,0 +1,66 @@
+/**
+ * Standalone PulseAudio worker for the native notification backend. Runs as an
+ * 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.
+ * It reads only argv, the environment and the owner-supplied snapshot; no SDK,
+ * UI, extension, config-owner, cookie-content logging or OS audio surface.
+ */
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { PulseClient } from "./notification-pulse-client.ts";
+import { playPulseWav } from "./notification-pulse-stream.ts";
+
+const SCHEMA = "gentle.audio.pulse/v1";
+const MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+
+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> {
+	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));
+	} finally {
+		await handle.close().catch(() => { /* close failure must not mask the outcome */ });
+	}
+}
+
+async function main(): Promise<void> {
+	const mode = process.argv[2];
+	if (mode === "probe") {
+		try {
+			const result = await new PulseClient({ env: process.env }).probe();
+			emit({ ok: true, available: result.available, formats: result.formats });
+		} catch {
+			emit({ ok: true, available: false, formats: [] });
+		}
+		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;
+		}
+		return;
+	}
+	emit({ ok: false });
+	process.exitCode = 1;
+}
+
+await main();