agentvibes 5.9.0 → 5.11.0

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

@@ -223,6 +223,8 @@ done
 
 # LLM settings win over agent-name settings
 [[ -n "$LLM_REVERB"    ]] && SOX_EFFECTS="$LLM_REVERB"
+# Allow caller to override reverb for one-shot preview (e.g. effects picker Space preview)
+[[ -n "${AGENTVIBES_REVERB_OVERRIDE:-}" ]] && SOX_EFFECTS="$AGENTVIBES_REVERB_OVERRIDE"
 [[ -n "$LLM_BG_FILE"   ]] && BG_FILE="$LLM_BG_FILE"
 [[ -n "$LLM_BG_VOLUME" ]] && BG_VOLUME="$LLM_BG_VOLUME"
 
@@ -274,7 +276,7 @@ if [[ -z "$PROVIDER" ]]; then
 fi
 # Validate — only known TTS providers (not transport providers like ssh-remote)
 case "${PROVIDER:-}" in
-  piper|soprano|macos|windows-sapi) ;;
+  piper|soprano|macos|windows-sapi|kokoro|elevenlabs) ;;
   *) PROVIDER="piper" ;;
 esac
 
@@ -334,7 +336,12 @@ echo "Sending to $SSH_HOST..." >&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")
+# 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),
+# 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
 
 # ForceCommand receiver: SSH_ORIGINAL_COMMAND passes the payload directly.
 # Run ssh inside the backgrounded subshell so its exit code is reachable via $?

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

