@bojackduy/opencode-voice 0.8.0 → 0.10.0

package/README.md

@@ -243,6 +243,65 @@ English reply no longer flips the whole thing to the Vietnamese voice, and
 vice versa. Toneless Vietnamese (no diacritics) still reads as English -
 that is not distinguishable from English by this heuristic.
 
+### Chatterbox engine (optional)
+
+Piper is the default and needs no setup beyond the section above. For more
+natural-sounding English, opt into [Chatterbox](https://github.com/resemble-ai/chatterbox)
+(Resemble AI, MIT) as the synthesis engine. It runs as a managed sidecar
+(`vendor/chatterbox_server.py`, stdlib HTTP only): the model loads once, the
+plugin probes readiness, and the sidecar is killed on dispose. Playback still
+goes through the existing `play` path, so `/tts-stop` and cancel behave the
+same on both engines.
+
+Setup (isolated venv, never touches your system python):
+
+```bash
+python3 -m venv ~/.local/share/opencode-voice/chatterbox-venv
+~/.local/share/opencode-voice/chatterbox-venv/bin/pip install chatterbox-tts
+# chatterbox's `perth` dependency needs pkg_resources (removed in setuptools ≥ 81):
+~/.local/share/opencode-voice/chatterbox-venv/bin/pip install 'setuptools<81'
+```
+
+First run downloads ~7GB of weights from HuggingFace, then the sidecar takes
+~20s to load on Apple Silicon (MPS). No venv, no weights, no wavs are ever
+committed.
+
+Options in `tui.json` (all under the plugin entry, next to `endpoint`):
+
+```json
+{
+  "ttsEngine": "chatterbox",
+  "ttsChatterboxVariant": "multilingual",
+  "ttsChatterboxVoiceRef": "/absolute/path/to/voice-5-20s.wav"
+}
+```
+
+- `ttsEngine`: `"piper"` (default) | `"chatterbox"`. Unknown values warn and
+  use Piper.
+- `ttsChatterboxVariant`: `"multilingual"` (default) | `"turbo"` | `"nano"`.
+- `ttsChatterboxVoiceRef`: optional absolute path to a 5-20s reference wav
+  for zero-shot voice cloning. Unset means the model default voice; a missing
+  file warns and proceeds voiceless.
+- `ttsChatterboxPython`: optional python binary for the sidecar. Defaults to
+  `python3` on `PATH` - set it to the venv python above.
+
+Per-utterance Piper fallback: whenever Chatterbox cannot speak an utterance,
+that utterance goes to Piper with a warn log (one toast per outage, not per
+utterance; the next utterance retries Chatterbox). Cases: sidecar not
+installed/crashed, ~15s synthesis bound exceeded, and language routing below.
+
+Honest limits, measured on Apple Silicon (MPS) with Multilingual V3:
+
+- Chatterbox does **not** speak Vietnamese. Its multilingual model covers 23
+  languages (`ar da de el en es fi fr he hi it ja ko ms nl no pl pt ru sv sw
+th tr zh`) - `vi` is not one, so **every** Vietnamese utterance falls back
+  to Piper regardless of variant. Nano/Turbo are English-only by design.
+- Latency for "Deploying now.": Piper 0.77s wall for 0.80s of audio (RTF
+  ~1.0); Chatterbox ~16s wall for ~1s of audio on first synthesis after load
+  (RTF ~15, MPS warmup included), ~5-8s wall (RTF ~1.5-3) once warm. It is a
+  quality upgrade, not a speed one.
+- Outputs carry Chatterbox's inaudible PerTh watermark.
+
 ### LLM endpoint
 
 An OpenAI-compatible LLM endpoint is required for text normalization. For
@@ -419,36 +478,47 @@ then `s`.
 
 ### Voice conversation
 
-| Command                    | Keybind    | Description                               |
-| -------------------------- | ---------- | ----------------------------------------- |
-| `/voice-conversation`      | `leader+v` | Toggle hands-free voice conversation mode |
-| `/voice-conversation-stop` |            | Exit voice conversation mode              |
+| Command                    | Keybind    | Description                                 |
+| -------------------------- | ---------- | ------------------------------------------- |
+| `/voice-conversation`      | `leader+v` | Toggle push-to-talk voice conversation mode |
+| `/voice-conversation-stop` |            | Exit voice conversation mode                |
 
-One key drives the whole loop - its meaning follows the toast on screen:
+One key drives the whole loop. It always means the same thing - "I want the
+floor" - and what it does follows the toast on screen:
 
 ```
-record -> transcribe -> normalize -> submit -> wait reply -> speak -> record ...
+press -> record -> press -> transcribe -> normalize -> submit -> speak -> press ...
 ```
 
-| Toast shows               | Pressing the key does                |
-| ------------------------- | ------------------------------------ |
-| ● Recording               | Finish the turn and submit           |
-| Speaking...               | Pause speech (press again to record) |
-| Paused                    | Record again                         |
-| Waiting / Transcribing... | Exit the mode                        |
-
-Empty or failed turns pause instead of re-recording, so the key never
-surprises. Saying only a stop phrase (`stop`, `stop stop`, `dừng lại đi`,
-...) ends the mode without submitting - full sentences mentioning stop still
-submit normally. `/tts-stop` pauses a speaking reply; `/voice-conversation-stop`
-exits from anywhere. While the mode is on, the plain `/stt-record` keys act
-as the conversation key and auto TTS stays silent (the loop speaks the reply
-itself).
+| Toast shows              | Pressing the key does                     |
+| ------------------------ | ----------------------------------------- |
+| Press `leader+v` to talk | Open the mic (this is the resting state)  |
+| ● Recording              | Finish the turn and submit                |
+| Working... / Speaking    | Barge in: cut audio, drop reply, open mic |
+| Answer on screen         | Same barge-in, while the agent resumes    |
+| Transcribing...          | Report busy - too short to interrupt      |
+
+The loop never reopens the mic by itself: after a reply is spoken the mode rests
+paused, so it cannot record the room while nobody is talking. Barge-in drops
+the pending reply on purpose - pressing means talking now, not hearing the
+rest.
+
+Answering a permission or a question is the one thing the key cannot do,
+because that answer is given on screen. The mode announces the gate, keeps the
+mic shut, then speaks the agent's answer once the agent resumes.
+
+Exit paths: a stop phrase (`stop`, `stop stop`, `dừng lại đi`, ...),
+`/voice-conversation-stop`, or the global `/voice-cancel` (`leader+.`). Only a
+bare stop phrase ends the mode - full sentences mentioning stop submit
+normally. Empty or failed turns pause instead of re-recording, so the key never
+surprises. `/tts-stop` pauses a speaking reply and rests paused. While the mode
+is on, the plain `/stt-record` keys act as the conversation key and auto TTS
+stays silent (the loop speaks the reply itself).
 
 While waiting, assistant text is spoken sentence by sentence as it streams in
 (local cleanup, no LLM), so the answer starts before the agent turn finishes.
 Code-like sentences are skipped; replies with nothing streamable fall back to
-the full narrated speak. Pressing the key mid-stream exits the mode.
+the full narrated speak.
 
 - `ttsNormalizeMode` _(optional)_ - `"llm"` (default, polished narration) or
   `"local"` (instant deterministic cleanup, no network). Streaming speech
@@ -667,6 +737,10 @@ live-mic session was measured.
    code-heavy responses, or briefly notify for confirmations
 3. Piper synthesizes speech locally, piped through sox for playback
 
+The LLM is only a polish layer: when the configured model is unavailable or out
+of quota, TTS speaks the local cleanup automatically instead of going silent.
+Set `ttsNormalizeMode: "local"` to skip narration entirely.
+
 ### Auto TTS
 
 When enabled (`/tts-mode`), the plugin automatically speaks:

package/lib/chatterbox-server.js

@@ -0,0 +1,428 @@
+// Managed Chatterbox TTS sidecar (see vendor/chatterbox_server.py).
+//
+// Why a sidecar instead of a one-shot CLI: Chatterbox loads a large torch
+// model. Loading it per utterance would never keep up with a spoken
+// conversation, so - exactly like lib/whisper-server.js for whisper.cpp - one
+// child process loads the model once and serves synthesis over HTTP while we
+// own its lifetime.
+//
+// Follows the whisper-server conventions deliberately:
+// - Port is probed BEFORE spawning; if anything already answers we never claim
+//   it and never kill the foreign process. Default-port callers auto-advance
+//   upward (bounded) so a second TUI lands on its own port with its own model
+//   load instead of being stuck on Piper forever.
+// - Readiness is GET /health: 200 = ready, 503 = still loading or failed. The
+//   sidecar answers 503 with the real reason ("chatterbox-tts not installed"),
+//   so we can fail fast with an actionable message instead of waiting out the
+//   whole timeout on an install that will never succeed.
+// - stop() only ever signals the handle this client spawned.
+// - Every failure is a typed {code, message}, never a silent return of nothing:
+//   the caller turns it into a per-utterance Piper fallback.
+//
+// This client is an OPTIMIZATION. Piper is the default engine and stays the
+// zero-setup fallback, so every failure path here ends in Piper, never silence.
+
+import fs from "node:fs";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 8120;
+const DEFAULT_PORT_SCAN_MAX = 4;
+// Model load on first run also downloads weights from HuggingFace, so the
+// readiness budget is generous. It is a bound, not a promise: a failed load
+// reports immediately via the 503 body instead of waiting this out.
+const READY_TIMEOUT_MS = 300000;
+const READY_POLL_MS = 500;
+// One utterance must never stall speech indefinitely.
+const SYNTHESIZE_TIMEOUT_MS = 15000;
+
+const SIDECAR_PATH = fileURLToPath(new URL("../vendor/chatterbox_server.py", import.meta.url));
+
+export const CHATTERBOX_VARIANTS = ["multilingual", "turbo", "nano"];
+export const DEFAULT_CHATTERBOX_VARIANT = "multilingual";
+
+// Per-variant language support, read off the real package
+// (chatterbox-tts 0.1.7) rather than guessed.
+//
+// MEASURED, and worth stating plainly: the multilingual model speaks 23
+// languages and Vietnamese is NOT one of them. Its generate() raises
+// ValueError on language_id "vi". Nano/Turbo are English-only by design. So
+// every variant routes a vi utterance to Piper, and Chatterbox covers English.
+// Do not "fix" this by adding "vi" here - it would fail at synthesis time.
+const CHATTERBOX_LANGUAGES = {
+  multilingual: new Set([
+    "ar",
+    "da",
+    "de",
+    "el",
+    "en",
+    "es",
+    "fi",
+    "fr",
+    "he",
+    "hi",
+    "it",
+    "ja",
+    "ko",
+    "ms",
+    "nl",
+    "no",
+    "pl",
+    "pt",
+    "ru",
+    "sv",
+    "sw",
+    "th",
+    "tr",
+    "zh",
+  ]),
+  turbo: new Set(["en"]),
+  nano: new Set(["en"]),
+};
+
+export function isChatterboxVariant(value) {
+  return CHATTERBOX_VARIANTS.includes(value);
+}
+
+// Can this variant speak this language? Unknown variants answer false, which
+// routes to Piper - the safe default, since Piper always has an answer.
+export function chatterboxSupportsLang(variant, lang) {
+  const set = CHATTERBOX_LANGUAGES[variant];
+  return !!set && set.has(lang);
+}
+
+// The one routing decision, pure and exported so it can be tested without a
+// sidecar, a model, or an audio device. Returns the engine to use plus the
+// reason, which the caller logs (and which keeps per-utterance skips quiet in
+// the UI - no toast spam for a language Piper can already read).
+export function resolveTtsEngine(opts, lang, warn) {
+  const configured = opts?.ttsEngine;
+  if (!configured || configured === "piper") return { engine: "piper", reason: "default" };
+  if (configured !== "chatterbox") {
+    warn?.(`Unknown ttsEngine "${configured}" - expected "piper" or "chatterbox"; using Piper`);
+    return { engine: "piper", reason: "unknown-engine" };
+  }
+  const requested = opts?.ttsChatterboxVariant;
+  if (requested && !isChatterboxVariant(requested)) {
+    warn?.(
+      `Unknown ttsChatterboxVariant "${requested}" - expected ${CHATTERBOX_VARIANTS.join(" | ")}; using "${DEFAULT_CHATTERBOX_VARIANT}"`,
+    );
+  }
+  const variant = isChatterboxVariant(requested) ? requested : DEFAULT_CHATTERBOX_VARIANT;
+  if (chatterboxSupportsLang(variant, lang)) return { engine: "chatterbox", variant, reason: "ok" };
+  warn?.(`Chatterbox variant "${variant}" cannot speak "${lang}" - using Piper for this utterance`);
+  return { engine: "piper", reason: "unsupported-language", variant };
+}
+
+export function buildChatterboxArgs({ scriptPath, host, port, variant }) {
+  return [
+    scriptPath || SIDECAR_PATH,
+    "--host",
+    host || DEFAULT_HOST,
+    "--port",
+    String(port || DEFAULT_PORT),
+    "--variant",
+    variant || DEFAULT_CHATTERBOX_VARIANT,
+  ];
+}
+
+export { DEFAULT_HOST, DEFAULT_PORT, DEFAULT_PORT_SCAN_MAX, SIDECAR_PATH };
+
+export function createChatterboxClient(options = {}) {
+  const {
+    host = DEFAULT_HOST,
+    python,
+    variant = DEFAULT_CHATTERBOX_VARIANT,
+    voiceRef,
+    exaggeration,
+    cfgWeight,
+    logger,
+    readyTimeoutMs = READY_TIMEOUT_MS,
+    readyPollMs = READY_POLL_MS,
+    synthesizeTimeoutMs = SYNTHESIZE_TIMEOUT_MS,
+    portScanMax = DEFAULT_PORT_SCAN_MAX,
+    deps = {},
+  } = options;
+  const scriptPath = options.scriptPath || SIDECAR_PATH;
+  const spawnFn = deps.spawn ?? spawn;
+  const fetchFn = deps.fetch ?? fetch;
+
+  let proc = null;
+  let ready = false;
+  let ownerPid = null;
+  // Where the port scan starts. The plugin never sets it (so production always
+  // begins at 8120), but tests bind an ephemeral port and need to reach it.
+  const basePort = options.port ?? DEFAULT_PORT;
+  let boundPort = basePort;
+  let lastError = null;
+  let device = "unknown";
+  // A missing reference wav must not kill the whole engine - the sidecar still
+  // speaks with its default voice, which is better than falling back to Piper.
+  let refPath = voiceRef ? String(voiceRef).replace(/^~(?=\/|$)/, os.homedir()) : "";
+  if (refPath && !fs.existsSync(refPath)) {
+    logger?.log(
+      "VOICE",
+      `Chatterbox voice reference not found, using default voice: ${refPath}`,
+      "warn",
+    );
+    refPath = "";
+  }
+
+  const baseUrlFor = (p) => `http://${host}:${p}`;
+
+  async function portResponds(p) {
+    const base = baseUrlFor(p);
+    for (const url of [`${base}/health`, base]) {
+      try {
+        const resp = await fetchFn(url, { signal: AbortSignal.timeout(1500) });
+        if (resp) return true;
+      } catch {
+        // Connection refused / timeout: try the next URL.
+      }
+    }
+    return false;
+  }
+
+  // One probe. "ready" | "loading" | {failed: message} | "down". The failed
+  // shape carries the sidecar's own reason so start() can surface it verbatim.
+  async function probeOnce() {
+    try {
+      const resp = await fetchFn(`${baseUrlFor(boundPort)}/health`, {
+        signal: AbortSignal.timeout(2000),
+      });
+      if (!resp) return "down";
+      if (resp.status === 503) {
+        let body = {};
+        try {
+          body = await resp.json();
+        } catch {
+          // Non-JSON 503: treat as still loading rather than guessing.
+        }
+        if (body?.phase === "failed") return { failed: body?.error || "model load failed" };
+        return "loading";
+      }
+      if (resp?.ok) {
+        try {
+          const body = await resp.json();
+          if (body?.device) device = body.device;
+        } catch {
+          // 200 with an unparseable body still means the port answered /health.
+        }
+        return "ready";
+      }
+      return "down";
+    } catch {
+      return "down";
+    }
+  }
+
+  async function pollReady(deadline) {
+    while (Date.now() < deadline) {
+      if (!proc) return { failed: "chatterbox sidecar exited before becoming ready" };
+      const state = await probeOnce();
+      if (state === "ready") return state;
+      if (state?.failed) return state;
+      await new Promise((r) => setTimeout(r, readyPollMs));
+    }
+    return "timeout";
+  }
+
+  // Attempt one port: probe, spawn, wait for readiness. stop() inside only ever
+  // signals the handle spawned here.
+  async function startOnPort(port) {
+    boundPort = port;
+    if (await portResponds(port)) {
+      return {
+        ok: false,
+        code: "PORT_IN_USE",
+        advancable: true,
+        message: `Port ${port} already answers - not starting a second chatterbox sidecar`,
+      };
+    }
+    const args = buildChatterboxArgs({ scriptPath, host, port, variant });
+    const bin = python || "python3";
+    try {
+      proc = spawnFn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    } catch (err) {
+      proc = null;
+      return {
+        ok: false,
+        code: "SPAWN_FAILED",
+        advancable: false,
+        message: `Failed to spawn ${bin}: ${err.message}`,
+      };
+    }
+
+    let stderr = "";
+    const owned = proc;
+    proc.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("exit", (code) => {
+      // A late event from a previous child must not wipe the current handle.
+      if (proc !== owned) return;
+      // Record why, so a sidecar that dies mid-session explains the Piper
+      // fallback instead of reporting a bare "not ready". A deliberate stop()
+      // already nulled proc, so it never reaches here.
+      lastError = { code: "EXITED", message: `chatterbox sidecar exited (code=${code})` };
+      proc = null;
+      ready = false;
+      ownerPid = null;
+    });
+    proc.on("error", (err) => {
+      if (proc !== owned) return;
+      logger?.log("VOICE", `chatterbox sidecar process error: ${err.message}`, "warn");
+      proc = null;
+      ready = false;
+      ownerPid = null;
+    });
+
+    const outcome = await pollReady(Date.now() + readyTimeoutMs);
+    if (outcome !== "ready") {
+      const tail = stderr.trim().slice(-300);
+      const message =
+        outcome === "timeout"
+          ? `chatterbox sidecar did not become ready in time (${readyTimeoutMs}ms) stderr=${tail}`
+          : `chatterbox sidecar unavailable: ${outcome.failed ?? "unknown"}`;
+      const code = outcome === "timeout" ? "START_TIMEOUT" : "MODEL_LOAD_FAILED";
+      stop();
+      return { ok: false, code, advancable: false, message };
+    }
+    ownerPid = proc?.pid ?? null;
+    return { ok: true };
+  }
+
+  async function start() {
+    if (proc && ready) return true; // reuse the owned, already-ready sidecar
+    const scanMax = Math.max(1, Math.floor(portScanMax) || 1);
+    for (let i = 0; i < scanMax; i += 1) {
+      const port = basePort + i;
+      const r = await startOnPort(port);
+      if (r.ok) {
+        ready = true;
+        lastError = null;
+        logger?.log(
+          "VOICE",
+          `chatterbox sidecar ready at ${baseUrlFor(boundPort)} variant=${variant} device=${device} pid=${ownerPid}`,
+          "debug",
+        );
+        return true;
+      }
+      if (!r.advancable) {
+        lastError = { code: r.code, message: r.message };
+        logger?.log("VOICE", r.message, "warn");
+        return false;
+      }
+      logger?.log("VOICE", r.message, "warn");
+    }
+    lastError = {
+      code: "PORT_RANGE_EXHAUSTED",
+      message: `No free port in ${basePort}..${basePort + scanMax - 1} - all answer, using Piper`,
+    };
+    logger?.log("VOICE", lastError.message, "warn");
+    return false;
+  }
+
+  // One-shot health read, for callers that want to report the engine's state
+  // (and for tests). Returns {ok, variant, device, phase, error?}.
+  async function health() {
+    try {
+      const resp = await fetchFn(`${baseUrlFor(boundPort)}/health`, {
+        signal: AbortSignal.timeout(2000),
+      });
+      const body = await resp.json();
+      return body;
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  }
+
+  // Synthesize one utterance. Returns {ok:true, wav:Buffer} or
+  // {ok:false, code, message} - never throws, so the caller always has a Piper
+  // fallback available. options.signal lets a cancel abort the in-flight request
+  // (the sidecar finishes its own generation and discards the result; the
+  // caller's generation guard is what actually prevents stale playback).
+  async function synthesize(text, languageId, opts = {}) {
+    if (!ready) {
+      return {
+        ok: false,
+        code: lastError?.code || "NOT_READY",
+        message: lastError?.message || "chatterbox sidecar not ready",
+      };
+    }
+    const body = {
+      text,
+      language_id: languageId || undefined,
+      exaggeration: opts.exaggeration ?? exaggeration ?? undefined,
+      cfg_weight: opts.cfgWeight ?? cfgWeight ?? undefined,
+      voice_ref: refPath || undefined,
+    };
+    try {
+      // One utterance must never stall speech indefinitely: bound the request,
+      // and let an outer cancel abort it too. On timeout we fall back to
+      // Piper for THIS utterance only - the sidecar stays up.
+      const timeout = AbortSignal.timeout(synthesizeTimeoutMs);
+      const signal = opts.signal ? AbortSignal.any([timeout, opts.signal]) : timeout;
+      const resp = await fetchFn(`${baseUrlFor(boundPort)}/speak`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!resp?.ok) {
+        let message = `chatterbox sidecar responded ${resp?.status}`;
+        try {
+          const data = await resp.json();
+          if (data?.error) message = data.error;
+        } catch {
+          // Keep the status-based message.
+        }
+        return { ok: false, code: "BAD_STATUS", message };
+      }
+      const audio = Buffer.from(await resp.arrayBuffer());
+      if (audio.length === 0) {
+        return { ok: false, code: "EMPTY_AUDIO", message: "chatterbox returned no audio" };
+      }
+      return { ok: true, wav: audio };
+    } catch (err) {
+      const timedOut = err?.name === "TimeoutError" || err?.name === "AbortError";
+      return {
+        ok: false,
+        code: timedOut ? "SYNTH_TIMEOUT" : "REQUEST_FAILED",
+        message: `chatterbox synthesis failed: ${err.message}`,
+      };
+    }
+  }
+
+  // Stop ONLY the process this client spawned (by handle). A foreign process
+  // on the same port is never signaled.
+  function stop() {
+    ready = false;
+    ownerPid = null;
+    if (proc) {
+      const owned = proc;
+      proc = null;
+      try {
+        owned.kill("SIGTERM");
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+
+  function isRunning() {
+    return ready && proc !== null;
+  }
+
+  function getLastError() {
+    return lastError;
+  }
+
+  function getPort() {
+    return boundPort;
+  }
+
+  return { start, stop, health, synthesize, isRunning, getLastError, getPort };
+}

package/lib/conversation.js

@@ -1,18 +1,27 @@
-// Voice conversation mode: hands-free talk loop with OpenCode.
+// Voice conversation mode: push-to-talk turns with barge-in.
 //
-// One key drives the whole loop; its meaning depends on the state shown in
+// One key drives the whole loop and its meaning is always the same: the user
+// wants the floor. What the key actually does depends on the state shown in
 // the toast:
 //
-//   record -> transcribe -> normalize -> submit -> wait reply -> speak -> record ...
+//   press -> record -> press -> transcribe -> normalize -> submit
+//         -> wait reply -> speak -> press -> record ...
 //
+// - paused + key: open the mic (the resting state is the user's turn)
 // - recording + key: finish the turn and submit
-// - speaking + key: pause speech (press again to record the next turn)
-// - paused + key: record again
-// - waiting/processing + key: exit the mode
+// - speaking/waiting + key: barge in - cut the audio, drop the pending reply,
+//   open the mic (one press, never a stop-then-record dance)
+// - processing + key: transcription is too short to interrupt, report busy
 //
-// Saying a stop phrase ("stop", "dừng lại", ...) ends the mode without
-// submitting. Empty or failed turns pause instead of auto-recording, so the
-// key never surprises.
+// The loop never reopens the mic by itself: after a reply is spoken the mode
+// rests paused, so it can never record the room while nobody is talking. That
+// auto-record is also why a question/permission gate used to eat the answer -
+// the mic opened, the user's muttering was submitted, and the real reply was
+// already torn down. Gates now announce and wait instead.
+//
+// Exit paths: a stop phrase ("stop", "dừng lại", ...), /voice-conversation-stop,
+// or the global /voice-cancel. Empty or failed turns pause instead of
+// auto-recording, so the key never surprises.
 //
 // Latency: while waiting, assistant text deltas are spoken sentence by
 // sentence (local cleanup, no LLM), so the answer starts before the turn
@@ -151,7 +160,34 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
       phase = "idle";
       stop("busy");
       toast("STT busy, conversation off", "warning");
+      return;
     }
+    toast(`Listening - press ${keyLabel()} to send`);
+  }
+
+  // The resting state: mic closed, one press to talk. Entered by start() and
+  // after a reply is spoken, never by the loop auto-recording.
+
+  function enterPaused() {
+    phase = "paused";
+    toast(`Press ${keyLabel()} to talk`);
+  }
+
+  // One press takes the floor: cut whatever audio is queued or playing, drop
+  // the pending reply, and open the mic. The mode stays on - a press always
+  // means "I want to talk now", so it must never exit silently.
+
+  function bargeIn() {
+    logger?.log("VOICE", "Conversation barge-in", "debug");
+    discardStreamAudio();
+    clearProcessingToast();
+    // Settle the pending reply wait as "stopped" so the abandoned answer is
+    // never flushed into the mic we are about to open.
+    if (waitCancel) {
+      waitCancel("stopped");
+      waitCancel = null;
+    }
+    beginTurn();
   }
 
   function endReplyStream() {
@@ -221,7 +257,7 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     const { sentences, rest } = splitSpokenSentences(streamBuffer);
     const ready = final && rest.trim() ? [...sentences, rest] : sentences;
     if (ready.length > 0 && streamSpokenChars === 0) {
-      showProcessingToast("Speaking...");
+      showProcessingToast(`Speaking - press ${keyLabel()} to interrupt`);
     }
     for (const sentence of ready) {
       if (!isSpeakableSentence(sentence)) continue;
@@ -234,9 +270,11 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
   }
 
   // Wait for the submitted turn to finish: idle, a permission/question gate,
-  // or timeout. Resolves early when stop() cancels the wait.
+  // or timeout. Resolves early when stop() cancels the wait. gates:false drops
+  // the permission/question subscriptions, so a second wait survives the gate
+  // the user is answering on screen and only ends on idle/timeout/stop.
 
-  function waitForReply(sessionID) {
+  function waitForReply(sessionID, { gates = true } = {}) {
     let settled = false;
     let unsubs = [];
     let timer = null;
@@ -276,12 +314,16 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
             finish("idle");
           }
         }),
-        api.event.on("permission.asked", (event) => {
-          if (forSession(event.properties)) finish("permission");
-        }),
-        api.event.on("question.asked", (event) => {
-          if (forSession(event.properties)) finish("question");
-        }),
+        ...(gates
+          ? [
+              api.event.on("permission.asked", (event) => {
+                if (forSession(event.properties)) finish("permission");
+              }),
+              api.event.on("question.asked", (event) => {
+                if (forSession(event.properties)) finish("question");
+              }),
+            ]
+          : []),
       ];
       timer = setTimeout(() => finish("timeout"), replyTimeoutMs);
     });
