agentvibes 5.12.0 → 5.13.1

package/src/console/bling.js

@@ -0,0 +1,71 @@
+/**
+ * AgentVibes — Shared "bling" readiness cue.
+ *
+ * A short, fire-and-forget chime played the instant a preview is committed, so
+ * silence during synthesis / an SSH round-trip never reads as a hang. Used by
+ * BOTH the voice picker (setup-tab.js) and the music-preview surfaces
+ * (music-tab.js, track-picker.js) so they can't drift.
+ *
+ * `buildBlingCommand` was originally defined in setup-tab.js; it was moved here
+ * and is re-exported from setup-tab.js for backward compatibility (existing
+ * imports and tests keep working).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+/**
+ * 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] };
+}
+
+/**
+ * Resolve the bundled CC0 bling wav for a package root.
+ * Sound: "Ui sounds - Shimmering success" by Philip_Berger, CC0 (freesound
+ * #648212). See .claude/audio/ui/CREDITS.txt.
+ * @param {string} packageRoot - AgentVibes package/repo root
+ * @returns {string}
+ */
+export function resolveBlingWav(packageRoot) {
+  return path.join(packageRoot, '.claude', 'audio', 'ui', 'bling-success.wav');
+}
+
+/**
+ * Play the readiness cue, fire-and-forget. Detached + unref'd + errors
+ * swallowed, so it never blocks the UI or fails a preview. A missing wav falls
+ * back to a platform system sound via buildBlingCommand.
+ * @param {string} packageRoot - AgentVibes package/repo root
+ */
+export function playBlingCue(packageRoot) {
+  try {
+    const wav = resolveBlingWav(packageRoot);
+    const { command, args } = buildBlingCommand(process.platform, wav, fs.existsSync(wav));
+    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 */ }
+}

package/src/console/music-preview.js

@@ -0,0 +1,79 @@
+/**
+ * AgentVibes — Shared music-preview transport helpers.
+ *
+ * Both music-preview surfaces (the Music tab and the track-picker widget) must
+ * make the same remote-vs-local decision: a transport provider routes audio to
+ * a remote receiver, so a local MP3 preview would be silent on a headless box
+ * and must be forwarded instead. This module holds the provider-resolve and the
+ * remote-forward spawn so the two surfaces can't drift.
+ *
+ * The caller owns UI feedback (status text, error messages) and attaches its own
+ * exit/error/stderr handlers to the returned child process.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+
+// Transport providers route audio to a remote receiver; local MP3 playback is
+// silent on a headless/remote box, so track previews must be forwarded instead.
+export const REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
+
+/**
+ * Resolve the active provider and the project dir it was read from, using the
+ * same search order as the voice pickers (CLAUDE_PROJECT_DIR → cwd → package →
+ * home). Returns { remote, projectDir } so a remote preview can forward the
+ * track to the receiver and tell the sender which .claude dir to resolve.
+ * @param {string} packageRoot - AgentVibes package/repo root (package fallback)
+ * @returns {{ remote: boolean, projectDir: string }}
+ */
+export function resolveMusicProvider(packageRoot) {
+  const dirs = [process.env.CLAUDE_PROJECT_DIR, process.cwd(), packageRoot, os.homedir()].filter(Boolean);
+  for (const d of dirs) {
+    const p = path.join(d, '.claude', 'tts-provider.txt');
+    try {
+      if (fs.existsSync(p)) {
+        const provider = fs.readFileSync(p, 'utf8').trim();
+        return { remote: REMOTE_PROVIDERS.includes(provider), projectDir: d };
+      }
+    } catch { /* next */ }
+  }
+  return { remote: false, projectDir: '' };
+}
+
+/**
+ * Resolve the SSH sender script path, preferring the package-bundled copy and
+ * falling back to the project's .claude/hooks copy.
+ * @param {string} packageRoot
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveRemoteSender(packageRoot, projectDir) {
+  const pkgSender = path.resolve(packageRoot, '.claude', 'hooks', 'play-tts-ssh-remote.sh');
+  return fs.existsSync(pkgSender)
+    ? pkgSender
+    : path.join(projectDir, '.claude', 'hooks', 'play-tts-ssh-remote.sh');
+}
+
+/**
+ * Spawn the SSH sender to forward a music track to the receiver, or stop the
+ * current one. Fire-and-forget (the sender exits after handing the payload to
+ * SSH; the receiver plays/stops asynchronously). Returns the child process so
+ * the caller can wire its own exit/error/stderr handlers for UI feedback.
+ *
+ * @param {object} opts
+ * @param {string} opts.packageRoot
+ * @param {string} opts.projectDir
+ * @param {object} opts.env         - base spawn env (e.g. buildAudioEnv())
+ * @param {string} [opts.track]     - track filename to play (ignored when stop)
+ * @param {boolean} [opts.stop]     - send an explicit music-stop signal instead
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnMusicRemote({ packageRoot, projectDir, env, track = null, stop = false }) {
+  const senderPath = resolveRemoteSender(packageRoot, projectDir);
+  const spawnEnv = { ...env, CLAUDE_PROJECT_DIR: projectDir };
+  if (stop) spawnEnv.AGENTVIBES_MUSIC_STOP = '1';
+  else spawnEnv.AGENTVIBES_MUSIC_ONLY = track;
+  return spawn('bash', [senderPath, '', ''], { stdio: ['ignore', 'ignore', 'pipe'], detached: true, env: spawnEnv }); // NOSONAR
+}

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

@@ -11,43 +11,20 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
-import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { buildAudioEnv, spawnMp3Player } from '../audio-env.js';
+import { resolveMusicProvider, spawnMusicRemote } from '../music-preview.js';
+import { playBlingCue } from '../bling.js';
 import { t } from '../../i18n/strings.js';
 
 const _MUSIC_TAB_DIR = path.dirname(fileURLToPath(import.meta.url));
 
-// Package-relative tracks dir — used as fallback when cwd has no .claude/audio/tracks/
-const _PKG_TRACKS_DIR = path.resolve(
-  _MUSIC_TAB_DIR, '..', '..', '..', '.claude', 'audio', 'tracks'
-);
-
-// Transport providers route audio to a remote receiver; local MP3 playback is
-// silent on a headless/remote box, so track previews must be forwarded instead.
-const _REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
+// AgentVibes package/repo root — used to resolve bundled assets (tracks dir,
+// bling cue) and as the package fallback when resolving the active provider.
+const _PKG_ROOT = path.resolve(_MUSIC_TAB_DIR, '..', '..', '..');
 
-/**
- * Resolve the active provider and the project dir it was read from, using the
- * same search order as the voice pickers (CLAUDE_PROJECT_DIR → cwd → package →
- * home). Returns { remote, projectDir } so a remote preview can forward the
- * track to the receiver and tell the sender which .claude dir to resolve.
- */
-function _resolveMusicProvider() {
-  const projectRoot = path.resolve(_MUSIC_TAB_DIR, '..', '..', '..');
-  const dirs = [process.env.CLAUDE_PROJECT_DIR, process.cwd(), projectRoot, os.homedir()].filter(Boolean);
-  for (const d of dirs) {
-    const p = path.join(d, '.claude', 'tts-provider.txt');
-    try {
-      if (fs.existsSync(p)) {
-        const provider = fs.readFileSync(p, 'utf8').trim();
-        return { remote: _REMOTE_PROVIDERS.includes(provider), projectDir: d };
-      }
-    } catch { /* next */ }
-  }
-  return { remote: false, projectDir: '' };
-}
+// Package-relative tracks dir — used as fallback when cwd has no .claude/audio/tracks/
+const _PKG_TRACKS_DIR = path.join(_PKG_ROOT, '.claude', 'audio', 'tracks');
 
 const IS_TEST = process.env.AGENTVIBES_TEST_MODE === 'true';
 
