agentvibes 5.6.7 → 5.6.9

package/CLAUDE.md

@@ -28,6 +28,15 @@ This project follows **BMAD (BMM - Business Model Methodology)** for all story d
 4. **Update sprint-status.yaml** automatically via `/dev-story`
 5. **Code review included** - Built into `/dev-story` workflow
 
+### ✅ Non-Destructive Configuration Rule (MANDATORY)
+All code that reads, writes, or modifies user configuration MUST be non-destructive:
+1. **Never delete or overwrite** existing user `.claude/` or `~/.claude/` config files (settings, voices, personalities, audio-effects.cfg) unless the user explicitly requested it
+2. **Copy new files; never remove existing ones** — installer adds missing files only
+3. **Write hooks only when absent** — `configureSessionStartHook` and similar functions check for existing hooks before writing
+4. **Preserve custom entries** — e.g. `audio-effects.cfg` user rows must survive an `agentvibes update`
+5. **Creating directories is fine** — `mkdir -p` / `{ recursive: true }` is always safe
+6. Any function that could overwrite user data must have a test asserting idempotency
+
 ### ✅ Git Workflow (ONLY Outside BMAD)
 For changes outside story development:
 1. Describe changes before acting

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6.7
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.6.9
 
 ---
 
@@ -40,9 +40,27 @@ Whether you're coding in Claude Code, chatting in Claude Desktop, using Warp Ter
 
 ---
 
-## 🌟 NEW IN v5.6.7 — Windows Preview Fixed
+## 🌟 NEW IN v5.6.9 — Reverb & Background Music Silent in NPX Installs
 
-The **Preview button in LLM audio configuration now works correctly on Windows**. It plays the voice, reverb, and background track you configured — no more defaulting to the wrong voice or playing silence.
+**NPX users:** Reverb and background music were silently broken for all `npx`-installed users. Hook files extracted from the npm tarball lacked execute bits (644), causing `audio-processor.sh` to exit with code 126. Fixed via `bash` prefix in the caller and a postinstall `chmod 755` step.
+
+**Voice Browser:** The Preview button now applies your configured reverb and background music — it was playing raw audio with no effects.
+
+**MCP tool:** `text_to_speech` now returns the correct audio file path (no trailing emoji garbage) and includes the voice name in its response.
+
+**Background music toggle:** Enabling music in the TUI now actually enables it — the flag file read by bash hooks is now kept in sync.
+
+## v5.6.8 — WSL Voice Routing Fixed + Session Lifecycle Reliability
+
+**WSL users:** AgentVibes was playing `en_US-lessac-medium` regardless of your configured voice. Fixed — Piper is now found in non-interactive shells by explicitly prepending `~/.local/bin` to `PATH` before the binary check.
+
+**Per-project routing:** The session-start hook now bakes `--project-dir` into every injected TTS command, so your configured voice and music play correctly in Bash tool calls even when `CLAUDE_PROJECT_DIR` isn't in the environment.
+
+`play-tts-piper.sh` and `play-tts-piper.ps1` are now included in `agentvibes install`'s critical hooks deployment — updated versions propagate automatically.
+
+## v5.6.7 — Windows Preview Fixed
+
+The Preview button in LLM audio configuration now works correctly on Windows.
 
 ## v5.6.6 — Preview Button Works in WSL + Comprehensive Windows Test Suite
 

package/RELEASE_NOTES.md

@@ -1,5 +1,66 @@
 # AgentVibes Release Notes
 