@@ -165,7 +165,9 @@ SAFE_TEXT="${TEXT//\'/\'\\\'\'}"
 # Build SSH args — use explicit key/port from config if available, else rely on ~/.ssh/config
 SSH_ARGS=(-o ConnectTimeout=5)
 [[ -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
 
 # Send TTS command to Android device via SSH
 # Use termux-tts-speak for native Android TTS

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

@@ -77,6 +77,15 @@ fi
 
 export PROJECT_ROOT  # Export for child scripts
 
+# Suppress audio when tests are running in a separate shell.
+# AGENTVIBES_TEST_MODE only propagates to child processes of the test runner;
+# external callers (e.g. Claude Code hooks) don't inherit it.
+# scripts/run-tests.sh writes this marker file so all play-tts.sh invocations —
+# regardless of which process spawns them — stay silent during test runs.
+if [[ -f "${HOME}/.agentvibes-tests-running" ]]; then
+  exit 0
+fi
+
 # Check if muted (persists across sessions)
 # Project settings always override global settings:
 # - .claude/agentvibes-unmuted = project explicitly unmuted (overrides global mute)
@@ -197,8 +206,8 @@ if [[ -n "$LLM_PROVIDER" ]]; then
       done < "$_cfg"
     fi
   done
-  # Apply LLM voice (only if no explicit voice override)
-  if [[ -n "$_LLM_VOICE" && -z "$VOICE_OVERRIDE" ]]; then
+  # Apply LLM voice (only if no explicit voice override, and not in effects-preview mode)
+  if [[ -n "$_LLM_VOICE" && -z "$VOICE_OVERRIDE" && -z "${AGENTVIBES_EFFECTS_PREVIEW:-}" ]]; then
     VOICE_OVERRIDE="$_LLM_VOICE"
   fi
   # Export LLM key for child scripts (process-local, not system-wide)
@@ -256,6 +265,17 @@ case "$ACTIVE_PROVIDER" in
     ;;
 esac
 
+# AGENTVIBES_FORCE_PROVIDER: set by agentvibes-receiver.sh to honour the
+# provider field in the incoming JSON payload (e.g. kokoro, elevenlabs).
+# Only applies when the locally-configured provider is still the default "piper"
+# so a receiver that has tts-provider.txt set keeps its own preference.
+if [[ -n "${AGENTVIBES_FORCE_PROVIDER:-}" && "$ACTIVE_PROVIDER" == "piper" ]]; then
+  case "$AGENTVIBES_FORCE_PROVIDER" in
+    piper|soprano|macos|windows-sapi|kokoro|elevenlabs)
+      ACTIVE_PROVIDER="$AGENTVIBES_FORCE_PROVIDER" ;;
+  esac
+fi
+
 # Per-LLM SSH override: if the current LLM has mode=remote in transport-config.json,
 # write a one-shot env override so play-tts-ssh-remote.sh uses that LLM's SSH config.
 _TRANSPORT_CFG="$HOME/.agentvibes/transport-config.json"
@@ -341,6 +361,43 @@ if [[ "${AGENTVIBES_VERBOSE:-0}" == "1" ]]; then
   echo "provider=${ACTIVE_PROVIDER}" >&2
 fi
 
+# @function _play_windows_sapi
+# @intent Speak via the built-in Windows SAPI engine from a POSIX shell
+# @why On Windows git-bash the `sapi`/`windows-sapi` provider has no native bash
+#      player; delegate to the PowerShell SAPI script so the engine selector's
+#      `sapi` id no longer dead-ends in "Unknown provider".
+# @param $1 text to speak
+# @param $2 voice override (optional)
+_play_windows_sapi() {
+  local text="$1"
+  local voice="${2:-}"
+
+  # Sibling hooks-windows/ holds the PowerShell players. Prefer the short name,
+  # fall back to the legacy windows-prefixed one.
+  local ps1="$SCRIPT_DIR/../hooks-windows/play-tts-sapi.ps1"
+  [[ -f "$ps1" ]] || ps1="$SCRIPT_DIR/../hooks-windows/play-tts-windows-sapi.ps1"
+  if [[ ! -f "$ps1" ]]; then
+    echo "❌ Windows SAPI player not found beside this hook" >&2
+    return 1
+  fi
+
+  local ps_exe=""
+  local c
+  for c in powershell.exe pwsh.exe powershell pwsh; do
+    if command -v "$c" >/dev/null 2>&1; then ps_exe="$c"; break; fi
+  done
+  if [[ -z "$ps_exe" ]]; then
+    echo "❌ Windows SAPI requires PowerShell (Windows only)" >&2
+    return 1
+  fi
+
+  # PowerShell needs a native Windows path, not a /c/... MSYS path.
+  local win_ps1="$ps1"
+  command -v cygpath >/dev/null 2>&1 && win_ps1="$(cygpath -w "$ps1")"
+
+  "$ps_exe" -NoProfile -ExecutionPolicy Bypass -File "$win_ps1" "$text" "$voice"
+}
+
 # @function speak_text
 # @intent Route text to appropriate TTS provider
 # @why Reusable function for speaking, used by both single and learning modes
@@ -363,6 +420,15 @@ speak_text() {
     macos)
       bash "$SCRIPT_DIR/play-tts-macos.sh" "$text" "$voice"
       ;;
+    elevenlabs)
+      bash "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$text" "$voice"
+      ;;
+    kokoro)
+      bash "$SCRIPT_DIR/play-tts-kokoro.sh" "$text" "$voice"
+      ;;
+    sapi|windows-sapi)
+      _play_windows_sapi "$text" "$voice"
+      ;;
     termux-ssh)
       bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$text" "$voice"
       ;;
@@ -493,6 +559,16 @@ case "$ACTIVE_PROVIDER" in
   macos)
     exec bash "$SCRIPT_DIR/play-tts-macos.sh" "$TEXT" "$VOICE_OVERRIDE"
     ;;
+  elevenlabs)
+    exec bash "$SCRIPT_DIR/play-tts-elevenlabs.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  kokoro)
+    exec bash "$SCRIPT_DIR/play-tts-kokoro.sh" "$TEXT" "$VOICE_OVERRIDE"
+    ;;
+  sapi|windows-sapi)
+    _play_windows_sapi "$TEXT" "$VOICE_OVERRIDE"
+    exit $?
+    ;;
   termux-ssh)
     exec bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$TEXT" "$VOICE_OVERRIDE"
     ;;

package/.claude/hooks/provider-commands.sh

@@ -63,13 +63,24 @@ is_language_supported() {
 
   case "$provider" in
     piper)
