osdy-pi 1.11.12 → 1.11.13

package/README.md

@@ -6,6 +6,8 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 ## Release highlights
 
+**Audio notifications share a bundled 180 ms default sound on macOS and Windows**, with a persistent master mute in `/osdyConfig` → **Sounds**. Custom paths take precedence: startup flag → saved global path → bundled default. Muting preserves those paths and visual alerts; explicit **Test effective** still plays while muted. See [Audio notifications](#audio-notifications).
+
 **The Control Center consolidates Osdy controls in `/osdyConfig`**: ten categories cover appearance, Git, sounds, accounts, usage, and TODO/Agents provider settings. Account quota previews query a selected stored Codex profile without switching it. The header shows the installed Osdy package version when it fits; constrained layouts show only the centered mascot. See [Control Center in Pi](#control-center-in-pi) for confirmation and persistence boundaries.
 
 **Codex banked resets show counts and per-reset local expiry** in `/usage` and the Control Center. Press **u** in `/usage` or select **Usage → Use or check banked reset** for Cancel-first, active-account use or pending-attempt checks; stored-profile previews stay read-only. See [Use or check a banked reset](#use-or-check-a-banked-reset).
@@ -15,6 +17,7 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 | Area | What ships |
 | --- | --- |
 | Control Center | **Ctrl+Option+O** or `/osdyConfig` opens ten categories, including confirmed TODO/Agents provider selection and explicit per-profile Codex quota previews. |
+| Audio | Shared bundled default, per-event custom paths, and persistent automatic-audio mute; [explicit tests remain available](#audio-notifications). |
 | Local analytics (1.10.0) | `/osdy-usage` opens Summary, Profiles, Models, and History pages for recorded tokens and estimated cost—not billing or subscription quota. |
 | Themes introduced in 1.11.0 | Spider-Man Classic, Miles Morales, and Spider-Verse add three distinct dark palettes. |
 | Themes introduced in 1.9.0 | Halloween and Halloween Killer add two dark palettes. |
@@ -85,7 +88,7 @@ Positive counts also trigger a best-effort read-only reset-details GET within th
 - A selection shows **Saving** until persistence finishes and **Saved globally** only on success. Failed saves retain the live preference but report **could not be saved**; select again to retry. Application errors report **Not saved**, without claiming the runtime change succeeded. Duplicate selections are ignored while saving.
 - **Git** shows the current branch (or detached HEAD), changed-entry count/clean status, and the current widget position as a read-only session detail. Working-tree enablement applies and saves through the same owner as `/osdy-pi working-tree`; Git inspection never writes Git. `/osdy-pi diff` and position commands are unchanged.
 - **Sounds** shows each event's saved and effective path/source. Configure opens a single-line path editor **inside this overlay**: enter a readable `.mp3`/`.wav` path, then **Enter** to validate and save immediately, or **Esc** to cancel editing. Relative paths resolve against the project directory and save as absolute paths. Clear removes only that event's saved path from the existing v1 audio store (`<agent-dir>/extensions/osdy-pi/audio-notifications.json`). Notifications read this store afresh; refresh failures are reported separately from save failures.
-- Sounds' master enablement is **unavailable**: the existing schema has paths, not an enable switch or presets. Startup `--osdy-pi-sound-<event>` flags override saved paths, so **clearing a saved path does not disable flag-configured playback**. Only **Test effective** explicitly plays a sound; opening categories and configuring paths never play. Tests report unavailable files/platforms or playback failures; playback remains macOS/Windows only. The legacy `/osdy-pi sound setup` wizard is preserved.
+- **Sounds → Mute automatic audio / Enable automatic audio** is a persistent master switch, enabled by default (including existing v1 files). Muting suppresses all automatic event sounds, even startup-flag paths, without losing saved paths or changing visual notifications. It applies to the next notification without reload; already-started playback is not stopped. **Test effective** still plays while muted; opening categories and configuring paths never play. Startup `--osdy-pi-sound-<event>` flags override saved paths, so **clearing a saved path does not disable flag-configured playback**. Tests report unavailable files/platforms or playback failures; playback remains macOS/Windows only. Configure, Clear, and the legacy `/osdy-pi sound setup` wizard preserve the master state.
 - **Account** shows one row per validated profile, marked **Active** and **Default** where applicable. Select a profile, then use its visible context bar: **v View usage**, **s Switch** (inactive profiles), **d Set default**, and **c Clear default** (when a default exists). **v** or **Enter** explicitly queries that profile's stored Codex credentials without activating it; no second action list appears. Opening, navigating or highlighting never queries; stored profiles are never polled. A dedicated quota view reuses `/usage` dashboard content: Session/Weekly cards, additional bucket groups, remaining-capacity bars, resets, and the quotas/account summary with plan and credits when available. Identity belongs to the selected stored profile; unknown provider/model metadata is labeled honestly. Checked and updated times use local time; absent data is unknown, not zero. Refresh/Back controls and query feedback stay pinned while long dashboard content scrolls. **r Refresh** repeats the selected profile query; **s Switch**, when available, confirms activation of the currently viewed inactive profile. Cancelling that confirmation preserves the quota view and scroll position. **b Back** or **Esc** returns to the overview with the profile selected, without closing the overlay. In quota details, **↑/↓** selects Refresh/Back and **Enter** activates it; **Page Up/Down** and **Home/End** scroll long quota data. Switch, set default, and clear default require an **in-screen confirmation** with Cancel selected initially; **Esc** cancels confirmation without closing the overlay. Single blank separators group the confirmation title, complete effects, choices, and instructions; gaps yield on short viewports. Resize if the full confirmation cannot fit—acceptance stays hidden and blocked. Switching through `/osdyConfig` waits for Pi to become idle; Ctrl+Option+O refuses busy account changes. Successful switching activates through the existing backend and refreshes subscription usage. Login remains Pi-owned (`/login`); create/rename/remove remain available in `/osdy-account`. Category navigation never changes profiles or credentials.
 - **Usage** shows the runtime's cached active Codex subscription quota (remaining-capacity bars and percentages, window, reset/fetch times) and the existing local history owner's recorded token/cache totals, cost gaps, and model detail. Select **Range: day/week/month** for the current local calendar period; toggle **Accounts: all/current** for local analytics (unmanaged when no valid current profile exists). Quota always belongs to the active account, not the analytics filter; local token/cost totals never become quota percentages. Select **Refresh quota and local history** explicitly; rendering and filters never fetch. Empty, loading, unavailable, and limited/incomplete coverage are reported honestly. Estimates are not billing or subscription quota. `/usage` remains the subscription dashboard; `/osdy-usage` remains local analytics.
 - **Esc** closes without undoing live or saved changes, except when cancelling a confirmation/input or returning from Account quota details. Account read-only queries are cancelled on Back/Esc, category exit or close; late results are ignored even if cancellation is not honored. Other in-flight operations still finish and are not claimed cancelled. Late results cannot replace a closed overlay or another category. On narrow terminals, categories and details share the viewport; use Tab to switch.
@@ -323,7 +326,7 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 | Status | Six activity labels with compact per-state glyphs and a shared theme-color pulse, responsive footer metrics, dynamic extension statuses, and Codex subscription quota with low-capacity emphasis |
 | Local analytics | Four keyboard-selectable pages with shared filters, token charts, estimated cost, and private metadata-only history from new assistant turns |
 | Git | Working-tree summary and a centered, filterable diff panel |
-| Audio | Optional event sounds on macOS and Windows |
+| Audio | Default-on event sounds on macOS and Windows, with master mute and custom paths |
 
 <img width="1280" height="433" alt="Osdy Pi header and editor" src="https://github.com/user-attachments/assets/20c7624d-9ad8-4494-97fb-6b6d81aaf328" />
 
@@ -554,7 +557,7 @@ Use `working-tree position top` or `bottom` to place the summary above or below
 
 ## Audio notifications
 
-Osdy Pi can play readable `.mp3` or `.wav` files on macOS and Windows. Other platforms safely skip playback. macOS playback requires the system `afplay` command; Windows playback requires `powershell.exe` and the Windows Media Player COM component (`WMPlayer.OCX`).
+Osdy Pi plays one shared, short, subtle original bundled WAV by default for every unconfigured audio event on macOS and Windows. Automatic audio is enabled by default; mute it in **Sounds** to turn it off without changing visual alerts. Custom readable `.mp3` or `.wav` files can replace the default per event. Other platforms safely skip playback. macOS playback requires the system `afplay` command; Windows playback requires `powershell.exe` and the Windows Media Player COM component (`WMPlayer.OCX`).
 
 | Event | Current meaning |
 | --- | --- |
@@ -563,7 +566,9 @@ Osdy Pi can play readable `.mp3` or `.wav` files on macOS and Windows. Other pla
 | `permission` | Hook is available but dormant until an explicit Pi approval integration uses it. |
 | `question` | Hook is available but dormant until an explicit Pi question integration uses it. |
 
-Run the guided wizard:
+To mute or re-enable automatic audio, open `/osdyConfig` → **Sounds** and select **Mute automatic audio / Enable automatic audio**. Saved paths stay intact; **Test effective** remains available while muted.
+
+Run the guided wizard to configure paths (without changing the master switch):
 
 ```text
 /osdy-pi sound setup
@@ -581,7 +586,7 @@ pi \
   --osdy-pi-sound-question /absolute/path/question.wav
 ```
 
-Precedence is startup flag, then saved global setting, then unconfigured. Empty flags do not override saved settings; relative startup paths resolve from the current working directory, while the wizard saves normalized absolute paths. Missing, unreadable, or unsupported files are skipped safely.
+Path precedence is **startup flag → saved global path → bundled default**. Clearing a saved path (or choosing **Use bundled default** in the wizard) restores the default unless a startup flag overrides. The bundled asset resolves relative to the installed module, not the project directory or home. The master mute suppresses automatic playback from every source; explicit **Test effective** can still play the default while muted. Empty flags do not override saved settings; relative startup paths resolve from the current working directory, while the wizard saves normalized absolute paths. Invalid configured paths (missing, unreadable, or unsupported) are skipped safely **without falling back** to the default.
 
 ## Local install and development
 
@@ -638,9 +643,9 @@ An isolated agent directory does **not** make custom audio paths or real provide
 - Account (manual): with disposable profiles only, check Cancel-first switch/set-default/clear-default confirmations, Esc cancellation, idle switching, and current/default labels. Verify Ctrl+Option+O refuses all three changes while busy, succeeds when idle, and `/osdyConfig` still waits for idle. Check one row per profile with **v/s/d/c** context actions and **Enter** usage fallback, without a second action list. From **v** quota details, check eligible **s Switch** opens the same Cancel-first confirmation, with blank separators between the title/effects, choices, and instructions; Cancel/Esc must retain the quota view and scroll position. Check gaps yield on short viewports without hiding safety content or enabling acceptance when the full confirmation cannot fit. Check remaining-capacity bars, **r Refresh**, **b Back/Esc** returning to the selected profile, long-view scrolling, no query on navigation, no stored-profile polling, and cancellation on exit. Create/rename/remove stay in `/osdy-account`, login in `/login`.
 - Subscription quota (manual): compare **Ctrl+Option+U** and `/usage` (Ctrl+Alt+U on other platforms), including **r Refresh** and Esc/q closing. Verify actual terminal chord delivery; use `/usage` if intercepted or unsupported.
 - Usage (manual): check day/week/month and all/current filters, empty/unavailable/limited states, and explicit refresh. Authenticated quota and post-switch account correctness need an intentionally authorized live provider check; local estimates are not billing.
-- Sounds (manual): use disposable readable `.mp3`/`.wav` files to check configure, cancel, clear, and startup-flag precedence. Only choose **Test effective** when playback is intended; actual macOS/Windows playback still needs a live check.
+- Sounds (manual): use disposable readable `.mp3`/`.wav` files to check configure, cancel, clear, and startup-flag precedence. Only choose **Test effective** when playback is intended. The user reported successful live playback of the bundled default; exhaustive macOS/Windows coverage still needs a live check.
 
-The user confirmed physical Ctrl+Option+O and Ctrl+Option+U delivery on one Mac terminal; other terminals may intercept or not support these chords. Live TUI appearance, real account switching/authenticated quota, and actual audio playback remain unverified; this checklist is not a recorded full pass.
+The user confirmed physical Ctrl+Option+O and Ctrl+Option+U delivery on one Mac terminal; other terminals may intercept or not support these chords. The user also reported that the bundled default audio works correctly in their live session. Other live TUI appearance, real account switching/authenticated quota, and exhaustive audio/platform coverage remain unverified; this checklist is not a recorded full pass.
 
 Install a local checkout into Pi with:
 

package/extensions/osdy-pi/assets/PROVENANCE.md

@@ -25,3 +25,24 @@ The exporter reads the landing without modifying it and writes only the adjacent
 The assistant marker uses Pi's real `Image`, at most 3 columns × 2 rows. At default 9 × 18 pixel cells it reserves 3 × 1 on Kitty and 3 × 2 on iTerm2. iTerm2 sends `height=auto`, so width is additionally bounded using current cell geometry. Narrow widths down to 2 columns remain safe; invalid widths render an empty row.
 
 PNG preview was inspected. Automated protocol tests are not a live Kitty/iTerm2 visual check; legibility at tiny terminal size still requires the user's trial. Emoji fallback and stored marker lifecycle are unchanged.
+
+# Original bundled notification sound
+
+`notification-default.wav` is an original synthesized two-note chime created for Osdy Pi, shared by every unconfigured audio event. No recording, external asset, download, or OS sound is used. Distributed under the repository's MIT license.
+
+## Reproduction
+
+Generate a 44-byte canonical little-endian RIFF/WAVE header followed by 4,320 signed PCM16 mono samples at 24,000 Hz (180 ms). Header: format chunk size 16, audio format 1, channels 1, sample rate 24000, byte rate 48000, block alignment 2, bits per sample 16, data size 8640, RIFF size 8676. Total file size: 8684 bytes.
+
+For sample index `i = 0..4319`, let `t = i / 24000`. For each note with start `s` and frequency `f`, set `u = (t - s) / 0.11` and:
+
+```js
+note(s, f) = u <= 0 || u >= 1
+  ? 0
+  : Math.sin(Math.PI * u) ** 2 * Math.sin(2 * Math.PI * f * (t - s));
+sample = Math.round(1800 * (note(0, 660) + note(0.07, 880)));
+```
+
+Write each sample with Node's `Buffer.writeInt16LE` at offset `44 + i * 2`. The squared-sine envelope provides smooth attack and release; the low amplitude is intentionally subtle. Regeneration uses JavaScript double-precision arithmetic and `Math.round`, not normalization, dithering, randomness, or metadata. Subjective sound quality and live macOS/Windows playback remain manual checks.
+
+SHA-256: `89f8e5e70edacb8c5232c3384d704906d5c6f8aa619f4c988a72be23636955dc`.

package/extensions/osdy-pi/audio-default-sound.test.ts

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GlobalAudioNotificationSettings } from "./audio-notification-types.js";
+registerHooks({
+	resolve(specifier, context, next) {
+		if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+			const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+			if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+		}
+		return next(specifier, context);
+	},
+	load(url, context, next) {
+		if (url.endsWith(".ts")) return { format: "module", shortCircuit: true,
+			source: ts.transpileModule(readFileSync(fileURLToPath(url), "utf8"), {
+				compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+			}).outputText };
+		return next(url, context);
+	},
+});
+const { resolveAudioNotificationSoundFromSettings, getEffectiveAudioNotificationPath } = await import("./audio-notification-config.js");
+const { createAudioNotificationService } = await import("./audio-notification-service.js");
+const { bindControlCenterSounds } = await import("./control-center-sounds.js");
+const { AUDIO_NOTIFICATION_EVENTS } = await import("./audio-notification-types.js");
+const bundled = fileURLToPath(new URL("./assets/notification-default.wav", import.meta.url));
+const pi = { getFlag: () => "" } as unknown as ExtensionAPI;
+const ctx = { cwd: "/unrelated-project" } as ExtensionContext;
+
+void test("every absent event selects the same readable module-relative bundled default", async () => {
+	const settings: GlobalAudioNotificationSettings = { version: 1, enabled: true, sounds: {} };
+	for (const event of AUDIO_NOTIFICATION_EVENTS) {
+		assert.deepEqual(getEffectiveAudioNotificationPath(pi, settings, event), { source: "bundled-default", path: bundled });
+		assert.deepEqual(await resolveAudioNotificationSoundFromSettings(pi, ctx, event, settings),
+			{ ok: true, event, path: bundled, source: "bundled-default" });
+		const blank = { ...settings, sounds: { [event]: "  " } };
+		assert.deepEqual(getEffectiveAudioNotificationPath(pi, blank, event), { source: "bundled-default", path: bundled });
+	}
+});
+
+void test("saved and flag paths outrank default; invalid explicit paths never fall back", async () => {
+	for (const event of AUDIO_NOTIFICATION_EVENTS) {
+		const settings: GlobalAudioNotificationSettings = { version: 1, enabled: true, sounds: { [event]: bundled } };
+		assert.deepEqual(await resolveAudioNotificationSoundFromSettings(pi, ctx, event, settings),
+			{ ok: true, event, path: bundled, source: "global" });
+		const flagged = { getFlag: () => bundled } as unknown as ExtensionAPI;
+		assert.deepEqual(await resolveAudioNotificationSoundFromSettings(flagged, ctx, event, settings),
+			{ ok: true, event, path: bundled, source: "startup-flag" });
+		for (const invalid of ["/missing-notification.wav", "/unsupported.txt", "relative.wav"]) {
+			const saved = { ...settings, sounds: { [event]: invalid } };
+			const invalidSaved = await resolveAudioNotificationSoundFromSettings(pi, ctx, event, saved);
+			assert.equal(invalidSaved.ok, false);
+			assert.equal(invalidSaved.source, "global");
+			const badFlag = { getFlag: () => invalid } as unknown as ExtensionAPI;
+			const result = await resolveAudioNotificationSoundFromSettings(badFlag, ctx, event, settings);
+			assert.equal(result.ok, false);
+			assert.equal(result.source, "startup-flag");
+		}
+	}
+});
+
+void test("bundled WAV is short PCM16 mono with a nonzero low-peak smoothly bounded waveform", () => {
+	const wav = readFileSync(bundled);
+	assert.equal(wav.toString("ascii", 0, 4), "RIFF");
+	assert.equal(wav.readUInt32LE(4), wav.length - 8);
+	assert.equal(wav.toString("ascii", 8, 16), "WAVEfmt ");
+	assert.equal(wav.readUInt32LE(16), 16);
+	assert.equal(wav.readUInt16LE(20), 1);
+	assert.equal(wav.readUInt16LE(22), 1);
+	assert.equal(wav.readUInt32LE(24), 24000);
+	assert.equal(wav.readUInt32LE(28), 48000);
+	assert.equal(wav.readUInt16LE(32), 2);
+	assert.equal(wav.readUInt16LE(34), 16);
+	assert.equal(wav.toString("ascii", 36, 40), "data");
+	assert.equal(wav.readUInt32LE(40), wav.length - 44);
+	const count = (wav.length - 44) / 2;
+	assert.equal(count / 24000, 0.18);
+	let peak = 0;
+	let maxStep = 0;
+	let previous = 0;
+	for (let i = 0; i < count; i++) {
+		const sample = wav.readInt16LE(44 + i * 2);
+		peak = Math.max(peak, Math.abs(sample));
+		maxStep = Math.max(maxStep, Math.abs(sample - previous));
+		previous = sample;
+	}
+	assert.ok(peak > 500 && peak <= 3000);
+	assert.ok(maxStep < 600);
+	assert.equal(wav.readInt16LE(44), 0);
+	assert.equal(previous, 0);
+});
+
+void test("default automatic playback obeys mute; explicit Test and clear restore default without changing mute", { timeout: 5000 }, async () => {
+	let settings: GlobalAudioNotificationSettings = { version: 1, enabled: false, sounds: {} };
+	const store = { path: "/unused", load: () => Promise.resolve(settings),
+		save: (value: GlobalAudioNotificationSettings) => { settings = value; return Promise.resolve(); } };
+	const played: string[] = [];
+	let complete = () => {};
+	const playback = { platform: "darwin" as const, play: (path: string) => {
+		played.push(path);
+		if (played.length === 4) complete();
+		return Promise.resolve();
+	} };
+	const service = createAudioNotificationService(pi, playback, store);
+	const sounds = bindControlCenterSounds(pi, ctx, store, playback);
+	for (const event of AUDIO_NOTIFICATION_EVENTS) service.notify(event, ctx);
+	await new Promise<void>(resolve => setImmediate(resolve));
+	assert.deepEqual(played, []);
+	assert.equal((await sounds.apply({ kind: "sound-test", event: "completion" })).failed, false);
+	assert.deepEqual(played, [bundled]);
+	const view = await sounds.read();
+	assert.match(view.note, /bundled default/i);
+	assert.match(view.rows[1]?.details?.join(" | ") ?? "", /Effective \(bundled-default\)/);
+	settings = { ...settings, sounds: { completion: bundled } };
+	assert.equal((await sounds.apply({ kind: "sound-clear", event: "completion" })).failed, false);
+	assert.equal(settings.enabled, false);
+	assert.deepEqual(settings.sounds, {});
+	const flagged = { getFlag: () => bundled } as unknown as ExtensionAPI;
+	assert.equal(getEffectiveAudioNotificationPath(flagged, settings, "completion").source, "startup-flag", "clearing never removes flag precedence");
+	assert.equal((await sounds.apply({ kind: "sound-test", event: "completion" })).failed, false);
+	played.length = 0;
+	assert.equal((await sounds.apply({ kind: "sound-enabled", value: true })).failed, false);
+	const completed = new Promise<void>(resolve => { complete = resolve; });
+	for (const event of AUDIO_NOTIFICATION_EVENTS) service.notify(event, ctx);
+	await completed;
+	assert.deepEqual(played, Array<string>(4).fill(bundled));
+});

package/extensions/osdy-pi/audio-default-wizard.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GlobalAudioNotificationSettings } from "./audio-notification-types.js";
+registerHooks({ resolve(specifier, context, next) {
+	if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+		const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+		if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+	}
+	return next(specifier, context);
+} });
+const { runSoundSetupWizard } = await import("./sound-setup-wizard.js");
+
+void test("wizard offers bundled default, explains flag precedence, and saves no asset paths while preserving mute", async () => {
+	const writes: GlobalAudioNotificationSettings[] = [];
+	const notices: string[] = [];
+	let summary = "";
+	const ctx = { cwd: "/unrelated-project", ui: {
+		select: (_title: string, options: string[]) => {
+			const choice = "Use bundled default (startup flags still override)";
+			assert.ok(options.includes(choice));
+			return Promise.resolve(choice);
+		},
+		confirm: (_title: string, value: string) => { summary = value; return Promise.resolve(true); },
+		notify: (value: string) => { notices.push(value); },
+	} } as unknown as ExtensionContext;
+	await runSoundSetupWizard(ctx, { path: "/unused", load: () => Promise.resolve({ version: 1, enabled: false, sounds: {} }),
+		save: value => { writes.push(value); return Promise.resolve(); } });
+	assert.deepEqual(writes, [{ version: 1, enabled: false, sounds: {} }]);
+	assert.match(summary, /completion: \(bundled default; startup flags still override\)/);
+	assert.match(notices.join(" | "), /bundled default/i);
+});

