verbalcoding 0.2.11 → 0.2.13

package/app-node/utterance_router.mjs

@@ -0,0 +1,216 @@
+// Voice utterance dispatch chain: tts/lang/clone command handlers,
+// routing state, adapter selection, and barge-in interrupt. handleRecording
+// (Phase 7a) and plan-mode dispatch (Phase 7b) moved out to their own
+// modules — this module is now pure command dispatch.
+//
+// createUtteranceRouter(deps) returns the small handlers main.mjs and
+// voice_turn_runner consume.
+
+export function createUtteranceRouter(deps) {
+  const {
+    bridge,
+    log,
+    warn,
+    agentAdapter,
+    settings,
+    projectSessionContextText,
+    createBridgeAgentAdapter,
+    buildAgentSettings,
+    commandIsInstalled,
+    shellSplit,
+    sendText,
+    speakText,
+    TTS_VOICE_CONFIG_PATH,
+    ensureTtsVoiceConfig,
+    updateTtsVoiceConfig,
+    writeTtsVoiceConfig,
+    applyVoiceConfigToProcessEnv,
+    ensureSelectedTtsBackendInstalled,
+    rebuildTtsRuntimeSettings,
+    voiceCommandFromTranscript,
+    voiceChangedText,
+    voiceLanguageCommandFromTranscript,
+    voiceCloneCommandFromText,
+    voiceCloneCapture,
+    notifyVoiceCloneSampleGapIfNeeded,
+    languageChangedText,
+    applyRuntimeLanguage,
+    persistEnvValues,
+    discardVoiceInputQueues,
+    path,
+    ROOT,
+  } = deps;
+
+function adapterForProjectSession(session) {
+  if (!session) return agentAdapter;
+  const key = session.slug || session.name;
+  if (!bridge.agentAdaptersBySession.has(key)) {
+    bridge.agentAdaptersBySession.set(key, createBridgeAgentAdapter({
+      ...settings.agent,
+      label: `${settings.agent.label} · ${session.name}`,
+      sessionFile: session.sessionFile,
+      cwd: session.workdir,
+      projectContext: projectSessionContextText(session),
+    }));
+  }
+  return bridge.agentAdaptersBySession.get(key);
+}
+
+function routingStateFor(channelKey) {
+  const key = String(channelKey || 'default');
+  let state = bridge.routingStateByChannel.get(key);
+  if (!state) {
+    state = {
+      activeRouting: { backend: settings.agent.backend, sticky: false },
+      lastUsedBackend: settings.agent.backend,
+      lastResolvedDecisions: {},
+      pendingFallbackPrompt: null,
+      recentUtterances: [],
+    };
+    bridge.routingStateByChannel.set(key, state);
+  }
+  return state;
+}
+
+function recordUtterance(channelKey, text) {
+  if (!text) return;
+  const state = routingStateFor(channelKey);
+  state.recentUtterances.push(text);
+  while (state.recentUtterances.length > 4) state.recentUtterances.shift();
+}
+
+function clearTransientRouting(channelKey) {
+  const state = routingStateFor(channelKey);
+  state.pendingFallbackPrompt = null;
+  if (!state.activeRouting?.sticky) {
+    state.activeRouting = { backend: settings.agent.backend, sticky: false };
+  }
+}
+
+function adapterForBackend(backend, session = null) {
+  const normalized = String(backend || '').toLowerCase();
+  if (!normalized || normalized === settings.agent.backend) {
+    return session ? adapterForProjectSession(session) : agentAdapter;
+  }
+  const key = `${normalized}::${session ? (session.slug || session.name) : '_default'}`;
+  if (bridge.agentAdaptersByBackend.has(key)) return bridge.agentAdaptersByBackend.get(key);
+  let routedSettings;
+  try {
+    const scrubbed = { ...process.env };
+    for (const key of ['AGENT_BACKEND', 'AGENT_LABEL', 'AGENT_COMMAND', 'AGENT_SESSION_FILE']) {
+      delete scrubbed[key];
+    }
+    scrubbed.AGENT_BACKEND = normalized;
+    routedSettings = buildAgentSettings({
+      ROOT: settings.agent.cwd || process.cwd(),
+      env: scrubbed,
+    });
+  } catch (e) {
+    warn(`adapterForBackend: cannot build settings for ${normalized}: ${e?.message || e}`);
+    return null;
+  }
+  if (session) {
+    routedSettings = {
+      ...routedSettings,
+      label: `${routedSettings.label} · ${session.name}`,
+      sessionFile: session.sessionFile,
+      cwd: session.workdir || routedSettings.cwd,
+      projectContext: projectSessionContextText(session),
+    };
+  }
+  const argv = shellSplit(String(routedSettings.command || ''));
+  const binary = argv[0];
+  if (binary && !commandIsInstalled(binary, { cwd: routedSettings.cwd || settings.agent.cwd || process.cwd() })) {
+    warn(`adapterForBackend: ${normalized} binary not found on PATH: ${binary}`);
+    return null;
+  }
+  const adapter = createBridgeAgentAdapter(routedSettings);
+  bridge.agentAdaptersByBackend.set(key, adapter);
+  return adapter;
+}
+
+async function handleTtsVoiceCommand(prompt, signal) {
+  const request = voiceCommandFromTranscript(prompt);
+  if (!request) return false;
+  discardVoiceInputQueues('voice-change');
+  let config = ensureTtsVoiceConfig();
+  config = updateTtsVoiceConfig(config, request);
+  writeTtsVoiceConfig(TTS_VOICE_CONFIG_PATH, config);
+  const { selection } = applyVoiceConfigToProcessEnv(config);
+  await ensureSelectedTtsBackendInstalled(selection, signal);
+  rebuildTtsRuntimeSettings(selection);
+  if (selection.voice?.language) settings.voiceLanguage = selection.voice.language;
+  persistEnvValues({
+    TTS_BACKEND: selection.backend,
+    TTS_VOICE_TYPE: selection.voiceType,
+    TTS_VOICE: selection.backend === 'edge' ? selection.voice.voice : process.env.TTS_VOICE,
+    VOICE_LANGUAGE: settings.voiceLanguage,
+    MLXAUDIO_PYTHON: selection.backend === 'mlxaudio' ? (process.env.MLXAUDIO_PYTHON || './.venv-mlxaudio/bin/python') : process.env.MLXAUDIO_PYTHON,
+    MLXAUDIO_VOICE: selection.backend === 'mlxaudio' ? (process.env.MLXAUDIO_VOICE || selection.voice?.voice) : process.env.MLXAUDIO_VOICE,
+    FIREREDTTS2_COMMAND: selection.backend === 'fireredtts2' ? (process.env.FIREREDTTS2_COMMAND || './.local/bin/fireredtts2') : process.env.FIREREDTTS2_COMMAND,
+    FIREREDTTS2_PRETRAINED_DIR: selection.backend === 'fireredtts2' ? (process.env.FIREREDTTS2_PRETRAINED_DIR || 'pretrained_models/FireRedTTS2') : process.env.FIREREDTTS2_PRETRAINED_DIR,
+  });
+  await speakText(voiceChangedText(selection), signal);
+  notifyVoiceCloneSampleGapIfNeeded(selection, signal).catch(e => warn('voice clone gap notice failed', e?.message || e));
+  return true;
+}
+
+async function handleLanguageCommand(prompt, signal) {
+  const request = voiceLanguageCommandFromTranscript(prompt);
+  if (!request) return false;
+  const preset = applyRuntimeLanguage(request.language);
+  await speakText(languageChangedText(preset), signal);
+  return true;
+}
+
+async function handleVoiceCloneCommand(userId, prompt, signal = null) {
+  const command = voiceCloneCommandFromText(prompt);
+  if (!command) return false;
+  if (command.action === 'cancel') {
+    const cancelled = voiceCloneCapture.cancel(userId);
+    await sendText(cancelled ? '🎙️ 보이스 클로닝 샘플 캡처를 취소했어.' : '🎙️ 대기 중인 보이스 클로닝 샘플 캡처가 없어.');
+    await speakText(cancelled ? '목소리 샘플 녹음 대기를 취소했어.' : '대기 중인 목소리 샘플 녹음은 없어.', signal);
+    return true;
+  }
+  if (command.action === 'status') {
+    const current = voiceCloneCapture.current();
+    const status = current?.userId === String(userId)
+      ? `🎙️ 다음 유효한 음성을 ${path.relative(ROOT, current.targetPath)}에 저장할게.`
+      : '🎙️ 지금 대기 중인 보이스 클로닝 샘플 캡처는 없어.';
+    await sendText(status);
+    await speakText(current?.userId === String(userId) ? '다음에 말하는 목소리를 샘플로 저장할게.' : '대기 중인 목소리 샘플 녹음은 없어.', signal);
+    return true;
+  }
+  const armed = voiceCloneCapture.arm({ userId, source: 'voice-command' });
+  await sendText(`🎙️ 보이스 클로닝 샘플 캡처 대기 중. 다음 10초에서 30초 정도 말하면 ${path.relative(ROOT, armed.targetPath)}에 저장할게.`);
+  await speakText('좋아. 다음에 10초에서 30초 정도 말하면 그 음성을 목소리 샘플로 저장할게.', signal);
+  return true;
+}
+
+function interruptCurrentResponse(userId, reason = 'barge-in') {
+  if (!bridge.speaking && !bridge.processing) return false;
+  const turnId = bridge.activeTurnId;
+  if (turnId) bridge.interruptedTurns.add(turnId);
+  log('interrupt current response', 'byUser', userId, 'reason', reason, 'speaking', bridge.speaking, 'processing', bridge.processing, 'turn', turnId);
+  if (bridge.currentAbortController && !bridge.currentAbortController.signal.aborted) {
+    try { bridge.currentAbortController.abort(); } catch (e) { warn('abort current response failed', e?.stack || e); }
+  }
+  try { bridge.player.stop(true); } catch (e) { warn('stop playback failed', e?.stack || e); }
+  bridge.speaking = false;
+  bridge.processing = false;
+  return true;
+}
+
+  return {
+
+    adapterForProjectSession,
+    routingStateFor,
+    recordUtterance,
+    clearTransientRouting,
+    adapterForBackend,
+    handleTtsVoiceCommand,
+    handleLanguageCommand,
+    handleVoiceCloneCommand,
+    interruptCurrentResponse,
+  };
+}

