agentvibes 5.12.0-alpha.0 → 5.13.0

package/src/console/tabs/settings-tab.js

@@ -19,9 +19,11 @@ import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import {
   scanInstalledVoices, getVoiceMeta, genderIconTag, PIPER_VOICES_DIR, SAMPLE_PHRASES, parseMultiSpeaker,
 } from './voices-tab.js';
+import { voicesForProvider } from '../../services/provider-voice-catalog.js';
 import { LanguageService } from '../../services/language-service.js';
 import { SUPPORTED_LANGUAGES, t } from '../../i18n/strings.js';
 import { buildAudioEnv, detectWavPlayer, detectRemoteLlm } from '../audio-env.js';
@@ -32,7 +34,7 @@ import { PERSONALITY_EMOJIS } from '../constants/personalities.js';
 import { formatTrackName as _sharedFormatTrackName, formatReverbState as _sharedFormatReverbState } from '../widgets/format-utils.js';
 import { showNotice as _showNoticeWidget } from '../widgets/notice.js';
 import {
-  getAvailableEngines, checkEngineInstalled,
+  getAvailableEngines, getAllEngines, checkEngineInstalled, receiverProviderId,
 } from '../../services/tts-engine-service.js';
 
 const IS_TEST = process.env.AGENTVIBES_TEST_MODE === 'true';
