verbalcoding 0.2.0

package/app-node/instance_doctor.test.mjs

@@ -0,0 +1,128 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { checkInstanceConfigs, tokenFingerprint } from './instance_doctor.mjs';
+
+function tempRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-instance-doctor-'));
+  fs.mkdirSync(path.join(root, 'instances'), { recursive: true });
+  return root;
+}
+
+function writeInstance(root, name, content) {
+  fs.writeFileSync(path.join(root, 'instances', `${name}.env`), content);
+}
+
+test('tokenFingerprint is stable and does not expose token contents', () => {
+  const fp = tokenFingerprint('super-secret-token');
+  assert.match(fp, /^[a-f0-9]{12}$/);
+  assert.equal(fp, tokenFingerprint('super-secret-token'));
+  assert.equal(fp.includes('secret'), false);
+});
+
+test('checkInstanceConfigs returns no issues when no instance env files exist', () => {
+  const root = tempRepo();
+  const result = checkInstanceConfigs(root);
+  assert.deepEqual(result, { errors: [], warnings: [], instances: [] });
+});
+
+test('checkInstanceConfigs requires token, voice channel, transcript target, and isolated runtime paths', () => {
+  const root = tempRepo();
+  writeInstance(root, 'llm-wiki', 'DISCORD_TOKEN=token-a\nAUTO_JOIN_VOICE_CHANNELS=LLM-Wiki\nTRANSCRIPT_CHANNEL_ID=111\nPROJECT_SESSIONS_FILE=config/llm.json\nBRIDGE_LOG_PATH=/tmp/llm.log\nNODE_AUDIO_DEBUG_DIR=/tmp/llm-debug\nHERMES_SESSION_FILE=.agent-sessions/llm.session\n');
+  writeInstance(root, 'bad', 'DISCORD_TOKEN=\nAUTO_JOIN_VOICE_CHANNELS=\nTRANSCRIPT_CHANNEL_ID=\nPROJECT_SESSIONS_FILE=config/llm.json\nBRIDGE_LOG_PATH=/tmp/llm.log\nNODE_AUDIO_DEBUG_DIR=/tmp/llm-debug\nHERMES_SESSION_FILE=.agent-sessions/llm.session\n');
+
+  const result = checkInstanceConfigs(root);
+  assert.deepEqual(result.instances.map(i => i.name), ['bad', 'llm-wiki']);
+  assert(result.errors.some(e => e.includes('bad: missing DISCORD_TOKEN or DISCORD_BOT_TOKEN')));
+  assert(result.errors.some(e => e.includes('bad: missing AUTO_JOIN_VOICE_CHANNELS')));
+  assert(result.errors.some(e => e.includes('bad: missing TRANSCRIPT_CHANNEL_ID')));
+  assert(result.errors.some(e => e.includes('PROJECT_SESSIONS_FILE collision')));
+  assert(result.errors.some(e => e.includes('BRIDGE_LOG_PATH collision')));
+  assert(result.errors.some(e => e.includes('NODE_AUDIO_DEBUG_DIR collision')));
+  assert(result.warnings.some(e => e.includes('HERMES_SESSION_FILE collision')));
+});
+
+test('checkInstanceConfigs detects duplicate token fingerprints without printing tokens', () => {
+  const root = tempRepo();
+  writeInstance(root, 'one', 'DISCORD_TOKEN=same-token\nAUTO_JOIN_VOICE_CHANNELS=One\nTRANSCRIPT_CHANNEL_ID=1\nPROJECT_SESSIONS_FILE=config/one.json\nBRIDGE_LOG_PATH=/tmp/one.log\nNODE_AUDIO_DEBUG_DIR=/tmp/one-debug\n');
+  writeInstance(root, 'two', 'DISCORD_BOT_TOKEN=same-token\nAUTO_JOIN_VOICE_CHANNELS=Two\nTRANSCRIPT_CHANNEL_ID=2\nPROJECT_SESSIONS_FILE=config/two.json\nBRIDGE_LOG_PATH=/tmp/two.log\nNODE_AUDIO_DEBUG_DIR=/tmp/two-debug\n');
+
+  const result = checkInstanceConfigs(root);
+  assert(result.errors.some(e => e.includes('duplicate Discord token fingerprint')));
+  assert.equal(result.errors.join('\n').includes('same-token'), false);
+});
+
+test('checkInstanceConfigs treats omitted runtime paths as effective default collisions', () => {
+  const root = tempRepo();
+  writeInstance(root, 'one', 'DISCORD_TOKEN=token-one\nAUTO_JOIN_VOICE_CHANNELS=One\nTRANSCRIPT_CHANNEL_ID=1\n');
+  writeInstance(root, 'two', 'DISCORD_TOKEN=token-two\nAUTO_JOIN_VOICE_CHANNELS=Two\nTRANSCRIPT_CHANNEL_ID=2\n');
+
+  const result = checkInstanceConfigs(root);
+  assert(result.errors.some(e => e.includes('PROJECT_SESSIONS_FILE collision')));
+  assert(result.errors.some(e => e.includes('NODE_AUDIO_DEBUG_DIR collision')));
+  assert(result.warnings.some(e => e.includes('HERMES_SESSION_FILE collision')));
+});
+
+test('checkInstanceConfigs warns when HERMES_HOME points at a missing profile', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-doctor-'));
+  const instancesDir = path.join(root, 'instances');
+  fs.mkdirSync(instancesDir, { recursive: true });
+  fs.writeFileSync(path.join(instancesDir, 'llm-wiki.env'), [
+    'DISCORD_TOKEN="t"',
+    'AUTO_JOIN_VOICE_CHANNELS="LLM-Wiki"',
+    'TRANSCRIPT_CHANNEL_ID="1"',
+    'AGENT_CWD="/projects/llm-wiki"',
+    'HERMES_HOME="/nonexistent/.hermes/profiles/llm-wiki"',
+    '',
+  ].join('\n'));
+  const result = checkInstanceConfigs(root, { instancesDir });
+  assert.ok(result.warnings.some(w => /HERMES_HOME points at .* missing/.test(w)));
+});
+
+test('checkInstanceConfigs errors when profile terminal.cwd differs from AGENT_CWD', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-doctor-'));
+  const instancesDir = path.join(root, 'instances');
+  const profileDir = path.join(root, '.hermes', 'profiles', 'llm-wiki');
+  fs.mkdirSync(instancesDir, { recursive: true });
+  fs.mkdirSync(profileDir, { recursive: true });
+  fs.writeFileSync(path.join(profileDir, 'config.yaml'), 'terminal:\n  cwd: /elsewhere\n');
+  fs.writeFileSync(path.join(instancesDir, 'llm-wiki.env'), [
+    'DISCORD_TOKEN="t"',
+    'AUTO_JOIN_VOICE_CHANNELS="LLM-Wiki"',
+    'TRANSCRIPT_CHANNEL_ID="1"',
+    'AGENT_CWD="/projects/llm-wiki"',
+    `HERMES_HOME="${profileDir}"`,
+    '',
+  ].join('\n'));
+  const result = checkInstanceConfigs(root, {
+    instancesDir,
+    readTerminalCwd: () => '/elsewhere',
+  });
+  assert.ok(result.errors.some(e => /terminal\.cwd .* does not match AGENT_CWD/.test(e)));
+});
+
+test('checkInstanceConfigs reads only terminal.cwd, ignoring sibling cwd keys', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-doctor-'));
+  const instancesDir = path.join(root, 'instances');
+  const profileDir = path.join(root, '.hermes', 'profiles', 'llm-wiki');
+  fs.mkdirSync(instancesDir, { recursive: true });
+  fs.mkdirSync(profileDir, { recursive: true });
+  // git.cwd appears BEFORE terminal.cwd; old regex would match git.cwd.
+  fs.writeFileSync(path.join(profileDir, 'config.yaml'),
+    'git:\n  cwd: /elsewhere\n' +
+    'terminal:\n  cwd: /projects/llm-wiki\n');
+  fs.writeFileSync(path.join(instancesDir, 'llm-wiki.env'), [
+    'DISCORD_TOKEN="t"',
+    'AUTO_JOIN_VOICE_CHANNELS="LLM-Wiki"',
+    'TRANSCRIPT_CHANNEL_ID="1"',
+    'AGENT_CWD="/projects/llm-wiki"',
+    `HERMES_HOME="${profileDir}"`,
+    '',
+  ].join('\n'));
+  const result = checkInstanceConfigs(root, { instancesDir });
+  assert.equal(result.errors.filter(e => /terminal\.cwd/.test(e)).length, 0,
+    `expected no terminal.cwd errors but got: ${result.errors.join(' | ')}`);
+});

