gentle-pi 4.0.0 → 4.2.0

package/tests/notification-pulse-stream.test.ts

@@ -0,0 +1,320 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createServer, type Server } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { PulseClient } from "../lib/notification-pulse-client.ts";
+import { boundedPulseTagReader, boundedPulseTagWriter } from "../lib/notification-pulse-protocol.ts";
+import { parsePulseWav, playPulseWav } from "../lib/notification-pulse-stream.ts";
+
+// --- independent golden encoders (deliberately NOT the production codec) ---
+const taggedU32 = (value: number): Buffer => { const b = Buffer.alloc(5); b[0] = 0x4c; b.writeUInt32BE(value, 1); return b; };
+const taggedString = (value: string): Buffer => Buffer.concat([Buffer.from([0x74]), Buffer.from(value, "utf8"), Buffer.from([0x00])]);
+const boolFalse = (): Buffer => Buffer.from([0x30]);
+const usec = (value: number): Buffer => { const b = Buffer.alloc(9); b[0] = 0x55; b.writeBigUInt64BE(BigInt(value), 1); return b; };
+const sampleSpec = (format: number, channels: number, rate: number): Buffer => { const b = Buffer.alloc(7); b[0] = 0x61; b[1] = format; b[2] = channels; b.writeUInt32BE(rate, 3); return b; };
+const channelMap = (channels: number): Buffer => Buffer.from([0x6d, channels, ...(channels === 1 ? [0] : [1, 2])]);
+const reply = (command: number, tag: number, ...args: Buffer[]): Buffer => Buffer.concat([taggedU32(command), taggedU32(tag), ...args]);
+const frame = (channel: number, payload: Buffer, flags = 0): Buffer => {
+	const header = Buffer.alloc(20);
+	header.writeUInt32BE(payload.length, 0); header.writeUInt32BE(channel, 4); header.writeUInt32BE(flags, 16);
+	return Buffer.concat([header, payload]);
+};
+const requestPayload = (index: number, bytes: number): Buffer => reply(61, 0xffffffff, taggedU32(index), taggedU32(bytes));
+const taggedValueAt = (payload: Buffer, at: number): number => payload.readUInt32BE(at + 1);
+const commandOf = (payload: Buffer): number => taggedValueAt(payload, 0);
+const tagOf = (payload: Buffer): number => taggedValueAt(payload, 5);
+
+// --- valid WAV builder (content is what the 9a validator already accepts) ---
+function wav(bits: number, channels: number, rate: number, frames: number): Buffer {
+	const sampleBytes = bits / 8;
+	const dataSize = frames * channels * sampleBytes;
+	const b = Buffer.alloc(44 + dataSize, 0x11);
+	b.write("RIFF", 0); b.writeUInt32LE(36 + dataSize, 4); b.write("WAVE", 8);
+	b.write("fmt ", 12); b.writeUInt32LE(16, 16); b.writeUInt16LE(1, 20);
+	b.writeUInt16LE(channels, 22); b.writeUInt32LE(rate, 24);
+	b.writeUInt32LE(rate * channels * sampleBytes, 28);
+	b.writeUInt16LE(channels * sampleBytes, 32); b.writeUInt16LE(bits, 34);
+	b.write("data", 36); b.writeUInt32LE(dataSize, 40);
+	return b;
+}
+interface PlayState { seen: number[]; pcm: Buffer[]; createPayload?: Buffer; streamIndex: number; drainSender?: () => void; }
+interface FakeServer { readonly path: string; readonly state: PlayState; close(): Promise<void>; }
+interface PlayScript {
+	streamIndex?: number; missing?: number; requests?: number[]; earlyRequestBytes?: number;
+	corruptSpec?: boolean; closeAfterFirstChunk?: boolean; errorOnDrain?: boolean; holdDrain?: boolean; unknownRequestIndex?: number;
+}
+async function startPlaybackServer(script: PlayScript): Promise<FakeServer> {
+	const dir = await mkdtemp(join(tmpdir(), "pulse-stream-"));
+	const path = join(dir, "native");
+	const state: PlayState = { seen: [], pcm: [], streamIndex: script.streamIndex ?? 7 };
+	const createReply = (tag: number, spec: { format: number; channels: number; rate: number }): Buffer => {
+		const echoed = script.corruptSpec ? { format: spec.format === 0 ? 3 : 0, channels: spec.channels, rate: spec.rate } : spec;
+		return reply(2, tag, taggedU32(state.streamIndex), taggedU32(state.streamIndex + 1), taggedU32(script.missing ?? 0),
+			taggedU32(0xffffffff), taggedU32(0), taggedU32(0), taggedU32(0),
+			sampleSpec(echoed.format, echoed.channels, echoed.rate), channelMap(spec.channels),
+			taggedU32(0), taggedString("auto_null"), boolFalse(), usec(0));
+	};
+	const server: Server = createServer(socket => {
+		let buffer = Buffer.alloc(0);
+		const write = (value: Buffer) => { if (!socket.destroyed) socket.write(value); };
+		const send = (payload: Buffer) => write(frame(0xffffffff, payload));
+		socket.on("error", () => { /* client closed mid-write */ });
+		socket.on("data", chunk => {
+			buffer = Buffer.concat([buffer, chunk]);
+			for (;;) {
+				if (buffer.length < 20) break;
+				const length = buffer.readUInt32BE(0);
+				if (buffer.length < 20 + length) break;
+				const payload = Buffer.from(buffer.subarray(20, 20 + length));
+				const channel = buffer.readUInt32BE(4);
+				buffer = buffer.subarray(20 + length);
+				if (channel !== 0xffffffff) { state.pcm.push(payload); if (script.closeAfterFirstChunk) socket.destroy(); continue; }
+				const command = commandOf(payload); const tag = tagOf(payload);
+				state.seen.push(command);
+				if (command === 8) { send(reply(2, tag, taggedU32(35))); continue; }
+				if (command === 9) { send(reply(2, tag, taggedU32(0))); continue; }
+				if (command === 4) { send(reply(2, tag)); continue; }
+				if (command === 12) {
+					if (script.errorOnDrain) { send(reply(0, tag, taggedU32(6))); continue; }
+					if (script.holdDrain) { state.drainSender = () => send(reply(2, tag)); continue; }
+					send(reply(2, tag)); continue;
+				}
+				if (command === 3) {
+					state.createPayload = Buffer.from(payload);
+					const spec = { format: payload[11]!, channels: payload[12]!, rate: payload.readUInt32BE(13) };
+					let out = frame(0xffffffff, createReply(tag, spec));
+					if (script.earlyRequestBytes) out = Buffer.concat([out, frame(0xffffffff, requestPayload(state.streamIndex, script.earlyRequestBytes))]);
+					write(out);
+					for (const bytes of script.requests ?? []) write(frame(0xffffffff, requestPayload(script.unknownRequestIndex ?? state.streamIndex, bytes)));
+					continue;
+				}
+			}
+		});
+	});
+	await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(path, () => resolve()); });
+	return { path, state, close: async () => { await new Promise<void>(resolve => server.close(() => resolve())); await rm(dir, { recursive: true, force: true }); } };
+}
+function fakeClock() {
+	let now = 0; let counter = 0;
+	const jobs = new Map<number, { at: number; fn: () => void }>();
+	return {
+		setTimeout: (fn: () => void, ms: number) => { const id = ++counter; jobs.set(id, { at: now + ms, fn }); return id; },
+		clearTimeout: (id: number | NodeJS.Timeout) => { jobs.delete(id as number); },
+		advance(ms: number) { now += ms; for (const [id, job] of [...jobs]) if (job.at <= now) { jobs.delete(id); job.fn(); } },
+	};
+}
+const pcmOf = (bytes: Buffer[]): Buffer => Buffer.concat(bytes);
+const dataOf = (bytes: Buffer): Buffer => { let offset = 12; for (;;) { const id = bytes.toString("ascii", offset, offset + 4); const size = bytes.readUInt32LE(offset + 4); if (id === "data") return bytes.subarray(offset + 8, offset + 8 + size); offset += 8 + size + (size % 2); } };
+
+test("parsePulseWav extracts PCM and maps 8/16/24/32-bit mono/stereo", () => {
+	const cases: Array<[number, number, number]> = [[8, 1, 8000], [16, 2, 44100], [24, 1, 48000], [32, 2, 192000]];
+	for (const [bits, channels, rate] of cases) {
+		const bytes = wav(bits, channels, rate, 100);
+		const pcm = parsePulseWav(bytes);
+		assert.equal(pcm.sampleSpec.format, bits === 8 ? 0 : bits === 16 ? 3 : bits === 24 ? 9 : 7, `${bits}bit`);
+		assert.equal(pcm.sampleSpec.channels, channels);
+		assert.equal(pcm.sampleSpec.rate, rate);
+		assert.equal(pcm.channelMap.length, channels);
+		assert.equal(pcm.frameSize, channels * bits / 8);
+		assert.deepEqual(pcm.data, dataOf(bytes));
+		assert.ok(Object.isFrozen(pcm));
+	}
+});
+
+test("parsePulseWav rejects invalid and oversized bytes while accepting the 10 s boundary without IO", () => {
+	assert.throws(() => parsePulseWav(Buffer.alloc(8)));
+	assert.throws(() => parsePulseWav(wav(16, 1, 8000, 100).subarray(0, 40)));
+	assert.throws(() => parsePulseWav(wav(16, 3, 8000, 10)));
+	assert.throws(() => parsePulseWav(wav(16, 1, 4000, 10)));
+	assert.equal(parsePulseWav(wav(16, 1, 8000, 80000)).durationMs, 10000); // exact 10 s boundary
+	assert.equal(parsePulseWav(wav(16, 1, 8000, 44640)).durationMs, 5580); // previously rejected 5.58 s
+	assert.throws(() => parsePulseWav(wav(16, 1, 8000, 80001))); // just past 10 s
+	assert.throws(() => parsePulseWav(wav(32, 2, 192000, 300000))); // > 2 MiB
+});
+
+test("playPulseWav rejects invalid bytes before opening a socket", async () => {
+	const server = await startPlaybackServer({});
+	try {
+		await assert.rejects(playPulseWav(Buffer.alloc(8), undefined, { clientOptions: { socketPath: server.path, cookie: Buffer.alloc(256) } }));
+		assert.deepEqual(server.state.seen, []);
+		assert.deepEqual(server.state.pcm, []);
+	} finally { await server.close(); }
+});
+
+test("golden CREATE v13 frame pins spec, default sink, flags, volume and proplist", async () => {
+	const bytes = wav(16, 2, 44100, 100);
+	const server = await startPlaybackServer({ missing: dataOf(bytes).length });
+	try {
+		await playPulseWav(bytes, undefined, { clientOptions: { socketPath: server.path, cookie: Buffer.alloc(256) } });
+		const payload = server.state.createPayload!;
+		assert.equal(commandOf(payload), 3);
+		assert.equal(payload[10], 0x61); // sample_spec
+		assert.equal(payload[11], 3); assert.equal(payload[12], 2); assert.equal(payload.readUInt32BE(13), 44100);
+		assert.equal(payload[17], 0x6d); // channel_map
+		assert.equal(payload[18], 2);
+		const sinkIndexAt = 17 + 2 + 2;
+		assert.equal(taggedValueAt(payload, sinkIndexAt), 0xffffffff);
+		assert.equal(payload[sinkIndexAt + 5], 0x4e); // sink_name null
+		const proplistAt = payload.indexOf(0x50, sinkIndexAt);
+		assert.ok(payload.indexOf(Buffer.from("media.name\0", "latin1")) > proplistAt);
+		assert.ok(payload.indexOf(Buffer.from("media.role\0", "latin1")) > proplistAt);
+		assert.ok(payload.indexOf(Buffer.from("event\0", "latin1")) > proplistAt);
+		// seven explicit false flags, muted false, adjust_latency false
+		assert.ok(payload.subarray(sinkIndexAt).includes(boolFalse()));
+		assert.deepEqual(pcmOf(server.state.pcm), dataOf(bytes));
+		assert.deepEqual(server.state.seen.slice(-2), [12, 4]);
+	} finally { await server.close(); }
+});
+
+test("initial missing plus later REQUEST drives aligned PCM and completes drain/delete", async () => {
+	const bytes = wav(16, 1, 8000, 500); const data = dataOf(bytes);
+	const server = await startPlaybackServer({ missing: 2, requests: [data.length - 2] });
+	try {
+		await playPulseWav(bytes, undefined, { clientOptions: { socketPath: server.path, cookie: Buffer.alloc(256) } });
+		assert.deepEqual(pcmOf(server.state.pcm), data);
+		for (const chunk of server.state.pcm) assert.equal(chunk.length % 2, 0);
+		assert.deepEqual(server.state.seen.slice(-2), [12, 4]);
+	} finally { await server.close(); }
+});
+
+test("early coalesced REQUEST right after the CREATE reply is queued and folded", async () => {
+	const bytes = wav(16, 1, 8000, 200); const data = dataOf(bytes);
+	const server = await startPlaybackServer({ missing: 2, earlyRequestBytes: data.length - 2 });
+	try {
+		await playPulseWav(bytes, undefined, { clientOptions: { socketPath: server.path, cookie: Buffer.alloc(256) } });
+		assert.deepEqual(pcmOf(server.state.pcm), data);
+	} finally { await server.close(); }
+});
+
+test("tiny unaligned requests accumulate until a whole frame and huge requests stay bounded", async () => {
+	const bytes = wav(16, 1, 8000, 64); const data = dataOf(bytes);
+	const server = await startPlaybackServer({ missing: 0, requests: [1, 1, 1, 0xffffffff] });
+	try {
+		await playPulseWav(bytes, undefined, { clientOptions: { socketPath: server.path, cookie: Buffer.alloc(256) } });
+		assert.deepEqual(pcmOf(server.state.pcm), data);
+		assert.ok(server.state.pcm.every(chunk => chunk.length <= 64 * 1024 && chunk.length % 2 === 0));
+	} finally { await server.close(); }
+});
+
+test("mismatched spec and unknown-stream requests fail before/without PCM", async () => {
+	const bytes = wav(16, 1, 8000, 100);
+	const mismatch = await startPlaybackServer({ missing: dataOf(bytes).length, corruptSpec: true });
+	try { await assert.rejects(playPulseWav(bytes, undefined, { clientOptions: { socketPath: mismatch.path, cookie: Buffer.alloc(256) } }), /Pulse stream/); }
+	finally { await mismatch.close(); }
+
+	const unknown = await startPlaybackServer({ missing: 0, requests: [100], unknownRequestIndex: 99 });
+	try { await assert.rejects(playPulseWav(bytes, undefined, { clientOptions: { socketPath: unknown.path, cookie: Buffer.alloc(256) } }), /Pulse stream/); }
+	finally { await unknown.close(); }
+});
+
+test("ERROR on drain and truncated PCM fail closed with best-effort cleanup", async () => {
+	const bytes = wav(16, 1, 8000, 300);
+	const errorServer = await startPlaybackServer({ missing: dataOf(bytes).length, errorOnDrain: true });
+	try {
+		await assert.rejects(playPulseWav(bytes, undefined, { clientOptions: { socketPath: errorServer.path, cookie: Buffer.alloc(256) } }), /Pulse client|Pulse stream/);
+		assert.deepEqual(pcmOf(errorServer.state.pcm), dataOf(bytes)); // no extra PCM after the error
+	} finally { await errorServer.close(); }
+
+	const truncating = await startPlaybackServer({ missing: dataOf(bytes).length, closeAfterFirstChunk: true });
+	try { await assert.rejects(playPulseWav(bytes, undefined, { clientOptions: { socketPath: truncating.path, cookie: Buffer.alloc(256) } }), /Pulse client|Pulse stream/); }
+	finally { await truncating.close(); }
+});
+
+test("a stalled demand fails by the playback budget instead of hanging", async () => {
+	const bytes = wav(16, 1, 8000, 100);
+	const server = await startPlaybackServer({ missing: 2, requests: [] });
+	try { await assert.rejects(playPulseWav(bytes, undefined, { clientOptions: { socketPath: server.path, cookie: Buffer.alloc(256) }, budgetMs: 120 }), /budget|Pulse/); }
+	finally { await server.close(); }
+});
+
+test("DRAIN may exceed the 900 ms default via a bounded per-request deadline", async () => {
+	const bytes = wav(16, 1, 8000, 100); const data = dataOf(bytes);
+	const server = await startPlaybackServer({ missing: data.length, holdDrain: true });
+	const clock = fakeClock();
+	try {
+		const client = new PulseClient({ socketPath: server.path, cookie: Buffer.alloc(256), requestTimeoutMs: 900, setTimeout: clock.setTimeout, clearTimeout: clock.clearTimeout });
+		await client.connect();
+		let settled = false;
+		const playing = playPulseWav(bytes, undefined, { client, requestTimeoutMs: 6000 }).then(() => { settled = true; }, error => { settled = true; throw error; });
+		for (let i = 0; i < 20 && !server.state.drainSender; i++) await new Promise(resolve => setTimeout(resolve, 5));
+		assert.ok(server.state.drainSender, "drain reached");
+		clock.advance(1200); // beyond the 900 ms default, within the 6000 ms override
+		await new Promise(resolve => setTimeout(resolve, 10));
+		assert.equal(settled, false);
+		server.state.drainSender!();
+		await playing;
+		await client.close();
+	} finally { await server.close(); }
+});
+
+test("default engine request deadline allows a full 10 s drain instead of the old 6 s", async () => {
+	const bytes = wav(16, 1, 8000, 100); const data = dataOf(bytes);
+	const server = await startPlaybackServer({ missing: data.length, holdDrain: true });
+	const clock = fakeClock();
+	try {
+		const client = new PulseClient({ socketPath: server.path, cookie: Buffer.alloc(256), requestTimeoutMs: 900, setTimeout: clock.setTimeout, clearTimeout: clock.clearTimeout });
+		await client.connect();
+		let settled = false;
+		const playing = playPulseWav(bytes, undefined, { client }).then(() => { settled = true; }, () => { settled = true; });
+		for (let i = 0; i < 20 && !server.state.drainSender; i++) await new Promise(resolve => setTimeout(resolve, 5));
+		assert.ok(server.state.drainSender, "drain reached");
+		clock.advance(10000); // past the old 6000 ms deadline, still inside the 10 s duration
+		await new Promise(resolve => setTimeout(resolve, 10));
+		assert.equal(settled, false);
+		clock.advance(1000); // now past the new 11000 ms deadline
+		await new Promise(resolve => setTimeout(resolve, 10));
+		assert.equal(settled, true);
+		await playing;
+		await client.close();
+	} finally { await server.close(); }
+});
+
+test("abort during drain best-effort deletes and closes without extra PCM", async () => {
+	const bytes = wav(16, 1, 8000, 100); const data = dataOf(bytes);
+	const server = await startPlaybackServer({ missing: data.length, holdDrain: true });
+	try {
+		const client = new PulseClient({ socketPath: server.path, cookie: Buffer.alloc(256) });
+		await client.connect();
+		const controller = new AbortController();
+		const playing = playPulseWav(bytes, controller.signal, { client });
+		for (let i = 0; i < 20 && !server.state.drainSender; i++) await new Promise(resolve => setTimeout(resolve, 5));
+		controller.abort();
+		await assert.rejects(playing, /aborted|Pulse/);
+		assert.deepEqual(pcmOf(server.state.pcm), data);
+		assert.ok(server.state.seen.includes(4)); // best-effort DELETE while the link is still usable
+		await client.close();
+	} finally { await server.close(); }
+});
+
+test("sendDataFrame returns a promise for backpressure and closes asynchronously", async () => {
+	const server = await startPlaybackServer({});
+	try {
+		const client = new PulseClient({ socketPath: server.path, cookie: Buffer.alloc(256) });
+		await client.connect();
+		assert.ok(client.sendDataFrame(5, Buffer.from([1, 2])) instanceof Promise);
+		await client.sendDataFrame(5, Buffer.from([3, 4]));
+		await client.close();
+	} finally { await server.close(); }
+});
+
+test("more than 32 coalesced early REQUESTs fail closed before any PCM", async () => {
+	type Listener = (command: number, reader: ReturnType<typeof boundedPulseTagReader>) => void;
+	const listeners = new Set<Listener>();
+	const requestReader = (index: number, bytes: number) => boundedPulseTagReader(boundedPulseTagWriter().u32(index).u32(bytes).finish());
+	const createReply = boundedPulseTagWriter().u32(7).u32(8).u32(0).u32(0).u32(0).u32(0).u32(0)
+		.sampleSpec({ format: 3, channels: 1, rate: 8000 }).channelMap([0]).u32(0).string(null).boolean(false).usec(0n).finish();
+	const sent: Buffer[] = [];
+	const client = {
+		onEvent: (listener: Listener) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+		request: async (command: number) => {
+			if (command === 3) for (let index = 0; index < 33; index++) for (const listener of listeners) listener(61, requestReader(7, 1));
+			return boundedPulseTagReader(createReply);
+		},
+		sendDataFrame: async (_channel: number, payload: Uint8Array) => { sent.push(Buffer.from(payload)); },
+		close: async () => {},
+	} as unknown as PulseClient;
+	await assert.rejects(playPulseWav(wav(16, 1, 8000, 64), undefined, { client }), /early|too many/);
+	assert.deepEqual(sent, []);
+});

