agentvibes 5.12.0 → 5.13.0

package/.claude/hooks/voice-manager.sh

@@ -43,6 +43,18 @@ to_lower() {
   echo "$1" | tr '[:upper:]' '[:lower:]'
 }
 
+# Source the generated Provider Catalog (bash-3.2-safe SSOT accessors) when present.
+# FAIL-SAFE: consumers probe `type catalog_* >/dev/null 2>&1` and fall back to the
+# legacy regex/hardcoded behavior when the artifact is missing (installed-tree skew)
+# — mirrors play-tts.sh's PLAN_OK legacy fallback. Switch/list never break on a
+# missing catalog. Double-sourcing is guarded inside provider-catalog.sh.
+_load_provider_catalog() {
+  if [[ -f "$SCRIPT_DIR/provider-catalog.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$SCRIPT_DIR/provider-catalog.sh" 2>/dev/null || true
+  fi
+}
+
 # Determine target .claude directory based on context
 # Priority:
 # 1. CLAUDE_PROJECT_DIR env var (set by MCP for project-specific settings)
@@ -82,13 +94,26 @@ get_default_voice() {
 
   case "$active_provider" in
     piper)
-      echo "en_US-lessac-medium"  # Piper default
+      # Piper default sourced from the generated Provider Catalog (SSOT, AVI-S9.4).
+      # FAIL-SAFE: legacy literal if the catalog artifact is missing (installed-tree skew).
+      _load_provider_catalog
+      if type catalog_default_voice >/dev/null 2>&1; then
+        catalog_default_voice piper
+      else
+        echo "en_US-lessac-medium"  # Piper default (legacy fallback)
+      fi
       ;;
     macos)
       echo "Samantha"  # macOS default
       ;;
     *)
-      echo "en_US-lessac-medium"  # Default to Piper
+      # Default to Piper — same catalog-sourced value, same fail-safe.
+      _load_provider_catalog
+      if type catalog_default_voice >/dev/null 2>&1; then
+        catalog_default_voice piper
+      else
+        echo "en_US-lessac-medium"  # Default to Piper (legacy fallback)
+      fi
       ;;
   esac
 }
@@ -103,7 +128,7 @@ case "$1" in
 
     ACTIVE_PROVIDER="piper"  # default
     if [ -f "$PROVIDER_FILE" ]; then
-      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+      ACTIVE_PROVIDER=$(tr -d '[:space:]' < "$PROVIDER_FILE")
     fi
 
     CURRENT_VOICE=$(cat "$VOICE_FILE" 2>/dev/null || get_default_voice)
@@ -170,12 +195,76 @@ case "$1" in
         fi
         echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
       fi
+    elif [[ "$ACTIVE_PROVIDER" == "kokoro" ]]; then
+      if [[ -f "$FORMATTER" ]] && command -v node &> /dev/null; then
+        node "$FORMATTER" "kokoro" "$CURRENT_VOICE"
+      else
+        echo "🎤 Available Kokoro TTS Voices:"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        _load_provider_catalog
+        if type catalog_list_voices >/dev/null 2>&1; then
+          # All ~54 ids from the SSOT, one per line (catalog order = grouped by lang prefix).
+          catalog_list_voices kokoro | sed 's/^/  /'
+        else
+          # FAIL-SAFE legacy path (catalog artifact missing) — degraded, never dead.
+          echo "  af_heart af_bella af_nicole af_sarah af_sky   (American, female)"
+          echo "  am_adam am_michael am_onyx am_puck            (American, male)"
+          echo "  bf_emma bf_lily  bm_george bm_daniel          (British)"
+          echo "  jf_alpha (Japanese) zf_xiaoxiao (Mandarin) ef_dora (Spanish)"
+        fi
+        echo "  (current: $CURRENT_VOICE)"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      fi
+    elif [[ "$ACTIVE_PROVIDER" == "elevenlabs" ]]; then
+      if [[ -f "$FORMATTER" ]] && command -v node &> /dev/null; then
+        node "$FORMATTER" "elevenlabs" "$CURRENT_VOICE"
+      else
+        echo "🎤 Available ElevenLabs Voices:"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        if [[ -f "$SCRIPT_DIR/elevenlabs-voices.sh" ]]; then
+          # shellcheck source=/dev/null
+          source "$SCRIPT_DIR/elevenlabs-voices.sh"
+          elevenlabs_voice_names | sort | sed 's/^/  /'
+        fi
+        echo "  (current: $CURRENT_VOICE)"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      fi
+    elif [[ "$ACTIVE_PROVIDER" == "soprano" ]]; then
+      # Soprano is a single-voice provider (voiceModel: single) — list its one
+      # canonical voice from the generated Provider Catalog (SSOT, AVI-S9.4).
+      if [[ -f "$FORMATTER" ]] && command -v node &> /dev/null; then
+        node "$FORMATTER" "soprano" "$CURRENT_VOICE"
+      else
+        echo "🎤 Available Soprano TTS Voices:"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        _load_provider_catalog
+        if type catalog_list_voices >/dev/null 2>&1; then
+          catalog_list_voices soprano | sed 's/^/  /'
+        else
+          # FAIL-SAFE legacy path (catalog artifact missing): single canonical voice.
+          echo "  soprano-default"
+        fi
+        echo "  (current: $CURRENT_VOICE)"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      fi
     else
       echo "❌ Unknown provider: $ACTIVE_PROVIDER"
       echo ""
       echo "Available providers:"