@@ -293,6 +335,7 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     if (!active || phase !== "recording") return;
     const myGen = generation;
     phase = "processing";
+    showProcessingToast("Transcribing...");
 
     const res = await stt.transcribeTurn();
     if (!active || myGen !== generation) return;
@@ -304,12 +347,12 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
         stop("error");
         return;
       }
-      pauseForRetry("Paused - press the key to retry");
+      pauseForRetry(`Paused - press ${keyLabel()} to retry`);
       return;
     }
     if (!res.text) {
       consecErrors = 0;
-      pauseForRetry("No speech heard - press the key to try again");
+      pauseForRetry(`No speech heard - press ${keyLabel()} to try again`);
       return;
     }
     consecErrors = 0;
@@ -331,7 +374,7 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     phase = "waiting";
     const sessionID = currentSessionID();
     const turnStart = Date.now();
-    showProcessingToast("Waiting for reply...");
+    showProcessingToast(`Working - press ${keyLabel()} to talk`);
     startReplyStream(sessionID, turnStart);
     const tWait = Date.now();
     const outcome = await waitForReply(sessionID);
@@ -351,46 +394,78 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
       return;
     }
     if (outcome === "permission" || outcome === "question") {
-      discardStreamAudio();
-      phase = "speaking";
-      showProcessingToast("Speaking...");
-      await tts.speak(
-        outcome === "permission"
-          ? "Permission requested. Please check your screen."
-          : "A question needs your answer. Please check your screen.",
-      );
-      clearProcessingToast();
-      if (!active || myGen !== generation || phase !== "speaking") return;
-      beginTurn();
+      await answerGateThenSpeak(myGen, sessionID, turnStart, outcome);
       return;
     }
     if (outcome === "stopped") return;
 
