agentvibes 5.12.0-alpha.0 → 5.13.0

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

@@ -31,28 +31,55 @@ SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
 SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
 
 source "$SCRIPT_DIR/audio-cache-utils.sh"
+source "$SCRIPT_DIR/python-resolver.sh"
 
 if [[ -z "$TEXT" ]]; then
   echo "Usage: $0 \"text to speak\" [voice]" >&2
   exit 1
 fi
 
+# Distinguish "no Python at all" from "Python present but kokoro module missing"
+# — the old check conflated them, so a Windows box where python3 simply wasn't on
+# PATH wrongly reported "Kokoro not installed" (see python-resolver.sh).
+if [[ -z "$PYTHON_BIN" ]]; then
+  echo "❌ No Python 3 interpreter found." >&2
+  echo "   Kokoro needs Python 3. Install it (Windows: https://python.org, or 'py')," >&2
+  echo "   or set AGENTVIBES_PYTHON=/path/to/python.exe if it's installed elsewhere." >&2
+  exit 2
+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
+if ! "$PYTHON_BIN" -c "import importlib.util; exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null; then
+  echo "❌ Kokoro TTS module not installed for: $PYTHON_BIN" >&2
   echo "   Install with: ${SCRIPT_DIR}/kokoro-installer.sh" >&2
-  echo "   Or manually:  pip install kokoro-onnx soundfile numpy" >&2
+  echo "   Or manually:  \"$PYTHON_BIN\" -m pip install kokoro soundfile numpy" >&2
   exit 2
 fi
 
 # ---------------------------------------------------------------------------
 # Resolve voice
+# Default voice sourced from the generated Provider Catalog (SSOT) when present.
+# FAIL-SAFE: keep the literal fallback for installed-tree skew (mirrors play-tts.sh
+# PLAN_OK) — synth never breaks on a missing catalog.
 DEFAULT_VOICE="af_heart"
+if [[ -f "$SCRIPT_DIR/provider-catalog.sh" ]]; then
+  # shellcheck source=/dev/null
+  source "$SCRIPT_DIR/provider-catalog.sh" 2>/dev/null || true
+  if type catalog_default_voice >/dev/null 2>&1; then
+    _CATALOG_DEFAULT="$(catalog_default_voice kokoro 2>/dev/null || true)"
+    [[ -n "$_CATALOG_DEFAULT" ]] && DEFAULT_VOICE="$_CATALOG_DEFAULT"
+  fi
+fi
+
+# Synth-time shape check (LENIENT per design §3.3): a voice from a NEWER kokoro
+# model that the shipped catalog doesn't know must still degrade audibly, not
+# brick — so this stays a shape check + loud-warning fallback, NOT membership.
+# One literal, reused at both call sites below.
+KOKORO_SHAPE_RE='^[a-z]{2}_[a-z0-9_]+$'
 
 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
+  if [[ "$VOICE_OVERRIDE" =~ $KOKORO_SHAPE_RE ]]; then
     VOICE="$VOICE_OVERRIDE"
   else
     echo "⚠️  Unrecognized kokoro voice '$VOICE_OVERRIDE', using $DEFAULT_VOICE" >&2
@@ -62,7 +89,7 @@ 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
+    if [[ "$_CONFIGURED" =~ $KOKORO_SHAPE_RE ]]; then
       VOICE="$_CONFIGURED"
     else
       VOICE="$DEFAULT_VOICE"
@@ -103,7 +130,7 @@ if [[ "${AGENTVIBES_TEST_MODE:-false}" == "true" ]]; then
 fi
 
 # Run synthesis — output path printed to stdout
