agentvibes 5.12.0 → 5.13.1

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

@@ -27,6 +27,20 @@ $ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
 $ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
 if (Test-Path $ProjectClaudeDir) { $ClaudeDir = $ProjectClaudeDir } else { $ClaudeDir = "$env:USERPROFILE\.claude" }
 
+# --- Default voice from the generated Provider Catalog (SSOT) -----------------
+# FAIL-SAFE: keep the literal fallback for installed-tree skew (mirrors play-tts.sh
+# PLAN_OK). The synth-time shape check below stays LENIENT (design §3.3) so a voice
+# from a newer kokoro model still degrades audibly instead of bricking.
+$KokoroDefault = "af_heart"
+$CatalogPs1 = Join-Path $ScriptPath 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) {
+    . $CatalogPs1
+    if (Get-Command Get-CatalogDefaultVoice -ErrorAction SilentlyContinue) {
+        $d = Get-CatalogDefaultVoice -Provider 'kokoro'
+        if ($d) { $KokoroDefault = $d }
+    }
+}
+
 $AudioDir  = "$ClaudeDir\audio"
 $ConfigDir = "$ClaudeDir\config"
 if (-not (Test-Path $AudioDir)) { New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null }
@@ -70,13 +84,15 @@ if ($VoiceOverride) {
 }
 # Kokoro voice ids look like af_heart, am_michael, bf_emma. Strip any ::display suffix.
 if ($VoiceName -match '::') { $VoiceName = ($VoiceName -split '::')[0] }
-if (-not $VoiceName) { $VoiceName = "af_heart" }
+if (-not $VoiceName) { $VoiceName = $KokoroDefault }
 
 # Security: validate voice id (lowercase prefix + underscore + name).
-# Rejects path-traversal / injection before it reaches the command line.
+# LENIENT shape check (design §3.3) — rejects path-traversal / injection but lets
+# an unknown-but-shape-valid voice from a newer kokoro model through; falls back
+# to the catalog default only on a shape violation.
 if ($VoiceName -notmatch '^[a-z]{2}_[a-z0-9_]+$') {
-    Write-Host "[WARNING] Invalid Kokoro voice '$VoiceName' - falling back to af_heart" -ForegroundColor Yellow
-    $VoiceName = "af_heart"
+    Write-Host "[WARNING] Invalid Kokoro voice '$VoiceName' - falling back to $KokoroDefault" -ForegroundColor Yellow
+    $VoiceName = $KokoroDefault
 }
 
 # --- Optional speed ----------------------------------------------------------

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