@@ -130,6 +132,16 @@ export function createSettingsTab(screen, services) {
   // Capture cwd once at construction (matches agents-tab.js pattern)
   const _projectRoot = process.cwd();
 
+  // Preview hooks: prefer the CURRENT package copy over the project-local
+  // .claude/hooks (a tarball reinstall refreshes node_modules only, not the
+  // project's .claude), so previews never run a stale sender. CLAUDE_PROJECT_DIR
+  // still points at _projectRoot so the hook reads the project's config/provider.
+  const _pkgClaudeDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '.claude');
+  function _hookScript(subdir, name) {
+    const pkg = path.join(_pkgClaudeDir, subdir, name);
+    return fs.existsSync(pkg) ? pkg : path.join(_projectRoot, '.claude', subdir, name);
+  }
+
   // ── Container ────────────────────────────────────────────────────────────
 
   const box = blessed.box({
@@ -168,7 +180,7 @@ export function createSettingsTab(screen, services) {
           const installed = engines.find(e => checkEngineInstalled(e.id));
           return installed ? installed.name : '(none)';
         }
-        const match = getAvailableEngines().find(e => e.id === engine);
+        const match = getAllEngines().find(e => e.id === engine);
         return match ? match.name : engine;
       },
       desc: 'Global default — individual providers can override in Setup → Configure',
@@ -474,15 +486,128 @@ export function createSettingsTab(screen, services) {
 
   // ── TTS Engine editor ────────────────────────────────────────────────────
 
+  // Build actionable "how to enable" text for an engine that shows [N/A] in the
+  // picker, so the user is never left stranded not knowing what to do.
+  function _engineGuidance(engine) {
+    if (!engine) return '';
+    if (engine.requiresApiKey) {
+      const keyHint = engine.id === 'elevenlabs'
+        ? '\n  or save it to ~/.agentvibes/elevenlabs-key.txt'
+        : '';
+      return `${engine.name} needs an API key.\n\n`
+        + `Set ${engine.apiKeyEnvVar} in your shell profile${keyHint}.\n\n`
+        + `Get a free key at elevenlabs.io, then reopen this menu.`;
+    }
+    if (engine.installCmd && !/^echo /.test(engine.installCmd)) {
+      return `${engine.name} isn't installed yet.\n\nInstall it with:\n  ${engine.installCmd}\n\nThen reopen this menu.`;
+    }
+    return `${engine.name} isn't available on this system.`;
+  }
+
+  function _showEngineGuidance(engine) {
+    const text = _engineGuidance(engine);
+    if (!text) return;
+    navigationService?.openModal();
+    const lines = text.split('\n');
+    const width = Math.min(76, Math.max(44, ...lines.map(l => l.length + 4)));
+    const modal = blessed.box({
+      parent: screen,
+      top: 'center',
+      left: 'center',
+      width,
+      height: lines.length + 4,
+      border: { type: 'line' },
+      tags: true,
+      keys: true,
+      mouse: true,
+      label: ` {bold}{yellow-fg} How to enable ${engine.name} {/yellow-fg}{/bold} `,
+      content: text,
+      style: { fg: COLORS.labelFg, bg: COLORS.contentBg, border: { fg: 'yellow' } },
+    });
+    modal.setFront();
+    const close = () => {
+      navigationService?.closeModal();
+      destroyList(modal, screen);
+      box.focus();
+      screen.render();
+    };
+    modal.key(['enter', 'escape', 'q', 'space'], close);
+    modal.focus();
+    screen.render();
+  }
+
+  // Announce the chosen engine to the remote by writing receiver-provider.txt —
+  // the exact file play-tts-ssh-remote.sh reads to fill the payload's `provider`
+  // field. The receiver then honors it (or overrides with its own local config).
+  // Written to ~/.agentvibes/config/ (the sender's guaranteed fallback path).
+  function _writeReceiverProvider(engineId) {
+    const provider = receiverProviderId(engineId);
+    try {
+      const dir = path.join(os.homedir(), '.agentvibes', 'config');
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'receiver-provider.txt'), provider + '\n', 'utf8');
+    } catch (e) {
+      process.stderr.write(`[AgentVibes] could not write receiver-provider.txt: ${e.message}\n`);
+    }
+  }
+
+  // Confirm selecting an engine that can't run on THIS machine but may run on the
+  // remote receiver (remote mode only). onConfirm() runs on Yes.
+  function _confirmReceiverEngine(engine, onConfirm) {
+    navigationService?.openModal();
+    const lines = [
+      `${engine.name} can't run on this machine's OS.`,
+      '',
+      'In remote mode the receiver synthesizes the audio, so this',
+      'only works if your remote receiver supports it.',
+      '',
+      `Are you sure your receiver supports ${engine.name}?`,
+      '',
+      '  [Y] Yes, send it to the receiver     [N] Cancel',
+    ];
+    const modal = blessed.box({
+      parent: screen,
+      top: 'center',
+      left: 'center',
+      width: Math.min(70, Math.max(50, ...lines.map(l => l.length + 4))),
+      height: lines.length + 4,
+      border: { type: 'line' },
+      tags: true,
+      keys: true,
+      mouse: true,
+      label: ' {bold}{yellow-fg} Confirm remote engine {/yellow-fg}{/bold} ',
+      content: lines.join('\n'),
+      style: { fg: COLORS.labelFg, bg: COLORS.contentBg, border: { fg: 'yellow' } },
+    });
+    modal.setFront();
+    // Restore focus to whatever was focused before (the engine list) so cancel
+    // returns the user there to pick again; on confirm, onConfirm() takes over.
+    const prevFocus = screen.focused;
+    const close = (confirmed) => {
+      navigationService?.closeModal();
+      destroyList(modal, screen);
+      if (prevFocus && !prevFocus.detached) prevFocus.focus(); else box.focus();
+      screen.render();
+      if (confirmed) onConfirm();
+    };
+    modal.key(['y', 'Y', 'enter'], () => close(true));
+    modal.key(['n', 'N', 'escape', 'q'], () => close(false));
+    modal.focus();
+    screen.render();
+  }
+
   function _editTtsEngine() {
     navigationService?.openModal();
 
-    const engines = getAvailableEngines();
+    // Show ALL engines (not just the platform-available ones) so off-platform
+    // engines like Windows SAPI appear greyed "(Not supported)" instead of looking
+    // missing. `supported` marks whether the engine can run on this OS.
+    const engines = getAllEngines();
     const modal = blessed.list({
       parent: screen,
       top: 'center',
       left: 'center',
-      width: 50,
+      width: 54,
       height: engines.length + 4,
       border: { type: 'line' },
       tags: true,
@@ -500,17 +625,51 @@ export function createSettingsTab(screen, services) {
     });
     modal.setFront();
 
+    // In remote mode the receiver synthesizes, so off-platform engines (e.g.
+    // Windows SAPI on a Linux server) ARE valid choices — the selection is sent
+    // to the receiver. Locally they cannot run, so they stay greyed & blocked.
+    const _isRemote = (configService?.getConfig?.()?.audio_destination ?? 'local') === 'remote';
+
     const items = engines.map(e => {
+      if (!e.supported) {
+        if (_isRemote) {
+          // Selectable, but tag it so it's clear it runs on the receiver, not here.
+          return `{cyan-fg}  ${e.name}  (Receiver){/cyan-fg}`;
+        }
+        // Greyed, non-selectable: not runnable on this OS and no remote to send to.
+        return `{#607d8b-fg}  ${e.name}  (Not supported){/#607d8b-fg}`;
+      }
       const installed = checkEngineInstalled(e.id);
       const status = installed ? '{green-fg}[OK]{/green-fg}' : '{yellow-fg}[N/A]{/yellow-fg}';
       return `  ${e.name}  ${status}`;
     });
     modal.setItems(items);
 
+    // Commit a selection: persist the local default AND announce it to the remote.
+    const _applyEngine = (sel, showGuidance) => {
+      configService.set('ttsEngine', sel.id);
+      _writeReceiverProvider(sel.id);
+      _closeModal();
+      if (showGuidance) _showEngineGuidance(sel);
+    };
+
     modal.key(['enter'], () => {
       const sel = engines[modal.selected];
-      if (sel) configService.set('ttsEngine', sel.id);
-      _closeModal();
+      if (!sel) { _closeModal(); return; }
+      if (!sel.supported) {
+        if (!_isRemote) {
+          // No remote receiver to run it on — explain and keep the menu open.
+          _showNoticeWidget(screen, `${sel.name} is not supported on this system`);
+          return;
+        }
+        // Remote mode: confirm the receiver can run it, then send the selection.
+        _confirmReceiverEngine(sel, () => _applyEngine(sel, false));
+        return;
+      }
+      // Supported locally: [N/A] means "installable here" — offer guidance, but not
+      // in remote mode (local install is irrelevant when the receiver synthesizes).
+      const notInstalled = !checkEngineInstalled(sel.id);
+      _applyEngine(sel, notInstalled && !_isRemote);
     });
     modal.key(['escape', 'q'], _closeModal);
 
@@ -633,7 +792,17 @@ export function createSettingsTab(screen, services) {
       if (_vpClosed) return;
       const savedIdx = vpList.selected ?? 0;
       const savedScroll = vpList.childBase ?? 0;
-      _allVoices = scanInstalledVoices();
+      // Provider-aware: list the ACTIVE engine's voices, derived from the Provider
+      // Catalog (via the voicesForProvider shim) — Kokoro/ElevenLabs from the catalog,
+      // Piper from the on-disk scan, soprano its single entry. Map {id,gender} → id
+      // so the rest of this picker (which treats _allVoices as string ids) is unchanged.
+      // The active ENGINE drives which voices to list. The "Default TTS Engine"
+      // selector writes config.ttsEngine (kokoro/elevenlabs/piper/…); prefer it,
+      // then the provider, then piper. (getActiveProvider = config.provider, which
+      // can be a transport like agentvibes-receiver and isn't the engine.)
+      const _activeProvider = configService?.getConfig?.()?.ttsEngine
+        || providerService?.getActiveProvider?.() || 'piper';
+      _allVoices = voicesForProvider(_activeProvider, { scanInstalledVoices, getVoiceMeta }).map(v => v.id);
       // Sort by display name so the first-letter quick jump is intuitive
       _allVoices.sort((a, b) => getVoiceMeta(a).displayName.localeCompare(
         getVoiceMeta(b).displayName, undefined, { sensitivity: 'base' }));
@@ -651,17 +820,41 @@ export function createSettingsTab(screen, services) {
       const phrase = SAMPLE_PHRASES[Math.floor(Math.random() * SAMPLE_PHRASES.length)]; // NOSONAR
 
       if (_isWin) {
-        // Windows: route through play-tts.ps1 (same pattern as non-Windows bash route)
-        const playTtsScript = path.join(_projectRoot, '.claude', 'hooks-windows', 'play-tts.ps1');
-        if (!fs.existsSync(playTtsScript)) return;
+        // Which engine is being previewed? (Default TTS Engine selector.)
+        const _engine = configService?.getConfig?.()?.ttsEngine
+          || providerService?.getActiveProvider?.() || 'piper';
+        const _prov = receiverProviderId(_engine); // windows-sapi / piper / kokoro / …
+
+        // Windows SAPI voice names ("Microsoft David Desktop") don't auto-route, and
+        // play-tts.ps1's per-LLM engine resolution overrides -ProviderOverride back to
+        // Piper — so preview SAPI by calling its provider script DIRECTLY. Deterministic
+        // and it plays the voice (effects are skipped, which is fine for a preview).
+        // Piper/Kokoro keep the existing play-tts.ps1 path (they auto-route correctly).
+        const _directNames = _prov === 'windows-sapi'
+          ? ['play-tts-sapi.ps1', 'play-tts-windows-sapi.ps1']
+          : null;
+        let _script = null;
+        const _psArgs = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File'];
+        if (_directNames) {
+          for (const n of _directNames) {
+            const p = _hookScript('hooks-windows', n);
+            if (fs.existsSync(p)) { _script = p; break; }
+          }
+          if (_script) _psArgs.push(_script, '-Text', phrase, '-VoiceOverride', voiceId);
+        }
+        if (!_script) {
+          _script = _hookScript('hooks-windows', 'play-tts.ps1');
+          if (!fs.existsSync(_script)) return;
+          _psArgs.push(_script, phrase, voiceId);
+        }
+
         _previewVoiceId = voiceId;
         if (!_vpClosed) {
           vpPreviewLine.setContent(`{cyan-fg}♪ Playing: ${voiceId}...{/cyan-fg}`);
           _refreshVP();
         }
-        _previewProc = spawn('powershell', [ // NOSONAR
-          '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', playTtsScript, phrase, voiceId,
-        ], { stdio: 'ignore', detached: false, windowsHide: true, env: _spawnEnv });
+        _previewProc = spawn('powershell', _psArgs, // NOSONAR
+          { stdio: 'ignore', detached: false, windowsHide: true, env: _spawnEnv });
         _previewProc.on('exit', () => {
           if (_previewVoiceId === voiceId) {
             _previewVoiceId = null;
@@ -674,7 +867,7 @@ export function createSettingsTab(screen, services) {
       }
 
       // Non-Windows: use bash play-tts.sh
-      const playTtsScript = path.join(_projectRoot, '.claude', 'hooks', 'play-tts.sh');
+      const playTtsScript = _hookScript('hooks', 'play-tts.sh');
       if (!fs.existsSync(playTtsScript)) return;
 
       const remoteLlm = detectRemoteLlm();

package/src/console/tabs/setup-tab.js

@@ -46,7 +46,13 @@ import { destroyList } from '../widgets/destroy-list.js';
 import { scanInstalledVoices, getVoiceMeta, genderIconTag, formatVoiceRow, voiceRowHeader, PIPER_VOICES_DIR, SAMPLE_PHRASES, parseMultiSpeaker, getFavorites, getThumbsDown, toggleFavorite, toggleThumbsUp, toggleThumbsDown } from './voices-tab.js';
 import { attachBtnBlink } from './agents-tab.js';
 import { buildAudioEnv, detectWavPlayer } from '../audio-env.js';
+import { buildBlingCommand, playBlingCue } from '../bling.js';
 import { spawn, spawnSync } from 'node:child_process';
+
+// Re-exported for backward compatibility — buildBlingCommand moved to
+// ../bling.js so the music-preview surfaces can share it. Existing imports and
+// tests that reference it from this module keep working.
+export { buildBlingCommand };
 import os from 'node:os';
 import crypto from 'node:crypto';
 import net from 'node:net';
@@ -271,33 +277,8 @@ export function buildPyModuleCheckArgs(mods) {
   return ['-c', `import importlib.util as u, sys; sys.exit(0 if ${expr} else 1)`];
 }
 
-/**
- * Build the fire-and-forget "preview ready" cue command for a platform. Pure
- * (no spawning here, so it is unit-testable). Plays the bundled CC0 wav when
- * present, else falls back to a system sound (Windows) / freedesktop cue or
- * terminal bell (POSIX). stdio is ignored by the caller, so the POSIX bell is
- * redirected to /dev/tty rather than the discarded stdout.
- * @param {string} platform - process.platform value
- * @param {string} wavPath - absolute path to the bling wav
- * @param {boolean} haveWav - whether wavPath exists on disk
- * @returns {{command: string, args: string[]}}
- */
-export function buildBlingCommand(platform, wavPath, haveWav) {
-  if (platform === 'win32') {
-    const ps = haveWav
-      ? `Add-Type -AssemblyName System.Windows.Forms; (New-Object System.Media.SoundPlayer('${wavPath.replace(/'/g, "''")}')).PlaySync()`
-      : '[System.Media.SystemSounds]::Asterisk.Play(); Start-Sleep -Milliseconds 700';
-    return { command: 'powershell', args: ['-NoProfile', '-Command', ps] };
-  }
-  if (haveWav) {
-    // Pass wavPath as a positional arg ($1) so the path is never interpolated
-    // into the shell string (prevents injection / breakage on special chars).
-    const sh = 'paplay "$1" 2>/dev/null || aplay -q "$1" 2>/dev/null || printf "\\a" > /dev/tty 2>/dev/null';
-    return { command: 'bash', args: ['-c', sh, '--', wavPath] };
-  }
-  const sh = 'paplay /usr/share/sounds/freedesktop/stereo/message.oga 2>/dev/null || printf "\\a" > /dev/tty 2>/dev/null';
-  return { command: 'bash', args: ['-c', sh] };
-}
+// buildBlingCommand moved to ../bling.js (imported + re-exported at the top of
+// this file). See that module for the readiness-cue command builder.
 
 // ---------------------------------------------------------------------------
 // Dependency detection helpers
@@ -2852,11 +2833,21 @@ export function createSetupTab(screen, services) {
     let _kSpinInterval = null;
     let _kSpinFrame = 0;
     let _kSpinningIdx = -1;
+    let _kSpinStartTs = 0;
+    let _kFloorTimer = null;   // pending _stopKSpinnerWithFloor timer (tracked so it can be cancelled)
+    // Remote SSH preview is fire-and-forget: play-tts-ssh-remote.sh backgrounds
+    // the ssh call and exits within milliseconds, so the row spinner would be
+    // torn down before it ever paints a frame while the receiver plays the audio
+    // a beat later — the user hears sound but never sees the spinner. Hold the
+    // spinner on-screen for this minimum window so the remote path still gives a
+    // visible "preview sent" cue (fire-and-forget has no playback signal to await).
+    const _K_MIN_SPIN_MS = 1100;
 
     function _startKSpinner(listIdx) {
       _stopKSpinner();
       _kSpinningIdx = listIdx;
       _kSpinFrame = 0;
+      _kSpinStartTs = Date.now();
       _kSpinInterval = setInterval(() => {
         if (_kClosed) { _stopKSpinner(); return; }
         const spin = `{cyan-fg}${_K_SPIN[_kSpinFrame++ % _K_SPIN.length]}{/cyan-fg}`;
@@ -2866,6 +2857,9 @@ export function createSetupTab(screen, services) {
     }
 
     function _stopKSpinner() {
+      // Cancel any pending floor timer so a stale one can't fire against a newer
+      // preview's spinner (rapid Space presses) or after the picker closes.
+      if (_kFloorTimer) { clearTimeout(_kFloorTimer); _kFloorTimer = null; }
       if (_kSpinInterval) { clearInterval(_kSpinInterval); _kSpinInterval = null; }
       if (_kSpinningIdx >= 0 && !_kClosed) {
         kPicker.setItem(_kSpinningIdx, _kokoroItem(voices[_kSpinningIdx]));
@@ -2874,6 +2868,21 @@ export function createSetupTab(screen, services) {
       _kSpinningIdx = -1;
     }
 
+    // Stop the spinner but keep it on-screen for at least _K_MIN_SPIN_MS so a
+    // fire-and-forget remote send stays visible; runs `after` once the floor is
+    // met. No-ops safely if the picker closes in the meantime (_stopKSpinner and
+    // the _kClosed guard both short-circuit). Used only by the remote path — the
+    // local synth path already spins for the whole (multi-second) synthesis.
+    function _stopKSpinnerWithFloor(after) {
+      if (_kFloorTimer) { clearTimeout(_kFloorTimer); _kFloorTimer = null; }
+      const wait = Math.max(0, _K_MIN_SPIN_MS - (Date.now() - _kSpinStartTs));
+      _kFloorTimer = setTimeout(() => {
+        _kFloorTimer = null;
+        _stopKSpinner();
+        if (!_kClosed && after) after();
+      }, wait);
+    }
+
     const LEGEND_H = 3;
     const pickerH = Math.min(voices.length + LEGEND_H + 3, 24);
 
@@ -3147,14 +3156,8 @@ export function createSetupTab(screen, services) {
     // Sound: "Ui sounds - Shimmering success" by Philip_Berger, CC0 (freesound
     // #648212). See .claude/audio/ui/CREDITS.txt. Falls back to a system sound
     // if the bundled asset is ever missing.
-    const _blingWav = path.join(packageDir, '.claude', 'audio', 'ui', 'bling-success.wav');
     function _playReadyCue() {
-      try {
-        const { command, args } = buildBlingCommand(process.platform, _blingWav, fs.existsSync(_blingWav));
-        const cue = spawn(command, args, { stdio: 'ignore', detached: true }); // NOSONAR
-        cue.on('error', () => { /* best-effort cue; a spawn failure must not surface */ });
-        cue.unref();
-      } catch { /* the readiness cue is purely cosmetic — never break the preview */ }
+      playBlingCue(packageDir);
     }
 
     kPicker.key(['space'], () => {
@@ -3226,8 +3229,7 @@ export function createSetupTab(screen, services) {
         _kPreviewProc = remoteProc;
         remoteProc.on('exit', (code) => {
           _kPreviewProc = null;
-          _stopKSpinner();
-          if (_kClosed) return;
+          _stopKSpinnerWithFloor(() => {
           if (code !== 0 && _isCjkVoice(voiceId)) {
             // CJK voice failed on receiver — needs the language-specific misaki extra there.
             // Still try to download the .pt file locally so the picker shows ✓.
@@ -3272,6 +3274,7 @@ export function createSetupTab(screen, services) {
             screen.render();
             setTimeout(() => { if (!_kClosed) { kBox.setLabel(IDLE_LABEL); screen.render(); } }, 3000);
           }
+          });
         });
         remoteProc.on('error', () => {
           _kPreviewProc = null;

package/src/console/tabs/voices-tab.js

@@ -15,6 +15,40 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { buildAudioEnv, detectWavPlayer, getAllWavPlayers } from '../audio-env.js';
 import { SURNAME_POOL, uniquifyVoiceName } from '../../utils/voice-names.js';
+import { voicesForProvider, ELEVENLABS_VOICES, KOKORO_VOICE_IDS, WINDOWS_SAPI_VOICES, MACOS_VOICES, kokoroGender } from '../../services/provider-voice-catalog.js';
+import { getProvider as _catalogGetProvider } from '../../services/provider-catalog.js';
+
+/**
+ * Resolve display name / gender / provider label for a NON-Piper catalog voice
+ * (Kokoro or ElevenLabs) from the Provider Catalog SSOT. Returns null for Piper
+ * ids so getVoiceMeta falls through to its Piper resolution. This keeps the
+ * picker's labels/gender correct once non-Piper voices are listed — otherwise
+ * a raw ElevenLabs id (EXAVITQu4vr4xnSDxMaL) would render as its own name,
+ * gender '—', provider 'Piper'.
+ */
+function catalogVoiceMeta(voiceId) {
+  const el = ELEVENLABS_VOICES.find(v => v.id === voiceId);
+  if (el) return { displayName: el.name || voiceId, gender: el.gender || '—', provider: 'ElevenLabs' };
+  if (KOKORO_VOICE_IDS.includes(voiceId)) {
+    // Kokoro ids look like af_heart / am_michael; title-case for display.
+    const pretty = voiceId.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    return { displayName: pretty, gender: kokoroGender(voiceId) || '—', provider: 'Kokoro' };
+  }
+  // OS-native voices (Windows SAPI "Microsoft David Desktop", macOS "Samantha").
+  const sapi = WINDOWS_SAPI_VOICES.find(v => v.id === voiceId);
+  if (sapi) return { displayName: sapi.name, gender: sapi.gender || '—', provider: 'Windows SAPI' };
+  const mac = MACOS_VOICES.find(v => v.id === voiceId);
+  if (mac) return { displayName: mac.name, gender: mac.gender || '—', provider: 'macOS Say' };
+  // Single-voice / native providers whose voice id IS the provider id or alias
+  // (soprano, windows-sapi/sapi, macos-say/say). Without this they fall through to
+  // the Piper resolution below and get mislabeled "Piper" (the soprano bug).
+  const prov = _catalogGetProvider(voiceId);
+  if (prov && prov.engineId !== 'piper') {
+    const label = prov.displayName.replace(/\s+TTS$/, '');
+    return { displayName: label, gender: '—', provider: label };
+  }
+  return null;
+}
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -603,6 +637,12 @@ export function getVoiceMeta(voiceId) {
   // Lazy-load the catalog so callers from any tab get uniquified names
   loadCatalog();
 
+  // Non-Piper catalog voices (Kokoro / ElevenLabs) resolve from the Provider
+  // Catalog SSOT — real name, real gender, correct provider label — before the
+  // Piper-only paths below (which would mislabel them).
+  const nonPiper = catalogVoiceMeta(voiceId);
+  if (nonPiper) { _metaCache.set(voiceId, nonPiper); return nonPiper; }
+
   const ms = parseMultiSpeaker(voiceId);
   if (ms.isMultiSpeaker) {
     if (!ms.speakerName) {
@@ -967,19 +1007,35 @@ export function createVoicesTab(screen, services) {
     // NOTE: projectRoot is AgentVibes repo root (3 levels up from src/console/tabs/)
     const projectRoot = path.resolve(__dirname, '..', '..', '..');
     let activeProvider = '';
+    // Capture the dir the provider was read from so we can forward it to
+    // play-tts.sh as --project-dir. Without it the script re-resolves the
+    // provider from its OWN cwd/package .claude (which has no tts-provider.txt),
+    // falls back to piper-local, and synthesizes to a silent local device on a
+    // headless/remote box — i.e. the preview appears to do nothing. Passing the
+    // exact dir we matched keeps the JS check and the shell routing in agreement.
+    let activeProjectDir = '';
     try {
-      const providerPaths = [
-        process.env.CLAUDE_PROJECT_DIR && path.join(process.env.CLAUDE_PROJECT_DIR, '.claude', 'tts-provider.txt'),
-        path.join(process.cwd(), '.claude', 'tts-provider.txt'),
-        path.join(projectRoot, '.claude', 'tts-provider.txt'),
-        path.join(os.homedir(), '.claude', 'tts-provider.txt'),
+      const providerDirs = [
+        process.env.CLAUDE_PROJECT_DIR,
+        process.cwd(),
+        projectRoot,
+        os.homedir(),
       ].filter(Boolean);
-      for (const p of providerPaths) {
-        if (fs.existsSync(p)) { activeProvider = fs.readFileSync(p, 'utf8').trim(); break; }
+      for (const d of providerDirs) {
+        const p = path.join(d, '.claude', 'tts-provider.txt');
+        if (fs.existsSync(p)) { activeProvider = fs.readFileSync(p, 'utf8').trim(); activeProjectDir = d; break; }
       }
     } catch {}
 
-    if (_remoteProviders.includes(activeProvider)) {
+    // Route through the engine-aware play-tts for ANY non-Piper provider — remote
+    // transports (ssh-remote / agentvibes-receiver) AND local non-Piper engines
+    // (kokoro / elevenlabs / soprano / macos). Only Piper (and unset = default)
+    // uses the fast local piper path below; play-tts.sh/.ps1 dispatches to the
+    // correct engine so Kokoro/ElevenLabs previews actually synthesize instead of
+    // erroring against a nonexistent <id>.onnx piper model.
+    const _isPiperLocal = (activeProvider === '' || activeProvider === 'piper' || activeProvider === 'windows-piper');
+    if (!_isPiperLocal) {
+      const _remote = _remoteProviders.includes(activeProvider);
       const isWindows = process.platform === 'win32' && !process.env.WSL_DISTRO_NAME;
       const phrase = `Hi, my name is ${getVoiceMeta(voiceId).displayName}.`;
       // Hooks live in the AgentVibes package (projectRoot), not the user's project dir.
@@ -994,12 +1050,14 @@ export function createVoicesTab(screen, services) {
       let proc;
       if (isWindows) {
         const playTts = path.join(hooksBase, '.claude', 'hooks-windows', 'play-tts.ps1');
-        proc = spawn('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', playTts, phrase, voiceId], { // NOSONAR
+        const _pdArgs = activeProjectDir ? ['-ProjectDir', activeProjectDir] : [];
+        proc = spawn('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', playTts, phrase, voiceId, ..._pdArgs], { // NOSONAR
           stdio: 'ignore', detached: false, windowsHide: true, env: _spawnEnv,
         });
       } else {
         const playTts = path.join(hooksBase, '.claude', 'hooks', 'play-tts.sh');
-        proc = spawn('bash', [playTts, phrase, voiceId], { // NOSONAR
+        const _pdArgs = activeProjectDir ? ['--project-dir', activeProjectDir] : [];
+        proc = spawn('bash', [playTts, phrase, voiceId, ..._pdArgs], { // NOSONAR
           stdio: ['ignore', 'ignore', 'pipe'], detached: true, env: _spawnEnv,
           cwd: process.cwd(),
         });
@@ -1007,7 +1065,7 @@ export function createVoicesTab(screen, services) {
       _playingProcess = proc;
       _playingVoiceId = voiceId;
       refreshDisplay();
-      previewLine.setContent('{bright-magenta-fg}♪ Synthesizing on remote...{/bright-magenta-fg}');
+      previewLine.setContent(`{bright-magenta-fg}♪ Synthesizing${_remote ? ' on remote' : ''}...{/bright-magenta-fg}`);
       screen.render();
       let _stderrBuf = '';
       if (proc.stderr) {
@@ -1678,10 +1736,16 @@ export function createVoicesTab(screen, services) {
       // genderIconTag has invisible color tags — pad with literal spaces (1 visible char + 3 spaces = 4)
       const gIcon = genderIconTag(gender);
       if (!installed) {
-        // Greyed-out row for uninstalled catalog voices — close grey wrap around the icon so its colors show
-        return `{bright-black-fg} ${star}  ${name}{/bright-black-fg}${gIcon}   {bright-black-fg}${provider}{/bright-black-fg}`;
+        // Greyed-out row for uninstalled catalog voices. Use a mid blue-grey (not
+        // bright-black) so the row stays legible when selected — bright-black on the
+        // green selection bg is unreadable. Close the grey wrap around the icon so
+        // its own colors show.
+        return `{#90a4ae-fg} ${star}  ${name}{/#90a4ae-fg}${gIcon}   {#90a4ae-fg}${provider}{/#90a4ae-fg}`;
       }
-      return `{${COLORS.labelFg}-fg} ${star}${dot} ${name}{/${COLORS.labelFg}-fg}${gIcon}   {${COLORS.labelFg}-fg}${provider}${isPrev ? ` ${_tl('voicePlaying')}` : ''}{/${COLORS.labelFg}-fg}`;
+      // No fg wrap on the name/provider: unselected rows inherit the list's item.fg
+      // (labelFg); the selected row inherits selected.fg (#ffffff bold) so the
+      // highlight is white-on-green and readable, instead of pale text on green.
+      return ` ${star}${dot} ${name}${gIcon}   ${provider}${isPrev ? ` ${_tl('voicePlaying')}` : ''}`;
     });
   }
 
@@ -1732,15 +1796,30 @@ export function createVoicesTab(screen, services) {
       _metaCache.clear();
     }
 
-    // Installed voices (from local disk)
-    const installed = scanInstalledVoices();
-    _installedSet = new Set(installed);
-
-    // Merge: installed voices first, then uninstalled catalog voices
-    const catalogOnly = _catalogEntries
-      .filter(c => !_installedSet.has(c.voiceId))
-      .map(c => c.voiceId);
-    _allVoices = [...installed, ...catalogOnly];
+    // Provider-aware voice list. Piper (disk-discovered) keeps the installer
+    // behavior — installed voices plus uninstalled catalog voices to download.
+    // For Kokoro/ElevenLabs/soprano the voices come from the Provider Catalog
+    // (via voicesForProvider) and are all available (nothing to "install"), so
+    // mark them installed to suppress the download UI.
+    // Prefer the explicitly-chosen Default TTS Engine (config.ttsEngine) over the
+    // provider (which may be a transport like agentvibes-receiver, not an engine).
+    const _vtProvider = configService?.getConfig?.()?.ttsEngine
+      || providerService?.getActiveProvider?.() || 'piper';
+    const _vtIsDisk = (_vtProvider === 'piper' || _vtProvider === 'windows-piper');
+    if (_vtIsDisk) {
+      // Installed voices (from local disk)
+      const installed = scanInstalledVoices();
+      _installedSet = new Set(installed);
+
+      // Merge: installed voices first, then uninstalled catalog voices
+      const catalogOnly = _catalogEntries
+        .filter(c => !_installedSet.has(c.voiceId))
+        .map(c => c.voiceId);
+      _allVoices = [...installed, ...catalogOnly];
+    } else {
+      _allVoices = voicesForProvider(_vtProvider, { scanInstalledVoices, getVoiceMeta }).map(v => v.id);
+      _installedSet = new Set(_allVoices);
+    }
 
     const active = providerService.getActiveVoiceId();
     const favorites = getFavorites(configService);