agentvibes 5.11.2 → 5.12.0

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

@@ -213,7 +213,7 @@ if ($BgEnabled -or $HasReverb) {
 #   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)
+#   4. BACKGROUND_VOLUME - Float 0.0-1.0 (or blank for default 0.20)
 #   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)
@@ -263,6 +263,99 @@ if (-not $llm) {
 # the POSIX play-tts.sh so the cross-platform contract is symmetric.
 $env:AGENTVIBES_LLM_KEY = "llm:$llm"
 
+# ── Utterance Resolver (AVI-S8.5 Stage 2) ────────────────────────────────────
+# Single source of truth for the voice + engine decision, mirroring the bash
+# play-tts.sh port. Resolve the plan ONCE and adopt its voice (per-LLM voice
+# wins over an LLM-echoed explicit override — R2) and, below, its local engine
+# (a kokoro-shaped voice forces the kokoro engine and engine aliases normalize —
+# R1/F5). FAIL-SAFE: if node or the resolver bundle isn't reachable (e.g. an
+# installed ~/.claude that predates the bundle-shipping installer), $PlanOk
+# stays $false and the legacy logic below runs unchanged — Windows TTS never
+# breaks on a missing bridge. AGENTVIBES_RESOLVER_CLI lets the installer (or
+# tests) point at the resolver bundle when it lives outside the hooks tree.
+
+# Map a resolver engine name to its Windows provider script. Returns $null for
+# engines with no local Windows script (e.g. elevenlabs/macos) so the caller
+# keeps the current provider rather than breaking playback.
+function Resolve-ProviderScriptForEngine {
+    param([string]$Engine, [string]$HooksRoot)
+    switch ($Engine) {
+        { $_ -in "windows-sapi", "sapi" } {
+            $s = "$HooksRoot\play-tts-sapi.ps1"
+            if (-not (Test-Path $s)) { $s = "$HooksRoot\play-tts-windows-sapi.ps1" }
+            return $s
+        }
+        { $_ -in "windows-piper", "piper" } {
+            $s = "$HooksRoot\play-tts-piper.ps1"
+            if (-not (Test-Path $s)) { $s = "$HooksRoot\play-tts-windows-piper.ps1" }
+            return $s
+        }
+        "soprano" { return "$HooksRoot\play-tts-soprano.ps1" }
+        "kokoro"  { return "$HooksRoot\play-tts-kokoro.ps1" }
+        default   { return $null }
+    }
+}
+
+$_OrigExplicitVoice = $VoiceOverride   # raw positional voice, before any per-LLM override
+$PlanOk         = $false
+$PlanVoice      = ""
+$PlanEngine     = ""
+$PlanVoiceIsOverride = $false
+# F-3: the SSH-receiver watcher forwards the sender's engine via -ProviderOverride
+# (a parameter the resolver can't see). Seed AGENTVIBES_FORCE_PROVIDER from it so
+# the resolver honors the forwarded provider instead of defaulting the plan engine
+# to piper (which dropped a forwarded windows-sapi/soprano voice → wrong/no audio).
+if ($ProviderOverride) {
+    # A fresh -ProviderOverride for THIS request must win over any stale/inherited
+    # AGENTVIBES_FORCE_PROVIDER in the environment (a validated allowlist only).
+    switch ($ProviderOverride) {
+        { $_ -in @('piper','soprano','macos','windows-sapi','sapi','kokoro','elevenlabs','windows-piper') } {
+            $env:AGENTVIBES_FORCE_PROVIDER = $ProviderOverride
+        }
+    }
+}
+$_ResolverCli = ""
+foreach ($_cand in @(
+        $env:AGENTVIBES_RESOLVER_CLI,
+        (Join-Path $ScriptPath "..\agentvibes-resolver\bin\resolve-utterance.js"),
+        (Join-Path $ScriptPath "..\..\bin\resolve-utterance.js"),
+        (Join-Path $ScriptPath "resolve-utterance.js"))) {
+    if ($_cand -and (Test-Path $_cand)) { $_ResolverCli = $_cand; break }
+}
+$_NodeCmd = Get-Command node -ErrorAction SilentlyContinue
+if ($_ResolverCli -and $_NodeCmd) {
+    # Voice provenance (F-1): AGENTVIBES_VOICE_SOURCE lets a caller declare it
+    # (MCP/watcher → user-explicit/agent-profile); audition never demotes; else
+    # llm-echo (parroted get_config voice, which the per-LLM row overrides — R2).
+    $_VoiceSource = if ($env:AGENTVIBES_VOICE_SOURCE) { $env:AGENTVIBES_VOICE_SOURCE }
+                    elseif ($env:AGENTVIBES_EFFECTS_PREVIEW) { "audition" }
+                    else { "llm-echo" }
+    $_ResolverPackageRoot = Split-Path -Parent $ClaudeDir
+    $_ResolverProjectDir = if ($env:CLAUDE_PROJECT_DIR) { $env:CLAUDE_PROJECT_DIR } else { $_ResolverPackageRoot }
+    $_ResolverArgs = @('--format', 'json', '--text', $Text, '--llm', $llm,
+                       '--voice-source', $_VoiceSource, '--project-dir', $_ResolverProjectDir,
+                       '--package-root', $_ResolverPackageRoot)
+    # Only pass --voice when there IS an explicit voice; an absent flag tells the
+    # resolver "no explicit override" (so per-LLM routing applies cleanly).
+    if ($_OrigExplicitVoice) { $_ResolverArgs += @('--voice', $_OrigExplicitVoice) }
+    try {
+        $_PlanJson = & $_NodeCmd.Source $_ResolverCli @_ResolverArgs 2>$null
+        if ($LASTEXITCODE -eq 0 -and $_PlanJson) {
+            $_Plan = ($_PlanJson | Out-String).Trim() | ConvertFrom-Json
+            if ($_Plan) {
+                $PlanOk = $true
+                if ($_Plan.voice)  { $PlanVoice  = [string]$_Plan.voice }
+                if ($_Plan.engine) { $PlanEngine = [string]$_Plan.engine }
+                $PlanVoiceIsOverride = [bool]$_Plan.voiceIsOverride
+            }
+        }
+    } catch {
+        # Any bridge failure (bad JSON, nonzero exit, missing bundle) fails safe
+        # to the legacy logic below.
+        $PlanOk = $false
+    }
+}
+
 # --- 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
@@ -320,8 +413,20 @@ $_LlmFound = $false
 # 3. BMAD agent voice from bmad-voice-map.json (resolved in provider scripts)
 # 4. Global active voice from tts-provider.txt / active-voice.txt
 
-# Apply LLM-specific voice only when no explicit -VoiceOverride was passed
-if ($_LlmVoice -and -not $VoiceOverride) {
+# Adopt the resolver's voice when a plan resolved (AVI-S8.5 Stage 2). The plan
+# already applied the R2 precedence (per-LLM voice wins over an LLM-echoed
+# explicit override; genuine explicit/audition voices still win), so take it
+# verbatim. FAIL-SAFE fallback: with no plan, use the legacy explicit-wins order
+# (explicit -VoiceOverride > per-LLM voice).
+# F-2: adopt the plan voice ONLY when it's a real override (explicit pick or
+# per-LLM row) — not the provider's stored voice file. A plain provider-file
+# voice is left empty here so the provider script does its own file+model+speaker
+# resolution (adopting it as an explicit override skips piper's multi-speaker
+# lookup and plays speaker 0). Engine coupling (R1) still applies regardless.
+if ($PlanOk -and $PlanVoiceIsOverride -and $PlanVoice) {
+    $VoiceOverride = $PlanVoice
+}
+elseif (-not $PlanOk -and $_LlmVoice -and -not $VoiceOverride) {
     $VoiceOverride = $_LlmVoice
 }
 
@@ -398,31 +503,45 @@ if ($OverrideEffects -ne "" -and $OverrideEffects -in @("off", "light", "medium"
 # piper/sapi for that LLM's normal text responses that use Piper voices — must
 # NOT redirect it to an incompatible engine, or synthesis fails silently
 # (Piper can't find the Kokoro voice model → no audio, exit 0).
-$_VoiceIsKokoro = $VoiceOverride -match '^[a-z]{2}_[a-z0-9_]+$'
-if ($_VoiceIsKokoro) {
-    # A Kokoro-format voice forces the Kokoro engine regardless of the per-LLM
-    # ENGINE column or the global tts-provider.txt default.
-    $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
-}
-elseif ($_LlmEngine) {
-    # Accept both canonical Windows names and the cross-platform aliases the TUI
-    # writes (e.g. "piper" saved on a Linux/WSL install that is later read on
-    # Windows, or "sapi" as a short form).  Unknown values keep the global default.
-    # Mirror the global-provider switch: prefer the PS-5.1-compatible script name,
-    # fall back to the alternate name if the first doesn't exist on disk.
-    switch ($_LlmEngine) {
-        { $_ -in "windows-sapi", "sapi" } {
-            $ProviderScript = "$HooksDir\play-tts-sapi.ps1"
-            if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
-        }
-        { $_ -in "windows-piper", "piper" } {
-            $ProviderScript = "$HooksDir\play-tts-piper.ps1"
-            if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
-        }
-        "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
-        "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
-        default {
-            Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' — keeping default provider" -ForegroundColor DarkGray
+if ($PlanOk -and $PlanEngine) {
+    # Resolver plan is authoritative for the LOCAL engine (AVI-S8.5 Stage 2):
+    # this cures the kokoro/piper voice->engine coupling (R1) and normalizes
+    # engine aliases like windows-sapi->sapi (F5), replacing the legacy heuristic
+    # below. An engine with no local Windows script (elevenlabs/macos) leaves the
+    # current provider in place.
+    $_PlanScript = Resolve-ProviderScriptForEngine -Engine $PlanEngine -HooksRoot $HooksDir
+    if ($_PlanScript) { $ProviderScript = $_PlanScript }
+}
+else {
+    # Legacy voice->engine heuristic — ONLY on the fallback path (no resolver
+    # plan). When a plan resolved, the resolver already coupled voice->engine
+    # correctly above, so this is skipped.
+    $_VoiceIsKokoro = $VoiceOverride -match '^[a-z]{2}_[a-z0-9_]+$'
+    if ($_VoiceIsKokoro) {
+        # A Kokoro-format voice forces the Kokoro engine regardless of the per-LLM
+        # ENGINE column or the global tts-provider.txt default.
+        $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
+    }
+    elseif ($_LlmEngine) {
+        # Accept both canonical Windows names and the cross-platform aliases the TUI
+        # writes (e.g. "piper" saved on a Linux/WSL install that is later read on
+        # Windows, or "sapi" as a short form).  Unknown values keep the global default.
+        # Mirror the global-provider switch: prefer the PS-5.1-compatible script name,
+        # fall back to the alternate name if the first doesn't exist on disk.
+        switch ($_LlmEngine) {
+            { $_ -in "windows-sapi", "sapi" } {
+                $ProviderScript = "$HooksDir\play-tts-sapi.ps1"
+                if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
+            }
+            { $_ -in "windows-piper", "piper" } {
+                $ProviderScript = "$HooksDir\play-tts-piper.ps1"
+                if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
+            }
+            "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
+            "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
+            default {
+                Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' — keeping default provider" -ForegroundColor DarkGray
+            }
         }
     }
 }
@@ -437,7 +556,20 @@ elseif ($_LlmEngine) {
 
 # --- Diagnostic output -------------------------------------------------------
 # Set AGENTVIBES_VERBOSE=1 in the shell environment to print routing state.
+# The bare `provider=`/`voice=`/`plan=` lines mirror play-tts.sh's verbose
+# DECISION echo so the resolved engine/voice can be characterization-tested
+# without producing real audio (see test/windows/play-tts-resolver.Tests.ps1).
 if ($env:AGENTVIBES_VERBOSE -eq "1") {
+    $_ProviderName = switch -Wildcard ($ProviderScript) {
+        "*play-tts-kokoro.ps1"  { "kokoro" }
+        "*soprano*"             { "soprano" }
+        "*piper*"               { "piper" }
+        "*sapi*"                { "sapi" }
+        default                 { Split-Path -Leaf $ProviderScript }
+    }
+    Write-Output "provider=$_ProviderName"
+    Write-Output "voice=$VoiceOverride"
+    Write-Output ("plan=" + $(if ($PlanOk) { "ok" } else { "fallback" }))
     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
 }
@@ -574,8 +706,9 @@ if (($BgEnabled -or $HasReverb) -and $HasFfmpeg) {
                 $BgTrackPath = Join-Path $TracksDir "agent_vibes_bachata_v1_loop.mp3"
             }
 
-            # Get volume (default 0.25) — per-message override takes precedence
-            $BgVolume = "0.25"
+            # Get volume (default 0.20) — per-message override takes precedence
+            # TODO(AVI-S8.6): generate this constant from the shared JSON source of truth.
+            $BgVolume = "0.20"
             $VolumeFile = "$ConfigDir\background-music-volume.txt"
             if (Test-Path $VolumeFile) {
                 $vol = (Get-Content $VolumeFile -Raw).Trim()

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

@@ -31,10 +31,65 @@ try {
             try { Rename-Item $f.FullName $procFile -ErrorAction Stop } catch { continue }
             try {
                 $req = Get-Content $procFile -Raw | ConvertFrom-Json
+
+                # Music preview: play/stop a standalone background-music track
+                # ASYNCHRONOUSLY (Start-Process) so it never blocks the TTS queue,
+                # tracking the ffplay PID so a new request (or an explicit stop)
+                # replaces the previous track instead of stacking playback.
+                #   kind=music       → stop any current preview, then play the track
+                #   kind=music-stop  → stop any current preview (no new playback)
+                if ($req.kind -eq 'music' -or $req.kind -eq 'music-stop') {
+                    $pidFile = Join-Path $env:USERPROFILE '.agentvibes\music-preview.pid'
+                    # Stop the currently-playing preview, if any. Verify the PID is
+                    # actually ffplay so a recycled PID can't kill an unrelated proc.
+                    if (Test-Path $pidFile) {
+                        $oldPid = (Get-Content $pidFile -Raw -ErrorAction SilentlyContinue).Trim()
+                        if ($oldPid -match '^\d+$') {
+                            $op = Get-Process -Id ([int]$oldPid) -ErrorAction SilentlyContinue
+                            if ($op -and $op.ProcessName -eq 'ffplay') { Stop-Process -Id ([int]$oldPid) -Force -ErrorAction SilentlyContinue }
+                        }
+                        Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+                    }
+                    if ($req.kind -eq 'music') {
+                        $trackName = [string]$req.music
+                        if ($trackName -match '^[A-Za-z0-9._][A-Za-z0-9._\-]*\.mp3$') {
+                            $tracksDir = Join-Path $env:USERPROFILE '.claude\audio\tracks'
+                            $full     = [System.IO.Path]::GetFullPath((Join-Path $tracksDir $trackName))
+                            $baseFull = [System.IO.Path]::GetFullPath($tracksDir)
+                            if (-not $baseFull.EndsWith([IO.Path]::DirectorySeparatorChar)) { $baseFull += [IO.Path]::DirectorySeparatorChar }
+                            if ($full.StartsWith($baseFull, [StringComparison]::OrdinalIgnoreCase) -and (Test-Path $full)) {
+                                $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
+                                if ($ffplay) {
+                                    Write-WatcherLog "INFO" "music-preview id=$($req.id) track=$trackName"
+                                    $mp = Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet','-volume','80',$full) -WindowStyle Hidden -PassThru
+                                    if ($mp) { Set-Content -Path $pidFile -Value $mp.Id -NoNewline -ErrorAction SilentlyContinue }
+                                } else {
+                                    Write-WatcherLog "WARN" "ffplay not found - cannot preview music id=$($req.id)"
+                                }
+                            } else {
+                                Write-WatcherLog "WARN" "music track not found id=$($req.id) track=$trackName"
+                            }
+                        } else {
+                            Write-WatcherLog "WARN" "invalid music track name id=$($req.id)"
+                        }
+                    } else {
+                        Write-WatcherLog "INFO" "music-stop id=$($req.id)"
+                    }
+                    Remove-Item $procFile -Force -ErrorAction SilentlyContinue
+                    continue
+                }
+
                 # Validate voice before passing to command line
                 $safeVoice = if ($req.voice -and $req.voice -match '^[a-zA-Z0-9_\-\. :]+$') { $req.voice } else { "" }
                 $env:CLAUDE_PROJECT_DIR = $env:USERPROFILE
                 $env:AGENTVIBES_NO_PRETEXT = "1"
+                # Carry the sender's project (folder name/path) through to the
+                # TalkingHead forward so the avatar badge/tab shows the real remote
+                # origin instead of this machine's own profile dir. (Grafted from master WIP.)
+                if ($req.project) { $env:AGENTVIBES_PROJECT = $req.project }
+                else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_PROJECT", $null, "Process") }
+                if ($req.projectPath) { $env:AGENTVIBES_PROJECT_PATH = $req.projectPath }
+                else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_PROJECT_PATH", $null, "Process") }
                 # Use SetEnvironmentVariable to truly unset (assignment to $null leaves empty string)
                 if ($req.music)   { $env:AGENTVIBES_OVERRIDE_MUSIC   = $req.music }
                 else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_OVERRIDE_MUSIC",   $null, "Process") }

package/.claude/hooks-windows/voice-manager-windows.ps1

@@ -6,7 +6,7 @@
 
 param(
     [Parameter(Position = 0)]
-    [ValidateSet('list', 'switch', 'get')]
+    [ValidateSet('list', 'switch', 'get', 'replay')]
     [string]$Command = 'list',
 
     [Parameter(Position = 1)]
@@ -155,6 +155,102 @@ function Show-CurrentVoice {
     }
 }
 
+# Play an audio file without blocking the caller (mirrors voice-manager.sh's
+# `afplay "$AUDIO_FILE" &` / `paplay ... &` background playback). Prefers
+# ffplay (handles wav/mp3/aiff); falls back to System.Media.SoundPlayer
+# (.Play(), which is inherently async — wav only).
+function Start-ReplayPlayback {
+    param([string]$FilePath)
+
+    # Stay silent while the automated test suite is running (same convention
+    # as play-tts.ps1's Invoke-AudioPlay).
+    if (Test-Path (Join-Path $env:USERPROFILE ".agentvibes-tests-running")) { return }
+
+    $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
+    if ($ffplayCmd) {
+        Start-Process -FilePath $ffplayCmd.Source `
+            -ArgumentList @("-autoexit", "-nodisp", "-loglevel", "quiet", $FilePath) `
+            -WindowStyle Hidden | Out-Null
+        return
+    }
+
+    try {
+        $player = New-Object System.Media.SoundPlayer $FilePath
+        $player.Play()
+    }
+    catch {
+        Write-Host "[WARN] Could not start playback: $_" -ForegroundColor Yellow
+    }
+}
+
+# Replay the Nth most recent TTS audio file (mirrors voice-manager.sh's
+# `replay` case: resolve the audio dir, validate N (1-10), pick the file by
+# most-recent-mtime, and play it in the background).
+function Replay-Audio {
+    param([string]$NArg)
+
+    $AudioDir = $null
+    if ($env:CLAUDE_PROJECT_DIR -and (Test-Path (Join-Path $env:CLAUDE_PROJECT_DIR ".claude"))) {
+        $AudioDir = Join-Path $env:CLAUDE_PROJECT_DIR ".claude\audio"
+    }
+    else {
+        # Walk up from cwd looking for a .claude directory (same fallback as voice-manager.sh).
+        # Use a plain string path throughout: Get-Location returns a PathInfo (.Path),
+        # but Get-Item returns a DirectoryInfo (no .Path) — mixing them made the second
+        # iteration do Join-Path $null and throw a terminating error.
+        $dirPath = (Get-Location).Path
+        while ($dirPath) {
+            $candidate = Join-Path $dirPath ".claude"
+            if (Test-Path $candidate) {
+                $AudioDir = Join-Path $candidate "audio"
+                break
+            }
+            $parent = Split-Path $dirPath -Parent
+            if (-not $parent -or $parent -eq $dirPath) { break }
+            $dirPath = $parent
+        }
+        if (-not $AudioDir) {
+            $AudioDir = Join-Path $ClaudeDir "audio"
+        }
+    }
+
+    $N = 1
+    if ($NArg) {
+        if ($NArg -notmatch '^\d+$') {
+            Write-Host "[ERROR] Invalid argument. Please use a number (1-10)" -ForegroundColor Red
+            exit 1
+        }
+        $N = [int]$NArg
+    }
+    if ($N -lt 1 -or $N -gt 10) {
+        Write-Host "[ERROR] Number out of range. Please choose 1-10" -ForegroundColor Red
+        exit 1
+    }
+
+    if (-not (Test-Path $AudioDir)) {
+        Write-Host "[ERROR] No audio history found" -ForegroundColor Red
+        Write-Host "Audio files are stored in: $AudioDir"
+        exit 1
+    }
+
+    $files = @(Get-ChildItem -Path $AudioDir -File -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -match '^tts-.*\.(wav|mp3|aiff)$' } |
+        Sort-Object LastWriteTime -Descending)
+
+    if ($files.Count -lt $N) {
+        Write-Host "[ERROR] Audio #$N not found in history" -ForegroundColor Red
+        Write-Host "Total audio files available: $($files.Count)"
+        exit 1
+    }
+
+    $target = $files[$N - 1]
+    Write-Host "[REPLAY] Replaying audio #${N}:" -ForegroundColor Cyan
+    Write-Host "   File: $($target.Name)"
+    Write-Host "   Path: $($target.FullName)"
+
+    Start-ReplayPlayback $target.FullName
+}
+
 # Main command routing
 switch ($Command) {
     'list' {
@@ -173,4 +269,8 @@ switch ($Command) {
     'get' {
         Show-CurrentVoice
     }
+
+    'replay' {
+        Replay-Audio $VoiceName
+    }
 }

package/README.md

@@ -58,14 +58,19 @@ New here? The [**Quick Start guide**](docs/quick-start.md) walks you through you
 
 ---
 
-## 🆕 Neural voices (v5.11.0)
+## 🆕 A stronger core (v5.12.0)
 
-Your agent team can now sound genuinely human — each agent with its own distinct voice.
+During a week of early access to Anthropic's new **Fable** model, we rebuilt the heart of AgentVibes into **one shared core**. The voice / engine / routing / volume / mute logic that used to be copied across four scripts (and drift apart) now lives in a single place — simpler, more consistent, and steadier.
 
-- **🧠 Kokoro** — local neural TTS that runs on your **CPU, no GPU required**, with **Chinese, Japanese, and Korean** voices built in.
-- **☁️ ElevenLabs** — premium cloud neural voices when you want the absolute best.
+- **🔊 Previews play in the right place** — with SSH remote configured, voice and **music previews** play on your receiver; otherwise they play locally.
+- **🧠 One shared core** — Kokoro-on-Linux silence and per-voice drift fixed at the source, with a safe fallback if needed.
+- **🧹 Removed the redundant Voices tab** — pick a voice for any provider in Setup.
 
-Plus combinable audio effects landed too: stack **reverb**, **echo**, and **chorus** on any voice.
+### v5.11.0 — Neural voices
+
+- **🧠 Kokoro** — local neural TTS on your **CPU, no GPU required** (Chinese, Japanese, Korean built in).
+- **☁️ ElevenLabs** — premium cloud neural voices.
+- Combinable audio effects: stack **reverb**, **echo**, and **chorus** on any voice.
 
 <div align="center">
 
@@ -219,7 +224,7 @@ Running a full BMAD agent team? **Every agent gets its own distinct voice**, aut
 
 ## About
 
-**AgentVibes** · v5.11.2 · Licensed under [Apache-2.0](LICENSE)
+**AgentVibes** · v5.12.0 · Licensed under [Apache-2.0](LICENSE)
 
 Built by **Paul Preibisch** — [@997Fire on X](https://x.com/997Fire) · [agentvibes.org](https://agentvibes.org) · [github.com/paulpreibisch/AgentVibes](https://github.com/paulpreibisch/AgentVibes)
 

package/RELEASE_NOTES.md

@@ -1,5 +1,72 @@
 # AgentVibes Release Notes
 
+## 🎉 v5.12.0 — The Fable Week Overhaul (Stable)
+
+**Released:** 2026-07-05 · now on `latest` — `npm install agentvibes`
+
+This turns the "Fable Week" alpha into a stable release. During a week of early access to Anthropic's new **Fable** model, we pointed it at the whole AgentVibes codebase and rebuilt the core properly.
+
+### A stronger, shared core
+
+Every time AgentVibes speaks it makes a lot of decisions — which voice, which engine, whether to play here or send the audio to another machine, background music, volume, mute. That logic had been copied into several separate scripts (Mac/Linux, Windows, remote, and the voice server), and the copies slowly **drifted apart** — a fix in one was missed in the others, which is why certain glitches kept coming back.
+
+We replaced all of it with **one shared core** that every part of AgentVibes now follows — one place to fix, one place to trust. What you'll notice:
+
+- **Kokoro voices that were silent on Linux now work everywhere.**
+- **Your voice choices stick** — settings no longer get quietly overridden.
+- **Volume, mute, and remote playback behave the same** across Mac, Linux, and Windows.
+- **Safe by default** — if the new core isn't available on your machine, AgentVibes falls back to the old behaviour, so it never just stops talking.
+
+### Previews now play in the right place
+
+Previewing a voice or track used to play on whatever machine you were sitting at — which was silent if you'd set AgentVibes up to send its audio elsewhere. Now:
+
+- **If you have SSH remote configured, previews play on your receiver; otherwise they play locally, like before.**
+- This covers **voice previews** (Piper and Kokoro) from the Setup, Agent, and Settings screens, and **music/track previews** — press Space to play, Space again to stop.
+
+### A simpler voice menu
+
+- We **removed the redundant Voices tab.** It only ever listed Piper voices and confused people, since choosing a voice for any provider already lives in **Setup**.
+
+### Groundwork for what's next
+
+- The receiver now also receives the **full path of the project folder** a message came from (a new `projectPath` field, alongside the project name it already got) — laying the groundwork for upcoming enhancements.
+
+### Reviewed before shipping
+
+We ran three independent reviews over the changes — security, correctness, and regressions — and fixed every real issue before release.
+
+---
+
+## 🧪 v5.12.0-alpha.0 — The "Fable Week" Overhaul (ALPHA / testing)
+
+**Published:** 2026-07-04 · dist-tag **`alpha`** (not `latest`). Try it with `npm install agentvibes@alpha`.
+
+### The story behind this release
+
+For one week, Anthropic gave us early access to their brand-new **Fable** model. Instead of keeping that to ourselves, we decided to **spend our tokens on the community** — we pointed Fable at the entire AgentVibes codebase and asked it to find everything that was fragile, duplicated, or quietly broken, and to help us rebuild it properly. This alpha is the result: a real overhaul, paid for with that week of access, so **everyone who uses AgentVibes benefits**.
+
+### What was wrong (in plain terms)
+
+AgentVibes has to make a lot of decisions every time it speaks — which voice, which engine, play here or send to another machine, background music on or off, how loud, muted or not. Over time, that decision-making logic had been **copied into four different places**, written in four different languages (the Mac/Linux script, the Windows script, the remote-audio script, and the voice-control server). Those copies slowly **drifted apart** — a fix made in one was missed in the others. That's why the same kinds of glitches kept coming back: a voice that played silence on one system but worked on another, volume that ignored your setting, mute that behaved differently everywhere.
+
+### What we did
+
+We built **one "brain"** that makes all those decisions in a single place, and everything else simply does what the brain says. One place to fix, one place to trust — which retires that whole family of recurring bugs. Concretely in this alpha:
+
+- **Kokoro voices that played silence on Linux now work** on every system.
+- **Your per-voice assignments stick** — the assistant repeating back its own settings no longer overrides them.
+- **Team/party voices are back** — a hidden crash that made every agent speak with the same voice is fixed; each agent has its own voice again.
+- **No more grabbing the wrong audio file** — a long-standing shortcut that could play another agent's clip is gone for good.
+- **Consistent volume, mute, and remote playback** across Mac, Linux, and Windows.
+- **Safety first:** if anything about the new brain isn't available on your machine, AgentVibes automatically falls back to the old behaviour — so your voice **never just stops working**.
+
+Before shipping, we had Fable act as a tough reviewer of our own work — it caught **three real bugs and a packaging mistake** we'd have otherwise released, and we fixed them first.
+
+**This is an alpha for testing.** `latest` is unchanged; please try it and tell us what you find. Thank you, Anthropic, for the week with Fable — and thanks to this community for making it worth spending on. 🙏
+
+---
+
 ## 🐛 v5.11.2 — Kokoro Installer Fix (PEP 668)
 
 **Released:** 2026-06-27

package/bin/mcp-server.sh

@@ -72,7 +72,7 @@ if ! python3 -c "import mcp" 2>/dev/null; then
     print_section "📦 Installing Python MCP Package"
     echo "Installing 'mcp' package to enable Claude Desktop integration..." >&2
 
-    if python3 -m pip install --user mcp --quiet 2>&1; then
+    if python3 -m pip install --user mcp --quiet >&2; then
         echo "✅ Python MCP package installed successfully!" >&2
     else
         echo "❌ Failed to auto-install MCP package" >&2
@@ -86,9 +86,10 @@ else
     echo "✅ Python MCP package already installed" >&2
 fi
 
-# Check provider (Piper vs ElevenLabs)
+# Check provider — ElevenLabs was removed from the product; Piper (free,
+# offline) is the only provider this wrapper does auto-setup for.
 PROVIDER_FILE="$PACKAGE_ROOT/.claude/tts-provider.txt"
-PROVIDER="elevenlabs"  # Default
+PROVIDER="piper"  # Default
 
 if [ -f "$PROVIDER_FILE" ]; then
     PROVIDER=$(cat "$PROVIDER_FILE" | tr -d '[:space:]')
@@ -104,7 +105,7 @@ if [ "$PROVIDER" = "piper" ]; then
             print_section "📦 Installing pipx"
             echo "pipx is needed to install Piper TTS..." >&2
 
-            if python3 -m pip install --user pipx --quiet 2>&1; then
+            if python3 -m pip install --user pipx --quiet >&2; then
                 # Add pipx to PATH for this session
                 export PATH="$HOME/.local/bin:$PATH"
 
@@ -137,7 +138,7 @@ if [ "$PROVIDER" = "piper" ]; then
             print_section "📦 Installing Piper TTS"
             echo "Installing Piper TTS (free, offline voice synthesis)..." >&2
 
-            if pipx install piper-tts --quiet 2>&1; then
+            if pipx install piper-tts --quiet >&2; then
                 echo "✅ Piper TTS installed successfully!" >&2
 
                 # Add pipx bin to PATH
@@ -181,20 +182,6 @@ if [ "$PROVIDER" = "piper" ]; then
             fi
         fi
     fi
-elif [ "$PROVIDER" = "elevenlabs" ]; then
-    # Check for ElevenLabs API key
-    if [ -z "$ELEVENLABS_API_KEY" ]; then
-        echo "⚠️  ElevenLabs selected but ELEVENLABS_API_KEY not set" >&2
-        echo "" >&2
-        echo "📖 Set your API key:" >&2
-        echo "   export ELEVENLABS_API_KEY='your-key-here'" >&2
-        echo "" >&2
-        echo "💡 Or switch to Piper TTS (free):" >&2
-        echo "   echo 'piper' > $PACKAGE_ROOT/.claude/tts-provider.txt" >&2
-        echo "" >&2
-    else
-        echo "✅ ElevenLabs API key configured" >&2
-    fi
 fi
 
 # All checks passed, run the MCP server