package/tests/notification-scheduler.test.ts

@@ -0,0 +1,258 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { NotificationScheduler, type PlaybackPermit } from "../lib/notification-scheduler.ts";
+import { DEFAULT_NOTIFICATION_SETTINGS, type NotificationSettings, type NotificationSound } from "../lib/notification-policy.ts";
+
+class Clock {
+	now = 0;
+	serial = 0;
+	timers = new Map<number, { at: number; fn: () => void }>();
+	setTimeout = (fn: () => void, delay: number) => {
+		const id = ++this.serial; this.timers.set(id, { at: this.now + delay, fn }); return id;
+	};
+	clearTimeout = (id: number) => { this.timers.delete(id); };
+	advance(ms: number) {
+		const end = this.now + ms;
+		for (;;) {
+			const next = [...this.timers].filter(([, timer]) => timer.at <= end).sort((a, b) => a[1].at - b[1].at)[0];
+			if (!next) break;
+			this.now = next[1].at; this.timers.delete(next[0]); next[1].fn();
+		}
+		this.now = end;
+	}
+}
+const tick = async () => { for (let i = 0; i < 6; i++) await Promise.resolve(); };
+function fixture(slow = false, dedupeCapacity = 256) {
+	const clock = new Clock();
+	const settings: NotificationSettings = { ...structuredClone(DEFAULT_NOTIFICATION_SETTINGS), enabled: true };
+	const calls: Array<{ sound: NotificationSound; signal: AbortSignal; permit: PlaybackPermit; finish: () => void; fail: () => void }> = [];
+	const starts: number[] = []; const errors: unknown[] = [];
+	const scheduler = new NotificationScheduler({ now: () => clock.now, setTimeout: clock.setTimeout, clearTimeout: clock.clearTimeout,
+		dedupeCapacity, onError: error => { errors.push(error); },
+		player: (sound, signal, permit) => new Promise<void>((resolve, reject) => {
+			calls.push({ sound, signal, permit, finish: resolve, fail: () => reject(new Error("audio")) });
+			if (!slow && permit.start()) starts.push(clock.now);
+		}),
+	});
+	scheduler.resetSession("s"); scheduler.configure(settings, false);
+	const enqueue = (sequence: number, event = "agent.completed" as const, occurredAt = clock.now) =>
+		scheduler.enqueue({ sessionId: "s", runId: "r", sequence, event, occurredAt });
+	return { clock, settings, calls, starts, errors, scheduler, enqueue };
+}
+
+test("burst priority belongs to event, ties latest, first coalesce deadline is fixed", () => {
+	const f = fixture();
+	f.settings.audio.events["agent.failed"] = "builtin:success";
+	f.settings.audio.events["agent.completed"] = "builtin:error";
+	f.scheduler.configure(f.settings, false);
+	f.enqueue(1); f.clock.advance(200);
+	f.scheduler.enqueue({ sessionId: "s", runId: "r", sequence: 2, event: "agent.failed", occurredAt: 200 });
+	f.enqueue(3); f.clock.advance(99); assert.equal(f.calls.length, 0);
+	f.clock.advance(1); assert.equal(f.calls[0].sound, "builtin:success");
+	const ties = fixture(); ties.enqueue(1); ties.clock.advance(200);
+	ties.settings.audio.events["agent.completed"] = "builtin:attention"; ties.scheduler.configure(ties.settings, false);
+	ties.enqueue(2); ties.clock.advance(100); assert.equal(ties.calls[0].sound, "builtin:attention");
+});
+
+test("serial active plus one pending, minimum interval measured between starts", async () => {
+	const f = fixture(); f.enqueue(1); f.clock.advance(300); f.enqueue(2); f.enqueue(3);
+	f.clock.advance(500); assert.equal(f.calls.length, 1);
+	f.calls[0].finish(); await tick(); f.clock.advance(499); assert.equal(f.calls.length, 1);
+	f.clock.advance(1); assert.deepEqual(f.starts, [300, 1300]);
+});
+
+test("TTL exact boundary and pending behind unstarted detection never replay", async () => {
+	const f = fixture(true); assert.equal(f.enqueue(1, "agent.completed", -2000), false);
+	assert.equal(f.enqueue(2, "agent.completed", -1999), true);
+	f.clock.advance(300); assert.equal(f.calls.length, 0);
+	f.enqueue(3); f.clock.advance(300); f.enqueue(4);
+	f.clock.advance(2000); f.calls[0].finish(); await tick(); f.clock.advance(5000);
+	assert.equal(f.calls.length, 1);
+});
+
+test("long playback preserves a pending failure without overlap or priority loss", async () => {
+	const f = fixture(); f.enqueue(1); f.clock.advance(300);
+	f.clock.advance(10);
+	assert.equal(f.scheduler.enqueue({ sessionId: "s", runId: "failed", sequence: 1,
+		event: "subagent.failed", occurredAt: f.clock.now }), true);
+	f.clock.advance(2419); // The local success WAV lasts 2429 ms.
+	assert.equal(f.calls.length, 1);
+	assert.equal(f.enqueue(2), false); // A newer success cannot replace the preserved failure.
+	assert.equal(f.enqueue(3, "agent.completed", f.clock.now - 2000), false);
+	f.calls[0].finish(); await tick();
+	assert.equal(f.calls.length, 2);
+	assert.equal(f.calls[1].sound, "builtin:error");
+	assert.deepEqual(f.starts, [300, 2729]);
+	f.calls[1].finish(); await tick(); f.clock.advance(5000);
+	assert.equal(f.calls.length, 2);
+});
+
+test("pending TTL pauses only after the active playback actually starts", async () => {
+	const f = fixture(true); f.enqueue(1); f.clock.advance(300); f.enqueue(2);
+	f.clock.advance(200); assert.equal(f.calls[0].permit.start(), true);
+	f.clock.advance(3000); assert.equal(f.calls.length, 1);
+	f.calls[0].finish(); await tick(); assert.equal(f.calls.length, 2);
+	// 200 ms of the pending event's TTL was spent before playback started.
+	f.clock.advance(1799); assert.equal(f.calls[1].signal.aborted, false);
+	f.clock.advance(1); assert.equal(f.calls[1].signal.aborted, true);
+	assert.equal(f.calls[1].permit.start(), false);
+});
+
+test("equal-priority replacement during playback keeps only the latest candidate", async () => {
+	const f = fixture(); f.enqueue(1); f.clock.advance(300); f.enqueue(2);
+	f.clock.advance(2500);
+	f.settings.audio.events["agent.completed"] = "builtin:attention";
+	f.scheduler.configure(f.settings, false);
+	assert.equal(f.enqueue(3), true);
+	f.clock.advance(2500); f.calls[0].finish(); await tick();
+	assert.equal(f.calls.length, 2);
+	assert.equal(f.calls[1].sound, "builtin:attention");
+	f.calls[1].finish(); await tick(); f.clock.advance(5000);
+	assert.equal(f.calls.length, 2);
+});
+
+test("started preview also preserves the next automatic candidate", async () => {
+	const f = fixture(); assert.equal(f.scheduler.preview("builtin:attention"), true);
+	f.enqueue(1); f.clock.advance(2856);
+	assert.equal(f.calls.length, 1);
+	f.calls[0].finish(); await tick();
+	assert.equal(f.calls.length, 2);
+	assert.equal(f.calls[1].sound, "builtin:success");
+});
+
+test("preserved pending events still expire during minimum interval after playback", async () => {
+	const f = fixture(); f.settings.audio.minimumIntervalMs = 6000;
+	f.scheduler.configure(f.settings, false); f.enqueue(1); f.clock.advance(300);
+	f.enqueue(2); f.clock.advance(2429); f.calls[0].finish(); await tick();
+	f.clock.advance(2000); f.clock.advance(6000);
+	assert.equal(f.calls.length, 1);
+});
+
+test("mute, off, session replacement and disposal discard playback-paused pending events", async () => {
+	for (const action of ["mute", "off", "session", "dispose"] as const) {
+		const f = fixture(); f.enqueue(1); f.clock.advance(300); f.enqueue(2);
+		f.clock.advance(3000);
+		if (action === "dispose") f.scheduler.dispose();
+		else if (action === "session") f.scheduler.resetSession("other");
+		else f.scheduler.configure({ ...f.settings, enabled: action !== "off" }, action === "mute");
+		assert.equal(f.calls[0].signal.aborted, true);
+		f.scheduler.resetSession("s"); f.scheduler.configure(f.settings, false);
+		f.calls[0].finish(); await tick(); f.clock.advance(5000);
+		assert.equal(f.calls.length, 1);
+	}
+});
+
+test("slow detection must acquire start permit immediately before spawn; expires and aborts", async () => {
+	const f = fixture(true); f.enqueue(1); f.clock.advance(300);
+	f.clock.advance(1699); assert.equal(f.calls[0].signal.aborted, false);
+	f.clock.advance(1); assert.equal(f.calls[0].signal.aborted, true);
+	assert.equal(f.calls[0].permit.start(), false);
+	f.enqueue(2); f.clock.advance(300); assert.equal(f.calls.length, 1);
+	f.calls[0].finish(); await tick(); assert.equal(f.calls.length, 2);
+	assert.equal(f.calls[1].permit.start(), true);
+	assert.equal(f.calls[1].permit.start(), false);
+});
+
+test("settled detection cannot start through its old permit after a new run reserves playback", async () => {
+	const f = fixture(true); f.enqueue(1); f.clock.advance(300);
+	const old = f.calls[0]; old.finish(); await tick();
+	assert.equal(f.scheduler.enqueue({ sessionId: "s", runId: "new", sequence: 1,
+		event: "agent.completed", occurredAt: f.clock.now }), true);
+	f.clock.advance(300); assert.equal(f.calls.length, 2);
+	assert.equal(old.signal.aborted, false); // Still inside TTL, same generation: identity must reject it.
+	assert.equal(f.calls[1].permit.start(), true);
+	assert.equal(old.permit.start(), false);
+	assert.equal(f.calls[1].permit.start(), false);
+});
+
+test("throttle follows actual start after slow detection, not detection invocation", async () => {
+	const f = fixture(true); f.enqueue(1); f.clock.advance(700);
+	assert.equal(f.calls[0].permit.start(), true); f.calls[0].finish(); await tick(); f.enqueue(2);
+	f.clock.advance(999); assert.equal(f.calls.length, 1);
+	f.clock.advance(1); assert.equal(f.calls.length, 2);
+});
+
+test("dedupe occurrence not state, bounded cap, session memory reaped, off events consumed", async () => {
+	const f = fixture(false, 2); assert.equal(f.enqueue(1), true); assert.equal(f.enqueue(1), false);
+	assert.equal(f.enqueue(2), true); assert.equal(f.enqueue(3), true); assert.equal(f.enqueue(1), true);
+	f.scheduler.configure({ ...f.settings, enabled: false }, false);
+	assert.equal(f.enqueue(9), false); f.scheduler.configure(f.settings, false); assert.equal(f.enqueue(9), false);
+	f.scheduler.resetSession("other"); assert.equal(f.enqueue(10), false);
+	f.scheduler.resetSession("s"); assert.equal(f.enqueue(9), true);
+	f.clock.advance(300); assert.equal(f.calls.length, 1);
+});
+
+test("off, mute and session changes abort and invalidate async; no overlap or replay", async () => {
+	for (const action of ["off", "mute", "session"] as const) {
+		const f = fixture(true); f.enqueue(1); f.clock.advance(300); f.enqueue(2);
+		if (action === "session") f.scheduler.resetSession("next");
+		else f.scheduler.configure({ ...f.settings, enabled: action !== "off" }, action === "mute");
+		assert.equal(f.calls[0].signal.aborted, true); assert.equal(f.calls[0].permit.start(), false);
+		f.scheduler.resetSession("s"); f.scheduler.configure(f.settings, false);
+		f.clock.advance(5000); assert.equal(f.calls.length, 1);
+		assert.equal(f.scheduler.preview("builtin:error"), false);
+		f.calls[0].finish(); await tick(); f.clock.advance(5000); assert.equal(f.calls.length, 1);
+		assert.equal(f.scheduler.preview("builtin:error"), true);
+	}
+});
+
+test("preview bypasses off/mute, stays serial, does not flush pending or modify config", async () => {
+	const f = fixture(); f.scheduler.configure({ ...f.settings, enabled: false }, true);
+	const before = JSON.stringify(f.settings); assert.equal(f.scheduler.preview("builtin:error"), true);
+	assert.equal(f.scheduler.preview("builtin:success"), false); assert.equal(f.enqueue(1), false);
+	f.calls[0].finish(); await tick(); f.scheduler.configure(f.settings, false); f.enqueue(2);
+	assert.equal(f.scheduler.preview("builtin:error"), false);
+	f.clock.advance(1000); assert.equal(f.calls.length, 2); assert.equal(JSON.stringify(f.settings), before);
+});
+
+test("start at TTL minus one succeeds, exact TTL denied even when timer delivery is late", () => {
+	const f = fixture(true); f.enqueue(1); f.clock.advance(1999);
+	assert.equal(f.calls[0].permit.start(), true);
+	f.clock.advance(1); assert.equal(f.calls[0].signal.aborted, false);
+	const late = fixture(true); late.enqueue(1); late.clock.advance(300);
+	late.clock.now = 2000; // Simulate blocked event loop: expiry callback has not run.
+	assert.equal(late.calls[0].signal.aborted, false);
+	assert.equal(late.calls[0].permit.start(), false);
+});
+
+test("large bursts still reserve only one pending; silent settings never enable or replay", async () => {
+	const f = fixture(); f.enqueue(1); f.clock.advance(300);
+	for (let i = 2; i < 1002; i++) f.enqueue(i);
+	f.clock.advance(1000); assert.equal(f.calls.length, 1);
+	f.calls[0].finish(); await tick(); assert.equal(f.calls.length, 2);
+	f.calls[1].finish(); await tick(); f.clock.advance(5000); assert.equal(f.calls.length, 2);
+	f.settings.audio.events = {}; f.scheduler.configure(f.settings, false);
+	assert.equal(f.enqueue(2000), false);
+	f.settings.audio.events["agent.completed"] = "builtin:success"; // Scheduler cloned configuration.
+	assert.equal(f.enqueue(2001), false);
+	f.scheduler.configure(f.settings, false); assert.equal(f.enqueue(2000), false);
+});
+
+test("dispose during detection aborts, rejects late errors silently and clears timers", async () => {
+	const f = fixture(true); f.enqueue(1); f.clock.advance(300); f.enqueue(2);
+	f.scheduler.dispose(); f.scheduler.dispose();
+	assert.equal(f.calls[0].signal.aborted, true); assert.equal(f.calls[0].permit.start(), false);
+	f.calls[0].fail(); await tick(); f.clock.advance(10000);
+	assert.equal(f.errors.length, 0); assert.equal(f.calls.length, 1); assert.equal(f.clock.timers.size, 0);
+});
+
+test("synchronous player errors release reservation and are contained", () => {
+	const clock = new Clock(); let errors = 0;
+	const scheduler = new NotificationScheduler({ now: () => clock.now, setTimeout: clock.setTimeout, clearTimeout: clock.clearTimeout,
+		player: () => { throw new Error("sync"); }, onError: () => { errors++; } });
+	assert.equal(scheduler.preview("builtin:error"), true);
+	assert.equal(scheduler.preview("builtin:error"), true); assert.equal(errors, 1); scheduler.dispose();
+});
+
+test("errors caught, diagnostics locally limited even if callback throws, disposal idempotent", async () => {
+	const f = fixture(); f.scheduler.configure({ ...f.settings, enabled: false }, false);
+	for (let i = 0; i < 3; i++) { assert.equal(f.scheduler.preview("builtin:error"), true); f.calls[i].fail(); await tick(); }
+	assert.equal(f.errors.length, 1); f.clock.advance(5000);
+	f.scheduler.preview("builtin:error"); f.calls[3].fail(); await tick(); assert.equal(f.errors.length, 2);
+	f.scheduler.configure(f.settings, false); f.enqueue(1); f.scheduler.dispose(); f.scheduler.dispose();
+	f.clock.advance(10000); assert.equal(f.calls.length, 4); assert.equal(f.scheduler.preview("builtin:error"), false);
+	const clock = new Clock();
+	const scheduler = new NotificationScheduler({ now: () => clock.now, setTimeout: clock.setTimeout, clearTimeout: clock.clearTimeout,
+		player: async () => { throw new Error("audio"); }, onError: () => { throw new Error("diagnostic"); } });
+	scheduler.preview("builtin:error"); await tick(); scheduler.dispose();
+});