agentvibes 5.2.0 → 5.3.0

package/.claude/hooks-windows/bmad-party-speak.ps1

@@ -242,7 +242,11 @@ try {
         try {
             # WaitOne throws AbandonedMutexException if prior process crashed while holding it.
             # That exception means we DID acquire the mutex — treat it as success (fixes M2).
-            $acquired = $mutex.WaitOne(60000)
+            # 600s timeout covers worst-case party-mode queue depth (9 agents x
+            # ~60s of speech each).  Shorter timeouts silently dropped the last
+            # agents to speak.  play-tts.ps1 bounds true stuck processes via its
+            # playback watchdog, so waiting longer here is safe.
+            $acquired = $mutex.WaitOne(600000)
         } catch [System.Threading.AbandonedMutexException] {
             $acquired = $true  # abandoned = we now own it
         }

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

@@ -16,14 +16,28 @@ param(
     [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_-]+$') {
-    Write-Error ("Invalid LLM provider name: '{0}' - must match {1}. Falling back to default config." -f $llm, '^[a-zA-Z0-9_-]+$')
+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 = ""
 }
 
@@ -53,63 +67,42 @@ if (-not $llm) {
 # 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.
+# --- 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.
 #
-# 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
-}
+# 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 {
-            # 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)
+            # 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 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.
+            # 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(-20)
+                $cutoff = (Get-Date).AddSeconds(-600)
                 $stuck = Get-CimInstance Win32_Process -ErrorAction SilentlyContinue |
                     Where-Object {
                         $_.Name -eq 'powershell.exe' -and
@@ -122,9 +115,28 @@ function Invoke-SerializedPlay {
                     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.")
+            [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
@@ -133,23 +145,18 @@ function Invoke-SerializedPlay {
             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 { }
         }
     }
 }
 
-# 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
 # Local project settings ALWAYS override global (~/.claude)
@@ -249,11 +256,26 @@ if ($llm) {
     $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
-$Pretext = $LlmPretext
-if (-not $Pretext) {
+#
+# 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",
@@ -569,6 +591,16 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                 $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)

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.2.0
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v5.3.0
 
 ---
 
@@ -43,7 +43,26 @@ Whether you're using Claude Code, GitHub Copilot, OpenAI Codex, Claude Desktop,
 
 ---
 
-## 🎯 NEW IN v5.2.0 — Remote Voice Preview + Caveman Mode + Voice Ratings
+## 🎯 NEW IN v5.3.0 — Take Control of Remote Voices
+
+- **Customize every remote announcement individually** — pass `--voice`, `--pretext`, `--music`, `--volume`, `--effects`, `--speed`, `--provider` on the command line for just that one message. No more editing config files and changing them back.
+- **Skip the intro phrase on demand** — `--pretext ""` suppresses the pretext for a single message.
+- **Long messages and special characters work correctly on Windows** — text with quotes, apostrophes, emoji, or multi-line content no longer gets truncated on its way to the voice engine.
+- **Voice playback works on Windows servers with no monitor** — a background helper runs in your user session and picks up announcements from a queue, so audio plays even when SSH'ing in headless.
+- **Voice preview on remote servers streams to the right device** — TUI preview no longer falls back to local audio on machines without speakers.
+- **No more double intro phrases** when both sender and receiver have pretext configured.
+- **55 new tests** for BMAD party mode voice assignment and agent isolation.
+
+## 🎯 v5.2.1 — Multi-LLM Identity & Install Polish
+
+- **Copilot gets its own voice + pretext + music** — "Copilot here" with bossa nova, fully distinct from Claude Code and Codex.
+- **Per-tool MCP configs with explicit identity** — `.vscode/mcp.json`, `.codex/config.toml`, `~/.copilot/mcp-config.json` each set their own `AGENTVIBES_LLM`.
+- **`get_config` MCP tool returns detected LLM** — calling assistants can confirm their routing and respond with the right voice.
+- **Setup nav: Install → Install → Install → Configure → Configure → Configure** — keyboard flow walks all three providers' Configures before landing on Default.
+- **Claude Code default background music** set to Chillwave.
+- **Linux compatibility refinements** — CRLF, permissions, transport provider override.
+
+## 🎯 v5.2.0 — Remote Voice Preview + Caveman Mode + Voice Ratings
 
 - **Caveman verbosity mode** — Ultra-terse TTS fragments. Set via `/agent-vibes:verbosity caveman`.
 - **👍/👎 voice ratings** — Press `+` to thumbs up, `-` to thumbs down in any voice list. Replaces star favorites.

package/RELEASE_NOTES.md

@@ -1,5 +1,135 @@
 # AgentVibes Release Notes
 
+## 🎯 v5.3.0 — Take Control of Remote Voices
+
+**Release Date:** April 2026
+
+If you're using AgentVibes to send voice announcements from a server to
+your phone, laptop, or another machine, this release puts you in the
+driver's seat. Every call can now pick its own voice, background music,
+intro phrase, reverb, volume, and speed — right from the command line,
+for just that one message.
+
+### ✨ What's New
+
+#### You can now customize every announcement individually
+
+Before, if you wanted a different voice or music for one specific
+message, you had to change a config file (and remember to change it
+back). Now you just add a flag to the command.
+
+Want Winston to speak in his British accent with jazz playing for this
+one deploy notification? Easy:
+
+```bash
+bash .claude/hooks/play-tts-ssh-remote.sh \
+  --text "Deploy complete" \
+  --voice "en_US-ryan-high" \
+  --pretext "Winston here" \
+  --music "Late Night Hip Hop Groove.mp3" \
+  --volume 0.25
+```
+
+Anything you don't specify falls back to your normal settings. Want to
+skip the intro phrase just this once? Pass `--pretext ""` and it stays
+silent before the message.
+
+**Available flags:**
+- `--voice` — which Piper voice to use
+- `--pretext` — the intro phrase before the message (pass `""` to skip it)
+- `--music` — background music track (filenames with spaces now work!)
+- `--volume` — how loud the background music is (0.0 to 1.0)
+- `--effects` — sound effects chain like reverb
+- `--speed` — how fast the voice speaks
+- `--provider` — which TTS engine to use
+- `--agent` — which agent personality to use
+
+The old way of calling the script still works, so nothing you've already
+set up will break.
+
+### 🛠 Reliability Fixes
+
+- **Long messages and special characters no longer get cut off.** On
+  Windows, long announcements or text with quotes, apostrophes, or
+  emoji were getting mangled before they reached the voice engine.
+  Fixed — your message now arrives exactly as you sent it, no matter
+  how long or weird.
+
+- **Voice announcements now work on Windows servers with no monitor.**
+  Windows refuses to play audio in the "service" session that SSH
+  normally uses. A small background helper now runs in your regular
+  user session and picks up announcements from a queue, so audio plays
+  correctly even on headless servers.
+
+- **Voice preview in the TUI works on remote servers.** Before, if you
+  previewed a voice from a server with no speakers, it would try to
+  play locally (and fail). Now it correctly streams to whatever remote
+  device you've configured.
+
+- **No more double intro phrases.** If you set a pretext on both the
+  sending server and the receiving machine, you used to hear it twice.
+  The sender's version wins now — the receiver won't add its own on top.
+
+- **Remote streaming settings now actually stick.** A recent change
+  accidentally caused remote-streaming setups (`ssh-remote`,
+  `agentvibes-receiver`) to get overridden and fall back to local
+  playback. Fixed.
+
+- **Long announcements don't get killed mid-sentence.** The safety
+  timeout that stops stuck audio was too aggressive for long messages.
+  It's now generous enough to handle paragraph-length announcements.
+
+- **Cleaner installer state** — when you install AgentVibes for Claude
+  Code, it now writes its TTS provider file explicitly instead of
+  relying on implicit state.
+
+### 🧪 Testing
+
+55 new tests make sure BMAD party mode keeps working: each agent gets
+their unique voice and music, agents don't accidentally share the same
+Piper speaker ID, and the installer always points party mode at the
+cross-platform entry point.
+
+---
+
+## 🎯 v5.2.1 — Multi-LLM Identity & Install Polish
+
+**Release Date:** April 2026
+
+Polished LLM routing for Copilot/Codex and refined the setup experience.
+
+### ✨ What's New
+
+#### Multi-LLM Identity Routing
+
+- **GitHub Copilot now gets its own voice, pretext, and background music** — fully distinct from Claude Code and Codex. Say hello to "Copilot here" with bossa nova on the way in.
+
+- **Per-tool MCP configs with explicit identity** — each AI tool (`.vscode/mcp.json`, `.codex/config.toml`, `~/.copilot/mcp-config.json`) sets its own `AGENTVIBES_LLM` so routing is deterministic.
+
+- **`get_config` MCP tool now returns the detected LLM** — so the calling assistant can confirm its routing and respond with the right voice out of the gate.
+
+- **Linux compatibility refinements** — CRLF line endings, permissions, and transport provider override handling.
+
+#### Setup Flow Improvements
+
+- **Keyboard navigation flow** — pressing Enter through the Install buttons (Claude → Copilot → Codex) now jumps to **Claude Configure** next, letting you walk all three Configures in order before landing on Default.
+
+- **Down-arrow skips the Default row** from Install/Remove columns (consistent with info-box dismiss nav).
+
+- **Partial install success messaging** — if file copies succeed but MCP config needs a nudge, you'll see a clear warning instead of a generic failure.
+
+#### Defaults
+
+- **Claude Code default background music** set to Chillwave (`agent_vibes_chillwave_v2_loop.mp3`).
+
+#### Under the Hood
+
+- LLM key validation tightened for safer env var handling.
+- Improved error logging for edge cases in Copilot CLI config writes.
+- Known limitation documented: if you launch VS Code from a Claude-Code-started terminal, `CLAUDECODE=1` can leak — workaround is to `unset CLAUDECODE` first.
+
+---
+
 ## 🎯 v5.2.0 — Remote Voice Preview + Caveman Mode + Voice Ratings
 
 **Release Date:** April 2026