verbalcoding 0.2.0

package/app-node/barge_in.test.mjs

@@ -0,0 +1,179 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  bargeInThresholdsForMode,
+  createLiveBargeInMonitor,
+  isBargeInCandidate,
+  isRepeatedNoiseTranscript,
+  isExplicitBargeInTranscript,
+  shouldUseLivePlaybackBargeIn,
+  pcm16StereoLevels,
+  sensitivityModeFromTranscript,
+} from './barge_in.mjs';
+
+function pcmWithConstantSample(sample, sampleCount) {
+  const buf = Buffer.alloc(sampleCount * 2);
+  for (let i = 0; i < sampleCount; i += 1) buf.writeInt16LE(sample, i * 2);
+  return buf;
+}
+
+test('isBargeInCandidate requires enough buffered audio before confirming', () => {
+  assert.equal(
+    isBargeInCandidate(100, { meanDb: -10, maxDb: -3 }, { minBytes: 200, minMeanDb: -35, minMaxDb: -18 }),
+    false,
+  );
+  assert.equal(
+    isBargeInCandidate(200, { meanDb: -10, maxDb: -3 }, { minBytes: 200, minMeanDb: -35, minMaxDb: -18 }),
+    true,
+  );
+});
+
+test('pcm16StereoLevels reports silence as negative infinity', () => {
+  const levels = pcm16StereoLevels(Buffer.alloc(480));
+  assert.equal(levels.meanDb, -Infinity);
+  assert.equal(levels.maxDb, -Infinity);
+  assert.equal(levels.sampleCount, 240);
+});
+
+test('createLiveBargeInMonitor confirms while audio stream is still active', () => {
+  const events = [];
+  const monitor = createLiveBargeInMonitor({
+    minBytes: 400,
+    minMeanDb: -35,
+    minMaxDb: -18,
+    onConfirm: event => events.push(event),
+  });
+
+  assert.equal(monitor.push(pcmWithConstantSample(12000, 100)), false);
+  assert.equal(events.length, 0);
+  assert.equal(monitor.push(pcmWithConstantSample(12000, 100)), true);
+
+  assert.equal(events.length, 1);
+  assert.equal(events[0].pcmBytes, 400);
+  assert.ok(events[0].levels.meanDb > -12);
+  assert.equal(monitor.confirmed, true);
+});
+
+test('playback barge-in requires a longer deliberate utterance by default', () => {
+  const pcmBytes = 48000 * 2 * 2 * 0.9;
+  const events = [];
+  const monitor = createLiveBargeInMonitor({
+    minBytes: pcmBytes,
+    minMeanDb: -36,
+    minMaxDb: -18,
+    requireBoth: true,
+    onConfirm: event => events.push(event),
+  });
+
+  assert.equal(monitor.push(pcmWithConstantSample(5000, pcmBytes / 3 / 2)), false);
+  assert.equal(events.length, 0);
+
+  assert.equal(monitor.push(pcmWithConstantSample(5000, pcmBytes / 3 / 2)), false);
+  assert.equal(events.length, 0);
+
+  assert.equal(monitor.push(pcmWithConstantSample(5000, pcmBytes / 3 / 2)), true);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].pcmBytes, pcmBytes);
+  assert.ok(events[0].levels.meanDb > -36);
+  assert.ok(events[0].levels.maxDb > -18);
+});
+
+test('playback barge-in requireBoth ignores short clicky peaks without sustained RMS', () => {
+  assert.equal(isBargeInCandidate(400, { meanDb: -50, maxDb: -3 }, { minBytes: 400, minMeanDb: -36, minMaxDb: -18, requireBoth: true }), false);
+  assert.equal(isBargeInCandidate(400, { meanDb: -35, maxDb: -17 }, { minBytes: 400, minMeanDb: -36, minMaxDb: -18, requireBoth: true }), true);
+});
+
+test('createLiveBargeInMonitor ignores low-volume candidates after minimum duration', () => {
+  const events = [];
+  const monitor = createLiveBargeInMonitor({
+    minBytes: 400,
+    minMeanDb: -35,
+    minMaxDb: -18,
+    onConfirm: event => events.push(event),
+  });
+
+  assert.equal(monitor.push(pcmWithConstantSample(120, 200)), false);
+
+  assert.equal(events.length, 0);
+  assert.equal(monitor.confirmed, false);
+});
+
+test('default barge-in thresholds are intentionally less sensitive than utterance detection', () => {
+  const normal = bargeInThresholdsForMode('normal');
+  const conservative = bargeInThresholdsForMode('conservative');
+
+  assert.equal(normal.minBytes, 48000 * 2 * 2 * 1.4);
+  assert.equal(normal.minMeanDb, -30);
+  assert.equal(normal.minMaxDb, -14);
+  assert.equal(conservative.minBytes, 48000 * 2 * 2 * 1.8);
+  assert.equal(conservative.minMeanDb, -27);
+  assert.equal(conservative.minMaxDb, -12);
+});
+
+test('conservative sensitivity requires a longer barge-in than normal mode', () => {
+  const normal = bargeInThresholdsForMode('normal', {
+    minSeconds: 0.9,
+    minMeanDb: -35,
+    minMaxDb: -18,
+  });
+  const conservative = bargeInThresholdsForMode('conservative', {
+    minSeconds: 0.9,
+    minMeanDb: -35,
+    minMaxDb: -18,
+  });
+
+  assert.equal(normal.minBytes, 48000 * 2 * 2 * 0.9);
+  assert.equal(conservative.minBytes, 48000 * 2 * 2 * 1.8);
+  assert.equal(conservative.minMeanDb, -27);
+  assert.equal(conservative.minMaxDb, -12);
+});
+
+test('sensitivityModeFromTranscript detects temporary outdoor and indoor mode requests', () => {
+  assert.deepEqual(sensitivityModeFromTranscript('밖이라 시끄러워 감도 낮춰'), { mode: 'conservative', reason: 'outdoor' });
+  assert.deepEqual(sensitivityModeFromTranscript('외부 보수 모드 켜'), { mode: 'conservative', reason: 'outdoor' });
+  assert.deepEqual(sensitivityModeFromTranscript('이제 실내니까 평소 감도로 해'), { mode: 'normal', reason: 'indoor' });
+  assert.equal(sensitivityModeFromTranscript('그냥 다음 작업 해줘'), null);
+});
+
+test('sensitivityModeFromTranscript ignores complaints that mention sensitivity mode', () => {
+  assert.equal(sensitivityModeFromTranscript('누가 외부 보수 모드로 바꾸랬어?'), null);
+  assert.equal(sensitivityModeFromTranscript('끼어들기 민감도 설정을 너무 멍청하게 해놨잖아'), null);
+  assert.equal(sensitivityModeFromTranscript('외부 보수 모드로 바꾸라는 말 아니야'), null);
+});
+
+test('isRepeatedNoiseTranscript rejects short repeated syllable noise', () => {
+  assert.equal(isRepeatedNoiseTranscript('너덜너덜너덜'), true);
+  assert.equal(isRepeatedNoiseTranscript('쒸'), true);
+  assert.equal(isRepeatedNoiseTranscript('잠깐 잠깐 멈춰'), false);
+});
+
+test('isRepeatedNoiseTranscript keeps common short valid Korean utterances', () => {
+  assert.equal(isRepeatedNoiseTranscript('안녕!'), false);
+  assert.equal(isRepeatedNoiseTranscript('네'), false);
+  assert.equal(isRepeatedNoiseTranscript('응'), false);
+  assert.equal(isRepeatedNoiseTranscript('그래'), false);
+});
+
+test('isRepeatedNoiseTranscript keeps real English sentences with repeated words or low unique ratio', () => {
+  assert.equal(isRepeatedNoiseTranscript('Fuck you. Fuck you.'), false);
+  assert.equal(isRepeatedNoiseTranscript("The problem is, you ignore my speech sometimes. That's the fucking problem."), false);
+  assert.equal(isRepeatedNoiseTranscript("I found the problem. You don't detect my speech."), false);
+});
+
+test('isExplicitBargeInTranscript only treats clear stop phrases as processing interrupts', () => {
+  assert.equal(isExplicitBargeInTranscript('잠깐 잠깐 멈춰'), true);
+  assert.equal(isExplicitBargeInTranscript('그만 말해'), true);
+  assert.equal(isExplicitBargeInTranscript('stop talking'), true);
+  assert.equal(isExplicitBargeInTranscript('shut up'), true);
+  assert.equal(isExplicitBargeInTranscript('cancel this'), true);
+  assert.equal(isExplicitBargeInTranscript('시청해 주셔서 감사합니다'), false);
+  assert.equal(isExplicitBargeInTranscript('너덜너덜너덜'), false);
+});
+
+
+test('shouldUseLivePlaybackBargeIn avoids aborting an active agent during progress TTS', () => {
+  assert.equal(shouldUseLivePlaybackBargeIn({ speaking: true, processing: false }), true);
+  assert.equal(shouldUseLivePlaybackBargeIn({ speaking: true, processing: true }), false);
+  assert.equal(shouldUseLivePlaybackBargeIn({ speaking: false, processing: true }), false);
+});

