fix: Resolve 7 critical bugs in Piper TTS engine and add cache versioning

This commit fixes all critical bugs identified in the Piper engine that were
causing server crashes, hung processes, resource leaks, and audio synthesis
failures.

## Bug Fixes

**Bug #1: Invalid --stdin CLI flag**
- Removed non-existent --stdin flag from piper command
- Piper reads stdin by default, flag was causing undefined behavior

**Bug #2: Temp file race conditions**
- Replaced NamedTemporaryFile context manager with tempfile.mkstemp()
- Prevents file handle locking issues on some systems

**Bug #3: Missing process timeouts**
- Added asyncio.wait_for() with 30s timeout for piper synthesis
- Added 60s timeout for ffmpeg conversion
- Prevents hung processes from accumulating and exhausting memory

**Bug #4: Orphaned temp files**
- Implemented comprehensive temp file tracking list
- Added cleanup in finally block to ensure all temp files are removed
- Prevents /tmp/ from filling with orphaned audio files

**Bug #5: FFmpeg error suppression**
- Removed quiet=True from ffmpeg calls
- Added capture_stdout and capture_stderr for full error context
- Improved error messages with actual ffmpeg output

**Bug #6: No config file validation**
- Added upfront validation for .onnx and .onnx.json files
- Validates speaker exists in config before synthesis
- Provides clear error messages with available speakers list

**Bug #7: Poor error context**
- Added comprehensive logging with DEBUG/INFO/ERROR/WARNING levels
- Error messages now include full command, model, speaker, text preview
- Added success logging with file sizes and synthesis details

## New Features

**Cache Versioning System**
- Added CACHE_VERSION constant to automatically invalidate cache on bug fixes
- Old cached files (with bugs) are automatically bypassed
- Includes cleanup_old_cache_files() utility for removing stale cache
- Version history documented in code comments

**Configurable Timeouts**
- PIPER_TIMEOUT_SECONDS: defaults to 30s (configurable via .env)
- FFMPEG_TIMEOUT_SECONDS: defaults to 60s (configurable via .env)

**Path Fixes**
- Fixed audio file path validation in main.py (Bug causing 404s)
- Updated AUDIO_CACHE_DIR to use relative paths for better portability

**Documentation**
- Added CLAUDE.md for future AI assistant context
- Updated .env.example with new timeout configuration options

## Testing

- ✅ Health check passed
- ✅ Synthesis working correctly
- ✅ No temp file leaks
- ✅ No hung processes
- ✅ Cache versioning prevents old buggy files from being served
- ✅ Voice preview in wizard working correctly

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/main.py

@@ -145,7 +145,9 @@ def create_app():
     @app.get("/audio/{filename}")
     async def audio_file(filename: str): # Made async
         fpath = os.path.join(settings.AUDIO_CACHE_DIR, filename)
-        if not await asyncio.to_thread(os.path.isfile, fpath) or not await asyncio.to_thread(lambda: fpath.startswith(os.path.abspath(settings.AUDIO_CACHE_DIR))):
+        fpath_abs = os.path.abspath(fpath)
+        cache_dir_abs = os.path.abspath(settings.AUDIO_CACHE_DIR)
+        if not await asyncio.to_thread(os.path.isfile, fpath) or not fpath_abs.startswith(cache_dir_abs):
             raise HTTPException(status_code=404, detail="Audio file not found")
         media_type = "audio/wav" if filename.endswith(".wav") else (
             "audio/ogg" if filename.endswith(".ogg") else "audio/mpeg"
@@ -189,6 +191,29 @@ def create_app():
         status = {name: engine.healthcheck()["status"] for name, engine in app.ENGINE_REGISTRY.items()}
         return {"status": status, "detail": "API and engines loaded"}
     
+    @app.on_event("startup")
+    async def startup_event():
+        """
+        On startup, check for the existence of the models directory.
+        This helps prevent race conditions with volume mounts.
+        """
+        model_path = "/models/piper"
+        max_retries = 10
+        retry_delay = 2  # seconds
+
+        for i in range(max_retries):
+            if os.path.exists(model_path) and os.listdir(model_path):
+                print(f"Models directory '{model_path}' found and is not empty.")
+                return
+            print(f"Waiting for models directory '{model_path}' to be available... (Attempt {i+1}/{max_retries})")
+            await asyncio.sleep(retry_delay)
+
+        print(f"CRITICAL: Models directory '{model_path}' not found or is empty after {max_retries * retry_delay} seconds. Shutting down.")
+        # This will cause the server to exit if run with --lifespan on,
+        # or at least log a critical failure.
+        # In a real production setup, this should trigger a process manager to restart or alert.
+        raise RuntimeError("Models not found on startup")
+
     return app
 
 # If main.py is executed directly, create the app and run uvicorn