verbalcoding 0.2.12 → 0.2.13

package/app-node/plan_mode.mjs

@@ -1,5 +1,10 @@
-const PLAN_RE = /PLAN_BEGIN\s*\n([\s\S]*?)\nPLAN_END/;
-const DECISIONS_RE = /DECISIONS_BEGIN\s*\n([\s\S]*?)\nDECISIONS_END/;
+const PLAN_RE = /PLAN_BEGIN\s*\n([\s\S]*?)\nPLAN_END/g;
+const DECISIONS_RE = /DECISIONS_BEGIN\s*\n([\s\S]*?)\nDECISIONS_END/g;
+
+function lastMatch(text, regex) {
+  const matches = Array.from(String(text || '').matchAll(regex));
+  return matches.length ? matches[matches.length - 1] : null;
+}
 
 const SKIP_EN = /\bskip\s+step\s+(\d+)\b/i;
 const SKIP_KO = /step\s*(\d+)\s*건너뛰/i;
@@ -13,19 +18,20 @@ const ENTER_EN = /\b(plan\s+(it\s+)?first|make\s+a\s+plan)\b/i;
 const ENTER_KO = /(먼저\s*계획|계획\s*먼저|계획부터)/i;
 
 export function parsePlanOutput(text) {
-  const planMatch = String(text || '').match(PLAN_RE);
+  const planMatch = lastMatch(text, PLAN_RE);
   if (!planMatch) return { steps: [], decisions: [] };
   const steps = planMatch[1]
     .split(/\r?\n/)
     .map(line => line.match(/^\s*(\d+)\.\s*(.+)$/))
     .filter(Boolean)
     .map(m => ({ id: Number(m[1]), text: m[2].trim(), status: 'pending' }));
-  const decisions = parseDecisions(String(text || ''));
+  const afterPlan = String(text || '').slice(planMatch.index + planMatch[0].length);
+  const decisions = parseDecisions(afterPlan);
   return { steps, decisions };
 }
 
 export function parseDecisions(text) {
-  const match = String(text || '').match(DECISIONS_RE);
+  const match = lastMatch(text, DECISIONS_RE);
   if (!match) return [];
   const out = [];
   let counter = 1;
@@ -48,6 +54,20 @@ const ORDINAL_EN = { first: 1, second: 2, third: 3, fourth: 4, fifth: 5, '1st':
 const ORDINAL_KO = { '첫': 1, '첫번째': 1, '첫 번째': 1, '두번째': 2, '두 번째': 2, '세번째': 3, '세 번째': 3, '네번째': 4 };
 const DEFER_RE = /\b(either|whatever|you\s+(decide|pick|choose)|agent\s+(decides|picks)|up\s+to\s+you|no\s+preference)\b|아무거나|네가\s*골라|마음대로|상관없|알아서/i;
 
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function optionMatchesText(text, optionLower) {
+  if (!optionLower || optionLower.length < 2) return false;
+  const asciiOnly = /^[\x00-\x7f]+$/.test(optionLower);
+  if (asciiOnly) {
+    const pattern = new RegExp(`(^|\\W)${escapeRegex(optionLower)}(\\W|$)`, 'i');
+    return pattern.test(text);
+  }
+  return text.includes(optionLower);
+}
+
 export function parseDecisionAnswer(utterance, decision, language = 'en') {
   const text = String(utterance || '').trim();
   if (!text || !decision || !Array.isArray(decision.options) || decision.options.length === 0) {
@@ -57,7 +77,7 @@ export function parseDecisionAnswer(utterance, decision, language = 'en') {
   if (DEFER_RE.test(text)) return { type: 'auto', choice: null };
   for (const opt of decision.options) {
     const optLower = String(opt).toLowerCase();
-    if (lower.includes(optLower) && optLower.length >= 2) return { type: 'option', choice: opt };
+    if (optionMatchesText(lower, optLower)) return { type: 'option', choice: opt };
   }
   const numMatch = text.match(/\b(\d+)\b/);
   if (numMatch) {
@@ -120,11 +140,18 @@ export function applyCommand(steps, cmd) {
     return steps.map(s => (s.id === cmd.index ? { ...s, status: 'skipped' } : s));
   }
   if (cmd.type === 'insert') {
+    const usedIds = new Set(steps.map(s => s.id));
+    let fraction = 0.5;
+    let proposed = cmd.after + fraction;
+    while (usedIds.has(proposed)) {
+      fraction /= 2;
+      proposed = cmd.after + fraction;
+    }
     const out = [];
     for (const s of steps) {
       out.push(s);
       if (s.id === cmd.after) {
-        out.push({ id: s.id + 0.5, text: cmd.text, status: 'added' });
+        out.push({ id: proposed, text: cmd.text, status: 'added' });
       }
     }
     return out;
@@ -150,6 +177,7 @@ export function planModePreamble(language = 'en') {
       '- <slot> | <한 문장 질문> | <옵션1> | <옵션2> | ...',
       'DECISIONS_END',
       '각 단계는 12단어 이하 한국어 한 줄. slot은 oauth_provider, session_store 같은 짧은 영문 키.',
+      'slot이 "which_agent"이면 다음에 답할 CLI 에이전트를 묻는 분기다 (options: codex, aider, claude, gemini, opencode, openclaw, cursor, hermes).',
       '결정이 필요 없으면 DECISIONS 블록 자체를 생략해라.',
     ].join('\n');
   }
@@ -164,6 +192,7 @@ export function planModePreamble(language = 'en') {
     '- <slot> | <one-sentence question> | <option1> | <option2> | ...',
     'DECISIONS_END',
     'Each step under 12 words. slot is a short snake_case key (e.g. oauth_provider).',
+    'Use slot "which_agent" when the choice is which CLI agent should answer next (options: codex, aider, claude, gemini, opencode, openclaw, cursor, hermes).',
     'Omit the DECISIONS block entirely if there is nothing to ask.',
   ].join('\n');
 }

package/app-node/plan_mode.test.mjs

@@ -12,6 +12,7 @@ import {
   isPlanEntryUtterance,
   planModePreamble,
 } from './plan_mode.mjs';
+import { isAgentRoutingDecision } from './agent_routing.mjs';
 
 test('parsePlanOutput extracts numbered steps between markers', () => {
   const out = parsePlanOutput('intro\nPLAN_BEGIN\n1. Read auth.ts\n2. Add login route\n3. Write test\nPLAN_END\nthanks');
@@ -76,6 +77,15 @@ test('parseDecisionAnswer returns unknown on no match', () => {
   assert.equal(parseDecisionAnswer('hello world', decision).type, 'unknown');
 });
 
+test('parseDecisionAnswer requires word boundaries for ASCII options', () => {
+  const decision = { slot: 'x', question: 'q', options: ['go', 'wait'] };
+  assert.equal(parseDecisionAnswer('go ahead', decision).choice, 'go');
+  // "go" should not match inside "ago" or "google"
+  const trickier = { slot: 'x', question: 'q', options: ['go', 'wait'] };
+  assert.equal(parseDecisionAnswer('a long time ago', trickier).type, 'unknown');
+  assert.equal(parseDecisionAnswer('let me google that', trickier).type, 'unknown');
+});
+
 test('renderDecisionPrompt formats question with numbered options', () => {
   const decision = { slot: 'x', question: 'Pick auth?', options: ['google', 'github'] };
   assert.match(renderDecisionPrompt(decision, 'en'), /Pick auth\?\s+Options:\s+1\) google\s+2\) github/);
@@ -131,6 +141,52 @@ test('applyCommand insert places new step after target', () => {
   assert.equal(after[2].text, 'b');
 });
 
+test('applyCommand two inserts after the same step get unique ids', () => {
+  let steps = [{ id: 1, text: 'a', status: 'pending' }, { id: 2, text: 'b', status: 'pending' }];
+  steps = applyCommand(steps, { type: 'insert', after: 1, text: 'first extra' });
+  steps = applyCommand(steps, { type: 'insert', after: 1, text: 'second extra' });
+  const ids = steps.map(s => s.id);
+  assert.equal(new Set(ids).size, ids.length, `expected unique ids, got ${ids.join(',')}`);
+});
+
+test('parsePlanOutput drops stale draft DECISIONS that precede the final PLAN', () => {
+  const text = [
+    'DECISIONS_BEGIN',
+    '- stale_slot | Old question? | a | b',
+    'DECISIONS_END',
+    '',
+    'PLAN_BEGIN',
+    '1. real step',
+    'PLAN_END',
+  ].join('\n');
+  const out = parsePlanOutput(text);
+  assert.deepEqual(out.steps.map(s => s.text), ['real step']);
+  assert.deepEqual(out.decisions, []);
+});
+
+test('parsePlanOutput picks the last PLAN/DECISIONS block when duplicates exist', () => {
+  const text = [
+    'PLAN_BEGIN',
+    '1. example step',
+    'PLAN_END',
+    'DECISIONS_BEGIN',
+    '- example_slot | Pick? | a | b',
+    'DECISIONS_END',
+    '',
+    'PLAN_BEGIN',
+    '1. real step one',
+    '2. real step two',
+    'PLAN_END',
+    'DECISIONS_BEGIN',
+    '- real_slot | Real question? | yes | no',
+    'DECISIONS_END',
+  ].join('\n');
+  const out = parsePlanOutput(text);
+  assert.deepEqual(out.steps.map(s => s.text), ['real step one', 'real step two']);
+  assert.equal(out.decisions.length, 1);
+  assert.equal(out.decisions[0].slot, 'real_slot');
+});
+
 test('renderFinalPlan skips skipped steps and renumbers', () => {
   const steps = [
     { id: 1, text: 'a', status: 'pending' },
@@ -151,3 +207,25 @@ test('planModePreamble contains PLAN_BEGIN marker', () => {
   assert.match(planModePreamble('en'), /PLAN_BEGIN/);
   assert.match(planModePreamble('ko'), /PLAN_BEGIN/);
 });
+
+test('parsePlanOutput tags which_agent decision via isAgentRoutingDecision', () => {
+  const text = [
+    'PLAN_BEGIN',
+    '1. Survey the codebase',
+    'PLAN_END',
+    'DECISIONS_BEGIN',
+    '- which_agent | Who should answer? | codex | aider',
+    'DECISIONS_END',
+  ].join('\n');
+  const out = parsePlanOutput(text);
+  assert.equal(out.decisions[0].slot, 'which_agent');
+  assert.equal(isAgentRoutingDecision(out.decisions[0]), true);
+});
+
+test('planModePreamble in English mentions which_agent', () => {
+  assert.match(planModePreamble('en'), /which_agent/);
+});
+
+test('planModePreamble in Korean mentions which_agent', () => {
+  assert.match(planModePreamble('ko'), /which_agent/);
+});

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);
+});