agentvibes 5.11.2 → 5.12.0

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

@@ -1,6 +1,6 @@
 
 llm:default|light||0.15|en_US-lessac-high||piper
-llm:claude-code|light|agent_vibes_chillwave_v2_loop.mp3|0.05||Agent Vibes local here|kokoro
+llm:claude-code|light|agent_vibes_chillwave_v2_loop.mp3|0.05|en_US-amy-medium|Agent Vibes local here|piper
 llm:copilot|light|agent_vibes_bossa_nova_v2_loop.mp3|0.15|en_US-libritts-high::Anna-11|Copilot here|piper
 llm:codex|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Codex here|piper
 llm:hermes|light|agent_vibes_bachata_v1_loop.mp3|0.15|en_US-libritts-high::Leo-8|Hermes here|piper

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

@@ -0,0 +1,7 @@
+
+llm:default|light||0.15|en_US-lessac-high||piper
+llm:claude-code|light|agent_vibes_chillwave_v2_loop.mp3|0.05|af_river|Agent Vibes local here|kokoro
+llm:copilot|light|agent_vibes_bossa_nova_v2_loop.mp3|0.15|en_US-libritts-high::Anna-11|Copilot here|piper
+llm:codex|light|agent_vibes_chillwave_v2_loop.mp3|0.15|en_US-lessac-high|Codex here|piper
+llm:hermes|light|agent_vibes_bachata_v1_loop.mp3|0.15|en_US-libritts-high::Leo-8|Hermes here|piper
+default||agent_vibes_arabic_v2_loop.mp3|0.30

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

@@ -1 +1 @@
-20260625
+20260703

package/.claude/hooks/audio-processor.sh

