Merge pull request #2007 from debpalash/release/v0.5.2

docs(changelog): cut the 0.5.2 release section

.agents/skills/fastapi-python/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: fastapi-python
+description: Expert in FastAPI Python development with best practices for APIs and async operations
+---
+
+# FastAPI Python
+
+You are an expert in FastAPI and Python backend development.
+
+## Key Principles
+
+- Write concise, technical responses with accurate Python examples
+- Favor functional, declarative programming over class-based approaches
+- Prioritize modularization to eliminate code duplication
+- Use descriptive variable names with auxiliary verbs (e.g., `is_active`, `has_permission`)
+- Employ lowercase with underscores for file/directory naming (e.g., `routers/user_routes.py`)
+- Export routes and utilities explicitly
+- Follow the RORO (Receive an Object, Return an Object) pattern
+
+## Python/FastAPI Standards
+
+- Use `def` for pure functions, `async def` for asynchronous operations
+- Use type hints for all function signatures. Prefer Pydantic models over raw dictionaries
+- Structure: exported router, sub-routes, utilities, static content, types (models, schemas)
+- Use ordinary Python control flow; prefer readability over compressed one-line conditionals
+
+## Error Handling
+
+- Handle edge cases at function entry points
+- Employ early returns for error conditions
+- Place happy path logic last
+- Avoid unnecessary else statements; use if-return patterns
+- Implement guard clauses for preconditions
+- Provide proper error logging and user-friendly messaging
+
+## FastAPI-Specific Guidelines
+
+- Use functional components (plain functions) and Pydantic models for input validation
+- Declare routes with clear return type annotations
+- Prefer lifespan context managers for managing startup and shutdown events
+- Leverage middleware for logging, error monitoring, and optimization
+- Use HTTPException for expected errors and model them as specific HTTP responses
+- Apply Pydantic's BaseModel consistently for validation
+
+## Performance Optimization
+
+- Minimize blocking I/O. In `async def` handlers, use awaitable database/API clients; put synchronous SQLite or other blocking work in synchronous routes or explicitly offload it
+- Implement caching with Redis or in-memory stores
+- Optimize Pydantic serialization/deserialization
+- Use lazy loading for large datasets
+
+## Key Conventions
+
+1. Rely on FastAPI's dependency injection system
+2. Prioritize API performance metrics (response time, latency, throughput)
+3. Structure routes and dependencies for readability and maintainability
+
+## Dependencies
+
+FastAPI, Pydantic v2, asyncpg/aiomysql, SQLAlchemy 2.0

.agents/skills/vite/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: vite
+description: Expert guidance for Vite development with modern build tooling, HMR, framework integrations, and performance optimization
+---
+
+# Vite Development
+
+You are an expert in Vite, modern JavaScript/TypeScript build tooling, and frontend development.
+
+## Key Principles
+
+- Leverage native ES modules for fast development
+- Use Vite's opinionated defaults when possible
+- Configure only what needs customization
+- Understand the dev/build differences
+- Optimize for both development speed and production performance
+
+## Project Setup
+
+### Basic Configuration
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 3000,
+    open: true,
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+  },
+});
+```
+
+### Path Aliases
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': new URL('./src', import.meta.url).pathname,
+      '@components': new URL('./src/components', import.meta.url).pathname,
+      '@utils': new URL('./src/utils', import.meta.url).pathname,
+    },
+  },
+});
+```
+
+## Environment Variables
+
+### Usage
+```typescript
+// .env
+VITE_API_URL=https://api.example.com
+VITE_APP_TITLE=My App
+
+// In code
+const apiUrl = import.meta.env.VITE_API_URL;
+const isDev = import.meta.env.DEV;
+const isProd = import.meta.env.PROD;
+const mode = import.meta.env.MODE;
+```
+
+### Type Definitions
+```typescript
+// src/vite-env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_URL: string;
+  readonly VITE_APP_TITLE: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+
+## Hot Module Replacement
+
+### Manual HMR
+```typescript
+// For libraries without HMR support
+if (import.meta.hot) {
+  import.meta.hot.accept('./module.ts', (newModule) => {
+    // Handle the updated module
+    console.log('Module updated:', newModule);
+  });
+
+  import.meta.hot.dispose(() => {
+    // Cleanup before module is replaced
+  });
+}
+```
+
+## Asset Handling
+
+### Static Assets
+```typescript
+// Import as URL
+import imageUrl from './image.png';
+// <img src={imageUrl} />
+
+// Import as string (raw)
+import shaderCode from './shader.glsl?raw';
+
+// Import as worker
+import Worker from './worker.ts?worker';
+const worker = new Worker();
+```
+
+### Public Directory
+```
+public/
+├── favicon.ico      # Served at /favicon.ico
+├── robots.txt       # Served at /robots.txt
+└── images/          # Served at /images/
+```
+
+## Framework Integrations
+
+### React
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react({
+      // Babel plugins
+      babel: {
+        plugins: ['@emotion/babel-plugin'],
+      },
+    }),
+  ],
+});
+```
+
+### Vue
+```typescript
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [vue()],
+});
+```
+
+### Svelte
+```typescript
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+
+export default defineConfig({
+  plugins: [svelte()],
+});
+```
+
+## Build Optimization
+
+### Code Splitting
+```typescript
+// Dynamic imports create separate chunks
+const AdminPanel = lazy(() => import('./AdminPanel'));
+
+// Manual chunks
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+          utils: ['lodash', 'date-fns'],
+        },
+      },
+    },
+  },
+});
+```
+
+### Chunk Size Optimization
+```typescript
+export default defineConfig({
+  build: {
+    chunkSizeWarningLimit: 500,
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          if (id.includes('node_modules')) {
+            return id.split('node_modules/')[1].split('/')[0];
+          }
+        },
+      },
+    },
+  },
+});
+```
+
+## CSS Handling
+
+### CSS Modules
+```typescript
+// styles.module.css is auto-detected
+import styles from './styles.module.css';
+
+// <div className={styles.container}>
+```
+
+### PostCSS
+```javascript
+// postcss.config.js
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+### Preprocessors
+```typescript
+// Automatically handled with package installed
+// npm install -D sass
+import './styles.scss';
+```
+
+## Proxy Configuration
+
+```typescript
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:4000',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+      '/socket.io': {
+        target: 'ws://localhost:4000',
+        ws: true,
+      },
+    },
+  },
+});
+```
+
+## Plugin Development
+
+```typescript
+// my-vite-plugin.ts
+import type { Plugin } from 'vite';
+
+export function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+
+    // Hook: modify config
+    config(config, { mode }) {
+      return {
+        define: {
+          __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
+        },
+      };
+    },
+
+    // Hook: transform code
+    transform(code, id) {
+      if (id.endsWith('.md')) {
+        return {
+          code: `export default ${JSON.stringify(code)}`,
+          map: null,
+        };
+      }
+    },
+
+    // Hook: configure dev server
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        // Custom middleware
+        next();
+      });
+    },
+  };
+}
+```
+
+## Testing with Vitest
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './src/test/setup.ts',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});
+```
+
+## SSR Configuration
+
+```typescript
+export default defineConfig({
+  build: {
+    ssr: true,
+    rollupOptions: {
+      input: './src/entry-server.ts',
+    },
+  },
+  ssr: {
+    external: ['express'],
+    noExternal: ['my-ui-library'],
+  },
+});
+```
+
+## Library Mode
+
+```typescript
+export default defineConfig({
+  build: {
+    lib: {
+      entry: './src/index.ts',
+      name: 'MyLib',
+      fileName: (format) => `my-lib.${format}.js`,
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom'],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+        },
+      },
+    },
+  },
+});
+```
+
+## Best Practices
+
+- Use `vite preview` to test production builds locally
+- Keep dependencies that support ESM in regular deps
+- Use `optimizeDeps.include` for CommonJS dependencies
+- Enable `build.sourcemap` for debugging production
+- Use `server.warmup` for faster dev server starts

.claude/skills/omnivoice/SKILL.md

@@ -5,6 +5,9 @@ description: "Local TTS, voice cloning, voice design, and video dubbing via the
 
 # VoiceStudio
 
+The canonical cross-agent package lives at `skills/omnivoice/SKILL.md`. This
+Claude-specific package retains the MCP lifecycle helpers and references.
+
 ## Overview
 
 Generate audio locally via the VoiceStudio MCP server. Tools: `generate_speech`, `list_voices`, `list_personalities`, `list_languages`, `check_health`. Resources: `voice://{id}`, `history://recent`.
@@ -166,4 +169,4 @@ The MCP server does not expose the dubbing endpoint. The full transcribe → tra
 
 Backend Swagger / OpenAPI: `http://127.0.0.1:3900/docs` (when backend is up).
 
-Upstream: github.com/debpalash/VoiceStudio — FSL-1.1-ALv2 (free for personal/internal/non-commercial; auto-converts to Apache-2.0 two years after each release).
+Upstream: github.com/debpalash/VoiceStudio. The app uses AGPL-3.0-only; optional engines and downloaded models retain their own licenses. See `LICENSE-NOTICE.md` in the repository.

.claude/skills/omnivoice/scripts/start-backend.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Start the OmniVoice FastAPI backend on 127.0.0.1:3900, detached, idempotent.
-# Honors $OMNIVOICE_HOME (default ~/OmniVoice-Studio).
+# Honors $OMNIVOICE_HOME (default ~/VoiceStudio).
 #
 # Exit codes:
 #   0   success (already running, or freshly started + healthy within 60s)
@@ -11,7 +11,7 @@
 
 set -euo pipefail
 
-HOME_DIR="${OMNIVOICE_HOME:-$HOME/OmniVoice-Studio}"
+HOME_DIR="${OMNIVOICE_HOME:-$HOME/VoiceStudio}"
 URL="${OMNIVOICE_API_URL:-http://127.0.0.1:3900}"
 LOG="$HOME_DIR/backend.log"
 

.github/CONTRIBUTING.md

@@ -40,6 +40,7 @@ sudo apt-get install -y \
   libwebkit2gtk-4.1-dev libgtk-3-dev libpango1.0-dev libcairo2-dev \
   libsoup-3.0-dev libgdk-pixbuf-2.0-dev \
   libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev \
+  gstreamer1.0-plugins-good \
   libasound2-dev build-essential curl wget file
 ```
 
@@ -84,14 +85,20 @@ names: there is no `desktop=prod` (note the **hyphen** in `desktop-prod`).
 
 Requires [Rust](https://rustup.rs/) and platform-specific Tauri dependencies — see the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/).
 
-After installing Rust with rustup on macOS/Linux, either open a new terminal or
-load Cargo into the current one before starting the desktop app:
+After installing Rust with rustup (or `uv` with its installer), a terminal that
+was already open still has the old `PATH`. The desktop launchers (`bun desktop`,
+`bun desktop-prod`, `bun desktop-fresh`) detect this and add `~/.cargo/bin` /
+`~/.local/bin` for that run, printing a one-line note; to make it permanent,
+open a new terminal, or on macOS/Linux load Cargo into the current one:
 
 ```bash
 source "$HOME/.cargo/env"
 bun desktop
 ```
 
+If Rust is genuinely not installed, the launchers stop up front with the
+install command instead of failing later inside `cargo metadata`.
+
 On Linux, errors such as `Package gdk-3.0 was not found`, `pango.pc` missing,
 or `javascriptcoregtk-4.1` missing mean the native packages above were not
 installed; changing `PKG_CONFIG_PATH` does not fix libraries that are absent.

.github/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version | Supported |
 |---------|-----------|
-| 0.3.x (latest release + `main` previews) | ✅ Current — all fixes land here |
+| 0.5.x (latest release + `main` previews) | ✅ Current — all fixes land here |
 | 0.2.7 | ⚠️ Legacy stable — security fixes only, upgrade recommended |
 | < 0.2.7 | ❌ No longer supported |
 

.github/workflows/build-omnivoice-tts.yml

@@ -51,6 +51,13 @@ jobs:
           - os: ubuntu-latest
             platform: linux-x86_64
             experimental: false
+          - os: ubuntu-24.04-arm
+            platform: linux-aarch64
+            # Apple Silicon under Asahi Linux. Experimental: the Vulkan
+            # (Honeykrisp GPU) build path is new and the hosted arm64
+            # runner has no GPU — it validates that the binary builds;
+            # on-host Vulkan acceleration is exercised by users.
+            experimental: true
           - os: windows-latest
             platform: windows-x86_64
             experimental: false
@@ -80,11 +87,18 @@ jobs:
       # Linux-only: upstream `buildcpu.sh` enables `-DGGML_BLAS=ON` which
       # requires a system BLAS implementation at cmake configure time.
       - name: Linux system deps (BLAS for ggml-blas backend)
-        if: matrix.platform == 'linux-x86_64'
+        if: startsWith(matrix.platform, 'linux')
         run: |
           sudo apt-get update
           sudo apt-get install -y libopenblas-dev pkg-config
 
+      # linux-aarch64: let the build script's Vulkan path (Honeykrisp GPU
+      # on Asahi) engage instead of silently falling back to CPU.
+      - name: Vulkan dev deps (linux-aarch64 GPU backend)
+        if: matrix.platform == 'linux-aarch64'
+        run: |
+          sudo apt-get install -y glslc libvulkan-dev spirv-headers
+
       - name: Build omnivoice-tts
         shell: bash
         # Pass values through env (quoted) rather than ${{ }} interpolation

.github/workflows/ci.yml

@@ -11,6 +11,11 @@ on:
   push:
     branches: [main]
   workflow_dispatch:
+    inputs:
+      windows_wix_diagnostic:
+        description: Run only the tiny nonpublishing Windows MSI authoring diagnostic
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -21,6 +26,7 @@ env:
 
 jobs:
   test:
+    if: ${{ !inputs.windows_wix_diagnostic }}
     name: Tests (backend + frontend)
     runs-on: ubuntu-22.04
     env:
@@ -189,6 +195,7 @@ jobs:
   # and `cargo test --lib` runs the shell's unit tests natively on each OS.
   # Full bundling stays in release.yml on tag push.
   tauri-cross-platform:
+    if: ${{ !inputs.windows_wix_diagnostic }}
     name: Tauri shell check (${{ matrix.label }})
     needs: test
     strategy:
@@ -289,6 +296,7 @@ jobs:
   # job above misses. Narrow scope (tests/smoke/ only) — full pytest stays
   # on Linux until Phase 1's INST-01 lands setuptools for WhisperX.
   smoke-matrix:
+    if: ${{ !inputs.windows_wix_diagnostic }}
     name: Smoke (${{ matrix.label }})
     needs: test
     strategy:
@@ -428,17 +436,68 @@ jobs:
           PY
 
       - name: Run smoke tests
+        # Exercise credential paths on native Windows as well as POSIX hosts.
         if: matrix.backend_supported
-        run: uv run --no-sync pytest tests/smoke/ -q --tb=short
+        run: uv run --no-sync pytest tests/smoke/ tests/test_hf_token_cache_paths.py -q --tb=short
         env:
           HF_HUB_OFFLINE: "1"  # same no-silent-downloads guard as the main pytest job
           HF_HUB_CACHE: ${{ runner.temp }}/pockettts-empty-hf-cache
 
+      # The isolated backend session, on Windows. The `test` job runs it on
+      # Linux only, which is how four tests that CANNOT pass on Windows shipped
+      # unnoticed: two reach for os.WNOHANG and os.waitid (POSIX-only, an
+      # AttributeError before the first assertion), one asserts a RuntimeError
+      # that `backend_drain_fd` returns None instead of raising off POSIX, and
+      # one raced the OS reaping a crashed child — a race Linux won and Windows
+      # lost every time. All four were invisible to CI and hit every Windows
+      # contributor on their first `pytest` run. Forty seconds closes the class.
+      - name: Isolated backend session (Windows)
+        if: runner.os == 'Windows' && matrix.backend_supported
+        run: uv run --no-sync pytest backend/tests/ -q --tb=short
+        env:
+          HF_HUB_OFFLINE: "1"
+
       # Artifact commits depend on native Windows rename/replace semantics;
       # Linux emulation cannot exercise sharing rules or path parsing.
+      # test_worker_task_store and test_worker_inbound_transport joined this
+      # step after a Windows run found a real portability bug the Linux-only
+      # `test` job could not see: a staged input's artifact id was built with
+      # os.path.join, so a Windows control plane persisted and shipped
+      # `inputs\<sha>.wav` — which a Linux worker cannot resolve. These suites
+      # need no ffmpeg, so they cost seconds here.
       - name: Remote-worker artifact paths (Windows)
         if: runner.os == 'Windows' && matrix.backend_supported
-        run: uv run --no-sync pytest tests/test_worker_upload_server.py tests/test_worker_server_integrity.py -q --tb=short
+        run: >-
+          uv run --no-sync pytest
+          tests/test_worker_upload_server.py
+          tests/test_worker_server_integrity.py
+          tests/test_worker_task_store.py
+          tests/test_worker_inbound_transport.py
+          -q --tb=short
         env:
           HF_HUB_OFFLINE: "1"
           HF_HUB_CACHE: ${{ runner.temp }}/worker-artifact-empty-hf-cache
+
+  windows-wix-diagnostic:
+    name: Windows MSI authoring (no publishing)
+    needs: test
+    if: ${{ !cancelled() && (inputs.windows_wix_diagnostic || needs.test.result == 'success') }}
+    runs-on: windows-2022
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - name: Bundle canonical system and per-user templates with a tiny payload
+        shell: pwsh
+        run: ./scripts/diagnose-windows-wix.ps1
+      - name: Restore hosted Installer policy after failed standard-user installation
+        shell: powershell
+        run: ./scripts/test-msi-policy-cleanup.ps1
+      - name: Preserve verbose linker output and rendered authoring
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-wix-diagnostic
+          path: wix-diagnostic-artifacts/
+          if-no-files-found: warn
+          retention-days: 3

.github/workflows/install-smoke.yml

@@ -0,0 +1,127 @@
+# Installer smoke — runs scripts/install.sh / scripts/install.ps1 end-to-end
+# on all three desktop platforms so the one-liner installers can't rot.
+#
+# Gated by `paths` because a cold run downloads multi-GB wheels (torch) and
+# takes ~15-30 min per OS; it only needs to fire when an installer or this
+# workflow changes. The heavy Tauri bundles stay in release.yml (tag push).
+
+name: Install smoke
+
+on:
+  pull_request:
+    paths:
+      - "scripts/install.sh"
+      - "scripts/install.ps1"
+      - ".github/workflows/install-smoke.yml"
+  push:
+    branches: [main]
+    paths:
+      - "scripts/install.sh"
+      - "scripts/install.ps1"
+      - ".github/workflows/install-smoke.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  install:
+    name: Install (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      # Running `sh scripts/install.sh` from the repo root exercises the
+      # repo-root resolution (script dir is scripts/, project root one level
+      # up) — the exact bug that made a local run clone a duplicate repo.
+      # Binary mode is the default: prebuilt release asset, checksum verified.
+      - name: Run installer — binary (macOS/Linux)
+        if: runner.os != 'Windows'
+        run: sh scripts/install.sh
+
+      - name: Verify install — binary (macOS/Linux)
+        if: runner.os != 'Windows'
+        run: |
+          if [ "$(uname)" = "Darwin" ]; then
+            test -d "/Applications/VoiceStudio.app" || { echo "::error::VoiceStudio.app missing from /Applications"; exit 1; }
+            echo "✓ VoiceStudio.app installed in /Applications"
+          else
+            test -x "$HOME/.local/bin/VoiceStudio" || { echo "::error::AppImage missing from ~/.local/bin"; exit 1; }
+            "$HOME/.local/bin/VoiceStudio" --appimage-help >/dev/null 2>&1 || true
+            echo "✓ AppImage installed and executable"
+          fi
+
+      # Source mode stays covered end-to-end behind --source.
+      - name: Run installer — source (macOS/Linux)
+        if: runner.os != 'Windows'
+        run: sh scripts/install.sh --source
+
+      - name: Verify install — source (macOS/Linux)
+        if: runner.os != 'Windows'
+        working-directory: ${{ github.workspace }}
+        run: |
+          test -d .venv || { echo "::error::.venv missing"; exit 1; }
+          test -f frontend/dist/index.html || { echo "::error::frontend build missing"; exit 1; }
+          echo "✓ venv + frontend bundle present"
+
+      # Binary mode is the default; CI runs msiexec silently.
+      - name: Run installer — binary (Windows)
+        if: runner.os == 'Windows'
+        env:
+          CI: true
+        shell: pwsh
+        run: '& { $ErrorActionPreference = "Stop"; & "${{ github.workspace }}\scripts\install.ps1" }'
+
+      - name: Verify install — binary (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $paths = @(
+            "HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*",
+            "HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*",
+            "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*"
+          )
+          $key = Get-ItemProperty $paths -ErrorAction SilentlyContinue |
+            Where-Object { $_.DisplayName -match "VoiceStudio|OmniVoice" } |
+            Select-Object -First 1
+          if (-not $key) {
+            Get-ItemProperty $paths -ErrorAction SilentlyContinue |
+              Where-Object DisplayName | ForEach-Object { Write-Host "  installed: $($_.DisplayName)" }
+            Write-Host "::error::MSI product not registered"; exit 1
+          }
+          Write-Host "✓ MSI product registered: $($key.DisplayName)"
+
+      # Source mode stays covered end-to-end behind -Source.
+      - name: Run installer — source (Windows)
+        if: runner.os == 'Windows'
+        env:
+          VOICESTUDIO_INSTALL_MODE: source
+        shell: pwsh
+        run: '& { $ErrorActionPreference = "Stop"; & "${{ github.workspace }}\scripts\install.ps1" }'
+
+      - name: Verify install — source (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          if (-not (Test-Path .venv)) { Write-Host "::error::.venv missing"; exit 1 }
+          if (-not (Test-Path frontend\dist\index.html)) { Write-Host "::error::frontend build missing"; exit 1 }
+          Write-Host "✓ venv + frontend bundle present"
+
+      - name: Upload install log on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: install-log-${{ matrix.os }}
+          path: |
+            /Users/runner/Library/Application Support/OmniVoice/*.log
+            /home/runner/.local/share/VoiceStudio/*.log
+            ${{ runner.temp }}/VoiceStudio/**/*.log
+          if-no-files-found: ignore

.github/workflows/release.yml

@@ -148,15 +148,20 @@ jobs:
   preview-gate:
     name: Preview gate
     runs-on: ubuntu-22.04
+    permissions:
+      contents: read
     outputs:
       is_preview: ${{ steps.decide.outputs.is_preview }}
       proceed: ${{ steps.decide.outputs.proceed }}
+      stable_tag: ${{ steps.decide.outputs.stable_tag }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 50
       - id: decide
         shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -euo pipefail
           event="${{ github.event_name }}"
@@ -171,6 +176,13 @@ jobs:
               exit 1
             fi
             echo "is_preview=true" >> "$GITHUB_OUTPUT"
+            # Resolve once before the matrix starts so every platform stamps
+            # against the same immutable Stable-channel snapshot.
+            STABLE_TAG=$(gh release view --repo "$GITHUB_REPOSITORY" --json tagName --jq .tagName)
+            [[ "$STABLE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+              echo "::error::latest stable release has an invalid tag"; exit 1;
+            }
+            echo "stable_tag=$STABLE_TAG" >> "$GITHUB_OUTPUT"
           else
             echo "is_preview=false" >> "$GITHUB_OUTPUT"
           fi
@@ -497,35 +509,22 @@ jobs:
             echo "APPLE_TEAM_ID=$TID"
           } >> "$GITHUB_ENV"
 
-      # Stamp each preview build with a unique, monotonically increasing semver
-      # PRERELEASE so the updater actually offers it (a rolling preview that
-      # always reported the static 0.3.0 never looked "newer", so no update was
-      # ever delivered). Ephemeral, CI-only — never committed. Tauri reads the
-      # bundle + updater version from tauri.conf.json, so rewriting it here
-      # stamps the artifacts + latest.json. Under the versioning hard rule
-      # (owner-set 2026-06-11) main is always last-release + 1, so BASE-N is a
-      # prerelease of the NEXT version and semver-sorts ABOVE the last stable
-      # (0.3.6-N > 0.3.5) — preview users naturally upgrade past stable, and
-      # the Windows MSI ProductVersion (which strips the prerelease → 0.3.6)
-      # is also correctly above the last stable.
+      # Stamp each preview with a numeric prerelease that is strictly above the
+      # latest stable release. Main may intentionally retain the released
+      # version while AUTO_VERSION_BUMP is disabled; in that case the helper
+      # advances the preview base by one patch so stable users can still opt in
+      # and receive it. The edit is ephemeral and never committed.
       - name: Stamp preview version
         if: needs.preview-gate.outputs.is_preview == 'true'
         shell: bash
+        env:
+          STABLE_TAG: ${{ needs.preview-gate.outputs.stable_tag }}
         run: |
           set -euo pipefail
-          # package.json is the single source of truth; tauri.conf.json reads its
-          # version from it ("version": "../package.json"), so stamping
-          # package.json restamps the whole bundle.
-          CONF=frontend/package.json
-          BASE=$(jq -r .version "$CONF")
-          # MSI/WiX requires the semver pre-release identifier to be numeric-only
-          # (and <= 65535). "preview.N" hard-fails the Windows bundler, so the
-          # preview stamp is BASE-N — still sorts below the stable BASE for the
-          # updater, still unique per run.
-          PREVIEW_VERSION="${BASE}-${{ github.run_number }}"
-          tmp=$(mktemp)
-          jq --arg v "$PREVIEW_VERSION" '.version = $v' "$CONF" > "$tmp"
-          mv "$tmp" "$CONF"
+          PREVIEW_VERSION=$(python scripts/stamp-preview-version.py \
+            --package-json frontend/package.json \
+            --stable-tag "$STABLE_TAG" \
+            --run-number "${{ github.run_number }}")
           echo "Stamped preview version: $PREVIEW_VERSION"
 
       # The rolling `preview` release is REUSED every night, and macOS updater
@@ -605,6 +604,21 @@ jobs:
             fi
           done < /tmp/stale.txt
 
+      # A retried job reuses its version and can collide with installers it
+      # uploaded before a later step failed. Keep other versions/arches intact;
+      # macOS versionless updater archives are scoped by release tag and arch.
+      - name: Clear this target's installer assets on retry
+        if: github.run_attempt > 1
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ (needs.preview-gate.outputs.is_preview == 'true') && 'preview' || github.ref_name }}
+          RELEASE_TARGET: ${{ matrix.rust_target }}
+        run: |
+          VERSION=$(python -c 'import json; print(json.load(open("frontend/package.json"))["version"])')
+          python scripts/clear-release-rerun-assets.py \
+            --tag "$RELEASE_TAG" --version "$VERSION" --target "$RELEASE_TARGET"
+
       - name: Build + release (Tauri)
         uses: tauri-apps/tauri-action@v0
         env:
@@ -649,6 +663,47 @@ jobs:
           updaterJsonPreferNsis: false
           includeUpdaterJson: true
 
+      - name: Build per-user Windows MSI
+        if: runner.os == 'Windows'
+        shell: bash
+        working-directory: frontend
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          python ../scripts/render-per-user-wix.py \
+            --source src-tauri/wix/main.wxs \
+            --system-wxs src-tauri/target/${{ matrix.rust_target }}/release/wix/x64/main.wxs \
+            --output src-tauri/target/wix-per-user/main.wxs
+          bunx tauri build --target ${{ matrix.rust_target }} --bundles msi \
+            --config src-tauri/tauri.per-user.conf.json
+          DIR="src-tauri/target/${{ matrix.rust_target }}/release/bundle/msi"
+          while IFS= read -r artifact; do
+            safe=${artifact// (Current User)/_Current_User}
+            [ "$safe" = "$artifact" ] || mv "$artifact" "$safe"
+          done < <(find "$DIR" -maxdepth 1 -type f -name '*Current*User*.msi*')
+
+      - name: Publish per-user Windows updater channel
+        if: runner.os == 'Windows'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ (needs.preview-gate.outputs.is_preview == 'true') && 'preview' || github.ref_name }}
+        run: |
+          set -euo pipefail
+          DIR="frontend/src-tauri/target/${{ matrix.rust_target }}/release/bundle/msi"
+          MSI=$(find "$DIR" -name '*Current*User*.msi' -type f | head -1)
+          [ -n "$MSI" ] || { echo "per-user MSI missing"; find "$DIR" -type f; exit 1; }
+          [ -f "$MSI.sig" ] || { echo "per-user MSI signature missing"; exit 1; }
+          VERSION=$(jq -r .version frontend/package.json)
+          python scripts/build_windows_user_manifest.py \
+            --repo "$GITHUB_REPOSITORY" --tag "$RELEASE_TAG" --version "$VERSION" \
+            --asset "$(basename "$MSI")" --signature-file "$MSI.sig" \
+            --output latest-user.json
+          gh release upload "$RELEASE_TAG" "$MSI" "$MSI.sig" latest-user.json \
+            --clobber --repo "$GITHUB_REPOSITORY"
+
       # ── Installer smoke (Phase 0 GATE-03) ─────────────────────────────
       # Structural verification of the installed/extracted bundle. The thin
       # uv-venv installer ships NO frozen backend binary (the venv is built on
@@ -717,8 +772,9 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          MSI=$(find frontend/src-tauri/target/${{ matrix.rust_target }}/release/bundle/msi -name "*.msi" | head -1)
+          MSI=$(find frontend/src-tauri/target/${{ matrix.rust_target }}/release/bundle/msi -name "*.msi" ! -name '*Current*User*' | head -1)
           echo "Smoke-testing MSI: $MSI"
+          powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/verify-windows-msi.ps1 -MsiPath "$(cygpath -w "$MSI")"
           # /quiet = no UI, /norestart = don't reboot the runner if a dep asks
           msiexec.exe //i "$(cygpath -w "$MSI")" //quiet //norestart
           INSTALL="/c/Program Files/VoiceStudio"
@@ -731,6 +787,16 @@ jobs:
           find "$INSTALL" -type f -path '*backend*main.py' | grep -q . || fail "backend source main.py missing"
           echo "OK — MSI installed shell + uv + backend resources"
 
+      - name: Per-user installer smoke (Windows, non-admin account)
+        if: runner.os == 'Windows'
+        timeout-minutes: 8
+        shell: bash
+        run: |
+          set -euo pipefail
+          MSI=$(find frontend/src-tauri/target/${{ matrix.rust_target }}/release/bundle/msi -name '*Current*User*.msi' | head -1)
+          powershell.exe -NoProfile -ExecutionPolicy Bypass \
+            -File scripts/smoke-per-user-msi.ps1 -MsiPath "$(cygpath -w "$MSI")" -PrepareHostedRunner
+
       # linuxdeploy re-links .DirIcon as an ABSOLUTE symlink into the build
       # machine AFTER tauri's files-map has placed the real icon bytes — the
       # exact bug #1518 guarded against, resurfacing on the first real tag

.gitignore

@@ -159,7 +159,24 @@ tests/probe/reports/
 # reports). Working notes for whoever is driving a change, not a repo artifact.
 /remote/
 
+# OmniVoice GGUF runtime build artifacts (scripts/build-omnivoice-tts.sh).
+# Only 0-byte placeholders of omnivoice-tts-* are tracked; real binaries,
+# the checksums manifest and the copied libggml shared libs ship via CI.
+bin/libggml*
+bin/checksums.sha256
+bin/omnivoice-tts-linux-aarch64
+
 # Dubbing-demo intermediates. The .mp4/.srt/manifest.json in this directory ARE
 # committed (they ship with the app); the per-language source WAVs are just the
 # inputs scripts/render_dub_demo_audio.py hands to scripts/build_dub_demo.sh.
 backend/assets/samples/demo/dubbing/*.src.wav
+
+# Stray sqlite session artifacts (`<db-path>.ses`). An in-memory DB yields the
+# literal name `:memory:.ses`, and a path containing `:` cannot be checked out
+# on Windows at all — committing one fails every Windows CI job at the git
+# checkout step, before a single test runs. Guarded by
+# tests/test_no_windows_hostile_paths.py.
+*.ses
+
+# Generated Windows MSI diagnostic logs and installer payloads
+/wix-diagnostic-artifacts/

.gitleaks.toml

@@ -25,4 +25,8 @@ regexes = [
   '''^hf_QWERTYUIOPasdfghjklZXCVBNM0123456789xyzAB$''',
   # NLLB generation length argument, not the value of a credential.
   '''^max_length=400$''',
+  # Dubbing pane split-position localStorage key, not a credential.
+  '''^omnivoice\.dubSplit\.v1$''',
+  # cryptography's Ed25519 private-key type name, not key material.
+  '''^Ed25519PrivateKey$''',
 ]

AGENTS.md

@@ -33,8 +33,17 @@ Binding for every AI agent (Claude, Codex, Cursor, review bots, …). CLAUDE.md
 - `frontend/package.json` dep changes require regenerating root `bun.lock` (Docker runs `--frozen-lockfile`).
 - Issues: absorb or decline — never defer to a future version. Check the open-PR queue before implementing community-reported fixes.
 
+## Shared select controls
+
+- Use `frontend/src/components/SearchableSelect.jsx` for all new or redesigned select boxes. Reuse `VoiceSelector` for voice choices. Do not introduce native `<select>` controls.
+- Provide a localized `ariaLabel`; use `menuPortal` inside scrolling or clipping containers. Preserve keyboard selection and disabled states.
+
 ## Agent skills
 
+Project development skills are pinned in `skills-lock.json` and installed under
+`.agents/skills/`: Vite and FastAPI.
+Repository rules and tracker mappings override generic skill guidance.
+
 ### Issue tracker
 
 GitHub Issues on `debpalash/VoiceStudio`, via the `gh` CLI. See `docs/agents/issue-tracker.md`.

CHANGELOG.md

@@ -8,27 +8,324 @@ the frozen-backend fallback mirror it for their toolchains.
 
 ## [Unreleased]
 
+## [0.5.2] — 2026-09-10
+
 **Highlights**
 
-- The backend now answers within a second of launch and narrates its startup step by step
-- Reporting a bug from an outdated build now offers the latest release first
-- The backend is only announced ready once it can actually serve, and crash-loop restarts now pace themselves
+- Supertonic-3 and PocketTTS show their license Accept button again, so they can be enabled (#2017)
+- An engine that can't run on your platform says so, instead of telling you to install it (#2018)
+- MOSS-TTS-v1.5, Confucius4-TTS, dots.tts, Supertonic-3 and PocketTTS install in one click, each in its own environment, so switching engines and back never breaks a working one (#2015, #2016)
+- A pronunciation entry that is stored but not applied yet says so, instead of looking like it did not match (#1949)
+- A bare 500 report now names the backend error class, so two unrelated faults stop filing the same issue (#1773)
+- A rejected dubbing source language now names the code it rejected (#1960)
+- The first-run install log is kept on disk instead of vanishing with the setup screen (#1847)
+- `bun run desktop` reclaims port 3900 from a backend the app itself left running, instead of refusing to start (#1974)
+- A dictation shortcut another app already owns now says so, instead of silently doing nothing (#1858)
+- Quitting on Windows is no longer reported as a crash on the next launch (#1898)
+- A Reduce motion switch in Settings, for calm without changing your whole system (#1857)
+- A light theme, and System Auto now follows a light-mode OS instead of staying dark (#1973) — thanks @CoDe-ReDz!
+- Generating from a one-character input now says the input was too short, instead of quoting a convolution error (#1826)
+- First run asks about text size before the install, not after it (#1849)
+- Cloning without a reference clip now says so, instead of naming library parameters you cannot set (#1879)
+- Upgrading torch for an RTX 50-series card no longer trades one startup crash for another, and the upgrade is documented (#1931)
+- A generation timeout now points at the compute-time budget in Settings rather than an environment variable (#1808)
+- An engine you have not installed now says so, instead of reporting a failed check (#1866)
+- The Accessibility prompt no longer floats over first-run setup and every other app until you grant it (#1845, #1886)
+- The last onboarding step offers to install a speech-to-text model instead of failing three times when none is installed (#1856)
+- A download that fails because the folder sits behind a mount point Windows will not cross now says so, and where to move it (#1957)
+- A GPU that is merely short on free memory is no longer told to reinstall its drivers (#1812) — thanks @michaelhuamanflores!
+- An error thrown by a browser extension is filtered on Safari and the macOS app too, not only on Chromium (#1901) — thanks @Chang-Jin-Lee!
+- Choosing the China mirror no longer re-races the network on every dependency step, which cost seconds per step on blocked connections (#1892) — thanks @yuezheng2006!
+- The backend log panel reports a log it cannot read instead of quietly showing less (#1847) — thanks @Chang-Jin-Lee!
+- The floating dictation bubble adds pause, resume, stop, close, and a multiline preview (#1952)
+- Transcriptions checks model readiness and offers an inline download and shortcut hints (#1952)
+- Transcriptions' missing-model prompt lists every dictation model by accuracy vs latency, languages and size, so you install the one that fits — or switch to one already on disk (#1952)
+- The Engines menu's Transcription tab picks the dictation model under Sherpa-ONNX, and that choice now also drives Sherpa transcription (#1952)
+- A failure with no stage attached no longer borrows another stage's advice, so a text-to-speech error stops telling you the video server dropped the download (#1943)
+- A generation failure that the app cannot classify now names the backend error class, so two unrelated faults stop arriving as the same untriageable report (#1800)
+- Transcriptions dictation wakes the desktop recorder, presents one contextual start action, and centers its microphone icon with the label (#1902)
+- Colab transcription and dubbing now include an explicit ASR model setup step (#1922) — thanks @nidhi-singh02!
+- Apple Silicon now shows one canonical OmniVoice choice in the engine picker while retaining its automatic crash-isolated sidecar runtime (#1913)
+- Validate current-user Windows installers under a standard account on hosted runners (#1883)
+- Model downloads survive a flaky connection instead of restarting from zero (#1940)
+- `bun run dev` recovers on Windows instead of demanding Task Manager (#1941)
+- The desktop app builds and opens from a fresh clone again (#1818) — thanks @flutterkage2k!
+- GPUs with less VRAM than the engine needs no longer get half the compute-time budget a CPU gets (#1806) — thanks @VishvakR!
+- Gallery voice previews play again — the quality guard was rejecting good renders as silent (#1819) — thanks @flutterkage2k!
+- Tilde-separated number ranges are spoken clearly without running their endpoints together (#1821) — thanks @flutterkage2k!
+- Voice modes use themed tabs, with Synthesize and Convert pinned below their scrolling forms (#1823)
+- Fix current-user Windows installer validation and nested resource cleanup (#1873)
+- Keep generated frontend assets available while building the current-user Windows installer (#1881)
+- Voice cloning now starts with a clear upload-or-record choice, reveals recording and reference details only when needed, and keeps sampling controls under Production Overrides (#1817)
+- The first-run welcome line uses an instruction accepted by OmniVoice and VoiceDesign engines (#1861) — thanks @psiberfunk!
+- audio.cpp joins the engine lineup as an opt-in CPU backend for Breeze-TTS-2 (English + Chinese, clone + voice design, explicit Model Catalogue install, no Python venv) (#1891)
+- audio.cpp uses installed native CUDA, HIP, Metal, and Vulkan providers and preserves device routing across remote workers (#1926)
+- Show estimated and measured model, dependency, cache, and temporary disk costs in the engine catalogue (#1718)
+- Preview builds now stay newer than Stable even when automatic post-release version bumps are disabled (#1762)
+- CosyVoice setup guidance now separates downloaded model files from the runtime that makes the engine available (#1761)
+- MCP tools can now keep audio out of agent context by returning files and accepting base-path-confined file inputs (#1760) — thanks @agudmund!
+- Hear a dub line as you type it — an opt-in live preview streams TTS for the edited segment (#1769) — thanks @mvanhorn!
+- Studio gains a Convert method: re-say any clip in one of your saved voices, speech to speech, fully local (#1765) — thanks @mvanhorn!
+- Hardsub video export gains an opt-in karaoke word-highlight caption style (#1764) — thanks @mvanhorn!
+- The batch queue can now watch a folder: new videos dropped into it are dubbed automatically (#1768) — thanks @mvanhorn!
+- The audiobook player now shows the chapter text and highlights the word being narrated (#1766) — thanks @mvanhorn!
+- The dub editor gains a casting board: drag voice chips onto speakers, dropdowns stay in sync (#1767) — thanks @mvanhorn!
 
 ### Changed
+
+- Tauri 2.11.5 with refreshed plugins (dialog, updater, log, opener, positioner, single-instance), React 19.3, TanStack Query 5.102, lucide 1.43, posthog-js 1.428, and the rest of the npm workspace on current minors; jsdom 30, jest-dom 7, concurrently 10, taze 21 (#1952)
+- eslint ignores `src-tauri/`, so a local Tauri build no longer floods `lint:hooks` with parse errors from generated assets (#1952)
+- Casting uses responsive SVG voice cards and searchable speaker menus that stay above surrounding panels (#1823)
+- Dubbing aligns output settings, brings review status forward, and simplifies transcript and glossary editing; Launchpad files and voices reflow into responsive grids (#1823)
+- Transcript segments use three readable rows for text, timing/status and voice controls, with heights that adapt to wrapping (#1823)
+- Dragging the waveform pans horizontally while a click still seeks, keeping the timed transcript aligned (#1823)
+- Bulk segment editing uses searchable voice and language menus, readable language names and a responsive selection toolbar (#1823)
+- Dubbing overlays playback controls on video, combines waveform and transcript in a compact timeline, and removes header/action background fills (#1823)
+- Dubbing uses compact casting, translation and output controls with responsive rows to leave more room for editing (#1823)
+- Export uses grouped format settings, themed track menus and switches, with a pinned filename summary and download action (#1823)
+- Dubbing output settings use icon-labelled switches, themed track and speaker menus, and clearer timing/transcript controls (#1823)
+- Casting voice menus use searchable themed options with SVG preset icons instead of native dropdowns (#1823)
+- Dubbing groups casting and translation controls with readable labels, SVG icons, searchable menus, and compact timeline spacing (#1823)
+- Production Overrides use readable icon-labelled controls and accessible Denoise/Postprocess switches (#1823)
+- Expanded navigation uses a theme-accent tint with subtle static wave gradients (#1823)
+- Convert groups source audio, target voice, and timing options into clearer controls; design choices include theme-matched SVG icons (#1823)
+- The expandable sidebar reveals workspace labels with restrained active states; language menus adapt to multiple columns on wider screens (#1823)
+- Voice design and recording use themed, keyboard-accessible selectors with clearer spacing and labels (#1823)
+- Voice tabs and upload/record controls have subtle SVG motion; Text adds clipboard paste and the upload area fills available height (#1823)
+- The title-bar label cycles through active speech, transcription, and LLM engines; bundled model labels correctly say OmniVoice (#1823)
+- The top-bar Engines panel groups Speech, Transcription, and LLM choices into tabs, with compact memory controls and no duplicate pickers (#1823)
+- Voice Design simplified: the 12-row fine-grained block collapses to one summary line with a five-field editor, English accent and Chinese dialect merge into a single field, and the starting-point chips now show 5 with an overflow toggle (#1793)
+
+### Added
+
+- The audiobook result is now a synced-lyrics player: chapter text follows playback with the current word highlighted and click-to-seek, timed from the render's own chapter durations with a karaoke-style even split — no ASR pass, fully local (#1766) — thanks @mvanhorn!
+- The dub CAST strip expands into a project-level casting board: drag voice chips (clone profiles, design presets, Default) onto speaker rows — or pick from a keyboard listbox — writing the same per-speaker cast fields as the existing dropdowns (#1767) — thanks @mvanhorn!
+- Studio's new Convert method turns a dropped or recorded clip into an existing voice profile's voice, with optional source-duration matching (#1765) — thanks @mvanhorn!
+- Opt-in watch folder on the batch queue: pick a directory once and new videos are auto-enqueued with your last Add-to-queue settings, with pause/stop controls and copy-in-progress protection — files upload as bytes, paths never leave the app (#1768) — thanks @mvanhorn!
+- Hardsub export can now burn karaoke word-highlight captions: an opt-in Line | Karaoke control renders a word-timed ASS sweep from timings persisted at transcription, with an even-split fallback for older jobs and translated tracks, plus a `GET /dub/ass/{job_id}` sidecar (#1764) — thanks @mvanhorn!
+- Windows releases now include an independently updatable per-user MSI that installs and uninstalls without elevation (#1713)
+- Dub segments can now stream live TTS while you edit a translated line — opt-in toggle, existing `/ws/tts` socket, shared generation admission, exports still render at full quality (#1769) — thanks @mvanhorn!
+- Engine status and diagnostic bundles now record loaded execution provider, device, precision, fallback stage, accelerator identity, runtime versions, and parent-process memory visibility (#1717)
+
+### Docs
+
+- PowerShell Docker setup now generates the administrator key without requiring Python on the host (#1993) — thanks @yangfan-yf-yf!
+- The torch upgrade an RTX 50-series card needs is written down, with the second pin file the resolver checks and the command that proves the kernels are there (#1931)
+- Docker quick starts now explain the AMD64-only images and direct Apple Silicon users to the native macOS app (#1921) — thanks @yangfan-yf-yf!
+- audio.cpp (Breeze-TTS-2) is now a documented opt-in engine: prebuilt binary install, explicit GGUF download, voice modes, and the weights' research/non-commercial terms (#1891)
+- `docs/STRUCTURE.md` describes the tree as it is today, and a test now keeps its counts honest (#1981) — thanks @Dawcraft!
+- Local gigastt is now documented as a supported OpenAI-compatible ASR endpoint, with loopback privacy distinguished from remote servers (#1736) — thanks @ekhodzitsky!
+- The CosyVoice guide now states that packaged builds have no one-click runtime installer and records the exact readiness checks exposed by [Discussion 1631](https://github.com/debpalash/VoiceStudio/discussions/1631) (#1761)
+- A production private-API guide now covers pinned containers, root credentials, network isolation, streaming proxies, health checks, upgrades, and benchmark evidence (#1720)
+- RX 6700 XT/gfx1031 over WSL2 ROCDXG is now explicitly unverified until a published end-to-end GPU workload proves the mapped path (#1716)
+
+### Fixed
+
+- One-click engine installs no longer inherit VoiceStudio's own PyTorch pin, which made MOSS-TTS-v1.5 and Confucius4 impossible to install (#2024)
+- Uninstalling a translation engine no longer removes a package VoiceStudio or another engine still needs (#2019)
+- Closing the dictation pill on Windows removes it from the screen: an empty dark rectangle used to stay there, always on top, until the app was quit (#2009)
+- The dictation pill on Windows no longer sits inside a bordered card wider than the pill itself (#2009)
+- Dictation uses the model you picked instead of one remembered from before the backend started, so it stops reporting no speech-to-text model while one is installed — and when none is, the main window offers the download (#2012)
+- The remote-worker loop-responsiveness tests no longer turn a build red over milliseconds of scheduling noise on shared CI hardware (#1990)
+- Remote GPU workers work when the machine running VoiceStudio is on Windows: a staged input is now identified the same way on every operating system, instead of with a path only Windows can read (#2005)
+- The pronunciation list badges an IPA or CMU entry as not applied yet, so you can see it without running a test (#1949) — thanks @utkarsha741!
+- A remote-worker test no longer fails at random on Windows CI: it waited for a background thread by spinning the event loop that thread's work needed (#1990)
+- The isolated backend test session passes on a stock Windows checkout, and CI now runs it there so it stays that way (#1990)
+- Windows contributors can run the test suite without Developer Mode: tests that create a symlink now skip instead of failing with `WinError 1314` (#1990)
+- The crash details dialog now says what the exit code means and what to try, instead of showing a raw number and a log (#1927)
+- A crash report now carries the backend's actual last words: the log tail is captured after the dying process's final output lands, not the instant it exits (#1850)
+- The first-run setup screen no longer mislabels a step when the bootstrap restarts itself: Rust now says which attempt each stage and log line belongs to, instead of the screen guessing from a once-a-second poll (#1900)
+- A port-3900 conflict now names who is actually holding it, and gives the command that ends an orphaned backend, instead of telling you to quit an app that has no window (#1933) — thanks @Chang-Jin-Lee!
+- Windows desktop launches no longer freeze at "Loading ML runtime (PyTorch)": the parent-liveness watchdog polls the stdin pipe instead of leaving a read pending, which deadlocked numpy's OpenBLAS initializer (#1952, #1955)
+- `bun desktop-prod` and `bun desktop-fresh` find Rust and uv from a terminal opened before they were installed, as `bun desktop` already did; a missing Rust toolchain fails up front with the install steps (#1952)
+- Voice synthesis progress no longer races to a fabricated 95%; it stays indeterminate until the active generation path reports real progress (#1907) — thanks @psiberfunk!
+- The Backend log tab keeps showing history across a log rollover, instead of going nearly empty until new lines arrive (#1920)
+- Clearing the logs now empties the rotated log files too, so it frees the space it appears to (#1920)
+- An error thrown by a browser extension no longer offers to file itself as a VoiceStudio bug (#1901)
+- Clearing the desktop logs no longer wipes the backend's stderr, which is the only record a native crash leaves behind and is meant to survive a respawn (#1510)
+- Long audiobook chapters now use the same device- and text-length-aware synthesis timeout as other TTS routes (#1910) — thanks @psiberfunk!
+- Interrupted audiobook renders can resume cached chapters after tab navigation, and their chapter cache is available from the recovery card (#1911) — thanks @psiberfunk!
+- System-check details and storage paths beginning with a number or a slash no longer render with their leading text moved to the end of the line (#1848) — thanks @psiberfunk!
+- An unavailable engine's row now links to that engine's guide, so the generic "check installation and configuration" message has somewhere to send you (#1866) — thanks @psiberfunk!
+- The backend log now records which engine failed a health check and whether its probe raised, instead of a line that identified neither (#1866) — thanks @psiberfunk!
+- The first-run Activity log counts every line instead of freezing at 200 while the install is still running, and Copy now hands back the whole run rather than the last 200 lines (#1847) — thanks @psiberfunk!
+- A first-run failure that happened early in a long install keeps its specific advice, instead of falling back to the generic retry hint once the log scrolled past 200 lines (#1847) — thanks @psiberfunk!
+- Opening the log panel no longer clips the Launchpad's heading and slides the feature cards up over it — the page scrolls instead of squashing itself (#1859) — thanks @psiberfunk!
+- Segmented model downloads split files into 16 MB ranges instead of one range per connection, so a dropped connection refetches one range rather than restarting the file (#1940)
+- The download accelerator is kept across retries after a transient network failure and resumes from its manifest, instead of falling back to a from-zero `snapshot_download` (#1940)
+- `dev-backend.mjs` stops the backend by process tree on Windows, so an orphaned uvicorn no longer holds port 3900 and turns a source reload into three phantom crashes (#1941)
+- `clear-dev-ports.mjs` can free a stuck development port on Windows again, bound to the inspected process instance so a recycled pid is never terminated (#1941)
+- Checkout-ownership matching no longer resolves POSIX paths with the host's separator, which made the guard's own test fail on Windows (#1941)
+- Install documentation help now prints correctly on Windows consoles using legacy encodings (#1815) — thanks @dajiaohuang!
+- Saved transcriptions with missing or invalid timestamps now remain readable (#1799) — thanks @yunaremaia and @tvbht!
+- Transcribing with an engine that reports no segment end no longer fails with a server error; the null timing is passed through the way the segment list already expects (#1904) — thanks @aeroglu!
+- Copying a saved transcription now uses the shared clipboard helper and reports failed copies accurately (#1803) — thanks @tvbht!
+- Voice reference preparation reclaims allocator memory before one bounded retry, then reports persistent GPU out-of-memory failures (#1811)
+- `bun run desktop` now opens on a fresh clone: the Vite alias for `@tauri-apps/plugin-dialog` no longer assumes a nested `frontend/node_modules`, which bun's workspace hoisting leaves empty (#1818) — thanks @flutterkage2k!
+- Slow backend startups remain running with progress updates, and Retry interrupts startup without stale timeout failures (#1809)
+- Backend connection errors report crashes only when recorded evidence exists, and diagnostic waits honor cancellation (#1810)
+- A CUDA or ROCm GPU with less VRAM than the engine needs now gets the CPU compute-time budget instead of the shorter accelerated one, since it pages to system RAM and renders slower than the CPU would — applied to local generation, voice conversion, and remote worker deadlines alike (#1806) — thanks @VishvakR!
+- Gallery previews no longer fail with "the voice engine returned no audible audio" on perfectly good renders: the degenerate-buzz guard measured spectral flatness over the whole clip (so the value tracked clip length) against a threshold calibrated on a synthetic signal, and rejected real speech in every language tested (#1819) — thanks @flutterkage2k!
+- Speak tilde separators in integer, signed, and decimal ranges in English, Korean, Japanese, and Chinese (#1821) — thanks @flutterkage2k!
+- Keep recording and conversion work safe while switching methods, synchronize dubbing language controls, and localize timeline controls and timing warnings (#1841)
+- Audiobook is now a Write → Cast → Produce tab workspace matching the voice workspace, with the warnings/progress/result rail pinned below (#1841)
+- Gallery uses a workspace header with zone tabs, hairline section dividers, theme-token cards, and borderless import rows (#1841)
+- Gallery cards reset native button faces, cluster icon actions in the header so Use voice never wraps, and use a roomier grid floor (#1841)
+- Gallery filters gain name search, removable iconified pills with clear-all, and dimension icons on every facet (#1841)
+- Dubbing playback starts before waveform decoding, automatic cast names are readable, and transcript timestamps have more room (#1823)
+- The title-bar engine button stays compact and stable while cycling labels, with engine names aligned right (#1823)
+- Long dubbing segment errors wrap in a bounded scrollable notice instead of widening the editor (#1823)
+- Voice dropdowns match their field width, use theme accents, and show recent voices only once (#1823)
+- Language menus no longer show a pale frame around their search header (#1823)
+- The notification count stays inside the title bar instead of clipping above the bell (#1823)
+- The workspace engine menu opens beside its button instead of at the opposite edge of the page (#1823)
+- Cloning reuses the dubbing language picker with flags, search, and single selection, opening above the pinned synthesis controls (#1823)
+- The first-run welcome line uses an instruction accepted by OmniVoice and VoiceDesign engines (#1861) — thanks @psiberfunk!
+- The header status dot now honors OS Reduce Motion instead of pulsing regardless (#1862) — thanks @psiberfunk!
+- Onboarding reads Hugging Face tokens locally, preserves Windows CLI logins, and requires successful discovery before replacing saved credentials (#1852) — thanks @psiberfunk!
+- The logs panel no longer reports “All clear” before log retrieval succeeds or while logs contain warnings or errors (#1870) — thanks @motodriver!
+- MOSS accelerator routing and status match runtime selection, with CPU fallback when device probing fails (#1830) — thanks @li-lizhe!
+- Confucius accelerator routing tolerates failed device probes, and dots.tts keeps safe default precision on non-CUDA hosts (#1831) — thanks @li-lizhe!
+- On macOS, the header status dot and kicker no longer render underneath the overlaid traffic lights (#1863) — thanks @psiberfunk!
+- The capture widget can hide after recording and recover from being left visible while idle (#1865) — thanks @psiberfunk!
+- macOS retains the shared desktop window sizing, resize limits, and file-drop behavior when native chrome is applied (#1865) — thanks @psiberfunk!
+- On macOS, the header no longer shows Windows-style minimize/maximize/close buttons alongside the native traffic lights (#1865) — thanks @psiberfunk!
+- Release retries replace their own partially uploaded installers without colliding with existing assets (#1871)
+- Timed-out voice engines finish process cleanup before retrying, and old timeout callbacks cannot kill replacement engines (#1872)
+- Fast macOS process exits no longer turn a completed shutdown into a permission error (#1809)
+- The bootstrap splash no longer shows fabricated first-run install steps on a warm start or repair sync — a step now renders done only once it was actually observed (#1894)
+- A deliberate, clean quit killed by the desktop shell's short shutdown grace no longer gets reported as a crash on next launch — the run sentinel now clears before the slower shutdown steps instead of after (#1895)
+- Model Catalogue engine rows stack into one column on narrow shells instead of clipping actions off-screen (#1891)
+- Simplified Chinese locale completed: all 486 missing keys translated and the parity ratchet tightened to zero (#1877) — thanks @yearth!
+- The generation compute-time budget is now a Settings control (Performance & Device) instead of an env-var-only setting the timeout error recommended with no UI path — the error copy points there too, and long CPU/MPS renders get an upfront heads-up before they start (#1787)
+- Windows: the backend can now start when the install path contains non-English characters (e.g. a CJK username) on a non-UTF-8 system code page — a new or broken Python environment now builds at an ASCII-safe path automatically (a healthy existing one is never relocated), and a specific error message names the cause and a working fix if the interpreter still crashes in `site` (#1783)
+- Exports and other native-picker actions no longer 403 with "Invalid or expired desktop authorization" when the desktop app and backend resolve different data directories, e.g. dev mode or a custom data folder (#1781)
+- Voice Design no longer lets you pick a Chinese dialect and an English accent together — the picker keeps them mutually exclusive instead of round-tripping a 400 (#1771)
+- The desktop app no longer attaches to an already-running backend on version string alone: it now verifies the backend's actual code fingerprint too, so an orphaned or manually started backend reporting the current version but running older code (e.g. a stale `destination_path` export 422) gets replaced instead of adopted (#1770)
+- Korean locale overhauled: 231 mistranslations corrected and all 493 missing keys translated (#1776) — thanks @j30231!
+- Japanese "Cleaning…" clone status now reads as denoising instead of housekeeping (#1775) — thanks @j30231!
+- The batch dubbing queue now has a UI entry point — a quiet link on the Dub landing (it was previously unreachable: the app switched on a mode nothing ever set) (#1768) — thanks @mvanhorn!
+- OpenAI-compatible ASR now requires HTTPS outside loopback and refuses redirects so audio stays on the configured origin (#1736)
+- Windows isolated engines now retain direct Job ownership without an extra Python supervisor process that can deadlock the child loader (#1734)
+- The setup splash now waits through the backend's full startup budget instead of reporting slow Windows CUDA initialization as stuck after two minutes (#1749)
+- Dubbing jobs can now reuse every source-language code produced by automatic ASR detection without a 400 error on the next upload (#1737)
+- Incomplete Sherpa-ONNX model snapshots now self-repair before recognizer startup instead of failing on a missing ONNX file (#1733)
+- OmniVoice subprocess startup now allows slow packaged Windows Python runtimes to signal readiness before termination (#1711)
+- SRT files selected during source analysis now wait for speaker cloning, then replace transcript text without losing voices (#1709)
+- Windows MSI deployments can now prohibit WebView2 bootstrap with `DISABLEWEBVIEW2BOOTSTRAP=1`, and `AUTOLAUNCHAPP=0` reliably suppresses first launch (#1714)
+- Subtitle rows now provide 100 ms timing steppers and flag adjacent overlaps without requiring precise timeline dragging (#1710)
+- Repair-sync failures now retain uv's final dependency error instead of reporting only an opaque exit status (#1705)
+- YouTube ingest now retries yt-dlp's transient “page needs to be reloaded” response (#1706)
+- Dictation model readiness now follows the live Hugging Face cache selected in Settings (#1707)
+- Dictation capture now queues native events whenever its webview listener unmounts or reloads instead of emitting them to nobody (#1707)
+- Desktop-contained backends now exit when their owning app disappears instead of surviving as stale port-3900 processes (#1707)
+
+## [0.5.1] — 2026-08-28
+
+**Highlights**
+
+- OmniVoice generation on Apple Silicon now runs in a crash-isolated child, so fatal MPS memory exits no longer take down the local backend (#1697, #1698) — thanks @ndntran14!
+- Model-load GPU exhaustion now returns a sanitized, actionable dubbing error, and readiness correctly attributes the shared model status to TTS (#1695)
+- Source-mode development now restarts an isolated backend crash without tearing down the UI, while repeated crash loops still stop loudly with diagnostics (#1690)
+- Dubbing playback now keeps an audible companion source when a WebView can render the preview picture but cannot decode its audio (#1692)
+- Model Catalogue engine rows now use the available desktop width and keep identity, runtime state, and actions from crowding one another (#1689)
+- VoiceStudio now acts as a local speech platform: other apps can trigger its native dictation or connect through versioned HTTP, WebSocket, JSON-RPC, CLI, and MCP transports (#1646)
+- A timed-out in-process dub transcription no longer starts a second WhisperX/CTranslate2 call over the abandoned native worker, preventing the overlapping access that preceded Windows `0xC0000005` exits (#1669)
+- Windows debugger termination code `0x40010004` is no longer misreported as a backend crash or charged against automatic restart recovery (#1663)
+- Studio now keeps one generation reservation across page changes, preventing a remount from stacking native jobs until the backend reports capacity busy or is killed under memory pressure (#1670)
+- Uploaded dubbing videos are normalized to browser-safe H.264/AAC before preview, preventing valid VP9, AV1, or Opus media from failing with “no supported sources” (#1644)
+- Dubbing now separates spoken and target languages, preserves translations through segment cleanup, and lets failed translations be retried or skipped without restarting the batch (#1654) — thanks @Number16BusShelter!
+- Importing replacement SRT subtitles now keeps each cue bound to the best-overlapping source speaker and clone instead of resetting every line to a random default voice (#1660) — thanks @invio-a11y!
+- Uploading a Dub preview no longer blocks every backend request while ffmpeg extracts its audio (#1667) — thanks @tfreyd!
+- Docker quick starts now require the administrator key needed through container NAT instead of starting a UI whose protected actions return 403 (#1651) — thanks @wd357dui!
+- WSL2 AMD containers now use the `/dev/dxg` ROCDXG bridge with actionable GPU diagnostics instead of silently falling back to CPU (#1655) — thanks @wd357dui!
+- Ad-hoc voice-clone references now stay alive until cancelled or timed-out GPU work actually stops reading them, so prompt caching can finish instead of failing on a deleted temp file (#1668) — thanks @tfreyd!
+- Dictation now stays bound to the app where it started and recovers locally from silent recognizer output (#1175)
+- The backend now answers within a second of launch and narrates its startup step by step (#1550)
+- Reporting a bug from an outdated build now offers the latest release first (#1547)
+- The backend is only announced ready once it can actually serve, and crash-loop restarts now pace themselves (#1548)
+- Invisible watermarking no longer stalls — or silently skips — the first take of a session (#1615)
+- Dub subtitles can be retimed, inserted, and merged in either direction from the segment table (#1612) — thanks @invio-a11y!
+
+### Changed
+- Model Catalogue now uses one breathable workspace canvas with simpler pane and engine-family navigation instead of nested cards and scroll regions (#1685)
+- Linux source launchers now catch missing libxdo and GStreamer audio plugins before they can cause a linker error or an aborted, blank WebKit renderer (#1680, #1682)
+- Dictation now carries one native output session from shortcut-down through final delivery, restores text, HTML, image, or file-list clipboards only when untouched, keeps Wayland copy-safe unless current-focus insertion is explicitly enabled, and retries silent Sherpa speech only through an already-installed local ASR model (#1175)
 - The backend binds its port immediately and reports startup progress live — `/health` answers 503-with-step and a new `/startup/progress` endpoint lists every step while PyTorch, API routes, and database migrations load in the background, so "starting at step X" is never mistakable for "dead"; the desktop splash narrates each step (#1550)
 
 ### Added
+- A bundled Rust loopback sidecar exposes dictation start/stop/toggle, focused-output sessions, discovery, and JSON-RPC; the backend adds versioned streaming events and a dependency-free CLI bridge for Herdr, coding agents, editors, desktop apps, and TUIs (#1646)
+- Headless NVIDIA and ROCm machines can now join as worker-only Docker Compose services with no published UI and durable protocol-v2 enrollment; update both machines together before reconnecting (#1638) — thanks @jkrogers9862!
+- Linux ARM64 (Asahi Apple Silicon) support for the OmniVoice GGUF engine — a `linux-aarch64` binary built with GGML Vulkan where the toolchain allows it, so Apple GPUs accelerate generation through the open-source Honeykrisp driver instead of falling back to CPU-only (#1641)
+- One-command install on every desktop OS: `curl -fsSL https://voicestudio.sh/install | sh` (macOS/Linux/WSL) or `irm https://voicestudio.sh/install | iex` (Windows) — the URL serves the right script per platform, and Windows gains a source installer (`scripts/install.ps1`) with a 3-OS CI smoke (#1626)
+- Per-line subtitle management in the dub table: a line's end time is editable alongside its start (typing a time and dragging its timeline edge now take the same path), lines merge with the previous row as well as the next (`Ctrl/Cmd+Shift+M`), and a new line can be inserted into the gap after any row (#1612) — thanks @invio-a11y!
+- CI now enforces performance regression budgets on the hot paths — operation-count tests pin streaming TTS to one synthesis per sentence and cached dub re-mixes to zero re-synthesis; fast-path guards cover zero re-decoding and ⌈N/W⌉ native batch calls when enabled (#1594)
+- Default-engine dubbing now synthesizes several segments per forward pass instead of one call per line — the width follows the host's device headroom (1 on CPU and low-VRAM cards, up to 8), `OMNIVOICE_DUB_BATCH_WIDTH` overrides it, and engines without native batching keep the single-segment path (#1594)
+- `/ws/tts` now reports real time-to-first-audio, and its RTF measures synthesis alone so a slow client can't inflate it (#1594)
+- The locally cached AudioSeal watermark generator warms on a background thread ~35s after boot (`OMNIVOICE_PRELOAD_WATERMARK=0` opts out; explicitly setting `=1` may download it), so the first synthesis no longer serializes the audioseal import + model load inline — measured at ~42s on a cold filesystem, 3s short of a 90s client timeout (#1576) — thanks @paoloantinori!
+- Voices you've cloned stay "warm" across restarts — encoded references now persist to disk (~10 KB each), so the first generation of a session skips the re-encode and any transcription pass; `OMNIVOICE_PROMPT_DISK_CACHE=0` opts out (#1565)
+- Optional FlashInfer acceleration for the default engine on CUDA (`OMNIVOICE_FLASHINFER=1`, ~2.2x measured) — needs the optional `flashinfer-python` package; missing package or kernel failure logs why and falls back to the standard path (#1565)
 - The bug reporter notices when you're on an outdated build and offers the latest release before filing — with a "File anyway" escape hatch — and stamps a `Build status` line into every report so up-to-date reports are tellable from stale ones (#1547)
 - Settings → Performance & Device gains a compute-device override (Auto / CUDA / ROCm / XPU / MPS / CPU, or `OMNIVOICE_DEVICE`) — pin the device when auto-detect picks wrong; only devices your machine actually has are offered (#1557)
+- Opt-in 24-layer PocketTTS checkpoints via `OMNIVOICE_POCKETTTS_24L` — better prosody for it/de/es/pt at roughly 2x render time (still faster than real-time); the fast 6-layer model stays the default (#1613) — thanks @paoloantinori!
 
 ### Docs
+- Supported-version and install guidance now identifies 0.5.1 as the stable desktop and container release (#1687)
+- The Docker Hub overview now shows the current engine-switching demo, Model Catalogue, and gallery voice workflow (#1593)
+- The Docker Hub overview and install guide now show the v0.5 tags and the built-in API-key/share-PIN security model instead of obsolete v0.4 and no-authentication guidance (#1592)
 - The READMEs now lead with download buttons and a three-step first-clone walkthrough, and a new benchmarks page anchors measured per-engine/per-device numbers on the in-repo harness (#1555)
 - Every engine now has its own guide — 21 new pages under docs/engines plus an index covering all 16 TTS and 11 ASR engines, linked from both READMEs (#1556)
+- The OmniVoice guide now covers combining style attributes with a reference clip (consistent instruct stabilizes cloning; the reference wins conflicts), inline pronunciation control (pinyin / CMU phonemes), and corrects the claim that the default engine can't do voice design — it can, from attributes (#1565)
 
 ### Fixed
+- Workspaces now measure their responsive width when the post-bootstrap shell actually mounts, so native UI scaling reflows Projects and History instead of crushing the Dubbing demo into unreadable columns (#1683)
+- Dubbing keeps the source-language selector visible after a local file is chosen, so ASR can be pinned before transcription starts (#1678) — thanks @Lonki-lomki-cloud!
+- First-run media-engine downloads become available to TTS immediately without a restart, and missing media-process failures now point to repair controls (#1677) — thanks @farhataligpt-dev!
+- Source installs on AMD GPUs honour `OMNIVOICE_TORCH_VARIANT=rocm`: `bun run desktop` now swaps in the ROCm torch wheel after `uv sync` and launches the backend without re-syncing, instead of silently reverting to the CPU-only CUDA build on every start (#1665) — thanks @uberclokr!
+- `bun run desktop` on a fresh clone no longer fails with "resource path `../../frontend/dist` doesn't exist" — the dev launcher creates the placeholder Tauri resource directory before compiling (#1664) — thanks @uberclokr!
+- macOS no longer loses TTS after the first request when Python lacks `os.waitid`; subprocess ownership now uses a safe `waitpid` fallback without risking reused process groups (#1656) — thanks @paoloantinori!
+- Desktop startup, Retry, reset, uninstall, shutdown, and crash recovery now share one backend lifecycle owner; quitting interrupts first-run installers and gracefully drains then force-cleans the full backend process tree, so overlaps cannot duplicate or orphan it (#1635) — thanks @Xohaibxobi!
+- Large Stories and Audiobook projects now persist in IndexedDB instead of overflowing the `omnivoice.app` localStorage envelope, with quota-safe migration and orderly exit/reload flushing (#1636) — thanks @leodzai!
+- OmniVoice and its crash-isolated subprocess now route to AMD ROCm GPUs instead of warning and falling back to CPU (#1629) — thanks @j4r3kb!
+- Dictation now cancels pending startup work, capture resources, sockets, and timers when the capture widget closes, preventing late work against a destroyed webview (#1645)
+- Streaming generation failures now show recognized recovery guidance and appear in Diagnostics instead of only returning a generic error (#1607)
+- The worker-capacity transport test no longer races its own setup: the 1-slot limit now goes through the enrollment handshake instead of mutating client config after connect, where the server's stream-open ConfigUpdate (carrying the registered capacity of 2) could overwrite it and fake an over-accept; failed CI twice on 2026-08-21 (#1630)
+- Moving words across a speaker boundary in a dub — merging two lines and splitting them again — no longer dubs the second half in the first speaker's voice; each half now keeps the speaker, voice, direction, gain, and language of whoever actually says it (#1612) — thanks @invio-a11y!
+- Dictation on a WebView that refuses a 16 kHz audio context (WKWebView) now low-passes before downsampling, so frequencies above 8 kHz stop folding into the speech the recognizer is fed (#1610)
+- A microphone context that cannot be resumed now reports a mic error instead of leaving the dictation pill on "Listening" while capturing nothing (#1610)
+- Dictation no longer retains a whole session's audio for silent-model recovery — an open mic grew that buffer by ~115 MB an hour; the recent two minutes are kept instead (#1610)
+- The clipboard-delivery status is now translated in all 21 languages, so Wayland users — where clipboard delivery is the default — no longer see an English string (#1610)
+- A native sherpa-onnx load failure of any exception type now degrades to "engine unavailable" instead of taking the dictation WebSocket down (#1610)
+- Dictation now ships Whisper Tiny as its one cross-platform default, avoiding Parakeet's measured empty decoding on Windows while keeping Parakeet selectable behind runtime fallback (#1175)
+- Re-mixing a dub no longer decodes, rewrites, and re-reads every cached segment — same-rate cached audio is reused directly (and rejected if truncated), switching timing modes can't reuse slot-truncated audio as natural-rate, and RVC respects natural-rate modes (#1594)
+- PocketTTS French works again — pocket-tts only ships a 24-layer French model and rejected the name the sidecar asked for, so every French request failed at model load; French now always loads `french_24l` (#1613) — thanks @paoloantinori!
+- Installing IndexTTS 2.5 no longer fails claiming an interrupted download — the weights repo ships `config.yaml` and VoiceStudio demanded a `config_v2_5.yaml` that exists in no upstream release; both names are accepted, so a hand-renamed checkout keeps working (#1611) — thanks @zuiaiyutu!
+- IndexTTS 2.5 no longer has long-text generation killed at 60 seconds — the sidecar now proves it is alive every 5 seconds while `infer()` runs, and its deadline rises to 900s (`OMNIVOICE_INDEXTTS_RECV_TIMEOUT_S`) (#1611) — thanks @zuiaiyutu!
+- The OpenAI-compatible `/v1/audio/speech` route now reuses the shared cached engine for explicit `model` ids instead of constructing a fresh engine — and its sidecar/model load, a ~28s floor per call for subprocess engines — on every request, with the same single-engine-resident discipline `/generate` applies (#1614) — thanks @paoloantinori!
+- The setup wizard's RAM check no longer blocks 8 GB machines whose OS reports ~7.8 GB usable — the thresholds now tolerate reserved memory, and `OMNIVOICE_RAM_PREFLIGHT=0` turns a genuine block into a warning for those who accept the OOM risk (#1618)
+- Invisible watermarking now runs eagerly instead of through `torch.compile` — AudioSeal's lazy compile sent the first embed of every session into Inductor's C++ codegen, which failed outright on macOS hosts whose toolchain couldn't serve it and shipped the audio unmarked after a 30-40s wait; first embed drops from 9.70s to 0.26s (#1615) — thanks @paoloantinori!
+- The macOS Accessibility blocker now rechecks while visible and closes as soon as the grant is enabled instead of keeping a stale permission prompt on screen (#1609)
+- The dubbing editor's video and transcript columns can now be resized by pointer or keyboard, and the chosen split persists across launches (#1571) — thanks @invio-a11y!
+- CPU-only synthesis now gets a bounded ten-minute execution budget, and a render that exhausts it is reported as a compute timeout instead of misleading "generation capacity is busy" queue pressure (#1588) — thanks @ChienNguyen1111!
+- Rapid Launchpad ↔ Dub navigation now replaces the workspace DOM owner cleanly, so late media/waveform cleanup cannot trigger React's `insertBefore` crash (#1590) — thanks @nicolas-jacques!
+- Watermark embedding failures now log the full traceback instead of just the exception message, so a silently-unmarked-audio incident (audio passes through unmarked by design) is diagnosable from the log alone (#1576) — thanks @paoloantinori!
+- Dubbing now recovers rapid two-speaker exchanges when diarization collapses them, defaults new projects to lip sync without overwriting saved timing choices, and keeps the editor usable on narrow screens (#1584) — thanks @victordonat0!
+- `OMNIVOICE_ASR_BACKEND=omnivoice` now selects the PyTorch-native Whisper path, so the documented ROCm escape hatch no longer fails as an unknown engine (#1582) — thanks @patmansk!
+- Network Sharing from Windows MSI/portable installs now serves the bundled web interface to LAN devices instead of redirecting them to their own `localhost` (#1589) — thanks @TWIISTED-STUDIOS!
+- Exported dubbed videos now mark the dubbed language as the default audio stream while keeping Original available as an explicit choice (#1575) — thanks @invio-a11y!
+- Cloning references can no longer exhaust system memory: transcript-free clips up to 75 seconds are searched in five bounded passages, longer clips ask to be trimmed, and supplied transcripts remain capped at 20 seconds to preserve alignment (#1578) — thanks @ACKAPOB!
+- Stored artifact subpaths now resolve after moving a data directory between Windows, macOS, Linux, and Docker, while traversal and symlink escapes remain blocked (#1559) — thanks @Eman-Yousaf!
+- A remote browser hitting an API-key-configured server's admin 403 now gets the API-key login form instead of endless console 403s, while desktop and PIN-only/no-key servers keep the plain loopback error so guests are never offered a login no key can satisfy (#1568) — thanks @paoloantinori!
 - The crash-isolated ASR sidecar and its download preflight now agree on which model to load — setting the shared faster-whisper model variable applies to both variants instead of the sidecar quietly using a different one (#1556)
 - "Ready" now requires the deep health probe (a working database-backed route), not just the identity probe — a backend whose install broke underneath can no longer be announced up while every real request fails (#1548)
 - Supervisor restarts after repeat crashes now back off (immediate, then 5s, then 15s) instead of respawning back-to-back, so a tight crash loop can't burn the whole restart budget in seconds (#1548)
+- The Linux desktop cleanup regression test now isolates build artifacts, so an existing developer build can no longer change its result (#1566)
+
+- Renaming, deleting, or revoking consent on a voice (and starring/clearing history, recording exports) now live-updates every open tab again — the sync routes' WebSocket events were silently dropped, which could look like "all my voices are gone" (#1561) — thanks @paoloantinori!
+
+### CI
+- Project agents now share pinned Vite and FastAPI skills from skills.sh (#1594)
+- Weekly full-history secret scans no longer mistake the Ed25519 private-key type name for committed key material (#1591)
 
 ## [0.5.0] — 2026-08-13
 
@@ -241,7 +538,7 @@ the frozen-backend fallback mirror it for their toolchains.
 - The stdio wire protocol every engine sidecar speaks is now tested once across all nine of them, instead of against a single engine — a bug in any one sidecar's copy gets caught — thanks @paoloantinori! (#1408)
 - Windows smoke tests stopped silently passing a broken ffmpeg install, and every smoke leg is now budgeted for a cold dependency install. (#1290)
 - Test suites no longer leak config paths or model-manager shutdown state into one another, which had been failing unrelated pull requests. (#1269)
-- The nightly preview build stopped refusing to publish its own healthy updater manifest when the macOS legs finished a few minutes ahead of the slowest one — Preview-channel users were silently left without new builds.
+- The nightly preview build stopped refusing to publish its own healthy updater manifest when the macOS legs finished a few minutes ahead of the slowest one — Preview-channel users were silently left without new builds. 
 
 ## [0.4.2] — 2026-07-28
 

CLAUDE.md

@@ -66,7 +66,10 @@ Architecture not yet mapped. Follow existing patterns found in the codebase.
 <!-- GSD:skills-start source:skills/ -->
 ## Project Skills
 
-No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`, or `.codex/skills/` with a `SKILL.md` index file.
+- `vite` — Vite configuration, assets, HMR, builds, and Vitest guidance.
+- `fastapi-python` — FastAPI and Pydantic implementation patterns.
+
+Canonical copies live under `.agents/skills/`; `skills-lock.json` pins their sources and hashes. Claude should follow these paths directly, avoiding cross-platform symlinks.
 <!-- GSD:skills-end -->
 
 <!-- GSD:workflow-start source:GSD defaults -->

LICENSE-NOTICE.md

@@ -10,10 +10,10 @@ Copyright 2024-present Palash Debnath and VoiceStudio contributors.
 
 VoiceStudio is **free and open-source software, licensed under the GNU
 Affero General Public License, Version 3 (AGPL-3.0)**. You are free to use,
-copy, modify, and redistribute it — and that **includes commercial and internal
-business use**: run the app, use its outputs commercially, sell the audio you
-produce with it, provide professional/client services with it, and deploy it
-within your organization.
+copy, modify, and redistribute it. That **includes commercial and internal
+business use** of the application itself. Model weights, tokenizers, and other
+third-party assets retain their own terms; this application license does not
+grant or summarize rights under those separate terms.
 
 Because this is the **Affero** GPL, one additional obligation applies: if you
 modify VoiceStudio and make that modified version available to others over
@@ -41,6 +41,12 @@ is **separately licensed under Apache License 2.0** by its upstream authors and
 is not relicensed here. Apache License 2.0 is compatible with, and may be
 combined under, the GNU AGPL-3.0. See `pyproject.toml`.
 
+Downloaded model weights are not relicensed by VoiceStudio. The default
+`k2-fsa/OmniVoice` model card identifies its code as Apache-2.0 and pretrained
+weights as CC-BY-NC. Its `audio_tokenizer/LICENSE` contains separate Boson
+Higgs Audio 2 and Meta Llama community terms. A commercial license for
+VoiceStudio-owned code does not replace any of those terms.
+
 Third-party dependencies retain their own licenses. See `Cargo.lock`,
 `bun.lock`, and `uv.lock` for the resolved set.
 

README.md

@@ -1,24 +1,30 @@
 <div align="center">
-  <img src="docs/logo.png" alt="VoiceStudio logo" width="120" height="120" />
+  <p><img src="docs/logo.png" alt="VoiceStudio logo" width="120" height="120" /></p>
   <h1>VoiceStudio</h1>
+  <p>
+    <a href="https://trendshift.io/repositories/28176?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-28176" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/28176" alt="VoiceStudio ranking on Trendshift" width="220" height="48" /></a>
+  </p>
   <p><sub>Previously OmniVoice-Studio</sub></p>
-  <h3>Local voice cloning, dubbing, dictation, and long-form audio.</h3>
-  <p>16 TTS engines · 11 ASR engines · 646-language catalogue · macOS, Windows, and Linux</p>
-  <p><strong>Local-first.</strong> No account, API key, subscription, or usage meter for the core workflow.</p>
+  <h3>Clone voices, dub video, dictate, and produce long-form audio on your own hardware.</h3>
+  <p>16 TTS engines · 11 ASR engines · 646-language catalogue · macOS, Windows, Linux, and Docker</p>
+  <p>No account, API key, subscription, or usage meter for the local workflow.</p>
 
   <p>
     <a href="#install">Install</a> ·
     <a href="#features">Features</a> ·
     <a href="#comparison">Compare</a> ·
     <a href="#requirements">Requirements</a> ·
+    <a href="#hardware-recommendations">Hardware</a> ·
     <a href="#engines">Engines</a> ·
     <a href="#architecture">Architecture</a> ·
     <a href="#api">API</a> ·
     <a href="#documentation">Docs</a> ·
+    <a href="#faq">FAQ</a> ·
     <a href="README_CN.md"><strong>简体中文</strong></a>
   </p>
 
   <p>
+    <a href="https://github.com/debpalash/VoiceStudio/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/debpalash/VoiceStudio/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status" /></a>
     <a href="https://github.com/debpalash/VoiceStudio/stargazers"><img src="https://img.shields.io/github/stars/debpalash/VoiceStudio?style=flat-square&color=f59e0b" alt="GitHub stars" /></a>
     <a href="https://github.com/debpalash/VoiceStudio/releases"><img src="https://img.shields.io/github/downloads/debpalash/VoiceStudio/total?style=flat-square&color=8b5cf6&label=downloads" alt="Total downloads" /></a>
     <a href="https://github.com/debpalash/VoiceStudio/releases/latest"><img src="https://img.shields.io/github/v/release/debpalash/VoiceStudio?style=flat-square&color=10b981" alt="Latest release" /></a>
@@ -36,7 +42,7 @@
 </div>
 
 > [!WARNING]
-> **Active beta.** Use the [latest release](https://github.com/debpalash/VoiceStudio/releases/latest) for stable work or `main` for current fixes. Report problems through [GitHub Issues](https://github.com/debpalash/VoiceStudio/issues).
+> **Active beta.** Use the [latest release](https://github.com/debpalash/VoiceStudio/releases/latest) for stable work. `main` contains the newest fixes and may change between releases. Report problems through [GitHub Issues](https://github.com/debpalash/VoiceStudio/issues).
 
 ## At a glance
 
@@ -49,33 +55,70 @@
 | **Compute** | CUDA · Apple Silicon MPS/MLX · ROCm on Linux · CPU · optional remote workers |
 | **Interfaces** | Desktop app · local REST/SSE/WebSocket API · OpenAI-compatible audio API · MCP Server |
 | **Storage** | Voices, projects, settings, and outputs stay on the machine by default |
-| **License** | AGPL-3.0; optional engines keep their own model licenses |
+| **License** | AGPL-3.0 application; downloaded models keep their upstream terms |
+
+The Voice workspace starts with three tabs: **From audio** for cloning, **By design** for creating a voice, and **Convert** for speech-to-speech conversion. Each tab displays its own workflow, with Synthesize Audio or Convert pinned below the scrolling form. The top-bar **Engines** panel combines engine selection, loaded models, and unload/flush controls; <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>E</kbd> opens it. The searchable language picker shares Dubbing’s flags and language list layout, selects one output language, and retains Auto and the full cloning catalogue. Language options flow into multiple columns when space allows. Expand **Workspaces** in the sidebar to reveal navigation labels; Escape collapses it.
+
+Dubbing starts with file upload or URL import and nearby language choices. Its **Projects** panel lists previous dubs so they can be reopened by clicking anywhere on a card; action buttons operate independently. Advanced import options include captions and optional YouTube sign-in. Dubbing places playback controls over the video with background blur and combines the waveform and timed transcript in one compact editing surface. Drag the zoomed waveform left or right to pan; click to seek. Translation language and ISO-code controls stay synchronized; Auto clears any previous language code and dialect. Transcript items group editable text, timing and status, and voice controls into three readable rows that wrap with the panel width. Output Options stays compact with the active settings shown in its summary; expand it to change output, timing, or voice matching. Transcript, glossary, and paste controls share a toolbar above the segment editor. Project details, workflow steps, and Generate/Verify/Export actions use an unfilled header.
+
+The Audiobook Script editor fills the available workspace beneath its markup toolbar; Voices and Book settings stay in their own tabs.
+
+Output settings use aligned rows; review status appears before the collapsible transcript and glossary. Glossary terms have labelled entry fields and an explicit edit action. Launchpad arranges recent files and saved voices side by side when space allows, with responsive card grids and visible Open actions.
+
+The casting board shows icon-based voice cards and searchable selectors for each speaker. Drag a card onto a speaker or choose a voice from that speaker’s menu.
 
 <a id="install"></a>
 
 ## Install
 
+Download a package from the [latest release](https://github.com/debpalash/VoiceStudio/releases/latest), then follow the platform guide.
+
 | Platform | Package | Guide |
 |---|---|---|
-| macOS 13.3+ | DMG, Apple Silicon | [Install on macOS](docs/install/macos.md) |
-| Windows 10/11 | MSI, x64 | [Install on Windows](docs/install/windows.md) |
+| macOS 13.3+ | Apple Silicon DMG | [Install on macOS](docs/install/macos.md) |
+| Windows 10/11 | x64 MSI; choose the current-user build when listed to install without admin access | [Install on Windows](docs/install/windows.md#install-pre-built-msi) |
 | Linux | AppImage, x86_64 with glibc 2.39+ | [Install on Linux](docs/install/linux.md) |
-| Docker | CUDA, ROCm, or CPU | [Run with Docker](docs/install/docker.md) |
+| Docker | Linux/AMD64 images; CUDA, ROCm, CPU, and worker-only GPU profiles | [Run with Docker](docs/install/docker.md) |
 
-Download packages from the [latest release](https://github.com/debpalash/VoiceStudio/releases/latest). First launch creates a managed Python environment and downloads the default model. Later launches reuse both.
+First launch creates a managed Python environment and downloads the default model. Later launches reuse both.
 
 > [!NOTE]
-> On macOS, first launch needs a one-time right-click → **Open** approval. Intel Macs cannot run the local Python backend; use a [remote backend](docs/install/macos.md) instead.
+> On macOS, first launch needs a one-time right-click, then **Open** approval. Intel Macs cannot run the local Python backend; use a [remote backend](docs/install/macos.md) instead.
+
+### Quick Docker run
+
+The published images are **`linux/amd64` only**. On Apple Silicon, use the
+[native macOS app](docs/install/macos.md) for GPU acceleration. ARM64 hosts
+should read the [architecture requirements](docs/install/docker.md#architecture)
+before pulling an image.
+
+```bash
+docker run -d -p 127.0.0.1:3900:3900 -v omnivoice-data:/app/omnivoice_data --name voicestudio palashdeb/omnivoice-studio:stable
+```
 
 ### First voice
 
 1. Launch VoiceStudio and open **Voice Cloning**.
-2. Add a clean voice sample. Three seconds works; 5–15 seconds usually gives a better prompt.
+2. Add a clean voice sample. Three seconds works; 5 to 15 seconds usually gives a better prompt.
 3. Enter text, choose a language, then select **Generate**.
 
+> [!TIP]
+> **Try without installing:** Run VoiceStudio in the cloud via the [Google Colab notebook](https://colab.research.google.com/github/debpalash/VoiceStudio/blob/main/notebooks/OmniVoice_Studio_Colab.ipynb). Explore audio quality comparisons in [benchmarks](docs/benchmarks.md) and prompt design tips in [expressive speech](docs/expressive-speech.md).
+
+### Audio samples
+
+Listen to sample outputs produced locally with VoiceStudio:
+
+| Workflow | Prompt / Reference Audio | Generated Audio |
+|---|---|---|
+| **Voice Cloning** | [demo_voice.wav](backend/assets/samples/demo_voice.wav) | [demo_clone_output.wav](backend/assets/samples/demo_clone_output.wav) |
+| **Voice Design** (US News Anchor) | *"Clear, authoritative American broadcast tone"* | [demo_voice_design_us_news_anchor.wav](backend/assets/samples/voice_design/demo_voice_design_us_news_anchor.wav) |
+| **Voice Design** (UK Audiobook) | *"Warm, expressive British storytelling voice"* | [demo_voice_design_audiobook_uk_narrator.wav](backend/assets/samples/voice_design/demo_voice_design_audiobook_uk_narrator.wav) |
+| **Video Dubbing** (Multilingual) | [source.src.wav](backend/assets/samples/demo/dubbing/source.src.wav) | [Spanish](backend/assets/samples/demo/dubbing/dubbed_es.src.wav) · [French](backend/assets/samples/demo/dubbing/dubbed_fr.src.wav) · [Japanese](backend/assets/samples/demo/dubbing/dubbed_ja.src.wav) · [Chinese](backend/assets/samples/demo/dubbing/dubbed_zh.src.wav) |
+
 ### Run from source
 
-Install the [development prerequisites](.github/CONTRIBUTING.md#development-setup), then:
+Install the [development prerequisites](.github/CONTRIBUTING.md#development-setup) (Node 20+/Bun and Python 3.11+), then:
 
 ```bash
 git clone https://github.com/debpalash/VoiceStudio.git
@@ -84,7 +127,7 @@ bun install
 bun run desktop
 ```
 
-Use `bun run dev` for the browser UI. See [Contributing](.github/CONTRIBUTING.md) for services, tests, and platform packages.
+The desktop launcher configures Python dependencies on first run via `uv` automatically. Use `bun run dev` for the browser UI. See [Contributing](.github/CONTRIBUTING.md) for services, tests, and platform packages.
 
 ### If setup fails
 
@@ -99,22 +142,22 @@ Use `bun run dev` for the browser UI. See [Contributing](.github/CONTRIBUTING.md
 
 | Area | Included |
 |---|---|
-| **Voice Cloning** | Zero-shot synthesis from a short reference clip |
-| **Voice Design** | Create a voice from age, accent, pitch, style, and delivery instructions |
-| **Video Dubbing** | Transcribe, translate, preserve speakers, synthesize, and export video |
+| **Voice Cloning** | Zero-shot synthesis from a short reference clip ([guide](docs/engines/README.md)) |
+| **Voice Design** | Create a voice from age, accent, pitch, style, and delivery instructions ([expressive speech](docs/expressive-speech.md)) |
+| **Video Dubbing** | Transcribe, translate, preserve speakers, synthesize, and export video; compact translation settings include track selection, and completed dubs flag timing issues for review ([export guide](docs/dubbing/export.md)) |
 | **Stories and audiobooks** | Multi-voice scripts · EPUB/PDF import · chapter rendering · `.m4b` export |
-| **Dictation Widget** | System-wide shortcut, live transcription, optional local-LLM cleanup |
+| **[Dictation Widget](docs/features/dictation.md)** | System-wide shortcut, live transcription, optional local-LLM cleanup |
 | **Vocal Isolation** | Demucs speech/background separation |
-| **Speaker Diarization** | Pyannote and WhisperX speaker assignment |
-| **Batch Queue** | Queue large sets of audio and video jobs with per-job progress |
-| **Model Catalogue** | Install, remove, select, and route TTS, ASR, and LLM models |
-| **Remote Model Downloads** | Install models on enrolled remote workers with live progress |
-| **GPU Auto-Detect** | CUDA, MPS, ROCm, and CPU routing with per-engine checks |
+| **Speaker Diarization** | Pyannote and WhisperX speaker assignment ([guide](docs/features/diarization.md)) |
+| **Batch Queue** | Queue large sets of audio and video jobs with per-job progress, or watch a local folder for new videos |
+| **Model Catalogue** | Install, remove, select, and route TTS, ASR, and LLM models ([catalogue](docs/engines/README.md)) |
+| **Remote Model Downloads** | Install models on enrolled remote workers with live progress ([guide](docs/downloading-models.md)) |
+| **GPU Auto-Detect** | CUDA, MPS, ROCm, and CPU routing with per-engine checks ([performance](docs/performance.md)) |
 | **AI Watermark** | AudioSeal embedding and detection |
-| **MCP Server** | Synthesis and transcription tools for MCP clients |
-| **Diagnostics** | Self-checks, error journal, logs, and scrubbed support bundles |
+| **MCP Server** | Synthesis and transcription tools for MCP clients ([guide](docs/mcp.md)) |
+| **Diagnostics** | Self-checks, error journal, logs, and scrubbed support bundles ([troubleshooting](docs/install/troubleshooting.md)) |
 | **Local-first** | Core creation stays local; network-backed features are explicit opt-ins |
-| **Extensible** | Registry-based TTS, ASR, and plugin interfaces |
+| **Extensible** | Registry-based TTS, ASR, and plugin interfaces ([acceptance](docs/engine-acceptance.md)) |
 
 <table>
 <tr>
@@ -157,10 +200,20 @@ Requirements vary by engine. These values cover the default local workflow.
 | **Disk** | 10 GB free | 20 GB+ SSD |
 | **GPU** | Optional; CPU mode is supported | NVIDIA CUDA or Apple Silicon |
 | **VRAM** | 4 GB when using a GPU | 8 GB+; large optional engines need more |
-| **Python from source** | 3.11+ | 3.11–3.12 |
+| **Python from source** | 3.11+ | 3.11 or 3.12 |
 
 ROCm is Linux-only and opt-in. Windows AMD/Ryzen AI uses CPU. Systems with limited VRAM offload work to CPU when required. See [performance](docs/performance.md), [benchmarks](docs/benchmarks.md), and [engine disk usage](docs/engines/disk-usage.md).
 
+<a id="hardware-recommendations"></a>
+
+### Recommended stack by hardware
+
+| Hardware | Recommended TTS | Recommended ASR | Why |
+|---|---|---|---|
+| **Apple Silicon (M1–M4)** | [MLX-Audio](docs/engines/mlx-audio.md) · [OmniVoice](docs/engines/omnivoice.md) (MPS) | [MLX Whisper](docs/engines/mlx-whisper.md) · [Parakeet MLX](docs/engines/parakeet-mlx.md) | Native unified memory, lowest latency on macOS |
+| **NVIDIA GPU (8 GB+ VRAM)** | [OmniVoice](docs/engines/omnivoice.md) · [CosyVoice 3](docs/engines/cosyvoice.md) | [WhisperX](docs/engines/whisperx.md) | High-fidelity zero-shot cloning, word timestamps, diarization |
+| **Low VRAM / CPU-only** | [PocketTTS](docs/engines/pockettts.md) · [Sherpa-ONNX](docs/engines/sherpa-onnx.md) · [KittenTTS](docs/engines/kittentts.md) | [Moonshine](docs/engines/moonshine.md) · [Faster-Whisper](docs/engines/faster-whisper.md) (`int8`) | Low memory footprint, optimized CPU inference |
+
 <a id="engines"></a>
 
 ## Engines
@@ -173,22 +226,22 @@ Engine support is capability-specific. Check cloning, language, platform, memory
 
 | Engine | Languages | Clone | Instruct | Linux | macOS ARM | Windows | License |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|---|
-| **VoiceStudio** (default, powered by k2-fsa/OmniVoice) | 600+ | Yes | Yes | CUDA/CPU | MPS | CUDA/CPU | [AGPL-3.0](LICENSE) app · [Apache-2.0](LICENSE-NOTICE.md) model |
-| **CosyVoice 3** | 9 + 18 dialects | Yes | Yes | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
-| **GPT-SoVITS** | 5 | Yes | — | CUDA/CPU | — | CUDA/CPU | MIT |
-| **VoxCPM2** | 30 | Yes | Yes | CUDA/CPU | MPS | CUDA/CPU | Apache-2.0 |
-| **MOSS-TTS-Nano** | 20 | Yes | — | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
-| **KittenTTS** | English | — | — | CPU | CPU | CPU | MIT |
-| **MLX-Audio** | Model-dependent | Varies | Varies | — | MLX | — | Varies |
-| **Sherpa-ONNX** | 20+ | — | — | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
-| **IndexTTS 2.5** ⚡ | ZH · EN · JA · ES · AR | Yes | — | CUDA/CPU | CPU | CUDA/CPU | Bilibili model license¹ |
-| **OmniVoice GGUF** ⚡ | 600+ | Yes | Yes | CUDA/CPU | MPS/CPU | CUDA/CPU | [AGPL-3.0](LICENSE) app · [Apache-2.0](LICENSE-NOTICE.md) model |
-| **OmniVoice (subprocess)** ⚡ | 600+ | Yes | Yes | CUDA/CPU | MPS | CUDA/CPU | [AGPL-3.0](LICENSE) app · [Apache-2.0](LICENSE-NOTICE.md) model |
-| **PocketTTS** ⚡ | EN · FR · DE · PT · IT · ES | Yes | — | CPU | CPU | CPU | CC-BY-4.0, gated² |
-| **Supertonic 3** ⚡ | 31 | — | — | CPU | CPU | CPU | OpenRAIL-M |
-| **MOSS-TTS-v1.5** ⚡ | 31 | Yes | — | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
-| **dots.tts** ⚡ | 24 | Yes | — | CUDA/CPU | CPU | — | Apache-2.0 |
-| **Confucius4-TTS** ⚡ | 14 | Yes | — | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
+| [**VoiceStudio** (default, powered by k2-fsa/OmniVoice)](docs/engines/omnivoice.md) | 600+ | Yes | Yes | CUDA/CPU | MPS | CUDA/CPU | [AGPL-3.0](LICENSE) app · [Apache-2.0 code, CC-BY-NC weights](https://huggingface.co/k2-fsa/OmniVoice#license)³ |
+| [**CosyVoice 3**](docs/engines/cosyvoice.md) | 9 + 18 dialects | Yes | Yes | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
+| [**GPT-SoVITS**](docs/engines/gpt-sovits.md) | 5 | Yes | No | CUDA/CPU | No | CUDA/CPU | MIT |
+| [**VoxCPM2**](docs/engines/voxcpm2.md) | 30 | Yes | Yes | CUDA/CPU | MPS | CUDA/CPU | Apache-2.0 |
+| [**MOSS-TTS-Nano**](docs/engines/moss-tts-nano.md) | 20 | Yes | No | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
+| [**KittenTTS**](docs/engines/kittentts.md) | English | No | No | CPU | CPU | CPU | MIT |
+| [**MLX-Audio**](docs/engines/mlx-audio.md) | Model-dependent | Varies | Varies | No | MLX | No | Varies |
+| [**Sherpa-ONNX**](docs/engines/sherpa-onnx.md) | 20+ | No | No | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
+| [**IndexTTS 2.5** ⚡](docs/engines/indextts.md) | ZH · EN · JA · ES · AR | Yes | No | CUDA/CPU | CPU | CUDA/CPU | Bilibili model license¹ |
+| [**OmniVoice GGUF** ⚡](docs/engines/omnivoice-gguf.md) | 600+ | Yes | Yes | CUDA/CPU | MPS/CPU | CUDA/CPU | [AGPL-3.0](LICENSE) app · [review the derivative model terms](https://huggingface.co/Serveurperso/OmniVoice-GGUF#license)³ |
+| [**OmniVoice (subprocess; opt-in off MPS)** ⚡](docs/engines/omnivoice-subprocess.md) | 600+ | Yes | Yes | CUDA/CPU | MPS via default OmniVoice | CUDA/CPU | [AGPL-3.0](LICENSE) app · [Apache-2.0 code, CC-BY-NC weights](https://huggingface.co/k2-fsa/OmniVoice#license)³ |
+| [**PocketTTS** ⚡](docs/engines/pockettts.md) | EN · FR · DE · PT · IT · ES | Yes | No | CPU | CPU | CPU | CC-BY-4.0, gated² |
+| [**Supertonic 3** ⚡](docs/engines/supertonic3.md) | 31 | No | No | CPU | CPU | CPU | OpenRAIL-M |
+| [**MOSS-TTS-v1.5** ⚡](docs/engines/moss-tts-v15.md) | 31 | Yes | No | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
+| [**dots.tts** ⚡](docs/engines/dots-tts.md) | 24 | Yes | No | CUDA/CPU | CPU | No | Apache-2.0 |
+| [**Confucius4-TTS** ⚡](docs/engines/confucius4-tts.md) | 14 | Yes | No | CUDA/CPU | CPU | CUDA/CPU | Apache-2.0 |
 
 ⚡ Installed or registered on demand.
 
@@ -196,6 +249,8 @@ Engine support is capability-specific. Check cloning, language, platform, memory
 
 ² PocketTTS shows its gated-access and CC-BY-4.0 terms before first use.
 
+³ The OmniVoice snapshot also includes an audio tokenizer under separate [Boson Higgs Audio 2 and Meta Llama community terms](https://huggingface.co/k2-fsa/OmniVoice/blob/main/audio_tokenizer/LICENSE). VoiceStudio's application license does not replace model or tokenizer terms.
+
 Clone-less engines cannot preserve a reference speaker in dubbing or pinned-voice batch jobs. VoiceStudio rejects those jobs instead of silently changing engines. Heavy engines have separate memory and platform limits; check their engine guide first.
 
 <a id="asr-engines"></a>
@@ -204,17 +259,17 @@ Clone-less engines cannot preserve a reference speaker in dubbing or pinned-voic
 
 | Engine | ID | Languages | Best fit |
 |---|---|:---:|---|
-| **WhisperX** (default) | `whisperx` | ~100 | Dubbing, subtitles, word-level timing |
-| **Faster-Whisper** | `faster-whisper` | ~100 | General cross-platform transcription |
-| **Faster-Whisper (isolated)** | `faster-whisper-isolated` | ~100 | Crash-isolated batch transcription |
-| **MLX Whisper** | `mlx-whisper` | ~100 | Apple Silicon |
-| **PyTorch Whisper** | `pytorch-whisper` | ~100 | CUDA, MPS, and CPU fallback |
-| **Parakeet TDT** | `nemo-parakeet` | English + 25 EU | Fast CPU/CUDA transcription |
-| **Parakeet TDT v3 (MLX)** | `parakeet-mlx` | 25 EU | Apple Silicon dictation and word timestamps |
-| **Moonshine** | `moonshine` | English | Low-power, low-latency ONNX |
-| **FunASR** | `funasr` | 50+ | VAD and inline diarization |
-| **sherpa-onnx** (live dictation) | `sherpa-onnx-asr` | Model-dependent | Streaming CPU dictation |
-| **OpenAI-compatible** ⚠️ remote | `openai-compat-asr` | Server-dependent | Qwen3-ASR or another compatible endpoint; audio leaves the machine |
+| [**WhisperX** (default)](docs/engines/whisperx.md) | `whisperx` | ~100 | Dubbing, subtitles, word-level timing |
+| [**Faster-Whisper**](docs/engines/faster-whisper.md) | `faster-whisper` | ~100 | General cross-platform transcription |
+| [**Faster-Whisper (isolated)**](docs/engines/faster-whisper-isolated.md) | `faster-whisper-isolated` | ~100 | Crash-isolated batch transcription |
+| [**MLX Whisper**](docs/engines/mlx-whisper.md) | `mlx-whisper` | ~100 | Apple Silicon |
+| [**PyTorch Whisper**](docs/engines/pytorch-whisper.md) | `pytorch-whisper` | ~100 | CUDA, MPS, and CPU fallback |
+| [**Parakeet TDT**](docs/engines/nemo-parakeet.md) | `nemo-parakeet` | English + 25 EU | Fast CPU/CUDA transcription |
+| [**Parakeet TDT v3 (MLX)**](docs/engines/parakeet-mlx.md) | `parakeet-mlx` | 25 EU | Apple Silicon dictation and word timestamps |
+| [**Moonshine**](docs/engines/moonshine.md) | `moonshine` | English | Low-power, low-latency ONNX |
+| [**FunASR**](docs/engines/funasr.md) | `funasr` | 50+ | VAD and inline diarization |
+| [**sherpa-onnx** (live dictation)](docs/engines/sherpa-onnx-asr.md) | `sherpa-onnx-asr` | Model-dependent | Streaming CPU dictation |
+| [**OpenAI-compatible** ⚠️ configured server](docs/engines/openai-compatible-asr.md) | `openai-compat-asr` | Server-dependent | Local gigastt/Qwen3-ASR or a remote endpoint; audio goes only to that server |
 
 WhisperX and Faster-Whisper retry with `int8` when efficient `float16` is unavailable. Pin `ASR_COMPUTE_TYPE=int8` or `float32` only if automatic selection still fails.
 
@@ -249,12 +304,12 @@ FastAPI backend
 
 - The desktop talks to a loopback-only backend on `localhost:3900`.
 - Loopback API calls need no server key. Remote access requires a share PIN or API key.
-- Remote workers and OpenAI-compatible ASR are opt-in. The UI identifies when audio leaves the machine.
-- Analytics is off until consent. If enabled, it sends allowlisted, content-free usage metadata—not text, audio, file names, or projects.
+- Remote workers and OpenAI-compatible ASR are opt-in. Loopback ASR may use HTTP and keeps audio on the machine; non-loopback endpoints require HTTPS, and redirects are not followed.
+- Analytics is off until consent. If enabled, it sends allowlisted, content-free usage metadata. It never sends text, audio, file names, or projects.
 
 <a id="api"></a>
 
-## OpenAI-compatible API
+## Local speech platform and OpenAI-compatible API
 
 Point an OpenAI-compatible audio client at the local backend:
 
@@ -267,6 +322,8 @@ Point an OpenAI-compatible audio client at the local backend:
 |---|---|
 | `POST /v1/audio/speech` | TTS to `mp3`, `opus`, `aac`, `flac`, `wav`, or `pcm`; select a profile with `voice` and an engine with `model` |
 | `POST /v1/audio/transcriptions` | STT to `json`, `text`, `verbose_json`, `srt`, or `vtt` |
+| `WS /v1/audio/transcriptions/stream` | Live PCM/WebM transcription with partial, utterance, and session-final events |
+| `GET /.well-known/voicestudio-speech` | Discover HTTP, WebSocket, MCP, and native dictation-control transports |
 | `GET /v1/audio/voices` | List local voice profiles and engines |
 
 ```python
@@ -283,19 +340,61 @@ with client.audio.speech.with_streaming_response.create(
     response.stream_to_file("speech.wav")
 ```
 
-The full API reference is in **Settings → OpenAPI Reference**. For LAN, Tailscale, or proxy access, read [API authentication](docs/api-auth.md) before exposing the backend.
+```bash
+# Quick test via cURL
+curl http://localhost:3900/v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{"model": "tts-1", "input": "Made on my own hardware.", "voice": "default", "response_format": "wav"}' \
+  --output speech.wav
+```
+
+The bundled Rust control sidecar lets Herdr, coding agents, VS Code, desktop apps,
+and TUIs trigger the system-wide dictation flow or reuse its native text
+insertion. See the [speech platform guide](docs/speech-platform.md). The full API
+reference is in **Settings → OpenAPI Reference**. For LAN, Tailscale, or proxy
+access, read [API authentication](docs/api-auth.md) before exposing the backend.
 
 ### Agent skills
 
 Install the VoiceStudio skills for Claude Code, Codex, Cursor, and other [skills.sh](https://skills.sh)-compatible agents:
 
 ```bash
-npx skills add debpalash/omnivoice-studio
+npx skills add debpalash/VoiceStudio
 ```
 
 - `omnivoice`: synthesize speech and transcribe audio through local VoiceStudio.
 - `oss-maintainer`: the repository's open-source maintenance workflow.
 
+### Model Context Protocol (MCP)
+
+VoiceStudio mounts an MCP server at `http://localhost:3900/mcp` for Claude Desktop, Cursor, and AI agents:
+
+```json
+{
+  "mcpServers": {
+    "voicestudio": {
+      "url": "http://localhost:3900/mcp"
+    }
+  }
+}
+```
+
+For clients requiring stdio transport, use the bundled local shim (`docs/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "voicestudio": {
+      "command": "python",
+      "args": ["-m", "backend.mcp_shim"],
+      "cwd": "/path/to/VoiceStudio"
+    }
+  }
+}
+```
+
+See the [MCP guide](docs/mcp.md) for tools (`generate_speech`, `clone_voice`, `transcribe`), file streaming modes, and client bindings.
+
 ### Google Colab
 
 [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/debpalash/VoiceStudio/blob/main/notebooks/OmniVoice_Studio_Colab.ipynb)
@@ -312,11 +411,13 @@ The [notebook](notebooks/OmniVoice_Studio_Colab.ipynb) runs the app and web UI o
 | Fix setup | [Troubleshooting](docs/install/troubleshooting.md) · [model downloads](docs/downloading-models.md) · [Hugging Face token](docs/setup/huggingface-token.md) |
 | Choose an engine | [Engine guides](docs/engines/README.md) · [benchmarks](docs/benchmarks.md) · [expressive speech](docs/expressive-speech.md) |
 | Tune hardware | [Performance](docs/performance.md) · [remote workers](docs/remote-workers.md) |
-| Build integrations | [API auth](docs/api-auth.md) · [MCP](docs/mcp.md) · [examples](examples/README.md) |
+| Build integrations | [Speech platform](docs/speech-platform.md) · [Private production API](docs/production-private-api.md) · [API auth](docs/api-auth.md) · [MCP](docs/mcp.md) · [examples](examples/README.md) |
 | Build VoiceStudio | [Contributing](.github/CONTRIBUTING.md) · [engine acceptance](docs/engine-acceptance.md) |
 | Track changes | [Changelog](CHANGELOG.md) · [roadmap](docs/ROADMAP.md) · [latest release](https://github.com/debpalash/VoiceStudio/releases/latest) |
 | Remove everything | [Uninstall guide](docs/install/uninstall.md) |
 
+<a id="faq"></a>
+
 ## FAQ
 
 <details>
@@ -328,19 +429,19 @@ Apple Silicon is supported with MPS and MLX options. Intel Macs cannot run the l
 <details>
 <summary><strong>How much VRAM do I need?</strong></summary>
 
-A GPU is optional. Use 4 GB VRAM as the minimum for accelerated work and 8 GB+ for the default multi-stage workflow. Large optional engines can require 12–16 GB or more. Check the [benchmarks](docs/benchmarks.md) and engine guide.
+A GPU is optional. Use 4 GB VRAM as the minimum for accelerated work and 8 GB+ for the default multi-stage workflow. Large optional engines can require 12 to 16 GB or more. Check the [benchmarks](docs/benchmarks.md) and engine guide.
 </details>
 
 <details>
 <summary><strong>Why does a longer reference clip not always improve the clone?</strong></summary>
 
-Cloning is zero-shot: the clip is a prompt, not training data. Use 5–15 seconds of one speaker, close to the microphone, without music, noise, or reverb. Match the tone and pace you want in the output. For training, see [data preparation](docs/data_preparation.md) and [training](docs/training.md).
+Cloning is zero-shot: the clip is a prompt, not training data. Use 5 to 15 seconds of one speaker, close to the microphone, without music, noise, or reverb. Match the tone and pace you want in the output. For training, see [data preparation](docs/data_preparation.md) and [training](docs/training.md).
 </details>
 
 <details>
 <summary><strong>Can I use generated audio commercially?</strong></summary>
 
-Yes under VoiceStudio's AGPL-3.0 terms. Optional engines and model weights may use different licenses; review the selected engine's license before commercial use.
+VoiceStudio's application license does not restrict generated audio, but it does not grant rights under a model's separate terms. The default OmniVoice repository labels its pretrained weights CC-BY-NC and includes a tokenizer under separate community terms. Review the selected model terms before commercial use.
 </details>
 
 <details>
@@ -362,17 +463,30 @@ Use `scripts/uninstall.sh` on macOS/Linux or `scripts\uninstall.ps1` on Windows.
 - [Good first issues](https://github.com/debpalash/VoiceStudio/labels/good%20first%20issue) for a scoped starting point.
 - [Contributing guide](.github/CONTRIBUTING.md) for setup, tests, and pull requests.
 
+<p align="center">
+  <a href="https://star-history.com/#debpalash/VoiceStudio&Date">
+    <img src="https://api.star-history.com/svg?repos=debpalash/VoiceStudio&type=Date" alt="Star History Chart" width="100%" />
+  </a>
+</p>
+
 ## Support development
 
 VoiceStudio is free and has no paid tier. Donations fund development and infrastructure.
 
 [Ko-fi](https://ko-fi.com/debpalash) · [PayPal](https://paypal.me/palashCoder) · [Sponsorship details](SPONSORS.md)
 
+## Responsible use and safety
+
+VoiceStudio enables zero-shot voice cloning and speech generation on personal hardware. Please use it responsibly:
+- **Consent:** Only clone or synthesize voices with explicit permission from the speaker.
+- **Audio provenance:** VoiceStudio integrates [AudioSeal](https://github.com/facebookresearch/audioseal) imperceptible watermarking by default to detect and identify synthetic speech without altering sound quality.
+- **Local privacy:** For the default local workflow, audio recordings, transcripts, voices, and projects remain strictly on your local disk; data leaves your device only when you explicitly configure remote workers or external ASR endpoints.
+
 ## License
 
-VoiceStudio is licensed under [AGPL-3.0](LICENSE). You may run it, modify it, use it internally, and sell generated audio. If you modify VoiceStudio and provide that modified version as a network service, AGPL requires you to offer the corresponding source under the same license. A commercial license is available for proprietary embedding; contact **VoiceStudio@palash.dev**. See [LICENSE-NOTICE.md](LICENSE-NOTICE.md) for the plain-language scope.
+VoiceStudio is licensed under [AGPL-3.0](LICENSE). You may run it, modify it, and use it internally. The application license itself does not restrict selling generated audio, but downloaded model and tokenizer terms may. If you modify VoiceStudio and provide that modified version as a network service, AGPL requires you to offer the corresponding source under the same license. A commercial license for VoiceStudio-owned code is available for proprietary embedding; it does not relicense third-party models. Contact **VoiceStudio@palash.dev**. See [LICENSE-NOTICE.md](LICENSE-NOTICE.md) for the plain-language scope.
 
-Optional engines and downloaded models retain their own licenses. The bundled `omnivoice/` model remains Apache-2.0 upstream.
+Optional engines and downloaded models retain their own licenses. The bundled `omnivoice/` Python code is Apache-2.0 upstream; the default downloaded weights and audio tokenizer use separate terms.
 
 ## Acknowledgments
 

README_CN.md

@@ -20,6 +20,7 @@
   </p>
 
   <p>
+    <a href="https://github.com/debpalash/VoiceStudio/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/debpalash/VoiceStudio/ci.yml?branch=main&style=flat-square&label=CI" alt="CI 状态" /></a>
     <a href="https://github.com/debpalash/VoiceStudio/stargazers"><img src="https://img.shields.io/github/stars/debpalash/VoiceStudio?style=flat-square&color=f59e0b" alt="Star 数" /></a>
     <a href="https://github.com/debpalash/VoiceStudio/releases/latest"><img src="https://img.shields.io/github/v/release/debpalash/VoiceStudio?style=flat-square&color=10b981" alt="版本" /></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square" alt="许可证" /></a>
@@ -65,11 +66,27 @@
 - 🐧 **Linux** — [docs/install/linux.md](docs/install/linux.md)
 - 🐳 **Docker** — [docs/install/docker.md](docs/install/docker.md) · [Docker Hub: `palashdeb/omnivoice-studio`](https://hub.docker.com/r/palashdeb/omnivoice-studio)
 
+```bash
+# Docker 快速运行 (CPU / 本地环回模式)
+docker run -d -p 127.0.0.1:3900:3900 -v omnivoice-data:/app/omnivoice_data --name voicestudio palashdeb/omnivoice-studio:stable
+```
+
 **三步克隆出你的第一个声音：**
 
 1. **安装并启动。** 首次启动会自动搭建 Python 运行环境并下载模型权重——启动画面会逐步显示进度（仅首次，需要几分钟；之后即开即用）。
 2. 从启动台打开**语音克隆**，拖入任意声音的 **3 秒音频**。
-3. **输入一句话，点击生成。** 音频完全属于你——在你的设备上生成和保存，支持 646 种语言。
+3. **输入一句话，点击生成。** 音频在你的设备上生成并保存，支持 646 种语言（商业使用前请审阅所选模型与分词器的许可条款）。
+
+### 🎧 音频示例
+
+在线试听 VoiceStudio 本地生成的实际音频样例：
+
+| 工作流 | 提示词 / 参考音频 | 生成音频 |
+|---|---|---|
+| **声音克隆** | [demo_voice.wav](backend/assets/samples/demo_voice.wav) | [demo_clone_output.wav](backend/assets/samples/demo_clone_output.wav) |
+| **声音设计** (美语新闻主播) | *"清晰、权威的美国广播级音色"* | [demo_voice_design_us_news_anchor.wav](backend/assets/samples/voice_design/demo_voice_design_us_news_anchor.wav) |
+| **声音设计** (英式有声书) | *"温暖生动的英式故事讲述音色"* | [demo_voice_design_audiobook_uk_narrator.wav](backend/assets/samples/voice_design/demo_voice_design_audiobook_uk_narrator.wav) |
+| **视频配音** (多语种) | [source.src.wav](backend/assets/samples/demo/dubbing/source.src.wav) | [西班牙语](backend/assets/samples/demo/dubbing/dubbed_es.src.wav) · [法语](backend/assets/samples/demo/dubbing/dubbed_fr.src.wav) · [日语](backend/assets/samples/demo/dubbing/dubbed_ja.src.wav) · [中文](backend/assets/samples/demo/dubbing/dubbed_zh.src.wav) |
 
 觉得慢？[docs/performance.md](docs/performance.md) 讲清了生成时间到底花在哪里、有哪些调优开关，以及“它变慢了”的三个经典原因。各引擎/设备的实测数据见 [docs/benchmarks.md](docs/benchmarks.md)。
 
@@ -217,6 +234,16 @@ Hugging Face Token 的配置见
 > [!IMPORTANT]
 > **macOS Intel（x86_64）不支持本地后端：** 应用 UI 可以安装，但 Python 后端无法运行，因为 PyTorch 已不再发布 Intel Mac 轮子（[#889](https://github.com/debpalash/VoiceStudio/issues/889)）。Intel Mac 用户仍可让 UI 指向另一台机器上的远程后端——参见 [docs/install/macos.md](docs/install/macos.md)。
 
+<a id="hardware-recommendations"></a>
+
+### 💡 按硬件推荐引擎配置
+
+| 硬件配置 | 推荐 TTS 引擎 | 推荐 ASR 语音识别 | 优势 |
+|---|---|---|---|
+| **Apple Silicon (M1–M4)** | [MLX-Audio](docs/engines/mlx-audio.md) · [OmniVoice](docs/engines/omnivoice.md) (MPS) | [MLX Whisper](docs/engines/mlx-whisper.md) · [Parakeet MLX](docs/engines/parakeet-mlx.md) | 原生统一内存，macOS 上延迟最低、性能最强 |
+| **NVIDIA 显卡 (8 GB+ 显存)** | [OmniVoice](docs/engines/omnivoice.md) · [CosyVoice 3](docs/engines/cosyvoice.md) | [WhisperX](docs/engines/whisperx.md) | 极致零样本克隆品质、字级时间戳对齐与说话人分离 |
+| **低显存 / 仅 CPU 设备** | [PocketTTS](docs/engines/pockettts.md) · [Sherpa-ONNX](docs/engines/sherpa-onnx.md) · [KittenTTS](docs/engines/kittentts.md) | [Moonshine](docs/engines/moonshine.md) · [Faster-Whisper](docs/engines/faster-whisper.md) (`int8`) | 超低内存占用，针对 CPU 指令集深度优化 |
+
 <a id="tts-engines"></a>
 
 ### 🗣️ TTS 引擎
@@ -338,9 +365,9 @@ print(result.text)
 
 ### 📓 在 Google Colab 上运行
 
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/debpalash/VoiceStudio/blob/main/notebooks/VoiceStudio_Studio_Colab.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/debpalash/VoiceStudio/blob/main/notebooks/OmniVoice_Studio_Colab.ipynb)
 
-没有本地 GPU？官方笔记本（[notebooks/VoiceStudio_Studio_Colab.ipynb](notebooks/VoiceStudio_Studio_Colab.ipynb)）可在免费的 Colab T4 上启动完整应用（包含 Web 界面）：在笔记本内直接构建前端，用 uv 安装后端（复用 Colab 预装的 CUDA PyTorch），并通过 Colab 内置端口代理打开界面。无需第三方隧道，也无需任何 API 密钥。随后还有一套覆盖全部主要功能的 API 导览，全部可在笔记本内直接播放：多语言 TTS、声音克隆与声音设计、已保存的声音档案、语音转写、AI 水印检测、OpenAI 兼容 API、多角色故事、带章节的 m4b 有声书，以及一个附带人声分离音轨的迷你视频配音。
+没有本地 GPU？官方笔记本（[notebooks/OmniVoice_Studio_Colab.ipynb](notebooks/OmniVoice_Studio_Colab.ipynb)）可在免费的 Colab T4 上启动完整应用（包含 Web 界面）：在笔记本内直接构建前端，用 uv 安装后端（复用 Colab 预装的 CUDA PyTorch），并通过 Colab 内置端口代理打开界面。无需第三方隧道，也无需任何 API 密钥。随后还有一套覆盖全部主要功能的 API 导览，全部可在笔记本内直接播放：多语言 TTS、声音克隆与声音设计、已保存的声音档案、语音转写、AI 水印检测、OpenAI 兼容 API、多角色故事、带章节的 m4b 有声书，以及一个附带人声分离音轨的迷你视频配音。
 
 ### 🤝 智能体技能（Agent Skills）
 
@@ -352,6 +379,36 @@ npx skills add debpalash/omnivoice-studio
 
 内含两个 [skills](https://skills.sh)：**`omnivoice`**——让任何智能体通过你的本地安装进行语音合成与转录（包括你克隆的声音），免费且离线；以及 **`oss-maintainer`**——本项目所遵循的维护者方法论，适合任何用智能体运营自己开源项目的人。
 
+### 🔌 模型上下文协议（MCP 服务器）
+
+VoiceStudio 在 `http://localhost:3900/mcp` 挂载了 MCP 服务，可供 Claude Desktop、Cursor 与自主智能体调用：
+
+```json
+{
+  "mcpServers": {
+    "voicestudio": {
+      "url": "http://localhost:3900/mcp"
+    }
+  }
+}
+```
+
+对于需要 stdio 管道传输的客户端，请使用内置的本地桥接脚本（`docs/mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "voicestudio": {
+      "command": "python",
+      "args": ["-m", "backend.mcp_shim"],
+      "cwd": "/path/to/VoiceStudio"
+    }
+  }
+}
+```
+
+支持 `generate_speech`、`clone_voice`、`transcribe` 等工具与流式文件输出模式，详见 [docs/mcp.md](docs/mcp.md)。
+
 ---
 
 ## 🗺️ 路线图
@@ -542,6 +599,13 @@ VoiceStudio **免费**且采用 **AGPL-3.0** 许可——没有付费版，没
 VoiceStudio 完全本地运行——卸载就是删除应用及其写入的文件夹（模型缓存、Python 环境、你的声音/项目、配置）。运行 <code>scripts/uninstall.sh</code>（macOS/Linux）或 <code>scripts\uninstall.ps1</code>（Windows）——它会先以干跑方式列出每个文件夹及其大小，加 <code>--yes</code> 才会真正删除。完整的各平台路径列表和应用移除步骤见 <a href="docs/install/uninstall.md"><b>docs/install/uninstall.md</b></a>。
 </details>
 
+## 🛡️ 负责任使用与安全
+
+VoiceStudio 在个人硬件上提供零样本语音克隆与语音创作能力。我们提倡负责任的技术使用：
+- **明确授权：** 严禁在未经说话人本人知情并明确授权的情况下克隆其声音。
+- **AI 溯源：** VoiceStudio 默认集成 [AudioSeal](https://github.com/facebookresearch/audioseal) 不可见神经音频水印，在完全不影响听感音质的前提下精准标记合成语音。
+- **本地隐私：** 默认本地工作流下，所有音频、声音档案、项目与转录文本始终保存在你的本地设备上；仅当你主动配置远程工作节点或第三方 ASR 端点时，相应数据才会传输到对应服务。
+
 ---
 
 <a id="license"></a>

backend/api/dependencies.py

@@ -54,6 +54,15 @@ def _server_mode() -> bool:
     return os.environ.get("OMNIVOICE_SERVER_MODE", "").strip().lower() in _TRUTHY
 
 
+def validate_server_admin_key() -> None:
+    """Reject an explicitly blank key before a server-mode app starts."""
+    raw_key = os.environ.get("OMNIVOICE_API_KEY")
+    if _server_mode() and raw_key is not None and not raw_key.strip():
+        raise RuntimeError(
+            "OMNIVOICE_API_KEY is blank; configure a non-whitespace administrator key"
+        )
+
+
 def _configured_pin(request) -> str | None:
     """The active share PIN (``app.state.network_share.pin``) or None. Read via
     getattr so a bare Request stub (or a request that hit before lifespan set
@@ -157,6 +166,31 @@ def require_loopback(request: Request) -> None:
     raise HTTPException(status_code=403, detail="loopback origin required")
 
 
+def _admin_gate_403() -> None:
+    """Raise the admin-gate 403 with a detail that states what would ACTUALLY
+    satisfy the gate. The bundled UI routes any 403 whose detail mentions
+    "admin api key" to the API-key login form (frontend ``client.ts``; the
+    literal contract is locked by ``tests/test_auth_gate_detail_lockstep.py``),
+    so the wording must not name a key where presenting one cannot help.
+
+    The detail names the key only when the gate would accept one: server mode
+    WITH an API key configured. Every other rejection — desktop mode (the
+    credential checks in the callers only run under server mode) and a
+    server-mode deployment with only a share PIN or nothing configured — keeps
+    the plain loopback detail, because only loopback can use admin there.
+    Naming the key in those cases would trap a LAN-share guest in a login
+    form that can never succeed (#1213, #1525; PR #1569 review).
+    """
+    raise HTTPException(
+        status_code=403,
+        detail=(
+            "loopback origin or admin API key required"
+            if _server_mode() and remote_api_key()
+            else "loopback origin required"
+        ),
+    )
+
+
 def require_admin(request: Request) -> None:
     """Gate RCE/filesystem-capable admin routers.
 
@@ -180,7 +214,7 @@ def require_admin(request: Request) -> None:
             return
         if _request_presents_admin_credential(request):
             return
-    raise HTTPException(status_code=403, detail="loopback origin or admin API key required")
+    _admin_gate_403()
 
 
 def require_admin_action(request: Request) -> None:
@@ -198,7 +232,7 @@ def require_admin_action(request: Request) -> None:
         side_effectful_get=True,
     ):
         return
-    raise HTTPException(status_code=403, detail="loopback origin or admin API key required")
+    _admin_gate_403()
 
 
 def require_desktop(request: Request) -> None:

backend/api/public_engine_metadata.py

@@ -32,23 +32,142 @@ def _public_routing_reason(status: object, diagnostic: object) -> str:
     return _ROUTING_BY_STATUS.get(status, _ROUTING_UNAVAILABLE)
 
 
+# Categories for WHY an engine is unavailable. The probe's own sentence cannot
+# cross the boundary — it carries exception text, local paths and sometimes
+# credentials — but "Engine unavailable. Check installation and configuration."
+# told the user nothing at all, and "Last error: A previous engine check
+# failed." reads like a crash rather than "you have not installed this yet"
+# (#1866). Classifying the private diagnostic into an owned sentence keeps the
+# boundary intact and still names the kind of problem and the place to fix it.
+_UNAVAILABLE_NOT_INSTALLED = (
+    "This engine's package isn't installed yet. Install it from "
+    "Model Catalogue → Engines."
+)
+# An engine gated behind an in-app license review (Supertonic-3, PocketTTS).
+# The Model Catalogue shows its Accept button only when the reason matches
+# /license not accepted/i (EngineCompatibilityMatrix.reasonMentionsLicense), so
+# this sentence must keep those words: collapsing it into the generic line hid
+# the only way to enable those engines.
+_UNAVAILABLE_LICENSE = (
+    "License not accepted yet. Review and accept it in "
+    "Model Catalogue → Engines to enable this engine."
+)
+# An engine that cannot run on this machine at all: Apple-Silicon-only MLX,
+# PyTorch with no Intel Mac build. "Isn't installed yet" or "check
+# installation" sent people after an install that could never work.
+_UNAVAILABLE_PLATFORM = (
+    "This engine doesn't run on this computer's platform. Its guide lists "
+    "the platforms it supports."
+)
+# Apple Silicon whose PyTorch cannot use the GPU (MPS): the platform is
+# right, the installation is not. MLX-Audio / MLX-Whisper need MPS (#390).
+_UNAVAILABLE_NO_MPS = (
+    "This engine needs Apple's GPU (MPS), and this installation's PyTorch "
+    "can't use it. Updating macOS or reinstalling VoiceStudio usually "
+    "restores it."
+)
+_UNAVAILABLE_NEEDS_CONFIG = (
+    "This engine needs to be configured before it can run. Open "
+    "Model Catalogue → Engines to finish setting it up."
+)
+_UNAVAILABLE_FILE_MISSING = (
+    "A file this engine needs is missing or unreadable. Reinstall it from "
+    "Model Catalogue → Engines."
+)
+
+# The same two cases for an engine the app cannot install for you. "Install it
+# from Model Catalogue → Engines" sent people to a page with no Install button
+# for that engine — most of the catalogue — which reads as the app being
+# broken. The row's own guide link (``docs_url``) is the real next step.
+_UNAVAILABLE_NOT_INSTALLED_MANUAL = (
+    "This engine isn't installed yet, and it has no one-click install. "
+    "Its guide lists the install steps."
+)
+_UNAVAILABLE_FILE_MISSING_MANUAL = (
+    "A file this engine needs is missing or unreadable. Its guide lists the "
+    "install steps."
+)
+_MANUAL_INSTALL_VARIANT = {
+    _UNAVAILABLE_NOT_INSTALLED: _UNAVAILABLE_NOT_INSTALLED_MANUAL,
+    _UNAVAILABLE_FILE_MISSING: _UNAVAILABLE_FILE_MISSING_MANUAL,
+}
+
+# Matched against the lowered probe text. Ordered most specific first: a
+# missing file often also says "not installed", and the file case has the more
+# useful remedy of the two.
+_UNAVAILABLE_SIGNATURES = (
+    # First: its probe text also says "Open Model Catalogue", and the
+    # license is the one gap only the user can close.
+    (_UNAVAILABLE_LICENSE, ("license not accepted",)),
+    # Before the install and file checks: a platform reason often also says
+    # "unavailable" or names a missing wheel, and no install can fix it. Not
+    # "apple silicon only": mlx-audio says that on an M-series Mac too, when
+    # the package is merely missing and installing does help.
+    (_UNAVAILABLE_PLATFORM, (
+        "requires apple silicon", "not supported on this platform",
+        "unavailable on intel macs", "no macos x86_64 wheel",
+        "no windows install", "not supported on windows",
+    )),
+    (_UNAVAILABLE_NO_MPS, ("torch mps unavailable",)),
+    (_UNAVAILABLE_FILE_MISSING, (
+        "file is missing", "file is empty", "file is unreadable",
+        "script missing", "binary", "not found at",
+    )),
+    (_UNAVAILABLE_NEEDS_CONFIG, (
+        "environment variable", "configure a server endpoint", "api key",
+        "unconfigured", "set the", "base url",
+    )),
+    (_UNAVAILABLE_NOT_INSTALLED, (
+        "not installed", "package missing", "not available", "no module named",
+        "import ", "unavailable:", "failed to load",
+    )),
+)
+
+
+def _public_unavailable_reason(diagnostic: object) -> str:
+    """Map a private availability probe to an accurate stable category."""
+    private = diagnostic.lower() if isinstance(diagnostic, str) else ""
+    for public, markers in _UNAVAILABLE_SIGNATURES:
+        if any(marker in private for marker in markers):
+            return public
+    return _UNAVAILABLE
+
+
 def public_backends(entries: list[dict]) -> list[dict]:
     """Copy registry entries while replacing service diagnostics.
 
     Availability probes may contain exception text, local paths, tracebacks, or
-    credentials. Installation hints are registry-authored and remain intact.
+    credentials. Registry-authored fields are not probe output and remain
+    intact: ``install_hint``, ``setup_snippet`` and ``docs_url`` are all
+    VoiceStudio-owned constants keyed on the engine id, so an unavailable row
+    still has something actionable to show and somewhere to send the user
+    (#1866) even though ``reason``/``last_error`` are replaced here.
     """
     safe: list[dict] = []
     for entry in entries:
         item = dict(entry)
         if item.get("reason") is not None:
-            item["reason"] = _UNAVAILABLE
+            reason = _public_unavailable_reason(item["reason"])
+            # Only a row that explicitly says it has NO one-click install gets
+            # the manual wording. Rows without the field (ASR, LLM,
+            # translation — some of which have installers of their own) keep
+            # the line that points at Model Catalogue.
+            if item.get("one_click_install") is False:
+                reason = _MANUAL_INSTALL_VARIANT.get(reason, reason)
+            item["reason"] = reason
         if item.get("last_error") is not None:
             item["last_error"] = _PREVIOUS_FAILURE
         if item.get("routing_reason") is not None:
             item["routing_reason"] = _public_routing_reason(
                 item.get("routing_status"), item["routing_reason"]
             )
+        evidence = item.get("execution_evidence")
+        if isinstance(evidence, dict) and evidence.get("cpu_fallback_reason") is not None:
+            evidence = dict(evidence)
+            evidence["cpu_fallback_reason"] = _public_routing_reason(
+                "cpu_fallback", evidence["cpu_fallback_reason"]
+            )
+            item["execution_evidence"] = evidence
         safe.append(item)
     return safe
 

backend/api/routers/archetypes.py

@@ -57,11 +57,12 @@ _PREVIEW_SEED = 42
 # 32 reliably converges to speech across the gallery's instruct/script space
 # at a one-time (cached) render cost.
 _PREVIEW_NUM_STEP = 32
-# Spectral-flatness floor below which a render is a degenerate tonal artifact
-# rather than speech. Real, mastered speech sits ~0.04–0.07; a tonal buzz
-# collapses to <0.005. 0.015 separates the two with wide margin and sits well
-# below even breathy/whisper voices (which are broadband → high flatness).
-_DEGENERATE_FLATNESS = 0.015
+# Reject near-pure tonal artifacts using mean framed spectral flatness.
+# Calibrated against the tracked speech demos exercised by
+# test_archetype_preview_quality.py: the quietest (Mandarin dubbing, 44.1 kHz)
+# measures ~7.7e-6, while the worst tested tonal buzz measures ~3.3e-9.
+# 1e-7 leaves >10x margin on both sides without rejecting low-flatness speech.
+_DEGENERATE_FLATNESS = 1e-7
 
 
 def _preview_key(a: dict) -> str:
@@ -248,24 +249,46 @@ def _is_blank_audio(audio_tensor) -> bool:
         return False
 
 
+_FLATNESS_FRAME = 1024
+_FLATNESS_HOP = 512
+#: Frames quieter than this fraction of the loudest frame's energy are the gaps
+#: between words, not speech; their spectrum is the noise floor and averaging it
+#: in drags the measurement toward the value of whatever silence sounds like.
+_FLATNESS_FRAME_FLOOR = 1e-4
+
+
 def _spectral_flatness(audio_tensor) -> Optional[float]:
-    """Geometric-mean / arithmetic-mean of the power spectrum.
+    """Mean per-frame geometric-mean / arithmetic-mean of the power spectrum.
 
     ~1.0 for broadband noise, →0 for a pure tone. The degenerate diffusion
-    renders this guards against are near-pure tonal buzzes (flatness <0.005),
-    distinct from both silence (caught by ``_is_blank_audio``) and real speech
-    (~0.04+). Returns ``None`` if it can't be computed so callers don't act on
-    a bad measurement.
+    renders this guards against are near-pure tonal buzzes, distinct from both
+    silence (caught by ``_is_blank_audio``) and real speech. Returns ``None``
+    if it can't be computed so callers don't act on a bad measurement.
+
+    Measured over short frames and averaged — the standard definition. A single
+    FFT of the whole clip (what this used to do) is not the same quantity: its
+    frequency resolution grows with clip length, so speech harmonics carve
+    ever-deeper nulls into the spectrum and the geometric mean collapses. That
+    made the result depend on how long the clip was rather than on what it
+    sounded like, and put real speech below the rejection threshold.
     """
     try:
         import torch
 
         t = audio_tensor if isinstance(audio_tensor, torch.Tensor) else torch.as_tensor(audio_tensor)
-        t = t.detach().to("cpu", dtype=torch.float32).flatten()
-        if t.numel() < 1024 or not torch.isfinite(t).all():
+        t = t.detach().to("cpu", dtype=torch.float32)
+        if t.ndim > 1:
+            t = t.mean(dim=0)
+        t = t.flatten()
+        if t.numel() < _FLATNESS_FRAME or not torch.isfinite(t).all():
             return None
-        spec = torch.fft.rfft(t * torch.hann_window(t.numel())).abs().pow(2) + 1e-12
-        return float(torch.exp(torch.mean(torch.log(spec))) / torch.mean(spec))
+        frames = t.unfold(0, _FLATNESS_FRAME, _FLATNESS_HOP)
+        spec = torch.fft.rfft(frames * torch.hann_window(_FLATNESS_FRAME)).abs().pow(2) + 1e-12
+        energy = spec.sum(dim=1)
+        spec = spec[energy > energy.max() * _FLATNESS_FRAME_FLOOR]
+        if spec.shape[0] == 0:
+            return None
+        return float((torch.exp(spec.log().mean(dim=1)) / spec.mean(dim=1)).mean())
     except Exception:  # never let the checker itself block a render
         return None
 
@@ -330,7 +353,7 @@ async def _render_archetype_wav(a: dict, out_path: Path) -> None:
     # GPU pool and brick the backend (#730 class). Budget comes from the shared
     # length-scaled helper (#1190) instead of the flat 300s default.
     from services.model_manager import generate_timeout_s
-    _budget = generate_timeout_s(text)
+    _budget = generate_timeout_s(text, engine=model)
     audio_tensor = await run_on_gpu_pool_guarded(
         lambda: _infer(_PREVIEW_SEED), what="Archetype preview generate",
         timeout=_budget)
@@ -357,15 +380,11 @@ async def _render_archetype_wav(a: dict, out_path: Path) -> None:
     # Runs on the dedicated watermark pool (#1190): AudioSeal embedding is CPU
     # work that holds no VRAM, so it must not occupy a GPU worker ahead of the
     # next generate on 1-worker hosts.
-    from services.watermark import mark_synthetic
-    from services.model_manager import get_watermark_pool
-    import functools
-    audio_tensor = await run_on_gpu_pool_guarded(
-        functools.partial(mark_synthetic, audio_tensor, model.sampling_rate,
-                          context="archetypes.render"),
-        what="Archetype watermark",
+    from services.watermark import mark_synthetic_async
+    audio_tensor = await mark_synthetic_async(
+        audio_tensor, model.sampling_rate,
+        context="archetypes.render",
         timeout=generate_timeout_s(""),
-        executor=get_watermark_pool(),
     )
 
     out_path.parent.mkdir(parents=True, exist_ok=True)

backend/api/routers/audiobook.py

@@ -361,7 +361,7 @@ LONGFORM_NUM_STEP = 32
 LONGFORM_GUIDANCE_SCALE = 2.0
 
 
-def _seed_segment_rng(base_seed, text: str, nonce: int = 0) -> None:
+def _seed_segment_rng(base_seed, text: str, nonce: int = 0) -> int | None:
     """Apply a profile's pinned seed to this synth call (#1139).
 
     ``_resolve_voice`` has always fetched the profile ``seed`` — but only the
@@ -380,11 +380,13 @@ def _seed_segment_rng(base_seed, text: str, nonce: int = 0) -> None:
     must cover /generate and here together, not one path.
     """
     if base_seed is None:
-        return
+        return None
     import torch
 
     from services.audiobook import segment_seed
-    torch.manual_seed(segment_seed(base_seed, text, nonce))
+    seed = segment_seed(base_seed, text, nonce)
+    torch.manual_seed(seed)
+    return seed
 
 
 def _base_seed(opts: ExpressiveOptions, voice: dict):
@@ -508,16 +510,21 @@ def _build_synth(
                 "get_model": get_model, "language": language, "opts": opts}
 
     backend = cls()
-    extra = _generic_extra_kwargs(opts)
+    native_proxy = bool(getattr(cls, "supports_native_omnivoice_controls", False))
+    extra = (_omnivoice_sampling_kwargs(opts) if native_proxy
+             else _generic_extra_kwargs(opts))
     next_nonce = _make_occ_counter(opts)
 
     def synth(text, voice_id, speed=None):
         v = resolve(voice_id)
-        _seed_segment_rng(_base_seed(opts, v), text, next_nonce())
+        seed = _seed_segment_rng(_base_seed(opts, v), text, next_nonce())
+        call_extra = dict(extra)
+        if native_proxy and seed is not None:
+            call_extra["seed"] = seed
         return backend.generate(
             text, language=language, ref_audio=v["ref_audio"],
             ref_text=v["ref_text"], instruct=v["instruct"], duration=None,
-            speed=float(speed) if speed else 1.0, **extra,
+            speed=float(speed) if speed else 1.0, **call_extra,
         )
     return {"mode": "generic", "resolve": resolve, "engine_id": engine_id,
             "synth": synth, "sample_rate": backend.sample_rate}
@@ -711,6 +718,10 @@ def _remote_chapter_call(chapter, *, engine_id, default_voice, voice_map,
         "expressive": opts.to_manifest(), "watermark": bool(watermark_enabled()),
     }
     signature = hashlib.sha256(json.dumps(params, sort_keys=True, default=str).encode()).hexdigest()
+    # The worker synthesizes from ``spans``, but the gateway and scheduler read
+    # top-level ``text`` to scale the remote execution deadline. Add this after
+    # the signature so existing content-addressed remote cache keys still hit.
+    params["text"] = "\n".join(row["text"] for row in rows)
     wav_path = os.path.join(cache_dir, f"remote-{signature}.wav")
 
     def decode(result):
@@ -732,7 +743,7 @@ async def _run_chapter(chapter, *, operation="audiobook", decision, job, default
                        voice_map, lexicon, cache_dir):
     """Run one chapter through the gateway; local preparation stays lazy."""
     from services import gpu_gateway
-    from services.tts_backend import active_backend_id
+    from services.tts_backend import active_backend_id, get_backend_class
 
     engine_id = active_backend_id()
     remote, remote_cache = _remote_chapter_call(
@@ -746,15 +757,27 @@ async def _run_chapter(chapter, *, operation="audiobook", decision, job, default
         return remote_cache, float(info.duration), True, None
 
     async def prepare_local():
+        from services.model_manager import generate_timeout_s
+
         synth, sr, resolve, local_engine = await _prepare_synth(
             default_voice, language=language, opts=opts, voice_map=voice_map
         )
+        try:
+            timeout_engine = get_backend_class(local_engine)
+        except ValueError:
+            # Tests and third-party integrations may inject a synth under a
+            # non-catalogue id. Keep the canonical host/text policy available;
+            # registered production engines still add their routing metadata.
+            timeout_engine = None
         return gpu_gateway.LocalCall(
             fn=lambda: _render_chapter_cached(
                 chapter, synth, sr, local_engine, resolve, cache_dir, lexicon,
                 language, opts, voice_map,
             ),
             what="Audiobook chapter",
+            timeout=generate_timeout_s(
+                remote.params["text"], engine=timeout_engine
+            ),
         )
 
     return await gpu_gateway.run(

backend/api/routers/batch.py

@@ -103,6 +103,93 @@ def _set_progress(job, stage, percent=0, **extra):
     job["progress"] = {"stage": stage, "percent": percent, **extra}
 
 
+#: Override for the native dub batch width. Set to 1 to disable batching.
+BATCH_WIDTH_ENV = "OMNIVOICE_DUB_BATCH_WIDTH"
+
+#: Hard ceiling on the override — a batch this wide is already amortizing
+#: almost all of the per-call setup, and beyond it the failure mode is an OOM
+#: that costs more than the saving.
+_MAX_BATCH_WIDTH = 16
+
+# Bound each allocation while persisting multipart uploads. Video inputs can
+# be many gigabytes; `await UploadFile.read()` with no size used to mirror the
+# entire file in process memory before writing it back out.
+_UPLOAD_CHUNK_BYTES = 1024 * 1024
+
+
+async def _save_upload(upload: UploadFile, destination: str) -> None:
+    try:
+        with open(destination, "wb") as output:
+            while chunk := await upload.read(_UPLOAD_CHUNK_BYTES):
+                output.write(chunk)
+    except BaseException:
+        try:
+            unlink_if_present(destination)
+        except FileCleanupError:
+            logger.warning("Could not remove incomplete batch upload", exc_info=True)
+        raise
+
+
+def _native_batch_width(backend) -> int:
+    """How many segments to render in one native batch on THIS host.
+
+    A native batch widens the forward pass, so the width cannot be a constant.
+    The default engine declares ``min_vram_gb = 6.0`` for a SINGLE job; an
+    unconditional 8-wide batch would OOM the 4-8 GB CUDA cards and the MPS
+    Macs where the per-segment path succeeds today — turning a throughput
+    optimization into a regression on exactly the hardware that already
+    struggles (#1616 is a 4 GB card reporting capacity failures). Default
+    behaviour must not get riskier on a host, so the width is derived from
+    measured headroom and falls back to 1 (no batching) when unknown.
+
+    CPU hosts get 1: batching there buys no kernel amortization and only
+    multiplies peak RAM.
+    """
+    override = os.environ.get(BATCH_WIDTH_ENV, "").strip()
+    if override:
+        try:
+            return max(1, min(_MAX_BATCH_WIDTH, int(override)))
+        except (TypeError, ValueError):
+            logger.warning(
+                "%s=%r is not an integer — deriving the batch width from the host instead.",
+                BATCH_WIDTH_ENV, override,
+            )
+    try:
+        from core.device_caps import detect_host_caps
+        caps = detect_host_caps()
+    except Exception:  # noqa: BLE001 — an unprobeable host takes the safe path
+        return 1
+    if caps.family == "cpu" or not caps.vram_gb:
+        return 1
+    headroom = caps.vram_gb - float(getattr(backend, "min_vram_gb", 0.0) or 0.0)
+    if headroom < 2.0:
+        return 1
+    if headroom < 6.0:
+        return 2
+    if headroom < 12.0:
+        return 4
+    return 8
+
+
+def _batch_timeout_s(texts: list[str], backend) -> float:
+    """Execution budget for one native batch.
+
+    Not the sum of the per-item budgets: ``generate_timeout_s`` returns a
+    floor (300s GPU / 600s CPU) plus per-length overage, so summing it across
+    eight items yields a ~2400s budget — and a wedged batch would hold a
+    GPU-pool worker for forty minutes before the reset this file depends on
+    (#730). One floor covers wedge detection for the whole call; only the
+    length-driven overage is genuinely additive.
+    """
+    from services.model_manager import generate_timeout_s
+
+    floor = generate_timeout_s("", engine=backend)
+    overage = sum(
+        max(0.0, generate_timeout_s(text, engine=backend) - floor) for text in texts
+    )
+    return floor + overage
+
+
 async def _run_batch_pipeline(job_id: str, job: dict):
     """Full batch dub pipeline: extract → transcribe → translate → generate → mix → export."""
     import subprocess
@@ -279,6 +366,111 @@ async def _run_batch_pipeline(job_id: str, job: dict):
         full_audio = torch.zeros(1, total_samples)
         total_segs = len(translated_segments)
 
+        # Native engines can amortize encoder/decoder setup across a small
+        # batch. Keep the adapter seam optional: engines without a real batch
+        # implementation inherit TTSBackend.generate_batch(), which preserves
+        # the established one-segment behavior below.
+        from services.tts_backend import TTSBackend
+        batched_audio: dict[int, torch.Tensor] = {}
+        has_native_batch = type(backend).generate_batch is not TTSBackend.generate_batch
+        if has_native_batch:
+            from services.text_normalization import normalize_for_tts
+
+            batch_ref_audio = None
+            batch_ref_text = None
+            if job.get("voice_id"):
+                from core.db import db_conn
+                from core.config import VOICES_DIR as _VD
+                with db_conn() as conn:
+                    row = conn.execute(
+                        "SELECT * FROM voice_profiles WHERE id=?",
+                        (job["voice_id"],),
+                    ).fetchone()
+                if row:
+                    if row["is_locked"] and row["locked_audio_path"]:
+                        batch_ref_audio = os.path.join(_VD, row["locked_audio_path"])
+                    elif row["ref_audio_path"]:
+                        batch_ref_audio = os.path.join(_VD, row["ref_audio_path"])
+                    batch_ref_text = row["ref_text"]
+
+            batch_width = _native_batch_width(backend)
+
+            async def _prefetch_batch(first_index: int) -> None:
+                """Render the batch beginning at ``first_index`` into
+                ``batched_audio``.
+
+                Rendered on demand rather than prerendering the whole track:
+                the tensors are popped as they are placed, so peak host memory
+                is one batch instead of every segment of the language — and
+                the progress bar tracks placement instead of running to the
+                end and restarting at segment 1.
+                """
+                if job["status"] == "cancelled":
+                    return
+                batch_rows = []
+                index = first_index
+                while index < total_segs and len(batch_rows) < batch_width:
+                    seg = translated_segments[index]
+                    if (seg.get("end", 0) - seg.get("start", 0) > 0.05
+                            and seg.get("text", "").strip()):
+                        batch_rows.append((index, seg))
+                    index += 1
+                if len(batch_rows) < 2:
+                    return  # nothing to amortize — the per-segment path is equal
+                batch_indices = [index for index, _ in batch_rows]
+                batch_texts = [
+                    normalize_for_tts(row.get("text", "").strip(), target_lang)
+                    for _, row in batch_rows
+                ]
+                batch_durations = [
+                    row.get("end", 0) - row.get("start", 0)
+                    for _, row in batch_rows
+                ]
+
+                def _render_native_batch():
+                    generated = backend.generate_batch(
+                        batch_texts,
+                        language=target_lang,
+                        ref_audio=batch_ref_audio,
+                        ref_text=batch_ref_text,
+                        duration=batch_durations,
+                        num_step=16,
+                        guidance_scale=2.0,
+                        speed=1.0,
+                        denoise=True,
+                        postprocess_output=True,
+                    )
+                    if len(generated) != len(batch_indices):
+                        raise RuntimeError(
+                            f"native batch returned {len(generated)} outputs for "
+                            f"{len(batch_indices)} segments"
+                        )
+                    rendered = []
+                    for audio_out in generated:
+                        if not getattr(backend, "applies_own_mastering", False):
+                            audio_out = apply_mastering(audio_out, sample_rate=sr)
+                        rendered.append(normalize_audio(audio_out, target_dBFS=-2.0))
+                    return rendered
+
+                try:
+                    rendered = await run_on_gpu_pool_guarded(
+                        _render_native_batch,
+                        what="Batch generate",
+                        timeout=_batch_timeout_s(batch_texts, backend),
+                    )
+                    batched_audio.update(zip(batch_indices, rendered))
+                except TimeoutError:
+                    # Do not immediately queue the same expensive work again:
+                    # the timed-out pool task may still be holding the device.
+                    raise
+                except Exception as e:
+                    logger.warning(
+                        "Native TTS batch failed for segments %s-%s; falling back per segment: %s",
+                        batch_indices[0] + 1,
+                        batch_indices[-1] + 1,
+                        e,
+                    )
+
         for i, seg in enumerate(translated_segments):
             if job["status"] == "cancelled":
                 return
@@ -356,10 +548,15 @@ async def _run_batch_pipeline(job_id: str, job: dict):
                 # Budget is the shared length-scaled one (#1190): a long segment
                 # on CPU-class hardware no longer dies on the flat 300s.
                 from services.model_manager import generate_timeout_s
-                audio_tensor = await run_on_gpu_pool_guarded(
-                    _gen, what="Batch generate",
-                    timeout=generate_timeout_s(seg_text),
-                )
+                if has_native_batch and i not in batched_audio:
+                    await _prefetch_batch(i)
+                if i in batched_audio:
+                    audio_tensor = batched_audio.pop(i)
+                else:
+                    audio_tensor = await run_on_gpu_pool_guarded(
+                        _gen, what="Batch generate",
+                        timeout=generate_timeout_s(seg_text, engine=backend),
+                    )
 
                 # Fit to slot
                 target_samples_seg = int(seg_duration * sr)
@@ -413,19 +610,15 @@ async def _run_batch_pipeline(job_id: str, job: dict):
         # unmarked while the interactive dub pipeline marked every segment.
         # One whole-track embed (chunked internally, #1045) is equivalent to
         # dub_generate's per-segment marks: the 16-bit message repeats
-        # throughout. Runs in the GPU pool like generate's finalize; never
-        # raises (degrades to unmarked on failure, same as every producer).
+        # throughout. Never raises (degrades to unmarked on failure, same as
+        # every producer).
         # Dispatched to the dedicated watermark pool, not the GPU pool (#1190):
         # AudioSeal embedding is CPU work that holds no VRAM, and a whole-track
         # embed is long enough that occupying a GPU worker with it stalled the
         # next language's segments on 1-worker hosts.
-        from services.watermark import mark_synthetic
-        from services.model_manager import get_watermark_pool
-        import functools
-        full_audio = await loop.run_in_executor(
-            get_watermark_pool(),
-            functools.partial(mark_synthetic, full_audio, sr,
-                              context="batch.dub_track"),
+        from services.watermark import mark_synthetic_async
+        full_audio = await mark_synthetic_async(
+            full_audio, sr, context="batch.dub_track",
         )
 
         # Same assembly pattern as dub_generate.py:390 — `full_audio` is a
@@ -515,9 +708,7 @@ async def enqueue_batch_job(
     ext = os.path.splitext(video.filename or "video.mp4")[1] or ".mp4"
     video_path = os.path.join(batch_dir, f"{job_id}{ext}")
 
-    with open(video_path, "wb") as f:
-        content = await video.read()
-        f.write(content)
+    await _save_upload(video, video_path)
 
     job = {
         "id": job_id,

backend/api/routers/capture.py

@@ -28,6 +28,17 @@ router = APIRouter()
 logger = logging.getLogger("omnivoice.capture")
 
 
+def _timing(value):
+    """A segment timing, or ``None`` when the engine could not determine one.
+
+    ``dict.get(key, 0)`` hands back a stored ``None`` rather than the default,
+    because the key is present — so rounding it raised and took a transcript
+    that was otherwise fine down with it (#1904). Pass the null through instead:
+    the segment list renders whichever half of the range is known.
+    """
+    return round(value, 2) if isinstance(value, (int, float)) else None
+
+
 def _truthy(value: Optional[str]) -> bool:
     """Parse a multipart form flag. Treats '1'/'true'/'yes'/'on'/'auto'
     (any case) as on; everything else — including None — as off."""
@@ -162,10 +173,15 @@ async def transcribe_audio(
         from services.text_polish import polish_text
         full_text = polish_text(full_text)
 
-        # Calculate audio duration from segments if available
+        # Calculate audio duration from segments if available. A segment whose
+        # timing the engine could not determine carries end=None (sherpa's
+        # _sherpa_result when the sample rate yields no duration, and every
+        # plain-text OpenAI-compatible response), so measure only the ones that
+        # have a number and keep 0.0 when none do.
         duration = 0.0
         if segments:
-            duration = max(s.get("end", 0) for s in segments)
+            ends = [e for e in (s.get("end") for s in segments) if isinstance(e, (int, float))]
+            duration = max(ends) if ends else 0.0
 
         detected_lang = result.get("language", language or "unknown")
 
@@ -194,8 +210,8 @@ async def transcribe_audio(
             "text": full_text,
             "segments": [
                 {
-                    "start": round(s.get("start", 0), 2),
-                    "end": round(s.get("end", 0), 2),
+                    "start": _timing(s.get("start", 0)),
+                    "end": _timing(s.get("end", 0)),
                     "text": s.get("text", "").strip(),
                 }
                 for s in segments

backend/api/routers/capture_ws.py

@@ -27,6 +27,10 @@ Protocol:
          "detail": "..."}                                  — error ("detail"
                                                           kept for legacy)
 
+    Sherpa ``final`` frames additionally carry
+    ``"final_kind": "utterance"|"summary"``. Utterances are mid-session
+    commits; the summary is the authoritative whole-session result at EOF.
+
     Every ``final`` text is normalised by services.text_polish (leading
     capital for Latin scripts, terminal punctuation, single-spaced) so the
     pasted result reads like typed text. Partials are raw.
@@ -34,10 +38,14 @@ Protocol:
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
+import math
 import os
 import tempfile
 import time
+import uuid
+from typing import Any
 
 from fastapi import APIRouter, WebSocket, WebSocketDisconnect
 
@@ -47,6 +55,20 @@ from services.text_polish import polish_text
 router = APIRouter()
 logger = logging.getLogger("omnivoice.capture_ws")
 
+
+def _timing(value):
+    """A segment timing, or ``None`` when the engine could not determine one.
+
+    ``dict.get(key, 0)`` returns a stored ``None`` rather than the default, so
+    rounding it raised (#1904). The null is the honest answer here — this module
+    emits it deliberately for un-endpointed utterances — and the segment list
+    renders whichever half of the range is known.
+    """
+    return round(value, 2) if isinstance(value, (int, float)) else None
+
+SPEECH_PROTOCOL = "voicestudio.speech.v1"
+PLATFORM_STREAM_PATH = "/v1/audio/transcriptions/stream"
+
 # How often (seconds) to run transcription on the accumulated buffer.
 # Shorter = more responsive but more GPU load.
 PARTIAL_INTERVAL_S = float(os.environ.get("OMNIVOICE_STREAM_INTERVAL", "2.0"))
@@ -70,17 +92,79 @@ _AEC_NEAR = 0x00  # microphone frame (clean it, then buffer for ASR)
 _AEC_FAR = 0x01   # playback reference frame (feed the echo model only)
 
 
-def _requested_pcm_sample_rate(query_params) -> int | None:
-    """Return a bounded PCM rate for ``?pcm=1``/``?aec=1`` sessions."""
-    raw_pcm = query_params.get("pcm") in ("1", "true", "on")
-    aec = query_params.get("aec") in ("1", "true", "on")
-    if not raw_pcm and not aec:
-        return None
+# Client-supplied ``?sr=`` values outside the range real capture devices use
+# are replaced with 16 kHz. The rate sizes server-side state — RecoveryTail
+# multiplies it by RECOVERY_TAIL_SECONDS to compute its byte ceiling — so an
+# absurd rate must never be believed: it would re-open the unbounded-memory
+# path the recovery-tail cap closed.
+SR_MIN, SR_MAX = 8000, 96000
+
+
+def _is_end_control(text: str | None) -> bool:
+    """Accept the versioned JSON control frame and the legacy ``EOF`` frame."""
+    if text == "EOF":
+        return True
+    if not text:
+        return False
+    try:
+        message = json.loads(text)
+    except (TypeError, json.JSONDecodeError):
+        return False
+    return isinstance(message, dict) and message.get("type") == "input_audio.end"
+
+
+class _PlatformWebSocket:
+    """Add v1 session metadata without changing the legacy WebSocket contract."""
+
+    def __init__(self, websocket: WebSocket):
+        self._websocket = websocket
+        self.session_id = uuid.uuid4().hex
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._websocket, name)
+
+    async def send_json(self, data: Any, mode: str = "text") -> None:
+        if isinstance(data, dict):
+            data = dict(data)
+            data.setdefault("protocol", SPEECH_PROTOCOL)
+            data.setdefault("session_id", self.session_id)
+            if data.get("type") == "final":
+                data.setdefault("final_kind", "summary")
+        await self._websocket.send_json(data, mode=mode)
+
+
+def _bounded_sample_rate(query_params) -> int:
     try:
         sample_rate = int(query_params.get("sr", "16000"))
     except (TypeError, ValueError):
         return 16000
-    return sample_rate if 8000 <= sample_rate <= 96000 else 16000
+    return sample_rate if SR_MIN <= sample_rate <= SR_MAX else 16000
+
+
+def _requested_pcm_sample_rate(query_params) -> int | None:
+    """Return the bounded rate when the client transport is raw PCM.
+
+    Sherpa clients omit ``pcm=1`` because the selected model already defines
+    that transport. If the model is demoted or its runtime is unavailable, the
+    legacy recognizer fallback must still decode those same bytes as PCM.
+    """
+    raw_pcm = query_params.get("pcm") in ("1", "true", "on")
+    aec = query_params.get("aec") in ("1", "true", "on")
+    sherpa_pcm = False
+    requested_model = query_params.get("model")
+    if requested_model:
+        try:
+            from services.sherpa_dictation import is_sherpa_model
+            sherpa_pcm = is_sherpa_model(requested_model)
+        except Exception:  # noqa: BLE001
+            # A broken sherpa install must not decide the framing question —
+            # sherpa_pcm stays False and the session negotiates the
+            # MediaRecorder path; availability is re-probed (and reported)
+            # when the model is actually selected.
+            sherpa_pcm = False
+    if not raw_pcm and not aec and not sherpa_pcm:
+        return None
+    return _bounded_sample_rate(query_params)
 
 
 def _demux_aec_frame(data: bytes) -> tuple[str, bytes]:
@@ -137,21 +221,47 @@ def _select_sherpa_spec(websocket: WebSocket):
         from services import sherpa_dictation as sd
     except Exception:
         return None
+
+    def _usable_spec(model_id):
+        spec = sd.get_spec(model_id)
+        if spec is not None and sd.is_demoted(spec.id):
+            logger.warning(
+                "dictation model %s is demoted — using the capture ASR fallback",
+                spec.id,
+            )
+            return None
+        return spec
+
     requested = websocket.query_params.get("model")
     if requested:
-        return sd.get_spec(requested)  # explicit selection (may be None if bad)
+        return _usable_spec(requested)  # explicit selection (may be unavailable)
     # Fall back to the persisted dictation pref.
     try:
         from services.asr_backend import dictation_model_id
         mid = dictation_model_id()
     except Exception:
         mid = None
-    return sd.get_spec(mid) if mid else None
+    return _usable_spec(mid) if mid else None
 
 
+@router.websocket(PLATFORM_STREAM_PATH)
 @router.websocket("/ws/transcribe")
 async def ws_transcribe(websocket: WebSocket):
     """Stream audio in, get partial + final transcription out."""
+    is_platform_stream = websocket.url.path == PLATFORM_STREAM_PATH
+    if is_platform_stream:
+        websocket = _PlatformWebSocket(websocket)
+    # A browser can reach localhost regardless of the page's own origin.
+    # Reject ambient cross-site WebSocket handshakes before the loopback-host
+    # shortcut or accept(), while keeping native clients (no Origin header)
+    # and configured/same-origin browser UIs working (#1646 review).
+    origin = websocket.headers.get("origin")
+    if origin:
+        from core.csrf import origin_allowed
+
+        if not origin_allowed(websocket):
+            await websocket.close(code=1008, reason="browser origin not allowed")
+            return
     # Loopback origin guard — refuse anything not from 127.0.0.1, ::1, or
     # localhost. Privileged HTTP routers use Depends(require_admin) at router
     # level; WebSocket dependency injection differs across FastAPI versions, so we
@@ -166,6 +276,16 @@ async def ws_transcribe(websocket: WebSocket):
         return
 
     await websocket.accept()
+    if is_platform_stream:
+        await websocket.send_json({
+            "type": "session.started",
+            "input_format": (
+                "audio/pcm;encoding=s16le;channels=1"
+                if _requested_pcm_sample_rate(websocket.query_params) is not None
+                else "audio/webm;codecs=opus"
+            ),
+            "sample_rate": _bounded_sample_rate(websocket.query_params),
+        })
 
     # Live-dictation engine selection. When a sherpa-onnx model is selected
     # (via ?model= or the dictation.model_id pref) AND sherpa is installed,
@@ -240,6 +360,7 @@ async def ws_transcribe(websocket: WebSocket):
     audio_chunks: list[bytes] = []
     total_bytes = 0
     last_audio_time = time.monotonic()
+    paused = False
     running = True
     partial_text = ""
     # Track whether the client initiated the disconnect. When True the
@@ -257,7 +378,7 @@ async def ws_transcribe(websocket: WebSocket):
         message as the authoritative result and skip the duplicate HTTP
         POST that used to run on every dictation.
         """
-        nonlocal total_bytes, last_audio_time, running, client_disconnected
+        nonlocal total_bytes, last_audio_time, running, client_disconnected, paused
         try:
             while running:
                 msg = await websocket.receive()
@@ -288,7 +409,11 @@ async def ws_transcribe(websocket: WebSocket):
                     total_bytes += len(data)
                     last_audio_time = time.monotonic()
                     continue
-                if msg.get("text") == "EOF":
+                if msg.get("text") in ("PAUSE", "RESUME"):
+                    paused = msg["text"] == "PAUSE"
+                    last_audio_time = time.monotonic()
+                    continue
+                if _is_end_control(msg.get("text")):
                     # Client signals end-of-audio but stays connected for `final`.
                     running = False
                     break
@@ -320,6 +445,9 @@ async def ws_transcribe(websocket: WebSocket):
             if not running:
                 break
 
+            if paused:
+                continue
+
             # Check silence timeout
             if time.monotonic() - last_audio_time > SILENCE_TIMEOUT_S and total_bytes > MIN_BUFFER_BYTES:
                 running = False
@@ -422,6 +550,64 @@ SHERPA_OFFLINE_SILENCE_S = float(os.environ.get("OMNIVOICE_SHERPA_OFFLINE_SILENC
 SHERPA_OFFLINE_RMS_FLOOR = float(os.environ.get("OMNIVOICE_SHERPA_OFFLINE_RMS", "0.01"))
 
 
+#: Seconds of audio retained for silent-model recovery. Recovery only needs
+#: enough speech to prove the model is broken and to re-transcribe what was
+#: said; retaining the whole session grew ~115 MB/hour at 16 kHz on an open
+#: mic, unbounded, and only ever got read when the fallback fired.
+RECOVERY_TAIL_DEFAULT_SECONDS = 120.0
+RECOVERY_TAIL_MAX_SECONDS = 300.0
+
+
+def _bounded_recovery_tail_seconds(value: str | None) -> float:
+    """Parse the recovery tail override without allowing unbounded buffers."""
+    try:
+        seconds = float(value) if value is not None else RECOVERY_TAIL_DEFAULT_SECONDS
+    except (TypeError, ValueError):
+        return RECOVERY_TAIL_DEFAULT_SECONDS
+    if not math.isfinite(seconds) or seconds <= 0:
+        return RECOVERY_TAIL_DEFAULT_SECONDS
+    return min(seconds, RECOVERY_TAIL_MAX_SECONDS)
+
+
+RECOVERY_TAIL_SECONDS = _bounded_recovery_tail_seconds(
+    os.environ.get("OMNIVOICE_DICTATION_RECOVERY_TAIL_S")
+)
+
+
+class RecoveryTail:
+    """The most recent ``RECOVERY_TAIL_SECONDS`` of session audio.
+
+    Keeps the *tail* rather than the head: a long dictation's useful speech is
+    what the user just said, and the silent-model check cares about how much
+    audio the session carried overall — which ``total_bytes`` still reports
+    truthfully after trimming.
+    """
+
+    __slots__ = ("_buf", "_max", "total_bytes")
+
+    def __init__(self, sample_rate: int, seconds: float = RECOVERY_TAIL_SECONDS):
+        # int16 mono → 2 bytes/sample. Floor of one frame so a nonsense rate
+        # or seconds value can't produce a zero-length buffer.
+        self._max = max(2, int(seconds * max(1, sample_rate)) * 2)
+        self._buf = bytearray()
+        self.total_bytes = 0
+
+    def extend(self, pcm: bytes) -> None:
+        self._buf.extend(pcm)
+        self.total_bytes += len(pcm)
+        excess = len(self._buf) - self._max
+        if excess > 0:
+            # int16 mono: trim whole samples only. A split frame can carry an
+            # odd byte count, and an odd trim would leave the tail starting
+            # mid-sample — every later sample byte-shifted, and the recovery
+            # transcription fed noise.
+            excess += excess % 2
+            del self._buf[:excess]
+
+    def tail(self) -> bytes:
+        return bytes(self._buf)
+
+
 def is_model_silent(text: str, heard_speech: bool, pcm_bytes: int) -> bool:
     """True when the dictation model produced NO text despite real speech.
 
@@ -448,19 +634,74 @@ def _pcm16_to_f32(pcm: bytes):
     return np.frombuffer(pcm, dtype=np.int16).astype(np.float32) / 32768.0
 
 
-async def _sherpa_session(websocket: WebSocket):
-    """Shared WS receive setup for the sherpa handlers.
+def _pcm16_rms(pcm: bytes) -> float:
+    samples = _pcm16_to_f32(pcm)
+    if not len(samples):
+        return 0.0
+    return float((samples * samples).mean() ** 0.5)
 
-    Returns ``(get_frame, state)`` where ``get_frame`` is an async callable
-    that yields the next near-end (mic) PCM bytes, ``b""`` for a keepalive/ref
-    frame, or ``None`` on EOF/disconnect. ``state`` carries sample rate, AEC,
-    and the disconnect flag for the caller's finaliser.
-    """
-    pcm_sr = 16000
+
+async def _recover_silent_sherpa(
+    spec, pcm: bytes, pcm_sr: int,
+) -> tuple[str, list[dict]]:
+    """Retry a token-silent Sherpa session through an installed local ASR."""
+    logger.warning(
+        "dictation model %s decoded NOTHING from %.1fs of speech-level audio "
+        "— falling back to the capture ASR engine for this session",
+        spec.id, len(pcm) / float(max(1, pcm_sr) * 2),
+    )
     try:
-        pcm_sr = int(websocket.query_params.get("sr", "16000"))
-    except (TypeError, ValueError):
-        pcm_sr = 16000
+        from services.asr_backend import asr_model_missing_error
+        fallback_missing = await asyncio.to_thread(
+            asr_model_missing_error,
+            purpose="dictation",
+            skip_sherpa=True,
+            require_installed=True,
+        )
+        if fallback_missing is not None:
+            logger.warning(
+                "dictation silent-model fallback is not installed (%s); "
+                "skipping recovery to avoid an automatic download",
+                fallback_missing.get("missing_repo_id", "unknown"),
+            )
+            return "", []
+
+        result = await _transcribe_buffer_full(
+            [pcm], pcm_sr=pcm_sr, skip_sherpa=True,
+        )
+        text = polish_text(_result_text(result))
+        if not text:
+            return "", []
+        # The RMS gate can fire on fan/keyboard noise. Only another recognizer
+        # producing words proves the audio held speech and makes persistent
+        # demotion safe.
+        try:
+            from services.sherpa_dictation import demote_model
+            if await asyncio.to_thread(demote_model, spec.id):
+                logger.error(
+                    "dictation model %s demoted on this machine — it will no longer be "
+                    "auto-selected. Pick it again in Settings to give it another chance.",
+                    spec.id,
+                )
+        except Exception:
+            logger.exception("silent-model demotion failed")
+        segments = (result or {}).get("segments") or [
+            {"start": 0.0, "end": None, "text": text}
+        ]
+        return text, segments
+    except Exception:
+        logger.exception("dictation silent-model fallback failed")
+        return "", []
+
+
+async def _sherpa_session(websocket: WebSocket):
+    """Shared WS setup for the sherpa handlers.
+
+    Returns ``(pcm_sr, aec)``: the bounded PCM sample rate for the session
+    and the echo canceller when ``?aec=1`` requested one (``None`` otherwise
+    or when AEC setup fails).
+    """
+    pcm_sr = _bounded_sample_rate(websocket.query_params)
     aec = None
     if websocket.query_params.get("aec") in ("1", "true", "on"):
         try:
@@ -498,7 +739,7 @@ async def _recv_pcm_frame(websocket: WebSocket, aec):
                 return "skip", b""
             return "near", aec.process_near_end(payload)
         return "near", data
-    if msg.get("text") == "EOF":
+    if _is_end_control(msg.get("text")):
         return "eof", b""
     return "skip", b""
 
@@ -569,6 +810,8 @@ async def _run_sherpa_streaming(websocket: WebSocket, spec):
 
     last_partial = ""
     committed: list[str] = []     # finalized utterances this session
+    session_pcm = RecoveryTail(pcm_sr)   # bounded audio for silent-model recovery
+    heard_speech = False
     client_disconnected = False
 
     async def _send(payload) -> bool:
@@ -610,6 +853,9 @@ async def _run_sherpa_streaming(websocket: WebSocket, spec):
                 break
             if kind == "skip":
                 continue
+            session_pcm.extend(pcm)
+            if not heard_speech and _pcm16_rms(pcm) >= SHERPA_OFFLINE_RMS_FLOOR:
+                heard_speech = True
             text, endpoint = await asyncio.to_thread(_decode_after_feed, pcm)
             if endpoint:
                 # Commit this utterance (polished — it gets pasted); reset
@@ -618,6 +864,7 @@ async def _run_sherpa_streaming(websocket: WebSocket, spec):
                 if text:
                     committed.append(text)
                     await _send({"type": "final", "text": text,
+                                 "final_kind": "utterance",
                                  "segments": [{"start": 0.0, "end": None, "text": text}],
                                  "language": "auto", "engine": backend.id})
                 rec.reset(stream)
@@ -644,7 +891,28 @@ async def _run_sherpa_streaming(websocket: WebSocket, spec):
     # Pieces are already polished; the join is too (polish is idempotent).
     full = " ".join(t for t in committed if t).strip()
     segments = [{"start": 0.0, "end": None, "text": t} for t in committed if t]
+
+    model_silent = is_model_silent(full, heard_speech, session_pcm.total_bytes)
+    if model_silent:
+        recovered, recovered_segments = await _recover_silent_sherpa(
+            spec, session_pcm.tail(), pcm_sr,
+        )
+        if recovered:
+            full = recovered
+            segments = recovered_segments
+
     if not client_disconnected:
+        payload = {"type": "final", "text": full, "final_kind": "summary",
+                   "segments": segments,
+                   "language": "auto", "engine": backend.id}
+        if model_silent:
+            payload["engine"] = "capture-asr-fallback" if full else backend.id
+            payload["model_silent"] = spec.id
+            payload["warning"] = (
+                f"The selected dictation model ({spec.id}) produced no text from your "
+                "speech. Switched to the fallback engine for this session — pick a "
+                "different model in Settings → Dictation."
+            )
         if full:
             # Hard-bounded refinement (~4s): never delays this summary `final`
             # beyond OMNIVOICE_REFINE_TIMEOUT_S even with a dead LLM endpoint.
@@ -653,14 +921,9 @@ async def _run_sherpa_streaming(websocket: WebSocket, spec):
                 refined = await maybe_refine_async(full)
             except Exception:
                 refined = None
-            payload = {"type": "final", "text": full, "segments": segments,
-                       "language": "auto", "engine": backend.id}
             if refined and refined != full:
                 payload["refined_text"] = refined
-            await _send(payload)
-        else:
-            await _send({"type": "final", "text": "", "segments": [],
-                         "language": "auto", "engine": backend.id})
+        await _send(payload)
         try:
             await websocket.close()
         except Exception:
@@ -697,7 +960,7 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
     # whisper/zipformer transcribe the same bytes). Keep the whole session's
     # audio and whether any of it was speech-level, so the finaliser can tell
     # "user said nothing" (fine) from "model produced nothing" (broken).
-    session_pcm = bytearray()
+    session_pcm = RecoveryTail(pcm_sr)
     heard_speech = False
     running = True
     client_disconnected = False
@@ -716,12 +979,6 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
             client_disconnected = True
             return False
 
-    def _rms(pcm: bytes) -> float:
-        samples = _pcm16_to_f32(pcm)
-        if not len(samples):
-            return 0.0
-        return float((samples * samples).mean() ** 0.5)
-
     def _decode_window(pcm: bytes) -> str:
         samples = _pcm16_to_f32(pcm)
         if not len(samples):
@@ -740,7 +997,7 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
                     continue
                 buf.extend(pcm)
                 session_pcm.extend(pcm)
-                if not heard_speech and _rms(pcm) >= SHERPA_OFFLINE_RMS_FLOOR:
+                if not heard_speech and _pcm16_rms(pcm) >= SHERPA_OFFLINE_RMS_FLOOR:
                     heard_speech = True
                 last_audio = time.monotonic()
         except WebSocketDisconnect:
@@ -766,6 +1023,7 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
         if text:
             committed.append(text)
             await _send({"type": "final", "text": text,
+                         "final_kind": "utterance",
                          "segments": [{"start": 0.0, "end": None, "text": text}],
                          "language": "auto", "engine": backend.id})
 
@@ -777,8 +1035,8 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
                 continue
             snapshot = bytes(buf)
             if len(snapshot) > sil_bytes and \
-                    _rms(snapshot[-sil_bytes:]) < SHERPA_OFFLINE_RMS_FLOOR:
-                if _rms(snapshot[:-sil_bytes]) >= SHERPA_OFFLINE_RMS_FLOOR:
+                    _pcm16_rms(snapshot[-sil_bytes:]) < SHERPA_OFFLINE_RMS_FLOOR:
+                if _pcm16_rms(snapshot[:-sil_bytes]) >= SHERPA_OFFLINE_RMS_FLOOR:
                     await _commit(snapshot)
                 else:
                     # Pure silence — drop it (keep the gate window for
@@ -824,39 +1082,18 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
     # quiet user — hand the session to the capture ASR backend so the user
     # still gets their words, and say which model let them down. Bounded to
     # this session; the pref is left alone so the user stays in control.
-    model_silent = is_model_silent(full, heard_speech, len(session_pcm))
+    model_silent = is_model_silent(full, heard_speech, session_pcm.total_bytes)
     if model_silent:
-        logger.warning(
-            "dictation model %s decoded NOTHING from %.1fs of speech-level audio "
-            "— falling back to the capture ASR engine for this session",
-            spec.id, len(session_pcm) / float(max(1, pcm_sr) * 2),
+        recovered, recovered_segments = await _recover_silent_sherpa(
+            spec, session_pcm.tail(), pcm_sr,
         )
-        # Demote it so the NEXT session doesn't repeat this round trip. The
-        # curated default can be broken on a platform we never tested (the
-        # NeMo-TDT decoder is, on Windows), and observing it beats guessing.
-        try:
-            from services.sherpa_dictation import demote_model
-            if demote_model(spec.id):
-                logger.error(
-                    "dictation model %s demoted on this machine — it will no longer be "
-                    "auto-selected. Pick it again in Settings to give it another chance.",
-                    spec.id,
-                )
-        except Exception:
-            logger.exception("silent-model demotion failed")
-        try:
-            result = await _transcribe_buffer_full([bytes(session_pcm)], pcm_sr=pcm_sr)
-            fb_text = polish_text((result or {}).get("text", "") or "")
-            if fb_text:
-                full = fb_text
-                segments = (result or {}).get("segments") or [
-                    {"start": 0.0, "end": None, "text": fb_text}
-                ]
-        except Exception:
-            logger.exception("dictation silent-model fallback failed")
+        if recovered:
+            full = recovered
+            segments = recovered_segments
 
     if not client_disconnected:
-        payload = {"type": "final", "text": full, "segments": segments,
+        payload = {"type": "final", "text": full, "final_kind": "summary",
+                   "segments": segments,
                    "language": "auto", "engine": backend.id}
         if model_silent:
             # The client surfaces this so a silently-broken model can't look
@@ -884,6 +1121,35 @@ async def _run_sherpa_offline(websocket: WebSocket, spec):
             pass
 
 
+def _result_text(result: dict | None) -> str:
+    """Normalize text from every ASR backend result shape.
+
+    Some backends return a top-level ``text`` value, while WhisperX, Faster
+    Whisper, Moonshine, and OpenAI-compatible ASR expose only ``segments`` and
+    ``chunks``. Dictation partials and finals must interpret both contracts the
+    same way.
+    """
+    if not isinstance(result, dict):
+        return ""
+
+    text = result.get("text")
+    if isinstance(text, str) and text.strip():
+        return text.strip()
+
+    for key in ("segments", "chunks"):
+        items = result.get(key)
+        if not isinstance(items, (list, tuple)):
+            continue
+        text = " ".join(
+            str(item.get("text", "")).strip()
+            for item in items
+            if isinstance(item, dict) and item.get("text")
+        ).strip()
+        if text:
+            return text
+    return ""
+
+
 async def _transcribe_buffer(chunks: list[bytes], *, pcm_sr: int | None = None) -> str:
     """Quick partial transcription of the current audio buffer."""
 
@@ -898,7 +1164,7 @@ async def _transcribe_buffer(chunks: list[bytes], *, pcm_sr: int | None = None)
         def _run():
             backend = get_capture_asr_backend()
             result = backend.transcribe(tmp, word_timestamps=False)
-            return result.get("text", "")
+            return _result_text(result)
 
         # Bound dictation transcribes (#730): a wedged whisperx/CTranslate2 call
         # must not hold its GPU-pool worker forever and starve TTS / other ASR
@@ -912,7 +1178,9 @@ async def _transcribe_buffer(chunks: list[bytes], *, pcm_sr: int | None = None)
             pass
 
 
-async def _transcribe_buffer_full(chunks: list[bytes], *, pcm_sr: int | None = None) -> dict:
+async def _transcribe_buffer_full(
+    chunks: list[bytes], *, pcm_sr: int | None = None, skip_sherpa: bool = False,
+) -> dict:
     """Full transcription with timing info for the final result."""
     tmp = _pcm16_to_wav(b"".join(chunks), pcm_sr) if pcm_sr else _chunks_to_wav(chunks)
     if tmp is None:
@@ -924,15 +1192,13 @@ async def _transcribe_buffer_full(chunks: list[bytes], *, pcm_sr: int | None = N
         from services.asr_backend import get_capture_asr_backend, run_transcribe_guarded
 
         def _run():
-            backend = get_capture_asr_backend()
+            backend = get_capture_asr_backend(skip_sherpa=skip_sherpa)
             t0 = time.perf_counter()
             result = backend.transcribe(tmp, word_timestamps=False)
             elapsed = round(time.perf_counter() - t0, 2)
 
             segments = result.get("segments", [])
-            full_text = result.get("text", "")
-            if not full_text and segments:
-                full_text = " ".join(s.get("text", "") for s in segments).strip()
+            full_text = _result_text(result)
 
             # Wave 1.1: strip Whisper hallucination loops from the final
             # text (the string that gets auto-pasted). Segments keep the
@@ -940,13 +1206,19 @@ async def _transcribe_buffer_full(chunks: list[bytes], *, pcm_sr: int | None = N
             from services.refinement import collapse_repetitive_artifacts
             full_text = collapse_repetitive_artifacts(full_text)
 
-            duration = max((s.get("end", 0) for s in segments), default=0.0)
+            # end=None means the engine could not determine the timing — this
+            # module writes exactly that in its own streaming payloads, and
+            # sherpa's _sherpa_result does too when the sample rate yields no
+            # duration. Measure only real numbers, and pass the nulls through
+            # rather than rounding them (#1904).
+            ends = [e for e in (s.get("end") for s in segments) if isinstance(e, (int, float))]
+            duration = max(ends) if ends else 0.0
 
             return {
                 "text": full_text,
                 "segments": [
-                    {"start": round(s.get("start", 0), 2),
-                     "end": round(s.get("end", 0), 2),
+                    {"start": _timing(s.get("start", 0)),
+                     "end": _timing(s.get("end", 0)),
                      "text": s.get("text", "").strip()}
                     for s in segments
                 ],

backend/api/routers/dictation.py

@@ -86,6 +86,18 @@ def list_dictation_models():
     }
 
 
+@router.get("/dictation/readiness", dependencies=[Depends(require_local)])
+def dictation_readiness(model_id: str | None = None) -> dict:
+    """Check capture's model selection without loading or downloading weights."""
+    from services.asr_backend import asr_model_missing_error
+
+    missing = asr_model_missing_error(
+        purpose="dictation",
+        sherpa_model_id=model_id or _read_prefs()["model_id"],
+    )
+    return {"ready": missing is None, "missing": missing}
+
+
 @router.get("/dictation/prefs", dependencies=[Depends(require_local)])
 def get_dictation_prefs():
     return _read_prefs()

backend/api/routers/dub_core.py

@@ -134,6 +134,82 @@ _save_job          = dub_pipeline.save_job
 # paste (or a mis-aimed binary) burn CPU in the parser.
 _MAX_SUBTITLE_PASTE_CHARS = 2_000_000
 
+_SRT_REPLACED_FIELDS = {
+    "id",
+    "start",
+    "end",
+    "text",
+    "text_original",
+    "translations",
+    "translate_error",
+    "translate_degraded",
+}
+
+
+def _best_overlapping_segment(cue: dict, existing: list[dict]) -> dict | None:
+    """Return the prior segment with the strongest temporal overlap."""
+    cue_start = float(cue.get("start") or 0.0)
+    cue_end = float(cue.get("end") or cue_start)
+    cue_mid = (cue_start + cue_end) / 2.0
+    best = None
+    best_key = None
+    for index, segment in enumerate(existing):
+        start = float(segment.get("start") or 0.0)
+        end = float(segment.get("end") or start)
+        overlap = min(cue_end, end) - max(cue_start, start)
+        if overlap <= 0:
+            continue
+        midpoint_distance = abs(cue_mid - ((start + end) / 2.0))
+        key = (overlap, -midpoint_distance, -index)
+        if best_key is None or key > best_key:
+            best = segment
+            best_key = key
+    return best
+
+
+def _carry_srt_voice_metadata(
+    cues: list[dict],
+    existing: list[dict],
+    segment_clones: dict | None,
+    speaker_clones: dict | None = None,
+) -> tuple[list[dict], dict]:
+    """Replace subtitle content while retaining the source cast assignment."""
+    source_clones = dict(segment_clones or {})
+    source_speaker_clones = dict(speaker_clones or {})
+    # Replacement cues get new positional ids. Starting from the old map would
+    # let an unmatched cue whose new id happens to equal an old id inherit an
+    # unrelated reference. Only explicitly overlap-matched references survive.
+    clones = {}
+    merged_segments = []
+    for new_id, cue in enumerate(cues):
+        prior = _best_overlapping_segment(cue, existing)
+        metadata = {
+            key: value
+            for key, value in (prior or {}).items()
+            if key not in _SRT_REPLACED_FIELDS
+        }
+        merged = {
+            **metadata,
+            "id": new_id,
+            "start": cue.get("start", 0.0),
+            "end": cue.get("end", 0.0),
+            "text": cue.get("text", ""),
+            "text_original": cue.get("text", ""),
+        }
+        if not merged.get("speaker_id"):
+            merged["speaker_id"] = cue.get("speaker_id") or "Speaker 1"
+        if prior is not None:
+            prior_id = str(prior.get("id", ""))
+            clone = source_clones.get(prior_id)
+            if clone is None:
+                clone = source_speaker_clones.get(prior.get("speaker_id"))
+            if clone is not None:
+                clones[str(new_id)] = clone
+                if merged.get("profile_id") == f"auto-seg:{prior_id}":
+                    merged["profile_id"] = f"auto-seg:{new_id}"
+        merged_segments.append(merged)
+    return merged_segments, clones
+
 
 @router.post("/dub/parse-subtitle-text")
 def dub_parse_subtitle_text(req: ParseSubtitleTextRequest):
@@ -234,7 +310,32 @@ async def dub_import_srt(job_id: str, file: UploadFile = File(...)):
     else:
         segments = result.segments
 
+    prior_segments = [
+        segment for segment in (job.get("segments") or []) if isinstance(segment, dict)
+    ]
+    segments, segment_clones = _carry_srt_voice_metadata(
+        segments,
+        prior_segments,
+        job.get("segment_clones"),
+        job.get("speaker_clones"),
+    )
     job["segments"] = segments
+    job["segment_clones"] = segment_clones
+    # A pooled speaker clone is keyed only by a display label. Replacement
+    # cues can reuse that label without overlapping the original speaker, so
+    # retain matched pooled references as segment-specific clones above and
+    # drop the global map before rebuilding the cast.
+    job["speaker_clones"] = {}
+    if segment_clones:
+        from services.speaker_clone import build_cast_sources
+
+        job["cast_sources"] = build_cast_sources(
+            segments,
+            None,
+            segment_clones,
+        )
+    else:
+        job.pop("cast_sources", None)
     # `source_lang` stays whatever the user (or the upload step) set; we
     # don't try to language-detect off the cue text — that's noisy and the
     # user usually knows what their .srt is.
@@ -351,12 +452,13 @@ async def preview_upload(video: UploadFile = File(...)):
     safe_name = f"{uuid.uuid4().hex[:12]}"
     vid_path = os.path.join(PREVIEW_DIR, f"{safe_name}{ext}")
     wav_path = os.path.join(PREVIEW_DIR, f"{safe_name}.wav")
-    
-    with open(vid_path, "wb") as f:
-        f.write(await video.read())
-        
-    has_audio = False
-    if ext not in [".wav", ".mp3", ".m4a", ".aac"]:
+    payload = await video.read()
+
+    def _write_and_extract() -> bool:
+        with open(vid_path, "wb") as f:
+            f.write(payload)
+        if ext in {".wav", ".mp3", ".m4a", ".aac"}:
+            return False
         try:
             ffmpeg_cmd = [
                 find_ffmpeg(), "-y", "-i", vid_path,
@@ -368,10 +470,16 @@ async def preview_upload(video: UploadFile = File(...)):
                 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
                 timeout=300,
             )
-            has_audio = True
+            return True
         except Exception as e:
             logger.warning("FFmpeg extraction failed: %s", log_safe(e))
-            pass
+            return False
+
+    # File writes and ffmpeg are blocking operations. Keep them on the bounded
+    # CPU pool so a large preview cannot stall unrelated API requests (#1667).
+    has_audio = await asyncio.get_running_loop().run_in_executor(
+        _cpu_pool, _write_and_extract
+    )
 
     return {
         "url": f"/preview/{safe_name}{ext}",
@@ -410,12 +518,70 @@ _ingest_gen       = dub_pipeline.ingest_pipeline
 #: container so a mislabelled video can't slip past the video-skipping branch.
 _AUDIO_EXTS = {".wav", ".mp3", ".m4a", ".aac", ".flac", ".ogg", ".opus", ".wma"}
 
+# Source-language choices exposed by the first-party dub UI, plus every
+# language code Whisper can write back after auto-detection. A restored job
+# may reuse that detected value as the next upload's override, so rejecting our
+# own persisted codes strands otherwise valid dubbing sessions (#1737).
+# Keeping this an allow-list still rejects language names and private-use
+# BCP-47 tags. Values are normalized to lowercase below.
+_DUB_SOURCE_LANG_CODES = frozenset({
+    "af", "sq", "am", "ar", "hy", "az", "eu", "be", "bn", "bs", "bg",
+    "my", "ca", "cmn-hans", "cmn-hant", "hr", "cs", "da", "nl", "en",
+    "et", "fi", "fr", "gl", "ka", "de", "el", "gu", "ht", "ha", "haw",
+    "he", "hi", "hu", "is", "id", "it", "ja", "jw", "kn", "kk", "km",
+    "ko", "ku", "ky", "lo", "la", "lv", "lt", "mk", "ms", "ml", "mt",
+    "mi", "mr", "mn", "ne", "no", "ps", "fa", "pl", "pt", "pa", "ro",
+    "ru", "sm", "gd", "sr", "sn", "sd", "si", "sk", "sl", "so", "es",
+    "su", "sw", "sv", "tg", "ta", "te", "th", "tr", "uk", "ur", "uz",
+    "vi", "cy", "xh", "yi", "yo", "zu",
+    "as", "ba", "bo", "br", "fo", "lb", "ln", "mg", "nn", "oc", "sa",
+    "tk", "tl", "tt", "yue", "zh",
+})
+
+
+def _source_lang_override(value: str | None) -> str | None:
+    """Normalize a user-selected source language; auto/und means detect.
+
+    A rejection NAMES the code it rejected. "Invalid source language code" on
+    its own cannot be acted on or reported usefully: it does not say which of
+    the ninety-odd codes was wrong, so neither the user nor a maintainer
+    reading the auto-filed issue can tell whether the picker offered something
+    the backend does not accept, or a stale preference from an older build is
+    still being sent (#1960).
+
+    The value is a language code the user chose from a menu — not private
+    data — and the neighbouring engine validator already echoes its input the
+    same way.
+    """
+    code = (value or "").strip().lower()
+    if code in {"", "auto", "und"}:
+        return None
+    if code not in _DUB_SOURCE_LANG_CODES:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                f"Invalid source language code: {code!r}. Pick a language from "
+                "the Dubbing source-language menu, or leave it on auto-detect."
+            ),
+        )
+    return code
+
+
+def _detected_source_lang(value: str | None) -> str:
+    """Normalize an ASR language without truncating valid three-letter codes."""
+    code = (value or "en").split("_", 1)[0].strip().lower()
+    if code in _DUB_SOURCE_LANG_CODES:
+        return code
+    short = code[:2]
+    return short if short in _DUB_SOURCE_LANG_CODES else "en"
+
 
 @router.post("/dub/upload")
 async def dub_upload(
     video: UploadFile = File(...),
     job_id: Optional[str] = Form(None),
     input_type: str = Form("video"),
+    source_lang: Optional[str] = Form(None),
 ):
     """Accept a media upload, write to disk, queue background prep task.
 
@@ -445,6 +611,7 @@ async def dub_upload(
             detail=f"Audio-only dubbing needs an audio file ({', '.join(sorted(_AUDIO_EXTS))}); got '{ext or 'no extension'}'.",
         )
 
+    source_lang_override = _source_lang_override(source_lang)
     os.makedirs(job_dir, exist_ok=True)
 
     video_path = os.path.join(job_dir, f"original{ext}")
@@ -456,7 +623,13 @@ async def dub_upload(
     await task_manager.add_task(
         task_id, "prep",
         _ingest_gen, job_id, job_dir,
-        {"kind": "file", "path": video_path, "input_type": input_type}, filename,
+        {
+            "kind": "file",
+            "path": video_path,
+            "input_type": input_type,
+            "source_lang": source_lang_override,
+        },
+        filename,
     )
     return JSONResponse(
         status_code=202,
@@ -478,6 +651,7 @@ async def dub_ingest_url(req: DubIngestUrlRequest, request: Request):
             status_code=400,
             detail="URL must start with http:// or https://. Paste a full video link (e.g. https://youtube.com/watch?v=…) or drop a local file instead.",
         )
+    source_lang_override = _source_lang_override(req.source_lang)
 
     try:
         import yt_dlp  # noqa: F401
@@ -513,6 +687,7 @@ async def dub_ingest_url(req: DubIngestUrlRequest, request: Request):
         "fetch_subs": bool(req.fetch_subs),
         "sub_langs": req.sub_langs or None,
         "cookie_file": cookie_path,
+        "source_lang": source_lang_override,
     }
     try:
         await task_manager.add_task(
@@ -577,6 +752,118 @@ def _clamp_num_speakers(value) -> Optional[int]:
     return value if 1 <= value <= 20 else None
 
 
+def _recover_from_phrase_embeddings(
+    diar_pipe,
+    diarized_segments: list[dict],
+    *,
+    phrases: list[dict],
+    requested_speakers: int | None,
+    audio_target: str,
+    segments: list[dict],
+    words: list,
+):
+    """Recover rapid turns when pyannote collapses a two-speaker exchange.
+
+    Uses ASR phrase boundaries and the embedding/audio components already
+    loaded by speaker-diarization-3.1. Weak or imbalanced clusters are rejected
+    so ordinary single-speaker recordings remain untouched. Returns
+    ``(segments, separation)`` or ``None``.
+    """
+    present = {
+        str(seg.get("speaker_id")) for seg in diarized_segments
+        if seg.get("speaker_id")
+    }
+    if len(present) > 1:
+        return None
+    usable_phrases = [
+        phrase for phrase in phrases
+        if phrase.get("text")
+        and float(phrase.get("end", 0.0)) - float(phrase.get("start", 0.0)) >= 0.75
+    ]
+    if len(usable_phrases) < 4:
+        return None
+    requested = int(requested_speakers) if requested_speakers else 2
+    if requested != 2:
+        return None
+    embedding = getattr(diar_pipe, "_embedding", None)
+    audio = getattr(diar_pipe, "_audio", None)
+    if embedding is None or audio is None:
+        return None
+    try:
+        import numpy as np
+        from pyannote.core import Segment as _PyannoteSegment
+        from sklearn.cluster import AgglomerativeClustering
+
+        vectors = []
+        durations = []
+        for phrase in usable_phrases:
+            start, end = float(phrase["start"]), float(phrase["end"])
+            duration = end - start
+            waveform, _ = audio.crop(
+                audio_target, _PyannoteSegment(start, end),
+                duration=duration, mode="pad",
+            )
+            vector = np.asarray(embedding(waveform[None])).reshape(-1)
+            if not np.isfinite(vector).all():
+                return None
+            vectors.append(vector)
+            durations.append(duration)
+        matrix = np.vstack(vectors)
+        labels = np.asarray(AgglomerativeClustering(
+            n_clusters=2, metric="cosine", linkage="average",
+        ).fit_predict(matrix))
+        if len(set(labels.tolist())) != 2:
+            return None
+
+        counts = [int(np.sum(labels == cluster)) for cluster in (0, 1)]
+        cluster_durations = [
+            float(sum(duration for duration, label in zip(durations, labels) if label == cluster))
+            for cluster in (0, 1)
+        ]
+        if min(counts) < 2 or min(cluster_durations) < 1.5:
+            return None
+
+        normalized = matrix / np.maximum(np.linalg.norm(matrix, axis=1, keepdims=True), 1e-8)
+        similarities = normalized @ normalized.T
+        within, cross = [], []
+        for left in range(len(labels)):
+            for right in range(left + 1, len(labels)):
+                target = within if labels[left] == labels[right] else cross
+                target.append(float(similarities[left, right]))
+        if not within or not cross:
+            return None
+        separation = float(np.mean(within) - np.mean(cross))
+        min_separation = 0.12 if requested_speakers == 2 else 0.18
+        if separation < min_separation:
+            logger.info(
+                "phrase-embedding speaker recovery rejected (separation=%.3f < %.3f)",
+                separation, min_separation,
+            )
+            return None
+
+        speaker_map = {}
+        turns = []
+        for phrase, label in zip(usable_phrases, labels.tolist()):
+            if label not in speaker_map:
+                speaker_map[label] = f"Speaker {len(speaker_map) + 1}"
+            turns.append({
+                "start": float(phrase["start"]),
+                "end": float(phrase["end"]),
+                "speaker": speaker_map[label],
+            })
+        # Assignment mutates segment dictionaries. Work on copies so a recovery
+        # rejected by the final two-speaker check cannot leak partial labels
+        # into the ordinary pyannote result.
+        assigned = assign_speakers_from_turns([dict(item) for item in segments], turns)
+        recovered = resplit_segments_by_turns(assigned, words, turns)
+        if len({item.get("speaker_id") for item in recovered if item.get("speaker_id")}) < 2:
+            return None
+        return recovered, separation
+    except Exception:
+        logger.exception("phrase-embedding speaker recovery failed")
+        return None
+
+
 @router.get("/dub/transcribe-stream/{job_id}")
 async def dub_transcribe_stream(
     job_id: str,
@@ -912,6 +1199,12 @@ async def dub_transcribe_stream(
         # Words (global-timeline) retained so diarization can re-split a segment
         # that spans two speakers' turns at the word boundary (#486).
         all_words: list = []
+        # Preserve the ASR backend's natural phrase boundaries before
+        # segment_transcript merges short neighboring phrases. Pyannote 3.1
+        # occasionally collapses rapid exchanges into one dominant speaker; in
+        # that narrow case these phrase spans give its own WeSpeaker embedding
+        # model clean candidate utterances for a conservative recovery pass.
+        asr_phrase_segments: list[dict] = []
         detected_lang = None
         next_seg_id = 0
         chunk_errors: list[str] = []
@@ -981,21 +1274,13 @@ async def dub_transcribe_stream(
                         "error_code": failure["code"],
                     }
 
-            # Retry a failed/timed-out chunk once on a fresh pool before giving
-            # up. Otherwise a transient wedge on the FIRST chunk (whisperx often
-            # cold-loads its model there, the #730 hang) drops that whole window
-            # and the transcript is "missing the beginning, only middle+end".
-            # The retry reuses the same audio window, so a recovered chunk fills
-            # the hole instead of leaving silent gaps.
+            # Retry an ordinary completed failure once. A timed-out native call
+            # is different: its thread is still executing and must not overlap
+            # a retry against the same backend (#1669).
             part = None
+            timed_out = False
             for _attempt in range(1, _CHUNK_TRANSCRIBE_ATTEMPTS + 1):
-                # A wedged chunk gets the SAME guarded-timeout + pool-reset
-                # semantics as the whole-file paths (#730/#851):
-                # run_transcribe_guarded bounds the call, abandons the poisoned
-                # pool so the retry (and any concurrent TTS work) gets a fresh
-                # worker, and raises the actionable ASRTimeoutError. Run it as
-                # a task and poll so we can keep yielding pings — the
-                # EventSource connection drops without them.
+                # Run as a task and poll so pings keep the EventSource alive.
                 task = asyncio.ensure_future(run_transcribe_guarded(
                     _gpu_pool, _transcribe_chunk,
                     what=f"Dub chunk {i + 1}/{chunks_n}",
@@ -1010,9 +1295,12 @@ async def dub_transcribe_stream(
                 try:
                     part = task.result()
                 except ASRTimeoutError:
-                    # The guard already reset the pool; keep the actionable
-                    # message (it names the durable fixes, and — after repeated
-                    # timeouts — the crash-isolated engine escape hatch).
+                    # Python cannot kill an in-process native transcribe. Do
+                    # not swap pools and retry over the still-running call:
+                    # concurrent whisperx/CTranslate2 access caused the native
+                    # Windows access violation in #1669. Stop this transcript;
+                    # the worker remains honestly occupied until it exits.
+                    timed_out = True
                     logger.error(
                         "Transcribe chunk %d/%d timed out after %.0fs (attempt %d/%d, job=%s)",
                         i + 1, chunks_n, transcribe_timeout_s, _attempt,
@@ -1031,23 +1319,36 @@ async def dub_transcribe_stream(
                 # error-part; the timeout path already reset the pool).
                 if part is not None and not part.get("error"):
                     break
-                if _attempt < _CHUNK_TRANSCRIBE_ATTEMPTS:
+                if timed_out:
+                    break
+                if not timed_out and _attempt < _CHUNK_TRANSCRIBE_ATTEMPTS:
                     logger.warning(
                         "Retrying transcribe chunk %d/%d after failure/timeout (next attempt %d/%d, job=%s)",
                         i + 1, chunks_n, _attempt + 1, _CHUNK_TRANSCRIBE_ATTEMPTS, log_safe(job_id),
                     )
-                    # A completed exception did not wedge the worker. Resetting
-                    # the pool here leaked a healthy executor on every ordinary
-                    # decode failure; run_transcribe_guarded already resets the
-                    # pool on the only case that needs it: a real timeout.
+                    # A completed exception did not leave native work behind,
+                    # so retrying this same audio window is safe.
             if part.get("error"):
                 chunk_errors.append(part["error"])
                 if part.get("error_code"):
                     chunk_error_codes.append(part["error_code"])
                 logger.warning("Chunk %d/%d error: %s", i + 1, chunks_n, log_safe(part["error"]))
+            if timed_out:
+                break
             if detected_lang is None and part.get("language"):
                 detected_lang = part["language"]
             asr_speaker_turns.extend(part.get("speaker_turns") or [])
+            for _phrase in part.get("chunks", []) or []:
+                _pts = _phrase.get("timestamp") or (None, None)
+                _ptext = (_phrase.get("text") or "").strip()
+                try:
+                    _ps, _pe = float(_pts[0]), float(_pts[1])
+                except (TypeError, ValueError, IndexError):
+                    continue
+                if _ptext and _pe > _ps:
+                    asr_phrase_segments.append({
+                        "start": _ps, "end": _pe, "text": _ptext,
+                    })
             chunk_segs = segment_transcript(part, duration=t1, scene_cuts=scene_cuts)
             # Same word source segment_transcript used (already global-timeline),
             # kept for the post-diarization speaker re-split (#486).
@@ -1313,7 +1614,25 @@ async def dub_transcribe_stream(
                 assigned = assign_speakers_from_diarization(all_segments, diar)
                 # #486: split any segment that spans two speakers' turns at the
                 # word boundary (single-speaker segments pass through unchanged).
-                return resplit_segments_by_diarization(assigned, all_words, diar), None, "pyannote"
+                resplit = resplit_segments_by_diarization(assigned, all_words, diar)
+                recovered = _recover_from_phrase_embeddings(
+                    diar_pipe,
+                    resplit,
+                    phrases=asr_phrase_segments,
+                    requested_speakers=num_speakers,
+                    audio_target=asr_audio_target,
+                    segments=all_segments,
+                    words=all_words,
+                )
+                if recovered is not None:
+                    recovered_segments, separation = recovered
+                    logger.info(
+                        "Recovered rapid two-speaker exchange from ASR phrase embeddings "
+                        "(phrases=%d, separation=%.3f).",
+                        len(asr_phrase_segments), separation,
+                    )
+                    return recovered_segments, None, "phrase_embeddings"
+                return resplit, None, "pyannote"
             except Exception as e:
                 logger.exception("Diarization failed")
                 # Inline ASR turns beat the silence-gap heuristic as a crash
@@ -1522,7 +1841,9 @@ async def dub_transcribe_stream(
         except Exception as e:
             logger.warning("speaker_clone extraction skipped: %s", e)
 
-        job["source_lang"] = ((detected_lang or "en").split("_")[0][:2] or "en").lower()
+        job["source_lang"] = job.get("source_lang_override") or _detected_source_lang(
+            detected_lang
+        )
         job["full_transcript"] = " ".join(s.get("text", "") for s in final_segs)
         _save_job(job_id, job)
 
@@ -1719,7 +2040,9 @@ async def dub_transcribe(job_id: str, num_speakers: Optional[int] = None):
             except Exception as e:
                 logger.warning("Failed to unload ASR backend: %s", e)
 
-        job["source_lang"] = (detected_lang or "en").split("_")[0][:2].lower()
+        job["source_lang"] = job.get("source_lang_override") or _detected_source_lang(
+            detected_lang
+        )
 
         scene_cuts = job.get("scene_cuts") or []
         segments = segment_transcript(result, duration=job.get("duration", 0.0), scene_cuts=scene_cuts)
@@ -1775,7 +2098,8 @@ async def dub_transcribe(job_id: str, num_speakers: Optional[int] = None):
             # Bound the whole-file transcribe (#730): a wedged whisperx/CTranslate2
             # call would otherwise hold its GPU-pool worker forever and starve
             # every other request into a "can't reach backend". run_transcribe_guarded
-            # also resets the pool on timeout so capacity is restored.
+            # leaves an unkillable native worker accounted for on timeout so a
+            # retry cannot overlap it (#1669).
             segments_result = await run_transcribe_guarded(_gpu_pool, _transcribe, what="Dub")
         except asyncio.CancelledError:
             job["aborted"] = True

backend/api/routers/dub_export.py

@@ -23,6 +23,7 @@ from services.ffmpeg_utils import (
     find_ffmpeg,
     run_ffmpeg,
 )
+from services.karaoke_ass import build_ass, scale_words
 from services.video_retime import (
     DRIFT_TOLERANCE_S,
     RetimeError,
@@ -403,6 +404,27 @@ def _write_burn_srt(job: dict, exports_dir: str, stamp: str, dual: bool,
     return sub_path
 
 
+def _write_burn_ass(job: dict, exports_dir: str, stamp: str,
+                    fitted_segments: "list[dict] | None" = None,
+                    lang: "str | None" = None) -> str | None:
+    """Karaoke variant of ``_write_burn_srt``: word-timed ASS via ``build_ass``.
+
+    Same text/timing resolution (``_segments_for_lang`` + fitted-cue overlay,
+    which also scales per-word times onto the fitted timeline); the basename
+    is plain ASCII under exports_dir so it is ffmpeg-filter-safe. Returns
+    None if there are no segments to render.
+    """
+    segments = _segments_for_lang(job, lang)
+    if not segments:
+        return None
+    if fitted_segments:
+        segments = _apply_fitted_times(segments, fitted_segments)
+    sub_path = os.path.join(exports_dir, f"burn_subs_{stamp}.ass")
+    with open(sub_path, "w", encoding="utf-8") as f:
+        f.write(build_ass(segments))
+    return sub_path
+
+
 def _ffmpeg_filter_escape(path: str) -> str:
     """Escape a path for use inside an ffmpeg filter value (subtitles=...).
 
@@ -515,6 +537,20 @@ def _apply_fitted_times(segments: list[dict], fitted: list[dict]) -> list[dict]:
         patched = dict(seg)
         patched["start"] = float(cue["start"])
         patched["end"] = float(cue["end"])
+        # Karaoke burn-in: persisted word times live on the original timeline;
+        # scale them linearly onto the fitted cue span so the highlight sweep
+        # follows the retimed audio. Degenerate spans drop the words — export
+        # then falls back to an even split over the fitted span. Inert for
+        # SRT/VTT, which never read ``words``.
+        if isinstance(seg.get("words"), list) and seg.get("words"):
+            scaled = scale_words(
+                seg["words"], seg.get("start", 0.0), seg.get("end", 0.0),
+                patched["start"], patched["end"],
+            )
+            if scaled is not None:
+                patched["words"] = scaled
+            else:
+                patched.pop("words", None)
         out.append(patched)
     return out
 
@@ -572,11 +608,12 @@ def _build_audio_export_cmd(
 async def dub_download(
     job_id: str,
     preserve_bg: bool = Query(True, description="Mix background noise into dubbed tracks"),
-    default_track: str = Query("original"),
+    default_track: str = Query("", description="Default audio track; omitted selects the first dubbed track"),
     include_tracks: str = Query("", description="Comma-separated list of tracks to include (e.g. 'original,de,es'). Empty = include all."),
     save_authorization: str = Header("", alias="X-VoiceStudio-Path-Authorization"),
     burn_subs: bool = Query(False, description="Burn subtitles into the video stream (forces re-encode). Uses dual-subtitle layout when dual=1."),
     dual: bool = Query(False, description="When burn_subs=1, render translated on top of italicised original."),
+    karaoke: bool = Query(False, description="When burn_subs=1, burn a word-timed karaoke highlight (ASS) instead of line subtitles. Ignored when dual=1 (dual karaoke is unsupported — the line burn renders instead)."),
     out_format: str = Query("m4a", description="Audio-only jobs (#119): output container — wav, m4a, mp3, or flac. Ignored for video jobs."),
 ):
     # Strict allowlist on the path param BEFORE it reaches any filesystem
@@ -607,6 +644,18 @@ async def dub_download(
         for key, value in filtered_tracks.items()
     }
 
+    # A dub export should play the dub without requiring player-specific track
+    # selection. Keep ``original`` as an explicit opt-in, but when callers omit
+    # the preference choose the first generated dub consistently (#1575).
+    if (
+        filtered_tracks
+        and not (default_track == "original" and include_original)
+        and default_track not in filtered_tracks
+    ):
+        default_track = next(iter(filtered_tracks))
+    elif not filtered_tracks and include_original:
+        default_track = "original"
+
     if not filtered_tracks and not include_original:
         raise HTTPException(status_code=400, detail="No tracks selected for export")
 
@@ -631,12 +680,17 @@ async def dub_download(
         fmt = (out_format or "m4a").lower()
         if fmt not in _AUDIO_FORMAT_CODECS:
             fmt = "m4a"
-        # lang_code is already constrained to an existing track key, but
-        # allowlist-sanitize it before it reaches the output path so a path
-        # component can never carry separators/traversal (same pattern as
-        # safe_name below).
-        safe_lang = "".join(c for c in lang_code if c.isalnum() or c in "-_") or "track"
-        out_path = os.path.join(exports_dir, f"dubbed_audio_{safe_lang}_{stamp}.{fmt}")
+        # Keep route/job data out of the filesystem and logging trust boundary.
+        # The selected format reaches the path only through literal branches.
+        if fmt == "wav":
+            output_name = f"dubbed_audio_{stamp}.wav"
+        elif fmt == "mp3":
+            output_name = f"dubbed_audio_{stamp}.mp3"
+        elif fmt == "flac":
+            output_name = f"dubbed_audio_{stamp}.flac"
+        else:
+            output_name = f"dubbed_audio_{stamp}.m4a"
+        out_path = os.path.join(exports_dir, output_name)
         bg = _optional_dub_artifact(job.get("no_vocals_path"), job_id) if preserve_bg else None
         cmd = _build_audio_export_cmd(ffmpeg, track_info["path"], bg, out_path, fmt)
         try:
@@ -654,15 +708,28 @@ async def dub_download(
             )
         if not os.path.exists(out_path) or os.path.getsize(out_path) == 0:
             raise HTTPException(status_code=500, detail="ffmpeg audio export produced no output file")
-        logger.info("Dub audio export wrote %s (%d bytes)", out_path, os.path.getsize(out_path))
+        logger.info("Dub audio export completed (%d bytes)", os.path.getsize(out_path))
 
-        base_name = os.path.splitext(job.get("filename", "output"))[0]
-        safe_name = "".join(c for c in base_name if c.isalnum() or c in "-_ ").strip() or "output"
-        dl_name = f"dubbed_{safe_name}_{safe_lang}_{stamp}.{fmt}"
+        # Response metadata must not become a second path-like sink for job or
+        # request data. Keep the user-selected format through explicit literal
+        # branches; source names and language keys never enter the label.
+        if fmt == "wav":
+            dl_name = f"dubbed_audio_{stamp}.wav"
+        elif fmt == "mp3":
+            dl_name = f"dubbed_audio_{stamp}.mp3"
+        elif fmt == "flac":
+            dl_name = f"dubbed_audio_{stamp}.flac"
+        else:
+            dl_name = f"dubbed_audio_{stamp}.m4a"
         media_type = _MEDIA_TYPES.get(f".{fmt}", "audio/mp4")
         save_path = _consume_native_save(save_authorization)
         if save_path:
-            return _native_save(out_path, save_path, dl_name, media_type=media_type)
+            # Keep the request-derived download label out of the filesystem
+            # trust boundary. It is response metadata, not a source or
+            # destination path (CodeQL, #1575).
+            result = _native_save(out_path, save_path, "dubbed_audio", media_type=media_type)
+            result["display_name"] = dl_name
+            return result
         return FileResponse(
             out_path, media_type=media_type,
             headers={"Content-Disposition": content_disposition(dl_name)},
@@ -699,7 +766,18 @@ async def dub_download(
     fitted_segments = _fitted_segments_for(job, default_track) if default_track and default_track != "original" else None
     # Burn the DEFAULT track's text (P1.2) — it's the audio the viewer hears.
     _burn_lang = default_track if default_track and default_track != "original" else None
-    sub_path = _write_burn_srt(job, exports_dir, stamp, dual, fitted_segments=fitted_segments, lang=_burn_lang) if burn_subs else None
+    # Karaoke (word-highlight) burn writes an ASS instead of the line SRT.
+    # Dual layout keeps the line burn — dual karaoke is out of scope, matching
+    # the disabled control in the Export drawer. The default (karaoke off)
+    # takes exactly the legacy SRT path.
+    sub_path = None
+    sub_is_ass = False
+    if burn_subs:
+        if karaoke and not dual:
+            sub_path = _write_burn_ass(job, exports_dir, stamp, fitted_segments=fitted_segments, lang=_burn_lang)
+            sub_is_ass = sub_path is not None
+        if sub_path is None:
+            sub_path = _write_burn_srt(job, exports_dir, stamp, dual, fitted_segments=fitted_segments, lang=_burn_lang)
 
     # ── Smart Fit video retime (two-tier) ─────────────────────────────────
     # Tier 1 (≤48 chunks): single filter_complex graph inlined into the mux
@@ -799,14 +877,16 @@ async def dub_download(
         esc = _ffmpeg_filter_escape(sub_path)
         # Burn AFTER any retime so cues (already on the fitted timeline for
         # Smart Fit) land on the retimed video. Without retime this reduces
-        # to the legacy `[0:v]subtitles=…[vsub]` graph.
+        # to the legacy `[0:v]subtitles=…[vsub]` graph. Karaoke burns the
+        # word-timed ASS through the ass filter at the same graph position.
         if video_map.startswith("["):
             sub_src = video_map
         elif retimed_idx is not None:
             sub_src = f"[{retimed_idx}:v]"
         else:
             sub_src = "[0:v]"
-        filter_parts.append(f"{sub_src}subtitles='{esc}'[vsub]")
+        _sub_filter = "ass" if sub_is_ass else "subtitles"
+        filter_parts.append(f"{sub_src}{_sub_filter}='{esc}'[vsub]")
         video_map = "[vsub]"
     if stretch_entry:
         orig_dur = float(stretch_entry.get("orig_duration") or job.get("duration") or 0.0)
@@ -887,7 +967,10 @@ async def dub_download(
     if default_track == "original" and include_original:
         cmd += ["-disposition:a:0", "default"]
     else:
-        target_idx = 0
+        # A stale/missing language preference still means "play a dub", not
+        # "silently fall back to the source". The first processed dub is the
+        # deterministic fallback; ``original`` above remains explicit.
+        target_idx = tracks_to_process[0]["stream_idx"] if tracks_to_process else 0
         for t in tracks_to_process:
             if t['lang_code'] == default_track:
                 target_idx = t["stream_idx"]
@@ -1566,7 +1649,10 @@ async def dub_download_audio(
         return _native_save(wav_path, save_path, dl_name, media_type="audio/wav")
     return FileResponse(
         wav_path, media_type="audio/wav",
-        headers={"Content-Disposition": content_disposition(dl_name)},
+        headers={
+            "Cache-Control": "no-store",
+            "Content-Disposition": content_disposition(dl_name),
+        },
     )
 
 
@@ -1708,6 +1794,50 @@ async def dub_export_vtt(
     )
 
 
+@router.get("/dub/ass/{job_id}")
+@router.get("/dub/ass/{job_id}/{filename}")
+async def dub_export_ass(
+    job_id: str,
+    lang: str = Query(None, description="Track language code. Same text/timing resolution as /dub/srt, rendered as a karaoke (word-highlight) ASS sidecar."),
+):
+    """Karaoke ASS sidecar — the same script the karaoke burn-in renders.
+
+    Raw text body like /dub/srt and /dub/vtt (the Tauri side writes the file
+    itself; no ?save_path= variant — see the comment above /dub/srt).
+    """
+    _job_dir_or_400(job_id)
+    lang = _safe_lang_or_400(lang)
+    job = _get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    segments = _segments_for_lang(job, lang)
+    if not segments:
+        raise HTTPException(status_code=400, detail="No transcript segments available")
+
+    # Same strategy-aware cue timing as /dub/srt. The fitted overlay also
+    # scales word times; the stretch_video cue path has no per-word record,
+    # so words are dropped and build_ass even-splits over the new spans.
+    fitted = _fitted_segments_for(job, lang)
+    if fitted:
+        segments = _apply_fitted_times(segments, fitted)
+    else:
+        cues = _fitted_cue_times(job, lang)
+        if cues:
+            segments = [
+                {**{k: v for k, v in seg.items() if k != "words"}, "start": s, "end": e}
+                for seg, (s, e) in zip(segments, cues)
+            ]
+
+    base_name = os.path.splitext(job.get('filename', 'video'))[0]
+    dl_name = f"subtitles_{base_name}_karaoke.ass"
+    return Response(
+        content=build_ass(segments),
+        media_type="text/plain",
+        headers={"Content-Disposition": content_disposition(dl_name)},
+    )
+
+
 @router.get("/dub/export-segments/{job_id}")
 async def dub_export_segments_zip(job_id: str, lang: str = Query(None)):
     import zipfile

backend/api/routers/dub_generate.py

@@ -1,6 +1,7 @@
 import os
 import re
 import json
+import struct
 import logging
 import time
 import asyncio
@@ -80,6 +81,62 @@ def _prepare_oom_retry(error: Exception, *, execution_target: str) -> bool:
     return True
 
 
+def _cached_payload_intact(path: str, info) -> bool:
+    """Cheap truth check on a cached WAV whose header we are about to trust.
+
+    The natural-rate fast path hands the mixer a PATH instead of decoded
+    audio, so a cache whose header reads fine but whose payload is truncated
+    would only fail later, during assembly — after the timing plan (Smart Fit,
+    video stretch) had been computed from the header's frame count. The plan
+    would then describe audio that no longer exists and the segment would be
+    replaced by slot-length silence, leaving the persisted video plan and the
+    rendered track disagreeing.
+
+    Comparing the declared frame count against the physical ``data`` chunk
+    catches that without decoding: a truncated file cannot hold the samples
+    its header claims. Anything failing here falls through to the decoding path, which
+    already degrades to a warning plus silence. Formats with no fixed
+    bits-per-sample (compressed caches) are left to the decoder as before.
+    """
+    try:
+        bits = int(getattr(info, "bits_per_sample", 0) or 0)
+        frames = int(getattr(info, "num_frames", 0) or 0)
+        channels = int(getattr(info, "num_channels", 0) or 0)
+        if bits <= 0 or frames <= 0 or channels <= 0:
+            # Undecidable metadata fails CLOSED (review on #1620): these caches
+            # are PCM WAVs this module wrote itself, so anything else is
+            # unexpected — and the decode path this falls through to handles
+            # every format the fast path would have.
+            return False
+        payload = frames * channels * (bits // 8)
+        if payload <= 0:
+            return False
+
+        # A WAV may carry JUNK/LIST metadata before data, so its header is not
+        # necessarily 44 bytes. Locate the data chunk instead of counting
+        # metadata as audio; otherwise an extended header can mask truncation.
+        file_size = os.path.getsize(path)
+        with open(path, "rb") as wav:
+            header = wav.read(12)
+            if len(header) != 12 or header[:4] != b"RIFF" or header[8:12] != b"WAVE":
+                return False
+            offset = 12
+            while offset + 8 <= file_size:
+                wav.seek(offset)
+                chunk_id = wav.read(4)
+                chunk_size_raw = wav.read(4)
+                if len(chunk_id) != 4 or len(chunk_size_raw) != 4:
+                    return False
+                chunk_size = struct.unpack("<I", chunk_size_raw)[0]
+                data_offset = offset + 8
+                if chunk_id == b"data":
+                    return chunk_size >= payload and file_size >= data_offset + payload
+                offset = data_offset + chunk_size + (chunk_size % 2)
+        return False
+    except Exception:  # noqa: BLE001 — an unstattable cache is the decoder's problem
+        return False
+
+
 def _underrun_min_rate() -> float:
     """Floor for the underrun fill (audio slowed toward its slot, never below
     this rate). Default 0.85 stays natural-sounding; OMNIVOICE_UNDERRUN_MIN_RATE=1.0
@@ -446,6 +503,18 @@ async def dub_generate(job_id: str, req: DubRequest):
         backend = await resolve_generation_backend(require_cloning=True)
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        from core.failure import is_gpu_oom
+
+        if not is_gpu_oom(e):
+            raise
+        from core.public_errors import public_exception_response
+
+        payload = public_exception_response(
+            e,
+            fallback="The TTS model could not be loaded.",
+        )
+        raise HTTPException(status_code=503, detail=payload["detail"]) from e
 
     async def _stream(task_id):
         total = len(req.segments)
@@ -593,11 +662,11 @@ async def dub_generate(job_id: str, req: DubRequest):
         voice_match = (req.voice_match or "per_line").lower()
         _consistent_ref_memo: dict = {}
         remote_audio: dict[int, str] = {}
-        # Strategy-transition guard: smart_fit re-mixes the *natural-rate*
-        # per-segment WAVs from disk. If the previous run used strict_slot,
-        # the on-disk WAVs are slot-squeezed ("slotted") — reusing them would
-        # double-compress. Force one full regen; afterwards seg_wav_kind is
-        # "natural" and partial regen / fit-only re-mix (regen_only=[]) work.
+        # Strategy-transition guard: concise, stretch_video and smart_fit all
+        # re-mix *natural-rate* per-segment WAVs. If the previous run used
+        # strict_slot, the on-disk WAVs are slot-squeezed ("slotted") — the
+        # missing tails cannot be recovered by a re-mix. Force one full regen;
+        # afterwards partial regen / fit-only re-mix (regen_only=[]) is safe.
         # Jobs predating this field have unknown kind → also regen once.
         # P1.3: the kind is per-track now (each language renders under its own
         # strategy); the flat job["seg_wav_kind"] is only consulted for jobs
@@ -608,7 +677,7 @@ async def dub_generate(job_id: str, req: DubRequest):
         _wav_kind = (
             _kind_map.get(lang_code) if isinstance(_kind_map, dict) else job.get("seg_wav_kind")
         )
-        if strategy == "smart_fit" and regen_only is not None and _wav_kind != "natural":
+        if strategy != "strict_slot" and regen_only is not None and _wav_kind != "natural":
             regen_only = None
         # Manifest: stable segment id per current index. Per-segment WAVs are
         # named by stable id (dub_seg_path) so regen reuses the right audio after
@@ -759,15 +828,38 @@ async def dub_generate(job_id: str, req: DubRequest):
                 if os.path.exists(seg_wav_path):
                     try:
                         _t_cache_0 = time.perf_counter()
+                        # Natural-rate caches are already the exact assembly
+                        # input.  Keep the durable path in the manifest so the
+                        # mixer decodes it once; the old path decoded here,
+                        # wrote an identical mix_<id> scratch WAV, then decoded
+                        # that copy again.  Header-only inspection preserves
+                        # the resample fallback for caches made by an engine
+                        # with a different sample rate.
+                        if strategy != "strict_slot":
+                            try:
+                                cached_info = torchaudio.info(seg_wav_path)
+                            except Exception:
+                                cached_info = None
+                            if (
+                                cached_info is not None
+                                and int(cached_info.sample_rate) == int(backend.sample_rate)
+                                and _cached_payload_intact(seg_wav_path, cached_info)
+                            ):
+                                all_segment_wavs.append(
+                                    (seg.start, seg.end, seg_wav_path, backend.sample_rate)
+                                )
+                                sync_scores.append(getattr(seg, 'sync_ratio', None) or 1.0)
+                                _t_cache += time.perf_counter() - _t_cache_0
+                                continue
+
                         cached_wav, cached_sr = torchaudio.load(seg_wav_path)
                         if cached_sr != backend.sample_rate:
                             import torchaudio.functional as AF
                             cached_wav = AF.resample(cached_wav, cached_sr, backend.sample_rate)
-                        # Pad/trim to slot — except smart_fit, whose mix
-                        # loop needs the natural-rate length to compute the
-                        # audio/video split (the seg_wav_kind guard above
-                        # guarantees these cached WAVs are natural-rate).
-                        if strategy != "smart_fit":
+                        # strict_slot persists slot-sized buffers.  Every other
+                        # strategy consumes natural-rate audio and lets the mix
+                        # loop fit it to the current timeline.
+                        if strategy == "strict_slot":
                             target_samples = int(seg_duration * backend.sample_rate)
                             current_samples = cached_wav.shape[-1]
                             if target_samples > current_samples:
@@ -1091,7 +1183,7 @@ async def dub_generate(job_id: str, req: DubRequest):
                             _num_step, req.guidance_scale, seg_speed, seg_profile, seg_effect_preset,
                         ),
                         what="Dub generate",
-                        timeout=generate_timeout_s(seg.text),
+                        timeout=generate_timeout_s(seg.text, engine=backend),
                     )
                 _t_tts += time.perf_counter() - _t_tts_0
 
@@ -1164,12 +1256,15 @@ async def dub_generate(job_id: str, req: DubRequest):
                         if rvc_sr == backend.sample_rate:
                             audio_tensor = rvc_wav
 
-                            target_samples = int(seg_duration * backend.sample_rate)
-                            current_samples = audio_tensor.shape[-1]
-                            if target_samples > current_samples:
-                                audio_tensor = torch.nn.functional.pad(audio_tensor, (0, target_samples - current_samples))
-                            elif current_samples > target_samples:
-                                audio_tensor = audio_tensor[..., :target_samples]
+                            if strategy == "strict_slot":
+                                target_samples = int(seg_duration * backend.sample_rate)
+                                current_samples = audio_tensor.shape[-1]
+                                if target_samples > current_samples:
+                                    audio_tensor = torch.nn.functional.pad(
+                                        audio_tensor, (0, target_samples - current_samples)
+                                    )
+                                elif current_samples > target_samples:
+                                    audio_tensor = audio_tensor[..., :target_samples]
                     except Exception as e:
                         yield f"data: {json.dumps({'type': 'warning', 'segment': i, 'message': f'RVC skipped: {str(e)[:120]}'})}\n\n"
 
@@ -1208,7 +1303,15 @@ async def dub_generate(job_id: str, req: DubRequest):
                         pass
                     _release_audio_tensors()
             except Exception as e:
-                yield f"data: {json.dumps({'type': 'error', 'segment': i, 'error': str(e)})}\n\n"
+                # A task-stream error bypasses the global exception handler.
+                # Never publish engine exception text here: allocator errors
+                # carry process tables and arbitrary failures can carry paths,
+                # tokens, or source text. The shared helper enriches recognized
+                # classes using VoiceStudio-owned constants only.
+                from core.public_errors import stream_generation_failure
+
+                error_detail = stream_generation_failure(e)["detail"]
+                yield f"data: {json.dumps({'type': 'error', 'segment': i, 'error': error_detail})}\n\n"
                 sr = backend.sample_rate
                 all_segment_wavs.append(_store_mix_wav(seg.start, seg.end, torch.zeros(1, max(0, int(seg_duration * sr))), sr, f"mix_{seg_id}"))
                 sync_scores.append(1.0)
@@ -1356,7 +1459,21 @@ async def dub_generate(job_id: str, req: DubRequest):
                 seg_gain = getattr(seg_ref, "gain", None) if seg_ref is not None else None
                 seg_gain = seg_gain if seg_gain is not None else 1.0
                 seg_gain = max(0.0, min(2.0, seg_gain))
-                wav = _load_entry_wav((start, end, wav_path, sr), sr)
+                try:
+                    wav = _load_entry_wav((start, end, wav_path, sr), sr)
+                except Exception as e:
+                    # A WAV header can be readable while its payload is
+                    # truncated.  Direct cache reuse deliberately defers the
+                    # decode to assembly, so preserve the old recovery contract
+                    # here: warn and fill this slot with silence instead of
+                    # aborting the entire dub.
+                    warning = {
+                        "type": "warning",
+                        "segment": i,
+                        "message": f"cached seg lost, padding silence: {str(e)[:120]}",
+                    }
+                    yield f"data: {json.dumps(warning)}\n\n"
+                    wav = torch.zeros(1, max(0, int((end - start) * sr)))
                 adjusted = wav * seg_gain
                 if adjusted.ndim == 2 and adjusted.shape[0] > 1:
                     adjusted = adjusted.mean(dim=0, keepdim=True)
@@ -1798,7 +1915,7 @@ async def preview_segment(job_id: str, req: SegmentPreviewRequest):
     from services.model_manager import generate_timeout_s
     audio_tensor = await run_on_gpu_pool_guarded(
         _gen, what="Dub preview generate",
-        timeout=generate_timeout_s(req.text),
+        timeout=generate_timeout_s(req.text, engine=backend),
     )
 
     sr = backend.sample_rate

backend/api/routers/engines.py

@@ -42,10 +42,26 @@ _FAMILIES = {
 }
 
 
+def _catalogue_active_id(family: str, module) -> str:
+    """Return the active id represented by the public engine catalogue."""
+    active = module.active_backend_id()
+    if family != "tts" or active != "omnivoice-subprocess":
+        return active
+
+    from core.device_caps import detect_host_caps
+
+    try:
+        return "omnivoice" if detect_host_caps().family == "mps" else active
+    except Exception:
+        return active
+
+
 def _family_payload(family: str, module):
     """Public inventory plus whether an environment pin owns this family."""
     return {
-        "active": module.active_backend_id(),
+        # MPS hides the explicit compatibility row, so legacy configs report
+        # the visible canonical equivalent as active to picker consumers.
+        "active": _catalogue_active_id(family, module),
         "env_override": bool(os.environ.get(f"OMNIVOICE_{family.upper()}_BACKEND")),
         "backends": public_backends(module.list_backends()),
     }
@@ -75,6 +91,21 @@ def list_tts_backends():
     return _family_payload("tts", tts_backend)
 
 
+@router.get(
+    "/engines/{engine_id}/disk-usage",
+    dependencies=[Depends(require_admin_action)],
+)
+def engine_disk_usage(engine_id: str):
+    """Measure owned engine bytes only when a catalogue row is opened."""
+    try:
+        tts_backend.get_backend_class(engine_id)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="Unknown TTS engine")
+    from services.engine_disk_usage import disk_usage_for
+
+    return disk_usage_for(engine_id)
+
+
 @router.get("/engines/asr")
 def list_asr_backends():
     return _family_payload("asr", asr_backend)
@@ -173,6 +204,11 @@ async def uninstall_translation_engine(engine_id: str):
     pkg = entry.get("pip_package")
     if not pkg:
         return {"status": "no_op", "engine": engine_id}
+    # The builtin flag is a promise someone has to remember to make; this
+    # check does not depend on it (#2019).
+    blocked = translation_engines.uninstall_blocker(engine_id)
+    if blocked:
+        raise HTTPException(status_code=blocked[0], detail=blocked[1])
     rc, out = await translation_engines.run_pip(["uninstall", "-y", pkg])
     if rc != 0:
         raise HTTPException(status_code=500, detail=f"pip uninstall {pkg} failed ({rc}): {out[-1000:]}")
@@ -215,6 +251,11 @@ def install_sidecar_engine(engine_id: str):
     from services import sidecar_install
     try:
         return sidecar_install.start_install(engine_id)
+    except sidecar_install.HostUnsupported as exc:
+        # The engine has an installer, but not one that can work on this
+        # machine. 409, not 404: the route is right, the host is the problem,
+        # and the message (a VoiceStudio-owned sentence) says what to do.
+        raise HTTPException(status_code=409, detail=str(exc))
     except KeyError:
         raise HTTPException(
             status_code=404,
@@ -339,6 +380,9 @@ def engine_health(engine_id: str):
         )
 
     t0 = perf_counter()
+    # Stable exception class when the probe itself raised, None when it merely
+    # returned not-available. Never the exception text — see the log line below.
+    raised_class: str | None = None
     if hasattr(cls, "health_check"):
         # SubprocessBackend path — spawn sidecar (if not running) and ping.
         # ``health_check`` already swallows its own exceptions per Plan
@@ -349,6 +393,7 @@ def engine_health(engine_id: str):
             ok, msg = instance.health_check()
         except Exception as exc:
             ok, msg = False, f"{type(exc).__name__}: {exc}"
+            raised_class = type(exc).__name__
     else:
         # In-process backend — `is_available()` is the classmethod-level
         # liveness check. Cheap and side-effect-free for every shipping
@@ -357,6 +402,7 @@ def engine_health(engine_id: str):
             ok, msg = cls.is_available()
         except Exception as exc:
             ok, msg = False, f"{type(exc).__name__}: {exc}"
+            raised_class = type(exc).__name__
 
     # Engine-owned output can contain much more than shaped HF tokens: local
     # paths, arbitrary credentials, source lines, or a nested traceback.
@@ -364,7 +410,38 @@ def engine_health(engine_id: str):
 
     latency_ms = (perf_counter() - t0) * 1000.0
     if not ok:
-        logger.warning("Engine health check failed; details withheld")
+        # The response tells the user to "check the backend log for details",
+        # and docs/engines/*.md asks a user diagnosing an unavailable engine to
+        # copy that engine's log lines. The old line named neither the engine
+        # nor anything about the probe, so neither instruction could be
+        # followed (#1866).
+        #
+        # `probe=` reports what the PROBE DID, not what went wrong. It cannot
+        # classify the cause: SubprocessBackend.health_check() swallows its own
+        # exceptions per Plan 02-01's contract, so a dead sidecar and a package
+        # that was never installed both arrive here as `returned-unavailable`.
+        # Separating those needs structured failure metadata from the probes
+        # themselves, which is a wider change than this one.
+        #
+        # Still no diagnostic text and still not the caller-supplied id: the
+        # engine id comes off the resolved registry class and a raised probe
+        # contributes only its exception class, the same shape
+        # core.public_errors.public_failure() logs as `class=`.
+        # tests/test_response_safety.py pins that boundary and passes
+        # unchanged.
+        #
+        # The id is a class attribute off the registry rather than caller
+        # input, but this line is a log-injection surface either way, so it is
+        # flattened to a single token before it goes in.
+        engine_label = str(getattr(cls, "id", None) or cls.__name__)
+        engine_label = "".join(
+            c if (c.isalnum() or c in "-_.") else "-" for c in engine_label
+        )[:64]
+        logger.warning(
+            "Engine health check failed; engine=%s probe=%s, details withheld",
+            engine_label or "unknown",
+            f"raised:{raised_class}" if raised_class else "returned-unavailable",
+        )
     return {
         "id": engine_id,
         "ok": bool(ok),
@@ -574,7 +651,15 @@ def select_engine(req: SelectEngineRequest):
     if not family:
         raise HTTPException(400, f"Unknown family: {req.family}. Expected one of tts/asr/llm.")
     module, pref_key = family
-    available = {b["id"]: b for b in module.list_backends()}
+    # MPS intentionally hides the redundant explicit OmniVoice sidecar from
+    # the picker, but existing scripts and saved preferences may still submit
+    # that supported compatibility id directly.
+    rows = (
+        module.list_backends(include_hidden=True)
+        if req.family == "tts"
+        else module.list_backends()
+    )
+    available = {b["id"]: b for b in rows}
     if req.backend_id not in available:
         raise HTTPException(400, f"Unknown {req.family} backend: {req.backend_id!r}")
     entry = available[req.backend_id]

backend/api/routers/generation.py

@@ -8,6 +8,7 @@ import asyncio
 import tempfile
 import contextlib
 import logging
+import threading
 import traceback
 from typing import Optional
 from fastapi import APIRouter, File, Form, UploadFile, HTTPException
@@ -32,6 +33,83 @@ router = APIRouter()
 logger = logging.getLogger("omnivoice.generate")
 
 
+class _TempReferenceLease:
+    """Delete a request-owned reference once every abandoned reader drains."""
+
+    def __init__(self, path: str):
+        self.path = path
+        self._lock = threading.Lock()
+        self._active = 0
+        self._request_done = False
+        self._deleted = False
+
+    def acquire(self):
+        with self._lock:
+            if self._request_done:
+                raise RuntimeError("reference lease acquired after request cleanup")
+            self._active += 1
+        once_lock = threading.Lock()
+        released = False
+
+        def release() -> None:
+            nonlocal released
+            with once_lock:
+                if released:
+                    return
+                released = True
+            self._release()
+
+        return release
+
+    def _release(self) -> None:
+        delete = False
+        with self._lock:
+            self._active -= 1
+            if self._active < 0:
+                raise RuntimeError("reference lease released too many times")
+            if self._request_done and self._active == 0 and not self._deleted:
+                self._deleted = True
+                delete = True
+        if delete:
+            with contextlib.suppress(OSError):
+                os.remove(self.path)
+
+    def finish_request(self) -> None:
+        delete = False
+        with self._lock:
+            self._request_done = True
+            if self._active == 0 and not self._deleted:
+                self._deleted = True
+                delete = True
+        if delete:
+            with contextlib.suppress(OSError):
+                os.remove(self.path)
+
+
+async def _run_with_reference_lease(lease, factory):
+    """Hold an ad-hoc reference through one local GPU-pool dispatch."""
+    if lease is None:
+        return await factory(None)
+    release = lease.acquire()
+    abandoned = False
+    try:
+        return await factory(release)
+    except GpuPoolBusyError:
+        # Busy means no job started; release now. The callback may already have
+        # done so, and the lease token is deliberately idempotent.
+        release()
+        abandoned = True
+        raise
+    except (asyncio.CancelledError, GpuJobTimeoutError):
+        # The guard owns release now: immediately for a queued cancellation,
+        # or from the worker finalizer after an in-flight job drains.
+        abandoned = True
+        raise
+    finally:
+        if not abandoned:
+            release()
+
+
 def _profile_instruct(row):
     """Validator-safe instruct for a stored profile row.
 
@@ -47,6 +125,96 @@ def _profile_instruct(row):
     return heal_design_instruct(row["instruct"], vd)
 
 
+def _resolve_profile_conditioning(row, *, ref_text=None, instruct=None,
+                                  seed=None, language=None):
+    """Resolve a ``voice_profiles`` row into generation conditioning.
+
+    Extracted verbatim from /generate's inline profile-resolution block so
+    other synthesis routes (POST /convert) share the exact same semantics —
+    lock wins, ``kind`` is authoritative (0005), legacy pre-0004 rows fall
+    back to the is_locked/instruct inference, and #533's language fill.
+
+    Request-supplied values (``ref_text``/``instruct``/``seed``/``language``)
+    always win over the stored row; only gaps are filled. Returns a dict with
+    ``ref_audio_path`` / ``ref_text`` / ``instruct`` / ``seed`` / ``language``
+    / ``kind`` plus ``persist_ref_text`` — True when the caller should cache
+    an auto-transcribed reference transcript back onto the row (#1032).
+    """
+    out = {
+        "ref_audio_path": None, "ref_text": ref_text, "instruct": instruct,
+        "seed": seed, "language": language, "kind": None,
+        "persist_ref_text": False,
+    }
+    # `kind` is authoritative (0005): 'design' profiles condition on their
+    # deterministic rendered sample + instruct; 'clone' on the user's
+    # reference. Lock always wins (it pins a specific take). Rows from
+    # pre-0004 DBs mid-upgrade may lack the column → fall back to the legacy
+    # is_locked/instruct inference.
+    try:
+        profile_kind = row["kind"] or "clone"
+    except (KeyError, IndexError):
+        profile_kind = "design" if (
+            row["instruct"] and not row["is_locked"] and not row["ref_audio_path"]
+        ) else "clone"
+    out["kind"] = profile_kind
+    if row["is_locked"] and row["locked_audio_path"]:
+        out["ref_audio_path"] = os.path.join(VOICES_DIR, row["locked_audio_path"])
+        if not out["ref_text"]:
+            out["ref_text"] = row["ref_text"]
+        if not out["instruct"]:
+            out["instruct"] = _profile_instruct(row)
+        if out["seed"] is None and row["seed"] is not None:
+            out["seed"] = row["seed"]
+    elif profile_kind == "design":
+        # Rendered sample (if present) carries the voice identity; instruct
+        # alone is the fallback for legacy archetype rows.
+        out["ref_audio_path"] = (
+            os.path.join(VOICES_DIR, row["ref_audio_path"]) if row["ref_audio_path"] else None
+        )
+        if out["ref_audio_path"] and not out["ref_text"] and row["ref_text"]:
+            out["ref_text"] = row["ref_text"]
+        if not out["instruct"]:
+            out["instruct"] = _profile_instruct(row)
+        if out["seed"] is None and row["seed"] is not None:
+            out["seed"] = row["seed"]
+    elif row["instruct"] and not row["is_locked"] and not row["ref_audio_path"]:
+        # Legacy design-shaped row (pre-0004 archetype materialization failure
+        # path): instruct-only conditioning.
+        if not out["instruct"]:
+            out["instruct"] = _profile_instruct(row)
+        if out["seed"] is None and row["seed"] is not None:
+            out["seed"] = row["seed"]
+    else:
+        out["ref_audio_path"] = (
+            os.path.join(VOICES_DIR, row["ref_audio_path"]) if row["ref_audio_path"] else None
+        )
+        if not out["ref_text"] and row["ref_text"]:
+            out["ref_text"] = row["ref_text"]
+        elif out["ref_audio_path"] and not out["ref_text"]:
+            # Empty stored transcript → the caller's auto-transcribe will run;
+            # cache its result onto the profile so it runs ONCE, not on every
+            # generate (#1032 perf regression).
+            out["persist_ref_text"] = True
+        if not out["instruct"] and row["instruct"]:
+            out["instruct"] = row["instruct"]
+        if out["seed"] is None and row["seed"] is not None:
+            out["seed"] = row["seed"]
+    if out["language"] == "Auto":
+        out["language"] = None
+    # #533: a profile's stored language must drive generation when the request
+    # didn't pin one. An EXPLICIT non-Auto request language still wins; we
+    # only fill the gap. `row` is a sqlite3.Row, so guard the column lookup
+    # for pre-language DBs mid-upgrade.
+    if out["language"] is None:
+        try:
+            prof_lang = row["language"]
+        except (KeyError, IndexError):
+            prof_lang = None
+        if prof_lang and prof_lang != "Auto":
+            out["language"] = prof_lang
+    return out
+
+
 def _note_generate_progress() -> None:
     """Tell the pool guard this render just finished a unit of work (#1391).
 
@@ -381,6 +549,31 @@ def _is_timeout_failure(e) -> bool:
     return False
 
 
+def _is_media_process_launch_failure(exc: BaseException) -> bool:
+    """Identify an ffmpeg/ffprobe launch ENOENT without guessing from a file name."""
+    if not isinstance(exc, FileNotFoundError):
+        return False
+
+    # A regular missing reference/model file may itself be named "ffmpeg".
+    # Require the innermost raise site to be Python's process launcher so that
+    # basename collisions keep the normal missing-file diagnosis (#1677).
+    traceback_cursor = exc.__traceback__
+    if traceback_cursor is None:
+        return False
+    while traceback_cursor.tb_next is not None:
+        traceback_cursor = traceback_cursor.tb_next
+    origin_module = traceback_cursor.tb_frame.f_globals.get("__name__", "")
+    if origin_module != "subprocess" and not origin_module.startswith("asyncio."):
+        return False
+
+    filename = getattr(exc, "filename", None)
+    if not filename:
+        return "[winerror 2]" in str(exc).lower()
+    return os.path.basename(str(filename)).lower() in {
+        "ffmpeg", "ffmpeg.exe", "ffprobe", "ffprobe.exe",
+    }
+
+
 def _oom_friendly_reraise(e):
     """Best-effort cache flush + the user-facing OOM hint shared by both
     inference paths."""
@@ -405,6 +598,21 @@ def _oom_friendly_reraise(e):
     # that lost its +x bit) is NOT an OOM — don't send the user to the Flush
     # button; tell them what's actually wrong.
     es = str(e)
+    # #1677: Windows CreateProcess reports a missing executable as a bare
+    # ``FileNotFoundError: [WinError 2] ...`` with no filename, while POSIX
+    # includes the missing ffmpeg/ffprobe name. The bundled-media downloader
+    # now republishes PATH as soon as it finishes, but a failed/blocked
+    # download still needs an actionable recovery rather than the unknown-
+    # error dead end. Keep missing reference/model files on their own path.
+    for _exc in _exception_chain(e):
+        if _is_media_process_launch_failure(_exc):
+            raise RuntimeError(
+                "A required media program couldn't be launched. Open "
+                "Settings → Audio tools and use "
+                "Download/Repair for the media engine, then retry. If Audio "
+                "tools is already ready, repair the selected TTS engine and "
+                f"restart VoiceStudio. Underlying error: {_safe_exc_text(_exc)}"
+            ) from e
     if isinstance(e, PermissionError) or "Permission denied" in es or "Errno 13" in es:
         raise RuntimeError(
             f"A required engine binary couldn't be executed (permission denied). "
@@ -596,16 +804,34 @@ def _oom_friendly_reraise(e):
     ) from e
 
 
-def _generate_timeout_s(text: str) -> float:
+def _generate_timeout_s(
+    text: str,
+    *,
+    execution_device=None,
+    min_vram_gb=0.0,
+    hardware_family=None,
+    vram_gb=None,
+) -> float:
     """Wall-clock budget for one generate, scaled to the request.
 
     Thin alias for the canonical helper, which moved to
     ``services.model_manager.generate_timeout_s`` (#1190) so /v1/audio/speech,
     batch, dub and archetype previews share it instead of each re-deriving (or,
     as they did, silently keeping the flat 300s).
+
+    ``min_vram_gb`` is the engine's declared VRAM floor. A GPU below it pages to
+    system RAM and renders slower than this machine's CPU, so it must not be
+    budgeted as fast hardware (#1804) — the same figure the dispatch already
+    hands the guard so a timeout message can name the card (#1226/#1222).
     """
     from services.model_manager import generate_timeout_s
-    return generate_timeout_s(text)
+    return generate_timeout_s(
+        text,
+        execution_device=execution_device,
+        min_vram_gb=min_vram_gb,
+        hardware_family=hardware_family,
+        vram_gb=vram_gb,
+    )
 
 
 def _run_inference(
@@ -695,15 +921,17 @@ def _run_backend_inference(
     backend, text, language, ref_audio_path, ref_text, instruct, duration,
     num_step, guidance_scale, speed, denoise, postprocess_output,
     used_seed, effect_preset="broadcast",
-    max_chunk_chars=None, crossfade_ms=None, *, dropped_sink=None,
+    max_chunk_chars=None, crossfade_ms=None, *, t_shift=None,
+    layer_penalty_factor=None, position_temperature=None,
+    class_temperature=None, dropped_sink=None,
 ):
     """Engine-aware twin of :func:`_run_inference` (issue #312).
 
     Runs the request through a pluggable ``TTSBackend`` adapter instead of the
-    VoiceStudio model directly. The adapter protocol is narrower than the
-    VoiceStudio-native surface — engine-specific extras (``t_shift``,
-    ``layer_penalty_factor``, …) only exist on the native path, which is why
-    VoiceStudio itself still goes through ``_run_inference``.
+    VoiceStudio model directly. A crash-isolated OmniVoice proxy advertises
+    ``supports_native_omnivoice_controls`` and receives the same advanced
+    controls and per-call seed as the native path; other adapters keep the
+    narrower protocol unchanged.
     """
     import torch
     try:
@@ -718,6 +946,18 @@ def _run_backend_inference(
             instruct=instruct, num_step=num_step, guidance_scale=guidance_scale,
             speed=speed, denoise=denoise, postprocess_output=postprocess_output,
         )
+        native_proxy = bool(
+            getattr(backend, "supports_native_omnivoice_controls", False)
+        )
+        if native_proxy:
+            gen_kwargs.update({
+                key: value for key, value in {
+                    "t_shift": t_shift,
+                    "layer_penalty_factor": layer_penalty_factor,
+                    "position_temperature": position_temperature,
+                    "class_temperature": class_temperature,
+                }.items() if value is not None
+            })
         sr = backend.sample_rate
 
         # Inline [pause Nms] markers (issue #276) work for every engine — the
@@ -727,10 +967,17 @@ def _run_backend_inference(
         has_pause = len(segments) > 1 or (segments and segments[0][1] > 0)
 
         if has_pause:
+            first_span = True
+
             def _gen_span(span_text):
+                nonlocal first_span
                 # Per-span duration is left to the engine; an explicit overall
                 # `duration` can't be meaningfully split across spans.
-                return backend.generate(span_text, duration=None, **gen_kwargs)
+                span_kwargs = dict(gen_kwargs)
+                if native_proxy and first_span and used_seed is not None:
+                    span_kwargs["seed"] = used_seed
+                first_span = False
+                return backend.generate(span_text, duration=None, **span_kwargs)
             audio_out = _render_with_pauses(_gen_span, segments, sr)
         else:
             # Wave 1.2: sentence-boundary chunking for long text (see
@@ -747,12 +994,19 @@ def _run_backend_inference(
                 for i, chunk_text in enumerate(text_chunks):
                     if used_seed is not None:
                         torch.manual_seed(used_seed + i)
-                    parts.append(backend.generate(chunk_text, duration=None, **gen_kwargs))
+                    chunk_kwargs = dict(gen_kwargs)
+                    if native_proxy and used_seed is not None:
+                        chunk_kwargs["seed"] = used_seed + i
+                    parts.append(backend.generate(
+                        chunk_text, duration=None, **chunk_kwargs
+                    ))
                     _note_generate_progress()
                 audio_out = concatenate_audio_chunks(parts, sr, _xfade_ms,
                                                      texts=text_chunks,
                                                      sink=dropped_sink)
             else:
+                if native_proxy and used_seed is not None:
+                    gen_kwargs["seed"] = used_seed
                 audio_out = backend.generate(text, duration=duration, **gen_kwargs)
 
         return _apply_effect_chain(
@@ -870,7 +1124,6 @@ async def _finalize_generation(
     Returns ``(watermarked_tensor, meta)`` where ``meta`` carries
     ``id`` / ``filename`` / ``duration`` / ``gen_time``.
     """
-    loop = asyncio.get_running_loop()
     # Invisible AudioSeal provenance watermark on the final audio. Embedding
     # was previously only wired into the dub pipeline (dub_generate.py), so
     # plain TTS came out unmarked despite the setting being on — and the same
@@ -882,12 +1135,9 @@ async def _finalize_generation(
     # AudioSeal embedding is CPU work that holds no VRAM, so occupying a GPU
     # worker with it only delays the next generate on 1-worker hosts.
     if not already_marked:
-        from services.watermark import mark_synthetic
-        from services.model_manager import get_watermark_pool
-        audio_tensor = await loop.run_in_executor(
-            get_watermark_pool(),
-            functools.partial(mark_synthetic, audio_tensor, sample_rate,
-                              context="generate.finalize"),
+        from services.watermark import mark_synthetic_async
+        audio_tensor = await mark_synthetic_async(
+            audio_tensor, sample_rate, context="generate.finalize",
         )
     gen_time = round(time.time() - start_time, 2)
 
@@ -1146,9 +1396,6 @@ async def generate_speech(
     # classic flow, so streaming is purely a delivery channel — engine-agnostic
     # (text-level chunking, no per-engine token streaming).
     stream: bool = Form(False),
-    # Explicit opt-in. The absence of this field preserves the local-first
-    # /generate contract even when an administrator configured hosted values.
-    hosted: bool = Form(False),
 ):
     # #502: NFC-normalize the input text so decomposed (NFD) diacritics — common
     # in pasted Vietnamese and other Latin-with-marks text — are composed to the
@@ -1159,36 +1406,6 @@ async def generate_speech(
     import unicodedata
     text = unicodedata.normalize("NFC", text)
 
-    if hosted:
-        # Hosted execution accepts only a previously, explicitly synchronized
-        # consent-verified profile. Never silently sync a local recording from
-        # a synthesis request: that would make normal offline use an upload.
-        if not profile_id:
-            raise HTTPException(status_code=422, detail="Hosted synthesis requires a synchronized voice profile.")
-        from services.hosted_voice_api import HostedSettings, HostedVoiceClient, HostedVoiceError
-        try:
-            settings = HostedSettings.from_environment()
-        except HostedVoiceError as exc:
-            raise HTTPException(status_code=503, detail=str(exc)) from exc
-        if settings is None:
-            raise HTTPException(status_code=409, detail="Hosted synthesis is not configured on this device.")
-        with db_conn() as conn:
-            profile = conn.execute("SELECT hosted_voice_id, language FROM voice_profiles WHERE id=?", (profile_id,)).fetchone()
-        if not profile:
-            raise HTTPException(status_code=404, detail="Voice profile not found")
-        if not profile["hosted_voice_id"]:
-            raise HTTPException(status_code=422, detail="Sync this consent-verified profile to hosted before hosted synthesis.")
-        client = HostedVoiceClient(settings)
-        try:
-            audio = await client.synthesize(
-                text=text, profile_voice_id=profile["hosted_voice_id"], language=language or profile["language"],
-            )
-        except HostedVoiceError as exc:
-            raise HTTPException(status_code=502, detail=str(exc)) from exc
-        finally:
-            await client.aclose()
-        return StreamingResponse(io.BytesIO(audio), media_type="audio/wav", headers={"X-OmniVoice-Execution": "hosted"})
-
     # ── Engine resolution (issue #312) ──────────────────────────────────────
     # The request runs on the engine selected in Settings (POST /engines/select,
     # env var OMNIVOICE_TTS_BACKEND wins), or an explicit per-request `engine`
@@ -1231,6 +1448,12 @@ async def generate_speech(
     _backend = None
     _engine_min_vram_gb = getattr(backend_cls, "min_vram_gb", 0.0)
     _routing_notice = None
+    # Remote renders deliberately skip this host's capability gate. Keep the
+    # local fallback call's timeout device-neutral so the closure is valid
+    # without pretending the control plane describes the remote worker.
+    _routing = {"effective_device": None}
+    _routing_hardware_family = None
+    _routing_vram_gb = None
 
     if not _remote:
         # Single-active-engine memory discipline: hand back any OTHER resident
@@ -1287,11 +1510,16 @@ async def generate_speech(
         # 4090 from a Mac control plane would be refused by a gate describing
         # a machine that is about to do nothing.
         from core.device_caps import detect_host_caps
-        from services.engine_routing import resolve_routing, routing_notice
-        _routing = resolve_routing(
-            getattr(backend_cls, "gpu_compat", ("cpu",)), detect_host_caps(),
-            _engine_min_vram_gb,
+        from services.engine_routing import (
+            routing_notice,
+            runtime_compute_profile_async,
         )
+        _routing = await runtime_compute_profile_async(
+            backend_cls, detect_host_caps()
+        )
+        _engine_min_vram_gb = _routing["min_vram_gb"]
+        _routing_hardware_family = _routing.get("runtime_hardware_family")
+        _routing_vram_gb = _routing.get("runtime_vram_gb")
         if _routing["routing_status"] == "unavailable":
             # The engine needs an accelerator this host lacks and has no CPU path.
             raise HTTPException(status_code=400, detail=_routing["routing_reason"])
@@ -1330,6 +1558,7 @@ async def generate_speech(
 
     ref_audio_path = None
     cleanup_ref = False
+    ref_lease = None
     used_seed = seed
     resolved_profile_id = None
     history_mode = None  # profile.kind when a profile drives; else inferred at insert
@@ -1347,76 +1576,28 @@ async def generate_speech(
             row = conn.execute("SELECT * FROM voice_profiles WHERE id=?", (profile_id,)).fetchone()
         if row:
             resolved_profile_id = profile_id
-            # `kind` is authoritative (0005): 'design' profiles condition on
-            # their deterministic rendered sample + instruct; 'clone' on the
-            # user's reference. Lock always wins (it pins a specific take).
-            # Rows from pre-0004 DBs mid-upgrade may lack the column → fall
-            # back to the legacy is_locked/instruct inference.
-            try:
-                profile_kind = row["kind"] or "clone"
-            except (KeyError, IndexError):
-                profile_kind = "design" if (row["instruct"] and not row["is_locked"] and not row["ref_audio_path"]) else "clone"
-            history_mode = profile_kind
-            if row["is_locked"] and row["locked_audio_path"]:
-                ref_audio_path = os.path.join(VOICES_DIR, row["locked_audio_path"])
-                if not ref_text:
-                    ref_text = row["ref_text"]
-                if not instruct:
-                    instruct = _profile_instruct(row)
-                if used_seed is None and row["seed"] is not None:
-                    used_seed = row["seed"]
-            elif profile_kind == "design":
-                # Rendered sample (if present) carries the voice identity;
-                # instruct alone is the fallback for legacy archetype rows.
-                ref_audio_path = os.path.join(VOICES_DIR, row["ref_audio_path"]) if row["ref_audio_path"] else None
-                if ref_audio_path and not ref_text and row["ref_text"]:
-                    ref_text = row["ref_text"]
-                if not instruct:
-                    instruct = _profile_instruct(row)
-                if used_seed is None and row["seed"] is not None:
-                    used_seed = row["seed"]
-            elif row["instruct"] and not row["is_locked"] and not row["ref_audio_path"]:
-                # Legacy design-shaped row (pre-0004 archetype materialization
-                # failure path): instruct-only conditioning.
-                if not instruct:
-                    instruct = _profile_instruct(row)
-                if used_seed is None and row["seed"] is not None:
-                    used_seed = row["seed"]
-            else:
-                ref_audio_path = os.path.join(VOICES_DIR, row["ref_audio_path"]) if row["ref_audio_path"] else None
-                if not ref_text and row["ref_text"]:
-                    ref_text = row["ref_text"]
-                elif ref_audio_path and not ref_text:
-                    # Empty stored transcript → the auto-transcribe below will
-                    # run; cache its result onto the profile so it runs ONCE,
-                    # not on every generate (#1032 perf regression).
-                    persist_ref_text_profile_id = profile_id
-                if not instruct and row["instruct"]:
-                    instruct = row["instruct"]
-                if used_seed is None and row["seed"] is not None:
-                    used_seed = row["seed"]
-            if language == "Auto":
-                language = None
-            # #533: a profile's stored language must drive generation when the
-            # request didn't pin one. Without this the German (etc.) archetype
-            # generates with language=None and the model drifts to English —
-            # even though the archetype PREVIEW renders correctly (archetypes.py
-            # passes the language). An EXPLICIT non-Auto request language still
-            # wins; we only fill the gap. `row` is a sqlite3.Row, so guard the
-            # column lookup for pre-language DBs mid-upgrade.
-            if language is None:
-                try:
-                    prof_lang = row["language"]
-                except (KeyError, IndexError):
-                    prof_lang = None
-                if prof_lang and prof_lang != "Auto":
-                    language = prof_lang
+            # Shared with POST /convert — see _resolve_profile_conditioning
+            # for the resolution rules (kind-authoritative, lock wins, #533
+            # language fill, #1032 transcript-cache signal).
+            _cond = _resolve_profile_conditioning(
+                row, ref_text=ref_text, instruct=instruct, seed=used_seed,
+                language=language,
+            )
+            history_mode = _cond["kind"]
+            ref_audio_path = _cond["ref_audio_path"]
+            ref_text = _cond["ref_text"]
+            instruct = _cond["instruct"]
+            used_seed = _cond["seed"]
+            language = _cond["language"]
+            if _cond["persist_ref_text"]:
+                persist_ref_text_profile_id = profile_id
     elif ref_audio is not None:
         try:
             with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as f:
                 f.write(await ref_audio.read())
                 ref_audio_path = f.name
                 cleanup_ref = True
+                ref_lease = _TempReferenceLease(ref_audio_path)
         except Exception as e:
             raise HTTPException(status_code=500, detail=str(e))
 
@@ -1433,13 +1614,19 @@ async def generate_speech(
         # built-in ASR fallback), so a timeout degrades to None rather than
         # failing the whole generate.
         try:
-            ref_text = await run_on_gpu_pool_guarded(
-                functools.partial(transcribe_reference, ref_audio_path),
-                what="Reference transcribe",
-                # Floor budget (#1190): a reference clip is seconds of audio,
-                # so the length-scaled bonus never applies — but the timeout is
-                # explicit here too, so no dispatch relies on a hidden default.
-                timeout=_generate_timeout_s(""),
+            ref_text = await _run_with_reference_lease(
+                ref_lease,
+                lambda release: run_on_gpu_pool_guarded(
+                    functools.partial(transcribe_reference, ref_audio_path),
+                    what="Reference transcribe",
+                    # Floor budget (#1190): a reference clip is seconds of audio,
+                    # so the length-scaled bonus never applies — but the timeout is
+                    # explicit here too, so no dispatch relies on a hidden default.
+                    timeout=_generate_timeout_s(
+                        "", execution_device=_routing["effective_device"]
+                    ),
+                    on_abandon=release,
+                )
             )
         # TimeoutError covers both the execution bound and pool saturation:
         # this path is best-effort either way.
@@ -1556,7 +1743,13 @@ async def generate_speech(
             local=gpu_gateway.LocalCall(
                 _remote_only_local_call(_target_label),
                 what="TTS generate",
-                timeout=_generate_timeout_s(text),
+                timeout=_generate_timeout_s(
+                    text,
+                    execution_device=_routing["effective_device"],
+                    min_vram_gb=_engine_min_vram_gb,
+                    hardware_family=_routing_hardware_family,
+                    vram_gb=_routing_vram_gb,
+                ),
                 min_vram_gb=_engine_min_vram_gb,
             ),
             remote=_remote_call,
@@ -1695,19 +1888,30 @@ async def generate_speech(
                     "target_label": e.worker_label or _target_label,
                     "hint": e.hint,
                 })
-            except Exception:
+            except Exception as exc:
                 # Mid-job remote failure is NOT quietly redone here: the client
                 # treats a retryable error as "surface it", so the user decides
-                # whether to spend the same minutes again on this machine.
-                logger.error("Remote generation failed", exc_info=True)
-                from core.public_errors import stream_failure
-                yield _line({"type": "error", **stream_failure("generation_failed")})
+                # whether to spend the same minutes again on this machine. Like
+                # the local streaming path, this in-band frame stands in for the
+                # global 500 handler, so it journals the scrubbed failure and
+                # names a recognized cause instead of the bare generic string
+                # (#1607).
+                logger.error(
+                    "Remote generation failed (class=%s)",
+                    type(exc).__name__,
+                )
+                from core.public_errors import stream_generation_failure
+                from core import error_journal
+
+                error_journal.record(
+                    exc, route="/generate", trace=traceback.format_exc()
+                )
+                yield _line({"type": "error", **stream_generation_failure(exc)})
             finally:
                 if not render.done():
                     render.cancel()
-                if cleanup_ref and ref_audio_path:
-                    with contextlib.suppress(OSError):
-                        os.remove(ref_audio_path)
+                if cleanup_ref and ref_lease is not None:
+                    ref_lease.finish_request()
 
         return StreamingResponse(
             _remote_stream_events(),
@@ -1749,6 +1953,17 @@ async def generate_speech(
                         instruct=instruct, num_step=num_step,
                         guidance_scale=guidance_scale, speed=speed,
                         denoise=denoise, postprocess_output=postprocess_output,
+                        **({
+                            key: value for key, value in {
+                                "t_shift": t_shift,
+                                "layer_penalty_factor": layer_penalty_factor,
+                                "position_temperature": position_temperature,
+                                "class_temperature": class_temperature,
+                                "seed": used_seed + i if used_seed is not None else None,
+                            }.items() if value is not None
+                        } if getattr(
+                            _backend, "supports_native_omnivoice_controls", False
+                        ) else {}),
                     )
                     sr = _backend.sample_rate
                     skip = getattr(_backend, "applies_own_mastering", False)
@@ -1812,33 +2027,57 @@ async def generate_speech(
                 if _has_pause or len(_text_chunks) <= 1:
                     # Single-shot pipeline, unchanged — streamed as one chunk.
                     if _backend is not None:
-                        audio_tensor = await run_on_gpu_pool_guarded(
-                            functools.partial(
-                                _run_backend_inference,
-                                _backend, text, language, ref_audio_path, ref_text,
-                                instruct, duration, num_step, guidance_scale, speed,
-                                denoise, postprocess_output, used_seed, effect_preset,
-                                max_chunk_chars, crossfade_ms, dropped_sink=_dropped_sink,
-                            ),
-                            what="TTS generate",
-                            min_vram_gb=_engine_min_vram_gb,
-                            timeout=_generate_timeout_s(text),
+                        audio_tensor = await _run_with_reference_lease(
+                            ref_lease,
+                            lambda release: run_on_gpu_pool_guarded(
+                                functools.partial(
+                                    _run_backend_inference,
+                                    _backend, text, language, ref_audio_path, ref_text,
+                                    instruct, duration, num_step, guidance_scale, speed,
+                                    denoise, postprocess_output, used_seed, effect_preset,
+                                    max_chunk_chars, crossfade_ms, t_shift=t_shift,
+                                    layer_penalty_factor=layer_penalty_factor,
+                                    position_temperature=position_temperature,
+                                    class_temperature=class_temperature,
+                                    dropped_sink=_dropped_sink,
+                                ),
+                                what="TTS generate",
+                                min_vram_gb=_engine_min_vram_gb,
+                                timeout=_generate_timeout_s(
+                                    text,
+                                    execution_device=_routing["effective_device"],
+                                    min_vram_gb=_engine_min_vram_gb,
+                                    hardware_family=_routing_hardware_family,
+                                    vram_gb=_routing_vram_gb,
+                                ),
+                                on_abandon=release,
+                            )
                         )
                         sample_rate = _backend.sample_rate
                     else:
-                        audio_tensor = await run_on_gpu_pool_guarded(
-                            functools.partial(
-                                _run_inference,
-                                _model, text, language, ref_audio_path, ref_text,
-                                instruct, duration, num_step, guidance_scale, speed,
-                                t_shift, denoise, postprocess_output,
-                                layer_penalty_factor, position_temperature,
-                                class_temperature, used_seed, effect_preset,
-                                max_chunk_chars, crossfade_ms, dropped_sink=_dropped_sink,
-                            ),
-                            what="TTS generate",
-                            min_vram_gb=_engine_min_vram_gb,
-                            timeout=_generate_timeout_s(text),
+                        audio_tensor = await _run_with_reference_lease(
+                            ref_lease,
+                            lambda release: run_on_gpu_pool_guarded(
+                                functools.partial(
+                                    _run_inference,
+                                    _model, text, language, ref_audio_path, ref_text,
+                                    instruct, duration, num_step, guidance_scale, speed,
+                                    t_shift, denoise, postprocess_output,
+                                    layer_penalty_factor, position_temperature,
+                                    class_temperature, used_seed, effect_preset,
+                                    max_chunk_chars, crossfade_ms, dropped_sink=_dropped_sink,
+                                ),
+                                what="TTS generate",
+                                min_vram_gb=_engine_min_vram_gb,
+                                timeout=_generate_timeout_s(
+                                    text,
+                                    execution_device=_routing["effective_device"],
+                                    min_vram_gb=_engine_min_vram_gb,
+                                    hardware_family=_routing_hardware_family,
+                                    vram_gb=_routing_vram_gb,
+                                ),
+                                on_abandon=release,
+                            )
                         )
                         sample_rate = _model.sampling_rate
                     yield _line({
@@ -1855,12 +2094,10 @@ async def generate_speech(
                     # (#1190): AudioSeal embedding is CPU work that owns no
                     # VRAM, and on a 1-worker host it used to serialize
                     # directly ahead of the next generate.
-                    from services.watermark import mark_synthetic
-                    from services.model_manager import get_watermark_pool
-                    _preview = await asyncio.get_running_loop().run_in_executor(
-                        get_watermark_pool(),
-                        functools.partial(mark_synthetic, audio_tensor, sample_rate,
-                                          context="generate.stream_preview"),
+                    from services.watermark import mark_synthetic_async
+                    _preview = await mark_synthetic_async(
+                        audio_tensor, sample_rate,
+                        context="generate.stream_preview",
                     )
                     yield _line({"type": "chunk", "seq": 0, "pcm": _pcm16_b64(_preview)})
                 else:
@@ -1869,25 +2106,33 @@ async def generate_speech(
                     for i, chunk_text in enumerate(_text_chunks):
                         # Bounded per chunk + pool-reset on hang (#730 class);
                         # a timeout surfaces as an "error" event below.
-                        raw, preview, sample_rate = await run_on_gpu_pool_guarded(
-                            functools.partial(_render_stream_chunk, i, chunk_text),
-                            what="TTS generate",
-                            min_vram_gb=_engine_min_vram_gb,
-                            # Budget scaled to THIS chunk (#1190) — the flat
-                            # 300s here is what made long streamed renders fail
-                            # even after the v0.3.22 scaled budget shipped.
-                            timeout=_generate_timeout_s(chunk_text),
+                        raw, preview, sample_rate = await _run_with_reference_lease(
+                            ref_lease,
+                            lambda release: run_on_gpu_pool_guarded(
+                                functools.partial(_render_stream_chunk, i, chunk_text),
+                                what="TTS generate",
+                                min_vram_gb=_engine_min_vram_gb,
+                                # Budget scaled to THIS chunk (#1190) — the flat
+                                # 300s here is what made long streamed renders fail
+                                # even after the v0.3.22 scaled budget shipped.
+                                timeout=_generate_timeout_s(
+                                    chunk_text,
+                                    execution_device=_routing["effective_device"],
+                                    min_vram_gb=_engine_min_vram_gb,
+                                    hardware_family=_routing_hardware_family,
+                                    vram_gb=_routing_vram_gb,
+                                ),
+                                on_abandon=release,
+                            )
                         )
                         parts.append(raw)
                         # Provenance-mark the streamed copy off the GPU pool
                         # (#1169 mark, #1190 placement): CPU-only AudioSeal
                         # work must not occupy a GPU worker between chunks.
-                        from services.watermark import mark_synthetic
-                        from services.model_manager import get_watermark_pool
-                        preview = await asyncio.get_running_loop().run_in_executor(
-                            get_watermark_pool(),
-                            functools.partial(mark_synthetic, preview, sample_rate,
-                                              context="generate.stream_preview"),
+                        from services.watermark import mark_synthetic_async
+                        preview = await mark_synthetic_async(
+                            preview, sample_rate,
+                            context="generate.stream_preview",
                         )
                         if i == 0:
                             # After the first render so lazy-loading engines
@@ -1902,7 +2147,7 @@ async def generate_speech(
                     audio_tensor = await run_on_gpu_pool_guarded(
                         functools.partial(_assemble_stream_chunks, parts, sample_rate),
                         what="TTS assemble",
-                        timeout=_generate_timeout_s(text),
+                        timeout=_generate_timeout_s(text, execution_device=_routing["effective_device"]),
                     )
 
                 _, meta = await _finalize_generation(
@@ -1931,7 +2176,7 @@ async def generate_speech(
                 # Client went away mid-stream — same semantics as aborting a
                 # classic /generate mid-render: nothing is saved.
                 raise
-            except (GpuJobTimeoutError, GpuPoolBusyError) as e:
+            except GpuPoolBusyError as e:
                 # In-band error frame carries the machine-readable retryable
                 # marker (#1190) — an NDJSON consumer can back off instead of
                 # guessing from the prose.
@@ -1940,20 +2185,44 @@ async def generate_speech(
                 failure = stream_failure("generation_busy")
                 failure["retry_after"] = getattr(e, "retry_after", 30)
                 yield _line({"type": "error", **failure})
+            except GpuJobTimeoutError:
+                # The worker started and spent its full execution budget. That
+                # is compute time, not queue pressure (#1588).
+                logger.error("Streaming generation exceeded its compute budget")
+                from core.public_errors import stream_failure
+                failure = stream_failure("generation_timeout")
+                failure["retry_after"] = 30
+                yield _line({"type": "error", **failure})
             except ValueError:
                 logger.error("Streaming generation request rejected")
                 from core.public_errors import stream_failure
                 yield _line({"type": "error", **stream_failure("invalid_request")})
-            except Exception:
-                logger.error("Streaming generation failed unexpectedly")
-                from core.public_errors import stream_failure
-                yield _line({"type": "error", **stream_failure("generation_failed")})
+            except Exception as exc:
+                # A streaming request answers 200 and carries its failure as an
+                # in-band error frame, so it never reaches the global 500
+                # handler — which is where a classic /generate failure gets its
+                # scrubbed journal entry (Diagnostics / recent errors) AND its
+                # classified, actionable message. Both have to be reproduced
+                # here or a streaming generation failure is invisible in the
+                # diagnostic bundle and opaque to the user (#1607). The raw
+                # exception is NOT logged: it can carry a reference-clip path or
+                # a provider secret, and only the journal scrubs before storing.
+                logger.error(
+                    "Streaming generation failed unexpectedly (class=%s)",
+                    type(exc).__name__,
+                )
+                from core.public_errors import stream_generation_failure
+                from core import error_journal
+
+                error_journal.record(
+                    exc, route="/generate", trace=traceback.format_exc()
+                )
+                yield _line({"type": "error", **stream_generation_failure(exc)})
             finally:
                 # Ownership of the temp reference clip moves to this generator
                 # in stream mode (the route returns before rendering starts).
-                if cleanup_ref and ref_audio_path:
-                    with contextlib.suppress(OSError):
-                        os.remove(ref_audio_path)
+                if cleanup_ref and ref_lease is not None:
+                    ref_lease.finish_request()
 
         # Routing notice (#21): known before the stream starts, so it rides the
         # same headers the classic path uses — and now also carries "your
@@ -1991,7 +2260,11 @@ async def generate_speech(
                     _backend, text, language, ref_audio_path, ref_text, instruct,
                     duration, num_step, guidance_scale, speed, denoise,
                     postprocess_output, used_seed, effect_preset,
-                    max_chunk_chars, crossfade_ms, dropped_sink=_dropped_text,
+                    max_chunk_chars, crossfade_ms, t_shift=t_shift,
+                    layer_penalty_factor=layer_penalty_factor,
+                    position_temperature=position_temperature,
+                    class_temperature=class_temperature,
+                    dropped_sink=_dropped_text,
                 )
             else:
                 _local_render = functools.partial(
@@ -2002,14 +2275,24 @@ async def generate_speech(
                     class_temperature, used_seed, effect_preset,
                     max_chunk_chars, crossfade_ms, dropped_sink=_dropped_text,
                 )
-            audio_tensor = await gpu_gateway.run(
-                _REMOTE_OP,
-                local=gpu_gateway.LocalCall(
-                    _local_render, what="TTS generate",
-                    timeout=_generate_timeout_s(text),
-                    min_vram_gb=_engine_min_vram_gb,
-                ),
-                decision=_decision,
+            audio_tensor = await _run_with_reference_lease(
+                ref_lease,
+                lambda release: gpu_gateway.run(
+                    _REMOTE_OP,
+                    local=gpu_gateway.LocalCall(
+                        _local_render, what="TTS generate",
+                        timeout=_generate_timeout_s(
+                            text,
+                            execution_device=_routing["effective_device"],
+                            min_vram_gb=_engine_min_vram_gb,
+                            hardware_family=_routing_hardware_family,
+                            vram_gb=_routing_vram_gb,
+                        ),
+                        min_vram_gb=_engine_min_vram_gb,
+                        on_abandon=release,
+                    ),
+                    decision=_decision,
+                )
             )
             # Read after generation: engines with lazy model loading report
             # their real rate only once weights are up.
@@ -2129,7 +2412,16 @@ async def generate_speech(
         raise HTTPException(status_code=503, detail=str(e)) from e
     except ValueError as e:
         logger.error("Validation failed: %s", e)
-        raise HTTPException(status_code=400, detail=str(e)) from e
+        # Most ValueErrors here are VoiceStudio's own validation messages and
+        # are exactly what the user should read. A few are raw library text
+        # naming parameters and files the user cannot act on — those get the
+        # owned remedy for their class instead (#1879). Unclassified ones keep
+        # passing through, so this cannot swallow a good message.
+        from core.failure import classify, public_hint_for_topic
+
+        _topic = classify(str(e))
+        _owned = public_hint_for_topic(_topic) if _topic else ""
+        raise HTTPException(status_code=400, detail=_owned or str(e)) from e
     except Exception as e:
         tb = traceback.format_exc()
         logger.error("Inference failed: %s\n%s", e, tb)
@@ -2141,9 +2433,8 @@ async def generate_speech(
             ),
         )
     finally:
-        if cleanup_ref and ref_audio_path:
-            with contextlib.suppress(OSError):
-                os.remove(ref_audio_path)
+        if cleanup_ref and ref_lease is not None:
+            ref_lease.finish_request()
 
 def _safe_output_path(name):
     if not name:

backend/api/routers/openai_compat.py

@@ -160,7 +160,9 @@ _OPENAI_VOICE_ALIASES = {
 
 def _resolve_engine(model_id: str):
     """Map an OpenAI model name to a VoiceStudio backend."""
-    from services.tts_backend import get_backend_class, get_active_tts_backend
+    from services.tts_backend import (
+        get_backend_class, get_active_tts_backend, get_engine_instance_for,
+    )
 
     # Accept OpenAI model names as pass-through to the active engine.
     if model_id in ("tts-1", "tts-1-hd"):
@@ -177,8 +179,18 @@ def _resolve_engine(model_id: str):
             )
         from services.tts_backend import OmniVoiceBackend
         if cls is OmniVoiceBackend:
+            # OmniVoice only ever runs as the shared active engine — the
+            # explicit-omnivoice request is the active-engine request.
             return get_active_tts_backend()
-        return cls()
+        # Cached singleton, not a fresh cls(): SubprocessBackend engines would
+        # spawn a sidecar process and reload their model on EVERY request, and
+        # register a new atexit hook each time (get_engine_instance's contract).
+        # No router-local cache on top of it: the shared cache is keyed by
+        # CLASS precisely so id rebinds/evictions can't serve a stale instance,
+        # and cross-engine memory discipline is create_speech's
+        # evict_other_tts_engines call (the same seam /generate uses) — not a
+        # bespoke unload here.
+        return get_engine_instance_for(model_id)
     except ValueError:
         raise HTTPException(
             status_code=400,
@@ -313,10 +325,9 @@ async def create_speech(req: SpeechRequest):
 
     # Routing gate (#21 — no silent CPU fallback), identical to REST /generate.
     from core.device_caps import detect_host_caps
-    from services.engine_routing import resolve_routing, routing_notice
-    _routing = resolve_routing(
-        getattr(backend, "gpu_compat", ("cpu",)), detect_host_caps(),
-        getattr(backend, "min_vram_gb", 0.0),
+    from services.engine_routing import routing_notice, runtime_compute_profile_async
+    _routing = await runtime_compute_profile_async(
+        backend, detect_host_caps()
     )
     if _routing["routing_status"] == "unavailable":
         raise HTTPException(status_code=400, detail=_routing["routing_reason"])
@@ -388,6 +399,15 @@ async def create_speech(req: SpeechRequest):
     # VRAM eviction runs in get_model()'s warm-return path now, covering every
     # native TTS generate (this route, WS TTS, dub, batch, audiobook).
 
+    # Single-active-engine memory discipline (MM2-01), the same call /generate
+    # makes before its load: hand back every OTHER resident TTS engine's model
+    # before this one warms up, so switching `model` ids across requests —
+    # explicit id → explicit id, or explicit id → the tts-1/omnivoice aliases —
+    # can't stack multi-GB engines/sidecars. No-op when nothing else is
+    # resident; opt out with OMNIVOICE_SINGLE_ENGINE_RESIDENT=0.
+    from services.engine_memory import evict_other_tts_engines
+    await evict_other_tts_engines(backend.id)
+
     # ── #1033/#1037/#1014: warm the engine under the LOAD budget before the
     # generate clock starts. The T4 verification (#1014) measured a fresh
     # install's first /v1/audio/speech burning its whole 300s generate budget
@@ -454,7 +474,7 @@ async def create_speech(req: SpeechRequest):
         from services.model_manager import generate_timeout_s
         wav, sr = await run_on_gpu_pool_guarded(
             lambda: _run_tts(backend, text, kw), what="OpenAI TTS generate",
-            timeout=generate_timeout_s(text))
+            timeout=generate_timeout_s(text, engine=backend))
     except Exception as e:
         # #1172/#1173: typed failures get their real status + actionable
         # message (400 bad input / 503 broken engine binary) instead of a

backend/api/routers/profiles.py

@@ -14,7 +14,6 @@ from core import event_bus
 from core.personalities import get_personalities
 from omnivoice.utils.voice_design import heal_design_instruct, sanitize_instruct
 from core.path_security import UnsafePath, resolve_within
-from services.hosted_voice_api import HostedSettings, HostedVoiceClient, HostedVoiceError
 
 router = APIRouter()
 
@@ -185,50 +184,6 @@ def get_profile(profile_id: str):
     return dict(row)
 
 
-@router.post("/profiles/{profile_id}/hosted-sync")
-async def sync_profile_to_hosted(profile_id: str):
-    """Explicitly copy a consent-verified local clone to the hosted library.
-
-    This is deliberately not part of local profile creation: merely creating a
-    profile must never upload biometric source audio. The hosted service records
-    the existing spoken-consent evidence as its versioned attestation; it does
-    not receive the consent recording itself.
-    """
-    try:
-        settings = HostedSettings.from_environment()
-    except HostedVoiceError as exc:
-        raise HTTPException(status_code=503, detail=str(exc)) from exc
-    if settings is None:
-        raise HTTPException(status_code=409, detail="Hosted voice sync is not configured on this device.")
-    with db_conn() as conn:
-        row = conn.execute(
-            "SELECT id, name, description, ref_text, ref_audio_path, verified_own_voice, consent_text, hosted_voice_id "
-            "FROM voice_profiles WHERE id=?", (profile_id,)
-        ).fetchone()
-    if not row:
-        raise HTTPException(status_code=404, detail="Profile not found")
-    if row["hosted_voice_id"]:
-        return {"profile_id": profile_id, "hosted_voice_id": row["hosted_voice_id"], "state": "already_synced"}
-    if not row["verified_own_voice"] or not row["consent_text"].strip():
-        raise HTTPException(status_code=422, detail="Record the voice-ownership consent statement before hosted sync.")
-    reference_path = _voices_path(row["ref_audio_path"] or "")
-    if not reference_path or not os.path.isfile(reference_path):
-        raise HTTPException(status_code=422, detail="This profile has no local reference recording to sync.")
-    client = HostedVoiceClient(settings)
-    try:
-        hosted_voice_id = await client.create_voice(
-            name=row["name"], description=row["description"] or row["ref_text"] or "", reference_path=reference_path,
-        )
-    except HostedVoiceError as exc:
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
-    finally:
-        await client.aclose()
-    with db_conn() as conn:
-        conn.execute("UPDATE voice_profiles SET hosted_voice_id=? WHERE id=? AND hosted_voice_id=''", (hosted_voice_id, profile_id))
-        persisted = conn.execute("SELECT hosted_voice_id FROM voice_profiles WHERE id=?", (profile_id,)).fetchone()["hosted_voice_id"]
-    return {"profile_id": profile_id, "hosted_voice_id": persisted, "state": "synced"}
-
-
 @router.put("/profiles/{profile_id}")
 def update_profile(profile_id: str, patch: ProfileUpdate):
     """Partial update — only fields set on the payload are changed."""

backend/api/routers/pronunciation.py

@@ -32,7 +32,11 @@ from pydantic import BaseModel
 
 from api.dependencies import require_admin
 from core.db import db_conn
-from services.pronunciation import apply_pronunciation, entries_for_language
+from services.pronunciation import (
+    apply_pronunciation,
+    entries_for_language,
+    inert_entries_for_language,
+)
 
 logger = logging.getLogger("omnivoice.pronunciation")
 router = APIRouter(dependencies=[Depends(require_admin)])
@@ -250,11 +254,18 @@ def test_substitution(req: PronTestRequest):
         ).fetchall()
     substituted = apply_pronunciation(req.text, rows, req.language)
     applied = entries_for_language(rows, req.language)
+    # IPA/CMU rows are validated and stored but not applied yet, so a term that
+    # DOES match can still change nothing. Reporting them separately keeps the
+    # dry run honest — otherwise it says "no entries match", which is wrong and
+    # sends the user to re-type an entry that was already correct (#1949).
+    inert = inert_entries_for_language(rows, req.language)
     return {
         "input": req.text,
         "substituted": substituted,
         "changed": substituted != req.text,
         "applied_terms": sorted(applied.keys(), key=len, reverse=True),
+        # Present but not honoured: [{term, type}, …]. Empty on the happy path.
+        "inert_entries": inert,
     }
 
 

backend/api/routers/settings.py

@@ -35,11 +35,11 @@ class _HFTokenBody(BaseModel):
     token: str = Field(..., min_length=1, description="HuggingFace access token")
 
 
-def _state_response() -> dict:
+def _state_response(*, validate: bool = False) -> dict:
     """Return the same shape the React panel renders. Never includes raw token."""
     from services import token_resolver
 
-    s = token_resolver.state()
+    s = token_resolver.state(validate=validate)
     return {
         "active": s["active"],
         "sources": [asdict(row) for row in s["sources"]],
@@ -65,8 +65,7 @@ def save_hf_token(body: _HFTokenBody):
 
 @router.delete("/hf-token")
 def clear_hf_token(also_clear_hf_cli: bool = Query(False)):
-    """Clear the App-source token. Optionally also call huggingface_hub.logout
-    to clear the canonical HF file. Returns the updated cascade state."""
+    """Clear the App token and optionally recognized local Hub token files."""
     from services import token_resolver
     try:
         token_resolver.clear_app_token(also_clear_hf_cli=also_clear_hf_cli)
@@ -82,13 +81,12 @@ def get_hf_token_state(fresh: bool = Query(False)):
 
     ``fresh=1`` drops the resolver's whoami validation cache first so the
     response re-runs whoami for every source — this is what the panel's
-    "Test now" button sends. Plain GETs (panel mounts) keep the 300s cache
-    so repeat Settings visits don't hammer the HF API.
+    "Test now" button sends. Plain GETs only inspect local token presence.
     """
     from services import token_resolver
     if fresh:
         token_resolver.invalidate_cache()
-    return _state_response()
+    return _state_response(validate=fresh)
 
 
 # ── Performance settings (INST-12) ────────────────────────────────────────
@@ -150,7 +148,7 @@ def _compute_device_state() -> dict:
     caps = device_caps.detect_host_caps()
     env_pin = (os.environ.get("OMNIVOICE_DEVICE") or "").strip().lower()
     auto_family = next(
-        (f for f in ("cuda", "rocm", "xpu", "mps") if f in caps.available_families),
+        (f for f in device_caps.ACCELERATOR_PRIORITY if f in caps.available_families),
         "cpu",
     )
     value = device_caps.requested_device_override()
@@ -1035,9 +1033,10 @@ def set_asr_openai_compat(body: _ASROpenAICompatBody):
     from services import asr_backend, settings_store
 
     if body.base_url is not None:
-        url = body.base_url.strip().rstrip("/")
-        if url and not url.startswith(("http://", "https://")):
-            raise HTTPException(status_code=400, detail="Base URL must start with http(s)://")
+        try:
+            url = asr_backend.normalize_openai_compat_asr_base_url(body.base_url)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
         settings_store.set_text(asr_backend._ASR_OPENAI_COMPAT_BASE_URL_KEY, url)
     if body.model is not None:
         settings_store.set_text(

backend/api/routers/setup/download.py

@@ -76,6 +76,7 @@ _cancelled: set[str] = set()
 _active_installs: set[str] = set()
 _active_installs_lock = threading.Lock()
 _install_tasks: set[asyncio.Task] = set()
+_install_tasks_by_repo: dict[str, asyncio.Task] = {}
 
 
 def _download_max_workers() -> int:
@@ -380,11 +381,60 @@ def _is_retryable_download_error(exc: BaseException) -> bool:
     return is_hf_connectivity_error(str(exc))
 
 
+def _segmented_retry_plan(
+    exc: BaseException, attempt: int, max_attempts: int
+) -> tuple[bool, bool]:
+    """What to do after the segmented accelerator failed on ``attempt``.
+
+    Returns ``(disable_accelerator, reraise)``.
+
+    A dropped connection is not the accelerator's fault, so the error is
+    re-raised for the outer retry: the next attempt re-enters
+    :func:`_segmented_snapshot`, which resumes from the ``.part`` manifest.
+    Falling straight through to ``snapshot_download`` instead would finish the
+    install from a separate ``.incomplete`` file and strand that manifest — the
+    restart-from-zero this exists to prevent.
+
+    The final attempt is always reserved for the plain path, so the accelerator
+    can never be the reason an install fails outright. The two flags are
+    decoupled for that handover: the attempt that exhausts the accelerator still
+    re-raises, so the plain path starts on the LAST attempt rather than the
+    second-to-last. Disabling and falling through in the same attempt would
+    abandon the resumable manifest one attempt early and restart through a
+    separate file — which is the failure this whole helper exists to avoid.
+    """
+    if not _is_retryable_download_error(exc):
+        return True, False  # the accelerator cannot work here at all
+    if attempt >= max_attempts:
+        # Nothing left to hand over to: take the plain path now rather than
+        # re-raising out of the loop with no fallback ever tried.
+        return True, False
+    return attempt >= max_attempts - 1, True
+
+
+def _segmented_retry_note(disable: bool, reraise: bool) -> str:
+    """How to describe the outcome of :func:`_segmented_retry_plan` in the log.
+
+    Three distinct states, and reading only ``disable`` conflates two of them:
+    the attempt that exhausts the accelerator is disabled AND re-raises, so the
+    fallback starts on the NEXT attempt, not this one.
+    """
+    if not disable:
+        return "kept for the next attempt (resumes from its manifest)"
+    if reraise:
+        return "exhausted — retrying once more, then snapshot_download takes over"
+    return "disabled for this install — falling back to snapshot_download now"
+
+
 @router.post("/models/install")
 async def install_model(req: InstallModelRequest):
     """Download one HF repo snapshot; progress goes through the shared
     ``/setup/download-stream`` SSE feed."""
-    if req.repo_id not in [m["repo_id"] for m in KNOWN_MODELS]:
+    model_spec = next(
+        (model for model in KNOWN_MODELS if model["repo_id"] == req.repo_id),
+        None,
+    )
+    if model_spec is None:
         raise HTTPException(
             status_code=400,
             detail=(
@@ -392,6 +442,7 @@ async def install_model(req: InstallModelRequest):
                 + ", ".join(m["repo_id"] for m in KNOWN_MODELS)
             ),
         )
+    allow_patterns = list(model_spec.get("allow_patterns") or []) or None
     target = (req.target or "").strip()
     if target != "local":
         from services import gpu_gateway  # noqa: PLC0415
@@ -420,16 +471,11 @@ async def install_model(req: InstallModelRequest):
                 f"Retry in {remaining}s or check your network."
             ),
         )
-    with _active_installs_lock:
-        if req.repo_id in _active_installs:
-            return {"status": "already_running", "repo_id": req.repo_id}
-        _active_installs.add(req.repo_id)
     loop = asyncio.get_running_loop()
 
     def _do():
         token = hf_progress.current_repo_id.set(req.repo_id)
         target_token = hf_progress.current_target.set("local")
-        _cancelled.discard(req.repo_id)  # clear any stale cancel from a prior run
         hf_progress.emit({
             "repo_id": req.repo_id,
             "filename": req.repo_id,
@@ -454,6 +500,8 @@ async def install_model(req: InstallModelRequest):
                 "revision": revision_for(req.repo_id),
                 "max_workers": _download_max_workers(),
             }
+            if allow_patterns:
+                dl_kwargs["allow_patterns"] = allow_patterns
             _tqdm_cls = hf_progress.tracked_tqdm_class()
             if _tqdm_cls is not None:
                 dl_kwargs["tqdm_class"] = _tqdm_cls
@@ -497,6 +545,8 @@ async def install_model(req: InstallModelRequest):
                 "revision": dl_kwargs["revision"],
                 "dry_run": True,
             }
+            if allow_patterns:
+                _preflight_kwargs["allow_patterns"] = allow_patterns
             if _endpoint:
                 _preflight_kwargs["endpoint"] = _endpoint
             try:
@@ -552,6 +602,11 @@ async def install_model(req: InstallModelRequest):
 
             _max_attempts = 5
             _attempt = 0
+            # The accelerator is retried across attempts so its manifest-based
+            # resume actually gets used; it is disabled for the rest of the
+            # install only when it fails for a reason that is NOT transient
+            # network trouble (i.e. the accelerator itself is unusable here).
+            _segmented_off = False
             while True:
                 if req.repo_id in _cancelled:
                     raise _InstallCancelled()
@@ -559,11 +614,17 @@ async def install_model(req: InstallModelRequest):
                 try:
                     # Segmented accelerator (FDL-09, default ON): parallel
                     # byte-range fetch with real live progress, for the
-                    # legacy-LFS path. Any failure falls through to
-                    # snapshot_download — the accelerator can never compromise a
-                    # correct install.
+                    # legacy-LFS path. A failure that is not transient network
+                    # trouble falls through to snapshot_download, and so does the
+                    # install's last attempt — the accelerator can never
+                    # compromise a correct install (see _segmented_retry_plan).
                     _snapshot_path = None
-                    if _attempt == 1 and _segmented_enabled() and not _xet_active():
+                    if (
+                        not _segmented_off
+                        and not allow_patterns
+                        and _segmented_enabled()
+                        and not _xet_active()
+                    ):
                         try:
                             _snapshot_path = _segmented_snapshot(
                                 req.repo_id,
@@ -573,10 +634,16 @@ async def install_model(req: InstallModelRequest):
                         except _InstallCancelled:
                             raise
                         except Exception as _seg_err:
-                            logger.info(
-                                "segmented download for %s failed (%s); falling back to snapshot_download",
-                                req.repo_id, _seg_err,
+                            _segmented_off, _seg_reraise = _segmented_retry_plan(
+                                _seg_err, _attempt, _max_attempts
                             )
+                            logger.info(
+                                "segmented download for %s failed (%s); accelerator %s",
+                                req.repo_id, _seg_err,
+                                _segmented_retry_note(_segmented_off, _seg_reraise),
+                            )
+                            if _seg_reraise:
+                                raise
                             _snapshot_path = None
                     if _snapshot_path is None:
                         _snapshot_path = snapshot_download(**dl_kwargs)  # nosec B615 -- immutable revision_for pin
@@ -688,17 +755,53 @@ async def install_model(req: InstallModelRequest):
             with _active_installs_lock:
                 _active_installs.discard(req.repo_id)
 
-    try:
-        task = loop.create_task(asyncio.to_thread(_do))
-        _install_tasks.add(task)
-        task.add_done_callback(_install_tasks.discard)
-    except Exception:
-        with _active_installs_lock:
+    with _active_installs_lock:
+        if req.repo_id in _active_installs:
+            return {"status": "already_running", "repo_id": req.repo_id}
+        _active_installs.add(req.repo_id)
+        # Admission and task publication are one atomic generation boundary:
+        # cancellation can never observe an admitted install without its task.
+        _cancelled.discard(req.repo_id)
+        try:
+            task = loop.create_task(asyncio.to_thread(_do))
+            _install_tasks.add(task)
+            _install_tasks_by_repo[req.repo_id] = task
+        except Exception:
             _active_installs.discard(req.repo_id)
-        raise
+            raise
+
+    def install_finished(completed: asyncio.Task) -> None:
+        with _active_installs_lock:
+            _install_tasks.discard(completed)
+            if _install_tasks_by_repo.get(req.repo_id) is completed:
+                _install_tasks_by_repo.pop(req.repo_id, None)
+
+    task.add_done_callback(install_finished)
     return {"status": "install_started", "repo_id": req.repo_id}
 
 
+async def cancel_install_and_wait(repo_id: str) -> None:
+    """Request cancellation and retain authority until its thread exits."""
+    from worker.async_utils import drain_task  # noqa: PLC0415
+
+    with _active_installs_lock:
+        _cancelled.add(repo_id)
+        _install_cooldowns.pop(repo_id, None)
+        task = _install_tasks_by_repo.get(repo_id)
+    if task is None:
+        return
+    try:
+        # asyncio.to_thread cannot stop snapshot_download mid-file. Cancelling
+        # its wrapper would only detach the thread, so wait until the blocking
+        # call observes the flag or naturally returns.
+        await drain_task(task)
+    finally:
+        with _active_installs_lock:
+            current = _install_tasks_by_repo.get(repo_id)
+            if current is None or current is task:
+                _cancelled.discard(repo_id)
+
+
 @router.post("/models/install/cancel")
 async def cancel_install(req: InstallModelRequest):
     """Request cancellation of an in-flight install (FDL-11).

backend/api/routers/setup/wizard.py

@@ -19,6 +19,7 @@ import sys
 from fastapi import APIRouter
 
 from api.schemas import SetupStatusResponse, PreflightResponse
+from core.device_caps import KERNEL_RISK_MARKER
 # MIN_FREE_GB + disk_free_bytes are single-sourced in ``.models`` (the lowest
 # module in the setup import graph) so the wizard gate, the /models header, and
 # the per-install disk guard can't drift apart.
@@ -62,6 +63,11 @@ def setup_status():
 _MIN_NVIDIA_DRIVER = 555
 _RAM_FAIL_GB = 8
 _RAM_WARN_GB = 12
+# Installed DIMMs never fully reach the OS: firmware, integrated graphics and
+# kernel reservations shave off up to ~7% (an "8 GB" Windows laptop reports
+# ~7.8 GB usable). Thresholds are compared with this allowance applied so the
+# machines a threshold is meant to admit aren't blocked by that gap (#1618).
+_RAM_RESERVED_ALLOWANCE = 0.93
 
 
 def _run_cmd(args: list[str], timeout: float = 2.0) -> tuple[int, str]:
@@ -169,8 +175,8 @@ def _detect_gpu() -> dict:
     return info
 
 
-def _probe_network(host: str = "huggingface.co", port: int = 443, timeout: float = 2.0) -> bool:
-    """Tiny TCP connect test."""
+def _probe_network(host: str = "huggingface.co", port: int = 443, timeout: float = 8.0) -> bool:
+    """Tiny TCP connect test. 8s default — high-latency / China paths often exceed 2–3s."""
     import socket
     try:
         with socket.create_connection((host, port), timeout=timeout):
@@ -352,17 +358,28 @@ def preflight():
 
     # ── RAM
     ram = _ram_gb()
+    # Escape hatch (#1618): a preflight should inform, not brick setup —
+    # OMNIVOICE_RAM_PREFLIGHT=0 downgrades the hard block to a warning for
+    # users who accept the OOM risk. Same opt-out shape as
+    # OMNIVOICE_ASR_VRAM_PREFLIGHT.
+    ram_gate = os.environ.get(
+        "OMNIVOICE_RAM_PREFLIGHT", "1"
+    ).strip().lower() not in ("0", "false", "no")
     if ram == 0:
         ram_status, ram_detail, ram_fix = (
             "warn", "Could not detect system RAM.",
             "Install psutil in the backend environment or ignore this warning.",
         )
-    elif ram < _RAM_FAIL_GB:
+    elif ram < _RAM_FAIL_GB * _RAM_RESERVED_ALLOWANCE:
         ram_status, ram_detail, ram_fix = (
-            "fail", f"{ram:.1f} GB total (need ≥ {_RAM_FAIL_GB} GB)",
-            "The app will OOM on first dub. Close other apps or upgrade RAM.",
+            "fail" if ram_gate else "warn",
+            f"{ram:.1f} GB total (need ≥ {_RAM_FAIL_GB} GB)",
+            "The app will OOM on first dub. Close other apps or upgrade RAM."
+            if ram_gate else
+            "RAM check disabled via OMNIVOICE_RAM_PREFLIGHT=0 — dubbing may "
+            "OOM on this machine.",
         )
-    elif ram < _RAM_WARN_GB:
+    elif ram < _RAM_WARN_GB * _RAM_RESERVED_ALLOWANCE:
         ram_status, ram_detail, ram_fix = (
             "warn", f"{ram:.1f} GB total ({_RAM_WARN_GB}+ GB recommended)",
             "Long videos may hit swap. Keep other apps closed during dubbing.",
@@ -482,10 +499,14 @@ def preflight():
         _why = gpu_routing.get("routing_reason")
         if _rs == "accelerated" and not _why:
             r_status, r_detail, r_fix = "pass", f"{_eng} → {_dev} (accelerated)", None
-        elif _rs == "accelerated":  # driver/arch caveat
+        elif _rs == "accelerated" and KERNEL_RISK_MARKER in (_why or ""):
             r_status, r_detail, r_fix = "warn", f"{_eng} → {_dev}: {_why}", (
                 "GPU selected but may fail at kernel launch — update drivers / "
                 "reinstall torch for this GPU architecture.")
+        elif _rs == "accelerated":  # low-VRAM caveat — not a driver/arch issue
+            r_status, r_detail, r_fix = "warn", f"{_eng} → {_dev}: {_why}", (
+                "Unload other models before generating, keep the text short, "
+                "or pick a lighter engine.")
         elif _rs == "cpu_fallback":
             r_status, r_detail, r_fix = "warn", (
                 f"{_eng} runs on CPU here: {_why or 'no GPU path for this host'}"), (

backend/api/routers/speech_platform.py

@@ -0,0 +1,160 @@
+"""Discovery contract for VoiceStudio's local speech platform.
+
+Interfaces should discover this document instead of hard-coding whichever
+dictation route the desktop happens to use.  Endpoint URLs are relative so the
+same response works on loopback, a tailnet GPU host, and a reverse proxy.
+"""
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+from core.version import APP_VERSION
+
+router = APIRouter(tags=["Speech Platform"])
+
+SPEECH_PROTOCOL = "voicestudio.speech.v1"
+STREAM_PATH = "/v1/audio/transcriptions/stream"
+
+
+class EndpointCapability(BaseModel):
+    path: str
+    transport: Literal["http", "websocket", "mcp-streamable-http", "mcp-stdio"]
+    method: str | None = None
+    protocol: str | None = None
+
+
+class StreamInputCapability(BaseModel):
+    framing: Literal["binary"] = "binary"
+    formats: list[str]
+    default_format: str
+    sample_rate_query: str = "sr"
+    end_control: dict[str, str]
+
+
+class StreamOutputCapability(BaseModel):
+    framing: Literal["json"] = "json"
+    events: list[str]
+    final_kinds: list[str]
+
+
+class SpeechFeatureCapabilities(BaseModel):
+    batch_transcription: bool = True
+    streaming_transcription: bool = True
+    partial_transcripts: bool = True
+    utterance_finals: bool = True
+    session_summary: bool = True
+    word_timestamps: bool = True
+    local_refinement: bool = True
+    acoustic_echo_cancellation: bool = True
+    native_dictation_control: bool = False
+
+
+class SpeechAuthCapabilities(BaseModel):
+    loopback: Literal["none"] = "none"
+    remote: Literal["bearer"] = "bearer"
+    header: str = "Authorization: Bearer <OMNIVOICE_API_KEY>"
+    browser_session_endpoint: str = "/api/auth/session"
+    websocket_ticket_endpoint: str = "/api/auth/ws-ticket"
+    websocket_ticket_query_parameter: Literal["ws_ticket"] = "ws_ticket"
+
+
+class SpeechCapabilities(BaseModel):
+    schema_: Literal["voicestudio.speech-capabilities"] = Field(
+        default="voicestudio.speech-capabilities",
+        serialization_alias="schema",
+    )
+    protocol: Literal["voicestudio.speech.v1"] = SPEECH_PROTOCOL
+    protocol_version: Literal["1.0"] = "1.0"
+    service: str = "VoiceStudio"
+    service_version: str = APP_VERSION
+    local_first: bool = True
+    endpoints: dict[str, EndpointCapability]
+    stream_input: StreamInputCapability
+    stream_output: StreamOutputCapability
+    features: SpeechFeatureCapabilities
+    authentication: SpeechAuthCapabilities
+
+
+def speech_capabilities() -> SpeechCapabilities:
+    """Return the stable, side-effect-free integration contract."""
+    endpoints = {
+        "capabilities": EndpointCapability(
+            path="/.well-known/voicestudio-speech",
+            transport="http",
+            method="GET",
+        ),
+        "batch_transcription": EndpointCapability(
+            path="/v1/audio/transcriptions",
+            transport="http",
+            method="POST",
+            protocol="openai.audio.transcriptions",
+        ),
+        "streaming_transcription": EndpointCapability(
+            path=STREAM_PATH,
+            transport="websocket",
+            protocol=SPEECH_PROTOCOL,
+        ),
+        "mcp": EndpointCapability(
+            path="/mcp",
+            transport="mcp-streamable-http",
+            method="POST",
+            protocol="mcp",
+        ),
+        "mcp_stdio": EndpointCapability(
+            path="python -m backend.mcp_shim",
+            transport="mcp-stdio",
+            protocol="mcp",
+        ),
+    }
+    native_control = False
+    try:
+        control_port = int(os.environ.get("VOICESTUDIO_SPEECH_CONTROL_PORT", ""))
+    except (TypeError, ValueError):
+        control_port = 0
+    if 0 < control_port <= 65535:
+        native_control = True
+        endpoints["native_dictation_control"] = EndpointCapability(
+            path=f"http://127.0.0.1:{control_port}/v1/capabilities",
+            transport="http",
+            method="GET",
+            protocol=SPEECH_PROTOCOL,
+        )
+
+    return SpeechCapabilities(
+        endpoints=endpoints,
+        stream_input=StreamInputCapability(
+            formats=[
+                "audio/pcm;encoding=s16le;channels=1",
+                "audio/webm;codecs=opus",
+            ],
+            default_format="audio/webm;codecs=opus",
+            end_control={"type": "input_audio.end"},
+        ),
+        stream_output=StreamOutputCapability(
+            events=["session.started", "status", "partial", "final", "error"],
+            final_kinds=["utterance", "summary"],
+        ),
+        features=SpeechFeatureCapabilities(
+            native_dictation_control=native_control,
+        ),
+        authentication=SpeechAuthCapabilities(),
+    )
+
+
+@router.get(
+    "/.well-known/voicestudio-speech",
+    response_model=SpeechCapabilities,
+    response_model_by_alias=True,
+)
+@router.get(
+    "/v1/audio/capabilities",
+    response_model=SpeechCapabilities,
+    response_model_by_alias=True,
+)
+async def get_speech_capabilities() -> SpeechCapabilities:
+    """Advertise batch, streaming, and agent-facing speech transports."""
+    return speech_capabilities()

backend/api/routers/system.py

@@ -203,8 +203,22 @@ def system_info():
     """
     try:
         _ffmpeg = find_ffmpeg()
+        from services import model_manager as _mm
+        from core import prefs as _prefs_mod
         return {
             "app_version": APP_VERSION,
+            "generate_timeout_s": _mm.GPU_JOB_TIMEOUT_S,
+            "cpu_generate_timeout_s": _mm.CPU_JOB_TIMEOUT_S,
+            # #1787 review fix: a saved prefs.json value for either key can be
+            # silently shadowed by an external env var (os.environ.setdefault
+            # in core.prefs.restore_env is a no-op when one is already
+            # present) — the Settings panel must say so rather than promise a
+            # restart will apply a value that never will.
+            "generate_timeout_shadowed": _prefs_mod.is_env_shadowed(
+                "OMNIVOICE_GENERATE_TIMEOUT_S"),
+            "cpu_generate_timeout_shadowed": _prefs_mod.is_env_shadowed(
+                "OMNIVOICE_CPU_GENERATE_TIMEOUT_S"),
+            "code_fingerprint": os.environ.get("OMNIVOICE_BUILD_FINGERPRINT", ""),
             "data_dir": DATA_DIR,
             "outputs_dir": OUTPUTS_DIR,
             "crash_log_path": CRASH_LOG_PATH,
@@ -240,6 +254,11 @@ def system_info():
         logger.exception("system_info failed — returning safe defaults")
         return {
             "app_version": APP_VERSION,
+            "generate_timeout_s": 300.0,
+            "cpu_generate_timeout_s": 600.0,
+            "generate_timeout_shadowed": False,
+            "cpu_generate_timeout_shadowed": False,
+            "code_fingerprint": os.environ.get("OMNIVOICE_BUILD_FINGERPRINT", ""),
             "data_dir": DATA_DIR,
             "outputs_dir": OUTPUTS_DIR,
             "crash_log_path": str(CRASH_LOG_PATH),
@@ -278,6 +297,142 @@ def _tail_file(path: str, tail: int):
     return all_lines[-tail:], len(all_lines)
 
 
+# Must track main.py's _WindowsSafeRotatingFileHandler(backupCount=3). The
+# handler rolls omnivoice.log at 2 MB into .1/.2/.3, so up to 6 MB of history
+# lives in files this module used to ignore entirely.
+_LOG_BACKUP_COUNT = 3
+
+
+def _rotated_log_paths(base: str) -> list[str]:
+    """Existing `<base>.1 … .N`, newest first."""
+    return [p for p in (f"{base}.{i}" for i in range(1, _LOG_BACKUP_COUNT + 1)) if os.path.exists(p)]
+
+
+def _tail_rolling(base: str, tail: int):
+    """Tail `base`, reaching into its rotated siblings when it runs short.
+
+    A rollover leaves omnivoice.log nearly empty, and the Backend tab then
+    showed a handful of lines — or none — while the failure the user was asked
+    to copy sat in omnivoice.log.1. Reading the current file first keeps the
+    common case at one file read; the backups are only touched when they are
+    the only place the requested lines can come from.
+
+    Returns (lines oldest-first, total lines across the files read, paths read
+    oldest-first). The total counts only the files it had to open — it stops as
+    soon as `tail` is satisfied, so it is "how much is behind these lines",
+    not the size of the whole rotation set.
+    """
+    chunks: list[list[str]] = []
+    paths: list[str] = []
+    total = 0
+    remaining = tail
+    candidates = [p for p in [base, *_rotated_log_paths(base)] if os.path.exists(p)]
+    for path in candidates:
+        if remaining <= 0:
+            break
+        try:
+            lines, count = _tail_file(path, remaining)
+        except FileNotFoundError:
+            # A rollover can rename a candidate between the existence check
+            # above and this open, and the handler holds no lock we can take
+            # from a route. Skip the vanished file rather than 500 the whole
+            # panel over one member of the set — the previous single-file
+            # version failed the request outright in the same situation.
+            #
+            # A roll landing mid-walk can also shift which chunk a file holds,
+            # so a tail taken at that instant may repeat or miss a block. The
+            # panel re-polls every 5s and the next read is clean; buying strict
+            # consistency here would mean reaching into logging's internals.
+            continue
+        except PermissionError as exc:
+            # Windows only, and only the sharing violation: the handler still
+            # holds the file it is rolling. Any other permission failure is a
+            # real misconfiguration and must not be hidden.
+            if os.name == "nt" and getattr(exc, "winerror", None) == 32:
+                continue
+            raise
+        if count == 0:
+            continue
+        chunks.append(lines)
+        paths.append(path)
+        total += count
+        remaining -= len(lines)
+    # Files were visited newest-first; the reader wants oldest-first.
+    out: list[str] = []
+    for chunk in reversed(chunks):
+        out.extend(chunk)
+    return out, total, list(reversed(paths))
+
+def _tauri_plugin_log_candidates():
+    """The `tauri-plugin-log` files — the shell's own log, and the only thing
+    the Tauri tab actually displays.
+
+    Split out from :func:`_tauri_log_candidates` so Clear can touch these and
+    leave the backend stdout/stderr redirect alone. See
+    :func:`clear_tauri_logs`.
+    """
+    home = os.path.expanduser("~")
+    bid = "com.debpalash.omnivoice-studio"
+    if sys.platform == "darwin":
+        return [
+            os.path.join(home, "Library/Logs", bid, "tauri.log"),
+            os.path.join(home, "Library/Logs", bid, "VoiceStudio.log"),
+        ]
+    if sys.platform.startswith("linux"):
+        data_dir = os.environ.get("XDG_DATA_HOME") or os.path.join(home, ".local/share")
+        return [
+            os.path.join(data_dir, bid, "logs", "tauri.log"),
+            os.path.join(home, ".config", bid, "logs", "tauri.log"),
+        ]
+    if sys.platform.startswith("win"):
+        appdata = os.environ.get("APPDATA", home)
+        localappdata = os.environ.get("LOCALAPPDATA") or os.path.join(home, "AppData", "Local")
+        return [
+            os.path.join(localappdata, bid, "logs", "tauri.log"),
+            os.path.join(appdata, bid, "logs", "tauri.log"),
+        ]
+    return []
+
+
+def _backend_redirect_log_candidates():
+    """`backend.log` / `backend_err.log` — the spawned backend's stdout and
+    stderr, written by `src-tauri/src/backend.rs::backend_log_path()`.
+
+    Deliberately NOT cleared by the Tauri tab's Clear button.
+    `open_err_log_for_run()` opens `backend_err.log` **append-only** so "a
+    respawn must not destroy the previous run's evidence" (#1510), rotates it
+    to `.1` rather than truncating, and its spawn diagnostics are described
+    there as "retained in backend_err.log across runs and lands verbatim in bug
+    reports". A native death (a Windows access violation, a SIGSEGV) writes
+    nothing to the Python log by construction, so this file is the only record
+    of it.
+
+    `OMNIVOICE_LOG_DIR` is honoured first, in the same precedence
+    `backend_log_path()` uses. The backend is a child of the shell, so an
+    ambient override reaches both — and a resolver that ignored it would look
+    in the per-OS default while the writer wrote somewhere else, which is the
+    divergence class this file already has one of (see #1782).
+    """
+    override = (os.environ.get("OMNIVOICE_LOG_DIR") or "").strip()
+    if override:
+        return [
+            os.path.join(override, "backend.log"),
+            os.path.join(override, "backend_err.log"),
+        ]
+    home = os.path.expanduser("~")
+    if sys.platform == "darwin":
+        base = os.path.join(home, "Library/Logs/OmniVoice")
+    elif sys.platform.startswith("linux"):
+        state_dir = os.environ.get("XDG_STATE_HOME") or os.path.join(home, ".local/state")
+        base = os.path.join(state_dir, "OmniVoice")
+    elif sys.platform.startswith("win"):
+        localappdata = os.environ.get("LOCALAPPDATA") or os.path.join(home, "AppData", "Local")
+        base = os.path.join(localappdata, "OmniVoice", "Logs")
+    else:
+        return []
+    return [os.path.join(base, "backend.log"), os.path.join(base, "backend_err.log")]
+
+
 def _tauri_log_candidates():
     """Likely paths for Tauri-side logs, most useful first.
 
@@ -289,40 +444,15 @@ def _tauri_log_candidates():
       `com.debpalash.omnivoice-studio` (frontend/src-tauri/tauri.conf.json).
     - backend.rs::backend_log_path() redirects the spawned backend's
       stdout/stderr to `backend.log` / `backend_err.log` under
-      `~/Library/Logs/OmniVoice` (macOS), `$XDG_STATE_HOME/VoiceStudio` falling
+      `~/Library/Logs/OmniVoice` (macOS), `$XDG_STATE_HOME/OmniVoice` falling
       back to `~/.local/state/OmniVoice` (Linux), and
       `%LOCALAPPDATA%\\OmniVoice\\Logs` (Windows). This is where uvicorn
       startup banners and hard-crash tracebacks land — keep all three OS
       shapes listed or sidecar crashes become invisible off-macOS.
     """
-    home = os.path.expanduser("~")
-    bid = "com.debpalash.omnivoice-studio"
-    if sys.platform == "darwin":
-        return [
-            os.path.join(home, "Library/Logs", bid, "tauri.log"),
-            os.path.join(home, "Library/Logs", bid, "VoiceStudio.log"),
-            os.path.join(home, "Library/Logs/OmniVoice/backend.log"),
-            os.path.join(home, "Library/Logs/OmniVoice/backend_err.log"),
-        ]
-    if sys.platform.startswith("linux"):
-        data_dir = os.environ.get("XDG_DATA_HOME") or os.path.join(home, ".local/share")
-        state_dir = os.environ.get("XDG_STATE_HOME") or os.path.join(home, ".local/state")
-        return [
-            os.path.join(data_dir, bid, "logs", "tauri.log"),
-            os.path.join(home, ".config", bid, "logs", "tauri.log"),
-            os.path.join(state_dir, "OmniVoice", "backend.log"),
-            os.path.join(state_dir, "OmniVoice", "backend_err.log"),
-        ]
-    if sys.platform.startswith("win"):
-        appdata = os.environ.get("APPDATA", home)
-        localappdata = os.environ.get("LOCALAPPDATA") or os.path.join(home, "AppData", "Local")
-        return [
-            os.path.join(localappdata, bid, "logs", "tauri.log"),
-            os.path.join(appdata, bid, "logs", "tauri.log"),
-            os.path.join(localappdata, "OmniVoice", "Logs", "backend.log"),
-            os.path.join(localappdata, "OmniVoice", "Logs", "backend_err.log"),
-        ]
-    return []
+    # Composed from the two halves so the read path keeps seeing every file
+    # while Clear can be narrowed to the shell's own log.
+    return _tauri_plugin_log_candidates() + _backend_redirect_log_candidates()
 
 
 @router.get("/system/logs")
@@ -337,12 +467,24 @@ async def system_logs(tail: int = 200):
     except Exception:
         tail = 200
 
-    path = LOG_PATH if os.path.exists(LOG_PATH) else CRASH_LOG_PATH
-    if not os.path.exists(path):
+    if os.path.exists(LOG_PATH) or _rotated_log_paths(LOG_PATH):
+        base = LOG_PATH
+    else:
+        base = CRASH_LOG_PATH
+    if not os.path.exists(base) and not _rotated_log_paths(base):
         return {"lines": [], "path": LOG_PATH, "exists": False}
+    path = base
     try:
-        lines, total = await asyncio.to_thread(_tail_file, path, tail)
-        return {"lines": lines, "path": path, "exists": True, "total_lines": total}
+        lines, total, paths = await asyncio.to_thread(_tail_rolling, base, tail)
+        return {
+            "lines": lines,
+            "path": path,
+            "exists": True,
+            "total_lines": total,
+            # Which files the tail actually came from, oldest first. A bug
+            # report can then say whether it crossed a rollover.
+            "paths": paths,
+        }
     except Exception as e:
         raise HTTPException(
             status_code=500,
@@ -448,9 +590,23 @@ def _read_from_pos(path: str, pos: int) -> list[str]:
 
 @router.post("/system/logs/clear")
 async def clear_system_logs():
-    """Truncate the rolling runtime log and the crash log (what the Backend tab reads)."""
+    """Truncate the rolling runtime log and the crash log (what the Backend tab reads).
+
+    Includes the rotated siblings. Truncating only omnivoice.log left up to
+    6 MB in .1/.2/.3, so Clear freed almost nothing and — now that the tail
+    reaches into those files — would have looked like it did nothing at all.
+    """
     cleared_any = False
-    for p in (LOG_PATH, CRASH_LOG_PATH):
+    # The full fixed name set rather than a snapshot of what exists: enumerating
+    # first leaves a window where a rollover creates a backup after the scan and
+    # its history survives a Clear that reported success. Names the handler can
+    # ever write are known up front, so there is nothing to enumerate.
+    targets = [
+        LOG_PATH,
+        *(f"{LOG_PATH}.{i}" for i in range(1, _LOG_BACKUP_COUNT + 1)),
+        CRASH_LOG_PATH,
+    ]
+    for p in targets:
         if os.path.exists(p):
             try:
                 await asyncio.to_thread(_truncate_file, p)
@@ -483,10 +639,20 @@ def _truncate_file(path: str):
 
 @router.post("/system/logs/tauri/clear")
 async def clear_tauri_logs():
-    """Truncate whichever Tauri-side log files we know about. OS-level rotation may recreate them."""
+    """Truncate the shell's own log files. OS-level rotation may recreate them.
+
+    The backend stdout/stderr redirect is deliberately excluded. This button
+    lives on a tab that shows `tauri.log`, and truncating `backend_err.log`
+    from it destroyed evidence the user was never shown — the one record of a
+    native death, which writes nothing to the Python log. `backend.rs`'s
+    `open_err_log_for_run()` opens that file append-only precisely so "a
+    respawn must not destroy the previous run's evidence" (#1510) and rotates
+    it to `.1` instead of truncating, so it manages its own size and does not
+    need clearing from here.
+    """
     cleared = []
     failed = 0
-    for p in _tauri_log_candidates():
+    for p in _tauri_plugin_log_candidates():
         if os.path.exists(p):
             try:
                 await asyncio.to_thread(_truncate_file, p)
@@ -848,6 +1014,14 @@ PERSISTENT_KEYS = {
     # the Rust sidecar reads OMNIVOICE_PORT at startup and the backend derives
     # the LAN-share/UI ports from the others.
     "OMNIVOICE_PORT", "OMNIVOICE_SHARE_PORT", "OMNIVOICE_UI_PORT",
+    # Per-job compute-time budgets (#1787). Both are captured at import time
+    # by services/model_manager.py (GPU_JOB_TIMEOUT_S / CPU_JOB_TIMEOUT_S), so
+    # a value saved here takes effect on the NEXT backend restart — same
+    # contract as OMNIVOICE_PORT above. Restored into os.environ during the
+    # "env_prefs" startup step (main.py), which runs before model_manager is
+    # first imported ("ml_imports"), so the restored value is what the module
+    # captures. The Settings UI must say so (RestartBadge).
+    "OMNIVOICE_GENERATE_TIMEOUT_S", "OMNIVOICE_CPU_GENERATE_TIMEOUT_S",
 }
 
 # Sidecar-engine install dirs (OMNIVOICE_INDEXTTS_DIR, …). The one-click
@@ -865,6 +1039,16 @@ except Exception:  # pragma: no cover — defensive: env panel > installer wirin
 # being set so a bad value never reaches uvicorn / the share listener.
 _PORT_KEYS = {"OMNIVOICE_PORT", "OMNIVOICE_SHARE_PORT", "OMNIVOICE_UI_PORT"}
 
+# Keys whose value is a wall-clock compute-time budget in seconds (#1787).
+# Validated the same way as _PORT_KEYS: reject anything that isn't a
+# positive number before it reaches services/model_manager.py. Upper bound is
+# generous — long enough that a legitimate multi-hour, audiobook-length CPU
+# render is never blocked — but still bounded, so a fat-fingered extra digit
+# (300 -> 3000000) can't turn a wedged job into one that silently occupies a
+# worker for days before the guard ever fires.
+_TIMEOUT_KEYS = {"OMNIVOICE_GENERATE_TIMEOUT_S", "OMNIVOICE_CPU_GENERATE_TIMEOUT_S"}
+_MAX_GENERATE_TIMEOUT_S = 21600.0  # 6 hours
+
 
 @router.post("/system/set-env")
 async def set_env_var(body: dict):
@@ -873,7 +1057,7 @@ async def set_env_var(body: dict):
     Persistent keys (proxy, FFMPEG_PATH, translation provider keys, …) are
     saved to ``prefs.json`` so they survive backend restarts (restored at
     startup in ``main.py``). HF_TOKEN is persisted via
-    ``huggingface_hub.login()`` (and cleared via ``logout()``). Other keys
+    ``huggingface_hub.login()`` (and cleared with the shared token-file helper). Other keys
     are set on ``os.environ`` for the running process.
 
     The loopback-origin gate that previously lived inline here is now applied
@@ -908,6 +1092,22 @@ async def set_env_var(body: dict):
                     status_code=400,
                     detail=f"Invalid port for {key}: must be between 1024 and 65535.",
                 )
+        if key in _TIMEOUT_KEYS:
+            try:
+                timeout_n = float(value)
+            except (TypeError, ValueError):
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Invalid timeout for {key}: '{value}' is not a number.",
+                )
+            if not (0 < timeout_n <= _MAX_GENERATE_TIMEOUT_S):
+                raise HTTPException(
+                    status_code=400,
+                    detail=(
+                        f"Invalid timeout for {key}: must be greater than 0 "
+                        f"and at most {_MAX_GENERATE_TIMEOUT_S:.0f} seconds."
+                    ),
+                )
         os.environ[key] = value
         logger.info("Environment variable set (length=%d)", len(value))
 
@@ -932,14 +1132,14 @@ async def set_env_var(body: dict):
         # Mirror the persistence on clear — wipe the saved token file too.
         if key == "HF_TOKEN":
             try:
-                from huggingface_hub import logout as _hf_logout
-                _hf_logout()
-                logger.info("HF token cleared from $HF_HOME/token via logout()")
-            except Exception as e:
-                logger.warning("Could not clear HF token file: %s", e)
+                from services.token_resolver import clear_hf_cli_tokens
+                clear_hf_cli_tokens()
+                logger.info("Local Hugging Face token files cleared")
+            except Exception:
+                raise HTTPException(status_code=500, detail="Could not clear local Hugging Face token files") from None
 
     # HF_TOKEN persistence is handled above via huggingface_hub.login()/
-    # logout() — it never touches prefs.json. Everything else in
+    # clear_hf_cli_tokens() — it never touches prefs.json. Everything else in
     # PERSISTENT_KEYS (proxy, FFMPEG_PATH, translation provider keys, …) is
     # saved to prefs.json so it survives backend restarts (restored at
     # startup in main.py). Non-persistent keys stay process-local.
@@ -950,7 +1150,13 @@ async def set_env_var(body: dict):
         else:
             prefs_delete(prefs_key)
 
-    return {"key": key, "set": bool(value)}
+    # #1787 review fix: tell the caller up front when the value just saved is
+    # being shadowed by an external env var — set at THIS process's startup,
+    # before our own prefs restore ran, so it predicts the next restart too.
+    # A response that just said {"set": True} let the Settings panel promise
+    # a restart would apply a value that never will.
+    from core.prefs import is_env_shadowed
+    return {"key": key, "set": bool(value), "shadowed": is_env_shadowed(key)}
 
 
 @router.post("/clean-audio")
@@ -1041,7 +1247,7 @@ def asr_backends():
 def hf_token_state():
     """Return the 3-source HF token cascade state for the Settings UI
     (Wave 2 React panel consumes this). Never returns the raw token —
-    only a masked preview, whoami username, and per-source validity.
+    only a masked preview and local presence; no outbound validation.
     """
     from dataclasses import asdict
     from services import token_resolver

backend/api/routers/tts_stream.py

@@ -10,7 +10,8 @@ as they're generated. This unlocks:
 Protocol:
     → Client sends JSON: {"text": "...", "voice": "profile_id", ...}
     ← Server sends binary audio chunks (PCM16 @ 24kHz mono) as generated
-    ← Server sends JSON: {"type": "done", "duration_s": 4.2, "gen_time_s": 1.1}
+    ← Server sends JSON: {"type": "done", "duration_s": 4.2,
+      "gen_time_s": 1.1, "ttfa_ms": 180.0, "rtf": 0.262}
     ← Server sends JSON: {"type": "error", "detail": "..."}
 
 The chunked delivery targets <100ms time-to-first-audio (TTFA) on warm models.
@@ -33,6 +34,30 @@ logger = logging.getLogger("omnivoice.tts_stream")
 # Smaller chunks = lower latency but more WebSocket overhead.
 CHUNK_SAMPLES = int(os.environ.get("OMNIVOICE_STREAM_CHUNK", "4800"))
 
+# Module seam for deterministic latency-contract tests.  Keep every timing
+# sample on the same monotonic clock.
+_perf_counter = time.perf_counter
+
+
+async def _resolve_stream_backend(engine_id: str | None):
+    """Resolve the live-stream engine without bypassing host isolation."""
+    from services.tts_backend import (
+        OmniVoiceBackend,
+        active_backend_id,
+        get_active_tts_backend,
+        get_backend_class,
+    )
+
+    if engine_id:
+        return get_backend_class(engine_id)()
+
+    cls = get_backend_class(active_backend_id())
+    if cls is OmniVoiceBackend:
+        from services.model_manager import get_model
+
+        return get_active_tts_backend(model=await get_model())
+    return get_active_tts_backend()
+
 
 class StreamTTSRequest(BaseModel):
     """Client request for streaming TTS."""
@@ -85,7 +110,7 @@ async def ws_tts(websocket: WebSocket):
                 })
                 continue
 
-            t0 = time.perf_counter()
+            t0 = _perf_counter()
             text = data["text"]
 
             # Remote GPU: this socket stays on this machine, and says so.
@@ -127,10 +152,6 @@ async def ws_tts(websocket: WebSocket):
 
             try:
                 # Resolve engine
-                from services.tts_backend import (
-                    get_active_tts_backend,
-                    get_backend_class,
-                )
                 engine_id = data.get("engine")
                 # #1224: leave a breadcrumb when memory is already tight before
                 # a heavy load. /generate has done this since the 16 GB-Mac
@@ -146,24 +167,21 @@ async def ws_tts(websocket: WebSocket):
                     log_if_low(f"TTS stream load ({engine_id or 'active engine'})")
                 except Exception:
                     pass
-                if engine_id:
-                    cls = get_backend_class(engine_id)
-                    backend = cls()
-                else:
-                    from services.model_manager import get_model
-                    model = await get_model()
-                    backend = get_active_tts_backend(model=model)
+                backend = await _resolve_stream_backend(engine_id)
 
                 # ── Routing gate (#21 — no silent CPU fallback). WebSockets have
                 # no response headers, so this uses frames: an error frame +
                 # close on `unavailable`, a one-time `routing` frame on
                 # cpu_fallback / accelerated-with-caveat (before any audio).
                 from core.device_caps import detect_host_caps
-                from services.engine_routing import resolve_routing, routing_notice
+                from services.engine_routing import (
+                    routing_notice,
+                    runtime_compute_profile_async,
+                )
                 from core.scrub import scrub_text
-                _routing = resolve_routing(
-                    getattr(backend, "gpu_compat", ("cpu",)), detect_host_caps(),
-                    getattr(backend, "min_vram_gb", 0.0))
+                _routing = await runtime_compute_profile_async(
+                    backend, detect_host_caps()
+                )
                 if _routing["routing_status"] == "unavailable":
                     await websocket.send_json({
                         "type": "error",
@@ -258,6 +276,11 @@ async def ws_tts(websocket: WebSocket):
                 from services.model_manager import run_on_gpu_pool_guarded
 
                 def _generate(sentence_text):
+                    # Timed INSIDE the pool worker: the guarded dispatch below
+                    # can queue behind other jobs, and queue wait is not
+                    # synthesis (review on #1620) — under contention it would
+                    # inflate rtf without the engine slowing at all.
+                    _synth_t0 = _perf_counter()
                     from services.audio_dsp import apply_mastering, normalize_audio
                     from services.watermark import mark_synthetic
                     wav = backend.generate(sentence_text, **kw)
@@ -279,12 +302,19 @@ async def ws_tts(websocket: WebSocket):
                     # watermark._iter_chunks), which is inherent to marking
                     # ultra-short clips, not a coverage gap.
                     wav = mark_synthetic(wav, sr_actual, context="tts_stream.sentence")
-                    return wav, sr_actual
+                    return wav, sr_actual, _perf_counter() - _synth_t0
 
                 import torch
                 total_samples = 0
                 sr = backend.sample_rate
                 started = False
+                first_audio_at: float | None = None
+                # Synthesis time only. The wall clock below also carries socket
+                # delivery and the per-chunk event-loop yields, so deriving RTF
+                # from it reports "how slow was the client" as if it were engine
+                # throughput — on a slow consumer that inflates RTF without the
+                # engine having changed at all.
+                synth_time = 0.0
 
                 for sentence in sentences:
                     # Bounded + pool-reset on hang so a wedged generate can't
@@ -294,11 +324,12 @@ async def ws_tts(websocket: WebSocket):
                     # Length-scaled budget per sentence (#1190) — the flat 300s
                     # default is gone from every dispatch.
                     from services.model_manager import generate_timeout_s
-                    wav_tensor, sr = await run_on_gpu_pool_guarded(
+                    wav_tensor, sr, sentence_synth_s = await run_on_gpu_pool_guarded(
                         functools.partial(_generate, sentence),
                         what="TTS generate",
-                        timeout=generate_timeout_s(sentence),
+                        timeout=generate_timeout_s(sentence, engine=backend),
                     )
+                    synth_time += sentence_synth_s
 
                     if not started:
                         # Send metadata after the first generation so
@@ -325,25 +356,49 @@ async def ws_tts(websocket: WebSocket):
                         end = min(sent_samples + CHUNK_SAMPLES, n_samples)
                         chunk = pcm_bytes[sent_samples * 2: end * 2]
                         await websocket.send_bytes(chunk)
+                        if first_audio_at is None:
+                            # TTFA ends when the first audio bytes have been
+                            # handed to the socket.  The previous log used the
+                            # whole-render duration and called it TTFA.
+                            first_audio_at = _perf_counter()
                         sent_samples = end
                         # Yield to event loop between chunks for responsiveness
                         await asyncio.sleep(0)
                     total_samples += n_samples
 
-                gen_time = round(time.perf_counter() - t0, 3)
+                finished_at = _perf_counter()
+                wall_time_raw = max(0.0, finished_at - t0)
+                synth_time_raw = max(0.0, synth_time)
+                gen_time = round(wall_time_raw, 3)
                 duration = round(total_samples / sr, 3)
+                ttfa_ms = (
+                    round(max(0.0, first_audio_at - t0) * 1000.0, 1)
+                    if first_audio_at is not None
+                    else None
+                )
+                # RTF is a render metric: synthesis seconds per audio second.
+                rtf = (
+                    round(synth_time_raw / (total_samples / sr), 3)
+                    if total_samples > 0
+                    else None
+                )
 
                 await websocket.send_json({
                     "type": "done",
                     "duration_s": duration,
                     "gen_time_s": gen_time,
+                    "ttfa_ms": ttfa_ms,
+                    "rtf": rtf,
                     "samples": total_samples,
                     "sample_rate": sr,
                     "engine": backend.id,
                 })
                 logger.info(
-                    "TTS stream: %.1fs audio in %.1fs (TTFA=%.0fms)",
-                    duration, gen_time, gen_time * 1000,
+                    "TTS stream: %.1fs audio in %.1fs (TTFA=%s, RTF=%s)",
+                    duration,
+                    gen_time,
+                    f"{ttfa_ms:.0f}ms" if ttfa_ms is not None else "n/a",
+                    f"{rtf:.3f}" if rtf is not None else "n/a",
                 )
 
             except Exception as e:

backend/api/routers/voice_convert.py

@@ -0,0 +1,394 @@
+"""Speech-to-speech voice changer — Studio's Convert method (POST /convert).
+
+The user drops (or records) a source clip, picks an existing voice profile,
+and gets the same words back in that profile's voice: the active ASR backend
+transcribes the clip (no word timestamps — the text is all we need), the
+active TTS engine re-synthesizes it conditioned on the profile's reference
+audio, and — by default — the take is pitch-preservingly time-stretched
+(ffmpeg atempo, clamped to one well-behaved 0.5–2.0 stage) so it lands near
+the source clip's duration.
+
+Deliberately reuses the /generate choke points instead of re-deriving them:
+
+* profile row → conditioning via ``generation._resolve_profile_conditioning``
+  (lock wins, ``kind`` authoritative, #533 language fill),
+* engine resolution via ``services.tts_backend.resolve_generation_backend``
+  (never a silent OmniVoice fallback; ``require_cloning=True`` refuses
+  clone-less engines with the actionable switch-engine message),
+* synthesis via ``generation._run_backend_inference`` on the guarded GPU
+  pool (#730 bound + reset; busy/timeout → retryable 503),
+* provenance + persistence via ``services.watermark.mark_synthetic_async``
+  and ``generation._finalize_generation`` (watermark → WAV in OUTPUTS_DIR →
+  history row → retention prune), marked AFTER the stretch so the take users
+  keep carries exactly one whole-take mark.
+
+Local-first: no network calls; ASR-model-less installs get the same typed
+409 download CTA as /transcribe; a backend mid-shutdown surfaces the global
+503 ``[shutting_down]`` (ModelLoadInterruptedByShutdown → main.py handler).
+Reachability matches /generate: loopback bind by default, with the shared
+network-share PIN / API-key middleware gating any non-loopback exposure.
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import os
+import tempfile
+import time
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+
+router = APIRouter()
+logger = logging.getLogger("omnivoice.convert")
+
+#: ffmpeg's atempo filter is well-behaved in [0.5, 2.0] per stage. Convert
+#: clamps to ONE stage by design: needing more than 2× either way means the
+#: synthesized speech differs so much from the source that "matching" it
+#: would produce chipmunk/slow-motion artifacts worse than the mismatch.
+ATEMPO_MIN = 0.5
+ATEMPO_MAX = 2.0
+
+#: Within this relative tolerance the durations already match — stretching
+#: would resample the whole take for an inaudible gain.
+_MATCH_TOLERANCE = 0.02
+
+#: Convert clips are short conversational inputs, not long-form media. Stream
+#: them to disk in bounded chunks so a network-share client cannot make the
+#: backend materialize an arbitrarily large multipart upload in memory.
+_MAX_SOURCE_AUDIO_BYTES = 64 * 1024 * 1024
+_UPLOAD_CHUNK_BYTES = 1024 * 1024
+
+
+async def _copy_source_upload(audio: UploadFile, destination) -> int:
+    """Stream ``audio`` into ``destination`` with the Convert upload cap."""
+    total = 0
+    while True:
+        chunk = await audio.read(_UPLOAD_CHUNK_BYTES)
+        if not chunk:
+            return total
+        total += len(chunk)
+        if total > _MAX_SOURCE_AUDIO_BYTES:
+            raise HTTPException(
+                status_code=413,
+                detail="Source audio is too large (maximum 64 MB).",
+            )
+        destination.write(chunk)
+
+
+def _clamped_tempo_ratio(tts_duration_s: float, source_duration_s: float) -> "float | None":
+    """The atempo ratio that fits the take into the source duration, or None.
+
+    ratio > 1 speeds the take up (it came out longer than the source),
+    ratio < 1 slows it down. Clamped to a single atempo stage's [0.5, 2.0];
+    None when either duration is unusable or they already match.
+    """
+    if not source_duration_s or source_duration_s <= 0:
+        return None
+    if not tts_duration_s or tts_duration_s <= 0:
+        return None
+    ratio = tts_duration_s / source_duration_s
+    if abs(ratio - 1.0) <= _MATCH_TOLERANCE:
+        return None
+    return min(ATEMPO_MAX, max(ATEMPO_MIN, ratio))
+
+
+async def _match_source_duration(audio_tensor, sample_rate: int, source_duration_s: float):
+    """Best-effort pitch-preserving stretch of the take toward the source
+    clip's duration. Returns the input unchanged when no stretch is needed
+    or ffmpeg fails — a duration mismatch is better than a failed convert."""
+    n_samples = int(audio_tensor.shape[-1])
+    ratio = _clamped_tempo_ratio(n_samples / sample_rate, source_duration_s)
+    if ratio is None:
+        return audio_tensor
+    target_samples = max(1, int(round(n_samples / ratio)))
+    from services.ffmpeg_utils import _pitch_preserving_stretch
+    try:
+        return await _pitch_preserving_stretch(audio_tensor, target_samples, sample_rate)
+    except Exception as e:  # noqa: BLE001 — stretch is opt-in polish, never fatal
+        logger.warning("duration match skipped — atempo stretch failed: %s", e)
+        return audio_tensor
+
+
+async def _transcribe_source(tmp_path: str, *, source_lease=None) -> dict:
+    """Active-ASR transcription of the uploaded clip (no word timestamps).
+
+    Mirrors POST /transcribe: typed 409 + download CTA before any backend
+    is constructed (never a silent multi-GB auto-download), the guarded GPU
+    pool dispatch (#730), 504 on timeout, and the same 409 when the loader
+    degrades onto an engine with no weights on disk (#1185).
+    """
+    from services.asr_backend import (
+        ASRModelMissingError,
+        ASRTimeoutError,
+        asr_model_missing_detail,
+        asr_model_missing_error,
+        run_transcribe_guarded,
+    )
+
+    missing = await asyncio.to_thread(asr_model_missing_error, purpose="transcribe")
+    if missing is not None:
+        raise HTTPException(
+            status_code=409,
+            detail={**missing, "message": asr_model_missing_detail(missing)},
+        )
+
+    def _run():
+        # `load_*`, not `get_*`: the loader runs ensure_loaded() and degrades
+        # past an engine whose deep import chain is broken (#1185).
+        from services.asr_backend import load_active_asr_backend
+        backend = load_active_asr_backend()
+        return backend.transcribe(tmp_path, word_timestamps=False)
+
+    from services.model_manager import _gpu_pool
+    release = source_lease.acquire() if source_lease is not None else None
+    abandoned = False
+    try:
+        return await run_transcribe_guarded(
+            _gpu_pool,
+            _run,
+            what="Voice convert",
+            on_abandon=release,
+        )
+    except asyncio.CancelledError:
+        # The guard now owns the lease token until the native worker drains.
+        abandoned = True
+        raise
+    except ASRTimeoutError as e:
+        abandoned = True
+        logger.warning("Convert transcription timed out: %s", e)
+        raise HTTPException(status_code=504, detail=str(e))
+    except ASRModelMissingError as e:
+        raise HTTPException(
+            status_code=409,
+            detail={**e.payload, "message": asr_model_missing_detail(e.payload)},
+        )
+    finally:
+        if release is not None and not abandoned:
+            release()
+
+
+@router.post("/convert")
+async def convert_speech(
+    audio: UploadFile = File(...),
+    profile_id: str = Form(...),
+    match_duration: bool = Form(True),
+):
+    """Convert a spoken clip into an existing voice profile's voice.
+
+    Multipart form: ``audio`` (the source clip), ``profile_id`` (an existing
+    voice profile), optional ``match_duration`` (default on — atempo the take
+    toward the source clip's length, clamped to 0.5–2.0×).
+
+    Returns JSON ``{audio_url, text, duration_s, id}`` — the take is saved to
+    OUTPUTS_DIR and served from the ``/audio`` mount like every other take.
+    """
+    from core.db import db_conn
+    from api.routers.generation import _resolve_profile_conditioning, _TempReferenceLease
+
+    # ── Profile first: strict 404, unlike /generate's silent skip — Convert
+    # has no meaning without a target voice.
+    with db_conn() as conn:
+        row = conn.execute(
+            "SELECT * FROM voice_profiles WHERE id=?", (profile_id,)
+        ).fetchone()
+    if not row:
+        raise HTTPException(
+            status_code=404,
+            detail="That voice profile doesn't exist. It may have been deleted from another tab.",
+        )
+    cond = _resolve_profile_conditioning(row)
+
+    # ── Save the upload before loading an engine. Every ASR backend (and
+    # ffprobe) needs a file path; the bounded streaming copy rejects oversized
+    # network-share requests without materializing them in process memory or
+    # starting heavyweight model work.
+    ext = os.path.splitext(audio.filename or "audio.wav")[1] or ".wav"
+    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=ext)
+    source_lease = None
+    try:
+        try:
+            await _copy_source_upload(audio, tmp)
+        finally:
+            tmp.close()
+        source_lease = _TempReferenceLease(tmp.name)
+
+        # ── Engine gate before ASR/TTS work: the shared resolver refuses a
+        # clone-less engine with the actionable switch-engine message (→ 400),
+        # and a backend mid-shutdown raises ModelLoadInterruptedByShutdown out
+        # of the model load → the global 503 [shutting_down] handler.
+        from services.tts_backend import resolve_generation_backend
+        try:
+            backend = await resolve_generation_backend(
+                require_cloning=True, cloning_purpose="voice conversion",
+            )
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+        result = await _transcribe_source(tmp.name, source_lease=source_lease)
+
+        segments = result.get("segments", [])
+        text = result.get("text", "")
+        if not text and segments:
+            text = " ".join(s.get("text", "") for s in segments).strip()
+        # Same final-text hygiene as /transcribe: strip Whisper hallucination
+        # loops, then deterministic polish (leading capital + terminal
+        # punctuation) so the TTS input reads as typed text.
+        from services.refinement import collapse_repetitive_artifacts
+        from services.text_polish import polish_text
+        text = polish_text(collapse_repetitive_artifacts(text))
+        if not text or not text.strip():
+            raise HTTPException(
+                status_code=422,
+                detail=(
+                    "No speech was recognized in the source clip, so there is "
+                    "nothing to convert. Record or drop a clip with clear, "
+                    "audible speech and try again."
+                ),
+            )
+
+        # #308/#1032 parity with /generate: a clone profile saved without a
+        # transcript conditions better when its reference clip is transcribed,
+        # and that transcript is cached onto the row so it happens ONCE, not
+        # per convert. Best-effort exactly like /generate — a timeout/failure
+        # degrades to ref_text=None and the engine's own fallback. The ASR
+        # model is already warm here (the source transcribe above just used it).
+        if cond["ref_audio_path"] and not cond["ref_text"]:
+            from api.routers.generation import (
+                _generate_timeout_s,
+                _persist_profile_ref_text,
+            )
+            from services.asr_backend import transcribe_reference
+            from services.model_manager import run_on_gpu_pool_guarded
+            try:
+                cond["ref_text"] = await run_on_gpu_pool_guarded(
+                    functools.partial(transcribe_reference, cond["ref_audio_path"]),
+                    what="Reference transcribe",
+                    timeout=_generate_timeout_s(""),
+                )
+            except TimeoutError as e:
+                logger.warning(
+                    "reference transcribe hung (%s); using engine ASR fallback", e,
+                )
+                cond["ref_text"] = None
+            if cond["ref_text"] and cond["persist_ref_text"]:
+                _persist_profile_ref_text(profile_id, cond["ref_text"])
+
+        # Source duration for the optional match: the container's own length
+        # (ffprobe), falling back to the last ASR segment end. Best-effort —
+        # None just skips the stretch.
+        source_duration_s = None
+        if match_duration:
+            from services.ffmpeg_utils import probe_duration
+            source_duration_s = await probe_duration(
+                tmp.name, allowed_root=os.path.dirname(tmp.name),
+            )
+            if not source_duration_s and segments:
+                source_duration_s = max((s.get("end", 0) or 0) for s in segments) or None
+
+        # ── Same text choke point as /generate: engine-agnostic normalization
+        # (numbers→words, junk strip) on the fully resolved language.
+        from services.text_normalization import normalize_for_tts
+        language = cond["language"]
+        text = normalize_for_tts(text, language)
+
+        used_seed = cond["seed"]
+        if used_seed is None:
+            import random
+            used_seed = random.randint(0, 2**31 - 1)
+
+        from api.routers.generation import (
+            _finalize_generation,
+            _generate_timeout_s,
+            _run_backend_inference,
+        )
+        from services.model_manager import (
+            GpuJobTimeoutError,
+            GpuPoolBusyError,
+            run_on_gpu_pool_guarded,
+        )
+        from core.device_caps import detect_host_caps
+        from services.engine_routing import runtime_compute_profile_async
+        compute_profile = await runtime_compute_profile_async(
+            backend, detect_host_caps()
+        )
+        if compute_profile["routing_status"] == "unavailable":
+            raise HTTPException(
+                status_code=400,
+                detail=compute_profile["routing_reason"],
+            )
+
+        start_time = time.time()
+        _render = functools.partial(
+            _run_backend_inference,
+            backend, text, language, cond["ref_audio_path"], cond["ref_text"],
+            cond["instruct"],
+            None,        # duration — the model picks; match_duration owns pacing
+            16, 2.0,     # num_step / guidance_scale (the /generate defaults)
+            1.0,         # speed
+            True, True,  # denoise / postprocess_output
+            used_seed,
+        )
+        try:
+            audio_tensor = await run_on_gpu_pool_guarded(
+                _render,
+                what="Voice convert",
+                timeout=_generate_timeout_s(
+                    text,
+                    execution_device=compute_profile["effective_device"],
+                    min_vram_gb=compute_profile["min_vram_gb"],
+                    hardware_family=compute_profile.get("runtime_hardware_family"),
+                    vram_gb=compute_profile.get("runtime_vram_gb"),
+                ),
+                min_vram_gb=compute_profile["min_vram_gb"],
+            )
+        except GpuPoolBusyError as e:
+            raise HTTPException(
+                status_code=503, detail=str(e),
+                headers={"Retry-After": str(e.retry_after),
+                         "X-OmniVoice-Retryable": "true"},
+            ) from e
+        except GpuJobTimeoutError as e:
+            raise HTTPException(
+                status_code=503, detail=str(e),
+                headers={"Retry-After": "30", "X-OmniVoice-Retryable": "true"},
+            ) from e
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+        sample_rate = backend.sample_rate
+
+        if match_duration and source_duration_s:
+            audio_tensor = await _match_source_duration(
+                audio_tensor, sample_rate, source_duration_s,
+            )
+
+        # Provenance mark AFTER the stretch (one whole-take mark on the audio
+        # the user actually keeps), then the shared finalize tail — WAV in
+        # OUTPUTS_DIR, self-healing history row, retention prune, event emit.
+        from services.watermark import mark_synthetic_async
+        audio_tensor = await mark_synthetic_async(
+            audio_tensor, sample_rate, context="convert.finalize",
+        )
+        _, meta = await _finalize_generation(
+            audio_tensor, sample_rate, text=text, history_mode="convert",
+            ref_audio_path=cond["ref_audio_path"], language=language,
+            instruct=cond["instruct"], resolved_profile_id=profile_id,
+            used_seed=used_seed, start_time=start_time,
+            already_marked=True,
+        )
+
+        return {
+            "id": meta["id"],
+            "audio_url": f"/audio/{meta['filename']}",
+            "text": text,
+            "duration_s": meta["duration"],
+            "gen_time_s": meta["gen_time"],
+        }
+    finally:
+        if source_lease is not None:
+            source_lease.finish_request()
+        else:
+            try:
+                os.unlink(tmp.name)
+            except OSError:
+                pass

backend/api/routers/workers.py

@@ -23,13 +23,16 @@ appears and is replaced by the GPU gateway.
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import logging
 
 from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field
 
 from api.dependencies import require_admin
 from worker import registry, routing, service
+from worker.async_utils import drain_task, to_thread_and_defer_cancellation
 
 logger = logging.getLogger("omnivoice.worker")
 
@@ -158,6 +161,19 @@ def agent_status() -> dict:
     return worker_agent.agent.status()
 
 
+@router.get("/agent/readiness", include_in_schema=False, response_model=None)
+def agent_readiness() -> JSONResponse:
+    """Container readiness: 200 only after this process registered as a worker."""
+    from worker import agent as worker_agent  # noqa: PLC0415
+
+    readiness = worker_agent.agent.readiness()
+    return JSONResponse(
+        status_code=200 if readiness["ready"] else 503,
+        content=readiness,
+        headers={} if readiness["ready"] else {"Retry-After": "2"},
+    )
+
+
 def _refuse_when_env_pinned(worker_agent) -> None:
     """OMNIVOICE_WORKER_MODE wins over the setting everywhere else.
 
@@ -176,6 +192,63 @@ def _refuse_when_env_pinned(worker_agent) -> None:
         )
 
 
+async def _finish_cleanup(awaitable):
+    """Run rollback to completion even if its HTTP task was cancelled."""
+    task = asyncio.create_task(awaitable)
+    await drain_task(task)
+    return task.result()
+
+
+async def _set_worker_mode(worker_agent, enabled: bool) -> None:
+    _result, cancelled = await to_thread_and_defer_cancellation(
+        worker_agent.set_worker_mode_enabled, enabled
+    )
+    if cancelled:
+        raise asyncio.CancelledError
+
+
+async def _restore_agent_transaction(
+    worker_agent, previous: dict, *, was_running: bool
+) -> None:
+    """Restore durable enrollment/settings and the exact prior live state."""
+    try:
+        await _finish_cleanup(worker_agent.agent.stop())
+        await _finish_cleanup(worker_agent.restore_enrollment(previous))
+        if was_running and not worker_agent.agent.running:
+            await _finish_cleanup(worker_agent.agent.start())
+        elif not was_running and worker_agent.agent.running:
+            await _finish_cleanup(worker_agent.agent.stop())
+    except worker_agent.EnrollmentRollbackError:
+        raise
+    except BaseException as exc:
+        message = (
+            "The previous worker state could not be restored safely. "
+            "Worker mode remains stopped; fix its enrollment/settings storage, then retry."
+        )
+        with contextlib.suppress(BaseException):
+            await _finish_cleanup(worker_agent.agent.stop())
+        worker_agent.agent.last_error = message
+        raise worker_agent.EnrollmentRollbackError(message) from exc
+
+
+def _raise_agent_transaction_failure(
+    worker_agent, operation: BaseException, rollback: BaseException | None
+) -> None:
+    if isinstance(operation, asyncio.CancelledError):
+        if rollback is not None:
+            logger.error(
+                "Worker rollback failed during request cancellation",
+                exc_info=(type(rollback), rollback, rollback.__traceback__),
+            )
+        raise operation
+    if rollback is not None:
+        raise HTTPException(status_code=409, detail=str(rollback)) from rollback
+    if isinstance(operation, Exception):
+        worker_agent.agent.last_error = str(operation)
+        raise HTTPException(status_code=409, detail=str(operation)) from operation
+    raise operation
+
+
 @router.post("/agent/join")
 async def join_control_plane(request: JoinRequest) -> dict:
     """Redeem a join code and start working for that control plane.
@@ -200,26 +273,37 @@ async def join_control_plane(request: JoinRequest) -> dict:
     # says it joined and never lends anything (CodeRabbit).
     _refuse_when_env_pinned(worker_agent)
     async with worker_agent.agent.lifecycle:
-        # A rejoin replaces a working enrollment. Keep enough to put it back:
-        # pinning the new certificate overwrites the old one on disk, so a
-        # failed rejoin would otherwise leave the machine unable to reconnect
-        # to the control plane it was already serving.
-        previous = worker_agent.snapshot_enrollment()
-        await worker_agent.agent.stop()
         try:
+            previous, cancelled = await to_thread_and_defer_cancellation(
+                worker_agent.snapshot_enrollment
+            )
+        except worker_agent.EnrollmentStateError as exc:
+            worker_agent.agent.last_error = str(exc)
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        if cancelled:
+            raise asyncio.CancelledError
+        was_running = worker_agent.agent.running
+
+        # A rejoin stops a working agent before the replacement is accepted.
+        # Stop, acceptance and the durable setting are one transaction: every
+        # failure, including cancellation, restores both trust and live state.
+        try:
+            await worker_agent.agent.stop()
             await worker_agent.agent.start(token_text=token)
             # Success is the control plane ACCEPTING this worker, not the
             # connection being scheduled — see wait_until_registered.
             await worker_agent.agent.wait_until_registered()
-        except Exception as exc:
-            worker_agent.agent.last_error = str(exc)
-            await worker_agent.agent.stop()
-            await worker_agent.restore_enrollment(previous)
-            raise HTTPException(status_code=409, detail=str(exc)) from exc
+            await _set_worker_mode(worker_agent, True)
+        except BaseException as exc:
+            rollback_exc = None
+            try:
+                await _restore_agent_transaction(
+                    worker_agent, previous, was_running=was_running
+                )
+            except BaseException as rollback_error:
+                rollback_exc = rollback_error
+            _raise_agent_transaction_failure(worker_agent, exc, rollback_exc)
         worker_agent.agent.last_error = ""
-        # Persisted only after the join actually worked: a machine that failed
-        # to enrol must not come back up trying again forever.
-        worker_agent.set_worker_mode_enabled(True)
         return worker_agent.agent.status()
 
 
@@ -235,19 +319,35 @@ async def set_agent_enabled(request: EnableRequest) -> dict:
 
     _refuse_when_env_pinned(worker_agent)
     async with worker_agent.agent.lifecycle:
-        if request.enabled:
-            try:
+        try:
+            previous, cancelled = await to_thread_and_defer_cancellation(
+                worker_agent.snapshot_enrollment
+            )
+        except worker_agent.EnrollmentStateError as exc:
+            worker_agent.agent.last_error = str(exc)
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        if cancelled:
+            raise asyncio.CancelledError
+        was_running = worker_agent.agent.running
+
+        try:
+            if request.enabled:
                 await worker_agent.agent.start()
                 await worker_agent.agent.wait_until_registered()
-            except Exception as exc:
-                worker_agent.agent.last_error = str(exc)
+                await _set_worker_mode(worker_agent, True)
+            else:
                 await worker_agent.agent.stop()
-                raise HTTPException(status_code=409, detail=str(exc)) from exc
-            worker_agent.agent.last_error = ""
-            worker_agent.set_worker_mode_enabled(True)
-        else:
-            await worker_agent.agent.stop()
-            worker_agent.set_worker_mode_enabled(False)
+                await _set_worker_mode(worker_agent, False)
+        except BaseException as exc:
+            rollback_exc = None
+            try:
+                await _restore_agent_transaction(
+                    worker_agent, previous, was_running=was_running
+                )
+            except BaseException as rollback_error:
+                rollback_exc = rollback_error
+            _raise_agent_transaction_failure(worker_agent, exc, rollback_exc)
+        worker_agent.agent.last_error = ""
         return worker_agent.agent.status()
 
 
@@ -263,9 +363,14 @@ def create_enrollment(request: EnrollRequest) -> dict:
             status_code=409,
             detail="Remote workers are turned off. Enable them in Settings → System → Remote workers first.",
         )
-    token = service.control_plane.create_enrollment(
-        endpoint=request.endpoint, label=request.label, ttl_seconds=request.ttl_seconds
-    )
+    try:
+        token = service.control_plane.create_enrollment(
+            endpoint=request.endpoint,
+            label=request.label,
+            ttl_seconds=request.ttl_seconds,
+        )
+    except service.EndpointCertificateError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
     return {
         "token": token.encode(),
         "endpoint": token.endpoint,
@@ -275,23 +380,55 @@ def create_enrollment(request: EnrollRequest) -> dict:
     }
 
 
+def _persist_worker_update(
+    worker_id: str, request: WorkerUpdate
+):
+    """Write policy on a worker thread; live publication stays loop-owned."""
+    return registry.update_policy(
+        worker_id,
+        name=request.name,
+        enabled=request.enabled,
+        priority=request.priority,
+    )
+
+
 @router.patch("/{worker_id}")
-def update_worker(worker_id: str, request: WorkerUpdate) -> dict:
-    worker = registry.get(worker_id)
-    if worker is None:
+async def update_worker(worker_id: str, request: WorkerUpdate) -> dict:
+    pool = service.control_plane.pool if service.control_plane.running else None
+    live = None
+    was_pending = False
+    if pool is not None:
+        # Quiesce dispatch before releasing authority for the SQLite write.
+        # The publication after the await restores the exact prior state, so a
+        # concurrent registration handoff remains quiesced for its own reason.
+        with registry.authority_guard():
+            live = pool.get(worker_id)
+            if live is not None:
+                was_pending = live.registration_pending
+                live.registration_pending = True
+    updated = None
+    cancelled = False
+    try:
+        updated, cancelled = await to_thread_and_defer_cancellation(
+            _persist_worker_update, worker_id, request
+        )
+    finally:
+        if pool is not None:
+            with registry.authority_guard():
+                if updated is not None:
+                    # Pool state, including the cached record the scheduler
+                    # reads, belongs to the app's event loop.
+                    pool.refresh_record(updated)
+                current = pool.get(worker_id)
+                if current is live:
+                    current.registration_pending = was_pending
+    if updated is None:
+        if cancelled:
+            raise asyncio.CancelledError
         raise HTTPException(status_code=404, detail="No such worker.")
-    if request.name is not None:
-        registry.rename(worker_id, request.name)
-    if request.enabled is not None:
-        registry.set_enabled(worker_id, request.enabled)
-    if request.priority is not None:
-        registry.set_priority(worker_id, request.priority)
-    updated = registry.get(worker_id)
-    # Keep the live copy in step, so the scheduler and its logs do not go on
-    # using the name or priority this worker had when it connected.
-    if updated is not None and service.control_plane.running:
-        service.control_plane.pool.refresh_record(updated)
-    return updated.to_dict() if updated else {}
+    if cancelled:
+        raise asyncio.CancelledError
+    return updated.to_dict()
 
 
 @router.post("/{worker_id}/consent")
@@ -305,7 +442,7 @@ def grant_consent(worker_id: str) -> dict:
 
 
 @router.post("/{worker_id}/resume")
-def clear_breaker(worker_id: str) -> dict:
+async def clear_breaker(worker_id: str) -> dict:
     """Clear a paused worker's circuit breakers.
 
     The user fixed the machine and knows it — a breaker with no manual clear is
@@ -320,18 +457,53 @@ def clear_breaker(worker_id: str) -> dict:
 
 
 @router.delete("/{worker_id}")
-def revoke_worker(worker_id: str) -> dict:
+async def revoke_worker(worker_id: str) -> dict:
     """Remove a worker — which means revoke its key, not hide the row.
 
     Its in-flight work is released so it can be retried elsewhere rather than
     waiting out a lease on a machine that will never answer again.
     """
-    if registry.get(worker_id) is None:
+    pool = service.control_plane.pool if service.control_plane.running else None
+    live = None
+    was_pending = False
+    if pool is not None:
+        with registry.authority_guard():
+            live = pool.get(worker_id)
+            if live is not None:
+                was_pending = live.registration_pending
+                live.registration_pending = True
+    try:
+        revoked, cancelled = await to_thread_and_defer_cancellation(
+            registry.revoke, worker_id
+        )
+    except BaseException:
+        if pool is not None:
+            with registry.authority_guard():
+                current = pool.get(worker_id)
+                if current is live:
+                    current.registration_pending = was_pending
+        raise
+    if not revoked:
+        if pool is not None:
+            with registry.authority_guard():
+                current = pool.get(worker_id)
+                if current is live:
+                    current.registration_pending = was_pending
+        if cancelled:
+            raise asyncio.CancelledError
         raise HTTPException(status_code=404, detail="No such worker.")
-    registry.revoke(worker_id)
-    if service.control_plane.running:
-        service.control_plane.scheduler.on_disconnected(worker_id)
-        service.control_plane.pool.breakers.forget_worker(worker_id)
+
+    # The tombstone committed before any egress/session mutation. Everything
+    # below is loop-owned and published under the same scheduler authority read
+    # used by next_assignment(), so no task can bind in the handoff window.
+    with registry.authority_guard():
+        if service.control_plane.running:
+            if service.control_plane.servicer is not None:
+                service.control_plane.servicer.revoke_worker_sessions(worker_id)
+            service.control_plane.scheduler.on_disconnected(worker_id)
+            service.control_plane.pool.breakers.forget_worker(worker_id)
+    if cancelled:
+        raise asyncio.CancelledError
     return {"ok": True, "revoked": worker_id}
 
 
@@ -375,7 +547,9 @@ async def submit_task(request: Request, body: SubmitTaskRequest) -> dict:
 
     scheduler = service.control_plane.scheduler
     try:
-        task = scheduler.submit(
+        submit = getattr(scheduler, "submit_async", None)
+        submit = submit if callable(submit) else scheduler.submit
+        submitted = submit(
             operation=body.operation,
             engine=body.engine,
             model_id=body.model_id,
@@ -384,6 +558,7 @@ async def submit_task(request: Request, body: SubmitTaskRequest) -> dict:
             deadline_seconds=body.deadline_seconds,
             pinned_worker_id=routing.decide().worker_id or None,
         )
+        task = await submitted if asyncio.iscoroutine(submitted) else submitted
     except QueueFull as exc:
         raise HTTPException(status_code=429, detail=str(exc)) from exc
 
@@ -505,8 +680,33 @@ async def set_inbound_enabled(request: InboundEnableRequest) -> dict:
                 "machine. Change that environment setting and restart VoiceStudio."
             ),
         )
+
+    requested_bind = (
+        inbound_service.normalise_bind_host(request.bind)
+        if request.bind
+        else inbound_service.bind_host()
+    )
+    requested_port = request.port or inbound_service.bind_port()
+    if (
+        request.enabled
+        and inbound_service.node.running
+        and (
+            requested_bind != inbound_service.bind_host()
+            or requested_port != inbound_service.node.port
+        )
+    ):
+        # start() is intentionally idempotent while a listener owns its
+        # socket. Persisting a new endpoint here would make the UI report a
+        # narrower/different bind while the original socket stayed live.
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Turn off Accept connections before changing its bind address "
+                "or port."
+            ),
+        )
     if request.bind:
-        inbound_service.set_bind_host(request.bind)
+        inbound_service.set_bind_host(requested_bind)
     if request.port:
         inbound_service.set_bind_port(request.port)
     inbound_service.set_enabled(request.enabled)
@@ -535,6 +735,7 @@ def issue_inbound_key(request: IssueKeyRequest) -> dict:
     is stored, so it cannot be shown again, only replaced.
     """
     from worker.inbound import service as inbound_service  # noqa: PLC0415
+    from worker.inbound.keys import KeyLimitExceeded  # noqa: PLC0415
 
     if not inbound_service.node.running:
         raise HTTPException(
@@ -544,7 +745,10 @@ def issue_inbound_key(request: IssueKeyRequest) -> dict:
                 "Settings → System → Remote workers → Accept connections first."
             ),
         )
-    issued = inbound_service.node.keys.issue(request.label)
+    try:
+        issued = inbound_service.node.keys.issue(request.label)
+    except KeyLimitExceeded as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
     return {
         "key_id": issued.key.key_id,
         "label": issued.key.label,
@@ -555,12 +759,12 @@ def issue_inbound_key(request: IssueKeyRequest) -> dict:
 
 
 @router.delete("/inbound/keys/{key_id}")
-def revoke_inbound_key(key_id: str) -> dict:
+async def revoke_inbound_key(key_id: str) -> dict:
     """Revoke one panel. Everyone else stays connected — the whole reason keys
     are per panel rather than one shared node key."""
     from worker.inbound import service as inbound_service  # noqa: PLC0415
 
-    if not inbound_service.node.keys.revoke(key_id):
+    if not await inbound_service.node.revoke_key(key_id):
         raise HTTPException(status_code=404, detail="No such key.")
     return inbound_service.node.snapshot()
 
@@ -579,6 +783,7 @@ async def add_inbound_connection(request: ConnectRequest) -> dict:
     """Paste a connection string from a GPU machine and dial it."""
     from worker.inbound import service as inbound_service  # noqa: PLC0415
     from worker.inbound.connection_string import InvalidConnectionString  # noqa: PLC0415
+    from worker.inbound.connector import InboundConnectionError  # noqa: PLC0415
 
     if not service.control_plane.running:
         raise HTTPException(
@@ -597,12 +802,18 @@ async def add_inbound_connection(request: ConnectRequest) -> dict:
         # surfaces as "cannot connect", which is what a firewall, a wrong port
         # and a dead node all say too.
         raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except InboundConnectionError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
     return {"endpoint": connection.endpoint, "connections": inbound_service.outbound.snapshot()}
 
 
 @router.delete("/inbound/connections/{endpoint}")
 async def remove_inbound_connection(endpoint: str) -> dict:
     from worker.inbound import service as inbound_service  # noqa: PLC0415
+    from worker.inbound.connector import InboundConnectionError  # noqa: PLC0415
 
-    await inbound_service.outbound.remove(endpoint)
+    try:
+        await inbound_service.outbound.remove(endpoint)
+    except InboundConnectionError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
     return {"connections": inbound_service.outbound.snapshot()}

backend/api/schemas.py

@@ -26,6 +26,21 @@ class SystemInfoResponse(BaseModel):
     model_config = ConfigDict(extra="allow")
 
     app_version: str = ""
+    # Effective compute-time budgets (seconds) for one synthesis job — the
+    # values services/model_manager.py's GPU_JOB_TIMEOUT_S / CPU_JOB_TIMEOUT_S
+    # captured at backend import time (#1787). A value just saved via
+    # /system/set-env is NOT reflected here until the next restart.
+    generate_timeout_s: float = 300.0
+    cpu_generate_timeout_s: float = 600.0
+    # True when an external env var (shell, `.env`, Docker, …) is currently
+    # shadowing a prefs.json save for this key — see core.prefs.is_env_shadowed.
+    generate_timeout_shadowed: bool = False
+    cpu_generate_timeout_shadowed: bool = False
+    # #1770: the desktop attach handshake's code fingerprint — whatever
+    # Tauri set OMNIVOICE_BUILD_FINGERPRINT to when it spawned this process,
+    # echoed back verbatim. Blank when unset (dev mode, a manually started
+    # backend). See frontend/src-tauri/src/backend.rs::code_fingerprint_is_current.
+    code_fingerprint: str = ""
     data_dir: str
     outputs_dir: str
     crash_log_path: str

backend/config/models.yaml

@@ -28,6 +28,9 @@
 #                            their own (weights live in referenced sub-repos). Such
 #                            a cache is legitimately tiny, so the truncated-download
 #                            (weights-missing) detector must NOT flag it incomplete.
+#   allow_patterns (optional) — restrict installation to these repository paths.
+#                               Use for multi-package repos so an explicit install
+#                               never downloads unrelated model variants.
 # ─────────────────────────────────────────────────────────────────────────
 
 models:
@@ -40,6 +43,14 @@ models:
     required: true
     curated_on: [all]
 
+  - repo_id: "audio-cpp/audio.cpp-gguf"
+    label: "Breeze-TTS-2 Q8_0 for audio.cpp (English + Chinese, clone + design)"
+    role: TTS
+    size_gb: 4.73
+    allow_patterns:
+      - "Breeze-TTS-2-GGUF/breeze-tts-2-q8_0.gguf"
+    note: "Optional audio.cpp model. Research/non-commercial weights and self-hosted outputs; install only after reviewing the license."
+
   # ── ASR (optional — curated per platform) ─────────────────────────────
   # No ASR model is required to boot: TTS-only installs work. Dubbing,
   # dictation, and clone-reference transcription prompt for the curated
@@ -159,17 +170,16 @@ models:
   - repo_id: "csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8"
     label: "Parakeet TDT v3 (sherpa-onnx — dictation, 25 EU langs)"
     role: ASR
-    size_gb: 0.18
+    size_gb: 0.67
     engine: sherpa-onnx
     dictation_id: sherpa-parakeet-tdt-v3
     tag: offline
-    curated_on: [all]
-    note: "Recommended live-dictation default. CPU, int8 ONNX. Requires sherpa-onnx."
+    note: "Multilingual European-language dictation. CPU, int8 ONNX. Requires sherpa-onnx."
 
   - repo_id: "csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8"
     label: "Parakeet TDT v2 (sherpa-onnx — dictation, English)"
     role: ASR
-    size_gb: 0.17
+    size_gb: 0.66
     engine: sherpa-onnx
     dictation_id: sherpa-parakeet-tdt-v2
     tag: offline
@@ -178,7 +188,7 @@ models:
   - repo_id: "csukuangfj/sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20"
     label: "Zipformer Bilingual (sherpa-onnx — streaming, zh+en)"
     role: ASR
-    size_gb: 0.13
+    size_gb: 0.2
     engine: sherpa-onnx
     dictation_id: sherpa-zipformer-bilingual-zh-en
     tag: streaming
@@ -187,7 +197,7 @@ models:
   - repo_id: "csukuangfj/sherpa-onnx-streaming-paraformer-bilingual-zh-en"
     label: "Paraformer Bilingual (sherpa-onnx — streaming, zh+en)"
     role: ASR
-    size_gb: 0.115
+    size_gb: 0.24
     engine: sherpa-onnx
     dictation_id: sherpa-paraformer-bilingual-zh-en
     tag: streaming
@@ -196,7 +206,7 @@ models:
   - repo_id: "csukuangfj/sherpa-onnx-streaming-zipformer-en-20M-2023-02-17"
     label: "Zipformer Streaming EN 20M (sherpa-onnx — streaming, English)"
     role: ASR
-    size_gb: 0.128
+    size_gb: 0.044
     engine: sherpa-onnx
     dictation_id: sherpa-zipformer-en-20m
     tag: streaming
@@ -205,7 +215,7 @@ models:
   - repo_id: "csukuangfj/sherpa-onnx-streaming-zipformer-zh-14M-2023-02-23"
     label: "Zipformer Streaming ZH 14M (sherpa-onnx — streaming, Chinese)"
     role: ASR
-    size_gb: 0.074
+    size_gb: 0.025
     engine: sherpa-onnx
     dictation_id: sherpa-zipformer-zh-14m
     tag: streaming
@@ -214,11 +224,12 @@ models:
   - repo_id: "csukuangfj/sherpa-onnx-whisper-tiny"
     label: "Whisper Tiny (sherpa-onnx — dictation, 90+ langs)"
     role: ASR
-    size_gb: 0.116
+    size_gb: 0.104
     engine: sherpa-onnx
     dictation_id: sherpa-whisper-tiny
     tag: offline
-    note: "Multilingual offline dictation (auto-detect). CPU, int8 ONNX. Requires sherpa-onnx."
+    curated_on: [all]
+    note: "Recommended cross-platform dictation default (auto-detect). CPU, int8 ONNX. Requires sherpa-onnx."
 
   # ── Diarisation ───────────────────────────────────────────────────────
 

backend/core/config.py

@@ -15,6 +15,18 @@ def get_app_data_dir():
         return os.path.expanduser("~/.omnivoice")
 
 
+def _configured_hf_token_path():
+    """Match Hub's token location without importing or refreshing credentials."""
+    default_cache = os.path.join(os.path.expanduser("~"), ".cache")
+    hf_home = os.environ.get("HF_HOME", os.path.join(os.environ.get("XDG_CACHE_HOME", default_cache), "huggingface"))
+    return os.path.expandvars(os.path.expanduser(os.environ.get("HF_TOKEN_PATH", os.path.join(hf_home, "token"))))
+
+
+# Snapshot recognized locations before automatic model-cache redirection.
+# Explicit cache/token overrides restrict clearing to their selected location.
+HF_CLI_TOKEN_PATHS = (_configured_hf_token_path(),)
+
+
 def _ensure_short_hf_cache_on_windows():
     """Redirect HuggingFace cache to a short path on Windows.
 
@@ -38,6 +50,14 @@ def _ensure_short_hf_cache_on_windows():
         return
     short_cache = os.path.join(local_app, "OmniVoice", "hf_cache")
     os.makedirs(short_cache, exist_ok=True)
+    if "HF_TOKEN_PATH" not in os.environ:
+        global HF_CLI_TOKEN_PATHS
+        canonical = HF_CLI_TOKEN_PATHS[0]
+        legacy = os.path.join(short_cache, "token")
+        HF_CLI_TOKEN_PATHS = tuple(dict.fromkeys((canonical, legacy)))
+        # Keep existing app-written logins usable without copying credentials.
+        selected = canonical if os.path.exists(canonical) or not os.path.exists(legacy) else legacy
+        os.environ.setdefault("HF_TOKEN_PATH", selected)
     os.environ["HF_HOME"] = short_cache
     os.environ["HF_HUB_CACHE"] = short_cache
 

backend/core/contained_subprocess.py

@@ -0,0 +1,716 @@
+"""Nested subprocess ownership for desktop-managed backend operations.
+
+The desktop owns the backend with an OS process group/Job.  Engine and
+installer operations also need an independently terminable subtree: killing
+only their direct child on a timeout leaves uv/git/model workers holding pipes
+and mutating files.
+
+On POSIX a small supervisor is the unreaped leader of a nested process group.
+A control-pipe EOF (including kernel EOF when the backend dies) kills that
+group; the parent also drains the group before reaping its stable leader. On
+Windows the backend retains a nested kill-on-close Job directly and assigns
+the suspended operation before resuming it. The outer desktop Job remains the
+terminal fallback.
+
+Standalone/server launches use the same nested owner, preserving their
+independently terminable subtree without relying on ``taskkill`` or discovery.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import struct
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+
+_RESULT = struct.Struct("!i")
+_DESKTOP_MARKER = "OMNIVOICE_DESKTOP_CONTAINED"
+_DRAIN_FD_ENV = "OMNIVOICE_DESKTOP_DRAIN_FD"
+
+
+def backend_drain_fd(*, required: bool = False) -> Optional[int]:
+    """Validated Rust-owned drain writer inherited by the desktop backend."""
+    if os.name != "posix" or os.environ.get(_DESKTOP_MARKER) != "1":
+        return None
+    try:
+        fd = int(os.environ[_DRAIN_FD_ENV])
+        os.fstat(fd)
+    except (KeyError, ValueError, OSError) as exc:
+        if required:
+            raise RuntimeError(
+                "desktop backend is missing its live nested-operation drain descriptor"
+            ) from exc
+        return None
+    return fd
+
+
+def secure_backend_drain_fd() -> None:
+    """Restore CLOEXEC after Rust's one intentional backend inheritance."""
+    fd = backend_drain_fd(required=True)
+    if fd is not None:
+        os.set_inheritable(fd, False)
+
+
+class OwnedPopen:
+    """Popen-compatible handle for a desktop-owned nested operation."""
+
+    def __init__(
+        self,
+        proc: subprocess.Popen,
+        control_fd: int,
+        result_fd: int,
+    ) -> None:
+        self._proc = proc
+        self._control_fd: Optional[int] = control_fd
+        self._result_fd: Optional[int] = result_fd
+        self._returncode: Optional[int] = None
+        self._lock = threading.RLock()
+
+        # Popen callers use these directly (protocol pipes and log drains).
+        self.stdin = proc.stdin
+        self.stdout = proc.stdout
+        self.stderr = proc.stderr
+
+    @property
+    def pid(self) -> int:
+        return self._proc.pid
+
+    @property
+    def args(self) -> Any:
+        return self._proc.args
+
+    @property
+    def returncode(self) -> Optional[int]:
+        return self._returncode
+
+    def _close_control(self) -> None:
+        fd, self._control_fd = self._control_fd, None
+        if fd is not None:
+            try:
+                os.close(fd)
+            except OSError:
+                # Cleanup is idempotent; another teardown path already closed it.
+                pass
+
+    def _read_result(self, fallback: int) -> int:
+        fd, self._result_fd = self._result_fd, None
+        if fd is None:
+            return fallback
+        try:
+            payload = b""
+            while len(payload) < _RESULT.size:
+                chunk = os.read(fd, _RESULT.size - len(payload))
+                if not chunk:
+                    break
+                payload += chunk
+            return _RESULT.unpack(payload)[0] if len(payload) == _RESULT.size else fallback
+        except OSError:
+            return fallback
+        finally:
+            try:
+                os.close(fd)
+            except OSError:
+                # The descriptor may have been closed by cancellation cleanup.
+                pass
+
+    def _posix_exited_unreaped(self) -> bool:
+        flags = os.WEXITED | os.WNOHANG | os.WNOWAIT
+        info = os.waitid(os.P_PID, self.pid, flags)
+        return info is not None and info.si_pid != 0
+
+    def _posix_exited_reaping(self) -> Optional[int]:
+        """macOS fallback for :meth:`_posix_exited_unreaped` (#1656).
+
+        CPython on macOS does not expose ``os.waitid`` (HAVE_WAITID is not set
+        in its build), so the WNOWAIT probe is unavailable there. This
+        fallback *reaps* the wrapper with ``waitpid(WNOHANG)``: it returns
+        the wrapper's exit code once it has exited, None while it is still
+        running, and raises ``ChildProcessError`` when another owner already
+        reaped it (the same refusal the waitid probe gives).
+
+        Reaping earlier than the WNOWAIT dance loses the pre-reap group kill
+        in :meth:`poll`; that is safe because the supervisor's control-pipe
+        EOF already terminates the whole nested group (#1635 design).
+        """
+        pid, status = os.waitpid(self.pid, os.WNOHANG)
+        if pid != self.pid:
+            return None
+        rc = os.waitstatus_to_exitcode(status)
+        # Publish on the underlying Popen so its own wait()/poll() no-op.
+        self._proc.returncode = rc
+        return rc
+
+    def _posix_exit_state_reaping(self) -> Optional[int]:
+        """:meth:`_posix_exited_reaping` plus one concession: if the leader
+        was already reaped through *this* Popen (``_proc.returncode`` known),
+        report that code rather than refusing — reaping by our own handle is
+        not the foreign reaper the ECHILD refusal exists for."""
+        try:
+            return self._posix_exited_reaping()
+        except ChildProcessError:
+            return self._proc.returncode
+
+    def _signal_owned_group(self, sig: int) -> None:
+        # The numeric group is safe only while its direct-child leader remains
+        # ours and unreaped.  ECHILD therefore refuses rather than guessing.
+        try:
+            os.waitid(os.P_PID, self.pid, os.WEXITED | os.WNOHANG | os.WNOWAIT)
+        except ChildProcessError:
+            return
+        except AttributeError:
+            # macOS CPython has no os.waitid (#1656). waitpid still proves
+            # that this exact numeric pid is our live child: ECHILD refuses a
+            # foreign-reaped/reused pid, while pid == self.pid records an exit
+            # without ever signalling the now-unowned process-group number.
+            try:
+                pid, status = os.waitpid(self.pid, os.WNOHANG)
+            except ChildProcessError:
+                return
+            if pid == self.pid:
+                self._proc.returncode = os.waitstatus_to_exitcode(status)
+                return
+        try:
+            os.killpg(self.pid, sig)
+        except ProcessLookupError:
+            # The owned group exited between the waitid probe and the signal.
+            pass
+
+    def poll(self) -> Optional[int]:
+        with self._lock:
+            if self._returncode is not None:
+                return self._returncode
+            if os.name == "posix":
+                try:
+                    if hasattr(os, "waitid"):
+                        if not self._posix_exited_unreaped():
+                            return None
+                        self._signal_owned_group(signal.SIGKILL)
+                        wrapper_rc = self._proc.wait()
+                    else:
+                        # macOS CPython: no os.waitid (#1656) — the reaping
+                        # probe already terminated/killed nothing; the group
+                        # is torn down by the control-pipe EOF in _close_control.
+                        wrapper_rc = self._posix_exit_state_reaping()
+                        if wrapper_rc is None:
+                            return None
+                except ChildProcessError:
+                    # Never signal a potentially reused group after another
+                    # owner reaped the stable leader.
+                    return None
+            else:
+                wrapper_rc = self._proc.poll()
+                if wrapper_rc is None:
+                    return None
+            self._close_control()
+            self._returncode = self._read_result(wrapper_rc)
+            return self._returncode
+
+    def wait(self, timeout: Optional[float] = None) -> int:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            rc = self.poll()
+            if rc is not None:
+                return rc
+            if deadline is not None and time.monotonic() >= deadline:
+                raise subprocess.TimeoutExpired(self.args, timeout)
+            time.sleep(0.01)
+
+    def terminate(self) -> None:
+        with self._lock:
+            if self._returncode is not None:
+                return
+            self._close_control()
+            if os.name == "posix":
+                self._signal_owned_group(signal.SIGTERM)
+            else:
+                # Closing the control pipe asks the supervisor to terminate
+                # its nested Job.  The stable wrapper handle is a fallback.
+                try:
+                    self._proc.terminate()
+                except OSError:
+                    # The wrapper exited after the return-code check.
+                    pass
+
+    def kill(self) -> None:
+        with self._lock:
+            if self._returncode is not None:
+                return
+            self._close_control()
+            if os.name == "posix":
+                self._signal_owned_group(signal.SIGKILL)
+            else:
+                try:
+                    self._proc.kill()
+                except OSError:
+                    # The wrapper exited after the return-code check.
+                    pass
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._proc, name)
+
+    def __del__(self) -> None:
+        self._close_control()
+        fd, self._result_fd = self._result_fd, None
+        if fd is not None:
+            try:
+                os.close(fd)
+            except OSError:
+                # Finalization may race explicit wait or cancellation cleanup.
+                pass
+
+
+class WindowsJobPopen:
+    """Popen-compatible handle whose child tree lives in a retained Job.
+
+    Windows Job handles already provide the stable ownership that POSIX needs
+    a supervisor process group for. Keeping the handle in the backend means an
+    abrupt backend exit closes it in the kernel and kills the whole operation
+    tree, without inserting a second Python process in the sidecar loader path
+    (#1734).
+    """
+
+    def __init__(self, proc: subprocess.Popen, job: Any, kernel32: Any) -> None:
+        self._proc = proc
+        self._job = job
+        self._kernel32 = kernel32
+        self._lock = threading.RLock()
+        self.stdin = proc.stdin
+        self.stdout = proc.stdout
+        self.stderr = proc.stderr
+
+    @property
+    def pid(self) -> int:
+        return self._proc.pid
+
+    @property
+    def args(self) -> Any:
+        return self._proc.args
+
+    @property
+    def returncode(self) -> Optional[int]:
+        return self._proc.returncode
+
+    def _close_job(self, *, terminate: bool) -> None:
+        job, self._job = self._job, None
+        if job is None:
+            return
+        try:
+            if terminate:
+                self._kernel32.TerminateJobObject(job, 1)
+        finally:
+            self._kernel32.CloseHandle(job)
+
+    def poll(self) -> Optional[int]:
+        with self._lock:
+            rc = self._proc.poll()
+            if rc is None:
+                return None
+            # A successful direct child may leave helpers behind. Match the
+            # supervisor contract by draining the retained Job before return.
+            self._close_job(terminate=True)
+            return rc
+
+    def wait(self, timeout: Optional[float] = None) -> int:
+        try:
+            rc = self._proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            raise
+        with self._lock:
+            self._close_job(terminate=True)
+        return rc
+
+    def terminate(self) -> None:
+        with self._lock:
+            self._close_job(terminate=True)
+
+    def kill(self) -> None:
+        self.terminate()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._proc, name)
+
+    def __del__(self) -> None:
+        try:
+            self._close_job(terminate=True)
+        except Exception:
+            pass  # interpreter shutdown; closing the OS handle is best-effort
+
+
+def _spawn_windows_owned(argv: list[str], kwargs: dict[str, Any]) -> WindowsJobPopen:
+    """Start *argv* suspended, assign its tree to a Job, then resume it."""
+    import ctypes
+
+    job, kernel32, wintypes = _windows_job()
+    child: Optional[subprocess.Popen] = None
+    popen_kwargs = dict(kwargs)
+    supplied_env = popen_kwargs.get("env")
+    operation_env = dict(os.environ if supplied_env is None else supplied_env)
+    operation_env.pop(_DRAIN_FD_ENV, None)
+    operation_env.pop(_DESKTOP_MARKER, None)
+    popen_kwargs["env"] = operation_env
+    supplied_flags = int(popen_kwargs.pop("creationflags", 0))
+    popen_kwargs["creationflags"] = supplied_flags | 0x08000000 | 0x00000004
+    try:
+        child = subprocess.Popen(argv, **popen_kwargs)
+        assign = kernel32.AssignProcessToJobObject
+        assign.argtypes = (wintypes.HANDLE, wintypes.HANDLE)
+        assign.restype = wintypes.BOOL
+        if not assign(job, wintypes.HANDLE(child._handle)):
+            raise OSError(ctypes.get_last_error(), "AssignProcessToJobObject")
+        _resume_windows_process(kernel32, wintypes, child.pid)
+        return WindowsJobPopen(child, job, kernel32)
+    except BaseException:
+        kernel32.TerminateJobObject(job, 1)
+        if child is not None:
+            try:
+                child.kill()
+            except OSError:
+                pass  # the suspended child may already have exited
+            try:
+                child.wait(timeout=5)
+            except (OSError, subprocess.TimeoutExpired):
+                pass  # Job termination remains the authoritative cleanup
+        kernel32.CloseHandle(job)
+        raise
+
+
+def spawn_owned(
+    argv: list[str], **kwargs: Any
+) -> "subprocess.Popen | OwnedPopen | WindowsJobPopen":
+    """Spawn an operation with a stable, independently terminable owner."""
+
+    if os.name == "nt":
+        return _spawn_windows_owned(argv, kwargs)
+
+    drain_fd = backend_drain_fd(required=True)
+    control_read, control_write = os.pipe()
+    result_read, result_write = os.pipe()
+    wrapper_argv = _supervisor_argv(
+        control_read,
+        result_write,
+        argv,
+    )
+    wrapper_kwargs = dict(kwargs)
+    wrapper_kwargs["start_new_session"] = True
+    pass_fds = [control_read, result_write]
+    if drain_fd is not None:
+        pass_fds.append(drain_fd)
+        if wrapper_kwargs.get("env") is not None:
+            wrapper_env = dict(wrapper_kwargs["env"])
+            wrapper_env[_DESKTOP_MARKER] = "1"
+            wrapper_env[_DRAIN_FD_ENV] = str(drain_fd)
+            wrapper_kwargs["env"] = wrapper_env
+    wrapper_kwargs["pass_fds"] = tuple(pass_fds)
+    try:
+        proc = subprocess.Popen(wrapper_argv, **wrapper_kwargs)
+    except BaseException:
+        # The finally block exclusively owns the child-side endpoints. Closing
+        # them here as well risks closing a reused descriptor in another thread.
+        for fd in (control_write, result_read):
+            try:
+                os.close(fd)
+            except OSError:
+                # A partial spawn may already have closed a parent-side endpoint.
+                pass
+        raise
+    finally:
+        for fd in (control_read, result_write):
+            try:
+                os.close(fd)
+            except OSError:
+                # Popen may have consumed an inherited child-side endpoint.
+                pass
+    return OwnedPopen(proc, control_write, result_read)
+
+
+def _supervisor_argv(
+    control_token: int,
+    result_token: int,
+    argv: list[str],
+) -> list[str]:
+    prefix = [sys.executable]
+    if not getattr(sys, "frozen", False):
+        prefix.append(str(Path(__file__).resolve().parents[1] / "main.py"))
+    return [
+        *prefix,
+        "--supervise",
+        str(control_token),
+        str(result_token),
+        "--",
+        *map(str, argv),
+    ]
+
+
+def _write_result(fd: int, returncode: int) -> None:
+    try:
+        os.write(fd, _RESULT.pack(int(returncode)))
+    except OSError:
+        # The caller may have cancelled and closed its result reader.
+        pass
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            # Writing or cancellation may already have closed the descriptor.
+            pass
+
+
+def _operation_env() -> dict[str, str]:
+    env = os.environ.copy()
+    # The operation intentionally does not own the Rust drain writer. Avoid
+    # exposing a stale numeric token which nested code could mistake as valid.
+    env.pop(_DRAIN_FD_ENV, None)
+    env.pop(_DESKTOP_MARKER, None)
+    return env
+
+
+def _supervise_posix(control_fd: int, result_fd: int, argv: list[str]) -> int:
+    def cancel_on_eof() -> None:
+        try:
+            while os.read(control_fd, 1):
+                pass
+        except OSError:
+            # Closing the control descriptor is itself a cancellation signal.
+            pass
+        os.killpg(os.getpgrp(), signal.SIGKILL)
+
+    threading.Thread(target=cancel_on_eof, daemon=True).start()
+    try:
+        child = subprocess.Popen(argv, close_fds=True, env=_operation_env())
+        rc = child.wait()
+    except OSError:
+        rc = 127
+    _write_result(result_fd, rc)
+    # Drain children which outlived the operation before the stable group
+    # leader exits.  SIGKILL intentionally includes this supervisor.
+    os.killpg(os.getpgrp(), signal.SIGKILL)
+    return rc  # unreachable
+
+
+def _windows_job() -> tuple[Any, Any, Any]:
+    import ctypes
+    import ctypes.wintypes as wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.CloseHandle.argtypes = (wintypes.HANDLE,)
+    kernel32.CloseHandle.restype = wintypes.BOOL
+    kernel32.TerminateJobObject.argtypes = (wintypes.HANDLE, wintypes.UINT)
+    kernel32.TerminateJobObject.restype = wintypes.BOOL
+    kernel32.ReadFile.argtypes = (
+        wintypes.HANDLE,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+    )
+    kernel32.ReadFile.restype = wintypes.BOOL
+    kernel32.WriteFile.argtypes = (
+        wintypes.HANDLE,
+        ctypes.c_void_p,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.c_void_p,
+    )
+    kernel32.WriteFile.restype = wintypes.BOOL
+    create = kernel32.CreateJobObjectW
+    create.argtypes = (ctypes.c_void_p, wintypes.LPCWSTR)
+    create.restype = wintypes.HANDLE
+    job = create(None, None)
+    if not job:
+        raise OSError(ctypes.get_last_error(), "CreateJobObjectW")
+
+    class BasicLimits(ctypes.Structure):
+        _fields_ = [
+            ("PerProcessUserTimeLimit", ctypes.c_longlong),
+            ("PerJobUserTimeLimit", ctypes.c_longlong),
+            ("LimitFlags", wintypes.DWORD),
+            ("MinimumWorkingSetSize", ctypes.c_size_t),
+            ("MaximumWorkingSetSize", ctypes.c_size_t),
+            ("ActiveProcessLimit", wintypes.DWORD),
+            ("Affinity", ctypes.c_size_t),
+            ("PriorityClass", wintypes.DWORD),
+            ("SchedulingClass", wintypes.DWORD),
+        ]
+
+    class IoCounters(ctypes.Structure):
+        _fields_ = [(name, ctypes.c_ulonglong) for name in (
+            "ReadOperationCount", "WriteOperationCount", "OtherOperationCount",
+            "ReadTransferCount", "WriteTransferCount", "OtherTransferCount",
+        )]
+
+    class ExtendedLimits(ctypes.Structure):
+        _fields_ = [
+            ("BasicLimitInformation", BasicLimits),
+            ("IoInfo", IoCounters),
+            ("ProcessMemoryLimit", ctypes.c_size_t),
+            ("JobMemoryLimit", ctypes.c_size_t),
+            ("PeakProcessMemoryUsed", ctypes.c_size_t),
+            ("PeakJobMemoryUsed", ctypes.c_size_t),
+        ]
+
+    info = ExtendedLimits()
+    info.BasicLimitInformation.LimitFlags = 0x00002000  # KILL_ON_JOB_CLOSE
+    set_info = kernel32.SetInformationJobObject
+    set_info.argtypes = (wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD)
+    set_info.restype = wintypes.BOOL
+    if not set_info(job, 9, ctypes.byref(info), ctypes.sizeof(info)):
+        error = ctypes.get_last_error()
+        kernel32.CloseHandle(job)
+        raise OSError(error, "SetInformationJobObject")
+    return job, kernel32, wintypes
+
+
+def _resume_windows_process(kernel32: Any, wintypes: Any, pid: int) -> None:
+    import ctypes
+
+    class ThreadEntry(ctypes.Structure):
+        _fields_ = [
+            ("dwSize", wintypes.DWORD),
+            ("cntUsage", wintypes.DWORD),
+            ("th32ThreadID", wintypes.DWORD),
+            ("th32OwnerProcessID", wintypes.DWORD),
+            ("tpBasePri", wintypes.LONG),
+            ("tpDeltaPri", wintypes.LONG),
+            ("dwFlags", wintypes.DWORD),
+        ]
+
+    kernel32.CreateToolhelp32Snapshot.argtypes = (wintypes.DWORD, wintypes.DWORD)
+    kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
+    kernel32.Thread32First.argtypes = (wintypes.HANDLE, ctypes.POINTER(ThreadEntry))
+    kernel32.Thread32First.restype = wintypes.BOOL
+    kernel32.Thread32Next.argtypes = (wintypes.HANDLE, ctypes.POINTER(ThreadEntry))
+    kernel32.Thread32Next.restype = wintypes.BOOL
+    kernel32.OpenThread.argtypes = (wintypes.DWORD, wintypes.BOOL, wintypes.DWORD)
+    kernel32.OpenThread.restype = wintypes.HANDLE
+    kernel32.ResumeThread.argtypes = (wintypes.HANDLE,)
+    kernel32.ResumeThread.restype = wintypes.DWORD
+
+    snapshot = kernel32.CreateToolhelp32Snapshot(0x00000004, 0)
+    invalid = ctypes.c_void_p(-1).value
+    if snapshot == invalid:
+        raise OSError(ctypes.get_last_error(), "CreateToolhelp32Snapshot")
+    try:
+        entry = ThreadEntry(dwSize=ctypes.sizeof(ThreadEntry))
+        found = kernel32.Thread32First(snapshot, ctypes.byref(entry))
+        while found:
+            if entry.th32OwnerProcessID == pid:
+                thread = kernel32.OpenThread(0x0002, False, entry.th32ThreadID)
+                if not thread:
+                    raise OSError(ctypes.get_last_error(), "OpenThread")
+                try:
+                    if kernel32.ResumeThread(thread) == 0xFFFFFFFF:
+                        raise OSError(ctypes.get_last_error(), "ResumeThread")
+                    return
+                finally:
+                    kernel32.CloseHandle(thread)
+            found = kernel32.Thread32Next(snapshot, ctypes.byref(entry))
+    finally:
+        kernel32.CloseHandle(snapshot)
+    raise OSError("suspended operation thread was not found")
+
+
+def _supervise_windows(control_fd: int, result_fd: int, argv: list[str]) -> int:
+    import ctypes
+
+    job, kernel32, wintypes = _windows_job()
+    cancelled = threading.Event()
+    job_lock = threading.Lock()
+    job_open = True
+
+    def terminate_job() -> None:
+        with job_lock:
+            if job_open:
+                kernel32.TerminateJobObject(job, 1)
+
+    def cancel_on_eof() -> None:
+        byte = ctypes.create_string_buffer(1)
+        count = wintypes.DWORD()
+        while kernel32.ReadFile(
+            wintypes.HANDLE(control_fd), byte, 1, ctypes.byref(count), None
+        ) and count.value:
+            pass
+        kernel32.CloseHandle(wintypes.HANDLE(control_fd))
+        cancelled.set()
+        terminate_job()
+
+    threading.Thread(target=cancel_on_eof, daemon=True).start()
+    child: Optional[subprocess.Popen] = None
+    rc = 127
+    try:
+        child = subprocess.Popen(
+            argv,
+            close_fds=True,
+            env=_operation_env(),
+            creationflags=0x08000000 | 0x00000004,  # NO_WINDOW | SUSPENDED
+        )
+        assign = kernel32.AssignProcessToJobObject
+        assign.argtypes = (wintypes.HANDLE, wintypes.HANDLE)
+        assign.restype = wintypes.BOOL
+        if not assign(job, wintypes.HANDLE(child._handle)):
+            raise OSError(ctypes.get_last_error(), "AssignProcessToJobObject")
+        if cancelled.is_set():
+            terminate_job()
+        else:
+            _resume_windows_process(kernel32, wintypes, child.pid)
+        rc = child.wait()
+        # A successful direct child may leave helpers behind; terminate the
+        # nested stable Job before reporting completion.
+        terminate_job()
+    except OSError:
+        terminate_job()
+        if child is not None:
+            try:
+                # Assignment itself may have failed, leaving this suspended
+                # process outside the nested Job.  Terminate it through its
+                # stable process handle before waiting; never strand an
+                # unassigned operation or rely on the outer desktop Job.
+                child.kill()
+            except OSError:
+                # The suspended child may have exited during Job teardown.
+                pass
+            try:
+                child.wait(timeout=5)
+            except (OSError, subprocess.TimeoutExpired):
+                # The outer desktop Job remains the terminal containment fallback.
+                pass
+    finally:
+        payload = _RESULT.pack(int(rc))
+        payload_buffer = ctypes.create_string_buffer(payload)
+        written = wintypes.DWORD()
+        kernel32.WriteFile(
+            wintypes.HANDLE(result_fd),
+            payload_buffer,
+            len(payload),
+            ctypes.byref(written),
+            None,
+        )
+        kernel32.CloseHandle(wintypes.HANDLE(result_fd))
+        with job_lock:
+            job_open = False
+            kernel32.CloseHandle(job)
+    return rc
+
+
+def supervisor_main(args: list[str]) -> int:
+    if len(args) < 5 or args[0] != "--supervise" or args[3] != "--":
+        return 2
+    control_fd = int(args[1])
+    result_fd = int(args[2])
+    argv = args[4:]
+    secure_backend_drain_fd()
+    if os.name == "posix":
+        return _supervise_posix(control_fd, result_fd, argv)
+    return _supervise_windows(control_fd, result_fd, argv)
+
+
+def _main() -> int:
+    return supervisor_main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

backend/core/db.py

@@ -57,9 +57,6 @@ _BASE_SCHEMA = """
         consent_recorded_at REAL DEFAULT NULL,
         kind TEXT DEFAULT 'clone',
         vd_states TEXT DEFAULT NULL,
-        -- Hosted Voice ID is opt-in synchronization metadata. Local synthesis
-        -- never depends on it, so existing offline profiles remain useful.
-        hosted_voice_id TEXT DEFAULT '',
         created_at REAL
     );
     CREATE TABLE IF NOT EXISTS generation_history (
@@ -277,7 +274,8 @@ _BASE_SCHEMA = """
         started_at REAL,
         finished_at REAL,
         lease_expires_at REAL,
-        grace_expires_at REAL
+        grace_expires_at REAL,
+        deadlines_json TEXT
     );
     CREATE INDEX IF NOT EXISTS idx_remote_attempts_task ON remote_task_attempts(task_id);
     CREATE INDEX IF NOT EXISTS idx_remote_attempts_worker ON remote_task_attempts(worker_id, state);

backend/core/device_caps.py

@@ -35,7 +35,8 @@ import sys
 from dataclasses import dataclass
 from typing import Literal
 
-DeviceFamily = Literal["cuda", "rocm", "mps", "xpu", "cpu"]
+DeviceFamily = Literal["cuda", "rocm", "mps", "xpu", "npu", "cpu"]
+ACCELERATOR_PRIORITY = ("cuda", "rocm", "xpu", "npu", "mps")
 
 # Stable substring stamped onto notes that represent a real kernel-launch risk
 # (arch/driver mismatch) — as opposed to advisory notes (multi-GPU, VRAM query
@@ -177,6 +178,23 @@ def gfx_for_hsa_override(value: str) -> str | None:
 #: The ROCm kernel driver interface. Its absence, or its presence without
 #: permission, are the two commonest reasons a ROCm host silently runs on CPU.
 _KFD_DEVICE = "/dev/kfd"
+_DXG_DEVICE = "/dev/dxg"
+_DXG_RUNTIME_PATHS = (
+    "/usr/lib/libdxcore.so",
+    "/usr/lib/librocdxg.so",
+    "/usr/share/rocdxg/dids.conf",
+)
+
+
+def _rocm_requires_dxg_detection(version: object) -> bool:
+    """Whether WSL's ROCDXG bridge still needs its explicit opt-in."""
+    try:
+        parts = str(version).split(".")
+        return (int(parts[0]), int(parts[1])) < (7, 13)
+    except (IndexError, TypeError, ValueError):
+        # Unknown versions get the conservative advice. The variable is
+        # harmless on newer runtimes and necessary on every older one.
+        return True
 
 
 def why_no_gpu(torch) -> tuple[str, ...]:
@@ -230,6 +248,40 @@ def why_no_gpu(torch) -> tuple[str, ...]:
         # /dev/kfd only exists on Linux; on any other platform its absence
         # says nothing, so don't invent a reason.
         if sys.platform.startswith("linux"):
+            if not os.path.exists(_KFD_DEVICE) and os.path.exists(_DXG_DEVICE):
+                if not os.access(_DXG_DEVICE, os.R_OK | os.W_OK):
+                    return (
+                        f"ROCm {hip} is installed and {_DXG_DEVICE} exists, "
+                        "but this process cannot open it — pass "
+                        "--device /dev/dxg to the WSL container",
+                    )
+                dxg_detection = os.environ.get("HSA_ENABLE_DXG_DETECTION", "").strip()
+                if dxg_detection == "0":
+                    return (
+                        f"ROCm {hip} is installed and {_DXG_DEVICE} is reachable, "
+                        "but HSA_ENABLE_DXG_DETECTION=0 explicitly disables the "
+                        "WSL GPU bridge; remove it or set it to 1",
+                    )
+                if _rocm_requires_dxg_detection(hip) and dxg_detection != "1":
+                    return (
+                        f"ROCm {hip} is installed and {_DXG_DEVICE} is "
+                        "reachable, but this pre-7.13 runtime requires "
+                        "HSA_ENABLE_DXG_DETECTION=1 inside WSL containers",
+                    )
+                missing = [
+                    path for path in _DXG_RUNTIME_PATHS if not os.path.exists(path)
+                ]
+                if missing:
+                    return (
+                        f"ROCm {hip} can reach {_DXG_DEVICE}, but the WSL "
+                        "ROCDXG runtime mounts are incomplete; missing: "
+                        f"{', '.join(missing)}",
+                    )
+                return (
+                    f"ROCm {hip} and the WSL ROCDXG bridge are reachable, "
+                    "but no GPU was enumerated — verify the AMD Windows "
+                    "driver, librocdxg/ROCm compatibility, and host `rocminfo`",
+                )
             if not os.path.exists(_KFD_DEVICE):
                 return (
                     f"ROCm {hip} is installed but {_KFD_DEVICE} is not "
@@ -482,9 +534,13 @@ def _probe() -> HostCaps:
         # is the whole truth in that case (CodeRabbit, #1425).
         notes.extend(why_no_gpu(torch))
 
-    # ── Intel XPU via IPEX ───────────────────────────────────────────────
+    # Older builds register XPU through IPEX; modern torch exposes it directly.
     try:
         import intel_extension_for_pytorch  # noqa: F401
+    except Exception:
+        # Optional IPEX may be absent or incompatible; still probe native torch XPU.
+        pass
+    try:
         if hasattr(torch, "xpu") and torch.xpu.is_available():
             detected.append("xpu")
             if not device_name:
@@ -495,7 +551,23 @@ def _probe() -> HostCaps:
                     pass
             notes.append("XPU VRAM not queried (unreliable across IPEX versions)")
     except Exception:
-        # IPEX absent or XPU probe failed — no XPU on this host.
+        # XPU probe failed — no usable XPU on this host.
+        pass
+
+    # Vendor extensions may register an NPU with torch. Probe only an already
+    # registered backend; never install or import an optional vendor package.
+    try:
+        if hasattr(torch, "npu") and torch.npu.is_available():
+            detected.append("npu")
+            if not device_name:
+                try:
+                    device_name = torch.npu.get_device_name(0)
+                except Exception:
+                    # An unavailable display name does not invalidate a usable NPU.
+                    pass
+            notes.append("NPU VRAM not queried")
+    except Exception:
+        # Missing or broken vendor backends mean no usable NPU; continue probing.
         pass
 
     # ── Apple Silicon MPS ────────────────────────────────────────────────
@@ -528,7 +600,7 @@ def _probe() -> HostCaps:
 
     # Preferred family by priority; cpu when nothing accelerated was detected.
     family: DeviceFamily = "cpu"
-    for pref in ("cuda", "rocm", "xpu", "mps"):
+    for pref in ACCELERATOR_PRIORITY:
         if pref in detected:
             family = pref  # type: ignore[assignment]
             break

backend/core/diagnose.py

@@ -21,12 +21,14 @@ Check shape:
 """
 from __future__ import annotations
 
+import importlib
 import os
 import platform
 import shutil
 import sys
 
 from core.config import DATA_DIR
+from core.device_caps import KERNEL_RISK_MARKER
 from core.scrub import scrub_text
 from core.version import APP_VERSION
 
@@ -188,7 +190,7 @@ def _check_ram() -> dict:
 def _check_engines() -> dict:
     try:
         from services.tts_backend import list_backends, active_backend_id
-        backends = list_backends()
+        backends = list_backends(include_hidden=True)
         active = active_backend_id()
     except Exception as e:
         return _check("engines", "TTS engines", WARN, f"could not enumerate: {e}")
@@ -229,11 +231,16 @@ def _check_gpu_routing() -> dict:
     host = v.get("host_family", "cpu")
 
     if status == "accelerated":
-        if reason:  # driver/arch caveat — accelerated but at risk
+        if reason and KERNEL_RISK_MARKER in reason:  # driver/arch caveat — at risk
             return _check("gpu_routing", "GPU routing", WARN,
                           f"{engine} -> {dev}: {reason}",
                           "The GPU is selected but may fail at kernel launch — "
                           "update drivers / reinstall torch for this GPU arch.")
+        if reason:  # low-VRAM caveat — not a driver/arch issue
+            return _check("gpu_routing", "GPU routing", WARN,
+                          f"{engine} -> {dev}: {reason}",
+                          "Unload other models before generating, keep the text "
+                          "short, or pick a lighter engine.")
         return _check("gpu_routing", "GPU routing", OK, f"{engine} -> {dev} (accelerated)")
     if status == "cpu_fallback":
         return _check("gpu_routing", "GPU routing", WARN,
@@ -367,10 +374,49 @@ def run_diagnostics(include_network: bool = True, deep: bool = False) -> dict:
     counts = {OK: 0, WARN: 0, FAIL: 0}
     for c in checks:
         counts[c["status"]] += 1
+    engine_execution = []
+    for family in ("tts", "asr"):
+        active = "unknown"
+        try:
+            module = importlib.import_module(f"services.{family}_backend")
+            active = module.active_backend_id()
+            rows = (
+                module.list_backends(include_hidden=True)
+                if family == "tts"
+                else module.list_backends()
+            )
+            row = next((item for item in rows if item.get("id") == active), None)
+            if row is not None:
+                engine_execution.append({
+                    "family": family,
+                    "engine_id": active,
+                    **row["execution_evidence"],
+                })
+        except Exception:  # noqa: BLE001 - evidence must not break diagnostics
+            # Preserve the other family's successful evidence and make this
+            # collection failure explicit without exposing exception text.
+            engine_execution.append({
+                "family": family,
+                "engine_id": active,
+                "implementation_variant": None,
+                "declared_device_families": [],
+                "evidence_state": "collection_failed",
+                "actual_execution_provider": None,
+                "actual_execution_device": None,
+                "gpu_name": None,
+                "gpu_architecture": None,
+                "precision_or_quantization": None,
+                "cpu_fallback_reason": None,
+                "cpu_fallback_stage": None,
+                "parent_memory_observable": None,
+                "runtime_versions": {},
+            })
+
     return {
         "app_version": APP_VERSION,
         "platform": scrub_text(platform.platform()),
         "checks": checks,
+        "engine_execution": engine_execution,
         "summary": {
             "ok": counts[FAIL] == 0,
             "passed": counts[OK],
@@ -395,6 +441,35 @@ def format_text(report: dict) -> str:
         lines.append(f"{tag[c['status']]} {c['label']}: {c['detail']}")
         if c.get("hint"):
             lines.append(f"       hint: {c['hint']}")
+    if report.get("engine_execution"):
+        lines.append("")
+        lines.append("Engine execution evidence:")
+        for item in report["engine_execution"]:
+            if item.get("actual_execution_provider"):
+                provider = item["actual_execution_provider"]
+            elif item.get("evidence_state") == "subprocess_loaded_provider_unreported":
+                provider = "loaded child; provider not reported"
+            else:
+                provider = "not loaded"
+            precision = item.get("precision_or_quantization") or "unknown"
+            device = item.get("actual_execution_device") or "unknown"
+            gpu = item.get("gpu_name") or "none"
+            architecture = item.get("gpu_architecture") or "unknown"
+            fallback_stage = item.get("cpu_fallback_stage") or "none"
+            fallback_reason = item.get("cpu_fallback_reason") or "none"
+            versions = ",".join(
+                f"{name}={version}"
+                for name, version in sorted(item.get("runtime_versions", {}).items())
+            ) or "none"
+            visible = "yes" if item.get("parent_memory_observable") else "no"
+            lines.append(
+                f"  {item['family']}:{item['engine_id']} provider={provider}; "
+                f"device={device}; gpu={gpu}; architecture={architecture}; "
+                f"precision={precision}; fallback-stage={fallback_stage}; "
+                f"fallback-reason={fallback_reason}; runtimes={versions}; "
+                f"evidence-state={item.get('evidence_state', 'unknown')}; "
+                f"parent-memory-visible={visible}"
+            )
     s = report["summary"]
     lines.append("")
     lines.append(

backend/core/event_bus.py

@@ -23,9 +23,17 @@ logger = logging.getLogger("omnivoice.events")
 _listeners: list[asyncio.Queue] = []
 _lock = asyncio.Lock()
 
+# The loop that serves /ws/events, captured on first use. Sync FastAPI
+# endpoints (rename/delete profile, revoke consent) run in threadpool workers
+# where `asyncio.get_running_loop()` raises, which used to silently drop their
+# events — the UI then never refetched the voice list (#1158 class).
+_serving_loop: asyncio.AbstractEventLoop | None = None
+
 
 async def subscribe() -> asyncio.Queue:
     """Register a new listener. Returns a Queue that receives event dicts."""
+    global _serving_loop
+    _serving_loop = asyncio.get_running_loop()
     q: asyncio.Queue = asyncio.Queue(maxsize=64)
     async with _lock:
         _listeners.append(q)
@@ -57,11 +65,29 @@ def emit(kind: str, payload: dict[str, Any] | None = None) -> None:
     }
     event_str = json.dumps(event)
     try:
-        loop = asyncio.get_running_loop()
-        loop.create_task(_broadcast(event_str))
+        caller_loop = asyncio.get_running_loop()
     except RuntimeError:
-        # No event loop running (unlikely in FastAPI context but safe)
+        caller_loop = None
+    target_loop = _serving_loop or caller_loop
+    if target_loop is None:
+        # No serving loop yet — nobody to notify; dropping is correct.
         logger.debug("No event loop — event dropped: %s", kind)
+        return
+    try:
+        if caller_loop is target_loop:
+            target_loop.create_task(_broadcast(event_str))
+        else:
+            # Sync endpoints and async producers on a foreign loop must both
+            # hand off: the lock and listener queues belong to serving_loop.
+            target_loop.call_soon_threadsafe(_schedule_broadcast, event_str)
+    except RuntimeError:
+        # The serving loop closed between capture and use (app shutdown).
+        logger.debug("Event loop closed — event dropped: %s", kind)
+
+
+def _schedule_broadcast(event_str: str) -> None:
+    """Run `_broadcast` on the serving loop; called via call_soon_threadsafe."""
+    asyncio.get_running_loop().create_task(_broadcast(event_str))
 
 
 async def _broadcast(event_str: str) -> None:
@@ -73,11 +99,11 @@ async def _broadcast(event_str: str) -> None:
                 q.put_nowait(event_str)
             except asyncio.QueueFull:
                 # Slow consumer — drop oldest, then push. Not a race (#1163):
-                # every queue op runs on the single event loop, and there is
-                # no await between the QueueFull and this get_nowait/put_nowait
-                # pair — no consumer can interleave, so get_nowait cannot raise
-                # QueueEmpty here. emit() from a foreign thread drops the event
-                # before ever touching a queue (see the RuntimeError branch).
+                # every queue op runs on the single event loop (a foreign
+                # thread's emit() hands off via call_soon_threadsafe first),
+                # and there is no await between the QueueFull and this
+                # get_nowait/put_nowait pair — no consumer can interleave, so
+                # get_nowait cannot raise QueueEmpty here.
                 try:
                     q.get_nowait()
                     q.put_nowait(event_str)

backend/core/failure.py

@@ -52,6 +52,7 @@ _REDACTED_VALUE = "***REDACTED***"
 # One-line "what to do" per docs-taxonomy key. Keys mirror error_docs_map's
 # taxonomy; the docs URL itself stays owned by error_docs_map.
 _HINTS: dict[str, str] = {
+    "GPU_OOM": "Close other GPU-heavy apps or unload models, then retry. You can also choose CPU in Settings → Performance & Device or select a smaller TTS engine.",
     "WORKER_AT_CAPACITY": "Wait for a running job on that worker to finish, or choose another available worker and retry.",
     "MODEL_NOT_INSTALLED": "Install or enable this engine on the worker machine, then refresh its capabilities and retry.",
     "MODEL_NOT_DOWNLOADED": "Open Models, install this model on the selected worker, then retry when the download completes.",
@@ -96,6 +97,9 @@ _HINTS: dict[str, str] = {
     "TRANSFORMERS_IMPORT": "Your transformers install is incomplete, or a package it loads models through (torchaudio, torchvision) is missing or mismatched with your torch — a torch/torchvision version mismatch fails with exactly this wording. Reinstall them together at the pinned versions (`uv pip install --python .venv --reinstall torch==2.8.0 torchaudio==2.8.0 torchvision==0.23.0 transformers` in the project folder), then restart the backend. If only transcription is affected, switching ASR to faster-whisper (Model Catalogue → Models) also works around it.",
     "WINDOWS_APP_CONTROL_BLOCKED": "Windows refused to load a file VoiceStudio needs — an Application Control policy (Smart App Control, WDAC, or AppLocker) blocked it. On a personal PC: Windows Security → App & browser control → Smart App Control → Off (Windows only lets you turn it off once — re-enabling requires a Windows reset), then restart VoiceStudio. On a managed/work PC, ask IT to allow the VoiceStudio install folder.",
     "WINDOWS_PAGING_FILE_TOO_SMALL": "Windows ran out of virtual memory while mapping the model into memory — its paging file is smaller than the model needs. This is not the same as your RAM being full, and closing other apps usually won't fix it: Windows has to be allowed to back the mapping. Set a bigger paging file — Settings → System → About → Advanced system settings → Performance → Settings → Advanced → Virtual memory → Change: untick \"Automatically manage\", pick your system drive, choose \"Custom size\" and set both Initial and Maximum to at least 32768 MB (more than the model's size), then OK and restart Windows. A smaller/quantized engine (OmniVoice GGUF, Supertonic-3) also avoids the large mapping entirely.",
+    "WINDOWS_UNTRUSTED_MOUNT": "Windows refused to walk a folder on the way to this file because the path crosses a mount point it does not trust (WinError 448). That is a Windows rule about the VOLUME, not about VoiceStudio or the file itself — it turns up on Dev Drives, on mounted VHD/ReFS volumes, and on junctions pointing into another user profile, so retrying the same link cannot help. Point VoiceStudio at a folder on an ordinary local drive instead: Settings → Storage → data directory, or the download/output folder named in the message. If that folder has to stay where it is, trust the volume with `fsutil devdrv trust <drive>:` from an elevated prompt and restart.",
+    "INPUT_TOO_SHORT": "The input was too short for this engine to process — its first convolution needs more frames than the text (or the reference clip) produced. This is a hard limit of the model, not a transient failure, so retrying the same input will fail the same way. Give it a few more words, or a longer reference clip: a short phrase rather than one or two characters, and about a second of speech rather than a fragment.",
+    "CLONE_REFERENCE_MISSING": "This engine was asked to clone a voice but got no reference audio to clone FROM, and the model folder carries no built-in voice either. Pick a voice profile that has a saved reference clip, or record/upload a few seconds of clean speech as the reference, then generate again. A designed voice with no saved reference cannot be cloned from — synthesize with it directly instead.",
     "MEDIA_TOOL_MISSING": "VoiceStudio's media engine (ffmpeg/ffprobe) wasn't on the system path when a component went looking for it. Open Settings → Audio tools and use Download/Repair to fetch the bundled copy, then retry — a restart picks it up for everything. If you'd rather use a system install, install ffmpeg (macOS: `brew install ffmpeg`; Windows: `winget install Gyan.FFmpeg`; Linux: your package manager) and restart VoiceStudio, or point FFMPEG_PATH / OMNIVOICE_FFPROBE_PATH at the binaries in Settings.",
     "AUDIO_IO_FAILED": "An audio file couldn't be read or written at the OS level. Check the drive isn't full, that the output and temp folders exist and are writable, and that antivirus or OneDrive isn't locking them (add a VoiceStudio exclusion if you use one).",
     "VIDEO_DOWNLOAD_OS_ERROR": "The OS refused a file operation while saving the downloaded video — this is a disk/folder problem, not a network one, so retrying the same link won't help. The download is written to a job folder under your VoiceStudio data directory (Settings → Storage shows the path): check that drive isn't full, that the folder exists and is writable, and that antivirus or a cloud-sync client (OneDrive, Dropbox) isn't locking it — add a VoiceStudio exclusion if you use one. If your data directory sits on a synced or network drive, move it to a local one.",
@@ -290,6 +294,9 @@ def append_hf_mirror_hint(text: str) -> str:
 # must NOT be added: its bare "timed out" trigger would stamp a "video server"
 # hint on a model-load timeout that leaks through the 500 handler.
 _CONTEXT_FREE_HINT_CLASSES = frozenset({
+    # Device allocator signatures are specific enough to attach the shared
+    # recovery without exposing CUDA's process table or filesystem paths.
+    "GPU_OOM",
     "SOCKS_PROXY_SUPPORT_MISSING",
     "SSL_HANDSHAKE_FAILURE",
     # Its trigger is an exact OpenSSL string, so it cannot be confused with
@@ -304,6 +311,23 @@ _CONTEXT_FREE_HINT_CLASSES = frozenset({
     # a Windows virtual-memory setting rather than a connectivity problem, and
     # the detailed hint we already had for it never reached them.
     "WINDOWS_PAGING_FILE_TOO_SMALL",
+    # #1957: triggered by WinError 448 or the literal "untrusted mount
+    # point" — both unmistakable, and it reaches the user as a bare
+    # download failure with only the OS sentence attached.
+    "WINDOWS_UNTRUSTED_MOUNT",
+    # #1826: torch's own conv wording, which nothing else produces, and it
+    # reaches the user through the generic 500.
+    "INPUT_TOO_SHORT",
+    # #1879: matched on wording no other failure produces, and it reaches the
+    # user as a bare 400 carrying only the library sentence.
+    "CLONE_REFERENCE_MISSING",
+    # Its trigger is a VoiceStudio-authored sentence — "the TTS model cache
+    # for … is incomplete" plus "could not be auto-repaired" / "weights
+    # missing" — so it cannot be produced by an unrelated library. The 500
+    # handler is the surface a corrupt cache actually reaches, and dropping
+    # its hint there would leave the user with no way to know a redownload
+    # is the fix.
+    "MODEL_CACHE_CORRUPT",
 })
 
 
@@ -323,6 +347,38 @@ def append_hint(text: str) -> str:
     return f"{text} — {hint}" if hint else text
 
 
+_GPU_OOM_SIGNATURES = (
+    "cuda out of memory",
+    "cuda error: out of memory",
+    "cuda_error_out_of_memory",
+    "mps backend out of memory",
+    "hip out of memory",
+    "out of memory on device",
+)
+
+
+def is_gpu_oom(error: BaseException | str) -> bool:
+    """Recognize device OOMs through wrappers without importing torch."""
+    pending: list[BaseException] = [error] if isinstance(error, BaseException) else []
+    seen: set[int] = set()
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        if type(current).__name__ == "OutOfMemoryError":
+            return True
+        if any(signature in str(current).lower() for signature in _GPU_OOM_SIGNATURES):
+            return True
+        if current.__cause__ is not None:
+            pending.append(current.__cause__)
+        if current.__context__ is not None:
+            pending.append(current.__context__)
+    if isinstance(error, str):
+        return any(signature in error.lower() for signature in _GPU_OOM_SIGNATURES)
+    return False
+
+
 def classify(reason: str) -> str:
     """Map a failure reason to a docs-taxonomy key, or "" when unknown.
 
@@ -330,6 +386,8 @@ def classify(reason: str) -> str:
     backend log / diagnostic names the same class the UI deeplink will use.
     """
     low = (reason or "").lower()
+    if is_gpu_oom(low):
+        return "GPU_OOM"
     if "pkg_resources" in low:
         return "PKG_RESOURCES_MISSING"
     if "quarantine" in low or "is damaged" in low or "gatekeeper" in low:
@@ -519,6 +577,7 @@ def classify(reason: str) -> str:
         or "unable to download video" in low
         or "remote end closed" in low
         or "timed out" in low
+        or "the page needs to be reloaded" in low
     ):
         return "VIDEO_DOWNLOAD_NETWORK"
     # #1227: Windows Smart App Control / WDAC / AppLocker refused to load a
@@ -530,6 +589,34 @@ def classify(reason: str) -> str:
         or "application control policy" in low
     ):
         return "WINDOWS_APP_CONTROL_BLOCKED"
+    # #1957: the path to a download or output file crosses a mount point
+    # Windows will not traverse (Dev Drive, mounted VHD/ReFS, a junction into
+    # another profile). Matched on the numeric code first because the OS
+    # translates the sentence, with the English phrase as a fallback.
+    if "[winerror 448]" in low or "untrusted mount point" in low:
+        return "WINDOWS_UNTRUSTED_MOUNT"
+    # #1826: a degenerate-length input reaches a conv layer whose kernel is
+    # wider than the tensor, and torch says so in its own terms — "Calculated
+    # padded input size per channel: (1). Kernel size: (2). Kernel size can't
+    # be greater than actual input size". That arrived doubly wrapped in
+    # "Underlying error:" and told the user nothing they could act on, when
+    # the fix is simply "type more than one character".
+    if "kernel size can't be greater than actual input size" in low or (
+        "calculated padded input size per channel" in low
+    ):
+        return "INPUT_TOO_SHORT"
+    # #1879: mlx-audio (and the Chatterbox-family models under it) raise a
+    # bare ValueError naming their own parameters — "No conditionals
+    # available. Either provide audio_prompt/audio_prompt_sr ... or ensure
+    # conds.safetensors is in the model directory." The generate route passed
+    # that straight through as the 400 detail, so the user was told to supply
+    # an argument they have no way to name and to check for a file they have
+    # never heard of. What actually happened is "you asked to clone without a
+    # reference clip".
+    if "no conditionals available" in low or (
+        "audio_prompt" in low and "conds.safetensors" in low
+    ):
+        return "CLONE_REFERENCE_MISSING"
     # #1221: libsndfile failed an OS-level audio read/write. Its own wording is
     # a bare "System error.", so match the library name — audio_io already
     # prefixes the target path and free space onto the write-path failures.

backend/core/parent_liveness.py

@@ -0,0 +1,108 @@
+"""Terminate a desktop-contained backend when its owning shell disappears."""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Any, BinaryIO, Callable, Optional
+
+# Poll cadence for the Windows pipe watcher. Exit latency after the desktop
+# closes its end is bounded by this; the desktop's own kill-on-close Job is the
+# hard backstop, so a quarter second is plenty and costs nothing measurable.
+WINDOWS_PIPE_POLL_INTERVAL_S = 0.25
+_FILE_TYPE_PIPE = 3  # winbase.h FILE_TYPE_PIPE
+
+
+def _watch_parent_pipe(reader: BinaryIO, exit_process: Callable[[int], None]) -> None:
+    """Block until the desktop-owned stdin pipe closes, then exit immediately."""
+    try:
+        while reader.read(1):
+            pass
+    except (OSError, ValueError):
+        # A broken or already-closed parent-owned pipe is equivalent to EOF.
+        pass
+    exit_process(0)
+
+
+def _watch_parent_pipe_handle(
+    handle: int,
+    exit_process: Callable[[int], None],
+    *,
+    peek: Optional[Callable[[int], Any]] = None,
+    read_file: Optional[Callable[[int, int], Any]] = None,
+    sleep: Callable[[float], None] = time.sleep,
+    interval: float = WINDOWS_PIPE_POLL_INTERVAL_S,
+) -> None:
+    """Windows twin of :func:`_watch_parent_pipe` that never leaves a read
+    pending on the pipe.
+
+    A synchronous ``ReadFile`` parked on the stdin pipe — whether issued through
+    the C runtime's ``read()`` or straight to the kernel — deadlocks the
+    OpenBLAS DLL initializer that ``import torch`` reaches (numpy's
+    ``_multiarray_umath``) in the startup worker: every desktop-spawned backend
+    on Windows froze at "Loading ML runtime (PyTorch)" while the identical
+    command from a terminal, with no stdin pipe and no watchdog, started in
+    seconds. A thread that merely sleeps does not trigger it; only the pending
+    read on that pipe does. So instead of blocking in a read, poll with
+    ``PeekNamedPipe``: it returns immediately, holds no I/O on the file object,
+    drains any keepalive bytes the desktop might write, and fails with
+    ``ERROR_BROKEN_PIPE`` the moment the desktop closes its end — which is the
+    same EOF signal the POSIX reader gets.
+    """
+    if peek is None or read_file is None:
+        import _winapi  # Windows-only stdlib module; the caller gates on the platform
+
+        peek = peek or _winapi.PeekNamedPipe
+        read_file = read_file or _winapi.ReadFile
+    try:
+        while True:
+            available, _ = peek(handle)
+            if available:
+                # Bytes are already buffered, so this read cannot block.
+                read_file(handle, available)
+            else:
+                sleep(interval)
+    except OSError:
+        # ERROR_BROKEN_PIPE (109) is how the closed parent end surfaces here.
+        pass
+    exit_process(0)
+
+
+def _windows_pipe_handle(reader: Any) -> Optional[int]:
+    """The OS handle behind ``reader`` when it is a pipe, else None."""
+    try:
+        import msvcrt
+        import _winapi
+
+        handle = msvcrt.get_osfhandle(reader.fileno())
+        if _winapi.GetFileType(handle) != _FILE_TYPE_PIPE:
+            return None
+        return handle
+    except (OSError, ValueError, AttributeError, ImportError):
+        return None
+
+
+def arm_desktop_parent_watchdog() -> bool:
+    """Use stdin EOF as an unforgeable parent-liveness signal for desktop runs."""
+    if os.environ.get("OMNIVOICE_DESKTOP_CONTAINED") != "1":
+        return False
+    reader = getattr(sys.stdin, "buffer", None)
+    if reader is None:
+        return False
+    target: Callable[..., None] = _watch_parent_pipe
+    args: tuple = (reader, os._exit)
+    if os.name == "nt":
+        handle = _windows_pipe_handle(reader)
+        if handle is not None:
+            target = _watch_parent_pipe_handle
+            args = (handle, os._exit)
+        # A non-pipe stdin (file, NUL) cannot have a read pending against a
+        # pipe file object, so the blocking reader stays correct there.
+    threading.Thread(
+        target=target,
+        args=args,
+        name="desktop-parent-watchdog",
+        daemon=True,
+    ).start()
+    return True

backend/core/path_authorization.py

@@ -7,6 +7,7 @@ only the unguessable capability token crosses loopback HTTP.
 from __future__ import annotations
 
 import json
+import logging
 import os
 import re
 import secrets
@@ -14,6 +15,8 @@ import stat
 
 from core.config import DATA_DIR
 
+logger = logging.getLogger("omnivoice.path_authorization")
+
 _TOKEN_RE = re.compile(r"[0-9a-f]{64}\Z")
 _KINDS = {
     "models_dir",
@@ -40,25 +43,49 @@ def consume(token: str, expected_kind: str) -> str:
     if expected_kind not in _KINDS or not _TOKEN_RE.fullmatch(token or ""):
         raise PathAuthorizationError("Invalid or expired desktop authorization")
     root = _AUTH_DIR
+    # Distinguish "the store exists but this token isn't in it" (expired /
+    # already consumed / never issued — normal, no server-side signal) from
+    # "the store doesn't exist at all" (the desktop app and this backend are
+    # very likely pointed at different data directories, e.g. a dev backend
+    # started without OMNIVOICE_DATA_DIR, or a stale custom data folder — see
+    # #1781). The client-facing message is byte-identical either way (never
+    # leak local filesystem paths, or even which case occurred, over HTTP —
+    # CWE-200); the mismatch case additionally gets a server log line so it's
+    # diagnosable instead of a silent 403. That log line is deliberately
+    # path-free too (CWE-532: per-user filesystem paths, e.g. a home
+    # directory username, are sensitive and don't belong in application
+    # logs) — it names the failure mode, not the directory.
+    try:
+        entries = os.scandir(root)
+    except FileNotFoundError as exc:
+        logger.warning(
+            "path authorization store does not exist; the desktop app and "
+            "this backend likely resolved different data directories "
+            "(see #1781)"
+        )
+        raise PathAuthorizationError("Invalid or expired desktop authorization") from exc
+    except OSError as exc:
+        raise PathAuthorizationError("Invalid or expired desktop authorization") from exc
     candidate = None
     try:
-        for entry in os.scandir(root):
-            if not _TOKEN_RE.fullmatch(entry.name.removesuffix(".json")):
-                continue
-            if not entry.is_file(follow_symlinks=False):
-                continue
-            try:
-                with open(entry.path, "r", encoding="utf-8") as handle:
-                    probe = json.load(handle)
-            except (OSError, UnicodeError, json.JSONDecodeError):
-                continue  # Ignore corrupt/stale capabilities; they authorize nothing.
-            if isinstance(probe, dict) and secrets.compare_digest(
-                str(probe.get("token", "")), token
-            ):
-                candidate = entry.path
-                break
+        with entries:
+            for entry in entries:
+                if not _TOKEN_RE.fullmatch(entry.name.removesuffix(".json")):
+                    continue
+                if not entry.is_file(follow_symlinks=False):
+                    continue
+                try:
+                    with open(entry.path, "r", encoding="utf-8") as handle:
+                        probe = json.load(handle)
+                except (OSError, UnicodeError, json.JSONDecodeError):
+                    continue  # Ignore corrupt/stale capabilities; they authorize nothing.
+                if isinstance(probe, dict) and secrets.compare_digest(
+                    str(probe.get("token", "")), token
+                ):
+                    candidate = entry.path
+                    break
         if candidate is None:
-            raise OSError("capability not found")
+            raise PathAuthorizationError("Invalid or expired desktop authorization")
         claimed = os.path.join(root, f".consuming-{os.getpid()}-{secrets.token_hex(16)}")
         os.replace(candidate, claimed)
     except OSError as exc:

backend/core/path_security.py

@@ -17,6 +17,13 @@ _WINDOWS_RESERVED_NAMES = frozenset({"CON", "PRN", "AUX", "NUL"}) | frozenset(
     f"{prefix}{number}" for prefix in ("COM", "LPT") for number in range(1, 10)
 )
 
+# Both separator families, so a stored sub-path splits into the same components
+# on every host. Windows accepts ``/`` as a real separator, so splitting on
+# ``os.sep`` alone left ``"job/out.mp4"`` as a single component there while the
+# identical value split cleanly on POSIX. POSIX input never reaches this with a
+# backslash — it is rejected as a foreign separator before the split.
+_PATH_SEPARATORS = re.compile(r"[\\/]")
+
 
 class UnsafePath(ValueError):
     """Raised when a path crosses its allowed filesystem boundary."""
@@ -52,11 +59,10 @@ def resolve_within(root: os.PathLike[str] | str, value: os.PathLike[str] | str)
     raw = os.fspath(value) if value is not None else ""
     if not isinstance(raw, str) or not raw:
         raise UnsafePath("path is empty")
-    # Treat both separator families as structural on every host. Otherwise a
-    # Windows traversal string is an innocent-looking filename when validated
-    # on Linux (and can become dangerous after persisted data is moved).
-    if os.sep != "\\" and ("\\" in raw or bool(ntpath.splitdrive(raw)[0])):
-        raise UnsafePath("path uses a foreign separator or drive")
+    # Treat both separator families as structural on every host while still
+    # rejecting Windows drive paths before rebuilding relative components.
+    if os.sep != "\\" and bool(ntpath.splitdrive(raw)[0]):
+        raise UnsafePath("path uses a drive")
     root_path = Path(root).expanduser().resolve(strict=False)
     root_text = str(root_path)
     if os.path.isabs(raw):
@@ -69,7 +75,7 @@ def resolve_within(root: os.PathLike[str] | str, value: os.PathLike[str] | str)
     # containment proof explicit to static analysis, this rejects empty,
     # dot, parent, drive, and separator-bearing components before Path sees
     # any persisted/request-derived string.
-    parts = raw.split(os.sep)
+    parts = _PATH_SEPARATORS.split(raw)
     clean_parts: list[str] = []
     for part in parts:
         clean = os.path.basename(part)

backend/core/prefs.py

@@ -91,3 +91,53 @@ def resolve(key: str, *, env: Optional[str] = None, default: Any = None) -> Any:
         if v:
             return v
     return get(key, default)
+
+
+# ── external-override detection (#1787 review fix) ──────────────────────────
+# restore_env() below uses os.environ.setdefault(), so a value already present
+# in the process's environment (shell profile, `.env`, Docker `-e`, systemd
+# unit, …) silently wins over anything saved in prefs.json — the setdefault
+# call is a no-op. That is the right behavior (env stays authoritative,
+# matching resolve()'s contract above), but a Settings control that persists a
+# value to prefs.json must not tell the user it "took effect after restart"
+# when an external source will keep shadowing it on every future restart too.
+#
+# _EXTERNALLY_PROVIDED records, once per process start, every bare key that
+# was ALREADY present in os.environ the moment restore_env() ran — i.e.
+# before our own setdefault() calls could have put it there, and before any
+# value our Settings UI ever wrote (Settings only ever writes prefs.json plus
+# the CURRENT process's os.environ; it never touches a shell profile or `.env`
+# file). Snapshotting unconditionally — not only for keys prefs.json already
+# has an entry for — means is_env_shadowed() also answers correctly for a key
+# a user is about to save for the FIRST time. Membership is stable for the
+# life of the process (nothing removes an inherited env var), and since a
+# plain restart re-inherits the same shell / container environment, it is
+# also a reliable predictor for the NEXT start: if the external source is
+# still exporting the key, the next restart will be shadowed again the same
+# way.
+_EXTERNALLY_PROVIDED: frozenset[str] = frozenset()
+
+
+def restore_env(data: dict) -> None:
+    """Restore ``env.*`` prefs into ``os.environ`` (startup only).
+
+    Called once from main.py's ``env_prefs`` step, before any user code reads
+    ``os.environ``. Snapshots which keys were already externally provided —
+    see :func:`is_env_shadowed` — then applies every saved ``env.*`` pref via
+    ``setdefault`` (never overriding an explicitly-set env var).
+    """
+    global _EXTERNALLY_PROVIDED
+    _EXTERNALLY_PROVIDED = frozenset(os.environ.keys())
+    for k, v in data.items():
+        if not k.startswith("env.") or not v:
+            continue
+        os.environ.setdefault(k[len("env."):], str(v))
+
+
+def is_env_shadowed(key: str) -> bool:
+    """Whether *key* was already present in the environment from a source
+    other than our own prefs restore, as of the last time :func:`restore_env`
+    ran. If prefs.json holds (or will hold) a saved value for *key*, that
+    value is being silently ignored — and will be again on the next restart —
+    unless the external source is removed."""
+    return key in _EXTERNALLY_PROVIDED

backend/core/public_errors.py

@@ -28,6 +28,15 @@ def stream_failure(code: str) -> dict[str, object]:
             "detail": "Generation capacity is busy. Try again shortly.",
             "retryable": True,
         },
+        "generation_timeout": {
+            "code": "generation_timeout",
+            "detail": (
+                "Generation exceeded the compute-time limit. The backend is "
+                "still running; try a shorter passage, or raise the "
+                "compute-time budget in Settings → Performance & Device."
+            ),
+            "retryable": True,
+        },
         "invalid_request": {
             "code": "invalid_request",
             "detail": "The generation request could not be processed.",
@@ -65,6 +74,58 @@ def stream_failure(code: str) -> dict[str, object]:
     return dict(failures.get(code, failures["generation_failed"]))
 
 
+def stream_generation_failure(error: BaseException | object) -> dict[str, object]:
+    """``generation_failed`` stream metadata, enriched with the actual cause.
+
+    The bare "Generation failed. Check the selected engine and try again." is
+    the floor for an *unrecognized* failure. When the private exception DOES
+    classify to a known failure class — a corrupt model cache, an unreachable
+    Hugging Face mirror, a missing ffmpeg/ffprobe, a Windows paging-file limit,
+    a SOCKS/TLS proxy problem, … — the stable VoiceStudio-owned remediation for
+    that class is appended so the user can self-diagnose instead of guessing
+    which engine or which failure. This is the same enrichment the classic
+    (non-streaming) ``/generate`` 500 already gets via
+    :func:`public_exception_response`; the in-band streaming error frame
+    replaces the global 500 handler for a streaming request and used to bypass
+    it entirely (#1607).
+
+    Only VoiceStudio-owned constants are copied — never a substring of
+    ``error`` (Constitution I). Never raises: a diagnosis failure must not
+    replace the failure being diagnosed.
+    """
+    payload = stream_failure("generation_failed")
+    if isinstance(error, BaseException):
+        # The exception's TYPE NAME, never its message. Two failures that both
+        # render the floor message "Generation failed. Check the selected
+        # engine and try again." are indistinguishable in an auto-filed report,
+        # so every unclassified streaming failure arrives as the same issue and
+        # none of them can be triaged (#1800). A class name is VoiceStudio-safe
+        # by the same reasoning that already puts it on the wire as
+        # `error_class` in the dub routes and on the analytics allowlist: it is
+        # a Python type, not user text, and no substring of `error` is copied.
+        payload["error_class"] = type(error).__name__
+    try:
+        enriched = public_exception_response(error, fallback=str(payload["detail"]))
+    except Exception:
+        return payload
+    hint = enriched.get("hint")
+    if hint:
+        payload["detail"] = enriched["detail"]
+        payload["hint"] = hint
+        topic = enriched.get("docs_topic")
+        if topic:
+            payload["docs_topic"] = topic
+            try:
+                from core import error_docs_map
+
+                url = error_docs_map.ERROR_DOCS.get(topic, "")
+            except Exception:
+                url = ""
+            if url:
+                payload["docs_url"] = url
+    return payload
+
+
 def public_failure(
     logger: logging.Logger,
     log_message: str,
@@ -98,12 +159,31 @@ def public_exception_response(error: BaseException, *, fallback: str) -> dict[st
     Classification may inspect the private diagnostic locally, but response
     values come exclusively from VoiceStudio-owned constants. No substring of
     ``error`` is copied into the payload.
+
+    Every caller is a CONTEXT-FREE surface — the global 500 handler, the
+    streaming generate error frame, the dub GPU-OOM 503 — so the topic is
+    filtered through ``failure._CONTEXT_FREE_HINT_CLASSES`` before its hint is
+    attached. Without that filter a topic whose trigger is a generic phrase
+    stamps a confidently wrong remediation on an unrelated failure: #1943 is a
+    macOS mlx-audio TTS 500 that came back advising the user that "the
+    connection to the video server dropped mid-download", because
+    VIDEO_DOWNLOAD_NETWORK triggers on a bare "timed out" / "connection
+    reset". The allowlist already existed and already named that class as the
+    example of what must not appear here; only :func:`failure.append_hint`
+    honoured it, and this helper replaced ``append_hint`` on the 500 path
+    without carrying the rule across.
+
+    HF_MIRROR_UNREACHABLE is allowed alongside it: its hint is dynamic (it
+    names the configured mirror) and its trigger requires that a mirror is
+    configured at all, so it cannot fire on an unrelated failure (#874).
     """
-    from core.failure import classify, public_hint_for_topic
+    from core.failure import _CONTEXT_FREE_HINT_CLASSES, classify, public_hint_for_topic
 
     try:
         topic = classify(str(error))
-        hint = public_hint_for_topic(topic)
+        if topic and topic not in _CONTEXT_FREE_HINT_CLASSES and topic != "HF_MIRROR_UNREACHABLE":
+            topic = ""
+        hint = public_hint_for_topic(topic) if topic else ""
     except Exception:
         topic = ""
         hint = ""

backend/core/torch_indexes.py

@@ -0,0 +1,43 @@
+"""The PyTorch wheel index VoiceStudio installs CUDA builds from.
+
+A local-version pin such as ``torch==2.9.1+cu128`` exists only on PyTorch's
+own index, never on PyPI. The app's own ``pyproject.toml`` routes torch there
+through ``[tool.uv.sources]``, but a sidecar engine is installed with
+``uv pip install`` into its own venv, which knows nothing about that config —
+so every CUDA-pinned sidecar install has to name the index itself.
+
+MOSS-TTS-v1.5's install did not, and its ``[torch-runtime]`` extra
+(``torch==2.9.1+cu128``) could never resolve: ``uv pip compile`` reports it
+unsatisfiable without this index and resolves it with it. One definition here,
+imported by the one-click installer and by the engine's own bootstrap, so the
+two cannot drift apart again. ``tests/test_sidecar_install.py`` pins the URL
+to the ``pytorch-cuda`` index declared in the app's ``pyproject.toml``.
+"""
+
+PYTORCH_CU128_INDEX_URL = "https://download.pytorch.org/whl/cu128"
+
+# `unsafe-best-match`: the PyTorch index also mirrors common dependencies
+# (numpy, pillow, sympy, …) at a narrower range of versions than PyPI. uv's
+# default first-index strategy would stop at whichever index lists a name first
+# and could pin an old mirror copy or fail outright. The index is PyTorch's
+# official one, so the dependency-confusion risk the name warns about does not
+# apply to it.
+UV_PIP_CU128_ARGS: tuple[str, ...] = (
+    "--extra-index-url",
+    PYTORCH_CU128_INDEX_URL,
+    "--index-strategy",
+    "unsafe-best-match",
+)
+
+PYTORCH_CPU_INDEX_URL = "https://download.pytorch.org/whl/cpu"
+
+# For an engine that runs torch only on the CPU (PocketTTS). On Linux, PyPI's
+# torch is the CUDA build and pulls ~15 NVIDIA packages the engine never uses;
+# this index serves `+cpu` builds for Linux and Windows and the regular build
+# for macOS.
+UV_PIP_CPU_ARGS: tuple[str, ...] = (
+    "--extra-index-url",
+    PYTORCH_CPU_INDEX_URL,
+    "--index-strategy",
+    "unsafe-best-match",
+)

backend/core/version.py

@@ -24,7 +24,7 @@ from pathlib import Path
 # tests/test_app_version.py::test_all_version_files_in_lockstep and bumped by
 # release.yml's version-bump job, so it stays equal to
 # pyproject/tauri.conf/Cargo/package.json.
-_FALLBACK_VERSION = "0.5.0"
+_FALLBACK_VERSION = "0.5.2"
 
 
 def _fallback_version() -> str:

backend/engines/audiocpp/__init__.py

@@ -0,0 +1,590 @@
+"""audio.cpp TTS backend — Breeze-TTS-2 via a managed native server.
+
+audio.cpp (0xShug0/audio.cpp) is a pure-C++ ggml runtime: prebuilt
+``audiocpp_server`` binaries for Windows/macOS/Linux, no Python venv, no
+``transformers`` pin — so this engine needs neither the venv-isolation
+(``engines.dots_tts``) nor the per-generate CLI-spawn (``engines
+.omnivoice_gguf``) patterns. The parent instead:
+
+1. resolves the binary + GGUF model (``bootstrap.py``),
+2. spawns ONE long-lived ``audiocpp_server`` on 127.0.0.1 (lazy model load,
+   so model memory is only held after the first generate), and
+3. speaks its OpenAI-style ``POST /v1/audio/speech`` per generate.
+
+v1 serves the ``breeze_tts`` family only (Breeze-TTS-2, en+zh, voice clone
++ voice design + voice direction). The server is task-agnostic on the
+speech route — reference-audio presence selects clone/direction vs design —
+so a single ``task: tts`` model entry covers all three modes.
+
+License honesty: Breeze-TTS-2 weights (``BreezeBlue/Breeze-TTS-2`` and the
+audio.cpp GGUF repack) are RESEARCH AND NON-COMMERCIAL ONLY
+(``BreezeBlue Research and Non-Commercial License``); only the audio.cpp
+code is Apache-2.0. There is no in-tree acceptance dialog for this engine
+yet (settings ``/license`` allow-list), so the restriction is surfaced in
+the display name, the install hint, and ``docs/engines/audio-cpp.md`` —
+not silently.
+"""
+from __future__ import annotations
+
+import atexit
+import base64
+import io
+import json
+import logging
+import os
+import secrets
+
+# Used only for stream constants; spawn_owned performs the process launch.
+import subprocess  # nosec B404
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from core.contained_subprocess import spawn_owned
+from services.tts_backend import TTSBackend, TTSInputError
+
+if TYPE_CHECKING:
+    import torch
+
+logger = logging.getLogger("omnivoice.audiocpp")
+
+#: Engine id in the TTS registry.
+ENGINE_ID = "audiocpp"
+
+#: How long to wait for ``/health`` after spawning the server (first spawn
+#: extracts nothing heavy — the model loads lazily on first generate).
+_HEALTH_TIMEOUT_S = 120.0
+
+#: Finish the inner HTTP request before the canonical generation guard can
+#: abandon its worker thread. This leaves enough time to terminate the owned
+#: native process and release its model memory synchronously.
+_TERMINATE_GRACE_S = 5.0
+_TERMINATE_KILL_S = 5.0
+_GENERATE_TIMEOUT_MARGIN_S = (
+    _TERMINATE_GRACE_S + _TERMINATE_KILL_S + 5.0
+)
+
+
+# ── pure request/config builders (unit-tested, no I/O) ──────────────────────
+
+
+def _cpu_thread_count() -> int:
+    """Use up to 16 physical cores, with a stdlib fallback."""
+    try:
+        import psutil
+
+        cores = psutil.cpu_count(logical=False)
+    except (ImportError, OSError):
+        cores = None
+    return min(16, max(1, cores or os.cpu_count() or 1))
+
+
+def _device_min_vram_gb(device) -> float:
+    """Dedicated-memory comfort floor for one discovered native device."""
+    return 6.0 if (
+        device
+        and device.kind == "GPU"
+        and (
+            device.backend == "vulkan"
+            or device.hardware_family in {"cuda", "rocm"}
+        )
+    ) else 0.0
+
+
+def build_server_config(
+    *, model_id: str, family: str, model_path: str, port: int,
+    backend: str = "cpu", device: int = 0,
+    execution_target: str | None = None,
+) -> dict:
+    """``server.json`` dict for the managed ``audiocpp_server``.
+
+    ``lazy_load`` defers the ~4.73 GiB GGUF load to the first generate;
+    ``max_loaded_models: 1`` bounds residency to the one model we serve.
+    """
+    return {
+        "host": "127.0.0.1",
+        "port": port,
+        "backend": backend,
+        "device": device,
+        # The pinned CPU runtime scales strongly through 16 workers while
+        # producing byte-identical audio.
+        "threads": _cpu_thread_count()
+        if (execution_target or backend) == "cpu" else 1,
+        "lazy_load": True,
+        "max_loaded_models": 1,
+        "models": [
+            {
+                "id": model_id,
+                "family": family,
+                "path": model_path,
+                "task": "tts",
+                "mode": "offline",
+            }
+        ],
+    }
+
+
+def build_speech_payload(
+    *, model_id: str, text: str, ref_audio: str | None = None,
+    ref_text: str | None = None, instructions: str | None = None,
+    guidance_scale: float | None = None, seed: int | None = None,
+) -> dict:
+    """``POST /v1/audio/speech`` JSON body.
+
+    Field spellings verified against ``app/server/runtime.cpp``
+    (``build_speech_request``): ``instructions`` (plural, OpenAI spelling)
+    feeds the ``instruction`` request option; ``reference_text`` and
+    ``guidance_scale``/``seed`` pass through top-level; ``voice_ref`` takes
+    a ``{"type": "path", ...}`` object so the reference stays on disk
+    (the 5 MiB base64 cap never bites). ``response_format: json`` returns
+    the WAV base64-in-JSON — one round trip, no binary framing.
+    """
+    payload: dict[str, Any] = {
+        "model": model_id,
+        "input": text,
+        "response_format": "json",
+    }
+    if instructions:
+        payload["instructions"] = instructions
+    if ref_audio:
+        payload["voice_ref"] = {"type": "path", "path": str(ref_audio)}
+        if ref_text:
+            payload["reference_text"] = ref_text
+    if guidance_scale is not None:
+        payload["guidance_scale"] = float(guidance_scale)
+    if seed is not None:
+        payload["seed"] = int(seed)
+    return payload
+
+
+def decode_speech_json(obj: dict) -> tuple[int, object]:
+    """``(sample_rate, mono float32 numpy)`` from a ``response_format=json``
+    speech body. Raises ``ValueError`` on a server error payload."""
+    if not isinstance(obj, dict):
+        raise TypeError(f"audio.cpp speech reply is not JSON: {obj!r:.120}")
+    if "audio" not in obj:
+        raise ValueError(f"audio.cpp speech failed: {obj.get('error', obj)!r:.300}")
+    import numpy as np
+    import soundfile as sf
+
+    wav_bytes = base64.b64decode(obj["audio"])
+    wav, sr = sf.read(io.BytesIO(wav_bytes), dtype="float32", always_2d=False)
+    wav = np.asarray(wav, dtype=np.float32)
+    if wav.ndim > 1:
+        wav = wav.mean(axis=-1)
+    return int(sr), wav
+
+
+# ── backend ─────────────────────────────────────────────────────────────────
+
+
+class AudioCPPBackend(TTSBackend):
+    """Breeze-TTS-2 through a parent-managed ``audiocpp_server``."""
+
+    id = ENGINE_ID
+    display_name = (
+        "audio.cpp · Breeze-TTS-2 (native GGUF, en+zh, clone+design; "
+        "weights research/non-commercial)"
+    )
+    supports_voice_design = True
+    applies_own_mastering = True  # model-decoded 24 kHz studio output
+    gpu_compat = ("cpu",)
+    runs_out_of_process = True
+    # Same marker SubprocessBackend sets: this engine lives in another OS
+    # process. Consumers only branch the matrix label and the self-test
+    # route (spawn-and-ping instead of in-process synth) — both correct
+    # here; nothing assumes the stdio protocol from it.
+    _is_subprocess_isolated = True
+    _DEFAULT_SAMPLE_RATE = 24000  # Breeze-TTS-2 native rate
+
+    def __init__(self) -> None:
+        self._proc: Any | None = None
+        self._port: int | None = None
+        self._server_model_id: str | None = None
+        self._sr = self._DEFAULT_SAMPLE_RATE
+        self._lock = threading.RLock()
+        self._server_json: Path | None = None
+        self._selection = None
+        self._device = None
+        self._provider = None
+
+    # ── availability ────────────────────────────────────────────────────
+
+    @classmethod
+    def is_available(cls) -> tuple[bool, str]:
+        from engines.audiocpp import bootstrap
+
+        try:
+            bootstrap.resolve_server_binary()
+            bootstrap.resolve_model_file()
+        except RuntimeError as exc:
+            return False, str(exc)
+        return True, "ready"
+
+    @classmethod
+    def runtime_compute_profile(cls, caps) -> dict:
+        from dataclasses import replace
+
+        from engines.audiocpp import bootstrap
+        from services.engine_routing import low_vram_caveat
+
+        try:
+            selection = bootstrap.resolve_compute_selection(caps)
+            targets = bootstrap.runtime_targets()
+        except RuntimeError as exc:
+            return {
+                "gpu_compat": cls.gpu_compat,
+                "min_vram_gb": 0.0,
+                "effective_device": "cpu",
+                "routing_status": "unavailable",
+                "routing_reason": str(exc),
+                "runtime_backend": None,
+                "runtime_device_index": None,
+                "runtime_device_name": None,
+                "runtime_hardware_family": None,
+                "runtime_vram_gb": None,
+                "runtime_device_verified": False,
+            }
+        selected = selection.device
+        accelerated = selected.target != "cpu"
+        min_vram_gb = _device_min_vram_gb(selected)
+        dedicated = min_vram_gb > 0
+        reason = selection.fallback_reason
+        if accelerated and dedicated and reason is None:
+            selected_caps = replace(
+                caps,
+                device_name=selected.name,
+                vram_gb=selection.verified_vram_gb,
+            )
+            reason = low_vram_caveat(
+                selected_caps,
+                min_vram_gb,
+                family=selected.hardware_family,
+                vram_gb=selection.verified_vram_gb,
+            )
+        status = "accelerated" if accelerated else (
+            "cpu_fallback" if selection.fallback_reason else "cpu_only"
+        )
+        return {
+            "gpu_compat": targets,
+            "min_vram_gb": min_vram_gb,
+            "effective_device": selected.target,
+            "routing_status": status,
+            "routing_reason": reason,
+            "runtime_backend": selected.backend,
+            "runtime_device_index": selected.index,
+            "runtime_device_name": selected.name,
+            "runtime_hardware_family": selected.hardware_family,
+            "runtime_vram_gb": selection.verified_vram_gb,
+            "runtime_device_verified": selection.verified_vram_gb > 0,
+        }
+
+    # ── TTSBackend protocol ─────────────────────────────────────────────
+
+    @property
+    def sample_rate(self) -> int:
+        return self._sr
+
+    @property
+    def supported_languages(self) -> list[str]:
+        return ["en", "zh"]
+
+    def model_identity(self) -> str | None:
+        from engines.audiocpp import bootstrap
+
+        return f"{bootstrap.FAMILY}/{bootstrap.package_filename()}"
+
+    # ── server lifecycle ────────────────────────────────────────────────
+
+    def _base_url(self) -> str:
+        return f"http://127.0.0.1:{self._port}"
+
+    def _ensure_loaded(self) -> None:
+        """Spawn the server (once) and wait for ``/health``. Idempotent."""
+        with self._lock:
+            if self._proc is not None and self._proc.poll() is None:
+                return
+            self._proc = None  # stale handle — respawn below
+            from engines.audiocpp import bootstrap
+
+            binary = bootstrap.resolve_server_binary()
+            selection = bootstrap.resolve_compute_selection()
+            model_file = bootstrap.resolve_model_file()
+            self._port = bootstrap.server_port()
+            # The random model id is a per-launch challenge. Before sending
+            # speech text or a reference path, _verify_server_identity asks
+            # /v1/models to prove this is the child configured by this process,
+            # not an unrelated listener that pre-bound the loopback port.
+            self._server_model_id = f"{bootstrap.MODEL_ID}-{secrets.token_hex(16)}"
+            config = build_server_config(
+                model_id=self._server_model_id,
+                family=bootstrap.FAMILY,
+                model_path=str(model_file),
+                port=self._port,
+                backend=selection.device.backend,
+                device=selection.device.index,
+                execution_target=selection.device.target,
+            )
+            self._selection = selection
+            self._device = selection.device.target
+            self._provider = selection.device.backend
+            from core.config import DATA_DIR
+
+            workdir = Path(str(DATA_DIR)) / "audiocpp"
+            workdir.mkdir(parents=True, exist_ok=True)
+            self._server_json = workdir / "server.json"
+            flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+            config_fd = os.open(self._server_json, flags, 0o600)
+            try:
+                if os.name != "nt":
+                    os.fchmod(config_fd, 0o600)
+                with os.fdopen(config_fd, "w", encoding="utf-8") as config_fh:
+                    config_fd = -1
+                    json.dump(config, config_fh, indent=2)
+            finally:
+                if config_fd >= 0:
+                    os.close(config_fd)
+            log_path = workdir / "server.log"
+            logger.info(
+                "audio.cpp: starting %s (backend=%s, device=%d, port=%d, model=%s)",
+                binary.name, selection.device.backend, selection.device.index,
+                self._port, model_file.name,
+            )
+            with open(log_path, "ab") as log_fh:
+                self._proc = spawn_owned(
+                    [str(binary), "--config", str(self._server_json)],
+                    stdout=log_fh,
+                    stderr=subprocess.STDOUT,
+                    stdin=subprocess.DEVNULL,
+                )
+            atexit.register(self._terminate_server)
+            self._wait_for_health()
+
+    def _wait_for_health(self) -> None:
+        if self._proc is None or self._port is None:
+            raise RuntimeError("managed audio.cpp server was not started")
+        deadline = time.monotonic() + _HEALTH_TIMEOUT_S
+        last_err = "unknown"
+        url = self._base_url() + "/health"
+        while time.monotonic() < deadline:
+            if self._proc.poll() is not None:
+                raise RuntimeError(
+                    "audiocpp_server exited during startup "
+                    f"(code {self._proc.returncode}). See the server log next "
+                    "to server.json under the app data audiocpp/ directory — "
+                    "the managed port may already be in use."
+                )
+            try:
+                # ``url`` is always the hard-coded loopback host plus a
+                # validated integer port; arbitrary schemes are impossible.
+                with urllib.request.urlopen(url, timeout=5) as resp:  # nosec B310
+                    if resp.status == 200:
+                        self._verify_server_identity()
+                        if self._proc.poll() is None:
+                            logger.info(
+                                "audio.cpp: managed server is healthy on loopback"
+                            )
+                            return
+                    last_err = f"HTTP {resp.status}"
+            except Exception as exc:  # noqa: BLE001 — still starting; retry
+                last_err = f"{type(exc).__name__}: {exc}"
+            time.sleep(1.0)
+        self._terminate_server()
+        raise RuntimeError(
+            f"audiocpp_server did not become healthy within "
+            f"{_HEALTH_TIMEOUT_S:.0f}s (last: {last_err})."
+        )
+
+    def _get_json(self, path: str, timeout: float = 5.0) -> dict:
+        """GET one loopback JSON endpoint without sending request content."""
+        if self._port is None:
+            raise RuntimeError("managed audio.cpp server port is missing")
+        req = urllib.request.Request(self._base_url() + path, method="GET")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+            obj = json.loads(resp.read().decode("utf-8"))
+        if not isinstance(obj, dict):
+            raise TypeError("audio.cpp returned an invalid JSON response")
+        return obj
+
+    def _verify_server_identity(self) -> None:
+        """Prove the loopback listener owns this launch's random model id."""
+        if self._proc is None or self._proc.poll() is not None:
+            raise RuntimeError("managed audio.cpp server is not running")
+        expected = self._server_model_id
+        if not expected:
+            raise RuntimeError("managed audio.cpp server identity is missing")
+        obj = self._get_json("/v1/models")
+        data = obj.get("data", [])
+        if not isinstance(data, list):
+            raise TypeError("managed audio.cpp server identity is invalid")
+        model_ids = {
+            item.get("id") for item in data
+            if isinstance(item, dict)
+        }
+        if expected not in model_ids or self._proc.poll() is not None:
+            raise RuntimeError(
+                "loopback listener did not prove managed audio.cpp ownership"
+            )
+
+    def _post_json(self, path: str, payload: dict, timeout: float) -> dict:
+        """Verify child ownership, then POST JSON to the managed server."""
+        if self._port is None:
+            raise RuntimeError("managed audio.cpp server port is missing")
+        self._verify_server_identity()
+        body = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            self._base_url() + path,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            # ``req`` targets only ``_base_url()`` (127.0.0.1 + validated
+            # integer port), never a caller-provided URL.
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:500]
+            raise RuntimeError(
+                f"audio.cpp {path} failed (HTTP {exc.code}): {detail}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            if isinstance(exc.reason, TimeoutError):
+                raise TimeoutError("audio.cpp request timed out") from exc
+            raise
+
+    def _terminate_server(self) -> None:
+        proc, self._proc = self._proc, None
+        self._server_model_id = None
+        if proc is None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout=_TERMINATE_GRACE_S)
+        except Exception:  # noqa: BLE001 — kill as last resort, never raise
+            try:
+                proc.kill()
+                proc.wait(timeout=_TERMINATE_KILL_S)
+            except Exception as exc:  # noqa: BLE001 — process is already failing
+                logger.debug("audio.cpp: final server kill failed: %s", exc)
+
+    # ── generate ────────────────────────────────────────────────────────
+
+    def generate(self, text: str, **kw) -> torch.Tensor:
+        import torch
+        from services.model_manager import (
+            GENERATE_PROGRESS_GRACE_S,
+            generate_timeout_s,
+            report_generate_progress,
+        )
+
+        if not text or not text.strip():
+            raise TTSInputError(
+                "audio.cpp: the input contains no speakable text — "
+                "send at least one word."
+            )
+        ref_audio = kw.get("ref_audio")
+        ref_text = kw.get("ref_text")
+        if ref_text and not ref_audio:
+            logger.info(
+                "audio.cpp: ref_text supplied without ref_audio; ignoring."
+            )
+            ref_text = None
+
+        # Voice design: our `description=` (no ref) and voice direction
+        # (`instruct=` + ref) both ride the server's `instructions` field —
+        # verified spelling against app/server/runtime.cpp.
+        instruct = kw.get("instruct") or kw.get("description") or None
+
+        language = kw.get("language")
+        if language and str(language).strip().lower() not in {
+            "auto", "en", "english", "zh", "chinese",
+        }:
+            logger.info(
+                "audio.cpp (Breeze-TTS-2) is en+zh only; ignoring "
+                "language=%r.", language,
+            )
+        if kw.get("speed", 1.0) != 1.0:
+            logger.info("audio.cpp: speed is not supported; ignoring.")
+
+        request_started = time.monotonic()
+        with self._lock:
+            self._ensure_loaded()
+            selected = self._selection.device if self._selection else None
+            min_vram_gb = _device_min_vram_gb(selected)
+            request_budget = generate_timeout_s(
+                text,
+                execution_device=selected.target if selected else "cpu",
+                min_vram_gb=min_vram_gb,
+                hardware_family=selected.hardware_family if selected else None,
+                vram_gb=self._selection.verified_vram_gb
+                if self._selection else 0.0,
+            )
+            if not self._server_model_id:
+                raise RuntimeError("managed audio.cpp server identity is missing")
+            payload = build_speech_payload(
+                model_id=self._server_model_id,
+                text=text,
+                ref_audio=str(ref_audio) if ref_audio else None,
+                ref_text=ref_text,
+                instructions=instruct,
+                guidance_scale=kw.get("guidance_scale", 1.0),
+                seed=kw.get("seed"),
+            )
+            # Device discovery and server startup can consume part of the soft
+            # budget. This fresh synthesis lease gives the lazy model load and
+            # request a bounded window. The inner request always expires early
+            # enough to reap the owned server before the outer guard abandons us.
+            report_generate_progress()
+            soft_remaining = request_budget - (time.monotonic() - request_started)
+            timeout = (
+                max(soft_remaining, GENERATE_PROGRESS_GRACE_S)
+                - _GENERATE_TIMEOUT_MARGIN_S
+            )
+            if timeout <= 0:
+                self._terminate_server()
+                raise TimeoutError(
+                    "audio.cpp startup exhausted the generation time budget"
+                )
+            try:
+                obj = self._post_json(
+                    "/v1/audio/speech", payload, timeout=timeout,
+                )
+            except TimeoutError:
+                self._terminate_server()
+                raise RuntimeError(
+                    "audio.cpp generation timed out; its managed server was reset"
+                ) from None
+        sr, wav_np = decode_speech_json(obj)
+        self._sr = sr
+        wav = torch.from_numpy(wav_np).float()
+        if wav.ndim == 0:
+            raise RuntimeError("audio.cpp produced empty audio")
+        return wav.unsqueeze(0)
+
+    # ── lifecycle ───────────────────────────────────────────────────────
+
+    def unload(self) -> None:
+        """Free the model server-side, then stop it. Idempotent."""
+        with self._lock:
+            if self._port is not None and self._proc is not None \
+                    and self._proc.poll() is None:
+                try:
+                    self._post_json("/v1/tasks/unload_all_models", {}, timeout=30)
+                except Exception as exc:  # noqa: BLE001 — best effort
+                    logger.warning("audio.cpp: server unload failed: %s", exc)
+            self._port = None
+            self._terminate_server()
+        super().unload()
+
+
+__all__ = [
+    "ENGINE_ID",
+    "AudioCPPBackend",
+    "build_server_config",
+    "build_speech_payload",
+    "decode_speech_json",
+]

backend/engines/audiocpp/bootstrap.py

@@ -0,0 +1,738 @@
+"""audio.cpp binary probe + model resolution.
+
+audio.cpp (0xShug0/audio.cpp) is a pure-C++ ggml inference engine with
+prebuilt release binaries — no Python venv, no ``transformers`` pin, so
+none of the dependency-isolation machinery in ``engines._venv_probe`` or
+``services.subprocess_backend`` applies. The parent instead:
+
+1. locates a user-installed ``audiocpp_server`` (env var, user dir, or this
+   package's ``bin/``), and
+2. resolves an explicitly installed GGUF model file from a direct path or
+   the shared Hugging Face cache.
+
+Probe order for the server binary (existing installs win, zero migration):
+
+    1. ``${OMNIVOICE_AUDIOCPP_BIN}`` — absolute path to the binary itself.
+    2. ``${OMNIVOICE_AUDIOCPP_DIR}/audiocpp_server[.exe]`` — a user-managed
+       install dir (e.g. an extracted release zip, or a self-built tree).
+    3. ``backend/engines/audiocpp/bin/audiocpp_server[.exe]`` — an explicitly
+       installed local copy.
+
+``is_installed()`` is a cheap file-existence check — no spawn, no network.
+VoiceStudio never downloads executable code for this engine.
+"""
+from __future__ import annotations
+
+import errno
+import functools
+import logging
+import os
+import platform
+import subprocess  # nosec B404 -- fixed argv probes a user-selected executable
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger("omnivoice.audiocpp.bootstrap")
+
+#: Pinned audio.cpp release. BreezeTTS-2 support landed in 0.7.2 — older
+#: binaries have no ``breeze_tts`` family, so the floor is also the pin.
+VERSION = "v0.7.2"
+
+#: GitHub repo serving the prebuilt binaries.
+GH_REPO = "0xShug0/audio.cpp"
+
+#: HuggingFace repo serving the GGUF model packages (not gated).
+HF_MODEL_REPO = "audio-cpp/audio.cpp-gguf"
+
+# Immutable repository revision used for the v0.7.2 Breeze-TTS-2 package.
+# Pinning prevents a later upstream file replacement from silently changing
+# the model exercised by this backend.
+HF_MODEL_REVISION = "dc6fecccc2b0c6bdda0a8b2f38fa61394fee0b9c"
+
+#: Model id used in the generated ``server.json`` and in speech requests.
+MODEL_ID = "breeze-tts-2"
+
+#: audio.cpp family name for BreezeTTS 2 (``--family`` / server ``family``).
+FAMILY = "breeze_tts"
+
+#: GGUF package directory inside :data:`HF_MODEL_REPO`.
+PACKAGE_DIR = "Breeze-TTS-2-GGUF"
+
+#: Default package (Q8_0, the upstream-recommended GGUF). ``bf16`` is
+#: available via ``OMNIVOICE_AUDIOCPP_PACKAGE``.
+DEFAULT_PACKAGE = "breeze-tts-2-q8_0.gguf"
+
+#: Env var pointing directly at the ``audiocpp_server`` binary.
+BIN_ENV = "OMNIVOICE_AUDIOCPP_BIN"
+
+#: Env var pointing at a directory containing ``audiocpp_server``.
+DIR_ENV = "OMNIVOICE_AUDIOCPP_DIR"
+
+#: Env var overriding the GGUF package filename (e.g. the bf16 package).
+PACKAGE_ENV = "OMNIVOICE_AUDIOCPP_PACKAGE"
+
+#: Optional advanced overrides for a binary that exposes several runtimes or
+#: devices. Device indices are local to the selected backend registry.
+BACKEND_ENV = "OMNIVOICE_AUDIOCPP_BACKEND"
+DEVICE_ENV = "OMNIVOICE_AUDIOCPP_DEVICE"
+
+#: Env var overriding the loopback port the managed server binds.
+PORT_ENV = "OMNIVOICE_AUDIOCPP_PORT"
+
+#: Default loopback port. High and engine-specific to avoid clashing with
+#: the app itself or a user-run ``audiocpp_server`` (default 8080).
+DEFAULT_PORT = 17860
+
+#: This package's owned binary dir (probe 3).
+_PKG_BIN_DIR: Path = Path(__file__).parent / "bin"
+
+# Recommended (asset filename, sha256) per platform slug, from the v0.7.2
+# release. Windows and Linux use the vendor-neutral Vulkan build, which also
+# exposes the native CPU backend. Upstream publishes the macOS builds under
+# the Metal package name. No linux-aarch64 prebuilt exists in v0.7.2.
+_ASSETS: dict[str, tuple[str, str]] = {
+    "windows-x64": (
+        "audio-v0.7.2-bin-windows-x64-vulkan.zip",
+        "15b8232eae740e21e507d87f827a89966de9451b085a45932d9e214e032962c1",
+    ),
+    "linux-x64": (
+        "audio-v0.7.2-bin-ubuntu-x64-vulkan.tar.gz",
+        "fee1f978cee76453cf17f00196554bc2ee294645739538af0726a143b6a69a23",
+    ),
+    "darwin-arm64": (
+        "audio-v0.7.2-bin-macos-arm64-metal.tar.gz",
+        "c01e4f82971bedbe341697e63a9cebd5a5d1f72d5a9bcb51a3191f95ddab7a95",
+    ),
+    "darwin-x64": (
+        "audio-v0.7.2-bin-macos-x64-metal.tar.gz",
+        "3862270f33439077225324169313f727064f727305b54d8ce920244d75ddcc24",
+    ),
+}
+
+#: Binary filename per platform.
+_BINARY_NAMES = {"windows-x64": "audiocpp_server.exe"}
+
+_REGISTRY_BACKENDS = {
+    "CPU": "cpu",
+    "CUDA": "cuda",
+    "MUSA": "cuda",
+    "HIP": "hip",
+    "ROCm": "hip",
+    "Vulkan": "vulkan",
+    "Metal": "metal",
+    "MTL": "metal",
+}
+_BACKEND_ALIASES = {
+    "cpu": "cpu",
+    "cuda": "cuda",
+    "hip": "hip",
+    "rocm": "hip",
+    "vulkan": "vulkan",
+    "metal": "metal",
+}
+
+
+@dataclass(frozen=True)
+class AudioCPPDevice:
+    """One immutable device from audio.cpp's backend-local registry."""
+
+    registry: str
+    backend: str
+    index: int
+    name: str
+    kind: str
+    target: str
+    hardware_family: str
+
+
+@dataclass(frozen=True)
+class AudioCPPSelection:
+    """The runtime/device chosen for the next managed server."""
+
+    device: AudioCPPDevice
+    fallback_reason: str | None = None
+    verified_vram_gb: float = 0.0
+
+
+@dataclass(frozen=True)
+class _ProbeOutcome:
+    devices: tuple[AudioCPPDevice, ...] = ()
+    error: str | None = None
+
+
+def _cpu_probe_fallback(error: RuntimeError) -> AudioCPPSelection:
+    """A usable automatic fallback when native device discovery fails."""
+    return AudioCPPSelection(
+        AudioCPPDevice(
+            registry="CPU",
+            backend="cpu",
+            index=0,
+            name="Host CPU",
+            kind="CPU",
+            target="cpu",
+            hardware_family="cpu",
+        ),
+        f"{error}; running on CPU",
+    )
+
+
+def _vulkan_hardware_family(name: str) -> str:
+    low = name.casefold()
+    if any(token in low for token in ("nvidia", "geforce", "quadro", "tesla")):
+        return "cuda"
+    if any(token in low for token in ("amd", "radeon")):
+        return "rocm"
+    if any(token in low for token in ("intel", "arc ")):
+        return "xpu"
+    return "vulkan"
+
+
+def _device_families(registry: str, name: str, kind: str) -> tuple[str, str]:
+    # Software adapters such as Vulkan llvmpipe may be listed by a GPU
+    # registry but still execute on the CPU. Keep their runtime backend for
+    # explicit overrides while reporting and routing them as CPU work.
+    if kind == "CPU":
+        return "cpu", "cpu"
+    if registry in {"CUDA", "MUSA"}:
+        return "cuda", "cuda"
+    if registry in {"HIP", "ROCm"}:
+        return "rocm", "rocm"
+    if registry in {"Metal", "MTL"}:
+        return "mps", "mps"
+    if registry == "Vulkan":
+        return "vulkan", _vulkan_hardware_family(name)
+    return "cpu", "cpu"
+
+
+def parse_device_list(output: str) -> tuple[AudioCPPDevice, ...]:
+    """Parse the stable stdout contract of ``--list-devices``.
+
+    Backend diagnostics are emitted on stderr and deliberately never enter
+    this parser. Unknown future registries are ignored; malformed entries for
+    a registry we understand fail closed instead of selecting the wrong GPU.
+    """
+    devices: list[AudioCPPDevice] = []
+    seen: set[tuple[str, int]] = set()
+    for raw in str(output or "").splitlines():
+        line = raw.strip()
+        registry, colon, detail = line.partition(":")
+        if not colon or registry not in _REGISTRY_BACKENDS:
+            continue
+        index_text, space, remainder = detail.strip().partition(" ")
+        if not space or not index_text.isascii() or not index_text.isdecimal():
+            raise RuntimeError(
+                f"malformed audio.cpp {registry} device entry"
+            )
+        index = int(index_text)
+        remainder = remainder.strip()
+        kind_start = remainder.rfind("[")
+        if kind_start < 0 or not remainder.endswith("]"):
+            raise RuntimeError(
+                f"malformed audio.cpp {registry} device entry"
+            )
+        name_field = remainder[:kind_start].strip()
+        if name_field:
+            if len(name_field) < 2 or name_field[0] != '"' or name_field[-1] != '"':
+                raise RuntimeError(
+                    f"malformed audio.cpp {registry} device entry"
+                )
+            name = name_field[1:-1]
+        else:
+            name = ""
+        kind = remainder[kind_start + 1:-1].strip().upper()
+        if kind not in {"CPU", "GPU", "IGPU", "ACCEL", "META"}:
+            raise RuntimeError("unknown audio.cpp device kind")
+        # Registry aliases such as HIP/ROCm share one backend-local index
+        # namespace and therefore cannot safely describe different devices.
+        key = (_REGISTRY_BACKENDS[registry], index)
+        if key in seen:
+            raise RuntimeError(
+                f"duplicate audio.cpp device entry: {registry}:{index}"
+            )
+        seen.add(key)
+        target, hardware_family = _device_families(registry, name, kind)
+        devices.append(AudioCPPDevice(
+            registry=registry,
+            backend=_REGISTRY_BACKENDS[registry],
+            index=index,
+            name=name,
+            kind=kind,
+            target=target,
+            hardware_family=hardware_family,
+        ))
+    if not devices:
+        raise RuntimeError("audio.cpp reported no recognized compute devices")
+    return tuple(devices)
+
+
+def _platform_slug() -> str:
+    system = sys.platform
+    machine = platform.machine().lower()
+    if system == "win32":
+        return "windows-x64"
+    if system == "darwin":
+        return "darwin-arm64" if machine in ("arm64", "aarch64") else "darwin-x64"
+    if machine in ("x86_64", "amd64"):
+        return "linux-x64"
+    return f"linux-{machine}"
+
+
+def binary_name(slug: str | None = None) -> str:
+    """``audiocpp_server`` filename for ``slug`` (``.exe`` on Windows)."""
+    return _BINARY_NAMES.get(slug or _platform_slug(), "audiocpp_server")
+
+
+def _probe_paths() -> list[Path]:
+    out: list[Path] = []
+    direct = os.environ.get(BIN_ENV, "").strip()
+    if direct:
+        out.append(Path(direct))
+    user_dir = os.environ.get(DIR_ENV, "").strip()
+    if user_dir:
+        out.append(Path(user_dir) / binary_name())
+    out.append(_PKG_BIN_DIR / binary_name())
+    return out
+
+
+def is_installed() -> bool:
+    """Cheap precedence-aware check for a usable server binary."""
+    try:
+        resolve_server_binary()
+    except RuntimeError:
+        return False
+    return True
+
+
+def resolve_server_binary() -> Path:
+    """Resolve the ``audiocpp_server`` binary. Raises ``RuntimeError`` with
+    install instructions when none is found."""
+    for cand in _probe_paths():
+        if cand.is_file():
+            if os.name == "nt" or os.access(cand, os.X_OK):
+                return cand
+            raise RuntimeError(
+                "audiocpp_server is not executable. Run `chmod +x "
+                "audiocpp_server` on the configured binary, then restart "
+                "VoiceStudio. See docs/engines/audio-cpp.md."
+            )
+    slug = _platform_slug()
+    asset = _ASSETS.get(slug)
+    if asset is None:
+        raise RuntimeError(
+            f"audio.cpp ships no prebuilt binary for this platform ({slug}). "
+            "Build from https://github.com/0xShug0/audio.cpp and set "
+            f"{BIN_ENV} to your audiocpp_server binary. See "
+            "docs/engines/audio-cpp.md."
+        )
+    raise RuntimeError(
+        "audiocpp_server not found. Download "
+        f"https://github.com/{GH_REPO}/releases/download/{VERSION}/{asset[0]} "
+        f"(SHA-256 {asset[1]}), verify and extract it, and set {BIN_ENV} to the "
+        "audiocpp_server binary (or "
+        f"{DIR_ENV} to its directory). See docs/engines/audio-cpp.md."
+    )
+
+
+@functools.lru_cache(maxsize=4)
+def _probe_device_outcome(binary: str) -> _ProbeOutcome:
+    try:
+        proc = subprocess.run(  # nosec B603 -- executable is the resolved engine binary
+            [binary, "--list-devices"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return _ProbeOutcome(
+            error="audiocpp_server device discovery timed out after 10 seconds"
+        )
+    except OSError as exc:
+        return _ProbeOutcome(
+            error=(
+                "audiocpp_server device discovery could not start: "
+                f"{type(exc).__name__}"
+            )
+        )
+    if proc.returncode != 0:
+        return _ProbeOutcome(
+            error=(
+                "audiocpp_server device discovery failed "
+                f"(code {proc.returncode}). Check the audio.cpp server log "
+                "for details."
+            )
+        )
+    try:
+        return _ProbeOutcome(devices=parse_device_list(proc.stdout))
+    except RuntimeError as exc:
+        return _ProbeOutcome(error=str(exc))
+
+
+def _probe_devices(binary: str) -> tuple[AudioCPPDevice, ...]:
+    outcome = _probe_device_outcome(binary)
+    if outcome.error:
+        raise RuntimeError(outcome.error)
+    return outcome.devices
+
+
+def probe_devices() -> tuple[AudioCPPDevice, ...]:
+    """Return the installed binary's devices without loading a model."""
+    return _probe_devices(str(resolve_server_binary()))
+
+
+def _priority(device: AudioCPPDevice) -> tuple[int, int]:
+    if device.kind == "META":
+        # Tensor-parallel meta devices are valid explicit targets, but their
+        # resource footprint is not safe to choose implicitly over CPU.
+        rank = 8
+    elif device.backend != "cpu" and device.kind == "CPU":
+        # Native CPU is the predictable fallback. Software adapters remain
+        # available to an explicit backend override but never win auto mode.
+        rank = 7
+    elif device.backend == "cuda":
+        rank = 0
+    elif device.backend == "hip":
+        rank = 1
+    elif device.backend == "metal":
+        rank = 2
+    elif device.backend == "vulkan" and device.kind == "GPU":
+        rank = 3
+    elif device.backend == "vulkan" and device.kind in {"IGPU", "ACCEL"}:
+        rank = 4
+    elif device.backend == "cpu":
+        rank = 6
+    else:
+        rank = 5
+    return rank, device.index
+
+
+def select_device(
+    devices: tuple[AudioCPPDevice, ...],
+    *,
+    requested_family: str = "auto",
+    backend_override: str | None = None,
+    device_override: int | None = None,
+    preferred_name: str = "",
+) -> AudioCPPSelection:
+    """Resolve one device with explicit overrides and discrete-GPU priority."""
+    if backend_override:
+        normalized = _BACKEND_ALIASES.get(backend_override.strip().lower())
+        if normalized is None:
+            valid = ", ".join(_BACKEND_ALIASES)
+            raise RuntimeError(
+                f"unknown audio.cpp backend '{backend_override}' (valid: {valid})"
+            )
+        candidates = [device for device in devices if device.backend == normalized]
+        if device_override is not None:
+            candidates = [
+                device for device in candidates if device.index == device_override
+            ]
+        if not candidates:
+            suffix = "" if device_override is None else f" device {device_override}"
+            available = ", ".join(
+                f"{device.backend}:{device.index}" for device in devices
+            )
+            raise RuntimeError(
+                f"audio.cpp backend '{backend_override}'{suffix} is unavailable "
+                f"(available: {available})"
+            )
+        # An explicit runtime request should still prefer a compute device to
+        # a software adapter when no backend-local index was supplied. META is
+        # valid here because the user explicitly chose this registry.
+        return AudioCPPSelection(min(
+            candidates,
+            key=lambda device: (device.kind == "CPU", _priority(device)),
+        ))
+
+    if device_override is not None:
+        raise RuntimeError(
+            f"{DEVICE_ENV} requires {BACKEND_ENV} because device indices are "
+            "backend-local"
+        )
+
+    family = (requested_family or "auto").strip().lower()
+    if family != "auto":
+        candidates = [
+            device for device in devices if device.hardware_family == family
+        ]
+        if candidates:
+            preferred = preferred_name.casefold().strip()
+            if preferred:
+                named = [
+                    device for device in candidates
+                    if device.name
+                    and (
+                        preferred in device.name.casefold()
+                        or device.name.casefold() in preferred
+                    )
+                ]
+                if named:
+                    candidates = named
+            return AudioCPPSelection(min(candidates, key=_priority))
+        cpu = [device for device in devices if device.backend == "cpu"]
+        if cpu:
+            return AudioCPPSelection(
+                min(cpu, key=_priority),
+                f"requested {family.upper()} device is not exposed by the "
+                "installed audio.cpp binary; running on CPU",
+            )
+        raise RuntimeError(
+            f"requested {family.upper()} device is not exposed by the "
+            "installed audio.cpp binary"
+        )
+
+    return AudioCPPSelection(min(devices, key=_priority))
+
+
+def resolve_compute_selection(caps=None) -> AudioCPPSelection:
+    """Select the runtime from engine env overrides, Settings, then auto."""
+    backend_override = os.environ.get(BACKEND_ENV, "").strip() or None
+    raw_device = os.environ.get(DEVICE_ENV, "").strip()
+    device_override: int | None = None
+    if raw_device:
+        try:
+            device_override = int(raw_device)
+        except ValueError as exc:
+            raise RuntimeError(
+                f"{DEVICE_ENV} must be a non-negative integer"
+            ) from exc
+        if device_override < 0:
+            raise RuntimeError(f"{DEVICE_ENV} must be a non-negative integer")
+
+    if caps is None:
+        from core.device_caps import detect_host_caps
+
+        caps = detect_host_caps()
+    requested = getattr(caps, "requested_family", "auto") or "auto"
+    try:
+        devices = probe_devices()
+    except RuntimeError as exc:
+        if backend_override or raw_device or requested != "auto":
+            raise
+        return _cpu_probe_fallback(exc)
+    selection = select_device(
+        devices,
+        requested_family=requested,
+        backend_override=backend_override,
+        device_override=device_override,
+        preferred_name=getattr(caps, "device_name", "") or "",
+    )
+    # HostCaps measures the preferred accelerator's device 0. Reuse that VRAM
+    # only when the selected native registry has exactly one device with the
+    # same normalized name. Multi-GPU peers with identical names stay unknown.
+    selected_name = " ".join(selection.device.name.casefold().split())
+    host_name = " ".join(
+        str(getattr(caps, "device_name", "") or "").casefold().split()
+    )
+    peers = [
+        device for device in devices
+        if device.backend == selection.device.backend
+        and " ".join(device.name.casefold().split()) == host_name
+    ]
+    if (
+        selected_name
+        and selected_name == host_name
+        and len(peers) == 1
+        and float(getattr(caps, "vram_gb", 0.0) or 0.0) > 0
+    ):
+        return AudioCPPSelection(
+            selection.device,
+            selection.fallback_reason,
+            float(caps.vram_gb),
+        )
+    return selection
+
+
+def runtime_targets(devices: tuple[AudioCPPDevice, ...] | None = None) -> tuple[str, ...]:
+    """Actual compute backends compiled into the selected binary."""
+    if devices is not None:
+        found = devices
+    else:
+        try:
+            found = probe_devices()
+        except RuntimeError:
+            if (
+                os.environ.get(BACKEND_ENV, "").strip()
+                or os.environ.get(DEVICE_ENV, "").strip()
+            ):
+                raise
+            return ("cpu",)
+    ordered: list[str] = []
+    for device in sorted(found, key=_priority):
+        if device.target not in ordered:
+            ordered.append(device.target)
+    return tuple(ordered)
+
+
+def invalidate() -> None:
+    """Forget cached binary capability discovery after an install change."""
+    _probe_device_outcome.cache_clear()
+
+
+def default_asset() -> tuple[str, str] | None:
+    """``(filename, sha256)`` of the release asset for this host, or None
+    when upstream ships no prebuilt for it."""
+    return _ASSETS.get(_platform_slug())
+
+
+def server_port() -> int:
+    """Loopback port for the managed server (env override or default)."""
+    raw = os.environ.get(PORT_ENV, "").strip()
+    if raw:
+        try:
+            port = int(raw)
+            if 1 <= port <= 65535:
+                return port
+            logger.warning("Ignoring %s=%r: out of range.", PORT_ENV, raw)
+        except ValueError:
+            logger.warning("Ignoring %s=%r: not a number.", PORT_ENV, raw)
+    return DEFAULT_PORT
+
+
+def package_filename() -> str:
+    """GGUF package filename (env override or the Q8_0 default)."""
+    return os.environ.get(PACKAGE_ENV, "").strip() or DEFAULT_PACKAGE
+
+
+def _materialize_gguf_cache_path(model_file: Path) -> Path:
+    """Return a real ``.gguf`` path when the HF snapshot is a symlink.
+
+    audio.cpp canonicalizes model paths before inspecting the suffix. The
+    Hugging Face cache points the friendly ``.gguf`` snapshot name at an
+    extensionless content-addressed blob, so passing that symlink makes the
+    server reject a valid model. A hard link beside the snapshot keeps the
+    required suffix without copying a multi-gigabyte model or escaping the
+    snapshot's cleanup lifecycle.
+    """
+    resolved = model_file.resolve()
+    if resolved.suffix.lower() == ".gguf":
+        return model_file
+    if model_file.suffix.lower() != ".gguf":
+        raise RuntimeError(f"audio.cpp model must be a .gguf file: {model_file}")
+
+    def _link(alias: Path) -> Path:
+        for attempt in range(2):
+            try:
+                os.link(resolved, alias)
+            except FileExistsError:
+                if (
+                    not alias.is_symlink()
+                    and alias.is_file()
+                    and os.path.samefile(resolved, alias)
+                ):
+                    return alias
+                if attempt == 0 and alias.is_symlink():
+                    alias.unlink()
+                    continue
+                raise RuntimeError(
+                    f"audio.cpp model alias points at a different file: {alias}"
+                ) from None
+            return alias
+        raise RuntimeError(f"audio.cpp model alias could not be created: {alias}")
+
+    alias = model_file.with_name(
+        f".{model_file.stem}-{HF_MODEL_REVISION[:12]}.audiocpp.gguf"
+    )
+    try:
+        return _link(alias)
+    except OSError as exc:
+        if exc.errno == errno.EXDEV:
+            # An explicit symlink may live on a different filesystem from its
+            # target. Put the suffix-preserving hard link beside the resolved
+            # file so no multi-gigabyte copy is needed.
+            target_alias = resolved.with_name(
+                f".{resolved.name}-{HF_MODEL_REVISION[:12]}.audiocpp.gguf"
+            )
+            try:
+                return _link(target_alias)
+            except OSError as target_exc:
+                exc = target_exc
+        raise RuntimeError(
+            "audio.cpp cannot materialize the Hugging Face cache symlink as "
+            f"a .gguf hard link: {exc}"
+        ) from exc
+
+
+def resolve_model_file() -> Path:
+    """Resolve an explicitly installed Breeze-TTS-2 GGUF file.
+
+    An explicit ``OMNIVOICE_AUDIOCPP_MODEL`` path wins (file or directory
+    containing the package file). Otherwise only the local Hugging Face cache
+    is inspected. Downloads must be started explicitly from Model Catalogue →
+    Models, so generation can never silently transfer the 4.73 GiB package.
+    """
+    override = os.environ.get("OMNIVOICE_AUDIOCPP_MODEL", "").strip()
+    if override:
+        cand = Path(override)
+        if cand.is_file():
+            return _materialize_gguf_cache_path(cand)
+        if cand.is_dir():
+            inner = cand / package_filename()
+            if inner.is_file():
+                return _materialize_gguf_cache_path(inner)
+        raise RuntimeError(
+            f"OMNIVOICE_AUDIOCPP_MODEL={override} is not a GGUF file or a "
+            "directory containing one."
+        )
+
+    from huggingface_hub import snapshot_download
+    from huggingface_hub.utils import LocalEntryNotFoundError
+
+    try:
+        cached = Path(
+            snapshot_download(
+                repo_id=HF_MODEL_REPO,
+                # Full immutable commit SHA declared above; Bandit cannot follow
+                # the module constant through this call.
+                revision=HF_MODEL_REVISION,  # nosec B615
+                allow_patterns=[f"{PACKAGE_DIR}/{package_filename()}"],
+                local_files_only=True,
+            )
+        )
+    except (LocalEntryNotFoundError, OSError) as exc:
+        raise RuntimeError(
+            "Breeze-TTS-2 is not installed. Install the audio.cpp Breeze-TTS-2 "
+            "model from Model Catalogue → Models, or set "
+            "OMNIVOICE_AUDIOCPP_MODEL to an existing GGUF file."
+        ) from exc
+    model_file = cached / PACKAGE_DIR / package_filename()
+    if not model_file.is_file():
+        raise RuntimeError(
+            f"Breeze-TTS-2 package {package_filename()} is not completely "
+            "installed. Reinstall it from Model Catalogue → Models."
+        )
+    return _materialize_gguf_cache_path(model_file)
+
+
+__all__ = [
+    "AudioCPPDevice",
+    "AudioCPPSelection",
+    "BACKEND_ENV",
+    "BIN_ENV",
+    "DEFAULT_PACKAGE",
+    "DEFAULT_PORT",
+    "DEVICE_ENV",
+    "DIR_ENV",
+    "FAMILY",
+    "HF_MODEL_REPO",
+    "HF_MODEL_REVISION",
+    "MODEL_ID",
+    "PACKAGE_DIR",
+    "PACKAGE_ENV",
+    "PORT_ENV",
+    "VERSION",
+    "_materialize_gguf_cache_path",
+    "binary_name",
+    "default_asset",
+    "invalidate",
+    "is_installed",
+    "package_filename",
+    "parse_device_list",
+    "probe_devices",
+    "resolve_compute_selection",
+    "resolve_model_file",
+    "resolve_server_binary",
+    "runtime_targets",
+    "server_port",
+]

backend/engines/confucius4/__init__.py

@@ -56,15 +56,15 @@ class Confucius4Backend(SubprocessBackend):
 
     id = "confucius4-tts"
     display_name = (
-        "Confucius4-TTS (LLM, 14 langs, cross-lingual zero-shot clone, CUDA/CPU, Apache-2.0)"
+        "Confucius4-TTS (LLM, 14 langs, cross-lingual zero-shot clone, Apache-2.0)"
     )
     supports_voice_design = False  # timbre comes from a reference clip
     # Upstream vocoder rate (config target_sample_rate) — confirmed 22 050 Hz by
     # a live run (2026-07-02); still re-read from the sidecar's ready/audio frames.
     _DEFAULT_SAMPLE_RATE = 22050
-    # CUDA fast path + CPU fallback, both exercised (CPU end-to-end validated).
-    # No MPS claim — upstream has no Metal path.
-    gpu_compat = ("cuda", "cpu")
+    # Match device propagation into upstream .to(device). XPU/NPU routing is
+    # contract-tested, not a claim of physical-hardware synthesis validation.
+    gpu_compat = ("cuda", "rocm", "xpu", "npu", "cpu")
 
     @classmethod
     def is_available(cls) -> tuple[bool, str]:

backend/engines/confucius4/main.py

@@ -104,7 +104,7 @@ def _ensure_clone_on_sys_path() -> None:
 
 
 def _load_model(stdout):
-    """Cold-construct the Confucius4 model (CUDA, else CPU — both validated)."""
+    """Cold-construct using an available torch accelerator, with CPU fallback."""
     global _model
     if _model is not None:
         return _model
@@ -115,7 +115,18 @@ def _load_model(stdout):
     import torch
     from confuciustts.cli.inference import ConfuciusTTS  # type: ignore[import-not-found]
 
-    device = "cuda" if torch.cuda.is_available() else "cpu"
+    try:
+        # Existing manually provisioned venvs may predate torch.accelerator.
+        current_accelerator = getattr(getattr(torch, "accelerator", None), "current_accelerator", None)
+        if current_accelerator is None:
+            device = torch.device("cuda") if torch.cuda.is_available() else None
+        else:
+            device = current_accelerator(check_available=True)
+        device = device.type if device is not None else "cpu"  # 'cuda', 'npu', 'mps', 'xpu', 'cpu'
+    except Exception:
+        device = "cpu"  # Broken accelerator drivers must not block CPU loading.
+    if device == "mps":
+        device = "cpu"  # MPS was slower than CPU in the existing validation run
     _send(stdout, {"op": "progress", "stage": "loading_model", "percent": 50})
 
     _model = ConfuciusTTS(config_path=_config_path(), device=device)

backend/engines/dots_tts/main.py

@@ -115,7 +115,12 @@ def _load_runtime(stdout):
     from dots_tts.runtime import DotsTtsRuntime  # type: ignore[import-not-found]
 
     repo = os.environ.get("OMNIVOICE_DOTS_TTS_MODEL", _DEFAULT_REPO)
-    default_precision = "bfloat16" if torch.cuda.is_available() else "float32"
+    # Match DotsTtsRuntime's own CUDA/CPU selection. Its _check_torch_env
+    # rejects half precision without CUDA, even when an XPU/NPU is available.
+    try:
+        default_precision = "bfloat16" if torch.cuda.is_available() else "float32"
+    except Exception:
+        default_precision = "float32"  # Probe failure must not force half precision.
     precision = os.environ.get("OMNIVOICE_DOTS_TTS_PRECISION", default_precision)
     optimize = os.environ.get("OMNIVOICE_DOTS_TTS_OPTIMIZE", "0") == "1"
 

backend/engines/indextts/__init__.py

@@ -28,6 +28,7 @@ packages. The parent only ever spawns it as a subprocess.
 from __future__ import annotations
 
 import logging
+import math
 import os
 import re
 from typing import TYPE_CHECKING
@@ -164,6 +165,23 @@ class IndexTTS2Backend(SubprocessBackend):
         from engines.indextts.bootstrap import resolve_indextts_venv
         return resolve_indextts_venv()
 
+    @property
+    def recv_timeout_s(self) -> float:
+        # IndexTTS was the only sidecar left on the 60s class default while
+        # pockettts and omnivoice-subprocess both raised theirs. infer() is one
+        # blocking upstream call, so a long passage legitimately outruns 60s and
+        # the parent's watchdog killed a healthy synthesis (#1611). main.py also
+        # heartbeats during infer(), which is what actually proves liveness —
+        # this deadline is the ceiling for a sidecar that has gone genuinely
+        # silent. OMNIVOICE_INDEXTTS_RECV_TIMEOUT_S tunes it.
+        try:
+            v = float(os.environ.get("OMNIVOICE_INDEXTTS_RECV_TIMEOUT_S", "900"))
+        except (ValueError, TypeError):
+            return 900.0
+        if not math.isfinite(v):  # reject inf/nan so the deadline can't be disabled
+            return 900.0
+        return max(30.0, v)
+
     @classmethod
     def sidecar_script(cls):
         from engines.indextts.bootstrap import INDEXTTS_SIDECAR_SCRIPT

backend/engines/indextts/main.py

@@ -63,11 +63,13 @@ Restrictions:
 from __future__ import annotations
 
 import base64
+import contextlib
 import json
 import os
 import struct
 import sys
 import tempfile
+import threading
 import traceback
 
 
@@ -117,11 +119,59 @@ EMOTION_KWARGS_ALLOWLIST = frozenset({
 # ── wire protocol ─────────────────────────────────────────────────────────
 
 
+#: Seconds between keep-alive progress frames during a long blocking call.
+_HEARTBEAT_S = 5.0
+
+#: Serializes _send across threads (the heartbeat below + the main loop) so
+#: concurrent length+body writes can't interleave and corrupt the framing.
+_send_lock = threading.Lock()
+
+
 def _send(stream, obj: dict) -> None:
     body = json.dumps(obj, separators=(",", ":")).encode("utf-8")
-    stream.write(struct.pack("!I", len(body)))
-    stream.write(body)
-    stream.flush()
+    with _send_lock:
+        stream.write(struct.pack("!I", len(body)))
+        stream.write(body)
+        stream.flush()
+
+
+@contextlib.contextmanager
+def _heartbeat(stdout, stage: str):
+    """Emit a progress frame every ~5s for the duration of the block.
+
+    IndexTTS spends the whole of a cold load and the whole of ``infer()``
+    inside one blocking upstream call, saying nothing on the wire. The parent
+    reads that silence two ways, and BOTH kill a perfectly healthy synthesis
+    of a long passage (#1611):
+
+      * ``SubprocessBackend.generate`` re-arms its recv watchdog on every
+        frame, so with no frames it hard-kills the sidecar at recv_timeout_s;
+      * each frame also reports activity to the GPU pool's execution clock
+        (#1367), so with no frames the outer generate budget expires and
+        blames the hardware.
+
+    Raising the deadline alone therefore does not fix long-text generation —
+    the sidecar has to prove it is alive. Percent climbs 1..99 because the
+    upstream call exposes no real progress; it is a liveness signal, not a
+    measurement.
+    """
+    stop = threading.Event()
+
+    def _beat() -> None:
+        pct = 1
+        while not stop.wait(_HEARTBEAT_S):
+            pct = min(pct + 1, 99)
+            try:
+                _send(stdout, {"op": "progress", "stage": stage, "percent": pct})
+            except Exception:
+                return  # pipe gone — the main loop will surface it
+    hb = threading.Thread(target=_beat, name=f"indextts-{stage}-heartbeat", daemon=True)
+    hb.start()
+    try:
+        yield
+    finally:
+        stop.set()
+        hb.join(timeout=_HEARTBEAT_S + 1)
 
 
 def _recv(stream):
@@ -160,14 +210,40 @@ def _torch_bf16_supported() -> bool:
         return False
 
 
+#: Model-config filenames to look for, most-preferred first, per version.
+#: IndexTeam/IndexTTS-2.5 ships ``config.yaml``; VoiceStudio used to demand
+#: ``config_v2_5.yaml``, a name that exists in no upstream revision, so the
+#: install failed until the user hand-renamed the file (#1611). Both names are
+#: accepted now — the hand-renamed installs must keep working untouched — and
+#: the renamed one wins, because a user who created it did so deliberately.
+_CFG_NAMES = {
+    "2.5": ("config_v2_5.yaml", "config.yaml"),
+    "2": ("config.yaml",),
+}
+
+
+def _resolve_cfg_path(model_dir: str, *, version: str) -> str:
+    """First accepted config that exists in ``model_dir``.
+
+    Falls back to the last candidate when none exist, so the failure surfaces
+    as upstream's own "no such file" naming a real expected path rather than
+    a name no upstream release has ever shipped.
+    """
+    names = _CFG_NAMES.get(version, _CFG_NAMES["2"])
+    for name in names:
+        candidate = os.path.join(model_dir, name)
+        if os.path.isfile(candidate):
+            return candidate
+    return os.path.join(model_dir, names[-1])
+
+
 def _model_init_kwargs(
     repo_dir: str, *, version: str, reduced_precision: bool,
 ) -> dict:
     """Build version-specific constructor arguments for IndexTTS 2.5 or 2."""
     model_dir = os.path.join(repo_dir, "checkpoints")
-    cfg_name = "config_v2_5.yaml" if version == "2.5" else "config.yaml"
     kwargs = {
-        "cfg_path": os.path.join(model_dir, cfg_name),
+        "cfg_path": _resolve_cfg_path(model_dir, version=version),
         "model_dir": model_dir,
         "use_cuda_kernel": False,
         "use_deepspeed": False,
@@ -216,7 +292,8 @@ def _load_model(stdout) -> object:
     model_kw = _model_init_kwargs(
         repo_dir, version=_model_version, reduced_precision=reduced_precision,
     )
-    _model = IndexTTS2(**model_kw)
+    with _heartbeat(stdout, "loading_model"):
+        _model = IndexTTS2(**model_kw)
 
     _send(stdout, {"op": "progress", "stage": "loading_model", "percent": 100})
     return _model
@@ -276,7 +353,10 @@ def _handle_synthesize(msg: dict, stdout) -> None:
         tmp_path = tmp.name
     try:
         infer_kw["output_path"] = tmp_path
-        model.infer(**infer_kw)
+        # A long passage keeps infer() busy for minutes with nothing on the
+        # wire; without this the parent kills the sidecar mid-synthesis (#1611).
+        with _heartbeat(stdout, "synthesizing"):
+            model.infer(**infer_kw)
         pcm_b64, sr, n_samples = _wav_to_pcm_b64(tmp_path)
     finally:
         try:

backend/engines/moss_tts_v15/__init__.py

@@ -29,15 +29,11 @@ Do NOT import ``main.py`` from the parent process — it runs under a
 different venv (``transformers==5.0.0``) and importing it in-process would
 re-introduce the exact conflict this isolation exists to avoid.
 
-Hardware honesty (cross-platform rule): MOSS-TTS-v1.5's upstream documents
-only CUDA and CPU. There is **no documented or tested MPS path** — the
-custom ``trust_remote_code`` modelling code and the separate audio
-tokenizer are unverified on Apple Silicon. We therefore advertise
-``gpu_compat = ("cuda", "cpu")`` and the sidecar selects ``cuda`` when
-present else ``cpu`` — it never silently routes to MPS where it might
-crash. On Apple Silicon the engine honestly resolves to CPU (slow but
-correct), and the engine is opt-in regardless, so it never becomes a
-broken default on any platform.
+Hardware routing follows the sidecar's runtime-available PyTorch accelerator:
+CUDA/ROCm, XPU, or a registered NPU. MPS remains excluded; CPU is the fallback.
+XPU/NPU routing is covered with mocked device contracts, not physical-hardware
+synthesis certification; users need a compatible torch/vendor runtime in the
+isolated engine venv.
 """
 from __future__ import annotations
 
@@ -85,13 +81,13 @@ class MossTTSV15Backend(SubprocessBackend):
 
     id = "moss-tts-v15"
     display_name = (
-        "MOSS-TTS-v1.5 (8B, 31 langs, zero-shot clone, CUDA/CPU, Apache-2.0)"
+        "MOSS-TTS-v1.5 (8B, 31 langs, zero-shot clone, Apache-2.0)"
     )
     supports_voice_design = False  # requires ref audio for timbre cloning
     _DEFAULT_SAMPLE_RATE = 24000
-    # Honest hardware surface: upstream documents CUDA + CPU only. MPS is
-    # undocumented / untested, so we do NOT claim it (cross-platform rule).
-    gpu_compat = ("cuda", "cpu")
+    # Accelerator routing requires its matching runtime in the isolated venv.
+    # MPS remains untested and is deliberately excluded.
+    gpu_compat = ("cuda", "rocm", "xpu", "npu", "cpu")
 
     # ── availability ───────────────────────────────────────────────────────
 
@@ -111,7 +107,7 @@ class MossTTSV15Backend(SubprocessBackend):
             return False, (
                 "MOSS-TTS-v1.5 venv not found. Set OMNIVOICE_MOSS_TTS_V15_DIR "
                 "to your MOSS-TTS clone (the directory containing pyproject.toml) "
-                "and restart VoiceStudio. CUDA or CPU only (no MPS). See "
+                "and restart VoiceStudio. Install the matching PyTorch runtime. See "
                 "docs/engines/moss-tts-v15.md for the full install walk-through."
             )
         if not MOSS_TTS_V15_SIDECAR_SCRIPT.exists():
@@ -119,7 +115,7 @@ class MossTTSV15Backend(SubprocessBackend):
                 "MOSS-TTS-v1.5 sidecar script missing at "
                 f"{MOSS_TTS_V15_SIDECAR_SCRIPT} — reinstall VoiceStudio."
             )
-        return True, "ok (CUDA when present, else CPU)"
+        return True, "ok (runtime-available accelerator or CPU; no MPS)"
 
     @classmethod
     def venv_python(cls):

backend/engines/moss_tts_v15/bootstrap.py

@@ -222,8 +222,7 @@ def _bootstrap_engines_venv(clone_dir: Path) -> Path:
     Runs ``uv venv <engines_venv>`` then ``uv pip install --python
     <engines_venv>/bin/python -e "<clone>[torch-runtime]"``. Verifies the
     result by re-probing the import — a successful uv invocation that still
-    can't import the stack indicates a deeper environment problem (e.g. the
-    ``+cu128`` torch-runtime extra can't resolve on a non-CUDA host) and we
+    can't import the stack indicates a deeper environment problem, and we
     raise with whatever stderr we captured plus a docs pointer.
     """
     uv = _locate_uv()
@@ -254,6 +253,8 @@ def _bootstrap_engines_venv(clone_dir: Path) -> Path:
             f"{exc.stderr.decode('utf-8', errors='replace') if exc.stderr else exc}"
         ) from exc
 
+    from core.torch_indexes import UV_PIP_CU128_ARGS
+
     python_path = _venv_python_path(_ENGINES_VENV_DIR)
     try:
         subprocess.run(
@@ -261,6 +262,10 @@ def _bootstrap_engines_venv(clone_dir: Path) -> Path:
                 uv, "pip", "install",
                 "--python", str(python_path),
                 "-e", f"{clone_dir}[torch-runtime]",
+                # The extra pins torch==2.9.1+cu128, which exists only on
+                # PyTorch's index — without it this could never resolve, on
+                # any host (core.torch_indexes).
+                *UV_PIP_CU128_ARGS,
             ],
             check=True,
             timeout=_UV_PIP_INSTALL_TIMEOUT_S,
@@ -270,9 +275,10 @@ def _bootstrap_engines_venv(clone_dir: Path) -> Path:
     except subprocess.CalledProcessError as exc:
         raise RuntimeError(
             "uv pip install -e failed during MOSS-TTS-v1.5 bootstrap "
-            f"({clone_dir}). On a non-CUDA host the upstream '[torch-runtime]' "
-            "extra (cu128) cannot resolve — set up the venv manually per "
-            "docs/engines/moss-tts-v15.md. Error: "
+            # uv's own error names what failed; the PyTorch index is always
+            # supplied now, so a guess about the host would only mislead.
+            f"({clone_dir}). See docs/engines/moss-tts-v15.md for the manual "
+            "install. Error: "
             f"{exc.stderr.decode('utf-8', errors='replace') if exc.stderr else exc}"
         ) from exc
 

backend/engines/moss_tts_v15/main.py

@@ -138,11 +138,12 @@ _state = None
 def _load_model(stdout):
     """Cold-construct the MOSS-TTS-v1.5 processor + model.
 
-    Device selection is CUDA-or-CPU only — MOSS's upstream documents no MPS
-    path and the custom ``trust_remote_code`` modelling code is untested on
-    Apple Silicon, so we never route to MPS where it might crash. dtype is
-    bf16 on CUDA, fp32 on CPU (bf16 CPU ops are spotty). Emits progress
-    frames so the parent can surface the multi-GB cold-load latency.
+    Device selection uses the torch.accelerator API to support any backend
+    (CUDA, NPU, XPU, etc.) automatically. MPS is excluded — MOSS's upstream
+    ``trust_remote_code`` modelling code is untested on Apple Silicon. dtype is
+    bf16 on GPU-class accelerators, fp32 on CPU (bf16 CPU ops are spotty).
+    Emits progress frames so the parent can surface the multi-GB cold-load
+    latency.
     """
     global _state
     if _state is not None:
@@ -154,8 +155,22 @@ def _load_model(stdout):
     from transformers import AutoModel, AutoProcessor
 
     repo, revision = _model_source()
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    dtype = torch.bfloat16 if device == "cuda" else torch.float32
+    # current_accelerator() returns None on CPU-only builds (no accelerator
+    # compiled in) or when no accelerator is available; fall back to "cpu".
+    # Existing manually provisioned venvs may predate torch.accelerator.
+    current_accelerator = getattr(getattr(torch, "accelerator", None), "current_accelerator", None)
+    try:
+        if current_accelerator is None:
+            accel = torch.device("cuda") if torch.cuda.is_available() else None
+        else:
+            accel = current_accelerator(check_available=True)
+    except Exception:
+        # Optional drivers can fail during probing; CPU loading remains usable.
+        accel = None
+    device = accel.type if accel is not None else "cpu"  # 'cuda', 'npu', 'mps', 'xpu', 'cpu'
+    if device == "mps":
+        device = "cpu"  # MOSS is untested on MPS; fall back to CPU for safety
+    dtype = torch.bfloat16 if device != "cpu" else torch.float32
     # "sdpa" works on CUDA + CPU and needs no extra dep. flash_attention_2
     # (Ampere+ CUDA, optional flash-attn) is opt-in via env.
     attn = os.environ.get("OMNIVOICE_MOSS_TTS_V15_ATTN", "sdpa")

backend/engines/omnivoice_gguf/backend.py

@@ -98,6 +98,7 @@ def _platform_slug() -> str:
         darwin-x86_64
         windows-x86_64
         linux-x86_64
+        linux-aarch64
     """
     system = platform.system().lower()
     machine = platform.machine().lower()
@@ -107,6 +108,8 @@ def _platform_slug() -> str:
         return "darwin-x86_64"
     if system == "windows":
         return "windows-x86_64"
+    if system == "linux" and machine in ("arm64", "aarch64"):
+        return "linux-aarch64"
     # Linux + everything else falls into the linux slug.
     return "linux-x86_64"
 

backend/engines/omnivoice_subprocess/__init__.py

@@ -1,7 +1,9 @@
 """omnivoice-subprocess: the resident OmniVoice TTS engine in a crash-isolated
 sidecar process (#730/#1190).
 
-The default ``omnivoice`` engine runs in-process on the GPU ``ThreadPoolExecutor``.
+The ``omnivoice`` engine runs in-process on CUDA, ROCm, and CPU. On MPS it is
+resolved to :class:`OmniVoiceMPSSubprocessBackend` so a fatal native allocator
+exit cannot take down the local API process.
 When a generate or load there exceeds its execution budget the pool is "reset"
 but the abandoned worker *thread* cannot be killed (Python cannot interrupt a
 native torch/MPS call), so it holds the MPS device until it finishes on its
@@ -13,16 +15,11 @@ timeout the parent's watchdog calls ``proc.kill()``, reclaiming the child's
 VRAM/device, and the next request transparently respawns a fresh sidecar. That
 is the one thing the in-process engine structurally cannot do.
 
-OPT-IN (Settings -> Engines, or ``OMNIVOICE_TTS_BACKEND=omnivoice-subprocess``);
-the in-process ``omnivoice`` stays the default so existing users see no change.
+The explicit ``omnivoice-subprocess`` id remains available on every host for
+operators who want the same containment elsewhere.
 
-Tradeoff vs the in-process engine: identical model and quality, a little extra
-per-call overhead (one stdio round-trip), and it does not carry the native
-advanced-parameter surface (``t_shift`` / ``layer_penalty_factor`` /
-``position_temperature`` / ``class_temperature``) or parent-side seed
-determinism, because the generic ``backend.generate`` path does not forward
-those. Acceptable for unattended / reaction-triggered use where reliability
-matters more than those controls.
+Tradeoff vs the in-process engine: identical model, controls, seed behavior,
+and quality, with a little extra per-call overhead (one stdio round-trip).
 
 Unlike IndexTTS / dots.tts / Supertonic-3, this sidecar runs under the PARENT
 interpreter (``venv_python() -> sys.executable``): the goal here is crash
@@ -51,10 +48,15 @@ class OmniVoiceSubprocessBackend(SubprocessBackend):
     id = "omnivoice-subprocess"
     display_name = "OmniVoice (subprocess-isolated, killable on timeout)"
     _DEFAULT_SAMPLE_RATE = 24000
-    gpu_compat = ("cuda", "mps", "cpu")
+    gpu_compat = ("cuda", "rocm", "mps", "cpu")
     # Match OmniVoiceBackend: the measured floor below which a render that
     # should take seconds runs for minutes (the #1226/#1222 4 GB reports).
     min_vram_gb = 6.0
+    # Packaged Windows hosts can spend more than the base 30 seconds starting
+    # the shared Python runtime before this stdlib-only sidecar emits ready.
+    # Keep the bound below the 300-second generation budget while avoiding the
+    # repeated false kill captured in #1711.
+    spawn_ready_timeout_s = 120.0
 
     @classmethod
     def is_available(cls) -> tuple[bool, str]:
@@ -102,4 +104,34 @@ class OmniVoiceSubprocessBackend(SubprocessBackend):
         return ["multi"]
 
 
-__all__ = ["OmniVoiceSubprocessBackend"]
+class OmniVoiceMPSSubprocessBackend(OmniVoiceSubprocessBackend):
+    """Effective ``omnivoice`` implementation on MPS.
+
+    Native torch/MPS allocator failures can terminate the process without a
+    catchable Python exception. Keeping the same engine id and model surface in
+    a child makes that failure recoverable while Settings, APIs, and saved
+    projects continue to refer to ``omnivoice``.
+    """
+
+    id = "omnivoice"
+    display_name = "VoiceStudio (k2-fsa/OmniVoice, 600+ languages)"
+    supports_native_omnivoice_controls = True
+
+    def generate(self, text: str, **kw):
+        from services.model_manager import make_room_before_generate
+
+        make_room_before_generate()
+        try:
+            return super().generate(text, **kw)
+        except RuntimeError as exc:
+            if "sidecar closed pipe mid-generate" not in str(exc):
+                raise
+            raise RuntimeError(
+                "The isolated OmniVoice engine stopped during generation, "
+                "usually because macOS reclaimed it under memory pressure. "
+                "The VoiceStudio backend is still running. Close memory-heavy "
+                "apps or select a smaller TTS engine, then retry."
+            ) from exc
+
+
+__all__ = ["OmniVoiceMPSSubprocessBackend", "OmniVoiceSubprocessBackend"]

backend/engines/omnivoice_subprocess/main.py

@@ -50,6 +50,8 @@ OMNIVOICE_SAMPLE_RATE = 24000
 _GEN_KW_ALLOWLIST = (
     "language", "instruct", "duration", "num_step", "guidance_scale",
     "speed", "denoise", "postprocess_output", "preprocess_prompt",
+    "t_shift", "layer_penalty_factor", "position_temperature",
+    "class_temperature", "audio_chunk_duration", "audio_chunk_threshold",
 )
 
 _model = None
@@ -183,6 +185,12 @@ def _handle_synthesize(msg: dict, stdout) -> None:
     ref_text = msg.get("ref_text") or None
     gen_kw = {k: msg[k] for k in _GEN_KW_ALLOWLIST if k in msg}
 
+    seed = msg.get("seed")
+    if seed is not None:
+        import torch
+
+        torch.manual_seed(int(seed))
+
     audios = model.generate(
         text=text, ref_audio=ref_audio, ref_text=ref_text, **gen_kw
     )

backend/engines/pockettts/__init__.py

@@ -48,6 +48,15 @@ from services.subprocess_backend import SubprocessBackend
 
 logger = logging.getLogger("omnivoice.engines.pockettts")
 
+_VENV_ENV_VAR = "OMNIVOICE_POCKETTTS_DIR"
+
+
+def _own_venv_python() -> "Path | None":
+    """The venv the one-click installer made for this engine, if any."""
+    from services.sidecar_install import engine_venv_python
+
+    return engine_venv_python(_VENV_ENV_VAR)
+
 if TYPE_CHECKING:
     import torch  # noqa: F401
 
@@ -121,16 +130,17 @@ class PocketTTSBackend(SubprocessBackend):
     def is_available(cls) -> tuple[bool, str]:
         if platform_error := cls._platform_error():
             return False, platform_error
-        # Optional-dep gate: the pocket-tts wheel is installed only when the user
-        # opted in. The interpreter is the parent's own (sys.executable), so
-        # there is no separate venv to validate.
-        try:
-            import pocket_tts  # type: ignore[import-not-found]  # noqa: F401
-        except Exception as e:
-            return False, (
-                f"pocket_tts package not installed or failed to import ({e}). "
-                f"Enable in Settings -> Engines (uv sync --extra pockettts)."
-            )
+        # Installed either into its own venv by the one-click installer, which
+        # verified `import pocket_tts` there before saving the path, or into the
+        # app's environment by `uv sync --extra pockettts`.
+        if _own_venv_python() is None:
+            try:
+                import pocket_tts  # type: ignore[import-not-found]  # noqa: F401
+            except Exception as e:
+                return False, (
+                    f"pocket_tts package not installed or failed to import ({e}). "
+                    "Install it from Model Catalogue → Engines."
+                )
 
         # The model repository has an additional gated-access agreement and
         # prohibited-use conditions beyond its CC-BY-4.0 license. Keep first
@@ -145,10 +155,10 @@ class PocketTTSBackend(SubprocessBackend):
 
     @classmethod
     def venv_python(cls) -> Path:
-        # Parent interpreter: pocket-tts deps (torch>=2.5, scipy, beartype) sit
-        # happily at the parent's pins, so this isolates for crash recovery, not
-        # dependency pins (same rationale as omnivoice-subprocess).
-        return Path(sys.executable)
+        # Its own venv when the one-click installer made one. Otherwise the
+        # parent interpreter, where `uv sync --extra pockettts` installs it
+        # (its deps sit happily at the parent's pins).
+        return _own_venv_python() or Path(sys.executable)
 
     @classmethod
     def sidecar_script(cls) -> Path:

backend/engines/pockettts/main.py

@@ -151,6 +151,40 @@ def _pocket_language(raw) -> str:
     )
 
 
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _has_24l_config(language: str) -> bool:
+    """Whether the installed pocket-tts ships a 24-layer checkpoint for
+    ``language`` (it/de/es/pt/fr in 2.1.0; english has none)."""
+    try:
+        from pocket_tts.models.tts_model import CONFIGS_DIR  # type: ignore[import-not-found]  # noqa: PLC0415
+    except Exception as exc:  # noqa: BLE001 — absence of the package is not fatal here
+        # Log it, though: if a future pocket-tts moves CONFIGS_DIR, the 24L
+        # opt-in would otherwise go silently inert.
+        print(f"pockettts sidecar: 24l config probe failed: {exc!r}", file=sys.stderr)
+        return False
+    from pathlib import Path  # noqa: PLC0415
+
+    return (Path(CONFIGS_DIR) / f"{language}_24l.yaml").is_file()
+
+
+def _model_config_name(language: str) -> str:
+    """Pocket-tts config name to load: the 6-layer default, or the 24-layer
+    checkpoint when OMNIVOICE_POCKETTTS_24L is set and one exists for the
+    language. Opt-in only — defaults keep the fast model; the 24-layer variant
+    trades roughly 4x transformer compute for better prosody.
+
+    French is the exception: pocket-tts 2.1.0 only ships a 24-layer French
+    model and load_model(language="french") raises, so French always maps to
+    french_24l regardless of the env var."""
+    if language == "french":
+        return "french_24l"
+    if os.environ.get("OMNIVOICE_POCKETTTS_24L", "").strip().lower() not in _TRUTHY:
+        return language
+    return f"{language}_24l" if _has_24l_config(language) else language
+
+
 def _load_model(stdout, language: str):
     """Cold-construct the PocketTTS model for ``language`` (cached per language).
     Emits progress frames for the parent watchdog. Raises on failure (e.g.
@@ -178,7 +212,7 @@ def _load_model(stdout, language: str):
     try:
         from pocket_tts import TTSModel  # type: ignore[import-not-found]  # noqa: PLC0415
 
-        model = TTSModel.load_model(language=language)
+        model = TTSModel.load_model(language=_model_config_name(language))
         _MODELS[language] = model
     finally:
         stop.set()

backend/engines/supertonic3/backend.py

@@ -48,6 +48,15 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("omnivoice.supertonic3")
 
+_VENV_ENV_VAR = "OMNIVOICE_SUPERTONIC3_DIR"
+
+
+def _own_venv_python() -> "Path | None":
+    """The venv the one-click installer made for this engine, if any."""
+    from services.sidecar_install import engine_venv_python
+
+    return engine_venv_python(_VENV_ENV_VAR)
+
 
 # Absolute path to the sidecar script ‑‑ same pattern as IndexTTS's
 # ``INDEXTTS_SIDECAR_SCRIPT``. SubprocessBackend spawns it with the
@@ -80,11 +89,11 @@ class Supertonic3Backend(SubprocessBackend):
 
     @classmethod
     def venv_python(cls) -> Path:
-        """Supertonic-3 lives in the main OmniVoice venv ‑‑ no dedicated
-        venv. ``sys.executable`` is the parent interpreter, which is the
-        same Python that ``uv sync --extra supertonic`` populated.
+        """Its own venv when the one-click installer made one. Otherwise the
+        parent interpreter, the same Python ``uv sync --extra supertonic``
+        populated.
         """
-        return Path(sys.executable)
+        return _own_venv_python() or Path(sys.executable)
 
     @classmethod
     def sidecar_script(cls) -> Path:
@@ -96,14 +105,16 @@ class Supertonic3Backend(SubprocessBackend):
     def is_available(cls) -> tuple[bool, str]:
         # 1. Optional-dep gate (TTS-02). The ``supertonic`` wheel is only
         #    installed when the user opted in via ``--extra supertonic``.
-        try:
-            import supertonic  # type: ignore[import-not-found]  # noqa: F401
-        except ImportError:
-            return False, (
-                "supertonic package not installed. Enable in "
-                "Model Catalogue → Engines (installs `supertonic` via `uv add --optional "
-                "supertonic supertonic==1.3.1`)."
-            )
+        #    Its own venv (made by the one-click installer, which verified the
+        #    import there) or the app's environment (`uv sync --extra`).
+        if _own_venv_python() is None:
+            try:
+                import supertonic  # type: ignore[import-not-found]  # noqa: F401
+            except ImportError:
+                return False, (
+                    "supertonic package not installed. Install it from "
+                    "Model Catalogue → Engines."
+                )
 
         # 2. License acceptance gate (TTS-05). Defence in depth: the
         #    settings_store helper handles the read; we just refuse

backend/engines/supertonic3/sidecar.py

@@ -137,9 +137,17 @@ def _resolve_pinned_sha() -> str:
         # Final fallback ‑‑ relative import for when the file is invoked
         # via ``python backend/engines/supertonic3/sidecar.py`` rather
         # than via ``python -m backend.engines.supertonic3.sidecar``.
-        sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
-        from engines.supertonic3.constants import PINNED_REVISION_SHA  # type: ignore[import-not-found]
-        return PINNED_REVISION_SHA
+        # Load constants.py by path. Importing it as `engines.supertonic3…`
+        # runs the package __init__, which imports the app's backend, and that
+        # is absent from the engine's own venv (one-click install).
+        import importlib.util
+
+        spec = importlib.util.spec_from_file_location(
+            "_supertonic3_constants", Path(__file__).resolve().with_name("constants.py"),
+        )
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+        return module.PINNED_REVISION_SHA
 
 
 # ── model loading (lazy, on first synthesize) ─────────────────────────────

backend/main.py

@@ -9,6 +9,24 @@ _backend_dir = os.path.dirname(os.path.abspath(__file__))
 if _backend_dir not in sys.path:
     sys.path.insert(0, _backend_dir)
 
+# PyInstaller re-executes this entry module when the frozen backend binary is
+# launched. Nested operation supervisors therefore dispatch here, before math,
+# logging, FastAPI, torch, or any application initialization. Source launches
+# use this same entry contract so frozen/source behavior cannot drift.
+if __name__ == "__main__" and len(sys.argv) > 1 and sys.argv[1] == "--supervise":
+    from core.contained_subprocess import supervisor_main
+
+    raise SystemExit(supervisor_main(sys.argv[1:]))
+
+# Rust clears CLOEXEC only for the backend exec. Re-arm PEP 446 immediately:
+# nested supervisors receive this descriptor solely through explicit pass_fds,
+# so a third-party close_fds=False child cannot hold the desktop drain barrier.
+from core.contained_subprocess import secure_backend_drain_fd  # noqa: E402
+
+secure_backend_drain_fd()
+
+import math  # noqa: E402
+
 # Windows: run every child process (ffmpeg, engine sidecars, yt-dlp, demucs, …)
 # WITHOUT popping a console window. The backend itself is spawned console-less by
 # the Tauri shell, so on Windows each console subprocess it launches would
@@ -59,6 +77,7 @@ os.environ.setdefault("FOR_DISABLE_CONSOLE_CTRL_HANDLER", "1")
 # (utils.hf_progress.SafeFileWrapper — same wrapper the patched hub tqdm
 # already uses for its own fp.)
 from utils.hf_progress import SafeFileWrapper as _SafeStdio  # noqa: E402
+from core.parent_liveness import arm_desktop_parent_watchdog  # noqa: E402
 
 # Force UTF-8 stdio before wrapping (#1155): on Windows the spawned backend's
 # stdout defaults to cp1252, and any library that prints user text (kittentts
@@ -71,6 +90,11 @@ for _stream in (sys.stdout, sys.stderr):
     except Exception:  # noqa: BLE001 — pythonw/frozen builds may lack reconfigure
         pass
 
+# The desktop keeps the backend's stdin pipe open for its own lifetime. EOF is
+# therefore a stable ownership signal that survives PID reuse and lets a child
+# terminate even when the shell crashes before its normal process-tree teardown.
+arm_desktop_parent_watchdog()
+
 if not getattr(sys.stdout, "_is_safe_wrapper", False):
     sys.stdout = _SafeStdio(sys.stdout)
 if not getattr(sys.stderr, "_is_safe_wrapper", False):
@@ -369,19 +393,36 @@ def _env_flag(name: str, default: bool = False) -> bool:
 _EAGER = _env_flag("OMNIVOICE_EAGER_INIT", default=("pytest" in sys.modules))
 
 
+def _env_float(name: str, default: float) -> float:
+    """Parse a float env override, rejecting negative and non-finite values.
+
+    Shared by the preload-delay / timeout knobs: NaN would silently never
+    fire, a negative would fire during startup I/O, so both fall back to the
+    default instead (the bug class CodeRabbit flagged on the watermark knob
+    in PR #1577 — latent in the older copies too, closed here for all)."""
+    raw = os.environ.get(name, "")
+    try:
+        value = float(raw) if raw.strip() else default
+    except ValueError:
+        return default
+    return value if math.isfinite(value) and value >= 0 else default
+
+
 def _capture_preload_delay_s() -> float:
     """Seconds after boot before the dictation (capture ASR) model warms.
 
     Late enough that it never competes with startup I/O or the TTS preload;
     overridable via OMNIVOICE_CAPTURE_PRELOAD_DELAY (mostly for tests)."""
-    raw = os.environ.get("OMNIVOICE_CAPTURE_PRELOAD_DELAY", "")
-    try:
-        v = float(raw)
-        if v >= 0:
-            return v
-    except (TypeError, ValueError):
-        pass
-    return 30.0
+    return _env_float("OMNIVOICE_CAPTURE_PRELOAD_DELAY", 30.0)
+
+def _watermark_preload_delay_s() -> float:
+    """Seconds after boot before the AudioSeal generator warm-up fires.
+
+    Own knob, NOT ``_capture_preload_delay_s`` + offset: a capture-specific
+    env override must not retime the watermark warm too, and the two cold
+    imports shouldn't fire on the same tick (CodeRabbit, PR #1577). Default
+    35s sits ~5s past the capture-ASR warm for the same reason."""
+    return _env_float("OMNIVOICE_PRELOAD_WATERMARK_DELAY", 35.0)
 
 
 def _capture_preload_ram_ok(min_free_bytes: int = 4 * 1024**3) -> bool:
@@ -398,14 +439,7 @@ def _capture_preload_ram_ok(min_free_bytes: int = 4 * 1024**3) -> bool:
 def _mcp_start_timeout_s() -> float:
     """Seconds to wait for the MCP session manager to start before giving up
     and serving without it (#632). Overridable via OMNIVOICE_MCP_START_TIMEOUT_S."""
-    raw = os.environ.get("OMNIVOICE_MCP_START_TIMEOUT_S", "")
-    try:
-        v = float(raw)
-        if v > 0:
-            return v
-    except (TypeError, ValueError):
-        pass
-    return 30.0
+    return max(_env_float("OMNIVOICE_MCP_START_TIMEOUT_S", 30.0), 0.001)
 
 
 async def _serve_mcp(session_manager, ready: "asyncio.Event", stop: "asyncio.Event") -> None:
@@ -551,13 +585,14 @@ def _phase_a_build_inner() -> None:
         pass  # never block startup on the migration; it retries next launch
     # Restore persisted env vars from prefs.json (Settings UI writes them
     # there so they survive backend restarts) — before any user code reads
-    # os.environ, and never overriding an explicitly-set env var.
+    # os.environ, and never overriding an explicitly-set env var. Also
+    # snapshots which keys an external source (shell, `.env`, Docker, …)
+    # already provided, so a Settings control can tell the user their saved
+    # value is being shadowed instead of silently promising it will apply
+    # (core.prefs.is_env_shadowed — #1787 review fix).
     try:
-        from core.prefs import _load as _load_all_prefs
-        _prefs = _load_all_prefs()
-        for _k, _v in _prefs.items():
-            if _k.startswith("env.") and _v:
-                os.environ.setdefault(_k[len("env."):], str(_v))
+        from core.prefs import _load as _load_all_prefs, restore_env
+        restore_env(_load_all_prefs())
     except Exception:
         pass  # prefs.json missing or broken — fine on first run
     # yt-dlp user-update overlay: must run before anything imports yt_dlp so
@@ -589,7 +624,19 @@ def _phase_a_build_inner() -> None:
     _startup_progress.begin_step("ml_imports")
     import torchaudio
     warnings.filterwarnings("ignore", category=UserWarning)
-    torchaudio.set_audio_backend("soundfile")
+    # torchaudio 2.9 REMOVED set_audio_backend(); soundfile has been the only
+    # backend since 2.0, so the call was already a no-op there and is simply
+    # absent now. Unguarded it raises AttributeError inside `ml_imports`, and a
+    # failure in that phase takes the whole backend down — the desktop app sits
+    # on "starting backend" forever and /health stays 503.
+    #
+    # That is not a hypothetical version: RTX 50-series (Blackwell, sm_120)
+    # users have no choice but to move off the pinned torch 2.8.0, which has no
+    # sm_120 kernels, and the torch 2.9.x they land on brings torchaudio 2.9
+    # with it. So the one group forced to upgrade hit a hard startup crash for
+    # a line that does nothing (#1931).
+    if hasattr(torchaudio, "set_audio_backend"):
+        torchaudio.set_audio_backend("soundfile")
     from utils import hf_progress
     # HF tqdm patch before any library import that can trigger
     # hf_hub_download (transformers, mlx_whisper, …).
@@ -638,6 +685,7 @@ def _phase_a_build_inner() -> None:
         events,
         capture,
         capture_ws,
+        speech_platform,
         dictation,
         openai_compat,
         tts_stream,
@@ -650,14 +698,15 @@ def _phase_a_build_inner() -> None:
         settings as settings_router,  # Phase 1 AUTH-03: HF token save/clear/state
         media_tools as media_tools_router,  # Audio tools: ffmpeg/ffprobe/yt-dlp
         auth as auth_router,
+        voice_convert,  # Studio Convert: speech-to-speech via ASR → TTS
     )
     from api.routers import mcp_bindings as _mcp_bindings_router  # noqa: E402
     from api.routers import workers as workers_router  # noqa: E402
     _router_modules.extend([
-        system, profiles, exports, generation, dub_core, dub_generate,
+        system, profiles, exports, generation, voice_convert, dub_core, dub_generate,
         dub_export, dub_translate, projects, glossary, engines, tools,
         stories, setup, gallery, archetypes, describe_voice, community,
-        batch, watermark, events, capture, capture_ws, dictation,
+        batch, watermark, events, capture, capture_ws, speech_platform, dictation,
         openai_compat, tts_stream, marketplace, personas, sonitranslate,
         audiobook, longform_jobs, pronunciation, settings_router,
         media_tools_router, auth_router, _mcp_bindings_router, workers_router,
@@ -852,6 +901,8 @@ async def _phase_b(app: FastAPI) -> None:
     # #1174: arm model loads for THIS run — an in-process relaunch may carry a
     # stale shutting-down flag from a previous lifespan.
     model_loads_reset_shutdown()
+    from services.model_manager import begin_watermark_pool_lifecycle
+    begin_watermark_pool_lifecycle()
     app.state.idle_task = asyncio.create_task(idle_worker())
     app.state.worker_task = asyncio.create_task(task_manager.worker())
     # Warm the TTS model in the background so first /generate is instant.
@@ -905,6 +956,50 @@ async def _phase_b(app: FastAPI) -> None:
     else:
         logger.info("Capture ASR preload disabled; dictation ASR will load on first use.")
 
+    # Watermark: warm the AudioSeal generator in the background so the first
+    # mark_synthetic doesn't serialize the audioseal import + model load
+    # inside the first synthesis (measured ~42 s inline on a cold filesystem,
+    # 2026-08-17 macOS report — 3 s short of the client's 90 s timeout).
+    # Small model on CPU; deferred a few seconds past the capture-ASR warm so
+    # the two cold imports don't contend for the same disk, and no RAM guard
+    # is needed. Runs on the watermark pool — where the model is used — not
+    # the shared default executor.
+    if _env_flag("OMNIVOICE_PRELOAD_WATERMARK", default=True):
+        async def _preload_watermark():
+            await asyncio.sleep(_watermark_preload_delay_s())
+            loop = asyncio.get_running_loop()
+            from services import watermark as _watermark
+
+            # Gate BEFORE touching get_watermark_pool(): the pool is lazy so
+            # hosts with watermarking disabled never spawn its thread, and
+            # creating it unconditionally would break that invariant. The
+            # race with a first embed is benign — pool creation is itself
+            # lock-guarded.
+            if not _watermark.will_mark():
+                logger.debug("Watermark preload skipped (disabled or audioseal absent)")
+                return
+            from services.model_manager import get_watermark_pool
+
+            # Default startup may warm an existing local checkpoint but may
+            # not fetch one. Only an explicit user opt-in permits a download.
+            raw_preload = os.environ.get("OMNIVOICE_PRELOAD_WATERMARK", "")
+            allow_download = raw_preload.strip().lower() in {"1", "true", "yes", "on"}
+
+            try:
+                await loop.run_in_executor(
+                    get_watermark_pool(),
+                    lambda: _watermark.prefetch_generator(
+                        allow_download=allow_download
+                    ),
+                )
+            except Exception:
+                # prefetch_generator swallows its own errors; this guards the
+                # setup half (imports, pool construction) so a broken warm-up
+                # is visible now, not as an unretrieved exception at shutdown.
+                logger.warning("Watermark preload task failed", exc_info=True)
+
+        app.state.watermark_preload_task = asyncio.create_task(_preload_watermark())
+
     # ── MCP session manager (Wave 2.2) ────────────────────────────────────
     # Run it in its OWN task owning the full enter→exit lifecycle (anyio
     # task-affinity, see _serve_mcp); only wait, with a timeout, for ready —
@@ -934,6 +1029,9 @@ async def _phase_b(app: FastAPI) -> None:
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
+    from api.dependencies import validate_server_admin_key
+
+    validate_server_admin_key()
     # Startup watchdog (#632): a silent hang during startup (e.g. a model-load /
     # MCP deadlock on some platforms) means "Application startup complete" never
     # logs and the app sits forever with no error. If startup hasn't finished
@@ -994,6 +1092,33 @@ async def lifespan(app: FastAPI):
         app.state.startup_task = asyncio.create_task(_deferred_startup(app))
     yield
     # ── Graceful shutdown (SIGTERM from Tauri, Ctrl+C, etc.) ────────────
+    # Retire the run sentinel FIRST, before any bounded wait below (#1895):
+    # once uvicorn has begun graceful shutdown the exit is deliberate by
+    # definition, so the sentinel has already done its job. This is one
+    # os.remove, against a ~50s worst-case tail of bounded waits plus model
+    # unload / free_vram() / gc.collect() below. Measured on macOS: a normal
+    # shutdown takes 5.25s end to end, while the desktop shell allows 2s
+    # (bootstrap.rs terminate_process_tree) before SIGKILL — so the old
+    # placement at the very end was killed every time on any run that had
+    # reached a working state. Doing the deadline-sensitive step first makes
+    # correctness independent of how much of that tail runs, instead of
+    # depending on the shell-side deadline being long enough to cover it.
+    #
+    # SCOPE, explicitly: this only helps platforms where lifespan teardown
+    # actually BEGINS. On Windows it does not — tools.rs terminates the job
+    # object with no graceful phase at all, so this line is never reached and
+    # a deliberate quit is still misreported as a crash there. That needs the
+    # shell to signal deliberate intent before the hard kill, which is a
+    # separate Rust-side change and is tracked separately; nothing here
+    # should be read as fixing Windows.
+    #
+    # sentinel_cleared feeds the truthful "Shutdown: done."/degraded log at
+    # the end of this function; nothing below re-clears the sentinel, so a
+    # later failure can't mask this result.
+    try:
+        sentinel_cleared = run_sentinel.clear_sentinel()
+    except Exception:
+        sentinel_cleared = False
     # May run after a startup that never finished (SIGTERM mid-Phase-A/B), so
     # every handle is read from app.state with a None default and every
     # deferred-phase name is guarded.
@@ -1080,8 +1205,20 @@ async def lifespan(app: FastAPI):
         getattr(app.state, "worker_task", None),
         getattr(app.state, "preload_task", None),
         getattr(app.state, "capture_preload_task", None),
+        getattr(app.state, "watermark_preload_task", None),
         timeout=20.0,
     )
+    # The watermark warm-up runs on its dedicated 1-worker pool. Cancellation
+    # detaches the asyncio future but cannot kill a thread inside AudioSeal,
+    # so drain it fully before lifespan teardown reports completion.
+    try:
+        from services.model_manager import shutdown_watermark_pool as _wm_drain
+
+        _wm_drain()
+    except Exception:
+        # Best-effort drain: a failure here must not abort the remaining
+        # shutdown steps (model unload, MCP teardown) below.
+        logger.warning("Watermark pool drain failed at shutdown", exc_info=True)
     # Unload the model and free GPU memory
     try:
         import services.model_manager as mm
@@ -1108,13 +1245,9 @@ async def lifespan(app: FastAPI):
         await close_http_client()
     except Exception:
         pass
-    # Last thing on a clean shutdown: retire the run sentinel so the next
-    # startup doesn't misread this exit as a crash (#1164). If clearing fails,
-    # retain the sentinel and report a degraded shutdown truthfully.
-    try:
-        sentinel_cleared = run_sentinel.clear_sentinel()
-    except Exception:
-        sentinel_cleared = False
+    # Sentinel was already retired at the TOP of this block (#1895) — report
+    # truthfully using that result rather than clearing (or re-checking) it
+    # again here, so a failure in the steps above can't mask it as "done."
     if sentinel_cleared:
         logger.info("Shutdown: done.")
     else:

backend/mcp_server.py

@@ -7,8 +7,8 @@ Run standalone:
 
 Tools exposed:
     generate_speech   — text → WAV audio (voice clone or design)
-    clone_voice       — base64 reference audio → new voice profile
-    transcribe        — base64 audio → text
+    clone_voice       — reference audio (base64, or a file path) → new voice profile
+    transcribe        — audio (base64, or a file path) → text
     list_voices       — enumerate saved voice profiles
     list_languages    — available TTS languages
     list_personalities — voice personality presets
@@ -17,6 +17,18 @@ Tools exposed:
 Resources exposed:
     voice://{profile_id}  — voice profile metadata
     history://recent      — last 20 generated audio items
+
+Output mode (OMNIVOICE_MCP_OUTPUT_MODE):
+    resources — generate_speech returns the WAV as base64 inline (the original
+                contract; default)
+    files     — it returns a URL to the render (and, with a base path, a WAV
+                written there); nothing large ever enters the agent's context
+    both      — both of the above
+
+File inputs (OMNIVOICE_MCP_BASE_PATH):
+    One directory that agents may read audio from (transcribe / clone_voice
+    `*_path` arguments) and receive files in (files mode). It is the security
+    boundary: with no base path configured, path-shaped inputs are refused.
 """
 from __future__ import annotations
 
@@ -25,6 +37,8 @@ import base64
 import json
 import logging
 import os
+import re
+import stat
 import sys
 
 logger = logging.getLogger("omnivoice.mcp")
@@ -69,6 +83,244 @@ def _sniff_audio_ext(raw: bytes) -> str:
     return ".wav"
 
 
+# ── Output mode + the base path boundary ─────────────────────────────────
+# An LLM agent that receives a WAV as base64 pays for every byte in context:
+# a 1.4 s clip already brushes per-result token caps, and a paragraph of
+# narration blows them outright. The ElevenLabs MCP settled this with an
+# OUTPUT_MODE (files / resources / both) and a BASE_PATH that doubles as the
+# security boundary for file-shaped inputs; the same two knobs here, named in
+# the OMNIVOICE_* family the rest of the server reads.
+
+_OUTPUT_MODES = ("resources", "files", "both")
+_MAX_INPUT_BYTES = 200 * 1024 * 1024
+_SAFE_AUDIO_ID = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+
+def _output_mode() -> str:
+    """How generate_speech hands audio back (OMNIVOICE_MCP_OUTPUT_MODE).
+
+    'resources' is the original base64-inline contract and stays the default
+    so existing integrations see no change; 'files' returns a URL to the
+    render (plus a WAV under the base path when one is configured); 'both'
+    returns everything. Anything unrecognized falls back to 'resources' with
+    a warning rather than failing the tool."""
+    mode = os.environ.get("OMNIVOICE_MCP_OUTPUT_MODE", "resources").strip().lower()
+    if mode not in _OUTPUT_MODES:
+        logger.warning(
+            "OMNIVOICE_MCP_OUTPUT_MODE=%r is not one of %s; using 'resources'",
+            mode, _OUTPUT_MODES,
+        )
+        return "resources"
+    return mode
+
+
+def _base_path() -> "str | None":
+    """The one directory agents may read audio from and receive files in
+    (OMNIVOICE_MCP_BASE_PATH), realpath'd; None when unset."""
+    raw = os.environ.get("OMNIVOICE_MCP_BASE_PATH", "").strip()
+    if not raw:
+        return None
+    return os.path.realpath(os.path.expanduser(raw))
+
+
+def _resolve_under_base(path: str) -> str:
+    """Absolute realpath of ``path`` when it lies inside the base path.
+
+    Relative paths resolve against the base; absolute paths must already be
+    inside it. Both sides are realpath'd, so a symlink pointing outward cannot
+    smuggle a read in. Raises ValueError with an agent-legible reason when no
+    base path is configured or the path escapes it."""
+    base = _base_path()
+    if base is None:
+        raise ValueError(
+            "OMNIVOICE_MCP_BASE_PATH is not set; file paths are refused until it "
+            "names a directory"
+        )
+    candidate = os.path.realpath(os.path.join(base, os.path.expanduser(path)))
+    if not _path_is_under_base(base, candidate):
+        raise ValueError(f"{path!r} resolves outside OMNIVOICE_MCP_BASE_PATH")
+    return candidate
+
+
+def _opened_file_is_confined(fd: int, resolved: str, base: str) -> bool:
+    """Verify that an opened descriptor still names a file under ``base``."""
+    proc_fd = f"/proc/self/fd/{fd}"
+    if os.path.exists(proc_fd):
+        return _path_is_under_base(base, os.path.realpath(proc_fd))
+    try:
+        current = os.path.realpath(resolved)
+        return _path_is_under_base(base, current) and os.path.samestat(
+            os.fstat(fd), os.stat(current, follow_symlinks=False)
+        )
+    except OSError:
+        return False
+
+
+def _path_is_under_base(base: str, candidate: str) -> bool:
+    try:
+        common = os.path.commonpath([base, candidate])
+    except ValueError:  # different drives on Windows
+        return False
+    return os.path.normcase(common) == os.path.normcase(base)
+
+
+def _open_under_base(path: str, flags: int, *, mode: int = 0o600) -> tuple[int, str]:
+    """Open ``path`` without following a component replaced after validation."""
+    base = _base_path()
+    if base is None:
+        raise ValueError(
+            "OMNIVOICE_MCP_BASE_PATH is not set; file paths are refused until it "
+            "names a directory"
+        )
+    resolved = _resolve_under_base(path)
+    relative = os.path.relpath(resolved, base)
+    parts = [part for part in relative.split(os.sep) if part not in ("", ".")]
+    if not parts or parts[0] == os.pardir:
+        raise ValueError(f"{path!r} resolves outside OMNIVOICE_MCP_BASE_PATH")
+
+    no_follow = getattr(os, "O_NOFOLLOW", 0)
+    close_on_exec = getattr(os, "O_CLOEXEC", 0)
+    binary = getattr(os, "O_BINARY", 0)
+    file_flags = flags | no_follow | close_on_exec | binary
+    supports_dir_fd = os.open in getattr(os, "supports_dir_fd", ())
+    directory_flag = getattr(os, "O_DIRECTORY", 0)
+
+    if supports_dir_fd and directory_flag:
+        directory_flags = os.O_RDONLY | directory_flag | no_follow | close_on_exec
+        directory_fd = os.open(base, directory_flags)
+        try:
+            for component in parts[:-1]:
+                next_fd = os.open(component, directory_flags, dir_fd=directory_fd)
+                os.close(directory_fd)
+                directory_fd = next_fd
+            fd = os.open(parts[-1], file_flags, mode, dir_fd=directory_fd)
+        finally:
+            os.close(directory_fd)
+    else:
+        fd = os.open(resolved, file_flags, mode)
+
+    if not _opened_file_is_confined(fd, resolved, base):
+        os.close(fd)
+        raise ValueError(f"{path!r} resolves outside OMNIVOICE_MCP_BASE_PATH")
+    return fd, resolved
+
+
+def _read_input_audio(
+    audio_base64: "str | None",
+    audio_path: "str | None",
+    *,
+    label: str = "audio_base64",
+    too_big: str = "audio exceeds 200 MB limit",
+) -> "tuple[bytes | None, str | None]":
+    """Audio bytes from exactly one of the two input lanes, or (None, error).
+
+    The base64 lane keeps its data-URI tolerance and 200 MB cap; the path lane
+    is honored only inside the base path (the security boundary) and applies
+    the same cap to the file's size before reading it."""
+    if bool(audio_base64) == bool(audio_path):
+        return None, f"pass exactly one of {label} or the matching *_path argument"
+    if audio_path:
+        try:
+            fd, _resolved = _open_under_base(audio_path, os.O_RDONLY)
+        except ValueError as e:
+            return None, str(e)
+        except FileNotFoundError:
+            return None, f"no such file under OMNIVOICE_MCP_BASE_PATH: {audio_path!r}"
+        except OSError as e:
+            return None, f"could not safely read {audio_path!r}: {e}"
+        with os.fdopen(fd, "rb") as handle:
+            info = os.fstat(handle.fileno())
+            if not stat.S_ISREG(info.st_mode):
+                return None, f"{audio_path!r} is not a regular file"
+            if info.st_size > _MAX_INPUT_BYTES:
+                return None, too_big
+            raw = handle.read(_MAX_INPUT_BYTES + 1)
+        if len(raw) > _MAX_INPUT_BYTES:
+            return None, too_big
+        if not raw:
+            return None, f"{label} is empty"
+        return raw, None
+    encoded = (
+        audio_base64.split(",", 1)[-1]
+        if audio_base64.startswith("data:")
+        else audio_base64
+    )
+    max_encoded_bytes = 4 * ((_MAX_INPUT_BYTES + 2) // 3)
+    if len(encoded) > max_encoded_bytes:
+        return None, too_big
+    raw = _decode_ref_audio(audio_base64)
+    if raw is None:
+        return None, f"{label} is not valid base64"
+    if not raw:
+        return None, f"{label} is empty"
+    if len(raw) > _MAX_INPUT_BYTES:
+        return None, too_big
+    return raw, None
+
+
+def _write_output(audio_id: str, raw: bytes) -> str:
+    """Land a render under the base path as ``<audio_id>.wav``; returns the path."""
+    if not _SAFE_AUDIO_ID.fullmatch(audio_id):
+        raise ValueError("backend returned an invalid X-Audio-Id header")
+    base = _base_path()
+    os.makedirs(base, exist_ok=True)
+    filename = f"{audio_id}.wav"
+    fd, path = _open_under_base(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+    with os.fdopen(fd, "wb") as handle:
+        handle.write(raw)
+    return path
+
+
+def _post_timeout_s() -> float:
+    """Seconds the tools wait on a backend POST (OMNIVOICE_MCP_TIMEOUT_S,
+    default 120). A CPU host renders a paragraph in minutes and serializes
+    generations, so an agent behind another render used to hit the fixed
+    budget with an empty-message timeout; the knob follows the backend's own
+    OMNIVOICE_GENERATE_TIMEOUT_S when a deployment raises that."""
+    raw = os.environ.get("OMNIVOICE_MCP_TIMEOUT_S", "").strip()
+    try:
+        value = float(raw) if raw else 120.0
+    except ValueError:
+        logger.warning("OMNIVOICE_MCP_TIMEOUT_S=%r is not a number; using 120", raw)
+        return 120.0
+    return value if value > 0 else 120.0
+
+
+def _maybe_number(value):
+    """A response-header number as a number, or the raw text (e.g. '?')."""
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return value
+
+
+def _speech_result(audio_id: str, gen_time, duration, raw: bytes, api_base: str) -> dict:
+    """The generate_speech reply shaped by the output mode.
+
+    The backend already keeps every render on disk and serves it at
+    ``/audio/<audio_id>.wav``, so files mode costs nothing but a URL - plus one
+    write when a base path invites the WAV into the agent's own directory."""
+    if not _SAFE_AUDIO_ID.fullmatch(audio_id):
+        raise ValueError("backend returned an invalid X-Audio-Id header")
+    mode = _output_mode()
+    out = {
+        "audio_id": audio_id,
+        "generation_time_s": gen_time,
+        "audio_duration_s": duration,
+        "format": "wav",
+        "output_mode": mode,
+    }
+    if mode in ("files", "both"):
+        out["audio_url"] = f"{api_base.rstrip('/')}/audio/{audio_id}.wav"
+        if _base_path() is not None:
+            out["output_path"] = _write_output(audio_id, raw)
+        else:
+            out["note"] = "set OMNIVOICE_MCP_BASE_PATH to also receive the WAV as a file"
+    if mode in ("resources", "both"):
+        out["wav_base64"] = base64.b64encode(raw).decode("ascii")
+    return out
+
+
 # ── Lazy imports — keeps startup fast when not using MCP ────────────────
 
 
@@ -147,7 +399,7 @@ def create_mcp_server():
 
     async def _api_post_form(path: str, data: dict, files: dict | None = None):
         import httpx
-        async with httpx.AsyncClient(base_url=_api_base(), timeout=120) as c:
+        async with httpx.AsyncClient(base_url=_api_base(), timeout=_post_timeout_s()) as c:
             r = await c.post(path, data=data, files=files or {})
             r.raise_for_status()
             return r
@@ -190,8 +442,12 @@ def create_mcp_server():
             steps: Diffusion steps (8=fast/draft, 16=balanced, 32=quality).
 
         Returns:
-            JSON with audio_id, generation_time, audio_duration, and
-            base64-encoded WAV data.
+            JSON with audio_id, generation_time_s, audio_duration_s and the
+            audio itself shaped by OMNIVOICE_MCP_OUTPUT_MODE: base64 WAV data
+            ('resources', the default), a URL to the render plus a WAV under
+            OMNIVOICE_MCP_BASE_PATH when one is set ('files'), or all of the
+            above ('both'). Prefer 'files' for LLM agents: nothing large
+            enters the context.
         """
         # Per-agent voice binding (Wave 2.2): explicit arg wins; otherwise
         # resolve this client's bound profile, then the global default.
@@ -218,18 +474,10 @@ def create_mcp_server():
         r = await _api_post_form("/generate", data=form)
 
         audio_id = r.headers.get("X-Audio-Id", "unknown")
-        gen_time = r.headers.get("X-Gen-Time", "?")
-        duration = r.headers.get("X-Audio-Duration", "?")
+        gen_time = _maybe_number(r.headers.get("X-Gen-Time", "?"))
+        duration = _maybe_number(r.headers.get("X-Audio-Duration", "?"))
 
-        wav_b64 = base64.b64encode(r.content).decode("ascii")
-
-        return (
-            f'{{"audio_id":"{audio_id}",'
-            f'"generation_time_s":{gen_time},'
-            f'"audio_duration_s":{duration},'
-            f'"format":"wav",'
-            f'"wav_base64":"{wav_b64}"}}'
-        )
+        return json.dumps(_speech_result(audio_id, gen_time, duration, r.content, _api_base()))
 
     @mcp.tool()
     async def list_voices() -> str:
@@ -266,30 +514,39 @@ def create_mcp_server():
         )
 
     @mcp.tool()
-    async def transcribe(audio_base64: str, language: str | None = None) -> str:
+    async def transcribe(
+        audio_base64: str | None = None,
+        audio_path: str | None = None,
+        language: str | None = None,
+    ) -> str:
         """Transcribe spoken audio to text.
 
+        Pass exactly one of audio_base64 or audio_path.
+
         Args:
             audio_base64: Base64-encoded audio bytes (wav/mp3/webm/m4a).
+            audio_path: Path to an audio file under OMNIVOICE_MCP_BASE_PATH
+                (relative to it, or absolute inside it). The base path is the
+                security boundary: with none configured, paths are refused.
+                Prefer this lane for LLM agents - the audio never enters the
+                agent's context.
             language: Optional language hint; omit for auto-detect.
 
         Returns:
             JSON with the recognized text, language, and duration.
         """
-        try:
-            raw = base64.b64decode(audio_base64, validate=True)
-        except Exception:
-            return '{"error":"audio_base64 is not valid base64"}'
-        # 200 MB cap — same spirit as voicebox's transcribe gate. Keeps a
-        # buggy/hostile agent from posting an unbounded blob.
-        if len(raw) > 200 * 1024 * 1024:
-            return '{"error":"audio exceeds 200 MB limit"}'
+        # 200 MB cap on both lanes — same spirit as voicebox's transcribe
+        # gate. Keeps a buggy/hostile agent from posting an unbounded blob.
+        raw, err = _read_input_audio(audio_base64, audio_path)
+        if err:
+            return json.dumps({"error": err})
         data = {}
         if language:
             data["language"] = language
         r = await _api_post_form(
             "/transcribe", data=data,
-            files={"audio": ("audio.wav", raw, "application/octet-stream")},
+            files={"audio": (f"audio{_sniff_audio_ext(raw)}", raw,
+                             "application/octet-stream")},
         )
         return str(r.json())
 
@@ -319,15 +576,17 @@ def create_mcp_server():
     @mcp.tool()
     async def clone_voice(
         name: str,
-        ref_audio_base64: str,
+        ref_audio_base64: str | None = None,
         ref_text: str = "",
         instruct: str = "",
         language: str = "Auto",
+        ref_audio_path: str | None = None,
     ) -> str:
         """Clone a new voice profile from a reference audio sample.
 
         The new voice is immediately available for use with generate_speech
-        (pass the returned profile_id as the profile_id argument).
+        (pass the returned profile_id as the profile_id argument). Pass
+        exactly one of ref_audio_base64 or ref_audio_path.
 
         Args:
             name: A human-friendly name for the cloned voice.
@@ -338,19 +597,20 @@ def create_mcp_server():
                 quality for some engines).
             instruct: Optional style instruction (e.g. 'whisper', 'excited').
             language: Language of the reference audio (ISO code or 'Auto').
+            ref_audio_path: Path to the reference audio under
+                OMNIVOICE_MCP_BASE_PATH (relative to it, or absolute inside
+                it); refused when no base path is configured. Prefer this
+                lane for LLM agents - the clip never enters the context.
 
         Returns:
             JSON with the new profile's id, name, and kind.
         """
-        # Reject oversized inputs before decoding (base64 is always larger
-        # than raw, so this is a safe lower bound on the decoded size).
-        if len(ref_audio_base64) > 200 * 1024 * 1024:
-            return '{"error":"reference audio exceeds 200 MB limit"}'
-        raw = _decode_ref_audio(ref_audio_base64)
-        if raw is None:
-            return '{"error":"ref_audio_base64 is not valid base64"}'
-        if not raw:
-            return '{"error":"ref_audio_base64 is empty"}'
+        raw, err = _read_input_audio(
+            ref_audio_base64, ref_audio_path,
+            label="ref_audio_base64", too_big="reference audio exceeds 200 MB limit",
+        )
+        if err:
+            return json.dumps({"error": err})
         import httpx
         try:
             r = await _api_post_form(

backend/migrations/versions/0011_hosted_voice_sync.py

@@ -1,30 +0,0 @@
-"""Opt-in hosted Voice ID on local profiles.
-
-Revision ID: 0011_hosted_voice_sync
-Revises: 0010_remote_worker_schema
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-
-revision: str = "0011_hosted_voice_sync"
-down_revision: Union[str, None] = "0010_remote_worker_schema"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def _has_column(table: str, column: str) -> bool:
-    rows = op.get_bind().execute(sa.text(f"PRAGMA table_info({table})")).fetchall()
-    return any(row[1] == column for row in rows)
-
-
-def upgrade() -> None:
-    if not _has_column("voice_profiles", "hosted_voice_id"):
-        op.add_column("voice_profiles", sa.Column("hosted_voice_id", sa.Text(), nullable=True, server_default=""))
-
-
-def downgrade() -> None:
-    if _has_column("voice_profiles", "hosted_voice_id"):
-        op.drop_column("voice_profiles", "hosted_voice_id")

backend/migrations/versions/0011_remote_attempt_deadlines.py

@@ -0,0 +1,18 @@
+"""Retain the dispatch-time deadline policy across worker/control-plane loss."""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0011_remote_attempt_deadlines"
+down_revision = "0010_remote_worker_schema"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    columns = op.get_bind().execute(sa.text("PRAGMA table_info(remote_task_attempts)"))
+    if not any(row[1] == "deadlines_json" for row in columns):
+        op.add_column("remote_task_attempts", sa.Column("deadlines_json", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("remote_task_attempts", "deadlines_json")

backend/migrations/versions/0012_mark_archetype_profiles_design.py

@@ -1,54 +0,0 @@
-"""Mark materialized gallery archetypes as voice-design profiles.
-
-Revision ID: 0012_mark_archetype_profiles_design
-Revises: 0011_hosted_voice_sync
-Create Date: 2026-08-15 00:00:00.000000
-
-``POST /archetypes/{id}/use`` stores the archetype id in ``personality`` and
-also stores a locally rendered identity WAV.  That WAV must not make the
-profile a clone: the archetype's instruct recipe is authoritative.  Older
-rows relied on the ``kind='clone'`` default and therefore selected the clone
-generation path.  This data-only migration fixes every row whose personality
-is a current archetype id, leaving unrelated persona and marketplace imports
-untouched.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-from sqlalchemy import inspect
-
-
-revision: str = "0012_mark_archetype_profiles_design"
-down_revision: Union[str, None] = "0011_hosted_voice_sync"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    bind = op.get_bind()
-    inspector = inspect(bind)
-    if "voice_profiles" not in inspector.get_table_names():
-        return
-    columns = {column["name"] for column in inspector.get_columns("voice_profiles")}
-    if not {"kind", "personality"}.issubset(columns):
-        return
-
-    # The catalog is intentionally a value object, so checking an id against
-    # its current generated list is the precise provenance test.  The
-    # parameterized update avoids treating any other personality string as an
-    # archetype.
-    from core import archetypes
-
-    archetype_ids = [item["id"] for item in archetypes.list_archetypes()]
-    for archetype_id in archetype_ids:
-        bind.exec_driver_sql(
-            "UPDATE voice_profiles SET kind = 'design' "
-            "WHERE personality = ? AND (kind IS NULL OR kind = '' OR kind = 'clone')",
-            (archetype_id,),
-        )
-
-
-def downgrade() -> None:
-    # Do not silently convert voice-design profiles back to clones: that would
-    # reintroduce the generation mismatch for existing user data.
-    pass

backend/runtime_adapter/README.md

@@ -1,95 +0,0 @@
-# VoiceStudio runtime adapter
-
-A local gRPC server implementing the vssaas GPU-node runtime contract
-`voicestudio.runtime.v1.RuntimeAdapterService`, so a vssaas GPU Gateway can
-drive this VoiceStudio backend as its inference runtime.
-
-## Boundary (deliberate non-capabilities)
-
-- Binds **only** a Unix-domain socket (default `/run/voicestudio/runtime.sock`,
-  override with `VOICE_STUDIO_RUNTIME_SOCKET`). No HTTP listener, no TCP.
-- Never reaches PostgreSQL, customer credentials, or arbitrary network URLs.
-  `Execute` accepts **local file handles only** — absolute paths generated by
-  the Gateway; any URL-shaped or relative handle is rejected as invalid input.
-- The Gateway owns leases, artifact transfer, retries, and billing. This
-  adapter owns approved model loading and inference only.
-
-## Running
-
-```sh
-# serve (production socket):
-VOICE_STUDIO_RUNTIME_SOCKET=/run/voicestudio/runtime.sock \
-  python -m backend.runtime_adapter
-
-# self-check: starts the server on a private temp socket and validates the
-# same expectations the Go preflight (cmd/runtime-adapter-preflight) enforces:
-python -m backend.runtime_adapter --selfcheck
-```
-
-Environment:
-
-| Variable | Default | Meaning |
-| --- | --- | --- |
-| `VOICE_STUDIO_RUNTIME_SOCKET` | `/run/voicestudio/runtime.sock` | Unix socket path (must be absolute; parent dir must exist and not be world-writable). |
-| `VOICE_STUDIO_RUNTIME_SLOTS` | `1` | Concurrent execution slots per device. |
-
-## Wire contract and generated stubs
-
-`runtime_adapter.proto` is a **byte-identical vendored copy** of the vssaas
-contract `api/proto/voicestudio/runtime/v1/runtime_adapter.proto`. Do not edit
-it here; re-vendor from vssaas when the contract changes, then regenerate.
-
-The `gen/` stubs are committed (same policy as `backend/worker/protocol/gen/`).
-Regenerate with:
-
-```sh
-uv run python scripts/gen_runtime_adapter_protocol.py
-```
-
-`tests/test_runtime_adapter_gen.py` fails if the committed stubs drift from
-the proto.
-
-## Preflight expectations honoured
-
-The Go preflight (`internal/gateway/preflight.go`) fails closed unless:
-
-- the socket path is absolute, a real Unix socket (not a symlink), and its
-  parent directory is not world-writable — `server.prepare_socket` enforces
-  the same rules at bind time;
-- `Health` returns `SERVING_STATE_READY` with nonempty runtime + adapter
-  versions, and `GetCapabilities` returns **identical** versions — both
-  handlers read the same constants, so they cannot disagree;
-- at least one device with nonempty id/hardware class, nonzero VRAM and
-  slots, `free_slots <= total_slots`, unique ids;
-- at least one model **explicitly READY** with `catalog_model_id`,
-  `model_version`, `model_digest`, and ≥1 precision. A loading, installed,
-  or failed model is reported with its true state and never as READY.
-
-## Model identity
-
-- `catalog_model_id` — the VoiceStudio TTS engine id (`omnivoice`,
-  `voxcpm2`, …) from `services.tts_backend`'s registry.
-- `model_version` — an immutable catalog version comprising the installed
-  Hugging Face revision (40-char commit SHA) and the first 16 hex characters
-  of the attested snapshot digest. This creates a new catalog identity when
-  snapshot bytes change; it never rewrites an identity retained by a Job.
-- `model_digest` — `sha256:<hex>` computed over the installed snapshot files
-  (sorted relative path + per-file SHA-256), cached next to the repo cache
-  keyed by (revision, file list, sizes, mtimes) so multi-GB weights are
-  hashed once. See `digest.py`.
-
-## Failure taxonomy
-
-Stable codes (prefix `RTA_`) map onto the proto's `RuntimeFailureClass`:
-invalid input (`RTA_INPUT_*`), model load (`RTA_MODEL_LOAD_FAILED`),
-inference (`RTA_INFERENCE_*`), GPU resource (`RTA_GPU_*`), local storage
-(`RTA_STORAGE_*`), cancellation (terminal `ExecutionCanceled`), and adapter
-crash (`RTA_RUNTIME_CRASH`). See `codes.py`.
-
-## Tests
-
-```sh
-uv run pytest backend/tests/test_runtime_adapter_capabilities.py \
-              backend/tests/test_runtime_adapter_execute.py \
-              tests/test_runtime_adapter_gen.py
-```

backend/runtime_adapter/__init__.py

@@ -1,18 +0,0 @@
-"""VoiceStudio runtime adapter — the vssaas GPU-node runtime boundary.
-
-Implements ``voicestudio.runtime.v1.RuntimeAdapterService`` over a private
-Unix-domain socket so a vssaas GPU Gateway can drive VoiceStudio's TTS
-engines as its inference runtime. No HTTP listener, no database access, no
-outbound network: the adapter reads and writes only the local file handles
-each ``Execute`` request carries. See ``README.md`` in this directory.
-"""
-from __future__ import annotations
-
-#: Version of this adapter layer (the gRPC boundary), independent of the app
-#: version, which is reported as ``runtime_version``. Bump on any behavioral
-#: change to the adapter itself.
-ADAPTER_VERSION = "0.1.0"
-
-DEFAULT_SOCKET_PATH = "/run/voicestudio/runtime.sock"
-SOCKET_ENV = "VOICE_STUDIO_RUNTIME_SOCKET"
-SLOTS_ENV = "VOICE_STUDIO_RUNTIME_SLOTS"

backend/runtime_adapter/__main__.py

@@ -1,65 +0,0 @@
-"""Entry point: ``python -m backend.runtime_adapter``.
-
-Serves the runtime adapter on a private Unix-domain socket (default
-``/run/voicestudio/runtime.sock``, override ``VOICE_STUDIO_RUNTIME_SOCKET``
-or ``--socket``). ``--selfcheck`` instead starts the server on a temp socket
-and validates the GPU Gateway preflight expectations against it.
-"""
-from __future__ import annotations
-
-import argparse
-import sys
-
-from ._paths import ensure_backend_on_path
-
-
-def main(argv: list[str] | None = None) -> int:
-    ensure_backend_on_path()
-    parser = argparse.ArgumentParser(
-        prog="backend.runtime_adapter",
-        description="VoiceStudio runtime adapter (vssaas GPU-node gRPC server)",
-    )
-    parser.add_argument(
-        "--socket",
-        default=None,
-        help="absolute Unix socket path (default: $VOICE_STUDIO_RUNTIME_SOCKET "
-        "or /run/voicestudio/runtime.sock)",
-    )
-    parser.add_argument(
-        "--selfcheck",
-        action="store_true",
-        help="start on a temp socket and validate the preflight expectations",
-    )
-    parser.add_argument(
-        "--timeout",
-        type=float,
-        default=10.0,
-        help="selfcheck RPC timeout in seconds (default: 10)",
-    )
-    parser.add_argument(
-        "--no-prewarm",
-        action="store_true",
-        help="serve immediately without loading models first (the first "
-        "execution then pays weight loading and compilation)",
-    )
-    args = parser.parse_args(argv)
-
-    if args.selfcheck:
-        from .selfcheck import selfcheck  # noqa: PLC0415
-
-        return selfcheck(timeout_s=args.timeout)
-
-    from .production import build_runtime_context, prewarm_engines  # noqa: PLC0415
-    from .server import resolve_socket_path, serve  # noqa: PLC0415
-
-    context = build_runtime_context()
-    if not args.no_prewarm:
-        # Deliberately before the socket exists: the Gateway's preflight and
-        # first offer should both find a runtime that can start inference at
-        # once, rather than one that spends an attempt lease compiling.
-        prewarm_engines(context)
-    return serve(context, resolve_socket_path(args.socket))
-
-
-if __name__ == "__main__":
-    sys.exit(main())

backend/runtime_adapter/_paths.py

@@ -1,20 +0,0 @@
-"""Import-path bootstrap for running outside the FastAPI app.
-
-The backend is laid out to run with ``--app-dir backend`` (imports like
-``services.tts_backend`` resolve against the ``backend/`` directory). When
-the adapter is launched as ``python -m backend.runtime_adapter`` from the
-repo root, ``backend/`` is a namespace package but not on ``sys.path`` — so
-call :func:`ensure_backend_on_path` before any ``services.*`` / ``core.*``
-import. Idempotent; mirrors ``backend/tests/conftest.py``.
-"""
-from __future__ import annotations
-
-import os
-import sys
-
-
-def ensure_backend_on_path() -> str:
-    backend_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-    if backend_dir not in sys.path:
-        sys.path.insert(0, backend_dir)
-    return backend_dir

backend/runtime_adapter/codes.py

@@ -1,163 +0,0 @@
-"""Stable failure codes and exception classification for Execute.
-
-The vssaas API Gateway keys retry and customer-charge policy off these codes,
-so they are a wire contract: never rename an existing code, only add. Every
-code maps to exactly one proto ``RuntimeFailureClass``.
-"""
-from __future__ import annotations
-
-import re
-
-from .gen import runtime_adapter_pb2 as pb2
-
-# ── invalid approved input ────────────────────────────────────────────────
-INPUT_ATTEMPT_IDENTITY = "RTA_INPUT_ATTEMPT_IDENTITY"
-INPUT_ATTEMPT_DUPLICATE = "RTA_INPUT_ATTEMPT_DUPLICATE"
-INPUT_MODEL_UNKNOWN = "RTA_INPUT_MODEL_UNKNOWN"
-INPUT_MODEL_NOT_READY = "RTA_INPUT_MODEL_NOT_READY"
-INPUT_MODEL_DIGEST_MISMATCH = "RTA_INPUT_MODEL_DIGEST_MISMATCH"
-INPUT_MODEL_PRECISION = "RTA_INPUT_MODEL_PRECISION_UNSUPPORTED"
-INPUT_DEVICE_UNKNOWN = "RTA_INPUT_DEVICE_UNKNOWN"
-INPUT_HANDLE_INVALID = "RTA_INPUT_HANDLE_INVALID"
-INPUT_ARTIFACTS_INVALID = "RTA_INPUT_ARTIFACTS_INVALID"
-INPUT_CHECKSUM_MISMATCH = "RTA_INPUT_CHECKSUM_MISMATCH"
-INPUT_TEXT_EMPTY = "RTA_INPUT_TEXT_EMPTY"
-INPUT_TEXT_TOO_LARGE = "RTA_INPUT_TEXT_TOO_LARGE"
-INPUT_TEXT_ENCODING = "RTA_INPUT_TEXT_ENCODING"
-INPUT_PARAMETER_UNKNOWN = "RTA_INPUT_PARAMETER_UNKNOWN"
-INPUT_PARAMETER_TYPE = "RTA_INPUT_PARAMETER_TYPE"
-INPUT_PARAMETER_RANGE = "RTA_INPUT_PARAMETER_RANGE"
-INPUT_DEADLINE_INVALID = "RTA_INPUT_DEADLINE_INVALID"
-INPUT_REJECTED = "RTA_INPUT_REJECTED"  # engine-level TTSInputError
-
-# ── model load / inference ────────────────────────────────────────────────
-MODEL_LOAD_FAILED = "RTA_MODEL_LOAD_FAILED"
-MODEL_LOAD_DEADLINE = "RTA_MODEL_LOAD_DEADLINE_EXCEEDED"
-INFERENCE_FAILED = "RTA_INFERENCE_FAILED"
-INFERENCE_BAD_OUTPUT = "RTA_INFERENCE_BAD_OUTPUT"
-INFERENCE_DEADLINE = "RTA_INFERENCE_DEADLINE_EXCEEDED"
-
-# ── GPU resource ──────────────────────────────────────────────────────────
-GPU_OUT_OF_MEMORY = "RTA_GPU_OUT_OF_MEMORY"
-GPU_SLOTS_EXHAUSTED = "RTA_GPU_SLOTS_EXHAUSTED"
-
-# ── local storage ─────────────────────────────────────────────────────────
-STORAGE_READ_FAILED = "RTA_STORAGE_READ_FAILED"
-STORAGE_WRITE_FAILED = "RTA_STORAGE_WRITE_FAILED"
-
-# ── adapter crash ─────────────────────────────────────────────────────────
-RUNTIME_CRASH = "RTA_RUNTIME_CRASH"
-
-_INPUT = pb2.RUNTIME_FAILURE_CLASS_INPUT
-_MODEL_LOAD = pb2.RUNTIME_FAILURE_CLASS_MODEL_LOAD
-_INFERENCE = pb2.RUNTIME_FAILURE_CLASS_INFERENCE
-_GPU = pb2.RUNTIME_FAILURE_CLASS_GPU_RESOURCE
-_STORAGE = pb2.RUNTIME_FAILURE_CLASS_LOCAL_STORAGE
-_RUNTIME = pb2.RUNTIME_FAILURE_CLASS_RUNTIME
-
-CODE_CLASS: dict[str, int] = {
-    INPUT_ATTEMPT_IDENTITY: _INPUT,
-    INPUT_ATTEMPT_DUPLICATE: _INPUT,
-    INPUT_MODEL_UNKNOWN: _INPUT,
-    INPUT_MODEL_NOT_READY: _INPUT,
-    INPUT_MODEL_DIGEST_MISMATCH: _INPUT,
-    INPUT_MODEL_PRECISION: _INPUT,
-    INPUT_DEVICE_UNKNOWN: _INPUT,
-    INPUT_HANDLE_INVALID: _INPUT,
-    INPUT_ARTIFACTS_INVALID: _INPUT,
-    INPUT_CHECKSUM_MISMATCH: _INPUT,
-    INPUT_TEXT_EMPTY: _INPUT,
-    INPUT_TEXT_TOO_LARGE: _INPUT,
-    INPUT_TEXT_ENCODING: _INPUT,
-    INPUT_PARAMETER_UNKNOWN: _INPUT,
-    INPUT_PARAMETER_TYPE: _INPUT,
-    INPUT_PARAMETER_RANGE: _INPUT,
-    INPUT_DEADLINE_INVALID: _INPUT,
-    INPUT_REJECTED: _INPUT,
-    MODEL_LOAD_FAILED: _MODEL_LOAD,
-    MODEL_LOAD_DEADLINE: _MODEL_LOAD,
-    INFERENCE_FAILED: _INFERENCE,
-    INFERENCE_BAD_OUTPUT: _INFERENCE,
-    INFERENCE_DEADLINE: _INFERENCE,
-    GPU_OUT_OF_MEMORY: _GPU,
-    GPU_SLOTS_EXHAUSTED: _GPU,
-    STORAGE_READ_FAILED: _STORAGE,
-    STORAGE_WRITE_FAILED: _STORAGE,
-    RUNTIME_CRASH: _RUNTIME,
-}
-
-
-class ExecutionFailure(Exception):
-    """A classified, wire-safe execution failure."""
-
-    def __init__(self, stable_code: str, safe_detail: str = ""):
-        if stable_code not in CODE_CLASS:  # programming error, not a wire case
-            raise ValueError(f"unknown stable code {stable_code!r}")
-        super().__init__(stable_code)
-        self.stable_code = stable_code
-        self.failure_class = CODE_CLASS[stable_code]
-        self.safe_detail = scrub_detail(safe_detail)
-
-
-_PATHISH = re.compile(r"(?:[A-Za-z]:)?[/\\][^\s'\"]+")
-_MAX_DETAIL = 240
-
-
-def scrub_detail(detail: str) -> str:
-    """Bound and de-path a detail string before it crosses the wire.
-
-    Local handles are server-generated, but engine exceptions routinely embed
-    checkpoint paths, cache dirs, and home directories. None of that belongs
-    in an event the Gateway relays upstream.
-    """
-    scrubbed = _PATHISH.sub("<path>", detail or "").strip()
-    return scrubbed[:_MAX_DETAIL]
-
-
-_OOM_MARKERS = (
-    "out of memory",
-    "cuda error: out of memory",
-    "mps backend out of memory",
-    "hip out of memory",
-    "cublas_status_alloc_failed",
-)
-
-
-def _is_oom(exc: BaseException) -> bool:
-    if type(exc).__name__ == "OutOfMemoryError":  # torch.cuda.OutOfMemoryError
-        return True
-    message = str(exc).lower()
-    return any(marker in message for marker in _OOM_MARKERS)
-
-
-def _is_engine_input_error(exc: BaseException) -> bool:
-    try:
-        from services.tts_backend import TTSInputError  # noqa: PLC0415
-    except Exception:
-        return False
-    return isinstance(exc, TTSInputError)
-
-
-def classify_engine_error(exc: BaseException, phase: str) -> ExecutionFailure:
-    """Map an engine exception to a stable failure code.
-
-    ``phase`` is ``"model_load"`` or ``"synthesis"`` — the phase the engine
-    thread was in when it raised.
-    """
-    if isinstance(exc, ExecutionFailure):
-        return exc
-    detail = f"{type(exc).__name__}: {exc}"
-    if _is_oom(exc):
-        return ExecutionFailure(GPU_OUT_OF_MEMORY, detail)
-    if _is_engine_input_error(exc):
-        return ExecutionFailure(INPUT_REJECTED, detail)
-    if isinstance(exc, OSError):
-        return ExecutionFailure(STORAGE_READ_FAILED, detail)
-    if phase == "model_load":
-        return ExecutionFailure(MODEL_LOAD_FAILED, detail)
-    return ExecutionFailure(INFERENCE_FAILED, detail)
-
-
-def deadline_failure(phase: str) -> ExecutionFailure:
-    code = MODEL_LOAD_DEADLINE if phase == "model_load" else INFERENCE_DEADLINE
-    return ExecutionFailure(code, "attempt deadline exceeded")

backend/runtime_adapter/digest.py

@@ -1,112 +0,0 @@
-"""Stable digests for locally installed model snapshots.
-
-``model_digest`` in the wire contract pins the exact bytes a READY model will
-execute with. Hugging Face snapshots are symlink farms into ``blobs/``, so the
-digest is computed over the *resolved* file contents: SHA-256 of the sorted
-sequence ``<posix relpath>\\n<file sha256>\\n``. That is stable across hosts,
-cache locations, and symlink layout, and changes whenever any weight byte or
-the file set changes.
-
-Hashing multi-GB weights on every ``GetCapabilities`` call would be absurd, so
-the result is cached in a JSON sidecar keyed by a cheap fingerprint of the
-file list (relpath, size, mtime_ns). Any file change invalidates the cache and
-forces a full re-hash.
-"""
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-from pathlib import Path
-
-DIGEST_PREFIX = "sha256:"
-_CHUNK = 1024 * 1024
-
-
-def file_sha256(path: str | os.PathLike[str]) -> str:
-    hasher = hashlib.sha256()
-    with open(path, "rb") as fh:
-        while True:
-            chunk = fh.read(_CHUNK)
-            if not chunk:
-                break
-            hasher.update(chunk)
-    return hasher.hexdigest()
-
-
-def _manifest(root: Path) -> list[tuple[str, int, int]]:
-    """Sorted (relpath, size, mtime_ns) for every regular file under root.
-
-    Follows symlinks (HF snapshot layout); a dangling symlink raises
-    ``FileNotFoundError`` — callers treat that as an incomplete install.
-    """
-    entries: list[tuple[str, int, int]] = []
-    for current, dirs, files in os.walk(root, followlinks=True):
-        dirs.sort()
-        for name in sorted(files):
-            path = Path(current) / name
-            stat = path.stat()  # resolves symlinks; raises if dangling
-            rel = path.relative_to(root).as_posix()
-            entries.append((rel, stat.st_size, stat.st_mtime_ns))
-    entries.sort()
-    return entries
-
-
-def _fingerprint(entries: list[tuple[str, int, int]]) -> str:
-    return hashlib.sha256(
-        json.dumps(entries, separators=(",", ":")).encode("utf-8")
-    ).hexdigest()
-
-
-def snapshot_digest(root: str | os.PathLike[str], cache_path: str | os.PathLike[str] | None = None) -> str:
-    """``sha256:<hex>`` digest of the snapshot at ``root``.
-
-    Raises ``FileNotFoundError`` for a missing/empty snapshot or dangling
-    symlink and ``OSError`` for unreadable files — callers classify those as
-    not-READY rather than fabricating a digest.
-    """
-    root = Path(root)
-    entries = _manifest(root)
-    if not entries:
-        raise FileNotFoundError(f"empty model snapshot: {root}")
-    fingerprint = _fingerprint(entries)
-
-    if cache_path is not None:
-        cached = _read_cache(cache_path)
-        if cached is not None and cached.get("fingerprint") == fingerprint:
-            digest = cached.get("digest", "")
-            if isinstance(digest, str) and digest.startswith(DIGEST_PREFIX):
-                return digest
-
-    hasher = hashlib.sha256()
-    for rel, _size, _mtime in entries:
-        hasher.update(rel.encode("utf-8"))
-        hasher.update(b"\n")
-        hasher.update(file_sha256(root / rel).encode("ascii"))
-        hasher.update(b"\n")
-    digest = DIGEST_PREFIX + hasher.hexdigest()
-
-    if cache_path is not None:
-        _write_cache(cache_path, fingerprint, digest)
-    return digest
-
-
-def _read_cache(cache_path: str | os.PathLike[str]) -> dict | None:
-    try:
-        with open(cache_path, encoding="utf-8") as fh:
-            data = json.load(fh)
-        return data if isinstance(data, dict) else None
-    except (OSError, ValueError):
-        return None
-
-
-def _write_cache(cache_path: str | os.PathLike[str], fingerprint: str, digest: str) -> None:
-    cache_path = Path(cache_path)
-    payload = json.dumps({"fingerprint": fingerprint, "digest": digest})
-    try:
-        cache_path.parent.mkdir(parents=True, exist_ok=True)
-        temporary = cache_path.with_suffix(f".tmp-{os.getpid()}")
-        temporary.write_text(payload, encoding="utf-8")
-        os.replace(temporary, cache_path)
-    except OSError:
-        pass  # cache is an optimization; the digest itself is already computed

backend/runtime_adapter/executor.py

@@ -1,664 +0,0 @@
-"""Execute/Cancel: attempt registry, validation, and the event stream.
-
-One ``Execute`` call is one *attempt*. The generator emits::
-
-    started → progress* → exactly one of completed | failed | canceled
-
-The engine call itself (``ensure_ready`` + ``generate``) runs on a daemon
-worker thread; the streaming generator polls it, emitting bounded heartbeat
-progress and enforcing the request deadline and cancellation. A blocking
-engine cannot be interrupted mid-kernel, so on cancel/deadline the thread is
-abandoned and its result discarded — the terminal event is what the Gateway
-acts on, and slot accounting is released only when the thread actually exits.
-
-The adapter never turns a customer string into a filesystem path: it touches
-exactly the local handles the request carries, after validation.
-"""
-from __future__ import annotations
-
-import os
-import threading
-import time
-from collections import OrderedDict
-from dataclasses import dataclass, field
-
-from . import codes
-from ._paths import ensure_backend_on_path
-from .digest import file_sha256
-from .gen import runtime_adapter_pb2 as pb2
-from .inventory import STATE_READY
-
-_MAX_TEXT_BYTES = 512_000
-_MAX_REF_AUDIO_BYTES = 100 * 1024 * 1024
-_MAX_DEADLINE_S = 24 * 3600.0
-_MAX_PROGRESS_EVENTS = 512
-
-#: Typed, bounded Execute parameters → the engine ``generate()`` kwarg of the
-#: same name. Kinds: ("string", max_len) / ("integer", lo, hi) /
-#: ("number", lo, hi) / ("boolean",).
-PARAMETER_SPECS: dict[str, tuple] = {
-    "language": ("string", 32),
-    "ref_text": ("string", 4096),
-    "instruct": ("string", 2048),
-    "description": ("string", 2048),
-    "speed": ("number", 0.25, 4.0),
-    "guidance_scale": ("number", 0.0, 16.0),
-    "num_step": ("integer", 1, 128),
-    # Gallery reference voices persist their OSS design seed.  Accept it at
-    # the hosted runtime boundary so a selected voice produces the same take.
-    "seed": ("integer", 0, 4_294_967_295),
-}
-
-
-# ── attempt registry ──────────────────────────────────────────────────────
-
-
-@dataclass
-class AttemptRecord:
-    job_id: str
-    attempt_id: str
-    cancel: threading.Event = field(default_factory=threading.Event)
-    terminal: str | None = None  # "completed" | "failed" | "canceled"
-
-
-class AttemptRegistry:
-    """Attempt bookkeeping: admission, idempotent cancel, bounded history."""
-
-    def __init__(self, max_terminal: int = 4096):
-        self._lock = threading.Lock()
-        self._active: dict[str, AttemptRecord] = {}
-        self._terminal: OrderedDict[str, AttemptRecord] = OrderedDict()
-        self._max_terminal = max_terminal
-
-    def begin(self, job_id: str, attempt_id: str, slot_limit: int) -> AttemptRecord:
-        with self._lock:
-            if attempt_id in self._active or attempt_id in self._terminal:
-                raise codes.ExecutionFailure(
-                    codes.INPUT_ATTEMPT_DUPLICATE, "attempt id already used"
-                )
-            if len(self._active) >= max(1, slot_limit):
-                raise codes.ExecutionFailure(
-                    codes.GPU_SLOTS_EXHAUSTED, "no free execution slot"
-                )
-            record = AttemptRecord(job_id=job_id, attempt_id=attempt_id)
-            self._active[attempt_id] = record
-            return record
-
-    def finish(self, attempt_id: str, terminal: str) -> None:
-        with self._lock:
-            record = self._active.pop(attempt_id, None)
-            if record is None:
-                return
-            record.terminal = terminal
-            self._terminal[attempt_id] = record
-            while len(self._terminal) > self._max_terminal:
-                self._terminal.popitem(last=False)
-
-    def active_count(self) -> int:
-        with self._lock:
-            return len(self._active)
-
-    def cancel(self, job_id: str, attempt_id: str) -> int:
-        """Idempotent by attempt id; returns a proto CancelDisposition."""
-        with self._lock:
-            record = self._active.get(attempt_id)
-            if record is not None:
-                if job_id and record.job_id and job_id != record.job_id:
-                    return pb2.CANCEL_DISPOSITION_NOT_FOUND
-                record.cancel.set()
-                return pb2.CANCEL_DISPOSITION_ACCEPTED
-            record = self._terminal.get(attempt_id)
-            if record is not None:
-                if job_id and record.job_id and job_id != record.job_id:
-                    return pb2.CANCEL_DISPOSITION_NOT_FOUND
-                return pb2.CANCEL_DISPOSITION_ALREADY_TERMINAL
-        return pb2.CANCEL_DISPOSITION_NOT_FOUND
-
-
-# ── request validation ────────────────────────────────────────────────────
-
-
-@dataclass
-class ValidatedRequest:
-    text: str
-    output_handle: str
-    output_media_type: str
-    output_size_bound: int
-    engine_kwargs: dict
-    deadline_monotonic: float
-    catalog_model_id: str
-
-
-def _validate_handle(handle: str, code: str = codes.INPUT_HANDLE_INVALID) -> str:
-    cleaned = (handle or "").strip()
-    if (
-        not cleaned
-        or "\x00" in cleaned
-        or "://" in cleaned
-        or not os.path.isabs(cleaned)
-        or os.path.normpath(cleaned) != cleaned
-    ):
-        raise codes.ExecutionFailure(code, "local handle must be an absolute path")
-    return cleaned
-
-
-def _read_input_file(artifact, max_bytes: int) -> bytes:
-    path = _validate_handle(artifact.local_handle)
-    try:
-        stat = os.lstat(path)
-    except OSError as exc:
-        raise codes.ExecutionFailure(
-            codes.STORAGE_READ_FAILED, f"input handle unreadable: {type(exc).__name__}"
-        )
-    import stat as stat_module  # noqa: PLC0415
-
-    if not stat_module.S_ISREG(stat.st_mode):
-        raise codes.ExecutionFailure(
-            codes.INPUT_HANDLE_INVALID, "input handle must be a regular file"
-        )
-    bound = max_bytes
-    if 0 < artifact.expected_size_bytes <= max_bytes:
-        bound = artifact.expected_size_bytes
-    if stat.st_size > bound:
-        raise codes.ExecutionFailure(
-            codes.INPUT_TEXT_TOO_LARGE, "input exceeds its size bound"
-        )
-    try:
-        with open(path, "rb") as fh:
-            data = fh.read(bound + 1)
-    except OSError as exc:
-        raise codes.ExecutionFailure(
-            codes.STORAGE_READ_FAILED, f"input read failed: {type(exc).__name__}"
-        )
-    if len(data) > bound:
-        raise codes.ExecutionFailure(
-            codes.INPUT_TEXT_TOO_LARGE, "input exceeds its size bound"
-        )
-    expected = (artifact.expected_sha256 or "").strip().lower().removeprefix("sha256:")
-    if expected:
-        import hashlib  # noqa: PLC0415
-
-        if hashlib.sha256(data).hexdigest() != expected:
-            raise codes.ExecutionFailure(
-                codes.INPUT_CHECKSUM_MISMATCH, "input checksum mismatch"
-            )
-    return data
-
-
-def _typed_parameter(name: str, value) -> object:
-    spec = PARAMETER_SPECS.get(name)
-    if spec is None:
-        raise codes.ExecutionFailure(
-            codes.INPUT_PARAMETER_UNKNOWN, f"unknown parameter {name!r}"
-        )
-    kind = spec[0]
-    which = value.WhichOneof("value")
-    if kind == "string":
-        if which != "string_value":
-            raise codes.ExecutionFailure(
-                codes.INPUT_PARAMETER_TYPE, f"parameter {name!r} must be a string"
-            )
-        text = value.string_value
-        if len(text) > spec[1]:
-            raise codes.ExecutionFailure(
-                codes.INPUT_PARAMETER_RANGE, f"parameter {name!r} too long"
-            )
-        return text
-    if kind == "integer":
-        if which != "integer_value":
-            raise codes.ExecutionFailure(
-                codes.INPUT_PARAMETER_TYPE, f"parameter {name!r} must be an integer"
-            )
-        number = value.integer_value
-        if not spec[1] <= number <= spec[2]:
-            raise codes.ExecutionFailure(
-                codes.INPUT_PARAMETER_RANGE, f"parameter {name!r} out of range"
-            )
-        return int(number)
-    if kind == "number":
-        if which == "number_value":
-            number = value.number_value
-        elif which == "integer_value":
-            number = float(value.integer_value)
-        else:
-            raise codes.ExecutionFailure(
-                codes.INPUT_PARAMETER_TYPE, f"parameter {name!r} must be a number"
-            )
-        if not spec[1] <= number <= spec[2]:
-            raise codes.ExecutionFailure(
-                codes.INPUT_PARAMETER_RANGE, f"parameter {name!r} out of range"
-            )
-        return float(number)
-    if which != "boolean_value":
-        raise codes.ExecutionFailure(
-            codes.INPUT_PARAMETER_TYPE, f"parameter {name!r} must be a boolean"
-        )
-    return bool(value.boolean_value)
-
-
-# ── the executor ──────────────────────────────────────────────────────────
-
-
-class Executor:
-    """Validates and runs attempts against an inventory + engine provider."""
-
-    def __init__(
-        self,
-        inventory,
-        engine_provider,
-        registry: AttemptRegistry,
-        *,
-        slot_limit: int = 1,
-        progress_interval: float = 0.5,
-        poll_interval: float = 0.02,
-        clock=time.monotonic,
-    ):
-        self._inventory = inventory
-        self._engine_provider = engine_provider
-        self._registry = registry
-        self._slot_limit = max(1, slot_limit)
-        self._progress_interval = progress_interval
-        self._poll_interval = poll_interval
-        self._clock = clock
-
-    # -- validation ----------------------------------------------------
-
-    def _validate(self, request) -> ValidatedRequest:
-        now_ms = int(time.time() * 1000)
-        if request.deadline_unix_ms <= now_ms:
-            raise codes.ExecutionFailure(
-                codes.INPUT_DEADLINE_INVALID, "deadline is not in the future"
-            )
-        budget_s = min((request.deadline_unix_ms - now_ms) / 1000.0, _MAX_DEADLINE_S)
-
-        model = self._validate_model(request.model)
-        self._validate_device(request.device_id)
-
-        text_artifact, ref_artifact = self._split_inputs(request.inputs)
-        output = self._single_output(request.outputs)
-        output_handle = _validate_handle(output.local_handle)
-        parent = os.path.dirname(output_handle)
-        if not os.path.isdir(parent):
-            raise codes.ExecutionFailure(
-                codes.INPUT_HANDLE_INVALID, "output handle directory does not exist"
-            )
-
-        raw = _read_input_file(text_artifact, _MAX_TEXT_BYTES)
-        try:
-            text = raw.decode("utf-8").strip()
-        except UnicodeDecodeError:
-            raise codes.ExecutionFailure(
-                codes.INPUT_TEXT_ENCODING, "input text is not valid UTF-8"
-            )
-        if not text:
-            raise codes.ExecutionFailure(codes.INPUT_TEXT_EMPTY, "input text is empty")
-
-        engine_kwargs: dict = {}
-        for name in sorted(request.parameters):
-            engine_kwargs[name] = _typed_parameter(name, request.parameters[name])
-        if ref_artifact is not None:
-            _read_input_file(ref_artifact, _MAX_REF_AUDIO_BYTES)  # existence/bounds/checksum
-            engine_kwargs["ref_audio"] = _validate_handle(ref_artifact.local_handle)
-
-        return ValidatedRequest(
-            text=text,
-            output_handle=output_handle,
-            output_media_type=output.media_type or "audio/wav",
-            output_size_bound=int(output.expected_size_bytes),
-            engine_kwargs=engine_kwargs,
-            deadline_monotonic=self._clock() + budget_s,
-            catalog_model_id=request.model.catalog_model_id,
-        )
-
-    def _validate_model(self, spec):
-        wanted = (spec.catalog_model_id or "").strip()
-        if not wanted:
-            raise codes.ExecutionFailure(
-                codes.INPUT_MODEL_UNKNOWN, "catalog model id is required"
-            )
-        matches = [
-            model
-            for model in self._inventory.models()
-            if model.catalog_model_id == wanted
-        ]
-        if not matches:
-            raise codes.ExecutionFailure(codes.INPUT_MODEL_UNKNOWN, "model not present")
-        model = matches[0]
-        if model.state != STATE_READY:
-            raise codes.ExecutionFailure(
-                codes.INPUT_MODEL_NOT_READY, "model is not READY"
-            )
-        if spec.model_version and spec.model_version != model.model_version:
-            raise codes.ExecutionFailure(
-                codes.INPUT_MODEL_UNKNOWN, "model version mismatch"
-            )
-        if not spec.model_digest or spec.model_digest != model.model_digest:
-            raise codes.ExecutionFailure(
-                codes.INPUT_MODEL_DIGEST_MISMATCH, "approved model digest mismatch"
-            )
-        if spec.precision and spec.precision not in model.precisions:
-            raise codes.ExecutionFailure(
-                codes.INPUT_MODEL_PRECISION, "precision not offered by this model"
-            )
-        return model
-
-    def _validate_device(self, device_id: str) -> None:
-        wanted = (device_id or "").strip()
-        if not wanted:
-            raise codes.ExecutionFailure(
-                codes.INPUT_DEVICE_UNKNOWN, "device id is required"
-            )
-        known = {device.device_id for device in self._inventory.devices()}
-        if wanted not in known:
-            raise codes.ExecutionFailure(
-                codes.INPUT_DEVICE_UNKNOWN, "device id not in inventory"
-            )
-
-    @staticmethod
-    def _split_inputs(inputs):
-        text_artifacts, audio_artifacts = [], []
-        for artifact in inputs:
-            if artifact.operation != pb2.LOCAL_ARTIFACT_OPERATION_READ:
-                raise codes.ExecutionFailure(
-                    codes.INPUT_ARTIFACTS_INVALID, "inputs must be READ artifacts"
-                )
-            media = artifact.media_type or ""
-            if media.startswith("audio/"):
-                audio_artifacts.append(artifact)
-            elif media == "" or media.startswith("text/"):
-                text_artifacts.append(artifact)
-            else:
-                raise codes.ExecutionFailure(
-                    codes.INPUT_ARTIFACTS_INVALID, f"unsupported input media {media!r}"
-                )
-        if len(text_artifacts) != 1 or len(audio_artifacts) > 1:
-            raise codes.ExecutionFailure(
-                codes.INPUT_ARTIFACTS_INVALID,
-                "tts needs exactly one text input and at most one reference audio",
-            )
-        return text_artifacts[0], (audio_artifacts[0] if audio_artifacts else None)
-
-    @staticmethod
-    def _single_output(outputs):
-        if len(outputs) != 1:
-            raise codes.ExecutionFailure(
-                codes.INPUT_ARTIFACTS_INVALID, "tts needs exactly one output artifact"
-            )
-        output = outputs[0]
-        if output.operation != pb2.LOCAL_ARTIFACT_OPERATION_WRITE:
-            raise codes.ExecutionFailure(
-                codes.INPUT_ARTIFACTS_INVALID, "output must be a WRITE artifact"
-            )
-        media = output.media_type or ""
-        if media and not media.startswith("audio/"):
-            raise codes.ExecutionFailure(
-                codes.INPUT_ARTIFACTS_INVALID, f"unsupported output media {media!r}"
-            )
-        return output
-
-    # -- execution -----------------------------------------------------
-
-    def execute(self, request, grpc_context=None):
-        """Generator of ``pb2.ExecuteResponse``. Never raises for a
-        classified failure — failures become terminal events."""
-        session = _Session(self, request)
-        return session.run(grpc_context)
-
-
-class _Session:
-    def __init__(self, executor: Executor, request):
-        self._x = executor
-        self.request = request
-        self.job_id = request.job_id
-        self.attempt_id = request.attempt_id
-        self.sequence = 0
-        self.phase = "model_load"
-        self.terminal_sent = False
-        self.chars = 0
-        self.gpu_ms = 0
-        self.cpu_ms = 0
-        self.output_audio_ms = 0
-
-    # event builders ---------------------------------------------------
-
-    def _event(self, **payload):
-        self.sequence += 1
-        return pb2.ExecuteResponse(
-            event=pb2.ExecutionEvent(
-                job_id=self.job_id,
-                attempt_id=self.attempt_id,
-                sequence=self.sequence,
-                observed_at_unix_ms=int(time.time() * 1000),
-                **payload,
-            )
-        )
-
-    def _measurements(self):
-        return pb2.RuntimeMeasurements(
-            normalized_input_characters=self.chars,
-            output_audio_ms=self.output_audio_ms,
-            gpu_execution_ms=self.gpu_ms,
-            cpu_execution_ms=self.cpu_ms,
-        )
-
-    def _failed(self, failure: codes.ExecutionFailure):
-        self.terminal_sent = True
-        return self._event(
-            failed=pb2.ExecutionFailed(
-                failure_class=failure.failure_class,
-                stable_code=failure.stable_code,
-                safe_detail=failure.safe_detail,
-                measurements=self._measurements(),
-            )
-        )
-
-    def _canceled(self):
-        self.terminal_sent = True
-        return self._event(
-            canceled=pb2.ExecutionCanceled(measurements=self._measurements())
-        )
-
-    # main flow --------------------------------------------------------
-
-    def run(self, grpc_context):
-        if not self.attempt_id.strip() or not self.job_id.strip():
-            yield self._failed(
-                codes.ExecutionFailure(
-                    codes.INPUT_ATTEMPT_IDENTITY, "job and attempt ids are required"
-                )
-            )
-            return
-        registry = self._x._registry
-        try:
-            record = registry.begin(self.job_id, self.attempt_id, self._x._slot_limit)
-        except codes.ExecutionFailure as failure:
-            yield self._failed(failure)
-            return
-        try:
-            yield from self._run_admitted(record, grpc_context)
-        finally:
-            terminal = "canceled"
-            if self.terminal_sent:
-                terminal = self._terminal_kind or "failed"
-            registry.finish(self.attempt_id, terminal)
-
-    _terminal_kind: str | None = None
-
-    def _run_admitted(self, record, grpc_context):
-        try:
-            validated = self._x._validate(self.request)
-        except codes.ExecutionFailure as failure:
-            self._terminal_kind = "failed"
-            yield self._failed(failure)
-            return
-        except Exception as exc:  # adapter bug — still a classified event
-            self._terminal_kind = "failed"
-            yield self._failed(
-                codes.ExecutionFailure(codes.RUNTIME_CRASH, f"{type(exc).__name__}")
-            )
-            return
-
-        self.chars = len(validated.text)
-        yield self._event(started=pb2.ExecutionStarted())
-
-        worker = _EngineWorker(self._x._engine_provider, validated, self)
-        worker.start()
-
-        clock = self._x._clock
-        next_progress = clock() + self._x._progress_interval
-        progress_events = 0
-        while not worker.done.wait(self._x._poll_interval):
-            if record.cancel.is_set() or (
-                grpc_context is not None and not grpc_context.is_active()
-            ):
-                self._terminal_kind = "canceled"
-                yield self._canceled()
-                return
-            now = clock()
-            if now >= validated.deadline_monotonic:
-                self._terminal_kind = "failed"
-                yield self._failed(codes.deadline_failure(self.phase))
-                return
-            if now >= next_progress and progress_events < _MAX_PROGRESS_EVENTS:
-                progress_events += 1
-                next_progress = now + self._x._progress_interval
-                permille = 100 if self.phase == "model_load" else 550
-                yield self._event(
-                    progress=pb2.ExecutionProgress(
-                        progress_permille=permille, stage_code=self.phase
-                    )
-                )
-
-        if record.cancel.is_set():
-            self._terminal_kind = "canceled"
-            yield self._canceled()
-            return
-        if worker.error is not None:
-            self._terminal_kind = "failed"
-            yield self._failed(codes.classify_engine_error(worker.error, worker.phase))
-            return
-
-        try:
-            manifest = self._write_output(worker, validated)
-        except codes.ExecutionFailure as failure:
-            self._terminal_kind = "failed"
-            yield self._failed(failure)
-            return
-        self._terminal_kind = "completed"
-        self.terminal_sent = True
-        yield self._event(
-            completed=pb2.ExecutionCompleted(
-                outputs=[manifest], measurements=self._measurements()
-            )
-        )
-
-    def _write_output(self, worker, validated: ValidatedRequest):
-        ensure_backend_on_path()
-        tensor = worker.result
-        sample_rate = worker.sample_rate
-        if tensor is None or not hasattr(tensor, "numel") or tensor.numel() == 0:
-            raise codes.ExecutionFailure(
-                codes.INFERENCE_BAD_OUTPUT, "engine returned no audio"
-            )
-        if not isinstance(sample_rate, int) or sample_rate <= 0:
-            raise codes.ExecutionFailure(
-                codes.INFERENCE_BAD_OUTPUT, "engine reported no sample rate"
-            )
-        try:
-            from services.audio_io import atomic_save_wav  # noqa: PLC0415
-
-            atomic_save_wav(validated.output_handle, tensor.detach().cpu(), sample_rate)
-        except codes.ExecutionFailure:
-            raise
-        except Exception as exc:
-            raise codes.ExecutionFailure(
-                codes.STORAGE_WRITE_FAILED, f"{type(exc).__name__}: {exc}"
-            )
-        try:
-            size = os.stat(validated.output_handle).st_size
-            sha = file_sha256(validated.output_handle)
-        except OSError as exc:
-            raise codes.ExecutionFailure(
-                codes.STORAGE_WRITE_FAILED, f"{type(exc).__name__}"
-            )
-        if 0 < validated.output_size_bound < size:
-            raise codes.ExecutionFailure(
-                codes.STORAGE_WRITE_FAILED, "output exceeds its size bound"
-            )
-        samples = tensor.numel() if tensor.dim() == 1 else tensor.shape[-1]
-        self.output_audio_ms = int(samples * 1000 / sample_rate)
-        return pb2.LocalArtifactManifest(
-            artifact_id=self.request.outputs[0].artifact_id,
-            local_handle=validated.output_handle,
-            size_bytes=size,
-            sha256=sha,
-            media_type=validated.output_media_type,
-            duration_ms=self.output_audio_ms,
-        )
-
-
-class _EngineWorker:
-    """Runs the engine on a daemon thread, recording phase and timings."""
-
-    def __init__(self, engine_provider, validated: ValidatedRequest, session: _Session):
-        self._engine_provider = engine_provider
-        self._validated = validated
-        self._session = session
-        self.done = threading.Event()
-        self.error: BaseException | None = None
-        self.result = None
-        self.sample_rate: int | None = None
-        self.phase = "model_load"
-
-    def start(self) -> None:
-        thread = threading.Thread(
-            target=self._run,
-            name=f"runtime-adapter-attempt-{self._session.attempt_id}",
-            daemon=True,
-        )
-        thread.start()
-
-    @staticmethod
-    def _synthesize(engine, text: str, params: dict):
-        """Use the same seeded native path as OSS Gallery and ovnode workers."""
-        from services import tts_backend  # noqa: PLC0415
-
-        if isinstance(engine, tts_backend.OmniVoiceBackend):
-            from api.routers.generation import _run_inference  # noqa: PLC0415
-
-            with tts_backend.engine_in_use(engine):
-                return _run_inference(
-                    engine._model, text, params.get("language"),
-                    params.get("ref_audio"), params.get("ref_text"),
-                    params.get("instruct"), params.get("duration"),
-                    params.get("num_step", 16), params.get("guidance_scale", 2.0),
-                    params.get("speed", 1.0), params.get("t_shift"),
-                    params.get("denoise", True), params.get("postprocess_output", True),
-                    params.get("layer_penalty_factor"),
-                    params.get("position_temperature"),
-                    params.get("class_temperature"), params.get("seed"),
-                )
-        return engine.generate(text, **params)
-
-    def _run(self) -> None:
-        wall_start = time.monotonic()
-        cpu_start = time.process_time()
-        try:
-            engine = self._engine_provider(self._validated.catalog_model_id)
-            ensure_ready = getattr(engine, "ensure_ready", None)
-            if callable(ensure_ready):
-                ensure_ready()
-            self.phase = "synthesis"
-            self._session.phase = "synthesis"
-            synth_start = time.monotonic()
-            self.result = self._synthesize(engine, self._validated.text, self._validated.engine_kwargs)
-            rate = getattr(engine, "sample_rate", None)
-            self.sample_rate = int(rate) if isinstance(rate, (int, float)) and rate else None
-            self._session.gpu_ms = int((time.monotonic() - synth_start) * 1000)
-        except BaseException as exc:  # classified later, never lost
-            self.error = exc
-        finally:
-            self._session.cpu_ms = int((time.process_time() - cpu_start) * 1000)
-            if self._session.gpu_ms == 0 and self.error is None:
-                self._session.gpu_ms = int((time.monotonic() - wall_start) * 1000)
-            self.done.set()

backend/runtime_adapter/gen/__init__.py

@@ -1,5 +0,0 @@
-"""Generated protocol stubs — DO NOT EDIT.
-
-Regenerate with ``uv run python scripts/gen_runtime_adapter_protocol.py``
-after any change to ``../runtime_adapter.proto``.
-"""

backend/runtime_adapter/gen/runtime_adapter_pb2.pyi

@@ -1,330 +0,0 @@
-from google.protobuf.internal import containers as _containers
-from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import message as _message
-from collections.abc import Iterable as _Iterable, Mapping as _Mapping
-from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
-
-DESCRIPTOR: _descriptor.FileDescriptor
-
-class ServingState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    SERVING_STATE_UNSPECIFIED: _ClassVar[ServingState]
-    SERVING_STATE_READY: _ClassVar[ServingState]
-    SERVING_STATE_DEGRADED: _ClassVar[ServingState]
-    SERVING_STATE_UNHEALTHY: _ClassVar[ServingState]
-
-class RuntimeModelState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    RUNTIME_MODEL_STATE_UNSPECIFIED: _ClassVar[RuntimeModelState]
-    RUNTIME_MODEL_STATE_INSTALLED: _ClassVar[RuntimeModelState]
-    RUNTIME_MODEL_STATE_LOADING: _ClassVar[RuntimeModelState]
-    RUNTIME_MODEL_STATE_READY: _ClassVar[RuntimeModelState]
-    RUNTIME_MODEL_STATE_FAILED: _ClassVar[RuntimeModelState]
-
-class LocalArtifactOperation(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    LOCAL_ARTIFACT_OPERATION_UNSPECIFIED: _ClassVar[LocalArtifactOperation]
-    LOCAL_ARTIFACT_OPERATION_READ: _ClassVar[LocalArtifactOperation]
-    LOCAL_ARTIFACT_OPERATION_WRITE: _ClassVar[LocalArtifactOperation]
-
-class RuntimeFailureClass(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    RUNTIME_FAILURE_CLASS_UNSPECIFIED: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_INPUT: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_MODEL_LOAD: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_INFERENCE: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_GPU_RESOURCE: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_LOCAL_STORAGE: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_RUNTIME: _ClassVar[RuntimeFailureClass]
-    RUNTIME_FAILURE_CLASS_CANCELED: _ClassVar[RuntimeFailureClass]
-
-class CancelDisposition(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
-    __slots__ = ()
-    CANCEL_DISPOSITION_UNSPECIFIED: _ClassVar[CancelDisposition]
-    CANCEL_DISPOSITION_ACCEPTED: _ClassVar[CancelDisposition]
-    CANCEL_DISPOSITION_ALREADY_TERMINAL: _ClassVar[CancelDisposition]
-    CANCEL_DISPOSITION_NOT_FOUND: _ClassVar[CancelDisposition]
-SERVING_STATE_UNSPECIFIED: ServingState
-SERVING_STATE_READY: ServingState
-SERVING_STATE_DEGRADED: ServingState
-SERVING_STATE_UNHEALTHY: ServingState
-RUNTIME_MODEL_STATE_UNSPECIFIED: RuntimeModelState
-RUNTIME_MODEL_STATE_INSTALLED: RuntimeModelState
-RUNTIME_MODEL_STATE_LOADING: RuntimeModelState
-RUNTIME_MODEL_STATE_READY: RuntimeModelState
-RUNTIME_MODEL_STATE_FAILED: RuntimeModelState
-LOCAL_ARTIFACT_OPERATION_UNSPECIFIED: LocalArtifactOperation
-LOCAL_ARTIFACT_OPERATION_READ: LocalArtifactOperation
-LOCAL_ARTIFACT_OPERATION_WRITE: LocalArtifactOperation
-RUNTIME_FAILURE_CLASS_UNSPECIFIED: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_INPUT: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_MODEL_LOAD: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_INFERENCE: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_GPU_RESOURCE: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_LOCAL_STORAGE: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_RUNTIME: RuntimeFailureClass
-RUNTIME_FAILURE_CLASS_CANCELED: RuntimeFailureClass
-CANCEL_DISPOSITION_UNSPECIFIED: CancelDisposition
-CANCEL_DISPOSITION_ACCEPTED: CancelDisposition
-CANCEL_DISPOSITION_ALREADY_TERMINAL: CancelDisposition
-CANCEL_DISPOSITION_NOT_FOUND: CancelDisposition
-
-class ExecuteResponse(_message.Message):
-    __slots__ = ("event",)
-    EVENT_FIELD_NUMBER: _ClassVar[int]
-    event: ExecutionEvent
-    def __init__(self, event: _Optional[_Union[ExecutionEvent, _Mapping]] = ...) -> None: ...
-
-class HealthRequest(_message.Message):
-    __slots__ = ()
-    def __init__(self) -> None: ...
-
-class HealthResponse(_message.Message):
-    __slots__ = ("state", "runtime_version", "adapter_version", "health_flags")
-    STATE_FIELD_NUMBER: _ClassVar[int]
-    RUNTIME_VERSION_FIELD_NUMBER: _ClassVar[int]
-    ADAPTER_VERSION_FIELD_NUMBER: _ClassVar[int]
-    HEALTH_FLAGS_FIELD_NUMBER: _ClassVar[int]
-    state: ServingState
-    runtime_version: str
-    adapter_version: str
-    health_flags: _containers.RepeatedScalarFieldContainer[str]
-    def __init__(self, state: _Optional[_Union[ServingState, str]] = ..., runtime_version: _Optional[str] = ..., adapter_version: _Optional[str] = ..., health_flags: _Optional[_Iterable[str]] = ...) -> None: ...
-
-class GetCapabilitiesRequest(_message.Message):
-    __slots__ = ()
-    def __init__(self) -> None: ...
-
-class GetCapabilitiesResponse(_message.Message):
-    __slots__ = ("runtime_version", "adapter_version", "devices", "models")
-    RUNTIME_VERSION_FIELD_NUMBER: _ClassVar[int]
-    ADAPTER_VERSION_FIELD_NUMBER: _ClassVar[int]
-    DEVICES_FIELD_NUMBER: _ClassVar[int]
-    MODELS_FIELD_NUMBER: _ClassVar[int]
-    runtime_version: str
-    adapter_version: str
-    devices: _containers.RepeatedCompositeFieldContainer[RuntimeDevice]
-    models: _containers.RepeatedCompositeFieldContainer[RuntimeModel]
-    def __init__(self, runtime_version: _Optional[str] = ..., adapter_version: _Optional[str] = ..., devices: _Optional[_Iterable[_Union[RuntimeDevice, _Mapping]]] = ..., models: _Optional[_Iterable[_Union[RuntimeModel, _Mapping]]] = ...) -> None: ...
-
-class RuntimeDevice(_message.Message):
-    __slots__ = ("device_id", "hardware_class", "total_vram_bytes", "total_slots", "free_slots")
-    DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
-    HARDWARE_CLASS_FIELD_NUMBER: _ClassVar[int]
-    TOTAL_VRAM_BYTES_FIELD_NUMBER: _ClassVar[int]
-    TOTAL_SLOTS_FIELD_NUMBER: _ClassVar[int]
-    FREE_SLOTS_FIELD_NUMBER: _ClassVar[int]
-    device_id: str
-    hardware_class: str
-    total_vram_bytes: int
-    total_slots: int
-    free_slots: int
-    def __init__(self, device_id: _Optional[str] = ..., hardware_class: _Optional[str] = ..., total_vram_bytes: _Optional[int] = ..., total_slots: _Optional[int] = ..., free_slots: _Optional[int] = ...) -> None: ...
-
-class RuntimeModel(_message.Message):
-    __slots__ = ("catalog_model_id", "model_version", "model_digest", "precisions", "features", "state")
-    CATALOG_MODEL_ID_FIELD_NUMBER: _ClassVar[int]
-    MODEL_VERSION_FIELD_NUMBER: _ClassVar[int]
-    MODEL_DIGEST_FIELD_NUMBER: _ClassVar[int]
-    PRECISIONS_FIELD_NUMBER: _ClassVar[int]
-    FEATURES_FIELD_NUMBER: _ClassVar[int]
-    STATE_FIELD_NUMBER: _ClassVar[int]
-    catalog_model_id: str
-    model_version: str
-    model_digest: str
-    precisions: _containers.RepeatedScalarFieldContainer[str]
-    features: _containers.RepeatedScalarFieldContainer[str]
-    state: RuntimeModelState
-    def __init__(self, catalog_model_id: _Optional[str] = ..., model_version: _Optional[str] = ..., model_digest: _Optional[str] = ..., precisions: _Optional[_Iterable[str]] = ..., features: _Optional[_Iterable[str]] = ..., state: _Optional[_Union[RuntimeModelState, str]] = ...) -> None: ...
-
-class ExecuteRequest(_message.Message):
-    __slots__ = ("job_id", "attempt_id", "device_id", "slot_id", "model", "parameters", "inputs", "outputs", "deadline_unix_ms", "maximum_preview_bytes")
-    class ParametersEntry(_message.Message):
-        __slots__ = ("key", "value")
-        KEY_FIELD_NUMBER: _ClassVar[int]
-        VALUE_FIELD_NUMBER: _ClassVar[int]
-        key: str
-        value: ParameterValue
-        def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[ParameterValue, _Mapping]] = ...) -> None: ...
-    JOB_ID_FIELD_NUMBER: _ClassVar[int]
-    ATTEMPT_ID_FIELD_NUMBER: _ClassVar[int]
-    DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
-    SLOT_ID_FIELD_NUMBER: _ClassVar[int]
-    MODEL_FIELD_NUMBER: _ClassVar[int]
-    PARAMETERS_FIELD_NUMBER: _ClassVar[int]
-    INPUTS_FIELD_NUMBER: _ClassVar[int]
-    OUTPUTS_FIELD_NUMBER: _ClassVar[int]
-    DEADLINE_UNIX_MS_FIELD_NUMBER: _ClassVar[int]
-    MAXIMUM_PREVIEW_BYTES_FIELD_NUMBER: _ClassVar[int]
-    job_id: str
-    attempt_id: str
-    device_id: str
-    slot_id: str
-    model: ModelSpec
-    parameters: _containers.MessageMap[str, ParameterValue]
-    inputs: _containers.RepeatedCompositeFieldContainer[LocalArtifact]
-    outputs: _containers.RepeatedCompositeFieldContainer[LocalArtifact]
-    deadline_unix_ms: int
-    maximum_preview_bytes: int
-    def __init__(self, job_id: _Optional[str] = ..., attempt_id: _Optional[str] = ..., device_id: _Optional[str] = ..., slot_id: _Optional[str] = ..., model: _Optional[_Union[ModelSpec, _Mapping]] = ..., parameters: _Optional[_Mapping[str, ParameterValue]] = ..., inputs: _Optional[_Iterable[_Union[LocalArtifact, _Mapping]]] = ..., outputs: _Optional[_Iterable[_Union[LocalArtifact, _Mapping]]] = ..., deadline_unix_ms: _Optional[int] = ..., maximum_preview_bytes: _Optional[int] = ...) -> None: ...
-
-class ModelSpec(_message.Message):
-    __slots__ = ("catalog_model_id", "model_version", "model_digest", "precision")
-    CATALOG_MODEL_ID_FIELD_NUMBER: _ClassVar[int]
-    MODEL_VERSION_FIELD_NUMBER: _ClassVar[int]
-    MODEL_DIGEST_FIELD_NUMBER: _ClassVar[int]
-    PRECISION_FIELD_NUMBER: _ClassVar[int]
-    catalog_model_id: str
-    model_version: str
-    model_digest: str
-    precision: str
-    def __init__(self, catalog_model_id: _Optional[str] = ..., model_version: _Optional[str] = ..., model_digest: _Optional[str] = ..., precision: _Optional[str] = ...) -> None: ...
-
-class ParameterValue(_message.Message):
-    __slots__ = ("string_value", "integer_value", "number_value", "boolean_value")
-    STRING_VALUE_FIELD_NUMBER: _ClassVar[int]
-    INTEGER_VALUE_FIELD_NUMBER: _ClassVar[int]
-    NUMBER_VALUE_FIELD_NUMBER: _ClassVar[int]
-    BOOLEAN_VALUE_FIELD_NUMBER: _ClassVar[int]
-    string_value: str
-    integer_value: int
-    number_value: float
-    boolean_value: bool
-    def __init__(self, string_value: _Optional[str] = ..., integer_value: _Optional[int] = ..., number_value: _Optional[float] = ..., boolean_value: _Optional[bool] = ...) -> None: ...
-
-class LocalArtifact(_message.Message):
-    __slots__ = ("artifact_id", "local_handle", "operation", "expected_size_bytes", "expected_sha256", "media_type")
-    ARTIFACT_ID_FIELD_NUMBER: _ClassVar[int]
-    LOCAL_HANDLE_FIELD_NUMBER: _ClassVar[int]
-    OPERATION_FIELD_NUMBER: _ClassVar[int]
-    EXPECTED_SIZE_BYTES_FIELD_NUMBER: _ClassVar[int]
-    EXPECTED_SHA256_FIELD_NUMBER: _ClassVar[int]
-    MEDIA_TYPE_FIELD_NUMBER: _ClassVar[int]
-    artifact_id: str
-    local_handle: str
-    operation: LocalArtifactOperation
-    expected_size_bytes: int
-    expected_sha256: str
-    media_type: str
-    def __init__(self, artifact_id: _Optional[str] = ..., local_handle: _Optional[str] = ..., operation: _Optional[_Union[LocalArtifactOperation, str]] = ..., expected_size_bytes: _Optional[int] = ..., expected_sha256: _Optional[str] = ..., media_type: _Optional[str] = ...) -> None: ...
-
-class ExecutionEvent(_message.Message):
-    __slots__ = ("job_id", "attempt_id", "sequence", "observed_at_unix_ms", "started", "progress", "preview", "completed", "failed", "canceled")
-    JOB_ID_FIELD_NUMBER: _ClassVar[int]
-    ATTEMPT_ID_FIELD_NUMBER: _ClassVar[int]
-    SEQUENCE_FIELD_NUMBER: _ClassVar[int]
-    OBSERVED_AT_UNIX_MS_FIELD_NUMBER: _ClassVar[int]
-    STARTED_FIELD_NUMBER: _ClassVar[int]
-    PROGRESS_FIELD_NUMBER: _ClassVar[int]
-    PREVIEW_FIELD_NUMBER: _ClassVar[int]
-    COMPLETED_FIELD_NUMBER: _ClassVar[int]
-    FAILED_FIELD_NUMBER: _ClassVar[int]
-    CANCELED_FIELD_NUMBER: _ClassVar[int]
-    job_id: str
-    attempt_id: str
-    sequence: int
-    observed_at_unix_ms: int
-    started: ExecutionStarted
-    progress: ExecutionProgress
-    preview: PreviewChunk
-    completed: ExecutionCompleted
-    failed: ExecutionFailed
-    canceled: ExecutionCanceled
-    def __init__(self, job_id: _Optional[str] = ..., attempt_id: _Optional[str] = ..., sequence: _Optional[int] = ..., observed_at_unix_ms: _Optional[int] = ..., started: _Optional[_Union[ExecutionStarted, _Mapping]] = ..., progress: _Optional[_Union[ExecutionProgress, _Mapping]] = ..., preview: _Optional[_Union[PreviewChunk, _Mapping]] = ..., completed: _Optional[_Union[ExecutionCompleted, _Mapping]] = ..., failed: _Optional[_Union[ExecutionFailed, _Mapping]] = ..., canceled: _Optional[_Union[ExecutionCanceled, _Mapping]] = ...) -> None: ...
-
-class ExecutionStarted(_message.Message):
-    __slots__ = ()
-    def __init__(self) -> None: ...
-
-class ExecutionProgress(_message.Message):
-    __slots__ = ("progress_permille", "stage_code")
-    PROGRESS_PERMILLE_FIELD_NUMBER: _ClassVar[int]
-    STAGE_CODE_FIELD_NUMBER: _ClassVar[int]
-    progress_permille: int
-    stage_code: str
-    def __init__(self, progress_permille: _Optional[int] = ..., stage_code: _Optional[str] = ...) -> None: ...
-
-class PreviewChunk(_message.Message):
-    __slots__ = ("sequence", "media_type", "data")
-    SEQUENCE_FIELD_NUMBER: _ClassVar[int]
-    MEDIA_TYPE_FIELD_NUMBER: _ClassVar[int]
-    DATA_FIELD_NUMBER: _ClassVar[int]
-    sequence: int
-    media_type: str
-    data: bytes
-    def __init__(self, sequence: _Optional[int] = ..., media_type: _Optional[str] = ..., data: _Optional[bytes] = ...) -> None: ...
-
-class ExecutionCompleted(_message.Message):
-    __slots__ = ("outputs", "measurements")
-    OUTPUTS_FIELD_NUMBER: _ClassVar[int]
-    MEASUREMENTS_FIELD_NUMBER: _ClassVar[int]
-    outputs: _containers.RepeatedCompositeFieldContainer[LocalArtifactManifest]
-    measurements: RuntimeMeasurements
-    def __init__(self, outputs: _Optional[_Iterable[_Union[LocalArtifactManifest, _Mapping]]] = ..., measurements: _Optional[_Union[RuntimeMeasurements, _Mapping]] = ...) -> None: ...
-
-class LocalArtifactManifest(_message.Message):
-    __slots__ = ("artifact_id", "local_handle", "size_bytes", "sha256", "media_type", "duration_ms")
-    ARTIFACT_ID_FIELD_NUMBER: _ClassVar[int]
-    LOCAL_HANDLE_FIELD_NUMBER: _ClassVar[int]
-    SIZE_BYTES_FIELD_NUMBER: _ClassVar[int]
-    SHA256_FIELD_NUMBER: _ClassVar[int]
-    MEDIA_TYPE_FIELD_NUMBER: _ClassVar[int]
-    DURATION_MS_FIELD_NUMBER: _ClassVar[int]
-    artifact_id: str
-    local_handle: str
-    size_bytes: int
-    sha256: str
-    media_type: str
-    duration_ms: int
-    def __init__(self, artifact_id: _Optional[str] = ..., local_handle: _Optional[str] = ..., size_bytes: _Optional[int] = ..., sha256: _Optional[str] = ..., media_type: _Optional[str] = ..., duration_ms: _Optional[int] = ...) -> None: ...
-
-class ExecutionFailed(_message.Message):
-    __slots__ = ("failure_class", "stable_code", "safe_detail", "measurements")
-    FAILURE_CLASS_FIELD_NUMBER: _ClassVar[int]
-    STABLE_CODE_FIELD_NUMBER: _ClassVar[int]
-    SAFE_DETAIL_FIELD_NUMBER: _ClassVar[int]
-    MEASUREMENTS_FIELD_NUMBER: _ClassVar[int]
-    failure_class: RuntimeFailureClass
-    stable_code: str
-    safe_detail: str
-    measurements: RuntimeMeasurements
-    def __init__(self, failure_class: _Optional[_Union[RuntimeFailureClass, str]] = ..., stable_code: _Optional[str] = ..., safe_detail: _Optional[str] = ..., measurements: _Optional[_Union[RuntimeMeasurements, _Mapping]] = ...) -> None: ...
-
-class ExecutionCanceled(_message.Message):
-    __slots__ = ("measurements",)
-    MEASUREMENTS_FIELD_NUMBER: _ClassVar[int]
-    measurements: RuntimeMeasurements
-    def __init__(self, measurements: _Optional[_Union[RuntimeMeasurements, _Mapping]] = ...) -> None: ...
-
-class RuntimeMeasurements(_message.Message):
-    __slots__ = ("normalized_input_characters", "input_audio_ms", "output_audio_ms", "gpu_execution_ms", "cpu_execution_ms")
-    NORMALIZED_INPUT_CHARACTERS_FIELD_NUMBER: _ClassVar[int]
-    INPUT_AUDIO_MS_FIELD_NUMBER: _ClassVar[int]
-    OUTPUT_AUDIO_MS_FIELD_NUMBER: _ClassVar[int]
-    GPU_EXECUTION_MS_FIELD_NUMBER: _ClassVar[int]
-    CPU_EXECUTION_MS_FIELD_NUMBER: _ClassVar[int]
-    normalized_input_characters: int
-    input_audio_ms: int
-    output_audio_ms: int
-    gpu_execution_ms: int
-    cpu_execution_ms: int
-    def __init__(self, normalized_input_characters: _Optional[int] = ..., input_audio_ms: _Optional[int] = ..., output_audio_ms: _Optional[int] = ..., gpu_execution_ms: _Optional[int] = ..., cpu_execution_ms: _Optional[int] = ...) -> None: ...
-
-class CancelRequest(_message.Message):
-    __slots__ = ("job_id", "attempt_id", "reason_code", "deadline_unix_ms")
-    JOB_ID_FIELD_NUMBER: _ClassVar[int]
-    ATTEMPT_ID_FIELD_NUMBER: _ClassVar[int]
-    REASON_CODE_FIELD_NUMBER: _ClassVar[int]
-    DEADLINE_UNIX_MS_FIELD_NUMBER: _ClassVar[int]
-    job_id: str
-    attempt_id: str
-    reason_code: str
-    deadline_unix_ms: int
-    def __init__(self, job_id: _Optional[str] = ..., attempt_id: _Optional[str] = ..., reason_code: _Optional[str] = ..., deadline_unix_ms: _Optional[int] = ...) -> None: ...
-
-class CancelResponse(_message.Message):
-    __slots__ = ("disposition",)
-    DISPOSITION_FIELD_NUMBER: _ClassVar[int]
-    disposition: CancelDisposition
-    def __init__(self, disposition: _Optional[_Union[CancelDisposition, str]] = ...) -> None: ...

backend/runtime_adapter/gen/runtime_adapter_pb2_grpc.py

@@ -1,229 +0,0 @@
-# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
-"""Client and server classes corresponding to protobuf-defined services."""
-import grpc
-import warnings
-
-from . import runtime_adapter_pb2 as runtime__adapter__pb2
-
-GRPC_GENERATED_VERSION = '1.81.1'
-GRPC_VERSION = grpc.__version__
-_version_not_supported = False
-
-try:
-    from grpc._utilities import first_version_is_lower
-    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
-except ImportError:
-    _version_not_supported = True
-
-if _version_not_supported:
-    raise RuntimeError(
-        f'The grpc package installed is at version {GRPC_VERSION},'
-        + ' but the generated code in runtime_adapter_pb2_grpc.py depends on'
-        + f' grpcio>={GRPC_GENERATED_VERSION}.'
-        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
-        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
-    )
-
-
-class RuntimeAdapterServiceStub:
-    """RuntimeAdapterService is local to a GPU Node and is never publicly exposed.
-    """
-
-    def __init__(self, channel):
-        """Constructor.
-
-        Args:
-            channel: A grpc.Channel.
-        """
-        self.Health = channel.unary_unary(
-                '/voicestudio.runtime.v1.RuntimeAdapterService/Health',
-                request_serializer=runtime__adapter__pb2.HealthRequest.SerializeToString,
-                response_deserializer=runtime__adapter__pb2.HealthResponse.FromString,
-                _registered_method=True)
-        self.GetCapabilities = channel.unary_unary(
-                '/voicestudio.runtime.v1.RuntimeAdapterService/GetCapabilities',
-                request_serializer=runtime__adapter__pb2.GetCapabilitiesRequest.SerializeToString,
-                response_deserializer=runtime__adapter__pb2.GetCapabilitiesResponse.FromString,
-                _registered_method=True)
-        self.Execute = channel.unary_stream(
-                '/voicestudio.runtime.v1.RuntimeAdapterService/Execute',
-                request_serializer=runtime__adapter__pb2.ExecuteRequest.SerializeToString,
-                response_deserializer=runtime__adapter__pb2.ExecuteResponse.FromString,
-                _registered_method=True)
-        self.Cancel = channel.unary_unary(
-                '/voicestudio.runtime.v1.RuntimeAdapterService/Cancel',
-                request_serializer=runtime__adapter__pb2.CancelRequest.SerializeToString,
-                response_deserializer=runtime__adapter__pb2.CancelResponse.FromString,
-                _registered_method=True)
-
-
-class RuntimeAdapterServiceServicer:
-    """RuntimeAdapterService is local to a GPU Node and is never publicly exposed.
-    """
-
-    def Health(self, request, context):
-        """Missing associated documentation comment in .proto file."""
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-    def GetCapabilities(self, request, context):
-        """Missing associated documentation comment in .proto file."""
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-    def Execute(self, request, context):
-        """Missing associated documentation comment in .proto file."""
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-    def Cancel(self, request, context):
-        """Missing associated documentation comment in .proto file."""
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-
-def add_RuntimeAdapterServiceServicer_to_server(servicer, server):
-    rpc_method_handlers = {
-            'Health': grpc.unary_unary_rpc_method_handler(
-                    servicer.Health,
-                    request_deserializer=runtime__adapter__pb2.HealthRequest.FromString,
-                    response_serializer=runtime__adapter__pb2.HealthResponse.SerializeToString,
-            ),
-            'GetCapabilities': grpc.unary_unary_rpc_method_handler(
-                    servicer.GetCapabilities,
-                    request_deserializer=runtime__adapter__pb2.GetCapabilitiesRequest.FromString,
-                    response_serializer=runtime__adapter__pb2.GetCapabilitiesResponse.SerializeToString,
-            ),
-            'Execute': grpc.unary_stream_rpc_method_handler(
-                    servicer.Execute,
-                    request_deserializer=runtime__adapter__pb2.ExecuteRequest.FromString,
-                    response_serializer=runtime__adapter__pb2.ExecuteResponse.SerializeToString,
-            ),
-            'Cancel': grpc.unary_unary_rpc_method_handler(
-                    servicer.Cancel,
-                    request_deserializer=runtime__adapter__pb2.CancelRequest.FromString,
-                    response_serializer=runtime__adapter__pb2.CancelResponse.SerializeToString,
-            ),
-    }
-    generic_handler = grpc.method_handlers_generic_handler(
-            'voicestudio.runtime.v1.RuntimeAdapterService', rpc_method_handlers)
-    server.add_generic_rpc_handlers((generic_handler,))
-    server.add_registered_method_handlers('voicestudio.runtime.v1.RuntimeAdapterService', rpc_method_handlers)
-
-
- # This class is part of an EXPERIMENTAL API.
-class RuntimeAdapterService:
-    """RuntimeAdapterService is local to a GPU Node and is never publicly exposed.
-    """
-
-    @staticmethod
-    def Health(request,
-            target,
-            options=(),
-            channel_credentials=None,
-            call_credentials=None,
-            insecure=False,
-            compression=None,
-            wait_for_ready=None,
-            timeout=None,
-            metadata=None):
-        return grpc.experimental.unary_unary(
-            request,
-            target,
-            '/voicestudio.runtime.v1.RuntimeAdapterService/Health',
-            runtime__adapter__pb2.HealthRequest.SerializeToString,
-            runtime__adapter__pb2.HealthResponse.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-            _registered_method=True)
-
-    @staticmethod
-    def GetCapabilities(request,
-            target,
-            options=(),
-            channel_credentials=None,
-            call_credentials=None,
-            insecure=False,
-            compression=None,
-            wait_for_ready=None,
-            timeout=None,
-            metadata=None):
-        return grpc.experimental.unary_unary(
-            request,
-            target,
-            '/voicestudio.runtime.v1.RuntimeAdapterService/GetCapabilities',
-            runtime__adapter__pb2.GetCapabilitiesRequest.SerializeToString,
-            runtime__adapter__pb2.GetCapabilitiesResponse.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-            _registered_method=True)
-
-    @staticmethod
-    def Execute(request,
-            target,
-            options=(),
-            channel_credentials=None,
-            call_credentials=None,
-            insecure=False,
-            compression=None,
-            wait_for_ready=None,
-            timeout=None,
-            metadata=None):
-        return grpc.experimental.unary_stream(
-            request,
-            target,
-            '/voicestudio.runtime.v1.RuntimeAdapterService/Execute',
-            runtime__adapter__pb2.ExecuteRequest.SerializeToString,
-            runtime__adapter__pb2.ExecuteResponse.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-            _registered_method=True)
-
-    @staticmethod
-    def Cancel(request,
-            target,
-            options=(),
-            channel_credentials=None,
-            call_credentials=None,
-            insecure=False,
-            compression=None,
-            wait_for_ready=None,
-            timeout=None,
-            metadata=None):
-        return grpc.experimental.unary_unary(
-            request,
-            target,
-            '/voicestudio.runtime.v1.RuntimeAdapterService/Cancel',
-            runtime__adapter__pb2.CancelRequest.SerializeToString,
-            runtime__adapter__pb2.CancelResponse.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-            _registered_method=True)

backend/runtime_adapter/inventory.py

@@ -1,318 +0,0 @@
-"""Device and model inventory reported through Health/GetCapabilities.
-
-The server is written against the small protocol at the top of this module so
-tests can substitute fakes; :class:`ProductionInventory` is the real thing,
-wired to ``services.tts_backend``'s engine registry, ``services.hf_revisions``
-pinned revisions, and :mod:`runtime_adapter.digest`.
-
-State rules (mirrors the Go preflight's expectations):
-
-- READY is **explicit**: engine registered, availability probe passed, the
-  pinned snapshot fully present on disk, and a digest computed. Anything
-  less is INSTALLED / LOADING / FAILED — never READY.
-- A loading or failed model is still listed (with its true state) so the
-  Gateway can observe it; only READY models are schedulable.
-"""
-from __future__ import annotations
-
-import os
-import threading
-import time
-from dataclasses import dataclass, field
-
-from . import SLOTS_ENV
-from ._paths import ensure_backend_on_path
-from .digest import snapshot_digest
-
-STATE_INSTALLED = "installed"
-STATE_LOADING = "loading"
-STATE_READY = "ready"
-STATE_FAILED = "failed"
-
-
-@dataclass(frozen=True)
-class DeviceInfo:
-    device_id: str
-    hardware_class: str
-    total_vram_bytes: int
-    total_slots: int
-    free_slots: int
-
-
-@dataclass(frozen=True)
-class ModelInfo:
-    catalog_model_id: str
-    model_version: str
-    model_digest: str
-    precisions: tuple[str, ...] = ()
-    features: tuple[str, ...] = ()
-    state: str = STATE_INSTALLED
-
-
-#: Engines this adapter can attest as digest-pinned models: TTS engine id →
-#: curated Hugging Face repo (must be pinned in ``services.hf_revisions``).
-#: Engines without a single pinned weights repo (external API servers,
-#: multi-model muxes) are deliberately absent — they cannot be digest-pinned.
-ENGINE_MODEL_REPOS: dict[str, str] = {
-    "omnivoice": "k2-fsa/OmniVoice",
-    "voxcpm2": "openbmb/VoxCPM2",
-    "moss-tts-nano": "OpenMOSS-Team/MOSS-TTS-Nano-100M",
-    "kittentts": "KittenML/kitten-tts-mini-0.8",
-    "cosyvoice": "FunAudioLLM/Fun-CosyVoice3-0.5B-2512",
-    "moss-tts-v15": "OpenMOSS-Team/MOSS-TTS-v1.5",
-}
-
-
-def catalog_model_version(revision: str, model_digest: str) -> str:
-    """Return the immutable catalog version for an attested model snapshot.
-
-    A Hugging Face revision names source history, not necessarily the exact
-    snapshot bytes installed on a node.  The catalog version therefore carries
-    a short, deterministic digest suffix.  A changed snapshot becomes a new
-    catalog identity instead of mutating an identity retained by Jobs.
-    """
-    digest = model_digest.removeprefix("sha256:")
-    if len(revision) != 40 or len(digest) != 64:
-        raise ValueError("model identity requires a SHA revision and SHA-256 digest")
-    return f"{revision}+sha256-{digest[:16]}"
-
-
-def slots_per_device(default: int = 1) -> int:
-    raw = os.environ.get(SLOTS_ENV, "").strip()
-    try:
-        value = int(raw) if raw else default
-    except ValueError:
-        return default
-    return max(1, min(value, 64))
-
-
-@dataclass
-class ProductionInventory:
-    """Real host inventory. All heavy imports happen inside methods.
-
-    ``models()`` is memoized for ``model_ttl_s`` under a lock: the first call
-    hashes every installed snapshot (minutes for multi-GB weights, then cached
-    in the on-disk digest sidecar), and Health + GetCapabilities arrive
-    back-to-back. Call :meth:`warm` before serving so the first RPC never
-    pays the hashing cost inside its deadline.
-    """
-
-    slots: int = field(default_factory=slots_per_device)
-    model_ttl_s: float = 15.0
-
-    def __post_init__(self):
-        self._model_lock = threading.Lock()
-        self._model_cache: list[ModelInfo] | None = None
-        self._model_cache_at = 0.0
-
-    def warm(self) -> None:
-        self.models()
-
-    def devices(self, busy_slots: int = 0) -> list[DeviceInfo]:
-        ensure_backend_on_path()
-        devices = self._accelerators() or [self._cpu_device()]
-        return [self._with_slots(device, busy_slots) for device in devices]
-
-    def _with_slots(self, device: DeviceInfo, busy_slots: int) -> DeviceInfo:
-        free = max(0, min(device.total_slots - busy_slots, device.total_slots))
-        return DeviceInfo(
-            device_id=device.device_id,
-            hardware_class=device.hardware_class,
-            total_vram_bytes=device.total_vram_bytes,
-            total_slots=device.total_slots,
-            free_slots=free,
-        )
-
-    def _accelerators(self) -> list[DeviceInfo]:
-        try:
-            import torch  # noqa: PLC0415
-        except Exception:
-            return []
-        found: list[DeviceInfo] = []
-        try:
-            if torch.cuda.is_available():
-                for index in range(torch.cuda.device_count()):
-                    props = torch.cuda.get_device_properties(index)
-                    found.append(
-                        DeviceInfo(
-                            device_id=f"cuda:{index}",
-                            hardware_class=torch.cuda.get_device_name(index),
-                            total_vram_bytes=int(props.total_memory),
-                            total_slots=self.slots,
-                            free_slots=self.slots,
-                        )
-                    )
-                return found
-        except Exception:
-            pass
-        try:
-            if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
-                vram = 0
-                recommended = getattr(torch.mps, "recommended_max_memory", None)
-                if callable(recommended):
-                    try:
-                        vram = int(recommended())
-                    except Exception:
-                        vram = 0
-                if vram <= 0:
-                    vram = _system_memory_bytes()
-                return [
-                    DeviceInfo(
-                        device_id="mps:0",
-                        hardware_class="apple-silicon-mps",
-                        total_vram_bytes=vram,
-                        total_slots=self.slots,
-                        free_slots=self.slots,
-                    )
-                ]
-        except Exception:
-            pass
-        return []
-
-    def _cpu_device(self) -> DeviceInfo:
-        # A CPU-only node is a valid (slow) execution device. total_vram_bytes
-        # carries system memory so the Gateway's ">0" validity check reflects
-        # real capacity rather than a made-up constant.
-        import platform  # noqa: PLC0415
-
-        return DeviceInfo(
-            device_id="cpu:0",
-            hardware_class=platform.processor() or platform.machine() or "cpu",
-            total_vram_bytes=_system_memory_bytes(),
-            total_slots=self.slots,
-            free_slots=self.slots,
-        )
-
-    def models(self) -> list[ModelInfo]:
-        with self._model_lock:
-            now = time.monotonic()
-            if (
-                self._model_cache is not None
-                and now - self._model_cache_at < self.model_ttl_s
-            ):
-                return list(self._model_cache)
-            self._model_cache = self._scan_models()
-            self._model_cache_at = time.monotonic()
-            return list(self._model_cache)
-
-    def _scan_models(self) -> list[ModelInfo]:
-        ensure_backend_on_path()
-        from services.hf_cache_repair import repo_cache_dir  # noqa: PLC0415
-        from services.hf_revisions import installed_revision  # noqa: PLC0415
-        from services.tts_backend import get_backend_class  # noqa: PLC0415
-
-        models: list[ModelInfo] = []
-        for engine_id, repo_id in sorted(ENGINE_MODEL_REPOS.items()):
-            try:
-                backend_cls = get_backend_class(engine_id)
-            except Exception:
-                continue  # engine not registered in this build
-            repo_dir = repo_cache_dir(repo_id)
-            try:
-                revision = installed_revision(repo_id, os.path.dirname(repo_dir))
-            except ValueError:
-                continue  # repo not in the curated catalog — cannot attest
-            snapshot = os.path.join(repo_dir, "snapshots", revision)
-            if not os.path.isdir(snapshot):
-                continue  # weights not installed at the pinned revision
-            models.append(
-                self._model_state(engine_id, backend_cls, repo_dir, revision, snapshot)
-            )
-        return models
-
-    def _model_state(
-        self, engine_id: str, backend_cls, repo_dir: str, revision: str, snapshot: str
-    ) -> ModelInfo:
-        base = ModelInfo(
-            catalog_model_id=engine_id,
-            model_version=revision,
-            model_digest="",
-            precisions=self._precisions(backend_cls),
-            features=self._features(backend_cls),
-        )
-        try:
-            ok, _message = backend_cls.is_available()
-        except Exception:
-            return _replace_state(base, STATE_FAILED)
-        if not ok:
-            return _replace_state(base, STATE_INSTALLED)
-        if _snapshot_incomplete(repo_dir, snapshot):
-            return _replace_state(base, STATE_LOADING)
-        try:
-            model_digest = snapshot_digest(
-                snapshot,
-                cache_path=os.path.join(repo_dir, f"voicestudio-digest-{revision}.json"),
-            )
-        except OSError:
-            return _replace_state(base, STATE_LOADING)
-        return ModelInfo(
-            catalog_model_id=base.catalog_model_id,
-            model_version=catalog_model_version(base.model_version, model_digest),
-            model_digest=model_digest,
-            precisions=base.precisions,
-            features=base.features,
-            state=STATE_READY,
-        )
-
-    def _precisions(self, backend_cls) -> tuple[str, ...]:
-        # Advisory execution precisions. fp32 always works; fp16 is offered
-        # when the engine targets an accelerator this host actually has.
-        compat = tuple(getattr(backend_cls, "gpu_compat", ("cpu",)))
-        try:
-            from core.device_caps import detect_host_caps  # noqa: PLC0415
-
-            family = detect_host_caps().family
-        except Exception:
-            family = "cpu"
-        if family != "cpu" and family in compat:
-            return ("fp16", "fp32")
-        return ("fp32",)
-
-    def _features(self, backend_cls) -> tuple[str, ...]:
-        features = ["tts"]
-        if getattr(backend_cls, "supports_cloning", False) is True:
-            features.append("voice_clone")
-        if getattr(backend_cls, "supports_voice_design", False):
-            features.append("voice_design")
-        if getattr(backend_cls, "supports_emotion", False):
-            features.append("emotion")
-        return tuple(features)
-
-
-def _replace_state(model: ModelInfo, state: str) -> ModelInfo:
-    return ModelInfo(
-        catalog_model_id=model.catalog_model_id,
-        model_version=model.model_version,
-        model_digest=model.model_digest,
-        precisions=model.precisions,
-        features=model.features,
-        state=state,
-    )
-
-
-def _snapshot_incomplete(repo_dir: str, snapshot: str) -> bool:
-    """A download in flight leaves ``*.incomplete`` blobs or dangling links."""
-    blobs = os.path.join(repo_dir, "blobs")
-    try:
-        if any(name.endswith(".incomplete") for name in os.listdir(blobs)):
-            return True
-    except OSError:
-        pass
-    for current, _dirs, files in os.walk(snapshot):
-        for name in files:
-            path = os.path.join(current, name)
-            if not os.path.exists(path):  # dangling symlink
-                return True
-    return False
-
-
-def _system_memory_bytes() -> int:
-    try:
-        import psutil  # noqa: PLC0415
-
-        return int(psutil.virtual_memory().total)
-    except Exception:
-        try:
-            return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
-        except (ValueError, OSError, AttributeError):
-            return 1  # still nonzero: the preflight requires > 0

backend/runtime_adapter/production.py

@@ -1,63 +0,0 @@
-"""Wires the adapter to the real VoiceStudio backend.
-
-Kept separate from ``server.py`` so tests can build a
-:class:`~runtime_adapter.server.RuntimeContext` from fakes without importing
-torch or the engine registry.
-"""
-from __future__ import annotations
-
-import sys
-
-from . import ADAPTER_VERSION
-from ._paths import ensure_backend_on_path
-from .inventory import ProductionInventory, slots_per_device
-from .server import RuntimeContext
-
-
-def production_engine_provider(catalog_model_id: str):
-    """Resolve a READY catalog model id to its cached engine instance."""
-    ensure_backend_on_path()
-    from services.tts_backend import get_engine_instance_for  # noqa: PLC0415
-
-    return get_engine_instance_for(catalog_model_id)
-
-
-def build_runtime_context() -> RuntimeContext:
-    ensure_backend_on_path()
-    from core.version import APP_VERSION  # noqa: PLC0415
-
-    slots = slots_per_device()
-    return RuntimeContext(
-        runtime_version=APP_VERSION,
-        adapter_version=ADAPTER_VERSION,
-        inventory=ProductionInventory(slots=slots),
-        engine_provider=production_engine_provider,
-        slot_limit=slots,
-    )
-
-def prewarm_engines(context: RuntimeContext) -> None:
-    """Load and compile every READY model before the socket accepts work.
-
-    The GPU Gateway leases an attempt for a bounded window and renews it from
-    execution evidence. A cold engine produces no evidence: weight loading and
-    torch compilation can run for minutes emitting nothing, so the lease
-    expires mid-load, the attempt is fenced, the Job requeues, and the next
-    attempt pays the same cost — a loop that never yields audio.
-
-    Paying that cost once at startup, before the adapter is reachable, means
-    the first real Execute begins inference immediately. Preflight already
-    refuses a runtime with no READY model, so a failure here is reported and
-    the model is dropped from the advertised set rather than being offered as
-    schedulable capacity the node cannot actually serve promptly.
-    """
-    ensure_backend_on_path()
-    for model in context.inventory.models():
-        if model.state != "ready":
-            continue
-        try:
-            context.engine_provider(model.catalog_model_id)
-        except Exception as error:  # noqa: BLE001 - reported, never fatal
-            print(
-                f"runtime adapter: prewarm of {model.catalog_model_id} failed: {error}",
-                file=sys.stderr,
-            )

backend/runtime_adapter/runtime_adapter.proto

@@ -1,199 +0,0 @@
-syntax = "proto3";
-
-package voicestudio.runtime.v1;
-
-option go_package = "github.com/velixio/vssaas/api/gen/runtime/v1;runtimev1";
-
-// RuntimeAdapterService is local to a GPU Node and is never publicly exposed.
-service RuntimeAdapterService {
-  rpc Health(HealthRequest) returns (HealthResponse);
-  rpc GetCapabilities(GetCapabilitiesRequest) returns (GetCapabilitiesResponse);
-  rpc Execute(ExecuteRequest) returns (stream ExecuteResponse);
-  rpc Cancel(CancelRequest) returns (CancelResponse);
-}
-
-message ExecuteResponse { ExecutionEvent event = 1; }
-
-message HealthRequest {}
-
-message HealthResponse {
-  ServingState state = 1;
-  string runtime_version = 2;
-  string adapter_version = 3;
-  repeated string health_flags = 4;
-}
-
-enum ServingState {
-  SERVING_STATE_UNSPECIFIED = 0;
-  SERVING_STATE_READY = 1;
-  SERVING_STATE_DEGRADED = 2;
-  SERVING_STATE_UNHEALTHY = 3;
-}
-
-message GetCapabilitiesRequest {}
-
-message GetCapabilitiesResponse {
-  string runtime_version = 1;
-  string adapter_version = 2;
-  repeated RuntimeDevice devices = 3;
-  repeated RuntimeModel models = 4;
-}
-
-message RuntimeDevice {
-  string device_id = 1;
-  string hardware_class = 2;
-  uint64 total_vram_bytes = 3;
-  uint32 total_slots = 4;
-  uint32 free_slots = 5;
-}
-
-message RuntimeModel {
-  string catalog_model_id = 1;
-  string model_version = 2;
-  string model_digest = 3;
-  repeated string precisions = 4;
-  repeated string features = 5;
-  RuntimeModelState state = 6;
-}
-
-enum RuntimeModelState {
-  RUNTIME_MODEL_STATE_UNSPECIFIED = 0;
-  RUNTIME_MODEL_STATE_INSTALLED = 1;
-  RUNTIME_MODEL_STATE_LOADING = 2;
-  RUNTIME_MODEL_STATE_READY = 3;
-  RUNTIME_MODEL_STATE_FAILED = 4;
-}
-
-message ExecuteRequest {
-  string job_id = 1;
-  string attempt_id = 2;
-  string device_id = 3;
-  string slot_id = 4;
-  ModelSpec model = 5;
-  map<string, ParameterValue> parameters = 6;
-  repeated LocalArtifact inputs = 7;
-  repeated LocalArtifact outputs = 8;
-  int64 deadline_unix_ms = 9;
-  uint32 maximum_preview_bytes = 10;
-}
-
-message ModelSpec {
-  string catalog_model_id = 1;
-  string model_version = 2;
-  string model_digest = 3;
-  string precision = 4;
-}
-
-message ParameterValue {
-  oneof value {
-    string string_value = 1;
-    int64 integer_value = 2;
-    double number_value = 3;
-    bool boolean_value = 4;
-  }
-}
-
-message LocalArtifact {
-  string artifact_id = 1;
-  string local_handle = 2;
-  LocalArtifactOperation operation = 3;
-  uint64 expected_size_bytes = 4;
-  string expected_sha256 = 5;
-  string media_type = 6;
-}
-
-enum LocalArtifactOperation {
-  LOCAL_ARTIFACT_OPERATION_UNSPECIFIED = 0;
-  LOCAL_ARTIFACT_OPERATION_READ = 1;
-  LOCAL_ARTIFACT_OPERATION_WRITE = 2;
-}
-
-message ExecutionEvent {
-  string job_id = 1;
-  string attempt_id = 2;
-  uint64 sequence = 3;
-  int64 observed_at_unix_ms = 4;
-  oneof payload {
-    ExecutionStarted started = 10;
-    ExecutionProgress progress = 11;
-    PreviewChunk preview = 12;
-    ExecutionCompleted completed = 13;
-    ExecutionFailed failed = 14;
-    ExecutionCanceled canceled = 15;
-  }
-}
-
-message ExecutionStarted {}
-
-message ExecutionProgress {
-  uint32 progress_permille = 1;
-  string stage_code = 2;
-}
-
-message PreviewChunk {
-  uint64 sequence = 1;
-  string media_type = 2;
-  bytes data = 3;
-}
-
-message ExecutionCompleted {
-  repeated LocalArtifactManifest outputs = 1;
-  RuntimeMeasurements measurements = 2;
-}
-
-message LocalArtifactManifest {
-  string artifact_id = 1;
-  string local_handle = 2;
-  uint64 size_bytes = 3;
-  string sha256 = 4;
-  string media_type = 5;
-  uint64 duration_ms = 6;
-}
-
-message ExecutionFailed {
-  RuntimeFailureClass failure_class = 1;
-  string stable_code = 2;
-  string safe_detail = 3;
-  RuntimeMeasurements measurements = 4;
-}
-
-message ExecutionCanceled {
-  RuntimeMeasurements measurements = 1;
-}
-
-enum RuntimeFailureClass {
-  RUNTIME_FAILURE_CLASS_UNSPECIFIED = 0;
-  RUNTIME_FAILURE_CLASS_INPUT = 1;
-  RUNTIME_FAILURE_CLASS_MODEL_LOAD = 2;
-  RUNTIME_FAILURE_CLASS_INFERENCE = 3;
-  RUNTIME_FAILURE_CLASS_GPU_RESOURCE = 4;
-  RUNTIME_FAILURE_CLASS_LOCAL_STORAGE = 5;
-  RUNTIME_FAILURE_CLASS_RUNTIME = 6;
-  RUNTIME_FAILURE_CLASS_CANCELED = 7;
-}
-
-message RuntimeMeasurements {
-  uint64 normalized_input_characters = 1;
-  uint64 input_audio_ms = 2;
-  uint64 output_audio_ms = 3;
-  uint64 gpu_execution_ms = 4;
-  uint64 cpu_execution_ms = 5;
-}
-
-message CancelRequest {
-  string job_id = 1;
-  string attempt_id = 2;
-  string reason_code = 3;
-  int64 deadline_unix_ms = 4;
-}
-
-message CancelResponse {
-  CancelDisposition disposition = 1;
-}
-
-enum CancelDisposition {
-  CANCEL_DISPOSITION_UNSPECIFIED = 0;
-  CANCEL_DISPOSITION_ACCEPTED = 1;
-  CANCEL_DISPOSITION_ALREADY_TERMINAL = 2;
-  CANCEL_DISPOSITION_NOT_FOUND = 3;
-}

backend/runtime_adapter/selfcheck.py

@@ -1,168 +0,0 @@
-"""``--selfcheck``: validate the Go preflight's expectations against ourselves.
-
-Starts the server on a private temp socket, then runs a Python port of
-``internal/gateway/preflight.go``'s checks over the wire: socket-path safety,
-READY health with version evidence, identical versions across Health and
-GetCapabilities, valid unique devices, and at least one explicitly READY,
-digest-pinned model with a version and precisions. Prints only a bounded
-readiness summary (never handles, paths, or credentials) and exits nonzero on
-any failed expectation — the same fail-closed behavior a node deployment gets
-from ``cmd/runtime-adapter-preflight``.
-"""
-from __future__ import annotations
-
-import os
-import stat as stat_module
-import tempfile
-from dataclasses import dataclass
-
-import grpc
-
-from .gen import runtime_adapter_pb2 as pb2
-from .gen import runtime_adapter_pb2_grpc as pb2_grpc
-
-_MAX_UINT32 = 2**32 - 1
-
-
-class PreflightError(Exception):
-    """One failed preflight expectation, with a bounded message."""
-
-
-@dataclass(frozen=True)
-class PreflightSummary:
-    socket_path: str
-    runtime_version: str
-    adapter_version: str
-    device_count: int
-    ready_model_count: int
-    total_slots: int
-    free_slots: int
-
-    def render(self) -> str:
-        return (
-            f"runtime={self.runtime_version} adapter={self.adapter_version} "
-            f"devices={self.device_count} ready_models={self.ready_model_count} "
-            f"slots={self.free_slots}/{self.total_slots}"
-        )
-
-
-def validate_socket_file(socket_path: str) -> None:
-    if not socket_path or not os.path.isabs(socket_path):
-        raise PreflightError("socket path must be absolute")
-    info = os.lstat(socket_path)
-    if stat_module.S_ISLNK(info.st_mode) or not stat_module.S_ISSOCK(info.st_mode):
-        raise PreflightError("endpoint must be a local Unix socket")
-    parent = os.stat(os.path.dirname(socket_path))
-    if not stat_module.S_ISDIR(parent.st_mode) or parent.st_mode & 0o002:
-        raise PreflightError("socket directory is unsafe")
-
-
-def run_preflight(socket_path: str, timeout_s: float = 10.0) -> PreflightSummary:
-    """Port of ``PreflightRuntime`` + ``validateRuntimeCapabilities``."""
-    validate_socket_file(socket_path)
-    with grpc.insecure_channel(f"unix:{socket_path}") as channel:
-        stub = pb2_grpc.RuntimeAdapterServiceStub(channel)
-        try:
-            health = stub.Health(pb2.HealthRequest(), timeout=timeout_s)
-        except grpc.RpcError as exc:
-            raise PreflightError(f"health call failed: {exc.code().name}")
-        if (
-            health.state != pb2.SERVING_STATE_READY
-            or not health.runtime_version.strip()
-            or not health.adapter_version.strip()
-        ):
-            raise PreflightError("runtime is not ready with versioned adapter evidence")
-        try:
-            caps = stub.GetCapabilities(pb2.GetCapabilitiesRequest(), timeout=timeout_s)
-        except grpc.RpcError as exc:
-            raise PreflightError(f"capabilities call failed: {exc.code().name}")
-    return _validate_capabilities(socket_path, health, caps)
-
-
-def _validate_capabilities(socket_path, health, caps) -> PreflightSummary:
-    if not caps.runtime_version.strip() or not caps.adapter_version.strip():
-        raise PreflightError("capabilities lack version evidence")
-    if (
-        caps.runtime_version != health.runtime_version
-        or caps.adapter_version != health.adapter_version
-    ):
-        raise PreflightError("health and capabilities versions disagree")
-    if not caps.devices:
-        raise PreflightError("no execution devices reported")
-    total_slots = free_slots = 0
-    seen_devices: set[str] = set()
-    for device in caps.devices:
-        if (
-            not device.device_id.strip()
-            or not device.hardware_class.strip()
-            or device.total_vram_bytes == 0
-            or device.total_slots == 0
-            or device.free_slots > device.total_slots
-        ):
-            raise PreflightError("invalid execution device reported")
-        if device.device_id in seen_devices:
-            raise PreflightError("duplicate execution device reported")
-        seen_devices.add(device.device_id)
-        if (
-            total_slots + device.total_slots > _MAX_UINT32
-            or free_slots + device.free_slots > _MAX_UINT32
-        ):
-            raise PreflightError("slot total overflows protocol limit")
-        total_slots += device.total_slots
-        free_slots += device.free_slots
-    ready = 0
-    seen_models: set[tuple[str, str, str]] = set()
-    for model in caps.models:
-        if model.state != pb2.RUNTIME_MODEL_STATE_READY:
-            continue
-        if (
-            not model.catalog_model_id.strip()
-            or not model.model_version.strip()
-            or not model.model_digest.strip()
-            or not model.precisions
-        ):
-            raise PreflightError("invalid ready model reported")
-        identity = (model.catalog_model_id, model.model_version, model.model_digest)
-        if identity in seen_models:
-            raise PreflightError("duplicate ready model reported")
-        seen_models.add(identity)
-        ready += 1
-    if ready == 0:
-        raise PreflightError("no ready model reported")
-    return PreflightSummary(
-        socket_path=socket_path,
-        runtime_version=health.runtime_version,
-        adapter_version=health.adapter_version,
-        device_count=len(caps.devices),
-        ready_model_count=ready,
-        total_slots=total_slots,
-        free_slots=free_slots,
-    )
-
-
-def selfcheck(timeout_s: float = 10.0) -> int:
-    """Start the production server on a temp socket and preflight it."""
-    from .production import build_runtime_context  # noqa: PLC0415
-    from .server import create_server  # noqa: PLC0415
-
-    context = build_runtime_context()
-    warm = getattr(context.inventory, "warm", None)
-    if callable(warm):
-        print("selfcheck: warming model inventory (first run hashes weights)…")
-        warm()
-    # Short prefix: macOS caps Unix-socket paths at 103 characters and the
-    # default macOS tempdir is already ~60 characters deep.
-    with tempfile.TemporaryDirectory(prefix="vs-rta-") as tmp:
-        os.chmod(tmp, 0o700)
-        socket_path = os.path.join(tmp, "runtime.sock")
-        server = create_server(context, socket_path)
-        server.start()
-        try:
-            summary = run_preflight(socket_path, timeout_s=timeout_s)
-        except PreflightError as failure:
-            print(f"selfcheck: FAIL: {failure}")
-            return 1
-        finally:
-            server.stop(grace=2).wait()
-    print(f"selfcheck: OK: {summary.render()}")
-    return 0

backend/runtime_adapter/server.py

@@ -1,208 +0,0 @@
-"""The gRPC server: Unix-domain socket only, no HTTP, no TCP.
-
-``Health`` and ``GetCapabilities`` read the same version constants from one
-:class:`RuntimeContext`, so the "identical versions" preflight expectation
-holds by construction. Socket-path safety mirrors the Go preflight's checks
-(absolute path, no symlink, parent directory not world-writable) at bind time
-so an unsafe deployment fails closed on our side too.
-"""
-from __future__ import annotations
-
-import os
-import stat as stat_module
-import threading
-from concurrent import futures
-from dataclasses import dataclass, field
-
-import grpc
-
-from . import ADAPTER_VERSION, DEFAULT_SOCKET_PATH, SOCKET_ENV
-from .executor import AttemptRegistry, Executor
-from .gen import runtime_adapter_pb2 as pb2
-from .gen import runtime_adapter_pb2_grpc as pb2_grpc
-from .inventory import (
-    STATE_FAILED,
-    STATE_INSTALLED,
-    STATE_LOADING,
-    STATE_READY,
-)
-
-_MODEL_STATE_TO_PB = {
-    STATE_INSTALLED: pb2.RUNTIME_MODEL_STATE_INSTALLED,
-    STATE_LOADING: pb2.RUNTIME_MODEL_STATE_LOADING,
-    STATE_READY: pb2.RUNTIME_MODEL_STATE_READY,
-    STATE_FAILED: pb2.RUNTIME_MODEL_STATE_FAILED,
-}
-
-
-@dataclass
-class RuntimeContext:
-    """Everything the servicer needs; tests build it from fakes."""
-
-    runtime_version: str
-    inventory: object
-    engine_provider: object
-    adapter_version: str = ADAPTER_VERSION
-    slot_limit: int = 1
-    progress_interval: float = 0.5
-    poll_interval: float = 0.02
-    registry: AttemptRegistry = field(default_factory=AttemptRegistry)
-
-    def executor(self) -> Executor:
-        return Executor(
-            self.inventory,
-            self.engine_provider,
-            self.registry,
-            slot_limit=self.slot_limit,
-            progress_interval=self.progress_interval,
-            poll_interval=self.poll_interval,
-        )
-
-
-class RuntimeAdapterServicer(pb2_grpc.RuntimeAdapterServiceServicer):
-    def __init__(self, context: RuntimeContext):
-        self._context = context
-        self._executor = context.executor()
-
-    def Health(self, request, grpc_context):
-        flags: list[str] = []
-        state = pb2.SERVING_STATE_READY
-        try:
-            devices = self._context.inventory.devices(
-                busy_slots=self._context.registry.active_count()
-            )
-            models = self._context.inventory.models()
-        except Exception:
-            return pb2.HealthResponse(
-                state=pb2.SERVING_STATE_UNHEALTHY,
-                runtime_version=self._context.runtime_version,
-                adapter_version=self._context.adapter_version,
-                health_flags=["inventory-error"],
-            )
-        if not devices:
-            state = pb2.SERVING_STATE_UNHEALTHY
-            flags.append("no-device")
-        if not any(model.state == STATE_READY for model in models):
-            state = max(state, pb2.SERVING_STATE_DEGRADED)
-            flags.append("no-ready-model")
-        return pb2.HealthResponse(
-            state=state,
-            runtime_version=self._context.runtime_version,
-            adapter_version=self._context.adapter_version,
-            health_flags=flags,
-        )
-
-    def GetCapabilities(self, request, grpc_context):
-        busy = self._context.registry.active_count()
-        response = pb2.GetCapabilitiesResponse(
-            runtime_version=self._context.runtime_version,
-            adapter_version=self._context.adapter_version,
-        )
-        for device in self._context.inventory.devices(busy_slots=busy):
-            response.devices.append(
-                pb2.RuntimeDevice(
-                    device_id=device.device_id,
-                    hardware_class=device.hardware_class,
-                    total_vram_bytes=device.total_vram_bytes,
-                    total_slots=device.total_slots,
-                    free_slots=device.free_slots,
-                )
-            )
-        for model in self._context.inventory.models():
-            response.models.append(
-                pb2.RuntimeModel(
-                    catalog_model_id=model.catalog_model_id,
-                    model_version=model.model_version,
-                    model_digest=model.model_digest,
-                    precisions=list(model.precisions),
-                    features=list(model.features),
-                    state=_MODEL_STATE_TO_PB.get(
-                        model.state, pb2.RUNTIME_MODEL_STATE_UNSPECIFIED
-                    ),
-                )
-            )
-        return response
-
-    def Execute(self, request, grpc_context):
-        yield from self._executor.execute(request, grpc_context)
-
-    def Cancel(self, request, grpc_context):
-        disposition = self._context.registry.cancel(request.job_id, request.attempt_id)
-        return pb2.CancelResponse(disposition=disposition)
-
-
-def resolve_socket_path(explicit: str | None = None) -> str:
-    return (
-        (explicit or "").strip()
-        or os.environ.get(SOCKET_ENV, "").strip()
-        or DEFAULT_SOCKET_PATH
-    )
-
-
-def prepare_socket(socket_path: str) -> str:
-    """Fail closed on any unsafe socket placement; remove only a stale socket."""
-    if not socket_path or not os.path.isabs(socket_path):
-        raise ValueError("runtime socket path must be absolute")
-    parent = os.path.dirname(socket_path)
-    try:
-        parent_stat = os.stat(parent)
-    except OSError as exc:
-        raise ValueError(f"runtime socket directory is missing: {exc}") from exc
-    if not stat_module.S_ISDIR(parent_stat.st_mode) or parent_stat.st_mode & 0o002:
-        raise ValueError("runtime socket directory is unsafe (world-writable?)")
-    try:
-        existing = os.lstat(socket_path)
-    except FileNotFoundError:
-        return socket_path
-    if stat_module.S_ISSOCK(existing.st_mode):
-        os.unlink(socket_path)  # stale socket from a previous run
-        return socket_path
-    raise ValueError("runtime socket path exists and is not a socket")
-
-
-def create_server(
-    context: RuntimeContext, socket_path: str, *, max_workers: int | None = None
-) -> grpc.Server:
-    prepare_socket(socket_path)
-    workers = max_workers or max(8, context.slot_limit * 2 + 4)
-    server = grpc.server(
-        futures.ThreadPoolExecutor(
-            max_workers=workers, thread_name_prefix="runtime-adapter"
-        )
-    )
-    pb2_grpc.add_RuntimeAdapterServiceServicer_to_server(
-        RuntimeAdapterServicer(context), server
-    )
-    bound = server.add_insecure_port(f"unix:{socket_path}")
-    if bound == 0:
-        raise RuntimeError("failed to bind the runtime adapter socket")
-    return server
-
-
-def serve(context: RuntimeContext, socket_path: str) -> int:
-    """Run until SIGINT/SIGTERM. Returns a process exit code."""
-    import signal  # noqa: PLC0415
-
-    warm = getattr(context.inventory, "warm", None)
-    if callable(warm):
-        warm()  # hash installed snapshots before the socket exists
-    server = create_server(context, socket_path)
-    server.start()
-    try:
-        os.chmod(socket_path, 0o660)  # gateway runs under the same service identity
-    except OSError:
-        pass
-    stop = threading.Event()
-
-    def _stop(_signum, _frame):
-        stop.set()
-
-    signal.signal(signal.SIGTERM, _stop)
-    signal.signal(signal.SIGINT, _stop)
-    stop.wait()
-    server.stop(grace=10).wait()
-    try:
-        os.unlink(socket_path)
-    except OSError:
-        pass
-    return 0

backend/schemas/requests.py

@@ -190,6 +190,7 @@ class ParseSubtitleTextRequest(BaseModel):
 class DubIngestUrlRequest(BaseModel):
     url: str
     job_id: Optional[str] = None
+    source_lang: Optional[str] = None
     # When true and the URL is a caption-bearing host (YouTube, Vimeo, TED…),
     # ask yt-dlp to also download the original-language + any additional
     # sub_langs as VTT. The UI uses this to seed a transcript without running

backend/services/admin_sessions.py

@@ -33,7 +33,12 @@ WS_TICKET_PREFIX = "ovs_ws_ticket_"
 _TOKEN_BYTES = 32
 _ENCODED_TOKEN_LENGTH = 43
 _TOKEN_BODY_RE = re.compile(rf"^[A-Za-z0-9_-]{{{_ENCODED_TOKEN_LENGTH}}}$")
-_ALLOWED_WS_PATHS = frozenset({"/ws/events", "/ws/transcribe"})
+# Every ticketed WebSocket route. The first-party mirror is ``ALLOWED_WS_PATHS``
+# in frontend/src/api/authSession.ts — a route missing here mints a 422 and the
+# UI consumer fails silently (#1769 added /ws/tts for the live dub preview).
+_ALLOWED_WS_PATHS = frozenset(
+    {"/ws/events", "/ws/transcribe", "/ws/tts", "/v1/audio/transcriptions/stream"}
+)
 _ADMIN_CAPABILITIES = frozenset({"consume", "admin"})
 _KEY_GENERATION_INFO = b"omnivoice-admin-key-generation-v1"
 

backend/services/asr_backend.py

@@ -24,12 +24,15 @@ faster-whisper because it's available on every platform we ship to).
 from __future__ import annotations
 
 import asyncio
+import ipaddress
 import logging
 import os
 import re
 import contextlib
 import threading
 import time
+import weakref
+from urllib.parse import urlsplit
 from utils.containment import contain_system_exit
 
 from abc import ABC, abstractmethod
@@ -88,10 +91,9 @@ def reset_pool_after_wedge(executor, *, what: str = "ASR") -> bool:
 
 
 # ── Consecutive-timeout streak → recommend the crash-isolated engine ────────
-# A pool reset restores *capacity*, but the wedged CTranslate2/whisperx thread
-# keeps its VRAM until the process exits. When guarded transcribes keep timing
-# out back-to-back in one session, resets clearly aren't recovering the
-# underlying hang — the durable fix is the crash-isolated sidecar engine
+# A timed-out CTranslate2/whisperx thread keeps its worker and VRAM until the
+# native call exits. When guarded transcribes keep timing out back-to-back in
+# one session, the durable fix is the crash-isolated sidecar engine
 # (services.subprocess_asr, #393), whose child process CAN be hard-killed to
 # reclaim the hung call and its VRAM. We only *recommend* it (log + error
 # message); we never switch engines automatically (owner rule: no silent
@@ -146,41 +148,89 @@ def _isolated_engine_hint(streak: int) -> str:
 
 async def run_transcribe_guarded(executor, fn, *, what: str = "ASR",
                                  timeout: float = ASR_TRANSCRIBE_TIMEOUT_S,
-                                 timeout_env: str = "OMNIVOICE_ASR_TRANSCRIBE_TIMEOUT_S"):
+                                 timeout_env: str = "OMNIVOICE_ASR_TRANSCRIBE_TIMEOUT_S",
+                                 reset_on_timeout: bool = False,
+                                 on_abandon=None):
     """Run a blocking transcribe ``fn`` in ``executor`` with a hard wall-clock
     bound. On timeout, raise :class:`ASRTimeoutError` with guidance instead of
     letting the request hang forever.
 
-    ``run_in_executor`` cannot cancel the underlying thread, so a wedged
-    transcribe (a CTranslate2 / whisperx / VAD hang seen on some Windows + CUDA
-    setups, #730) keeps occupying its GPU-pool worker. With a 1–2 worker pool
-    that starves every *other* request — including TTS generate — and the next
-    thing the user does surfaces as "Can't reach the local backend" even though
-    the process is alive. So on timeout we also ``reset()`` the pool when it
-    supports it (``_ResilientGpuPool``): the wedged thread is abandoned and the
-    next submit gets a fresh worker, restoring capacity without an app restart.
-    The orphaned thread still holds its VRAM until the process exits, which is
-    why the message still recommends a smaller ASR model / Flush as the durable
-    fix. Executors without ``reset`` (a plain ThreadPoolExecutor in tests) just
-    get the bound + actionable error.
+    A future cannot cancel the underlying thread, so a timed-out
+    in-process CTranslate2/whisperx call still owns its model and device. The
+    default deliberately leaves that worker accounted for: swapping in a fresh
+    pool and immediately retrying the same backend overlaps two native calls,
+    which produced the Windows access violation in #1669. A caller backed by a
+    genuinely killable process may opt into ``reset_on_timeout``.
+
+    ``on_abandon`` is called once after a timed-out or cancelled worker can no
+    longer access its inputs. Queued work cancelled before it starts calls it
+    immediately; running work calls it from the worker finalizer. Normal
+    completion leaves cleanup with the caller.
     """
     loop = asyncio.get_running_loop()
     # Same SystemExit containment as the TTS pool (#1133 class): an ASR
     # dependency written as a CLI must not be able to shut the backend down.
-    fut = loop.run_in_executor(executor, contain_system_exit(fn, what))
+    inner = contain_system_exit(fn, what)
+    abandon_lock = threading.Lock()
+    abandon_state = {
+        "requested": False,
+        "finished": False,
+        "callback_called": False,
+    }
+
+    def _fire_abandon_callback() -> None:
+        if on_abandon is None:
+            return
+        with abandon_lock:
+            if abandon_state["callback_called"]:
+                return
+            abandon_state["callback_called"] = True
+        try:
+            on_abandon()
+        except Exception:  # noqa: BLE001 — cleanup cannot hide the ASR result
+            logger.exception("%s abandon cleanup failed", what)
+
+    def _job():
+        try:
+            return inner()
+        finally:
+            with abandon_lock:
+                abandon_state["finished"] = True
+                abandoned = abandon_state["requested"]
+            if abandoned:
+                _fire_abandon_callback()
+
+    concurrent_fut = executor.submit(_job)
+    fut = asyncio.wrap_future(concurrent_fut, loop=loop)
+
+    def _abandon() -> None:
+        cancelled_before_start = concurrent_fut.cancel()
+        with abandon_lock:
+            abandon_state["requested"] = True
+            finished = abandon_state["finished"]
+        fut.cancel()
+        if cancelled_before_start or finished:
+            _fire_abandon_callback()
+
     try:
-        result = await asyncio.wait_for(fut, timeout=timeout)
+        # Shield the wrapper so timeout does not discard our ability to tell a
+        # queued cancellation from a native thread that is still running.
+        result = await asyncio.wait_for(asyncio.shield(fut), timeout=timeout)
+    except asyncio.CancelledError:
+        _abandon()
+        raise
     except asyncio.TimeoutError:
-        # Free the poisoned pool so a hung transcribe can't keep starving TTS /
-        # other ASR work (the "can't reach backend" symptom, #730).
-        reset_pool_after_wedge(executor, what=what)
+        _abandon()
+        if reset_on_timeout:
+            reset_pool_after_wedge(executor, what=what)
         streak = _note_transcribe_timeout()
         msg = (
             f"{what} transcription exceeded {timeout:.0f}s and was abandoned — "
             "the backend is running, but the ASR model is too heavy for the "
             "available compute. Most often the GPU is VRAM-starved: the resident "
             "TTS model and a large ASR model (large-v3) contend for memory. "
-            "Capacity was restored automatically, but for a durable fix Flush the "
+            "The native call cannot be killed safely, so its capacity remains "
+            "reserved until it exits. For a durable fix Flush the "
             "TTS model to free VRAM, pick a smaller ASR model in "
             f"Model Catalogue → Models, or set ASR to CPU. (Raise {timeout_env} "
             "for very long transcribes.)"
@@ -310,6 +360,16 @@ class ASRBackend(ABC):
     # broken GPU path, strictly worse than the honest `cpu_fallback`.)
     gpu_compat: tuple[str, ...] = ("cpu",)
 
+    def execution_evidence_loaded(self) -> bool:
+        """Whether this instance has live model state worth reporting."""
+        if getattr(self, "runs_out_of_process", False):
+            proc = getattr(self, "_proc", None)
+            return proc is not None and proc.poll() is None
+        return any(
+            getattr(self, attr, None) is not None
+            for attr in ("_model", "_asr", "_pipeline", "_pipe", "_transcriber", "_rec")
+        )
+
     @classmethod
     @abstractmethod
     def is_available(cls) -> tuple[bool, str]:
@@ -956,6 +1016,8 @@ class FasterWhisperBackend(ASRBackend):
         # (after the #551 compute_type / #255 OOM→CPU fallback chain).
         self._device: str | None = None
         self._compute_type: str | None = None
+        self._fallback_reason: str | None = None
+        self._fallback_stage: str | None = None
 
     @classmethod
     def is_available(cls) -> tuple[bool, str]:
@@ -1033,6 +1095,8 @@ class FasterWhisperBackend(ASRBackend):
                 except Exception:  # noqa: BLE001 — cache clear is best-effort
                     pass
                 device = "cpu"
+                self._fallback_reason = "CUDA memory was exhausted while loading the engine"
+                self._fallback_stage = "model_load"
                 candidates = _compute_type_candidates(device)
                 compute_type = candidates[0]
                 continue
@@ -1737,9 +1801,7 @@ class SherpaDictationBackend(ASRBackend):
 
     def __init__(self, model_id: str | None = None):
         from services import sherpa_dictation as _sd
-        mid = model_id or os.environ.get(
-            "OMNIVOICE_SHERPA_ASR_MODEL", _sd.DEFAULT_MODEL_ID
-        )
+        mid = model_id or sherpa_engine_model_id()
         spec = _sd.get_spec(mid)
         if spec is None:
             raise ValueError(
@@ -1991,6 +2053,42 @@ _ASR_OPENAI_COMPAT_MODEL_KEY = "asr.openai_compat.model"
 _ASR_OPENAI_COMPAT_SECRET_NAME = "asr_openai_compat_key"
 
 
+def normalize_openai_compat_asr_base_url(value: str) -> str:
+    """Normalize a safe ASR endpoint, allowing plain HTTP only on loopback."""
+    base = (value or "").strip().rstrip("/")
+    if not base:
+        return ""
+    try:
+        parsed = urlsplit(base)
+        _ = parsed.port
+    except (TypeError, ValueError) as exc:
+        raise ValueError("Invalid OpenAI-compatible ASR base URL") from exc
+    scheme = parsed.scheme.lower()
+    if (
+        scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            "OpenAI-compatible ASR base URL must be a credential-free HTTP(S) URL"
+        )
+    host = parsed.hostname.lower()
+    loopback = host == "localhost"
+    if not loopback:
+        try:
+            address = ipaddress.ip_address(host)
+            address = getattr(address, "ipv4_mapped", None) or address
+            loopback = address.is_loopback
+        except ValueError:
+            loopback = False
+    if scheme == "http" and not loopback:
+        raise ValueError("Non-loopback OpenAI-compatible ASR endpoints require HTTPS")
+    return base
+
+
 def resolve_openai_compat_asr_base_url() -> str:
     from services import settings_store
     return (
@@ -2054,7 +2152,7 @@ def probe_openai_compat_server(
     maps to a translated message:
 
       not_configured   no base URL anywhere
-      invalid_url      base URL without an http(s):// scheme
+      invalid_url      malformed URL or non-loopback HTTP endpoint
       ok               2xx — ``model_found`` says whether the configured
                        model appears in the server's list (None = unknown)
       ok_no_models     404/405/501 — reachable, but no /models endpoint
@@ -2069,7 +2167,7 @@ def probe_openai_compat_server(
 
     from core.scrub import scrub_text
 
-    base = (base_url if base_url is not None else resolve_openai_compat_asr_base_url()).strip().rstrip("/")
+    configured_base = base_url if base_url is not None else resolve_openai_compat_asr_base_url()
     mdl = (model if model is not None else resolve_openai_compat_asr_model()).strip()
     if api_key is None:
         key = resolve_openai_compat_asr_api_key()
@@ -2085,9 +2183,11 @@ def probe_openai_compat_server(
         "model_found": None,
         "detail": None,
     }
-    if not base:
+    if not configured_base.strip():
         return out
-    if not base.startswith(("http://", "https://")):
+    try:
+        base = normalize_openai_compat_asr_base_url(configured_base)
+    except ValueError:
         out["status"] = "invalid_url"
         return out
 
@@ -2098,7 +2198,7 @@ def probe_openai_compat_server(
     try:
         with httpx.Client(
             timeout=httpx.Timeout(timeout_s, connect=min(5.0, timeout_s)),
-            follow_redirects=True,
+            follow_redirects=False,
         ) as client:
             resp = client.get(f"{base}/models", headers=headers)
     except httpx.TimeoutException as exc:
@@ -2161,13 +2261,20 @@ class OpenAICompatASRBackend(ASRBackend):
     gpu_compat = ("cpu",)  # network client only — no local compute
 
     def __init__(self):
-        self._base_url = resolve_openai_compat_asr_base_url()
+        self._base_url = normalize_openai_compat_asr_base_url(
+            resolve_openai_compat_asr_base_url()
+        )
         self._model = resolve_openai_compat_asr_model()
 
     @classmethod
     def is_available(cls) -> tuple[bool, str]:
-        if not resolve_openai_compat_asr_base_url():
+        base_url = resolve_openai_compat_asr_base_url()
+        if not base_url:
             return False, "Configure a server endpoint in Model Catalogue → Engines"
+        try:
+            normalize_openai_compat_asr_base_url(base_url)
+        except ValueError as exc:
+            return False, str(exc)
         try:
             import openai  # noqa: F401
         except ImportError:
@@ -2175,13 +2282,18 @@ class OpenAICompatASRBackend(ASRBackend):
         return True, "ready"
 
     def _client(self):
-        from openai import OpenAI
+        from openai import DefaultHttpxClient, OpenAI
         api_key = resolve_openai_compat_asr_api_key() or "not-needed"
         # max_retries=0: mirrors llm_skills.resolve_skill_client — a
         # rate-limited/slow server retrying inside the SDK would blow past
         # whatever bounded timeout the caller (dub transcribe, dictation)
         # expects from a single call.
-        return OpenAI(base_url=self._base_url, api_key=api_key, max_retries=0)
+        return OpenAI(
+            base_url=self._base_url,
+            api_key=api_key,
+            max_retries=0,
+            http_client=DefaultHttpxClient(follow_redirects=False),
+        )
 
     def transcribe(self, audio_path: str, *, word_timestamps: bool = True) -> dict:
         logger.info(
@@ -2360,6 +2472,8 @@ _LAST_ERRORS: dict[str, str] = {}
 # failing ASR wholesale. Per-process by design: repairing the env requires a
 # reinstall / ``uv sync --reinstall`` and an app restart anyway.
 _DEEP_IMPORT_BROKEN: dict[str, str] = {}
+_RUNTIME_EVIDENCE: dict[str, dict] = {}
+_RUNTIME_INSTANCES: weakref.WeakValueDictionary[str, "ASRBackend"] = weakref.WeakValueDictionary()
 
 
 def _deep_import_reason(cls: type["ASRBackend"], exc: ImportError) -> str:
@@ -2390,6 +2504,7 @@ def list_backends() -> list[dict]:
     """
     from core.device_caps import detect_host_caps
     from core.scrub import scrub_text
+    from services.engine_evidence import snapshot as execution_snapshot
     from services.engine_routing import routing_fields
     caps = detect_host_caps()
 
@@ -2414,6 +2529,24 @@ def list_backends() -> list[dict]:
             _LAST_ERRORS[bid] = scrub_text(msg)
         isolation = "subprocess" if getattr(cls, "_is_subprocess_isolated", False) else "in-process"
         gpu_compat = getattr(cls, "gpu_compat", ("cpu",))
+        routing = routing_fields(gpu_compat, caps)
+        # Cached load-time facts are valid only while their exact backend still
+        # owns live model state. Recompute from that instance so unload/reaping
+        # cannot leave ghost GPU/provider evidence in diagnostics.
+        instance = (
+            _ISOLATED_INSTANCES.get(bid)
+            if isolation == "subprocess"
+            else _RUNTIME_INSTANCES.get(bid)
+        )
+        execution_evidence = execution_snapshot(
+            engine_id=bid,
+            engine_cls=cls,
+            instance=instance,
+            routing=routing,
+            caps=caps,
+        )
+        if execution_evidence["evidence_state"] == "not_loaded":
+            _RUNTIME_EVIDENCE.pop(bid, None)
         out.append({
             "id": bid,
             "display_name": cls.display_name,
@@ -2425,7 +2558,14 @@ def list_backends() -> list[dict]:
             "last_error": _LAST_ERRORS.get(bid),
             "isolation_mode": isolation,
             "gpu_compat": list(gpu_compat),
-            **routing_fields(gpu_compat, caps),
+            **routing,
+            "execution_evidence": execution_evidence or execution_snapshot(
+                engine_id=bid,
+                engine_cls=cls,
+                instance=None,
+                routing=routing,
+                caps=caps,
+            ),
         })
     return out
 
@@ -2564,7 +2704,10 @@ def _auto_detect() -> str:
 def active_backend_id() -> str:
     explicit = os.environ.get("OMNIVOICE_ASR_BACKEND")
     if explicit:
-        return explicit
+        # #1582's public spelling predates the registry name. Keep it as a
+        # compatibility alias for the PyTorch-native Whisper implementation
+        # that can use ROCm/HIP; every ASR consumer resolves through here.
+        return "pytorch-whisper" if explicit == "omnivoice" else explicit
     from core import prefs
     picked = prefs.get("asr_backend")
     if picked:
@@ -2663,6 +2806,21 @@ def load_active_asr_backend(*, asr_pipe=None) -> ASRBackend:
                 raise ASRModelMissingError(missing)
         try:
             backend.ensure_loaded()
+            from core.device_caps import detect_host_caps
+            from services.engine_evidence import snapshot as execution_snapshot
+            from services.engine_routing import routing_fields
+
+            cls = type(backend)
+            caps = detect_host_caps()
+            routing = routing_fields(getattr(cls, "gpu_compat", ("cpu",)), caps)
+            _RUNTIME_EVIDENCE[bid] = execution_snapshot(
+                engine_id=bid,
+                engine_cls=cls,
+                instance=backend,
+                routing=routing,
+                caps=caps,
+            )
+            _RUNTIME_INSTANCES[bid] = backend
             return backend
         except ImportError as e:
             # ModuleNotFoundError and its ImportError parent ("cannot import
@@ -2887,6 +3045,31 @@ def get_sherpa_dictation_backend(model_id: str) -> "SherpaDictationBackend":
         return backend
 
 
+def sherpa_engine_model_id() -> str:
+    """The sherpa model the ``sherpa-onnx-asr`` engine loads when nothing pins
+    one explicitly: env var (power-user pin) → the dictation model the user
+    picked in Settings / the Engines menu → the catalogue default.
+
+    Unlike :func:`dictation_model_id` this ignores ``dictation.enabled`` — a
+    user who turned the hotkey off but chose the Sherpa engine for dub/batch
+    transcription still means *this* model — and never returns None: the
+    engine needs *some* model to construct. A demoted model (decoded nothing
+    on this host) falls through to the default rather than being re-picked.
+    """
+    from services import sherpa_dictation as _sd
+    explicit = os.environ.get("OMNIVOICE_SHERPA_ASR_MODEL")
+    if explicit:
+        return explicit
+    try:
+        from core import prefs
+        mid = prefs.get("dictation.model_id")
+    except Exception:  # noqa: BLE001 — prefs store unavailable → default
+        return _sd.DEFAULT_MODEL_ID
+    if _sd.is_sherpa_model(mid) and not _sd.is_demoted(mid):
+        return _sd.get_spec(mid).id
+    return _sd.DEFAULT_MODEL_ID
+
+
 def dictation_model_id() -> str | None:
     """The selected sherpa dictation model id, or None when dictation is off /
     no sherpa model is chosen. Env var wins (power-user pin), then prefs."""
@@ -2992,7 +3175,7 @@ def _capture_prefers_parakeet() -> bool:
     return _parakeet_mlx_installed()
 
 
-def get_capture_asr_backend() -> ASRBackend:
+def get_capture_asr_backend(*, skip_sherpa: bool = False) -> ASRBackend:
     """Pick the fastest ASR engine for capture / dictation.
 
     Selection order:
@@ -3017,6 +3200,9 @@ def get_capture_asr_backend() -> ASRBackend:
 
     Returns a cached singleton so the model stays warm between calls; the
     singleton is rebuilt if the selected sherpa model changes.
+
+    ``skip_sherpa`` is used only to validate a token-silent Sherpa result with
+    the installed capture fallback before persisting model demotion.
     """
     global _capture_backend, _capture_backend_key
 
@@ -3025,7 +3211,7 @@ def get_capture_asr_backend() -> ASRBackend:
     # call get_sherpa_dictation_backend concurrently) can't both build a model.
     with _capture_backend_lock:
         # 0. Honor an explicit sherpa dictation model selection.
-        sherpa_id = dictation_model_id()
+        sherpa_id = None if skip_sherpa else dictation_model_id()
         if sherpa_id:
             ok, _ = SherpaDictationBackend.is_available()
             if ok:
@@ -3158,9 +3344,7 @@ def _offline_asr_repo(backend_id: str | None = None) -> str | None:
         # Unknown/none → fail open.
         try:
             from services import sherpa_dictation as _sd
-            spec = _sd.get_spec(
-                os.environ.get("OMNIVOICE_SHERPA_ASR_MODEL", _sd.DEFAULT_MODEL_ID)
-            )
+            spec = _sd.get_spec(sherpa_engine_model_id())
             return spec.repo_id if spec is not None else None
         except Exception:  # noqa: BLE001 — preflight must stay best-effort
             return None
@@ -3192,7 +3376,10 @@ def _capture_whisper_repo() -> str | None:
     return os.environ.get("OMNIVOICE_PYTORCH_ASR_MODEL", _PYTORCH_ASR_DEFAULT)
 
 
-def _recommended_asr_model(purpose: str, missing_repo: str | None) -> dict | None:
+def _recommended_asr_model(
+    purpose: str, missing_repo: str | None, *, prefer_sherpa: bool = True,
+    excluded_sherpa_model_id: str | None = None,
+) -> dict | None:
     """The catalog entry to offer in the download CTA.
 
     Offline: the missing repo itself when it's in the catalog (guarantees
@@ -3212,20 +3399,38 @@ def _recommended_asr_model(purpose: str, missing_repo: str | None) -> dict | Non
 
     by_id = {m["repo_id"]: m for m in KNOWN_MODELS}
     exact = by_id.get(missing_repo) if missing_repo else None
-    want_sherpa = False
-    if purpose == "dictation":
-        if exact is not None and exact.get("engine") == "sherpa-onnx":
+
+    def _eligible(m: dict, *, sherpa: bool) -> bool:
+        if (m.get("engine") == "sherpa-onnx") != sherpa:
+            return False
+        if sherpa and m.get("dictation_id") == excluded_sherpa_model_id:
+            return False
+        return _model_supported(m)
+
+    if purpose != "dictation":
+        if exact is not None and _model_supported(exact):
             return _shape(exact)
+        prefer_sherpa = False
+
+    if purpose == "dictation" and prefer_sherpa:
         ok, _ = SherpaDictationBackend.is_available()
-        want_sherpa = ok
-    if not want_sherpa and exact is not None and _model_supported(exact):
+        if ok:
+            if exact is not None and _eligible(exact, sherpa=True):
+                return _shape(exact)
+            for m in KNOWN_MODELS:
+                if (m.get("role") == "ASR" and _eligible(m, sherpa=True)
+                        and _model_curated(m)):
+                    return _shape(m)
+
+    # No usable Sherpa recommendation remains (runtime unavailable, explicit
+    # fallback probe, or the sole curated entry is the demoted model). Offer
+    # the exact capture fallback so download → retry cannot loop.
+    if exact is not None and _eligible(exact, sherpa=False):
         return _shape(exact)
     for m in KNOWN_MODELS:
         if m.get("role") != "ASR":
             continue
-        if (m.get("engine") == "sherpa-onnx") != want_sherpa:
-            continue
-        if _model_curated(m) and _model_supported(m):
+        if _eligible(m, sherpa=False) and _model_curated(m):
             return _shape(m)
     return None
 
@@ -3256,7 +3461,9 @@ def _repo_installed(repo: str) -> bool:
 
 def asr_model_missing_error(*, purpose: str = "transcribe",
                             sherpa_model_id: str | None = None,
-                            backend_id: str | None = None) -> dict | None:
+                            backend_id: str | None = None,
+                            skip_sherpa: bool = False,
+                            require_installed: bool = False) -> dict | None:
     """None when the active ASR selection can transcribe without downloading
     anything; otherwise the typed ``{"error": "asr_model_missing", ...}``
     payload for a 409 / SSE / WS error with a download CTA.
@@ -3268,6 +3475,11 @@ def asr_model_missing_error(*, purpose: str = "transcribe",
     ``?model=`` override. Installed state comes from the same HF-cache helpers
     the model store uses (see :func:`_repo_installed`), so the answer matches
     the Model Catalogue → Models install badges.
+    ``skip_sherpa`` probes only the non-Sherpa capture fallback; silent-model
+    recovery uses it before deciding whether persistent demotion is warranted.
+    ``require_installed`` makes unknown/custom selections fail closed for that
+    recovery path so it can never turn the normal fail-open policy into an
+    implicit model download.
 
     FAIL-OPEN rule: a repo the model catalog doesn't know (a custom
     ``ASR_MODEL_*`` pin, pytorch-whisper's default repo, an unrecognized
@@ -3277,27 +3489,55 @@ def asr_model_missing_error(*, purpose: str = "transcribe",
     a broken preflight must degrade to the old behaviour, not block ASR.
     """
     try:
+        prefer_sherpa_recommendation = not skip_sherpa
+        excluded_sherpa_model_id = None
         if purpose == "dictation":
-            sid = sherpa_model_id or dictation_model_id()
+            sid = None if skip_sherpa else (sherpa_model_id or dictation_model_id())
             if sid:
                 ok, _ = SherpaDictationBackend.is_available()
                 if ok:
                     from services import sherpa_dictation as _sd
                     spec = _sd.get_spec(sid)
+                    # A recognizer observed returning silence must follow the
+                    # same capture fallback as execution, even when the
+                    # frontend keeps sending its persisted `?model=` value.
                     if spec is not None:
-                        if _sd.is_installed(spec):
-                            return None
-                        return {
-                            "error": ASR_MODEL_MISSING,
-                            "missing_repo_id": spec.repo_id,
-                            "recommended": _recommended_asr_model(purpose, spec.repo_id),
-                        }
+                        if _sd.is_demoted(spec.id):
+                            excluded_sherpa_model_id = spec.id
+                        else:
+                            if _sd.is_installed(spec):
+                                return None
+                            return {
+                                "error": ASR_MODEL_MISSING,
+                                "missing_repo_id": spec.repo_id,
+                                "recommended": _recommended_asr_model(
+                                    purpose, spec.repo_id,
+                                ),
+                            }
             repo = _capture_whisper_repo()
         else:
             repo = _offline_asr_repo(backend_id)
         if repo is None:
+            if require_installed:
+                return {
+                    "error": ASR_MODEL_MISSING,
+                    "missing_repo_id": "unresolved-capture-fallback",
+                    "recommended": None,
+                }
             return None  # explicit opt-in engine — can't (and shouldn't) preflight
         from api.routers.setup.models import get_model_catalog
+        if require_installed:
+            if _repo_installed(repo):
+                return None
+            return {
+                "error": ASR_MODEL_MISSING,
+                "missing_repo_id": repo,
+                "recommended": _recommended_asr_model(
+                    purpose, repo,
+                    prefer_sherpa=prefer_sherpa_recommendation,
+                    excluded_sherpa_model_id=excluded_sherpa_model_id,
+                ),
+            }
         if get_model_catalog().get(repo) is None:
             return None  # not installable from the CTA — fail open (see docstring)
         if _repo_installed(repo):
@@ -3305,7 +3545,11 @@ def asr_model_missing_error(*, purpose: str = "transcribe",
         return {
             "error": ASR_MODEL_MISSING,
             "missing_repo_id": repo,
-            "recommended": _recommended_asr_model(purpose, repo),
+            "recommended": _recommended_asr_model(
+                purpose, repo,
+                prefer_sherpa=prefer_sherpa_recommendation,
+                excluded_sherpa_model_id=excluded_sherpa_model_id,
+            ),
         }
     except Exception:  # noqa: BLE001 — preflight is best-effort, never a blocker
         logger.warning("ASR install preflight failed — proceeding without it",

backend/services/dub_pipeline.py

@@ -742,6 +742,74 @@ def _ensure_browser_playable_mp4(video_path: str) -> str:
     return video_path
 
 
+async def _ensure_browser_playable_mp4_for_job(job_id: str, video_path: str) -> str:
+    """Normalize an upload through the job's cancellable process registry."""
+    is_mp4 = video_path.lower().endswith(".mp4")
+    vcodec, acodec = await asyncio.to_thread(_probe_codecs, video_path)
+    if is_mp4 and vcodec in _BROWSER_VIDEO_CODECS and acodec in _BROWSER_AUDIO_CODECS:
+        return video_path
+
+    target = os.path.splitext(video_path)[0] + ".mp4"
+    if target == video_path:
+        target = os.path.splitext(video_path)[0] + ".browser.mp4"
+    run_proc = run_proc_factory(job_id)
+    ffmpeg_bin = find_ffmpeg()
+
+    async def attempt(cmd: list[str]) -> int:
+        try:
+            proc, _stdout, _stderr = await run_proc(cmd, timeout=1800.0)
+            return proc.returncode
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.warning(
+                "Browser-media normalization process failed for %s: %s",
+                log_safe(video_path),
+                log_safe(exc),
+            )
+            return 1
+
+    rc = 1
+    if not is_mp4:
+        rc = await attempt(
+            [
+                ffmpeg_bin, "-y", "-i", video_path,
+                "-c:v", "copy", "-c:a", "copy",
+                "-movflags", "+faststart", target,
+            ]
+        )
+        if rc == 0 and os.path.exists(target):
+            target_vcodec, target_acodec = await asyncio.to_thread(_probe_codecs, target)
+            if (
+                target_vcodec not in _BROWSER_VIDEO_CODECS
+                or target_acodec not in _BROWSER_AUDIO_CODECS
+            ):
+                rc = 1
+        else:
+            rc = 1
+    if rc != 0:
+        rc = await attempt(
+            [
+                ffmpeg_bin, "-y", "-i", video_path,
+                "-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
+                "-pix_fmt", "yuv420p", "-c:a", "aac", "-b:a", "192k",
+                "-movflags", "+faststart", target,
+            ]
+        )
+    if rc == 0 and os.path.exists(target) and target != video_path:
+        try:
+            os.remove(video_path)
+        except OSError:
+            pass  # Best effort: the normalized target is already complete.
+        return target
+    logger.warning(
+        "Could not transcode %s to browser-playable mp4 — the in-app "
+        "video player may render this file as a black box.",
+        log_safe(video_path),
+    )
+    return video_path
+
+
 # Bounded retry for transient download failures (#579/#598). yt-dlp's own
 # `retries`/`fragment_retries` cover per-fragment HTTP flakes, but a broken
 # pipe ([Errno 32]) raised while the write side of a pipe closes mid-stream
@@ -1257,6 +1325,13 @@ async def ingest_pipeline(
         except Exception:
             dur = 0.0
 
+        # URL downloads already pass through this guard in yt_download_sync.
+        # Uploaded videos did not, so a valid VP9/AV1/Opus upload could be
+        # processed successfully but remain undecodable by the in-app WebView.
+        # Codec probing/transcoding is blocking; keep it off the event loop.
+        if source.get("kind") != "url" and input_type != "audio":
+            video_path = await _ensure_browser_playable_mp4_for_job(job_id, video_path)
+
         # Content-hash cache: reuse artifacts from previous matching jobs.
         content_hash = await asyncio.to_thread(compute_file_hash, audio_path)
         cached = find_cached_job(content_hash, job_id)
@@ -1295,6 +1370,7 @@ async def ingest_pipeline(
                 "scene_cuts": scene_cuts,
                 "youtube_subs": youtube_subs_by_lang or None,
                 "input_type": input_type,
+                "source_lang_override": source.get("source_lang"),
             }
             if not put_and_save_job(
                 job_id, full_job, filename=filename, duration=dur, content_hash=content_hash,
@@ -1323,6 +1399,7 @@ async def ingest_pipeline(
                 "scene_cuts": [],
                 "youtube_subs": youtube_subs_by_lang or None,
                 "input_type": input_type,
+                "source_lang_override": source.get("source_lang"),
             }
             if not put_and_save_job(
                 job_id, partial, filename=filename, duration=dur, content_hash=content_hash,