package/app-node/bridge_logger.mjs

@@ -0,0 +1,66 @@
+export function isBrokenPipeError(error) {
+  return error?.code === 'EPIPE' || /write EPIPE/i.test(String(error?.message || error));
+}
+
+export function isTransientNetworkError(error) {
+  return ['EPIPE', 'ECONNRESET', 'ETIMEDOUT'].includes(error?.code) || /write EPIPE|socket hang up/i.test(String(error?.message || error));
+}
+
+export function createTransientErrorReporter({
+  now = () => Date.now(),
+  intervalMs = 30000,
+  warn = () => {},
+  isTransientError = isTransientNetworkError,
+} = {}) {
+  let nextLogAt = 0;
+  let suppressed = 0;
+  return function reportTransientError(label, error) {
+    if (!isTransientError(error)) return false;
+    const time = now();
+    if (time < nextLogAt) {
+      suppressed += 1;
+      return true;
+    }
+    const repeated = suppressed ? `repeated ${suppressed} times` : '';
+    suppressed = 0;
+    nextLogAt = time + intervalMs;
+    warn(`suppressed transient ${label}`, error?.code || '', error?.message || error, repeated);
+    return true;
+  };
+}
+
+export function createBridgeLogger({
+  now = () => new Date().toISOString(),
+  stdout = console,
+  appendLine = () => {},
+} = {}) {
+  let stdioBroken = false;
+
+  function lineFrom(args) {
+    return [now(), ...args].map(String).join(' ');
+  }
+
+  function emit(kind, args) {
+    const line = lineFrom(args);
+    try { appendLine(line); } catch {}
+    if (stdioBroken) return line;
+    try {
+      const fn = kind === 'warn' ? stdout.warn : stdout.log;
+      fn.call(stdout, line);
+    } catch (error) {
+      if (isBrokenPipeError(error)) {
+        stdioBroken = true;
+        return line;
+      }
+      throw error;
+    }
+    return line;
+  }
+
+  return {
+    log(...args) { return emit('log', args); },
+    warn(...args) { return emit('warn', args); },
+    markStdioBroken() { stdioBroken = true; },
+    get stdioBroken() { return stdioBroken; },
+  };
+}

