agentvibes 3.3.0-alpha.6 → 3.3.0

package/.claude/commands/agent-vibes/clean.md

@@ -0,0 +1,18 @@
+---
+description: Clean all TTS audio cache files (non-interactive)
+scope: user
+---
+
+Execute the AgentVibes non-interactive cleanup script using the Bash tool:
+
+```bash
+.claude/hooks/clean-audio-cache.sh
+```
+
+This will:
+- Count all TTS cache files (tts-*.wav, tts-*.mp3, tts-*.aiff, tts-padded-*)
+- Delete all cache files immediately (no confirmation required)
+- Report the number of files deleted and space freed
+- Preserve background music tracks in the tracks/ subdirectory
+
+**Note:** For interactive cleanup with confirmation prompts, use `/agent-vibes:cleanup` instead.

package/.claude/commands/agent-vibes/commands.json

@@ -135,7 +135,11 @@
     },
     {
       "name": "cleanup",
-      "description": "Clean up TTS cache files to free up disk space"
+      "description": "Clean up TTS cache files to free up disk space (interactive)"
+    },
+    {
+      "name": "clean",
+      "description": "Clean all TTS audio cache files (non-interactive)"
     }
   ]
 }

package/.claude/config/audio-effects.cfg

@@ -49,4 +49,4 @@ BMad Master|reverb 50 60 100 pitch -100|agentvibes_soft_flamenco_loop.mp3|0.30
 _party_mode|compand 0.3,1 6:-70,-60,-20|agent_vibes_dark_chill_step_loop.mp3|0.40
 |||
 # Default (no agent specified) - clean with Bachata background|||
-default|reverb 20 50 50|agent_vibes_ganawa_ambient_v2_loop.mp3|0.30
+default|reverb 40 50 70|agentvibes_soft_flamenco_loop.mp3|0.30

package/.claude/config/background-music-position.txt

@@ -20,7 +20,7 @@ agent_vibes_japanese_city_pop_v1_loop.mp3:6.054512
 agent_vibes_bossa_nova_v2_loop.mp3:5.369524
 agent_vibes_salsa_v2_loop.mp3:9.972790
 agent_vibes_cumbia_v1_loop.mp3:5.717823
-agentvibes_soft_flamenco_loop.mp3:4.998005
 agent_vibes_arabic_v2_loop.mp3:.00000000000000000006132724
 agent_vibes_chillwave_v2_loop.mp3:14.628390
 agent_vibes_bachata_v1_loop.mp3:.00000000000000000005344000
+agentvibes_soft_flamenco_loop.mp3:.00000000000000000006934441

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260201
+20260205

