@pellux/goodvibes-tui 1.25.0 → 1.27.0

package/src/audio/wake-inference.ts

@@ -0,0 +1,182 @@
+/**
+ * wake-inference.ts — the terminal's inference runtime for the wake engine.
+ *
+ * The SDK engine never imports an inference runtime; it declares the shape of a
+ * session ({@link WakeInferenceSession}) and takes one from the host. This is
+ * that host half: onnxruntime-web on its WASM backend, which serves the browser
+ * tab and bun/node from the same package with no native module to build.
+ *
+ * WHY THE TWO ASSETS ARE COPIED TO DISK
+ *
+ * onnxruntime-web loads its WASM glue by DYNAMIC IMPORT of a path, and a
+ * `bun build --compile` binary cannot satisfy that: the runtime asks for
+ * `/$bunfs/root/ort-wasm-simd-threaded.mjs`, which is not something bun embeds
+ * for a dynamic path import, and session creation fails at runtime with
+ * "Cannot find module". So both assets are imported with `with { type: 'file' }`
+ * — embedded in the binary, handed to us as a path — written into a directory
+ * this surface owns, and `ort.env.wasm.wasmPaths` is pointed at that directory.
+ * The same code path runs from source, where the imports resolve to the real
+ * files in node_modules and the copy is a no-op after the first launch.
+ *
+ * The copy is content-checked, not timestamp-checked: an identical byte length
+ * and identical bytes mean the file already on disk is the one this build wants,
+ * so nothing is rewritten. A different build writes its own bytes over the top
+ * rather than trusting a stale extraction from a previous version.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as ort from 'onnxruntime-web/wasm';
+import glueAssetPath from 'onnxruntime-web/ort-wasm-simd-threaded.mjs' with { type: 'file' };
+import wasmAssetPath from 'onnxruntime-web/ort-wasm-simd-threaded.wasm' with { type: 'file' };
+import type {
+  WakeInferenceSession,
+  WakeModelHandle,
+  WakeRuntimeSettings,
+  WakeTensor,
+} from '@pellux/goodvibes-sdk/platform/voice';
+import { WakeWordEngine } from '@pellux/goodvibes-sdk/platform/voice';
+
+/**
+ * The runtime asks for its glue and its wasm by these exact names, relative to
+ * `ort.env.wasm.wasmPaths` — so the extracted copies must keep them.
+ */
+const ORT_ASSETS = [
+  { source: glueAssetPath, name: 'ort-wasm-simd-threaded.mjs' },
+  { source: wasmAssetPath, name: 'ort-wasm-simd-threaded.wasm' },
+] as const;
+
+/** Set once, before the first session is created; changing it afterwards has no effect. */
+let configuredAssetDirectory: string | null = null;
+
+/**
+ * Copy the onnxruntime-web assets into `directory` and return the value
+ * `ort.env.wasm.wasmPaths` wants — a directory prefix WITH its trailing slash,
+ * which the runtime concatenates a file name onto. Without the slash it looks
+ * for a sibling of the directory and reports a missing module.
+ */
+export function extractOnnxRuntimeAssets(directory: string): string {
+  mkdirSync(directory, { recursive: true });
+  for (const asset of ORT_ASSETS) {
+    const target = join(directory, asset.name);
+    const bytes = readFileSync(asset.source);
+    let existing: Buffer | null = null;
+    try {
+      existing = readFileSync(target);
+    } catch {
+      // Absent, or unreadable: either way it gets written below.
+    }
+    if (existing !== null && existing.equals(bytes)) continue;
+    writeFileSync(target, bytes);
+  }
+  return `${directory}/`;
+}
+
+/**
+ * Point onnxruntime-web at the extracted assets and pin its threading.
+ *
+ * `numThreads = 1` is not a conservatism: the engine costs ~3.5 ms per 80 ms
+ * frame single-threaded, comfortably inside its budget, while a threaded WASM
+ * build needs a cross-origin-isolated environment to get its workers and would
+ * spend the difference failing to start them.
+ */
+export function configureOnnxRuntime(assetDirectory: string): void {
+  if (configuredAssetDirectory === assetDirectory) return;
+  ort.env.wasm.wasmPaths = extractOnnxRuntimeAssets(assetDirectory);
+  ort.env.wasm.numThreads = 1;
+  ort.env.logLevel = 'error';
+  configuredAssetDirectory = assetDirectory;
+}
+
+/**
+ * Adapt an onnxruntime session to the SDK's session shape.
+ *
+ * The engine reads `inputNames[0]` / `outputNames[0]` rather than hard-coded
+ * names, so the pinned classifier (`onnx::Flatten_0` -> `output`) and the
+ * speech-embedding front end (`input_1` -> `embedding`) both work through this
+ * one adapter with nothing per-model here.
+ */
+export function adaptOnnxSession(session: ort.InferenceSession): WakeInferenceSession {
+  return {
+    inputNames: session.inputNames,
+    outputNames: session.outputNames,
+    async run(feeds: Readonly<Record<string, WakeTensor>>): Promise<Readonly<Record<string, WakeTensor>>> {
+      const inputs: Record<string, ort.Tensor> = {};
+      for (const [name, tensor] of Object.entries(feeds)) {
+        inputs[name] = new ort.Tensor('float32', tensor.data, [...tensor.dims]);
+      }
+      const outputs = await session.run(inputs);
+      const result: Record<string, WakeTensor> = {};
+      for (const [name, tensor] of Object.entries(outputs)) {
+        // Every tensor the wake graphs produce is float32; the cast narrows the
+        // runtime's union of typed-array data types to the one this path sees.
+        result[name] = { data: tensor.data as Float32Array, dims: [...tensor.dims] };
+      }
+      return result;
+    },
+    release: () => session.release(),
+  };
+}
+
+/** Load one .onnx file into an adapted session. */
+export async function loadWakeSession(modelPath: string): Promise<WakeInferenceSession> {
+  const bytes = readFileSync(modelPath);
+  const session = await ort.InferenceSession.create(new Uint8Array(bytes), {
+    executionProviders: ['wasm'],
+  });
+  return adaptOnnxSession(session);
+}
+
+export interface WakeEngineFactoryOptions {
+  /** Directory this surface owns for the extracted onnxruntime assets. */
+  readonly assetDirectory: string;
+  /** The provisioned speech-embedding front end. */
+  readonly embeddingPath: string;
+  /** The provisioned classifiers, in configuration order. */
+  readonly models: readonly { readonly id: string; readonly path: string }[];
+  readonly settings: Pick<WakeRuntimeSettings, 'tuning' | 'preRollMs' | 'vadThreshold'>;
+  /**
+   * The provisioned speech gate, present only when `voice.wake.vadThreshold` asks
+   * for one. Absent means the engine scores every frame, which is what the
+   * shipped default of 0 asks for — not a gate that failed to load, because that
+   * case is a startup blocker upstream of here.
+   */
+  readonly vadPath?: string;
+  /** Where a classifier that fails to run is reported (the engine skips it rather than dying). */
+  readonly warn: (message: string, meta?: Readonly<Record<string, unknown>>) => void;
+  /** Injected in tests: a stub session per path, so no real model file is read. */
+  readonly loadSession?: (modelPath: string) => Promise<WakeInferenceSession>;
+}
+
+/**
+ * Build the `createEngine` callback the SDK listener drives.
+ *
+ * The listener calls it on EVERY start including a restart, because a restart
+ * exists to recover from a runtime that died — so the sessions are created here
+ * per call rather than captured once.
+ */
+export function createWakeEngineFactory(options: WakeEngineFactoryOptions): () => Promise<WakeWordEngine> {
+  const load = options.loadSession ?? loadWakeSession;
+  return async () => {
+    if (options.loadSession === undefined) configureOnnxRuntime(options.assetDirectory);
+    const embedding = await load(options.embeddingPath);
+    const models: WakeModelHandle[] = [];
+    for (const model of options.models) {
+      models.push({ id: model.id, session: await load(model.path) });
+    }
+    // Loaded per start, like every other session here: a restart exists to
+    // recover from a runtime that died, and a gate session carried over from the
+    // dead run would be the one piece that did not recover.
+    const vad = options.vadPath !== undefined && options.settings.vadThreshold > 0
+      ? { session: await load(options.vadPath), threshold: options.settings.vadThreshold }
+      : undefined;
+    return new WakeWordEngine({
+      embedding,
+      models,
+      tuning: options.settings.tuning,
+      preRollMs: options.settings.preRollMs,
+      ...(vad !== undefined ? { vad } : {}),
+      warn: options.warn,
+    });
+  };
+}