package/app-node/bridge_logger.test.mjs

@@ -0,0 +1,73 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { createBridgeLogger, createTransientErrorReporter, isBrokenPipeError } from './bridge_logger.mjs';
+
+test('isBrokenPipeError recognizes stdout/stderr pipe failures', () => {
+  assert.equal(isBrokenPipeError({ code: 'EPIPE', message: 'write EPIPE' }), true);
+  assert.equal(isBrokenPipeError({ code: 'ECONNRESET', message: 'socket hang up' }), false);
+});
+
+test('createBridgeLogger disables stdio after EPIPE but keeps file logging', () => {
+  const stdioCalls = [];
+  const fileLines = [];
+  const logger = createBridgeLogger({
+    now: () => '2026-05-01T00:00:00.000Z',
+    stdout: {
+      log: (...args) => {
+        stdioCalls.push(args);
+        const error = new Error('write EPIPE');
+        error.code = 'EPIPE';
+        throw error;
+      },
+      warn: (...args) => stdioCalls.push(args),
+    },
+    appendLine: line => fileLines.push(line),
+  });
+
+  logger.log('first');
+  logger.warn('second');
+
+  assert.equal(stdioCalls.length, 1);
+  assert.equal(fileLines.length, 2);
+  assert.match(fileLines[0], /first/);
+  assert.match(fileLines[1], /second/);
+});
+
+test('createBridgeLogger can be marked stdio-broken from stream error handlers', () => {
+  const stdioCalls = [];
+  const fileLines = [];
+  const logger = createBridgeLogger({
+    now: () => '2026-05-01T00:00:00.000Z',
+    stdout: { log: (...args) => stdioCalls.push(args), warn: (...args) => stdioCalls.push(args) },
+    appendLine: line => fileLines.push(line),
+  });
+
+  logger.markStdioBroken();
+  logger.log('file only');
+
+  assert.equal(stdioCalls.length, 0);
+  assert.equal(fileLines.length, 1);
+  assert.match(fileLines[0], /file only/);
+});
+
+test('createTransientErrorReporter rate-limits repeated transient errors', () => {
+  let now = 1000;
+  const lines = [];
+  const reporter = createTransientErrorReporter({
+    now: () => now,
+    intervalMs: 5000,
+    warn: (...args) => lines.push(args.join(' ')),
+  });
+  const error = Object.assign(new Error('write EPIPE'), { code: 'EPIPE' });
+
+  assert.equal(reporter('uncaught exception', error), true);
+  assert.equal(reporter('uncaught exception', error), true);
+  assert.equal(reporter('uncaught exception', error), true);
+  now = 7000;
+  assert.equal(reporter('uncaught exception', error), true);
+
+  assert.equal(lines.length, 2);
+  assert.match(lines[0], /suppressed transient uncaught exception EPIPE write EPIPE/);
+  assert.match(lines[1], /repeated 2 times/);
+});