@@ -577,7 +577,7 @@ main() {
     fi
 
     local used_background=""
-    if is_background_music_enabled && [[ -n "$background_path" ]] && [[ -f "$background_path" ]] && [[ "${bg_volume:-0}" != "0" ]] && [[ "${bg_volume:-0}" != "0.0" ]]; then
+    if [[ "$_bg_allowed" == "true" ]] && [[ -n "$background_path" ]] && [[ -f "$background_path" ]] && [[ "${bg_volume:-0}" != "0" ]] && [[ "${bg_volume:-0}" != "0.0" ]]; then
         local bg_display_name
         if [[ "$background_path" == "$custom_music_path" ]]; then
             bg_display_name="custom music"

package/.claude/hooks/background-music-manager.sh

@@ -33,7 +33,8 @@ ENABLED_FILE="$CONFIG_DIR/background-music-enabled.txt"
 VOLUME_FILE="$CONFIG_DIR/background-music-volume.txt"
 
 # Defaults
-DEFAULT_VOLUME="0.34"
+# TODO(AVI-S8.6): generate this constant from the shared JSON source of truth.
+DEFAULT_VOLUME="0.20"
 
 # Ensure config directory exists
 mkdir -p "$CONFIG_DIR"

package/.claude/hooks/bmad-speak-enhanced.sh

@@ -134,29 +134,44 @@ TEMP_FILE="$AUDIO_DIR/tts-enhanced-$(date +%s)-$$.wav"
 # Determine voice and generate audio
 if [[ -n "$AGENT_VOICE" ]]; then
     echo "🎤 Agent: $AGENT_FOR_EFFECTS | Voice: $AGENT_VOICE"
-    # Call piper directly to generate audio without playback
-    "$SCRIPT_DIR/play-tts-piper.sh" "$FULL_TEXT" "$AGENT_VOICE" > /dev/null 2>&1 &
-    PIPER_PID=$!
-
-    # Wait for piper to generate (it outputs the file path)
-    wait $PIPER_PID 2>/dev/null || true
-
-    # Find the most recent TTS file
-    GENERATED_FILE=$(ls -t "$AUDIO_DIR"/tts-padded-*.wav 2>/dev/null | head -1)
-
-    if [[ -n "$GENERATED_FILE" ]] && [[ -f "$GENERATED_FILE" ]]; then
-        # Apply audio effects and background mixing
-        if [[ -f "$SCRIPT_DIR/audio-processor.sh" ]]; then
-            PROCESSED_FILE="$AUDIO_DIR/tts-enhanced-processed-$(date +%s)-$$.wav"
-            "$SCRIPT_DIR/audio-processor.sh" "$GENERATED_FILE" "$AGENT_FOR_EFFECTS" "$PROCESSED_FILE" 2>/dev/null || {
-                # Fallback to original if processing fails
-                PROCESSED_FILE="$GENERATED_FILE"
-            }
 
-            # Play the processed file
-            if [[ -f "$PROCESSED_FILE" ]]; then
-                (mpv "$PROCESSED_FILE" || aplay "$PROCESSED_FILE" || paplay "$PROCESSED_FILE") >/dev/null 2>&1 &
-            fi
+    # Synthesize WITHOUT playback (this pipeline plays the post-processed file
+    # itself), CAPTURING the provider's stdout so we can read its AV_OUTPUT:
+    # sentinel — the EXACT absolute path piper wrote for THIS invocation.
+    #
+    # We deliberately do NOT scan the audio directory for the newest file (the
+    # banned most-recent-file / directory-listing heuristic): it races in party
+    # mode (grabs another agent's audio) and masks synthesis failures. See Story
+    # AVI-S8.5 (R6/R7) and memory: feedback_no_most_recent_file_heuristic.
+    PIPER_STDOUT=""
+    # Skip piper's internal (default-row) audio-processor pass: we run our OWN
+    # per-agent audio-processor pass below, so letting piper process first would
+    # double the effects/background-music (double reverb, overlapping tracks).
+    if ! PIPER_STDOUT=$(AGENTVIBES_NO_PLAYBACK=true AGENTVIBES_SKIP_INTERNAL_PROCESSOR=1 "$SCRIPT_DIR/play-tts-piper.sh" "$FULL_TEXT" "$AGENT_VOICE" 2>/dev/null); then
+        echo "❌ bmad-speak: piper synthesis failed for agent '$AGENT_FOR_EFFECTS'" >&2
+        exit 1
+    fi
+
+    # Capture the exact output path from the AV_OUTPUT: sentinel. FAIL LOUD if it
+    # is absent — never fall back to a directory listing.
+    GENERATED_FILE=$(printf '%s\n' "$PIPER_STDOUT" | sed -n 's/^AV_OUTPUT://p' | tail -1)
+
+    if [[ -z "$GENERATED_FILE" ]] || [[ ! -f "$GENERATED_FILE" ]]; then
+        echo "❌ bmad-speak: no AV_OUTPUT sentinel from play-tts-piper.sh — refusing to guess the output file (agent '$AGENT_FOR_EFFECTS')" >&2
+        exit 1
+    fi
+
+    # Apply audio effects and background mixing
+    if [[ -f "$SCRIPT_DIR/audio-processor.sh" ]]; then
+        PROCESSED_FILE="$AUDIO_DIR/tts-enhanced-processed-$(date +%s)-$$.wav"
+        "$SCRIPT_DIR/audio-processor.sh" "$GENERATED_FILE" "$AGENT_FOR_EFFECTS" "$PROCESSED_FILE" 2>/dev/null || {
+            # Fallback to original if processing fails
+            PROCESSED_FILE="$GENERATED_FILE"
+        }
+
+        # Play the processed file
+        if [[ -f "$PROCESSED_FILE" ]]; then
+            (mpv "$PROCESSED_FILE" || aplay "$PROCESSED_FILE" || paplay "$PROCESSED_FILE") >/dev/null 2>&1 &
         fi
     fi
 else

package/.claude/hooks/bmad-speak.sh

@@ -104,7 +104,7 @@ read_agent_profile_all() {
 
   # Validate agent_id format (prevent injection)
   if [[ ! "$agent_id" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    echo "|||||"
+    echo "||||||"
     return
   fi
 
@@ -173,13 +173,24 @@ map_to_agent_id() {
 
 AGENT_ID=$(map_to_agent_id "$AGENT_NAME_OR_ID")
 
-# Get agent's voice and intro text
-AGENT_VOICE=""
-AGENT_INTRO=""
-if [[ -n "$AGENT_ID" ]] && [[ -f "$SCRIPT_DIR/bmad-voice-manager.sh" ]]; then
-  AGENT_VOICE=$(cd "$PROJECT_ROOT" && "$SCRIPT_DIR/bmad-voice-manager.sh" get-voice "$AGENT_ID" 2>/dev/null)
-  AGENT_INTRO=$(cd "$PROJECT_ROOT" && "$SCRIPT_DIR/bmad-voice-manager.sh" get-intro "$AGENT_ID" 2>/dev/null)
-fi
+# ---------------------------------------------------------------------------
+# Populate the per-agent profile (voice/pretext/reverb/personality/music) from
+# bmad-voice-map.json. THIS is the population step that a botched merge
+# (610af0f2) dropped, leaving $PROFILE_VOICE et al. below referenced-but-never-
+# -assigned — a fatal "unbound variable" under `set -u`. read_agent_profile_all()
+# already existed (defined above) but was never called; wire it in here.
+# Always initialize (even to "") so downstream references never crash, and a
+# missing/unknown agent just falls through to normal TTS below.
+PROFILE_VOICE=""
+PROFILE_PRETEXT=""
+PROFILE_REVERB=""
+PROFILE_PERSONALITY=""
+PROFILE_MUSIC_TRACK=""
+PROFILE_MUSIC_VOLUME=""
+PROFILE_MUSIC_ENABLED=""
+_PROFILE_ALL="$(read_agent_profile_all "${AGENT_ID:-}")"
+IFS='|' read -r PROFILE_VOICE PROFILE_PRETEXT PROFILE_REVERB PROFILE_PERSONALITY \
+  PROFILE_MUSIC_TRACK PROFILE_MUSIC_VOLUME PROFILE_MUSIC_ENABLED <<< "$_PROFILE_ALL"
 
 # Read global background music volume as fallback (stored as 0.0-1.0, convert to 0-100 integer)
 _BG_VOL_FILE="${CLAUDE_PROJECT_DIR:-$PROJECT_ROOT}/.claude/config/background-music-volume.txt"
@@ -271,6 +282,13 @@ trap 'rmdir "$SPEECH_LOCK" 2>/dev/null' EXIT
 # Speak with agent's voice, passing the temp profile path as arg 3 so
 # play-tts-piper.sh → audio-processor.sh can read per-agent music settings
 # without any env vars (safe for concurrent multi-project use).
+#
+# Declare voice provenance so the resolver never demotes a BMAD agent's own voice
+# to the per-LLM/default row (F-1). This must be set independently of whether a
+# TEMP_PROFILE file was created: a voice-only agent (no reverb/personality/music)
+# has an empty TEMP_PROFILE, so the arg-3 heuristic in play-tts.sh alone would
+# miss it. AGENT_VOICE is an agent-profile voice, always.
+export AGENTVIBES_VOICE_SOURCE="agent-profile"
 if [[ -n "$AGENT_VOICE" ]]; then
   bash "$SCRIPT_DIR/play-tts.sh" "$FULL_TEXT" "$AGENT_VOICE" "$TEMP_PROFILE"
 else

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

@@ -99,7 +99,7 @@ echo "📱 Sending to $SSH_HOST for local playback..." >&2
 SSH_ARGS=()
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
 # 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.
+# Host alias port (e.g. my-laptop -> 2222). 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

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

@@ -94,7 +94,10 @@ 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.
+# Still emit the AV_OUTPUT sentinel so consumers get the exact intended path
+# (Story AVI-S8.5, R6): the path is machine-parseable regardless of playback.
 if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
+  printf 'AV_OUTPUT:%s\n' "$TEMP_WAV"
   trap '' EXIT
   exit 0
 fi
@@ -110,6 +113,12 @@ if [[ ! -f "$TEMP_WAV" || ! -s "$TEMP_WAV" ]]; then
   exit 3
 fi
 
+# AV_OUTPUT sentinel (Story AVI-S8.5, R6/R7): emit the EXACT absolute path of the
+# wav this invocation produced, on its own machine-parseable stdout line. Consumers
+# capture THIS path — never a directory listing (memory:
+# feedback_no_most_recent_file_heuristic).
+printf 'AV_OUTPUT:%s\n' "$TEMP_WAV"
+
 # ---------------------------------------------------------------------------
 # Play audio — try players in order (WAV-capable)
 # Skip playback in test mode or no-playback mode (matches the Piper provider).

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

@@ -474,7 +474,11 @@ fi
 # @returns Updates $TEMP_FILE to processed version, sets $BACKGROUND_MUSIC if used
 # @sideeffects Applies audio effects and background music
 BACKGROUND_MUSIC=""
-if [[ -f "$SCRIPT_DIR/audio-processor.sh" ]]; then
+# AGENTVIBES_SKIP_INTERNAL_PROCESSOR=1 lets a caller that will run its OWN
+# audio-processor pass (e.g. bmad-speak-enhanced.sh applying per-agent effects)
+# skip this generic default-row pass — otherwise effects/background-music get
+# applied twice (double reverb / overlapping music).
+if [[ "${AGENTVIBES_SKIP_INTERNAL_PROCESSOR:-}" != "1" && -f "$SCRIPT_DIR/audio-processor.sh" ]]; then
   _tmp=$(mktemp "$AUDIO_DIR/tts-processed-XXXXXX"); PROCESSED_FILE="${_tmp}.wav"; mv "$_tmp" "$PROCESSED_FILE"
   _CLEANUP_FILES+=("$PROCESSED_FILE")
   # audio-processor.sh returns: FILE_PATH|BACKGROUND_FILE
@@ -630,6 +634,14 @@ fi
 # Display with file count (now showing accurate post-cleanup size)
 echo -e "${WHITE}💾 Saved to:${NC} ${CYAN}$TEMP_FILE${NC} ${YELLOW}$FILE_COUNT${NC} ${WHITE}🗄️${NC} ${CACHE_COLOR}$SIZE_HUMAN${NC} ${WHITE}🧹${NC}${GOLD}[${AUTO_CLEAN_THRESHOLD}mb]${NC}"
 
+# AV_OUTPUT sentinel (Story AVI-S8.5, R6/R7): emit the EXACT absolute path of the
+# wav this invocation produced, on its own machine-parseable stdout line. Consumers
+# (e.g. bmad-speak-enhanced.sh) capture THIS path — never `ls -t | head -1`, which
+# races in party mode and masks synthesis failures (memory:
+# feedback_no_most_recent_file_heuristic). Additive: the human "Saved to:" line
+# above is intact for the MCP server's loose parser.
+printf 'AV_OUTPUT:%s\n' "$TEMP_FILE"
+
 if [[ -n "$BACKGROUND_MUSIC" ]]; then
   # Extract just the filename to save space
   MUSIC_FILENAME=$(basename "$BACKGROUND_MUSIC")

package/.claude/hooks/play-tts-ssh-remote.sh

@@ -34,8 +34,32 @@ fi
 # Default to "default" so remote always has an LLM key to look up
 LLM_NAME="${LLM_NAME:-default}"
 
-# Validate required input
-if [[ -z "$TEXT" ]]; then
+# Music-only preview mode: AGENTVIBES_MUSIC_ONLY=<track.mp3> tells the receiver to
+# play a standalone background-music track (no speech). Used by the Music tab's
+# remote preview so a track can be auditioned on the receiver. In this mode empty
+# TEXT is allowed and the track name is forwarded as the "music" field with
+# kind=music; the receiver resolves the file from its own ~/.claude/audio/tracks/.
+PAYLOAD_KIND="speak"
+MUSIC_ONLY_TRACK=""
+if [[ -n "${AGENTVIBES_MUSIC_STOP:-}" ]]; then
+  # Stop whatever music preview is currently playing on the receiver.
+  PAYLOAD_KIND="music-stop"
+elif [[ -n "${AGENTVIBES_MUSIC_ONLY:-}" ]]; then
+  # Only a bare .mp3 filename is allowed (no path separators, no leading dash) —
+  # the receiver resolves it against its own tracks dir, so reject path-like input.
+  if [[ "$AGENTVIBES_MUSIC_ONLY" =~ ^[A-Za-z0-9._][A-Za-z0-9._-]*\.mp3$ ]]; then
+    PAYLOAD_KIND="music"
+    MUSIC_ONLY_TRACK="$AGENTVIBES_MUSIC_ONLY"
+  else
+    echo "Invalid music track name: $AGENTVIBES_MUSIC_ONLY" >&2
+    exit 1
+  fi
+fi
+
+# Validate required input (music / music-stop modes carry no speech text)
+if [[ "$PAYLOAD_KIND" == "music" || "$PAYLOAD_KIND" == "music-stop" ]]; then
+  TEXT=""   # no speech in a music preview / stop
+elif [[ -z "$TEXT" ]]; then
   echo "Usage: $0 <text> [voice] [agent_name]" >&2
   exit 1
 fi
@@ -46,6 +70,9 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
 # Derive project name from directory
 PROJECT_NAME=$(basename "$PROJECT_ROOT")
+# Absolute path, forwarded so the receiver-side avatar can show/learn the real
+# remote folder (mirrors the local forward-to-avatar.sh's projectPath field).
+PROJECT_PATH="$PROJECT_ROOT"
 
 # ---------------------------------------------------------------------------
 # Get SSH connection details from config
@@ -149,7 +176,8 @@ fi
 
 SOX_EFFECTS=""
 BG_FILE=""
-BG_VOLUME="0.10"
+# TODO(AVI-S8.6): generate this constant from the shared JSON source of truth.
+BG_VOLUME="0.20"
 
 # Use CLAUDE_PROJECT_DIR (injected via --project-dir by play-tts.sh) so the
 # agent-name / default row is read from the user's project, not the package.
@@ -280,6 +308,76 @@ case "${PROVIDER:-}" in
   *) PROVIDER="piper" ;;
 esac
 
+# ---------------------------------------------------------------------------
+# Resolve the project-level .claude dir the way the local managers do:
+# CLAUDE_PROJECT_DIR (the real user project, injected via --project-dir by
+# play-tts.sh) wins; otherwise fall back to the package PROJECT_ROOT.
+# ---------------------------------------------------------------------------
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "$CLAUDE_PROJECT_DIR/.claude" ]]; then
+  _RESOLVE_PROJECT_DIR="$CLAUDE_PROJECT_DIR"
+else
+  _RESOLVE_PROJECT_DIR="$PROJECT_ROOT"
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve MUTE to forward (map §C 'mute never forwarded on SSH', R17).
+# Mirrors play-tts.sh's 3-level file check exactly:
+#   project-unmute (overrides global) > project-mute > global-mute.
+# The receiver is authoritative and applies a SAFETY-OR:
+#   effective_mute = receiver_local_mute OR forwarded_mute
+# so if EITHER side is muted, playback stays silent. We forward this as a
+# STRING ("true"/"false") — the receiver does a plain string compare, and it
+# keeps the JSON boolean out of python's "True"/"False" capitalization.
+# ---------------------------------------------------------------------------
+_GLOBAL_MUTE_FILE="$HOME/.agentvibes-muted"
+_PROJECT_MUTE_FILE="$_RESOLVE_PROJECT_DIR/.claude/agentvibes-muted"
+_PROJECT_UNMUTE_FILE="$_RESOLVE_PROJECT_DIR/.claude/agentvibes-unmuted"
+MUTE="false"
+if [[ -f "$_PROJECT_UNMUTE_FILE" ]]; then
+  MUTE="false"                       # project explicitly unmuted overrides global
+elif [[ -f "$_PROJECT_MUTE_FILE" ]]; then
+  MUTE="true"
+elif [[ -f "$_GLOBAL_MUTE_FILE" ]]; then
+  MUTE="true"
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve LANGUAGE to forward (map §D 'language | Forward on SSH', R18).
+# Precedence mirrors the local chain (learn-manager.sh / language-manager.sh):
+#   learning-mode target (tts-target-language.txt when tts-learn-mode.txt=="ON")
+#   > tts-language.txt.
+# Forwarded as a DEFAULT only — the receiver stays authoritative and its own
+# language config (if any) wins. language-manager.sh stores tts-language.txt at
+# the .claude/ root; the resolver contract tests use the .claude/config/ subdir,
+# so we accept both. Project scope wins over the global home fallback.
+# ---------------------------------------------------------------------------
+LANGUAGE=""
+for _cdir in "$_RESOLVE_PROJECT_DIR/.claude" "$HOME/.claude"; do
+  # Priority 1: learning-mode target language (only when learn mode is ON).
+  if [[ -z "$LANGUAGE" && -f "$_cdir/tts-learn-mode.txt" ]]; then
+    if [[ "$(cat "$_cdir/tts-learn-mode.txt" 2>/dev/null || true)" == "ON" ]]; then
+      [[ -f "$_cdir/tts-target-language.txt" ]] && \
+        LANGUAGE=$(cat "$_cdir/tts-target-language.txt" 2>/dev/null || true)
+    fi
+  fi
+  # Priority 2: tts-language.txt (root or config/ subdir).
+  if [[ -z "$LANGUAGE" && -f "$_cdir/tts-language.txt" ]]; then
+    LANGUAGE=$(cat "$_cdir/tts-language.txt" 2>/dev/null || true)
+  fi
+  if [[ -z "$LANGUAGE" && -f "$_cdir/config/tts-language.txt" ]]; then
+    LANGUAGE=$(cat "$_cdir/config/tts-language.txt" 2>/dev/null || true)
+  fi
+  [[ -n "$LANGUAGE" ]] && break
+done
+# Trim surrounding whitespace
+LANGUAGE="${LANGUAGE#"${LANGUAGE%%[![:space:]]*}"}"
+LANGUAGE="${LANGUAGE%"${LANGUAGE##*[![:space:]]}"}"
+# SECURITY: only forward a plain language name (letters, spaces, hyphen); jq
+# --arg escapes anyway, but reject odd values rather than propagate them.
+if [[ -n "$LANGUAGE" ]] && [[ ! "$LANGUAGE" =~ ^[a-zA-Z][a-zA-Z\ -]*$ ]]; then
+  LANGUAGE=""
+fi
+
 # ---------------------------------------------------------------------------
 # Build JSON payload
 # ---------------------------------------------------------------------------
@@ -294,22 +392,34 @@ build_json_payload() {
       --arg music "$BG_FILE" \
       --arg volume "$BG_VOLUME" \
       --arg project "$PROJECT_NAME" \
+      --arg projectPath "$PROJECT_PATH" \
       --arg pretext "$PRETEXT" \
       --arg speed "$SPEED" \
       --arg provider "$PROVIDER" \
       --arg llm "$LLM_NAME" \
-      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, pretext: $pretext, speed: $speed, provider: $provider, llm: $llm}'
+      --arg mute "$MUTE" \
+      --arg language "$LANGUAGE" \
+      --arg kind "$PAYLOAD_KIND" \
+      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, projectPath: $projectPath, pretext: $pretext, speed: $speed, provider: $provider, llm: $llm, mute: $mute, language: $language, kind: $kind}'
   else
     # Manual JSON — escape backslashes, quotes, control chars
     local escaped_text
     escaped_text=$(printf '%s' "$TEXT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ' | sed 's/\r//g')
     local escaped_pretext
     escaped_pretext=$(printf '%s' "$PRETEXT" | sed 's/\\/\\\\/g; s/"/\\"/g')
-    printf '{"text":"%s","voice":"%s","effects":"%s","music":"%s","volume":"%s","project":"%s","pretext":"%s","speed":"%s","provider":"%s","llm":"%s"}' \
-      "$escaped_text" "$VOICE" "$SOX_EFFECTS" "$BG_FILE" "$BG_VOLUME" "$PROJECT_NAME" "$escaped_pretext" "$SPEED" "$PROVIDER" "$LLM_NAME"
+    local escaped_project_path
+    escaped_project_path=$(printf '%s' "$PROJECT_PATH" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    printf '{"text":"%s","voice":"%s","effects":"%s","music":"%s","volume":"%s","project":"%s","projectPath":"%s","pretext":"%s","speed":"%s","provider":"%s","llm":"%s","mute":"%s","language":"%s","kind":"%s"}' \
+      "$escaped_text" "$VOICE" "$SOX_EFFECTS" "$BG_FILE" "$BG_VOLUME" "$PROJECT_NAME" "$escaped_project_path" "$escaped_pretext" "$SPEED" "$PROVIDER" "$LLM_NAME" "$MUTE" "$LANGUAGE" "$PAYLOAD_KIND"
   fi
 }
 
+# Music-only preview: force the track as the "music" field (overriding any
+# per-LLM/agent background-music config) so the receiver plays exactly this track.
+if [[ "$PAYLOAD_KIND" == "music" ]]; then
+  BG_FILE="$MUSIC_ONLY_TRACK"
+fi
+
 JSON_PAYLOAD=$(build_json_payload)
 
 # SECURITY: Base64-encode entire payload — safe for SSH transport
@@ -338,7 +448,7 @@ SSH_ARGS=()
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
 # Only pass -p for an explicit, non-default port.  Port 22 is ssh's universal
 # default, so forcing "-p 22" is at best a no-op and at worst overrides the
-# real port of an ~/.ssh/config Host alias (e.g. laptop-win -> Port 45217),
+# real port of an ~/.ssh/config Host alias (e.g. my-laptop -> Port 2222),
 # silently delivering the payload to the wrong port.  Empty or "22" means
 # "use ssh / ~/.ssh/config defaults" -- never force it.
 if [[ -n "$SSH_PORT" && "$SSH_PORT" != "22" ]]; then SSH_ARGS+=(-p "$SSH_PORT"); fi

package/.claude/hooks/play-tts-termux-ssh.sh

@@ -166,7 +166,7 @@ SAFE_TEXT="${TEXT//\'/\'\\\'\'}"
 SSH_ARGS=(-o ConnectTimeout=5)
 [[ -n "$SSH_KEY"  && -f "$SSH_KEY"  ]] && SSH_ARGS+=(-i "$SSH_KEY")
 # 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.
+# Host alias port (e.g. my-laptop -> 2222). Empty/22 => defer to ssh config.
 if [[ -n "$SSH_PORT" && "$SSH_PORT" != "22" ]]; then SSH_ARGS+=(-p "$SSH_PORT"); fi
 
 # Send TTS command to Android device via SSH

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

@@ -145,6 +145,7 @@ unset _POSITIONAL_ARGS
 TEXT="${1:-}"
 VOICE_OVERRIDE="${2:-}"  # Optional: voice name or ID
 AGENT_PROFILE_FILE="${3:-}"  # Optional: path to agent profile file
+_ORIG_EXPLICIT_VOICE="$VOICE_OVERRIDE"  # raw positional voice, before any per-LLM override (fed to the resolver as the explicit voice)
 
 # Security: Validate inputs
 if [[ -z "$TEXT" ]]; then
@@ -244,6 +245,75 @@ if [[ -n "$_PRETEXT" ]]; then
   TEXT="${_PRETEXT}, ${TEXT}"
 fi
 
+# ── Utterance Resolver (AVI-S8.5 Stage 2) ────────────────────────────────────
+# Single source of truth for the voice + engine decision. Resolve the plan once
+# and adopt its voice (per-LLM voice wins over an LLM-echoed override — R2) and,
+# below, its local engine (a kokoro-shaped voice forces the kokoro engine on
+# Linux too — R1, curing the detect_voice_provider silence bug). FAIL-SAFE: if
+# node or the resolver bundle isn't reachable (e.g. an installed ~/.claude that
+# predates the bundle-shipping installer change), PLAN_OK stays empty and the
+# legacy logic below runs unchanged — TTS never breaks on a missing bridge.
+PLAN_OK=""
+_RESOLVER_CLI=""
+# AGENTVIBES_RESOLVER_CLI lets the installer (or tests) point at the resolver
+# bundle when it lives outside the hooks tree — e.g. an installed ~/.claude/hooks
+# whose sibling package dir holds bin/resolve-utterance.js.
+# Candidate order: explicit env override; the installed dedicated bundle dir
+# (has its own package.json so ESM works on every Node version — F-5); the repo
+# layout (dev); a co-located copy.
+for _cand in "${AGENTVIBES_RESOLVER_CLI:-}" \
+             "$SCRIPT_DIR/../agentvibes-resolver/bin/resolve-utterance.js" \
+             "$SCRIPT_DIR/../../bin/resolve-utterance.js" \
+             "$SCRIPT_DIR/resolve-utterance.js"; do
+  [[ -n "$_cand" && -f "$_cand" ]] && { _RESOLVER_CLI="$_cand"; break; }
+done
+if [[ -n "$_RESOLVER_CLI" ]] && command -v node &>/dev/null; then
+  # Voice provenance (F-1): a per-agent profile ($3) is an 'agent-profile' voice
+  # (BMAD party mode — each agent its OWN voice, must not be demoted to the
+  # per-LLM/default voice); a caller may declare provenance via
+  # AGENTVIBES_VOICE_SOURCE (e.g. MCP text_to_speech → 'user-explicit'); the
+  # voice-browser sets 'audition'; otherwise it's an 'llm-echo' (the LLM parroting
+  # back get_config, which the per-LLM row rightly overrides — R2).
+  _vsource="${AGENTVIBES_VOICE_SOURCE:-llm-echo}"
+  # Whitelist the provenance — an unknown value falls back to llm-echo (safe default).
+  case "$_vsource" in
+    llm-echo|user-explicit|agent-profile|translation-target|audition) ;;
+    *) _vsource="llm-echo" ;;
+  esac
+  # A per-agent profile ($3) also implies agent-profile provenance (belt-and-suspenders
+  # with bmad-speak.sh's explicit AGENTVIBES_VOICE_SOURCE export).
+  [[ -n "${AGENT_PROFILE_FILE:-}" && "$_vsource" == "llm-echo" ]] && _vsource="agent-profile"
+  [[ -n "${AGENTVIBES_EFFECTS_PREVIEW:-}" ]] && _vsource="audition"
+  # `timeout 5` caps a wedged bridge so the fail-safe promise ("TTS never breaks
+  # on the bridge") also covers a hung node, not just a missing one.
+  _av_timeout="timeout 5"; command -v timeout &>/dev/null || _av_timeout=""
+  if _plan_sh=$($_av_timeout node "$_RESOLVER_CLI" --format sh \
+        --text "$TEXT" \
+        --llm "$LLM_PROVIDER" \
+        --voice "$_ORIG_EXPLICIT_VOICE" \
+        --voice-source "$_vsource" \
+        --project-dir "${CLAUDE_PROJECT_DIR:-$PROJECT_ROOT}" \
+        --package-root "$PROJECT_ROOT" 2>/dev/null); then
+    # Guard the eval: a malformed OR EMPTY plan must fall back to legacy, never
+    # abort the script mid-run under `set -euo pipefail`. `eval ""` succeeds with
+    # no AV_* vars set, which would falsely set PLAN_OK — so require non-empty
+    # output AND a field that is ALWAYS present in a valid plan. AV_TRANSPORT is
+    # always 'local' or a transport name (never empty), unlike AV_ENGINE which is
+    # legitimately empty on a remote plan (F-7).
+    if [[ -n "$_plan_sh" ]] && eval "$_plan_sh" 2>/dev/null && [[ -n "${AV_TRANSPORT:-}" ]]; then   # AV_* shell-quoted, safe
+      PLAN_OK=1
+      # Adopt the voice into VOICE_OVERRIDE ONLY when it's a real override
+      # (F-2): a plain provider-file voice is left for play-tts-piper.sh's own
+      # file+model+speaker-id resolution (adopting it as an explicit override
+      # skips the multi-speaker lookup and plays speaker 0). Engine coupling (R1)
+      # still applies below regardless.
+      if [[ "${AV_VOICE_IS_OVERRIDE:-false}" == "true" && -n "${AV_VOICE:-}" ]]; then
+        VOICE_OVERRIDE="$AV_VOICE"
+      fi
+    fi
+  fi
+fi
+
 # Source provider manager to get active provider
 source "$SCRIPT_DIR/provider-manager.sh"
 
@@ -259,7 +329,12 @@ case "$ACTIVE_PROVIDER" in
     # Transport — keep it.  The receiver's audio-effects.cfg picks the engine.
     ;;
   *)
