agentvibes 5.12.0 → 5.13.1

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

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

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

@@ -8,11 +8,19 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { destroyList } from './destroy-list.js';
 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 { playBlingCue } from '../bling.js';
+
+// AgentVibes package/repo root — resolves bundled assets (bling cue) and is the
+// package fallback when resolving the active provider for remote forwarding.
+const _WIDGET_DIR = path.dirname(fileURLToPath(import.meta.url));
+const _PKG_ROOT = path.resolve(_WIDGET_DIR, '..', '..', '..');
 
 const IS_TEST = process.env.AGENTVIBES_TEST_MODE === 'true';
 let blessed;
@@ -237,6 +245,10 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
   const _spawnEnv = buildAudioEnv();
   let _previewProc = null;
   let _previewTrackId = null;
+  // Remote playback is fire-and-forget (the local sender exits in ms while the
+  // receiver keeps playing), so the toggle tracks the intended remote track
+  // here rather than relying on a live local process.
+  let _remotePreviewTrackId = null;
 
   function _killPreview() {
     if (_previewProc) {
@@ -244,9 +256,75 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
       _previewProc = null;
     }
     _previewTrackId = null;
+    // Stop any remote preview so closing/selecting doesn't leave music playing
+    // on the receiver (the local equivalent of killing the player process).
+    if (_remotePreviewTrackId) {
+      const mp = resolveMusicProvider(_PKG_ROOT);
+      if (mp.remote) _sendRemote(mp, { stop: true });
+      _remotePreviewTrackId = null;
+    }
+  }
+
+  /**
+   * Forward a music track to the receiver (or stop it), mirroring the Music
+   * tab's remote-preview behavior. Fire-and-forget; UI errors surface in the
+   * title status area. Returns true if the send was launched.
+   * @param {{remote:boolean, projectDir:string}} mp
+   * @param {{track?:string, stop?:boolean}} opts
+   */
+  function _sendRemote(mp, { track = null, stop = false } = {}) {
+    let proc;
+    try {
+      proc = spawnMusicRemote({ packageRoot: _PKG_ROOT, projectDir: mp.projectDir, env: _spawnEnv, track, stop });
+    } catch {
+      if (!stop) {
+        _setStatus(' {red-fg}Remote preview failed{/red-fg} ');
+        setTimeout(() => { _setStatus(); }, 4000);
+      }
+      return false;
+    }
+    let _rerr = '';
+    if (proc.stderr) proc.stderr.on('data', d => { _rerr += d.toString(); });
+    proc.on('exit', (code) => {
+      if (stop || code === 0) return;
+      if (_remotePreviewTrackId === track) _remotePreviewTrackId = null;
+      const msg = _rerr.trim().split('\n').pop() || 'Remote preview failed';
+      _setStatus(` {red-fg}♪ ${msg}{/red-fg} `);
+      setTimeout(() => { _setStatus(); }, 4000);
+    });
+    proc.on('error', () => {
+      if (stop) return;
+      if (_remotePreviewTrackId === track) _remotePreviewTrackId = null;
+      _setStatus(' {red-fg}Remote preview failed{/red-fg} ');
+      setTimeout(() => { _setStatus(); }, 4000);
+    });
+    return true;
   }
 
   function _previewTrack(trackFile) {
+    // Transport provider: forward to the receiver instead of local playback
+    // (which is silent on a headless box) — parity with the Music tab.
+    const _mp = resolveMusicProvider(_PKG_ROOT);
+    if (_mp.remote) {
+      // Toggle off if same track → explicit music-stop signal
+      if (_remotePreviewTrackId === trackFile) {
+        _sendRemote(_mp, { stop: true });
+        _remotePreviewTrackId = null;
+        _setStatus();
+        return;
+      }
+      // Bling first (fire-and-forget, plays locally like the voice preview),
+      // then forward the track to the receiver.
+      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} `);
+      }
+      return;
+    }
+
+    // ── Local playback ──────────────────────────────────────────────────────
     // Toggle off if same track
     if (_previewTrackId === trackFile) {
       _killPreview();
@@ -266,6 +344,10 @@ export function openTrackPicker(screen, currentTrack, currentVolume, onSelect, o
       return;
     }
 
+    // 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) {
       _setStatus(' {red-fg}No MP3 player found{/red-fg} ');

package/src/installer.js

@@ -141,6 +141,33 @@ async function saveManifest(manifestPath, files) {
 //   • dest hash == manifest hash       → copy  (action: 'updated')
 //   • dest hash != manifest hash       → skip  (action: 'skipped', .user.bak saved)
 //   • no manifest entry yet            → copy  (action: 'updated')
+// Preserve destPath's CURRENT content in a sidecar backup before anything
+// overwrites it. Never clobbers an existing .user.bak — that backup may hold the
+// only surviving copy of an earlier customization; a second backup gets a
+// content-stamped name instead. Returns true only when the current content is
+// safely stored somewhere, so callers can refuse to overwrite when it isn't.
+async function backupUserFile(destPath) {
+  const bak = `${destPath}.user.bak`;
+  try {
+    const currentHash = await computeFileHash(destPath);
+    if (!currentHash) return false;
+
+    const existingHash = await computeFileHash(bak);
+    if (existingHash === currentHash) return true; // already backed up
+
+    if (existingHash) {
+      // A different backup exists — keep it and stamp this one.
+      await fs.copyFile(destPath, `${destPath}.user.bak.${currentHash.slice(0, 8)}`);
+      return true;
+    }
+
+    await fs.copyFile(destPath, bak);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function manifestSafeCopy(srcPath, destPath, manifest) {
   const srcHash = await computeFileHash(srcPath);
   if (!srcHash) return { action: 'skipped', hash: null }; // src missing
@@ -157,15 +184,29 @@ async function manifestSafeCopy(srcPath, destPath, manifest) {
   }
 
   const manifestHash = manifest[destPath]?.hash;
-  if (manifestHash && destHash !== manifestHash) {
-    // User modified the file since we last installed it — preserve it
-    try { await fs.copyFile(destPath, destPath + '.user.bak'); } catch { /* best effort */ }
-    return { action: 'skipped', hash: destHash };
+
+  if (manifestHash) {
+    if (destHash !== manifestHash) {
+      // User modified the file since we last installed it — preserve it
+      await backupUserFile(destPath);
+      return { action: 'skipped', hash: destHash };
+    }
+    // Byte-identical to what we last installed — untouched, ours to update
+    await fs.copyFile(srcPath, destPath);
+    return { action: 'updated', hash: srcHash };
   }
 
-  // Stock file (or no manifest entry yet) — safe to overwrite
+  // No manifest entry, and dest differs from what we ship. This is either a
+  // user's customized file or an older stock copy predating the manifest — the
+  // two are indistinguishable, so we must assume it could be a customization.
+  // Back it up before overwriting, and if the backup can't be secured, refuse
+  // to overwrite at all rather than destroy the only copy.
+  // (CLAUDE.md: never overwrite existing user .claude/ config.)
+  if (!(await backupUserFile(destPath))) {
+    return { action: 'skipped', hash: destHash };
+  }
   await fs.copyFile(srcPath, destPath);
-  return { action: 'updated', hash: srcHash };
+  return { action: 'updated', hash: srcHash, backedUp: true };
 }
 
 // Delete only the files listed in manifest that reside under baseDir.
@@ -3593,14 +3634,17 @@ async function copyCommandFiles(targetDir, spinner) {
  */
 function shouldIncludeHookFile(file, stat) {
   if (isNativeWindows()) {
-    // Include .ps1 scripts, .py helpers, and hooks.json; exclude dotfiles and prepare-release
+    // Include .ps1 scripts, .py helpers, hooks.json, and the generated
+    // provider-catalog.json; exclude dotfiles and prepare-release
     return stat.isFile() &&
-           (file.endsWith('.ps1') || file.endsWith('.py') || file === 'hooks.json') &&
+           (file.endsWith('.ps1') || file.endsWith('.py') || file === 'hooks.json' ||
+            file === 'provider-catalog.json') &&
            !file.includes('prepare-release') &&
            !file.startsWith('.');
   }
   return stat.isFile() &&
-         (file.endsWith('.sh') || file.endsWith('.py') || file === 'hooks.json') &&
+         (file.endsWith('.sh') || file.endsWith('.py') || file === 'hooks.json' ||
+          file === 'provider-catalog.json') &&
          !file.includes('prepare-release') &&
          !file.startsWith('.');
 }
@@ -5606,10 +5650,14 @@ async function performUpdateOperations(targetDir, spinner) {
     console.log(chalk.green(`✓ Updated ${resolverResult.count} resolver bundle files`));
   }
 
-  // Also update critical hooks in global ~/.claude/hooks/ if present (fixes stale installs)
-  const hooksSubdir = isNativeWindows() ? 'hooks-windows' : 'hooks';
-  const srcHooksDir = path.join(__dirname, '..', '.claude', hooksSubdir);
-  const globalHooksUpdated = await updateGlobalHooks(srcHooksDir);
+  // Also update critical hooks in global ~/.claude/hooks/ if present (fixes stale installs).
+  // ALWAYS pass the unix hooks dir: updateGlobalHooks copies CRITICAL_HOOKS (all .sh)
+  // from here and derives hooks-windows itself for CRITICAL_HOOKS_WINDOWS. Passing
+  // hooks-windows on Windows made every .sh lookup miss and hit the "src missing"
+  // catch, so ~/.claude/hooks/*.sh — which git-bash hooks actually execute on
+  // Windows — silently never updated (installs stayed frozen at their first version).
+  const srcGlobalHooksDir = path.join(__dirname, '..', '.claude', 'hooks');
+  const globalHooksUpdated = await updateGlobalHooks(srcGlobalHooksDir);
   if (globalHooksUpdated > 0) {
     console.log(chalk.green(`✓ Updated ${globalHooksUpdated} critical scripts in ~/.claude/hooks/`));
   }
@@ -5668,6 +5716,16 @@ async function performUpdateOperations(targetDir, spinner) {
   spinner.text = 'Checking for old configuration...';
   await detectAndMigrateOldConfig(targetDir, spinner);
 
+  // Upgrade safety for the new opt-in injection gate (session-start-tts.sh):
+  // a project that was already installed and talking pre-gate has no marker, so
+  // the gate would newly silence it. Backfill the enable marker for a PROJECT
+  // update so existing users keep their audio. A GLOBAL (home-dir) update stays
+  // opt-in — and we say so, otherwise the user's voice just stops with no clue.
+  if ((await configureInjectionScope(targetDir)) === 'global') {
+    console.log('');
+    warnGlobalInjectionScope();
+  }
+
   return {
     commandCount,
     hookCount: hookResult.count,
@@ -5721,6 +5779,61 @@ async function updateAgentVibes(targetDir, options) {
   }
 }
 
+/**
+ * Configure the session-start injection opt-in marker for this install/update.
+ *
+ * - PROJECT install → drop `.claude/agentvibes-enabled` so session-start-tts.sh
+ *   injects the TTS protocol for THIS project (and only this one), preserving the
+ *   "install in a project and it just works" experience.
+ * - GLOBAL install (target === home dir) → write nothing; injecting into every
+ *   session is exactly the "cacophony of agents" we are preventing.
+ *
+ * Uses `agentvibes-enabled`, NOT `agentvibes-unmuted`, on purpose: the unmuted
+ * marker OVERRIDES a global mute in play-tts.sh, so writing it here would let an
+ * install/update silently defeat a user's `~/.agentvibes-muted` kill-switch.
+ * Non-destructive: never touches an existing mute/unmute/enabled choice.
+ *
+ * @param {string} targetDir - install target
+ * @returns {Promise<'global'|'enabled'|'kept'|'error'>} what happened (for messaging)
+ */
+async function configureInjectionScope(targetDir) {
+  try {
+    // path.relative is case-insensitive on win32 and normalizes separators, so a
+    // lowercase drive letter or trailing slash no longer misdetects a home
+    // install; realpath (best-effort) also collapses a symlinked $HOME.
+    let resolvedTarget = path.resolve(targetDir);
+    let resolvedHome = path.resolve(os.homedir());
+    try { resolvedTarget = fsSync.realpathSync.native(resolvedTarget); } catch { /* dir may not exist yet */ }
+    try { resolvedHome = fsSync.realpathSync.native(resolvedHome); } catch { /* ignore */ }
+    if (path.relative(resolvedHome, resolvedTarget) === '') return 'global';
+
+    const claudeDir = path.join(targetDir, '.claude');
+    // Respect any prior explicit choice — enabled OR either mute/unmute marker.
+    for (const m of ['agentvibes-enabled', 'agentvibes-unmuted', 'agentvibes-muted']) {
+      if (await fs.access(path.join(claudeDir, m)).then(() => true).catch(() => false)) {
+        return 'kept';
+      }
+    }
+    await fs.mkdir(claudeDir, { recursive: true });
+    await fs.writeFile(path.join(claudeDir, 'agentvibes-enabled'), '', 'utf8');
+    return 'enabled';
+  } catch (err) {
+    // Never fail install/update over the marker, but don't swallow silently —
+    // a read-only FS here would otherwise produce a mysterious "silent" project.
+    console.log(chalk.gray(`   (Could not set TTS injection marker: ${err.code || err.message}. Run /agent-vibes:unmute to enable.)`));
+    return 'error';
+  }
+}
+
+// Print the "global install stays silent" guidance (shared by install + update).
+function warnGlobalInjectionScope() {
+  console.log(chalk.yellow.bold('  ⚠  Global install detected (installed at your home directory)'));
+  console.log(chalk.gray('     TTS stays OFF by default so it will NOT talk in every session at once.'));
+  console.log(chalk.gray('     Enable it in a specific project with:  ') + chalk.cyan('/agent-vibes:unmute'));
+  console.log(chalk.gray('     (or re-run the installer inside a project folder, not your home dir).'));
+  console.log('');
+}
+
 // Installation function
 async function install(options = {}) {
   const currentDir = process.env.INIT_CWD || process.cwd();
@@ -5842,10 +5955,10 @@ async function install(options = {}) {
     await copyCodexFiles(targetDir, silentSpinner);
 
     // Populate global ~/.claude/hooks[/-windows]/ so $HOME hook paths resolve
-    // on first install (not just on update).
-    const hooksSubdirInstall = isNativeWindows() ? 'hooks-windows' : 'hooks';
-    const srcHooksDirInstall = path.join(__dirname, '..', '.claude', hooksSubdirInstall);
-    await updateGlobalHooks(srcHooksDirInstall);
+    // on first install (not just on update). Always the unix hooks dir — see the
+    // note in the update path; updateGlobalHooks derives hooks-windows itself.
+    const srcGlobalHooksDirInstall = path.join(__dirname, '..', '.claude', 'hooks');
+    await updateGlobalHooks(srcGlobalHooksDirInstall);
     // Populate global ~/.claude/ resolver bundle too, same reasoning as above (AVI-S8.5 Stage 2)
     await updateGlobalResolverBundle();
 
@@ -6243,6 +6356,11 @@ def _strip_markdown(text: str) -> str:
     console.log(chalk.magenta('  \u2661  Sponsor this Developer  github.com/sponsors/paulpreibisch'));
     console.log('');
 
+    // Opt-in injection marker (prevents the global-install cacophony). See
+    // configureInjectionScope: project installs enable THIS project; a home-dir
+    // install stays silent. Uses agentvibes-enabled so it can't override a global mute.
+    if ((await configureInjectionScope(targetDir)) === 'global') warnGlobalInjectionScope();
+
     if (!(options.nonInteractive || process.env.AGENT_VIBES_NON_INTERACTIVE === '1')) {
       // Clean final summary
       console.log('');
@@ -6997,7 +7115,7 @@ export {
   CRITICAL_HOOKS, CRITICAL_HOOKS_WINDOWS,
   // Manifest utilities (used by tests and external tooling)
   getProjectManifestPath, getGlobalManifestPath,
-  loadManifest, saveManifest, computeFileHash, manifestSafeCopy, removeManifestFiles,
+  loadManifest, saveManifest, computeFileHash, manifestSafeCopy, backupUserFile, removeManifestFiles,
   // Pure helper functions exported for testing
   readJsonConfigSafe, backupConfigFile,
   isPiperProvider, supportsEmoji, getPersonalityIcon,