agentvibes 5.1.2 → 5.1.4

package/.claude/config/audio-effects.cfg

@@ -51,4 +51,6 @@ _party_mode|compand 0.3,1 6:-70,-60,-20|agent_vibes_dark_chill_step_loop.mp3|0.4
 # Default (no agent specified) - clean with Bachata background|||
 default||agent_vibes_chillwave_v2_loop.mp3|0.15
 analyst|reverb 70 50 100|agentvibes_soft_flamenco_loop.mp3|0.30
-llm:claude-code|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Claude Code here|piper
+llm:claude-code|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Claude Code here|piper
+llm:copilot|light|agent_vibes_bossa_nova_v2_loop.mp3|0.15|en_US-libritts-high::Anna-11|Copilot here|piper
+llm:codex|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Codex here|piper

package/.claude/hooks/play-tts.sh

@@ -126,6 +126,16 @@ TEXT="${TEXT//\\?/?}"        # Remove \?
 TEXT="${TEXT//\\,/,}"        # Remove \,
 TEXT="${TEXT//\\./.}"        # Remove \. (keep the period)
 
+# When no --llm is supplied, route through the "default" pseudo-LLM so the
+# user-managed `llm:default` row in audio-effects.cfg becomes the global
+# fallback for voice / pretext / music / effects.  This is configured via
+# Setup → Default → Configure in the TUI.  If `llm:default` doesn't exist,
+# the lookup returns empty and the script falls through to the legacy
+# global config chain (project / user .agentvibes/config.json).
+if [[ -z "$LLM_PROVIDER" ]]; then
+  LLM_PROVIDER="default"
+fi
+
 # Per-LLM config lookup: if --llm is passed, look up llm:<name> in audio-effects.cfg
 # Format: llm:<name>|REVERB_PRESET|BACKGROUND_FILE|BACKGROUND_VOLUME|VOICE|PRETEXT
 _LLM_VOICE=""

package/.claude/hooks-windows/play-tts.ps1

@@ -16,8 +16,142 @@ param(
     [string]$llm = ""
 )
 
+# Security: Validate LLM provider name (alphanumeric, hyphens, underscores
+# only) -- mirrors play-tts.sh line 92.  This prevents weird values from
+# poisoning the audio-effects.cfg lookup or the AGENTVIBES_LLM_KEY env var
+# we export to child scripts.  An invalid value is treated as unset rather
+# than aborting, so the script falls back to the default config and the
+# rest of TTS still works.
+if ($llm -and $llm -notmatch '^[a-zA-Z0-9_-]+$') {
+    Write-Error ("Invalid LLM provider name: '{0}' - must match {1}. Falling back to default config." -f $llm, '^[a-zA-Z0-9_-]+$')
+    $llm = ""
+}
+
+# When no -llm is supplied, route through the "default" pseudo-LLM so the
+# user-managed `llm:default` row in audio-effects.cfg becomes the global
+# fallback for voice / pretext / music / effects.  This is configured via
+# Setup -> Default -> Configure in the TUI.  If `llm:default` doesn't exist,
+# the lookup will return empty and the script falls through to the
+# legacy global config chain (project / user .agentvibes/config.json).
+if (-not $llm) {
+    $llm = "default"
+}
+
+# --- Cross-process playback serialization ---
+# Without this, any two callers of play-tts.ps1 (Claude Code PostToolUse hook,
+# Codex MCP text_to_speech, Copilot MCP text_to_speech, direct CLI) race each
+# other and produce overlapping / interleaved audio.  Party mode already has
+# its own mutex (AgentVibesPartyModeTTSQueue) at the bmad-party-speak.ps1
+# level, but MCP-initiated calls bypass it entirely.
+#
+# We use a DIFFERENT mutex name ("AgentVibesPlaybackLock") so there's no
+# deadlock risk with the party-mode mutex -- they can be held independently
+# by nested processes.
+#
+# The mutex is acquired immediately before PlaySync() and released right
+# after, so CPU-bound synthesis/ffmpeg work can overlap with another
+# process's playback.
+$_PlaybackMutex = New-Object System.Threading.Mutex($false, "AgentVibesPlaybackLock")
+
+# --- Script-level watchdog ---
+# If anything in this script hangs (SoundPlayer deadlock, audio device
+# locked, ffmpeg stuck, etc.), a sibling PowerShell job waits 25 seconds
+# and force-kills this process.  Without this, a stuck play-tts.ps1 holds
+# the playback mutex forever and silently blocks every subsequent TTS
+# call across all LLMs.  The watchdog guarantees forward progress.
+#
+# 25s is chosen to be LONGER than the mutex timeout (15s) but SHORT
+# enough that a stuck process clears before the user's next turn.  If
+# you fire two calls per turn and the first is stuck, the watchdog kills
+# it before the second turn arrives so the audio subsystem recovers
+# without manual intervention.  Long legitimate messages (>25s of speech)
+# are rare at default verbosity levels; when they do occur the watchdog
+# kills playback mid-sentence, which is acceptable degradation vs. a
+# deadlocked queue.
+$_WatchdogJob = $null
+try {
+    $_WatchdogJob = Start-Job -ArgumentList $PID -ScriptBlock {
+        param($parentPid)
+        Start-Sleep -Seconds 25
+        try {
+            # Only kill if still alive -- harmless if already exited
+            $p = Get-Process -Id $parentPid -ErrorAction SilentlyContinue
+            if ($p) {
+                [Console]::Error.WriteLine("[AgentVibes] play-tts.ps1 watchdog fired -- force-killing pid $parentPid after 25s")
+                Stop-Process -Id $parentPid -Force -ErrorAction SilentlyContinue
+            }
+        } catch { }
+    }
+} catch {
+    # If Start-Job fails (rare), just continue without the watchdog -- no
+    # regression from pre-watchdog behavior.
+    $_WatchdogJob = $null
+}
+
+function Invoke-SerializedPlay {
+    param([Parameter(Mandatory)][string]$WavPath)
+    $acquired = $false
+    try {
+        try {
+            # 15s timeout to acquire the playback mutex.  If we can't get
+            # it in 15s, the holder is almost certainly a stuck/crashed
+            # prior run.  AbandonedMutexException means the holder's
+            # process actually died -- we inherit ownership.
+            $acquired = $_PlaybackMutex.WaitOne(15000)
+        } catch [System.Threading.AbandonedMutexException] {
+            $acquired = $true
+        }
+        if (-not $acquired) {
+            # Self-heal: kill any stuck play-tts.ps1 processes (other than
+            # ourselves) that have been alive longer than 20 seconds.  This
+            # frees the mutex so the NEXT call can succeed without the user
+            # running taskkill manually.  We still exit with code 2 because
+            # this call's audio is lost, but the queue recovers immediately.
+            try {
+                $myPid = $PID
+                $cutoff = (Get-Date).AddSeconds(-20)
+                $stuck = Get-CimInstance Win32_Process -ErrorAction SilentlyContinue |
+                    Where-Object {
+                        $_.Name -eq 'powershell.exe' -and
+                        $_.ProcessId -ne $myPid -and
+                        $_.CommandLine -like '*play-tts.ps1*' -and
+                        $_.CreationDate -lt $cutoff
+                    }
+                foreach ($p in $stuck) {
+                    [Console]::Error.WriteLine("[AgentVibes] Self-heal: killing stuck play-tts.ps1 pid $($p.ProcessId) (alive since $($p.CreationDate))")
+                    Stop-Process -Id $p.ProcessId -Force -ErrorAction SilentlyContinue
+                }
+            } catch { }
+            [Console]::Error.WriteLine("[AgentVibes] ERROR: play-tts.ps1 could not acquire playback mutex within 15s. A prior play-tts.ps1 process was stuck holding it and has been killed; the next TTS call should succeed.")
+            exit 2
+        }
+        $player = $null
+        try {
+            $player = New-Object System.Media.SoundPlayer $WavPath
+            $player.PlaySync()
+        } finally {
+            if ($player) { $player.Dispose() }
+        }
+    } finally {
+        if ($acquired) {
+            try { $_PlaybackMutex.ReleaseMutex() } catch { }
+        }
+    }
+}
+
+# Register an exit handler that stops the watchdog job on normal exit so
+# it doesn't fire on successful short runs.
+Register-EngineEvent -SourceIdentifier PowerShell.Exiting -Action {
+    try {
+        if ($_WatchdogJob) {
+            Stop-Job -Job $_WatchdogJob -ErrorAction SilentlyContinue
+            Remove-Job -Job $_WatchdogJob -Force -ErrorAction SilentlyContinue
+        }
+    } catch { }
+} | Out-Null
+
 # Configuration paths