package/extensions/osdy-pi/audio-master-mute.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GlobalAudioNotificationSettings } from "./audio-notification-types.js";
+registerHooks({
+	resolve(specifier, context, next) {
+		if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+			const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+			if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+		}
+		return next(specifier, context);
+	},
+	load(url, context, next) {
+		if (url.endsWith(".ts")) return { format: "module", shortCircuit: true,
+			source: ts.transpileModule(readFileSync(fileURLToPath(url), "utf8"), {
+				compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+			}).outputText };
+		return next(url, context);
+	},
+});
+const { createAudioSoundSettingsStore } = await import("./audio-sound-settings.js");
+const { createAudioNotificationService } = await import("./audio-notification-service.js");
+const { bindControlCenterSounds } = await import("./control-center-sounds.js");
+const { AUDIO_NOTIFICATION_EVENTS, AUDIO_NOTIFICATION_FLAG_NAMES } = await import("./audio-notification-types.js");
+
+void test("v1 defaults/old files enable automatic audio; only boolean false mutes and roundtrips", async () => {
+	const previous = process.env.PI_CODING_AGENT_DIR;
+	process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "osdy-master-settings-"));
+	try {
+		const store = createAudioSoundSettingsStore();
+		assert.deepEqual(await store.load(), { version: 1, enabled: true, sounds: {} });
+		await store.save({ version: 1, enabled: false, sounds: { completion: "/saved.wav" } });
+		assert.deepEqual(await store.load(), { version: 1, enabled: false, sounds: { completion: "/saved.wav" } });
+		for (const enabled of [undefined, true, "false", 0, null]) {
+			writeFileSync(store.path, JSON.stringify({ version: 1, enabled, sounds: { completion: "/old.wav" } }));
+			assert.deepEqual(await store.load(), { version: 1, enabled: true, sounds: { completion: "/old.wav" } });
+		}
+		for (const content of ["invalid json", JSON.stringify({ version: 2, enabled: false })]) {
+			writeFileSync(store.path, content);
+			assert.deepEqual(await store.load(), { version: 1, enabled: true, sounds: {} });
+		}
+	} finally {
+		if (previous === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previous;
+	}
+});
+
+void test("automatic master gate covers every global/startup sound and refreshes next event; explicit tests bypass", { timeout: 5000 }, async () => {
+	const root = mkdtempSync(join(tmpdir(), "osdy-master-playback-"));
+	const sound = join(root, "sound.wav");
+	writeFileSync(sound, "mock wave bytes");
+	const ctx = { cwd: root } as ExtensionContext;
+	for (const source of ["global", "startup-flag"] as const) {
+		let settings: GlobalAudioNotificationSettings = { version: 1, enabled: false,
+			sounds: Object.fromEntries(AUDIO_NOTIFICATION_EVENTS.map(event => [event, sound])) };
+		let loads = 0;
+		const played: string[] = [];
+		const store = { path: "/unused", load: () => { loads++; return Promise.resolve(settings); },
+			save: (value: GlobalAudioNotificationSettings) => { settings = value; return Promise.resolve(); } };
+		let flagReads = 0;
+		const pi = { getFlag: (name: string) => {
+			flagReads++;
+			return source === "startup-flag" && Object.values(AUDIO_NOTIFICATION_FLAG_NAMES).includes(name) ? "sound.wav" : "";
+		} } as ExtensionAPI;
+		let playbackComplete = () => {};
+		const playback = { platform: "darwin" as const, play: (path: string) => {
+			played.push(path);
+			if (played.length === 4) playbackComplete();
+			return Promise.resolve();
+		} };
+		const service = createAudioNotificationService(pi, playback, store);
+		const sounds = bindControlCenterSounds(pi, ctx, store, playback);
+		const notify = async (expectPlayback = false) => {
+			const completed = expectPlayback ? new Promise<void>(resolve => { playbackComplete = resolve; }) : Promise.resolve();
+			for (const event of AUDIO_NOTIFICATION_EVENTS) service.notify(event, ctx);
+			await completed;
+			// A turn drains the resolved store/gate and releases the per-event in-flight guard.
+			await new Promise<void>(resolve => setImmediate(resolve));
+		};
+		await notify();
+		assert.deepEqual(played, [], `${source} must be muted`);
+		assert.equal(loads, 4, "one fresh snapshot per notification");
+		assert.equal(flagReads, 0, "muted notifications never resolve even startup paths");
+		assert.equal((await sounds.apply({ kind: "sound-test", event: "completion" })).failed, false);
+		assert.deepEqual(played, [sound]);
+		played.length = 0;
+		settings = { ...settings, enabled: true };
+		loads = 0;
+		await notify(true);
+		assert.deepEqual(played, Array<string>(4).fill(sound));
+		assert.equal(loads, 4);
+		settings = { ...settings, enabled: false };
+		played.length = 0;
+		await notify();
+		assert.deepEqual(played, [], "same service observes re-mute without reload");
+	}
+});

