agentvibes 5.3.0 → 5.5.0

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

@@ -12,167 +12,23 @@ param(
     [Parameter(Mandatory = $false, Position = 1)]
     [string]$VoiceOverride,
 
+    # LLM identity for per-LLM audio routing (e.g. "claude-code", "copilot", "codex").
+    # When provided, the router looks up an `llm:<name>` row in audio-effects.cfg
+    # to apply LLM-specific voice, pretext, reverb, and engine settings.
     [Parameter(Mandatory = $false)]
     [string]$llm = ""
 )
 
-# Text-file handoff: Windows command-line arg passing mangles text with
-# quotes, newlines, or non-ASCII characters. The SSH receiver watcher
-# (setup-ssh-receiver.ps1) writes long/special-char text to a UTF-8 temp
-# file and passes the sentinel "__from_file__" + AGENTVIBES_TEXT_FILE env
-# var. Load the real text here before any validation or synthesis.
-if ($Text -eq "__from_file__" -and $env:AGENTVIBES_TEXT_FILE) {
-    if (Test-Path $env:AGENTVIBES_TEXT_FILE) {
-        $Text = [System.IO.File]::ReadAllText($env:AGENTVIBES_TEXT_FILE, [System.Text.UTF8Encoding]::new($false))
-    } else {
-        Write-Error "AGENTVIBES_TEXT_FILE set to missing path: $($env:AGENTVIBES_TEXT_FILE)"
-        exit 1
-    }
-}
-
-# 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][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][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")
-
-# --- Playback watchdog ---
-# If playback itself hangs (SoundPlayer deadlock, audio device locked,
-# etc.), a sibling PowerShell job waits 120 seconds from the moment
-# playback STARTS 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.
-#
-# IMPORTANT: the watchdog is started AFTER mutex acquisition (inside
-# Invoke-SerializedPlay), not at script entry.  Starting it at script
-# entry caused round-robin / party-mode cut-offs: when 9 agents fire
-# text_to_speech in quick succession, later calls spend most of their
-# 120s budget waiting for the mutex, then get killed mid-playback.
-# The mutex WaitOne() bounds queue waiting separately.
-
-function Invoke-SerializedPlay {
-    param([Parameter(Mandatory)][string]$WavPath)
-    $acquired = $false
-    $watchdogJob = $null
-    try {
-        try {
-            # 600s timeout to acquire the playback mutex.  Covers worst-case
-            # queue depth (round-robin with 9 agents x ~60s of playback each).
-            # AbandonedMutexException means the holder's process actually
-            # died -- we inherit ownership.
-            $acquired = $_PlaybackMutex.WaitOne(600000)
-        } 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 10 minutes.  Past
-            # any legitimate playback window, so only truly stuck processes
-            # get killed.
-            try {
-                $myPid = $PID
-                $cutoff = (Get-Date).AddSeconds(-600)
-                $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 600s. A prior play-tts.ps1 process was stuck holding it and has been killed; the next TTS call should succeed.")
-            exit 2
-        }
-
-        # Start the watchdog NOW (after mutex acquisition) so its 120s
-        # budget covers only the playback itself, not time spent queued.
-        try {
-            $watchdogJob = Start-Job -ArgumentList $PID -ScriptBlock {
-                param($parentPid)
-                Start-Sleep -Seconds 120
-                try {
-                    $p = Get-Process -Id $parentPid -ErrorAction SilentlyContinue
-                    if ($p) {
-                        [Console]::Error.WriteLine("[AgentVibes] play-tts.ps1 playback watchdog fired -- force-killing pid $parentPid after 120s of playback")
-                        Stop-Process -Id $parentPid -Force -ErrorAction SilentlyContinue
-                    }
-                } catch { }
-            }
-        } catch {
-            $watchdogJob = $null
-        }
-
-        $player = $null
-        try {
-            $player = New-Object System.Media.SoundPlayer $WavPath
-            $player.PlaySync()
-        } finally {
-            if ($player) { $player.Dispose() }
-        }
-    } finally {
-        if ($watchdogJob) {
-            try {
-                Stop-Job -Job $watchdogJob -ErrorAction SilentlyContinue
-                Remove-Job -Job $watchdogJob -Force -ErrorAction SilentlyContinue
-            } catch { }
-        }
-        if ($acquired) {
-            try { $_PlaybackMutex.ReleaseMutex() } catch { }
-        }
-    }
-}
-
 # Configuration paths
-# Priority: CLAUDE_PROJECT_DIR env var -> script's parent project -> user profile
-# Local project settings ALWAYS override global (~/.claude)
+# First check if we're running from a project directory with .claude
 $ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
 