package/app-node/utterance_router.test.mjs

@@ -0,0 +1,236 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createUtteranceRouter } from './utterance_router.mjs';
+import { createBridge } from './bridge_context.mjs';
+import { createAgentTurnLifecycle } from './agent_turn.mjs';
+
+function noop() {}
+async function noopAsync() {}
+
+function makeDeps(overrides = {}) {
+  const bridge = createBridge();
+  // handleRecording's finally block touches bridge.bridgeState.deferredSize();
+  // give the tests a minimal stub so the cleanup path doesn't NPE.
+  bridge.bridgeState = {
+    deferredSize: () => 0,
+    currentEpoch: () => 1,
+    discardQueues: () => 0,
+  };
+  const agentTurnLifecycle = createAgentTurnLifecycle({ bridge, warn: noop });
+  const agentAdapter = {
+    label: 'default-agent',
+    backend: 'hermes',
+    readSessionId: () => null,
+    ask: async () => 'mock agent answer',
+  };
+  return {
+    bridge,
+    agentTurnLifecycle,
+    log: noop, warn: noop, path: { join: (...a) => a.join('/') }, fs: { rm: (_p, _o, cb) => cb && cb() },
+    ROOT: '/tmp/vc', TTS_VOICE_CONFIG_PATH: '/tmp/voices.json',
+    agentAdapter,
+    settings: {
+      voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' }, tts: {},
+    },
+    isPlanEntryUtterance: () => false,
+    parsePlanOutput: () => ({ steps: [], decisions: [] }),
+    parsePlanVoiceCommand: () => ({ type: 'unknown' }),
+    applyPlanCommand: state => state,
+    renderFinalPlan: () => '',
+    planModePreamble: () => '',
+    planExecutionPreamble: () => '',
+    parseDecisionAnswer: () => ({ type: 'unknown' }),
+    renderDecisionPrompt: d => d?.text || '',
+    renderResolvedDecisions: () => '',
+    isAgentRoutingDecision: () => false,
+    projectSessionContextText: () => '',
+    resolveProjectSessionForChannel: () => null,
+    createBridgeAgentAdapter: s => ({ label: s?.label || 'fake', backend: s?.backend || 'hermes', ask: async () => '' }),
+    buildAgentSettings: () => ({ backend: 'hermes', label: 'hermes' }),
+    commandIsInstalled: async () => true,
+    shellSplit: s => String(s).split(' '),
+    sendText: noopAsync, speakText: noopAsync,
+    ensureTtsVoiceConfig: () => ({ backends: {} }),
+    updateTtsVoiceConfig: c => c,
+    writeTtsVoiceConfig: noop,
+    applyVoiceConfigToProcessEnv: () => ({ selection: { backend: 'edge', voiceType: 'female', voice: { language: 'ko', voice: 'ko-KR-SunHiNeural' } } }),
+    ensureSelectedTtsBackendInstalled: noopAsync,
+    rebuildTtsRuntimeSettings: noop,
+    voiceCommandFromTranscript: () => null,
+    voiceChangedText: () => 'changed',
+    voiceLanguageCommandFromTranscript: () => null,
+    voiceCloneCommandFromText: () => null,
+    voiceCloneCapture: { arm: () => ({ targetPath: '/tmp/sample.wav' }), cancel: () => false, current: () => null },
+    notifyVoiceCloneSampleGapIfNeeded: noopAsync,
+    languageChangedText: () => 'language',
+    applyRuntimeLanguage: noop,
+    persistEnvValues: noop,
+    discardVoiceInputQueues: () => 0,
+    // Phase 4b deps for handleRecording
+    transcribe: async () => 'hey hermes do a thing',
+    beginStreamingTurn: () => false,
+    endStreamingTurn: noopAsync,
+    client: { channels: { cache: new Map() } },
+    isAllowed: () => true,
+    isAbortError: e => e?.name === 'AbortError',
+    sleep: async () => {},
+    sendEmbed: async () => true,
+    speakImmediateNotice: noopAsync,
+    reloadRuntimeLanguageFromEnv: () => ({ changed: false, voiceLanguage: 'ko', whisperLanguage: 'ko' }),
+    drainDeferredProcessingUtterances: noopAsync,
+    maybeNotifyTaskComplete: noopAsync,
+    ontologyStateFor: () => ({ nodeCount: 0, serializeForHandoff: () => '' }),
+    captureOntologyFromTurn: noop,
+    queueProgressSpeechText: noop,
+    stopProgressSpeech: noop,
+    agentAnswerHeader: () => 'agent says:',
+    emptyAgentAnswer: () => '(empty)',
+    formatRecentDiscordContext: () => '',
+    formatSttResultMessage: (_lang, _uid, text) => `you said: ${text}`,
+    formatSttStartMessage: () => '🎧 listening',
+    formatVoiceErrorMessage: (_lang, msg) => `error: ${msg}`,
+    formatWakeRejectedMessage: () => 'no wake word',
+    spokenResultOnly: (_p, answer) => answer,
+    stripWake: t => t,
+    acceptsWake: () => true,
+    sensitivityChangedSpeech: () => 'sensitivity set',
+    sensitivityModeFromTranscript: () => null,
+    sensitivityStatusText: () => 'normal',
+    setSensitivityMode: () => ({ mode: 'normal', minBytes: 0, minMeanDb: -40, minMaxDb: -20 }),
+    isSensitivityOnlyRequest: () => false,
+    verboseChangedSpeech: () => 'verbose set',
+    verboseModeFromTranscript: () => null,
+    verboseStatusText: () => 'verbose off',
+    setVerboseProgress: noop,
+    isVerboseOnlyRequest: () => false,
+    isRoutingOnlyUtterance: () => false,
+    parseAgentRoutingCommand: () => ({ type: 'none' }),
+    renderAgentPrefix: () => '',
+    buildCrossAgentPrompt: ({ prompt }) => prompt,
+    buildFallbackDecision: () => ({ slot: 'fallback' }),
+    parseResearchCommand: () => ({ type: 'none' }),
+    runResearchTurn: async () => ({ status: 'no_backend' }),
+    PROGRESS_IDLE_CHECK_MS: 5000,
+    PROGRESS_IDLE_NOTICE_INITIAL_MS: 10000,
+    PROGRESS_IDLE_NOTICE_LIMIT: 20,
+    PROGRESS_IDLE_NOTICE_MAX_MS: 30000,
+    PROGRESS_IDLE_NOTICE_MULTIPLIER: 1.8,
+    STT_START_VOICE_NOTICE: false,
+    ...overrides,
+  };
+}
+
+test('createUtteranceRouter exposes the expected functions', () => {
+  // handleRecording moved to voice_turn_runner in Phase 7a — see
+  // voice_turn_runner.test.mjs for its behaviour tests.
+  // Plan-mode dispatch moved to plan_dispatcher in Phase 7b — see
+  // plan_dispatcher.test.mjs.
+  const router = createUtteranceRouter(makeDeps());
+  for (const name of [
+    'adapterForProjectSession', 'routingStateFor', 'recordUtterance',
+    'clearTransientRouting', 'adapterForBackend', 'handleTtsVoiceCommand', 'handleLanguageCommand',
+    'handleVoiceCloneCommand', 'interruptCurrentResponse',
+  ]) {
+    assert.equal(typeof router[name], 'function', `${name} is exposed`);
+  }
+});
+
+// planChannelKey moved to plan_dispatcher in Phase 7b — see plan_dispatcher.test.mjs.
+
+test('routingStateFor lazily creates per-channel state with sensible defaults', () => {
+  const deps = makeDeps();
+  const { routingStateFor } = createUtteranceRouter(deps);
+  const state = routingStateFor('chan-a');
+  assert.equal(state.activeRouting.backend, 'hermes');
+  assert.equal(state.activeRouting.sticky, false);
+  assert.deepEqual(state.lastResolvedDecisions, {});
+  assert.equal(state.pendingFallbackPrompt, null);
+  assert.deepEqual(state.recentUtterances, []);
+  // Same channel returns the same object
+  const again = routingStateFor('chan-a');
+  assert.equal(state, again);
+});
+
+test('recordUtterance pushes to bounded recent buffer per channel', () => {
+  const deps = makeDeps();
+  const { routingStateFor, recordUtterance } = createUtteranceRouter(deps);
+  routingStateFor('c1');
+  for (let i = 0; i < 6; i++) recordUtterance('c1', `u${i}`);
+  const state = routingStateFor('c1');
+  assert.equal(state.recentUtterances.length, 4, 'buffer caps at 4');
+  assert.deepEqual(state.recentUtterances, ['u2', 'u3', 'u4', 'u5']);
+});
+
+test('clearTransientRouting wipes pending fallback prompt and non-sticky route', () => {
+  const deps = makeDeps();
+  const { routingStateFor, clearTransientRouting } = createUtteranceRouter(deps);
+  const state = routingStateFor('c1');
+  state.pendingFallbackPrompt = 'pending';
+  state.activeRouting = { backend: 'codex', sticky: false };
+  clearTransientRouting('c1');
+  const post = routingStateFor('c1');
+  assert.equal(post.pendingFallbackPrompt, null);
+  assert.equal(post.activeRouting.backend, 'hermes', 'reset to default backend');
+});
+
+test('clearTransientRouting leaves sticky routing intact', () => {
+  const deps = makeDeps();
+  const { routingStateFor, clearTransientRouting } = createUtteranceRouter(deps);
+  const state = routingStateFor('c1');
+  state.pendingFallbackPrompt = 'pending';
+  state.activeRouting = { backend: 'codex', sticky: true };
+  clearTransientRouting('c1');
+  const post = routingStateFor('c1');
+  assert.equal(post.pendingFallbackPrompt, null);
+  assert.equal(post.activeRouting.backend, 'codex', 'sticky backend is preserved');
+});
+
+test('adapterForProjectSession returns the default adapter when no session', () => {
+  const deps = makeDeps();
+  const { adapterForProjectSession } = createUtteranceRouter(deps);
+  assert.equal(adapterForProjectSession(null), deps.agentAdapter);
+});
+
+test('adapterForProjectSession caches per-session adapters', () => {
+  const deps = makeDeps();
+  const { adapterForProjectSession } = createUtteranceRouter(deps);
+  const session = { name: 'My Project', slug: 'my-project', sessionFile: '/tmp/s.json', workdir: '/tmp' };
+  const a = adapterForProjectSession(session);
+  const b = adapterForProjectSession(session);
+  assert.equal(a, b, 'same session returns cached adapter');
+  assert.equal(deps.bridge.agentAdaptersBySession.size, 1);
+});
+
+// handleRecording behaviour tests moved to voice_turn_runner.test.mjs in
+// Phase 7a, when handleRecording itself moved out of utterance_router.mjs
+// into voice_turn_runner.mjs.
+
+// --- cross-module state interactions ------------------------------------
+
+test('interruptCurrentResponse flips speaking/processing back to clean state', () => {
+  const deps = makeDeps();
+  // simulate mid-turn
+  deps.bridge.processing = true;
+  deps.bridge.speaking = true;
+  deps.bridge.activeTurnId = 42;
+  const controller = new AbortController();
+  deps.bridge.currentAbortController = controller;
+  deps.bridge.player = { stop: () => {} };
+
+  const { interruptCurrentResponse } = createUtteranceRouter(deps);
+  const out = interruptCurrentResponse('user-1', 'test-barge-in');
+
+  assert.equal(out, true, 'interrupt returns true when something was active');
+  assert.equal(deps.bridge.speaking, false, 'speaking cleared');
+  assert.equal(deps.bridge.processing, false, 'processing cleared');
+  assert.ok(deps.bridge.interruptedTurns.has(42), 'interrupted turn tracked');
+  assert.equal(controller.signal.aborted, true, 'abort controller fired');
+});
+
+test('interruptCurrentResponse is a no-op when nothing is in flight', () => {
+  const deps = makeDeps();
+  const { interruptCurrentResponse } = createUtteranceRouter(deps);
+  assert.equal(interruptCurrentResponse('user-1', 'noop'), false);
+  assert.equal(deps.bridge.speaking, false);
+  assert.equal(deps.bridge.processing, false);
+});

package/app-node/voice_autojoin.mjs

@@ -0,0 +1,37 @@
+export function isHumanAllowed(member, allowedUsers = new Set()) {
+  const userId = String(member?.user?.id || member?.id || '');
+  if (!userId || member?.user?.bot) return false;
+  return allowedUsers.size === 0 || allowedUsers.has(userId);
+}
+
+export function pickOccupiedUserVoiceChannel(guilds = [], allowedUsers = new Set(), { activeVoiceChannelId = '', activeGuildId = '' } = {}) {
+  const candidates = [];
+  const guildList = [...(guilds || [])];
+  for (const guild of guildList) {
+    const channels = [...(guild?.channels?.cache?.values?.() || [])];
+    for (const channel of channels) {
+      if (!channel?.isVoiceBased?.()) continue;
+      const members = [...(channel.members?.values?.() || [])];
+      if (members.some(member => isHumanAllowed(member, allowedUsers))) {
+        candidates.push({ channel, guildId: String(guild?.id || '') });
+      }
+    }
+  }
+  if (!candidates.length) return null;
+  if (activeVoiceChannelId) {
+    const stay = candidates.find(c => String(c.channel?.id || '') === String(activeVoiceChannelId));
+    if (stay) return stay.channel;
+  }
+  if (activeGuildId) {
+    const sameGuild = candidates.find(c => c.guildId === String(activeGuildId));
+    if (sameGuild) return sameGuild.channel;
+  }
+  return candidates[0].channel;
+}
+
+export function shouldFollowUserVoiceChannel({ singleInstance = true, userId = '', allowedUsers = new Set(), userChannelId = '', activeVoiceChannelId = '' } = {}) {
+  if (!singleInstance || !userChannelId) return false;
+  const id = String(userId || '');
+  if (!id || (allowedUsers.size > 0 && !allowedUsers.has(id))) return false;
+  return String(userChannelId) !== String(activeVoiceChannelId || '');
+}