package/extensions/osdy-pi/audio-notification-config.ts

@@ -1,6 +1,7 @@
 import { access, constants, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
@@ -147,7 +148,10 @@ export function getEffectiveAudioNotificationPath(
 	if (globalPath !== undefined) {
 		return { source: "global", path: globalPath };
 	}
-	return { source: "unconfigured" };
+	return {
+		source: "bundled-default",
+		path: fileURLToPath(new URL("./assets/notification-default.wav", import.meta.url)),
+	};
 }
 
 export async function resolveAudioNotificationSound(
@@ -156,7 +160,16 @@ export async function resolveAudioNotificationSound(
 	event: AudioNotificationEvent,
 	settingsStore: AudioSoundSettingsStore,
 ): Promise<ResolvedSoundFile> {
-	const globalSettings = await settingsStore.load();
+	return resolveAudioNotificationSoundFromSettings(pi, ctx, event, await settingsStore.load());
+}
+
+/** Resolve paths independently of master enablement so explicit tests still play. */
+export async function resolveAudioNotificationSoundFromSettings(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	event: AudioNotificationEvent,
+	globalSettings: GlobalAudioNotificationSettings,
+): Promise<ResolvedSoundFile> {
 	const effectivePath = getEffectiveAudioNotificationPath(
 		pi,
 		globalSettings,

package/extensions/osdy-pi/audio-notification-service.ts

@@ -3,7 +3,7 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import type { AudioSoundSettingsStore } from "./audio-sound-settings.js";
-import { resolveAudioNotificationSound } from "./audio-notification-config.js";
+import { resolveAudioNotificationSoundFromSettings } from "./audio-notification-config.js";
 import type { AudioNotificationEvent } from "./audio-notification-types.js";
 import type { AudioPlaybackAdapter } from "./audio-playback.js";
 
@@ -34,11 +34,14 @@ class DefaultAudioNotificationService implements AudioNotificationService {
 		event: AudioNotificationEvent,
 		ctx: ExtensionContext,
 	): Promise<void> {
-		const resolvedSound = await resolveAudioNotificationSound(
+		// One fresh snapshot gates all automatic audio, including startup flags.
+		const settings = await this.settingsStore.load();
+		if (!settings.enabled) return;
+		const resolvedSound = await resolveAudioNotificationSoundFromSettings(
 			this.pi,
 			ctx,
 			event,
-			this.settingsStore,
+			settings,
 		);
 		if (!resolvedSound.ok) return;
 		await this.playbackAdapter.play(resolvedSound.path);

package/extensions/osdy-pi/audio-notification-types.ts

@@ -23,10 +23,11 @@ export type AudioNotificationConfig = Partial<
 
 export type GlobalAudioNotificationSettings = {
 	version: 1;
+	enabled: boolean;
 	sounds: AudioNotificationConfig;
 };
 
-export type AudioConfigSource = "startup-flag" | "global" | "unconfigured";
+export type AudioConfigSource = "startup-flag" | "global" | "bundled-default" | "unconfigured";
 
 export type ResolvedSoundFile =
 	| {

package/extensions/osdy-pi/audio-sound-settings.ts

@@ -21,7 +21,7 @@ function getAgentDir(): string {
 }
 
 function createDefaultSettings(): GlobalAudioNotificationSettings {
-	return { version: GLOBAL_SETTINGS_VERSION, sounds: {} };
+	return { version: GLOBAL_SETTINGS_VERSION, enabled: true, sounds: {} };
 }
 
 function isAudioEvent(value: string): value is AudioNotificationEvent {
@@ -58,6 +58,8 @@ function normalizeLoadedSettings(
 
 	return {
 		version: GLOBAL_SETTINGS_VERSION,
+		// Old v1 files and invalid values retain automatic playback by default.
+		enabled: recordValue.enabled !== false,
 		sounds: normalizeSounds(recordValue.sounds),
 	};
 }

package/extensions/osdy-pi/control-center-git.test.ts

@@ -33,6 +33,8 @@ void test("Git reads branch/status only and delegates persisted enabled changes
 		["--no-optional-locks", "status", "--short", "--untracked-files=normal"],
 	]);
 	assert.deepEqual(applied, []);
+	assert.equal((await service.apply({ kind: "sound-enabled", value: false })).failed, true);
+	assert.deepEqual(applied, [], "sound master action cannot change Git preferences");
 	assert.equal((await service.apply({ kind: "git-enabled", value: false })).failed, false);
 	assert.deepEqual(applied, [false]);
 	assert.equal((await service.read()).rows[1]?.current, true);

package/extensions/osdy-pi/control-center-sounds.test.ts

@@ -16,7 +16,7 @@ registerHooks({ resolve(specifier, context, nextResolve) {
 const { createControlCenterSounds } = await import("./control-center-sounds.js");
 
 function fixture(platform: "darwin" | "unsupported" = "darwin") {
-	let settings: GlobalAudioNotificationSettings = { version: 1, sounds: { completion: "/saved.wav" } };
+	let settings: GlobalAudioNotificationSettings = { version: 1, enabled: false, sounds: { completion: "/saved.wav" } };
 	let saveFails = false;
 	let loadFails = false;
 	let playFails = false;
@@ -53,10 +53,12 @@ function fixture(platform: "darwin" | "unsupported" = "darwin") {
 void test("Sounds shows saved/effective paths and flag precedence without playing or saving", async () => {
 	const f = fixture();
 	const view = await f.service.read();
-	assert.match(view.summary, /Master.*unavailable/);
-	assert.match(view.rows[0]?.details?.join(" | ") ?? "", /saved: \/saved.wav.*Effective \(startup-flag\): \/flag.wav/);
+	assert.match(view.summary, /Automatic audio: muted/);
+	assert.match(view.rows[0]?.label ?? "", /Enable automatic audio/);
+	assert.match(view.rows[0]?.details?.join(" | ") ?? "", /explicit.*tests.*play/i);
+	assert.match(view.rows[1]?.details?.join(" | ") ?? "", /saved: \/saved.wav.*Effective \(startup-flag\): \/flag.wav/);
 	assert.match(view.note, /clearing.*does not disable/i);
-	assert.equal(view.rows.length, 12);
+	assert.equal(view.rows.length, 13);
 	assert.deepEqual(f.played, []); assert.deepEqual(f.writes, []);
 });
 
@@ -65,14 +67,29 @@ void test("configure validates before saving and refreshes; clear keeps v1 and o
 	assert.equal((await f.service.apply({ kind: "sound-set", event: "completion", path: "missing.wav" })).failed, true);
 	assert.equal(f.writes.length, 0);
 	assert.equal((await f.service.apply({ kind: "sound-set", event: "question", path: "valid.wav" })).failed, false);
-	assert.deepEqual(f.settings(), { version: 1, sounds: { completion: "/saved.wav", question: "/valid.wav" } });
+	assert.deepEqual(f.settings(), { version: 1, enabled: false, sounds: { completion: "/saved.wav", question: "/valid.wav" } });
 	const clear = await f.service.apply({ kind: "sound-clear", event: "completion" });
 	assert.equal(clear.failed, false);
-	assert.deepEqual(f.settings(), { version: 1, sounds: { question: "/valid.wav" } });
-	assert.match((await f.service.read()).rows[0]?.details?.join(" | ") ?? "", /saved: none.*Effective \(startup-flag\): \/flag.wav/);
+	assert.deepEqual(f.settings(), { version: 1, enabled: false, sounds: { question: "/valid.wav" } });
+	assert.match((await f.service.read()).rows[1]?.details?.join(" | ") ?? "", /saved: none.*Effective \(startup-flag\): \/flag.wav/);
 	assert.deepEqual(f.played, []);
 });
 
+void test("master toggle preserves all paths and exposes the inverse action", async () => {
+	const f = fixture();
+	assert.equal((await f.service.apply({ kind: "sound-enabled", value: true })).failed, false);
+	assert.deepEqual(f.settings(), { version: 1, enabled: true, sounds: { completion: "/saved.wav" } });
+	const view = await f.service.read();
+	assert.match(view.summary, /Automatic audio: enabled/);
+	assert.deepEqual(view.rows[0]?.action, { kind: "sound-enabled", value: false });
+	assert.equal((await f.service.apply({ kind: "sound-enabled", value: false })).failed, false);
+	assert.deepEqual(f.settings(), { version: 1, enabled: false, sounds: { completion: "/saved.wav" } });
+	assert.deepEqual(f.played, []);
+	f.failSave();
+	assert.equal((await f.service.apply({ kind: "sound-enabled", value: true })).failed, true);
+	assert.equal(f.settings().enabled, false);
+});
+
 void test("test playback is explicit, reports unavailable platforms and player failures", async () => {
 	const f = fixture();
 	assert.equal((await f.service.apply({ kind: "sound-test", event: "completion" })).failed, false);
@@ -95,7 +112,7 @@ void test("save errors and refresh errors never falsely report success", async (
 	const result = await h.service.apply({ kind: "sound-clear", event: "completion" });
 	assert.equal(result.failed, true);
 	assert.match(result.message, /Saved globally, but runtime refresh failed/);
-	assert.deepEqual(h.writes, [{ version: 1, sounds: {} }]);
+	assert.deepEqual(h.writes, [{ version: 1, enabled: false, sounds: {} }]);
 });
 
 void test("default validator rejects missing, unsupported and directory paths without saving", async () => {

package/extensions/osdy-pi/control-center-sounds.ts

@@ -22,19 +22,25 @@ export function createControlCenterSounds(dependencies: SoundDependencies): Cont
 		async read() {
 			const settings = await store.load();
 			return {
-				summary: "Master enablement: unavailable (path-only v1 settings)",
-				note: "Startup flags override saved paths; clearing a saved path does not disable flag-configured playback.",
-				rows: AUDIO_NOTIFICATION_EVENTS.flatMap((event) => {
-					const effective = dependencies.effective(settings, event);
-					const saved = settings.sounds[event];
-					const details = [`${event} saved: ${saved ?? "none"}`, `Effective (${effective.source}): ${effective.path ?? "none"}`];
-					return [
-						{ label: `Configure ${event}`,
-							current: false, details, action: { kind: "sound-configure" as const, event, path: saved ?? "" } },
-						{ label: `Clear saved ${event}`, current: false, details, action: { kind: "sound-clear" as const, event } },
-						{ label: `Test effective ${event}`, current: false, details, action: { kind: "sound-test" as const, event } },
-					];
-				}),
+				summary: `Automatic audio: ${settings.enabled ? "enabled" : "muted"}`,
+				note: "Startup flags override saved paths, then the bundled default. Clearing restores the bundled default unless a flag overrides; it does not disable flag-configured playback.",
+				rows: [
+					{ label: settings.enabled ? "Mute automatic audio" : "Enable automatic audio", current: false,
+						details: ["Mute all automatic sounds, including startup flags and the bundled default. Explicit sound tests still play.",
+							"Saved paths and visual notifications are unchanged. Applies to the next notification without reload; current playback is not stopped."],
+						action: { kind: "sound-enabled" as const, value: !settings.enabled } },
+					...AUDIO_NOTIFICATION_EVENTS.flatMap((event) => {
+						const effective = dependencies.effective(settings, event);
+						const saved = settings.sounds[event];
+						const details = [`${event} saved: ${saved ?? "none"}`, `Effective (${effective.source}): ${effective.path ?? "none"}`];
+						return [
+							{ label: `Configure ${event}`,
+								current: false, details, action: { kind: "sound-configure" as const, event, path: saved ?? "" } },
+							{ label: `Clear saved ${event}`, current: false, details, action: { kind: "sound-clear" as const, event } },
+							{ label: `Test effective ${event}`, current: false, details, action: { kind: "sound-test" as const, event } },
+						];
+					}),
+				],
 			};
 		},
 		async apply(action: ControlCenterServiceAction) {
@@ -57,15 +63,18 @@ export function createControlCenterSounds(dependencies: SoundDependencies): Cont
 					const validation = await (dependencies.validate ?? validateAudioNotificationPath)(action.path, { cwd: dependencies.cwd, mode: "global-save" });
 					if (!validation.ok) return { failed: true, message: `Invalid ${action.event} sound: ${validation.reason}. Use a readable .mp3 or .wav file. Not saved.` };
 					sounds[action.event] = validation.persistedPath;
-				} else delete sounds[action.event];
-				await store.save({ version: 1, sounds });
+				} else if (action.kind === "sound-clear") delete sounds[action.event];
+				await store.save({ ...settings, sounds,
+					enabled: action.kind === "sound-enabled" ? action.value : settings.enabled });
 			} catch (error) {
 				return { failed: true, message: `Not saved: ${message(error)}` };
 			}
 			// Event playback resolves the same store afresh each time; no separate runtime cache.
 			try {
 				await store.load();
-				return { failed: false, message: `Saved globally: ${action.event}. Runtime uses current saved paths; startup flags still take precedence.` };
+				return { failed: false, message: action.kind === "sound-enabled"
+					? `Saved globally: automatic audio ${action.value ? "enabled" : "muted"}. Applies to the next notification; explicit tests still play.`
+					: `Saved globally: ${action.event}. Runtime uses current saved paths; startup flags still take precedence.` };
 			} catch (error) {
 				return { failed: true, message: `Saved globally, but runtime refresh failed: ${message(error)}. Retry refresh by reopening Sounds.` };
 			}

package/extensions/osdy-pi/control-center.test.ts

@@ -276,6 +276,29 @@ void test("Agent direct letters never cross loading, query, save or text input b
 	assert.match(plain(account.panel.render(100)), /Loading stored-profile/); assert.equal(calls, 1); account.dispose();
 });
 
+void test("Sounds master action routes to its service, refreshes live, and never requests reload", async () => {
+	let enabled = true;
+	const actions: ControlCenterServiceAction[] = [];
+	let reloads = 0;
+	const f = fixture(undefined, undefined, { sounds: {
+		read: () => Promise.resolve({ summary: `Automatic audio: ${enabled ? "enabled" : "muted"}`, note: "Explicit tests still play.", rows: [
+			{ label: enabled ? "Mute automatic audio" : "Enable automatic audio", current: false, action: { kind: "sound-enabled", value: !enabled } },
+		] }),
+		apply: action => { actions.push(action); if (action.kind === "sound-enabled") enabled = action.value;
+			return Promise.resolve({ failed: false, message: "Saved globally" }); },
+	} }, () => { reloads++; });
+	for (let i = 0; i < 5; i++) f.panel.handleInput(down);
+	await settle();
+	assert.equal(actions.length, 0);
+	f.panel.handleInput(right); f.panel.handleInput("\r"); await settle();
+	assert.deepEqual(actions, [{ kind: "sound-enabled", value: false }]);
+	assert.match(plain(f.panel.render(100)), /Automatic audio: muted/);
+	f.panel.handleInput("\r"); await settle();
+	assert.deepEqual(actions[1], { kind: "sound-enabled", value: true });
+	assert.equal(reloads, 0);
+	f.dispose();
+});
+
 function fixture(names = ["dark", "light"], preferences?: ControlCenterPreferences,
 	services?: Pick<ControlCenterDependencies, "git" | "sounds" | "account" | "usage" | "todo" | "agents">,
 	reload?: ControlCenterDependencies["reload"]) {

package/extensions/osdy-pi/control-center.ts

@@ -16,6 +16,7 @@ export const CONTROL_CENTER_CATEGORIES = [
 export type ControlCenterCategory = (typeof CONTROL_CENTER_CATEGORIES)[number];
 export type ControlCenterServiceAction =
 	| { kind: "git-enabled"; value: boolean }
+	| { kind: "sound-enabled"; value: boolean }
 	| { kind: "sound-set"; event: AudioNotificationEvent; path: string }
 	| { kind: "sound-clear"; event: AudioNotificationEvent }
 	| { kind: "sound-test"; event: AudioNotificationEvent };
@@ -404,7 +405,7 @@ export class ControlCenter implements Component, Focusable {
 			};
 			return;
 		}
-		if (action.kind === "git-enabled" || action.kind === "sound-set" || action.kind === "sound-clear" || action.kind === "sound-test" || action.kind === "usage-refresh" || action.kind === "usage-range" || action.kind === "usage-account" || action.kind === "usage-detail") {
+		if (action.kind === "git-enabled" || action.kind === "sound-enabled" || action.kind === "sound-set" || action.kind === "sound-clear" || action.kind === "sound-test" || action.kind === "usage-refresh" || action.kind === "usage-range" || action.kind === "usage-account" || action.kind === "usage-detail") {
 			void this.activateService(action);
 			return;
 		}

package/extensions/osdy-pi/sound-setup-wizard.test.ts

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GlobalAudioNotificationSettings } from "./audio-notification-types.js";
+registerHooks({ resolve(specifier, context, next) {
+	if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+		const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+		if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+	}
+	return next(specifier, context);
+} });
+const { runSoundSetupWizard } = await import("./sound-setup-wizard.js");
+
+void test("legacy wizard preserves mute when setting/clearing paths; cancellation never saves", async () => {
+	const root = mkdtempSync(join(tmpdir(), "osdy-master-wizard-"));
+	const sound = join(root, "sound.wav");
+	writeFileSync(sound, "mock wave bytes");
+	for (const confirmed of [true, false]) {
+		const settings: GlobalAudioNotificationSettings = { version: 1, enabled: false, sounds: { completion: sound, permission: sound } };
+		const writes: GlobalAudioNotificationSettings[] = [];
+		const actions = ["Clear saved sound", "Set or replace", "Skip", "Use bundled default (startup flags still override)"];
+		const ctx = { cwd: root, ui: { select: () => Promise.resolve(actions.shift()), input: () => Promise.resolve(sound),
+			confirm: () => Promise.resolve(confirmed), notify: () => {} } } as unknown as ExtensionContext;
+		await runSoundSetupWizard(ctx, { path: "/unused", load: () => Promise.resolve(settings),
+			save: value => { writes.push(value); return Promise.resolve(); } });
+		assert.deepEqual(writes, confirmed ? [{ version: 1, enabled: false, sounds: { error: sound, permission: sound } }] : []);
+	}
+});

package/extensions/osdy-pi/sound-setup-wizard.ts

@@ -14,7 +14,7 @@ const CANCEL_SETUP_OPTION = "Cancel setup";
 const KEEP_CURRENT_OPTION = "Keep current";
 const SET_OR_REPLACE_OPTION = "Set or replace";
 const CLEAR_SAVED_OPTION = "Clear saved sound";
-const LEAVE_UNCONFIGURED_OPTION = "Leave unconfigured";
+const LEAVE_UNCONFIGURED_OPTION = "Use bundled default (startup flags still override)";
 
 function formatValidationReason(reason: AudioPathValidationReason): string {
 	switch (reason) {
@@ -35,7 +35,7 @@ function formatValidationReason(reason: AudioPathValidationReason): string {
 
 function createSummary(settings: AudioNotificationConfig): string {
 	return AUDIO_NOTIFICATION_EVENTS.map((event) => {
-		const value = settings[event] ?? "(unconfigured)";
+		const value = settings[event] ?? "(bundled default; startup flags still override)";
 		return `${event}: ${value}`;
 	}).join("\n");
 }
@@ -144,6 +144,7 @@ async function revalidateStagedSettings(
 
 function createSettingsPayload(
 	stagedSettings: AudioNotificationConfig,
+	enabled: boolean,
 ): GlobalAudioNotificationSettings {
 	const sounds: AudioNotificationConfig = {};
 	for (const event of AUDIO_NOTIFICATION_EVENTS) {
@@ -152,17 +153,18 @@ function createSettingsPayload(
 			sounds[event] = value;
 		}
 	}
-	return { version: 1, sounds };
+	return { version: 1, enabled, sounds };
 }
 
 export async function runSoundSetupWizard(
 	ctx: ExtensionContext,
 	settingsStore: AudioSoundSettingsStore,
 ): Promise<void> {
-	const currentSettings = (await settingsStore.load()).sounds;
+	const settings = await settingsStore.load();
+	const currentSettings = settings.sounds;
 	const stagedSettings: AudioNotificationConfig = { ...currentSettings };
 	ctx.ui.notify(
-		`Osdy Pi sound setup. Supported formats: .mp3 and .wav. Global config: ${settingsStore.path}`,
+		`Osdy Pi sound setup. Supported formats: .mp3 and .wav. No saved path uses the bundled default; startup flags still override. Global config: ${settingsStore.path}`,
 		"info",
 	);
 
@@ -187,7 +189,7 @@ export async function runSoundSetupWizard(
 		}
 		if (selectedAction === CLEAR_SAVED_OPTION) {
 			delete stagedSettings[event];
-			ctx.ui.notify(`Cleared saved ${event} sound.`, "info");
+			ctx.ui.notify(`Cleared saved ${event} sound. Uses bundled default unless a startup flag overrides.`, "info");
 			continue;
 		}
 		if (selectedAction === SET_OR_REPLACE_OPTION) {
@@ -215,6 +217,6 @@ export async function runSoundSetupWizard(
 		return;
 	}
 
-	await settingsStore.save(createSettingsPayload(stagedSettings));
+	await settingsStore.save(createSettingsPayload(stagedSettings, settings.enabled));
 	ctx.ui.notify("Osdy Pi sound settings saved.", "info");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "osdy-pi",
-	"version": "1.11.12",
+	"version": "1.11.13",
 	"description": "Osdy Pi package: themes, header, and custom editor for Pi.",
 	"license": "MIT",
 	"type": "module",
@@ -83,7 +83,7 @@
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.46.3"
 	},
-	"releaseSource": "3939affdb14faf94efa56c142a1927670b0df954",
+	"releaseSource": "89f3886287c5062fa45501a1a1869d25e7d46dac",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/OsdyOrtiz/Osdy-Pi.git"