-if ($env:CLAUDE_PROJECT_DIR -and (Test-Path "$env:CLAUDE_PROJECT_DIR\.claude")) {
-    $ClaudeDir = "$env:CLAUDE_PROJECT_DIR\.claude"
+# Use project .claude if running from there, otherwise use user profile
+if (Test-Path $ProjectClaudeDir) {
+    $ClaudeDir = $ProjectClaudeDir
 } else {
-    $PackageClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
-    if (Test-Path $PackageClaudeDir) {
-        $ClaudeDir = $PackageClaudeDir
-    } elseif (Test-Path "$env:USERPROFILE\.claude\tts-provider.txt") {
-        $ClaudeDir = "$env:USERPROFILE\.claude"
-    } else {
-        $ClaudeDir = "$env:USERPROFILE\.claude"
-    }
+    $ClaudeDir = "$env:USERPROFILE\.claude"
 }
 
 $HooksDir = "$ClaudeDir\hooks-windows"
@@ -187,124 +43,9 @@ if (Test-Path $MuteFile) {
     }
 }
 
-# Per-LLM config lookup: if --llm is passed, look up llm:<name> in audio-effects.cfg
-# 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",
-        "$env:USERPROFILE\.claude\config\audio-effects.cfg"
-    )
-    foreach ($cfgPath in $cfgPaths) {
-        if (-not $LlmVoice -and -not $LlmPretext -and (Test-Path $cfgPath)) {
-            foreach ($line in (Get-Content $cfgPath)) {
-                if ($line -match $llmKeyPattern) {
-                    $parts = $line -split '\|'
-                    # 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()
-                    }
-                    if ($parts.Length -ge 6 -and $parts[5].Trim()) {
-                        $LlmPretext = $parts[5].Trim()
-                    }
-                    if ($parts.Length -ge 7 -and $parts[6].Trim()) {
-                        $LlmEngine = $parts[6].Trim()
-                    }
-                    break
-                }
-            }
-        }
-    }
-    # 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)
-    $env:AGENTVIBES_LLM_KEY = "llm:$llm"
-}
-
-# ---------------------------------------------------------------------------
-# Per-call env-var overrides (set by the SSH watcher from queue JSON).
-# These win over audio-effects.cfg lookup results for this call only.
-# ---------------------------------------------------------------------------
-if ($env:AGENTVIBES_OVERRIDE_MUSIC)   { $LlmBgTrack  = $env:AGENTVIBES_OVERRIDE_MUSIC }
-if ($env:AGENTVIBES_OVERRIDE_VOLUME)  { $LlmBgVolume = $env:AGENTVIBES_OVERRIDE_VOLUME }
-if ($env:AGENTVIBES_OVERRIDE_EFFECTS) { $LlmReverb   = $env:AGENTVIBES_OVERRIDE_EFFECTS }
-
-# 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
-#
-# Honor AGENTVIBES_NO_PRETEXT=1 for callers that already prepended a pretext
-# (e.g., the SSH receiver watcher — server already added its own pretext
-# before sending; double-prepending here would say "AgentVibes here, server-pretext, message").
-$Pretext = ""
-if ($env:AGENTVIBES_NO_PRETEXT -ne "1") {
-    $Pretext = $LlmPretext
-}
-if (-not $Pretext -and $env:AGENTVIBES_NO_PRETEXT -ne "1") {
-    $PretextSources = @(
-        (Join-Path $ProjectRoot ".agentvibes\config.json"),
-        "$ClaudeDir\config\tts-pretext.txt",
-        "$env:USERPROFILE\.agentvibes\config.json",
-        "$env:USERPROFILE\.claude\config\tts-pretext.txt"
-    )
-    foreach ($src in $PretextSources) {
-        if (-not $Pretext -and (Test-Path $src)) {
-            if ($src -match '\.json$') {
-                try {
-                    $avCfg = Get-Content $src -Raw | ConvertFrom-Json
-                    if ($avCfg.pretext) { $Pretext = $avCfg.pretext.Trim() }
-                } catch { }
-            } else {
-                $val = (Get-Content $src -Raw).Trim()
-                if ($val) { $Pretext = $val }
-            }
-        }
-    }
-}
-if ($Pretext) {
-    $Text = "$Pretext, $Text"
-}
 # Determine active provider
