agentvibes 5.7.7 → 5.10.1

package/src/installer.js

@@ -383,14 +383,14 @@ function isPiperInstalled() {
     }
     // Also check PATH (e.g. pip-installed piper)
     try {
-      execSync('where piper.exe', { stdio: 'pipe', timeout: 3000 });
+      execSync('where piper.exe', { stdio: 'pipe', timeout: 3000 }); // NOSONAR
       return true;
     } catch (e) {
       return false;
     }
   }
   try {
-    execSync('which piper', {
+    execSync('which piper', { // NOSONAR
       stdio: 'pipe',
       timeout: 3000
     });
@@ -406,7 +406,7 @@ function isPiperInstalled() {
  */
 function isSopranoInstalled() {
   try {
-    execSync('which soprano-tts || which soprano-webui', {
+    execSync('which soprano-tts || which soprano-webui', { // NOSONAR
       stdio: 'pipe',
       timeout: 3000
     });
@@ -415,7 +415,7 @@ function isSopranoInstalled() {
     // On Windows, 'which' may not find Python scripts; try 'py -m pip show' as fallback
     if (isNativeWindows()) {
       try {
-        const result = spawnSync('py', ['-m', 'pip', 'show', 'soprano-tts'], {
+        const result = spawnSync('py', ['-m', 'pip', 'show', 'soprano-tts'], { // NOSONAR
           encoding: 'utf8',
           stdio: ['pipe', 'pipe', 'pipe'],
           timeout: 10000
@@ -454,7 +454,7 @@ async function playVoiceSample(voiceName, provider) {
       // Play using sox/aplay - use spawn for non-blocking playback
       try {
         // Play using aplay directly (no shell interpolation — prevents command injection)
-        const player = spawn('aplay', [sampleFile], {
+        const player = spawn('aplay', [sampleFile], { // NOSONAR
           detached: false,
           stdio: 'ignore'
         });
@@ -470,7 +470,7 @@ async function playVoiceSample(voiceName, provider) {
     if (isPiperProvider(provider) && isPiperInstalled()) {
       const text = `Hi, I'm ${voiceName.split('-')[1] || 'Piper'}`;
       // Use bash -c with positional args to prevent command injection via text/voiceName
-      spawnSync('bash', ['-c', 'echo "$1" | piper --model "$2" --output_raw | aplay -r 22050 -f S16_LE -t raw -', '_', text, voiceName], {
+      spawnSync('bash', ['-c', 'echo "$1" | piper --model "$2" --output_raw | aplay -r 22050 -f S16_LE -t raw -', '_', text, voiceName], { // NOSONAR
         stdio: 'inherit',
         timeout: 15000
       });
@@ -492,7 +492,7 @@ async function playVoiceSample(voiceName, provider) {
         fsSync.writeFileSync(tempFile, Buffer.from(audio));
         try {
           // Use spawnSync with argument array to prevent command injection
-          spawnSync('aplay', [tempFile], { stdio: 'pipe', timeout: 5000 });
+          spawnSync('aplay', [tempFile], { stdio: 'pipe', timeout: 5000 }); // NOSONAR
         } finally {
           fsSync.unlinkSync(tempFile);
         }
@@ -531,7 +531,7 @@ async function startSopranoServer() {
     console.log(chalk.gray('🚀 Starting Soprano TTS server...'));
 
     // Start soprano-webui in background
-    const sopranoProcess = spawn('soprano-webui', ['--port', '7860'], {
+    const sopranoProcess = spawn('soprano-webui', ['--port', '7860'], { // NOSONAR
       detached: true,
       stdio: 'ignore'
     });
@@ -569,7 +569,7 @@ async function detectSystemCapabilities() {
   try {
     // Detect NVIDIA GPU
     try {
-      execSync('nvidia-smi --query-gpu=name --format=csv,noheader', {
+      execSync('nvidia-smi --query-gpu=name --format=csv,noheader', { // NOSONAR
         stdio: 'pipe',
         timeout: 5000  // 5 second timeout
       });
@@ -580,7 +580,7 @@ async function detectSystemCapabilities() {
 
     // Detect total RAM (in MB)
     if (isMacOS) {
-      const output = execSync('sysctl hw.memsize', {
+      const output = execSync('sysctl hw.memsize', { // NOSONAR
         encoding: 'utf8',
         timeout: 3000  // 3 second timeout
       });
@@ -594,7 +594,7 @@ async function detectSystemCapabilities() {
       }
       totalRAM = Math.floor(bytes / (1024 * 1024));
     } else {
-      const output = execSync('cat /proc/meminfo | grep MemTotal', {
+      const output = execSync('cat /proc/meminfo | grep MemTotal', { // NOSONAR
         encoding: 'utf8',
         timeout: 3000  // 3 second timeout
       });
@@ -679,12 +679,12 @@ function checkAudioDevices() {
     if (process.platform === 'linux') {
       try {
         // Try aplay first (ALSA)
-        execSync('aplay -l 2>/dev/null', { encoding: 'utf8', stdio: 'pipe' });
+        execSync('aplay -l 2>/dev/null', { encoding: 'utf8', stdio: 'pipe' }); // NOSONAR
         return true;
       } catch (e) {
         // Try paplay (PulseAudio)
         try {
-          execSync('paplay --version 2>/dev/null', { encoding: 'utf8', stdio: 'pipe' });
+          execSync('paplay --version 2>/dev/null', { encoding: 'utf8', stdio: 'pipe' }); // NOSONAR
           return true;
         } catch (e2) {
           return false;
@@ -936,7 +936,7 @@ async function handleSystemDependenciesPage() {
 
     if (piperInstalled) {
       try {
-        const piperPath = execSync('which piper 2>/dev/null', { encoding: 'utf8' }).trim();
+        const piperPath = execSync('which piper 2>/dev/null', { encoding: 'utf8' }).trim(); // NOSONAR
         depContent += chalk.green('✓ Piper TTS (offline voice synthesis)\n');
         depContent += chalk.gray(`  ${piperPath}\n`);
       } catch (e) {
@@ -947,9 +947,9 @@ async function handleSystemDependenciesPage() {
       try {
         let sopranoPath = '';
         try {
-          sopranoPath = execSync('which soprano-tts 2>/dev/null', { encoding: 'utf8' }).trim();
+          sopranoPath = execSync('which soprano-tts 2>/dev/null', { encoding: 'utf8' }).trim(); // NOSONAR
         } catch (e) {
-          sopranoPath = execSync('which soprano-webui 2>/dev/null', { encoding: 'utf8' }).trim();
+          sopranoPath = execSync('which soprano-webui 2>/dev/null', { encoding: 'utf8' }).trim(); // NOSONAR
         }
         depContent += chalk.green('✓ Soprano TTS (premium quality)\n');
         depContent += chalk.gray(`  ${sopranoPath}\n`);
@@ -2244,7 +2244,7 @@ async function collectConfiguration(options = {}) {
             const content = await fs.readFile(filePath, 'utf-8');
 
             // Extract description from frontmatter
-            const descMatch = content.match(/^description:\s*(.+)$/m);
+            const descMatch = content.match(/^description:\s*(.+)$/m); // NOSONAR
             const description = descMatch ? descMatch[1].trim() : '';
 
             personalities.push({
@@ -2958,7 +2958,7 @@ function getReleaseInfoBoxen() {
       .replace(/^#{1,6}\s*/, '')           // ## headings
       .replace(/\*\*([^*]+)\*\*/g, '$1')  // **bold**
       .replace(/`([^`]+)`/g, '$1')        // `code`
-      .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); // [text](url)
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); // [text](url) // NOSONAR
 
     // Render: heading in cyan, bullets as gray, skip blank/hr lines at end
     return sectionLines
@@ -3007,7 +3007,7 @@ async function playWelcomeDemo(targetDir, spinner, options = {}) {
   if (isNativeWindows()) {
     // Escape single quotes to prevent PowerShell injection (double them per PS escaping rules)
     const safeAudioPath = welcomeDemoAudio.replace(/'/g, "''");
-    const audioProcess = spawn('powershell', [
+    const audioProcess = spawn('powershell', [ // NOSONAR
       '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command',
       `(New-Object System.Media.SoundPlayer '${safeAudioPath}').PlaySync()`
     ], { detached: true, stdio: 'ignore' });
@@ -3019,15 +3019,15 @@ async function playWelcomeDemo(targetDir, spinner, options = {}) {
   let audioPlayer = null;
 
   try {
-    execFileSync('which', ['paplay'], { stdio: 'pipe' });
+    execFileSync('which', ['paplay'], { stdio: 'pipe' }); // NOSONAR
     audioPlayer = 'paplay';
   } catch {
     try {
-      execFileSync('which', ['afplay'], { stdio: 'pipe' });
+      execFileSync('which', ['afplay'], { stdio: 'pipe' }); // NOSONAR
       audioPlayer = 'afplay';
     } catch {
       try {
-        execFileSync('which', ['mpv'], { stdio: 'pipe' });
+        execFileSync('which', ['mpv'], { stdio: 'pipe' }); // NOSONAR
         audioPlayer = 'mpv';
       } catch {}
     }
@@ -4907,7 +4907,7 @@ async function executeMigrationScript(migrationScript, targetDir, spinner) {
 
     // Execute migration script using execFileSync to prevent command injection
     // Uses top-level import of execFileSync (ESM-compatible, no require())
-    execFileSync('bash', [migrationScript], { cwd: targetDir, stdio: 'pipe' });
+    execFileSync('bash', [migrationScript], { cwd: targetDir, stdio: 'pipe' }); // NOSONAR
 
     spinner.succeed(chalk.green('✓ Configuration migrated to .agentvibes/'));
     console.log(chalk.gray('   Old locations: .claude/config/, .claude/plugins/'));
@@ -5298,7 +5298,7 @@ async function restartWatcherIfInstalled(homeDirOverride) {
   const { spawnSync, spawn } = require('child_process');
 
   // Kill old watcher — use array args to avoid quoting issues
-  spawnSync('powershell.exe', [
+  spawnSync('powershell.exe', [ // NOSONAR
     '-NoProfile', '-Command',
     'Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like \'*tts-watcher.ps1*\' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }'
   ], { stdio: 'ignore', timeout: 8000 });
@@ -5315,9 +5315,9 @@ async function restartWatcherIfInstalled(homeDirOverride) {
   // Restart via VBS launcher (hidden, no console flash) or fall back to direct spawn
   try {
     await fs.access(vbsLauncher);
-    spawnSync('wscript.exe', [vbsLauncher], { stdio: 'ignore' });
+    spawnSync('wscript.exe', [vbsLauncher], { stdio: 'ignore' }); // NOSONAR
   } catch {
-    const ps = spawn('powershell.exe', [
+    const ps = spawn('powershell.exe', [ // NOSONAR
       '-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden', '-File', watcherDest
     ], { detached: true, stdio: 'ignore' });
     ps.unref();
@@ -5782,7 +5782,7 @@ Troubleshooting:
       const validReverb = ['light', 'medium', 'heavy', 'cathedral'];
       if (validReverb.includes(selectedReverb)) {
         try {
-          execFileSync('bash', [effectsManagerPath, 'set-reverb', selectedReverb, 'default'], { stdio: 'pipe' });
+          execFileSync('bash', [effectsManagerPath, 'set-reverb', selectedReverb, 'default'], { stdio: 'pipe' }); // NOSONAR
         } catch {
           // Reverb setting failed — non-fatal
         }
@@ -6721,4 +6721,9 @@ export {
   // Manifest utilities (used by tests and external tooling)
   getProjectManifestPath, getGlobalManifestPath,
   loadManifest, saveManifest, computeFileHash, manifestSafeCopy, removeManifestFiles,
+  // Pure helper functions exported for testing
+  isPiperProvider, supportsEmoji, getPersonalityIcon,
+  detectEnvironment, createPageHeaderFooter, buildNavigationChoices, handleNavigationAction, getPageTitle,
+  getUserShell, showWelcome, getReleaseInfoBoxen, generateActivationInstructions,
+  collectConfiguration,
 };

package/src/services/provider-service.js

@@ -132,7 +132,7 @@ export class ProviderService {
    */
   _isAvailable(binary) {
     try {
-      execFileSync('which', [binary], { stdio: 'ignore', timeout: 2000 });
+      execFileSync('which', [binary], { stdio: 'ignore', timeout: 2000 }); // NOSONAR
       return true;
     } catch {
       return false;

package/src/services/tts-engine-service.js

@@ -49,10 +49,10 @@ export function checkEngineInstalled(engineId) {
             (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'AppData', 'Local') : null);
           if (localAppData && fs.existsSync(path.join(localAppData, 'Programs', 'Piper', 'piper.exe'))) return true;
         }
-        execFileSync('where', [binary], { stdio: 'ignore', timeout: 2000 });
+        execFileSync('where', [binary], { stdio: 'ignore', timeout: 2000 }); // NOSONAR
         return true;
       }
-      execFileSync('which', [binary], { stdio: 'ignore', timeout: 2000 });
+      execFileSync('which', [binary], { stdio: 'ignore', timeout: 2000 }); // NOSONAR
       return true;
     } catch {
       // try next binary

package/src/utils/audio-duration-validator.js

@@ -61,7 +61,7 @@ export async function getAudioDuration(filePath) {
       }
 
       // Check if ffprobe is available
-      const checkFFprobe = spawn('which', ['ffprobe']);
+      const checkFFprobe = spawn('which', ['ffprobe']); // NOSONAR
       let ffprobeExists = false;
 
       checkFFprobe.on('close', (code) => {
@@ -78,7 +78,7 @@ export async function getAudioDuration(filePath) {
 
         // Use ffprobe to get duration (part of ffmpeg)
         // SECURITY: Use spawn with args array to prevent command injection
-          const ffprobe = spawn('ffprobe', [
+          const ffprobe = spawn('ffprobe', [ // NOSONAR
           '-v', 'error',
           '-show_entries', 'format=duration',
           '-of', 'default=noprint_wrappers=1:nokey=1',

package/src/utils/list-formatter.js

@@ -71,9 +71,15 @@ export function formatVoicesList(voices, options = {}) {
   } = options;
 
   if (voices.length === 0) {
-    const content = chalk.yellow('No voices found') + '\n\n' +
-      chalk.gray('Download voices with:\n') +
-      chalk.cyan('  /agent-vibes:provider download <voice-name>');
+    const content =
+      chalk.yellow('No voices downloaded yet') + '\n\n' +
+      chalk.white('AgentVibes includes 900+ free voices.\n') +
+      chalk.white('Get started with a default voice:\n\n') +
+      chalk.cyan('  /agent-vibes:add\n\n') +
+      chalk.gray('Or browse the full voice library:\n') +
+      chalk.cyan('  /agent-vibes:list\n\n') +
+      chalk.dim('Piper installed but voices missing? Run:\n') +
+      chalk.dim('  /agent-vibes:provider download en_US-lessac-medium');
 
     return boxen(content, {
       padding: 1,

package/src/utils/platform-resolver.js

@@ -0,0 +1,369 @@
+/**
+ * AgentVibes Cross-Platform Resolver
+ *
+ * Implements the Agent Vibes Cross-Platform Contract v1.0.
+ * Single source of truth for binary resolution, path conventions, and env var interface.
+ *
+ * Resolution order (authoritative):
+ *   1. ENV_OVERRIDE  — AGENTVIBES_*_PATH env var; if invalid, fail HARD (no fallthrough)
+ *   2. which/where   — first result that passes validation
+ *   3. HINT_PATHS    — platform hint list in order; first valid wins
+ *   4. FAIL          — structured error, exit code 2
+ *
+ * Supported platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64
+ * WSL2 is treated as linux-x64.
+ */
+
+import { execFileSync } from 'child_process';
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+
+// ─── Platform Detection ───────────────────────────────────────────────────────
+
+function isWSL() {
+  try {
+    return /microsoft|wsl/i.test(fs.readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the current platform ID.
+ * Set AGENTVIBES_PLATFORM to override (CI / testing only).
+ * @returns {string} One of: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64, unknown
+ */
+export function detectPlatform() {
+  const forced = process.env.AGENTVIBES_PLATFORM;
+  if (forced) return forced;
+
+  const p = process.platform;
+  const arch = process.arch;
+
+  if (p === 'linux' && isWSL()) return arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
+  if (p === 'darwin') return arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  if (p === 'linux') return arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
+  if (p === 'win32') return 'win32-x64';
+  return 'unknown';
+}
+
+// ─── Path Hint Lists (only hardcoded paths in the entire codebase) ────────────
+
+const PIPER_HINTS = {
+  'darwin-arm64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'share', 'pipx', 'venvs', 'piper-tts', 'bin', 'piper'),
+    '/opt/homebrew/bin/piper',
+    '/usr/local/bin/piper',
+  ],
+  'darwin-x64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'share', 'pipx', 'venvs', 'piper-tts', 'bin', 'piper'),
+    '/usr/local/bin/piper',
+    '/opt/homebrew/bin/piper',
+  ],
+  'linux-x64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'share', 'pipx', 'venvs', 'piper-tts', 'bin', 'piper'),
+    '/usr/bin/piper',
+    '/usr/local/bin/piper',
+    '/snap/bin/piper',
+  ],
+  'linux-arm64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'bin', 'piper'),
+    path.join(os.homedir(), '.local', 'share', 'pipx', 'venvs', 'piper-tts', 'bin', 'piper'),
+    '/usr/bin/piper',
+    '/usr/local/bin/piper',
+  ],
+  'win32-x64': () => {
+    const appdata = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    const localappdata = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    const programfiles = process.env.PROGRAMFILES || path.join('C:', 'Program Files');
+    return [
+      path.join(appdata, 'AgentVibes', 'bin', 'piper.exe'),
+      path.join(localappdata, 'AgentVibes', 'bin', 'piper.exe'),
+      path.join(programfiles, 'AgentVibes', 'bin', 'piper.exe'),
+    ];
+  },
+};
+
+const FFMPEG_HINTS = {
+  'darwin-arm64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'ffmpeg'),
+    '/opt/homebrew/bin/ffmpeg',
+    '/usr/local/bin/ffmpeg',
+  ],
+  'darwin-x64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'ffmpeg'),
+    '/usr/local/bin/ffmpeg',
+    '/opt/homebrew/bin/ffmpeg',
+  ],
+  'linux-x64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'ffmpeg'),
+    '/usr/bin/ffmpeg',
+    '/usr/local/bin/ffmpeg',
+  ],
+  'linux-arm64': () => [
+    path.join(os.homedir(), '.agentvibes', 'bin', 'ffmpeg'),
+    '/usr/bin/ffmpeg',
+    '/usr/local/bin/ffmpeg',
+  ],
+  'win32-x64': () => {
+    const appdata = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    const localappdata = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    const programfiles = process.env.PROGRAMFILES || path.join('C:', 'Program Files');
+    return [
+      path.join(appdata, 'AgentVibes', 'bin', 'ffmpeg.exe'),
+      path.join(localappdata, 'AgentVibes', 'bin', 'ffmpeg.exe'),
+      path.join(programfiles, 'ffmpeg', 'bin', 'ffmpeg.exe'),
+    ];
+  },
+};
+
+// Derive ffprobe hints by substituting the binary name in every ffmpeg path.
+// ffprobe is always co-located with ffmpeg so sharing the directory list is correct.
+function deriveBinaryHints(templateHints, binaryName) {
+  const result = {};
+  for (const [plat, fn] of Object.entries(templateHints)) {
+    result[plat] = () => fn().map(p => {
+      const dir = path.dirname(p);
+      const ext = path.extname(p);
+      return path.join(dir, binaryName + ext);
+    });
+  }
+  return result;
+}
+
+const FFPROBE_HINTS = deriveBinaryHints(FFMPEG_HINTS, 'ffprobe');
+
+const BINARY_HINTS = { piper: PIPER_HINTS, ffmpeg: FFMPEG_HINTS, ffprobe: FFPROBE_HINTS };
+
+/** Canonical env var names — only override surface permitted by the contract */
+export const ENV_VARS = {
+  piper: 'AGENTVIBES_PIPER_PATH',
+  ffmpeg: 'AGENTVIBES_FFMPEG_PATH',
+  ffprobe: 'AGENTVIBES_FFPROBE_PATH',
+  config_dir: 'AGENTVIBES_CONFIG_DIR',
+  data_dir: 'AGENTVIBES_DATA_DIR',
+  cache_dir: 'AGENTVIBES_CACHE_DIR',
+  voice_dir: 'AGENTVIBES_VOICE_DIR',
+};
+
+// ─── Binary Validation ────────────────────────────────────────────────────────
+
+/**
+ * Validate that a candidate binary path is a real, executable, working binary.
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateBinary(binaryPath, binaryName) {
+  let stat;
+  try {
+    stat = fs.statSync(binaryPath);
+  } catch {
+    return { valid: false, reason: 'not_found' };
+  }
+
+  if (!stat.isFile()) return { valid: false, reason: 'not_a_file' };
+
+  if (process.platform !== 'win32') {
+    try {
+      fs.accessSync(binaryPath, fs.constants.X_OK);
+    } catch {
+      return { valid: false, reason: 'not_executable' };
+    }
+  }
+
+  // Smoke test: binary must respond to --version (or -version for ffmpeg/ffprobe)
+  const versionFlag = (binaryName === 'ffmpeg' || binaryName === 'ffprobe') ? '-version' : '--version';
+  try {
+    execFileSync(binaryPath, [versionFlag], { stdio: 'pipe', timeout: 3000 });
+    return { valid: true };
+  } catch {
+    return { valid: false, reason: 'version_check_failed' };
+  }
+}
+
+/**
+ * Find binary using which (POSIX) or where (Windows).
+ * Returns the realpath of the first result, or null.
+ */
+export function whichBinary(name) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const result = execFileSync(cmd, [name], { encoding: 'utf8', stdio: 'pipe', timeout: 3000 });
+    const first = result.trim().split('\n')[0].trim();
+    if (!first) return null;
+    // Resolve symlinks to get the real binary path
+    return fs.realpathSync(first);
+  } catch {
+    return null;
+  }
+}
+
+// ─── Binary Resolution (4-step contract) ─────────────────────────────────────
+
+/**
+ * Resolve a binary following the contract resolution order.
+ * Throws a structured error if resolution fails.
+ *
+ * @param {'piper'|'ffmpeg'|'ffprobe'} binaryName
+ * @returns {{ path: string, source: string }}
+ */
+export function resolveBinary(binaryName) {
+  const platformId = detectPlatform();
+  const envVar = ENV_VARS[binaryName];
+  const tried = [];
+
+  // Step 1: ENV_OVERRIDE — if set, it's absolute. Invalid = hard fail, no fallthrough.
+  if (envVar && process.env[envVar]) {
+    const overridePath = process.env[envVar];
+    const validation = validateBinary(overridePath, binaryName);
+    tried.push({ step: 'ENV_OVERRIDE', path: overridePath, ...validation });
+    if (!validation.valid) {
+      const err = new Error(
+        `[AgentVibes] RESOLUTION_FAILURE\n` +
+        `  binary:   ${binaryName}\n` +
+        `  error:    ENV_OVERRIDE_INVALID\n` +
+        `  platform: ${platformId}\n` +
+        `  ${envVar}=${overridePath} (${validation.reason})\n` +
+        `  fix:      Correct the ${envVar} environment variable or unset it`
+      );
+      err.code = 'ENV_OVERRIDE_INVALID';
+      err.tried = tried;
+      throw err;
+    }
+    return { path: overridePath, source: 'env_override' };
+  }
+  tried.push({ step: 'ENV_OVERRIDE', path: 'not set' });
+
+  // Step 2: which/where — respect what the user already has configured
+  const whichResult = whichBinary(binaryName);
+  if (whichResult) {
+    const validation = validateBinary(whichResult, binaryName);
+    tried.push({ step: 'WHICH', path: whichResult, ...validation });
+    if (validation.valid) {
+      return { path: whichResult, source: 'which' };
+    }
+    // Exists in PATH but failed validation — log and continue to hints
+  } else {
+    tried.push({ step: 'WHICH', path: 'not found' });
+  }
+
+  // Step 3: Platform hint list — last resort before failure
+  const hintFn = BINARY_HINTS[binaryName]?.[platformId];
+  if (hintFn) {
+    const hints = hintFn();
+    for (let i = 0; i < hints.length; i++) {
+      const hintPath = hints[i];
+      const validation = validateBinary(hintPath, binaryName);
+      tried.push({ step: `HINT[${i}]`, path: hintPath, ...validation });
+      if (validation.valid) {
+        return { path: hintPath, source: `hint[${i}]` };
+      }
+    }
+  }
+
+  // Step 4: FAIL — structured error with full audit trail
+  const triedFormatted = tried
+    .map(t => `    - ${t.step.padEnd(12)}: ${t.path}${t.reason ? ` → ${t.reason}` : ''}`)
+    .join('\n');
+  const err = new Error(
+    `[AgentVibes] RESOLUTION_FAILURE\n` +
+    `  binary:   ${binaryName}\n` +
+    `  error:    BINARY_NOT_FOUND\n` +
+    `  platform: ${platformId}\n` +
+    `  tried:\n${triedFormatted}\n` +
+    `  fix:      Install ${binaryName} or set ${envVar} to the binary path`
+  );
+  err.code = 'BINARY_NOT_FOUND';
+  err.binary = binaryName;
+  err.platform = platformId;
+  err.tried = tried;
+  throw err;
+}
+
+// ─── Directory Resolution ─────────────────────────────────────────────────────
+
+/**
+ * Resolve the voice model directory (never contains tilde on return).
+ * Windows: %LOCALAPPDATA%\AgentVibes\voices
+ * POSIX: $XDG_DATA_HOME/agentvibes/voices or ~/.local/share/agentvibes/voices
+ */
+export function resolveVoiceDir() {
+  const override = process.env[ENV_VARS.voice_dir];
+  if (override) return path.resolve(override);
+  return path.join(resolveDataDir(), 'voices');
+}
+
+/**
+ * Resolve the data directory.
+ * Uses LOCALAPPDATA on Windows, XDG_DATA_HOME or ~/.local/share on POSIX.
+ */
+export function resolveDataDir() {
+  const override = process.env[ENV_VARS.data_dir];
+  if (override) return path.resolve(override);
+
+  const platformId = detectPlatform();
+  if (platformId === 'win32-x64') {
+    const localappdata = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(localappdata, 'AgentVibes');
+  }
+  const xdgData = process.env.XDG_DATA_HOME;
+  if (xdgData) return path.join(xdgData, 'agentvibes');
+  return path.join(os.homedir(), '.local', 'share', 'agentvibes');
+}
+
+/**
+ * Resolve the config directory.
+ * Uses APPDATA on Windows, XDG_CONFIG_HOME or ~/.config on POSIX.
+ */
+export function resolveConfigDir() {
+  const override = process.env[ENV_VARS.config_dir];
+  if (override) return path.resolve(override);
+
+  const platformId = detectPlatform();
+  if (platformId === 'win32-x64') {
+    const appdata = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    return path.join(appdata, 'AgentVibes');
+  }
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
+  if (xdgConfig) return path.join(xdgConfig, 'agentvibes');
+  return path.join(os.homedir(), '.config', 'agentvibes');
+}
+
+// ─── PATH Augmentation Helper ─────────────────────────────────────────────────
+
+/**
+ * Return extra PATH directories for the current platform.
+ * MCP servers launched by Claude Desktop inherit a sanitized PATH that omits
+ * Homebrew (Mac) and pipx (POSIX) locations — this list covers those gaps.
+ * Never includes directories already on PATH.
+ * @returns {string[]} List of absolute directory paths
+ */
+export function getPathAugmentation() {
+  const platformId = detectPlatform();
+  const extra = [];
+
+  if (platformId === 'darwin-arm64') {
+    extra.push('/opt/homebrew/bin', '/usr/local/bin');
+  } else if (platformId === 'darwin-x64') {
+    extra.push('/usr/local/bin', '/opt/homebrew/bin');
+  }
+  // Linux/WSL: ~/.local/bin is the only reliable extra location
+  if (platformId === 'linux-x64' || platformId === 'linux-arm64') {
+    extra.push(path.join(os.homedir(), '.local', 'bin'));
+  }
+  // pipx venv — all POSIX platforms
+  if (platformId !== 'win32-x64') {
+    extra.push(path.join(os.homedir(), '.local', 'share', 'pipx', 'venvs', 'piper-tts', 'bin'));
+    extra.push(path.join(os.homedir(), '.local', 'bin'));
+  }
+
+  // Deduplicate, preserving order
+  return [...new Set(extra)];
+}