package/app-node/bridge_state.mjs

@@ -0,0 +1,104 @@
+export function createBridgeState({ log = () => {}, cleanupFile = () => {} } = {}) {
+  let epoch = 0;
+  const pendingUtterances = new Map();
+  const deferredUtterances = [];
+
+  function currentEpoch() {
+    return epoch;
+  }
+
+  function discardQueues(reason = 'state-change') {
+    epoch += 1;
+    for (const pending of pendingUtterances.values()) {
+      if (pending.timer) clearTimeout(pending.timer);
+      for (const file of pending.files || []) cleanupFile(file);
+    }
+    pendingUtterances.clear();
+    for (const item of deferredUtterances.splice(0)) {
+      if (item?.wavPath) cleanupFile(item.wavPath);
+    }
+    log('discard voice input queues', reason, 'epoch', epoch);
+    return epoch;
+  }
+
+  function getPending(userId) {
+    return pendingUtterances.get(userId);
+  }
+
+  function setPending(userId, pending) {
+    pendingUtterances.set(userId, { ...pending, epoch: pending.epoch ?? epoch });
+    return pendingUtterances.get(userId);
+  }
+
+  function deletePending(userId) {
+    const pending = pendingUtterances.get(userId);
+    pendingUtterances.delete(userId);
+    return pending;
+  }
+
+  function clearPendingTimer(userId) {
+    const pending = pendingUtterances.get(userId);
+    if (pending?.timer) {
+      clearTimeout(pending.timer);
+      pending.timer = null;
+    }
+    return pending;
+  }
+
+  function appendSegment(userId, { file, pcmBytes, startedAtMs = Date.now(), endedAtMs = Date.now(), timerFactory }) {
+    let pending = pendingUtterances.get(userId);
+    if (pending && pending.epoch !== epoch) {
+      if (pending.timer) clearTimeout(pending.timer);
+      for (const oldFile of pending.files || []) cleanupFile(oldFile);
+      pendingUtterances.delete(userId);
+      pending = null;
+    }
+    if (!pending) {
+      pending = { files: [], pcmBytes: 0, timer: null, firstPacketAt: startedAtMs, lastSegmentEndAt: endedAtMs, epoch };
+      pendingUtterances.set(userId, pending);
+    }
+    pending.files.push(file);
+    pending.pcmBytes += pcmBytes;
+    pending.firstPacketAt = Math.min(pending.firstPacketAt || startedAtMs, startedAtMs);
+    pending.lastSegmentEndAt = Math.max(pending.lastSegmentEndAt || endedAtMs, endedAtMs);
+    if (pending.timer) clearTimeout(pending.timer);
+    pending.timer = timerFactory?.();
+    return pending;
+  }
+
+  function isStale(item) {
+    return !item || item.epoch !== epoch;
+  }
+
+  function enqueueDeferred(item, enqueueFn, maxSize) {
+    return enqueueFn(deferredUtterances, { ...item, epoch }, maxSize);
+  }
+
+  function shiftDeferred() {
+    while (deferredUtterances.length > 0) {
+      const item = deferredUtterances.shift();
+      if (!isStale(item)) return item;
+      if (item?.wavPath) cleanupFile(item.wavPath);
+      log('drop stale deferred utterance', 'utteranceEpoch', item?.epoch, 'currentEpoch', epoch);
+    }
+    return null;
+  }
+
+  function deferredSize() {
+    return deferredUtterances.length;
+  }
+
+  return {
+    appendSegment,
+    clearPendingTimer,
+    currentEpoch,
+    deferredSize,
+    deletePending,
+    discardQueues,
+    enqueueDeferred,
+    getPending,
+    isStale,
+    setPending,
+    shiftDeferred,
+  };
+}

