Closes the last #21 gap: a per-request engine=/model= override bypasses the
/engines/select host-gate, so an engine that can't use this host's GPU could
still be triggered at synth time and silently fall back to CPU (or die mid-
synth). Now enforced at every TTS synth entry point, reusing the SAME probe +
resolver — never re-deriving routing.
Shared helpers (services/engine_routing.py):
- `routing_notice(result)` → (status, reason) to surface, or None. Fires for
cpu_fallback (always) and accelerated-with-caveat (driver/arch); silent for
cpu_only / clean-accelerated / n/a.
- `header_safe_reason(reason)` → scrubbed + ASCII-sanitized (headers are
latin-1; a non-ASCII device name would 500 otherwise) + ≤256 chars. No regex.
Entry points:
- REST `POST /generate` (generation.py): after engine resolution, resolve
routing once; `unavailable` → 400; cpu_fallback / accelerated-caveat → 200 +
`X-OmniVoice-Routing` + `X-OmniVoice-Routing-Reason` headers on the WAV
StreamingResponse; benign → no headers. Covers OmniVoice + adapter branches.
- OpenAI-compat `POST /v1/audio/speech` (openai_compat.py): same gate + same
headers; the tts-1/tts-1-hd alias inherits the active engine's routing.
- WebSocket `/ws/tts` (tts_stream.py): no headers → frames. `unavailable` →
`{"type":"error",...}` + skip stream; cpu_fallback / caveat → one
`{"type":"routing","status","reason"}` frame before any audio.
- `select_engine` response now echoes routing_status / effective_device /
routing_reason (PR #432 added the gate; this adds the fields so the UI can
warn on a cpu_fallback pick). New fields on SelectEngineResponse.
Frontend: `useTTS` reads the X-OmniVoice-Routing header and shows a one-time,
non-blocking toast (in-memory de-dup by status — a 50-clip batch fires once,
no localStorage). i18n keys `tts.routingFallback`/`tts.routingCaveat`.
Tests: routing_notice + header_safe_reason (ASCII/length/scrub) unit tests;
REST synth gate (unavailable→400, cpu_fallback→headers, cpu_only→none) via the
fake-engine harness with a mocked host; select response routing fields.
Deferred (small follow-up): dub-pipeline ASR routing note on the preflight_error
SSE channel — separate path, not a TTS synth entry point. No frontend /ws/tts
client exists today (the routing frame serves external API consumers).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