package/.claude/hooks/audio-cache-utils.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+# AgentVibes Audio Cache Utility Functions
+# Provides common functions for file counting, sizing, and cleanup operations
+
+# Get the audio directory path with priority order
+# Returns: Absolute path to audio directory
+get_audio_dir() {
+  local audio_dir=""
+
+  # Priority 1: Project-local directory (if CLAUDE_PROJECT_DIR is set)
+  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+    audio_dir="$CLAUDE_PROJECT_DIR/.claude/audio"
+  else
+    # Priority 2: Walk up directory tree to find .claude
+    local current_dir="$PWD"
+    while [[ "$current_dir" != "/" ]]; do
+      if [[ -d "$current_dir/.claude" ]]; then
+        audio_dir="$current_dir/.claude/audio"
+        break
+      fi
+      current_dir=$(dirname "$current_dir")
+    done
+  fi
+
+  # Priority 3: Fallback to global ~/.claude/audio
+  if [[ -z "$audio_dir" ]]; then
+    audio_dir="$HOME/.claude/audio"
+  fi
+
+  echo "$audio_dir"
+}
+
+# Count TTS audio files (excludes background music tracks in tracks/ subdirectory)
+# Args: $1 = audio_dir (optional, defaults to get_audio_dir)
+# Returns: Integer count
+count_tts_files() {
+  local audio_dir="${1:-$(get_audio_dir)}"
+
+  if [[ ! -d "$audio_dir" ]]; then
+    echo "0"
+    return
+  fi
+
+  # Count TTS output files only (excludes subdirectories like tracks/)
+  local count=0
+  count=$(find "$audio_dir" -maxdepth 1 -type f \( \
+    -name "tts-*.wav" -o \
+    -name "tts-*.mp3" -o \
+    -name "tts-*.aiff" -o \
+    -name "tts-padded-*.mp3" -o \
+    -name "tts-padded-*.wav" \
+  \) 2>/dev/null | wc -l)
+
+  echo "$count"
+}
+
+# Calculate total size of TTS audio files in bytes
+# Args: $1 = audio_dir (optional, defaults to get_audio_dir)
+# Returns: Size in bytes (integer)
+calculate_tts_size_bytes() {
+  local audio_dir="${1:-$(get_audio_dir)}"
+
+  if [[ ! -d "$audio_dir" ]]; then
+    echo "0"
+    return
+  fi
+
+  local total_bytes=0
+  local stat_cmd=""
+
+  # Detect stat command format (BSD vs GNU)
+  if stat -c%s /dev/null >/dev/null 2>&1; then
+    stat_cmd="stat -c%s"
+  else
+    stat_cmd="stat -f%z"
+  fi
+
+  # Sum file sizes for all TTS files
+  while IFS= read -r file; do
+    if [[ -f "$file" ]]; then
+      local size=$($stat_cmd "$file" 2>/dev/null || echo "0")
+      total_bytes=$((total_bytes + size))
+    fi
+  done < <(find "$audio_dir" -maxdepth 1 -type f \( \
+    -name "tts-*.wav" -o \
+    -name "tts-*.mp3" -o \
+    -name "tts-*.aiff" -o \
+    -name "tts-padded-*.mp3" -o \
+    -name "tts-padded-*.wav" \
+  \) 2>/dev/null)
+
+  echo "$total_bytes"
+}
+
+# Convert bytes to human-readable format (e.g., "1.4MB", "230KB")
+# Args: $1 = bytes
+# Returns: Human-readable string (B, KB, MB, GB)
+bytes_to_human() {
+  local bytes="${1:-0}"
+
+  if [[ ! "$bytes" =~ ^[0-9]+$ ]]; then
+    bytes="0"
+  fi
+
+  if [[ $bytes -lt 1024 ]]; then
+    echo "${bytes}B"
+  elif [[ $bytes -lt 1048576 ]]; then
+    awk "BEGIN {printf \"%.1fKB\", $bytes/1024}"
+  elif [[ $bytes -lt 1073741824 ]]; then
+    awk "BEGIN {printf \"%.1fMB\", $bytes/1048576}"
+  else
+    awk "BEGIN {printf \"%.1fGB\", $bytes/1073741824}"
+  fi
+}
+
+# Get auto-cleanup threshold (number of files before cleanup triggers)
+# Returns: Integer threshold (default: 50)
+get_auto_clean_threshold() {
+  local threshold_file=""
+  local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+  # Priority order for config file
+  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && [[ -f "$CLAUDE_PROJECT_DIR/.claude/tts-auto-clean-threshold.txt" ]]; then
+    threshold_file="$CLAUDE_PROJECT_DIR/.claude/tts-auto-clean-threshold.txt"
+  elif [[ -f "$script_dir/../tts-auto-clean-threshold.txt" ]]; then
+    threshold_file="$script_dir/../tts-auto-clean-threshold.txt"
+  elif [[ -f "$HOME/.claude/tts-auto-clean-threshold.txt" ]]; then
+    threshold_file="$HOME/.claude/tts-auto-clean-threshold.txt"
+  fi
+
+  if [[ -n "$threshold_file" ]]; then
+    local threshold=$(grep -v '^\s*#' "$threshold_file" 2>/dev/null | grep -v '^\s*$' | head -1)
+    if [[ "$threshold" =~ ^[0-9]+$ ]]; then
+      echo "$threshold"
+      return
+    fi
+  fi
+
+  # Default threshold
+  echo "50"
+}
+
+# Delete oldest TTS files to stay under size threshold (in MB)
+# Args: $1 = audio_dir, $2 = threshold (size in MB)
+# Returns: Number of files deleted
+auto_clean_old_files() {
+  local audio_dir="${1:-$(get_audio_dir)}"
+  local threshold_mb="${2:-15}"
+  local threshold_bytes=$((threshold_mb * 1048576))
+
+  if [[ ! -d "$audio_dir" ]]; then
+    echo "0"
+    return
+  fi
+
+  local current_size=$(calculate_tts_size_bytes "$audio_dir")
+
+  if [[ $current_size -le $threshold_bytes ]]; then
+    echo "0"
+    return
+  fi
+
+  # SAFETY CHECK: Skip cleanup if any TTS files have active write locks
+  # Check for .lock files that indicate in-progress TTS generation
+  local lock_count=$(find "$audio_dir" -maxdepth 1 -name "tts-*.lock" -type f 2>/dev/null | wc -l)
+  if [[ $lock_count -gt 0 ]]; then
+    # Active TTS generation in progress, skip cleanup to avoid race condition
+    return 0
+  fi
+
+  local files_deleted=0
+  local current_size_bytes=$current_size
+
+  # Delete oldest files until under threshold
+  # IMPORTANT: Only delete auto-generated TTS files, NOT project assets like welcome-multivoice-final.wav
+  while [[ $current_size_bytes -gt $threshold_bytes ]]; do
+    # Find the oldest file (only tts-processed-* and tts-padded-* files, not other project assets)
+    local oldest_file=$(find "$audio_dir" -maxdepth 1 -type f \( \
+      -name "tts-processed-*.wav" -o \
+      -name "tts-processed-*.mp3" -o \
+      -name "tts-padded-*.mp3" -o \
+      -name "tts-padded-*.wav" \
+    \) -printf '%T+ %p\n' 2>/dev/null | sort | head -1 | cut -d' ' -f2-)
+
+    if [[ -z "$oldest_file" ]]; then
+      break
+    fi
+
+    # Get file size and delete it
+    local file_size=$(stat -c%s "$oldest_file" 2>/dev/null || stat -f%z "$oldest_file" 2>/dev/null || echo "0")
+    rm -f "$oldest_file" 2>/dev/null || true
+    current_size_bytes=$((current_size_bytes - file_size))
+    files_deleted=$((files_deleted + 1))
+  done
+
+  echo "$files_deleted"
+}
+
+# Clean all TTS audio files and report stats
+# Args: $1 = audio_dir (optional, defaults to get_audio_dir)
+# Returns: Formatted output with cleanup stats
+clean_all_tts_files() {
+  local audio_dir="${1:-$(get_audio_dir)}"
+
+  # Color codes
+  local RED='\033[0;31m'
+  local GREEN='\033[0;32m'
+  local YELLOW='\033[1;33m'
+  local BLUE='\033[0;34m'
+  local NC='\033[0m' # No Color
+
+  # Get stats before cleanup
+  local count_before=$(count_tts_files "$audio_dir")
+  local size_before=$(calculate_tts_size_bytes "$audio_dir")
+  local human_before=$(bytes_to_human "$size_before")
+
+  if [[ $count_before -eq 0 ]]; then
+    echo -e "${GREEN}✅ Cache is already clean! No TTS files found.${NC}"
+    return
+  fi
+
+  # Delete auto-generated TTS files only (preserve project assets like welcome-multivoice-final.wav)
+  find "$audio_dir" -maxdepth 1 -type f \( \
+    -name "tts-processed-*.wav" -o \
+    -name "tts-processed-*.mp3" -o \
+    -name "tts-padded-*.mp3" -o \
+    -name "tts-padded-*.wav" \
+  \) -delete 2>/dev/null || true
+
+  # Also delete BMAD party mode recordings if they exist
+  if [[ -d "$audio_dir/bmad-party-mode-recordings" ]]; then
+    rm -rf "$audio_dir/bmad-party-mode-recordings" 2>/dev/null || true
+  fi
+
+  # Get stats after cleanup
+  local count_after=$(count_tts_files "$audio_dir")
+  local size_after=$(calculate_tts_size_bytes "$audio_dir")
+  local human_after=$(bytes_to_human "$size_after")
+  local freed=$((size_before - size_after))
+  local human_freed=$(bytes_to_human "$freed")
+
+  echo -e "${GREEN}✅ Cleanup complete!${NC}"
+  echo "  • Files deleted: ${YELLOW}$count_before${NC}"
+  echo "  • Space freed: ${YELLOW}$human_freed${NC}"
+  echo "  • Before: $human_before | After: $human_after"
+}

