osdy-pi 1.11.11 → 1.11.13

package/README.md

@@ -6,13 +6,18 @@ 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).
+
 **1.11.0 adds three Spider-Man-inspired dark palettes**, bringing the bundle to **23 themes**. It retains the four-page local usage analytics introduced in 1.10.0, with shared period and profile/provider/model filters, keyboard navigation, and metadata-only history. These version introductions are historical, not a fixed latest-version claim. After npm Trusted Publishing is configured, pushes to main (including direct pushes) run checks and attempt to publish an automatically allocated patch to npm. Failed checks publish nothing; authentication or registry failures can also stop publication. Verify the resolved npm version before installing. Maintainers: [automatic npm publishing setup](https://github.com/OsdyOrtiz/Osdy-Pi/blob/main/docs/npm-publishing.md).
 
 | 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. |
@@ -70,6 +75,10 @@ On macOS, **Option = Alt** in Pi's shortcut names: these bindings register as `c
 
 Ctrl+Option+U opens the existing `/usage` dashboard with the same refresh behavior; it does not open `/osdy-usage`.
 
+When Codex reports an available banked reset count, `/usage`, **Account → View usage**, and the **Usage** category show **Banked resets: N**, including zero. Unknown counts are omitted. Banked resets are separate from paid **Credits** and legacy **Credit resets**; local analytics filters do not change the count. Displaying it never consumes a reset or changes the compact footer.
+
+Positive counts also trigger a best-effort read-only reset-details GET within the same timeout budget. Dashboards label listed resets **Reset 1:**, **Reset 2:**, and so on, with expiry date/time in your machine's **local timezone**; the Usage count row includes these lines in its expanded help (`?`). Missing or invalid expiry shows **Expiry not provided**. Past dates show **expired** with **(cached; local time)** and are excluded from new-reset selection. **Reset expiry details unavailable** or **Partial expiry details: M of N resets listed** identifies missing or incomplete details. The usage summary remains the count authority even when details are empty, capped, inconsistent, or fail. Quotas and the count remain visible on details failure.
+
 - Use **↑/↓**, **Home/End**, or **Page Up/Down** to navigate; **Tab** or **←/→** switches between categories and details. **Enter** selects. Single blank lines separate the heading, summary, compact options, selected-item help, status, and action hints—not individual options. Gaps yield on short viewports so the selected option and controls remain reachable. Press **?** to expand/collapse the selected help and view notes; resize if expanded help is clipped. Confirmation effects remain complete, and **?** never toggles help during confirmation, path editing, loading, querying, or saving.
 - TODO shows configured selection, current eligibility, and actually loaded SDK registration separately. Opt-in/out requires an idle session and a Cancel-first inline confirmation naming the target, owned Gentle filter effects, and reload. Successful selection closes/disposes the panel and releases its editor hold before automatic command reload or the Ctrl+Option+O manual-reload notice described above; restart Pi if reload fails. Rejections stay in the panel. No installs or task-history changes occur; legacy `/osdy-pi todo on|off|status` remains available.
 - Agents shows concise **Joker / Gentle** choices without activating anything. With detail focus, visible lowercase-only **j Joker / g Gentle** letters open the existing confirmation directly; only available, unambiguous rows get shortcuts. **↑/↓ + Enter** remains the fallback. Profile and Agent selections survive category navigation; unavailable choices fall back to the current row. Letters never bypass category focus, confirmation, path input, loading, querying, or saving. Selection is idle-only and Cancel-first confirmed, naming the real target, possible Joker installation, owned agent filters, and preserved unrelated resources. Normal personal Pi only: `pi:dev` and isolated/override sessions are blocked, never redirected to personal settings. Success closes/disposes the panel and releases its editor hold before automatic command reload or the Ctrl+Option+O manual-reload notice described above; restart Pi if reload fails. Legacy `/osdy-pi agents setup|on|off|status` is unchanged.
@@ -79,9 +88,9 @@ Ctrl+Option+U opens the existing `/usage` dashboard with the same refresh behavi
 - 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` and `/osdy-usage` remain unchanged.
+- **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.
 
 This modal requires Pi's terminal UI, not RPC, JSON, or print mode. `/osdy-pi` remains the legacy extension command; the external shell command `osdy` (`bin/osdy.mjs`) remains the isolated launcher described below.
@@ -229,7 +238,7 @@ For a project-local installation, run `pi remove -l npm:@juicesharp/rpiv-todo` i
 
 **Quick path:** `/osdyConfig` → **Account** → select a profile → **v** (or **Enter**) for quota bars. Use **r Refresh** to query again or **b Back** / **Esc** to return with the profile selected. From the overview or quota dashboard, **s Switch** opens the same Cancel-first confirmation for the eligible inactive profile; cancelling from quota preserves the view and scroll position. From the overview, **d** sets the default and **c** clears an existing default, also with Cancel-first confirmation. The active profile also supports explicit stored-credential queries.
 
-Preview is **Codex only**, a live query using the selected profile's **stored credentials snapshot**, with no automatic refresh or stored-profile polling. Only **View usage** and the quota view's **Refresh** query; profile navigation does not. It never activates, borrows active credentials, refreshes tokens, writes auth, changes models/session state or overwrites active quota. Missing, malformed, expired or remotely rejected snapshots are unavailable—not zero quota. Even the current profile's stored snapshot may be stale: log in and save through the normal account workflow outside preview. Profile labels and decoded JWT claims do not verify human identity or server validity. Local history remains token/cost estimates, not subscription quota. Legacy `/osdy-account`, `/usage` and `/osdy-usage` remain unchanged; Agents configuration remains normal personal Pi only.
+Preview is **Codex only**, a live query using the selected profile's **stored credentials snapshot**, with no automatic refresh or stored-profile polling. Only **View usage** and the quota view's **Refresh** query; profile navigation does not. It never activates, borrows active credentials, refreshes tokens, writes auth, changes models/session state or overwrites active quota. Missing, malformed, expired or remotely rejected snapshots are unavailable—not zero quota. Even the current profile's stored snapshot may be stale: log in and save through the normal account workflow outside preview. Profile labels and decoded JWT claims do not verify human identity or server validity. Local history remains token/cost estimates, not subscription quota. Legacy `/osdy-account`, `/usage` and `/osdy-usage` remain available; Agents configuration remains normal personal Pi only.
 
 Osdy Pi can keep multiple ChatGPT Plus/Pro accounts authenticated and let you choose which one starts Pi. `personal` and `work` are only examples—you can create as many named profiles as you need.
 
@@ -294,7 +303,7 @@ To resume a specific session directly from the terminal:
 osdy-pi account use work -- --session /absolute/path/to/session.jsonl
 ```
 
-> **Privacy:** each profile keeps a private `auth.json`; Pi runs against its canonical shared `auth.json`. Account activation/preservation atomically copies opaque auth files. The separate explicit Account **View usage / Refresh** query reads a bounded stored auth snapshot, parses its Codex OAuth fields and unverified JWT claims, and sends the access token/account ID only to the fixed HTTPS Codex usage endpoint. It never refreshes tokens, logs in, switches accounts, writes auth, or queries automatically; it does not print or log credentials. Session history, settings, installed packages, and extension resources are shared, so every profile can access that local state. It keeps Pi's canonical `openai-codex` provider and delegates authentication to Pi's built-in `/login` flow.
+> **Privacy:** each profile keeps a private `auth.json`; Pi runs against its canonical shared `auth.json`. Account activation/preservation atomically copies opaque auth files. The separate explicit Account **View usage / Refresh** query reads a bounded stored auth snapshot, parses its Codex OAuth fields and unverified JWT claims, and sends the access token/account ID only to the fixed HTTPS Codex usage and optional reset-details endpoints. It never refreshes tokens, logs in, switches accounts, writes auth, or queries automatically; it does not print or log credentials. Session history, settings, installed packages, and extension resources are shared, so every profile can access that local state. It keeps Pi's canonical `openai-codex` provider and delegates authentication to Pi's built-in `/login` flow.
 
 Account switching is serialized in-process and protected by a private cross-process lock. Osdy Pi accepts only bounded regular auth files, refuses symlink-based auth sources, writes replacements with private permissions, and restores the previous canonical auth and account metadata when activation fails. A separate namespace lock protects concurrent profile creation, rename, and removal. Launchers activate the selected auth before starting Pi while continuing to use the shared agent directory; existing managed-directory links from earlier profile layouts are resolved for compatibility.
 
@@ -317,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" />
 
@@ -446,7 +455,17 @@ Active quota loads when an enabled session starts and refreshes when **Ctrl+Opti
 
 Automatic refresh retains the last snapshot during loading and on error, so an older reading can remain visible until a successful query replaces it. Manual refresh clears the previous snapshot before authentication resolves and supersedes any in-flight automatic request. Account switching refreshes active quota through that same clearing path. Session replacement and shutdown stop the timer, cancel pending requests and clear quota state; late results are ignored.
 
-> **Privacy:** this active-account `/usage` path resolves OAuth through Pi's `modelRegistry`, rather than directly reading auth files. The separate Control Center Account **View usage / Refresh** path reads the selected profile's bounded stored credentials snapshot; it never borrows active credentials or refreshes tokens, logs in, switches accounts, writes auth, or queries automatically. Both paths transmit the access token/account ID only to the fixed HTTPS Codex usage endpoint, reject redirects, and bound timeout and response size. Quota previews do not persist or log credentials or display account IDs, tokens, raw response bodies, or endpoint internals.
+> **Privacy:** this active-account `/usage` path resolves OAuth through Pi's `modelRegistry`, rather than directly reading auth files. The separate Control Center Account **View usage / Refresh** path reads the selected profile's bounded stored credentials snapshot; it never borrows active credentials or refreshes tokens, logs in, switches accounts, writes auth, or queries automatically. Both paths transmit the access token/account ID only to the fixed HTTPS Codex usage and optional reset-details endpoints, reject redirects, and bound timeout and response size. Quota previews do not persist or log credentials or display account IDs, tokens, raw response bodies, or endpoint internals. Only an explicitly selected and confirmed active-account reset additionally POSTs to the fixed Codex reset-consume endpoint.
+
+#### Use or check a banked reset
+
+1. In `/usage`, press **u**; or select **Usage → Use or check banked reset** in `/osdyConfig`. Account → View usage remains read-only, including previews of the current profile.
+2. The overlay closes first. Choose an indexed reset with its **local expiry date/time** (or **Expiry not provided**), then explicitly select **Use reset**. **Cancel is first**; Cancel/Esc sends nothing. The confirmation affects only the **active Codex account** and explains that a successful reset consumes one banked reset. Auth/account/session are checked again before POST.
+3. `/usage` reopens with the result snapshot if the same context remains active; Control Center exits, so reopen Usage to inspect it. A failed quota refresh or local bookkeeping failure is reported separately from a confirmed server outcome. `no_credit` and `nothing_to_reset` do not consume a reset; `already_redeemed` confirms prior success.
+
+**Unknown outcome:** do not start another reset or infer success from a changed count. Use **u** or the Usage row again and explicitly choose **Check pending attempt** to recheck the **same stored request UUID and reset ID**, which may finish an earlier unconfirmed reset—not start a new attempt. A private, durable local pending journal stores attempt identifiers, never credentials; reload does not automatically retry or replay it. Checking remains available with active Codex authentication even when the displayed count is zero or quota is unavailable.
+
+**Blocked storage/lock:** stop for manual verification of the previous attempt and any other running Pi process. Lock acquisition or pre-dispatch journal-save failure prevents a reset POST. Locks are not automatically reclaimed, even when apparently stale; orphaned locks can require manual recovery. There is no automatic lock cleanup or guarantee of perfect crash recovery. This flow has mocked transport tests, not live API, real-reset, or manual TUI verification.
 
 ### Local usage analytics (starting in 1.10.0)
 
@@ -461,7 +480,7 @@ Run `/osdy-usage` in interactive terminal Pi. **Summary** opens by default; use
 
 Narrow terminals stack metrics and wrap names; every group remains reachable by scrolling. Shares use the selected total tokens; bars scale to each ranking's maximum. Loading, stale, scan-limit/warning and unpriced/partial-cost states remain on every page and in help. Sticky status lines wrap instead of concealing cost status behind scan warnings, including at End. When height is scarce, statuses take priority over optional headings, charts and footer controls; the active page remains visible when space permits. Press `?` for methodology and full controls, then `?` again to return. Choosing a page also leaves help without discarding filters.
 
-This is separate from the unchanged `/usage` subscription quota panel. RPC, JSON and print modes receive a short notification instead of charts. The four-page UI passed independent scripted synthetic PTY checks for navigation, shared selection and responsive statuses at 12/32/100 columns, including a five-row terminal. Human visual confirmation and provider-backed capture remain unverified.
+This is separate from the `/usage` subscription quota panel. RPC, JSON and print modes receive a short notification instead of charts. The four-page UI passed independent scripted synthetic PTY checks for navigation, shared selection and responsive statuses at 12/32/100 columns, including a five-row terminal. Human visual confirmation and provider-backed capture remain unverified.
 
 | Control | Action |
 | --- | --- |
@@ -538,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 |
 | --- | --- |
@@ -547,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
@@ -565,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
 
@@ -622,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),
 	};
 }