package/src/audio/wake-runtime.ts

@@ -0,0 +1,341 @@
+/**
+ * wake-runtime.ts — wake-word detection on the terminal.
+ *
+ * The SDK owns the policy that would otherwise be rewritten per surface: the
+ * front end, the patience/cooldown rules, keeping ONE stream open across a wake
+ * so the utterance that follows is not clipped, resetting the engine afterwards
+ * so the command just spoken is not scored again, and the supervisor's restart
+ * and latch decisions. What is local is everything that touches this machine —
+ * the recorder subprocess (capture.ts), the inference runtime (wake-inference.ts),
+ * transcription over the daemon (core/voice-stt-gateway.ts), the activation sound, and
+ * the shell's indicator row.
+ *
+ * TWO THINGS ARE DELIBERATELY NOT AUTOMATIC
+ *
+ *  - **ENABLING NEVER DOWNLOADS.** The model ships with the installation, so on a
+ *    normal machine `start()` below finds the artifacts already there and needs
+ *    nothing else — that is the whole point of provisioning at install time. What
+ *    it must never do is FETCH: the check here is read-only and content-verified,
+ *    and a host whose artifacts are missing or torn gets told which and gets the
+ *    recovery command named, instead of a switch that silently pulls 6 MB. A
+ *    download is an install-time or boot-time act with a receipt; a toggle is not.
+ *  - **Disabled means no device is opened at all.** `settings.active` is the only
+ *    thing consulted before opening a microphone, and the SDK listener re-checks
+ *    it and refuses without touching the capture opener. A configuration that is
+ *    off must never produce a microphone permission prompt.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  WakeListener,
+  encodeWavPcm16,
+  resolveManagedWakePaths,
+  resolveWakeModelFiles,
+  resolveWakeRuntimeSettings,
+  retainedClipFileName,
+  utteranceToAudioArtifact,
+  wakeProvisionStatus,
+  type AudioCaptureOpener,
+  type CapturedUtterance,
+  type WakeListenerState,
+  type WakeRuntimeSettings,
+  type WakeProvisionStatus,
+  type WakeListenerOptions,
+} from '@pellux/goodvibes-sdk/platform/voice';
+import type { VoiceCaptureIndicatorState } from '../core/voice-capture-status.ts';
+import { describeWakeBlockers, describeWakeLimitations, terminalWakeCapabilities } from '../core/wake-provision-status.ts';
+import { createWakeEngineFactory } from './wake-inference.ts';
+import type { VoiceSttGateway } from '../core/voice-stt-gateway.ts';
+import { describeTranscriptionFailure } from '../core/voice-stt-gateway.ts';
+
+/** Indicator kind per listener phase. `idle`/`stopped` render nothing. */
+const PHASE_INDICATOR: Partial<Record<WakeListenerState['phase'], VoiceCaptureIndicatorState['kind']>> = {
+  starting: 'wake-listening',
+  listening: 'wake-listening',
+  'capturing-utterance': 'wake-capturing',
+  restarting: 'wake-restarting',
+  latched: 'wake-latched',
+};
+
+export interface WakeRuntimeDeps {
+  /** Reads a config key. The live subscription below watches the two enablement rows. */
+  readonly readConfig: (key: string) => unknown;
+  /** Runtime toggling: `voice.wake.enabled` and `voice.wake.surfaces.tui`. */
+  readonly subscribeConfig: (key: string, listener: () => void) => () => void;
+  readonly openCapture: AudioCaptureOpener;
+  /** Managed root the wake tree hangs off — `<managed>/wake` (SDK resolveManagedWakePaths). */
+  readonly managedRoot: string;
+  /** Directory this surface owns for the extracted onnxruntime assets. */
+  readonly assetDirectory: string;
+  /** Resolves the speech-to-text gateway, or explains why there is none. */
+  readonly resolveTranscriber: () => { readonly available: true; readonly gateway: VoiceSttGateway } | { readonly available: false; readonly reason: string };
+  /** Plays the resolved activation sound at the moment of a wake. */
+  readonly playActivationSound: (sound: WakeRuntimeSettings['activationSound']) => void;
+  /** Submits the recognised text as a turn (`voice.wake.autoSubmit` on). */
+  readonly submitTurn: (text: string) => void;
+  /** Writes the recognised text into the composer draft (`voice.wake.autoSubmit` off). */
+  readonly writeDraft: (text: string) => void;
+  readonly notify: (message: string) => void;
+  readonly render: () => void;
+  /** Names the retained clip so the SDK sweeper can reap it when this session ends. */
+  readonly sessionId: string;
+  readonly warn: (message: string, meta?: Readonly<Record<string, unknown>>) => void;
+  /** Injected in tests: a stub inference session per model path. */
+  readonly loadSession?: WakeRuntimeTestSeams['loadSession'];
+  /** Injected in tests: skips the on-disk provisioning check. */
+  readonly provisionStatus?: WakeRuntimeTestSeams['provisionStatus'];
+  /** Injected in tests: the suppression stage, without real WebAssembly. */
+  readonly createNoiseSuppression?: WakeRuntimeTestSeams['createNoiseSuppression'];
+  readonly now?: () => number;
+  readonly setTimeout?: (handler: () => void, ms: number) => unknown;
+  readonly clearTimeout?: (handle: unknown) => void;
+}
+
+/**
+ * What this runtime reads out of provisioning: whether the wake models are usable
+ * at all, and whether the SPEECH GATE's own artifact is there — they are separate
+ * answers, because `voice.wake.vadThreshold` defaults to 0 and a detector runs
+ * perfectly well with no gate provisioned.
+ */
+export interface WakeProvisionSnapshot {
+  readonly ready: boolean;
+  readonly reason: string | null;
+  readonly vadReady: boolean;
+}
+
+/** The two seams a test replaces so no model file and no runtime are needed. */
+export interface WakeRuntimeTestSeams {
+  readonly loadSession: Parameters<typeof createWakeEngineFactory>[0]['loadSession'];
+  /**
+   * Builds the suppression stage. The SDK's listener wraps the opener and defaults
+   * to the embedded speexdsp filter; a test replaces it so the WIRING is checkable
+   * without compiling WebAssembly, while the filter's numbers stay the SDK's to
+   * assert.
+   */
+  readonly createNoiseSuppression: NonNullable<WakeListenerOptions['createNoiseSuppression']>;
+  readonly provisionStatus: (managedRoot: string) => WakeProvisionSnapshot;
+}
+
+export interface WakeRuntime {
+  /**
+   * Apply the current configuration: start the detector when it should run, stop
+   * it when it should not. Called once at startup and on every change to the two
+   * enablement rows.
+   */
+  refresh(): Promise<void>;
+  /** Current indicator row, or null when nothing is listening. */
+  status(): VoiceCaptureIndicatorState | null;
+  /** The resolved settings, for a status surface. */
+  settings(): WakeRuntimeSettings;
+  /** Stop and release the device. Registered in the shell's teardown registry. */
+  stop(): Promise<void>;
+}
+
+/** Wire wake detection. Nothing is opened until `refresh()` finds it active. */
+/**
+ * Provisioning state for the capability read. Shares the injected seam `start`
+ * uses, so a test drives both from one stub, and is read per call rather than
+ * cached: a user provisions the speech gate while the session is running, and a
+ * snapshot taken at startup would keep reporting it unavailable afterwards.
+ */
+function provisionStatusFor(deps: WakeRuntimeDeps): WakeProvisionSnapshot {
+  return (deps.provisionStatus ?? ((root: string) => wakeProvisionStatus({ managedRoot: root })))(deps.managedRoot);
+}
+
+export function wireWakeRuntime(deps: WakeRuntimeDeps): WakeRuntime {
+  let listener: WakeListener | null = null;
+  let phase: WakeListenerState['phase'] = 'idle';
+  let deviceLabel: string | null = null;
+  let detail: string | undefined;
+
+  const resolve = (): WakeRuntimeSettings => resolveWakeRuntimeSettings(
+    deps.readConfig,
+    'tui',
+    terminalWakeCapabilities(provisionStatusFor(deps)),
+  );
+
+  const status = (): VoiceCaptureIndicatorState | null => {
+    const kind = PHASE_INDICATOR[phase];
+    if (kind === undefined) return null;
+    return { kind, deviceLabel, indicator: resolve().indicator, ...(detail !== undefined ? { detail } : {}) };
+  };
+
+  const retainClip = (utterance: CapturedUtterance): void => {
+    const retainedDir = resolveManagedWakePaths(deps.managedRoot).retainedDir;
+    try {
+      mkdirSync(retainedDir, { recursive: true });
+      // The SDK owns the filename, and it is load-bearing rather than cosmetic: the
+      // recovery sweeper reads the owning session id from the first `--`-delimited
+      // segment, so a name invented here would get a live session's clips reaped as
+      // orphans (or leave them unreaped forever).
+      const target = join(retainedDir, retainedClipFileName(deps.sessionId, (deps.now ?? Date.now)()));
+      writeFileSync(target, encodeWavPcm16(utterance.samples, utterance.sampleRate));
+    } catch (error) {
+      deps.warn('retaining the wake clip failed', { error: error instanceof Error ? error.message : String(error) });
+    }
+  };
+
+  const transcribeUtterance = async (utterance: CapturedUtterance, settings: WakeRuntimeSettings): Promise<void> => {
+    if (settings.retainAudio === 'session-temp') retainClip(utterance);
+    if (utterance.silent) {
+      deps.notify('[Wake] Heard the wake phrase but nothing above the silence floor followed it.');
+      deps.render();
+      return;
+    }
+    const resolution = deps.resolveTranscriber();
+    if (!resolution.available) {
+      deps.notify(`[Wake] Captured the utterance after the wake phrase but could not transcribe it: ${resolution.reason}`);
+      deps.render();
+      return;
+    }
+    try {
+      const text = (await resolution.gateway.transcribe(utteranceToAudioArtifact(utterance))).trim();
+      if (text.length === 0) {
+        deps.notify('[Wake] Speech-to-text returned no words for what followed the wake phrase.');
+        deps.render();
+        return;
+      }
+      if (settings.autoSubmit) deps.submitTurn(text);
+      else {
+        deps.writeDraft(text);
+        deps.notify('[Wake] Transcript placed in the composer (voice.wake.autoSubmit is off — press Enter to send it).');
+        deps.render();
+      }
+    } catch (error) {
+      deps.notify(`[Wake] Transcription failed: ${describeTranscriptionFailure(error)}`);
+      deps.render();
+    }
+  };
+
+  const start = async (settings: WakeRuntimeSettings): Promise<void> => {
+    const provision = provisionStatusFor(deps);
+    if (!provision.ready) {
+      deps.notify(
+        `[Wake] voice.wake.enabled is on, but the wake models are not provisioned (${provision.reason ?? 'not-provisioned'}), `
+        + 'so nothing is listening. Installing goodvibes provisions them and a running daemon retries at boot, so this '
+        + 'means the download has not succeeded yet — run /voice wake setup to fetch and verify them now.',
+      );
+      deps.render();
+      return;
+    }
+    const paths = resolveManagedWakePaths(deps.managedRoot);
+    // The SDK resolves `voice.wake.models` to files: the pinned id inside the
+    // managed tree, any other id against voice.wake.customModelDir — and when that
+    // row is empty, against the managed `custom` directory, which is the fallback
+    // the row's description promises and the one a host would otherwise get wrong
+    // by looking in the process's working directory.
+    const modelFiles = resolveWakeModelFiles(settings.modelIds, {
+      managedRoot: deps.managedRoot,
+      customModelDir: settings.customModelDir,
+    });
+    const unpinned = modelFiles.filter((model) => !model.pinned);
+    if (unpinned.length > 0) {
+      // Worth saying out loud: these bytes were never checksum-verified.
+      deps.notify(`[Wake] Loading ${unpinned.length} custom model${unpinned.length === 1 ? '' : 's'} that ${unpinned.length === 1 ? 'is' : 'are'} not checksum-pinned: ${unpinned.map((model) => `${model.id} (${model.path})`).join(', ')}`);
+    }
+    const active = new WakeListener({
+      settings,
+      openCapture: deps.openCapture,
+      ...(deps.createNoiseSuppression !== undefined ? { createNoiseSuppression: deps.createNoiseSuppression } : {}),
+      createEngine: createWakeEngineFactory({
+        assetDirectory: deps.assetDirectory,
+        embeddingPath: paths.embeddingPath,
+        models: modelFiles.map((model) => ({ id: model.id, path: model.path })),
+        settings,
+        // The speech gate, when the row asks for one. `voice.wake.vadThreshold`
+        // above 0 with the artifact missing never reaches here — it is a blocker
+        // from resolveWakeRuntimeSettings, so the detector does not start at all
+        // rather than starting with the gate quietly absent.
+        ...(settings.vadThreshold > 0 ? { vadPath: paths.vadPath } : {}),
+        warn: deps.warn,
+        ...(deps.loadSession !== undefined ? { loadSession: deps.loadSession } : {}),
+      }),
+      handlers: {
+        onStateChange: (state) => {
+          phase = state.phase;
+          deviceLabel = state.deviceLabel;
+          if (state.phase === 'latched') detail = state.latchReason ?? undefined;
+          deps.render();
+        },
+        onWake: (event) => {
+          deps.playActivationSound(event.activationSound);
+          deps.render();
+        },
+        onUtterance: (utterance) => { void transcribeUtterance(utterance, settings); },
+        onFailure: (error, restarting, failureDetail) => {
+          detail = failureDetail;
+          // Reported to the user, not only logged: a detector that stopped
+          // listening is exactly the thing a silent log entry hides.
+          deps.notify(restarting
+            ? `[Wake] The capture stream ended (${error.message}) — ${failureDetail}.`
+            : `[Wake] The wake-word detector stopped: ${failureDetail}. It stays off until voice.wake.enabled is turned off and on again.`);
+          deps.render();
+        },
+      },
+      warn: deps.warn,
+      ...(deps.now !== undefined ? { now: deps.now } : {}),
+      ...(deps.setTimeout !== undefined ? { setTimeout: deps.setTimeout } : {}),
+      ...(deps.clearTimeout !== undefined ? { clearTimeout: deps.clearTimeout } : {}),
+    });
+    listener = active;
+    const outcome = await active.start();
+    if (!outcome.started) {
+      listener = null;
+      phase = 'idle';
+      deps.notify(`[Wake] The wake-word detector did not start (${outcome.refusal}): ${outcome.detail}`);
+    } else {
+      const limitations = describeWakeLimitations(settings);
+      if (limitations.length > 0) {
+        deps.notify([`[Wake] Listening on ${outcome.deviceLabel}, with these rows not in force:`, ...limitations].join('\n'));
+      }
+    }
+    deps.render();
+  };
+
+  const stop = async (): Promise<void> => {
+    const active = listener;
+    listener = null;
+    phase = 'idle';
+    deviceLabel = null;
+    detail = undefined;
+    if (active !== null) await active.stop();
+  };
+
+  return {
+    refresh: async () => {
+      const settings = resolve();
+      if (!settings.active) {
+        await stop();
+        if (settings.enabled && settings.surfaceEnabled && settings.blockers.length > 0) {
+          // Blocked, not off: the user asked for this and is owed the reason.
+          deps.notify(['[Wake] The wake-word detector cannot start:', ...describeWakeBlockers(settings)].join('\n'));
+        }
+        deps.render();
+        return;
+      }
+      if (listener !== null) return;
+      await start(settings);
+    },
+    status,
+    settings: resolve,
+    stop,
+  };
+}
+
+/**
+ * Subscribe to the two rows that turn detection on and off at runtime, and apply
+ * the current configuration once. Returns the unsubscribers for the shell's
+ * teardown registry, plus a final release so a live recorder subprocess cannot
+ * outlive the process on any exit path.
+ */
+export function startWakeRuntime(runtime: WakeRuntime, deps: Pick<WakeRuntimeDeps, 'subscribeConfig'>): readonly (() => void)[] {
+  const apply = (): void => { void runtime.refresh(); };
+  const unsubs = [
+    deps.subscribeConfig('voice.wake.enabled', apply),
+    deps.subscribeConfig('voice.wake.surfaces.tui', apply),
+    () => { void runtime.stop(); },
+  ];
+  apply();
+  return unsubs;
+}