-      echo "  - piper (Free, Offline)"
-      echo "  - macos (Built-in, macOS only)"
+      # Derived from the generated Provider Catalog (SSOT, AVI-S9.4) so a new
+      # provider never silently goes missing from this help text again.
+      _load_provider_catalog
+      if type catalog_providers_for_platform >/dev/null 2>&1; then
+        while IFS= read -r _pid; do
+          echo "  - $_pid ($(catalog_display_name "$_pid"))"
+        done < <(catalog_providers_for_platform unix)
+      else
+        # FAIL-SAFE legacy path (catalog artifact missing).
+        echo "  - piper (Free, Offline)"
+        echo "  - macos (Built-in, macOS only)"
+        echo "  - kokoro (Neural, local)"
+        echo "  - elevenlabs (Cloud, API key)"
+      fi
       echo ""
       echo "Switch provider with: /agent-vibes:provider switch piper"
     fi
@@ -221,7 +310,7 @@ case "$1" in
 
     ACTIVE_PROVIDER="piper"  # default
     if [[ -n "$PROVIDER_FILE" ]]; then
-      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+      ACTIVE_PROVIDER=$(tr -d '[:space:]' < "$PROVIDER_FILE")
     fi
 
     # Voice lookup strategy depends on active provider
@@ -363,12 +452,123 @@ case "$1" in
         echo "Download extra voices with: /agent-vibes:provider download"
         exit 1
       fi