-    if [[ -n "$_LLM_ENGINE" ]]; then
+    if [[ "$VOICE_OVERRIDE" =~ ^(af|am|bf|bm|jf|jm|kf|km|zf|zm|ff|fm|hf|hm|if|im|pf|pm|ef|em|nf|nm)_[a-zA-Z0-9]+$ ]]; then
+      # Kokoro-shaped voice override (e.g. af_heart) must win over the LLM row's
+      # engine column, else it is synthesized as a Piper voice, 404s downloading
+      # a model that doesn't exist, and stays silent. (Grafted from master WIP.)
+      ACTIVE_PROVIDER="kokoro"
+    elif [[ -n "$_LLM_ENGINE" ]]; then
       ACTIVE_PROVIDER="$_LLM_ENGINE"
     fi
     ;;
@@ -320,6 +395,17 @@ PYEOF
   fi
 fi
 
+# Adopt the resolver's engine for LOCAL playback (AVI-S8.5 Stage 2): this cures
+# the kokoro/piper voice→engine coupling (R1) and normalizes engine aliases,
+# replacing the detect_voice_provider heuristic below. Transports are left
+# untouched — the plan forwards the voice and the receiver picks its own engine.
+if [[ -n "$PLAN_OK" ]]; then
+  case "$ACTIVE_PROVIDER" in
+    ssh-remote|agentvibes-receiver|termux-ssh) : ;;   # transport — keep it
+    *) [[ -n "${AV_ENGINE:-}" ]] && ACTIVE_PROVIDER="$AV_ENGINE" ;;
+  esac
+fi
+
 # Show GitHub star reminder (once per day)
 bash "$SCRIPT_DIR/github-star-reminder.sh" 2>/dev/null || true
 
