verbalcoding 0.2.11 → 0.2.13

package/app-node/progress_handler.mjs

@@ -0,0 +1,220 @@
+// Agent progress speech pipeline: queues verbose progress events into rate-limited
+// TTS batches, plays them through the shared bridge player, and stops cleanly
+// when the agent finally answers.
+//
+// Phase 5a extraction from main.mjs. Closes over bridge state
+// (activeProgressSignal, activeProgressAbortController, smartProgressSummarizer,
+// progressSpeechBatch, etc.) plus a handful of injected helpers (settings, log,
+// warn, playAudio, synthProgressTTS deps, refreshTtsRuntimeConfig).
+//
+// Module-level imports (createSmartProgressSummarizer, progressCategory,
+// formatProgressMessage, summarizeProgressEvents, progressTtsCacheFileName)
+// move with the handler — they're not needed anywhere else in main.mjs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createSmartProgressSummarizer } from './smart_progress.mjs';
+import { progressCategory, formatProgressMessage, summarizeProgressEvents } from './progress_speech.mjs';
+import { progressTtsCacheFileName } from './progress_cache.mjs';
+
+export function createProgressHandler(deps) {
+  const {
+    bridge,
+    settings,
+    log,
+    warn,
+    isAbortError,
+    playAudio,
+    sendText,
+    refreshTtsRuntimeConfig,
+  } = deps;
+
+  function ensureSmartProgressSummarizer() {
+    if (bridge.smartProgressSummarizer) return bridge.smartProgressSummarizer;
+    bridge.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,
+    });
+    bridge.smartProgressSummarizer.on('summary', summary => {
+      if (!summary || !bridge.activeProgressSignal) return;
+      queueVerboseProgressSpeech(summary, bridge.activeProgressSignal);
+    });
+    return bridge.smartProgressSummarizer;
+  }
+
+  function smartProgressStatusText() {
+    const hasKey = Boolean(process.env.SMART_PROGRESS_API_KEY);
+    const mode = bridge.smartProgressEnabled && hasKey ? 'on' : 'off';
+    const reason = !hasKey ? ' (no SMART_PROGRESS_API_KEY set)' : '';
+    return `smart-progress: ${mode}${reason}`;
+  }
+
+  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 });
+  }
+
+  function sendVerboseProgressText(event, signal) {
+    if (!bridge.verboseProgress || !signal || signal.aborted || bridge.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 === bridge.lastVerboseProgressText && now - bridge.lastVerboseProgressTextAt < 2000) return;
+    bridge.lastVerboseProgressText = message;
+    bridge.lastVerboseProgressTextAt = now;
+    void sendText(message).catch(e => warn('verbose progress text delivery failed', e?.stack || e));
+  }
+
+  async function synthProgressTTS(text, signal) {
+    await refreshTtsRuntimeConfig();
+    const ext = bridge.ttsBackend.outputExtension || 'mp3';
+    const cachePath = path.join(settings.tts.progressCacheDir, progressTtsCacheFileName({
+      backendKeyParts: bridge.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 bridge.ttsBackend.synthesize(text, { signal, kind: 'progress' });
+    fs.renameSync(tmp, cachePath);
+    return cachePath;
+  }
+
+  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 || bridge.activeProgressSignal !== signal) return;
+    bridge.verboseProgressSpeechQueue = bridge.verboseProgressSpeechQueue
+      .catch(() => {})
+      .then(async () => {
+        if (signal.aborted || bridge.activeProgressSignal !== signal || !bridge.processing) return;
+        log('progress speech queued', reason, 'text', spoken);
+        await speakProgress(spoken, signal);
+      });
+  }
+
+  function flushProgressSpeechBatch(signal, reason = 'timer') {
+    if (!signal || signal.aborted || bridge.activeProgressSignal !== signal) return;
+    if (bridge.progressSpeechBatchTimer) {
+      clearTimeout(bridge.progressSpeechBatchTimer);
+      bridge.progressSpeechBatchTimer = null;
+    }
+    const events = bridge.progressSpeechBatch;
+    bridge.progressSpeechBatch = [];
+    bridge.progressSpeechBatchSignal = null;
+    bridge.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 (!bridge.verboseProgress || !signal || signal.aborted || bridge.activeProgressSignal !== signal) return;
+    const text = String(event || '').replace(/\s+/g, ' ').trim().slice(0, 120);
+    if (!text) return;
+    if (bridge.progressSpeechBatchSignal && bridge.progressSpeechBatchSignal !== signal) {
+      bridge.progressSpeechBatch = [];
+      if (bridge.progressSpeechBatchTimer) clearTimeout(bridge.progressSpeechBatchTimer);
+      bridge.progressSpeechBatchTimer = null;
+      bridge.progressSpeechBatchStartedAt = 0;
+    }
+    bridge.progressSpeechBatchSignal = signal;
+    if (!bridge.progressSpeechBatchStartedAt) bridge.progressSpeechBatchStartedAt = Date.now();
+    bridge.progressSpeechBatch.push(text);
+    const elapsedMs = Date.now() - bridge.progressSpeechBatchStartedAt;
+    const ratePerSecond = bridge.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 (bridge.progressSpeechBatch.length >= maxBatchEvents) {
+      flushProgressSpeechBatch(signal, 'full');
+      return;
+    }
+    if (bridge.progressSpeechBatchTimer) clearTimeout(bridge.progressSpeechBatchTimer);
+    bridge.progressSpeechBatchTimer = setTimeout(() => flushProgressSpeechBatch(signal, 'timer'), batchDelayMs);
+  }
+
+  function clearProgressSpeechBatch(signal = bridge.activeProgressSignal) {
+    if (bridge.progressSpeechBatchTimer) {
+      clearTimeout(bridge.progressSpeechBatchTimer);
+      bridge.progressSpeechBatchTimer = null;
+    }
+    if (!signal || bridge.progressSpeechBatchSignal === signal) {
+      bridge.progressSpeechBatch = [];
+      bridge.progressSpeechBatchSignal = null;
+      bridge.progressSpeechBatchStartedAt = 0;
+    }
+  }
+
+  function stopProgressSpeech(signal, reason = 'final-answer') {
+    if (bridge.activeProgressSignal !== signal) return;
+    clearProgressSpeechBatch(signal);
+    bridge.activeProgressSignal = null;
+    if (bridge.activeProgressAbortController && !bridge.activeProgressAbortController.signal.aborted) {
+      try { bridge.activeProgressAbortController.abort(); } catch (e) { warn('abort progress speech failed', e?.stack || e); }
+    }
+    if (bridge.speaking) {
+      log('stop progress speech before final answer', reason);
+      try { bridge.player.stop(true); } catch (e) { warn('stop progress speech failed', e?.stack || e); }
+      bridge.speaking = false;
+    }
+  }
+
+  return {
+    ensureSmartProgressSummarizer,
+    smartProgressStatusText,
+    progressEmoji,
+    formatProgressText,
+    sendVerboseProgressText,
+    synthProgressTTS,
+    speakProgress,
+    speakImmediateNotice,
+    queueProgressSpeechText,
+    flushProgressSpeechBatch,
+    queueVerboseProgressSpeech,
+    clearProgressSpeechBatch,
+    stopProgressSpeech,
+  };
+}

