verbalcoding 0.2.12 → 0.2.13

package/app-node/main.mjs

@@ -6,19 +6,8 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 import { Client, GatewayIntentBits, Partials } from 'discord.js';
-import {
-  AudioPlayerStatus,
-  EndBehaviorType,
-  StreamType,
-  VoiceConnectionStatus,
-  createAudioPlayer,
-  createAudioResource,
-  entersState,
-  joinVoiceChannel,
-} from '@discordjs/voice';
-import prism from 'prism-media';
-import wav from 'wav';
-import { buildAgentSettings, createAgentAdapter, isPatchLikeOutput } from './agent_adapters.mjs';
+import { createAudioPlayer } from '@discordjs/voice';
+import { buildAgentSettings, createAgentAdapter, isPatchLikeOutput, shellSplit } from './agent_adapters.mjs';
 import {
   appendJsonl,
   createLatencyTurn,
@@ -26,11 +15,6 @@ import {
   readJsonlRecords,
   summarizeLatencyRecords,
 } from './latency_metrics.mjs';
-import { splitForTTS } from './tts_chunks.mjs';
-import { playChunkedTTSWithPrefetch } from './tts_prefetch.mjs';
-import { createSentencer } from './stream_sentencer.mjs';
-import { createStreamingTTSQueue } from './streaming_tts_queue.mjs';
-import { createSmartProgressSummarizer } from './smart_progress.mjs';
 import {
   isPlanEntryUtterance,
   parsePlanOutput,
@@ -43,8 +27,16 @@ import {
   renderDecisionPrompt,
   renderResolvedDecisions,
 } from './plan_mode.mjs';
-import { createNotifier, buildDiscordDeepLink } from './notify.mjs';
-import { progressCategory, summarizeProgressEvents, formatProgressMessage } from './progress_speech.mjs';
+import {
+  parseAgentRoutingCommand,
+  renderAgentPrefix,
+  buildCrossAgentPrompt,
+  isAgentRoutingDecision,
+  buildFallbackDecision,
+  isRoutingOnlyUtterance,
+} from './agent_routing.mjs';
+import { createSessionOntology } from './session_ontology.mjs';
+import { parseResearchCommand, runResearchTurn } from './research_mode.mjs';
 import { buildTtsSettings } from './tts_settings.mjs';
 import { createTtsBackend } from './tts_backends.mjs';
 import {
@@ -59,21 +51,30 @@ import {
 } from './tts_voice_config.mjs';
 import { createBridgeLogger, createTransientErrorReporter, isTransientNetworkError } from './bridge_logger.mjs';
 import { createBridgeState } from './bridge_state.mjs';
+import { createBridge } from './bridge_context.mjs';
+import { createVoiceIO } from './voice_io.mjs';
+import { createTtsPlayer } from './tts_player.mjs';
+import { createUtteranceRouter } from './utterance_router.mjs';
+import { createProgressHandler } from './progress_handler.mjs';
+import { createNotificationHandler } from './notification_handler.mjs';
+import { createTtsRuntime } from './tts_runtime.mjs';
+import { createDiscordVoiceSetup } from './discord_voice_setup.mjs';
+import { createAgentTurnLifecycle } from './agent_turn.mjs';
+import { createDiscordCommandRouter } from './discord_command_router.mjs';
+import { createVoiceTurnRunner } from './voice_turn_runner.mjs';
+import { createPlanDispatcher } from './plan_dispatcher.mjs';
 import { sendDiscordText, splitDiscordMessage } from './discord_text.mjs';
-import { progressTtsCacheFileName } from './progress_cache.mjs';
 import { shouldPassWhisperLanguage, voiceLanguageCommandFromTranscript, languagePreset } from './language_config.mjs';
-import { formatRestartCompleteNotice, formatRestartShutdownNotice } from './restart_notice.mjs';
+import { whisperFailureMessage, whisperTimeoutMs } from './stt_whisper.mjs';
+import { formatRestartCompleteNotice } from './restart_notice.mjs';
 import {
-  appendRecentDiscordText,
   formatRecentDiscordContext,
-  shouldRouteDiscordTextToAgent,
 } from './text_routing.mjs';
 import {
   bindProjectSessionToChannel,
   createProjectSession,
   listProjectSessions,
   loadProjectSessions,
-  parseProjectSessionCommand,
   projectSessionContextText,
   projectSessionForChannel,
   saveProjectSessions,
@@ -161,13 +162,20 @@ function ensureTtsVoiceConfig() {
   return readTtsVoiceConfig(TTS_VOICE_CONFIG_PATH);
 }
 function applyVoiceConfigToProcessEnv(config = ensureTtsVoiceConfig()) {
-  const selection = effectiveTtsVoiceSelection(config, {});
+  const selection = effectiveTtsVoiceSelection(config, process.env);
   const configuredVoiceLanguage = process.env.VOICE_LANGUAGE;
   const nextEnv = applyTtsVoiceSelectionToEnv(process.env, selection);
   if (configuredVoiceLanguage) nextEnv.VOICE_LANGUAGE = configuredVoiceLanguage;
   for (const [key, value] of Object.entries(nextEnv)) process.env[key] = value;
   return { config, selection };
 }
+function rebuildTtsRuntimeSettings(selection = null) {
+  settings.tts = buildTtsSettings(process.env, ROOT);
+  if (selection?.backend === 'edge' && selection.voice?.voice) settings.tts.edge.voice = selection.voice.voice;
+  try { bridge.ttsBackend?.close?.(); } catch (e) { warn('tts backend close failed', e?.message || e); }
+  bridge.ttsBackend = createTtsBackend(settings.tts, { execFileAsync, spawn, log, warn, onFallback: ttsFallbackNotice, voiceProvider: () => settings.tts.edge.voice });
+  return settings.tts;
+}
 function reloadRuntimeLanguageFromEnv() {
   const previousWhisperLanguage = settings?.whisperLanguage;
   const previousVoiceLanguage = settings?.voiceLanguage;
@@ -190,6 +198,7 @@ const settings = {
   whisperBin: process.env.WHISPER_CPP_BIN || 'whisper-cli',
   whisperModel: process.env.WHISPER_CPP_MODEL || path.join(ROOT, 'models', 'ggml-small-q5_1.bin'),
   whisperLanguage: process.env.WHISPER_CPP_LANGUAGE || process.env.STT_LANGUAGE || 'ko',
+  whisperTimeoutMs: whisperTimeoutMs(process.env),
   voiceLanguage: process.env.VOICE_LANGUAGE || process.env.WHISPER_CPP_LANGUAGE || process.env.STT_LANGUAGE || 'ko',
   tts: buildTtsSettings(process.env, ROOT),
   requireWakeWord: ['1', 'true', 'yes'].includes((process.env.REQUIRE_WAKE_WORD || '0').toLowerCase()),
@@ -207,21 +216,33 @@ const client = new Client({
   intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
   partials: [Partials.Channel],
 });
-let ttsBackend = createTtsBackend(settings.tts, { execFileAsync, log, warn, voiceProvider: () => settings.tts.edge.voice });
+const announcedTtsFallbacks = new Set();
+const pendingFallbackNoticePromises = new Set();
+function ttsFallbackNotice({ backend } = {}) {
+  if (!backend || backend === 'edge') return;
+  if (announcedTtsFallbacks.has(backend)) return;
+  announcedTtsFallbacks.add(backend);
+  const en = /^en/i.test(String(settings.voiceLanguage || ''));
+  const msg = en
+    ? `${backend} synthesis failed; using Edge for the rest of this session.`
+    : `${backend} 음성 생성에 실패해서 이번 세션은 Edge로 진행할게.`;
+  const textPromise = sendText(`⚠️ ${msg}`)
+    .catch(e => warn('tts fallback notice send failed', e?.message || e));
+  pendingFallbackNoticePromises.add(textPromise);
+  textPromise.finally(() => pendingFallbackNoticePromises.delete(textPromise));
+  const speakPromise = new Promise(resolve => queueMicrotask(() => {
+    speakText(msg, null, null, { mirrorText: false })
+      .catch(e => warn('tts fallback notice speak failed', e?.message || e))
+      .finally(resolve);
+  }));
+  pendingFallbackNoticePromises.add(speakPromise);
+  speakPromise.finally(() => pendingFallbackNoticePromises.delete(speakPromise));
+}
+const bridge = createBridge();
+bridge.ttsBackend = createTtsBackend(settings.tts, { execFileAsync, spawn, log, warn, onFallback: ttsFallbackNotice, voiceProvider: () => settings.tts.edge.voice });
 const voiceCloneCapture = createVoiceCloneCaptureState({ defaultTargetPath: settings.tts.openvoice.refAudio });
 
-let connection = null;
-let activeVoiceChannelId = '';
-let activeTranscriptChannelId = '';
-const recentDiscordTextByChannel = new Map();
-let player = createAudioPlayer();
-let speaking = false;
-let processing = false;
-let activeTurnId = 0;
-let currentAbortController = null;
-const interruptedTurns = new Set();
-const activeStreams = new Map();
-let bridgeState = null;
+bridge.player = createAudioPlayer();
 const MAX_DEFERRED_PROCESSING_UTTERANCES = Number(process.env.MAX_DEFERRED_PROCESSING_UTTERANCES || '0');
 const MIN_UTTERANCE_SECONDS = Number(process.env.MIN_UTTERANCE_SECONDS || '1.4');
 const MIN_UTTERANCE_BYTES = 48000 * 2 * 2 * MIN_UTTERANCE_SECONDS;
@@ -254,7 +275,7 @@ const bridgeLogger = createBridgeLogger({
 });
 function log(...args) { bridgeLogger.log(...args); }
 function warn(...args) { bridgeLogger.warn(...args); }
-bridgeState = createBridgeState({ log, cleanupFile: file => fs.rm(file, { force: true }, () => {}) });
+bridge.bridgeState = createBridgeState({ log, cleanupFile: file => fs.rm(file, { force: true }, () => {}) });
 const reportTransientProcessError = createTransientErrorReporter({ warn });
 function isBenignTransientNetworkError(error) {
   return isTransientNetworkError(error);
@@ -273,241 +294,80 @@ function newLatencyTurn(userId, startedAtMs) {
 }
 
 function discardVoiceInputQueues(reason = 'config-change') {
-  return bridgeState?.discardQueues(reason) || 0;
-}
-let verboseProgress = Boolean(settings.agent.verboseProgress);
-let activeProgressSignal = null;
-let verboseProgressSpeechQueue = Promise.resolve();
-let activeProgressAbortController = null;
-let speechPlaybackGeneration = 0;
-let progressSpeechBatch = [];
-let progressSpeechBatchTimer = null;
-let progressSpeechBatchSignal = null;
-let progressSpeechBatchStartedAt = 0;
-
-const STREAMING_TTS_ENABLED = ['1', 'true', 'yes', 'on'].includes(String(process.env.STREAMING_TTS || '0').toLowerCase());
-let activeSentencer = null;
-let activeStreamingQueue = null;
-let streamingSpeechDelivered = false;
-
-let notifyUserOptIn = false;
-let notifierInstance = null;
-function ensureNotifier() {
-  if (notifierInstance) return notifierInstance;
-  notifierInstance = createNotifier({
-    provider: (process.env.NOTIFY_PROVIDER || 'ntfy').toLowerCase(),
-    topic: process.env.NTFY_TOPIC || '',
-    pushoverUser: process.env.PUSHOVER_USER || '',
-    pushoverToken: process.env.PUSHOVER_TOKEN || '',
-  });
-  return notifierInstance;
-}
-function notifyStatusText() {
-  const provider = (process.env.NOTIFY_PROVIDER || 'ntfy').toLowerCase();
-  const hasTopic = provider === 'ntfy' ? Boolean(process.env.NTFY_TOPIC) : (provider === 'pushover' ? Boolean(process.env.PUSHOVER_USER && process.env.PUSHOVER_TOKEN) : true);
-  const mode = notifyUserOptIn ? 'always' : 'empty-channel only';
-  const config = hasTopic ? 'configured' : 'NOT configured';
-  return `notify: ${mode} via ${provider} (${config}). Threshold: ${process.env.NOTIFY_MIN_TASK_MS || '60000'}ms.`;
-}
-async function getVoiceChannelHumanCount() {
-  if (!activeVoiceChannelId) return 0;
-  try {
-    const ch = await client.channels.fetch(activeVoiceChannelId).catch(() => null);
-    if (!ch || !ch.members) return 0;
-    let count = 0;
-    for (const [, m] of ch.members) if (!m.user?.bot) count += 1;
-    return count;
-  } catch (e) {
-    warn('humanCount failed', e?.message || e);
-    return 0;
-  }
-}
-async function maybeNotifyTaskComplete({ answer, label, elapsedMs, guildId }) {
-  const provider = (process.env.NOTIFY_PROVIDER || '').toLowerCase();
-  if (!provider || provider === 'noop') return;
-  const minTaskMs = Number(process.env.NOTIFY_MIN_TASK_MS || '60000');
-  const humanCount = await getVoiceChannelHumanCount();
-  const notifier = ensureNotifier();
-  if (!notifier.shouldNotify({ humanCount, taskMs: elapsedMs, minTaskMs, userOptIn: notifyUserOptIn })) return;
-  const text = String(answer || '').trim();
-  const lastSentence = text.split(/(?<=[.!?。！？])\s+/).filter(Boolean).pop() || text;
-  const body = lastSentence.slice(0, 200);
-  const title = label ? `${label} finished` : 'VerbalCoding finished';
-  const deepLink = buildDiscordDeepLink({ guildId, channelId: activeVoiceChannelId });
-  try {
-    const result = await notifier.send({ title, body, deepLink });
-    log('notify sent', 'provider', provider, 'status', result?.status || result?.ok, 'skipped', result?.skipped || false);
-  } catch (e) {
-    warn('notify send failed', e?.message || e);
-  }
-}
-
-const planStates = new Map(); // channelId -> { steps, language }
-
-function planChannelKey() {
-  return activeVoiceChannelId || settings.transcriptChannelId || 'default';
-}
-
-async function askNextDecision(state, signal) {
-  const decision = state.decisions[state.pendingDecisionIndex];
-  if (!decision) return;
-  const text = renderDecisionPrompt(decision, state.language);
-  await sendText(`❓ ${text}`);
-  await speakText(text, signal, null);
+  return bridge.bridgeState?.discardQueues(reason) || 0;
 }
+bridge.verboseProgress = Boolean(settings.agent.verboseProgress);
 
-async function finalizePlanReady(state, signal) {
-  const language = state.language;
-  const resolvedLine = renderResolvedDecisions(state.resolvedDecisions, language);
-  const plan = planNarrationLines(state.steps, language);
-  const tail = /^en/i.test(String(language || ''))
-    ? `${plan}\n${resolvedLine}\nSay "approve" to run, or edit with skip/insert.`
-    : `${plan}\n${resolvedLine}\n"실행"이라고 하면 시작할게. skip/insert로 수정도 돼.`;
-  await sendText(`📝 ${tail}`);
-  await speakText(tail, signal, null);
-}
-
-async function dispatchPlanModeUtterance(prompt, signal) {
-  const language = settings.voiceLanguage;
-  const key = planChannelKey();
-  const existing = planStates.get(key);
-
-  if (existing && existing.pendingDecisionIndex < existing.decisions.length) {
-    const decision = existing.decisions[existing.pendingDecisionIndex];
-    const answer = parseDecisionAnswer(prompt, decision, language);
-    if (answer.type === 'unknown') {
-      await sendText(/^en/i.test(String(language || ''))
-        ? '⚠️ I did not catch that. Please pick an option.'
-        : '⚠️ 못 알아들었어. 옵션 중에 하나 골라줘.');
-      await askNextDecision(existing, signal);
-      return { handled: true };
-    }
-    const next = {
-      ...existing,
-      resolvedDecisions: { ...existing.resolvedDecisions, [decision.slot]: answer.choice },
-      pendingDecisionIndex: existing.pendingDecisionIndex + 1,
-    };
-    planStates.set(key, next);
-    if (next.pendingDecisionIndex < next.decisions.length) {
-      await askNextDecision(next, signal);
-    } else {
-      await finalizePlanReady(next, signal);
-    }
-    return { handled: true };
-  }
+const STREAMING_TTS_ENABLED = ['1', 'true', 'yes', 'on'].includes(String(process.env.STREAMING_TTS || '1').toLowerCase());
 
-  if (existing) {
-    const cmd = parsePlanVoiceCommand(prompt, language);
-    if (cmd.type === 'skip' || cmd.type === 'insert') {
-      const nextSteps = applyPlanCommand(existing.steps, cmd);
-      planStates.set(key, { ...existing, steps: nextSteps });
-      await finalizePlanReady({ ...existing, steps: nextSteps }, signal);
-      return { handled: true };
-    }
-    if (cmd.type === 'cancel') {
-      planStates.delete(key);
-      const msg = /^en/i.test(String(language || '')) ? 'Plan cancelled.' : '계획을 취소했어.';
-      await sendText(`❎ ${msg}`);
-      await speakText(msg, signal, null);
-      return { handled: true };
-    }
-    if (cmd.type === 'approve') {
-      const finalPlan = renderFinalPlan(existing.steps);
-      const resolvedLine = renderResolvedDecisions(existing.resolvedDecisions, language);
-      const promptToRun = [
-        planExecutionPreamble(language),
-        '',
-        finalPlan,
-        resolvedLine,
-        '',
-        `Original user request: ${existing.originalPrompt}`,
-      ].filter(Boolean).join('\n');
-      planStates.delete(key);
-      const note = /^en/i.test(String(language || '')) ? 'Running the plan now.' : '계획대로 실행할게.';
-      await sendText(`▶ ${note}`);
-      await speakText(note, signal, null);
-      return { handled: false, prompt: promptToRun };
-    }
-    planStates.delete(key);
-    return { handled: false, prompt };
-  }
-
-  if (isPlanEntryUtterance(prompt, language)) {
-    const planPrompt = `${planModePreamble(language)}\n\nUser request: ${prompt}`;
-    const adapter = adapterForProjectSession(resolveProjectSessionForChannel(planChannelKey()));
-    const plan = { task: false, label: adapter.label, verboseProgress: false, language, projectContext: '' };
-    const result = await adapter.run(planPrompt, signal, plan).catch(e => ({ answer: '', error: e }));
-    const { steps, decisions } = parsePlanOutput(result.answer || '');
-    if (!steps.length) {
-      const failMsg = /^en/i.test(String(language || ''))
-        ? 'I could not produce a plan. Continuing as a regular turn.'
-        : '계획을 만들지 못했어. 일반 작업으로 진행할게.';
-      await sendText(`⚠️ ${failMsg}`);
-      return { handled: false, prompt };
-    }
-    const state = {
-      steps,
-      decisions,
-      resolvedDecisions: {},
-      pendingDecisionIndex: 0,
-      originalPrompt: prompt,
-      language,
-    };
-    planStates.set(planChannelKey(), state);
-    const narration = planNarrationLines(steps, language);
-    await sendText(`📝 ${narration}`);
-    await speakText(narration, signal, null);
-    if (decisions.length) {
-      await askNextDecision(state, signal);
-    } else {
-      await finalizePlanReady(state, signal);
-    }
-    return { handled: true };
-  }
-  return { handled: false, prompt };
-}
-
-function planNarrationLines(steps, language) {
-  const visible = steps.filter(s => s.status !== 'skipped');
-  const header = /^en/i.test(String(language || ''))
-    ? `Plan with ${visible.length} steps. Say "skip step N", "add X after step N", or "approve" to run.`
-    : `${visible.length}단계 계획. "step N 건너뛰어", "step N 다음에 X 추가", "실행"이라고 말해줘.`;
-  const body = visible.map((s, i) => `${i + 1}. ${s.text}`).join('\n');
-  return `${header}\n${body}`;
-}
-
-let smartProgressEnabled = Boolean(process.env.SMART_PROGRESS_API_KEY);
-let smartProgressSummarizer = null;
-function ensureSmartProgressSummarizer() {
-  if (smartProgressSummarizer) return smartProgressSummarizer;
-  smartProgressSummarizer = createSmartProgressSummarizer({
-    apiKey: process.env.SMART_PROGRESS_API_KEY || '',
-    baseUrl: process.env.SMART_PROGRESS_BASE_URL || 'https://api.groq.com/openai/v1',
-    model: process.env.SMART_PROGRESS_MODEL || 'llama-3.1-8b-instant',
-    language: settings.voiceLanguage,
-  });
-  smartProgressSummarizer.on('summary', summary => {
-    if (!summary || !activeProgressSignal) return;
-    queueVerboseProgressSpeech(summary, activeProgressSignal);
-  });
-  return smartProgressSummarizer;
-}
-function smartProgressStatusText() {
-  const hasKey = Boolean(process.env.SMART_PROGRESS_API_KEY);
-  const mode = smartProgressEnabled && hasKey ? 'on' : 'off';
-  const reason = !hasKey ? ' (no SMART_PROGRESS_API_KEY set)' : '';
-  return `smart-progress: ${mode}${reason}`;
-}
-let activeProgressLastEventAt = 0;
-let lastVerboseProgressText = '';
-let lastVerboseProgressTextAt = 0;
+bridge.smartProgressEnabled = Boolean(process.env.SMART_PROGRESS_API_KEY);
+const VOICE_CONNECT_TIMEOUT_MS = Number(process.env.VOICE_CONNECT_TIMEOUT_MS || '60000');
 const PROGRESS_IDLE_NOTICE_INITIAL_MS = Number(process.env.PROGRESS_IDLE_NOTICE_INITIAL_MS || process.env.PROGRESS_IDLE_NOTICE_MS || '10000');
 const PROGRESS_IDLE_NOTICE_MAX_MS = Number(process.env.PROGRESS_IDLE_NOTICE_MAX_MS || '30000');
 const PROGRESS_IDLE_NOTICE_MULTIPLIER = Number(process.env.PROGRESS_IDLE_NOTICE_MULTIPLIER || '1.8');
 const PROGRESS_IDLE_CHECK_MS = Number(process.env.PROGRESS_IDLE_CHECK_MS || '5000');
 const PROGRESS_IDLE_NOTICE_LIMIT = Number(process.env.PROGRESS_IDLE_NOTICE_LIMIT || '20');
 const projectSessionsState = loadProjectSessions(settings.projectSessionsPath);
-const agentAdaptersBySession = new Map();
+const ttsPlayer = createTtsPlayer({
+  bridge,
+  settings,
+  log,
+  warn,
+  sleep,
+  sendText,
+  refreshTtsRuntimeConfig,
+  waitEvent,
+  isAbortError,
+  STREAMING_TTS_ENABLED,
+});
+const { synthTTS, playAudio, speakText, beginStreamingTurn, endStreamingTurn, stopPlaybackForBargeIn } = ttsPlayer;
+
+const progressHandler = createProgressHandler({
+  bridge,
+  settings,
+  log,
+  warn,
+  isAbortError,
+  playAudio,
+  sendText,
+  refreshTtsRuntimeConfig,
+});
+const {
+  ensureSmartProgressSummarizer,
+  smartProgressStatusText,
+  progressEmoji,
+  formatProgressText,
+  sendVerboseProgressText,
+  synthProgressTTS,
+  speakProgress,
+  speakImmediateNotice,
+  queueProgressSpeechText,
+  flushProgressSpeechBatch,
+  queueVerboseProgressSpeech,
+  clearProgressSpeechBatch,
+  stopProgressSpeech,
+} = progressHandler;
+
+const agentTurnLifecycle = createAgentTurnLifecycle({ bridge, warn });
+
+const notificationHandler = createNotificationHandler({ bridge, client, log, warn });
+const {
+  ensureNotifier,
+  notifyStatusText,
+  getVoiceChannelHumanCount,
+  maybeNotifyTaskComplete,
+} = notificationHandler;
+
+const ttsRuntime = createTtsRuntime({
+  bridge,
+  ROOT,
+  execFileAsync,
+  speakText,
+  warn,
+  persistEnvValues,
+});
+const { ensureSelectedTtsBackendInstalled, commandIsInstalled } = ttsRuntime;
+
 function createBridgeAgentAdapter(agentSettings) {
   return createAgentAdapter(agentSettings, {
     execFileAsync,
@@ -515,53 +375,72 @@ function createBridgeAgentAdapter(agentSettings) {
     log,
     warn,
     onProgress: event => {
-      if (!verboseProgress) return;
-      activeProgressLastEventAt = Date.now();
-      sendVerboseProgressText(event, activeProgressSignal);
-      if (smartProgressEnabled && process.env.SMART_PROGRESS_API_KEY) {
+      if (!bridge.verboseProgress) return;
+      bridge.activeProgressLastEventAt = Date.now();
+      sendVerboseProgressText(event, bridge.activeProgressSignal);
+      if (bridge.smartProgressEnabled && process.env.SMART_PROGRESS_API_KEY) {
         try { ensureSmartProgressSummarizer().ingest(event); }
-        catch (e) { warn('smart progress ingest failed', e?.stack || e); queueVerboseProgressSpeech(event, activeProgressSignal); }
+        catch (e) { warn('smart progress ingest failed', e?.stack || e); queueVerboseProgressSpeech(event, bridge.activeProgressSignal); }
       } else {
-        queueVerboseProgressSpeech(event, activeProgressSignal);
+        queueVerboseProgressSpeech(event, bridge.activeProgressSignal);
       }
     },
     onStdoutChunk: chunk => {
-      if (activeSentencer) {
-        try { activeSentencer.push(chunk); } catch (e) { warn('streaming sentencer push failed', e?.stack || e); }
+      if (bridge.activeSentencer) {
+        try { bridge.activeSentencer.push(chunk); } catch (e) { warn('streaming sentencer push failed', e?.stack || e); }
       }
     },
   });
 }
 const agentAdapter = createBridgeAgentAdapter(settings.agent);
-function adapterForProjectSession(session) {
-  if (!session) return agentAdapter;
-  const key = session.slug || session.name;
-  if (!agentAdaptersBySession.has(key)) {
-    agentAdaptersBySession.set(key, createBridgeAgentAdapter({
-      ...settings.agent,
-      label: `${settings.agent.label} · ${session.name}`,
-      sessionFile: session.sessionFile,
-      cwd: session.workdir,
-      projectContext: projectSessionContextText(session),
-    }));
-  }
-  return agentAdaptersBySession.get(key);
-}
 function resolveProjectSessionForChannel(channelId) {
   return projectSessionForChannel(projectSessionsState, channelId) || null;
 }
+
+function ontologyStateFor(channelKey) {
+  const key = String(channelKey || 'default');
+  let store = bridge.ontologyByChannel.get(key);
+  if (!store) {
+    store = createSessionOntology({ channelKey: key });
+    try { store.load(); } catch {}
+    bridge.ontologyByChannel.set(key, store);
+  }
+  return store;
+}
+function captureOntologyFromTurn(channelKey, { prompt, answer, backend }) {
+  try {
+    const store = ontologyStateFor(channelKey);
+    const promptEntities = store.entitiesFromText(String(prompt || ''), { by: backend, kind: 'utterance' });
+    const answerEntities = store.entitiesFromText(String(answer || ''), { by: backend, kind: 'result' });
+    store.add(promptEntities);
+    store.add(answerEntities);
+    store.save();
+  } catch (e) {
+    warn('ontology capture failed', e?.message || e);
+  }
+}
+function resetRoutingState(channelKey) {
+  const state = routingStateFor(channelKey);
+  state.activeRouting = { backend: settings.agent.backend, sticky: false };
+  state.pendingFallbackPrompt = null;
+}
+function invalidateBackendAdaptersForSession(sessionSlug) {
+  if (!sessionSlug) return;
+  for (const key of Array.from(bridge.agentAdaptersByBackend.keys())) {
+    if (key.endsWith(`::${sessionSlug}`)) bridge.agentAdaptersByBackend.delete(key);
+  }
+}
 function saveProjectSessionsState() {
   saveProjectSessions(settings.projectSessionsPath, projectSessionsState);
 }
-let sensitivityMode = SENSITIVITY_MODE_DEFAULT;
-let sensitivityModeExpiresAt = 0;
+bridge.sensitivityMode = SENSITIVITY_MODE_DEFAULT;
 function currentBargeInThresholds() {
-  if (sensitivityModeExpiresAt && Date.now() > sensitivityModeExpiresAt) {
-    sensitivityMode = SENSITIVITY_MODE_DEFAULT;
-    sensitivityModeExpiresAt = 0;
-    log('barge-in sensitivity mode expired; restored', sensitivityMode);
+  if (bridge.sensitivityModeExpiresAt && Date.now() > bridge.sensitivityModeExpiresAt) {
+    bridge.sensitivityMode = SENSITIVITY_MODE_DEFAULT;
+    bridge.sensitivityModeExpiresAt = 0;
+    log('barge-in sensitivity mode expired; restored', bridge.sensitivityMode);
   }
-  return bargeInThresholdsForMode(sensitivityMode, {
+  return bargeInThresholdsForMode(bridge.sensitivityMode, {
     minSeconds: BARGE_IN_MIN_SECONDS,
     minMeanDb: BARGE_IN_MIN_MEAN_VOLUME_DB,
     minMaxDb: BARGE_IN_MIN_MAX_VOLUME_DB,
@@ -581,48 +460,28 @@ function currentPlaybackBargeInThresholds() {
   };
 }
 function setSensitivityMode(mode, reason = 'manual') {
-  sensitivityMode = mode === 'conservative' ? 'conservative' : 'normal';
-  sensitivityModeExpiresAt = sensitivityMode === 'conservative' && SENSITIVITY_OUTDOOR_SECONDS > 0
+  bridge.sensitivityMode = mode === 'conservative' ? 'conservative' : 'normal';
+  bridge.sensitivityModeExpiresAt = bridge.sensitivityMode === 'conservative' && SENSITIVITY_OUTDOOR_SECONDS > 0
     ? Date.now() + SENSITIVITY_OUTDOOR_SECONDS * 1000
     : 0;
   const thresholds = currentBargeInThresholds();
-  log('barge-in sensitivity mode set', sensitivityMode, 'reason', reason, 'expiresAt', sensitivityModeExpiresAt || 'never', 'thresholds', thresholds);
+  log('barge-in sensitivity mode set', bridge.sensitivityMode, 'reason', reason, 'expiresAt', bridge.sensitivityModeExpiresAt || 'never', 'thresholds', thresholds);
   return thresholds;
 }
 function sensitivityStatusText() {
   const thresholds = currentBargeInThresholds();
-  const ttl = sensitivityModeExpiresAt ? Math.max(0, Math.round((sensitivityModeExpiresAt - Date.now()) / 1000)) : 0;
+  const ttl = bridge.sensitivityModeExpiresAt ? Math.max(0, Math.round((bridge.sensitivityModeExpiresAt - Date.now()) / 1000)) : 0;
   return sensitivityStatusTextForLanguage(thresholds, ttl, settings.voiceLanguage);
 }
 
 function verboseStatusText() {
-  return verboseStatusTextForLanguage(verboseProgress, settings.voiceLanguage);
-}
-
-function progressEmoji(event) {
-  const category = progressCategory(event, { language: settings.voiceLanguage })?.key;
-  return {
-    test: '🧪',
-    edit: '✏️',
-    read: '📖',
-    search: '🔎',
-    terminal: '⌨️',
-    skill: '🧰',
-    browser: '🌐',
-    tool: '🛠️',
-    agent: '🤖',
-    work: '⚙️',
-  }[category] || '⚙️';
-}
-
-function formatProgressText(event) {
-  return formatProgressMessage(event, { language: settings.voiceLanguage });
+  return verboseStatusTextForLanguage(bridge.verboseProgress, settings.voiceLanguage);
 }
 
 function setVerboseProgress(enabled, reason = 'manual') {
-  verboseProgress = Boolean(enabled);
-  log('verbose progress mode set', verboseProgress, 'reason', reason);
-  return verboseProgress;
+  bridge.verboseProgress = Boolean(enabled);
+  log('verbose progress mode set', bridge.verboseProgress, 'reason', reason);
+  return bridge.verboseProgress;
 }
 
 function persistEnvValues(values) {
@@ -633,7 +492,7 @@ function persistEnvValues(values) {
   } catch (e) {
     warn('read .env for update failed', e?.stack || e);
   }
-  const pending = new Map(Object.entries(values));
+  const pending = new Map(Object.entries(values).filter(([, value]) => value !== undefined));
   const updated = lines.map(line => {
     const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=.*$/);
     if (!match || !pending.has(match[1])) return line;
@@ -655,8 +514,8 @@ function applyRuntimeLanguage(language) {
   config = updateTtsVoiceConfig(config, { voiceType: preferredVoiceTypeForLanguage(config, preset.voiceLanguage) });
   writeTtsVoiceConfig(TTS_VOICE_CONFIG_PATH, config);
   const { selection } = applyVoiceConfigToProcessEnv(config);
-  settings.tts.backend = selection.backend;
-  settings.tts.edge.voice = selection.backend === 'edge' ? selection.voice.voice : preset.ttsVoice;
+  rebuildTtsRuntimeSettings(selection);
+  if (selection.backend !== 'edge') settings.tts.edge.voice = preset.ttsVoice;
   process.env.VOICE_LANGUAGE = preset.voiceLanguage;
   process.env.WHISPER_CPP_LANGUAGE = preset.sttLanguage;
   process.env.STT_LANGUAGE = preset.sttLanguage;
@@ -685,33 +544,23 @@ function voiceChangedText(selection) {
   return `Voice changed to ${selection.voice?.label || selection.voiceType}.`;
 }
 
-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);
-  settings.tts.backend = selection.backend;
-  if (selection.backend === 'edge') settings.tts.edge.voice = selection.voice.voice;
-  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,
-  });
-  await speakText(voiceChangedText(selection), signal);
-  return true;
+function isCloneVoiceType(voiceType) {
+  return /^(cloned_reference|prompt_reference|cosyvoice_reference)$/i.test(String(voiceType || ''));
 }
 
-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 notifyVoiceCloneSampleGapIfNeeded(selection, signal) {
+  if (!selection || selection.backend === 'edge') return;
+  if (!isCloneVoiceType(selection.voiceType)) return;
+  const ref = String(selection.voice?.voice || '').trim();
+  if (!ref) return;
+  const candidatePath = path.isAbsolute(ref) ? ref : path.resolve(ROOT, ref);
+  if (fs.existsSync(candidatePath)) return;
+  const en = /^en/i.test(String(settings.voiceLanguage || ''));
+  const msg = en
+    ? `${selection.backend} needs a voice clone sample at ${ref}. Say "voice clone capture" to record one, or pick a non-clone voice.`
+    : `${selection.backend} 백엔드는 음성 클론 샘플(${ref})이 필요해. "보이스 클로닝 캡처"라고 하거나 다른 보이스를 골라줘.`;
+  await sendText(`🎙️ ${msg}`);
+  await speakText(msg, signal, null);
 }
 
 function isAllowed(userId) { return settings.allowedUsers.size === 0 || settings.allowedUsers.has(String(userId)); }
@@ -757,13 +606,28 @@ function spokenResultOnly(userPrompt, answer, language = settings.voiceLanguage)
 async function sendText(text) {
   return sendDiscordText({
     client,
-    channelId: activeTranscriptChannelId || settings.transcriptChannelId,
+    channelId: bridge.activeTranscriptChannelId || settings.transcriptChannelId,
     text,
     log,
     warn,
   });
 }
 
+async function sendEmbed(embed, { content = '' } = {}) {
+  if (!embed) return false;
+  try {
+    const channelId = bridge.activeTranscriptChannelId || settings.transcriptChannelId;
+    if (!channelId) return false;
+    const channel = await client.channels.fetch(channelId).catch(() => null);
+    if (!channel?.send) return false;
+    await channel.send(content ? { content, embeds: [embed] } : { embeds: [embed] });
+    return true;
+  } catch (e) {
+    warn('sendEmbed failed', e?.message || e);
+    return false;
+  }
+}
+
 async function sendChannelText(channel, text) {
   const body = String(text || '');
   const chunks = splitDiscordMessage(body);
@@ -771,18 +635,6 @@ async function sendChannelText(channel, text) {
   return true;
 }
 
-function sendVerboseProgressText(event, signal) {
-  if (!verboseProgress || !signal || signal.aborted || activeProgressSignal !== signal) return;
-  const formatted = formatProgressText(event).replace(/\s+/g, ' ').trim();
-  if (!formatted) return;
-  const message = formatted.slice(0, 1900);
-  const now = Date.now();
-  if (message === lastVerboseProgressText && now - lastVerboseProgressTextAt < 2000) return;
-  lastVerboseProgressText = message;
-  lastVerboseProgressTextAt = now;
-  void sendText(message).catch(e => warn('verbose progress text delivery failed', e?.stack || e));
-}
-
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -798,83 +650,240 @@ function waitEvent(emitter, event, timeoutMs = 60000) {
   });
 }
 
-async function transcribeOnce(wavPath, input16k, outBase) {
-  const args = ['-m', settings.whisperModel, '-f', input16k];
-  if (shouldPassWhisperLanguage(settings.whisperLanguage)) args.push('-l', settings.whisperLanguage);
-  args.push('-nt', '-otxt', '-of', outBase, '-sns', '-nf', '-nth', '0.35', '-et', '2.2', '-lpt', '-0.8');
-  try {
-    await execFileAsync(settings.whisperBin, args, { timeout: 25000, maxBuffer: 2 * 1024 * 1024 });
-  } catch (e) {
-    throw new Error(`whisper failed: ${e.stderr || e.message}`);
-  }
-  const txtPath = `${outBase}.txt`;
-  const raw = fs.existsSync(txtPath) ? fs.readFileSync(txtPath, 'utf8') : '';
-  return { raw, txtPath };
-}
-
-async function transcribe(wavPath) {
-  const tmpBase = path.join(os.tmpdir(), `hermes-node-stt-${Date.now()}`);
-  const input16k = `${tmpBase}.16k.wav`;
-  const outBase = `${tmpBase}.out`;
-  // whisper.cpp can read WAV, but Discord receiver output is 48 kHz stereo.
-  // Convert explicitly to the 16 kHz mono PCM shape Whisper expects.
-  await execFileAsync('ffmpeg', ['-y', '-hide_banner', '-loglevel', 'error', '-i', wavPath, '-ac', '1', '-ar', '16000', '-sample_fmt', 's16', input16k], {
-    timeout: 20000,
-    maxBuffer: 1024 * 1024,
-  });
-
-  let raw = '';
-  let txtPath = '';
-  try {
-    ({ raw, txtPath } = await transcribeOnce(wavPath, input16k, outBase));
-    let cleaned = cleanTranscript(raw);
-    log('stt raw', JSON.stringify(raw.trim()).slice(0, 500), 'cleaned', JSON.stringify(cleaned).slice(0, 500));
-    if (!cleaned) {
-      await sleep(300);
-      const retryBase = `${tmpBase}.retry`;
-      const retry = await transcribeOnce(wavPath, input16k, retryBase);
-      raw = retry.raw;
-      txtPath = retry.txtPath;
-      cleaned = cleanTranscript(raw);
-      log('stt retry raw', JSON.stringify(raw.trim()).slice(0, 500), 'cleaned', JSON.stringify(cleaned).slice(0, 500));
-    }
-    return cleaned;
-  } finally {
-    if (settings.debugDir) {
-      const debug16k = path.join(settings.debugDir, `stt-input-${stamp()}.wav`);
-      fs.copyFile(input16k, debug16k, () => {});
-      if (raw) fs.writeFile(path.join(settings.debugDir, `stt-raw-${stamp()}.txt`), raw, () => {});
-    }
-    fs.rm(input16k, { force: true }, () => {});
-    if (txtPath) fs.rm(txtPath, { force: true }, () => {});
-  }
-}
-
-function cleanTranscript(raw) {
-  const bad = [
-    '구독', '좋아요', '알림설정', '시청해주셔서', '시청해주신', '다음영상', '영상에서만나요',
-    '부탁드려요', '큰힘이됩니다',
-    'mbc뉴스', '이준범기자입니다', '뉴스입니다', '기자입니다', '앵커', '속보', '보도입니다', '전해드립니다',
-  ];
-  const lines = raw
-    .split(/\r?\n/)
-    .map(l => l.trim())
-    .filter(Boolean)
-    .map(l => l.replace(/^\[[^\]]+\]\s*/, '').trim());
-  const kept = [];
-  for (const line of lines) {
-    const compact = line
-      .replace(/\s+/g, '')
-      .replace(/[\p{P}\p{S}_]+/gu, '');
-    if (!compact) continue;
-    if (/^[\(\[（【].*[\)\]）】]$/.test(line.replace(/\s+/g, ''))) continue;
-    if (['끄덕', '끄덕끄덕', '박수', '웃음', '음악', '자막', '침묵', '무음'].includes(compact)) continue;
-    if (bad.some(b => compact.toLowerCase().includes(b))) continue;
-    if (isRepeatedNoiseTranscript(compact)) continue;
-    kept.push(line);
-  }
-  return kept.join(' ').trim();
-}
+// handleRecording lives inside utteranceRouter (extracted in Phase 4b) but
+// voiceIO.flushUtterance needs to call it. Use a forward-declared `let` plus
+// a thunk so the deps for createVoiceIO resolve before createUtteranceRouter
+// is constructed.
+let utteranceRouter;
+let voiceTurnRunner;
+const voiceIO = createVoiceIO({
+  bridge,
+  settings,
+  client,
+  execFileAsync,
+  log,
+  warn,
+  stamp,
+  sleep,
+  isAllowed,
+  UTTERANCE_IDLE_MS,
+  SUBSCRIBE_AFTER_SILENCE_MS,
+  MIN_UTTERANCE_BYTES,
+  MIN_MEAN_VOLUME_DB,
+  MIN_MAX_VOLUME_DB,
+  currentBargeInThresholds,
+  currentPlaybackBargeInThresholds,
+  createLiveBargeInMonitor,
+  shouldUseLivePlaybackBargeIn,
+  stopPlaybackForBargeIn,
+  analyzeAudio,
+  concatWavs,
+  saveCapturedVoiceCloneSample,
+  isBargeInCandidate,
+  validateProcessingBargeIn,
+  enqueueDeferredProcessingUtterance,
+  newLatencyTurn,
+  handleRecording: (...args) => voiceTurnRunner.handleRecording(...args),
+});
+const { transcribeOnce, transcribe, cleanTranscript, queueSegment, flushUtterance, subscribeUser } = voiceIO;
+
+const discordVoiceSetup = createDiscordVoiceSetup({
+  bridge,
+  client,
+  settings,
+  ROOT,
+  log,
+  warn,
+  speakText,
+  waitEvent,
+  subscribeUser,
+  pendingFallbackNoticePromises,
+  bindProjectSessionToChannel,
+  createProjectSession,
+  resolveProjectSessionForChannel,
+  saveProjectSessionsState,
+  projectSessionsState,
+  invalidateBackendAdaptersForSession,
+  VOICE_CONNECT_TIMEOUT_MS,
+});
+const {
+  connectTo,
+  autoJoin,
+  findVoiceChannelBySelector,
+  voiceChannelLabel,
+  resolveVoiceChannelForAttach,
+  attachVoiceChannelToTextSession,
+  gracefulShutdown,
+} = discordVoiceSetup;
+utteranceRouter = createUtteranceRouter({
+  bridge,
+  agentTurnLifecycle,
+  log,
+  warn,
+  path,
+  fs,
+  ROOT,
+  TTS_VOICE_CONFIG_PATH,
+  agentAdapter,
+  settings,
+  isPlanEntryUtterance,
+  parsePlanOutput,
+  parsePlanVoiceCommand,
+  applyPlanCommand,
+  renderFinalPlan,
+  planModePreamble,
+  planExecutionPreamble,
+  parseDecisionAnswer,
+  renderDecisionPrompt,
+  renderResolvedDecisions,
+  isAgentRoutingDecision,
+  projectSessionContextText,
+  resolveProjectSessionForChannel,
+  createBridgeAgentAdapter,
+  buildAgentSettings,
+  commandIsInstalled,
+  shellSplit,
+  sendText,
+  speakText,
+  ensureTtsVoiceConfig,
+  updateTtsVoiceConfig,
+  writeTtsVoiceConfig,
+  applyVoiceConfigToProcessEnv,
+  ensureSelectedTtsBackendInstalled,
+  rebuildTtsRuntimeSettings,
+  voiceCommandFromTranscript,
+  voiceChangedText,
+  voiceLanguageCommandFromTranscript,
+  voiceCloneCommandFromText,
+  voiceCloneCapture,
+  notifyVoiceCloneSampleGapIfNeeded,
+  languageChangedText,
+  applyRuntimeLanguage,
+  persistEnvValues,
+  discardVoiceInputQueues,
+  // Phase 4b deps
+  transcribe,
+  beginStreamingTurn,
+  endStreamingTurn,
+  client,
+  isAllowed,
+  isAbortError,
+  sleep,
+  sendEmbed,
+  speakImmediateNotice,
+  reloadRuntimeLanguageFromEnv,
+  drainDeferredProcessingUtterances,
+  maybeNotifyTaskComplete,
+  ontologyStateFor,
+  captureOntologyFromTurn,
+  queueProgressSpeechText,
+  stopProgressSpeech,
+  agentAnswerHeader,
+  emptyAgentAnswer,
+  formatRecentDiscordContext,
+  formatSttResultMessage,
+  formatSttStartMessage,
+  formatVoiceErrorMessage,
+  formatWakeRejectedMessage,
+  spokenResultOnly,
+  stripWake,
+  acceptsWake,
+  sensitivityChangedSpeech,
+  sensitivityModeFromTranscript,
+  sensitivityStatusText,
+  setSensitivityMode,
+  isSensitivityOnlyRequest,
+  verboseChangedSpeech,
+  verboseModeFromTranscript,
+  verboseStatusText,
+  setVerboseProgress,
+  isVerboseOnlyRequest,
+  isRoutingOnlyUtterance,
+  parseAgentRoutingCommand,
+  renderAgentPrefix,
+  buildCrossAgentPrompt,
+  buildFallbackDecision,
+  parseResearchCommand,
+  runResearchTurn,
+  PROGRESS_IDLE_CHECK_MS,
+  PROGRESS_IDLE_NOTICE_INITIAL_MS,
+  PROGRESS_IDLE_NOTICE_LIMIT,
+  PROGRESS_IDLE_NOTICE_MAX_MS,
+  PROGRESS_IDLE_NOTICE_MULTIPLIER,
+  STT_START_VOICE_NOTICE,
+});
+const {
+  adapterForProjectSession,
+  routingStateFor,
+  recordUtterance,
+  clearTransientRouting,
+  adapterForBackend,
+  handleTtsVoiceCommand,
+  handleLanguageCommand,
+  handleVoiceCloneCommand,
+  interruptCurrentResponse,
+} = utteranceRouter;
+
+const planDispatcher = createPlanDispatcher({
+  bridge, settings,
+  sendText, speakText,
+  routingStateFor, adapterForBackend, adapterForProjectSession,
+  resolveProjectSessionForChannel,
+  isAgentRoutingDecision,
+  parseDecisionAnswer, parsePlanVoiceCommand: parsePlanVoiceCommand,
+  applyPlanCommand: applyPlanCommand,
+  parsePlanOutput,
+  renderDecisionPrompt, renderResolvedDecisions, renderFinalPlan,
+  planModePreamble, planExecutionPreamble, isPlanEntryUtterance,
+});
+const {
+  planChannelKey,
+  askNextDecision,
+  finalizePlanReady,
+  dispatchPlanModeUtterance,
+  planNarrationLines,
+} = planDispatcher;
+
+voiceTurnRunner = createVoiceTurnRunner({
+  bridge,
+  agentTurnLifecycle,
+  settings, client, log, warn, fs,
+  // From voice_io
+  transcribe,
+  // From tts_player
+  beginStreamingTurn, endStreamingTurn, speakText,
+  // From progress_handler
+  queueProgressSpeechText, stopProgressSpeech, speakImmediateNotice,
+  // From notification_handler
+  maybeNotifyTaskComplete,
+  // From utterance_router (sibling-module dispatch + adapter selection)
+  handleLanguageCommand, handleTtsVoiceCommand, handleVoiceCloneCommand,
+  dispatchPlanModeUtterance,
+  adapterForBackend, adapterForProjectSession,
+  planChannelKey, routingStateFor, recordUtterance, clearTransientRouting,
+  // Direct (imported in main or hoisted helpers)
+  isAllowed, isAbortError, sleep, sendText, sendEmbed,
+  reloadRuntimeLanguageFromEnv, drainDeferredProcessingUtterances,
+  resolveProjectSessionForChannel, projectSessionContextText,
+  ontologyStateFor, captureOntologyFromTurn,
+  formatRecentDiscordContext,
+  formatSttResultMessage, formatSttStartMessage,
+  formatVoiceErrorMessage, formatWakeRejectedMessage,
+  agentAnswerHeader, emptyAgentAnswer, spokenResultOnly,
+  stripWake, acceptsWake,
+  sensitivityChangedSpeech, sensitivityModeFromTranscript, sensitivityStatusText,
+  setSensitivityMode, isSensitivityOnlyRequest,
+  verboseChangedSpeech, verboseModeFromTranscript, verboseStatusText,
+  setVerboseProgress, isVerboseOnlyRequest,
+  isRoutingOnlyUtterance, parseAgentRoutingCommand, renderAgentPrefix,
+  buildCrossAgentPrompt, buildFallbackDecision,
+  parseDecisionAnswer,
+  parseResearchCommand, runResearchTurn,
+  PROGRESS_IDLE_CHECK_MS, PROGRESS_IDLE_NOTICE_INITIAL_MS,
+  PROGRESS_IDLE_NOTICE_LIMIT, PROGRESS_IDLE_NOTICE_MAX_MS,
+  PROGRESS_IDLE_NOTICE_MULTIPLIER, STT_START_VOICE_NOTICE,
+});
+const { handleRecording } = voiceTurnRunner;
 
 function isAbortError(e) {
   return e?.name === 'AbortError' || e?.code === 'ABORT_ERR';
@@ -914,274 +923,45 @@ async function refreshTtsRuntimeConfig() {
   if (previousBackend !== settings.tts.backend) {
     const rebuilt = buildTtsSettings(process.env, ROOT);
     Object.assign(settings.tts, rebuilt);
-    ttsBackend = createTtsBackend(settings.tts, { execFileAsync, log, warn, voiceProvider: () => settings.tts.edge.voice });
+    try { bridge.ttsBackend?.close?.(); } catch (e) { warn('tts backend close failed', e?.message || e); }
+    bridge.ttsBackend = createTtsBackend(settings.tts, { execFileAsync, spawn, log, warn, onFallback: ttsFallbackNotice, voiceProvider: () => settings.tts.edge.voice });
     log('tts backend reloaded from voice config', settings.tts.backend, 'voiceType', selection.voiceType);
   }
   return selection;
 }
 
-async function synthTTS(text, signal) {
-  await refreshTtsRuntimeConfig();
-  let lastError = null;
-  for (let attempt = 1; attempt <= 3; attempt += 1) {
-    try {
-      log('final tts synth start', 'backend', ttsBackend.name, 'attempt', attempt, 'chars', String(text || '').length);
-      const out = await ttsBackend.synthesize(text, { signal, kind: 'final' });
-      log('final tts synth done', 'backend', ttsBackend.name, 'attempt', attempt, out, fs.statSync(out).size);
-      return out;
-    } catch (e) {
-      lastError = e;
-      if (isAbortError(e) || signal?.aborted) throw e;
-      warn('final tts synth failed', 'attempt', attempt, e?.stderr?.toString?.().slice(-500) || e?.message || e);
-      await sleep(1000 * attempt);
-    }
-  }
-  throw lastError;
-}
-
-async function synthProgressTTS(text, signal) {
-  await refreshTtsRuntimeConfig();
-  const ext = ttsBackend.outputExtension || 'mp3';
-  const cachePath = path.join(settings.tts.progressCacheDir, progressTtsCacheFileName({
-    backendKeyParts: ttsBackend.cacheKeyParts(),
-    text,
-    ext,
-  }));
-  if (fs.existsSync(cachePath) && fs.statSync(cachePath).size > 0) {
-    log('progress tts cache hit', text, cachePath);
-    return cachePath;
-  }
-  log('progress tts cache miss', text);
-  const tmp = await ttsBackend.synthesize(text, { signal, kind: 'progress' });
-  fs.renameSync(tmp, cachePath);
-  return cachePath;
-}
-
-async function playAudio(file, { deleteAfter = true } = {}) {
-  if (!connection) return;
-  speaking = true;
-  try {
-    const resource = createAudioResource(file, { inputType: StreamType.Arbitrary, inlineVolume: true });
-    resource.volume?.setVolume(settings.tts.volume);
-    player.play(resource);
-    connection.subscribe(player);
-    await waitEvent(player, AudioPlayerStatus.Idle, 120000).catch(() => {});
-  } finally {
-    speaking = false;
-    if (deleteAfter) fs.rm(file, { force: true }, () => {});
-  }
-}
-
-async function speakText(text, signal, metricsTurn = null, options = {}) {
-  const chunks = splitForTTS(text, settings.tts.maxChars);
-  if (!chunks.length) return;
-  if (options.mirrorText !== false) {
-    await sendText(`${options.mirrorPrefix || '🔊 음성으로 읽는 내용'}:\n${String(text || '')}`);
-  }
-  log('TTS chunks', chunks.length, 'maxChars', settings.tts.maxChars, 'backend', ttsBackend.name);
-  const playbackGeneration = speechPlaybackGeneration;
-  const playbackStopped = () => playbackGeneration !== speechPlaybackGeneration;
-  let synthMs = 0;
-  let playMs = 0;
-  const ttsStart = Date.now();
-  await playChunkedTTSWithPrefetch(chunks, {
-    signal,
-    log,
-    synth: async chunk => {
-      if (playbackStopped()) return null;
-      const start = Date.now();
-      try { return await synthTTS(chunk, signal); }
-      finally { synthMs += Date.now() - start; }
-    },
-    play: async file => {
-      if (playbackStopped()) {
-        await fs.promises.rm(file, { force: true }).catch(() => {});
-        return;
-      }
-      const start = Date.now();
-      try { return await playAudio(file); }
-      finally { playMs += Date.now() - start; }
-    },
-    cleanup: file => fs.promises.rm(file, { force: true }),
-  });
-  metricsTurn?.stage('tts_synth', synthMs, { ttsChunks: chunks.length, spokenChars: String(text || '').length });
-  metricsTurn?.stage('tts_play', playMs);
-  metricsTurn?.stage('tts_total', Date.now() - ttsStart);
-}
-
-function beginStreamingTurn(signal) {
-  if (!STREAMING_TTS_ENABLED || !connection) return false;
-  streamingSpeechDelivered = false;
-  const sentencer = createSentencer({ minChars: 40, maxLatencyMs: 800 });
-  const queue = createStreamingTTSQueue({
-    synth: async text => synthTTS(text, signal),
-    play: async file => playAudio(file, { deleteAfter: false }),
-    cleanup: async file => { try { await fs.promises.rm(file, { force: true }); } catch {} },
-    signal,
-    log,
-  });
-  sentencer.on('sentence', text => {
-    if (signal?.aborted) return;
-    queue.enqueue(text);
-  });
-  activeSentencer = sentencer;
-  activeStreamingQueue = queue;
-  log('streaming turn begin');
-  return true;
-}
-
-async function endStreamingTurn() {
-  const sentencer = activeSentencer;
-  const queue = activeStreamingQueue;
-  activeSentencer = null;
-  activeStreamingQueue = null;
-  if (!sentencer || !queue) return;
-  try { sentencer.flush(); } catch (e) { warn('streaming sentencer flush failed', e?.stack || e); }
-  try { await queue.drain(); } catch (e) { warn('streaming queue drain failed', e?.stack || e); }
-  streamingSpeechDelivered = queue.size === 0;
-  log('streaming turn end');
-}
-
-async function speakProgress(text, signal) {
-  if (signal?.aborted) return;
-  try {
-    const mp3 = await synthProgressTTS(text, signal);
-    if (signal?.aborted) return;
-    await playAudio(mp3, { deleteAfter: false });
-  } catch (e) {
-    if (!isAbortError(e)) warn('progress tts failed', e?.stack || e);
-  }
-}
-
-async function speakImmediateNotice(text, signal, reason = 'notice') {
-  if (signal?.aborted) return;
-  try {
-    log('immediate notice speech', reason, 'text', String(text || '').slice(0, 80));
-    const mp3 = await synthProgressTTS(text, signal);
-    if (signal?.aborted) return;
-    await playAudio(mp3, { deleteAfter: false });
-  } catch (e) {
-    if (!isAbortError(e)) warn('immediate notice speech failed', reason, e?.stack || e);
-  }
-}
-
-function queueProgressSpeechText(text, signal, reason = 'status') {
-  const spoken = String(text || '').replace(/\s+/g, ' ').trim();
-  if (!spoken || !signal || signal.aborted || activeProgressSignal !== signal) return;
-  verboseProgressSpeechQueue = verboseProgressSpeechQueue
-    .catch(() => {})
-    .then(async () => {
-      if (signal.aborted || activeProgressSignal !== signal || !processing) return;
-      log('progress speech queued', reason, 'text', spoken);
-      await speakProgress(spoken, signal);
-    });
-}
-
-function flushProgressSpeechBatch(signal, reason = 'timer') {
-  if (!signal || signal.aborted || activeProgressSignal !== signal) return;
-  if (progressSpeechBatchTimer) {
-    clearTimeout(progressSpeechBatchTimer);
-    progressSpeechBatchTimer = null;
-  }
-  const events = progressSpeechBatch;
-  progressSpeechBatch = [];
-  progressSpeechBatchSignal = null;
-  progressSpeechBatchStartedAt = 0;
-  const text = summarizeProgressEvents(events, { maxCategories: 3, language: settings.voiceLanguage });
-  if (!text) return;
-  queueProgressSpeechText(text, signal, `batch-${reason}-${events.length}`);
-}
-
-function queueVerboseProgressSpeech(event, signal) {
-  if (!verboseProgress || !signal || signal.aborted || activeProgressSignal !== signal) return;
-  const text = String(event || '').replace(/\s+/g, ' ').trim().slice(0, 120);
-  if (!text) return;
-  if (progressSpeechBatchSignal && progressSpeechBatchSignal !== signal) {
-    progressSpeechBatch = [];
-    if (progressSpeechBatchTimer) clearTimeout(progressSpeechBatchTimer);
-    progressSpeechBatchTimer = null;
-    progressSpeechBatchStartedAt = 0;
-  }
-  progressSpeechBatchSignal = signal;
-  if (!progressSpeechBatchStartedAt) progressSpeechBatchStartedAt = Date.now();
-  progressSpeechBatch.push(text);
-  const elapsedMs = Date.now() - progressSpeechBatchStartedAt;
-  const ratePerSecond = progressSpeechBatch.length / Math.max(0.2, elapsedMs / 1000);
-  const maxBatchEvents = ratePerSecond >= 6 ? 5 : ratePerSecond >= 3 ? 4 : 3;
-  const batchDelayMs = ratePerSecond >= 6 ? 650 : ratePerSecond >= 3 ? 550 : 450;
-  if (progressSpeechBatch.length >= maxBatchEvents) {
-    flushProgressSpeechBatch(signal, 'full');
-    return;
-  }
-  if (progressSpeechBatchTimer) clearTimeout(progressSpeechBatchTimer);
-  progressSpeechBatchTimer = setTimeout(() => flushProgressSpeechBatch(signal, 'timer'), batchDelayMs);
-}
-
-function clearProgressSpeechBatch(signal = activeProgressSignal) {
-  if (progressSpeechBatchTimer) {
-    clearTimeout(progressSpeechBatchTimer);
-    progressSpeechBatchTimer = null;
-  }
-  if (!signal || progressSpeechBatchSignal === signal) {
-    progressSpeechBatch = [];
-    progressSpeechBatchSignal = null;
-    progressSpeechBatchStartedAt = 0;
-  }
-}
-
-function stopProgressSpeech(signal, reason = 'final-answer') {
-  if (activeProgressSignal !== signal) return;
-  clearProgressSpeechBatch(signal);
-  activeProgressSignal = null;
-  if (activeProgressAbortController && !activeProgressAbortController.signal.aborted) {
-    try { activeProgressAbortController.abort(); } catch (e) { warn('abort progress speech failed', e?.stack || e); }
-  }
-  if (speaking) {
-    log('stop progress speech before final answer', reason);
-    try { player.stop(true); } catch (e) { warn('stop progress speech failed', e?.stack || e); }
-    speaking = false;
-  }
-}
-
 async function handleTextAgentMessage(msg, text, { speakResponse = false } = {}) {
-  if (processing) {
+  if (bridge.processing) {
     await msg.reply('지금 이전 작업을 처리 중이야. 끝나면 다시 보내줘.');
     return;
   }
-  processing = true;
-  const controller = new AbortController();
-  currentAbortController = controller;
-  const signal = controller.signal;
-  const progressController = new AbortController();
-  activeProgressAbortController = progressController;
-  activeProgressSignal = progressController.signal;
-  activeProgressLastEventAt = Date.now();
-  const previousTranscriptChannelId = activeTranscriptChannelId;
+  const turn = agentTurnLifecycle.start();
+  const { controller, signal, progressController } = turn;
   const session = resolveProjectSessionForChannel(msg.channelId);
-  activeTranscriptChannelId = session?.transcriptChannelId || msg.channelId;
+  bridge.activeTranscriptChannelId = session?.transcriptChannelId || msg.channelId;
   const selectedAgentAdapter = adapterForProjectSession(session);
   const projectContext = projectSessionContextText(session);
-  const recentDiscordContext = formatRecentDiscordContext(recentDiscordTextByChannel, {
-    channelId: activeTranscriptChannelId,
+  const recentDiscordContext = formatRecentDiscordContext(bridge.recentDiscordTextByChannel, {
+    channelId: bridge.activeTranscriptChannelId,
   });
   const plan = {
     task: true,
     label: selectedAgentAdapter.label,
-    verboseProgress,
+    verboseProgress: bridge.verboseProgress,
     language: settings.voiceLanguage,
     cwd: session?.workdir,
     projectContext,
     recentDiscordContext,
   };
   const sessionBefore = selectedAgentAdapter.readSessionId?.();
-  log('text agent request start', selectedAgentAdapter.label, sessionBefore ? 'resume-existing-session' : 'new-session', 'verbose', verboseProgress, session ? `project=${session.slug}` : 'project=default');
+  log('text agent request start', selectedAgentAdapter.label, sessionBefore ? 'resume-existing-session' : 'new-session', 'verbose', bridge.verboseProgress, session ? `project=${session.slug}` : 'project=default');
   try {
     const result = await selectedAgentAdapter.run(text, signal, plan);
     const answer = result.answer || emptyAgentAnswer(settings.voiceLanguage);
     const fullAnswerText = `${agentAnswerHeader(settings.voiceLanguage, selectedAgentAdapter.label)}\n${answer}`;
     await sendChannelText(msg.channel, fullAnswerText);
     stopProgressSpeech(progressController.signal, 'text-agent-answer-ready');
-    if (speakResponse && connection) {
+    if (speakResponse && bridge.connection) {
       const spokenAnswer = spokenResultOnly(text, answer, settings.voiceLanguage);
       await speakText(spokenAnswer, signal, null, { mirrorText: false });
     }
@@ -1190,15 +970,11 @@ async function handleTextAgentMessage(msg, text, { speakResponse = false } = {})
     warn('text agent request failed', e?.stack || e);
     await sendChannelText(msg.channel, formatVoiceErrorMessage(settings.voiceLanguage, String(e?.message || e).slice(0, 800)));
   } finally {
-    if (activeProgressAbortController && activeProgressAbortController.signal === progressController.signal && !activeProgressAbortController.signal.aborted) {
-      try { activeProgressAbortController.abort(); } catch (e) { warn('abort text progress speech failed', e?.stack || e); }
-    }
-    if (activeProgressSignal === progressController.signal) activeProgressSignal = null;
-    if (activeProgressAbortController?.signal === progressController.signal) activeProgressAbortController = null;
+    // Text-path-only behaviour pre-refactor: drain the verbose-progress batch
+    // before tearing the controllers down. Kept explicit so the lifecycle's
+    // finish() can stay path-agnostic.
     clearProgressSpeechBatch(progressController.signal);
-    if (currentAbortController === controller) currentAbortController = null;
-    activeTranscriptChannelId = previousTranscriptChannelId;
-    processing = false;
+    agentTurnLifecycle.finish(turn);
   }
 }
 
@@ -1222,53 +998,6 @@ async function saveCapturedVoiceCloneSample(userId, wavPath, pcmBytes, segments,
   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 stopPlaybackForBargeIn(userId, reason = 'playback-barge-in') {
-  if (!speaking) return false;
-  log('stop playback for barge-in', 'byUser', userId, 'reason', reason, 'speaking', speaking, 'processing', processing, 'turn', activeTurnId);
-  speechPlaybackGeneration += 1;
-  try { player.stop(true); } catch (e) { warn('stop playback failed', e?.stack || e); }
-  speaking = false;
-  return true;
-}
-
-function interruptCurrentResponse(userId, reason = 'barge-in') {
-  if (!speaking && !processing) return false;
-  const turnId = activeTurnId;
-  if (turnId) interruptedTurns.add(turnId);
-  log('interrupt current response', 'byUser', userId, 'reason', reason, 'speaking', speaking, 'processing', processing, 'turn', turnId);
-  if (currentAbortController && !currentAbortController.signal.aborted) {
-    try { currentAbortController.abort(); } catch (e) { warn('abort current response failed', e?.stack || e); }
-  }
-  try { player.stop(true); } catch (e) { warn('stop playback failed', e?.stack || e); }
-  speaking = false;
-  processing = false;
-  return true;
-}
-
 function acceptsWake(text) {
   if (!settings.requireWakeWord) return true;
   const low = text.toLowerCase();
@@ -1316,17 +1045,6 @@ async function concatWavs(files, output) {
   }
 }
 
-function queueSegment(userId, file, pcmBytes, startedAtMs = Date.now(), endedAtMs = Date.now()) {
-  const pending = bridgeState.appendSegment(userId, {
-    file,
-    pcmBytes,
-    startedAtMs,
-    endedAtMs,
-    timerFactory: () => setTimeout(() => flushUtterance(userId).catch(e => warn('flushUtterance failed', userId, e?.stack || e)), UTTERANCE_IDLE_MS),
-  });
-  log('queued segment', userId, 'segments', pending.files.length, 'totalPcmBytes', pending.pcmBytes, 'idleMs', UTTERANCE_IDLE_MS, 'epoch', pending.epoch);
-}
-
 function isBargeInCandidate(pcmBytes, levels) {
   const thresholds = currentBargeInThresholds();
   return isValidatedBargeInCandidate(pcmBytes, levels, thresholds);
@@ -1334,7 +1052,7 @@ function isBargeInCandidate(pcmBytes, levels) {
 
 function enqueueDeferredProcessingUtterance({ userId, wavPath, pcmBytes, segments, startedAtMs = Date.now() }) {
   const item = { userId, wavPath, pcmBytes, segments, startedAtMs };
-  const result = bridgeState.enqueueDeferred(item, enqueueDeferredUtterance, MAX_DEFERRED_PROCESSING_UTTERANCES);
+  const result = bridge.bridgeState.enqueueDeferred(item, enqueueDeferredUtterance, MAX_DEFERRED_PROCESSING_UTTERANCES);
   if (!result.queued) {
     log('drop deferred utterance because queue disabled', userId, wavPath, 'max', MAX_DEFERRED_PROCESSING_UTTERANCES);
     return false;
@@ -1342,15 +1060,15 @@ function enqueueDeferredProcessingUtterance({ userId, wavPath, pcmBytes, segment
   if (result.dropped) {
     log('drop oldest deferred utterance because queue is full', result.dropped?.userId, result.dropped?.wavPath);
   }
-  log('queued deferred utterance while processing', userId, wavPath, 'queueSize', bridgeState.deferredSize(), 'epoch', bridgeState.currentEpoch());
+  log('queued deferred utterance while processing', userId, wavPath, 'queueSize', bridge.bridgeState.deferredSize(), 'epoch', bridge.bridgeState.currentEpoch());
   return true;
 }
 
 async function drainDeferredProcessingUtterances() {
-  if (processing || bridgeState.deferredSize() === 0) return;
-  const next = bridgeState.shiftDeferred();
+  if (bridge.processing || bridge.bridgeState.deferredSize() === 0) return;
+  const next = bridge.bridgeState.shiftDeferred();
   if (!next) return;
-  log('drain deferred utterance', next.userId, next.wavPath, 'remaining', bridgeState.deferredSize());
+  log('drain deferred utterance', next.userId, next.wavPath, 'remaining', bridge.bridgeState.deferredSize());
   const metricsTurn = newLatencyTurn(next.userId, next.startedAtMs || Date.now());
   metricsTurn.mark('voice_first_packet', next.startedAtMs || Date.now());
   metricsTurn.mark('utterance_flush');
@@ -1374,398 +1092,6 @@ async function validateProcessingBargeIn(userId, wavPath, pcmBytes, segments) {
   return { action: 'interrupt', text };
 }
 
-async function flushUtterance(userId) {
-  const pending = bridgeState.deletePending(userId);
-  if (!pending) return;
-  if (pending.timer) clearTimeout(pending.timer);
-  const files = pending.files;
-  const pcmBytes = pending.pcmBytes;
-  const metricsTurn = newLatencyTurn(userId, pending.firstPacketAt || Date.now());
-  metricsTurn.mark('voice_first_packet', pending.firstPacketAt || Date.now());
-  metricsTurn.mark('voice_segment_end', pending.lastSegmentEndAt || Date.now());
-  metricsTurn.mark('utterance_flush');
-  metricsTurn.addMeta({ segments: files.length, pcmBytes, epoch: pending.epoch });
-  if (pending.epoch !== bridgeState.currentEpoch()) {
-    log('drop stale utterance after voice input queue reset', userId, 'utteranceEpoch', pending.epoch, 'currentEpoch', bridgeState.currentEpoch());
-    for (const file of files) fs.rm(file, { force: true }, () => {});
-    metricsTurn.finish({ status: 'stale_after_config_change' });
-    return;
-  }
-  if (pcmBytes < MIN_UTTERANCE_BYTES) {
-    log('skip short utterance', userId, 'segments', files.length, 'pcmBytes', pcmBytes, 'minBytes', MIN_UTTERANCE_BYTES);
-    metricsTurn.finish({ status: 'skip_short' });
-    return;
-  }
-  const merged = path.join(settings.debugDir, `utterance-merged-${stamp()}-${userId}.wav`);
-  await concatWavs(files, merged);
-  const levels = await analyzeAudio(merged);
-  log('utterance levels', userId, 'segments', files.length, 'pcmBytes', pcmBytes, 'meanDb', levels.meanDb, 'maxDb', levels.maxDb);
-  if (await saveCapturedVoiceCloneSample(userId, merged, pcmBytes, files.length)) {
-    metricsTurn.addMeta({ meanDb: levels.meanDb, maxDb: levels.maxDb });
-    metricsTurn.finish({ status: 'voice_clone_sample_saved' });
-    return;
-  }
-  const candidate = isBargeInCandidate(pcmBytes, levels);
-  if (speaking || processing) {
-    const thresholds = currentBargeInThresholds();
-    if (!candidate) {
-      log('check weak barge-in for explicit stop transcript', userId, 'pcmBytes', pcmBytes, 'meanDb', levels.meanDb, 'maxDb', levels.maxDb, 'thresholdBytes', thresholds.minBytes, 'thresholds', thresholds.minMeanDb, thresholds.minMaxDb, 'mode', thresholds.mode);
-    }
-    const validation = await validateProcessingBargeIn(userId, merged, pcmBytes, files.length);
-    if (validation?.action === 'interrupt') {
-      metricsTurn.finish({ status: processing ? 'barge_in_processing_interrupt' : 'barge_in_playback_interrupt' });
-      return;
-    }
-    if (processing && validation?.action === 'defer') {
-      const queued = enqueueDeferredProcessingUtterance({
-        userId,
-        wavPath: merged,
-        pcmBytes,
-        segments: files.length,
-        startedAtMs: pending.firstPacketAt || Date.now(),
-      });
-      metricsTurn.finish({ status: queued ? 'deferred_during_processing' : 'drop_deferred_during_processing' });
-      return;
-    }
-    metricsTurn.finish({ status: speaking ? 'barge_in_playback_ignored' : 'barge_in_processing_ignored' });
-    return;
-  }
-  // Drop only when BOTH overall energy and peak are low. Real Discord speech from this
-  // mic can have low mean volume while still carrying intelligible peaks; using OR here
-  // caused valid Korean utterances to be discarded as "low-energy".
-  if (levels.meanDb < MIN_MEAN_VOLUME_DB && levels.maxDb < MIN_MAX_VOLUME_DB) {
-    log('skip low-energy utterance', userId, 'meanDb', levels.meanDb, 'maxDb', levels.maxDb, 'thresholds', MIN_MEAN_VOLUME_DB, MIN_MAX_VOLUME_DB, 'mode', 'both-below');
-    metricsTurn.addMeta({ meanDb: levels.meanDb, maxDb: levels.maxDb });
-    metricsTurn.finish({ status: 'skip_low_energy' });
-    return;
-  }
-  metricsTurn.addMeta({ meanDb: levels.meanDb, maxDb: levels.maxDb });
-  await handleRecording(userId, merged, pcmBytes, files.length, metricsTurn);
-}
-
-async function handleRecording(userId, wavPath, pcmBytes, segments = 1, metricsTurn = null) {
-  if (processing) { log('drop while processing', userId); metricsTurn?.finish({ status: 'drop_processing' }); return; }
-  if (!isAllowed(userId)) { warn('ignore unauthorized', userId); metricsTurn?.finish({ status: 'unauthorized' }); return; }
-  processing = true;
-  const turnId = ++activeTurnId;
-  const controller = new AbortController();
-  currentAbortController = controller;
-  const signal = controller.signal;
-  const sessionForVoice = resolveProjectSessionForChannel(activeVoiceChannelId || settings.transcriptChannelId);
-  const previousTranscriptChannelId = activeTranscriptChannelId;
-  activeTranscriptChannelId = sessionForVoice?.transcriptChannelId || settings.transcriptChannelId;
-  try {
-    const runtimeLanguage = reloadRuntimeLanguageFromEnv();
-    if (runtimeLanguage.changed) {
-      log('drop current utterance because language changed before STT', userId, 'turn', turnId, 'language', runtimeLanguage.voiceLanguage);
-      fs.rm(wavPath, { force: true }, () => {});
-      metricsTurn?.finish({ status: 'drop_stale_language_change' });
-      return;
-    }
-    const session = resolveProjectSessionForChannel(activeVoiceChannelId || settings.transcriptChannelId);
-    activeTranscriptChannelId = session?.transcriptChannelId || settings.transcriptChannelId;
-    log('voice turn text target', session ? `project=${session.slug}` : 'project=default', 'channel', activeTranscriptChannelId ? 'project-or-default' : 'none');
-    log('transcribing', userId, wavPath, 'pcmBytes', pcmBytes, 'segments', segments, 'turn', turnId);
-    const sttNotice = formatSttStartMessage(settings.voiceLanguage);
-    await sendText(sttNotice);
-    const sttNoticeSpeech = STT_START_VOICE_NOTICE
-      ? speakImmediateNotice(sttNotice.replace(/^🎧\s*/u, ''), signal, 'stt-start')
-      : Promise.resolve();
-    const sttStart = Date.now();
-    const text = await transcribe(wavPath);
-    await sttNoticeSpeech;
-    metricsTurn?.stage('stt', Date.now() - sttStart, { transcriptChars: String(text || '').length });
-    if (interruptedTurns.has(turnId) || signal.aborted) { metricsTurn?.finish({ status: 'aborted_after_stt' }); return; }
-    if (!text) { log('empty transcript', userId, wavPath); metricsTurn?.finish({ status: 'empty_transcript' }); return; }
-    log(`user ${userId} said: ${text}`);
-    await sendText(formatSttResultMessage(settings.voiceLanguage, userId, text));
-    if (!acceptsWake(text)) { await sendText(formatWakeRejectedMessage(settings.voiceLanguage)); metricsTurn?.finish({ status: 'wake_rejected' }); return; }
-
-    const prompt = stripWake(text);
-    if (await handleLanguageCommand(prompt, signal)) {
-      metricsTurn?.finish({ status: 'language_command' });
-      return;
-    }
-    if (await handleTtsVoiceCommand(prompt, signal)) {
-      metricsTurn?.finish({ status: 'voice_command' });
-      return;
-    }
-    if (await handleVoiceCloneCommand(userId, prompt, signal)) {
-      metricsTurn?.finish({ status: 'voice_clone_command' });
-      return;
-    }
-    const sensitivityRequest = sensitivityModeFromTranscript(prompt);
-    if (sensitivityRequest) {
-      const thresholds = setSensitivityMode(sensitivityRequest.mode, sensitivityRequest.reason);
-      await sendText(`🎚️ ${sensitivityStatusText()}`);
-      if (isSensitivityOnlyRequest(prompt)) {
-        await speakText(sensitivityChangedSpeech(thresholds.mode, settings.voiceLanguage), signal, metricsTurn);
-        metricsTurn?.finish({ status: 'sensitivity_only' });
-        return;
-      }
-    }
-    const verboseRequest = verboseModeFromTranscript(prompt);
-    if (verboseRequest !== null) {
-      setVerboseProgress(verboseRequest, 'voice-command');
-      await sendText(`🔎 ${verboseStatusText()}`);
-      if (isVerboseOnlyRequest(prompt)) {
-        await speakText(verboseChangedSpeech(verboseRequest, settings.voiceLanguage), signal, metricsTurn);
-        metricsTurn?.finish({ status: 'verbose_only' });
-        return;
-      }
-    }
-    let promptForAgent = prompt;
-    try {
-      const planOutcome = await dispatchPlanModeUtterance(prompt, signal);
-      if (planOutcome.handled) {
-        metricsTurn?.finish({ status: 'plan_mode' });
-        return;
-      }
-      if (planOutcome.prompt) promptForAgent = planOutcome.prompt;
-    } catch (e) {
-      warn('plan mode dispatch failed', e?.stack || e);
-    }
-    const selectedAgentAdapter = adapterForProjectSession(session);
-    const projectContext = projectSessionContextText(session);
-    const recentDiscordContext = formatRecentDiscordContext(recentDiscordTextByChannel, {
-      channelId: activeTranscriptChannelId,
-    });
-    const plan = {
-      task: true,
-      label: selectedAgentAdapter.label,
-      verboseProgress,
-      language: settings.voiceLanguage,
-      cwd: session?.workdir,
-      projectContext,
-      recentDiscordContext,
-    };
-    log('Agent plan', plan.label, 'backend', selectedAgentAdapter.backend, 'task', plan.task, 'language', plan.language, session ? `project=${session.slug}` : 'project=default');
-    const agentStart = Date.now();
-    const progressController = new AbortController();
-    activeProgressAbortController = progressController;
-    activeProgressSignal = progressController.signal;
-    activeProgressLastEventAt = Date.now();
-    const streamingTurnActive = beginStreamingTurn(signal);
-    const agentPromise = selectedAgentAdapter.ask(promptForAgent, signal, plan);
-    let done = false;
-    // Status announcements share one queue with verbose progress so they never
-    // talk over each other. In verbose mode, skip the generic initial prompt;
-    // the detailed tool/file/test events are the initial progress voice.
-    const progressLoop = (async () => {
-      if (!verboseProgress) {
-        await sleep(2500);
-        if (!done && !signal.aborted && !interruptedTurns.has(turnId)) {
-          const initial = /^en/i.test(String(settings.voiceLanguage || ''))
-            ? 'calling the agent.'
-            : '에이전트 호출했어. 응답 기다리는 중.';
-          queueProgressSpeechText(initial, progressController.signal, 'generic-initial');
-        }
-      }
-      let idleNotices = 0;
-      let nextIdleNoticeMs = PROGRESS_IDLE_NOTICE_INITIAL_MS;
-      let lastObservedProgressAt = activeProgressLastEventAt;
-      while (!done && !signal.aborted && !interruptedTurns.has(turnId) && idleNotices < PROGRESS_IDLE_NOTICE_LIMIT) {
-        await sleep(Math.min(PROGRESS_IDLE_CHECK_MS, nextIdleNoticeMs));
-        if (done || signal.aborted || interruptedTurns.has(turnId)) break;
-        if (activeProgressLastEventAt !== lastObservedProgressAt) {
-          lastObservedProgressAt = activeProgressLastEventAt;
-          nextIdleNoticeMs = PROGRESS_IDLE_NOTICE_INITIAL_MS;
-          continue;
-        }
-        const idleMs = Date.now() - activeProgressLastEventAt;
-        if (idleMs < nextIdleNoticeMs) continue;
-        idleNotices += 1;
-        activeProgressLastEventAt = Date.now();
-        lastObservedProgressAt = activeProgressLastEventAt;
-        const idle = /^en/i.test(String(settings.voiceLanguage || ''))
-          ? 'still working on that.'
-          : '아직 작업 중이야.';
-        queueProgressSpeechText(idle, progressController.signal, `idle-${idleNotices}-${Math.round(nextIdleNoticeMs / 1000)}s`);
-        nextIdleNoticeMs = Math.min(
-          PROGRESS_IDLE_NOTICE_MAX_MS,
-          Math.max(nextIdleNoticeMs + 1000, Math.round(nextIdleNoticeMs * PROGRESS_IDLE_NOTICE_MULTIPLIER)),
-        );
-      }
-    })().catch(e => {
-      if (!isAbortError(e)) warn('progress loop failed', e?.stack || e);
-    });
-    const answer = await agentPromise.finally(() => { done = true; });
-    if (streamingTurnActive) await endStreamingTurn();
-    metricsTurn?.stage('agent', Date.now() - agentStart, { answerChars: String(answer || '').length, backend: selectedAgentAdapter.backend });
-    void progressLoop;
-    if (interruptedTurns.has(turnId) || signal.aborted) { metricsTurn?.finish({ status: 'aborted_after_agent' }); return; }
-
-    log('Agent answer', selectedAgentAdapter.label, answer.slice(0, 200));
-    const spokenAnswer = spokenResultOnly(prompt, answer, settings.voiceLanguage);
-    const fullAnswerText = `${agentAnswerHeader(settings.voiceLanguage, selectedAgentAdapter.label)}\n${answer || emptyAgentAnswer(settings.voiceLanguage)}`;
-    log('send agent answer text', 'chars', fullAnswerText.length);
-    const answerTextDelivered = await sendText(fullAnswerText);
-    if (!answerTextDelivered) {
-      warn('agent answer text delivery failed; still speaking answer');
-    }
-    log('spoken answer', spokenAnswer.slice(0, 200));
-    stopProgressSpeech(progressController.signal, 'agent-answer-ready');
-    if (streamingTurnActive && streamingSpeechDelivered) {
-      log('skipping post-run speakText; streaming already delivered audio');
-    } else {
-      await speakText(spokenAnswer, signal, metricsTurn, { mirrorText: !answerTextDelivered });
-    }
-    try {
-      const guildId = client.channels.cache.get(activeVoiceChannelId)?.guild?.id || '';
-      await maybeNotifyTaskComplete({
-        answer: spokenAnswer || answer,
-        label: selectedAgentAdapter.label,
-        elapsedMs: Date.now() - agentStart,
-        guildId,
-      });
-    } catch (e) { warn('maybeNotifyTaskComplete failed', e?.message || e); }
-    metricsTurn?.finish({ status: 'ok' });
-  } catch (e) {
-    if (isAbortError(e) || interruptedTurns.has(turnId)) {
-      log('turn aborted', userId, 'turn', turnId);
-      metricsTurn?.finish({ status: 'aborted' });
-      return;
-    }
-    warn('handleRecording failed', e?.stack || e);
-    const shortMsg = String(e?.message || e).slice(0, 800);
-    metricsTurn?.finish({ status: 'error', error: shortMsg });
-    await sendText(formatVoiceErrorMessage(settings.voiceLanguage, shortMsg));
-  } finally {
-    if (activeProgressAbortController && !activeProgressAbortController.signal.aborted) {
-      try { activeProgressAbortController.abort(); } catch (e) { warn('abort progress speech in cleanup failed', e?.stack || e); }
-    }
-    if (activeProgressSignal === activeProgressAbortController?.signal) activeProgressSignal = null;
-    activeProgressAbortController = null;
-    if (currentAbortController === controller) currentAbortController = null;
-    activeTranscriptChannelId = previousTranscriptChannelId;
-    interruptedTurns.delete(turnId);
-    if (activeTurnId === turnId) activeTurnId = 0;
-    processing = false;
-    if (bridgeState.deferredSize() > 0) {
-      setImmediate(() => drainDeferredProcessingUtterances().catch(e => warn('drain deferred utterance failed', e?.stack || e)));
-    }
-  }
-}
-
-function subscribeUser(receiver, userId) {
-  if (!isAllowed(userId)) return;
-  if (String(userId) === client.user?.id) return;
-  const wasSpeaking = speaking;
-  const wasProcessing = processing;
-  if ((wasSpeaking || wasProcessing) && !activeStreams.has(userId)) {
-    // Speaking-start alone is too noisy in Discord voice. Record and validate a
-    // real segment first; only confirmed playback barge-in stops the current
-    // audio chunk, and only explicit stop transcripts abort active agent work.
-    log('possible barge-in start; waiting for segment validation', userId, 'speaking', wasSpeaking, 'processing', wasProcessing);
-  }
-  if (activeStreams.has(userId)) return;
-  const pending = bridgeState.getPending(userId);
-  if (pending?.timer) {
-    bridgeState.clearPendingTimer(userId);
-    log('extend pending utterance because new segment started', userId, 'segments', pending.files.length, 'totalPcmBytes', pending.pcmBytes);
-  }
-
-  const file = path.join(settings.debugDir, `segment-${stamp()}-${userId}.wav`);
-  log('subscribe user', userId, file);
-  const opusStream = receiver.subscribe(userId, { end: { behavior: EndBehaviorType.AfterSilence, duration: SUBSCRIBE_AFTER_SILENCE_MS } });
-  const decoder = new prism.opus.Decoder({ rate: 48000, channels: 2, frameSize: 960 });
-  const writer = new wav.FileWriter(file, { sampleRate: 48000, channels: 2, bitDepth: 16 });
-  activeStreams.set(userId, { opusStream, decoder, writer, file, startedAtMs: Date.now() });
-  let pcmBytes = 0;
-  const liveThresholds = wasSpeaking && !wasProcessing ? currentPlaybackBargeInThresholds() : currentBargeInThresholds();
-  const liveBargeIn = shouldUseLivePlaybackBargeIn({ speaking: wasSpeaking, processing: wasProcessing }) ? createLiveBargeInMonitor({
-    minBytes: liveThresholds.minBytes,
-    minMeanDb: liveThresholds.minMeanDb,
-    minMaxDb: liveThresholds.minMaxDb,
-    requireBoth: liveThresholds.requireBoth,
-    log,
-    onConfirm: ({ pcmBytes: confirmedBytes, levels }) => {
-      log('confirmed live playback barge-in before segment end', userId, 'pcmBytes', confirmedBytes, 'meanDb', levels.meanDb, 'maxDb', levels.maxDb);
-      stopPlaybackForBargeIn(userId, 'confirmed-live-playback-barge-in');
-    },
-  }) : null;
-  decoder.on('data', chunk => {
-    pcmBytes += chunk.length;
-    liveBargeIn?.push(chunk);
-  });
-  opusStream.on('error', e => warn('opus stream error', userId, e?.stack || e));
-  decoder.on('error', e => warn('opus decoder error', userId, e?.stack || e));
-  writer.on('error', e => warn('wav writer error', userId, e?.stack || e));
-  opusStream.on('end', () => log('opus end', userId, 'pcmBytes', pcmBytes));
-  writer.on('finish', () => {
-    const streamState = activeStreams.get(userId);
-    activeStreams.delete(userId);
-    const endedAtMs = Date.now();
-    log('saved segment', userId, 'pcmBytes', pcmBytes, file);
-    queueSegment(userId, file, pcmBytes, streamState?.startedAtMs || endedAtMs, endedAtMs);
-  });
-  opusStream.pipe(decoder).pipe(writer);
-}
-
-async function connectTo(channel) {
-  if (connection) {
-    try { connection.destroy(); } catch {}
-  }
-  activeVoiceChannelId = channel.id;
-  connection = joinVoiceChannel({
-    channelId: channel.id,
-    guildId: channel.guild.id,
-    adapterCreator: channel.guild.voiceAdapterCreator,
-    selfDeaf: false,
-    selfMute: false,
-  });
-  const voiceConnection = connection;
-  voiceConnection.subscribe(player);
-  voiceConnection.on('error', e => warn('voice connection error', e?.stack || e));
-  voiceConnection.on('stateChange', async (oldState, newState) => {
-    log('voice connection state', oldState.status, '->', newState.status);
-    if (connection !== voiceConnection) {
-      log('ignore stale voice connection state', oldState.status, '->', newState.status);
-      return;
-    }
-    if (newState.status === VoiceConnectionStatus.Disconnected) {
-      try {
-        await Promise.race([
-          entersState(voiceConnection, VoiceConnectionStatus.Signalling, 5000),
-          entersState(voiceConnection, VoiceConnectionStatus.Connecting, 5000),
-        ]);
-      } catch (e) {
-        if (connection !== voiceConnection) return;
-        warn('voice connection disconnected; reconnecting to channel', channel.guild.name, channel.name, e?.message || e);
-        try { voiceConnection.destroy(); } catch {}
-        connection = null;
-        setTimeout(() => connectTo(channel).catch(err => warn('voice reconnect failed', err?.stack || err)), 1500);
-      }
-    }
-  });
-  await entersState(voiceConnection, VoiceConnectionStatus.Ready, 30000);
-  voiceConnection.receiver.speaking.on('start', userId => subscribeUser(voiceConnection.receiver, userId));
-  log(`Listening in voice channel ${channel.guild.name} / ${channel.name}`);
-}
-
-async function autoJoin() {
-  const attempted = [];
-  for (const preferredName of settings.autoJoinVoiceChannels) {
-    for (const guild of client.guilds.cache.values()) {
-      const channels = await guild.channels.fetch();
-      for (const ch of channels.values()) {
-        if (!ch?.isVoiceBased?.() || ch.name.toLowerCase() !== preferredName) continue;
-        attempted.push(`${guild.name}/${ch.name}`);
-        try {
-          await connectTo(ch);
-          return;
-        } catch (e) {
-          warn('auto-join failed; trying next configured voice channel', guild.name, ch.name, e?.stack || e);
-          try { connection?.destroy(); } catch {}
-          connection = null;
-          activeVoiceChannelId = '';
-        }
-      }
-    }
-  }
-  warn('No auto-join channel found or reachable', settings.autoJoinVoiceChannels, 'attempted', attempted);
-}
-
 function consumeRestartNotice() {
   const noticePath = path.join(ROOT, '.cache', 'restart-notice.txt');
   try {
@@ -1787,76 +1113,8 @@ async function announceRestartComplete() {
   await speakText(speech, undefined, null, { mirrorText: false });
 }
 
-async function findVoiceChannelBySelector(guild, selector) {
-  const wanted = String(selector || '').trim();
-  if (!wanted || !guild) return null;
-  const id = wanted.replace(/^<#(\d+)>$/, '$1');
-  const channels = await guild.channels.fetch();
-  const voiceChannels = [...channels.values()].filter(ch => ch?.isVoiceBased?.());
-  const byId = voiceChannels.find(ch => ch.id === id);
-  if (byId) return byId;
-  const matches = voiceChannels.filter(ch => String(ch.name || '').toLowerCase() === wanted.toLowerCase());
-  if (matches.length === 1) return matches[0];
-  if (matches.length > 1) throw new Error(`같은 이름의 음성 채널이 여러 개야. 채널 ID나 멘션으로 지정해줘: ${wanted}`);
-  throw new Error(`음성 채널을 찾지 못했어: ${wanted}`);
-}
-
-async function voiceChannelLabel(guild, channelId) {
-  if (!channelId || !guild) return '없음';
-  try {
-    const ch = await guild.channels.fetch(channelId);
-    return ch?.name || '지정됨';
-  } catch {
-    return '지정됨';
-  }
-}
-
-async function resolveVoiceChannelForAttach(msg, selector = '') {
-  if (selector) return findVoiceChannelBySelector(msg.guild, selector);
-  if (msg.member?.voice?.channel) return msg.member.voice.channel;
-  if (activeVoiceChannelId && msg.guild) {
-    try {
-      const ch = await msg.guild.channels.fetch(activeVoiceChannelId);
-      if (ch?.isVoiceBased?.()) return ch;
-    } catch {}
-  }
-  throw new Error('붙일 음성 채널을 못 찾았어. 음성채널에 들어가서 `!session attach-voice`를 치거나 `--voice "채널명"`을 붙여줘.');
-}
-
-async function attachVoiceChannelToTextSession(msg, command) {
-  const voiceChannel = await resolveVoiceChannelForAttach(msg, command.voice);
-  let session = null;
-  if (command.name) {
-    session = bindProjectSessionToChannel({ state: projectSessionsState, nameOrSlug: command.name, channelId: msg.channelId });
-  } else {
-    session = resolveProjectSessionForChannel(msg.channelId)
-      || resolveProjectSessionForChannel(voiceChannel.id);
-    if (!session) {
-      const fallbackName = String(msg.channel?.name || `channel-${msg.channelId}`).trim() || `channel-${msg.channelId}`;
-      session = createProjectSession({
-        root: ROOT,
-        state: projectSessionsState,
-        name: fallbackName,
-        workdir: settings.agent.cwd || ROOT,
-        channelId: msg.channelId,
-        voiceChannelId: voiceChannel.id,
-        transcriptChannelId: msg.channelId,
-        mcpContext: 'Ad-hoc Discord text channel session',
-      });
-    }
-  }
-  session.transcriptChannelId = msg.channelId;
-  session.voiceChannelId = voiceChannel.id;
-  projectSessionsState.channelSessions[msg.channelId] = session.slug;
-  projectSessionsState.channelSessions[voiceChannel.id] = session.slug;
-  saveProjectSessionsState();
-  agentAdaptersBySession.delete(session.slug);
-  if (activeVoiceChannelId !== voiceChannel.id) await connectTo(voiceChannel);
-  return msg.reply(`${session.name} 세션을 이 텍스트 채널과 음성 채널 ${voiceChannel.name}에 붙였어. 이제 그 음성채널 발화의 STT/답변 텍스트는 이 채널로 가.`);
-}
-
 async function handleProjectSessionCommand(msg, command) {
-  const activeSession = resolveProjectSessionForChannel(msg.channelId) || resolveProjectSessionForChannel(activeVoiceChannelId);
+  const activeSession = resolveProjectSessionForChannel(msg.channelId) || resolveProjectSessionForChannel(bridge.activeVoiceChannelId);
   if (command.action === 'attach-voice') return void await attachVoiceChannelToTextSession(msg, command);
   if (command.action === 'status') {
     if (!activeSession) return void msg.reply(`${agentAdapter.label} 기본 세션: ${agentAdapter.readSessionId?.() || '아직 없음'}`);
@@ -1914,7 +1172,8 @@ async function handleProjectSessionCommand(msg, command) {
       mcpContext: command.mcpContext,
     });
     saveProjectSessionsState();
-    agentAdaptersBySession.delete(session.slug);
+    bridge.agentAdaptersBySession.delete(session.slug);
+  invalidateBackendAdaptersForSession(session.slug);
     return void msg.reply(`${session.name} 프로젝트 세션 만들었어. 작업실은 ${session.workdir}이고, 이 텍스트 채널${voiceChannel ? `과 음성 채널 ${voiceChannel.name}` : ''} 입력은 별도 Hermes 세션 파일로 이어져.`);
   }
 }
@@ -1925,130 +1184,22 @@ client.once('ready', async () => {
   await announceRestartComplete();
 });
 
-client.on('messageCreate', async msg => {
-  if (msg.author.bot) return;
-  if (!isAllowed(msg.author.id)) return;
-  const content = msg.content.trim();
-  appendRecentDiscordText(recentDiscordTextByChannel, {
-    channelId: msg.channelId,
-    authorLabel: msg.member?.displayName || msg.author?.username || 'user',
-    content,
-  });
-  const projectSessionCommand = parseProjectSessionCommand(content);
-  if (projectSessionCommand) {
-    try {
-      await handleProjectSessionCommand(msg, projectSessionCommand);
-    } catch (e) {
-      warn('project session command failed', e?.stack || e);
-      await msg.reply(String(e?.message || e).slice(0, 700));
-    }
-    return;
-  }
-  if (content === '!ping') return void msg.reply('pong');
-  if (content === '!verbose') return void msg.reply(verboseStatusText());
-  if (['!verbose on', '!verbose true', '!verbose 1', '!verbose 켜', '!verbose 켜줘'].includes(content.toLowerCase())) {
-    setVerboseProgress(true, 'discord-command');
-    return void msg.reply(verboseStatusText());
-  }
-  if (['!verbose off', '!verbose false', '!verbose 0', '!verbose 꺼', '!verbose 꺼줘'].includes(content.toLowerCase())) {
-    setVerboseProgress(false, 'discord-command');
-    return void msg.reply(verboseStatusText());
-  }
-  if (content === '!notify') return void msg.reply(notifyStatusText());
-  if (['!notify on', '!notify always', '!notify 1'].includes(content.toLowerCase())) {
-    notifyUserOptIn = true;
-    return void msg.reply(notifyStatusText());
-  }
-  if (['!notify off', '!notify auto', '!notify 0'].includes(content.toLowerCase())) {
-    notifyUserOptIn = false;
-    return void msg.reply(notifyStatusText());
-  }
-  if (content === '!smart-progress' || content === '!smart_progress') return void msg.reply(smartProgressStatusText());
-  if (['!smart-progress on', '!smart-progress true', '!smart-progress 1', '!smart_progress on'].includes(content.toLowerCase())) {
-    smartProgressEnabled = true;
-    return void msg.reply(smartProgressStatusText());
-  }
-  if (['!smart-progress off', '!smart-progress false', '!smart-progress 0', '!smart_progress off'].includes(content.toLowerCase())) {
-    smartProgressEnabled = false;
-    return void msg.reply(smartProgressStatusText());
-  }
-  if (content === '!sensitivity') return void msg.reply(sensitivityStatusText());
-  if (content === '!latency' || content === '!metrics') {
-    const summary = summarizeLatencyRecords(readJsonlRecords(settings.latencyLogPath, { limit: 200 }));
-    return void msg.reply(`최근 latency 요약 (${settings.latencyLogPath}):\n${formatLatencySummary(summary)}`.slice(0, 1900));
-  }
-  if (content === '!sensitivity conservative') {
-    setSensitivityMode('conservative', 'discord-command');
-    return void msg.reply(sensitivityStatusText());
-  }
-  if (content === '!sensitivity normal') {
-    setSensitivityMode('normal', 'discord-command');
-    return void msg.reply(sensitivityStatusText());
-  }
-  if (content === '!session') return void handleProjectSessionCommand(msg, { action: 'status' });
-  if (content === '!reset-session') return void handleProjectSessionCommand(msg, { action: 'reset' });
-  if (content === '!join') {
-    const ch = msg.member?.voice?.channel;
-    if (!ch) return void msg.reply('먼저 음성 채널에 들어가줘.');
-    await connectTo(ch);
-    return void msg.reply('들어왔어. Node receiver로 듣는 중.');
-  }
-  if (content === '!leave') {
-    try { connection?.destroy(); } catch {}
-    connection = null;
-    activeVoiceChannelId = '';
-    return void msg.reply('나갈게.');
-  }
-  if (content.startsWith('!say ')) {
-    const text = content.slice(5).trim();
-    const mp3 = await synthTTS(text);
-    await playAudio(mp3);
-    return;
-  }
-  if (content.startsWith('!voice-test ')) {
-    const text = content.slice('!voice-test '.length).trim();
-    if (!text) return void msg.reply('테스트할 문장을 붙여줘.');
-    const started = Date.now();
-    try {
-      await msg.reply(`TTS 백엔드 ${ttsBackend.name}로 음성 테스트할게.`);
-      await speakText(text);
-      await msg.channel.send(`음성 테스트 완료: ${ttsBackend.name}, ${Date.now() - started}ms`);
-    } catch (e) {
-      warn('voice-test failed', e?.stack || e);
-      await msg.channel.send(`음성 테스트 실패: ${String(e?.message || e).slice(0, 700)}`);
-    }
-    return;
-  }
-  if (content === '!voice-clone' || content === '!voice-clone status') {
-    const current = voiceCloneCapture.current();
-    if (current?.userId === String(msg.author.id)) {
-      return void msg.reply(`다음 유효한 음성을 ${path.relative(ROOT, current.targetPath)}에 저장할게.`);
-    }
-    return void msg.reply('대기 중인 보이스 클로닝 샘플 캡처가 없어. `!voice-clone capture`로 시작해.');
-  }
-  if (content === '!voice-clone cancel') {
-    const cancelled = voiceCloneCapture.cancel(msg.author.id);
-    return void msg.reply(cancelled ? '보이스 클로닝 샘플 캡처를 취소했어.' : '대기 중인 캡처가 없어.');
-  }
-  if (content === '!voice-clone capture') {
-    const armed = voiceCloneCapture.arm({ userId: msg.author.id, source: 'discord-command' });
-    return void msg.reply(`다음 유효한 음성을 ${path.relative(ROOT, armed.targetPath)}에 저장할게. 음성 채널에서 10~30초 정도 말해줘.`);
-  }
-  if (content.startsWith('!ask ')) {
-    const text = content.slice(5).trim();
-    if (!text) return void msg.reply('물어볼 내용을 붙여줘.');
-    await handleTextAgentMessage(msg, text, { speakResponse: true });
-    return;
-  }
-  if (shouldRouteDiscordTextToAgent({
-    content,
-    channelId: msg.channelId,
-    transcriptChannelId: settings.transcriptChannelId,
-  }) || resolveProjectSessionForChannel(msg.channelId)) {
-    await handleTextAgentMessage(msg, content, { speakResponse: false });
-    return;
-  }
+const discordCommandRouter = createDiscordCommandRouter({
+  bridge, settings, warn, path, ROOT,
+  isAllowed,
+  handleProjectSessionCommand,
+  handleTextAgentMessage,
+  resolveProjectSessionForChannel,
+  verboseStatusText, setVerboseProgress,
+  notifyStatusText,
+  smartProgressStatusText,
+  sensitivityStatusText, setSensitivityMode,
+  summarizeLatencyRecords, readJsonlRecords, formatLatencySummary,
+  connectTo,
+  synthTTS, playAudio, speakText,
+  voiceCloneCapture,
 });
+client.on('messageCreate', msg => discordCommandRouter.handleDiscordMessage(msg).catch(e => warn('discord command router failed', e?.stack || e)));
 
 process.stdout?.on?.('error', error => {
   if (isBenignTransientNetworkError(error)) {
@@ -2078,37 +1229,6 @@ process.on('uncaughtException', error => {
 client.on('error', e => warn('discord client error', e?.stack || e));
 client.on('shardError', e => warn('discord shard error', e?.stack || e));
 
-let shutdownStarted = false;
-async function gracefulShutdown(signalName) {
-  if (shutdownStarted) return;
-  shutdownStarted = true;
-  log('graceful shutdown requested', signalName, 'connection', Boolean(connection));
-  try {
-    if (currentAbortController && !currentAbortController.signal.aborted) currentAbortController.abort();
-  } catch (e) {
-    warn('abort before shutdown failed', e?.stack || e);
-  }
-  try {
-    if (connection) {
-      let detail = '';
-      const noticePath = path.join(ROOT, '.cache', 'restart-notice.txt');
-      try {
-        if (fs.existsSync(noticePath)) {
-          detail = fs.readFileSync(noticePath, 'utf8').replace(/\s+/g, ' ').trim().slice(0, 120);
-        }
-      } catch (e) {
-        warn('read restart notice failed', e?.stack || e);
-      }
-      await speakText(formatRestartShutdownNotice(detail, settings.tts.edge.voice));
-      await waitEvent(player, AudioPlayerStatus.Idle, 30000).catch(() => {});
-    }
-  } catch (e) {
-    warn('shutdown voice notice failed', e?.stack || e);
-  }
-  try { connection?.destroy(); } catch {}
-  try { client.destroy(); } catch {}
-  process.exit(0);
-}
 process.on('SIGTERM', () => { void gracefulShutdown('SIGTERM'); });
 process.on('SIGINT', () => { void gracefulShutdown('SIGINT'); });