package/app-node/instance_profile_lifecycle.mjs

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ensureHermesProfile as defaultEnsure } from './hermes_profiles.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export async function healInstanceProfileFromEnv(name, instanceEnv, deps = {}) {
+  if (!instanceEnv || !instanceEnv.HERMES_HOME) return null;
+  const ensure = deps.ensureHermesProfile || defaultEnsure;
+  return ensure({
+    name,
+    workdir: instanceEnv.AGENT_CWD || ROOT,
+    projectContext: instanceEnv.AGENT_PROJECT_CONTEXT || '',
+  });
+}

package/app-node/instances.mjs

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { parseKeyValueEnv } from './install_config.mjs';
+
+export function instanceNameFromEnvPath(file) {
+  return path.basename(file).replace(/\.env$/i, '');
+}
+
+export function listInstanceEnvFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(name => name.endsWith('.env') && name !== 'example.env')
+    .sort()
+    .map(name => path.join(dir, name));
+}
+
+export function instanceRuntimePaths(root, name) {
+  return {
+    pidFile: path.join(root, '.run', 'instances', `${name}.pid`),
+    defaultLogPath: `/tmp/verbalcoding-${name}.log`,
+  };
+}
+
+export function readInstanceEnv(file) {
+  try {
+    return parseKeyValueEnv(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function readPidFile(pidFile) {
+  try {
+    const value = Number.parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+    return Number.isInteger(value) && value > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+export function statusForInstance(root, envPath) {
+  const name = instanceNameFromEnvPath(envPath);
+  const runtime = instanceRuntimePaths(root, name);
+  const env = readInstanceEnv(envPath);
+  const pid = readPidFile(runtime.pidFile);
+  const alive = pid !== null && isPidAlive(pid);
+  return {
+    name,
+    envPath,
+    pid: alive ? pid : null,
+    status: alive ? 'running' : 'stopped',
+    logPath: env.BRIDGE_LOG_PATH || runtime.defaultLogPath,
+    pidFile: runtime.pidFile,
+  };
+}
+
+export function listInstanceStatuses(root, instancesDir = path.join(root, 'instances')) {
+  return listInstanceEnvFiles(instancesDir).map(envPath => statusForInstance(root, envPath));
+}
+
+export function resolveInstanceEnvPath(root, name) {
+  const clean = String(name || '').trim();
+  if (!/^[A-Za-z0-9_.-]+$/.test(clean) || clean.startsWith('.') || clean.endsWith('.env')) {
+    throw new Error(`invalid instance name: ${name}`);
+  }
+  const candidate = path.join(root, 'instances', `${clean}.env`);
+  if (!fs.existsSync(candidate)) {
+    throw new Error(`instance env file not found: ${candidate}`);
+  }
+  return candidate;
+}
+
+export function startInstance(root, name, options = {}) {
+  const envPath = resolveInstanceEnvPath(root, name);
+  const instanceName = instanceNameFromEnvPath(envPath);
+  const runtime = instanceRuntimePaths(root, instanceName);
+  const currentPid = readPidFile(runtime.pidFile);
+  if (currentPid && isPidAlive(currentPid)) {
+    throw new Error(`${instanceName} is already running pid=${currentPid}`);
+  }
+  fs.mkdirSync(path.dirname(runtime.pidFile), { recursive: true });
+  const instanceEnv = readInstanceEnv(envPath);
+  const child = spawn(path.join(root, 'run.sh'), [envPath], {
+    cwd: root,
+    detached: true,
+    stdio: ['ignore', 'ignore', 'ignore'],
+    env: {
+      ...process.env,
+      BRIDGE_LOG_PATH: instanceEnv.BRIDGE_LOG_PATH || runtime.defaultLogPath,
+      NODE_AUDIO_DEBUG_DIR: instanceEnv.NODE_AUDIO_DEBUG_DIR || `/tmp/verbalcoding-${instanceName}-debug`,
+      PROJECT_SESSIONS_FILE: instanceEnv.PROJECT_SESSIONS_FILE || path.join(root, 'config', `project-sessions.${instanceName}.json`),
+      HERMES_SESSION_FILE: instanceEnv.HERMES_SESSION_FILE || path.join(root, '.agent-sessions', 'hermes', `${instanceName}.session`),
+      VERBALCODING_INSTANCE_NAME: instanceName,
+      VERBALCODING_INSTANCE_ENV: envPath,
+      ...(options.env || {}),
+    },
+  });
+  child.unref();
+  fs.writeFileSync(runtime.pidFile, `${child.pid}\n`);
+  const status = statusForInstance(root, envPath);
+  return { ...status, pid: child.pid, status: 'running' };
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function stopInstance(root, name, options = {}) {
+  const envPath = resolveInstanceEnvPath(root, name);
+  const instanceName = instanceNameFromEnvPath(envPath);
+  const runtime = instanceRuntimePaths(root, instanceName);
+  const pid = readPidFile(runtime.pidFile);
+  if (!pid || !isPidAlive(pid)) {
+    fs.rmSync(runtime.pidFile, { force: true });
+    return { name: instanceName, pid: null, status: 'stopped', alreadyStopped: true };
+  }
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const intervalMs = options.intervalMs ?? 250;
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    if (err?.code !== 'ESRCH') throw err;
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) {
+      fs.rmSync(runtime.pidFile, { force: true });
+      return { name: instanceName, pid, status: 'stopped', killed: false };
+    }
+    await sleep(intervalMs);
+  }
+  if (isPidAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch (err) {
+      if (err?.code !== 'ESRCH') throw err;
+    }
+  }
+  fs.rmSync(runtime.pidFile, { force: true });
+  return { name: instanceName, pid, status: 'stopped', killed: true };
+}

package/app-node/instances.test.mjs

@@ -0,0 +1,102 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  instanceNameFromEnvPath,
+  instanceRuntimePaths,
+  isPidAlive,
+  listInstanceEnvFiles,
+  readPidFile,
+  resolveInstanceEnvPath,
+  statusForInstance,
+} from './instances.mjs';
+
+function tempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'vc-instances-'));
+}
+
+test('listInstanceEnvFiles finds env files except example', () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, 'example.env'), '');
+  fs.writeFileSync(path.join(dir, 'llm-wiki.env'), '');
+  fs.writeFileSync(path.join(dir, 'verbalcoding.env'), '');
+  fs.writeFileSync(path.join(dir, 'notes.txt'), '');
+
+  assert.deepEqual(listInstanceEnvFiles(dir).map(p => path.basename(p)), ['llm-wiki.env', 'verbalcoding.env']);
+});
+
+test('listInstanceEnvFiles returns empty for missing directory', () => {
+  const dir = path.join(tempDir(), 'missing');
+  assert.deepEqual(listInstanceEnvFiles(dir), []);
+});
+
+test('instanceNameFromEnvPath strips only the env extension', () => {
+  assert.equal(instanceNameFromEnvPath('/repo/instances/llm-wiki.env'), 'llm-wiki');
+  assert.equal(instanceNameFromEnvPath('/repo/instances/foo.local.env'), 'foo.local');
+});
+
+test('instanceRuntimePaths derives pid and log paths', () => {
+  assert.deepEqual(instanceRuntimePaths('/repo', 'llm-wiki'), {
+    pidFile: '/repo/.run/instances/llm-wiki.pid',
+    defaultLogPath: '/tmp/verbalcoding-llm-wiki.log',
+  });
+});
+
+test('readPidFile returns null for missing or invalid pid file', () => {
+  const dir = tempDir();
+  assert.equal(readPidFile(path.join(dir, 'missing.pid')), null);
+  const file = path.join(dir, 'bad.pid');
+  fs.writeFileSync(file, 'not-a-pid');
+  assert.equal(readPidFile(file), null);
+});
+
+test('readPidFile parses a numeric pid', () => {
+  const dir = tempDir();
+  const file = path.join(dir, 'ok.pid');
+  fs.writeFileSync(file, '12345\n');
+  assert.equal(readPidFile(file), 12345);
+});
+
+test('isPidAlive treats current process as alive and impossible pid as dead', () => {
+  assert.equal(isPidAlive(process.pid), true);
+  assert.equal(isPidAlive(99999999), false);
+});
+
+test('statusForInstance reports stopped when no pid file exists', () => {
+  const root = tempDir();
+  const envPath = path.join(root, 'instances', 'llm-wiki.env');
+  fs.mkdirSync(path.dirname(envPath), { recursive: true });
+  fs.writeFileSync(envPath, 'INSTANCE_NAME=llm-wiki\n');
+
+  assert.deepEqual(statusForInstance(root, envPath), {
+    name: 'llm-wiki',
+    envPath,
+    pid: null,
+    status: 'stopped',
+    logPath: '/tmp/verbalcoding-llm-wiki.log',
+    pidFile: path.join(root, '.run', 'instances', 'llm-wiki.pid'),
+  });
+});
+
+test('statusForInstance prefers BRIDGE_LOG_PATH from env file', () => {
+  const root = tempDir();
+  const envPath = path.join(root, 'instances', 'verbalcoding.env');
+  fs.mkdirSync(path.dirname(envPath), { recursive: true });
+  fs.writeFileSync(envPath, 'BRIDGE_LOG_PATH=/tmp/custom-vc.log\n');
+
+  const status = statusForInstance(root, envPath);
+  assert.equal(status.logPath, '/tmp/custom-vc.log');
+});
+
+test('resolveInstanceEnvPath accepts only safe instance names under instances directory', () => {
+  const root = tempDir();
+  fs.mkdirSync(path.join(root, 'instances'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'instances', 'llm-wiki.env'), '');
+  assert.equal(resolveInstanceEnvPath(root, 'llm-wiki'), path.join(root, 'instances', 'llm-wiki.env'));
+  assert.throws(() => resolveInstanceEnvPath(root, '../.env'), /invalid instance name/);
+  assert.throws(() => resolveInstanceEnvPath(root, '/tmp/other.env'), /invalid instance name/);
+  assert.throws(() => resolveInstanceEnvPath(root, 'bad name'), /invalid instance name/);
+});