package/app-node/progress_handler.test.mjs

@@ -0,0 +1,193 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createProgressHandler } from './progress_handler.mjs';
+import { createBridge } from './bridge_context.mjs';
+
+const noop = () => {};
+const noopAsync = async () => {};
+
+function makeDeps(overrides = {}) {
+  const bridge = createBridge();
+  bridge.ttsBackend = {
+    outputExtension: 'mp3',
+    cacheKeyParts: () => ['fake'],
+    synthesize: async () => '/tmp/progress-tmp.mp3',
+  };
+  return {
+    bridge,
+    settings: { tts: { progressCacheDir: '/tmp/progress-cache' }, voiceLanguage: 'ko' },
+    log: noop, warn: noop,
+    isAbortError: () => false,
+    playAudio: noopAsync,
+    sendText: noopAsync,
+    refreshTtsRuntimeConfig: noopAsync,
+    ...overrides,
+  };
+}
+
+test('createProgressHandler exposes the expected functions', () => {
+  const handler = createProgressHandler(makeDeps());
+  for (const name of [
+    'ensureSmartProgressSummarizer', 'smartProgressStatusText', 'progressEmoji',
+    'formatProgressText', 'sendVerboseProgressText', 'synthProgressTTS',
+    'speakProgress', 'speakImmediateNotice', 'queueProgressSpeechText',
+    'flushProgressSpeechBatch', 'queueVerboseProgressSpeech',
+    'clearProgressSpeechBatch', 'stopProgressSpeech',
+  ]) {
+    assert.equal(typeof handler[name], 'function', `${name} is exposed`);
+  }
+});
+
+test('smartProgressStatusText reports off + no-key when env is empty', () => {
+  const prev = process.env.SMART_PROGRESS_API_KEY;
+  delete process.env.SMART_PROGRESS_API_KEY;
+  try {
+    const { smartProgressStatusText } = createProgressHandler(makeDeps());
+    const text = smartProgressStatusText();
+    assert.match(text, /smart-progress: off/);
+    assert.match(text, /no SMART_PROGRESS_API_KEY set/);
+  } finally {
+    if (prev !== undefined) process.env.SMART_PROGRESS_API_KEY = prev;
+  }
+});
+
+test('progressEmoji maps category keys to emoji glyphs', () => {
+  const { progressEmoji } = createProgressHandler(makeDeps());
+  // progressCategory returns null for empty event -> fallback emoji
+  assert.equal(progressEmoji(''), '⚙️');
+});
+
+test('queueProgressSpeechText drops empty/aborted/mismatched signals', () => {
+  const deps = makeDeps();
+  let calls = 0;
+  deps.playAudio = async () => { calls++; };
+  const { queueProgressSpeechText } = createProgressHandler(deps);
+  const signal = new AbortController().signal;
+  // No active progress signal set -> drop
+  queueProgressSpeechText('hello', signal, 'test');
+  assert.equal(calls, 0);
+});
+
+test('clearProgressSpeechBatch resets the batch buffer for the active signal', () => {
+  const deps = makeDeps();
+  const { clearProgressSpeechBatch } = createProgressHandler(deps);
+  deps.bridge.progressSpeechBatchSignal = 'sig';
+  deps.bridge.progressSpeechBatch = ['a', 'b'];
+  deps.bridge.progressSpeechBatchStartedAt = 12345;
+  clearProgressSpeechBatch('sig');
+  assert.equal(deps.bridge.progressSpeechBatchSignal, null);
+  assert.deepEqual(deps.bridge.progressSpeechBatch, []);
+  assert.equal(deps.bridge.progressSpeechBatchStartedAt, 0);
+});
+
+test('stopProgressSpeech is a no-op when signal does not match active', () => {
+  const deps = makeDeps();
+  deps.bridge.activeProgressSignal = 'A';
+  deps.bridge.speaking = true;
+  const { stopProgressSpeech } = createProgressHandler(deps);
+  stopProgressSpeech('B', 'mismatch');
+  // Unchanged because mismatched signal
+  assert.equal(deps.bridge.activeProgressSignal, 'A');
+  assert.equal(deps.bridge.speaking, true);
+});
+
+test('sendVerboseProgressText debounces repeated identical messages', async () => {
+  const deps = makeDeps();
+  let sent = 0;
+  deps.sendText = async () => { sent++; };
+  deps.bridge.verboseProgress = true;
+  const signal = new AbortController().signal;
+  deps.bridge.activeProgressSignal = signal;
+  const handler = createProgressHandler(deps);
+  handler.sendVerboseProgressText('test', signal);
+  await new Promise(r => setImmediate(r));
+  handler.sendVerboseProgressText('test', signal);
+  await new Promise(r => setImmediate(r));
+  // Second identical call within 2s window is debounced
+  assert.equal(sent, 1);
+});
+
+// --- queueVerboseProgressSpeech: batch sizing + flush -------------------
+
+test('queueVerboseProgressSpeech buffers events into the bridge batch', () => {
+  // Note: the flush size is rate-adaptive — when events arrive faster than
+  // 6/sec (which happens in synchronous test loops), maxBatchEvents climbs
+  // to 5. Here we just verify the buffering side: events accumulate on the
+  // bridge and the signal is recorded. The flush-on-size path is exercised
+  // implicitly by the "ratePerSecond >= 6 path" assertion below.
+  const deps = makeDeps();
+  deps.bridge.verboseProgress = true;
+  const signal = new AbortController().signal;
+  deps.bridge.activeProgressSignal = signal;
+  const handler = createProgressHandler(deps);
+
+  handler.queueVerboseProgressSpeech('event one', signal);
+  assert.equal(deps.bridge.progressSpeechBatch.length, 1);
+  assert.ok(deps.bridge.progressSpeechBatchSignal === signal);
+  assert.ok(deps.bridge.progressSpeechBatchStartedAt > 0, 'batch start time recorded');
+
+  handler.queueVerboseProgressSpeech('event two', signal);
+  assert.equal(deps.bridge.progressSpeechBatch.length, 2);
+});
+
+test('queueVerboseProgressSpeech flushes on the slow-rate threshold (3 events)', () => {
+  const deps = makeDeps();
+  deps.bridge.verboseProgress = true;
+  const signal = new AbortController().signal;
+  deps.bridge.activeProgressSignal = signal;
+  const handler = createProgressHandler(deps);
+
+  // Force the slow-rate path by backdating progressSpeechBatchStartedAt so
+  // ratePerSecond falls below the 3/sec threshold (maxBatchEvents=3).
+  handler.queueVerboseProgressSpeech('event one', signal);
+  deps.bridge.progressSpeechBatchStartedAt = Date.now() - 5000;  // 1 event over 5s -> 0.2/sec
+  handler.queueVerboseProgressSpeech('event two', signal);
+  // Backdate again before the third event so we stay on the slow path.
+  deps.bridge.progressSpeechBatchStartedAt = Date.now() - 5000;
+  handler.queueVerboseProgressSpeech('event three', signal);
+  // Third event hits maxBatchEvents=3 -> flush.
+  assert.equal(deps.bridge.progressSpeechBatch.length, 0, 'batch flushed on hitting slow-rate size');
+  assert.equal(deps.bridge.progressSpeechBatchSignal, null);
+  assert.equal(deps.bridge.progressSpeechBatchTimer, null);
+});
+
+test('queueVerboseProgressSpeech ignores events when signal does not match active', () => {
+  const deps = makeDeps();
+  deps.bridge.verboseProgress = true;
+  const activeSig = new AbortController().signal;
+  const otherSig = new AbortController().signal;
+  deps.bridge.activeProgressSignal = activeSig;
+  const handler = createProgressHandler(deps);
+  handler.queueVerboseProgressSpeech('orphan event', otherSig);
+  assert.equal(deps.bridge.progressSpeechBatch.length, 0, 'no batching for mismatched signal');
+});
+
+test('queueVerboseProgressSpeech is a no-op when verboseProgress disabled', () => {
+  const deps = makeDeps();
+  deps.bridge.verboseProgress = false;
+  const sig = new AbortController().signal;
+  deps.bridge.activeProgressSignal = sig;
+  const handler = createProgressHandler(deps);
+  handler.queueVerboseProgressSpeech('test', sig);
+  assert.equal(deps.bridge.progressSpeechBatch.length, 0);
+});
+
+test('flushProgressSpeechBatch with mismatched signal does not drain the buffer', () => {
+  const deps = makeDeps();
+  deps.bridge.progressSpeechBatch = ['queued event'];
+  deps.bridge.activeProgressSignal = 'A';
+  const handler = createProgressHandler(deps);
+  handler.flushProgressSpeechBatch('B', 'wrong-signal');
+  assert.deepEqual(deps.bridge.progressSpeechBatch, ['queued event'], 'mismatched flush is no-op');
+});
+
+test('ensureSmartProgressSummarizer memoizes and registers a summary callback', () => {
+  // Ensure no API key path: the summarizer is still constructed, but won't ingest.
+  // We don't need to interact with the real summarizer — just verify memoization.
+  const deps = makeDeps();
+  const handler = createProgressHandler(deps);
+  const a = handler.ensureSmartProgressSummarizer();
+  const b = handler.ensureSmartProgressSummarizer();
+  assert.equal(a, b, 'summarizer memoized on bridge');
+  assert.equal(deps.bridge.smartProgressSummarizer, a);
+});

