agentvibes 5.1.3 → 5.2.0

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

@@ -17,18 +17,141 @@ param(
 )
 
 # Security: Validate LLM provider name (alphanumeric, hyphens, underscores
-# only) — mirrors play-tts.sh line 92.  This prevents weird values from
+# 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: '$llm' — must match ^[a-zA-Z0-9_-]+$. Falling back to default config."
+    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
 
@@ -58,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",
@@ -76,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()
                     }
@@ -96,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)
@@ -105,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 = @(
@@ -132,7 +277,6 @@ if (-not $Pretext) {
 if ($Pretext) {
     $Text = "$Pretext, $Text"
 }
-
 # Determine active provider
 # LLM-specific engine overrides global provider
 $ActiveProvider = "sapi"
@@ -194,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"
@@ -227,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
@@ -245,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
@@ -279,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
@@ -298,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) {
@@ -320,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)) {
@@ -340,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
 
@@ -378,7 +553,7 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                     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_\-\.]+$') {
+                        if ($trackName -match '^[a-zA-Z0-9_\-\. ]+$') {
                             $DefaultTrack = $trackName
                         }
                     }
@@ -403,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
@@ -426,64 +608,36 @@ 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 {
     Remove-Item env:AGENTVIBES_NO_PLAY -ErrorAction SilentlyContinue
 }
+
+# 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

package/.claude/hooks-windows/session-start-tts.ps1

@@ -56,6 +56,7 @@ $VerbositySection = switch ($Verbosity) {
     "low"    { "## Verbosity: LOW`n- Acknowledgment: Action only`n- Completion: Result + errors only`n- Skip: Reasoning, decisions" }
     "medium" { "## Verbosity: MEDIUM`n- Acknowledgment: Action + key approach`n- Completion: Result + important decisions`n- Include: Major choices only" }
     "high"   { "## Verbosity: HIGH`n- Acknowledgment: Action + approach + why`n- Completion: Result + decisions + trade-offs`n- Include: Full reasoning, alternatives" }
+    "caveman" { "## Verbosity: CAVEMAN`n- Respond terse. All technical substance stays. Only fluff dies.`n- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging`n- Abbreviate: DB/auth/config/req/res/fn/impl. Use arrows (X -> Y). Strip conjunctions.`n- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.`n- Pattern: [thing] [action] [reason]. [next step].`n- TTS: Ultra-short. Max 60 chars." }
     default  { "## Verbosity: LOW`n- Acknowledgment: Action only`n- Completion: Result + errors only" }
 }
 
@@ -86,7 +87,7 @@ $VerbositySection
 4. Keep under 150 chars
 5. Always include errors
 
-Quick Ref: low=action+result | medium=+key decisions | high=+full reasoning
+Quick Ref: low=action+result | medium=+key decisions | high=+full reasoning | caveman=ultra-terse fragments
 
 ## BMAD Agent Voice Routing
 If ``.bmad-agent-context`` exists, check its content: