agentvibes 5.15.0 → 5.15.2

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260720
+20260721

package/README.md

@@ -58,7 +58,19 @@ New here? The [**Quick Start guide**](docs/quick-start.md) walks you through you
 
 ---
 
-## 🆕 Multi-session control on Windows (v5.15.0)
+## 🆕 Fixes for the preview indicators (v5.15.2)
+
+- **Fixed a TUI crash** — filtering/favoriting a track while a preview was playing could rebuild the list under the indicator and crash; it can't now.
+- **Honest per-agent badge** — the voice picker shows **(remotely via SSH)** vs **(locally)** from your real routing, not a partial guess.
+- **BMAD agents show their real names** (Mary, Winston…) even when a skill file lacks the `Name — Title` heading; plus small preview/onboarding polish.
+
+### v5.15.1 — Know where your preview plays
+
+- **Every preview shows where it plays** — voice and music previews now display **(locally)** or **(remotely via SSH)** right on the row you're auditioning, so you're never guessing (or hearing silence on a headless box).
+- **Preview standardized across the app** — the voice pickers (Kokoro, Piper, ElevenLabs, per-agent BMAD) and the Music page all show the same indicator; music previews now follow a project's remote receiver too.
+- **Cleaner Agents tab** — it lists your real BMAD agents (not a skill's internal helpers) and re-checks itself on focus; **Reset** moved off `X` (which jumped to the Receiver tab) to **`Del`**.
+
+### v5.15.0 — Multi-session control on Windows
 
 - **Sessions stay quiet unless you enable them** — a session speaks only in a project you've turned on; others add no instructions and no token cost.
 - **`/agent-vibes:mute` now works on Windows** — it previously had no effect there. Both project and global mute are honoured on every platform.
@@ -266,7 +278,7 @@ anything (no new network calls, no behavior change) for every current install.
 
 ## About
 
-**AgentVibes** · v5.15.0 · Licensed under [Apache-2.0](LICENSE)
+**AgentVibes** · v5.15.2 · Licensed under [Apache-2.0](LICENSE)
 
 Built by **Paul Preibisch** — [@997Fire on X](https://x.com/997Fire) · [agentvibes.org](https://agentvibes.org) · [github.com/paulpreibisch/AgentVibes](https://github.com/paulpreibisch/AgentVibes)
 

package/RELEASE_NOTES.md

@@ -1,5 +1,56 @@
 # AgentVibes Release Notes
 
+## v5.15.2 — Fixes for the preview indicators
+
+**Released:** 2026-07-22 · `npm install agentvibes@latest`
+
+Follow-up fixes for the 5.15.1 preview work, from an adversarial code review:
+
+- **Fixed a crash** — filtering or favoriting a track *while a preview was
+  playing* could rebuild the list out from under the indicator and take the whole
+  TUI down. It can't anymore.
+- **The badge tells the truth** — the per-agent voice picker now shows
+  **(remotely via SSH)** vs **(locally)** based on your actual routing (provider
+  file or remote receiver), not a partial guess.
+- **Your BMAD agents show their real names** — the Agents tab reads the persona
+  name (Mary, Winston, Amelia…) even on installs whose skill files don't use the
+  `Name — Title` heading format.
+- **Smaller polish** — a remote voice-preview error no longer leaves a stuck
+  spinner, the onboarding "re-check" hint is translated in all languages, and the
+  onboarding screen keeps keyboard focus after a re-check.
+
+## v5.15.1 — Know where your preview plays
+
+**Released:** 2026-07-21 · `npm install agentvibes@latest`
+
+Here's the thing we kept running into: when you press Space to preview a voice
+or a music track, there was no way to tell whether it was about to play *on your
+own machine* or get sent *to your remote receiver*. On a headless box that meant
+pressing preview and hearing… nothing — with no idea why.
+
+So we fixed it. Every preview now tells you exactly where the sound is going —
+**(locally)** or **(remotely via SSH)** — right on the row you're auditioning.
+No more guessing.
+
+And while we were in there, we **standardized preview across the whole app**.
+The voice pickers (Kokoro, Piper, ElevenLabs, and per-agent BMAD voices) and the
+Music page now all show the same `Previewing (locally / remotely via SSH)`
+indicator, so it looks and behaves identically everywhere. It's a small thing
+that turns out to be genuinely useful.
+
+One practical upshot: if a project routes its TTS to a remote receiver, **music
+previews now follow it too** — before, they quietly played on the local machine,
+which is silence on a headless server.
+
+### Also in this release
+
+- **The Agents tab shows your real BMAD agents** (Mary, Winston, Amelia, John,
+  Paige, Sally…) instead of a skill's internal helpers — and it re-checks itself
+  when you switch back to the tab, so a fresh BMAD install shows up without a
+  restart.
+- **Reset no longer yanks you to the Receiver tab.** It was mapped to `X`, the
+  same key that globally jumps to Receiver; it's now `Del`.
+
 ## v5.15.0 — Multi-session control on Windows
 
 **Released:** 2026-07-20 · `npm install agentvibes@latest`

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.15.0",
+  "version": "5.15.2",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/src/console/footer-config.js

@@ -33,7 +33,7 @@ export const FOOTER_CONFIG = {
   },
   agents: {
     color: '#9c27b0',
-    text: ` ${key('↑↓')} Navigate  ${key('Enter')} Edit Agent  ${key('Space')} Sample  ${key('R')} Reset`,
+    text: ` ${key('↑↓')} Navigate  ${key('Enter')} Edit Agent  ${key('Space')} Sample  ${key('Del')} Reset`,
   },
   receiver: {
     color: '#00897b',

package/src/console/music-preview.js

@@ -15,11 +15,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
+import { detectRemoteLlm } from './audio-env.js';
 
 // 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'];
 
+// Preview transport badge + row spinner live in the neutral preview-transport
+// module (shared with the voice pickers). Re-exported here for the music
+// surfaces that already import from music-preview.js.
+export { transportBadge, createRowSpinner, previewRowContent, SPIN_FRAMES } from './preview-transport.js';
+
 /**
  * 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 →
@@ -30,16 +36,26 @@ export const REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
  */
 export function resolveMusicProvider(packageRoot) {
   const dirs = [process.env.CLAUDE_PROJECT_DIR, process.cwd(), packageRoot, os.homedir()].filter(Boolean);
+
+  // A configured remote TTS transport (transport-config.json mode=remote) routes
+  // audio to a receiver, so a LOCAL music preview would be silent on this box —
+  // forward it too, matching the voice preview. This is a SEPARATE signal from
+  // the provider file: a project can carry tts-provider.txt=piper (local) while
+  // the global transport routes TTS to a remote receiver, and the two surfaces
+  // must agree or the picker plays to an inaudible local sink.
+  const transportRemote = !!detectRemoteLlm();
+
   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 };
+        return { remote: REMOTE_PROVIDERS.includes(provider) || transportRemote, projectDir: d };
       }
     } catch { /* next */ }
   }