@@ -116,8 +116,9 @@ switch ($ActiveProvider) {
 # by the SSH-receiver watcher via -ProviderOverride).  This lets the Linux-side
 # audio-effects.cfg row for llm:claude-code specify "piper" and have it honoured
 # on Windows without requiring the Windows tts-provider.txt to be reconfigured.
-# Priority: lower than per-LLM $_LlmEngine (audio-effects.cfg row, set later), higher
-# than the global tts-provider.txt default set above.
+# Priority: an explicit -ProviderOverride is AUTHORITATIVE — it wins over both the
+# per-LLM $_LlmEngine column and the global tts-provider.txt default (see the
+# $ProviderOverride guard in the engine-resolution block below).
 if ($ProviderOverride) {
     switch ($ProviderOverride) {
         { $_ -in "windows-piper", "piper" } {
@@ -308,8 +309,30 @@ $PlanVoiceIsOverride = $false
 if ($ProviderOverride) {
     # A fresh -ProviderOverride for THIS request must win over any stale/inherited
     # AGENTVIBES_FORCE_PROVIDER in the environment (a validated allowlist only).
+    #
+    # The allowlist DERIVES from the Provider Catalog (SSOT): the Windows platform
+    # set PLUS the cross-platform forwarding aliases this script normalizes
+    # (piper→windows-piper, sapi→windows-sapi, and macos forwarded verbatim for
+    # SSH-relayed senders). FAIL-SAFE: the literal below is the legacy fallback
+    # used when the generated provider-catalog.ps1 is missing (installed-tree skew).
+    $ProviderOverrideAllowlist = @('piper','soprano','macos','windows-sapi','sapi','kokoro','windows-piper')
+    $__CatalogPs1 = Join-Path $ScriptPath 'provider-catalog.ps1'
+    if (Test-Path $__CatalogPs1) {
+        try {
+            . $__CatalogPs1
+            if (Get-Command Get-CatalogProvidersForPlatform -ErrorAction SilentlyContinue) {
+                $__WinSet = @(Get-CatalogProvidersForPlatform 'windows')
+                if ($__WinSet.Count -gt 0) {
+                    # Windows synth providers + the forwarding aliases play-tts.ps1 normalizes.
+                    $ProviderOverrideAllowlist = @($__WinSet + @('piper','sapi','macos') | Select-Object -Unique)
+                }
+            }
+        } catch {
+            # Keep the legacy fallback allowlist on any catalog load error.
+        }
+    }
     switch ($ProviderOverride) {
-        { $_ -in @('piper','soprano','macos','windows-sapi','sapi','kokoro','elevenlabs','windows-piper') } {
+        { $_ -in $ProviderOverrideAllowlist } {
             $env:AGENTVIBES_FORCE_PROVIDER = $ProviderOverride
         }
     }
@@ -522,6 +545,12 @@ else {
         # ENGINE column or the global tts-provider.txt default.
         $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
     }
+    elseif ($ProviderOverride) {
+        # An explicit -ProviderOverride (forwarded from the SSH payload's "provider"
+        # field, or a preview) is AUTHORITATIVE and was already applied above. Do NOT
+        # let the per-LLM ENGINE column override it, or a receiver whose llm row
+        # defaults to piper silently swallows a forwarded windows-sapi request.
+    }
     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

package/.claude/hooks-windows/provider-catalog.ps1

@@ -0,0 +1,140 @@
+# provider-catalog.ps1 — GENERATED FILE. DO NOT EDIT.
+# DO NOT EDIT — generated from src/services/provider-catalog.js
+# Regenerate with: node scripts/generate-provider-catalog.mjs
+# content-hash: sha256:5e717024f1250a8f54d07291256e532606dba7b4a15ab9589305d1af6bba7f35
+# Dot-source this file to load the catalog accessors; do not execute it.
+
+$script:AgentVibesCatalogVersion = '5e717024f1250a8f'
+
+$script:CatalogDefaults = @{
+  'soprano' = 'soprano-default'
+  'piper' = 'en_US-lessac-medium'
+  'kokoro' = 'af_heart'
+  'elevenlabs' = 'Sarah'
+  'macos' = 'Samantha'
+  'windows-sapi' = ''
+  'windows-piper' = 'en_US-lessac-medium'
+}
+
+$script:CatalogDisplayNames = @{
+  'soprano' = 'Soprano TTS'
+  'piper' = 'Piper TTS'
+  'kokoro' = 'Kokoro TTS'
+  'elevenlabs' = 'ElevenLabs'
+  'macos' = 'macOS Say'
+  'windows-sapi' = 'Windows SAPI'
+  'windows-piper' = 'Piper TTS'
+}
+
+$script:CatalogAlias = @{
+  'macos-say' = 'macos'
+  'say' = 'macos'
+  'sapi' = 'windows-sapi'
+}
+
+$script:CatalogPlatform = @{
+  'unix' = @('soprano','piper','kokoro','elevenlabs')
+  'darwin' = @('soprano','piper','kokoro','elevenlabs','macos')
+  'windows' = @('soprano','kokoro','windows-sapi','windows-piper')
+}
+
+$script:CatalogVoices = @{
+  'soprano' = @('soprano-default')
+  'piper' = @()
+  'kokoro' = @('af_heart','af_alloy','af_aoede','af_bella','af_jessica','af_kore','af_nicole','af_nova','af_river','af_sarah','af_sky','am_adam','am_echo','am_eric','am_fenrir','am_liam','am_michael','am_onyx','am_puck','bf_alice','bf_emma','bf_isabella','bf_lily','bm_daniel','bm_fable','bm_george','bm_lewis','jf_alpha','jf_gongitsune','jf_nezumi','jf_tebukuro','jm_kumo','zf_xiaobei','zf_xiaoni','zf_xiaoxiao','zf_xiaoyi','zm_yunxi','zm_yunxia','zm_yunyang','ef_dora','em_alex','em_santa','ff_siwis','hf_alpha','hm_omega','if_sara','im_nicola','pf_dora','pm_alex','pm_santa','kf_alpha','km_hyunsu')
+  'elevenlabs' = @('Sarah','Roger','Laura','Charlie','George','Callum','River','Harry','Liam','Alice','Matilda','Will','Jessica','Eric','Bella','Chris','Brian','Daniel','Lily','Adam','Bill')
+  'macos' = @()
+  'windows-sapi' = @()
+  'windows-piper' = @()
+}
+
+$script:CatalogElevenLabs = @{
+  'sarah' = 'EXAVITQu4vr4xnSDxMaL'
+  'roger' = 'CwhRBWXzGAHq8TQ4Fs17'
+  'laura' = 'FGY2WhTYpPnrIDTdsKH5'
+  'charlie' = 'IKne3meq5aSn9XLyUdCD'
+  'george' = 'JBFqnCBsd6RMkjVDRZzb'
+  'callum' = 'N2lVS1w4EtoT3dr4eOWO'
+  'river' = 'SAz9YHcvj6GT2YYXdXww'
+  'harry' = 'SOYHLrjzK2X1ezoPC6cr'
+  'liam' = 'TX3LPaxmHKxFdv7VOQHJ'
+  'alice' = 'Xb7hH8MSUJpSbSDYk0k2'
+  'matilda' = 'XrExE9yKIg1WjnnlVkGX'
+  'will' = 'bIHbv24MWmeRgasZH58o'
+  'jessica' = 'cgSgspJ2msm6clMCkdW9'
+  'eric' = 'cjVigY5qzO86Huf0OWal'
+  'bella' = 'hpp4J3VqNfWAUOO0d1Us'
+  'chris' = 'iP95p4xoKVk53GoZ742B'
+  'brian' = 'nPczCjzI2devNBz1zQrb'
+  'daniel' = 'onwK4e9ZLuTAKqWW03F9'
+  'lily' = 'pFZP5JQG7iQjIQuC4Bku'
+  'adam' = 'pNInz6obpgDQGcFmaJgB'
+  'bill' = 'pqHfZKP75CvOlQylNhV4'
+}
+
+function Get-CatalogCanonicalProvider {
+  param([Parameter(Mandatory)][string]$Provider)
+  $key = $Provider.Trim().ToLowerInvariant()
+  if ($script:CatalogDefaults.ContainsKey($key)) { return $key }
+  if ($script:CatalogAlias.ContainsKey($key)) { return $script:CatalogAlias[$key] }
+  return $null
+}
+
+function Get-CatalogDefaultVoice {
+  param([Parameter(Mandatory)][string]$Provider)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return $null }
+  return $script:CatalogDefaults[$p]
+}
+
+function Get-CatalogDisplayName {
+  param([Parameter(Mandatory)][string]$Provider)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return $Provider }
+  return $script:CatalogDisplayNames[$p]
+}
+
+function Get-CatalogProvidersForPlatform {
+  param([Parameter(Mandatory)][string]$Platform)
+  $key = $Platform.Trim().ToLowerInvariant()
+  if ($script:CatalogPlatform.ContainsKey($key)) { return $script:CatalogPlatform[$key] }
+  return @()
+}
+
+function Get-CatalogVoices {
+  param([Parameter(Mandatory)][string]$Provider)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return @() }
+  return $script:CatalogVoices[$p]
+}
+
+function Test-CatalogVoice {
+  param([Parameter(Mandatory)][string]$Provider, [Parameter(Mandatory)][AllowEmptyString()][string]$Voice)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return $null }
+  $lc = $Voice.Trim().ToLowerInvariant()
+  switch ($p) {
+    'kokoro' {
+      if ($script:CatalogVoices['kokoro'] -contains $lc) { return $lc }
+      return $null
+    }
+    'elevenlabs' {
+      if ($script:CatalogElevenLabs.ContainsKey($lc)) { return $script:CatalogElevenLabs[$lc] }
+      if ($Voice -match '^[A-Za-z0-9]{20}$') { return $Voice }
+      return $null
+    }
+    'soprano' {
+      if ($lc -eq '' -or $lc -eq 'soprano' -or $lc -eq 'soprano-default') { return 'soprano-default' }
+      return $null
+    }
+    { $_ -eq 'piper' -or $_ -eq 'windows-piper' } {
+      if ($Voice -match '^[a-z]{2,3}_[A-Z]{2}-' -or $Voice -like '*::*') { return $Voice }
+      return $null
+    }
+    default {
+      if ($Voice -ne '') { return $Voice }
+      if ($p -eq 'windows-sapi') { return '' }
+      return $null
+    }
+  }
+}

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

@@ -15,7 +15,25 @@ param(
 
 $ClaudeDir = "$env:USERPROFILE\.claude"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
-$ValidProviders = @('windows-piper', 'windows-sapi', 'soprano')
+# $ValidProviders DERIVES from the generated Provider Catalog (SSOT): the Windows
+# platform set (kokoro is cross-platform — play-tts-kokoro.ps1 exists; elevenlabs
+# is NOT playable on Windows and is therefore absent). Dot-source the generated
+# provider-catalog.ps1 and pull `windows`. FAIL-SAFE: the literal below is the
+# legacy fallback used when the catalog artifact is missing (installed-tree skew)
+# — mirrors AVI-S9.3's probe/fallback pattern. See AVI-S8.1 / AVI-S9.5.
+$ValidProviders = @('windows-piper', 'windows-sapi', 'soprano', 'kokoro')
+$__CatalogPs1 = Join-Path $PSScriptRoot 'provider-catalog.ps1'
+if (Test-Path $__CatalogPs1) {
+    try {
+        . $__CatalogPs1
+        if (Get-Command Get-CatalogProvidersForPlatform -ErrorAction SilentlyContinue) {
+            $__WinSet = @(Get-CatalogProvidersForPlatform 'windows')
+            if ($__WinSet.Count -gt 0) { $ValidProviders = $__WinSet }
+        }
+    } catch {
+        # Keep the legacy fallback literal on any catalog load error.
+    }
+}
 
 # Ensure claude directory exists
 if (-not (Test-Path $ClaudeDir)) {
@@ -35,6 +53,14 @@ function Get-ActiveProvider {
 function Get-AvailableProviders {
     $available = @()
 
+    # Fast path: skip the live install probes (soprano HTTP + kokoro python
+    # spawns). Those probes are what make `provider list` occasionally stall for
+    # tens of seconds under load; when the caller only needs the provider NAMES
+    # (e.g. the parallel test harness, or an offline listing) set
+    # AGENTVIBES_PROVIDER_LIST_NO_PROBE=1 to report installed=$false without
+    # touching the network or spawning interpreters. Default behavior unchanged.
+    $noProbe = ($env:AGENTVIBES_PROVIDER_LIST_NO_PROBE -eq '1')
+
     # Always available
     $available += @{
         name = "windows-sapi"
@@ -59,15 +85,18 @@ function Get-AvailableProviders {
         $null = Get-Command soprano -ErrorAction Stop
         $sopranoInstalled = $true
     } catch {
-        # Also check if a Soprano server is running (try both API paths)
-        try {
-            $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/gradio_api/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
-            $sopranoInstalled = $true
-        } catch {
+        # Also check if a Soprano server is running (try both API paths) — unless
+        # the fast path is requested, in which case skip the network probes.
+        if (-not $noProbe) {
             try {
-                $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
+                $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/gradio_api/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
                 $sopranoInstalled = $true
-            } catch {}
+            } catch {
+                try {
+                    $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
+                    $sopranoInstalled = $true
+                } catch {}
+            }
         }
     }
 
@@ -77,6 +106,32 @@ function Get-AvailableProviders {
         installed = $sopranoInstalled
     }
 
+    # Check if Kokoro is installed. Mirror validateKokoroInstallation() in
+    # src/utils/provider-validator.js, but use importlib.util.find_spec so we do
+    # NOT actually import kokoro — importing the 82M-param neural lib takes
+    # several seconds and would make `provider list` hang (AVI-S8.1). find_spec
+    # only confirms the packages are importable, which is all we need here.
+    $kokoroInstalled = $false
+    $kokoroProbe = "import importlib.util as u,sys; sys.exit(0 if all(u.find_spec(m) for m in ('kokoro','soundfile','numpy')) else 1)"
+    foreach ($py in ($(if ($noProbe) { @() } else { @('py', 'python', 'python3') }))) {
+        if (-not (Get-Command $py -ErrorAction SilentlyContinue)) { continue }
+        try {
+            $null = & $py -c $kokoroProbe 2>$null
+            # Only stop once an interpreter actually HAS the packages — mirrors
+            # validateKokoroInstallation(), which tries every interpreter (the
+            # packages may live under python/python3, not the `py` launcher).
+            if ($LASTEXITCODE -eq 0) { $kokoroInstalled = $true; break }
+        } catch {
+            # interpreter present but failed to run the probe — try next
+        }
+    }
+
+    $available += @{
+        name = "kokoro"
+        description = "Kokoro TTS (Neural, pip install kokoro-onnx soundfile numpy)"
+        installed = $kokoroInstalled
+    }
+
     return $available
 }
 

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

@@ -52,7 +52,7 @@ try {
                     }
                     if ($req.kind -eq 'music') {
                         $trackName = [string]$req.music
-                        if ($trackName -match '^[A-Za-z0-9._][A-Za-z0-9._\-]*\.mp3$') {
+                        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)
@@ -61,6 +61,17 @@ try {
                                 $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
                                 if ($ffplay) {
                                     Write-WatcherLog "INFO" "music-preview id=$($req.id) track=$trackName"
+                                    # Readiness bling — a short cue played in THIS (audio-capable) watcher
+                                    # session BEFORE the track so a listener knows music is incoming. Launched
+                                    # async (NOT -Wait — the wav's shimmer tail is long); a fixed 0.3s gap then
+                                    # lets the music follow tightly. Best-effort: a missing wav / player error
+                                    # never blocks the track.
+                                    $blingWav = Join-Path $env:USERPROFILE '.claude\audio\ui\bling-success.wav'
+                                    if (-not (Test-Path $blingWav)) { $blingWav = Join-Path $env:USERPROFILE '.agentvibes\bling-success.wav' }
+                                    if (Test-Path $blingWav) {
+                                        try { Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet',$blingWav) -WindowStyle Hidden | Out-Null } catch { }
+                                        Start-Sleep -Milliseconds 300
+                                    }
                                     $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 {
@@ -83,9 +94,9 @@ try {
                 $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.)
+                # Carry the sender's project (folder name/path) through so a
+                # downstream receiver shows the real remote origin instead of
+                # this machine's own profile dir.
                 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 }
@@ -99,16 +110,26 @@ try {
                 else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_OVERRIDE_EFFECTS", $null, "Process") }
 
                 if (Test-Path $PlayTts) {
-                    # Play remote arrival prefix sound if configured
-                    $prefixSoundFile = "$env:USERPROFILE\.agentvibes\remote-prefix-sound.txt"
-                    if (Test-Path $prefixSoundFile) {
-                        $prefixSound = (Get-Content $prefixSoundFile -Raw).Trim()
-                        if ($prefixSound -and (Test-Path $prefixSound)) {
-                            $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
-                            if ($ffplay) {
-                                & $ffplay.Source -autoexit -nodisp -loglevel quiet $prefixSound 2>$null
+                    # Always play a crisp local "incoming" bling so the user KNOWS audio is
+                    # on the way — even when audio is routed to a downstream receiver
+                    # instead of the local speakers. Standard bling-success.wav, async
+                    # with a 0.3s gap (same as the music-preview path); fall back to the
+                    # user-configured remote-prefix-sound.txt if the bling wav is missing.
+                    $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
+                    if ($ffplay) {
+                        $blingWav = Join-Path $env:USERPROFILE '.claude\audio\ui\bling-success.wav'
+                        if (-not (Test-Path $blingWav)) { $blingWav = Join-Path $env:USERPROFILE '.agentvibes\bling-success.wav' }
+                        if (-not (Test-Path $blingWav)) {
+                            $prefixSoundFile = "$env:USERPROFILE\.agentvibes\remote-prefix-sound.txt"
+                            if (Test-Path $prefixSoundFile) {
+                                $ps = (Get-Content $prefixSoundFile -Raw).Trim()
+                                if ($ps -and (Test-Path $ps)) { $blingWav = $ps }
                             }
                         }
+                        if (Test-Path $blingWav) {
+                            try { Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet',$blingWav) -WindowStyle Hidden | Out-Null } catch { }
+                            Start-Sleep -Milliseconds 300
+                        }
                     }
 
                     $tempText = Join-Path $env:TEMP "agentvibes-tts-$($req.id).txt"

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

@@ -17,6 +17,14 @@ $ClaudeDir = "$env:USERPROFILE\.claude"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
 $VoiceSapiFile = "$ClaudeDir\tts-voice-sapi.txt"
 $VoicePiperFile = "$ClaudeDir\tts-voice-piper.txt"
+$VoiceKokoroFile = "$ClaudeDir\tts-voice-kokoro.txt"
+
+# Load the generated Provider Catalog (SSOT) for kokoro switch-time validation.
+# FAIL-SAFE: consumers probe `Get-Command Test-CatalogVoice` and fall back to the
+# legacy shape regex when the artifact is missing (installed-tree skew) — mirrors
+# play-tts.sh's PLAN_OK legacy fallback. Switch never breaks on a missing catalog.
+$CatalogPs1 = Join-Path $PSScriptRoot 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) { . $CatalogPs1 }
 
 # Get active provider
 $ActiveProvider = "windows-sapi"
@@ -129,6 +137,47 @@ function Switch-Voice {
         Write-Host "[INFO] Soprano uses a single fixed voice (Soprano-1.1-80M)" -ForegroundColor Cyan
         return $true
     }
+    elseif ($ActiveProvider -eq "kokoro") {
+        # Kokoro switch-time validation via the generated Provider Catalog (SSOT):
+        # MEMBERSHIP + canonical case-fold, so a typo like af_hart is rejected HERE
+        # and never reaches tts-voice-kokoro.txt to die silently at the model.
+        # Escape hatch AGENTVIBES_ALLOW_UNLISTED_VOICE=1 bypasses MEMBERSHIP (not
+        # shape) so a voice from a newer kokoro model still switches. FAIL-SAFE:
+        # fall back to the legacy shape regex when the catalog artifact is missing.
+        $kokoroVoice = $NewVoice.ToLower()
+        $allowUnlisted = ($env:AGENTVIBES_ALLOW_UNLISTED_VOICE -eq '1')
+        if (Get-Command Test-CatalogVoice -ErrorAction SilentlyContinue) {
+            $canon = Test-CatalogVoice -Provider 'kokoro' -Voice $NewVoice
+            if ($canon) {
+                Set-Content -Path $VoiceKokoroFile -Value $canon
+                Write-Host "[OK] Voice set to: $canon" -ForegroundColor Green
+                return $true
+            }
+            elseif ($allowUnlisted -and $kokoroVoice -match '^[a-z]{2}_[a-z0-9_]+$') {
+                Write-Host "[WARN] '$NewVoice' is not in the shipped Kokoro catalog; allowing it (AGENTVIBES_ALLOW_UNLISTED_VOICE=1)." -ForegroundColor Yellow
+                Set-Content -Path $VoiceKokoroFile -Value $kokoroVoice
+                Write-Host "[OK] Voice set to: $kokoroVoice" -ForegroundColor Green
+                return $true
+            }
+            else {
+                Write-Host "[ERROR] Kokoro voice not found: $NewVoice" -ForegroundColor Red
+                Write-Host "That is not a known Kokoro voice. Examples: af_heart, am_michael, bf_emma, bm_george, jf_alpha, zf_xiaoxiao, ef_dora." -ForegroundColor Yellow
+                Write-Host "Set AGENTVIBES_ALLOW_UNLISTED_VOICE=1 to allow a newer-model voice." -ForegroundColor Yellow
+                return $false
+            }
+        }
+        else {
+            # FAIL-SAFE legacy path (catalog artifact missing): shape-only regex.
+            if ($kokoroVoice -notmatch '^[a-z]{2}_[a-z0-9_]+$') {
+                Write-Host "[ERROR] Kokoro voice not found: $NewVoice" -ForegroundColor Red
+                Write-Host "Kokoro ids look like <lang><sex>_name, e.g. af_heart, am_michael, bf_emma." -ForegroundColor Yellow
+                return $false
+            }
+            Set-Content -Path $VoiceKokoroFile -Value $kokoroVoice
+            Write-Host "[OK] Voice set to: $kokoroVoice" -ForegroundColor Green
+            return $true
+        }
+    }
 
     if ($ValidVoices -notcontains $NewVoice) {
         Write-Host "[ERROR] Voice not found: $NewVoice" -ForegroundColor Red

package/.mcp.json

@@ -1,12 +1,5 @@
 {
   "mcpServers": {
-    "firecrawl-mcp": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "firecrawl-mcp"
-      ]
-    },
     "agentvibes": {
       "command": "npx",
       "args": [

package/README.md

@@ -58,9 +58,18 @@ New here? The [**Quick Start guide**](docs/quick-start.md) walks you through you
 
 ---
 
-## 🆕 A stronger core (v5.12.0)
+## 🆕 Your voices everywhere (v5.13.0)
 
-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.
+Pick the voices built into **Windows** or **Mac** and hear them wherever you're listening — even when your agents run on another computer. Plus a friendly heads-up chime so you always know sound is coming.
+
+- **🖥️ Your computer's own voices, from anywhere** — choose Windows or Mac voices and hear them on your machine; every voice is shown, with unavailable ones clearly marked.
+- **🗂️ All voices in one list** — Piper, Kokoro, ElevenLabs, Windows, Mac, and Soprano in one place, so what you see is what you can use.
+- **🔔 Heads-up chime** — a short sound plays just before a voice or music preview, so you know audio is on the way.
+- **🆔 Agents that introduce themselves** — optional self-introductions so you know who's talking in a team.
+
+### v5.12.0 — A stronger core
+
+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 now lives in a single place — simpler, more consistent, and steadier.
 
 - **🔊 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.
@@ -224,7 +233,7 @@ Running a full BMAD agent team? **Every agent gets its own distinct voice**, aut
 
 ## About
 
-**AgentVibes** · v5.12.0 · Licensed under [Apache-2.0](LICENSE)
+**AgentVibes** · v5.13.1 · 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,66 @@
 # AgentVibes Release Notes
 
+## 🔧 v5.13.1 — Windows updates that actually update
+
+**Released:** 2026-07-16 · on `latest` — `npm install agentvibes@latest`
+
+### 🪟 Your Windows scripts now really do update
+
+On Windows, the little scripts that make your agents talk live in your `.claude/hooks` folder. Updating said it refreshed them — but on Windows it quietly didn't, so they could sit on the version you first installed for months.
+
+Now they update for real. Run `npx agentvibes update` and you'll pick up every fix you've been missing. Anything you'd customized yourself is still kept safe beside it as a `.user.bak` file, exactly as before.
+
+If you're on macOS or Linux, nothing changes — updates were already working for you.
+
+### 🔒 A security tune-up under the hood
+
+We updated one of the building blocks AgentVibes uses to read settings files. A specially-crafted settings file could have made it grind to a halt. Nothing could ever have been stolen or snooped on — but now it can't get stuck either. Nothing for you to do; it's just in.
+
+---
+
+## 🎉 v5.13.0 — Your Voices Everywhere, With a Heads-Up
+
+**Released:** 2026-07-16 · on `latest` — `npm install agentvibes`
+
+What's new:
+
+### 🖥️ Use your computer's own voices, from anywhere
+
+Run your agents on one machine and listen on another? You can now pick the voices built into **Windows** (David, Zira, Mark) or **Mac**, and hear them right where you're sitting. AgentVibes shows you every voice and clearly marks the ones your listening device can play.
+
+### 🗂️ All your voices in one tidy list
+
+Piper, Kokoro, ElevenLabs, Windows, Mac, Soprano — every voice now comes from a single list, so what you see is always what you can use.
+
+### 🔔 A "heads-up" chime before sound plays
+
+Just before a voice line or music preview starts, you'll hear a short chime — so you always know audio is on the way, even if it takes a moment.
+
+### 🎵 Music previews follow your sound
+
+Preview a track and it plays wherever your audio is set to go — including on another computer.
+
+### 🆔 Agents that introduce themselves
+
+Turn on self-introductions and each agent says who it is when it starts — handy when a whole team is talking.
+
+### 🛟 Your own edits are kept safe when you update
+
+Tinkered with one of the AgentVibes files in your `.claude/hooks` folder? From this version on, updating never throws your work away. If we need to update a file you'd changed, we tuck your copy in beside it with `.user.bak` on the end — like `play-tts.sh.user.bak`.
+
+**That file is made by AgentVibes — nothing is broken and nothing else put it there.** It's simply your old version, saved so you can peek at it or copy your changes back into the new one. Delete it whenever you're done with it.
+
+If you customized files in an older version, it's worth a quick look in `.claude/hooks` for anything you'd want to put back.
+
+### ✨ More voices, smoother ride
+
+- **ElevenLabs** voices fully supported
+- More **Kokoro** voices, working great on Windows
+- Faster, more reliable setup on Windows
+- **3,263 automated tests passing** — steady and dependable
+
+---
+
 ## 🎉 v5.12.0 — The Fable Week Overhaul (Stable)
 
 **Released:** 2026-07-05 · now on `latest` — `npm install agentvibes`