package/app-node/bridge_state.test.mjs

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createBridgeState } from './bridge_state.mjs';
+
+test('bridge state discards pending and deferred utterances on epoch change', () => {
+  const cleaned = [];
+  const logs = [];
+  const state = createBridgeState({ cleanupFile: file => cleaned.push(file), log: (...args) => logs.push(args.join(' ')) });
+
+  state.appendSegment('user', {
+    file: '/tmp/one.wav',
+    pcmBytes: 10,
+    startedAtMs: 1,
+    endedAtMs: 2,
+    timerFactory: () => setTimeout(() => {}, 10000),
+  });
+  state.enqueueDeferred({ userId: 'user', wavPath: '/tmp/deferred.wav' }, (queue, item) => {
+    queue.push(item);
+    return { queued: true };
+  }, 10);
+
+  const nextEpoch = state.discardQueues('language-change');
+
+  assert.equal(nextEpoch, 1);
+  assert.deepEqual(cleaned.sort(), ['/tmp/deferred.wav', '/tmp/one.wav'].sort());
+  assert.equal(state.getPending('user'), undefined);
+  assert.equal(state.deferredSize(), 0);
+  assert.match(logs.join('\n'), /language-change/);
+});
+
+test('bridge state drops stale pending segment after config change', () => {
+  const cleaned = [];
+  const state = createBridgeState({ cleanupFile: file => cleaned.push(file) });
+
+  state.appendSegment('user', { file: '/tmp/old.wav', pcmBytes: 10, startedAtMs: 1, endedAtMs: 2 });
+  state.discardQueues('voice-change');
+  const pending = state.appendSegment('user', { file: '/tmp/new.wav', pcmBytes: 20, startedAtMs: 3, endedAtMs: 4 });
+
+  assert.equal(pending.epoch, state.currentEpoch());
+  assert.deepEqual(pending.files, ['/tmp/new.wav']);
+  assert.equal(pending.pcmBytes, 20);
+  assert.ok(cleaned.includes('/tmp/old.wav'));
+});
+
+test('bridge state skips stale deferred utterances', () => {
+  const cleaned = [];
+  const state = createBridgeState({ cleanupFile: file => cleaned.push(file) });
+
+  state.enqueueDeferred({ userId: 'user', wavPath: '/tmp/stale.wav' }, (queue, item) => {
+    queue.push(item);
+    return { queued: true };
+  }, 10);
+  state.discardQueues('language-change');
+  state.enqueueDeferred({ userId: 'user', wavPath: '/tmp/current.wav' }, (queue, item) => {
+    queue.push(item);
+    return { queued: true };
+  }, 10);
+
+  const next = state.shiftDeferred();
+  assert.equal(next.wavPath, '/tmp/current.wav');
+  assert.equal(state.shiftDeferred(), null);
+  assert.ok(cleaned.includes('/tmp/stale.wav'));
+});