-  return { remote: false, projectDir: '' };
+  // No provider file found anywhere — still forward if a remote transport is set.
+  return { remote: transportRemote, projectDir: process.env.CLAUDE_PROJECT_DIR || process.cwd() };
 }
 
 /**

package/src/console/preview-transport.js

@@ -0,0 +1,147 @@
+/**
+ * AgentVibes — Shared preview transport badge + row spinner.
+ *
+ * Every music & voice preview surface renders an identical "previewing" cue ON
+ * THE SELECTED ROW (not a separate bottom line), so the user always sees where a
+ * preview is going and can stop it:
+ *
+ *   ⠹ Previewing (locally)            (Space to stop)   — green, plays here
+ *   ⠹ Previewing (remotely via SSH)   (Space to stop)   — red, forwarded to receiver
+ *
+ * The item name is intentionally omitted — the animated row IS the selected item.
+ * Kept in one neutral module so music and voice pickers can't drift.
+ */
+
+/** Braille spinner frames, shared by every preview surface. */
+export const SPIN_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/**
+ * Color-coded transport badge shown right after "Previewing".
+ * @param {boolean} remote - true when forwarded to the SSH receiver
+ * @returns {string} blessed-tagged badge, e.g. "{red-fg}(remotely via SSH){/red-fg}"
+ */
+export function transportBadge(remote) {
+  return remote
+    ? '{red-fg}(remotely via SSH){/red-fg}'
+    : '{green-fg}(locally){/green-fg}';
+}
+
+/**
+ * Right-pad a blessed-tagged string with spaces to a target VISIBLE width, so a
+ * shorter row fully overwrites a longer previous row (blessed's list.setItem does
+ * not clear leftover cells → the old tail ghosts through). Color tags don't count
+ * toward width. Over-padding is safe: a non-wrapping list clips the overflow.
+ * @param {string} tagged
+ * @param {number} width - target visible width (e.g. the list's outer width)
+ * @returns {string}
+ */
+export function padTaggedTo(tagged, width) {
+  if (!width || width <= 0) return tagged;
+  const visible = tagged.replace(/\{[^}]*\}/g, '');
+  const pad = width - visible.length;
+  return pad > 0 ? tagged + ' '.repeat(pad) : tagged;
+}
+
+/**
+ * The full "previewing" row content (spinner frame + Previewing + badge + hint).
+ * @param {string} frameChar - one SPIN_FRAMES glyph
+ * @param {boolean} remote
+ * @param {string} [stopHint]
+ * @returns {string} blessed-tagged row content
+ */
+export function previewRowContent(frameChar, remote, stopHint = 'Space to stop') {
+  return `{cyan-fg}${frameChar} Previewing {/cyan-fg}${transportBadge(remote)}{cyan-fg}  (${stopHint}){/cyan-fg}`;
+}
+
+/**
+ * Attach an animated preview indicator to the SELECTED row of a blessed list.
+ * Generalizes the Kokoro picker's row spinner so every picker behaves identically.
+ *
+ * @param {object}   list        - blessed list (needs setItem(idx, str))
+ * @param {object}   screen      - blessed screen (needs render())
+ * @param {(idx:number)=>string} renderItem - returns a row's normal content (to restore on stop)
+ * @param {object}   [opts]
+ * @param {()=>boolean} [opts.isClosed] - guard: true once the picker is torn down
+ * @param {()=>number}  [opts.now]      - clock (ms); injectable for tests
+ * @param {number}   [opts.intervalMs]  - frame interval (default 80)
+ * @param {number}   [opts.minVisibleMs]- min on-screen window for fire-and-forget remote (default 1100)
+ * @returns {{ start:Function, stop:Function, stopWithFloor:Function, isActive:Function, activeIdx:Function }}
+ */
+export function createRowSpinner(list, screen, renderItem, opts = {}) {
+  const isClosed = opts.isClosed ?? (() => false);
+  const now = opts.now ?? (() => Date.now());
+  const intervalMs = opts.intervalMs ?? 80;
+  const minVisibleMs = opts.minVisibleMs ?? 1100;
+  // isStatic: write the indicator ONCE (no animation). Used for lists with
+  // double-width emoji (the Music tab): repeated in-place mutation of emoji rows
+  // desyncs blessed's terminal output. One write + full-width space padding is
+  // the least-fragile option there. A frozen "♪" stands in for the spinner.
+  const isStatic = opts.static ?? false;
+
+  let timer = null;
+  let floor = null;
+  let frame = 0;
+  let idx = -1;
+  let remote = false;
+  let startTs = 0;
+
+  // Guard: blessed's List.setItem dereferences this.items[i] unchecked, so a
+  // stale idx (e.g. the list was rebuilt shorter by a filter while a preview was
+  // active) would throw an uncaught TypeError and kill the whole TUI. Only touch
+  // a row that still exists. list.items is an array on a real list; the test stub
+  // uses a plain object, so treat "not an array" as always-in-range.
+  function _inRange(i) {
+    if (i < 0) return false;
+    return Array.isArray(list.items) ? i < list.items.length : true;
+  }
+
+  function _paint() {
+    if (!_inRange(idx)) return;
+    // Pad to the widest reliable measure so the row fully overwrites the previous
+    // (longer) content. list.width may still be a percentage string pre-layout, so
+    // fall back to the screen width; over-padding is clipped by the non-wrapping list.
+    const lw = (typeof list.width === 'number' && list.width > 0) ? list.width : 0;
+    const sw = (screen && typeof screen.width === 'number' && screen.width > 0) ? screen.width : 0;
+    const w = Math.max(lw, sw, 80);
+    const spin = isStatic ? '♪' : SPIN_FRAMES[frame++ % SPIN_FRAMES.length];
+    list.setItem(idx, padTaggedTo(previewRowContent(spin, remote), w));
+    screen.render();
+  }
+
+  function stop() {
+    if (floor) { clearTimeout(floor); floor = null; }
+    if (timer) { clearInterval(timer); timer = null; }
+    if (_inRange(idx) && !isClosed()) {
+      list.setItem(idx, renderItem(idx));
+      screen.render();
+    }
+    idx = -1;
+  }
+
+  return {
+    start(rowIdx, isRemote) {
+      stop();
+      idx = rowIdx;
+      frame = 0;
+      remote = !!isRemote;
+      startTs = now();
+      _paint();
+      if (isStatic) return; // static indicator: written once, no animation loop
+      timer = setInterval(() => { if (isClosed()) { stop(); return; } _paint(); }, intervalMs);
+      // A UI spinner must never keep the process alive (blessed's stdin does that
+      // in the real TUI); unref so a leaked spinner can't hang node --test on exit.
+      if (timer.unref) timer.unref();
+    },
+    // Fire-and-forget remote sends exit in ms; keep the row visible ≥ minVisibleMs
+    // so the user still sees a "preview sent" cue, then restore and run `after`.
+    stopWithFloor(after) {
+      if (floor) { clearTimeout(floor); floor = null; }
+      const wait = Math.max(0, minVisibleMs - (now() - startTs));
+      floor = setTimeout(() => { floor = null; stop(); if (!isClosed() && after) after(); }, wait);
+      if (floor.unref) floor.unref();
+    },
+    stop,
+    isActive: () => idx >= 0,
+    activeIdx: () => idx,
+  };
+}

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

@@ -20,6 +20,8 @@ import {
   getFavorites, getThumbsDown, toggleThumbsUp, toggleThumbsDown,
 } from './voices-tab.js';
 import { buildAudioEnv, detectWavPlayer, detectRemoteLlm } from '../audio-env.js';
+import { createRowSpinner } from '../preview-transport.js';
+import { resolveMusicProvider } from '../music-preview.js';
 import { voicesForProvider } from '../../services/provider-voice-catalog.js';
 import { destroyList } from '../widgets/destroy-list.js';
 import { BRAND_PINK } from '../brand-colors.js';
