agentvibes 5.9.0 → 5.11.0

package/.claude/hooks/piper-installer.sh

@@ -178,9 +178,9 @@ else
 
     # Try to install pipx
     if command -v apt-get &> /dev/null; then
-      # Debian/Ubuntu
-      sudo apt-get update
-      sudo apt-get install -y pipx
+      # Debian/Ubuntu — DEBIAN_FRONTEND prevents tzdata interactive prompt
+      DEBIAN_FRONTEND=noninteractive sudo -E apt-get update -qq
+      DEBIAN_FRONTEND=noninteractive sudo -E apt-get install -y pipx
     elif command -v brew &> /dev/null; then
       # Linux with Homebrew
       brew install pipx
@@ -198,16 +198,21 @@ else
       exit 1
     fi
 
-    # Ensure pipx is in PATH
-    pipx ensurepath
+    # Ensure pipx is in PATH (updates shell rc file) and update current session
+    pipx ensurepath 2>/dev/null || true
+    export PATH="$HOME/.local/bin:$PATH"
     echo ""
   fi
 
+  # Make sure ~/.local/bin is in PATH for this session (pipx installs there)
+  export PATH="$HOME/.local/bin:$PATH"
+  INSTALL_DIR="$HOME/.local/bin"
+
   # Install Piper TTS
   echo "📥 Installing Piper TTS via pipx..."
   pipx install piper-tts
 
-  if ! command -v piper &> /dev/null; then
+  if ! command -v piper &> /dev/null && [[ ! -x "$HOME/.local/bin/piper" ]]; then
     echo ""
     echo "❌ Installation completed but piper command not found in PATH"
     echo ""

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