package/.claude/hooks/clawdbot-receiver-SECURE.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/clawdbot-receiver.sh (SECURITY-HARDENED VERSION)
+#
+# AgentVibes Clawdbot Receiver - SSH-Remote TTS with Agent Support and Intro Messages
+# Receives base64-encoded text, voice, agent name, and optional intro from remote Clawdbot instances
+# Calls AgentVibes play-tts-enhanced.sh to apply agent-specific audio effects
+#
+# SECURITY ENHANCEMENTS:
+# - Voice name whitelist validation
+# - Agent name format validation (alphanumeric only)
+# - Length limits on decoded content
+# - Safe HOME directory handling
+#
+# Usage (called via SSH from remote):
+#   clawdbot-receiver.sh <base64_text> <voice> <base64_agent_name> [base64_intro]
+#
+# Copyright (c) 2025 Paul Preibisch
+# Licensed under the Apache License, Version 2.0
+#
+
+set -euo pipefail
+
+ENCODED_TEXT="${1:-}"
+VOICE="${2:-en_US-lessac-medium}"
+ENCODED_AGENT="${3:-}"
+ENCODED_INTRO="${4:-}"
+
+# SECURITY: Whitelist of allowed voice names
+ALLOWED_VOICES="en_US-amy-medium|en_US-lessac-medium|es_ES-mls_9972-low|es_ES-davefx-medium|en_US-joe-medium"
+
+# Validate inputs
+if [[ -z "$ENCODED_TEXT" ]]; then
+  echo "❌ No encoded text provided" >&2
+  echo "Usage: $0 <base64_text> <voice> <base64_agent_name> [base64_intro]" >&2
+  exit 1
+fi
+
+# SECURITY: Validate VOICE parameter against whitelist
+if ! [[ "$VOICE" =~ ^($ALLOWED_VOICES)$ ]]; then
+  echo "❌ Invalid voice name: $VOICE" >&2
+  echo "Allowed voices: $(echo "$ALLOWED_VOICES" | tr '|' ', ')" >&2
+  exit 1
+fi
+
+# SECURITY: Decode base64 safely
+# This prevents command injection from malicious text
+DECODED_TEXT=$(echo -n "$ENCODED_TEXT" | base64 -d 2>/dev/null) || {
+  echo "❌ Failed to decode text (invalid base64)" >&2
+  exit 1
+}
+
+# SECURITY: Enforce length limit on decoded text (10KB max)
+if [[ ${#DECODED_TEXT} -gt 10000 ]]; then
+  echo "❌ Decoded text too long (${#DECODED_TEXT} chars, max 10000)" >&2
+  exit 1
+fi
+
+DECODED_AGENT="default"
+if [[ -n "$ENCODED_AGENT" ]]; then
+  DECODED_AGENT=$(echo -n "$ENCODED_AGENT" | base64 -d 2>/dev/null) || DECODED_AGENT="default"
+  
+  # SECURITY: Validate agent name format (alphanumeric, dash, underscore only)
+  if ! [[ "$DECODED_AGENT" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    echo "⚠️  Invalid agent name format, using 'default'" >&2
+    DECODED_AGENT="default"
+  fi
+  
+  # SECURITY: Enforce length limit on agent name
+  if [[ ${#DECODED_AGENT} -gt 50 ]]; then
+    echo "⚠️  Agent name too long, using 'default'" >&2
+    DECODED_AGENT="default"
+  fi
+fi
+
+# Decode and prepend intro if provided
+DECODED_INTRO=""
+if [[ -n "$ENCODED_INTRO" ]]; then
+  DECODED_INTRO=$(echo -n "$ENCODED_INTRO" | base64 -d 2>/dev/null) || DECODED_INTRO=""
+  
+  # SECURITY: Enforce length limit on intro message
+  if [[ ${#DECODED_INTRO} -gt 200 ]]; then
+    echo "⚠️  Intro message too long, truncating" >&2
+    DECODED_INTRO="${DECODED_INTRO:0:200}"
+  fi
+fi
+
+# Prepend intro to text if configured
+if [[ -n "$DECODED_INTRO" ]]; then
+  DECODED_TEXT="${DECODED_INTRO} ${DECODED_TEXT}"
+fi
+
+# Find AgentVibes installation
+# SECURITY: Validate HOME is set and use absolute paths
+if [[ -z "${HOME:-}" ]]; then
+  echo "❌ HOME environment variable not set" >&2
+  exit 1
+fi
+
+# Priority: 1. ~/agentvibes, 2. ~/AgentVibes-dev, 3. current directory
+AGENTVIBES_ROOT=""
+if [[ -f "$HOME/agentvibes/.claude/hooks/play-tts-enhanced.sh" ]]; then
+  AGENTVIBES_ROOT="$HOME/agentvibes"
+elif [[ -f "$HOME/AgentVibes-dev/.claude/hooks/play-tts-enhanced.sh" ]]; then
+  AGENTVIBES_ROOT="$HOME/AgentVibes-dev"
+elif [[ -f ".claude/hooks/play-tts-enhanced.sh" ]]; then
+  AGENTVIBES_ROOT="$(pwd)"
+else
+  echo "❌ AgentVibes not found" >&2
+  echo "💡 Install AgentVibes at ~/agentvibes/ or ~/AgentVibes-dev/" >&2
+  exit 1
+fi
+
+# SECURITY: Validate AgentVibes root is a directory
+if [[ ! -d "$AGENTVIBES_ROOT" ]]; then
+  echo "❌ AgentVibes root is not a directory: $AGENTVIBES_ROOT" >&2
+  exit 1
+fi
+
+echo "🎤 Voice: $VOICE | Agent: $DECODED_AGENT | Vol: 30% | Effects: default" >&2
+
+# Call AgentVibes play-tts-enhanced.sh with agent name for audio-effects.cfg lookup
+# SECURITY: Use absolute path and proper quoting
+cd "$AGENTVIBES_ROOT" && \
+  bash .claude/hooks/play-tts-enhanced.sh "$DECODED_TEXT" "$DECODED_AGENT" "$VOICE" 2>&1 || {
+  # Fallback to standard play-tts if enhanced fails
+  echo "⚠️  Enhanced TTS failed, using standard TTS" >&2
+  bash .claude/hooks/play-tts.sh "$DECODED_TEXT" "$VOICE" 2>&1
+}
+
+exit 0

package/.claude/hooks/clawdbot-receiver.sh

@@ -2,14 +2,20 @@
 #
 # File: .claude/hooks/clawdbot-receiver.sh
 #
-# AgentVibes Clawdbot Receiver - SSH-Remote TTS with Agent Support
-# Receives base64-encoded text, voice, and agent name from remote Clawdbot instances
-# Calls AgentVibes play-tts-enhanced.sh to apply agent-specific audio effects
+# AgentVibes Clawdbot Receiver - SSH-Remote TTS with Agent Support and Intro Messages
+# Receives base64-encoded text, voice, agent name, and optional intro from remote Clawdbot instances
 #
 # Usage (called via SSH from remote):
-#   clawdbot-receiver.sh <base64_text> <voice> <base64_agent_name>
+#   clawdbot-receiver.sh <base64_text> <voice> <base64_agent_name> [base64_intro]
 #
-# Installed at: ~/.termux/agentvibes-play.sh or ~/.agentvibes/play-remote.sh
+# Parameters:
+#   base64_text       - The main TTS text (base64 encoded)
+#   voice             - Piper voice name (e.g., en_US-amy-medium)
+#   base64_agent_name - Agent name for audio effects lookup (base64 encoded)
+#   base64_intro      - Optional intro message to prepend (base64 encoded)
+#                       e.g., "Orion ClawdBot here." or "Samuel, your assistant."
+#
+# The intro is prepended to the text: "${INTRO} ${TEXT}"
 #
 # Copyright (c) 2025 Paul Preibisch
 # Licensed under the Apache License, Version 2.0
@@ -20,16 +26,16 @@ set -euo pipefail
 ENCODED_TEXT="${1:-}"
 VOICE="${2:-en_US-lessac-medium}"
 ENCODED_AGENT="${3:-}"
+ENCODED_INTRO="${4:-}"
 
 # Validate inputs
 if [[ -z "$ENCODED_TEXT" ]]; then
   echo "❌ No encoded text provided" >&2
-  echo "Usage: $0 <base64_text> <voice> <base64_agent_name>" >&2
+  echo "Usage: $0 <base64_text> <voice> <base64_agent_name> [base64_intro]" >&2
   exit 1
 fi
 
 # SECURITY: Decode base64 safely
-# This prevents command injection from malicious text
 DECODED_TEXT=$(echo -n "$ENCODED_TEXT" | base64 -d 2>/dev/null) || {
   echo "❌ Failed to decode text (invalid base64)" >&2
   exit 1
@@ -40,8 +46,18 @@ if [[ -n "$ENCODED_AGENT" ]]; then
   DECODED_AGENT=$(echo -n "$ENCODED_AGENT" | base64 -d 2>/dev/null) || DECODED_AGENT="default"
 fi
 
+# Decode and prepend intro if provided
+DECODED_INTRO=""
+if [[ -n "$ENCODED_INTRO" ]]; then
+  DECODED_INTRO=$(echo -n "$ENCODED_INTRO" | base64 -d 2>/dev/null) || DECODED_INTRO=""
+fi
+
+# Prepend intro to text if configured
+if [[ -n "$DECODED_INTRO" ]]; then
+  DECODED_TEXT="${DECODED_INTRO} ${DECODED_TEXT}"
+fi
+
 # Find AgentVibes installation
-# Priority: 1. ~/agentvibes, 2. ~/AgentVibes-dev, 3. current directory
 AGENTVIBES_ROOT=""
 if [[ -f "$HOME/agentvibes/.claude/hooks/play-tts-enhanced.sh" ]]; then
   AGENTVIBES_ROOT="$HOME/agentvibes"
@@ -55,12 +71,11 @@ else
   exit 1
 fi
 
-echo "🎤 Agent: $DECODED_AGENT | Voice: $VOICE" >&2
+echo "🎤 Voice: $VOICE | Agent: $DECODED_AGENT" >&2
 
-# Call AgentVibes play-tts-enhanced.sh with agent name for audio-effects.cfg lookup
-cd "$AGENTVIBES_ROOT" && \
-  bash .claude/hooks/play-tts-enhanced.sh "$DECODED_TEXT" "$DECODED_AGENT" "$VOICE" 2>&1 || {
-  # Fallback to standard play-tts if enhanced fails
+# Play TTS directly (lock removed temporarily for testing)
+cd "$AGENTVIBES_ROOT"
+bash .claude/hooks/play-tts-enhanced.sh "$DECODED_TEXT" "$DECODED_AGENT" "$VOICE" 2>&1 || {
   echo "⚠️  Enhanced TTS failed, using standard TTS" >&2
   bash .claude/hooks/play-tts.sh "$DECODED_TEXT" "$VOICE" 2>&1
 }

package/.claude/hooks/clean-audio-cache.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Non-Interactive TTS Audio Cache Cleanup
+# Used by /agent-vibes:clean skill and MCP clean_audio_cache tool
+
+set -euo pipefail
+
+# Source audio cache utilities
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/audio-cache-utils.sh"
+
+# Colors
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🧹 AgentVibes Cache Cleanup (Non-Interactive)${NC}"
+echo ""
+
+# Get audio directory and perform cleanup
+AUDIO_DIR=$(get_audio_dir)
+clean_all_tts_files "$AUDIO_DIR"
+
+echo ""

package/.claude/hooks/piper-download-voices.sh

@@ -40,6 +40,9 @@
 # @related piper-voice-manager.sh, piper-installer.sh
 #
 
+# REQUIRED: Bash strict mode for security and reliability (CLAUDE.md)
+set -euo pipefail
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/piper-voice-manager.sh"
 
@@ -60,9 +63,8 @@ COMMON_VOICES=(
   "en_US-kathleen-low"       # Clear female (13MB) - BMAD: Paige (tech-writer)
   "en_US-kusal-medium"       # Male voice (13MB) - BMAD: Saif (frame-expert)
   "en_US-kristin-medium"     # Female voice (13MB) - BMAD: Sally (ux-designer)
-  "en_US-libritts_r-high"    # Premium male (57MB) - BMAD: BMad Master
+  "en_US-libritts_r-medium"  # Premium male (57MB) - BMAD: BMad Master (NOTE: Changed from -high to -medium, -high doesn't exist)
   "en_US-libritts-high"      # Premium quality (57MB)
-  "16Speakers"               # Multi-speaker: 12 US + 4 UK voices (77MB) - REQUIRED for BMAD agents
 )
 
 echo "🎙️  Piper Voice Model Downloader"
@@ -74,15 +76,15 @@ echo ""
 
 # Check if piper is installed
 if ! command -v piper &> /dev/null; then
-  echo "❌ Error: Piper TTS not installed"
-  echo "Install with: pipx install piper-tts"
+  echo "❌ Error: Piper TTS not installed" >&2
+  echo "Install with: pipx install piper-tts" >&2
   exit 1
 fi
 
 # Get storage directory
 VOICE_DIR=$(get_voice_storage_dir)
 
-echo "📂 Storage location: $VOICE_DIR"
+echo "📂 Storage location: \"$VOICE_DIR\""
 echo ""
 
 # Count already downloaded
@@ -100,8 +102,8 @@ for voice in "${COMMON_VOICES[@]}"; do
 done
 
 echo "📊 Status:"
-echo "   Already downloaded: $ALREADY_DOWNLOADED voice(s)"
-echo "   Need to download: ${#NEED_DOWNLOAD[@]} voice(s)"
+echo "   Already downloaded: \"$ALREADY_DOWNLOADED\" voice(s)"
+echo "   Need to download: \"${#NEED_DOWNLOAD[@]}\" voice(s)"
 echo ""
 
 # Show already downloaded voices
@@ -129,8 +131,14 @@ if [[ "$AUTO_YES" == "false" ]]; then
   read -p "Download ${#NEED_DOWNLOAD[@]} voice model(s)? [Y/n]: " -n 1 -r
   echo
 
-  if [[ ! $REPLY =~ ^[Yy]$ ]] && [[ -n $REPLY ]]; then
-    echo "❌ Download cancelled"
+  # Validate input is Y, y, N, n, or empty (default to Y)
+  if [[ ! $REPLY =~ ^[YyNn]?$ ]]; then
+    echo "❌ Invalid input. Please enter Y or N." >&2
+    exit 1
+  fi
+
+  if [[ $REPLY =~ ^[Nn]$ ]]; then
+    echo "❌ Download cancelled" >&2
     exit 0
   fi
 else
@@ -148,8 +156,8 @@ for voice in "${NEED_DOWNLOAD[@]}"; do
 
   if download_voice "$voice"; then
     ((DOWNLOADED++))
-    local voice_path="$VOICE_DIR/${voice}.onnx"
-    local file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
+    voice_path="$VOICE_DIR/${voice}.onnx"
+    file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
     echo "   ✓ Downloaded: $voice"
     echo "   📁 Path: $voice_path"
     echo "   📦 Size: $file_size"
@@ -165,8 +173,8 @@ echo "📊 Download Summary:"
 echo ""
 echo "Installed voices:"
 for voice in "${ALREADY_DOWNLOADED_LIST[@]}"; do
-  local voice_path="$VOICE_DIR/${voice}.onnx"
-  local file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
+  voice_path="$VOICE_DIR/${voice}.onnx"
+  file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
   echo "   ✓ $voice ($file_size)"
   echo "     $voice_path"
 done
@@ -175,9 +183,9 @@ if [[ $DOWNLOADED -gt 0 ]]; then
   echo ""
   echo "Just downloaded:"
   for voice in "${NEED_DOWNLOAD[@]}"; do
-    local voice_path="$VOICE_DIR/${voice}.onnx"
+    voice_path="$VOICE_DIR/${voice}.onnx"
     if [[ -f "$voice_path" ]]; then
-      local file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
+      file_size=$(du -h "$voice_path" 2>/dev/null | cut -f1)
       echo "   ✓ $voice ($file_size)"
       echo "     $voice_path"
     fi
@@ -188,7 +196,7 @@ if [[ $FAILED -gt 0 ]]; then
   echo ""
   echo "Failed downloads:"
   for voice in "${NEED_DOWNLOAD[@]}"; do
-    local voice_path="$VOICE_DIR/${voice}.onnx"
+    voice_path="$VOICE_DIR/${voice}.onnx"
     if [[ ! -f "$voice_path" ]]; then
       echo "   ✗ $voice"
     fi
@@ -207,6 +215,11 @@ if [[ $DOWNLOADED -gt 0 ]]; then
   echo "  /agent-vibes:preview"
 fi
 
-# Always exit successfully even if some downloads failed
-# (individual failures are tracked in FAILED counter)
+# Exit with error code if any downloads failed (Unix convention)
+if [[ $FAILED -gt 0 ]]; then
+  echo "" >&2
+  echo "⚠️  Warning: $FAILED download(s) failed. Some voices may not be available." >&2
+  exit 1
+fi
+
 exit 0