package/app-node/language_config.mjs

@@ -0,0 +1,73 @@
+export const LANGUAGE_PRESETS = {
+  ko: {
+    key: 'ko',
+    label: 'Korean',
+    sttLanguage: 'ko',
+    voiceLanguage: 'ko',
+    ttsVoice: 'ko-KR-InJoonNeural',
+  },
+  en: {
+    key: 'en',
+    label: 'English',
+    sttLanguage: 'en',
+    voiceLanguage: 'en',
+    ttsVoice: 'en-US-GuyNeural',
+  },
+  auto: {
+    key: 'auto',
+    label: 'Auto-detect STT, English voice',
+    sttLanguage: 'auto',
+    voiceLanguage: 'en',
+    ttsVoice: 'en-US-GuyNeural',
+  },
+};
+
+export function normalizeLanguageKey(value, fallback = 'ko') {
+  const raw = String(value || '').trim().toLowerCase();
+  if (['korean', 'kr', 'kor', '한국어', 'ko-kr'].includes(raw)) return 'ko';
+  if (['english', 'eng', 'en-us', 'en-gb', '영어'].includes(raw)) return 'en';
+  if (['auto', 'detect', 'auto-detect', '자동', '자동감지'].includes(raw)) return 'auto';
+  return LANGUAGE_PRESETS[raw] ? raw : fallback;
+}
+
+export function languagePreset(value, fallback = 'ko') {
+  return LANGUAGE_PRESETS[normalizeLanguageKey(value, fallback)];
+}
+
+export function shouldPassWhisperLanguage(language) {
+  const raw = String(language || '').trim().toLowerCase();
+  return raw && raw !== 'auto' && raw !== 'detect';
+}
+
+export function applyLanguagePreset(env = {}, language = 'ko') {
+  const preset = languagePreset(language);
+  return {
+    ...env,
+    VOICE_LANGUAGE: preset.voiceLanguage,
+    WHISPER_CPP_LANGUAGE: preset.sttLanguage,
+    STT_LANGUAGE: preset.sttLanguage,
+    TTS_BACKEND: env.TTS_BACKEND || 'edge',
+    TTS_VOICE: preset.ttsVoice,
+  };
+}
+
+export function languageStatus(values = {}) {
+  const stt = values.WHISPER_CPP_LANGUAGE || values.STT_LANGUAGE || 'ko';
+  const voiceLanguage = values.VOICE_LANGUAGE || (/^en/i.test(String(values.TTS_VOICE || '')) ? 'en' : 'ko');
+  const ttsVoice = values.TTS_VOICE || 'ko-KR-InJoonNeural';
+  return { sttLanguage: stt, voiceLanguage, ttsVoice };
+}
+
+export function voiceLanguageCommandFromTranscript(text) {
+  const raw = String(text || '').trim();
+  if (!raw) return null;
+  const compact = raw.toLowerCase().replace(/\s+/g, '');
+  const looksLikeCommand = /\b(change|switch|set)\b.*\b(language|voice|stt|speech)\b/i.test(raw)
+    || /\b(language|voice|stt|speech)\b.*\b(to|as)\b/i.test(raw)
+    || /(언어|음성|말|말투).*(바꿔|변경|설정|해줘)|로말해|로바꿔/u.test(compact);
+  if (!looksLikeCommand) return null;
+  if (/(auto.?detect|detect.?language|automatic|자동|자동감지)/iu.test(raw)) return { language: 'auto' };
+  if (/(english|영어|en-us|eng)/iu.test(raw)) return { language: 'en' };
+  if (/(korean|한국어|한글|ko-kr|kor)/iu.test(raw)) return { language: 'ko' };
+  return null;
+}