+    elif [[ "$ACTIVE_PROVIDER" == "kokoro" ]]; then
+      # Kokoro switch-time validation via the generated Provider Catalog (SSOT):
+      # MEMBERSHIP + canonical case-fold (AF_HEART → af_heart), so a typo like
+      # `af_hart` is rejected HERE and never reaches tts-voice.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: if the catalog artifact is missing (installed-tree skew) we fall
+      # back to the legacy shape-only regex — degraded, never dead.
+      _load_provider_catalog
+      KOKORO_VOICE_LC="$(to_lower "$VOICE_NAME")"
+      if type catalog_validate_voice >/dev/null 2>&1; then
+        _KOKORO_CANON="$(catalog_validate_voice kokoro "$VOICE_NAME" 2>/dev/null || true)"
+        if [[ -n "$_KOKORO_CANON" ]]; then
+          FOUND="$_KOKORO_CANON"
+        elif [[ "${AGENTVIBES_ALLOW_UNLISTED_VOICE:-}" == "1" ]] && [[ "$KOKORO_VOICE_LC" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
+          echo "⚠️  '$VOICE_NAME' is not in the shipped Kokoro catalog; allowing it (AGENTVIBES_ALLOW_UNLISTED_VOICE=1)." >&2
+          FOUND="$KOKORO_VOICE_LC"
+        else
+          echo "❌ Kokoro voice not found: $VOICE_NAME"
+          echo ""
+          echo "That is not a known Kokoro voice. Examples:"
+          echo "  - af_heart, af_bella, af_nicole   (American English, female)"
+          echo "  - am_adam, am_michael             (American English, male)"
+          echo "  - bf_emma, bf_lily                (British English, female)"
+          echo "  - bm_george, bm_daniel            (British English, male)"
+          echo "  - jf_alpha (Japanese), zf_xiaoxiao (Mandarin), ef_dora (Spanish)"
+          echo ""
+          echo "Set AGENTVIBES_ALLOW_UNLISTED_VOICE=1 to allow a newer-model voice."
+          echo "List all Kokoro voices with: /agent-vibes:list"
+          exit 1
+        fi
+      else
+        # FAIL-SAFE legacy path (catalog artifact missing): shape-only regex.
+        if [[ "$KOKORO_VOICE_LC" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
+          FOUND="$KOKORO_VOICE_LC"
+        else
+          echo "❌ Kokoro voice not found: $VOICE_NAME"
+          echo ""
+          echo "Kokoro voice ids look like <lang><sex>_name. Examples:"
+          echo "  - af_heart, af_bella, af_nicole   (American English, female)"
+          echo "  - am_adam, am_michael             (American English, male)"
+          echo "  - bf_emma, bf_lily                (British English, female)"
+          echo "  - bm_george, bm_daniel            (British English, male)"
+          echo "  - jf_alpha (Japanese), zf_xiaoxiao (Mandarin), ef_dora (Spanish)"
+          echo ""
+          echo "List all Kokoro voices with: /agent-vibes:list"
+          exit 1
+        fi
+      fi
+    elif [[ "$ACTIVE_PROVIDER" == "elevenlabs" ]]; then
+      # ElevenLabs voice lookup — resolve a friendly name (case-insensitive) OR a
+      # raw voice_id to the canonical voice_id and save THAT (play-tts-elevenlabs.sh
+      # accepts a raw id directly). Resolution is bash-native via the shared catalog
+      # (elevenlabs-voices.sh) — the SAME source the synth hook uses — so it works
+      # in installed deployments with no Node dependency.
+      EL_RESOLVED=""
+      if [[ -f "$SCRIPT_DIR/elevenlabs-voices.sh" ]]; then
+        # shellcheck source=/dev/null
+        source "$SCRIPT_DIR/elevenlabs-voices.sh"
+        EL_RESOLVED="$(elevenlabs_resolve_voice "$VOICE_NAME" 2>/dev/null || true)"
+      elif [[ "$VOICE_NAME" =~ ^[A-Za-z0-9]{20}$ ]]; then
+        # Catalog missing but the input is already a raw voice_id — accept it.
+        EL_RESOLVED="$VOICE_NAME"
+      fi
+      if [[ -n "$EL_RESOLVED" ]]; then
+        FOUND="$EL_RESOLVED"
+      else
+        echo "❌ ElevenLabs voice not found: $VOICE_NAME"
+        echo ""
+        echo "ElevenLabs voices include: Sarah, Roger, Laura, George, Callum, Alice,"
+        echo "Matilda, Will, Jessica, Eric, Brian, Daniel, Lily, Bill (or a raw voice_id)."
+        echo ""
+        echo "List all ElevenLabs voices with: /agent-vibes:list"
+        exit 1
+      fi
+    elif [[ "$ACTIVE_PROVIDER" == "soprano" ]]; then
+      # Soprano switch-time validation via the generated Provider Catalog (SSOT):
+      # voiceModel `single` — accepts '', 'soprano', 'soprano-default' (case-insensitive)
+      # and canonicalizes to 'soprano-default'; anything else is rejected here so a
+      # typo never reaches tts-voice.txt. FAIL-SAFE: if the catalog artifact is
+      # missing, the same fixed rule is applied hardcoded (soprano has exactly one
+      # voice — this rule never drifts).
+      _load_provider_catalog
+      SOPRANO_CANON=""
+      if type catalog_validate_voice >/dev/null 2>&1; then
+        SOPRANO_CANON="$(catalog_validate_voice soprano "$VOICE_NAME" 2>/dev/null || true)"
+      else
+        case "$(to_lower "$VOICE_NAME")" in
+          ''|soprano|soprano-default) SOPRANO_CANON="soprano-default" ;;
+        esac
+      fi
+      if [[ -n "$SOPRANO_CANON" ]]; then
+        FOUND="$SOPRANO_CANON"
+      else
+        echo "❌ Soprano voice not found: $VOICE_NAME"
+        echo ""
+        echo "Soprano TTS has a single voice: soprano-default"
+        echo "(accepts '', 'soprano', or 'soprano-default')."
+        exit 1
+      fi
     else
       echo "❌ Unknown provider: $ACTIVE_PROVIDER"
       echo ""
       echo "Available providers:"
-      echo "  - piper (Free, Offline)"
-      echo "  - macos (Built-in, macOS only)"
+      # Derived from the generated Provider Catalog (SSOT, AVI-S9.4).
+      _load_provider_catalog
+      if type catalog_providers_for_platform >/dev/null 2>&1; then
+        while IFS= read -r _pid; do
+          echo "  - $_pid ($(catalog_display_name "$_pid"))"
+        done < <(catalog_providers_for_platform unix)
+      else
+        # FAIL-SAFE legacy path (catalog artifact missing).
+        echo "  - piper (Free, Offline)"
+        echo "  - macos (Built-in, macOS only)"
+        echo "  - kokoro (Neural, local)"
+        echo "  - elevenlabs (Cloud, API key)"
+      fi
       echo ""
       echo "Switch provider with: /agent-vibes:provider switch piper"
       exit 1
@@ -412,7 +612,7 @@ case "$1" in
     fi
 
     if [ -f "$PROVIDER_FILE" ]; then
-      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+      ACTIVE_PROVIDER=$(tr -d '[:space:]' < "$PROVIDER_FILE")
       if [[ "$ACTIVE_PROVIDER" == "piper" ]]; then
         echo "Provider: Piper TTS (Free, Offline)"
       elif [[ "$ACTIVE_PROVIDER" == "ssh-remote" ]]; then
@@ -421,6 +621,10 @@ case "$1" in
         echo "Provider: Piper TTS (via AgentVibes Receiver)"
       elif [[ "$ACTIVE_PROVIDER" == "macos" ]]; then
         echo "Provider: macOS Say (Built-in, Free)"
+      elif [[ "$ACTIVE_PROVIDER" == "kokoro" ]]; then
+        echo "Provider: Kokoro TTS (Neural, Local)"
+      elif [[ "$ACTIVE_PROVIDER" == "elevenlabs" ]]; then
+        echo "Provider: ElevenLabs (Cloud, API Key)"
       else
         echo "Provider: $ACTIVE_PROVIDER"
       fi
@@ -466,7 +670,7 @@ case "$1" in
 
     ACTIVE_PROVIDER="piper"  # default
     if [ -f "$PROVIDER_FILE" ]; then
-      ACTIVE_PROVIDER=$(cat "$PROVIDER_FILE")
+      ACTIVE_PROVIDER=$(tr -d '[:space:]' < "$PROVIDER_FILE")
     fi
 
     if [[ "$ACTIVE_PROVIDER" == "piper" || "$ACTIVE_PROVIDER" == "ssh-remote" || "$ACTIVE_PROVIDER" == "agentvibes-receiver" ]]; then
@@ -487,6 +691,34 @@ case "$1" in
       else
         echo "(macOS voices only available on macOS)"
       fi
+    elif [[ "$ACTIVE_PROVIDER" == "kokoro" ]]; then
+      # Kokoro's catalog is fixed; list ALL ids from the generated Provider Catalog (SSOT).
+      _load_provider_catalog
+      if type catalog_list_voices >/dev/null 2>&1; then
+        catalog_list_voices kokoro | sort
+      else
+        # FAIL-SAFE legacy path (catalog artifact missing): representative subset.
+        printf '%s\n' af_heart af_bella af_nicole af_sarah af_sky \
+          am_adam am_michael am_onyx am_puck \
+          bf_emma bf_lily bm_george bm_daniel \
+          jf_alpha zf_xiaoxiao ef_dora | sort
+      fi
+    elif [[ "$ACTIVE_PROVIDER" == "elevenlabs" ]]; then
+      if [[ -f "$SCRIPT_DIR/elevenlabs-voices.sh" ]]; then
+        # shellcheck source=/dev/null
+        source "$SCRIPT_DIR/elevenlabs-voices.sh"
+        elevenlabs_voice_names | sort
+      fi
+    elif [[ "$ACTIVE_PROVIDER" == "soprano" ]]; then
+      # Soprano's catalog is a single fixed voice; list it from the generated
+      # Provider Catalog (SSOT, AVI-S9.4).
+      _load_provider_catalog
+      if type catalog_list_voices >/dev/null 2>&1; then
+        catalog_list_voices soprano
+      else
+        # FAIL-SAFE legacy path (catalog artifact missing).
+        echo "soprano-default"
+      fi
     else
       echo "(Unknown provider: $ACTIVE_PROVIDER)"
     fi

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

@@ -146,7 +146,13 @@ switch ($Command) {
             Write-Output "Usage: language-manager.ps1 check-voice <voice-name>"
             exit 1
         }
-        $multilingual = @("Antoni", "Rachel", "Domi", "Bella", "Charlotte", "Matilda")
+        # AVI-S9.6 AC1: trimmed to names that exist in the 21-voice ElevenLabs
+        # catalog (src/services/provider-catalog.js ELEVENLABS_VOICES) — the
+        # list previously included "Antoni"/"Rachel"/"Domi"/"Charlotte", none of
+        # which exist there (the same class of bug design row 21 found in the
+        # now-deleted learn-manager.sh). Parity-asserted against the catalog by
+        # test/unit/provider-catalog-conformance.test.js.
+        $multilingual = @("Bella", "Matilda")
         if ($Arg1 -in $multilingual) { Write-Output "yes" } else { Write-Output "no" }
     }
 

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

@@ -29,6 +29,13 @@ if ($env:CLAUDE_PROJECT_DIR -and (Test-Path "$env:CLAUDE_PROJECT_DIR\.claude"))
 
 $PersonalityFile = Join-Path $ConfigClaudeDir "tts-personality.txt"
 
+# Load the generated Provider Catalog (SSOT) for the Piper default voice.
+# FAIL-SAFE: consumers probe `Get-Command Get-CatalogDefaultVoice` and fall back
+# to the legacy literal when the artifact is missing (installed-tree skew) —
+# mirrors voice-manager-windows.ps1 / play-tts-kokoro.ps1 (AVI-S9.3/9.4).
+$CatalogPs1 = Join-Path $ScriptDir 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) { . $CatalogPs1 }
+
 function Get-PersonalityData {
     param([string]$Personality, [string]$Field)
     $file = Join-Path $PersonalitiesDir "$Personality.md"
@@ -116,7 +123,15 @@ switch ($Command) {
 
         # Get assigned voice
         $assignedVoice = Get-PersonalityData $personality "piper_voice"
-        if (-not $assignedVoice) { $assignedVoice = "en_US-lessac-medium" }
+        if (-not $assignedVoice) {
+            # Fallback to default Piper voice — sourced from the generated Provider
+            # Catalog SSOT (AVI-S9.4). FAIL-SAFE: legacy literal if artifact missing.
+            $assignedVoice = $null
+            if (Get-Command Get-CatalogDefaultVoice -ErrorAction SilentlyContinue) {
+                $assignedVoice = Get-CatalogDefaultVoice -Provider 'piper'
+            }
+            if (-not $assignedVoice) { $assignedVoice = "en_US-lessac-medium" }
+        }
 
         if ($assignedVoice) {
             Write-Output "Switching to assigned voice: $assignedVoice"

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
+    }
+  }
+}