verbalcoding 0.2.11 → 0.2.13

package/app-node/mcp_tools.test.mjs

@@ -7,6 +7,11 @@ import path from 'node:path';
 import { createVerbalCodingMcpTools, readEnvFile } from './mcp_tools.mjs';
 import { AUTO_RESTART_ENV_KEY } from './restart_policy.mjs';
 
+const __tempRoots = [];
+test.after(() => {
+  for (const root of __tempRoots) try { fs.rmSync(root, { recursive: true, force: true }); } catch {}
+});
+
 test('MCP tool definitions expose VerbalCoding control surface', () => {
   const { toolDefs, tools } = createVerbalCodingMcpTools({ root: process.cwd() });
   const names = toolDefs.map(tool => tool.name).sort();
@@ -16,6 +21,7 @@ test('MCP tool definitions expose VerbalCoding control surface', () => {
 
 test('set_auto_restart MCP tool writes the default-off restart flag', async () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-mcp-'));
+  __tempRoots.push(dir);
   const envPath = path.join(dir, '.env');
   const { tools } = createVerbalCodingMcpTools({ root: dir, envPath });
   const off = await tools.get('set_auto_restart').handler({ enabled: false });
@@ -28,6 +34,7 @@ test('set_auto_restart MCP tool writes the default-off restart flag', async () =
 
 test('set_language MCP tool updates STT, progress, and TTS language together', async () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-mcp-lang-'));
+  __tempRoots.push(dir);
   const envPath = path.join(dir, '.env');
   const { tools } = createVerbalCodingMcpTools({ root: dir, envPath });
   const result = await tools.get('set_language').handler({ language: 'en' });

package/app-node/notification_handler.mjs

@@ -0,0 +1,89 @@
+// Runtime notification dispatcher built on top of `./notify.mjs`'s createNotifier.
+//
+// Phase 5b extraction from main.mjs. Closes over bridge state
+// (notifierInstance, notifyUserOptIn, lastNotifyAt, lastNotifyBody,
+// activeVoiceChannelId) plus the Discord client for human-count lookups.
+//
+// `ttsFallbackNotice` stays in main.mjs: it's wired through createTtsBackend's
+// onFallback callback at module init (before ttsPlayer / sendText / speakText
+// are fully bound), and threading it through a factory would require thunk
+// indirection for marginal gain.
+
+import { createNotifier, buildDiscordDeepLink } from './notify.mjs';
+
+export function createNotificationHandler(deps) {
+  const {
+    bridge,
+    client,
+    log,
+    warn,
+  } = deps;
+
+  function ensureNotifier() {
+    if (bridge.notifierInstance) return bridge.notifierInstance;
+    bridge.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 bridge.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 = bridge.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 (!bridge.activeVoiceChannelId) return 0;
+    try {
+      const ch = await client.channels.fetch(bridge.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 debounceMs = Number(process.env.NOTIFY_DEBOUNCE_MS || '30000');
+    const humanCount = await getVoiceChannelHumanCount();
+    const notifier = ensureNotifier();
+    if (!notifier.shouldNotify({ humanCount, taskMs: elapsedMs, minTaskMs, userOptIn: bridge.notifyUserOptIn })) return;
+    const text = String(answer || '').trim();
+    const lastSentence = text.split(/(?<=[.!?。！？])\s+/).filter(Boolean).pop() || text;
+    const body = lastSentence.slice(0, 200);
+    const now = Date.now();
+    if (body && body === bridge.lastNotifyBody && now - bridge.lastNotifyAt < debounceMs) {
+      log('notify debounced', 'sinceLastMs', now - bridge.lastNotifyAt);
+      return;
+    }
+    const title = label ? `${label} finished` : 'VerbalCoding finished';
+    const deepLink = buildDiscordDeepLink({ guildId, channelId: bridge.activeVoiceChannelId });
+    try {
+      const result = await notifier.send({ title, body, deepLink });
+      bridge.lastNotifyAt = now;
+      bridge.lastNotifyBody = body;
+      log('notify sent', 'provider', provider, 'status', result?.status || result?.ok, 'skipped', result?.skipped || false);
+    } catch (e) {
+      warn('notify send failed', e?.message || e);
+    }
+  }
+
+  return {
+    ensureNotifier,
+    notifyStatusText,
+    getVoiceChannelHumanCount,
+    maybeNotifyTaskComplete,
+  };
+}

package/app-node/notification_handler.test.mjs

@@ -0,0 +1,187 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotificationHandler } from './notification_handler.mjs';
+import { createBridge } from './bridge_context.mjs';
+
+function makeDeps(overrides = {}) {
+  const bridge = createBridge();
+  const client = {
+    channels: {
+      fetch: async () => ({ members: new Map() }),
+    },
+  };
+  return { bridge, client, log: () => {}, warn: () => {}, ...overrides };
+}
+
+test('createNotificationHandler exposes the expected functions', () => {
+  const h = createNotificationHandler(makeDeps());
+  for (const name of ['ensureNotifier', 'notifyStatusText', 'getVoiceChannelHumanCount', 'maybeNotifyTaskComplete']) {
+    assert.equal(typeof h[name], 'function', `${name} is exposed`);
+  }
+});
+
+test('ensureNotifier memoizes onto bridge.notifierInstance', () => {
+  const deps = makeDeps();
+  const { ensureNotifier } = createNotificationHandler(deps);
+  const first = ensureNotifier();
+  const second = ensureNotifier();
+  assert.equal(first, second);
+  assert.equal(deps.bridge.notifierInstance, first);
+});
+
+test('notifyStatusText reflects userOptIn and provider configuration', () => {
+  const prev = { ...process.env };
+  process.env.NOTIFY_PROVIDER = 'ntfy';
+  process.env.NTFY_TOPIC = '';
+  try {
+    const deps = makeDeps();
+    const { notifyStatusText } = createNotificationHandler(deps);
+    let text = notifyStatusText();
+    assert.match(text, /empty-channel only/);
+    assert.match(text, /NOT configured/);
+    deps.bridge.notifyUserOptIn = true;
+    process.env.NTFY_TOPIC = 'topic-x';
+    text = notifyStatusText();
+    assert.match(text, /always/);
+    assert.match(text, /\(configured\)/);
+  } finally {
+    Object.keys(process.env).forEach(k => { if (!(k in prev)) delete process.env[k]; });
+    Object.assign(process.env, prev);
+  }
+});
+
+test('getVoiceChannelHumanCount returns 0 when no active channel', async () => {
+  const deps = makeDeps();
+  const { getVoiceChannelHumanCount } = createNotificationHandler(deps);
+  assert.equal(await getVoiceChannelHumanCount(), 0);
+});
+
+test('getVoiceChannelHumanCount excludes bots', async () => {
+  const members = new Map([
+    ['1', { user: { bot: false } }],
+    ['2', { user: { bot: true } }],
+    ['3', { user: { bot: false } }],
+  ]);
+  const deps = makeDeps({ client: { channels: { fetch: async () => ({ members }) } } });
+  deps.bridge.activeVoiceChannelId = 'vc-1';
+  const { getVoiceChannelHumanCount } = createNotificationHandler(deps);
+  assert.equal(await getVoiceChannelHumanCount(), 2);
+});
+
+test('maybeNotifyTaskComplete returns early when provider is unset/noop', async () => {
+  const prev = process.env.NOTIFY_PROVIDER;
+  try {
+    delete process.env.NOTIFY_PROVIDER;
+    const deps = makeDeps();
+    const { maybeNotifyTaskComplete } = createNotificationHandler(deps);
+    await maybeNotifyTaskComplete({ answer: 'ok', label: 'agent', elapsedMs: 99999, guildId: 'g' });
+    assert.equal(deps.bridge.notifierInstance, null, 'no notifier when provider unset');
+    process.env.NOTIFY_PROVIDER = 'noop';
+    await maybeNotifyTaskComplete({ answer: 'ok', label: 'agent', elapsedMs: 99999, guildId: 'g' });
+    assert.equal(deps.bridge.notifierInstance, null, 'no notifier when provider noop');
+  } finally {
+    if (prev === undefined) delete process.env.NOTIFY_PROVIDER;
+    else process.env.NOTIFY_PROVIDER = prev;
+  }
+});
+
+// --- happy-path send + debounce + body construction ----------------------
+
+test('maybeNotifyTaskComplete fires notifier.send with last sentence as body, deep link, and tracks lastNotify state', async () => {
+  const prev = { ...process.env };
+  const calls = [];
+  process.env.NOTIFY_PROVIDER = 'ntfy';
+  process.env.NTFY_TOPIC = 'topic-x';
+  process.env.NOTIFY_MIN_TASK_MS = '0';      // pass the min-task gate
+  process.env.NOTIFY_DEBOUNCE_MS = '5000';
+  try {
+    const deps = makeDeps();
+    deps.bridge.notifyUserOptIn = true;        // bypass humanCount/empty-channel gate
+    deps.bridge.activeVoiceChannelId = 'vc-1'; // for deepLink construction
+    // Pre-seed a notifier so we don't depend on createNotifier internals.
+    deps.bridge.notifierInstance = {
+      shouldNotify: () => true,
+      send: async payload => { calls.push(payload); return { ok: true, status: 200 }; },
+    };
+    const { maybeNotifyTaskComplete } = createNotificationHandler(deps);
+    const answer = 'first sentence here. SECOND SENTENCE is the body.';
+    await maybeNotifyTaskComplete({ answer, label: 'hermes', elapsedMs: 5000, guildId: 'g-1' });
+    assert.equal(calls.length, 1, 'notifier.send called exactly once');
+    assert.equal(calls[0].title, 'hermes finished');
+    assert.equal(calls[0].body, 'SECOND SENTENCE is the body.', 'body = last sentence');
+    assert.match(calls[0].deepLink, /g-1/, 'deep link includes guild id');
+    assert.ok(deps.bridge.lastNotifyAt > 0, 'lastNotifyAt updated');
+    assert.equal(deps.bridge.lastNotifyBody, 'SECOND SENTENCE is the body.');
+  } finally {
+    Object.keys(process.env).forEach(k => { if (!(k in prev)) delete process.env[k]; });
+    Object.assign(process.env, prev);
+  }
+});
+
+test('maybeNotifyTaskComplete debounces identical body within debounce window', async () => {
+  const prev = { ...process.env };
+  process.env.NOTIFY_PROVIDER = 'ntfy';
+  process.env.NTFY_TOPIC = 'topic-x';
+  process.env.NOTIFY_MIN_TASK_MS = '0';
+  process.env.NOTIFY_DEBOUNCE_MS = '60000';
+  try {
+    let sendCalls = 0;
+    const deps = makeDeps();
+    deps.bridge.notifyUserOptIn = true;
+    deps.bridge.notifierInstance = {
+      shouldNotify: () => true,
+      send: async () => { sendCalls++; return { ok: true }; },
+    };
+    const { maybeNotifyTaskComplete } = createNotificationHandler(deps);
+    const answer = 'identical message';
+    await maybeNotifyTaskComplete({ answer, label: 'a', elapsedMs: 5000, guildId: 'g' });
+    await maybeNotifyTaskComplete({ answer, label: 'a', elapsedMs: 5000, guildId: 'g' });
+    assert.equal(sendCalls, 1, 'second identical call is debounced');
+  } finally {
+    Object.keys(process.env).forEach(k => { if (!(k in prev)) delete process.env[k]; });
+    Object.assign(process.env, prev);
+  }
+});
+
+test('maybeNotifyTaskComplete respects shouldNotify=false (e.g. occupied channel, opt-out)', async () => {
+  const prev = { ...process.env };
+  process.env.NOTIFY_PROVIDER = 'ntfy';
+  process.env.NOTIFY_MIN_TASK_MS = '0';
+  try {
+    let sendCalls = 0;
+    const deps = makeDeps();
+    deps.bridge.notifierInstance = {
+      shouldNotify: () => false,
+      send: async () => { sendCalls++; return { ok: true }; },
+    };
+    const { maybeNotifyTaskComplete } = createNotificationHandler(deps);
+    await maybeNotifyTaskComplete({ answer: 'hi', label: 'x', elapsedMs: 9999, guildId: 'g' });
+    assert.equal(sendCalls, 0, 'send not called when shouldNotify returns false');
+    assert.equal(deps.bridge.lastNotifyAt, 0, 'lastNotifyAt untouched');
+  } finally {
+    Object.keys(process.env).forEach(k => { if (!(k in prev)) delete process.env[k]; });
+    Object.assign(process.env, prev);
+  }
+});
+
+test('maybeNotifyTaskComplete swallows notifier.send errors and warns', async () => {
+  const prev = { ...process.env };
+  process.env.NOTIFY_PROVIDER = 'ntfy';
+  process.env.NOTIFY_MIN_TASK_MS = '0';
+  try {
+    const warnCalls = [];
+    const deps = makeDeps({ warn: (...args) => warnCalls.push(args) });
+    deps.bridge.notifyUserOptIn = true;
+    deps.bridge.notifierInstance = {
+      shouldNotify: () => true,
+      send: async () => { throw new Error('network down'); },
+    };
+    const { maybeNotifyTaskComplete } = createNotificationHandler(deps);
+    // Must not reject the calling code.
+    await maybeNotifyTaskComplete({ answer: 'hi', label: 'x', elapsedMs: 9999, guildId: 'g' });
+    assert.ok(warnCalls.some(args => /notify send failed/.test(args[0])), 'warn called with explanatory message');
+  } finally {
+    Object.keys(process.env).forEach(k => { if (!(k in prev)) delete process.env[k]; });
+    Object.assign(process.env, prev);
+  }
+});

package/app-node/notify.mjs

@@ -0,0 +1,73 @@
+const SECRET_RE = /\b(?:token|api[_-]?key|password|secret|authorization|bearer)\b\s*[:=]?\s*\S+/gi;
+const SK_RE = /\bsk-[a-zA-Z0-9_-]{8,}\b/g;
+const NTFY_BASE_DEFAULT = 'https://ntfy.sh';
+
+function redact(text) {
+  return String(text || '')
+    .replace(SECRET_RE, '$& [REDACTED]')
+    .replace(/(\[REDACTED\]\s*)+/g, '[REDACTED] ')
+    .replace(SK_RE, '[REDACTED]');
+}
+
+export function buildDiscordDeepLink({ guildId, channelId } = {}) {
+  if (!guildId || !channelId) return '';
+  return `https://discord.com/channels/${guildId}/${channelId}`;
+}
+
+export function createNotifier({
+  provider = 'ntfy',
+  topic = '',
+  fetchImpl = globalThis.fetch,
+  ntfyBase = NTFY_BASE_DEFAULT,
+  pushoverUser = '',
+  pushoverToken = '',
+} = {}) {
+  async function sendNtfy({ title, body, deepLink }) {
+    if (!topic) return { skipped: true, reason: 'no topic' };
+    const headers = { Title: title };
+    if (deepLink) headers.Click = deepLink;
+    const res = await fetchImpl(`${ntfyBase}/${encodeURIComponent(topic)}`, {
+      method: 'POST',
+      headers,
+      body,
+    });
+    return { ok: !!res?.ok, status: res?.status };
+  }
+
+  async function sendPushover({ title, body, deepLink }) {
+    if (!pushoverUser || !pushoverToken) return { skipped: true, reason: 'no pushover creds' };
+    const payload = {
+      user: pushoverUser,
+      token: pushoverToken,
+      title,
+      message: body,
+    };
+    if (deepLink) {
+      payload.url = deepLink;
+      payload.url_title = 'Open Discord';
+    }
+    const res = await fetchImpl('https://api.pushover.net/1/messages.json', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    return { ok: !!res?.ok, status: res?.status };
+  }
+
+  async function send({ title = 'VerbalCoding', body = '', deepLink = '' } = {}) {
+    const safeBody = redact(body).slice(0, 200);
+    const safeTitle = redact(title).slice(0, 80);
+    if (provider === 'ntfy') return sendNtfy({ title: safeTitle, body: safeBody, deepLink });
+    if (provider === 'pushover') return sendPushover({ title: safeTitle, body: safeBody, deepLink });
+    if (provider === 'noop') return { ok: true };
+    throw new Error(`unknown notify provider ${provider}`);
+  }
+
+  function shouldNotify({ humanCount = 0, taskMs = 0, minTaskMs = 60_000, userOptIn = false } = {}) {
+    if (taskMs < minTaskMs) return false;
+    if (userOptIn) return true;
+    return humanCount === 0;
+  }
+
+  return { send, shouldNotify };
+}

package/app-node/notify.test.mjs

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotifier, buildDiscordDeepLink } from './notify.mjs';
+
+test('ntfy provider posts to topic URL with title body and click headers', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => { calls.push({ url, opts }); return { ok: true, status: 200 }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'verbalcoding-test', fetchImpl });
+  const res = await n.send({ title: 'Done', body: 'All green.', deepLink: 'discord://x' });
+  assert.equal(res.ok, true);
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].url, /ntfy\.sh\/verbalcoding-test/);
+  assert.equal(calls[0].opts.headers.Title, 'Done');
+  assert.equal(calls[0].opts.headers.Click, 'discord://x');
+  assert.equal(calls[0].opts.body, 'All green.');
+});
+
+test('ntfy returns skipped when topic missing', async () => {
+  const n = createNotifier({ provider: 'ntfy', fetchImpl: async () => ({ ok: true }) });
+  const res = await n.send({ title: 't', body: 'b' });
+  assert.equal(res.skipped, true);
+});
+
+test('shouldNotify true when zero humans and task long enough', () => {
+  const n = createNotifier({ provider: 'noop' });
+  assert.equal(n.shouldNotify({ humanCount: 0, taskMs: 10_000, minTaskMs: 1000 }), true);
+  assert.equal(n.shouldNotify({ humanCount: 1, taskMs: 10_000, minTaskMs: 1000 }), false);
+  assert.equal(n.shouldNotify({ humanCount: 0, taskMs: 100, minTaskMs: 1000 }), false);
+  assert.equal(n.shouldNotify({ humanCount: 1, taskMs: 10_000, minTaskMs: 1000, userOptIn: true }), true);
+});
+
+test('redacts secret patterns from body', async () => {
+  const calls = [];
+  const fetchImpl = async (u, o) => { calls.push(o); return { ok: true }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'x', fetchImpl });
+  await n.send({ title: 't', body: 'token=abc123 finished. sk-fooBar12 also.', deepLink: '' });
+  assert.match(calls[0].body, /\[REDACTED\]/);
+  assert.doesNotMatch(calls[0].body, /sk-fooBar12/);
+});
+
+test('truncates long body to 200 chars', async () => {
+  const calls = [];
+  const fetchImpl = async (u, o) => { calls.push(o); return { ok: true }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'x', fetchImpl });
+  await n.send({ title: 't', body: 'x'.repeat(500) });
+  assert.equal(calls[0].body.length, 200);
+});
+
+test('pushover posts json payload with url', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => { calls.push({ url, opts }); return { ok: true, status: 200 }; };
+  const n = createNotifier({ provider: 'pushover', pushoverUser: 'u', pushoverToken: 'tk', fetchImpl });
+  await n.send({ title: 'Done', body: 'all good', deepLink: 'discord://x' });
+  assert.match(calls[0].url, /pushover\.net/);
+  const body = JSON.parse(calls[0].opts.body);
+  assert.equal(body.user, 'u');
+  assert.equal(body.url, 'discord://x');
+});
+
+test('buildDiscordDeepLink composes web URL', () => {
+  assert.equal(buildDiscordDeepLink({ guildId: '1', channelId: '2' }), 'https://discord.com/channels/1/2');
+  assert.equal(buildDiscordDeepLink({}), '');
+});
+
+test('unknown provider throws', async () => {
+  const n = createNotifier({ provider: 'unknown' });
+  await assert.rejects(() => n.send({ title: 't', body: 'b' }), /unknown notify provider/);
+});

package/app-node/plan_dispatcher.mjs

@@ -0,0 +1,215 @@
+// Plan-mode dispatcher: STATEFUL plan-mode logic that builds on
+// ./plan_mode.mjs's pure parsers/renderers. Owns the per-channel plan
+// state lifecycle on bridge.planStates and the multi-turn decision UX.
+//
+// Phase 7b extraction from utterance_router.mjs. Five functions:
+//   - planChannelKey: which channel-id keys the plan state. Kept here
+//     because plan state, routing state, and ontology state all share
+//     this key shape.
+//   - askNextDecision / finalizePlanReady / planNarrationLines: the
+//     narration helpers used to prompt the user for next decisions or
+//     confirm a plan is ready to run.
+//   - dispatchPlanModeUtterance: the multi-turn state machine. Detects
+//     plan-entry utterances, processes voice approve/skip/insert/cancel
+//     commands, resolves decisions one at a time, and either re-prompts
+//     or returns { handled, prompt? } for the caller to feed to the agent.
+//
+// Caller integration: voice_turn_runner consumes dispatchPlanModeUtterance
+// as a dep. The Discord text path doesn't touch plan mode (no plan-mode
+// integration in text agent messages today).
+
+export function createPlanDispatcher(deps) {
+  const {
+    bridge,
+    settings,
+    sendText,
+    speakText,
+    routingStateFor,
+    adapterForBackend,
+    adapterForProjectSession,
+    resolveProjectSessionForChannel,
+    isAgentRoutingDecision,
+    parseDecisionAnswer,
+    parsePlanVoiceCommand,
+    applyPlanCommand,
+    parsePlanOutput,
+    renderDecisionPrompt,
+    renderResolvedDecisions,
+    renderFinalPlan,
+    planModePreamble,
+    planExecutionPreamble,
+    isPlanEntryUtterance,
+  } = deps;
+
+function planChannelKey() {
+  return bridge.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);
+}
+
+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 = bridge.planStates.get(key);
+
+  if (existing && existing.pendingDecisionIndex < existing.decisions.length) {
+    const controlCommand = parsePlanVoiceCommand(prompt, language);
+    if (controlCommand.type === 'cancel') {
+      const cancelState = routingStateFor(key);
+      if (existing.routingSnapshot) cancelState.activeRouting = { ...existing.routingSnapshot };
+      cancelState.pendingFallbackPrompt = null;
+      cancelState.lastResolvedDecisions = {};
+      bridge.planStates.delete(key);
+      const msg = /^en/i.test(String(language || '')) ? 'Plan cancelled.' : '계획을 취소했어.';
+      await sendText(`❎ ${msg}`);
+      await speakText(msg, signal, null);
+      return { handled: true };
+    }
+    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,
+    };
+    bridge.planStates.set(key, next);
+    if (isAgentRoutingDecision(decision) && answer.choice) {
+      const candidate = adapterForBackend(answer.choice, resolveProjectSessionForChannel(key));
+      if (candidate) {
+        routingStateFor(key).activeRouting = { backend: answer.choice, sticky: true };
+      } else {
+        const msg = /^en/i.test(String(language || ''))
+          ? `${answer.choice} is not installed; staying with ${settings.agent.label}.`
+          : `${answer.choice}이(가) 설치되어 있지 않아. ${settings.agent.label}로 진행할게.`;
+        await sendText(`⚠️ ${msg}`);
+        await speakText(msg, signal, null);
+      }
+    }
+    if (next.pendingDecisionIndex < next.decisions.length) {
+      await askNextDecision(next, signal);
+    } else {
+      await finalizePlanReady(next, signal);
+    }
+    return { handled: true };
+  }
+
+  if (existing) {
+    const cmd = parsePlanVoiceCommand(prompt, language);
+    if (cmd.type === 'skip' || cmd.type === 'insert') {
+      const nextSteps = applyPlanCommand(existing.steps, cmd);
+      bridge.planStates.set(key, { ...existing, steps: nextSteps });
+      await finalizePlanReady({ ...existing, steps: nextSteps }, signal);
+      return { handled: true };
+    }
+    if (cmd.type === 'cancel') {
+      const cancelState = routingStateFor(key);
+      if (existing.routingSnapshot) cancelState.activeRouting = { ...existing.routingSnapshot };
+      cancelState.pendingFallbackPrompt = null;
+      cancelState.lastResolvedDecisions = {};
+      bridge.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') {
+      routingStateFor(key).lastResolvedDecisions = existing.resolvedDecisions || {};
+      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');
+      bridge.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 };
+    }
+    bridge.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 planKey = planChannelKey();
+    const routingSnapshot = { ...routingStateFor(planKey).activeRouting };
+    const state = {
+      steps,
+      decisions,
+      resolvedDecisions: {},
+      pendingDecisionIndex: 0,
+      originalPrompt: prompt,
+      language,
+      routingSnapshot,
+    };
+    bridge.planStates.set(planKey, 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}`;
+}
+
+  return {
+    planChannelKey,
+    askNextDecision,
+    finalizePlanReady,
+    dispatchPlanModeUtterance,
+    planNarrationLines,
+  };
+}