@@ -338,10 +424,10 @@ detect_voice_provider() {
   fi
 }
 
-# Override provider if voice indicates different provider (mixed-provider mode)
-# But never override transport providers (ssh-remote, agentvibes-receiver, termux-ssh)
-# — those are transport layers, not synth engines. The receiver picks its own engine.
-if [[ -n "$VOICE_OVERRIDE" ]]; then
+# Legacy mixed-provider heuristic — ONLY on the fallback path (no resolver plan).
+# When PLAN_OK is set, the resolver already coupled voice→engine correctly above
+# (including kokoro, which this heuristic misses — the R1 silence bug), so skip it.
+if [[ -z "$PLAN_OK" && -n "$VOICE_OVERRIDE" ]]; then
   case "$ACTIVE_PROVIDER" in
     ssh-remote|agentvibes-receiver|termux-ssh)
       # Transport provider — don't override, voice info is forwarded to receiver
@@ -432,12 +518,17 @@ speak_text() {
     termux-ssh)
       bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$text" "$voice"
       ;;
-    ssh-remote)
+    ssh-remote|agentvibes-receiver)
+      # Both route through the base64-JSON sender that the modern receiver
+      # (templates/agentvibes-receiver.ps1 / .sh, installed as play-remote.*)
+      # understands. The old voiceless-connections sender spoke a 3-positional-arg
+      # protocol for a legacy ~/.agentvibes/play-remote.sh receiver that no current
+      # receiver install produces, so it delivered a non-base64 command the modern
+      # receiver rejects ("Payload must be base64-encoded"). play-tts-ssh-remote.sh
+      # resolves the host from any transport-config mode=remote entry (Priority 2b),
+      # so the agentvibes-receiver section is found without an ssh-remote section.
       bash "$SCRIPT_DIR/play-tts-ssh-remote.sh" "$text" "$voice" "" "${profile_file:-}"
       ;;
