@pellux/goodvibes-tui 1.25.0 → 1.27.0

package/src/cli/redaction.ts

@@ -1,6 +1,56 @@
 export const REDACTED_VALUE = '<redacted>';
 
+// Matches a config path whose LAST SEGMENT is exactly one of these words. That
+// is the whole reach of this pattern, and it is why the declared list below
+// exists: `surfaces.calendar.caldavPassword` does not end in a `.password`
+// segment, it ends in a `caldavPassword` segment, so this pattern answers false
+// for it — as it does for `imapPassword`, `appPassword` and `authToken`.
 const SENSITIVE_PATH_PATTERN = /(^|\.)(apiKey|accessToken|botToken|appToken|signingSecret|webhookSecret|verifyToken|verificationToken|secret|password|token|keyFile)$/i;
+
+// Credential-bearing config keys that are sensitive by NAME rather than by the
+// generic trailing-word list above. Every one of these was carried in the clear
+// by a support bundle before it was listed here, because the pattern matches a
+// trailing WORD and these names carry the credential word in the middle or
+// prefixed by a protocol ("caldavPassword", "imapPassword", "appPassword",
+// "authToken").
+//
+// The `*Ref` Cloudflare keys normally hold a `goodvibes://secrets/...`
+// reference, which shouldRedactValue already lets through as safe. They are
+// listed as a BACKSTOP, for the same reason the mail keys are worth listing
+// twice over: it costs nothing, and it is what stands between a future code
+// path that writes a literal token there and that token reaching a file the
+// owner emails to someone for support.
+const SENSITIVE_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  // Mailbox / CalDAV — the credentials the daemon polls mail and calendar with.
+  'surfaces.email.password',
+  'surfaces.email.imapPassword',
+  'surfaces.email.imap.password',
+  'surfaces.email.smtp.password',
+  'surfaces.calendar.caldavPassword',
+  // Telephony.
+  'surfaces.telephony.authToken',
+  'surfaces.msteams.appPassword',
+  // Cloudflare token references.
+  'cloudflare.apiTokenRef',
+  'cloudflare.tunnelTokenRef',
+  'cloudflare.accessServiceTokenRef',
+  'cloudflare.workerTokenRef',
+  'cloudflare.workerClientTokenRef',
+  // Cluster shared phrase.
+  'cluster.secret',
+  // Payment card material. ADDED to this set, never substituted for it: this
+  // set is a hardcoded list with no delegation, so replacing it wholesale with
+  // another product's would silently stop redacting whatever that one omits.
+  // The four names below end in no word the suffix pattern knows —
+  // "cardNumber", "cardExpiry" and "cardholderName" match none of them — which
+  // is the whole reason a declared list exists rather than a naming habit.
+  // (The `.map` below lowercases every entry; the lookup lowercases too.)
+  'payments.cardNumber',
+  'payments.cardExpiry',
+  'payments.cardCvv',
+  'payments.cardholderName',
+].map((key) => key.toLowerCase()));
+
 const SECRET_LIKE_TEXT_PATTERNS: readonly RegExp[] = [
   /\bsk-[A-Za-z0-9_-]{16,}\b/g,
   /\bghp_[A-Za-z0-9_]{16,}\b/g,
@@ -13,7 +63,7 @@ const SECRET_LIKE_TEXT_PATTERNS: readonly RegExp[] = [
 ];
 
 export function isSensitiveConfigPath(path: string): boolean {
-  return SENSITIVE_PATH_PATTERN.test(path);
+  return SENSITIVE_PATH_PATTERN.test(path) || SENSITIVE_CONFIG_KEYS.has(path.toLowerCase());
 }
 
 export function isRedactedValue(value: unknown): boolean {
@@ -25,9 +75,14 @@ export interface RedactedConfigResult<T> {
   readonly redactedPaths: readonly string[];
 }
 
+// Redaction rule for sensitive config paths:
+// - Non-string values: redact if truthy (i.e. non-null, non-undefined, non-zero, non-false).
+//   Rationale: zero and false are never meaningful secrets; null/undefined mean absent.
+// - String values: redact non-empty strings that are not goodvibes:// secret refs.
+//   Rationale: empty string means unset; secret refs are safe placeholders, not raw values.
 function shouldRedactValue(path: string, value: unknown): boolean {
   if (!isSensitiveConfigPath(path)) return false;
-  if (typeof value !== 'string') return value !== undefined && value !== null;
+  if (typeof value !== 'string') return value !== null && value !== undefined && Boolean(value);
   if (value.trim().length === 0) return false;
   if (value.startsWith('goodvibes://secrets/')) return false;
   return true;
@@ -64,7 +119,17 @@ export function redactConfig<T>(config: T): RedactedConfigResult<T> {
 }
 
 export function redactText(input: string): string {
-  let output = input;
+  // Assignment form: keyword=value — anchored so 'monkey=' and 'donkey=' do NOT match.
+  // Matches: token=, access_token=, api_key=, api-key=, secret=, password= and colon form token: value
+  let output = input
+    .replace(
+      /(?<![A-Za-z])(?:access_token|api[_-]?key|secret|password|token)\s*=\s*([^ \t\r\n"'`]+)/gi,
+      (m, val) => m.slice(0, m.length - val.length) + REDACTED_VALUE,
+    )
+    .replace(
+      /(?<![A-Za-z])(?:access_token|api[_-]?key|secret|password|token)\s*:\s*([^ \t\r\n"'`]+)/gi,
+      (m, val) => m.slice(0, m.length - val.length) + REDACTED_VALUE,
+    );
   for (const pattern of SECRET_LIKE_TEXT_PATTERNS) {
     output = output.replace(pattern, REDACTED_VALUE);
   }

package/src/config/goodvibes-home.ts

@@ -44,6 +44,15 @@ export interface GoodVibesHomeOwnership {
   readonly homeDirectory: string;
   /** The daemon's own identity directory, under the tree root by default. */
   readonly daemonHomeDirectory: string;
+  /**
+   * True when either `GOODVIBES_HOME` or `GOODVIBES_DAEMON_HOME` named an
+   * override (a blank/whitespace-only value does not count — see
+   * resolveGoodVibesHome). Callers that need to know "is this process running
+   * out of a relocated tree or identity directory" (e.g. to refuse adopting
+   * the machine's real service unit) read this instead of re-reading the raw
+   * environment variable themselves — this module is the one reader.
+   */
+  readonly isOverridden: boolean;
 }
 
 /**
@@ -117,6 +126,7 @@ export function resolveGoodVibesHomeOwnership(
   return {
     homeDirectory,
     daemonHomeDirectory: resolveGoodVibesDaemonHome(homeDirectory, env),
+    isOverridden: Boolean(env['GOODVIBES_HOME']?.trim()) || Boolean(env['GOODVIBES_DAEMON_HOME']?.trim()),
   };
 }
 

package/src/config/secret-config.ts

@@ -1,8 +1,27 @@
-import { isSecretRefInput } from '@pellux/goodvibes-sdk/platform/config';
+import { isSecretRefInput, isDaemonOwnedConfigKey } from '@pellux/goodvibes-sdk/platform/config';
 import type { ConfigKey } from './index.ts';
 import type { SecretScope, SecretStorageMedium } from './secrets.ts';
 
 export const SECRET_CONFIG_KEYS = new Set<ConfigKey>([
+  // Mailbox and CalDAV credentials. Their own CONFIG_SCHEMA descriptions read
+  // "Stored in the daemon secret tier, never in config" — and until they were
+  // listed here that sentence was aspirational: the settings modal wrote them
+  // as plain strings into a config JSON file, because membership in this set is
+  // the thing that routes an edit through the secret manager instead.
+  //
+  // The daemon reads each of these back with
+  // resolveConfigSecret('<key>') → GOODVIBES_<KEY>, which is exactly the store
+  // key buildGoodVibesSecretKey() writes — see
+  // daemon/handlers/inbox/providers/email.ts.
+  'surfaces.email.password',
+  'surfaces.email.imapPassword',
+  'surfaces.email.imap.password',
+  'surfaces.email.smtp.password',
+  'surfaces.calendar.caldavPassword',
+  // Telephony delivery credentials — same shape, same file, same gap.
+  'surfaces.telephony.authToken',
+  'surfaces.telephony.token',
+  'surfaces.telephony.webhookSecret',
   'surfaces.slack.signingSecret',
   'surfaces.slack.botToken',
   'surfaces.slack.appToken',
@@ -23,6 +42,16 @@ export const SECRET_CONFIG_KEYS = new Set<ConfigKey>([
   'surfaces.bluebubbles.password',
   'surfaces.mattermost.botToken',
   'surfaces.matrix.accessToken',
+  // TUI-local synthetic sub-keys, one level under the SDK's real `payments`
+  // section (not yet a scalar CONFIG_SCHEMA entry — same situation as
+  // tts.speed, behavior.notifyAfterSeconds, etc. in settings-modal-data.ts),
+  // hence the cast. See input/payments-config.ts for why these are named flat
+  // (payments.cardNumber, not payments.card.number): a flat one-level leaf is
+  // the shape the real ConfigManager tolerates for an undeclared key.
+  'payments.cardNumber' as ConfigKey,
+  'payments.cardExpiry' as ConfigKey,
+  'payments.cardCvv' as ConfigKey,
+  'payments.cardholderName' as ConfigKey,
 ]);
 
 export interface SecretBackedConfigUpdate {
@@ -96,6 +125,28 @@ export function buildSecretBackedConfigUpdate(configKey: ConfigKey, rawValue: st
   };
 }
 
+/**
+ * Where a secret-backed write lands when the caller did not name a scope.
+ *
+ * A daemon-owned config key (`surfaces.*`, `payments.*`, `controlPlane.*`, ...)
+ * names a credential the DAEMON executes with, not this interactive client, so
+ * its secret material belongs in the daemon-scoped tier the daemon actually
+ * reads — the same rule the SDK's config-ownership.ts already applies to the
+ * `goodvibes://` reference that points at it.
+ *
+ * Defaulting these to 'user' (the historical behavior here) split the pair: the
+ * reference landed in the daemon's own settings file, because ConfigManager
+ * routes daemon-owned keys there, while the value it pointed at sat in a tier
+ * the daemon never resolves. The surface reported success and the daemon found
+ * nothing. For the mailbox password that is the whole feature failing silently —
+ * the daemon is the process that polls IMAP and answers over Telegram, and it
+ * does so with every surface closed. A payment card entered through
+ * /payments card is the same shape of failure at purchase time.
+ */
+export function defaultSecretBackedScope(configKey: ConfigKey): SecretScope {
+  return isDaemonOwnedConfigKey(configKey) ? 'daemon' : 'user';
+}
+
 export async function persistSecretBackedConfigValue(
   configManager: SecretBackedConfigManager,
   secretsManager: SecretBackedSecretStore | null | undefined,
@@ -104,16 +155,21 @@ export async function persistSecretBackedConfigValue(
   options: { readonly scope?: SecretScope } = {},
 ): Promise<string> {
   const update = buildSecretBackedConfigUpdate(configKey, rawValue);
-  const scope = options.scope ?? 'user';
+  const scope = options.scope ?? defaultSecretBackedScope(configKey);
+  const medium = getSecretWriteMedium(configManager.get('storage.secretPolicy'));
+
+  // 1. Validate config write first. If setDynamic throws, no secret is written (avoids orphans).
+  configManager.setDynamic(configKey, update.configValue);
+
+  // 2. Write new secret only after config accepted it.
   if (update.secretKey && update.secretValue !== undefined && secretsManager) {
-    await secretsManager.set(update.secretKey, update.secretValue, {
-      scope,
-      medium: getSecretWriteMedium(configManager.get('storage.secretPolicy')),
-    });
+    await secretsManager.set(update.secretKey, update.secretValue, { scope, medium });
   }
+
+  // 3. Clear old secret — pass the same medium so plaintext-medium secrets are found for deletion.
   if (update.clearSecretKey && secretsManager?.delete) {
-    await secretsManager.delete(update.clearSecretKey, { scope });
+    await secretsManager.delete(update.clearSecretKey, { scope, medium });
   }
-  configManager.setDynamic(configKey, update.configValue);
+
   return update.configValue;
 }

package/src/core/turn-event-wiring.ts

@@ -1,7 +1,7 @@
 import type { UiRuntimeEvents, RuntimeEventBus } from '@/runtime/index.ts';
 import { buildPersistedSessionContext, persistConversation } from '@/runtime/index.ts';
 import { buildCompactionReceiptBlock } from './compaction-receipt.ts';
-import { formatTurnBudgetOutcome } from './turn-budget-outcome.ts';
+import { workstreamFailureNotification } from './workstream-notification.ts';
 import { persistTurnAnchors, recordTurnAnchor, summarizeTurnLabel } from './rewind-turn-anchors.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
@@ -328,21 +328,12 @@ export function wireTurnEventHandlers(
     unsubs.push(events.workflows.on('WORKFLOW_CHAIN_FAILED', (payload) => {
       if (!shouldFireAlert(focusTracker, configGet, 'behavior.notifyOnChainFailure')) return;
       try {
-        // An operator cancellation is an intended stop, not a failure — narrate it
-        // as cancelled (the reason already carries the landed-work count from the
-        // chain's edit ledger), so the notification never contradicts the cancelled
-        // chain/owner/cohort surfaces.
-        if (payload.failureKind === 'cancelled') {
-          notifyCompletion('GoodVibes — WRFC chain cancelled', `chain ${payload.chainId.slice(0, 12)} cancelled: ${payload.reason}`, FORCE_NOTIFY_DURATION_MS);
-        } else if (payload.failureKind === 'max_turns') {
-          // A turn-budget exhaustion is a spent ceiling, not an infrastructure
-          // failure — narrate the limit and where it came from, from the typed
-          // event fields, never a regex of the prose reason.
-          notifyCompletion('GoodVibes — WRFC chain hit its turn budget', `chain ${payload.chainId.slice(0, 12)} ${formatTurnBudgetOutcome({ limit: payload.turnLimit, source: payload.turnLimitSource })}`, FORCE_NOTIFY_DURATION_MS);
-        } else {
-          const kindLabel = payload.failureKind === 'transport' ? 'transient transport error' : payload.reason;
-          notifyCompletion('GoodVibes — WRFC chain failed', `chain ${payload.chainId.slice(0, 12)} failed: ${kindLabel}`, FORCE_NOTIFY_DURATION_MS);
-        }
+        // Title and body come from workstream-notification.ts, which is where
+        // the three branches (cancelled / turn budget / failed) are narrated and
+        // tested. A notification is a message to a person, so it carries neither
+        // the internal name for the machinery nor the chain id.
+        const notice = workstreamFailureNotification(payload);
+        notifyCompletion(notice.title, notice.body, FORCE_NOTIFY_DURATION_MS);
       } catch (err) {
         logger.debug('turn-event-wiring: chain-failure notify error', { error: String(err) });
       }

package/src/core/voice-capture-status.ts

@@ -0,0 +1,53 @@
+/**
+ * voice-capture-status.ts — what the shell shows while a microphone is open.
+ *
+ * A capture indicator is not decoration. Two of the three states here exist
+ * because the alternative is a user who cannot tell whether their microphone is
+ * live: wake detection holds a device open for as long as the feature is on, and
+ * push-to-talk holds one open between two keypresses. `voice.wake.indicator`
+ * governs how prominent the detector's row is; a push-to-talk recording is
+ * always shown, because the user is mid-act and waiting for it.
+ *
+ * The shape lives here rather than in the renderer or in src/audio so both can
+ * use it: the audio layer must not import shell-UI (the architecture check
+ * enforces that), and the renderer must not own capture state.
+ */
+
+/** What a voice-capture row is reporting. */
+export type VoiceCaptureIndicatorKind =
+  /** Push-to-talk: the user pressed the key and is speaking now. */
+  'recording'
+  /** Push-to-talk: the device is being opened (a permission prompt takes real time). */
+  | 'requesting'
+  /** Push-to-talk: capture ended and the audio is being transcribed. */
+  | 'transcribing'
+  /** Wake detection is listening and scoring frames. */
+  | 'wake-listening'
+  /** A wake confirmed; the utterance that followed it is being captured. */
+  | 'wake-capturing'
+  /** The detector's stream died and a restart is scheduled. */
+  | 'wake-restarting'
+  /** The supervisor gave up; the detector is off until the feature is toggled. */
+  | 'wake-latched';
+
+/** One live capture row. Absent (null) means no microphone is open and no row renders. */
+export interface VoiceCaptureIndicatorState {
+  readonly kind: VoiceCaptureIndicatorKind;
+  /** What opened the device, e.g. `parecord`; null before anything is open. */
+  readonly deviceLabel: string | null;
+  /**
+   * Prominence for the wake rows, from `voice.wake.indicator`. `off` suppresses
+   * them entirely. Push-to-talk rows ignore it: the user asked for that capture
+   * one keypress ago and is owed the confirmation.
+   */
+  readonly indicator: 'off' | 'statusline' | 'banner';
+  /** Extra words for the row — a restart delay, a latch reason, an elapsed time. */
+  readonly detail?: string | undefined;
+}
+
+/** True when this state should produce a footer row at all. */
+export function voiceCaptureRowVisible(state: VoiceCaptureIndicatorState | null): boolean {
+  if (state === null) return false;
+  const isWakeRow = state.kind.startsWith('wake-');
+  return !isWakeRow || state.indicator !== 'off';
+}

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');