package/app-node/language_config.test.mjs

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  applyLanguagePreset,
+  languagePreset,
+  languageStatus,
+  normalizeLanguageKey,
+  shouldPassWhisperLanguage,
+  voiceLanguageCommandFromTranscript,
+} from './language_config.mjs';
+
+test('normalizeLanguageKey accepts common English, Korean, and auto aliases', () => {
+  assert.equal(normalizeLanguageKey('english'), 'en');
+  assert.equal(normalizeLanguageKey('한국어'), 'ko');
+  assert.equal(normalizeLanguageKey('auto-detect'), 'auto');
+});
+
+test('voiceLanguageCommandFromTranscript detects voice language changes', () => {
+  assert.deepEqual(voiceLanguageCommandFromTranscript('change language to English'), { language: 'en' });
+  assert.deepEqual(voiceLanguageCommandFromTranscript('영어로 바꿔'), { language: 'en' });
+  assert.deepEqual(voiceLanguageCommandFromTranscript('한국어로 말해'), { language: 'ko' });
+  assert.deepEqual(voiceLanguageCommandFromTranscript('switch to auto detect language'), { language: 'auto' });
+  assert.equal(voiceLanguageCommandFromTranscript('do we have a language option?'), null);
+});
+
+test('language presets update STT and TTS together', () => {
+  const en = applyLanguagePreset({ TTS_RATE: '+0%' }, 'en');
+  assert.equal(en.WHISPER_CPP_LANGUAGE, 'en');
+  assert.equal(en.STT_LANGUAGE, 'en');
+  assert.equal(en.VOICE_LANGUAGE, 'en');
+  assert.equal(en.TTS_VOICE, 'en-US-GuyNeural');
+
+  const ko = languagePreset('ko');
+  assert.equal(ko.ttsVoice, 'ko-KR-InJoonNeural');
+});
+
+test('auto language omits forced whisper language while keeping a voice language', () => {
+  const auto = applyLanguagePreset({}, 'auto');
+  assert.equal(auto.WHISPER_CPP_LANGUAGE, 'auto');
+  assert.equal(shouldPassWhisperLanguage(auto.WHISPER_CPP_LANGUAGE), false);
+  assert.equal(shouldPassWhisperLanguage('en'), true);
+});
+
+test('languageStatus summarizes current env values', () => {
+  assert.deepEqual(languageStatus({ WHISPER_CPP_LANGUAGE: 'en', VOICE_LANGUAGE: 'en', TTS_VOICE: 'en-US-GuyNeural' }), {
+    sttLanguage: 'en',
+    voiceLanguage: 'en',
+    ttsVoice: 'en-US-GuyNeural',
+  });
+});