@@ -591,16 +568,9 @@ export function createMusicTab(screen, services) {
    * @param {{track?:string, stop?:boolean}} opts
    */
   function _sendMusicRemote(mp, { track = null, stop = false } = {}) {
-    const _pkgSender = path.resolve(_MUSIC_TAB_DIR, '..', '..', '..', '.claude', 'hooks', 'play-tts-ssh-remote.sh');
-    const senderPath = fs.existsSync(_pkgSender)
-      ? _pkgSender
-      : path.join(mp.projectDir, '.claude', 'hooks', 'play-tts-ssh-remote.sh');
-    const env = { ..._spawnEnv, CLAUDE_PROJECT_DIR: mp.projectDir };
-    if (stop) env.AGENTVIBES_MUSIC_STOP = '1';
-    else env.AGENTVIBES_MUSIC_ONLY = track;
     let rproc;
     try {
-      rproc = spawn('bash', [senderPath, '', ''], { stdio: ['ignore', 'ignore', 'pipe'], detached: true, env }); // NOSONAR
+      rproc = spawnMusicRemote({ packageRoot: _PKG_ROOT, projectDir: mp.projectDir, env: _spawnEnv, track, stop });
     } catch {
       previewLine.setContent('{red-fg}Remote music preview failed{/red-fg}');
       screen.render();
@@ -646,7 +616,7 @@ export function createMusicTab(screen, services) {
     // is silent on a headless box). The receiver auto-stops any prior track when
     // a new one arrives; pressing Space on the currently-playing track sends an
     // explicit stop (toggle off).
-    const _mp = _resolveMusicProvider();
+    const _mp = resolveMusicProvider(_PKG_ROOT);
     if (_mp.remote) {
       if (_remotePlayingTrackId === trackId) {
         _sendMusicRemote(_mp, { stop: true });
@@ -655,6 +625,9 @@ export function createMusicTab(screen, services) {
         screen.render();
         return;
       }
+      // Bling first (fire-and-forget, plays locally) — same readiness cue as the
+      // voice preview — then forward the track to the receiver.
+      playBlingCue(_PKG_ROOT);
       const rlabel = _allTracks.find(t => t.id === trackId)?.label ?? formatTrackLabel(trackId);
       if (_sendMusicRemote(_mp, { track: trackId })) {
         _remotePlayingTrackId = trackId;
@@ -678,6 +651,10 @@ export function createMusicTab(screen, services) {
     _killPlayingProcess();
     _playingTrackId = null;
 
+    // Bling first (fire-and-forget) — same readiness cue as the voice preview —
+    // then start local playback.
+    playBlingCue(_PKG_ROOT);
+
     const proc = spawnMp3Player(trackPath, _spawnEnv);
     if (!proc) {
       const installHint = process.platform === 'win32'

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

@@ -23,6 +23,7 @@ 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';
@@ -33,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';
@@ -179,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',
@@ -485,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,
@@ -511,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);
 
@@ -644,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' }));
@@ -662,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 = _hookScript('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;

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
@@ -3175,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'], () => {