package/app-node/voice_autojoin.test.mjs

@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  isHumanAllowed,
+  pickOccupiedUserVoiceChannel,
+  shouldFollowUserVoiceChannel,
+} from './voice_autojoin.mjs';
+
+function member(id, { bot = false } = {}) {
+  return { user: { id, bot } };
+}
+
+function voiceChannel(id, name, members = []) {
+  return {
+    id,
+    name,
+    members: new Map(members.map(m => [m.user.id, m])),
+    isVoiceBased: () => true,
+  };
+}
+
+function textChannel(id, name) {
+  return { id, name, members: new Map(), isVoiceBased: () => false };
+}
+
+function guild(channels) {
+  return { channels: { cache: new Map(channels.map(ch => [ch.id, ch])) } };
+}
+
+test('pickOccupiedUserVoiceChannel selects an allowed human voice channel before configured names', () => {
+  const empty = voiceChannel('v1', 'General', []);
+  const occupied = voiceChannel('v2', 'Summer', [member('u1')]);
+
+  const selected = pickOccupiedUserVoiceChannel([guild([textChannel('t1', 'text'), empty, occupied])], new Set(['u1']));
+
+  assert.equal(selected, occupied);
+});
+
+test('pickOccupiedUserVoiceChannel ignores bots and disallowed humans', () => {
+  const botOnly = voiceChannel('v1', 'Bot room', [member('bot1', { bot: true })]);
+  const disallowed = voiceChannel('v2', 'Other', [member('u2')]);
+
+  const selected = pickOccupiedUserVoiceChannel([guild([botOnly, disallowed])], new Set(['u1']));
+
+  assert.equal(selected, null);
+});
+
+test('shouldFollowUserVoiceChannel only follows allowed users in single-instance mode', () => {
+  assert.equal(shouldFollowUserVoiceChannel({ singleInstance: true, userId: 'u1', allowedUsers: new Set(['u1']), userChannelId: 'voice-a', activeVoiceChannelId: 'voice-b' }), true);
+  assert.equal(shouldFollowUserVoiceChannel({ singleInstance: false, userId: 'u1', allowedUsers: new Set(['u1']), userChannelId: 'voice-a', activeVoiceChannelId: 'voice-b' }), false);
+  assert.equal(shouldFollowUserVoiceChannel({ singleInstance: true, userId: 'u2', allowedUsers: new Set(['u1']), userChannelId: 'voice-a', activeVoiceChannelId: 'voice-b' }), false);
+  assert.equal(shouldFollowUserVoiceChannel({ singleInstance: true, userId: 'u1', allowedUsers: new Set(['u1']), userChannelId: 'voice-a', activeVoiceChannelId: 'voice-a' }), false);
+});
+
+test('isHumanAllowed accepts any non-bot when allowlist is empty', () => {
+  assert.equal(isHumanAllowed(member('u1'), new Set()), true);
+  assert.equal(isHumanAllowed(member('bot1', { bot: true }), new Set()), false);
+});