package/src/cli/bundle-command.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { RuntimeEventBus } from '@/runtime/index.ts';
+import { RuntimeEventBus, configureRuntimeEventBusDefaults, runtimeEventBusOptionsFrom } from '@/runtime/index.ts';
 import { createShellPathService } from '@/runtime/index.ts';
 import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers';
 import { createRuntimeServices } from '../runtime/services.ts';
@@ -83,6 +83,9 @@ function readAuthPosture(runtime: CliCommandRuntime) {
 }
 
 async function buildProviderReadiness(runtime: CliCommandRuntime) {
+  // Point the bus listener cap at runtime.eventBus.maxListeners before the
+  // first bus exists, so every bus this process builds later uses it.
+  configureRuntimeEventBusDefaults(runtimeEventBusOptionsFrom((key) => runtime.configManager.get(key)));
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
   const services = createRuntimeServices({

package/src/cli/help.ts

@@ -341,6 +341,16 @@ export function renderGoodVibesDaemonHelp(binary = 'goodvibes-daemon'): string {
     '  service-status                 Show whether the daemon service is installed / enabled / active',
     '  migrate-service                Guided migration from an install-script goodvibes-daemon.service unit; prints a plan',
     '                                 unless run with -y/--yes (never auto-migrates)',
+    '  send [message]                 Send a message to one of your configured channels — Telegram, ntfy,',
+    '                                 Discord, Slack, Google Chat, Signal, WhatsApp, iMessage, Teams,',
+    '                                 BlueBubbles, Mattermost, Matrix or a webhook. Takes the message as',
+    '                                 an argument or on stdin, so it composes with other tooling.',
+    '                                 --channel <id> picks the channel; with none named it uses your one',
+    '                                 configured channel and says which. --to <address> targets a specific',
+    '                                 topic / chat / room within it, --title <text> sets a title, and',
+    '                                 --list shows every channel with where it would send. A channel that',
+    '                                 is off is refused rather than redirected to the default, and a',
+    '                                 failed send exits non-zero with the provider\'s own error.',
     '  cluster <command>              Share inbound channel work with your other machines on this network.',
     '                                 status | create | join | key | nodes | forget <machine> | rotate [--now]',
     '                                 | leave | rename | groups',

package/src/cli/management-utils.ts

@@ -24,7 +24,7 @@ import { refreshMemoryRecallSnapshot } from '../runtime/orchestrator-core-servic
 import { createRuntimeServices } from '../runtime/services.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
 import type { RuntimeServices } from '../runtime/services.ts';
-import { RuntimeEventBus, type TurnEvent, createShellPathService } from '@/runtime/index.ts';
+import { RuntimeEventBus, type TurnEvent, createShellPathService, configureRuntimeEventBusDefaults, runtimeEventBusOptionsFrom } from '@/runtime/index.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { applyRuntimeEndpointFlagOverrides } from './config-overrides.ts';
@@ -225,6 +225,9 @@ export async function withRuntimeServices<T>(
   runtime: CliCommandRuntime,
   fn: (services: RuntimeServices) => Promise<T> | T,
 ): Promise<T> {
+  // Point the bus listener cap at runtime.eventBus.maxListeners before the
+  // first bus exists, so every bus this process builds later uses it.
+  configureRuntimeEventBusDefaults(runtimeEventBusOptionsFrom((key) => runtime.configManager.get(key)));
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
   const services = createRuntimeServices({