package/app-node/latency_metrics.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function roundMs(value) {
+  return Math.max(0, Math.round(Number(value) || 0));
+}
+
+function percentile(values, p) {
+  const xs = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (!xs.length) return 0;
+  const idx = Math.min(xs.length - 1, Math.ceil((p / 100) * xs.length) - 1);
+  return xs[idx];
+}
+
+export function appendJsonl(file, record) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+
+export function readJsonlRecords(file, { limit = 200 } = {}) {
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean);
+    return lines.slice(Math.max(0, lines.length - limit)).map(line => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+export function createLatencyTurn({ id, userId, startedAtMs = Date.now(), now = Date.now, writeRecord = () => {} } = {}) {
+  const marks = { start: startedAtMs };
+  const durations = {};
+  const meta = {};
+  let finished = false;
+
+  return {
+    id,
+    userId,
+    marks,
+    durations,
+    meta,
+    mark(name, atMs = now()) {
+      marks[name] = atMs;
+      return atMs;
+    },
+    stage(name, durationMs, extra = {}) {
+      durations[`${name}_ms`] = roundMs(durationMs);
+      Object.assign(meta, extra);
+    },
+    addMeta(extra = {}) {
+      Object.assign(meta, extra);
+    },
+    finish(extra = {}) {
+      if (finished) return null;
+      finished = true;
+      const endedAtMs = extra.endedAtMs ?? now();
+      marks.end = endedAtMs;
+      if (marks.voice_first_packet && marks.voice_segment_end) {
+        durations.voice_capture_ms = roundMs(marks.voice_segment_end - marks.voice_first_packet);
+      }
+      if (marks.voice_segment_end && marks.utterance_flush) {
+        durations.utterance_idle_wait_ms = roundMs(marks.utterance_flush - marks.voice_segment_end);
+      }
+      durations.total_ms = roundMs(endedAtMs - marks.start);
+      const record = {
+        id,
+        userId,
+        ts: new Date(endedAtMs).toISOString(),
+        status: extra.status || 'ok',
+        durations,
+        meta,
+      };
+      if (extra.error) record.error = String(extra.error).slice(0, 500);
+      writeRecord(record);
+      return record;
+    },
+  };
+}
+
+export function summarizeLatencyRecords(records = []) {
+  const statuses = {};
+  const durationKeys = new Set();
+  for (const r of records) {
+    statuses[r.status || 'unknown'] = (statuses[r.status || 'unknown'] || 0) + 1;
+    for (const key of Object.keys(r.durations || {})) durationKeys.add(key);
+  }
+  const durations = {};
+  for (const key of [...durationKeys].sort()) {
+    const values = records.map(r => Number(r.durations?.[key])).filter(Number.isFinite);
+    if (!values.length) continue;
+    const sum = values.reduce((a, b) => a + b, 0);
+    durations[key] = {
+      avg: roundMs(sum / values.length),
+      p50: percentile(values, 50),
+      p95: percentile(values, 95),
+      min: Math.min(...values),
+      max: Math.max(...values),
+      n: values.length,
+    };
+  }
+  return {
+    count: records.length,
+    ok: statuses.ok || 0,
+    statuses,
+    durations,
+  };
+}
+
+export function formatLatencySummary(summary) {
+  if (!summary?.count) return 'latency 기록이 아직 없어.';
+  const names = [
+    'total_ms',
+    'voice_capture_ms',
+    'utterance_idle_wait_ms',
+    'stt_ms',
+    'agent_ms',
+    'tts_synth_ms',
+    'tts_play_ms',
+    'tts_total_ms',
+  ];
+  const lines = [`처리량: ${summary.count}턴, 성공 ${summary.ok}턴`];
+  for (const name of names) {
+    const s = summary.durations[name];
+    if (!s) continue;
+    const label = name.replace(/_ms$/, '');
+    lines.push(`${label}: avg ${s.avg}ms / p95 ${s.p95}ms / max ${s.max}ms (n=${s.n})`);
+  }
+  const otherStatuses = Object.entries(summary.statuses)
+    .filter(([k]) => k !== 'ok')
+    .map(([k, v]) => `${k}:${v}`)
+    .join(', ');
+  if (otherStatuses) lines.push(`기타 상태: ${otherStatuses}`);
+  return lines.join('\n');
+}