-RESULT=$(python3 "$SYNTH_SCRIPT" "$TEXT" "$VOICE" "$TEMP_WAV" "$SPEED" 2>&1) || {
+RESULT=$("$PYTHON_BIN" "$SYNTH_SCRIPT" "$TEXT" "$VOICE" "$TEMP_WAV" "$SPEED" 2>&1) || {
   echo "❌ Kokoro synthesis failed: $RESULT" >&2
   exit 3
 }

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

@@ -54,6 +54,7 @@ VOICE_OVERRIDE="$2"  # Ignored — Soprano has a single voice, kept for provider
 SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
 SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
 source "$SCRIPT_DIR/audio-cache-utils.sh"
+source "$SCRIPT_DIR/python-resolver.sh"
 
 SOPRANO_PORT="${SOPRANO_PORT:-7860}"
 SOPRANO_DEVICE="${SOPRANO_DEVICE:-auto}"
@@ -135,7 +136,7 @@ SYNTH_MODE=""
 if check_webui_server; then
   # Gradio WebUI mode — use Python helper for SSE protocol
   SYNTH_MODE="webui"
-  python3 "$SCRIPT_DIR/soprano-gradio-synth.py" "$TEXT" "$TEMP_FILE" "$SOPRANO_PORT" 2>/dev/null
+  "$PYTHON_BIN" "$SCRIPT_DIR/soprano-gradio-synth.py" "$TEXT" "$TEMP_FILE" "$SOPRANO_PORT" 2>/dev/null
 elif check_api_server; then
   # OpenAI-compatible API mode — direct curl
   SYNTH_MODE="api"
@@ -151,7 +152,7 @@ fi
 
 if [[ ! -f "$TEMP_FILE" ]] || [[ ! -s "$TEMP_FILE" ]]; then
   echo "❌ Failed to synthesize speech with Soprano ($SYNTH_MODE mode)"
-  [[ "$SYNTH_MODE" == "webui" ]] && echo "   Try: python3 $SCRIPT_DIR/soprano-gradio-synth.py \"test\" /tmp/test.wav $SOPRANO_PORT"
+  [[ "$SYNTH_MODE" == "webui" ]] && echo "   Try: $PYTHON_BIN $SCRIPT_DIR/soprano-gradio-synth.py \"test\" /tmp/test.wav $SOPRANO_PORT"
   exit 4
 fi
 

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

@@ -34,18 +34,60 @@ 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.
+  # Spaces ARE allowed (many track names contain them, e.g. "Late Night Hip Hop.mp3");
+  # the name travels as a jq --arg-escaped JSON string, so a space is not injectable.
+  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
 
 # Get script directory and project root
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/python-resolver.sh"
+source "$SCRIPT_DIR/session-id.sh"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Derive project name from directory
-PROJECT_NAME=$(basename "$PROJECT_ROOT")
+# Canonical routing session id. The receiver multiplexes forwarded TTS by this
+# id, so it MUST derive from CLAUDE_PROJECT_DIR (the real user project injected
+# via --project-dir), NOT basename(PROJECT_ROOT) — for a global install that
+# basename collapses to the HOME dir name and merges every project into one
+# session. Fallback (CLAUDE_PROJECT_DIR unset) is PROJECT_ROOT, preserving the
+# legacy value for the no-project case.
+SESSION_ID="$(av_session_id "$PROJECT_ROOT")"
+# PROJECT_NAME is kept for receiver back-compat (the receiver reads "project");
+# set it to the SAME corrected session id so both fields agree.
+PROJECT_NAME="$SESSION_ID"
+# Absolute path, forwarded so the receiver can show/learn the real remote folder.
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  PROJECT_PATH="$CLAUDE_PROJECT_DIR"
+else
+  PROJECT_PATH="$PROJECT_ROOT"
+fi
 
 # ---------------------------------------------------------------------------
 # Get SSH connection details from config
@@ -66,10 +108,10 @@ fi
 # Priority 2: ~/.agentvibes/transport-config.json (ssh-remote section)
 if [[ -z "$SSH_HOST" ]]; then
   _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
-  if [[ -f "$_TRANSPORT_CFG" ]] && command -v python3 &>/dev/null; then
-    SSH_HOST=$(python3 -c "import json,sys; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('ssh-remote',{}); print(p.get('host',''))" 2>/dev/null || echo "")
-    SSH_KEY=$(python3  -c "import json,sys; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('ssh-remote',{}); print(p.get('sshKey',''))" 2>/dev/null || echo "")
-    SSH_PORT=$(python3 -c "import json,sys; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('ssh-remote',{}); print(p.get('port',''))" 2>/dev/null || echo "")
+  if [[ -f "$_TRANSPORT_CFG" ]] && [[ -n "$PYTHON_BIN" ]]; then
+    SSH_HOST=$("$PYTHON_BIN" -c "import json,sys; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('ssh-remote',{}); print(p.get('host',''))" 2>/dev/null || echo "")
+    SSH_KEY=$("$PYTHON_BIN"  -c "import json,sys; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('ssh-remote',{}); print(p.get('sshKey',''))" 2>/dev/null || echo "")
+    SSH_PORT=$("$PYTHON_BIN" -c "import json,sys; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('ssh-remote',{}); print(p.get('port',''))" 2>/dev/null || echo "")
   fi
 fi
 
@@ -77,8 +119,8 @@ fi
 # (config keyed by LLM name rather than 'ssh-remote', e.g. 'claude-code')
 if [[ -z "$SSH_HOST" ]]; then
   _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
-  if [[ -f "$_TRANSPORT_CFG" ]] && command -v python3 &>/dev/null; then
-    _remote_data=$(python3 -c "
+  if [[ -f "$_TRANSPORT_CFG" ]] && [[ -n "$PYTHON_BIN" ]]; then
+    _remote_data=$("$PYTHON_BIN" -c "
 import json, sys
 try:
     d = json.load(open('$_TRANSPORT_CFG'))
@@ -129,10 +171,11 @@ if [[ -n "$SSH_PORT" ]] && [[ ! "$SSH_PORT" =~ ^[0-9]+$ ]]; then
 fi
 
 # SECURITY: Validate VOICE
-# Allow letters, digits, underscore, hyphen, period, colon (for :: multi-speaker separator), slash.
+# Allow letters, digits, underscore, hyphen, period, colon (for :: multi-speaker separator),
+# slash, and SPACES (Windows SAPI voice names like "Microsoft David Desktop").
 # Voice is passed to the remote via base64-encoded JSON (jq --arg safely escapes it),
-# so shell metacharacters are the only real risk.
-if [[ ! "$VOICE" =~ ^[a-zA-Z0-9_.:\/-]+$ ]]; then
+# so shell metacharacters are the only real risk — a space is not injectable.
+if [[ ! "$VOICE" =~ ^[a-zA-Z0-9_.:\/\ -]+$ ]]; then
   echo "Invalid voice format: $VOICE" >&2
   exit 1
 fi
@@ -316,9 +359,7 @@ 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.
+# Source: tts-language.txt (set by language-manager.sh).
 # 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,
@@ -326,14 +367,7 @@ fi
 # ---------------------------------------------------------------------------
 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).
+  # 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
@@ -364,25 +398,36 @@ build_json_payload() {
       --arg effects "$SOX_EFFECTS" \
       --arg music "$BG_FILE" \
       --arg volume "$BG_VOLUME" \
+      --arg session "$SESSION_ID" \
       --arg project "$PROJECT_NAME" \
+      --arg projectPath "$PROJECT_PATH" \
       --arg pretext "$PRETEXT" \
       --arg speed "$SPEED" \
       --arg provider "$PROVIDER" \
       --arg llm "$LLM_NAME" \
       --arg mute "$MUTE" \
       --arg language "$LANGUAGE" \
-      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, pretext: $pretext, speed: $speed, provider: $provider, llm: $llm, mute: $mute, language: $language}'
+      --arg kind "$PAYLOAD_KIND" \
+      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, session: $session, 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","mute":"%s","language":"%s"}' \
-      "$escaped_text" "$VOICE" "$SOX_EFFECTS" "$BG_FILE" "$BG_VOLUME" "$PROJECT_NAME" "$escaped_pretext" "$SPEED" "$PROVIDER" "$LLM_NAME" "$MUTE" "$LANGUAGE"
+    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","session":"%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" "$SESSION_ID" "$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

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

@@ -68,6 +68,7 @@ VOICE_OVERRIDE="$2"  # Not used for termux-ssh, but kept for interface compatibi
 
 # Script directory
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/python-resolver.sh"
 
 # @function get_ssh_host
 # @intent Determine SSH host alias for Android device
@@ -119,10 +120,10 @@ SSH_KEY=""
 SSH_PORT=""
 
 _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
-if [[ -f "$_TRANSPORT_CFG" ]] && command -v python3 &>/dev/null; then
-  _CFG_HOST=$(python3 -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('termux-ssh',{}); print(p.get('host',''))" 2>/dev/null || echo "")
-  SSH_KEY=$(python3    -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('termux-ssh',{}); print(p.get('sshKey',''))" 2>/dev/null || echo "")
-  SSH_PORT=$(python3   -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('termux-ssh',{}); print(p.get('port',''))" 2>/dev/null || echo "")
+if [[ -f "$_TRANSPORT_CFG" ]] && [[ -n "$PYTHON_BIN" ]]; then
+  _CFG_HOST=$("$PYTHON_BIN" -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('termux-ssh',{}); print(p.get('host',''))" 2>/dev/null || echo "")
+  SSH_KEY=$("$PYTHON_BIN"    -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('termux-ssh',{}); print(p.get('sshKey',''))" 2>/dev/null || echo "")
+  SSH_PORT=$("$PYTHON_BIN"   -c "import json; d=json.load(open('$_TRANSPORT_CFG')); p=d.get('termux-ssh',{}); print(p.get('port',''))" 2>/dev/null || echo "")
 fi
 
 if [[ -n "${_CFG_HOST:-}" ]]; then

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

@@ -31,13 +31,13 @@
 #
 # ---
 #
-# @fileoverview TTS Provider Router with Translation and Language Learning Support
+# @fileoverview TTS Provider Router with Translation Support
 # @context Routes TTS requests to active provider (Piper or macOS) with optional translation
-# @architecture Provider abstraction layer - single entry point for all TTS, handles translation and learning mode
-# @dependencies provider-manager.sh, play-tts-piper.sh, translator.py, translate-manager.sh, learn-manager.sh
+# @architecture Provider abstraction layer - single entry point for all TTS, handles translation
+# @dependencies provider-manager.sh, play-tts-piper.sh, translator.py, translate-manager.sh
 # @entrypoints Called by hooks, slash commands, personality-manager.sh, and all TTS features
 # @patterns Provider pattern - delegates to provider-specific implementations, auto-detects provider from voice name
-# @related provider-manager.sh, play-tts-piper.sh, learn-manager.sh, translate-manager.sh
+# @related provider-manager.sh, play-tts-piper.sh, translate-manager.sh
 #
 # **IMPORTANT: This script should be called inline (NOT in background) in Bash tool**
 # Wait for TTS playback to complete before continuing.
@@ -113,6 +113,12 @@ elif [[ -f "$GLOBAL_MUTE_FILE" ]]; then
   exit 0
 fi
 
+# Resolve a working Python interpreter once (translator and transport config
+# both need it). Sourced AFTER the mute exits so muted calls
+# pay nothing. Windows git-bash frequently has no python3 on PATH — see
+# python-resolver.sh; $PYTHON_BIN is empty when none is usable.
+source "$SCRIPT_DIR/python-resolver.sh"
+
 # Parse named flags (e.g. --llm) before positional arguments.
 # This allows callers to pass: play-tts.sh --llm claude-code "text to speak"
 # Named args are extracted; remaining positional args are shifted into $1/$2/$3.
@@ -241,6 +247,53 @@ if [[ -z "$_PRETEXT" ]]; then
     fi
   done
 fi
+# Dynamic session self-ID: a per-LLM PRETEXT containing the {{session}} token
+# expands to "<LLM> on <Project> in <Terminal>" so multi-session users can tell
+# which tab just spoke. Announced once per session (best-effort — see the key
+# note below); on later utterances the token is dropped so it doesn't prefix
+# every line. Opt-in — only fires when the pretext actually contains the token.
+if [[ "$_PRETEXT" == *"{{session}}"* ]]; then
+  # Session key. There is no true Claude-session id available to a plain Bash
+  # command, so this is best-effort: a terminal-session id if the emulator
+  # exports one (stable for the tab's life), else the parent PID. Worst case the
+  # self-ID repeats or is skipped — cosmetic, and only when a pretext opts in.
+  _SID_RAW="${WT_SESSION:-${TERM_SESSION_ID:-${TMUX:-$PPID}}}"
+  _SID_KEY="$(printf '%s' "${LLM_PROVIDER:-}|$(basename "${CLAUDE_PROJECT_DIR:-$PROJECT_ROOT}")|$_SID_RAW" | tr -c 'A-Za-z0-9' '_')"
+  # Announce-marker dir: an OWNED subdir, per the project's secure-temp rule.
+  # If the dir exists but isn't ours (pre-created symlink attack on a shared
+  # host), skip the marker entirely and just strip the token — never chmod or
+  # write through someone else's path.
+  _ANN_BASE="${XDG_RUNTIME_DIR:-/tmp/agentvibes-$(id -u 2>/dev/null || echo 0)}"
+  _ANN_DIR="$_ANN_BASE/agentvibes-session"
+  _ANN_OK=0
+  if mkdir -p "$_ANN_DIR" 2>/dev/null && chmod 700 "$_ANN_DIR" 2>/dev/null; then
+    _ANN_OWNER="$(stat -c '%u' "$_ANN_DIR" 2>/dev/null || stat -f '%u' "$_ANN_DIR" 2>/dev/null || echo '')"
+    [[ -z "$_ANN_OWNER" || "$_ANN_OWNER" == "$(id -u 2>/dev/null || echo 0)" ]] && _ANN_OK=1
+  fi
+  _ANN_FILE="$_ANN_DIR/announced-$_SID_KEY"
+  # First utterance → replacement is the self-ID; later utterances → empty (drop).
+  if [[ "$_ANN_OK" == "1" && -f "$_ANN_FILE" ]]; then
+    _SESSION_ID=""
+  else
+    _SESSION_ID="$(bash "$SCRIPT_DIR/agentvibes-session-id.sh" "${LLM_PROVIDER:-claude-code}" "${CLAUDE_PROJECT_DIR:-$PROJECT_ROOT}" 2>/dev/null || true)"
+    if [[ "$_ANN_OK" == "1" ]]; then
+      touch "$_ANN_FILE" 2>/dev/null || true
+      # Bound growth: drop announce-markers older than a day (find is optional).
+      find "$_ANN_DIR" -maxdepth 1 -name 'announced-*' -mtime +1 -delete 2>/dev/null || true
+    fi
+  fi
+  if [[ -n "$_SESSION_ID" ]]; then
+    _PRETEXT="${_PRETEXT//"{{session}}"/$_SESSION_ID}"
+  else
+    # Empty replacement: also swallow one adjacent ", " so "Hey {{session}}, ready"
+    # becomes "Hey ready", not "Hey , ready"; then drop any bare token.
+    _PRETEXT="${_PRETEXT//"{{session}}, "/}"
+    _PRETEXT="${_PRETEXT//", {{session}}"/}"
+    _PRETEXT="${_PRETEXT//"{{session}}"/}"
+  fi
+  # Final tidy: collapse doubled/edge commas and runs of whitespace.
+  _PRETEXT="$(printf '%s' "$_PRETEXT" | sed -E 's/,[[:space:]]*,/,/g; s/^[[:space:]]*,[[:space:]]*//; s/[[:space:]]*,[[:space:]]*$//; s/[[:space:]]{2,}/ /g; s/^[[:space:]]+//; s/[[:space:]]+$//')"
+fi
 if [[ -n "$_PRETEXT" ]]; then
   TEXT="${_PRETEXT}, ${TEXT}"
 fi
@@ -329,7 +382,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.
+      ACTIVE_PROVIDER="kokoro"
+    elif [[ -n "$_LLM_ENGINE" ]]; then
       ACTIVE_PROVIDER="$_LLM_ENGINE"
     fi
     ;;
@@ -351,8 +409,8 @@ fi
 _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
 if [[ "$ACTIVE_PROVIDER" != "ssh-remote" && "$ACTIVE_PROVIDER" != "agentvibes-receiver" && "$ACTIVE_PROVIDER" != "termux-ssh" ]] \
    && [[ -n "$LLM_PROVIDER" && "$LLM_PROVIDER" != "default" ]] \
-   && [[ -f "$_TRANSPORT_CFG" ]] && command -v python3 &>/dev/null; then
-  _LLM_SSH_MODE=$(AGENTVIBES_CFG="$_TRANSPORT_CFG" AGENTVIBES_KEY="$LLM_PROVIDER" python3 - <<'PYEOF'
+   && [[ -f "$_TRANSPORT_CFG" ]] && [[ -n "$PYTHON_BIN" ]]; then
+  _LLM_SSH_MODE=$(AGENTVIBES_CFG="$_TRANSPORT_CFG" AGENTVIBES_KEY="$LLM_PROVIDER" "$PYTHON_BIN" - <<'PYEOF'
 import json, os, sys
 try:
     d = json.load(open(os.environ['AGENTVIBES_CFG'], encoding='utf-8'))
@@ -363,7 +421,7 @@ PYEOF
 )
   if [[ "$_LLM_SSH_MODE" == "remote" ]]; then
     # Redirect this LLM's audio through ssh-remote using its own SSH config
-    _llm_remote_data=$(AGENTVIBES_CFG="$_TRANSPORT_CFG" AGENTVIBES_KEY="$LLM_PROVIDER" python3 - <<'PYEOF'
+    _llm_remote_data=$(AGENTVIBES_CFG="$_TRANSPORT_CFG" AGENTVIBES_KEY="$LLM_PROVIDER" "$PYTHON_BIN" - <<'PYEOF'
 import json, os, sys
 try:
     d = json.load(open(os.environ['AGENTVIBES_CFG'], encoding='utf-8'))
@@ -513,12 +571,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
@@ -526,50 +589,8 @@ speak_text() {
   esac
 }
 
-# Note: learn-manager.sh and translate-manager.sh are sourced inside their
-# respective handler functions to avoid triggering their main handlers
-
-# @function handle_learning_mode
-# @intent Speak in both main language and target language for learning
-# @why Issue #51 - Auto-translate and speak twice for immersive language learning
-# @returns 0 if learning mode handled, 1 if not in learning mode
-handle_learning_mode() {
-  # Source learn-manager for learning mode functions
-  source "$SCRIPT_DIR/learn-manager.sh" 2>/dev/null || return 1
-
-  # Check if learning mode is enabled
-  if ! is_learn_mode_enabled 2>/dev/null; then
-    return 1
-  fi
-
-  local target_lang
-  target_lang=$(get_target_language 2>/dev/null || echo "")
-  local target_voice
-  target_voice=$(get_target_voice 2>/dev/null || echo "")
-
-  # Need both target language and voice for learning mode
-  if [[ -z "$target_lang" ]] || [[ -z "$target_voice" ]]; then
-    return 1
-  fi
-
-  # 1. Speak in main language (current voice)
-  speak_text "$TEXT" "$VOICE_OVERRIDE" "$ACTIVE_PROVIDER"
-
-  # 2. Auto-translate to target language
-  local translated
-  # SECURITY: Add timeout to prevent hanging (#134)
-  translated=$(timeout 5 python3 "$SCRIPT_DIR/translator.py" "$TEXT" "$target_lang" 2>/dev/null) || translated="$TEXT"
-
-  # Small pause between languages
-  sleep 0.5
-
-  # 3. Speak translated text with target voice
-  local target_provider
-  target_provider=$(detect_voice_provider "$target_voice")
-  speak_text "$translated" "$target_voice" "$target_provider"
-
-  return 0
-}
+# Note: translate-manager.sh is sourced inside its handler function to avoid
+# triggering its main handler
 
 # @function handle_translation_mode
 # @intent Translate and speak in target language (non-learning mode)
@@ -594,7 +615,7 @@ handle_translation_mode() {
   # Translate text
   local translated
   # SECURITY: Add timeout to prevent hanging (#134)
-  translated=$(timeout 5 python3 "$SCRIPT_DIR/translator.py" "$TEXT" "$translate_to" 2>/dev/null) || translated="$TEXT"
+  translated=$(timeout 5 "${PYTHON_BIN:-python3}" "$SCRIPT_DIR/translator.py" "$TEXT" "$translate_to" 2>/dev/null) || translated="$TEXT"
 
   # Get voice for target language if no override specified
   local voice_to_use="$VOICE_OVERRIDE"
@@ -615,14 +636,8 @@ handle_translation_mode() {
 }
 
 # Mode priority:
-# 1. Learning mode (speaks twice: main + translated)
-# 2. Translation mode (speaks translated only)
-# 3. Normal mode (speaks as-is)
-
-# Try learning mode first (Issue #51)
-if handle_learning_mode; then
-  exit 0
-fi
+# 1. Translation mode (speaks translated only)
+# 2. Normal mode (speaks as-is)
 
 # Try translation mode (Issue #50)
 if handle_translation_mode; then
@@ -653,12 +668,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