package/app-node/cli_install.test.mjs

@@ -0,0 +1,97 @@
+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 { healInstanceProfileFromEnv } from './instance_profile_lifecycle.mjs';
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+
+test('package exposes a short vc shell command', () => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+  assert.equal(pkg.private, undefined);
+  assert.equal(pkg.license, 'MIT');
+  assert.equal(pkg.engines?.node, '>=20');
+  assert.equal(pkg.bin?.vc, 'scripts/cli.mjs');
+  assert.equal(pkg.bin?.verbalcoding, 'scripts/cli.mjs');
+  assert.ok(pkg.files.includes('app-node/'));
+  assert.ok(pkg.files.includes('scripts/*.mjs'));
+  assert.ok(pkg.files.includes('scripts/*.sh'));
+  assert.ok(pkg.files.includes('scripts/*.py'));
+  assert.ok(pkg.files.includes('run.sh'));
+  assert.ok(pkg.files.includes('LICENSE'));
+});
+
+test('CLI includes npm-friendly setup and start commands', () => {
+  const cli = fs.readFileSync(path.join(ROOT, 'scripts', 'cli.mjs'), 'utf8');
+
+  assert.match(cli, /vc setup \[--yes\]/);
+  assert.match(cli, /command === 'setup'/);
+  assert.match(cli, /VERBALCODING_SKIP_CLI_LINK/);
+  assert.match(cli, /command === 'start'/);
+  assert.match(cli, /run\.sh/);
+});
+
+test('installer shell script links the vc command during setup', () => {
+  const script = fs.readFileSync(path.join(ROOT, 'scripts', 'install.sh'), 'utf8');
+
+  assert.match(script, /bootstrap_prereqs\.sh/);
+  assert.match(script, /--no-wizard/);
+  assert.match(script, /VERBALCODING_SKIP_BOOTSTRAP/);
+  assert.match(script, /npm link/);
+  assert.match(script, /Installed shell CLI: vc/);
+  assert.match(script, /VERBALCODING_SKIP_CLI_LINK/);
+});
+
+test('bootstrap script installs cross-platform prerequisites and local model helpers', () => {
+  const script = fs.readFileSync(path.join(ROOT, 'scripts', 'bootstrap_prereqs.sh'), 'utf8');
+
+  assert.match(script, /brew install/);
+  assert.match(script, /apt-get install/);
+  assert.match(script, /dnf install/);
+  assert.match(script, /pacman -Sy/);
+  assert.match(script, /git clone --depth 1 https:\/\/github\.com\/ggml-org\/whisper\.cpp\.git/);
+  assert.match(script, /ggml-small-q5_1\.bin/);
+  assert.match(script, /\.venv-tts/);
+});
+
+test('Ubuntu Docker smoke script validates clean install without secrets', () => {
+  const script = fs.readFileSync(path.join(ROOT, 'scripts', 'docker_ubuntu_smoke.sh'), 'utf8');
+
+  assert.match(script, /ubuntu:24\.04/);
+  assert.match(script, /git .*archive --format=tar HEAD/);
+  assert.match(script, /\.\/scripts\/install\.sh --yes --no-wizard/);
+  assert.match(script, /DISCORD_BOT_TOKEN="smoke-test-token"/);
+  assert.match(script, /AGENT_BACKEND="custom"/);
+  assert.match(script, /vc doctor/);
+  assert.doesNotMatch(script, /npm run vc/);
+});
+
+test('healInstanceProfileFromEnv ensures profile when HERMES_HOME is set', async () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'vc-home-'));
+  const calls = [];
+  const ensure = async args => {
+    calls.push(args);
+    return { created: true, dir: path.join(home, '.hermes/profiles', args.name), name: args.name, warnings: [] };
+  };
+  const env = {
+    HERMES_HOME: path.join(home, '.hermes/profiles/llm-wiki'),
+    AGENT_CWD: '/projects/llm-wiki',
+    AGENT_PROJECT_CONTEXT: 'LLM-Wiki agent',
+  };
+  const result = await healInstanceProfileFromEnv('llm-wiki', env, { ensureHermesProfile: ensure });
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].name, 'llm-wiki');
+  assert.equal(calls[0].workdir, '/projects/llm-wiki');
+  assert.equal(result.created, true);
+});
+
+test('healInstanceProfileFromEnv is a no-op when HERMES_HOME is unset', async () => {
+  let invoked = false;
+  const ensure = async () => { invoked = true; return null; };
+  const result = await healInstanceProfileFromEnv('llm-wiki', {}, { ensureHermesProfile: ensure });
+  assert.equal(invoked, false);
+  assert.equal(result, null);
+});