-# Priority: CLAUDE_PROJECT_DIR env var → script's parent project → user profile
+# Priority: CLAUDE_PROJECT_DIR env var -> script's parent project -> user profile
 # Local project settings ALWAYS override global (~/.claude)
 $ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
 
@@ -47,16 +181,19 @@ if (Test-Path $MuteFile) {
 }
 
 # Per-LLM config lookup: if --llm is passed, look up llm:<name> in audio-effects.cfg
-# Format: llm:<name>|SOX_EFFECTS|BACKGROUND_FILE|BACKGROUND_VOLUME|VOICE|PRETEXT
+# Format: llm:<name>|REVERB|BG_FILE|BG_VOLUME|VOICE|PRETEXT|ENGINE
 $LlmVoice = ""
 $LlmPretext = ""
 $LlmReverb = ""
 $LlmEngine = ""
+$LlmBgTrack = ""
+$LlmBgVolume = ""
 $ProjectRoot = Split-Path -Parent $ClaudeDir
 $ConfigDir = "$ClaudeDir\config"
 
 if ($llm) {
     $llmKey = "llm:$llm"
+    $llmKeyPattern = '^' + [regex]::Escape($llmKey) + '\|'
     # Check project-local audio-effects.cfg first, then global
     $cfgPaths = @(
         "$ConfigDir\audio-effects.cfg",
@@ -65,12 +202,18 @@ if ($llm) {
     foreach ($cfgPath in $cfgPaths) {
         if (-not $LlmVoice -and -not $LlmPretext -and (Test-Path $cfgPath)) {
             foreach ($line in (Get-Content $cfgPath)) {
-                if ($line -match "^$([regex]::Escape($llmKey))\|") {
+                if ($line -match $llmKeyPattern) {
                     $parts = $line -split '\|'
-                    # parts: [0]=key [1]=reverb_preset [2]=bg_file [3]=bg_vol [4]=voice [5]=pretext
+                    # parts: [0]=key [1]=reverb [2]=bg_file [3]=bg_vol [4]=voice [5]=pretext [6]=engine
                     if ($parts.Length -ge 2 -and $parts[1].Trim()) {
                         $LlmReverb = $parts[1].Trim()
                     }
+                    if ($parts.Length -ge 3 -and $parts[2].Trim()) {
+                        $LlmBgTrack = $parts[2].Trim()
+                    }
+                    if ($parts.Length -ge 4 -and $parts[3].Trim()) {
+                        $LlmBgVolume = $parts[3].Trim()
+                    }
                     if ($parts.Length -ge 5 -and $parts[4].Trim()) {
                         $LlmVoice = $parts[4].Trim()
                     }
@@ -85,8 +228,21 @@ if ($llm) {
             }
         }
     }
-    # Apply LLM voice override (only if no explicit VoiceOverride was passed)
-    if ($LlmVoice -and -not $VoiceOverride) {
+    # LLM per-LLM voice routing.
+    #
+    # PRIORITY CHANGE: when -llm is passed AND the llm row has a voice,
+    # the per-LLM voice always wins — even over an explicit VoiceOverride
+    # parameter passed by the MCP caller.  Rationale: Codex / Copilot /
+    # Claude Code all call `get_config` at session start and then echo
+    # the global voice back on every `text_to_speech` call.  With the
+    # old "explicit wins" priority, that global voice overrode our
+    # per-LLM routing and broke the entire point of having llm:<key>
+    # rows in audio-effects.cfg.
+    #
+    # To request a specific voice for a specific call that bypasses the
+    # LLM routing, the caller should NOT pass -llm, or should use the
+    # `llm:default` row (which has no voice column to override).
+    if ($LlmVoice) {
         $VoiceOverride = $LlmVoice
     }
     # Export LLM key for child scripts (process-local, not system-wide)
@@ -94,8 +250,8 @@ if ($llm) {
 }
 
 # Prepend pretext if configured
-# Priority: LLM-specific pretext → project .agentvibes/config.json → project .claude/config/tts-pretext.txt
-#           → global ~/.agentvibes/config.json → global ~/.claude/config/tts-pretext.txt
+# Priority: LLM-specific pretext -> project .agentvibes/config.json -> project .claude/config/tts-pretext.txt
+#           -> global ~/.agentvibes/config.json -> global ~/.claude/config/tts-pretext.txt
 $Pretext = $LlmPretext
 if (-not $Pretext) {
     $PretextSources = @(
@@ -121,7 +277,6 @@ if (-not $Pretext) {
 if ($Pretext) {
     $Text = "$Pretext, $Text"
 }
-
 # Determine active provider
 # LLM-specific engine overrides global provider
 $ActiveProvider = "sapi"
@@ -183,6 +338,15 @@ if (Test-Path $AgentVibesConfig) {
     }
 }
 
+# When a per-LLM row in audio-effects.cfg has a background track configured,
+# that's an implicit "bg music enabled for this LLM" — force it on regardless
+# of the global backgroundMusic.enabled flag.  Without this, setting a per-LLM
+# track in the TUI's Configure modal would have no effect unless the user
+# ALSO toggled global bg music on.
+if ($LlmBgTrack) {
+    $BgEnabled = $true
+}
+
 # Check if reverb is enabled (allowlist validation)
 # LLM-specific reverb overrides global setting
 $ReverbLevel = "off"
@@ -216,7 +380,7 @@ if ($BgEnabled -or $HasReverb) {
     }
 }
 
-# Check for pre-synthesized WAV (party mode optimization — synthesis done before mutex acquisition)
+# Check for pre-synthesized WAV (party mode optimization -- synthesis done before mutex acquisition)
 $PreSynthWav = $env:AGENTVIBES_PRESYNTHESIZED_WAV
 $UsePreSynth = $PreSynthWav -and (Test-Path $PreSynthWav) -and
     (Get-Item $PreSynthWav -ErrorAction SilentlyContinue).Length -gt 0
@@ -234,14 +398,10 @@ if ($UsePreSynth) {
     Write-Host "[SYNTH] Using pre-synthesized audio..." -ForegroundColor Cyan
     # If no post-processing needed, play the pre-synth file directly and exit
     if (-not $NeedsPostProcess) {
-        $player = $null
         try {
-            $player = New-Object System.Media.SoundPlayer $PreSynthWav
-            $player.PlaySync()
+            Invoke-SerializedPlay -WavPath $PreSynthWav
         } catch {
             Write-Host "[WARNING] Pre-synth playback failed: $_" -ForegroundColor Yellow
-        } finally {
-            if ($player) { $player.Dispose() }
         }
         Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
         exit 0
@@ -268,6 +428,25 @@ if ($UsePreSynth) {
                     Write-Host "$item"
                 }
             }
+            # Parse the provider output for "[OK] Saved to: <path>" so we can
+            # use the EXACT file the provider just wrote.  This replaces the
+            # old "pick most recent tts-XXXXXXXX.wav" heuristic which would
+            # silently replay stale audio whenever synthesis failed.
+            $FreshSynthFile = $null
+            foreach ($item in $providerOutput) {
+                $line = if ($item -is [System.Management.Automation.InformationRecord]) {
+                    $m = $item.MessageData
+                    if ($m -is [System.Management.Automation.HostInformationMessage]) { $m.Message } else { "$item" }
+                } else { "$item" }
+                if ($line -match '^\[OK\] Saved to:\s*(.+\.wav)\s*$') {
+                    $FreshSynthFile = $Matches[1].Trim()
+                }
+            }
+            if (-not $FreshSynthFile -or -not (Test-Path $FreshSynthFile)) {
+                [Console]::Error.WriteLine("[AgentVibes] ERROR: Provider synthesis did not produce an output file. NOT falling back to stale audio.  Check provider logs above.")
+                Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
+                exit 3
+            }
         } else {
             if ($VoiceOverride) {
                 & $ProviderScript $Text $VoiceOverride
@@ -287,13 +466,17 @@ if ($UsePreSynth) {
 if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
     Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
 
-    # Find the WAV to post-process: use pre-synthesized file if available, else most recent
+    # Use the EXACT file the provider script just wrote (captured from its
+    # "[OK] Saved to: <path>" output line above).  The old "pick most recent
+    # tts-XXXXXXXX.wav" heuristic silently replayed stale audio whenever
+    # synthesis failed — there is no safe way to guess which file is fresh.
     $AudioDir = "$ClaudeDir\audio"
     $RecentWav = if ($UsePreSynth) {
         Get-Item $PreSynthWav -ErrorAction SilentlyContinue
+    } elseif ($FreshSynthFile -and (Test-Path $FreshSynthFile)) {
+        Get-Item $FreshSynthFile -ErrorAction SilentlyContinue
     } else {
-        Get-ChildItem -Path $AudioDir -Filter "tts-*.wav" -ErrorAction SilentlyContinue |
-            Sort-Object LastWriteTime -Descending | Select-Object -First 1
+        $null
     }
 
     if ($RecentWav -and $RecentWav.Length -gt 0) {
@@ -309,7 +492,10 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                 default     { "" }
             }
             if ($reverbFilter) {
-                $reverbedFile = "$AudioDir\tts-reverbed.wav"
+                # Use a fixed name OUTSIDE the `tts-XXXXXXXX` random-name
+                # namespace so the "pick most recent tts-*.wav" logic can't
+                # accidentally pick this post-processed file as a synth input.
+                $reverbedFile = "$AudioDir\av-reverbed-scratch.wav"
                 $reverbArgs = "-y -i `"$voicePath`" -af `"$reverbFilter`" `"$reverbedFile`""
                 $proc = Start-Process -FilePath "ffmpeg" -ArgumentList $reverbArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "$env:TEMP\agentvibes-ffmpeg-stderr.txt"
                 if ($proc.ExitCode -eq 0 -and (Test-Path $reverbedFile)) {
@@ -329,7 +515,7 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
             if (Test-Path $AudioEffectsCfg) {
                 # Try agent-specific config first, then fall back to default
                 # Format: AGENT_NAME|SOX_EFFECTS|BACKGROUND_FILE|BACKGROUND_VOLUME
-                # Lookup order: agent name → llm:<name> → default
+                # Lookup order: agent name -> llm:<name> -> default
                 $agentName = $env:AGENTVIBES_AGENT_NAME
                 $configLine = $null
 
@@ -392,7 +578,14 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
             }
 
             if (Test-Path $BgTrackPath) {
-                $MixedFile = $RecentWav.FullName -replace '\.wav$', '-mixed.wav'
+                # Mixed output goes to a fixed name OUTSIDE the tts-XXXXXXXX
+                # random-name namespace so the "pick most recent tts-*.wav"
+                # logic can't accidentally pick this as a synth input in the
+                # next invocation.  (Previously we'd name this as
+                # "$voicePath-mixed.wav" which generated files like
+                # tts-xxx.wav.effected-mixed.wav that kept re-matching and
+                # compounding on every run.)
+                $MixedFile = "$AudioDir\av-mixed-scratch.wav"
 
                 try {
                     # Get voice duration to calculate total length
@@ -415,62 +608,28 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                     $proc = Start-Process -FilePath "ffmpeg" -ArgumentList $ffmpegArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "$env:TEMP\agentvibes-ffmpeg-stderr.txt"
 
                     if ($proc.ExitCode -eq 0 -and (Test-Path $MixedFile) -and (Get-Item $MixedFile).Length -gt 0) {
-                        # Play the mixed audio
-                        $player = $null
+                        # Play the mixed audio (via serialized mutex)
                         try {
-                            $player = New-Object System.Media.SoundPlayer $MixedFile
-                            $player.PlaySync()
+                            Invoke-SerializedPlay -WavPath $MixedFile
                         } catch {
                             Write-Host "[WARNING] Mixed playback failed, playing voice only" -ForegroundColor Yellow
-                            $player2 = $null
-                            try {
-                                $player2 = New-Object System.Media.SoundPlayer $voicePath
-                                $player2.PlaySync()
-                            } finally {
-                                if ($player2) { $player2.Dispose() }
-                            }
-                        } finally {
-                            if ($player) { $player.Dispose() }
+                            Invoke-SerializedPlay -WavPath $voicePath
                         }
                     } else {
                         # Mixing failed, play voice only
-                        $player = $null
-                        try {
-                            $player = New-Object System.Media.SoundPlayer $voicePath
-                            $player.PlaySync()
-                        } finally {
-                            if ($player) { $player.Dispose() }
-                        }
+                        Invoke-SerializedPlay -WavPath $voicePath
                     }
                 } catch {
                     # ffmpeg failed, play voice only
-                    $player = $null
-                    try {
-                        $player = New-Object System.Media.SoundPlayer $voicePath
-                        $player.PlaySync()
-                    } finally {
-                        if ($player) { $player.Dispose() }
-                    }
+                    Invoke-SerializedPlay -WavPath $voicePath
                 }
             } else {
                 # No background track found, play voice only
-                $player = $null
-                try {
-                    $player = New-Object System.Media.SoundPlayer $voicePath
-                    $player.PlaySync()
-                } finally {
-                    if ($player) { $player.Dispose() }
-                }
+                Invoke-SerializedPlay -WavPath $voicePath
             }
         } else {
             # No background music, play the (possibly reverbed) voice
-            $player = $null
-            try {
-                $player = New-Object System.Media.SoundPlayer $voicePath
-                $player.PlaySync()
-            } finally {
-                if ($player) { $player.Dispose() }
-            }
+            Invoke-SerializedPlay -WavPath $voicePath
         }
     }
 } else {

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.1.2
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.1.4
 
 ---
 
@@ -43,6 +43,29 @@ Whether you're using Claude Code, GitHub Copilot, OpenAI Codex, Claude Desktop,
 
 ---
 
+## 🛡️ NEW IN v5.1.4 — TTS Resilience Overhaul + Default LLM Provider
+
+- **Default LLM provider** — New fallback entry at the bottom of Setup → Providers. Config-only; opens the standard Configure modal. Used when a tool calls TTS without identifying its LLM.
+- **Per-LLM background music auto-enables** — Setting a bg track on the per-LLM Configure modal actually plays it now (no need to also toggle global bg music).
+- **Copilot CLI support** — `installCopilotMcp` now writes both `.vscode/mcp.json` (Copilot Chat) AND `~/.copilot/mcp-config.json` (Copilot CLI — different product, different config path).
+- **Per-client routing architecture** — `.mcp.json` no longer sets `AGENTVIBES_LLM`. Claude Code is auto-detected via `CLAUDECODE=1` env var. Copilot CLI reads its own global config. No more client config conflicts.
+- **Self-healing TTS mutex** — When a stuck `play-tts.ps1` process blocks the playback queue, the next caller auto-kills it (no manual `taskkill` needed). 25-second watchdog guarantees forward progress.
+- **No more stale audio replay** — `play-tts.ps1` captures the exact synth output filename from provider stdout instead of guessing "most recent `tts-*.wav`". Silent replay of old audio is gone.
+- **Per-LLM voice wins over explicit `VoiceOverride`** — LLMs echo back `get_config` results on every call, which was overriding per-LLM routing. Fixed.
+- **`lessac-medium` → `lessac-high`** default for codex — Silent synthesis failure workaround.
+- **Scratch file rename + ASCII-only encoding** — Eliminates accumulating compound audio files and CP1252 parse errors on Windows.
+- **Setup → Install confirmation** now advances focus to the next provider row (Install → Install → Install flow).
+
+---
+
+## 🛡️ v5.1.3 — Hardening Pass (Adversarial Review Followup)
+
+- **Existing `.mcp.json` is now auto-migrated** — v5.1.2's installer detected an existing `.mcp.json` and printed instructions instead of fixing it, leaving v5.1.0/v5.1.1 users still broken after upgrade. v5.1.3 merges the `AGENTVIBES_LLM` env var into existing configs in-place.
+- **`AGENTVIBES_LLM` is now validated** in both `mcp-server/server.py` (Python regex) and `play-tts.ps1` (PowerShell regex), matching `play-tts.sh`'s `^[a-zA-Z0-9_-]+$` check. Cross-platform contract is now symmetric.
+- **`npm pack` content guard hardened**: hard-fails (not silent-passes) when `npm pack` errors; uses `git status --porcelain` to catch UNTRACKED publishable files (the v5.1.0 disaster also could've happened with a stray new file); has explicit 60s timeout to prevent CI hangs.
+
+---
+
 ## 🔀 v5.1.2 — MCP Per-LLM Routing Hotfix
 
 - **MCP server now reads `AGENTVIBES_LLM` env var** instead of hardcoding `copilot` — Codex / Copilot / Claude Code each get routed to their own per-LLM voice / pretext / music / effects config from `audio-effects.cfg`.

package/RELEASE_NOTES.md

@@ -1,5 +1,117 @@
 # AgentVibes Release Notes
 
+## 🛡️ v5.1.4 — TTS Resilience Overhaul + Default LLM Provider + Per-Client Routing
+
+**Release Date:** April 2026
+
+This release closes a long-running cluster of bugs around per-LLM TTS routing, parallel audio playback, stuck-process deadlocks, and stale-audio replay. It also adds a new "Default" provider slot in the Setup tab for fallback audio configuration, and switches to a per-client config scheme that correctly routes Claude Code, GitHub Copilot (Chat + CLI), and OpenAI Codex to their own voices and pretexts.
+
+### New Features
+
+- **Default LLM provider** — New entry at the bottom of Setup → Providers. Config-only (no install/remove buttons) with a Configure button that opens the standard per-LLM audio modal. When any tool calls TTS without identifying its LLM, the `llm:default` row in `audio-effects.cfg` provides the fallback voice, pretext, music, reverb, and engine. Empty pretext by default — users opt in.
+
+- **Per-LLM background music now auto-enables** — Setting a `bg_track` on any per-LLM Configure modal now actually plays that track. Previously you also had to toggle the global `backgroundMusic.enabled` flag, which made the per-LLM bg track field silently dead.
+
+- **Copilot CLI support** — `installCopilotMcp` now writes BOTH `.vscode/mcp.json` (for VS Code Copilot Chat) AND `~/.copilot/mcp-config.json` (for the standalone `copilot` CLI, which is a different product). Fresh installs support both tools automatically.
+
+### Per-Client Routing Architecture
+
+Previously `AGENTVIBES_LLM=claude-code` was set in `.mcp.json`, which broke Copilot CLI because Copilot CLI also reads `.mcp.json` with precedence over its own `~/.copilot/mcp-config.json` — so it adopted Claude Code's env and mis-routed.
+
+The new architecture splits per-LLM identification per-client:
+
+- `.mcp.json` (project) has **no `AGENTVIBES_LLM` env block**
+- `~/.copilot/mcp-config.json` sets `AGENTVIBES_LLM=copilot` for GitHub Copilot CLI
+- `~/.codex/config.toml` sets `AGENTVIBES_LLM=codex` for OpenAI Codex
+- The MCP server (`mcp-server/server.py`) **auto-detects Claude Code** via the `CLAUDECODE=1` env var that Claude Code sets on every subprocess it spawns. Copilot CLI and Codex don't set this var, so each client reliably routes to its own config.
+
+Upgrade path: re-run the AgentVibes installer in any existing project. The new `installClaudeMcp` auto-strips any stale `AGENTVIBES_LLM` env block from existing `.mcp.json` files so Copilot CLI stops mis-routing.
+
+### TTS Resilience Overhaul (`play-tts.ps1`)
+
+- **Cross-process playback mutex** — `AgentVibesPlaybackLock` (named mutex) serializes playback across all callers: Claude Code hooks, MCP `text_to_speech`, direct CLI, party mode. No more overlapping or parallel audio when multiple LLMs run in the same project.
+
+- **Self-healing on mutex timeout** — When the 15-second mutex acquisition fails, the new code queries `Win32_Process` for any stuck `play-tts.ps1` process older than 20 seconds, calls `Stop-Process -Force` on each, and logs the kill to stderr. The next TTS call succeeds immediately — no manual `taskkill` needed.
+
+- **25-second script watchdog** — A sibling PowerShell job force-kills `play-tts.ps1` after 25 seconds regardless of where it's stuck (SoundPlayer deadlock, locked audio device, zombie ffmpeg). Guarantees forward progress.
+
+- **Hard error on mutex timeout** — Replaces the old "play anyway" fallback which just stacked more stuck processes behind the first. Now exits cleanly with code 2 and a diagnostic message.
+
+- **Exact filename capture from provider stdout** — `play-tts.ps1` parses the `[OK] Saved to: <path>` line from `play-tts-piper.ps1` and uses that exact file. Replaces the old "pick most recent `tts-*.wav` in the audio dir" heuristic which silently replayed stale audio from earlier sessions whenever synthesis failed. Root cause of the "Codex speaks Claude Code's audio" bug.
+
+- **Synthesis-failure hard error** — When the provider doesn't produce an output file, `play-tts.ps1` exits with code 3 and a loud error instead of falling back to any older file in the cache.
+
+- **Scratch file rename** — Reverb post-processing now writes to `av-reverbed-scratch.wav` and mix post-processing writes to `av-mixed-scratch.wav`. Fixed names outside the `tts-XXXXXXXX` random namespace so the file lookup can never pick them up as a synth input. Eliminates the compound `tts-xxx.wav.effected-mixed-mixed-mixed-mixed.wav` chain that accumulated on every run.
+
+- **Per-LLM voice overrides explicit `VoiceOverride`** — LLMs call `get_config` at session start and echo the returned voice back on every `text_to_speech` call as an explicit MCP parameter. With the old "explicit wins" priority, that global voice overrode per-LLM routing. Now the `llm:<key>` voice row always wins when `-llm` is set.
+
+- **`$LlmBgTrack` and `$LlmBgVolume` parsed from cfg row** — Previously fields 2 and 3 of the `llm:<key>` line were ignored in the PowerShell version (the bash version already parsed them).
+
+- **Per-LLM `bg_track` force-enables `$BgEnabled`** — When a per-LLM row specifies a background track, it's auto-enabled regardless of the global `backgroundMusic.enabled` flag.
+
+- **ASCII-only encoding** — Removed em-dash `—` and right-arrow `→` from `play-tts.ps1`. PowerShell on some Windows locales loads scripts in CP1252 and choked on the UTF-8 bytes with a misleading "Missing closing `}`" parse error.
+
+- **`lessac-medium` → `lessac-high` default for codex** — `en_US-lessac-medium` silently fails to synthesize on some Windows Piper installs (loads the model, exits with empty output). `lessac-high` works reliably and is the new default in `DEFAULT_LLM_CONFIGS.codex` and the packaged `audio-effects.cfg`.
+
+### UX Improvements
+
+- **Setup → Providers Install confirmation** — Pressing Enter to dismiss the post-install confirmation page now advances focus to the NEXT provider row's same-column button (Install → Install, Configure → Configure), instead of snapping back to Claude Code's Install. Installing all three providers is now a natural Enter-Enter-Enter flow.
+
+### Testing & Hardening
+
+- **30 new/updated regression tests** in `test/unit/llm-provider-mcp-routing.test.js` and `test/unit/windows-tts.test.js` covering:
+  - Default LLM provider config shape + setup-tab wiring
+  - `CLAUDECODE` auto-detection in `server.py`
+  - `.mcp.json` template MUST NOT contain `AGENTVIBES_LLM`
+  - `~/.copilot/mcp-config.json` writer in `installCopilotMcp`
+  - `play-tts.ps1` PowerShell-parseable (catches em-dash / encoding regressions via `[System.Management.Automation.Language.Parser]`)
+
+### How to Update
+
+```
+npm cache clean --force
+npx --yes agentvibes@5.1.4
+```
+
+If you have any existing project with AgentVibes installed, re-run the installer there once so the per-client config migration takes effect. The `.mcp.json` in each project will be auto-upgraded to strip the stale `AGENTVIBES_LLM` env block, and `~/.copilot/mcp-config.json` will be created if you have the Copilot provider enabled.
+
+---
+
+## 🛡️ v5.1.3 — Hardening Pass (Adversarial Review Followup)
+
+**Release Date:** April 2026
+
+This release addresses HIGH/MEDIUM findings from a parallel adversarial review (Blind Hunter + Edge Case Hunter) of the v5.1.2 hotfix.
+
+### Bug Fixes
+
+- **Existing `.mcp.json` is now auto-migrated** — v5.1.2's installer detected an existing `.mcp.json` and printed instructions to fix it manually. Result: anyone upgrading from v5.1.0/v5.1.1 was still broken after `npm i -g agentvibes@5.1.2`. v5.1.3 detects an existing config, merges the `AGENTVIBES_LLM` env var (and the rest of the agentvibes server entry) in-place, and shows a green "✅ MCP Configuration Updated" message. Existing user `env` keys are preserved.
+
+- **`AGENTVIBES_LLM` is now validated** before being forwarded to the child shell. The bash version of `play-tts.sh` already validated `^[a-zA-Z0-9_-]+$` and rejected weird values; the Python `mcp-server/server.py` and the Windows `play-tts.ps1` did not. Now all three do, with the same regex. Invalid values are logged to stderr and treated as "unset" so TTS still works (falls back to default config).
+
+### Testing & Hardening
+
+- **`npm pack` content guard now hard-fails on `packError`** instead of silently returning early. The previous v5.1.2 implementation had `if (packError) return;` in 6 of 8 tests, which meant a real `npm pack` failure surfaced as one failed test and SIX false-greens — defeating the entire purpose of the publish guard.
+
+- **Dirty-tree check now uses `git status --porcelain`** instead of `git diff HEAD`. The previous implementation only caught modified-but-uncommitted tracked files; it missed brand-new untracked files in publishable directories (e.g. a `play-tts.ps1.new` someone forgot to delete). The v5.1.0 disaster could just as easily have shipped via an untracked stray file.
+
+- **`npm pack` exec timeout** — added explicit 60-second timeout with `SIGKILL` so the publish guard can't hang CI on a stuck registry call.
+
+- **`git status` failures hard-fail** instead of silently skipping. A missing git binary in CI was previously treated as "no findings" — that's exactly the opposite of what a security guard should do. Now it fails loudly with a message explaining the guard requires git.
+
+- **3 new regression tests** for the new validations and migration logic.
+
+### How to Update
+
+```
+npm cache clean --force
+npx --yes agentvibes@5.1.3
+```
+
+If you upgraded from v5.1.0 or v5.1.1, **re-run the AgentVibes installer once** so the new in-place migration touches your existing `.mcp.json` / `.codex/config.toml` / `.vscode/mcp.json`.
+
+---
+
 ## 🔀 v5.1.2 — MCP Per-LLM Routing Hotfix
 
 **Release Date:** April 2026

package/mcp-server/server.py

@@ -51,8 +51,6 @@ from typing import Optional
 from mcp.server import Server
 from mcp.types import Tool, TextContent, ImageContent, EmbeddedResource
 import mcp.server.stdio
-
-
 class AgentVibesServer:
     """MCP Server for AgentVibes TTS functionality"""
 
@@ -196,17 +194,38 @@ class AgentVibesServer:
 
             # Call the TTS script via appropriate shell.
             #
-            # The LLM key is read from the AGENTVIBES_LLM env var so each
-            # caller (Claude Code, GitHub Copilot, OpenAI Codex) gets routed
-            # to its own per-LLM voice / pretext / music / effects config.
-            # The MCP launcher in each provider's config file should set
-            # this env var (e.g. .codex/config.toml [mcp_servers.agentvibes]
-            # env = { AGENTVIBES_LLM = "codex" }).
+            # The LLM key is determined with the following priority:
+            #
+            # 1. AGENTVIBES_LLM env var (explicit — wins over everything).
+            #    Set in each provider's MCP launcher config:
+            #      ~/.codex/config.toml         -> "codex"
+            #      ~/.copilot/mcp-config.json   -> "copilot"
             #
-            # If unset, no -llm flag is passed and play-tts falls back to
-            # the project / global default config — which is the correct
-            # behavior for ad-hoc / unconfigured callers.
+            # 2. Auto-detection via CLAUDECODE=1 env var (Claude Code sets
+            #    this automatically when it spawns any subprocess).  This
+            #    lets project-level .mcp.json files omit the env block —
+            #    which is critical because GitHub Copilot CLI also reads
+            #    .mcp.json and would otherwise pick up claude-code's env.
+            #
+            # 3. Unset — play-tts falls back to llm:default or global config.
+            #
+            # Validation mirrors play-tts.sh line 92 — alphanumeric /
+            # hyphen / underscore only.  Prevents weird values from
+            # poisoning the audio-effects.cfg lookup or child-shell args.
+            import re as _re
             llm_key = os.environ.get("AGENTVIBES_LLM", "").strip()
+            if llm_key and not _re.match(r"^[a-zA-Z0-9_-]+$", llm_key):
+                print(
+                    f"[AgentVibes] WARN: Ignoring invalid AGENTVIBES_LLM='{llm_key}' "
+                    "(must match ^[a-zA-Z0-9_-]+$); falling back to auto-detect",
+                    file=__import__('sys').stderr,
+                )
+                llm_key = ""
+            # Claude Code sets CLAUDECODE=1 when it spawns subprocesses.
+            # Use that as a fallback identifier when no explicit env var
+            # was provided.  Copilot CLI and Codex do NOT set this.
+            if not llm_key and os.environ.get("CLAUDECODE", "").strip() == "1":
+                llm_key = "claude-code"
             tts_script = "play-tts.ps1" if self.is_windows else "play-tts.sh"
             play_tts = self.hooks_dir / tts_script
             if self.is_windows:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.1.2",
+  "version": "5.1.4",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/tabs/setup-tab.js

@@ -565,6 +565,13 @@ export function createSetupTab(screen, services) {
       },
     });
 
+    // The "default" provider is config-only — it has no install/remove
+    // semantics.  Hide those buttons and only show Configure.
+    if (provider.isDefault) {
+      installBtn.hide();
+      removeBtn.hide();
+    }
+
     // Wire actions
     installBtn.on('press', async () => { await handleProviderInstall(provider); });
     installBtn.key(['enter', 'space'], async () => { await handleProviderInstall(provider); });
@@ -575,8 +582,10 @@ export function createSetupTab(screen, services) {
     configBtn.on('press', async () => { await handleProviderConfigure(provider); });
     configBtn.key(['enter', 'space'], async () => { await handleProviderConfigure(provider); });
 
-    // Navigation on each button
-    for (const btn of [installBtn, removeBtn, configBtn]) {
+    // Navigation on each button — for the default provider, only Configure
+    // is focusable since install/remove are hidden.
+    const navButtons = provider.isDefault ? [configBtn] : [installBtn, removeBtn, configBtn];
+    for (const btn of navButtons) {
       btn.key(['tab', 'right'], () => { cycleFocus(1); });
       btn.key(['S-tab', 'left'], () => { cycleFocus(-1); });
       btn.key(['escape'], () => {
@@ -609,10 +618,17 @@ export function createSetupTab(screen, services) {
     return { installBtn, removeBtn, configBtn };
   }
 
-  // Build all provider rows
+  // Build all provider rows.
+  // For the default provider, install/remove are hidden — push configBtn
+  // three times so the row-of-3 arrow-nav arithmetic still works (every
+  // "slot" in the default row lands on Configure, the only visible button).
   for (let i = 0; i < PROVIDERS.length; i++) {
     const { installBtn, removeBtn, configBtn } = createProviderRow(PROVIDERS[i], i);
-    providerFocusableItems.push(installBtn, removeBtn, configBtn);
+    if (PROVIDERS[i].isDefault) {
+      providerFocusableItems.push(configBtn, configBtn, configBtn);
+    } else {
+      providerFocusableItems.push(installBtn, removeBtn, configBtn);
+    }
   }
 
   function cycleFocus(dir) {
@@ -624,6 +640,10 @@ export function createSetupTab(screen, services) {
   // ── Provider install/remove handlers ──────────────────────────────────────
 
   async function handleProviderInstall(provider) {
+    // Remember which button the user was on so we can advance focus to
+    // the NEXT row (same column) after they dismiss the info page.
+    _preInfoFocusIndex = providerFocusIndex;
+
     if (provider.id === 'claude-code') {
       const wasInstalled = installedState[provider.id];
       const result = await installClaudeMcp(targetDir);
@@ -643,7 +663,6 @@ export function createSetupTab(screen, services) {
     if (provider.id === 'openai-codex') {
       const wasInstalled = installedState[provider.id];
       const result = await installCodexMcp(targetDir);
-      await installCopilotMcp(targetDir);
       await installCodexInstructions(targetDir, packageDir);
       await installCodexHooks(targetDir, packageDir);
       await refreshInstalledState();
@@ -652,6 +671,10 @@ export function createSetupTab(screen, services) {
   }
 
   async function handleProviderRemove(provider) {
+    // Remember which button the user was on so we can advance focus to
+    // the NEXT row (same column) after they dismiss the info page.
+    _preInfoFocusIndex = providerFocusIndex;
+
     if (provider.id === 'claude-code') {
       const result = await uninstallClaude(targetDir);
       await refreshInstalledState();
@@ -668,7 +691,6 @@ export function createSetupTab(screen, services) {
 
     if (provider.id === 'openai-codex') {
       await removeCodexMcp(targetDir);
-      await removeCopilotMcp(targetDir);
       await removeCodexInstructions(targetDir);
       await removeCodexHooks(targetDir);
       await refreshInstalledState();
@@ -683,6 +705,7 @@ export function createSetupTab(screen, services) {
       'claude-code': 'claude-code',
       'github-copilot': 'copilot',
       'openai-codex': 'codex',
+      'default': 'default',
     };
     const llmKey = llmKeyMap[provider.id] || provider.id;
     const config = loadLlmConfigSync(llmKey, targetDir);
@@ -701,6 +724,7 @@ export function createSetupTab(screen, services) {
       'claude-code': 'Claude Code here',
       'copilot': 'Copilot here',
       'codex': 'Codex here',
+      'default': '',  // empty by default — user sets via Configure
     };
 
     // Read global defaults for display
@@ -1432,10 +1456,18 @@ export function createSetupTab(screen, services) {
   function showAllProviderRows() {
     providerHeader.show();
     for (const row of providerRows) {
+      const provider = PROVIDERS.find(p => p.id === row.id);
       row.label.show();
       row.statusText.show();
-      row.installBtn.show();
-      row.removeBtn.show();
+      // The "default" provider has no install/remove semantics — keep its
+      // install/remove buttons hidden so only Configure shows.
+      if (provider?.isDefault) {
+        row.installBtn.hide();
+        row.removeBtn.hide();
+      } else {
+        row.installBtn.show();
+        row.removeBtn.show();
+      }
       row.configBtn.show();
     }
   }
@@ -1587,28 +1619,53 @@ export function createSetupTab(screen, services) {
     screen.render();
   }
 
-  function showProviderListView() {
+  function showProviderListView(targetIdx = 0) {
     providerView = 'list';
     infoBox.hide();
     contentBox.hide();
     showAllProviderRows();
-    providerFocusIndex = 0;
-    if (providerFocusableItems.length) providerFocusableItems[0].focus();
+    const max = providerFocusableItems.length;
+    if (max > 0) {
+      providerFocusIndex = ((targetIdx % max) + max) % max;
+      providerFocusableItems[providerFocusIndex].focus();
+    }
     screen.render();
   }
 
   infoBox.key(['escape', 'enter'], () => {
-    showProviderListView();
+    // After dismissing the install/remove info page, advance focus to the
+    // NEXT provider row but keep the same column (Install stays on Install,
+    // Remove stays on Remove, Configure stays on Configure).  Each row has
+    // 3 focusable slots so +3 moves one full row down with wraparound.
+    const max = providerFocusableItems.length;
+    const nextIdx = max > 0 ? (_preInfoFocusIndex + 3) % max : 0;
+    showProviderListView(nextIdx);
   });
 
+  // Captured by handleProviderInstall/Remove right before showing info.
+  // Defaults to 0 so the first-time flow still lands on Claude Code Install.
+  let _preInfoFocusIndex = 0;
+
   async function refreshInstalledState() {
     for (const p of PROVIDERS) {
+      // The "default" provider is config-only — always treat as available.
+      if (p.isDefault) {
+        installedState[p.id] = true;
+        continue;
+      }
       const checkFn = p.id === 'claude-code' ? checkClaudeInstalled
         : p.id === 'github-copilot' ? checkCopilotInstalled
         : checkCodexInstalled;
       installedState[p.id] = await checkFn(targetDir);
     }
     for (const row of providerRows) {
+      const provider = PROVIDERS.find(p => p.id === row.id);
+      // The default provider has no install state to display — show its
+      // config-only nature instead.
+      if (provider?.isDefault) {
+        row.statusText.setContent('{cyan-fg}[Config Only]{/cyan-fg}');
+        continue;
+      }
       const installed = installedState[row.id];
       row.statusText.setContent(
         installed

package/src/installer.js

@@ -4298,14 +4298,17 @@ async function handleMcpConfiguration(targetDir, options) {
   const mcpConfigPath = path.join(targetDir, '.mcp.json');
 
   // MCP server configuration for AgentVibes.
-  // The AGENTVIBES_LLM env var tells the MCP server which LLM is calling
-  // so per-LLM voice / pretext / music / effects routing works correctly.
+  //
+  // No `env.AGENTVIBES_LLM` block: GitHub Copilot CLI also reads project
+  // `.mcp.json` with precedence over its own `~/.copilot/mcp-config.json`,
+  // so setting `claude-code` here would mis-route Copilot CLI too.
+  // Instead, the MCP server auto-detects Claude Code via the `CLAUDECODE=1`
+  // env var that Claude Code sets on every subprocess it spawns.
   const mcpConfig = {
     mcpServers: {
       agentvibes: {
         command: 'npx',
-        args: ['-y', '--package=agentvibes', 'agentvibes-mcp-server'],
-        env: { AGENTVIBES_LLM: 'claude-code' }
+        args: ['-y', '--package=agentvibes', 'agentvibes-mcp-server']
       }
     }
   };
@@ -4320,18 +4323,78 @@ async function handleMcpConfiguration(targetDir, options) {
   }
 
   if (mcpExists) {
-    // Scenario 3: Config already exists - show manual instructions
+    // Existing config: upgrade it in-place.  Two jobs:
+    //   1. Ensure the agentvibes server entry exists.
+    //   2. STRIP any stale `env.AGENTVIBES_LLM` from earlier versions
+    //      (v5.1.2..v5.1.4) — setting it in `.mcp.json` broke Copilot CLI
+    //      routing because Copilot CLI also reads `.mcp.json` and would
+    //      adopt claude-code's env.  Claude Code is now auto-detected
+    //      downstream via the CLAUDECODE=1 env var.
+    let migrated = false;
+    let migrationError = null;
+    try {
+      const existingRaw = await fs.readFile(mcpConfigPath, 'utf8');
+      const existingCfg = JSON.parse(existingRaw);
+      if (existingCfg && typeof existingCfg === 'object') {
+        if (!existingCfg.mcpServers || typeof existingCfg.mcpServers !== 'object') {
+          existingCfg.mcpServers = {};
+        }
+        const current = existingCfg.mcpServers.agentvibes;
+        const hasStaleEnv = current?.env?.AGENTVIBES_LLM !== undefined;
+        const needsWrite = !current || hasStaleEnv;
+        if (needsWrite) {
+          // Preserve any OTHER env keys the user added manually (rare) but
+          // drop AGENTVIBES_LLM so Copilot CLI doesn't mis-route.
+          const cleanEnv = { ...(current?.env ?? {}) };
+          delete cleanEnv.AGENTVIBES_LLM;
+          const newEntry = {
+            command: 'npx',
+            args: ['-y', '--package=agentvibes', 'agentvibes-mcp-server'],
+          };
+          if (Object.keys(cleanEnv).length > 0) {
+            newEntry.env = cleanEnv;
+          }
+          existingCfg.mcpServers.agentvibes = newEntry;
+          await fs.writeFile(mcpConfigPath, JSON.stringify(existingCfg, null, 2) + '\n');
+          migrated = true;
+        }
+      }
+    } catch (err) {
+      migrationError = err;
+    }
+
+    if (migrated) {
+      console.log(
+        boxen(
+          chalk.green.bold('✅ MCP Configuration Updated\n\n') +
+          chalk.white('Your existing ') + chalk.cyan('.mcp.json') + chalk.white(' has been updated.\n') +
+          chalk.white('Claude Code is auto-detected via ') + chalk.cyan('CLAUDECODE=1') + chalk.white(' at runtime.'),
+          {
+            padding: 1,
+            margin: { top: 1, bottom: 1, left: 0, right: 0 },
+            borderStyle: 'double',
+            borderColor: 'green',
+          }
+        )
+      );
+      return;
+    }
+
+    // Migration was not needed (already correct) or failed — fall through
+    // to the manual-instructions box.
     console.log(
       boxen(
         chalk.yellow.bold('ℹ️  MCP Configuration Already Exists\n\n') +
         chalk.white('An ') + chalk.cyan('.mcp.json') + chalk.white(' file already exists in this project.\n\n') +
-        chalk.white('To add AgentVibes MCP server manually, add this\n') +
-        chalk.white('to your ') + chalk.cyan('mcpServers') + chalk.white(' section:'),
+        (migrationError
+          ? chalk.red('Could not auto-update it: ' + migrationError.message + '\n\n')
+          : chalk.gray('It already has the correct AgentVibes entry.\n\n')) +
+        chalk.white('To add or fix the AgentVibes MCP server manually, use:'),
         {
           padding: 1,
           margin: { top: 1, bottom: 1, left: 0, right: 0 },
           borderStyle: 'round',
-          borderColor: 'yellow',
+          borderColor: migrationError ? 'red' : 'yellow',
         }
       )
     );
@@ -4340,8 +4403,7 @@ async function handleMcpConfiguration(targetDir, options) {
     console.log(
       '\n"agentvibes": {\n' +
       '  "command": "npx",\n' +
-      '  "args": ["-y", "--package=agentvibes", "agentvibes-mcp-server"],\n' +
-      '  "env": { "AGENTVIBES_LLM": "claude-code" }\n' +
+      '  "args": ["-y", "--package=agentvibes", "agentvibes-mcp-server"]\n' +
       '}\n'
     );
 
@@ -4446,8 +4508,7 @@ async function handleMcpConfiguration(targetDir, options) {
       '  "mcpServers": {\n' +
       '    "agentvibes": {\n' +
       '      "command": "npx",\n' +
-      '      "args": ["-y", "--package=agentvibes", "agentvibes-mcp-server"],\n' +
-      '      "env": { "AGENTVIBES_LLM": "claude-code" }\n' +
+      '      "args": ["-y", "--package=agentvibes", "agentvibes-mcp-server"]\n' +
       '    }\n' +
       '  }\n' +
       '}\n'

package/src/services/llm-provider-service.js

@@ -27,8 +27,66 @@ export const PROVIDERS = [
     name: 'OpenAI Codex',
     desc: 'OpenAI CLI agent — .codex/config.toml + AGENTS.md',
   },
+  {
+    id: 'default',
+    name: 'Default (Fallback)',
+    desc: 'Used when any tool calls TTS without identifying its LLM',
+    // No install/uninstall — this is a config-only entry
+    isDefault: true,
+  },
 ];
 
+const DEFAULT_LLM_CONFIGS = {
+  // Fallback used when play-tts is invoked with no -llm flag.  Pretext is
+  // empty by default — users edit it via Setup → Default → Configure.  When
+  // empty, no prefix is prepended at all.
+  default: {
+    effects: 'light',
+    bgTrack: '',
+    bgVolume: '0.15',
+    voice: 'en_US-lessac-high',
+    pretext: '',
+    ttsEngine: 'piper',
+  },
+  'claude-code': {
+    effects: 'light',
+    bgTrack: 'agent_vibes_chillwave_v2_loop.mp3',
+    bgVolume: '0.15',
+    voice: 'en_US-lessac-high',
+    pretext: 'Claude Code here',
+    ttsEngine: 'piper',
+  },
+  copilot: {
+    effects: 'light',
+    bgTrack: 'agent_vibes_bossa_nova_v2_loop.mp3',
+    bgVolume: '0.15',
+    voice: 'en_US-libritts-high::Anna-11',
+    pretext: 'Copilot here',
+    ttsEngine: 'piper',
+  },
+  codex: {
+    effects: 'light',
+    bgTrack: 'agent_vibes_chillwave_v2_loop.mp3',
+    bgVolume: '0.15',
+    // NOTE: lessac-medium appears to silently fail to synthesize on some
+    // Windows Piper installs (loads the model, exits with no output).
+    // lessac-high works reliably, so use it as the default for codex.
+    voice: 'en_US-lessac-high',
+    pretext: 'Codex here',
+    ttsEngine: 'piper',
+  },
+};
+
+function ensureDefaultLlmConfigSync(llmKey, targetDir) {
+  const existing = loadLlmConfigSync(llmKey, targetDir);
+  if (existing.sourcePath) return;
+
+  const defaults = DEFAULT_LLM_CONFIGS[llmKey];
+  if (!defaults) return;
+
+  saveLlmConfigSync(llmKey, defaults, targetDir);
+}
+
 // ── Provider install-checks ─────────────────────────────────────────────────
 
 export async function checkClaudeInstalled(targetDir) {
@@ -73,12 +131,24 @@ export async function checkCodexInstalled(targetDir) {
 export async function installClaudeMcp(targetDir) {
   const mcpConfigPath = path.join(targetDir, '.mcp.json');
 
+  // The agentvibes server entry for Claude Code's .mcp.json.
+  //
+  // IMPORTANT: no `env.AGENTVIBES_LLM` block here.  GitHub Copilot CLI
+  // also reads project-level `.mcp.json` with precedence over its own
+  // `~/.copilot/mcp-config.json` — so if we set `AGENTVIBES_LLM=claude-code`
+  // in `.mcp.json`, Copilot CLI picks up that value too and mis-routes.
+  // Instead, the MCP server (mcp-server/server.py) auto-detects Claude
+  // Code via the `CLAUDECODE=1` env var that Claude Code sets on every
+  // subprocess it spawns.  Copilot CLI does NOT set that var, so its
+  // spawned MCP server correctly falls back to its own config.
+  const agentvibesServer = {
+    command: 'npx',
+    args: ['-y', '--package=agentvibes', 'agentvibes-mcp-server'],
+  };
+
   const mcpConfig = {
     mcpServers: {
-      agentvibes: {
-        command: 'npx',
-        args: ['-y', '--package=agentvibes', 'agentvibes-mcp-server'],
-      },
+      agentvibes: agentvibesServer,
     },
   };
 
@@ -86,15 +156,15 @@ export async function installClaudeMcp(targetDir) {
     let mcpCreated = false;
     try {
       await fs.access(mcpConfigPath);
-      // Already exists — merge agentvibes key if missing
+      // Already exists — merge / upgrade the agentvibes entry.  This also
+      // STRIPS any stale AGENTVIBES_LLM env block left over from v5.1.2..4
+      // so Copilot CLI stops mis-routing.
       try {
         const existing = JSON.parse(await fs.readFile(mcpConfigPath, 'utf8'));
-        if (!existing.mcpServers?.agentvibes) {
-          existing.mcpServers = existing.mcpServers || {};
-          existing.mcpServers.agentvibes = mcpConfig.mcpServers.agentvibes;
-          await fs.writeFile(mcpConfigPath, JSON.stringify(existing, null, 2) + '\n');
-          mcpCreated = true;
-        }
+        existing.mcpServers = existing.mcpServers || {};
+        existing.mcpServers.agentvibes = { ...agentvibesServer };
+        await fs.writeFile(mcpConfigPath, JSON.stringify(existing, null, 2) + '\n');
+        mcpCreated = true;
       } catch { /* parse error — don't corrupt */ }
     } catch {
       // File doesn't exist — create it
@@ -112,6 +182,7 @@ export async function installClaudeMcp(targetDir) {
     await installer.copyPluginFiles(targetDir, silentSpinner);
     await installer.copyBmadConfigFiles(targetDir, silentSpinner);
     await installer.copyBackgroundMusicFiles(targetDir, silentSpinner);
+    ensureDefaultLlmConfigSync('claude-code', targetDir);
 
     return { success: true, mcpCreated };
   } catch (err) {
@@ -247,6 +318,37 @@ export async function installCopilotMcp(targetDir) {
 
     mcpConfig.servers.agentvibes = agentvibesServer;
     await fs.writeFile(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+
+    // Also write ~/.copilot/mcp-config.json so the GitHub Copilot CLI
+    // (different product from VS Code Copilot Chat!) can find the
+    // agentvibes MCP server.  VS Code reads .vscode/mcp.json, but the
+    // CLI reads ONLY from ~/.copilot/mcp-config.json per docs:
+    // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
+    try {
+      const copilotHome = process.env.COPILOT_HOME ||
+        path.join(process.env.USERPROFILE || process.env.HOME || '', '.copilot');
+      const copilotMcpPath = path.join(copilotHome, 'mcp-config.json');
+      await fs.mkdir(copilotHome, { recursive: true });
+      let cliConfig = { mcpServers: {} };
+      try {
+        const existingCli = await fs.readFile(copilotMcpPath, 'utf8');
+        const parsedCli = JSON.parse(existingCli);
+        if (parsedCli && typeof parsedCli === 'object') {
+          cliConfig = parsedCli;
+          if (!cliConfig.mcpServers) cliConfig.mcpServers = {};
+        }
+      } catch { /* new file */ }
+      cliConfig.mcpServers.agentvibes = {
+        type: 'local',
+        command: 'npx',
+        args: ['-y', '--package=agentvibes', 'agentvibes-mcp-server'],
+        env: { AGENTVIBES_LLM: 'copilot' },
+        tools: ['*'],
+      };
+      await fs.writeFile(copilotMcpPath, JSON.stringify(cliConfig, null, 2) + '\n');
+    } catch { /* best effort — CLI might not be installed */ }
+
+    ensureDefaultLlmConfigSync('copilot', targetDir);
     return { success: true };
   } catch (err) {
     return { success: false, error: err.message };
@@ -300,6 +402,7 @@ export async function installCodexMcp(targetDir) {
     try { existing = await fs.readFile(tomlPath, 'utf8'); } catch { /* new file */ }
     const content = buildCodexToml(existing);
     await fs.writeFile(tomlPath, content);
+    ensureDefaultLlmConfigSync('codex', targetDir);
     return { success: true };
   } catch (err) {
     return { success: false, error: err.message };