-# LLM-specific engine overrides global provider
-$ActiveProvider = "sapi"
-if ($LlmEngine) {
-    $ActiveProvider = $LlmEngine
-} elseif (Test-Path $ProviderFile) {
+$ActiveProvider = "windows-sapi"
+if (Test-Path $ProviderFile) {
     $ActiveProvider = (Get-Content $ProviderFile -Raw).Trim()
 }
 
@@ -312,18 +53,15 @@ if ($LlmEngine) {
 $ProviderScript = ""
 
 switch ($ActiveProvider) {
-    { $_ -in "sapi", "windows-sapi" } {
-        $ProviderScript = "$HooksDir\play-tts-sapi.ps1"
+    "windows-sapi" {
+        $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1"
     }
-    { $_ -in "piper", "windows-piper" } {
-        $ProviderScript = "$HooksDir\play-tts-piper.ps1"
+    "windows-piper" {
+        $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1"
     }
     "soprano" {
         $ProviderScript = "$HooksDir\play-tts-soprano.ps1"
     }
-    "termux-ssh" {
-        $ProviderScript = "$HooksDir\play-tts-termux-ssh.ps1"
-    }
     default {
         Write-Host "[ERROR] Unknown provider: $ActiveProvider" -ForegroundColor Red
         Write-Host "Use: .\provider-manager.ps1 list" -ForegroundColor Yellow
@@ -338,168 +76,258 @@ if (-not (Test-Path $ProviderScript)) {
 }
 
 # Check if background music is enabled
-# Primary source of truth: .agentvibes/config.json (used by TUI console)
-# Fallback: .claude/config/background-music-enabled.txt (legacy PowerShell config)
 $ConfigDir = "$ClaudeDir\config"
 $BgEnabled = $false
-$AgentVibesConfig = Join-Path (Split-Path -Parent $ClaudeDir) ".agentvibes\config.json"
-if (Test-Path $AgentVibesConfig) {
-    try {
-        $json = Get-Content $AgentVibesConfig -Raw | ConvertFrom-Json
-        if ($json.backgroundMusic -and $null -ne $json.backgroundMusic.enabled) {
-            $BgEnabled = [bool]$json.backgroundMusic.enabled
-        }
-    } catch {
-        $BgEnabled = $false
-    }
-} else {
-    # Fallback to legacy txt config
-    $BgEnabledFile = "$ConfigDir\background-music-enabled.txt"
-    if (Test-Path $BgEnabledFile) {
-        $BgEnabled = (Get-Content $BgEnabledFile -Raw).Trim() -eq "true"
-    }
-}
-
-# 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
+$BgEnabledFile = "$ConfigDir\background-music-enabled.txt"
+if (Test-Path $BgEnabledFile) {
+    $BgEnabled = (Get-Content $BgEnabledFile -Raw).Trim() -eq "true"
 }
 
 # Check if reverb is enabled (allowlist validation)
-# LLM-specific reverb overrides global setting
 $ReverbLevel = "off"
-if ($LlmReverb -and $LlmReverb -in @("off", "light", "medium", "heavy", "cathedral")) {
-    $ReverbLevel = $LlmReverb
-} else {
-    $ReverbFile = "$ConfigDir\reverb-level.txt"
-    if (Test-Path $ReverbFile) {
-        $reverbVal = (Get-Content $ReverbFile -Raw).Trim()
-        if ($reverbVal -in @("off", "light", "medium", "heavy", "cathedral")) {
-            $ReverbLevel = $reverbVal
-        }
+$ReverbFile = "$ConfigDir\reverb-level.txt"
+if (Test-Path $ReverbFile) {
+    $reverbVal = (Get-Content $ReverbFile -Raw).Trim()
+    if ($reverbVal -in @("off", "light", "medium", "heavy", "cathedral")) {
+        $ReverbLevel = $reverbVal
     }
 }
 $HasReverb = $ReverbLevel -ne "off"
 
 # Check ffmpeg availability for background music mixing or reverb
-# Refresh PATH from registry so newly-installed tools are found without shell restart
 $HasFfmpeg = $false
 if ($BgEnabled -or $HasReverb) {
     try {
         $null = Get-Command ffmpeg -ErrorAction Stop
         $HasFfmpeg = $true
-    } catch {
-        # PATH may be stale (common after winget install); refresh from registry
-        $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
-        try {
-            $null = Get-Command ffmpeg -ErrorAction Stop
-            $HasFfmpeg = $true
-        } catch {}
+    } catch {}
+}
+
+# ===========================================================================
+# Per-LLM Audio Routing
+# ===========================================================================
+# When mcp-server/server.py invokes play-tts.ps1 on Windows it passes the
+# -llm flag with the active LLM identity (e.g. "claude-code", "copilot",
+# "codex").  The router reads audio-effects.cfg and looks up the row whose
+# key is `llm:<name>`, allowing each LLM to have its own voice, pretext,
+# reverb, and engine without requiring global settings to be reconfigured.
+#
+# Expected audio-effects.cfg row format (pipe-delimited):
+#   llm:<name>|REVERB_PRESET|BACKGROUND_FILE|BACKGROUND_VOLUME|VOICE|PRETEXT|ENGINE
+#
+# Column descriptions:
+#   1. Key           - Must start with "llm:" followed by the LLM name
+#   2. REVERB_PRESET - One of: off, light, medium, heavy, cathedral (or blank)
+#   3. BACKGROUND_FILE - Filename relative to .claude/audio/tracks/ (or blank)
+#   4. BACKGROUND_VOLUME - Float 0.0-1.0 (or blank for default 0.25)
+#   5. VOICE         - Provider voice name to use (or blank for global default)
+#   6. PRETEXT       - Text prepended to all TTS utterances (or blank)
+#   7. ENGINE        - Windows engine: windows-sapi, windows-piper, soprano (or blank)
+#
+# Example rows:
+#   llm:claude-code|off|||en_US-amy-medium|Agent Vibes Here|windows-piper
+#   llm:copilot|light|||en_US-ryan-low||windows-sapi
+#   llm:codex|off||||Code complete|windows-piper
+#   llm:default|off|||||
+#
+# The "default" key is always looked up when no explicit -llm flag is
+# provided.  Configure it via Setup → Default → Configure in the TUI to
+# apply consistent audio settings across all LLM sessions.
+#
+# Security: The -llm value is validated against an allowlist regex so that
+# injected values like "-rf" or path-traversal strings are rejected before
+# they can appear in lookup keys, environment variables, or file paths.
+
+# --- Validate -llm parameter format ------------------------------------------
+if ($llm -and $llm -notmatch '^[a-zA-Z0-9][a-zA-Z0-9_-]*$') {
+    Write-Host "[WARNING] play-tts.ps1: Invalid -llm value '$llm' ignored" `
+        "(must match ^[a-zA-Z0-9][a-zA-Z0-9_-]*`$)" -ForegroundColor Yellow
+    $llm = ""
+}
+
+# --- Default fallback --------------------------------------------------------
+# An empty $llm routes through the "default" pseudo-LLM.  Users who configure
+# an `llm:default` row in audio-effects.cfg get consistent audio settings for
+# every LLM that doesn't pass its own -llm flag — a convenient global override
+# that doesn't require per-LLM configuration.
+if (-not $llm) {
+    $llm = "default"
+}
+
+# --- Export LLM key for child scripts ----------------------------------------
+# Provider scripts (play-tts-windows-*.ps1) and any other downstream tooling
+# can inspect AGENTVIBES_LLM_KEY to identify which LLM is currently speaking.
+# This mirrors the `export AGENTVIBES_LLM_KEY="llm:${LLM_PROVIDER}"` line in
+# the POSIX play-tts.sh so the cross-platform contract is symmetric.
+$env:AGENTVIBES_LLM_KEY = "llm:$llm"
+
+# --- Lookup per-LLM config in audio-effects.cfg ------------------------------
+# Scan project config first, then user-profile config.  Stop at first match.
+# Variables are intentionally prefixed with _ to distinguish LLM-local state
+# from the global session state set earlier in this script.
+$_LlmVoice    = ""
+$_LlmPretext  = ""
+$_LlmReverb   = ""
+$_LlmEngine   = ""
+$_LlmBgFile   = ""
+$_LlmBgVol    = ""
+$_LlmKey      = "llm:$llm"
+
+$_AudioEffectsCfgPaths = @(
+    (Join-Path $ClaudeDir "config\audio-effects.cfg"),
+    (Join-Path $env:USERPROFILE ".claude\config\audio-effects.cfg")
+)
+
+:llmCfgSearch foreach ($_cfgFile in $_AudioEffectsCfgPaths) {
+    if ((-not $_LlmVoice) -and (-not $_LlmPretext) -and (Test-Path $_cfgFile)) {
+        $cfgContent = Get-Content $_cfgFile -ErrorAction SilentlyContinue
+        if ($null -ne $cfgContent) {
+            foreach ($_cfgLine in $cfgContent) {
+                # Skip blank lines and comment / separator lines
+                $stripped = $_cfgLine.Trim()
+                if ($stripped.Length -eq 0 -or $stripped.StartsWith('#')) { continue }
+
+                # Split on pipe; expect at least the key column
+                $_cols = $_cfgLine -split '\|'
+                if ($_cols.Count -ge 1 -and $_cols[0].Trim() -eq $_LlmKey) {
+                    # Unpack columns defensively — missing columns stay empty
+                    if ($_cols.Count -ge 2) { $_LlmReverb  = $_cols[1].Trim() }
+                    if ($_cols.Count -ge 3) { $_LlmBgFile  = $_cols[2].Trim() }
+                    if ($_cols.Count -ge 4) { $_LlmBgVol   = $_cols[3].Trim() }
+                    if ($_cols.Count -ge 5) { $_LlmVoice   = $_cols[4].Trim() }
+                    if ($_cols.Count -ge 6) { $_LlmPretext = $_cols[5].Trim() }
+                    if ($_cols.Count -ge 7) { $_LlmEngine  = $_cols[6].Trim() }
+                    break llmCfgSearch
+                }
+            }
+        }
     }
 }
 
-# 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
+# --- Voice priority order (highest wins) -------------------------------------
+# 1. Explicit -VoiceOverride parameter (caller always wins)
+# 2. LLM-specific voice from audio-effects.cfg llm:<key> row
+# 3. BMAD agent voice from bmad-voice-map.json (resolved in provider scripts)
+# 4. Global active voice from tts-provider.txt / active-voice.txt
 
-# If background music or reverb enabled and ffmpeg available, tell provider to skip playback
-if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
-    $env:AGENTVIBES_NO_PLAY = "1"
+# Apply LLM-specific voice only when no explicit -VoiceOverride was passed
+if ($_LlmVoice -and -not $VoiceOverride) {
+    $VoiceOverride = $_LlmVoice
+}
+
+# --- Apply LLM-specific pretext ----------------------------------------------
+# Prepend the configured pretext (e.g. "Agent Vibes Here") to the speech
+# text.  Guard against double-prefixing on re-entrant or looped calls by
+# checking whether the text already starts with the pretext string.
+if ($_LlmPretext -and -not $Text.StartsWith($_LlmPretext)) {
+    $Text = "$_LlmPretext, $Text"
 }
 
-# Call the provider script (skip if using pre-synthesized audio)
-# When post-processing (reverb/music), capture output preserving InformationRecord colors.
-# Otherwise call directly so Write-Host colors pass through to the terminal.
-$NeedsPostProcess = ($BgEnabled -or $HasReverb) -and $HasFfmpeg
-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) {
-        try {
-            Invoke-SerializedPlay -WavPath $PreSynthWav
-        } catch {
-            Write-Host "[WARNING] Pre-synth playback failed: $_" -ForegroundColor Yellow
+# --- Reverb override from per-LLM config -------------------------------------
+# If the llm:<key> row specifies a reverb preset, override the file-based
+# $ReverbLevel that was set from reverb-level.txt earlier.  The allowlist
+# check is repeated here so a malformed config row can't inject arbitrary
+# strings into the ffmpeg filter chain.
+if ($_LlmReverb) {
+    $validReverbLevels = @("off", "light", "medium", "heavy", "cathedral")
+    if ($validReverbLevels -contains $_LlmReverb) {
+        $ReverbLevel = $_LlmReverb
+        $HasReverb = $ReverbLevel -ne "off"
+        # If the LLM config enables reverb and ffmpeg wasn't found yet, retry
+        if ($HasReverb -and -not $HasFfmpeg) {
+            try { $null = Get-Command ffmpeg -ErrorAction Stop; $HasFfmpeg = $true } catch {}
         }
-        Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
-        exit 0
     }
-} else {
-    try {
-        if ($NeedsPostProcess) {
-            if ($VoiceOverride) {
-                $providerOutput = & $ProviderScript $Text $VoiceOverride 6>&1 2>&1
-            } else {
-                $providerOutput = & $ProviderScript $Text 6>&1 2>&1
-            }
-            # Re-emit preserving colors from InformationRecords (Write-Host output)
-            foreach ($item in $providerOutput) {
-                if ($item -is [System.Management.Automation.InformationRecord]) {
-                    $msg = $item.MessageData
-                    if ($msg -is [System.Management.Automation.HostInformationMessage]) {
-                        Write-Host $msg.Message -ForegroundColor $msg.ForegroundColor -NoNewline:$msg.NoNewLine
-                        if (-not $msg.NoNewLine) { Write-Host }
-                    } else {
-                        Write-Host "$item"
-                    }
-                } else {
-                    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
-            } else {
-                & $ProviderScript $Text
-            }
+}
+
+# --- Apply LLM-specific engine override --------------------------------------
+# Allowed local Windows engines: windows-sapi, windows-piper, soprano.
+# Transport providers (ssh-remote etc.) are not listed because they forward
+# TTS to a remote host — overriding with a local engine would synthesize on
+# the wrong machine.
+if ($_LlmEngine) {
+    $allowedLocalEngines = @("windows-sapi", "windows-piper", "soprano")
+    if ($allowedLocalEngines -contains $_LlmEngine) {
+        switch ($_LlmEngine) {
+            "windows-sapi"  { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1"  }
+            "windows-piper" { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
+            "soprano"       { $ProviderScript = "$HooksDir\play-tts-soprano.ps1"        }
         }
+    } else {
+        Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' in audio-effects.cfg — keeping default provider" -ForegroundColor DarkGray
     }
-    catch {
-        Write-Host "[ERROR] TTS Error: $_" -ForegroundColor Red
-        Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
-        exit 1
+}
+
+# --- BMAD Party Mode note ----------------------------------------------------
+# When BMAD party mode is active, multiple agents speak in rapid succession.
+# Each agent's voice is resolved from bmad-voice-map.json inside the provider
+# scripts — that BMAD-level routing is independent of this per-LLM system.
+# The -llm flag is still used to set AGENTVIBES_LLM_KEY and can supply a
+# background music track and reverb preset that stays consistent throughout
+# the entire party mode session regardless of which agent is speaking.
+
+# --- Diagnostic output -------------------------------------------------------
+# Set AGENTVIBES_VERBOSE=1 in the shell environment to print routing state.
+if ($env:AGENTVIBES_VERBOSE -eq "1") {
+    Write-Host "[DEBUG] play-tts.ps1 LLM routing: llm=$llm | voice=$VoiceOverride | engine=$_LlmEngine | pretext=$_LlmPretext" -ForegroundColor DarkCyan
+    Write-Host "[DEBUG] play-tts.ps1 LLM routing: reverb=$ReverbLevel | HasFfmpeg=$HasFfmpeg | BgEnabled=$BgEnabled | script=$ProviderScript" -ForegroundColor DarkCyan
+}
+
+# ===========================================================================
+# End of Per-LLM Audio Routing
+# ===========================================================================
+
+# Helper: play a WAV file preferring ffplay over SoundPlayer.
+# SoundPlayer uses WinMM's low-quality resampler (22050 Hz → 48000 Hz is choppy);
+# ffplay uses libswresample with sinc resampling — no artefacts.
+function Invoke-AudioPlay {
+    param([string]$FilePath)
+    $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+    if (-not $fp) {
+        # Watcher sessions may inherit a minimal PATH — refresh from registry
+        $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" +
+                    [System.Environment]::GetEnvironmentVariable("Path","User")
+        $fp = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
     }
+    if ($fp) {
+        & $fp -autoexit -nodisp -loglevel quiet $FilePath 2>$null
+    } else {
+        $p = $null
+        try   { $p = New-Object System.Media.SoundPlayer $FilePath; $p.PlaySync() }
+        finally { if ($p) { $p.Dispose() } }
+    }
+}
+
+# If background music or reverb enabled and ffmpeg available, tell provider to skip playback
+if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
+    $env:AGENTVIBES_NO_PLAY = "1"
+}
+
+# Call the provider script
+try {
+    if ($VoiceOverride) {
+        $providerOutput = & $ProviderScript $Text $VoiceOverride 2>&1
+    }
+    else {
+        $providerOutput = & $ProviderScript $Text 2>&1
+    }
+    # Show provider output
+    $providerOutput | ForEach-Object { Write-Host $_ }
+}
+catch {
+    Write-Host "[ERROR] TTS Error: $_" -ForegroundColor Red
+    $env:AGENTVIBES_NO_PLAY = $null
+    exit 1
 }
 
 # Apply reverb and/or mix with background music
 if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
-    Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
+    $env:AGENTVIBES_NO_PLAY = $null
 
-    # 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.
+    # Find the most recent TTS wav file
     $AudioDir = "$ClaudeDir\audio"
-    $RecentWav = if ($UsePreSynth) {
-        Get-Item $PreSynthWav -ErrorAction SilentlyContinue
-    } elseif ($FreshSynthFile -and (Test-Path $FreshSynthFile)) {
-        Get-Item $FreshSynthFile -ErrorAction SilentlyContinue
-    } else {
-        $null
-    }
+    $RecentWav = Get-ChildItem -Path $AudioDir -Filter "tts-*.wav" -ErrorAction SilentlyContinue |
+        Sort-Object LastWriteTime -Descending | Select-Object -First 1
 
     if ($RecentWav -and $RecentWav.Length -gt 0) {
         $voicePath = $RecentWav.FullName
@@ -514,12 +342,9 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                 default     { "" }
             }
             if ($reverbFilter) {
-                # 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"
+                $reverbedFile = "$AudioDir\tts-reverbed.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"
+                $proc = Start-Process -FilePath "ffmpeg" -ArgumentList $reverbArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "NUL"
                 if ($proc.ExitCode -eq 0 -and (Test-Path $reverbedFile)) {
                     $voicePath = $reverbedFile
                 }
@@ -528,101 +353,40 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
 
         # Mix with background music if enabled
         if ($BgEnabled) {
-            # Read background track and volume from audio-effects.cfg (matches Linux behavior)
+            # Get background track - default to bachata, or read from config
             $TracksDir = "$ClaudeDir\audio\tracks"
-            $DefaultTrack = ""
-            $BgVolume = "0.25"
-            $AudioEffectsCfg = "$ConfigDir\audio-effects.cfg"
-
-            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
-                $agentName = $env:AGENTVIBES_AGENT_NAME
-                $configLine = $null
-
-                $cfgLines = Get-Content $AudioEffectsCfg
-                if ($agentName) {
-                    foreach ($line in $cfgLines) {
-                        if ($line -match "^$([regex]::Escape($agentName))\|") {
-                            $configLine = $line
-                            break
-                        }
-                    }
-                }
-                # Try LLM-specific config (--llm parameter)
-                if (-not $configLine -and $llm) {
-                    $llmBgKey = "llm:$llm"
-                    foreach ($line in $cfgLines) {
-                        if ($line -match "^$([regex]::Escape($llmBgKey))\|") {
-                            $configLine = $line
-                            break
-                        }
-                    }
-                }
-                # Fall back to default
-                if (-not $configLine) {
-                    foreach ($line in $cfgLines) {
-                        if ($line -match '^default\|') {
-                            $configLine = $line
-                            break
-                        }
-                    }
-                }
-
-                if ($configLine) {
-                    $parts = $configLine -split '\|'
-                    if ($parts.Length -ge 3 -and $parts[2]) {
-                        $trackName = $parts[2].Trim()
-                        # Validate: filename only, no path separators or traversal
-                        if ($trackName -match '^[a-zA-Z0-9_\-\. ]+$') {
-                            $DefaultTrack = $trackName
-                        }
-                    }
-                    if ($parts.Length -ge 4 -and $parts[3]) {
-                        $volVal = $parts[3].Trim()
-                        if ($volVal -match '^\d+\.?\d*$') { $BgVolume = $volVal }
-                    }
+            $DefaultTrack = "agent_vibes_bachata_v1_loop.mp3"
+            $DefaultTrackFile = "$ConfigDir\background-music-default.txt"
+            if (Test-Path $DefaultTrackFile) {
+                $configTrack = (Get-Content $DefaultTrackFile -Raw).Trim()
+                # Validate: filename only, no path separators or traversal
+                if ($configTrack -and $configTrack -match '^[a-zA-Z0-9_\-\.]+$') {
+                    $DefaultTrack = $configTrack
                 }
             }
-
-            # Fallback if no track found in config
-            if (-not $DefaultTrack) {
-                $DefaultTrack = "agent_vibes_celtic_harp_v1_loop.mp3"
-            }
-
-            # Per-call env-var overrides (set by SSH watcher from queue JSON).
-            # Win over audio-effects.cfg lookup above.  Validate filename to
-            # prevent path traversal before accepting.
-            if ($env:AGENTVIBES_OVERRIDE_MUSIC -and $env:AGENTVIBES_OVERRIDE_MUSIC -match '^[a-zA-Z0-9_\-\. ]+$') {
-                $DefaultTrack = $env:AGENTVIBES_OVERRIDE_MUSIC
-            }
-            if ($env:AGENTVIBES_OVERRIDE_VOLUME -and $env:AGENTVIBES_OVERRIDE_VOLUME -match '^\d+\.?\d*$') {
-                $BgVolume = $env:AGENTVIBES_OVERRIDE_VOLUME
-            }
-
             $BgTrackPath = Join-Path $TracksDir $DefaultTrack
             # Path containment: verify resolved path stays within tracks directory
             $ResolvedBgTrack = [System.IO.Path]::GetFullPath($BgTrackPath)
             $ResolvedTracksDir = [System.IO.Path]::GetFullPath($TracksDir)
             if (-not $ResolvedBgTrack.StartsWith($ResolvedTracksDir + [System.IO.Path]::DirectorySeparatorChar)) {
-                $BgTrackPath = Join-Path $TracksDir "agent_vibes_celtic_harp_v1_loop.mp3"
+                $BgTrackPath = Join-Path $TracksDir "agent_vibes_bachata_v1_loop.mp3"
+            }
+
+            # Get volume (default 0.25)
+            $BgVolume = "0.25"
+            $VolumeFile = "$ConfigDir\background-music-volume.txt"
+            if (Test-Path $VolumeFile) {
+                $vol = (Get-Content $VolumeFile -Raw).Trim()
+                if ($vol -match '^\d+\.?\d*$') { $BgVolume = $vol }
             }
 
             if (Test-Path $BgTrackPath) {
-                # 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"
+                $MixedFile = $RecentWav.FullName -replace '\.wav$', '-mixed.wav'
 
                 try {
                     # Get voice duration to calculate total length
                     $probArgs = "-v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 `"$voicePath`""
-                    $durationProc = Start-Process -FilePath "ffprobe" -ArgumentList $probArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "$env:TEMP\agentvibes-ffmpeg-stderr.txt" -RedirectStandardOutput "$env:TEMP\agentvibes-duration.txt"
+                    $durationProc = Start-Process -FilePath "ffprobe" -ArgumentList $probArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "NUL" -RedirectStandardOutput "$env:TEMP\agentvibes-duration.txt"
                     $voiceDuration = 5  # default fallback
                     if (Test-Path "$env:TEMP\agentvibes-duration.txt") {
                         $durStr = (Get-Content "$env:TEMP\agentvibes-duration.txt" -Raw).Trim()
@@ -633,43 +397,37 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                     $fadeOutStart = $totalDuration - 2
 
                     # Filter: music fades in 0.5s, voice delayed 2s, music fades out last 2s
-                    $filter = "[0:a]volume=${BgVolume},afade=t=in:d=0.5,afade=t=out:st=${fadeOutStart}:d=2[bg];[1:a]adelay=1000|1000,volume=1.5,apad=pad_dur=2[voice];[bg][voice]amix=inputs=2:duration=longest:dropout_transition=2:normalize=0[out]"
+                    $filter = "[0:a]volume=${BgVolume},afade=t=in:d=0.5,afade=t=out:st=${fadeOutStart}:d=2[bg];[1:a]adelay=2000|2000,apad=pad_dur=2[voice];[bg][voice]amix=inputs=2:duration=longest:dropout_transition=2[out]"
 
                     # Run ffmpeg - use Start-Process to avoid stderr issues with $ErrorActionPreference
                     $ffmpegArgs = "-y -stream_loop -1 -i `"$BgTrackPath`" -i `"$voicePath`" -filter_complex `"$filter`" -map `"[out]`" -t $totalDuration `"$MixedFile`""
-                    $proc = Start-Process -FilePath "ffmpeg" -ArgumentList $ffmpegArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "$env:TEMP\agentvibes-ffmpeg-stderr.txt"
+                    $proc = Start-Process -FilePath "ffmpeg" -ArgumentList $ffmpegArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "NUL"
 
                     if ($proc.ExitCode -eq 0 -and (Test-Path $MixedFile) -and (Get-Item $MixedFile).Length -gt 0) {
-                        # Play the mixed audio (via serialized mutex)
+                        # Play the mixed audio
                         try {
-                            Invoke-SerializedPlay -WavPath $MixedFile
+                            Invoke-AudioPlay $MixedFile
                         } catch {
                             Write-Host "[WARNING] Mixed playback failed, playing voice only" -ForegroundColor Yellow
-                            Invoke-SerializedPlay -WavPath $voicePath
+                            Invoke-AudioPlay $voicePath
                         }
                     } else {
                         # Mixing failed, play voice only
-                        Invoke-SerializedPlay -WavPath $voicePath
+                        Invoke-AudioPlay $voicePath
                     }
                 } catch {
                     # ffmpeg failed, play voice only
-                    Invoke-SerializedPlay -WavPath $voicePath
+                    Invoke-AudioPlay $voicePath
                 }
             } else {
                 # No background track found, play voice only
-                Invoke-SerializedPlay -WavPath $voicePath
+                Invoke-AudioPlay $voicePath
             }
         } else {
             # No background music, play the (possibly reverbed) voice
-            Invoke-SerializedPlay -WavPath $voicePath
+            Invoke-AudioPlay $voicePath
         }
     }
 } else {
-    Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
+    $env:AGENTVIBES_NO_PLAY = $null
 }
-
-# Explicit exit 0 so that $LASTEXITCODE from native commands (piper.exe,
-# ffmpeg, sox, etc.) doesn't leak through as the process exit code.
-# Without this, bash/Claude Code sees whatever random exit code the last
-# native command returned (e.g. 127) and treats it as a TTS failure.
-exit 0