-    // Streamed path: sentences already queued; flush the tail and let the
-    // audio finish before listening again. Fall back to the full
-    // LLM-narrated speak only when nothing streamable arrived.
+    await speakReply(myGen);
+  }
+
+  // A permission/question gate is answered ON SCREEN, so the mic must stay
+  // shut. Announce the gate, then re-arm the reply stream and wait for the
+  // agent to resume so its post-answer reply is spoken aloud - before this,
+  // endReplyStream() had already run and the answer was dropped in silence.
 
+  async function answerGateThenSpeak(myGen, sessionID, turnStart, outcome) {
+    discardStreamAudio();
+    phase = "speaking";
+    showProcessingToast("Speaking...");
+    await tts.speak(
+      outcome === "permission"
+        ? "Permission requested. Please check your screen."
+        : "A question needs your answer. Please check your screen.",
+    );
+    clearProcessingToast();
+    if (!active || myGen !== generation || phase !== "speaking") return;
+
+    // Still "waiting": the user answers on screen, and a press here is an
+    // ordinary barge-in (drop the pending reply, open the mic).
+    phase = "waiting";
+    showProcessingToast(`Answer on screen - press ${keyLabel()} to talk`);
+    startReplyStream(sessionID, turnStart);
+    const resumed = await waitForReply(sessionID, { gates: false });
+    if (!active || myGen !== generation) return;
+    if (resumed === "stopped") return;
+    endReplyStream();
+    if (resumed === "timeout") {
+      discardStreamAudio();
+      stop("timeout");
+      toast("No reply in time, conversation off", "warning");
+      return;
+    }
+    await speakReply(myGen);
+  }
+
+  // Speak whatever this turn produced, then rest paused with the mic OFF.
+  // Streamed sentences are already queued, so only the tail needs flushing;
+  // the full LLM-narrated speak is the fallback when nothing streamable
+  // arrived. Returns early on any generation/phase change (barge-in, stop).
+
+  async function speakReply(myGen) {
+    phase = "speaking";
+    showProcessingToast(`Speaking - press ${keyLabel()} to interrupt`);
     if (streamSpokenChars > 0) {
-      phase = "speaking";
       flushStream(true);
       await speakTail;
       clearProcessingToast();
       if (!active || myGen !== generation || phase !== "speaking") return;
       await delay(restartDelayMs);
       if (!active || myGen !== generation || phase !== "speaking") return;
-      beginTurn();
+      enterPaused();
       return;
     }
-
-    phase = "speaking";
     const spoken = await tts.speakAssistantTurn();
     if (!active || myGen !== generation || phase !== "speaking") return;
+    // Drop the sticky speaking status before the paused toast, or it keeps
+    // re-announcing "interrupt" once the mic is closed again.
+    clearProcessingToast();
     if (!spoken.spoken) {
-      toast("No reply to speak, listening again", "warning");
+      toast("No reply to speak", "warning");
     }
     await delay(restartDelayMs);
     if (!active || myGen !== generation || phase !== "speaking") return;
-    beginTurn();
+    enterPaused();
   }
 
   // Pause instead of auto-recording so an empty or failed turn never feels