+## 🔇 v5.6.9 — Reverb & Background Music Silent in NPX Installs
+
+**Released:** 2026-05-09
+
+### 🐛 Reverb and Background Music Silently Broken for All NPX Users
+
+When AgentVibes is installed via `npx`, hook files are extracted from the tarball with 644 permissions — no execute bit. `play-tts-piper.sh` called `audio-processor.sh` directly, which exits immediately with code 126 (Permission denied) on a non-executable file. Every `npx`-installed user was getting voice-only TTS — no reverb, no background music, silently.
+
+**Fix 1:** `play-tts-piper.sh` now calls `audio-processor.sh` via `bash "$SCRIPT_DIR/audio-processor.sh"`, bypassing the execute-bit check.
+**Fix 2:** `install-deps.js` (postinstall) now runs `ensureHookPermissions()` to `chmod 755` all `.sh` files after npm install.
+
+### 🐛 Voice Browser Preview Ignored Reverb and Background Music
+
+The **Preview** button in the Voice Browser played raw piper output with no reverb and no background music, bypassing `audio-processor.sh` entirely.
+
+**Fix:** Preview audio now routes through the same `audio-processor.sh` pipeline as real TTS.
+
+### 🐛 MCP `text_to_speech` Returned Garbled File Path and Missing Voice Info
+
+The tool extracted the audio file path incorrectly (trailing size/emoji characters included) and never reported the voice name in its response.
+
+**Fix:** ANSI codes are stripped before parsing, the `.wav` path is cleanly extracted, and the `🎤 Voice used:` line is included in the tool response.
+
+### 🐛 Background Music TUI Toggle Didn't Take Effect
+
+Enabling background music in the **Music** tab wrote to `config.json` but not to `background-music-enabled.txt` (read by bash hooks). Music stayed off after toggling. Saving a track also now implies enabling music.
+
+---
+
+## 🐧 v5.6.8 — WSL Voice Routing Fixed + Session Lifecycle Reliability
+
+**Released:** 2026-05-09
+
+### 🐛 WSL: Configured Voice Now Plays (Not Lessac Fallback)
+
+In WSL sessions, AgentVibes was playing `en_US-lessac-medium` regardless of what voice you configured. The root cause: `pipx` installs Piper to `~/.local/bin/`, which interactive shells get via `.bashrc`/`.zshrc`, but Claude Code's Bash tool calls run non-interactively and skip profile sourcing — `command -v piper` failed, falling back to the default voice.
+
+**Fix:** `play-tts-piper.sh` now prepends `~/.local/bin` and the pipx Piper venv bin to `PATH` before the binary check, so Piper is found regardless of shell mode.
+
+### 🐛 Per-Project Voice/Music Lost When `CLAUDE_PROJECT_DIR` Not in Bash Environment
+
+When Claude Code runs a Bash tool call, `CLAUDE_PROJECT_DIR` is not passed in the environment. The TTS hooks couldn't find per-project config and fell back to global defaults — wrong voice, wrong music, no pretext.
+
+**Fix:** `session-start-tts.sh` (and `.ps1`) now bakes the project directory into the injected hook command as `--project-dir`. `play-tts.sh` reads this flag before any config lookup, so per-project routing is reliable in every Bash tool call.
+
+### 🐛 `play-tts-piper.sh` and `play-tts-piper.ps1` Not Deployed by `agentvibes install`
+
+These hooks were missing from `CRITICAL_HOOKS` / `CRITICAL_HOOKS_WINDOWS`, so `agentvibes install` never propagated updated versions to `~/.claude/hooks/`.
+
+**Fix:** Both are now in the critical hooks list and always deployed on install/update.
+
+### 🐛 Voice Display Name Bugs
+
+- `uniquifyVoiceName("Mary-1")` returned `"Mary-1 Bell"` instead of `"Mary Bell"`.
+- 16Speakers names like `Rose_Ibex` were incorrectly getting a surname appended (`"Rose Ibex Bell"`).
+- `🎤 Voice used:` line was missing from WSL bash output.
+
+All three fixed. A new test file (`test/unit/voice-names.test.js`, 16 tests) covers these cases.
+
+---
+
 ## 🪟 v5.6.7 — Windows Preview Fixed
 
 **Released:** 2026-05-08

package/WINDOWS-SETUP.md