-      # Piper only supports English natively
+      # Piper only supports English natively (multilingual models exist but aren't bundled)
       return 1
       ;;
     macos)
       # macOS has voices for 40+ languages built-in
       return 0
       ;;
+    elevenlabs)
+      # ElevenLabs eleven_multilingual_v2 supports 32+ languages
+      return 0
+      ;;
+    kokoro)
+      # Kokoro supports English, Japanese, Korean, French, German, Spanish, Portuguese, Hindi
+      case "$language" in
+        japanese|korean|french|german|spanish|portuguese|hindi) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
     *)
       return 1
       ;;
@@ -88,48 +99,86 @@ provider_list() {
     is_macos=true
   fi
 
-  echo "┌────────────────────────────────────────────────────────────┐"
-  echo "│ Available TTS Providers                                    │"
-  echo "├────────────────────────────────────────────────────────────┤"
+  # Check installation status of optional providers
+  local kokoro_installed=false
+  python3 -c "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec('kokoro') else 1)" 2>/dev/null && kokoro_installed=true
+
+  local elevenlabs_key_set=false
+  if [[ -n "${ELEVENLABS_API_KEY:-}" ]]; then
+    elevenlabs_key_set=true
+  elif [[ -f "${HOME}/.agentvibes/elevenlabs-key.txt" ]]; then
+    elevenlabs_key_set=true
+  fi
+
+  _active() { [[ "$current_provider" == "$1" ]]; }
+  _mark()   { _active "$1" && echo "[ACTIVE]" || echo ""; }
+
+  echo "┌──────────────────────────────────────────────────────────────┐"
+  echo "│ Available TTS Providers                                      │"
+  echo "├──────────────────────────────────────────────────────────────┤"
 
   # macOS Say (show first on macOS systems)
   if [[ "$is_macos" == true ]]; then
-    if [[ "$current_provider" == "macos" ]]; then
-      echo "│ ✓ macOS Say     Built-in, free     ⭐⭐⭐⭐      [ACTIVE]    │"
+    if _active "macos"; then
+      echo "│ ✓ macOS Say     Built-in, free     ⭐⭐⭐⭐      [ACTIVE]     │"
     else
-      echo "│   macOS Say     Built-in, free     ⭐⭐⭐⭐   [RECOMMENDED] │"
+      echo "│   macOS Say     Built-in, free     ⭐⭐⭐⭐  [RECOMMENDED]  │"
     fi
-    echo "│   Cost: Free (built-in)                                   │"
-    echo "│   Platform: macOS only                                    │"
-    echo "│   Offline: Yes                                            │"
-    echo "│                                                            │"
+    echo "│   Cost: Free (built-in)  Platform: macOS  Offline: Yes     │"
+    echo "│                                                              │"
   fi
 
   # Piper
-  if [[ "$current_provider" == "piper" ]]; then
+  if _active "piper"; then
     echo "│ ✓ Piper TTS     Free, offline      ⭐⭐⭐⭐       [ACTIVE]    │"
   else
-    echo "│   Piper TTS     Free, offline      ⭐⭐⭐⭐                  │"
+    echo "│   Piper TTS     Free, offline      ⭐⭐⭐⭐                   │"
+  fi
+  echo "│   Cost: Free forever  Platform: Linux/WSL  Offline: Yes     │"
+  echo "│                                                              │"
+
+  # Kokoro
+  if _active "kokoro"; then
+    echo "│ ✓ Kokoro TTS    Local neural        ⭐⭐⭐⭐⭐    [ACTIVE]    │"
+  else
+    if [[ "$kokoro_installed" == true ]]; then
+      echo "│   Kokoro TTS    Local neural        ⭐⭐⭐⭐⭐  [installed]  │"
+    else
+      echo "│   Kokoro TTS    Local neural        ⭐⭐⭐⭐⭐  [not installed]│"
+    fi
+  fi
+  echo "│   Cost: Free  60+ voices  8 languages  Offline: Yes         │"
+  echo "│   Install: ${SCRIPT_DIR}/kokoro-installer.sh               │"
+  echo "│                                                              │"
+
+  # ElevenLabs
+  if _active "elevenlabs"; then
+    echo "│ ✓ ElevenLabs    Premium cloud      ⭐⭐⭐⭐⭐    [ACTIVE]    │"
+  else
+    if [[ "$elevenlabs_key_set" == true ]]; then
+      echo "│   ElevenLabs    Premium cloud      ⭐⭐⭐⭐⭐  [key set]    │"
+    else
+      echo "│   ElevenLabs    Premium cloud      ⭐⭐⭐⭐⭐  [needs key]  │"
+    fi
   fi
-  echo "│   Cost: Free forever                                       │"
-  echo "│   Platform: WSL, Linux only                                │"
-  echo "│   Offline: Yes                                             │"
+  echo "│   Cost: Free tier available  32+ languages  Offline: No     │"
+  echo "│   Key:  export ELEVENLABS_API_KEY=your_key                  │"
+  echo "│                                                              │"
 
   # macOS Say (show at end for non-macOS systems)
   if [[ "$is_macos" != true ]]; then
-    echo "│                                                            │"
-    if [[ "$current_provider" == "macos" ]]; then
+    if _active "macos"; then
       echo "│ ✓ macOS Say     Built-in, free     ⭐⭐⭐⭐      [ACTIVE]    │"
     else
       echo "│   macOS Say     Built-in, free     ⭐⭐⭐⭐   (macOS only)  │"
     fi
-    echo "│   Cost: Free (built-in)                                   │"
-    echo "│   Platform: macOS only                                    │"
-    echo "│   Offline: Yes                                            │"
+    echo "│   Cost: Free (built-in)  Platform: macOS only             │"
+    echo "│                                                              │"
   fi
 
-  echo "└────────────────────────────────────────────────────────────┘"
+  echo "└──────────────────────────────────────────────────────────────┘"
   echo ""
+  echo "Switch:  /agent-vibes:provider switch <name>"
   echo "Learn more: agentvibes.org/providers"
 }
 

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