@@ -139,7 +141,7 @@ const COLORS = {
   linkFg:     'bright-cyan',
 };
 
-const _FOOTER_BMAD_EN   = '[↑↓/jk] Navigate  [Space] Preview  [Enter] Configure  [A] Auto-assign  [B] Bulk  [X] Reset  [Q] Quit';
+const _FOOTER_BMAD_EN   = '[↑↓/jk] Navigate  [Space] Preview  [Enter] Configure  [A] Auto-assign  [B] Bulk  [Del] Reset  [Q] Quit';
 const _FOOTER_NOBMAD_EN = '[Tab] Switch Tab  [Q] Quit';
 
 const _modalTitle = (text) => ` {${BRAND_PINK}-fg}${text}{/${BRAND_PINK}-fg} `;
@@ -332,6 +334,14 @@ ${_tl('bmadDesc')}
     if (typeof focusMainTabBar === 'function') { focusMainTabBar(); screen.render(); }
   });
 
+  // Manual re-check: after installing BMAD from a separate terminal, Enter
+  // re-scans without leaving the tab. (Switching tabs also re-scans via onFocus.)
+  // If BMAD now shows up, move focus to the roster (else keys go to the hidden box).
+  onboardingBox.key(['enter'], () => {
+    refreshDisplay();
+    if (_bmadDetected) { agentList.focus(); screen.render(); }
+  });
+
   // -------------------------------------------------------------------------
   // BMAD state — section header
 
@@ -421,7 +431,7 @@ ${_tl('bmadDesc')}
     left: 4,
     hidden: true,
     tags: true,
-    content: '{#546e7a-fg}[Space] Preview  [Enter] Configure  [X] Reset  [A] Auto-assign  [B] Bulk Edit{/#546e7a-fg}',
+    content: '{#546e7a-fg}[Space] Preview  [Enter] Configure  [Del] Reset  [A] Auto-assign  [B] Bulk Edit{/#546e7a-fg}',
     style: { bg: COLORS.contentBg },
   });
 
@@ -468,7 +478,7 @@ ${_tl('bmadDesc')}
     return btn;
   }
 
-  const resetBtn = _createBtn('[X] Reset', () => {
+  const resetBtn = _createBtn('[Del] Reset', () => {
     const agent = _agents[agentList.selected ?? 0];
     if (agent) {
       voiceStore.resetAgentProfile(agent.id);
@@ -1073,6 +1083,11 @@ ${_tl('bmadDesc')}
       content: '', style: { fg: 'bright-cyan', bg: COLORS.contentBg },
     });
 
+    // Row spinner: "⠹ Previewing (locally|remotely via SSH)  (Space to stop)" ON
+    // the selected row — shared with every other picker. renderItem restores the
+    // row on stop. vpPreviewLine is retained for parity but no longer shows preview.
+    const _vpSpin = createRowSpinner(vpList, screen, (i) => _buildVoiceItems([_allVoices[i]])[0], { isClosed: () => _vpClosed });
+
     blessed.text({
       parent: vpModal, bottom: 3, left: 2, right: 2, height: 1, tags: true,
       content: '{white-fg}[↑↓] Nav  [PgUp/PgDn] Page  [a-z] Jump{/white-fg}',
@@ -1119,27 +1134,32 @@ ${_tl('bmadDesc')}
     }
 
     function _previewVoice(voiceId) {
-      if (_previewVoiceId === voiceId) { _killVP(); vpPreviewLine.setContent(''); _refreshVP(); return; }
+      if (_previewVoiceId === voiceId) { _killVP(); _vpSpin.stop(); return; }
       _killVP();
       if (_previewMinTimer) { clearTimeout(_previewMinTimer); _previewMinTimer = null; }
 
       const phrase = previewPhrase(voiceId);
       const _isWin = process.platform === 'win32' && !process.env.WSL_DISTRO_NAME;
+      // Badge must match where play-tts actually routes: remote if the provider
+      // file is ssh-remote/agentvibes-receiver OR a transport-config entry is
+      // mode=remote. resolveMusicProvider is the shared transport resolver (both
+      // signals) — don't re-derive routing here (CLAUDE.md invariant #1).
+      const _isRemote = resolveMusicProvider(path.dirname(_pkgClaudeDir)).remote;
 
       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;
         _previewVoiceId = voiceId;
-        if (!_vpClosed) { vpPreviewLine.setContent(`{bright-cyan-fg}♪ Playing: ${voiceId}...{/bright-cyan-fg}`); _refreshVP(); }
+        if (!_vpClosed) { _vpSpin.start(vpList.selected, _isRemote); }
         _previewProc = spawn('powershell', [ // NOSONAR
           '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', playTtsScript, phrase, voiceId,
         ], { stdio: 'ignore', detached: false, windowsHide: true,
           env: { ..._spawnEnv, AGENTVIBES_VOICE_SOURCE: 'audition' } });
         _previewProc.on('exit', () => {
-          if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); } }
+          if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; _vpSpin.stop(); }
         });
-        _previewProc.on('error', () => { _previewProc = null; _previewVoiceId = null; });
+        _previewProc.on('error', () => { _previewProc = null; _previewVoiceId = null; _vpSpin.stop(); });
         return;
       }
 
@@ -1166,12 +1186,12 @@ ${_tl('bmadDesc')}
         cwd: _projectRoot,
       });
       _previewVoiceId = voiceId;
-      if (!_vpClosed) { vpPreviewLine.setContent(`{bright-cyan-fg}♪ Playing: ${voiceId}...{/bright-cyan-fg}`); _refreshVP(); }
+      if (!_vpClosed) { _vpSpin.start(vpList.selected, _isRemote); }
 
       const _clearAfterMinDisplay = () => {
         if (_previewVoiceId === voiceId) {
           _previewVoiceId = null; _previewProc = null;
-          if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); }
+          _vpSpin.stop();
         }
         _previewMinTimer = null;
       };
@@ -1878,7 +1898,12 @@ ${_tl('bmadDesc')}
   // -------------------------------------------------------------------------
   // Key bindings
 