package/app-node/deferred_queue.mjs

@@ -0,0 +1,12 @@
+export function enqueueDeferredUtterance(queue, item, maxSize) {
+  const limit = Number(maxSize);
+  if (!Number.isFinite(limit) || limit <= 0) {
+    return { queued: false, dropped: item, reason: 'disabled' };
+  }
+  let dropped = null;
+  while (queue.length >= limit) {
+    dropped = queue.shift();
+  }
+  queue.push(item);
+  return { queued: true, dropped, reason: dropped ? 'replaced-oldest' : 'queued' };
+}

package/app-node/deferred_queue.test.mjs

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { enqueueDeferredUtterance } from './deferred_queue.mjs';
+
+test('enqueueDeferredUtterance drops immediately when queue is disabled', () => {
+  const queue = [];
+  const item = { text: 'do not run this later' };
+  const result = enqueueDeferredUtterance(queue, item, 0);
+  assert.deepEqual(result, { queued: false, dropped: item, reason: 'disabled' });
+  assert.deepEqual(queue, []);
+});
+
+test('enqueueDeferredUtterance keeps only latest items up to max size', () => {
+  const queue = [{ text: 'old' }];
+  const result = enqueueDeferredUtterance(queue, { text: 'new' }, 1);
+  assert.equal(result.queued, true);
+  assert.equal(result.reason, 'replaced-oldest');
+  assert.deepEqual(result.dropped, { text: 'old' });
+  assert.deepEqual(queue, [{ text: 'new' }]);
+});

package/app-node/discord_invite_cli.test.mjs

@@ -0,0 +1,31 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const CLI = path.join(ROOT, 'scripts', 'cli.mjs');
+
+test('vc bot invite prints an OAuth URL for a Discord client id', () => {
+  const result = spawnSync(process.execPath, [CLI, 'bot', 'invite', '123456789012345678'], {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Discord bot invite URL:/);
+  assert.match(result.stdout, /client_id=123456789012345678/);
+  assert.match(result.stdout, /scope=bot\+applications\.commands|scope=bot%20applications\.commands/);
+  assert.match(result.stdout, /permissions=277028604928/);
+});
+
+test('vc bot invite supports a guild id shortcut', () => {
+  const result = spawnSync(process.execPath, [CLI, 'bot', 'invite', '123456789012345678', '--guild', '987654321098765432'], {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /guild_id=987654321098765432/);
+  assert.match(result.stdout, /disable_guild_select=true/);
+});

package/app-node/discord_text.mjs

@@ -0,0 +1,29 @@
+export function splitDiscordMessage(text, maxLength = 1900) {
+  const body = String(text || '');
+  if (!body.length) return [''];
+  const chunks = [];
+  for (let i = 0; i < body.length; i += maxLength) chunks.push(body.slice(i, i + maxLength));
+  return chunks;
+}
+
+export async function sendDiscordText({ client, channelId, text, log = () => {}, warn = () => {} }) {
+  const body = String(text || '');
+  if (!channelId) {
+    warn('sendText missing transcript channel id; text not delivered', body.slice(0, 200));
+    return false;
+  }
+  try {
+    const ch = await client.channels.fetch(channelId);
+    if (!ch?.isTextBased?.()) {
+      warn('sendText target is not text based', channelId);
+      return false;
+    }
+    const chunks = splitDiscordMessage(body);
+    for (const chunk of chunks) await ch.send(chunk);
+    log('sendText delivered', 'chars', body.length, 'chunks', chunks.length);
+    return true;
+  } catch (e) {
+    warn('sendText failed', e?.stack || e);
+    return false;
+  }
+}