@pellux/goodvibes-tui 1.26.0 → 1.27.0

package/src/core/voice-stt-gateway.ts

@@ -0,0 +1,75 @@
+/**
+ * voice-stt-gateway.ts — speech-to-text for captured audio.
+ *
+ * Both voice consumers end here: push-to-talk hands over what the user just
+ * said, and a confirmed wake hands over the utterance that followed it. The
+ * transcription itself is the daemon's, not this process's — `voice.stt`
+ * (POST /api/voice/stt) transcribes an audio artifact through whichever voice
+ * provider is registered, including the managed local whisper that
+ * `/voice setup` provisions.
+ *
+ * The verb has no named facade on the in-process OperatorClient, so it goes over
+ * the generic operator invoke path exactly like the voice PROVISIONING verbs do
+ * (see core/voice-provision-gateway.ts) — same daemon, same resolution, same
+ * honest refusal reasons up front rather than a throw mid-capture.
+ */
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { GoodVibesSdkError } from '@pellux/goodvibes-sdk';
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+import type { UtteranceAudioArtifact } from '@pellux/goodvibes-sdk/platform/voice';
+import { resolveOperatorRpc, describeOperatorRpcError } from '../input/commands/operator-rpc.ts';
+
+/** voice.stt output — the recognised text plus the provider that produced it. */
+export type VoiceTranscriptionResult = OperatorMethodOutput<'voice.stt'>;
+
+/** The narrow verb surface a capture consumer needs. */
+export interface VoiceSttGateway {
+  /** Transcribe one captured utterance; resolves to the recognised text. */
+  transcribe(audio: UtteranceAudioArtifact): Promise<string>;
+}
+
+/**
+ * Why transcription is unavailable, surfaced verbatim so a capture path prints
+ * the daemon's reason instead of inventing one.
+ */
+export type VoiceSttGatewayResolution =
+  | { readonly available: true; readonly gateway: VoiceSttGateway }
+  | { readonly available: false; readonly reason: string };
+
+export interface VoiceSttGatewayDeps {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+}
+
+/** Build the live speech-to-text gateway, or say why there is none. */
+export function createVoiceSttGateway(deps: VoiceSttGatewayDeps): VoiceSttGatewayResolution {
+  const rpc = resolveOperatorRpc({ configManager: deps.configManager, homeDirectory: deps.homeDirectory });
+  if (!rpc.available) return { available: false, reason: rpc.reason };
+  const { sdk } = rpc;
+  return {
+    available: true,
+    gateway: {
+      transcribe: async (audio) => {
+        // The generic invoke widens to `unknown` for this verb; the cast names the
+        // contract's own output type rather than inventing a local shape, so a
+        // contract change surfaces here as a type error.
+        const result = await sdk.operator.invoke('voice.stt', { audio }) as VoiceTranscriptionResult;
+        return result.text;
+      },
+    },
+  };
+}
+
+/**
+ * Render a `voice.stt` rejection honestly. A 501 (the verb is cataloged but this
+ * daemon has no voice provider wired behind it) and a 404 (an older daemon
+ * without the route) are both "no transcription here" — distinct from a request
+ * that reached a provider and failed, which the user can act on differently.
+ */
+export function describeTranscriptionFailure(error: unknown): string {
+  if (error instanceof GoodVibesSdkError && (error.status === 501 || error.status === 404)) {
+    return 'this daemon has no speech-to-text provider wired up — run /voice setup to provision the managed local runtime.';
+  }
+  return describeOperatorRpcError(error);
+}

package/src/core/wake-provision-runner.ts