@@ -191,12 +191,18 @@ migrate_voice_to_provider() {
   local piper_default="en_US-lessac-medium"
   local macos_default="Samantha"
   local soprano_default="soprano-default"  # Single voice — no selection needed
+  local elevenlabs_default="Rachel"
+  local kokoro_default="af_heart"
 
-  # Soprano has a single voice, so migration is straightforward
-  if [[ "$target_provider" == "soprano" ]]; then
-    echo "$soprano_default"
-    return 0
-  fi
+  # Single-voice providers: migration is straightforward
+  case "$target_provider" in
+    soprano)
+      echo "$soprano_default"; return 0 ;;
+    elevenlabs)
+      echo "$elevenlabs_default"; return 0 ;;
+    kokoro)
+      echo "$kokoro_default"; return 0 ;;
+  esac
 
   # If no current voice, return default for target provider
   if [[ -z "$current_voice" ]]; then
@@ -208,8 +214,8 @@ migrate_voice_to_provider() {
     return 0
   fi
 
-  # If migrating FROM Soprano, return default for target provider
-  if [[ "$current_voice" == "soprano-default" ]]; then
+  # If migrating FROM a single-voice provider, return default for target provider
+  if [[ "$current_voice" == "soprano-default" || "$current_voice" == "Rachel" || "$current_voice" =~ ^[a-z]{2}_[a-z0-9_]+$ ]]; then
     case "$target_provider" in
       piper) echo "$piper_default" ;;
       macos) echo "$macos_default" ;;
@@ -265,6 +271,8 @@ migrate_voice_to_provider() {
   case "$target_provider" in
     piper) echo "$piper_default" ;;
     macos) echo "$macos_default" ;;
+    elevenlabs) echo "$elevenlabs_default" ;;
+    kokoro) echo "$kokoro_default" ;;
     *) echo "$piper_default" ;;
   esac
 }

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

@@ -513,6 +513,12 @@ case "$1" in
       fi
     fi
 
+    # Normalize to canonical path so ls output is consistent across platforms
+    # (Git Bash resolves /tmp→/c/Users/..., macOS has /var→/private/var)
+    if [[ -d "$AUDIO_DIR" ]]; then
+      AUDIO_DIR=$(cd "$AUDIO_DIR" && pwd -P)
+    fi
+
     # Default to replay last audio (N=1)
     N="${2:-1}"
 