-    agentvibes-receiver)
-      bash "$SCRIPT_DIR/play-tts-agentvibes-receiver-for-voiceless-connections.sh" "$text" "$voice"
-      ;;
     *)
       echo "❌ Unknown provider: $provider" >&2
       return 1
@@ -572,12 +663,14 @@ case "$ACTIVE_PROVIDER" in
   termux-ssh)
     exec bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$TEXT" "$VOICE_OVERRIDE"
     ;;
-  ssh-remote)
+  ssh-remote|agentvibes-receiver)
+    # Both route through the base64-JSON sender the modern receiver understands.
+    # The legacy voiceless-connections sender spoke a 3-arg protocol for an old
+    # ~/.agentvibes/play-remote.sh receiver that no current install produces, so it
+    # delivered a non-base64 command the modern receiver rejects with
+    # "Payload must be base64-encoded".
     exec bash "$SCRIPT_DIR/play-tts-ssh-remote.sh" "$TEXT" "$VOICE_OVERRIDE" "" "${AGENT_PROFILE_FILE:-}"
     ;;
-  agentvibes-receiver)
-    exec bash "$SCRIPT_DIR/play-tts-agentvibes-receiver-for-voiceless-connections.sh" "$TEXT" "$VOICE_OVERRIDE"
-    ;;
   *)
     echo "❌ Unknown provider: $ACTIVE_PROVIDER" >&2
     echo "   Run: /agent-vibes:provider list" >&2