@@ -0,0 +1,86 @@
+// ---------------------------------------------------------------------------
+// wake-provision-runner.ts — what `/voice wake status` and `/voice wake setup` do.
+//
+// `/voice wake setup` IS NO LONGER HOW THE MODEL ARRIVES. It used to be the only
+// way, and the result was that installing goodvibes produced a wake-word feature
+// that could not start until the user went and found a command nobody had told
+// them about. The installer and the npm postinstall provision the model now, and
+// a daemon retries at boot whatever the install could not fetch (the SDK's
+// voice/wake/install-provision.ts owns that policy).
+//
+// So what this command is FOR, on a normal machine, is recovery and
+// re-provisioning: an install that was offline, an artifact that stopped
+// verifying, or a re-fetch after the pinned model changes. It still works
+// exactly as it did, which is the point — the degraded path an offline install
+// falls back to is this one.
+//
+// What has NOT changed is the runtime rule. Nothing in this path downloads on its
+// own: `/voice wake status` only reads what is on disk (verifying by content,
+// never by existence), and a download happens only because the user typed
+// `setup`. Turning `voice.wake.enabled` on never fetches anything either — see
+// audio/wake-runtime.ts, which reports what is missing and names this command.
+//
+// Both SDK calls are injectable so a wire test drives the whole flow — a fresh
+// host, a corrupt artifact, a failed component — with no network and no files.
+// ---------------------------------------------------------------------------
+
+import {
+  provisionWakeWordModels,
+  wakeProvisionStatus,
+  type WakeProvisionProgress,
+  type WakeProvisionResult,
+  type WakeProvisionStatus,
+  type WakeRuntimeSettings,
+} from '@pellux/goodvibes-sdk/platform/voice';
+import {
+  WAKE_SETUP_ANNOUNCEMENT,
+  wakeProvisionReceiptLines,
+  wakeStatusLines,
+} from './wake-provision-status.ts';
+
+export interface WakeProvisionRunnerDeps {
+  /** Managed root the wake tree hangs off; `<managedRoot>/wake` holds the artifacts. */
+  readonly managedRoot: string;
+  /** Already-resolved `voice.wake.*` rows, so the status block reports the live posture. */
+  readonly settings: WakeRuntimeSettings;
+  readonly print: (block: string) => void;
+  /** Injected in tests; defaults to the SDK's content-verifying read. */
+  readonly readStatus?: (managedRoot: string) => WakeProvisionStatus;
+  /** Injected in tests; defaults to the SDK's checksum-pinned download. */
+  readonly provision?: (
+    managedRoot: string,
+    onProgress: (progress: WakeProvisionProgress) => void,
+  ) => Promise<WakeProvisionResult>;
+}
+
+/** Print the honest on-disk + configured posture. Reads only; never downloads. */
+export function printWakeStatus(deps: WakeProvisionRunnerDeps): void {
+  const read = deps.readStatus ?? ((managedRoot: string) => wakeProvisionStatus({ managedRoot }));
+  deps.print(['Wake-Word Detection', ...wakeStatusLines(read(deps.managedRoot), deps.settings)].join('\n'));
+}
+
+/**
+ * Run the provision, narrating each artifact as its phase advances, then print
+ * the receipt. A component that fails is named in the receipt with its "got X,
+ * want Y" reason rather than folded into an overall failure.
+ */
+export async function runWakeProvision(deps: WakeProvisionRunnerDeps): Promise<void> {
+  const provision = deps.provision
+    ?? ((managedRoot: string, onProgress: (progress: WakeProvisionProgress) => void) =>
+      provisionWakeWordModels({ managedRoot, onProgress }));
+  deps.print(WAKE_SETUP_ANNOUNCEMENT);
+  // One line per phase CHANGE, so a slow download does not repeat itself.
+  const lastPhase = new Map<string, string>();
+  const onProgress = (progress: WakeProvisionProgress): void => {
+    if (lastPhase.get(progress.component) === progress.phase) return;
+    lastPhase.set(progress.component, progress.phase);
+    const extra = progress.message !== undefined ? ` — ${progress.message}` : '';
+    deps.print(`  ${progress.component}: ${progress.phase}${extra}`);
+  };
+  try {
+    const result = await provision(deps.managedRoot, onProgress);
+    deps.print(['Wake-Word Setup — receipt', ...wakeProvisionReceiptLines(result)].join('\n'));
+  } catch (error) {
+    deps.print(`Wake-Word Setup\n  provisioning failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/core/wake-provision-status.ts

@@ -0,0 +1,170 @@
+// ---------------------------------------------------------------------------
+// wake-provision-status.ts — the surface-facing projection of wake-word
+// provisioning and of the rows that are or are not in force.
+//
+// The wake models are checksum-pinned and arrive WITH THE INSTALLATION: the
+// installer and the npm postinstall provision them, and a daemon retries at boot
+// whatever the install could not fetch. `/voice wake setup` is the recovery act
+// for the case where that did not land, not the normal way in — so the lines
+// below name it where it helps and do not imply it is a required step.
+//
+// This module is the read-only projection the /voice wake surfaces render from:
+// per-artifact present / verified / corrupt / bytes taken straight from the SDK's
+// wakeProvisionStatus, which verifies by CONTENT rather than by existence — a
+// truncated or wrong-asset file reports corrupt instead of present, because a
+// detector loading it would fail in a way the user could not diagnose.
+//
+// Pure formatting only (no I/O), mirroring voice-provision-status.ts: the command
+// layer fetches the status and hands it here, so these builders are testable
+// against fixture shapes.
+// ---------------------------------------------------------------------------
+
+import type {
+  WakeArtifactStatus,
+  WakeProvisionResult,
+  WakeProvisionStatus,
+  WakeRuntimeSettings,
+  WakeSurfaceCapabilities,
+} from '@pellux/goodvibes-sdk/platform/voice';
+import { noiseSuppressionSupport } from '@pellux/goodvibes-sdk/platform/voice/capture';
+import { formatVoiceBytes } from './voice-provision-status.ts';
+
+/**
+ * What a terminal can actually do, so a `voice.wake.*` row is refused or reported
+ * rather than faked. Lives here — beside the status projection and away from the
+ * inference runtime — so the command layer can resolve settings without pulling
+ * onnxruntime into a `/voice wake status` call.
+ */
+export function terminalWakeCapabilities(status?: Pick<WakeProvisionStatus, 'vadReady'>): WakeSurfaceCapabilities {
+  return {
+    // Asked of the SDK rather than declared here. The filter is a WebAssembly
+    // module carried in the package, so the only question is whether this runtime
+    // has WebAssembly at all — which the SDK answers, with a reason a settings
+    // surface can show. A host constant would go stale the moment the stage
+    // shipped, which is exactly what happened to the previous one.
+    speexAvailable: noiseSuppressionSupport().supported,
+    // The speech gate needs its own provisioned model, so this follows what is
+    // VERIFIED ON DISK rather than what the build is capable of: with the artifact
+    // missing, `voice.wake.vadThreshold` above 0 still blocks startup and says so.
+    vadAvailable: status?.vadReady === true,
+    // A terminal has a filesystem (retainAudio) and an audio player (a custom
+    // activation sound file).
+    canRetainAudio: true,
+    canPlayLocalFile: true,
+  };
+}
+
+/** One artifact's line: what is on disk, verified by content. */
+export function wakeArtifactLine(label: string, artifact: WakeArtifactStatus): string {
+  if (artifact.verified) return `  ${label}: verified (${formatVoiceBytes(artifact.bytes)})`;
+  if (artifact.corrupt) {
+    return `  ${label}: PRESENT BUT FAILS VERIFICATION (${formatVoiceBytes(artifact.bytes)}) — torn, truncated, or the wrong asset; /voice wake setup replaces it`;
+  }
+  return `  ${label}: missing`;
+}
+
+/**
+ * Blockers, in the SDK's own words. A blocker means the detector must NOT start,
+ * so the row's key and the written reason are both shown — a swallowed blocker is
+ * a user staring at a feature that is on and doing nothing.
+ */
+export function describeWakeBlockers(settings: Pick<WakeRuntimeSettings, 'blockers'>): string[] {
+  return settings.blockers.map((blocker) => `  ${blocker.key}: ${blocker.detail}`);
+}
+
+/** Limitations: the detector runs, with one row not in force, and says which. */
+export function describeWakeLimitations(settings: Pick<WakeRuntimeSettings, 'limitations'>): string[] {
+  return settings.limitations.map((limitation) => `  ${limitation.key}: ${limitation.detail}`);
+}
+
+/** The `/voice wake status` block. */
+export function wakeStatusLines(
+  status: WakeProvisionStatus,
+  settings: WakeRuntimeSettings,
+): string[] {
+  const lines: string[] = [
+    `  feature: voice.wake.enabled=${settings.enabled ? 'on' : 'off'}, voice.wake.surfaces.tui=${settings.surfaceEnabled ? 'on' : 'off'}`,
+    `  listening on this terminal: ${settings.active ? 'yes, when the models are provisioned' : 'no'}`,
+    `  models provisioned: ${status.ready ? 'yes' : `no (${status.reason ?? 'not-provisioned'})`}`,
+    `  model version: ${status.modelVersion ?? 'unpinned'}`,
+    wakeArtifactLine('classifier', status.classifier),
+    wakeArtifactLine('speech-embedding front end', status.embedding),
+    // One NOTICE per redistributable artifact, named so it is obvious which is
+    // which: both are required, and a reader chasing a missing one needs to know
+    // whether it is ours or Google's.
+    wakeArtifactLine('attribution NOTICE (classifier)', status.notice),
+    wakeArtifactLine('attribution NOTICE (front end)', status.embeddingNotice),
+    // Reported but never presented as a problem: nothing on this terminal loads
+    // it, and it is here so a surface can see whether the daemon could serve it.
+    `${wakeArtifactLine('classifier, tflite form (served to other runtimes; unused here)', status.mobileClassifier)}`,
+    // The speech gate reports separately from `models provisioned` for the same
+    // reason it is outside the SDK's `ready`: voice.wake.vadThreshold is 0 unless
+    // someone turns it on, so a missing gate is not a broken detector. It is
+    // printed rather than left out because vadThreshold above 0 refuses to start
+    // when the gate is absent, and a reader needs to see why.
+    `  speech gate provisioned: ${status.vadReady ? 'yes' : 'no — voice.wake.vadThreshold above 0 will refuse to start'}`,
+    wakeArtifactLine('speech gate', status.vad),
+    wakeArtifactLine('attribution NOTICE (speech gate)', status.vadNotice),
+  ];
+  if (!status.ready) {
+    lines.push(
+      `  a fresh provision would download ${formatVoiceBytes(status.downloadBytes)}. Installing goodvibes normally does this,`,
+      '  and a running daemon retries at boot — run /voice wake setup to fetch it now (nothing downloads on its own).',
+    );
+  }
+  lines.push(
+    `  wake models configured: ${settings.modelIds.length > 0 ? settings.modelIds.join(', ') : 'none (voice.wake.models is empty, so nothing is scored)'}`,
+    `  recorder: voice.wake.captureCommand=${settings.capture.backend}, device=${settings.capture.device.trim().length > 0 ? settings.capture.device : 'system default'}`,
+    `  after a wake: ${settings.autoSubmit ? 'the transcript is submitted as a turn' : 'the transcript is placed in the composer'}`,
+    `  indicator: voice.wake.indicator=${settings.indicator}, activation sound=${settings.activationSound.kind}`,
+    `  retained audio: voice.wake.retainAudio=${settings.retainAudio}`,
+  );
+  if (status.recallIsSyntheticOnly) {
+    lines.push('  the published recall figures for this model are measured on synthesised speech only — no human recording of the phrase exists behind them.');
+  }
+  const blockers = describeWakeBlockers(settings);
+  if (blockers.length > 0) lines.push('  rows blocking startup:', ...blockers);
+  const limitations = describeWakeLimitations(settings);
+  if (limitations.length > 0) lines.push('  rows not in force:', ...limitations);
+  return lines;
+}
+
+/** The `/voice wake setup` receipt. */
+export function wakeProvisionReceiptLines(result: WakeProvisionResult): string[] {
+  const lines = [
+    `  ready: ${result.ready ? 'yes' : 'no'}`,
+    `  model version: ${result.modelVersion ?? 'unpinned'}`,
+    // Separate from `ready` on purpose: this terminal loads the onnx build, so a
+    // missing tflite twin is not a detector that cannot run.
+    `  tflite form (for runtimes that cannot load onnx): ${result.mobileFormatReady ? 'installed' : 'not installed — nothing on this terminal needs it'}`,
+    // Separate from `ready` for its own reason: voice.wake.vadThreshold ships at
+    // 0, so the detector runs without the gate — but a value above 0 refuses to
+    // start without it, which is what this line lets a reader act on.
+    `  speech gate (voice.wake.vadThreshold): ${result.vadReady ? 'installed' : 'not installed — voice.wake.vadThreshold above 0 will refuse to start'}`,
+  ];
+  for (const outcome of result.outcomes) {
+    const detail = outcome.state === 'failed'
+      ? ` — ${outcome.error ?? 'no reason reported'}`
+      : outcome.bytes !== undefined ? ` (${formatVoiceBytes(outcome.bytes)})` : '';
+    lines.push(`  ${outcome.component}: ${outcome.state}${detail}`);
+    lines.push(`    ${outcome.path}`);
+  }
+  if (result.noticePath !== null) {
+    lines.push(`  attribution NOTICE (travels with the classifier): ${result.noticePath}`);
+  }
+  if (result.embeddingNoticePath !== null) {
+    lines.push(`  attribution NOTICE (travels with the front end): ${result.embeddingNoticePath}`);
+  }
+  if (result.recallIsSyntheticOnly) {
+    lines.push('  the published recall figures for this model are measured on synthesised speech only — no human recording of the phrase exists behind them.');
+  }
+  return lines;
+}
+
+/** The one-line announcement printed before a (multi-megabyte) provision runs. */
+export const WAKE_SETUP_ANNOUNCEMENT = [
+  'Wake-Word Setup',
+  '  downloading the pinned "hey goodvibes" classifier (both runtime formats), the shared speech-embedding front end, and the speech gate voice.wake.vadThreshold runs…',
+  '  every artifact is checksum-verified and the download is resumable — one that already matches is skipped, so re-running this only fetches what is missing.',
+  '  installing goodvibes normally does this for you; running it by hand is how you recover an install that could not reach the network.',
+].join('\n');

package/src/daemon/cli.ts

@@ -8,10 +8,11 @@ import {
 import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
 import { formatProviderModel, getModelIdFromProviderModel, getProviderIdFromModel } from '../config/provider-model.ts';
 import { resolveGoodVibesHomeOwnership } from '../config/goodvibes-home.ts';
-import { RuntimeEventBus, GlobalNetworkTransportInstaller } from '@/runtime/index.ts';
+import { RuntimeEventBus, GlobalNetworkTransportInstaller, configureRuntimeEventBusDefaults, runtimeEventBusOptionsFrom } from '@/runtime/index.ts';
 import { bindFeatureSettingsBridge, createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
 import { createRuntimeServices } from '../runtime/services.ts';
+import { startDeviceHousekeeping } from '../runtime/device-posture-composition.ts';
 import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
 import { createHostPowerSeam } from '@pellux/goodvibes-sdk/platform/power';
 import { flushActivityLogSync, logger } from '@pellux/goodvibes-sdk/platform/utils';
@@ -34,6 +35,7 @@ import {
   persistProviders,
 } from '@pellux/goodvibes-sdk/platform/discovery';
 import { createSafeHostServeFactory } from './safe-serve.ts';
+import { runProvisionWakeModelCommand } from './provision-wake-model.ts';
 import { runSendCommand } from './send/command.ts';
 import { createSendStack } from './send/composition.ts';
 import { readAllStdin } from './send/stdin.ts';
@@ -181,6 +183,25 @@ async function main(): Promise<void> {
     process.exit(result.exitCode);
   }
 
+  // `provision-wake-model …` is intercepted here for the same two reasons, plus
+  // its own: the curl installer runs it on the binary it has just placed, before
+  // any daemon exists, and it must reach the SDK's pinned manifest rather than
+  // have install.sh carry a second copy of the pins. It composes no runtime — it
+  // resolves a home directory, derives the managed voice root the running daemon
+  // uses, and calls one SDK function. See provision-wake-model.ts for why it
+  // exits 0 on a failed download.
+  if (rawArgs[0] === 'provision-wake-model') {
+    const ownership = resolveDaemonCliOwnership();
+    const result = await runProvisionWakeModelCommand(rawArgs.slice(1), {
+      homeDirectory: ownership.homeDirectory,
+    });
+    for (const line of result.lines) {
+      // eslint-disable-next-line no-console
+      console.log(line);
+    }
+    process.exit(result.exitCode);
+  }
+
   // Parse CLI flags first so --daemon-home and --working-dir env vars are set
   // before resolveDaemonCliOwnership() reads them.
   const cli = parseGoodVibesCli(process.argv.slice(2), 'goodvibes-daemon');
@@ -343,6 +364,9 @@ async function main(): Promise<void> {
     }
   }
 
+  // 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) => config.get(key)));
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
   // Gate states derive from the domain settings keys; the bridge keeps live
@@ -374,6 +398,13 @@ async function main(): Promise<void> {
     // the non-spawning unavailable seam; only daemon compositions opt in. Mirrors
     // the SDK daemon cli's createHostPowerSeam() (sdk commit 3a5ea26d).
     powerSeam: createHostPowerSeam(),
+    // The wake-word model ships with the installation, and this is the retry: at
+    // every daemon start, sweep the managed wake tree and fetch whatever the
+    // install could not (an offline install, a killed download, a changed pin).
+    // It never blocks startup and never fails it — see the SDK's
+    // voice/wake/install-provision.ts. The webui reads the model bytes from THIS
+    // process, so a provisioned daemon is what makes the browser path work too.
+    provisionWakeModelsAtBoot: true,
   });
 
   // Load persisted providers from disk so the provider registry is pre-populated
@@ -460,6 +491,12 @@ async function main(): Promise<void> {
   // box that has been off for months re-keys itself with no operator action.
   await runtimeServices.startCluster();
 
+  // Grants and captures from paired phones outlive a restart, so the recovery
+  // sweep runs before this daemon serves its first request and the periodic one
+  // keeps a long-running daemon from going days without a sweep. The stop is
+  // registered with the disposal scope, so shutdown clears the timer.
+  startDeviceHousekeeping(runtimeServices.devicePosture);
+
   await Promise.all([
     daemon.start(),
     config.get('danger.httpListener') ? listener.start() : Promise.resolve(),

package/src/daemon/provision-wake-model.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// provision-wake-model.ts — `goodvibes-daemon provision-wake-model`.
+//
+// WHAT THIS IS FOR
+//
+// The curl installer needs to put the wake-word model on the machine, and it must
+// not hold the pinned URLs, byte counts or checksums to do it. Those live in ONE
+// place — the SDK's wake-word manifest — and a shell script that copied them
+// would be a second copy of a pin, drifting silently the first time the model is
+// retrained. So the installer runs the binary it just installed and lets the SDK
+// do what the SDK owns.
+//
+// IT EXITS 0 EVEN WHEN THE DOWNLOAD FAILS, ON PURPOSE
+//
+// The caller is an installer. A wake-word model is not a reason to fail installing
+// a coding tool, and an installer that aborts half-way through is worse than one
+// that finishes without a wake word. The outcome is printed either way — one plain
+// line naming what happened and how to retry — and a running daemon retries at
+// every boot. `--strict` is there for a caller that genuinely wants the exit code
+// to carry the result (a test, a provisioning script that is checking); the
+// installer does not pass it.
+//
+// It composes NOTHING. No runtime, no config manager, no gateway: this reads a
+// home directory, derives the managed voice root the same way the running daemon
+// does, and calls one SDK function. Composing a runtime here would start a second
+// set of pollers on a machine whose daemon is probably already running.
+// ---------------------------------------------------------------------------
+
+import {
+  provisionWakeWordModelsAtInstall,
+  resolveManagedVoiceRoot,
+} from '@pellux/goodvibes-sdk/platform/voice';
+
+export interface ProvisionWakeModelResult {
+  readonly exitCode: number;
+  readonly lines: readonly string[];
+}
+
+export interface ProvisionWakeModelDeps {
+  /** The home directory whose `.goodvibes/voice` tree receives the artifacts. */
+  readonly homeDirectory: string;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** Injected in tests: the SDK policy, so nothing downloads. */
+  readonly provisionAtInstall?: typeof provisionWakeWordModelsAtInstall | undefined;
+}
+
+/**
+ * Run the install-time provision and report it.
+ *
+ * `--strict` makes a degraded outcome exit 1. Without it, every outcome exits 0,
+ * because the caller is an installer and the alternative is an aborted install
+ * over an optional model.
+ */
+export async function runProvisionWakeModelCommand(
+  argv: readonly string[],
+  deps: ProvisionWakeModelDeps,
+): Promise<ProvisionWakeModelResult> {
+  const strict = argv.includes('--strict');
+  const provision = deps.provisionAtInstall ?? provisionWakeWordModelsAtInstall;
+  let managedRoot: string;
+  try {
+    managedRoot = resolveManagedVoiceRoot(deps.homeDirectory);
+  } catch (error) {
+    // A home directory this process cannot make sense of is still not a reason to
+    // fail an install, so it is reported on the same terms as a failed download.
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: strict ? 1 : 0,
+      lines: [`wake-word model: skipped — ${message}`],
+    };
+  }
+  const outcome = await provision({
+    managedRoot,
+    recoveryHint: '/voice wake setup',
+    ...(deps.env !== undefined ? { env: deps.env } : {}),
+  });
+  return {
+    exitCode: strict && outcome.state === 'degraded' ? 1 : 0,
+    lines: [`wake-word model: ${outcome.message}`],
+  };
+}

package/src/input/command-registry.ts

@@ -108,6 +108,12 @@ export interface CommandUiActions {
   deleteQueuedMessage?: (id: string) => boolean;
   /** Toggle the drill-in of the "used N memories" provenance chip (memory.showProvenance). */
   toggleMemoryProvenance?: () => void;
+  /**
+   * Start voice input, or stop the recording already running and transcribe it
+   * into the composer. Two discrete presses rather than a hold, because a
+   * terminal delivers key events and never key-release state.
+   */
+  toggleVoiceInput?: () => void;
   /** The current host sleep-ownership projection (power.status.get, flattened) — chip, held-because, lid-split. */
   getPowerState?: () => import('../core/power-status.ts').PowerSurfaceState;
   /** Set the daemon-held keep-awake toggle (power.keepAwake.set), acquiring/releasing the inhibitor live; returns the new state. */

package/src/input/commands/experience-runtime.ts

@@ -3,6 +3,10 @@ import { dirname, resolve } from 'node:path';
 import type { CommandRegistry } from '../command-registry.ts';
 import { requirePanelManager, requireShellPaths } from './runtime-services.ts';
 import { createVoiceProvisionGateway, renderVoiceProvision, runVoiceSetupWithProgress, VOICE_SETUP_ANNOUNCEMENT } from '../../core/voice-provision-gateway.ts';
+import { resolveWakeRuntimeSettings } from '@pellux/goodvibes-sdk/platform/voice/wake/runtime';
+import { terminalWakeCapabilities } from '../../core/wake-provision-status.ts';
+import { printWakeStatus, runWakeProvision } from '../../core/wake-provision-runner.ts';
+import { wakeProvisionStatus } from '@pellux/goodvibes-sdk/platform/voice';
 
 interface VoiceBundle {
   readonly version: 1;
@@ -223,11 +227,41 @@ export function registerExperienceRuntimeCommands(registry: CommandRegistry): vo
 
   registry.register({
     name: 'voice',
-    description: 'Review or toggle always-speak mode, provision the managed local voice runtime (setup/status), and package portable voice metadata',
-    usage: '[review|status|setup|enable|disable|bundle export <path>|bundle inspect <path>]',
+    description: 'Review or toggle always-speak mode, provision the managed local voice runtime and the wake-word models (setup/status), and package portable voice metadata',
+    usage: '[review|status|setup|enable|disable|wake status|wake setup|bundle export <path>|bundle inspect <path>]',
     async handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
       const sub = (args[0] ?? 'review').toLowerCase();
+      if (sub === 'wake') {
+        // The wake models are provisioned locally by the SDK (checksum-pinned
+        // download), not through a daemon verb, so this path needs no gateway.
+        // Installation already provisions them and a daemon retries at boot;
+        // `setup` here is the recovery act, and nothing downloads unless the user
+        // typed it — see wake-provision-runner.ts.
+        const wakeSub = (args[1] ?? 'status').toLowerCase();
+        const managedRoot = shellPaths.resolveUserPath('voice');
+        const runner = {
+          managedRoot,
+          settings: resolveWakeRuntimeSettings(
+            (key: string) => ctx.platform.configManager.get(key as Parameters<typeof ctx.platform.configManager.get>[0]),
+            'tui',
+            // Read from disk, so `/voice wake status` reports the speech gate as
+            // available exactly when its artifact is there and verified.
+            terminalWakeCapabilities(wakeProvisionStatus({ managedRoot })),
+          ),
+          print: (block: string) => ctx.print(block),
+        };
+        if (wakeSub === 'setup') {
+          await runWakeProvision(runner);
+          return;
+        }
+        if (wakeSub === 'status') {
+          printWakeStatus(runner);
+          return;
+        }
+        ctx.print('Usage: /voice wake [status|setup]');
+        return;
+      }
       if (sub === 'status' || sub === 'setup') {
         // The one-act managed install returns a final receipt (no per-phase
         // streaming over the verb), so the announcement block prints first and
@@ -294,7 +328,7 @@ export function registerExperienceRuntimeCommands(registry: CommandRegistry): vo
           return;
         }
       }
-      ctx.print('Usage: /voice [review|status|setup|enable|disable|bundle export <path>|bundle inspect <path>]');
+      ctx.print('Usage: /voice [review|status|setup|enable|disable|wake status|wake setup|bundle export <path>|bundle inspect <path>]');
     },
   });
 }

package/src/input/handler-shortcuts.ts

@@ -132,6 +132,14 @@ export function handleGlobalShortcutToken(
       state.commandContext?.toggleMemoryProvenance?.();
       return true;
 
+    case 'voice-input':
+      // Start recording, or stop the recording already running. Routed globally so
+      // the key works whether focus is on the composer or the panel workspace —
+      // dictation is not a composer-only act. Still consumed when voice input is
+      // not wired, so a stray Alt+V never lands in the prompt as text.
+      state.commandContext?.toggleVoiceInput?.();
+      return true;
+
     case 'toggle-keep-awake': {
       // Flip the daemon-held keep-awake toggle; the always-visible "sleep
       // disabled" chip is the confirmation. Fire-and-forget (the seam renders on

package/src/input/keybindings.ts

@@ -71,7 +71,8 @@ export type KeyAction =
   | 'yank-pop'
   | 'cancel-tool-call'
   | 'toggle-keep-awake'
-  | 'toggle-memory-provenance';
+  | 'toggle-memory-provenance'
+  | 'voice-input';
 
 /** Human-readable description for each action (used in /keybindings display). */
 export const ACTION_DESCRIPTIONS: Record<KeyAction, string> = {
@@ -117,6 +118,10 @@ export const ACTION_DESCRIPTIONS: Record<KeyAction, string> = {
   'cancel-tool-call':      'Cancel the running tool call (the turn continues)',
   'toggle-keep-awake':     'Toggle keep-awake (the "sleep disabled" chip)',
   'toggle-memory-provenance': 'List/hide the memories a turn used (provenance chip drill-in)',
+  // Named for what it actually does. A terminal delivers key EVENTS, not held-key
+  // state — there is no release event to watch — so this is two discrete presses,
+  // and the description says so instead of implying a hold that cannot exist.
+  'voice-input':           'Voice input: press to start recording, press again to stop and transcribe into the composer',
 };
 
 /** Default key bindings for all actions. */
@@ -207,6 +212,10 @@ export const DEFAULT_KEYBINDINGS: Record<KeyAction, KeyCombo[]> = {
   // Alt+M: expand/collapse the "used N memories" provenance chip's drill-in.
   // Alt+M is unused by any other default. A no-op when the chip is not showing.
   'toggle-memory-provenance': [{ key: 'm', alt: true }],
+  // Alt+V: start/stop voice input. Alt+V is unused by any other default (Ctrl+V
+  // is paste and stays paste). Two presses rather than a hold: see the action's
+  // description — a terminal has no key-release event to hold against.
+  'voice-input':           [{ key: 'v', alt: true }],
 };
 
 /** Resolved overrides type: each key can be a single combo or array. */