-  agentList.key(['x', 'X'], () => {
+  // Reset uses Delete/Backspace — NOT a letter. 'x'/'X' is the GLOBAL shortcut
+  // for the Receiver tab (navigation.js KEY_TO_TAB), and screen-level keys fire
+  // even while this list is focused, so binding Reset to X reset the agent AND
+  // jumped to the Receiver tab. Delete has no global binding and doesn't clash
+  // with type-to-jump.
+  agentList.key(['delete', 'backspace'], () => {
     const agent = _agents[agentList.selected ?? 0];
     if (agent) {
       voiceStore.resetAgentProfile(agent.id);
@@ -2038,6 +2063,11 @@ ${_tl('bmadDesc')}
     },
 
     onFocus() {
+      // Re-detect on focus so BMAD installed in another tab/terminal (or just
+      // now, via the onboarding install command) appears without restarting the
+      // TUI. Tab switching invokes onFocus, so returning to this tab IS the
+      // rescan — onboarding ⇄ agent list flips automatically.
+      refreshDisplay();
       if (_bmadDetected) {
         agentList.focus();
       } else {

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

@@ -13,7 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildAudioEnv, spawnMp3Player } from '../audio-env.js';
-import { resolveMusicProvider, spawnMusicRemote } from '../music-preview.js';
+import { resolveMusicProvider, spawnMusicRemote, createRowSpinner } from '../music-preview.js';
 import { playBlingCue } from '../bling.js';
 import { t } from '../../i18n/strings.js';
 
@@ -372,6 +372,20 @@ export function createMusicTab(screen, services) {
     },
   });
 
+  // Row spinner: paints "⠹ Previewing (locally|remotely via SSH)  (Space to stop)"
+  // ON the selected track row — shared with every other picker. renderItem
+  // restores the row's normal content when the preview stops.
+  const _trackSpin = createRowSpinner(trackList, screen, (i) => {
+    const t = _getVisibleTracks()[i];
+    if (!t) return '';
+    const { track: activeTrackId } = _getMusic(configService);
+    return _buildListItems([t], activeTrackId, getMusicFavorites(configService))[0];
+    // static: track rows carry double-width emoji; animating/reallocating them
+    // desyncs blessed's terminal output (jumps/corruption). Write the indicator
+    // ONCE (padded to full width to clear the old row), no animation, no realloc —
+    // the least-fragile option for emoji rows.
+  }, { isClosed: () => box.hidden, static: true });
+
   // -------------------------------------------------------------------------
   // Status panel
 
@@ -522,7 +536,23 @@ export function createMusicTab(screen, services) {
     return _stripHint(_stripBlink(raw));
   }
 
+  // Strip hint text + blink cursor from EVERY row and forget the hint anchor.
+  // Called when a preview starts so the internal buffer is clean before the
+  // spinner's full-repaint (otherwise a stale hint/blink would be faithfully
+  // re-rendered by the realloc).
+  function _clearRowDecorations() {
+    const items = trackList.items || [];
+    for (let i = 0; i < items.length; i++) {
+      if (items[i]) items[i].setContent(_stripDecorations(items[i].content));
+    }
+    _hintIdx = -1; _hintBase = '';
+  }
+
   function _updateHint(idx) {
+    // While a preview spinner is animating a row, it owns row rendering — the
+    // inline hint must not rewrite rows (it would fight the 80ms spinner and
+    // leave ghost characters on the previewing row when the cursor moves).
+    if (_trackSpin.isActive()) return;
     const items = trackList.items;
     // Restore previously hinted row — pad with spaces to overwrite ghost hint text
     const _pad = ' '.repeat(60);
@@ -621,17 +651,20 @@ export function createMusicTab(screen, services) {
       if (_remotePlayingTrackId === trackId) {
         _sendMusicRemote(_mp, { stop: true });
         _remotePlayingTrackId = null;
+        _trackSpin.stop();
+        if (_listFocused) _updateHint(trackList.selected);
         previewLine.setContent(_listFocused ? _hintText() : '');
         screen.render();
         return;
       }
       // Bling first (fire-and-forget, plays locally) — same readiness cue as the
-      // voice preview — then forward the track to the receiver.
+      // voice preview — then forward the track to the receiver. The receiver keeps
+      // playing until an explicit stop, so the row spinner persists (no floor).
       playBlingCue(_PKG_ROOT);
-      const rlabel = _allTracks.find(t => t.id === trackId)?.label ?? formatTrackLabel(trackId);
       if (_sendMusicRemote(_mp, { track: trackId })) {
         _remotePlayingTrackId = trackId;
-        previewLine.setContent(`{${COLORS.playingFg}-fg}♪ Playing on receiver: ${rlabel}  (Space to stop){/${COLORS.playingFg}-fg}`);
+        _clearRowDecorations();   // spinner owns the rows; wipe stale hint/blink first
+        _trackSpin.start(trackList.selected, true);
       }
       screen.render();
       return;
@@ -642,6 +675,8 @@ export function createMusicTab(screen, services) {
     if (_playingTrackId === trackId) {
       _killPlayingProcess();
       _playingTrackId = null;
+      _trackSpin.stop();
+      if (_listFocused) _updateHint(trackList.selected);
       previewLine.setContent(_listFocused ? _hintText() : '');
       screen.render();
       return;
@@ -668,17 +703,15 @@ export function createMusicTab(screen, services) {
 
     _playingProcess = proc;
     _playingTrackId = trackId;
-
-    const label = _allTracks.find(t => t.id === trackId)?.label ?? formatTrackLabel(trackId);
-    previewLine.setContent(`{${COLORS.playingFg}-fg}♪ Previewing: ${label}  (Space again to stop){/${COLORS.playingFg}-fg}`);
+    _clearRowDecorations();   // spinner owns the rows; wipe stale hint/blink first
+    _trackSpin.start(trackList.selected, false);
     screen.render();
 
     proc.on('exit', () => {
       if (_playingTrackId === trackId) {
         _playingTrackId = null;
         _playingProcess = null;
-        previewLine.setContent(_listFocused ? _hintText() : '');
-        refreshDisplay(); // clears (playing) label
+        _trackSpin.stop();
       }
     });
 
@@ -687,7 +720,7 @@ export function createMusicTab(screen, services) {
         _killPlayingProcess();
         _playingTrackId = null;
         _playingProcess = null;
-        previewLine.setContent(_listFocused ? _hintText() : '');
+        _trackSpin.stop();
       }
     });
   }
@@ -732,8 +765,26 @@ export function createMusicTab(screen, services) {
     });
   }
 
+  // Stop any in-flight preview (local player, remote receiver, and the row
+  // spinner). Used before a list rebuild so a stale spinner index can't crash
+  // blessed's setItem, and so a preview can't be left "playing" invisibly.
+  function _stopAnyPreview() {
+    if (_remotePlayingTrackId) {
+      const mp = resolveMusicProvider(_PKG_ROOT);
+      if (mp.remote) _sendMusicRemote(mp, { stop: true });
+      _remotePlayingTrackId = null;
+    }
+    _killPlayingProcess();
+    _playingTrackId = null;
+    _trackSpin.stop();
+  }
+
   function refreshDisplay() {
     _refreshing = true;
+    // A rebuild (setItems) invalidates the spinner's row index and wipes its
+    // indicator — stop any active preview first (guarded, so a normal refresh with
+    // no preview is a no-op). Prevents a stale-index crash and a stuck preview.
+    if (_trackSpin.isActive()) _stopAnyPreview();
     const savedIdx = trackList.selected ?? 0;
 
     _allTracks = _buildAllTracks();
@@ -819,6 +870,7 @@ export function createMusicTab(screen, services) {
     function _close() {
       _killPlayingProcess();
       _playingTrackId = null;
+      _trackSpin.stop();
       previewLine.setContent(_listFocused ? _hintText() : '');
       modal.destroy();
       trackList.focus();
@@ -942,8 +994,9 @@ export function createMusicTab(screen, services) {
   trackList.key(['space'], () => {
     const trackId = _getSelectedTrackId();
     if (trackId) {
+      // No refreshDisplay() here — it rebuilds every row via setItems and would
+      // clobber the preview spinner's row (the spinner now shows preview state).
       _playTrack(trackId);
-      refreshDisplay();
     }
   });
 
@@ -1013,6 +1066,10 @@ export function createMusicTab(screen, services) {
   let _tlBlink = { interval: null, on: false, sel: -1 };
   process.on('exit', () => { if (_tlBlink.interval) clearInterval(_tlBlink.interval); });
   function _tlTick() {
+    // While a preview is animating a row, the preview spinner (80ms) owns the
+    // display — don't fight it with the 500ms blink cursor (that interleaving
+    // left ghost characters on the previewing row).
+    if (_trackSpin.isActive()) return;
     _tlBlink.on = !_tlBlink.on;
     const items = trackList.items;
     const cur = trackList.selected ?? 0;
@@ -1134,6 +1191,7 @@ export function createMusicTab(screen, services) {
       // Stop any preview when leaving the tab
       _killPlayingProcess();
       _playingTrackId = null;
+      _trackSpin.stop();
       previewLine.setContent('');
       box.hide();
       screen.render();
@@ -1148,6 +1206,7 @@ export function createMusicTab(screen, services) {
       // Stop preview when focus leaves Music tab
       _killPlayingProcess();
       _playingTrackId = null;
+      _trackSpin.stop();
     },
 
     getFooterText() {

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

@@ -46,6 +46,7 @@ import { destroyList } from '../widgets/destroy-list.js';
 import { scanInstalledVoices, getVoiceMeta, previewPhrase, 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 { previewRowContent, createRowSpinner, padTaggedTo } from '../preview-transport.js';
 import { buildBlingCommand, playBlingCue } from '../bling.js';
 import { spawn, spawnSync } from 'node:child_process';
 
@@ -2907,6 +2908,7 @@ export function createSetupTab(screen, services) {
     let _kSpinFrame = 0;
     let _kSpinningIdx = -1;
     let _kSpinStartTs = 0;
+    let _kSpinRemote = false;  // whether the active preview is forwarded to the receiver
     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
@@ -2916,17 +2918,20 @@ export function createSetupTab(screen, services) {
     // visible "preview sent" cue (fire-and-forget has no playback signal to await).
     const _K_MIN_SPIN_MS = 1100;
 
-    function _startKSpinner(listIdx) {
+    function _startKSpinner(listIdx, remote = false) {
       _stopKSpinner();
       _kSpinningIdx = listIdx;
       _kSpinFrame = 0;
       _kSpinStartTs = Date.now();
+      _kSpinRemote = remote;
       _kSpinInterval = setInterval(() => {
         if (_kClosed) { _stopKSpinner(); return; }
-        const spin = `{cyan-fg}${_K_SPIN[_kSpinFrame++ % _K_SPIN.length]}{/cyan-fg}`;
-        kPicker.setItem(listIdx, `${_kokoroItem(voices[listIdx])} ${spin}`);
+        // Row indicator: "⠹ Previewing (locally|remotely via SSH)  (Space to stop)".
+        // The row IS the selected voice, so the name is intentionally omitted.
+        kPicker.setItem(listIdx, padTaggedTo(previewRowContent(_K_SPIN[_kSpinFrame++ % _K_SPIN.length], _kSpinRemote), kPicker.width || 78));
         screen.render();
       }, 80);
+      if (_kSpinInterval.unref) _kSpinInterval.unref(); // never keep the process alive
     }
 
     function _stopKSpinner() {
@@ -3277,7 +3282,7 @@ export function createSetupTab(screen, services) {
 
       // ── Remote preview: route through SSH pipeline so receiver plays it ──
       if (_validSshHost) {
-        _startKSpinner(kPicker.selected);
+        _startKSpinner(kPicker.selected, true);
         const hookDir = path.join(packageDir, '.claude', 'hooks');
         const remoteEnv = { ...process.env, CLAUDE_PROJECT_DIR: targetDir, AGENTVIBES_SSH_HOST: _sshHost };
         if (_validSshKey)  remoteEnv.AGENTVIBES_SSH_KEY  = _sshKey;
@@ -3392,6 +3397,7 @@ export function createSetupTab(screen, services) {
           }
           screen.render();
         }, 120);
+        if (_kAnimInterval.unref) _kAnimInterval.unref(); // never keep the process alive
       }
 
       function _stopDlAnim() {
@@ -3788,10 +3794,15 @@ export function createSetupTab(screen, services) {
     function _setHint(text) { elBox.setLabel(text || _defaultHint); screen.render(); }
     _setHint(_defaultHint);
 
+    // Row spinner: "⠹ Previewing (locally)  (Space to stop)" on the selected row.
+    // ElevenLabs preview always plays locally today, so the badge is honestly
+    // local; _setHint stays for error messages only.
+    const _elSpin = createRowSpinner(elPicker, screen, (i) => _items[i], { isClosed: () => _elClosed });
+
     function _previewEl() {
       if (_elPreviewProc) {  // toggle off
         _killElPreview();
-        _setHint(_defaultHint);
+        _elSpin.stop();
         return;
       }
       const v = ELEVENLABS_VOICES[elPicker.selected];
@@ -3808,18 +3819,17 @@ export function createSetupTab(screen, services) {
         return;
       }
       _elPreviewProc = proc;
-      _setHint(` {cyan-fg}♪ ${v.name}... (Space=stop){/cyan-fg} `);
+      _elSpin.start(elPicker.selected, false);
       proc.on('exit', (code) => {
         _elPreviewProc = null;
         if (_elClosed) return;
+        _elSpin.stop();
         if (code && code !== 0) {
           _setHint(' {red-fg}Preview failed — check API key / plan{/red-fg} ');
           setTimeout(() => { if (!_elClosed) _setHint(_defaultHint); }, 3000);
-        } else {
-          _setHint(_defaultHint);
         }
       });
-      proc.on('error', () => { _elPreviewProc = null; if (!_elClosed) _setHint(' {red-fg}Preview failed{/red-fg} '); });
+      proc.on('error', () => { _elPreviewProc = null; _elSpin.stop(); if (!_elClosed) _setHint(' {red-fg}Preview failed{/red-fg} '); });
     }
 
     elPicker.key(['enter'], () => {
@@ -4137,6 +4147,11 @@ export function createSetupTab(screen, services) {
       content: ' ', style: { fg: 'cyan', bg: COLORS.contentBg },
     });
 
+    // Row spinner: paints "⠹ Previewing (locally|remotely via SSH)  (Space to stop)"
+    // ON the selected row (shared with every other picker). renderItem restores the
+    // row's normal content on stop. vpPreviewLine is kept for error messages only.
+    const _vpSpin = createRowSpinner(vpList, screen, (i) => _buildVoiceItems([_allVoices[i]])[0], { isClosed: () => _vpClosed });
+
     // Movement hints at the bottom (primary actions live in the top help bar, so
     // they are not duplicated here). Standardized [key] = label formatting.
     blessed.text({
@@ -4186,7 +4201,7 @@ export function createSetupTab(screen, services) {
     }
 
     function _previewVoice(voiceId) {
-      if (_previewVoiceId === voiceId) { _killVP(); vpPreviewLine.setContent(''); _refreshVP(); return; }
+      if (_previewVoiceId === voiceId) { _killVP(); _vpSpin.stop(); return; }
       _killVP();
 
       const phrase = previewPhrase(voiceId);
@@ -4238,15 +4253,15 @@ export function createSetupTab(screen, services) {
         }
         _previewProc = rProc;
         _previewVoiceId = voiceId;
-        if (!_vpClosed) { _refreshVP(); vpPreviewLine.setContent('{bright-magenta-fg}♪ Synthesizing on remote...{/bright-magenta-fg}'); screen.render(); }
+        if (!_vpClosed) { _vpSpin.start(vpList.selected, true); }
         rProc.on('exit', () => {
           if (_previewVoiceId === voiceId) {
             _previewVoiceId = null; _previewProc = null;
-            // Keep message + ♪ visible for 5s while remote device synthesises and plays
-            setTimeout(() => { if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); } }, 5000);
+            // Fire-and-forget SSH exits in ms; keep the row cue up briefly, then restore.
+            _vpSpin.stopWithFloor();
           }
         });
-        rProc.on('error', () => { _previewProc = null; _previewVoiceId = null; });
+        rProc.on('error', () => { _previewProc = null; _previewVoiceId = null; _vpSpin.stop(); });
         return;
       }
 
@@ -4279,9 +4294,9 @@ export function createSetupTab(screen, services) {
         }
         _previewProc = nProc;
         _previewVoiceId = voiceId;
-        if (!_vpClosed) { vpPreviewLine.setContent(`{cyan-fg}♪ Playing: ${voiceId}...{/cyan-fg}`); _refreshVP(); }
-        nProc.on('exit', () => { if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); } } });
-        nProc.on('error', () => { _previewProc = null; _previewVoiceId = null; });
+        if (!_vpClosed) { _vpSpin.start(vpList.selected, false); }
+        nProc.on('exit', () => { if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; _vpSpin.stop(); } });
+        nProc.on('error', () => { _previewProc = null; _previewVoiceId = null; _vpSpin.stop(); });
         return;
       }
 
@@ -4316,14 +4331,14 @@ export function createSetupTab(screen, services) {
       _previewVoiceId = voiceId;
 
       if (!_vpClosed) {
-        vpPreviewLine.setContent(`{cyan-fg}♪ Synthesizing: ${voiceId}...{/cyan-fg}`);
-        _refreshVP();
+        _vpSpin.start(vpList.selected, false);
       }
 
       piper.on('exit', (code) => {
         if (_previewVoiceId !== voiceId) { try { fs.unlinkSync(tempWav); } catch {} return; }
         if (code !== 0) {
           _previewProc = null; _previewVoiceId = null;
+          _vpSpin.stop();
           if (!_vpClosed) {
             vpPreviewLine.setContent('{red-fg}♪ Preview failed — is Piper installed?{/red-fg}');
             screen.render();
@@ -4341,14 +4356,15 @@ export function createSetupTab(screen, services) {
           env: _spawnEnv,
         });
         _previewProc = pp;
-        if (!_vpClosed) { vpPreviewLine.setContent(`{cyan-fg}♪ Playing: ${voiceId}{/cyan-fg}`); screen.render(); }
+        // Row spinner already running from the synth phase — keep it through playback.
         pp.on('exit', () => {
-          if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; if (!_vpClosed) { vpPreviewLine.setContent(''); _refreshVP(); } }
+          if (_previewVoiceId === voiceId) { _previewVoiceId = null; _previewProc = null; _vpSpin.stop(); }
           try { fs.unlinkSync(tempWav); } catch {}
         });
       });
       piper.on('error', () => {
         _previewProc = null; _previewVoiceId = null;
+        _vpSpin.stop();
         if (!_vpClosed) {
           vpPreviewLine.setContent('{red-fg}♪ Cannot find Piper — install it first{/red-fg}');
           screen.render();

package/src/console/widgets/track-picker.js

@@ -14,7 +14,7 @@ import { BRAND_PINK } from '../brand-colors.js';
 import { renderHelpBar, selectorTitle } from './help-bar.js';
 import { formatTrackName } from './format-utils.js';
 import { buildAudioEnv, spawnMp3Player } from '../audio-env.js';
-import { resolveMusicProvider, spawnMusicRemote } from '../music-preview.js';
+import { resolveMusicProvider, spawnMusicRemote, createRowSpinner } from '../music-preview.js';
 import { playBlingCue } from '../bling.js';
 
 // AgentVibes package/repo root — resolves bundled assets (bling cue) and is the
@@ -231,12 +231,20 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
     },
   });
 
-  // Transient preview/error status shows in the title area; idle restores the title.
+  // Transient error status shows in the title area; idle restores the title.
   function _setStatus(text) {
     box.setLabel(text || TITLE);
     screen.render();
   }
 
+  // Row spinner: paints "⠹ Previewing (locally|remotely via SSH)  (Space to stop)"
+  // ON the selected track row — shared with every other picker. _setStatus stays
+  // for error messages only.
+  let _closed = false;
+  const _rowSpin = createRowSpinner(list, screen, (i) => (
+    tracks[i] && tracks[i].file === currentTrack ? `● ${tracks[i].label}` : `  ${tracks[i] ? tracks[i].label : ''}`
+  ), { isClosed: () => _closed });
+
   if (currentIdx >= 0) list.select(currentIdx);
   list.focus();
   screen.render();
@@ -263,6 +271,7 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
       if (mp.remote) _sendRemote(mp, { stop: true });
       _remotePreviewTrackId = null;
     }
+    _rowSpin.stop();
   }
 
   /**
@@ -310,16 +319,16 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
       if (_remotePreviewTrackId === trackFile) {
         _sendRemote(_mp, { stop: true });
         _remotePreviewTrackId = null;
-        _setStatus();
+        _rowSpin.stop();
         return;
       }
       // Bling first (fire-and-forget, plays locally like the voice preview),
-      // then forward the track to the receiver.
+      // then forward the track to the receiver. The receiver keeps playing until
+      // an explicit stop, so the row spinner persists (no floor).
       playBlingCue(_PKG_ROOT);
       if (_sendRemote(_mp, { track: trackFile })) {
         _remotePreviewTrackId = trackFile;
-        const rlabel = tracks.find(t => t.file === trackFile)?.label ?? trackFile;
-        _setStatus(` {bright-cyan-fg}♪ ${rlabel}  (Space to stop){/bright-cyan-fg} `);
+        _rowSpin.start(list.selected, true);
       }
       return;
     }
@@ -357,25 +366,25 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
 
     _previewProc = proc;
     _previewTrackId = trackFile;
-
-    const label = tracks.find(t => t.file === trackFile)?.label ?? trackFile;
-    _setStatus(` {bright-cyan-fg}♪ ${label}  (Space to stop){/bright-cyan-fg} `);
+    _rowSpin.start(list.selected, false);
 
     proc.on('exit', () => {
       if (_previewTrackId === trackFile) {
         _previewTrackId = null;
         _previewProc = null;
-        _setStatus();
+        _rowSpin.stop();
       }
     });
 
     proc.on('error', () => {
       _previewTrackId = null;
       _previewProc = null;
+      _rowSpin.stop();
     });
   }
 
   function _close(callback) {
+    _closed = true;
     _killPreview();
     if (callback) {
       callback();

package/src/i18n/de.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "Suche:",
   readmeScrollMore: "↓ Scrollen für mehr Inhalt ↓",
   readmeNotFound: "*(Keine README.md im aktuellen Verzeichnis gefunden)*",
-  bmadFooterNobmad: "[Tab] Tab wechseln  [Q] Beenden",
-  bmadFooterBmad: "[↑↓/jk] Navigieren  [Space] Vorschau  [Enter] Konfigurieren  [A] Auto-zuweisen  [B] Stapel  [X] Zurücksetzen  [Q] Beenden",
+  bmadFooterNobmad: "[Enter] Erneut prüfen  [Tab] Tab wechseln  [Q] Beenden",
+  bmadFooterBmad: "[↑↓/jk] Navigieren  [Space] Vorschau  [Enter] Konfigurieren  [A] Auto-zuweisen  [B] Stapel  [Del] Zurücksetzen  [Q] Beenden",
 };

package/src/i18n/en.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "Search:",
   readmeScrollMore: "↓ Scroll for more content ↓",
   readmeNotFound: "*(No README.md found in current directory)*",
-  bmadFooterNobmad: "[Tab] Switch Tab  [Q] Quit",
-  bmadFooterBmad: "[↑↓/jk] Navigate  [Space] Preview  [Enter] Configure  [A] Auto-assign  [B] Bulk  [X] Reset  [Q] Quit",
-};
+  bmadFooterNobmad: "[Enter] Re-check  [Tab] Switch Tab  [Q] Quit",
+  bmadFooterBmad: "[↑↓/jk] Navigate  [Space] Preview  [Enter] Configure  [A] Auto-assign  [B] Bulk  [Del] Reset  [Q] Quit",
+};

package/src/i18n/es.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "Buscar:",
   readmeScrollMore: "↓ Desplázate para ver más ↓",
   readmeNotFound: "*(No se encontró README.md en el directorio actual)*",
-  bmadFooterNobmad: "[Tab] Cambiar Pestaña  [Q] Salir",
-  bmadFooterBmad: "[↑↓/jk] Navegar  [Space] Previsualizar  [Enter] Configurar  [A] Auto-asignar  [B] Masivo  [X] Restablecer  [Q] Salir",
+  bmadFooterNobmad: "[Enter] Volver a comprobar  [Tab] Cambiar Pestaña  [Q] Salir",
+  bmadFooterBmad: "[↑↓/jk] Navegar  [Space] Previsualizar  [Enter] Configurar  [A] Auto-asignar  [B] Masivo  [Del] Restablecer  [Q] Salir",
 };

package/src/i18n/fr.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "Recherche:",
   readmeScrollMore: "↓ Défiler pour plus de contenu ↓",
   readmeNotFound: "*(Aucun README.md trouvé dans le répertoire actuel)*",
-  bmadFooterNobmad: "[Tab] Changer d'onglet  [Q] Quitter",
-  bmadFooterBmad: "[↑↓/jk] Naviguer  [Space] Aperçu  [Enter] Configurer  [A] Auto-assigner  [B] Lot  [X] Réinitialiser  [Q] Quitter",
+  bmadFooterNobmad: "[Enter] Revérifier  [Tab] Changer d'onglet  [Q] Quitter",
+  bmadFooterBmad: "[↑↓/jk] Naviguer  [Space] Aperçu  [Enter] Configurer  [A] Auto-assigner  [B] Lot  [Del] Réinitialiser  [Q] Quitter",
 };

package/src/i18n/hi.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "खोजें:",
   readmeScrollMore: "↓ अधिक सामग्री के लिए स्क्रॉल करें ↓",
   readmeNotFound: "*(वर्तमान निर्देशिका में README.md नहीं मिला)*",
-  bmadFooterNobmad: "[Tab] टैब बदलें  [Q] बाहर",
-  bmadFooterBmad: "[↑↓/jk] नेविगेट  [Space] प्रीव्यू  [Enter] कॉन्फ़िगर  [A] ऑटो-असाइन  [B] बल्क  [X] रीसेट  [Q] बाहर",
+  bmadFooterNobmad: "[Enter] फिर से जाँचें  [Tab] टैब बदलें  [Q] बाहर",
+  bmadFooterBmad: "[↑↓/jk] नेविगेट  [Space] प्रीव्यू  [Enter] कॉन्फ़िगर  [A] ऑटो-असाइन  [B] बल्क  [Del] रीसेट  [Q] बाहर",
 };

package/src/i18n/ja.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "検索：",
   readmeScrollMore: "↓ スクロールして続きを見る ↓",
   readmeNotFound: "*(現在のディレクトリにREADME.mdが見つかりません)*",
-  bmadFooterNobmad: "[Tab] タブ切替  [Q] 終了",
-  bmadFooterBmad: "[↑↓/jk] 移動  [Space] プレビュー  [Enter] 設定  [A] 自動割当  [B] 一括  [X] リセット  [Q] 終了",
+  bmadFooterNobmad: "[Enter] 再確認  [Tab] タブ切替  [Q] 終了",
+  bmadFooterBmad: "[↑↓/jk] 移動  [Space] プレビュー  [Enter] 設定  [A] 自動割当  [B] 一括  [Del] リセット  [Q] 終了",
 };

package/src/i18n/ko.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "검색:",
   readmeScrollMore: "↓ 아래로 스크롤하여 더 보기 ↓",
   readmeNotFound: "*(현재 디렉토리에서 README.md를 찾을 수 없습니다)*",
-  bmadFooterNobmad: "[Tab] 탭 전환  [Q] 나가기",
-  bmadFooterBmad: "[↑↓/jk] 탐색  [Space] 미리보기  [Enter] 설정  [A] 자동배정  [B] 일괄  [X] 초기화  [Q] 나가기",
+  bmadFooterNobmad: "[Enter] 다시 확인  [Tab] 탭 전환  [Q] 나가기",
+  bmadFooterBmad: "[↑↓/jk] 탐색  [Space] 미리보기  [Enter] 설정  [A] 자동배정  [B] 일괄  [Del] 초기화  [Q] 나가기",
 };

package/src/i18n/pt.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "Buscar:",
   readmeScrollMore: "↓ Role para mais conteúdo ↓",
   readmeNotFound: "*(Nenhum README.md encontrado no diretório atual)*",
-  bmadFooterNobmad: "[Tab] Mudar Aba  [Q] Sair",
-  bmadFooterBmad: "[↑↓/jk] Navegar  [Space] Visualizar  [Enter] Configurar  [A] Auto-atribuir  [B] Lote  [X] Redefinir  [Q] Sair",
+  bmadFooterNobmad: "[Enter] Verificar novamente  [Tab] Mudar Aba  [Q] Sair",
+  bmadFooterBmad: "[↑↓/jk] Navegar  [Space] Visualizar  [Enter] Configurar  [A] Auto-atribuir  [B] Lote  [Del] Redefinir  [Q] Sair",
 };

package/src/i18n/zh-CN.js

@@ -198,6 +198,6 @@ export default {
   helpSearchLabel: "搜索：",
   readmeScrollMore: "↓ 向下滚动查看更多 ↓",
   readmeNotFound: "*(当前目录中未找到README.md)*",
-  bmadFooterNobmad: "[Tab] 切换标签  [Q] 退出",
-  bmadFooterBmad: "[↑↓/jk] 导航  [Space] 预览  [Enter] 配置  [A] 自动分配  [B] 批量  [X] 重置  [Q] 退出",
+  bmadFooterNobmad: "[Enter] 重新检查  [Tab] 切换标签  [Q] 退出",
+  bmadFooterBmad: "[↑↓/jk] 导航  [Space] 预览  [Enter] 配置  [A] 自动分配  [B] 批量  [Del] 重置  [Q] 退出",
 };

package/src/services/agent-voice-store.js

@@ -192,9 +192,76 @@ function _parseCSVLine(line) {
 // ---------------------------------------------------------------------------
 // BMAD agent scanner (story 11.5) — fallback when manifest is unavailable
 
+/** Title-case a hyphenated id: "tech-writer" → "Tech Writer". */
+function _titleCaseId(id) {
+  return id.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+/**
+ * Find v6.6+ persona-agent skills: top-level skill directories named
+ * `bmad-agent-<role>` under <root>/.claude/skills (e.g. bmad-agent-analyst →
+ * "analyst"). Deliberately IGNORES a skill's private `agents/` subfolder (e.g.
+ * bmad-prfaq/agents/) — those hold a skill's internal helper sub-agents, not
+ * BMAD persona agents. Matching them produced a bogus "2 agents" roster in the
+ * Agents tab when no real BMAD roster was installed.
+ *
+ * @param {string} root
+ * @returns {{ id: string, dir: string }[]}
+ */
+function _findBmadAgentSkills(root) {
+  const skillsDir = path.resolve(root, '.claude', 'skills');
+  const out = [];
+  if (!fs.existsSync(skillsDir)) return out;
+  try {
+    for (const skill of fs.readdirSync(skillsDir)) {
+      if (!skill.startsWith('bmad-agent-')) continue;
+      const id = skill.slice('bmad-agent-'.length);
+      if (!_isValidAgentId(id)) continue;
+      out.push({ id, dir: path.resolve(skillsDir, skill) });
+    }
+  } catch { /* skip */ }
+  return out;
+}
+
+/**
+ * Build an agent record from a `bmad-agent-*` skill dir, reading the SKILL.md
+ * heading ("# Mary — Business Analyst") for the persona name + title. Falls back
+ * to a title-cased id when the heading is missing/unreadable.
+ */
+// Generic section words that a bare "# Word" heading might be (not a persona).
+const _GENERIC_HEADING = /^(overview|about|usage|conventions|activation|role|purpose|description|instructions)$/i;
+
+function _agentFromSkill(id, skillDir) {
+  let displayName = _titleCaseId(id);
+  let title = '';
+  try {
+    const md = fs.readFileSync(path.resolve(skillDir, 'SKILL.md'), 'utf8');
+    // 1) Preferred: "# Mary — Business Analyst" (name <dash> title).
+    const dash = md.match(/^#\s+([^\n]+?)\s+[—–-]\s+([^\n]+?)\s*$/m); // em / en / hyphen
+    if (dash) {
+      displayName = dash[1].trim() || displayName;
+      title = dash[2].trim();
+    } else {
+      // 2) Frontmatter description often names the persona: "...talk to Mary...".
+      const desc = md.match(/^description:\s*(.+)$/mi);
+      const talk = desc && desc[1].match(/talk to ([A-Z][\w'’-]+)/);
+      if (talk) {
+        displayName = talk[1];
+      } else {
+        // 3) A bare "# Mary" heading — but skip generic section headings so a
+        // skill without a persona heading (e.g. "# Overview") falls back to the id.
+        const h1 = md.match(/^#\s+([A-Z][\w'’-]*)\s*$/m);
+        if (h1 && !_GENERIC_HEADING.test(h1[1])) displayName = h1[1];
+      }
+    }
+  } catch { /* use derived displayName */ }
+  return { id, displayName, title, icon: '', module: 'bmm' };
+}
+
 /**
  * Scan for BMAD agents in the project root.
- * Prefers manifest-based discovery; falls back to directory scan.
+ * Prefers manifest-based discovery; falls back to legacy dir scan, then to the
+ * v6.6+ skills-only layout (`bmad-agent-*` skills).
  *
  * @param {string} projectRoot
  * @returns {{ id: string, displayName: string, title: string, icon: string, module: string }[]}
@@ -207,50 +274,42 @@ export function scanBmadAgents(projectRoot) {
   // Fallback: directory scan — check project-local then home dir
   const safeRoot = path.resolve(projectRoot ?? process.cwd());
   const homeDir2 = os.homedir();
+  const roots = safeRoot !== homeDir2 ? [safeRoot, homeDir2] : [safeRoot];
 
-  // v6.6+: agents under .claude/skills/*/agents/ — collect all such dirs
-  const skillsAgentDirs = [];
-  for (const root of (safeRoot !== homeDir2 ? [safeRoot, homeDir2] : [safeRoot])) {
-    const skillsDir = path.resolve(root, '.claude', 'skills');
-    if (fs.existsSync(skillsDir)) {
-      try {
-        for (const skill of fs.readdirSync(skillsDir)) {
-          const agentsDir = path.resolve(skillsDir, skill, 'agents');
-          if (fs.existsSync(agentsDir)) skillsAgentDirs.push(agentsDir);
-        }
-      } catch { /* skip */ }
-    }
+  // Legacy layouts: <root>/_bmad/bmm/agents and <root>/.bmad/agents hold one
+  // .md per agent.
+  const candidateDirs = [];
+  for (const root of roots) {
+    candidateDirs.push(path.resolve(root, '_bmad', 'bmm', 'agents'));
+    candidateDirs.push(path.resolve(root, '.bmad', 'agents'));
   }
-
-  const candidateDirs = [
-    path.resolve(safeRoot, '_bmad', 'bmm', 'agents'),
-    path.resolve(safeRoot, '.bmad', 'agents'),
-    ...(safeRoot !== homeDir2 ? [
-      path.resolve(homeDir2, '_bmad', 'bmm', 'agents'),
-      path.resolve(homeDir2, '.bmad', 'agents'),
-    ] : []),
-    ...skillsAgentDirs,
-  ];
-
   for (const dir of candidateDirs) {
     if (!fs.existsSync(dir)) continue;
     try {
-      const files = fs.readdirSync(dir);
-      return files
+      const agents = fs.readdirSync(dir)
         .filter(f => f.endsWith('.md') && !f.includes('.backup') && !f.includes('.bak'))
         .map(f => {
           const id = f.replace(/\.md$/, '');
-          const displayName = id
-            .split('-')
-            .map(w => w.charAt(0).toUpperCase() + w.slice(1))
-            .join(' ');
-          return { id, displayName, title: '', icon: '', module: 'bmm' };
-        })
-        .sort((a, b) => a.id.localeCompare(b.id));
+          return { id, displayName: _titleCaseId(id), title: '', icon: '', module: 'bmm' };
+        });
+      if (agents.length > 0) return agents.sort((a, b) => a.id.localeCompare(b.id));
     } catch {
       // Directory not readable — skip
     }
   }
+
+  // v6.6+ skills-only install: persona agents are `bmad-agent-<role>` skills.
+  const seen = new Set();
+  const skillAgents = [];
+  for (const root of roots) {
+    for (const { id, dir } of _findBmadAgentSkills(root)) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      skillAgents.push(_agentFromSkill(id, dir));
+    }
+  }
+  if (skillAgents.length > 0) return skillAgents.sort((a, b) => a.id.localeCompare(b.id));
+
   return [];
 }
 
@@ -277,14 +336,10 @@ export function isBmadDetected(projectRoot) {
     ];
     if (dirs.some(d => fs.existsSync(d))) return true;
 
-    // v6.6+: agents live under .claude/skills/*/agents/
-    const skillsDir = path.resolve(root, '.claude', 'skills');
-    if (fs.existsSync(skillsDir)) {
-      try {
-        const skills = fs.readdirSync(skillsDir);
-        if (skills.some(s => fs.existsSync(path.resolve(skillsDir, s, 'agents')))) return true;
-      } catch { /* skip */ }
-    }
+    // v6.6+ skills-only install: persona agents are `bmad-agent-<role>` skills.
+    // (NOT `<skill>/agents/` subfolders — those are a skill's private helper
+    // sub-agents and must not count as a BMAD install.)
+    if (_findBmadAgentSkills(root).length > 0) return true;
   }
 
   return false;