@@ -1,208 +1,208 @@
-# AgentVibes Windows Native Setup
-
-This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
-
-## Quick Start
-
-### 1. Open in VS Code (Native Windows)
-
-- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
-- Make sure you're opening in **native Windows VS Code** (not WSL remote)
-
-### 2. Open PowerShell Terminal
-
-- **Terminal > New Terminal**
-- Change shell to **PowerShell** (if needed)
-
-### 3. Run Setup
-
-```powershell
-.\setup-windows.ps1
-```
-
-This script will:
-- Check PowerShell version (5.1+)
-- Create `.claude` directories
-- Let you choose TTS provider (Piper or SAPI)
-- Install Piper if you choose it
-- Download a default voice model
-- Test TTS
-- Configure for first use
-
-### 4. Install Dependencies
-
-```powershell
-npm install
-```
-
-### 5. Start Using AgentVibes
-
-Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
-
-## TTS Providers
-
-### Option 1: Soprano (Best Quality)
-- **Quality**: Ultra-high (80M parameter neural model)
-- **Voices**: Single high-quality voice (Soprano-1.1-80M)
-- **Download**: `pip install soprano-tts`
-- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
-- **Speed**: GPU-accelerated, very fast
-- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
-
-To set up Soprano:
-```powershell
-# Install Soprano
-pip install soprano-tts
-
-# Start WebUI (recommended - stays running in background)
-soprano-webui
-
-# Set provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-
-# Test
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
-```
-
-### Option 2: Windows Piper (Recommended for Offline)
-- **Quality**: High (neural voices)
-- **Voices**: 50+ available
-- **Download**: ~100MB
-- **Setup**: Automatic (run `setup-windows.ps1`)
-- **Speed**: Offline synthesis
-- **Features**: All AgentVibes features supported
-
-### Option 3: Windows SAPI (Built-in, Zero Setup)
-- **Quality**: Basic
-- **Voices**: ~10 built-in (David, Zira, Mark)
-- **Download**: 0 MB (no installation needed)
-- **Setup**: Select during `setup-windows.ps1`
-- **Speed**: Fast
-- **Features**: Core TTS only
-
-## Claude Code Integration
-
-AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{
-        "type": "command",
-        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
-      }]
-    }]
-  }
-}
-```
-
-This injects TTS protocol instructions so Claude speaks every response using the configured provider.
-
-## Manual Commands
-
-Test TTS manually:
-
-```powershell
-# Test current provider
-.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
-
-# Test specific providers
-.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
-.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
-.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
-
-# List available voices
-.\.claude\hooks-windows\voice-manager-windows.ps1 list
-
-# Switch voice (for Piper/SAPI)
-.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
-
-# List providers
-.\.claude\hooks-windows\provider-manager.ps1 list
-
-# Switch provider
-.\.claude\hooks-windows\provider-manager.ps1 set soprano
-.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
-.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
-```
-
-## Troubleshooting
-
-### PowerShell Execution Policy Error
-
-If you get an "execution policy" error, run:
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-```
-
-Then try again.
-
-### No Audio Playing
-
-1. Check Windows volume isn't muted
-2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
-3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
-
-### Soprano Not Detected
-
-1. Ensure soprano-webui is running: `soprano-webui`
-2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
-3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
-
-### Piper Installation Failed
-
-1. Check internet connection
-2. Run setup again: `.\setup-windows.ps1`
-3. Or manually download from: https://github.com/rhasspy/piper/releases
-
-### Can't Find Voice
-
-For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
-
-You can download additional voices with `.\download-piper-voices.ps1`.
-
-## Architecture
-
-```
-agentvibes-in-windows/
-├── .claude/
-│   ├── hooks-windows/               # PowerShell TTS scripts
-│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
-│   │   ├── play-tts-soprano.ps1     # Soprano provider
-│   │   ├── play-tts-windows-piper.ps1  # Piper provider
-│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
-│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
-│   │   ├── provider-manager.ps1     # Provider switching
-│   │   ├── voice-manager-windows.ps1   # Voice management
-│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
-│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
-│   ├── settings.json                # Claude Code hooks config
-│   ├── audio/                       # Audio cache (auto-created)
-│   ├── piper-voices/                # Piper voice models (auto-created)
-│   └── tts-provider.txt             # Active provider config
-├── setup-windows.ps1                # Installation script
-├── download-piper-voices.ps1        # Download additional Piper voices
-└── WINDOWS-SETUP.md                 # This file
-```
-
-## What's Different from WSL
-
-| Feature | WSL Version | Windows Native |
-|---------|-------------|----------------|
-| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
-| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
-| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
-| **Setup** | WSL + PulseAudio config | Native Windows only |
-| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
-
-## Support
-
-- **Documentation**: https://agentvibes.org
-- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-
----
-
-**Version**: 2.0 (Windows Native + Soprano)
-**Last Updated**: 2026-02-11
+# AgentVibes Windows Native Setup
+
+This folder contains AgentVibes configured for **native Windows** (not WSL) with three TTS providers available.
+
+## Quick Start
+
+### 1. Open in VS Code (Native Windows)
+
+- **File > Open Folder** > Select this folder (`agentvibes-in-windows`)
+- Make sure you're opening in **native Windows VS Code** (not WSL remote)
+
+### 2. Open PowerShell Terminal
+
+- **Terminal > New Terminal**
+- Change shell to **PowerShell** (if needed)
+
+### 3. Run Setup
+
+```powershell
+.\setup-windows.ps1
+```
+
+This script will:
+- Check PowerShell version (5.1+)
+- Create `.claude` directories
+- Let you choose TTS provider (Piper or SAPI)
+- Install Piper if you choose it
+- Download a default voice model
+- Test TTS
+- Configure for first use
+
+### 4. Install Dependencies
+
+```powershell
+npm install
+```
+
+### 5. Start Using AgentVibes
+
+Open a Claude Code session in this project. The SessionStart hook will automatically inject TTS protocol instructions, causing Claude to speak all responses.
+
+## TTS Providers
+
+### Option 1: Soprano (Best Quality)
+- **Quality**: Ultra-high (80M parameter neural model)
+- **Voices**: Single high-quality voice (Soprano-1.1-80M)
+- **Download**: `pip install soprano-tts`
+- **Setup**: Start WebUI with `soprano-webui` or API with `uvicorn soprano.server:app`
+- **Speed**: GPU-accelerated, very fast
+- **Features**: Gradio WebUI mode, OpenAI-compatible API mode, CLI fallback
+
+To set up Soprano:
+```powershell
+# Install Soprano
+pip install soprano-tts
+
+# Start WebUI (recommended - stays running in background)
+soprano-webui
+
+# Set provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+
+# Test
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello from Soprano"
+```
+
+### Option 2: Windows Piper (Recommended for Offline)
+- **Quality**: High (neural voices)
+- **Voices**: 50+ available
+- **Download**: ~100MB
+- **Setup**: Automatic (run `setup-windows.ps1`)
+- **Speed**: Offline synthesis
+- **Features**: All AgentVibes features supported
+
+### Option 3: Windows SAPI (Built-in, Zero Setup)
+- **Quality**: Basic
+- **Voices**: ~10 built-in (David, Zira, Mark)
+- **Download**: 0 MB (no installation needed)
+- **Setup**: Select during `setup-windows.ps1`
+- **Speed**: Fast
+- **Features**: Core TTS only
+
+## Claude Code Integration
+
+AgentVibes hooks into Claude Code via `.claude/settings.json`. The SessionStart hook runs automatically when Claude starts a session:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$CLAUDE_PROJECT_DIR\\.claude\\hooks-windows\\session-start-tts.ps1\""
+      }]
+    }]
+  }
+}
+```
+
+This injects TTS protocol instructions so Claude speaks every response using the configured provider.
+
+## Manual Commands
+
+Test TTS manually:
+
+```powershell
+# Test current provider
+.\.claude\hooks-windows\play-tts.ps1 "Hello from Windows"
+
+# Test specific providers
+.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "Hello SAPI"
+.\.claude\hooks-windows\play-tts-windows-piper.ps1 "Hello Piper"
+.\.claude\hooks-windows\play-tts-soprano.ps1 "Hello Soprano"
+
+# List available voices
+.\.claude\hooks-windows\voice-manager-windows.ps1 list
+
+# Switch voice (for Piper/SAPI)
+.\.claude\hooks-windows\voice-manager-windows.ps1 switch "en_US-lessac-high"
+
+# List providers
+.\.claude\hooks-windows\provider-manager.ps1 list
+
+# Switch provider
+.\.claude\hooks-windows\provider-manager.ps1 set soprano
+.\.claude\hooks-windows\provider-manager.ps1 set windows-piper
+.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi
+```
+
+## Troubleshooting
+
+### PowerShell Execution Policy Error
+
+If you get an "execution policy" error, run:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+Then try again.
+
+### No Audio Playing
+
+1. Check Windows volume isn't muted
+2. Try switching to SAPI provider (zero-setup): `.\.claude\hooks-windows\provider-manager.ps1 set windows-sapi`
+3. Test SAPI directly: `.\.claude\hooks-windows\play-tts-windows-sapi.ps1 "test"`
+
+### Soprano Not Detected
+
+1. Ensure soprano-webui is running: `soprano-webui`
+2. Check port 7860 is accessible: `Test-NetConnection -ComputerName 127.0.0.1 -Port 7860`
+3. Set custom port if needed: `$env:SOPRANO_PORT = "8080"` before running TTS
+
+### Piper Installation Failed
+
+1. Check internet connection
+2. Run setup again: `.\setup-windows.ps1`
+3. Or manually download from: https://github.com/rhasspy/piper/releases
+
+### Can't Find Voice
+
+For Piper, voices are stored in: `%USERPROFILE%\.claude\piper-voices\`
+
+You can download additional voices with `.\download-piper-voices.ps1`.
+
+## Architecture
+
+```
+agentvibes-in-windows/
+├── .claude/
+│   ├── hooks-windows/               # PowerShell TTS scripts
+│   │   ├── play-tts.ps1             # Main router (dispatches to active provider)
+│   │   ├── play-tts-soprano.ps1     # Soprano provider
+│   │   ├── play-tts-windows-piper.ps1  # Piper provider
+│   │   ├── play-tts-windows-sapi.ps1   # SAPI provider
+│   │   ├── soprano-gradio-synth.py  # Python helper for Soprano Gradio API
+│   │   ├── provider-manager.ps1     # Provider switching
+│   │   ├── voice-manager-windows.ps1   # Voice management
+│   │   ├── session-start-tts.ps1    # SessionStart hook (injects TTS protocol)
+│   │   └── audio-cache-utils.ps1    # Audio cache cleanup
+│   ├── settings.json                # Claude Code hooks config
+│   ├── audio/                       # Audio cache (auto-created)
+│   ├── piper-voices/                # Piper voice models (auto-created)
+│   └── tts-provider.txt             # Active provider config
+├── setup-windows.ps1                # Installation script
+├── download-piper-voices.ps1        # Download additional Piper voices
+└── WINDOWS-SETUP.md                 # This file
+```
+
+## What's Different from WSL
+
+| Feature | WSL Version | Windows Native |
+|---------|-------------|----------------|
+| **TTS Scripts** | Bash shell scripts (.sh) | PowerShell scripts (.ps1) |
+| **Audio** | PulseAudio/paplay | System.Media.SoundPlayer |
+| **Providers** | Piper, macOS, Termux, Soprano | Piper, SAPI, Soprano |
+| **Setup** | WSL + PulseAudio config | Native Windows only |
+| **Hook Dir** | `.claude/hooks/` | `.claude/hooks-windows/` |
+
+## Support
+
+- **Documentation**: https://agentvibes.org
+- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+
+---
+
+**Version**: 2.0 (Windows Native + Soprano)
+**Last Updated**: 2026-02-11

package/bin/agentvibes-voice-browser.js

@@ -474,6 +474,51 @@ class AgentVibesVoiceBrowser {
     this.screen.render();
   }
 
+  /**
+   * Apply audio effects (reverb, background music) via audio-processor.sh.
+   * Falls back to rawFile if the processor is unavailable or fails.
+   * @param {string} rawFile - Path to the raw piper-generated WAV
+   * @returns {Promise<string>} Path to processed WAV (or rawFile on failure)
+   */
+  async applyEffects(rawFile) {
+    // Find audio-processor.sh relative to this script (bin/../.claude/hooks/)
+    const processorPath = path.resolve(path.join(__dirname, '..', '.claude', 'hooks', 'audio-processor.sh'));
+
+    // SECURITY: Validate path stays within the expected hooks directory
+    const hooksDir = path.resolve(path.join(__dirname, '..', '.claude', 'hooks'));
+    if (!processorPath.startsWith(hooksDir + path.sep) && processorPath !== hooksDir) {
+      return rawFile;
+    }
+
+    if (!fsSync.existsSync(processorPath)) {
+      return rawFile;
+    }
+
+    const processedFile = rawFile.replace(/\.wav$/, '-preview-proc.wav');
+    const env = { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() };
+
+    return new Promise((resolve) => {
+      // Use 'bash' prefix so the script works even without execute permission (NPX cache)
+      const proc = spawn('bash', [processorPath, rawFile, 'llm:claude-code', processedFile, ''], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env
+      });
+
+      proc.on('close', (code) => {
+        let stat;
+        try { stat = fsSync.statSync(processedFile); } catch { stat = null; }
+        if (code === 0 && stat && stat.size > 0) {
+          resolve(processedFile);
+        } else {
+          try { fsSync.unlinkSync(processedFile); } catch { /* ignore */ }
+          resolve(rawFile);
+        }
+      });
+
+      proc.on('error', () => resolve(rawFile));
+    });
+  }
+
   async playSample(row) {
     if (this.currentAudioProcess) {
       try {
@@ -574,10 +619,13 @@ class AgentVibesVoiceBrowser {
       }
     }
 
+    // Apply audio effects (reverb, background music) before playback
+    const playFile = await this.applyEffects(outputFile);
+
     const players = [
-      { cmd: 'aplay', args: [outputFile] },
-      { cmd: 'paplay', args: [outputFile] },
-      { cmd: 'ffplay', args: ['-nodisp', '-autoexit', outputFile] }
+      { cmd: 'aplay', args: [playFile] },
+      { cmd: 'paplay', args: [playFile] },
+      { cmd: 'ffplay', args: ['-nodisp', '-autoexit', playFile] }
     ];
 
     for (const player of players) {
@@ -592,14 +640,21 @@ class AgentVibesVoiceBrowser {
           if (this.currentAudioProcess === audioProcess) {
             this.currentAudioProcess = null;
           }
+          // Clean up processed preview file (not the cached raw file)
+          if (playFile !== outputFile) {
+            try { fsSync.unlinkSync(playFile); } catch { /* ignore */ }
+          }
           this.statusBar.setContent(`{green-fg}✓ Played ${row.name}{/green-fg}`);
           this.screen.render();
         });
 
-        audioProcess.on('error', (err) => {
+        audioProcess.on('error', () => {
           if (this.currentAudioProcess === audioProcess) {
             this.currentAudioProcess = null;
           }
+          if (playFile !== outputFile) {
+            try { fsSync.unlinkSync(playFile); } catch { /* ignore */ }
+          }
         });
 
         break;