agentvibes 5.12.0-alpha.0 → 5.13.0

package/.claude/hooks/python-resolver.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/python-resolver.sh
+#
+# AgentVibes - Text-to-Speech WITH personality for AI Assistants
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Licensed under the Apache License, Version 2.0
+#
+# @fileoverview Locate a WORKING Python 3 interpreter across platforms.
+# @context Windows git-bash frequently has NO `python3`/`python` on PATH even when
+#          Python is installed (the on-PATH WindowsApps entries are Microsoft Store
+#          execution-alias stubs that do not actually run). The old `command -v
+#          python3` guard therefore made hooks falsely report "not installed".
+# @architecture Sourced (not executed) by hooks; sets and exports $PYTHON_BIN.
+#          $PYTHON_BIN is empty when no usable interpreter exists. Callers should
+#          test `[[ -n "$PYTHON_BIN" ]]` instead of `command -v python3`.
+# @related play-tts.sh, play-tts-kokoro.sh, kokoro-installer.sh, provider-commands.sh
+#
+# Usage:
+#   source "$SCRIPT_DIR/python-resolver.sh"
+#   [[ -n "$PYTHON_BIN" ]] || { echo "No Python 3 found" >&2; exit 1; }
+#   "$PYTHON_BIN" my-script.py ...
+#
+# Override: set AGENTVIBES_PYTHON=/path/to/python to force a specific interpreter.
+
+# Fast path: resolve once per process. Several hooks source this file
+# transitively (e.g. play-tts.sh -> provider-manager.sh), so if PYTHON_BIN is
+# already exported and the file still exists, TRUST it without re-launching
+# Python — a fresh interpreter startup per source adds ~100ms of latency per
+# utterance for nothing. We only pay the exec-validation cost during genuine
+# discovery below, where the Windows Store stub actually needs rejecting.
+if [[ -n "${PYTHON_BIN:-}" && -f "$PYTHON_BIN" ]]; then
+  export PYTHON_BIN
+else
+  _AV_PY_CACHE="${HOME}/.claude/config/python-bin.txt"
+
+  # A candidate is valid only if it runs AND is Python 3. Running it filters out
+  # the Windows Store alias stub (which exits non-zero when given args); the
+  # version check rejects a lone python2 whose py3 syntax would crash at runtime.
+  _av_python_valid() {
+    [[ -n "${1:-}" ]] || return 1
+    "$1" -c 'import sys; sys.exit(0 if sys.version_info[0] >= 3 else 1)' >/dev/null 2>&1
+  }
+
+  _av_resolve_python() {
+    local cand resolved
+
+    # 1. Explicit override wins.
+    if [[ -n "${AGENTVIBES_PYTHON:-}" ]] && _av_python_valid "$AGENTVIBES_PYTHON"; then
+      printf '%s' "$AGENTVIBES_PYTHON"; return 0
+    fi
+
+    # 2. Previously-cached hit (strip a stray CR from a CRLF-edited cache file).
+    if [[ -f "$_AV_PY_CACHE" ]]; then
+      cand="$(head -1 "$_AV_PY_CACHE" 2>/dev/null | tr -d '\r' || true)"
+      if _av_python_valid "$cand"; then printf '%s' "$cand"; return 0; fi
+    fi
+
+    # 3. On PATH — but VALIDATE each (rejects the WindowsApps store stub).
+    for cand in python3 python python3.13 python3.12 python3.11 python3.10; do
+      resolved="$(command -v "$cand" 2>/dev/null || true)"
+      if [[ -n "$resolved" ]] && _av_python_valid "$resolved"; then
+        printf '%s' "$resolved"; return 0
+      fi
+    done
+
+    # 4. Windows `py` launcher — ask it for the real interpreter path. Python on
+    #    Windows emits CRLF even to a pipe, so strip the trailing CR or the exec
+    #    of "…python.exe\r" fails.
+    if command -v py >/dev/null 2>&1; then
+      cand="$(py -3 -c 'import sys; print(sys.executable)' 2>/dev/null | tr -d '\r' || true)"
+      if _av_python_valid "$cand"; then printf '%s' "$cand"; return 0; fi
+    fi
+
+    # 5. Known Windows install locations, newest version first. Built with
+    #    nullglob into an array so paths containing spaces ("C:\Program Files",
+    #    "C:\Users\John Smith\…") survive — an unquoted *variable* glob would
+    #    word-split them, which is exactly the case this resolver exists to fix.
+    #    This file is SOURCED, so nullglob is saved and restored to avoid leaking
+    #    the option into the calling hook.
+    local _av_restore_glob; _av_restore_glob="$(shopt -p nullglob 2>/dev/null || true)"
+    shopt -s nullglob 2>/dev/null || true
+    local -a _av_pys=(
+      "${LOCALAPPDATA:-$HOME/AppData/Local}/Programs/Python"/Python3*/python.exe
+      "$HOME/AppData/Local/Programs/Python"/Python3*/python.exe
+      /c/Python3*/python.exe
+      "/c/Program Files/Python3"*/python.exe
+      "/c/Program Files (x86)/Python3"*/python.exe
+    )
+    eval "${_av_restore_glob:-shopt -u nullglob}" 2>/dev/null || true
+    # Version-sort descending (Python312 before Python39 — a plain sort -r is
+    # lexical and would rank "39" above "312"); NUL-delimited so spacey paths
+    # stay intact. `sort -zrV` is GNU coreutils, which git-bash ships (this glob
+    # only ever matches under git-bash anyway).
+    if [[ ${#_av_pys[@]} -gt 0 ]]; then
+      while IFS= read -r -d '' cand; do
+        _av_python_valid "$cand" && { printf '%s' "$cand"; return 0; }
+      done < <(printf '%s\0' "${_av_pys[@]}" | sort -zrV 2>/dev/null)
+    fi
+
+    return 1
+  }
+
+  PYTHON_BIN="$(_av_resolve_python || true)"
+  export PYTHON_BIN
+
+  # Cache a fresh discovery (best-effort; never fatal). Only rewrite when it
+  # actually changed, to avoid needless disk writes on every hook invocation.
+  if [[ -n "$PYTHON_BIN" ]]; then
+    if [[ ! -f "$_AV_PY_CACHE" ]] || [[ "$(head -1 "$_AV_PY_CACHE" 2>/dev/null | tr -d '\r' || true)" != "$PYTHON_BIN" ]]; then
+      mkdir -p "$(dirname "$_AV_PY_CACHE")" 2>/dev/null || true
+      printf '%s\n' "$PYTHON_BIN" > "$_AV_PY_CACHE" 2>/dev/null || true
+    fi
+  fi
+fi

package/.claude/hooks/session-id.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/session-id.sh
+#
+# AgentVibes - Canonical routing session-id helper.
+#
+# The receiver MULTIPLEXES forwarded TTS from many sources (multiple local
+# projects + remote machines) keyed by a per-message identity. That identity
+# MUST be stable and correctly derived, or the receiver merges unrelated
+# sessions into one.
+#
+# This helper is the SINGLE source of truth for that routing id so every
+# forward path (e.g. play-tts-ssh-remote.sh SSH) derives it identically:
+#
+#   session id = basename(CLAUDE_PROJECT_DIR)   when CLAUDE_PROJECT_DIR is set
+#              = basename(<fallback dir>)        otherwise (passed dir, else PWD)
+#
+# It is intentionally NOT basename(install root): for a global install
+# (~/.claude/hooks) that basename collapses to the HOME dir name (e.g.
+# "administrator"), so every project on the machine would report the same id.
+#
+# NOTE: This is a PLAIN SLUG for routing — do NOT confuse it with
+# agentvibes-session-id.sh, which produces a human SPOKEN identity string.
+#
+# Usage:
+#   source "$(dirname "${BASH_SOURCE[0]}")/session-id.sh"
+#   SESSION_ID="$(av_session_id "$FALLBACK_PROJECT_DIR")"
+#
+# bash-3.2 safe (macOS default bash). Sourced by scripts already in strict mode;
+# defines a function only and does not alter shell options.
+#
+
+# av_session_id [fallback_dir]
+#   Prints the canonical routing session id (plain slug) to stdout.
+#   Prefers CLAUDE_PROJECT_DIR (the real user project injected via
+#   --project-dir); else the passed fallback dir; else PWD. Callers MUST pass a
+#   real project dir as the fallback — never the package/install root.
+av_session_id() {
+  local _dir="${CLAUDE_PROJECT_DIR:-}"
+  if [[ -z "$_dir" ]]; then
+    _dir="${1:-$PWD}"
+  fi
+  # Strip trailing slashes so basename of "/a/b/" is "b", not "".
+  while [[ "$_dir" == */ && "${#_dir}" -gt 1 ]]; do
+    _dir="${_dir%/}"
+  done
+  local _base
+  _base="$(basename "$_dir" 2>/dev/null || printf '%s' "$_dir")"
+  # Slugify: collapse anything outside [A-Za-z0-9._-] to '-' so the id is safe
+  # as a JSON string and a stable map key on the receiver.
+  _base="$(printf '%s' "$_base" | tr -c 'A-Za-z0-9._-' '-')"
+  # Trim leading/trailing dashes introduced by slugification.
+  _base="${_base#-}"; _base="${_base%-}"
+  [[ -z "$_base" ]] && _base="unknown"
+  printf '%s' "$_base"
+}

package/.claude/hooks/session-start-tts.sh

@@ -38,6 +38,45 @@ else
   _PROJECT_CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
 fi
 
+# ---------------------------------------------------------------------------
+# OPT-IN INJECTION GATE (Issue: global-install cacophony).
+#
+# Previously this hook injected the ~250-token TTS protocol into EVERY session
+# where AgentVibes was found on disk. A GLOBAL install therefore made every open
+# Claude session start speaking at once ("a cacophony of agents"). It also spent
+# tokens on idle sessions that never wanted audio. Injection is now OPT-IN.
+#
+# Two distinct markers, kept SEPARATE on purpose:
+#   * agentvibes-unmuted / agentvibes-muted — the user's runtime mute choice,
+#     also read by play-tts.sh, where a project `unmuted` OVERRIDES a global mute.
+#   * agentvibes-enabled — "this project opted into injection" (written by a
+#     project install). It does NOT override a global mute; it only turns the
+#     protocol injection on. This separation is why a project install can no
+#     longer silently defeat a user's `~/.agentvibes-muted` global kill-switch.
+#
+# Precedence (mirrors play-tts.sh so injection and audio agree):
+#   1. project agentvibes-unmuted  → inject   (explicit per-project ON)
+#   2. project agentvibes-muted    → silent
+#   3. global ~/.agentvibes-muted  → silent   (the global kill-switch)
+#   4. project agentvibes-enabled, OR global opt-in
+#      (~/.claude/agentvibes-enabled or ~/.claude/agentvibes-unmuted) → inject
+#   5. otherwise                   → silent   (opt-in default; zero tokens)
+if [[ -f "$_PROJECT_CLAUDE_DIR/agentvibes-unmuted" ]]; then
+  :   # explicit per-project enable — wins over a global mute, as in play-tts.sh
+elif [[ -f "$_PROJECT_CLAUDE_DIR/agentvibes-muted" ]]; then
+  exit 0
+elif [[ -f "$HOME/.agentvibes-muted" ]]; then
+  exit 0   # global kill-switch, no per-project override
+elif [[ -f "$_PROJECT_CLAUDE_DIR/agentvibes-enabled" \
+     || -f "$HOME/.claude/agentvibes-enabled" \
+     || -f "$HOME/.claude/agentvibes-unmuted" ]]; then
+  :   # opted in (project install marker, or a deliberate global opt-in)
+else
+  # Not enabled for this project → inject nothing (zero tokens).
+  # Enable for this project with:  /agent-vibes:unmute
+  exit 0
+fi
+
 # Build --project-dir flag to embed in TTS commands.
 # Sanitize: strip any embedded quotes that would break shell quoting.
 PROJECT_DIR_FLAG=""

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

@@ -37,7 +37,7 @@
 # @dependencies .claude/config/tts-speech-rate.txt, .claude/config/tts-target-speech-rate.txt
 # @entrypoints Called by /agent-vibes:set-speed slash command
 # @patterns Provider-agnostic speed config, legacy file migration, random tongue twisters for testing
-# @related play-tts.sh, play-tts-piper.sh, play-tts-macos.sh, learn-manager.sh
+# @related play-tts.sh, play-tts-piper.sh, play-tts-macos.sh
 #
 
 # Get script directory

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

@@ -32,7 +32,7 @@
 # @dependencies translator.py, language-manager.sh, .bmad/core/config.yaml (optional)
 # @entrypoints Called by /agent-vibes:translate commands and play-tts.sh
 # @patterns Config cascade - manual override > BMAD config > default (no translation)
-# @related translator.py, play-tts.sh, language-manager.sh, learn-manager.sh
+# @related translator.py, play-tts.sh, language-manager.sh
 
 # Only set strict mode when executed directly, not when sourced
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
@@ -40,6 +40,7 @@ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
 fi
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/python-resolver.sh"
 
 # Use PWD for project dir when called from project context, fall back to script-relative
 if [[ -d "$PWD/.claude" ]]; then
@@ -173,7 +174,7 @@ translate_text() {
 
     # Call translator.py
     local translated
-    translated=$(python3 "$SCRIPT_DIR/translator.py" "$text" "$target" 2>/dev/null) || translated="$text"
+    translated=$("$PYTHON_BIN" "$SCRIPT_DIR/translator.py" "$text" "$target" 2>/dev/null) || translated="$text"
 
     echo "$translated"
 }

package/.claude/hooks/translator.py

@@ -32,7 +32,7 @@
 # @dependencies deep-translator, langdetect (pip install deep-translator langdetect)
 # @entrypoints CLI: python3 translator.py <text> <target_lang>, Library: from translator import translate
 # @patterns Command pattern - supports translate, detect, and batch operations
-# @related play-tts.sh, learn-manager.sh, language-manager.sh
+# @related play-tts.sh, language-manager.sh
 #
 
 """

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