@@ -402,14 +477,15 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     if (message) toast(message, "warning");
   }
 
-  // Stop speech and hold the mode. The next keypress records again.
+  // Stop speech and hold the mode, mic still closed. The next keypress records
+  // again. Only the TTS stop key lands here; the conversation key barges in.
 
   function pauseSpeech() {
     if (!active || phase !== "speaking") return;
     logger?.log("VOICE", "Conversation speech paused", "debug");
     tts.stop();
     phase = "paused";
-    toast("Paused - press the key to speak");
+    toast(`Speech paused - press ${keyLabel()} to talk`);
   }
 
   // Called by the TTS stop command while the mode is on. Returns true when the
@@ -431,7 +507,10 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     return false;
   }
 
-  function onKey(source) {
+  // One press, one meaning: "I want the floor". The source key (record,
+  // submit, toggle) no longer changes the outcome, and a press never exits.
+
+  function onKey() {
     if (!active) {
       start();
       return;
@@ -440,21 +519,16 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
       finishTurnFlow();
       return;
     }
-    if (phase === "speaking") {
-      pauseSpeech();
+    if (phase === "speaking" || phase === "waiting") {
+      bargeIn();
       return;
     }
     if (phase === "paused") {
       beginTurn();
       return;
     }
-    // processing | waiting | idle
-    if (source === "toggle") {
-      stop("cancelled");
-      toast("Conversation off");
-    } else {
-      toast("Conversation busy, please wait...", "warning");
-    }
+    // processing | idle: the transcription in flight is too short to interrupt.
+    toast("Conversation busy, please wait...", "warning");
   }
 
   function start() {
@@ -471,12 +545,12 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     generation += 1;
     turn = 0;
     consecErrors = 0;
-    phase = "idle";
+    phase = "paused";
     tts.setConversationActive(true);
-    stt.setStopHint("<leader>v");
+    // Recording toasts must name the key the user actually has bound.
+    stt.setStopHint(kb("voice.conversation"));
     logger?.log("VOICE", "Conversation started", "debug");
-    toast("Conversation on - one key: send, pause speech, resume");
-    beginTurn();
+    toast(`Conversation on - press ${keyLabel()} to talk`);
   }
 
   api.lifecycle?.onDispose?.(() => stop("dispose"));
@@ -495,16 +569,24 @@ export function registerConversation(api, opts, logger, { stt, tts, isLiveNotesA
     return v;
   }
 
+  // Every toast names the key that acts, resolved from the user's keybinds
+  // instead of the default literal - a rebound key must never be announced as
+  // something the user does not have.
+  function keyLabel() {
+    return kb("voice.conversation") || "the key";
+  }
+
   const commands = [
     {
       title: "Voice: conversation mode",
       value: "voice.conversation",
       category: "opencode-voice",
-      description: "Toggle voice conversation (one key: send, pause speech, resume, exit)",
+      description:
+        "Toggle voice conversation (push-to-talk: press to record, press again to send, press while it speaks to interrupt)",
       ...(kb("voice.conversation") ? { keybind: kb("voice.conversation") } : {}),
       slash: { name: "voice-conversation" },
       onSelect() {
-        onKey("toggle");
+        onKey();
       },
     },
     {

package/lib/tts.js

@@ -6,6 +6,7 @@ import os from "node:os";
 import { spawn } from "node:child_process";
 import { getSessionTitle } from "./session.js";
 import { clearProcessingToast, showProcessingToast, updateProcessingToast } from "./stt.js";
+import { createChatterboxClient, resolveTtsEngine } from "./chatterbox-server.js";
 
 const VOICES_DIR = path.join(os.homedir(), ".local", "share", "piper-voices");
 
@@ -66,6 +67,44 @@ export function localSpeechCleanup(text) {
   return out.replace(/\s+/g, " ").trim();
 }
 
+// ---- Speech must never depend on the LLM ----
+// The narrator is a cosmetic polish layer on top of local Piper, which is
+// always available. So when the narrator fails for any reason (quota
+// exhausted, bad auth, unreachable endpoint, missing model, non-2xx) we speak
+// the deterministic local cleanup instead of going silent - this is the one
+// place the decision lives, so every caller benefits.
+//
+// Pure so it is testable without a TUI, a model, or piper.
+
+export function resolveSpeechText(rawText, llmResult) {
+  if (llmResult?.text) return { text: llmResult.text };
+  return { text: localSpeechCleanup(rawText), error: llmResult?.error, fellBack: true };
+}
+
+// The llm-client retries with backoff (normalizeRetries in llm-client.js), so a
+// model that is merely out of quota stalls for many seconds before admitting
+// failure - waiting that long for a polish layer is worse than unpolished
+// speech, so bound the wait. The timer is unref'd (same trick as
+// wallTimeout in streaming-stt.js) and cleared on the happy path, so tests and
+// short-lived processes never wait out the full bound.
+const NORMALIZE_FALLBACK_TIMEOUT_MS = 12000;
+
+async function normalizeWithinBound(promise) {
+  let timer = null;
+  const bound = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      timer = null;
+      resolve({ text: null, error: "LLM normalization timed out" });
+    }, NORMALIZE_FALLBACK_TIMEOUT_MS);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([promise, bound]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 // Split streamed text into complete spoken sentences. Returns what is ready
 // plus the trailing incomplete fragment to keep buffering. Sentences that
 // look like code dumps (overlong, backticks) are skipped by the caller.
@@ -300,14 +339,48 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     }
   }
 
+  // Spawn the sox `play` process every engine speaks through.
+  //
+  // Piper streams raw PCM, so the sample format must be declared up front.
+  // Chatterbox returns a complete WAV, which sox detects from the RIFF header -
+  // so it passes no formatArgs and we reuse this exact process rather than
+  // building a second audio pipeline.
+  function startPlayProcess(formatArgs, onDone) {
+    let playStderr = "";
+    playProc = spawn("play", [...formatArgs, "-q", "-"], {
+      stdio: ["pipe", "ignore", "pipe"],
+    });
+
+    playProc.stderr.on("data", (chunk) => {
+      playStderr += chunk.toString();
+    });
+
+    playProc.on("close", (code) => {
+      if (code !== 0 && code !== null) {
+        logger?.log?.("TTS", `play exited code=${code} stderr=${playStderr.trim()}`, "error");
+      } else {
+        logger?.log?.("TTS", "playback finished", "debug");
+      }
+      piperProc = null;
+      playProc = null;
+      onDone();
+    });
+
+    playProc.on("error", (err) => {
+      logger?.log?.("TTS", `play error: ${err.message}`, "error");
+      killProcs();
+      onDone();
+    });
+
+    return playProc;
+  }
+
   // Spawn piper -> play and wire them. Resolves onDone when playback ends.
 
   function spawnPlayback(voiceModel, onDone) {
     let piperStderr = "";
-    let playStderr = "";
     const rate = getVoiceRate(voiceModel);
-    playProc = spawn(
-      "play",
+    startPlayProcess(
       [
         "-t",
         "raw",
@@ -319,10 +392,8 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
         String(PIPER_BITS),
         "-c",
         String(PIPER_CHANNELS),
-        "-q",
-        "-",
       ],
-      { stdio: ["pipe", "ignore", "pipe"] },
+      onDone,
     );
 
     piperProc = spawn("piper", ["-m", voiceModel, "--output_raw"], {
@@ -332,9 +403,6 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     piperProc.stderr.on("data", (chunk) => {
       piperStderr += chunk.toString();
     });
-    playProc.stderr.on("data", (chunk) => {
-      playStderr += chunk.toString();
-    });
 
     piperProc.stdout.on("data", (chunk) => {
       if (playProc?.stdin && !playProc.stdin.destroyed) {
@@ -351,27 +419,20 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
       }
     });
 
-    playProc.on("close", (code) => {
-      if (code !== 0 && code !== null) {
-        logger?.log?.("TTS", `play exited code=${code} stderr=${playStderr.trim()}`, "error");
-      } else {
-        logger?.log?.("TTS", "playback finished", "debug");
-      }
-      piperProc = null;
-      playProc = null;
-      onDone();
-    });
-
     piperProc.on("error", (err) => {
       logger?.log?.("TTS", `piper error: ${err.message}`, "error");
       killProcs();
       onDone();
     });
-    playProc.on("error", (err) => {
-      logger?.log?.("TTS", `play error: ${err.message}`, "error");
-      killProcs();
-      onDone();
-    });
+  }
+
+  // Chatterbox playback: the sidecar already produced whole WAV bytes, so this
+  // is just the same play process fed the buffer and closed.
+  function spawnWavPlayback(wavBuffer, onDone) {
+    const play = startPlayProcess([], onDone);
+    if (play?.stdin && !play.stdin.destroyed) {
+      play.stdin.end(wavBuffer);
+    }
   }
 
   function resolveVoiceOrWarn(line) {
@@ -389,6 +450,82 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     return voiceModel;
   }
 
+  // ---- Optional Chatterbox engine (lib/chatterbox-server.js) ----
+  // Piper stays the default and stays the fallback: this is an opt-in quality
+  // upgrade, never a new dependency. Piper has a Vietnamese voice and is
+  // already installed; Chatterbox does not speak Vietnamese at all (its
+  // multilingual model covers 23 languages, vi is not one), so a vi utterance
+  // is routed to Piper regardless of variant - see resolveTtsEngine.
+  const createChatterbox = deps.createChatterboxClient ?? createChatterboxClient;
+  let chatterboxClient = null;
+  // Shared in-flight start so two utterances never load the model twice.
+  let chatterboxStarting = null;
+  // A synthesis that is waiting on the sidecar is still "speaking" as far as
+  // stop/isSpeaking are concerned, so a cancel lands exactly as it would on
+  // Piper's stdout stream.
+  let synthPending = false;
+  // One toast per availability state change, not one per utterance.
+  let chatterboxToastShown = false;
+
+  function chatterboxWarn(message) {
+    logger?.log?.("TTS", message, "warn");
+  }
+
+  function noteChatterboxFailure(message) {
+    logger?.log?.("TTS", message, "warn");
+    if (chatterboxToastShown) return;
+    chatterboxToastShown = true;
+    toast(`${message} - using Piper`);
+  }
+
+  // Recovering (or simply working) re-arms the toast, so a later outage is
+  // reported once again instead of staying silent for the rest of the session.
+  function noteChatterboxOk() {
+    chatterboxToastShown = false;
+  }
+
+  function getChatterboxClient() {
+    if (!chatterboxClient) {
+      chatterboxClient = createChatterbox({
+        variant: opts?.ttsChatterboxVariant,
+        python: opts?.ttsChatterboxPython,
+        voiceRef: opts?.ttsChatterboxVoiceRef,
+        logger,
+      });
+    }
+    return chatterboxClient;
+  }
+
+  // Start the sidecar lazily, on the first utterance that actually needs it.
+  // Never at plugin load: the first run downloads model weights, so eagerly
+  // loading would mean every opencode session pays for a TTS nobody asked for.
+  async function ensureChatterboxReady() {
+    if (chatterboxClient?.isRunning()) return true;
+    if (!chatterboxStarting) {
+      chatterboxStarting = getChatterboxClient()
+        .start()
+        .then((ok) => {
+          if (ok) {
+            noteChatterboxOk();
+            return true;
+          }
+          const err = chatterboxClient.getLastError?.();
+          noteChatterboxFailure(
+            `Chatterbox unavailable (${err?.code || "START_FAILED"}: ${err?.message || "unknown"})`,
+          );
+          return false;
+        })
+        .catch((err) => {
+          noteChatterboxFailure(`Chatterbox unavailable (${err.message})`);
+          return false;
+        })
+        .finally(() => {
+          chatterboxStarting = null;
+        });
+    }
+    return chatterboxStarting;
+  }
+
   function speak(text) {
     const myGen = speechGen;
     if (!text) return Promise.resolve();
@@ -397,14 +534,23 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
 
     killProcs();
 
+    const lang = detectLang(line);
+    const route = resolveTtsEngine(opts, lang, chatterboxWarn);
+    if (route.engine === "chatterbox") {
+      return speakViaChatterbox(line, lang, route.variant, myGen);
+    }
     // One voice for the whole call (see detectLang) - no mid-utterance
     // switching.
+    return speakViaPiper(line, myGen);
+  }
+
+  // Piper synthesis path, shared by the default route and by the Chatterbox
+  // fallback so both play identically.
+  function speakViaPiper(line, myGen = speechGen) {
     const voiceModel = resolveVoiceOrWarn(line);
     if (!voiceModel) return Promise.resolve();
-    // A cancel (stopSpeech) during normalization invalidates this speech.
     if (myGen !== speechGen) return Promise.resolve();
     logger?.log?.("TTS", `Speak requested chars=${line.length} voice=${voiceModel}`, "debug");
-
     return new Promise((resolve) => {
       spawnPlayback(voiceModel, resolve);
       if (piperProc?.stdin && !piperProc.stdin.destroyed) {
@@ -414,6 +560,49 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     });
   }
 
+  async function speakViaChatterbox(line, lang, variant, myGen) {
+    // Claim "speaking" for the WHOLE attempt, including the sidecar startup
+    // wait: set before the first await, so /tts-stop and the global cancel act
+    // on a Chatterbox utterance the instant it is requested.
+    synthPending = true;
+    try {
+      const ready = await ensureChatterboxReady();
+      // A cancel that landed while the sidecar was loading must not speak.
+      if (myGen !== speechGen) return;
+      if (!ready) return speakViaPiper(line, myGen);
+
+      let result;
+      try {
+        result = await getChatterboxClient().synthesize(line, lang);
+      } catch (err) {
+        // The client already returns typed errors; this only guards a thrown
+        // client bug so speech still falls back instead of rejecting.
+        result = { ok: false, code: "REQUEST_FAILED", message: err.message };
+      }
+
+      // Same generation guard as Piper: a stop during synthesis must prevent
+      // the audio from ever reaching sox.
+      if (myGen !== speechGen) return;
+      if (!result?.ok) {
+        noteChatterboxFailure(`Chatterbox synthesis failed (${result?.code}: ${result?.message})`);
+        return speakViaPiper(line, myGen);
+      }
+
+      noteChatterboxOk();
+      logger?.log?.(
+        "TTS",
+        `Speak via Chatterbox chars=${line.length} lang=${lang} variant=${variant} wavBytes=${result.wav.length}`,
+        "debug",
+      );
+      return new Promise((resolve) => {
+        spawnWavPlayback(result.wav, resolve);
+      });
+    } finally {
+      // Playback, if it started, is tracked by playProc from here on.
+      synthPending = false;
+    }
+  }
+
   // ---- Session-prefixed announcements ----
 
   async function speakWithSessionPrefix(sessionID, message, suffix) {
@@ -429,7 +618,10 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     // Always invalidate: a pending normalize handoff must not speak after
     // the cancel even when nothing is currently playing.
     speechGen += 1;
-    const wasPlaying = piperProc !== null || playProc !== null;
+    // A waiting Chatterbox synthesis counts as playing, so /tts-stop and the
+    // global cancel kill it exactly like Piper playback.
+    const wasPlaying = piperProc !== null || playProc !== null || synthPending;
+    synthPending = false;
     killProcs();
     return wasPlaying;
   }
@@ -473,14 +665,11 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
       clearProcessingToast();
       return;
     }
-    if (!llmResult.text) {
+    if (!announceNormalize("Auto", llmResult)) {
       clearProcessingToast();
-      logger?.log?.("TTS", `Auto normalization failed: ${llmResult.error}`, "warn");
-      toast(`TTS normalization failed: ${llmResult.error}`, "warning");
       return;
     }
 
-    logger?.log?.("TTS", `Auto normalization succeeded chars=${llmResult.text.length}`, "debug");
     clearProcessingToast();
     await speakWithSessionPrefix(sessionID, llmResult.text, "Ready for your input.");
   });
@@ -519,14 +708,11 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
       clearProcessingToast();
       return;
     }
-    if (!llmResult.text) {
+    if (!announceNormalize("Manual", llmResult)) {
       clearProcessingToast();
-      logger?.log?.("TTS", `Manual normalization failed: ${llmResult.error}`, "warn");
-      toast(`TTS normalization failed: ${llmResult.error}`, "warning");
       return;
     }
 
-    logger?.log?.("TTS", `Manual normalization succeeded chars=${llmResult.text.length}`, "debug");
     updateProcessingToast("Speaking...");
     await speak(llmResult.text);
     clearProcessingToast();
@@ -541,7 +727,31 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
 
   async function normalizeOrLocal(text, systemPrompt, maxTokens) {
     if (ttsLocal) return { text: localSpeechCleanup(text) };
-    return normalizeForSpeech(text, systemPrompt, maxTokens);
+    const llmResult = await normalizeWithinBound(normalizeForSpeech(text, systemPrompt, maxTokens));
+    return resolveSpeechText(text, llmResult);
+  }
+
+  // Shared tail for all three normalize call sites: one informational toast
+  // when we are speaking the local fallback, and - when the cleanup left
+  // nothing speakable (a pure code dump) - a quiet debug log, because nothing
+  // failed there, there was just nothing to read. Returns whether to speak.
+
+  function announceNormalize(label, result) {
+    if (!result.text) {
+      logger?.log?.("TTS", `${label}: nothing speakable (${result.error})`, "debug");
+      return false;
+    }
+    if (result.fellBack) {
+      logger?.log?.(
+        "TTS",
+        `${label} narration unavailable (${result.error}); speaking local cleanup`,
+        "warn",
+      );
+      toast("Model unavailable - speaking text as-is");
+      return true;
+    }
+    logger?.log?.("TTS", `${label} normalization succeeded chars=${result.text.length}`, "debug");
+    return true;
   }
 
   async function speakAssistantTurn() {
@@ -564,11 +774,9 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
       clearProcessingToast();
       return { spoken: false };
     }
-    if (!llmResult.text) {
+    if (!announceNormalize("Conversation", llmResult)) {
       clearProcessingToast();
-      logger?.log?.("TTS", `Conversation normalization failed: ${llmResult.error}`, "warn");
-      toast(`TTS normalization failed: ${llmResult.error}`, "warning");
-      return { spoken: false, error: llmResult.error };
+      return { spoken: false };
     }
 
     updateProcessingToast("Speaking...");
@@ -601,7 +809,9 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     speak: (text) => speak(text),
     speakAssistantTurn,
     stop: () => stopSpeech(),
-    isSpeaking: () => piperProc !== null || playProc !== null,
+    // A Chatterbox utterance is "speaking" from the moment it is handed to the
+    // sidecar, not only once audio reaches sox.
+    isSpeaking: () => piperProc !== null || playProc !== null || synthPending,
     setConversationActive: (v) => {
       conversationActive = !!v;
     },
@@ -610,6 +820,14 @@ export function registerTTS(api, kv, complete, prompts, opts, logger, deps = {})
     },
   };
 
+  // The Chatterbox sidecar holds a multi-hundred-MB torch model; leaving it
+  // running past the session would strand that memory. Same lifecycle hook the
+  // STT and live-notes servers use.
+  api.lifecycle?.onDispose?.(() => {
+    chatterboxClient?.stop();
+    chatterboxClient = null;
+  });
+
   // ---- Commands ----
 
   const commands = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bojackduy/opencode-voice",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Speech-to-text and text-to-speech for OpenCode. Record voice prompts with whisper-cpp, hear responses via Piper TTS, with LLM normalization through any OpenAI-compatible endpoint.",
   "keywords": [
     "opencode",