package/app-node/progress_speech.mjs

@@ -11,20 +11,58 @@ const CATEGORY_LABELS = {
 
 const CATEGORY_RULES = [
   { key: 'test', pattern: /(테스트|test|pytest|npm test|node --test)/i },
-  { key: 'edit', pattern: /(파일\s*수정|수정|patch|write_file|쓰기|변경|edit)/i },
-  { key: 'read', pattern: /(파일\s*읽기|read_file|읽기|열람)/i },
-  { key: 'search', pattern: /(웹\s*검색|검색|web_search|search_files|찾기)/i },
-  { key: 'terminal', pattern: /(터미널|명령|terminal|shell|실행)/i },
-  { key: 'skill', pattern: /(스킬|skill)/i },
-  { key: 'browser', pattern: /(브라우저|browser)/i },
-  { key: 'tool', pattern: /(툴|도구|tool)/i },
-  { key: 'agent', pattern: /(에이전트|agent|hermes)/i },
+  { key: 'edit', pattern: /(파일\s*수정|수정|patch|write_file|쓰기|변경|edit|editing\s+files?)/i },
+  { key: 'read', pattern: /(파일\s*읽기|read_file|읽기|열람|reading\s+files?)/i },
+  { key: 'search', pattern: /(웹\s*검색|검색|web_search|search_files|찾기|searching)/i },
+  { key: 'terminal', pattern: /(터미널|명령|terminal|shell|실행|running\s+terminal\s+commands?)/i },
+  { key: 'skill', pattern: /(스킬|skill|loading\s+skills?)/i },
+  { key: 'browser', pattern: /(브라우저|browser|checking\s+the\s+browser)/i },
+  { key: 'tool', pattern: /(툴|도구|tool|using\s+tools?)/i },
+  { key: 'agent', pattern: /(에이전트|agent|hermes|calling\s+the\s+agent|received\s+agent\s+response)/i },
 ];
 
 function labelsFor(language = 'ko') {
   return /^en/i.test(String(language || '')) ? CATEGORY_LABELS.en : CATEGORY_LABELS.ko;
 }
 
+function categoryEmoji(key = 'work') {
+  return {
+    test: '🧪',
+    edit: '✏️',
+    read: '📖',
+    search: '🔎',
+    terminal: '💻',
+    skill: '📚',
+    browser: '🌐',
+    agent: '🤖',
+    tool: '🛠️',
+    work: '⚙️',
+  }[key] || '⚙️';
+}
+
+function stripProgressPrefix(text, category, { keepPaths = false, language = 'ko' } = {}) {
+  let detail = String(text || '')
+    .replace(/^VERBALCODING_PROGRESS:\s*/i, '')
+    .replace(/^(파일\s*읽기|파일\s*수정|웹\s*검색|터미널\s*(명령\s*)?실행|테스트\s*실행|스킬\s*사용|툴\s*사용|브라우저\s*확인|에이전트\s*(호출|처리|응답\s*수신)?|Hermes Agent\s*(호출\s*시작|응답\s*수신)?)\s*/i, '')
+    .replace(/^(reading\s+files?|editing\s+files?|searching(?:\s+web)?|running\s+(terminal\s+commands?|tests?)|loading\s+skills?|checking\s+the\s+browser|using\s+tools?|calling\s+the\s+agent|received\s+agent\s+response|working)\s*/i, '')
+    .replace(/^(read_file|write_file|patch|web_search|search_files|terminal|skill_view|tool)\s*/i, '')
+    .replace(/[`*_#>\[\](){}]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  const label = category?.label || labelsFor(language).work;
+  if (detail.toLowerCase().startsWith(label.toLowerCase())) {
+    detail = detail.slice(label.length).replace(/^\s*[-:–—,;.]?\s*/u, '').trim();
+  }
+  if (!keepPaths) {
+    detail = detail
+      .replace(/\bHermes\s+Agent\b/gi, '')
+      .replace(/\b[a-zA-Z0-9_.\/-]+\.(mjs|js|py|md|json|txt|sh|yaml|yml)\b/g, '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+  return detail;
+}
+
 export function progressCategory(event, { language = 'ko' } = {}) {
   const text = String(event || '').replace(/\s+/g, ' ').trim();
   if (!text) return null;
@@ -37,16 +75,10 @@ export function progressDetail(event, { language = 'ko' } = {}) {
   const text = String(event || '').replace(/\s+/g, ' ').trim();
   if (!text) return '';
   const category = progressCategory(text, { language });
-  let detail = text
-    .replace(/^VERBALCODING_PROGRESS:\s*/i, '')
-    .replace(/^(파일\s*읽기|파일\s*수정|웹\s*검색|터미널\s*(명령\s*)?실행|테스트\s*실행|스킬\s*사용|툴\s*사용|브라우저\s*확인|에이전트\s*(호출|처리|응답\s*수신)?|Hermes Agent\s*(호출\s*시작|응답\s*수신)?)\s*/i, '')
-    .replace(/^(read_file|write_file|patch|web_search|search_files|terminal|skill_view|tool)\s*/i, '')
-    .replace(/[`*_#>\[\](){}]/g, '')
-    .replace(/\b[a-zA-Z0-9_.\/-]+\.(mjs|js|py|md|json|txt|sh|yaml|yml)\b/g, '')
-    .replace(/\s+/g, ' ')
-    .trim();
+  let detail = stripProgressPrefix(text, category, { language });
   if (!detail || detail.length < 2) return category?.label || '';
-  if (detail.length > 28) detail = detail.slice(0, 27).replace(/[\s,.;:，。]+$/u, '');
+  const codepoints = Array.from(detail);
+  if (codepoints.length > 28) detail = codepoints.slice(0, 27).join('').replace(/[\s,.;:，。]+$/u, '');
   return `${category?.label || labelsFor(language).work} ${detail}`.trim();
 }
 
@@ -54,22 +86,12 @@ export function formatProgressMessage(event, { language = 'ko' } = {}) {
   const text = String(event || '').replace(/\s+/g, ' ').trim();
   if (!text) return '';
   const category = progressCategory(text, { language });
-  const detail = progressDetail(text, { language });
+  let detail = stripProgressPrefix(text, category, { language, keepPaths: true });
   const english = /^en/i.test(String(language || ''));
-  const safeDetail = english && /\p{Script=Hangul}/u.test(detail) ? '' : detail;
-  const body = english ? (safeDetail || category?.label || 'working') : (safeDetail || category?.label || '작업 처리');
-  const emoji = {
-    test: '🧪',
-    edit: '✏️',
-    read: '📖',
-    search: '🔎',
-    terminal: '💻',
-    skill: '📚',
-    browser: '🌐',
-    agent: '🤖',
-    tool: '🛠️',
-    work: '⚙️',
-  }[category?.key || 'work'] || '⚙️';
+  if (english && /\p{Script=Hangul}/u.test(detail)) detail = '';
+  if (!english && /[A-Za-z]/.test(detail) && !/\p{Script=Hangul}/u.test(detail)) detail = '';
+  const body = [category?.label || (english ? 'working' : '작업 처리'), detail].filter(Boolean).join(': ');
+  const emoji = categoryEmoji(category?.key || 'work');
   return `${emoji} ${body}`.trim();
 }
 

package/app-node/progress_speech.test.mjs

@@ -16,9 +16,18 @@ test('progressDetail preserves the meaningful task name after the generic prefix
 });
 
 test('formatProgressMessage renders intermediate text in the selected English language', () => {
-  assert.equal(formatProgressMessage('파일 읽기 app-node/main.mjs', { language: 'en' }), '📖 reading files');
-  assert.equal(formatProgressMessage('터미널 명령 실행 npm test', { language: 'en' }), '🧪 running tests npm test');
-  assert.equal(formatProgressMessage('파일 수정 재시작 안내 문구 개선', { language: 'en' }), '✏️ editing files');
+  assert.equal(formatProgressMessage('reading files app-node/main.mjs', { language: 'en' }), '📖 reading files: app-node/main.mjs');
+  assert.equal(formatProgressMessage('running terminal commands npm test', { language: 'en' }), '🧪 running tests: npm test');
+  assert.equal(formatProgressMessage('editing files app-node/main.mjs restart notice', { language: 'en' }), '✏️ editing files: app-node/main.mjs restart notice');
+});
+
+test('English spoken progress does not repeat category phrases', () => {
+  assert.equal(progressDetail('calling the agent Hermes Agent', { language: 'en' }), 'calling the agent');
+  assert.equal(summarizeProgressEvents(['calling the agent Hermes Agent'], { language: 'en' }), 'calling the agent.');
+  assert.equal(summarizeProgressEvents([
+    'calling the agent Hermes Agent',
+    'received agent response Hermes Agent',
+  ], { language: 'en' }), 'calling the agent.');
 });
 
 test('agent progress events format as visible and speakable status', () => {

package/app-node/project_sessions.mjs

@@ -26,11 +26,14 @@ export function loadProjectSessions(configPath) {
 
 export function saveProjectSessions(configPath, state) {
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, `${JSON.stringify({
+  const payload = `${JSON.stringify({
     version: 1,
     sessions: state.sessions || {},
     channelSessions: state.channelSessions || {},
-  }, null, 2)}\n`, { mode: 0o600 });
+  }, null, 2)}\n`;
+  const tmpPath = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmpPath, payload, { mode: 0o600 });
+  fs.renameSync(tmpPath, configPath);
 }
 
 export function createProjectSession({ root, state, name, workdir, channelId, voiceChannelId = '', transcriptChannelId = '', mcpContext = '' }) {

package/app-node/project_sessions.test.mjs

@@ -16,8 +16,14 @@ import {
   slugifySessionName,
 } from './project_sessions.mjs';
 
+const __tempRoots = [];
+test.after(() => {
+  for (const root of __tempRoots) try { fs.rmSync(root, { recursive: true, force: true }); } catch {}
+});
+
 test('project sessions map Discord text and voice channel ids to isolated Hermes session files', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-sessions-'));
+  __tempRoots.push(root);
   const state = loadProjectSessions(path.join(root, 'sessions.json'));
   const session = createProjectSession({ root, state, name: 'LLM Wiki', workdir: '/tmp/llm-wiki', channelId: 'text-1', voiceChannelId: 'voice-1', mcpContext: 'llm-wiki graph' });
   assert.equal(session.slug, 'llm-wiki');
@@ -30,6 +36,7 @@ test('project sessions map Discord text and voice channel ids to isolated Hermes
 
 test('project sessions persist and can be rebound to another channel', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-sessions-persist-'));
+  __tempRoots.push(root);
   const configPath = path.join(root, 'sessions.json');
   const state = loadProjectSessions(configPath);
   createProjectSession({ root, state, name: 'Other Project', workdir: root, channelId: 'a' });