@@ -62,16 +62,16 @@ PIPER_VOICES_BASE_URL="https://huggingface.co/rhasspy/piper-voices/resolve/main"
 # @calledby All voice management functions (verify_voice, get_voice_path, download_voice, list_downloaded_voices)
 # @calls mkdir, cat, dirname
 get_voice_storage_dir() {
-  local voice_dir
+  local voice_dir=""
 
   # Check for custom path in environment or config file
-  if [[ -n "$PIPER_VOICES_DIR" ]]; then
-    voice_dir="$PIPER_VOICES_DIR"
+  if [[ -n "${PIPER_VOICES_DIR:-}" ]]; then
+    voice_dir="${PIPER_VOICES_DIR}"
   else
     # Check for config file (project-local first, then global)
-    local config_file
-    if [[ -n "$CLAUDE_PROJECT_DIR" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt" ]]; then
-      config_file="$CLAUDE_PROJECT_DIR/.claude/piper-voices-dir.txt"
+    local config_file=""
+    if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && [[ -f "${CLAUDE_PROJECT_DIR}/.claude/piper-voices-dir.txt" ]]; then
+      config_file="${CLAUDE_PROJECT_DIR}/.claude/piper-voices-dir.txt"
     else
       # Search up directory tree for .claude/
       local current_dir="$PWD"

package/.claude/hooks/play-tts-agentvibes-receiver-for-voiceless-connections.sh

@@ -98,7 +98,9 @@ echo "📱 Sending to $SSH_HOST for local playback..." >&2
 # Build SSH args — use explicit key/port from config if available, else rely on ~/.ssh/config
 SSH_ARGS=()
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
-[[ -n "$SSH_PORT" ]] && SSH_ARGS+=(-p "$SSH_PORT")
+# Never force "-p 22" (ssh default) -- it would override an ~/.ssh/config
+# Host alias port (e.g. laptop-win -> 45217). Empty/22 => defer to ssh config.
+if [[ -n "$SSH_PORT" && "$SSH_PORT" != "22" ]]; then SSH_ARGS+=(-p "$SSH_PORT"); fi
 
 # Try receiver scripts in order — single SSH call, no separate probe
 # SECURITY: Base64-encoded values are safe to pass as arguments (no shell metacharacters)

package/.claude/hooks/play-tts-elevenlabs.sh

@@ -0,0 +1,360 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-elevenlabs.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 ElevenLabs TTS Provider — cloud neural voices with 32+ language support
+# @context Provider-specific implementation for ElevenLabs API integration
+# @architecture Implements provider contract: text/voice → audio playback
+# @dependencies ELEVENLABS_API_KEY env var, curl, ffmpeg (optional), audio player
+# @entrypoints Called by play-tts.sh router when provider=elevenlabs
+# @related play-tts.sh, provider-manager.sh, language-manager.sh
+#
+# Voice can be a name (e.g. "Rachel") or a raw ElevenLabs voice ID.
+# Set ELEVENLABS_API_KEY in your shell profile or via Infisical.
+# Default voice: Rachel (English, warm female)
+#
+
+set -euo pipefail
+export LC_ALL=C
+
+TEXT="${1:-}"
+VOICE_OVERRIDE="${2:-}"
+
+# Resolve script dir (handles symlinks)
+SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+
+source "$SCRIPT_DIR/audio-cache-utils.sh"
+source "$SCRIPT_DIR/language-manager.sh"
+
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice_name_or_id]" >&2
+  exit 1
+fi
+
+# Clamp text to 2000 chars (ElevenLabs API limit)
+if [[ ${#TEXT} -gt 2000 ]]; then
+  TEXT="${TEXT:0:1997}..."
+fi
+
+# ---------------------------------------------------------------------------
+# Optional: fetch the key from Infisical on demand, so no key is stored on disk.
+# Opt-in via ~/.agentvibes/infisical.env, which sets (env vars take precedence):
+#   INFISICAL_SECRET_NAME   name of the secret in Infisical (e.g. ELEVEN_LABS)
+#   INFISICAL_PROJECT_ID    project/workspace id
+#   INFISICAL_ENV           environment slug         (default: prod)
+#   INFISICAL_DOMAIN        API base URL             (default: http://127.0.0.1:8200/api)
+#   INFISICAL_BOOTSTRAP     universal-auth creds file (default: ~/.palace-bootstrap)
+# Requires the infisical CLI + python3. Fails soft: prints nothing and returns
+# non-zero when unconfigured or unreachable, so the normal error path still runs.
+# The fetched value is never printed.
+_fetch_key_from_infisical() {
+  local cfg="${HOME}/.agentvibes/infisical.env"
+  if [[ -f "$cfg" ]]; then
+    set -o allexport; source "$cfg"; set +o allexport
+  fi
+
+  local secret_name="${INFISICAL_SECRET_NAME:-}"
+  local project_id="${INFISICAL_PROJECT_ID:-}"
+  local env_name="${INFISICAL_ENV:-prod}"
+  local domain="${INFISICAL_DOMAIN:-http://127.0.0.1:8200/api}"
+  local bootstrap="${INFISICAL_BOOTSTRAP:-${HOME}/.palace-bootstrap}"
+
+  [[ -n "$secret_name" && -n "$project_id" ]] || return 1
+  command -v infisical >/dev/null 2>&1 || return 1
+  command -v python3   >/dev/null 2>&1 || return 1
+
+  # Obtain an access token: reuse an exported INFISICAL_TOKEN, else exchange the
+  # universal-auth client credentials from the bootstrap file (creds via env only).
+  local token="${INFISICAL_TOKEN:-}"
+  if [[ -z "$token" ]]; then
+    [[ -f "$bootstrap" ]] || return 1
+    set -o allexport; source "$bootstrap"; set +o allexport
+    [[ -n "${INFISICAL_UNIVERSAL_AUTH_CLIENT_ID:-}" && -n "${INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET:-}" ]] || return 1
+    token="$(_AV_DOMAIN="$domain" python3 -c '
+import os, json, urllib.request
+d = os.environ["_AV_DOMAIN"].rstrip("/")
+req = urllib.request.Request(d + "/v1/auth/universal-auth/login",
+    data=json.dumps({"clientId": os.environ["INFISICAL_UNIVERSAL_AUTH_CLIENT_ID"],
+                     "clientSecret": os.environ["INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET"]}).encode(),
+    headers={"Content-Type": "application/json"})
+print(json.loads(urllib.request.urlopen(req, timeout=10).read())["accessToken"])
+' 2>/dev/null || true)"
+  fi
+  [[ -n "$token" ]] || return 1
+
+  INFISICAL_TOKEN="$token" infisical secrets get "$secret_name" \
+    --projectId "$project_id" --env "$env_name" --domain "$domain" \
+    --plain 2>/dev/null | head -1
+}
+
+# ---------------------------------------------------------------------------
+# API key — env var (only if it looks valid), then key file, then Infisical.
+# A malformed/truncated ELEVENLABS_API_KEY (e.g. a half-pasted key) is ignored so
+# it can't silently shadow a good key file — a common foot-gun that yields
+# confusing "API key fail" errors despite a valid key on disk.
+_looks_like_el_key() {
+  [[ "$1" =~ ^sk_[A-Za-z0-9]{40,}$ ]] && return 0   # current format: sk_ + >=40 chars
+  [[ "$1" =~ ^[A-Fa-f0-9]{32}$ ]] && return 0        # legacy 32-char hex key
+  return 1
+}
+
+API_KEY=""
+if [[ -n "${ELEVENLABS_API_KEY:-}" ]]; then
+  # A non-empty env var is authoritative — ElevenLabs has shipped several key
+  # formats over time, so we must not silently discard a key just because it
+  # looks unfamiliar. Warn (using ONLY the length, never the value) if the format
+  # is unexpected, but use it regardless.
+  API_KEY="$ELEVENLABS_API_KEY"
+  if ! _looks_like_el_key "$ELEVENLABS_API_KEY"; then
+    echo "⚠️  ELEVENLABS_API_KEY env var has an unexpected format (length ${#ELEVENLABS_API_KEY}); using it anyway." >&2
+  fi
+fi
+if [[ -z "$API_KEY" ]]; then
+  _key_file="${HOME}/.agentvibes/elevenlabs-key.txt"
+  if [[ -f "$_key_file" ]]; then
+    API_KEY="$(tr -d '[:space:]' < "$_key_file")"
+  fi
+fi
+if [[ -z "$API_KEY" ]]; then
+  API_KEY="$(_fetch_key_from_infisical || true)"
+  API_KEY="$(printf '%s' "$API_KEY" | tr -d '[:space:]')"
+fi
+
+if [[ -z "$API_KEY" ]]; then
+  echo "❌ ElevenLabs API key not set." >&2
+  echo "   Set it one of three ways:" >&2
+  echo "   1. export ELEVENLABS_API_KEY=your_key  (add to ~/.bashrc or ~/.zshrc)" >&2
+  echo "   2. echo 'your_key' > ~/.agentvibes/elevenlabs-key.txt && chmod 600 ~/.agentvibes/elevenlabs-key.txt" >&2
+  echo "   3. Configure Infisical in ~/.agentvibes/infisical.env (INFISICAL_SECRET_NAME + INFISICAL_PROJECT_ID)" >&2
+  echo "   Get a free key at: https://elevenlabs.io" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Inline voice name → ID map (covers common built-in ElevenLabs voices)
+declare -A VOICE_IDS
+VOICE_IDS["Rachel"]="21m00Tcm4TlvDq8ikWAM"
+VOICE_IDS["Adam"]="pNInz6obpgDQGcFmaJgB"
+VOICE_IDS["Antoni"]="ErXwobaYiN019PkySvjV"
+VOICE_IDS["Arnold"]="VR6AewLTigWG4xSOukaG"
+VOICE_IDS["Bella"]="EXAVITQu4vr4xnSDxMaL"
+VOICE_IDS["Callum"]="N2lVS1w4EtoT3dr4eOWO"
+VOICE_IDS["Charlie"]="IKne3meq5aSn9XLyUdCD"
+VOICE_IDS["Charlotte"]="XB0fDUnXU5powFXDhCwa"
+VOICE_IDS["Clyde"]="2EiwWnXFnvU5JabPnv8n"
+VOICE_IDS["Daniel"]="onwK4e9ZLuTAKqWW03F9"
+VOICE_IDS["Dave"]="CYw3kZ02Hs0563khs1Fj"
+VOICE_IDS["Dorothy"]="ThT5KcBeYPX3keUQqHPh"
+VOICE_IDS["Domi"]="AZnzlk1XvdvUeBnXmlld"
+VOICE_IDS["Drew"]="29vD33N1CtxCmqQRPOHJ"
+VOICE_IDS["Emily"]="LcfcDJNUP1GQjkzn1xUU"
+VOICE_IDS["Ethan"]="g5CIjZEefAph4nQFvHAz"
+VOICE_IDS["Fin"]="D38z5RcWu1voky8WS1ja"
+VOICE_IDS["Freya"]="jsCqWAovK2LkecY7zXl4"
+VOICE_IDS["Gigi"]="jBpfuIE2acCO8z3wKNLl"
+VOICE_IDS["Giovanni"]="zcAOhNBS3c14rBihAFp1"
+VOICE_IDS["Glinda"]="z9fAnlkpzviPz146aGWa"
+VOICE_IDS["Grace"]="oWAxZDx7w5VEj9dCyTzz"
+VOICE_IDS["Harry"]="SOYHLrjzK2X1ezoPC6cr"
+VOICE_IDS["James"]="ZQe5CZNOzWyzPSCn5a3c"
+VOICE_IDS["Jessie"]="t0jbNlBVZ17f02VDIeMI"
+VOICE_IDS["Josh"]="TxGEqnHWrfWFTfGW9XjX"
+VOICE_IDS["Liam"]="TX3LPaxmHKxFdv7VOQHJ"
+VOICE_IDS["Lily"]="pFZP5JQG7iQjIQuC4Bku"
+VOICE_IDS["Matilda"]="XrExE9yKIg1WjnnlVkGX"
+VOICE_IDS["Michael"]="flq6f7yk4E4fJM5XTYuZ"
+VOICE_IDS["Mimi"]="zrHiDhphv9ZnVXBqCLjz"
+VOICE_IDS["Nicole"]="piTKgcLEGmPE4e6mEKli"
+VOICE_IDS["Patrick"]="ODq5zmih8GrVes37Dizd"
+VOICE_IDS["Paul"]="5Q0t7uMcjvnagumLfvZi"
+VOICE_IDS["Sam"]="yoZ06aMxZJJ28mfd3POQ"
+VOICE_IDS["Sarah"]="EXAVITQu4vr4xnSDxMaL"
+VOICE_IDS["Serena"]="pMsXgVXv3BLzUgSXRplE"
+VOICE_IDS["Thomas"]="GBv7mTt0atIp3Br8iCZE"
+
+DEFAULT_VOICE_ID="${VOICE_IDS[Rachel]}"
+
+# ---------------------------------------------------------------------------
+# Resolve voice ID from override or config
+VOICE_ID=""
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  if [[ -n "${VOICE_IDS[$VOICE_OVERRIDE]:-}" ]]; then
+    VOICE_ID="${VOICE_IDS[$VOICE_OVERRIDE]}"
+  elif [[ "$VOICE_OVERRIDE" =~ ^[a-zA-Z0-9]{10,40}$ ]]; then
+    # Looks like a raw voice ID
+    VOICE_ID="$VOICE_OVERRIDE"
+  else
+    echo "⚠️  Unknown ElevenLabs voice '$VOICE_OVERRIDE', using Rachel" >&2
+    VOICE_ID="$DEFAULT_VOICE_ID"
+  fi
+else
+  # Check voice manager for configured voice
+  VOICE_NAME=""
+  if [[ -f "$SCRIPT_DIR/voice-manager.sh" ]]; then
+    VOICE_NAME="$("$SCRIPT_DIR/voice-manager.sh" get 2>/dev/null || true)"
+  fi
+
+  if [[ -n "$VOICE_NAME" && -n "${VOICE_IDS[$VOICE_NAME]:-}" ]]; then
+    VOICE_ID="${VOICE_IDS[$VOICE_NAME]}"
+  else
+    VOICE_ID="$DEFAULT_VOICE_ID"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Language/model selection
+CURRENT_LANGUAGE="$(get_language_code 2>/dev/null || echo 'english')"
+
+case "$CURRENT_LANGUAGE" in
+  english) LANGUAGE_CODE="en"; MODEL_ID="eleven_turbo_v2_5" ;;
+  spanish) LANGUAGE_CODE="es"; MODEL_ID="eleven_multilingual_v2" ;;
+  french)  LANGUAGE_CODE="fr"; MODEL_ID="eleven_multilingual_v2" ;;
+  german)  LANGUAGE_CODE="de"; MODEL_ID="eleven_multilingual_v2" ;;
+  italian) LANGUAGE_CODE="it"; MODEL_ID="eleven_multilingual_v2" ;;
+  portuguese) LANGUAGE_CODE="pt"; MODEL_ID="eleven_multilingual_v2" ;;
+  chinese) LANGUAGE_CODE="zh"; MODEL_ID="eleven_multilingual_v2" ;;
+  japanese) LANGUAGE_CODE="ja"; MODEL_ID="eleven_multilingual_v2" ;;
+  korean)  LANGUAGE_CODE="ko"; MODEL_ID="eleven_multilingual_v2" ;;
+  russian) LANGUAGE_CODE="ru"; MODEL_ID="eleven_multilingual_v2" ;;
+  polish)  LANGUAGE_CODE="pl"; MODEL_ID="eleven_multilingual_v2" ;;
+  dutch)   LANGUAGE_CODE="nl"; MODEL_ID="eleven_multilingual_v2" ;;
+  arabic)  LANGUAGE_CODE="ar"; MODEL_ID="eleven_multilingual_v2" ;;
+  hindi)   LANGUAGE_CODE="hi"; MODEL_ID="eleven_multilingual_v2" ;;
+  turkish) LANGUAGE_CODE="tr"; MODEL_ID="eleven_multilingual_v2" ;;
+  swedish) LANGUAGE_CODE="sv"; MODEL_ID="eleven_multilingual_v2" ;;
+  *)       LANGUAGE_CODE="en"; MODEL_ID="eleven_turbo_v2_5" ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Audio output directory
+AUDIO_DIR="$(get_audio_cache_dir 2>/dev/null || echo "${HOME}/.claude/audio")"
+mkdir -p "$AUDIO_DIR"
+chmod 700 "$AUDIO_DIR"
+
+TEMP_FILE="${AUDIO_DIR}/tts-elevenlabs-$(date +%s%N | head -c 18).mp3"
+BODY_FILE="${AUDIO_DIR}/tts-el-body-$(date +%s%N | head -c 18).json"
+trap 'rm -f "${TEMP_FILE:-}" "${BODY_FILE:-}" 2>/dev/null || true' EXIT
+
+# ---------------------------------------------------------------------------
+# Build the JSON request body with python so all escaping is handled correctly
+# (text is passed via env, never interpolated into a shell-quoted payload).
+if ! TTS_TEXT="$TEXT" TTS_MODEL="$MODEL_ID" TTS_LANG="$LANGUAGE_CODE" python3 -c '
+import os, json
+print(json.dumps({
+    "text": os.environ["TTS_TEXT"],
+    "model_id": os.environ["TTS_MODEL"],
+    "language_code": os.environ["TTS_LANG"],
+    "voice_settings": {"stability": 0.5, "similarity_boost": 0.75},
+}))' > "$BODY_FILE" 2>/dev/null; then
+  echo "❌ Failed to build ElevenLabs request body (python3 required)" >&2
+  exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Test mode: never make a billable request to the ElevenLabs API (and never play
+# audio). Short-circuit BEFORE the network call. Mirrors the sibling providers'
+# AGENTVIBES_TEST_MODE handling; the EXIT trap cleans up the temp files.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Call ElevenLabs API
+# Security: API key passed via a curl config read from stdin (-K -), so it never
+# appears in argv (where `ps` could expose it) nor in any temp file.
+HTTP_STATUS=$(printf 'header = "xi-api-key: %s"\n' "$API_KEY" | curl -s -o "$TEMP_FILE" -w "%{http_code}" \
+  -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" \
+  -K - \
+  -H "Content-Type: application/json" \
+  --max-time 30 \
+  --data-binary "@${BODY_FILE}" 2>&1)
+rm -f "$BODY_FILE" 2>/dev/null || true
+
+if [[ "$HTTP_STATUS" != "200" ]]; then
+  echo "❌ ElevenLabs API error (HTTP $HTTP_STATUS)" >&2
+  if [[ -f "$TEMP_FILE" ]]; then
+    cat "$TEMP_FILE" >&2
+  fi
+  exit 3
+fi
+
+if [[ ! -f "$TEMP_FILE" || ! -s "$TEMP_FILE" ]]; then
+  echo "❌ ElevenLabs returned empty audio" >&2
+  exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Convert MP3 → WAV so the post-processor (sox effects) can read it, and add a
+# short silence lead-in (prevents a clipped first phoneme / WSL audio static).
+# ffmpeg is preferred; if it is absent we keep the MP3 and skip effects/music.
+if command -v ffmpeg &>/dev/null; then
+  _WAV="${AUDIO_DIR}/tts-el-$(date +%s%N | head -c 18).wav"
+  trap 'rm -f "${TEMP_FILE:-}" "${_WAV:-}" 2>/dev/null || true' EXIT
+  if ffmpeg -f lavfi -i "anullsrc=r=44100:cl=mono:d=0.15" -i "$TEMP_FILE" \
+      -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" \
+      -map "[out]" -ar 44100 -ac 1 -y "$_WAV" 2>/dev/null \
+      && [[ -s "$_WAV" ]]; then
+    rm -f "$TEMP_FILE"
+    TEMP_FILE="$_WAV"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Post-process: apply audio effects (reverb/echo/chorus via sox) and mix
+# background music (via ffmpeg) — exactly like the Piper provider does. Honors
+# the per-LLM row (AGENTVIBES_LLM_KEY) and any per-call AGENTVIBES_REVERB_OVERRIDE.
+# Fails soft: if audio-processor.sh or its tools (sox/ffmpeg) are missing, the
+# unprocessed audio is played instead. NOTE: reverb/echo/chorus REQUIRE sox to be
+# installed; without it, effects are silently skipped (background music still works
+# via ffmpeg).
+#
+# Only post-process when invoked via the orchestrator (which exports
+# AGENTVIBES_LLM_KEY) or with an explicit per-call effect override. A bare direct
+# call — e.g. the voice-picker audition — gets the clean, dry voice so the user
+# hears the voice itself, not the default LLM row's effects/music.
+if [[ -f "$SCRIPT_DIR/audio-processor.sh" \
+      && ( -n "${AGENTVIBES_LLM_KEY:-}" || -n "${AGENTVIBES_REVERB_OVERRIDE:-}" ) ]]; then
+  _PROCESSED="${AUDIO_DIR}/tts-el-proc-$(date +%s%N | head -c 18).wav"
+  trap 'rm -f "${TEMP_FILE:-}" "${_PROCESSED:-}" 2>/dev/null || true' EXIT
+  _AGENT_KEY="${AGENTVIBES_LLM_KEY:-default}"
+  if _PROC_OUT="$(bash "$SCRIPT_DIR/audio-processor.sh" "$TEMP_FILE" "$_AGENT_KEY" "$_PROCESSED" 2>/dev/null)"; then
+    _PF="${_PROC_OUT%%|*}"
+    if [[ -n "$_PF" && -f "$_PF" && -s "$_PF" && "$_PF" != "$TEMP_FILE" ]]; then
+      rm -f "$TEMP_FILE"
+      TEMP_FILE="$_PF"
+    fi
+  fi
+fi
+
+# Play audio (skip in test mode or no-playback mode — matches the Piper provider)
+# AGENTVIBES_NO_PLAYBACK: Set to "true" to generate audio without playing (for post-processing)
+# Native Windows (git-bash, OS=Windows_NT — not WSL) has none of the Linux
+# players, and ffplay spawned from the TUI's Node process is unreliable. Use the
+# built-in PowerShell WPF MediaPlayer (same as audio-env.js) — no ffmpeg/PATH
+# dependency. Other platforms try the usual players.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]] && [[ "${AGENTVIBES_NO_PLAYBACK:-false}" != "true" ]]; then
+  _PS_BIN="$(command -v powershell 2>/dev/null || command -v powershell.exe 2>/dev/null || true)"
+  if [[ "${OS:-}" == "Windows_NT" && -n "$_PS_BIN" ]]; then
+    _WINPATH="$(cygpath -w "$TEMP_FILE" 2>/dev/null || echo "$TEMP_FILE")"
+    _WINPATH="${_WINPATH//\'/\'\'}"   # escape single quotes for the PowerShell literal
+    "$_PS_BIN" -NoProfile -Command "Add-Type -AssemblyName PresentationCore; \$p = New-Object System.Windows.Media.MediaPlayer; \$p.Open([uri]'${_WINPATH}'); \$p.Play(); Start-Sleep -Milliseconds 300; \$last=[TimeSpan]::Zero; \$stall=0; \$n=0; while (\$n -lt 100) { Start-Sleep -Milliseconds 100; \$pos=\$p.Position; if (\$p.NaturalDuration.HasTimeSpan -and \$pos -ge \$p.NaturalDuration.TimeSpan) { break }; if (\$pos -eq \$last) { \$stall++ } else { \$stall=0 }; if (\$stall -ge 8 -and \$pos -gt [TimeSpan]::Zero) { break }; \$last=\$pos; \$n++ }; \$p.Stop(); \$p.Close()" 2>/dev/null || true
+  else
+    (paplay "$TEMP_FILE" 2>/dev/null \
+      || aplay "$TEMP_FILE" 2>/dev/null \
+      || mpg123 -q "$TEMP_FILE" 2>/dev/null \
+      || ffplay -nodisp -autoexit -loglevel error "$TEMP_FILE" 2>/dev/null \
+      || true) &
+    wait $!
+  fi
+fi
+
+# Cancel trap so file persists in cache (for replay)
+trap '' EXIT

package/.claude/hooks/play-tts-kokoro.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-kokoro.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 Kokoro TTS Provider — 82M-param local neural TTS, 60+ voices, 8+ languages
+# @context Provides high-quality local TTS via kokoro-onnx (MIT license, no API key needed)
+# @architecture Implements provider contract: text/voice → audio playback
+# @dependencies kokoro-onnx, soundfile, numpy (pip), ffmpeg (optional), audio player
+# @entrypoints Called by play-tts.sh router when provider=kokoro
+# @related play-tts.sh, kokoro-installer.sh, kokoro-tts.py
+#
+# Default voice: af_heart (American Female, warm)
+# Install: /home/user/.claude/hooks/kokoro-installer.sh
+# Or manually: pip install kokoro-onnx soundfile numpy
+#
+
+set -euo pipefail
+export LC_ALL=C
+
+TEXT="${1:-}"
+VOICE_OVERRIDE="${2:-}"
+
+# Resolve script dir (handles symlinks)
+SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+
+source "$SCRIPT_DIR/audio-cache-utils.sh"
+
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: $0 \"text to speak\" [voice]" >&2
+  exit 1
+fi
+
+# Check kokoro is installed (use find_spec to avoid slow torch import)
+if ! python3 -c "import importlib.util; exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null; then
+  echo "❌ Kokoro TTS not installed." >&2
+  echo "   Install with: ${SCRIPT_DIR}/kokoro-installer.sh" >&2
+  echo "   Or manually:  pip install kokoro-onnx soundfile numpy" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve voice
+DEFAULT_VOICE="af_heart"
+
+if [[ -n "$VOICE_OVERRIDE" ]]; then
+  # Accept kokoro-style voice IDs (2-letter prefix + underscore + name)
+  # e.g. af_heart, am_adam, bf_emma, bm_george
+  if [[ "$VOICE_OVERRIDE" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
+    VOICE="$VOICE_OVERRIDE"
+  else
+    echo "⚠️  Unrecognized kokoro voice '$VOICE_OVERRIDE', using $DEFAULT_VOICE" >&2
+    VOICE="$DEFAULT_VOICE"
+  fi
+else
+  # Check voice manager
+  if [[ -f "$SCRIPT_DIR/voice-manager.sh" ]]; then
+    _CONFIGURED="$("$SCRIPT_DIR/voice-manager.sh" get 2>/dev/null || true)"
+    if [[ "$_CONFIGURED" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
+      VOICE="$_CONFIGURED"
+    else
+      VOICE="$DEFAULT_VOICE"
+    fi
+  else
+    VOICE="$DEFAULT_VOICE"
+  fi
+fi
+
+# Speed from config (optional, defaults to 1.0)
+# SECURITY: Validate speed is numeric before passing to python (avoids traceback)
+SPEED="${KOKORO_SPEED:-1.0}"
+[[ "$SPEED" =~ ^[0-9]+(\.[0-9]+)?$ ]] || SPEED="1.0"
+
+# ---------------------------------------------------------------------------
+# Synthesis
+AUDIO_DIR="$(get_audio_cache_dir 2>/dev/null || echo "${HOME}/.claude/audio")"
+mkdir -p "$AUDIO_DIR"
+chmod 700 "$AUDIO_DIR"
+
+TEMP_WAV="${AUDIO_DIR}/tts-kokoro-$(date +%s%N | head -c 18).wav"
+trap 'rm -f "${TEMP_WAV:-}" 2>/dev/null || true' EXIT
+
+SYNTH_SCRIPT="${SCRIPT_DIR}/kokoro-tts.py"
+if [[ ! -f "$SYNTH_SCRIPT" ]]; then
+  echo "❌ kokoro-tts.py not found at $SYNTH_SCRIPT" >&2
+  exit 2
+fi
+
+# Skip the (slow) synthesis + playback entirely in test mode — nothing to play
+# and no need to spin up the kokoro model. Mirrors the sibling Piper provider.
+if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
+  trap '' EXIT
+  exit 0
+fi
+
+# Run synthesis — output path printed to stdout
+RESULT=$(python3 "$SYNTH_SCRIPT" "$TEXT" "$VOICE" "$TEMP_WAV" "$SPEED" 2>&1) || {
+  echo "❌ Kokoro synthesis failed: $RESULT" >&2
+  exit 3
+}
+
+if [[ ! -f "$TEMP_WAV" || ! -s "$TEMP_WAV" ]]; then
+  echo "❌ Kokoro synthesis produced no audio" >&2
+  exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Play audio — try players in order (WAV-capable)
+# Skip playback in test mode or no-playback mode (matches the Piper provider).
+# AGENTVIBES_NO_PLAYBACK: Set to "true" to generate audio without playing (for post-processing)
+if [[ "${AGENTVIBES_TEST_MODE:-false}" != "true" ]] && [[ "${AGENTVIBES_NO_PLAYBACK:-false}" != "true" ]]; then
+  (aplay -q "$TEMP_WAV" 2>/dev/null \
+    || paplay "$TEMP_WAV" 2>/dev/null \
+    || ffplay -nodisp -autoexit -loglevel quiet "$TEMP_WAV" 2>/dev/null \
+    || mpg123 -q "$TEMP_WAV" 2>/dev/null \
+    || true) &
+  wait $!
+fi
+
+# Cancel trap so file persists in cache
+trap '' EXIT

package/.claude/hooks/play-tts-piper.sh

@@ -73,10 +73,8 @@ TEXT=$(printf '%s' "$TEXT" | perl -CSD -pe '
   s/^\s*[-]\s*//g;                # list dashes
 ')
 
-# Source voice manager and language manager
-# Use readlink -f to handle symlinks correctly
-SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
-SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+# cd-based resolution works on macOS (BSD readlink lacks -f) and Linux alike
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 source "$SCRIPT_DIR/piper-voice-manager.sh"
 source "$SCRIPT_DIR/language-manager.sh"
 source "$SCRIPT_DIR/audio-cache-utils.sh"
@@ -226,11 +224,19 @@ if [[ -z "$TEXT" ]]; then
 fi
 
 # Augment PATH for non-interactive shells (pipx installs to ~/.local/bin which
-# interactive shells get via .bashrc/.zshrc, but Bash tool calls skip profile)
+# interactive shells get via .bashrc/.zshrc, but Bash tool calls skip profile).
+# Mac: add both Apple Silicon (/opt/homebrew) and Intel (/usr/local) Homebrew locations.
 export PATH="$HOME/.local/bin:$HOME/.local/share/pipx/venvs/piper-tts/bin:$PATH"
+if [[ "$(uname -s 2>/dev/null)" == "Darwin" ]]; then
+  export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+fi
+
+# Resolve explicit piper binary path — avoids bare `piper` invocation failing when
+# PATH augmentation above hasn't propagated into nested subshells.
+PIPER_BIN=$(command -v piper 2>/dev/null || echo "")
 
 # Check if Piper is installed
-if ! command -v piper &> /dev/null; then
+if [[ -z "$PIPER_BIN" ]]; then
   echo "❌ Error: Piper TTS not installed"
   echo "Install with: pipx install piper-tts"
   echo "Or run: .claude/hooks/piper-installer.sh"
@@ -309,6 +315,8 @@ else
 fi
 
 mkdir -p "$AUDIO_DIR"
+# Normalize to canonical path (handles Git Bash /tmp→/c/Users/..., macOS /var→/private/var)
+AUDIO_DIR=$(cd "$AUDIO_DIR" && pwd -P)
 _tmp=$(mktemp "$AUDIO_DIR/tts-XXXXXX"); TEMP_FILE="${_tmp}.wav"; mv "$_tmp" "$TEMP_FILE"
 
 # @function get_speech_rate
@@ -380,6 +388,10 @@ get_speech_rate() {
 
 SPEECH_RATE=$(get_speech_rate)
 
+# Ensure piper log directory exists so stderr redirect never silently fails
+_PIPER_LOG_DIR="${AGENTVIBES_LOG_DIR:-$HOME/.local/state/agentvibes/logs}"
+mkdir -p "$_PIPER_LOG_DIR" 2>/dev/null || true
+
 # @function synthesize_with_piper
 # @intent Generate speech using Piper TTS
 # @why Provides free, offline TTS alternative
@@ -391,10 +403,10 @@ SPEECH_RATE=$(get_speech_rate)
 if [[ -n "${SPEAKER_ID:-}" ]]; then
   # Multi-speaker voice: Pass speaker ID
   # SECURITY: Use printf instead of echo for pipe safety (#134)
-  printf '%s\n' "$TEXT" | piper --model "$VOICE_PATH" --speaker "$SPEAKER_ID" --length-scale "$SPEECH_RATE" --sentence-silence 2.0 --output_file "$TEMP_FILE" 2>/dev/null
+  printf '%s\n' "$TEXT" | "$PIPER_BIN" --model "$VOICE_PATH" --speaker "$SPEAKER_ID" --length-scale "$SPEECH_RATE" --sentence-silence 2.0 --output_file "$TEMP_FILE" 2>>"$_PIPER_LOG_DIR/piper.log"
 else
   # Single-speaker voice
-  printf '%s\n' "$TEXT" | piper --model "$VOICE_PATH" --length-scale "$SPEECH_RATE" --sentence-silence 2.0 --output_file "$TEMP_FILE" 2>/dev/null
+  printf '%s\n' "$TEXT" | "$PIPER_BIN" --model "$VOICE_PATH" --length-scale "$SPEECH_RATE" --sentence-silence 2.0 --output_file "$TEMP_FILE" 2>>"$_PIPER_LOG_DIR/piper.log"
 fi
 
 if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
@@ -538,11 +550,6 @@ AUDIO_DIR="${TEMP_FILE%/*}"
 WRITE_LOCK_FILE="$AUDIO_DIR/$(basename "$TEMP_FILE" .wav).lock"
 touch "$WRITE_LOCK_FILE"
 
-# Get audio duration for proper lock timing
-DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$TEMP_FILE" 2>/dev/null)
-DURATION=${DURATION%.*}  # Round to integer
-DURATION=${DURATION:-1}   # Default to 1 second if detection fails
-
 # Get audio duration for proper lock timing
 DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$TEMP_FILE" 2>/dev/null || true)
 DURATION=${DURATION%.*}  # Round to integer