package/.claude/hooks-windows/kokoro-server.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+#
+# File: .claude/hooks/kokoro-server.py
+#
+# AgentVibes - Kokoro TTS persistent daemon
+# Loads the Kokoro model ONCE (on GPU when available) and serves synthesis over
+# a localhost HTTP socket, so each request skips the ~10s model-load + CUDA-init
+# cost that a fresh `python kokoro-tts.py` invocation pays every time.
+#
+# This is the difference between ~31s/message (cold process per call) and
+# ~2-3s/message (warm resident model).
+#
+# Endpoints (bound to 127.0.0.1 only — never exposed off-host):
+#   GET  /health  -> 200 {"ok":true} once the model is loaded and warmed
+#   POST /synth   -> body {text, voice, speed, output}; writes a WAV to `output`
+#                    and returns {"ok":true,"path":output} or {"ok":false,"error":...}
+#
+# Usage: python kokoro-server.py [port]   (default port 7855)
+#
+# Licensed under the Apache License, Version 2.0
+#
+import json
+import os
+import sys
+import tempfile
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+# A bad argv[1] (non-numeric) must not crash the daemon before it can bind;
+# fall back to the standard kokoro-server port.
+try:
+    PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 7855
+except (ValueError, IndexError):
+    PORT = 7855
+
+# Language code from the voice prefix (af/am=American, bf/bm=British, etc.)
+LANG_MAP = {
+    'af': 'a', 'am': 'a', 'bf': 'b', 'bm': 'b', 'jf': 'j', 'jm': 'j',
+    'kf': 'k', 'km': 'k', 'zf': 'z', 'zm': 'z', 'ff': 'f', 'fm': 'f',
+    'hf': 'h', 'hm': 'h', 'if': 'i', 'im': 'i', 'pf': 'p', 'pm': 'p',
+    'ef': 'e', 'em': 'e', 'nf': 'n', 'nm': 'n',
+}
+
+# Heavy imports up front so the model is resident before we accept connections.
+import numpy as np
+import soundfile as sf
+from kokoro import KPipeline
+
+_pipelines = {}
+_lock = threading.Lock()        # guards pipeline creation only
+_infer_lock = threading.Lock()  # serializes inference (torch is not thread-safe)
+
+
+def get_pipeline(lang_code):
+    """Return a cached KPipeline for the language, creating it once on demand."""
+    with _lock:
+        pipe = _pipelines.get(lang_code)
+        if pipe is None:
+            pipe = KPipeline(lang_code=lang_code)
+            _pipelines[lang_code] = pipe
+        return pipe
+
+
+def synth(text, voice, speed, output):
+    """Synthesize `text` with `voice` to the `output` WAV path. Returns the path."""
+    prefix = voice[:2].lower() if len(voice) >= 2 else 'af'
+    lang_code = LANG_MAP.get(prefix, 'a')
+    pipeline = get_pipeline(lang_code)
+
+    chunks = []
+    # The daemon shares one KPipeline across ThreadingHTTPServer worker threads
+    # and torch inference is not thread-safe — run one inference at a time. This
+    # lock is acquired after get_pipeline() has released _lock, so no deadlock.
+    with _infer_lock:
+        for result in pipeline(text, voice=voice, speed=speed):
+            audio = getattr(result, "audio", None)
+            if audio is None:
+                try:
+                    audio = result[-1]
+                except (TypeError, IndexError, KeyError):
+                    audio = None
+            if audio is None:
+                continue
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            audio = np.asarray(audio).reshape(-1)
+            if audio.size > 0:
+                chunks.append(audio)
+
+    if not chunks:
+        raise RuntimeError("Kokoro returned no audio samples")
+
+    sf.write(output, np.concatenate(chunks), 24000)  # kokoro is always 24 kHz
+    return output
+
+
+def _allowed_output_dirs():
+    """Directories a /synth request is permitted to write a WAV into.
+
+    Mirrors the shell hooks' audio-cache resolution (project-local first, then
+    the global ~/.claude/audio) plus TEMP, which is where the daemon writes its
+    own transient/warmup files.
+    """
+    dirs = []
+    proj = os.environ.get("CLAUDE_PROJECT_DIR")
+    if proj:
+        dirs.append(os.path.join(proj, ".claude", "audio"))
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    dirs.append(os.path.join(home, ".claude", "audio"))
+    dirs.append(os.environ.get("TEMP", "/tmp"))
+    return dirs
+
+
+def is_output_within_cache(output):
+    """True if `output` resolves inside an allowed audio dir (blocks traversal).
+
+    The daemon is shared across projects on a fixed port, so it cannot rely on
+    its own CLAUDE_PROJECT_DIR to know every project's audio dir. Accept the
+    home/TEMP locations plus any file that sits directly inside a ".claude/audio"
+    directory (the only place the providers ever write). realpath has already
+    collapsed any "..", so true traversal (e.g. /etc/x.wav) is still rejected.
+    """
+    tgt = os.path.realpath(output)
+    for base in _allowed_output_dirs():
+        base = os.path.realpath(base)
+        if tgt == base or tgt.startswith(base + os.sep):
+            return True
+    # Project-local audio dir for ANY project — the file must live directly in
+    # a ".claude/audio" directory.
+    parent = os.path.dirname(tgt).replace("\\", "/").lower()
+    if parent.endswith("/.claude/audio"):
+        return True
+    return False
+
+
+class Handler(BaseHTTPRequestHandler):
+    # Silence default per-request stderr logging
+    def log_message(self, *args):
+        pass
+
+    def _send(self, code, obj):
+        data = json.dumps(obj).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        try:
+            self.wfile.write(data)
+        except OSError:
+            # Client closed the socket early (health probes do this) — WinError
+            # 10053/10054 etc. Nothing to send to; ignore.
+            pass
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._send(200, {"ok": True})
+        else:
+            self._send(404, {"ok": False, "error": "not found"})
+
+    def do_POST(self):
+        if self.path != "/synth":
+            self._send(404, {"ok": False, "error": "not found"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length", 0))
+            body = json.loads(self.rfile.read(length) or b"{}")
+            text = body["text"]
+            voice = body.get("voice", "af_heart")
+            speed = float(body.get("speed", 1.0))
+            output = body["output"]
+            # Output must be an absolute .wav path (the provider always supplies one)
+            if not isinstance(output, str) or not output.lower().endswith(".wav"):
+                raise ValueError("output must be a .wav path")
+            # Path-traversal guard: the resolved target must stay inside an
+            # allowed audio directory — reject before any file is written.
+            if not is_output_within_cache(output):
+                self._send(400, {"ok": False, "error": "output path outside allowed audio directory"})
+                return
+            synth(text, voice, speed, output)
+            self._send(200, {"ok": True, "path": output})
+        except Exception as e:  # noqa: BLE001 - report any failure to the client
+            self._send(500, {"ok": False, "error": str(e)})
+
+
+def main():
+    try:
+        import torch
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    except Exception:
+        device = "cpu"
+
+    # Bind first so a second accidental launch fails fast (address in use) and
+    # exits instead of loading a second copy of the model.
+    try:
+        server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
+    except OSError as e:
+        print(f"kokoro-server: port {PORT} unavailable ({e}); another instance is likely running", file=sys.stderr)
+        sys.exit(0)
+
+    # Warm the default English pipeline + trigger CUDA kernel compilation so the
+    # very first real /synth request is already fast.
+    warm_fd, warm_out = tempfile.mkstemp(suffix=".wav")
+    os.close(warm_fd)  # synth/soundfile reopens by path; we only need the name
+    try:
+        synth("ready", "af_heart", 1.0, warm_out)
+    except Exception as e:  # noqa: BLE001
+        print(f"kokoro-server: warmup failed (continuing): {e}", file=sys.stderr)
+    finally:
+        try:
+            os.remove(warm_out)
+        except OSError:
+            pass
+
+    print(f"kokoro-server ready on 127.0.0.1:{PORT} device={device}", flush=True)
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()