package/.claude/hooks-windows/background-music-manager.ps1

@@ -25,7 +25,8 @@ $EnabledFile = Join-Path $ConfigDir "background-music-enabled.txt"
 $VolumeFile = Join-Path $ConfigDir "background-music-volume.txt"
 $AudioEffectsCfg = Join-Path $ConfigDir "audio-effects.cfg"
 
-$DefaultVolume = "0.34"
+# TODO(AVI-S8.6): generate this constant from the shared JSON source of truth.
+$DefaultVolume = "0.20"
 
 # Ensure config directory exists
 if (-not (Test-Path $ConfigDir)) {

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

@@ -160,6 +160,20 @@ try {
     Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
     Write-Host "[VOICE] Voice used: $VoiceName (Kokoro TTS)" -ForegroundColor Green
 
+    # Kokoro outputs at a lower level than Piper/SAPI, and ffmpeg's amix halves
+    # the voice when background music is mixed in.  Apply a 2.5x (≈8 dB) volume
+    # boost here so the voice is audible in all playback paths.
+    $ffplayCheck = Get-Command ffmpeg -ErrorAction SilentlyContinue
+    if ($ffplayCheck) {
+        $boostedFile = "$AudioDir\tts-boosted-$([System.IO.Path]::GetRandomFileName() -replace '\..*').wav"
+        $boostArgs = "-y -i `"$AudioFile`" -af `"volume=2.5`" `"$boostedFile`""
+        $boostProc = Start-Process -FilePath "ffmpeg" -ArgumentList $boostArgs -NoNewWindow -Wait -PassThru -RedirectStandardError "NUL"
+        if ($boostProc.ExitCode -eq 0 -and (Test-Path $boostedFile) -and (Get-Item $boostedFile).Length -gt 0) {
+            Remove-Item $AudioFile -Force -ErrorAction SilentlyContinue
+            $AudioFile = $boostedFile
+        }
+    }
+
     # Apply per-agent audio effects via audio-processor.ps1, but SKIP when
     # AGENTVIBES_NO_PLAY is set - that means the parent play-tts.ps1 will do its
     # own reverb / background-music post-processing and running effects here too