voice: announce LLM errors instead of silent 'thinking forever' (LLMErrorAnnouncer)

[mabry1985]

Problem

When the active LLM endpoint fails (auth 401, unreachable, timeout), the orb sits in "thinking" forever, silently. The StallWatchdog disarms on LLMFullResponseStartFrame (pushed before the HTTP call), and the resulting ErrorFrame flows upstream where nothing re-arms or reacts. The user gets no signal at all.

This is the worst first-run failure, and the free + OSS pivot makes it more acute: every user now wires their own LLM endpoint, so a misconfigured key / wrong URL (→ 401 / connection refused) is one of the most likely first-run states.

Secondary effect: a dead LLM + silence also trips wake auto-close, which masquerades as "the app keeps turning off."

Proposed fix — LLMErrorAnnouncer

A processor/observer that:

1. Catches the upstream ErrorFrame from the active LLM service.
2. Classifies it: auth (401/403) vs unreachable (connection/DNS/timeout) vs other.
3. Speaks one throttled canned line via an out-of-band TTSSpeakFrame (append_to_context=False), e.g. "I can't reach my language model right now — check the endpoint in settings." Distinct copy per class.
4. Re-arms the StallWatchdog (or otherwise clears the stuck "thinking" state) so the next turn is clean.

Notes / guardrails

• Throttle hard (one line per N seconds) — a flapping endpoint must not spam.
• Route the spoken line through TTS only (no LLM round-trip — the LLM is what's broken).
• Pairs with the StallWatchdog; see STATUS.md 06-11 "Live incident during testing".

LOE: S–M. Priority: top of the audit/robustness list.

[mabry1985]

Design locked (root-caused against pipecat source)

Root cause confirmed. FrameProcessor.push_error() pushes the ErrorFrame upstream (pipecat/processors/frame_processor.py:650), and LLM services use it on a generate failure (pipecat/services/llm_service.py:1011, fatal=False). The StallWatchdog sits downstream of the LLM, so it never sees the upstream error — and it has already disarmed on LLMFullResponseStartFrame (pushed before the HTTP call). Nothing re-arms → silent "thinking forever".

Why a naive upstream processor won't work. ServiceSwitcher (our LLMSwitcher failover, orbis-1dd) re-propagates the ErrorFrame upstream even when failover succeeds (pipecat/pipeline/service_switcher.py:302-303: "The error frame is still propagated upstream so that application-level error handlers can observe it"). So a processor placed upstream of the LLM would false-fire on a recovered failover.

Chosen design: an Observer + debounce + throttle. Pipecat explicitly intends app-level error handlers to observe the ErrorFrame, and an observer sees every frame in both directions regardless of position (same family as our SseBusObserver).

1. Detect — on_push_frame: non-fatal ErrorFrame whose .processor is an LLM service.
2. Debounce — arm a ~2s timer on the error; cancel if LLMTextFrame or BotStartedSpeakingFrame arrives first (real output → single-LLM retry or switcher failover recovered → don't announce).
3. Throttle — min ~20s between spoken lines so a flapping endpoint can't spam.
4. Classify — 401/403/unauthorized → auth ("can't authenticate with my language model — check the API key in settings"); connection/refused/timeout/name resolution → unreachable ("can't reach my language model — check the endpoint in settings"); else generic.
5. Speak — inject TTSSpeakFrame(line, append_to_context=False) via the PipelineTask (out-of-band, like the filler/watchdog lines). The bot speaking also clears the stuck "thinking" bot-state via the existing SSE observer.

Test plan: unit test (mirror tests/test_stall_watchdog.py): feed an LLM ErrorFrame → assert one TTS line with the right class; feed ErrorFrame then a quick LLMTextFrame → assert no line (debounce); two errors within the throttle window → assert one line.

Open impl detail: confirm the task-side frame-injection entry point (queue_frame/queue_frames) and pass the task handle to the observer after task creation.

Needs live validation before merge: a real 401 (bad key) and a real unreachable endpoint (wrong URL) on the running build — this is med-churn (must not fight failover), so it gets its own PR + a soak, not a tail-of-turn commit.