@pellux/goodvibes-tui 1.18.0 → 1.19.0

package/src/core/memory-status.ts

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// memory-status.ts — the surface-facing projection of the daemon's memory
+// governance (ops.memory.get + OPS_MEMORY_PRESSURE).
+//
+// The SDK's MemoryGovernor owns the policy: it samples RSS/heap against a
+// budget, sheds memory by tier (trimming registered caches, pausing deferrable
+// background jobs), refuses new expensive work at the critical tier, and trips
+// on a genuine leak before the OS OOM-kills it. This module is the read-only
+// projection the /health memory (doctor) surface renders from — the snapshot
+// rows — and the attention line OPS_MEMORY_PRESSURE produces when the tier
+// changes or the tripwire fires.
+//
+// Pure formatting only (no I/O): the command fetches the typed verb response
+// over the operator invoke seam (memory-diagnostics-gateway.ts) and hands it
+// here, so these builders are unit-testable against fixture shapes.
+// ---------------------------------------------------------------------------
+
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+import type { OpsEvent } from '@/runtime/index.ts';
+
+/** ops.memory.get output — the full governor snapshot. */
+export type MemoryGovernorSnapshotResult = OperatorMethodOutput<'ops.memory.get'>;
+/** The OPS_MEMORY_PRESSURE event payload (a tier change or a tripwire firing). */
+export type MemoryPressurePayload = Extract<OpsEvent, { type: 'OPS_MEMORY_PRESSURE' }>;
+
+/** Human MB (the governor already reports MB as numbers; round to 1 decimal). */
+export function formatMb(mb: number | null | undefined): string {
+  if (mb === null || mb === undefined || !Number.isFinite(mb)) return 'unknown';
+  return `${mb >= 100 ? Math.round(mb) : Math.round(mb * 10) / 10} MB`;
+}
+
+/** Human byte size for a cache footprint estimate. */
+export function formatMemoryBytes(bytes: number | null | undefined): string {
+  if (bytes === null || bytes === undefined || !Number.isFinite(bytes) || bytes < 0) return 'size n/a';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${units[unit]}`;
+}
+
+/** A plain-language note for the current tier (the governor's posture at this tier). */
+export function memoryTierNote(tier: MemoryGovernorSnapshotResult['tier']): string {
+  switch (tier) {
+    case 'normal': return 'footprint is comfortably within budget';
+    case 'elevated': return 'trimming caches to a floor and running gc';
+    case 'high': return 'flushing caches and pausing deferrable background jobs';
+    case 'critical': return 'refusing new expensive work until the footprint recovers';
+    default: return '';
+  }
+}
+
+/**
+ * The /health memory (doctor) rows — the honest account of the daemon defending
+ * its footprint. Order: tier + posture, budget vs RSS, heap, tier thresholds,
+ * per-cache footprints the governor can shrink, which deferrable jobs are
+ * paused, and the leak-tripwire state.
+ */
+export function memoryStatusLines(snapshot: MemoryGovernorSnapshotResult): string[] {
+  const lines: string[] = [];
+  lines.push(`  tier: ${snapshot.tier} — ${memoryTierNote(snapshot.tier)}`);
+  if (snapshot.refusingExpensiveWork) {
+    lines.push('  expensive work: REFUSED (critical tier) — new ingestion / reindex / voice install is declined until RSS recovers');
+  }
+  lines.push(`  budget: ${formatMb(snapshot.rssMb)} rss / ${formatMb(snapshot.budgetMb)} budget (${Math.round(snapshot.usedPct)}%)`);
+  const heap = snapshot.heapTotalMb !== undefined
+    ? `${formatMb(snapshot.heapUsedMb)} used / ${formatMb(snapshot.heapTotalMb)} total`
+    : formatMb(snapshot.heapUsedMb);
+  lines.push(`  heap: ${heap}`);
+  lines.push(`  tiers: elevated ${snapshot.thresholds.elevatedPct}% · high ${snapshot.thresholds.highPct}% · critical ${snapshot.thresholds.criticalPct}%`);
+
+  if (snapshot.caches.length === 0) {
+    lines.push('  caches: none registered');
+  } else {
+    lines.push(`  caches: ${snapshot.caches.length}`);
+    for (const cache of snapshot.caches) {
+      const size = cache.estimatedBytes !== undefined ? `, ~${formatMemoryBytes(cache.estimatedBytes)}` : '';
+      lines.push(`    ${cache.id} (${cache.name}): ${cache.entries} entries${size}`);
+    }
+  }
+
+  lines.push(snapshot.pausedJobs.length === 0
+    ? '  paused jobs: none'
+    : `  paused jobs: ${snapshot.pausedJobs.join(', ')}`);
+
+  if (snapshot.tripwire.armed) {
+    lines.push(`  tripwire: ARMED — watching for a sustained >${snapshot.tripwire.rateMbPerSec} MB/s post-flush leak (held ${Math.round(snapshot.tripwire.sustainedSec)}s)`);
+  } else {
+    lines.push('  tripwire: disarmed (no post-flush leak growth under watch)');
+  }
+  return lines;
+}
+
+/**
+ * The attention line OPS_MEMORY_PRESSURE produces: a one-liner naming the new
+ * tier and the RSS/budget, plus a distinct escalation when the leak tripwire
+ * fires (the daemon is about to exit for a clean supervisor restart). Returned
+ * as a single string so the notice/attention surface can push it directly.
+ */
+export function memoryPressureLine(event: MemoryPressurePayload): string {
+  const base = `memory pressure: ${event.previousTier} → ${event.tier} (${formatMb(event.rssMb)} rss / ${formatMb(event.budgetMb)} budget, ${Math.round(event.usedPct)}%)`;
+  if (event.tripwire) {
+    return `${base} — leak tripwire fired (${event.tripwire.rateMbPerSec} MB/s sustained ${Math.round(event.tripwire.sustainedSec)}s); the daemon will exit for a clean restart`;
+  }
+  if (event.note) return `${base} — ${event.note}`;
+  return base;
+}
+
+/** Severity for the notice feed: critical tier (or a tripwire) is critical; high is a warning. */
+export function memoryPressureLevel(event: MemoryPressurePayload): 'info' | 'warning' | 'critical' {
+  if (event.tripwire || event.tier === 'critical') return 'critical';
+  if (event.tier === 'high') return 'warning';
+  return 'info';
+}

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

@@ -0,0 +1,202 @@
+// ---------------------------------------------------------------------------
+// voice-provision-gateway.ts
+//
+// The daemon-backed verbs the /voice setup + /voice status surfaces read:
+// voice.local.status (GET /api/voice/local/status) — the no-network installed
+// snapshot — and voice.local.install (POST /api/voice/local/install) — the
+// one-act managed install. Neither has a named facade on the in-process
+// OperatorClient, so — exactly like the memory-consolidation gateway — they go
+// over the generic operator invoke path (operator-rpc.ts's resolveOperatorRpc
+// -> sdk.operator.invoke), reaching the SAME daemon the command layer does.
+//
+// A daemon that predates managed voice provisioning answers an honest 501 (verb
+// cataloged but no handler) or a 404 (older daemon without the route) — both
+// are "verb unavailable", NOT a fabricated empty/failed install (see
+// classifyVoiceProvisionError). The interface is injectable so the command and
+// its tests round-trip against a mocked daemon.
+// ---------------------------------------------------------------------------
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { GoodVibesSdkError } from '@pellux/goodvibes-sdk';
+import { resolveOperatorRpc, describeOperatorRpcError } from '../input/commands/operator-rpc.ts';
+import type { VoiceRuntimeStatusResult, VoiceLocalInstallResult } from './voice-provision-status.ts';
+import { voiceStatusLines, voiceInstallReceiptLines, voiceInstallComponentLine } from './voice-provision-status.ts';
+
+/** The narrow async verb surface the /voice setup + /voice status surfaces drive. */
+export interface VoiceProvisionGateway {
+  /** Read the no-network managed-runtime snapshot (voice.local.status). */
+  fetchStatus(): Promise<VoiceRuntimeStatusResult>;
+  /** Run the one-act managed install (voice.local.install); resolves to the receipt. */
+  runInstall(): Promise<VoiceLocalInstallResult>;
+}
+
+/**
+ * Why the gateway could not be built (daemon disabled / no control-plane URL),
+ * surfaced verbatim so the surface prints an honest "unavailable" line rather
+ * than guessing — mirrors MemoryConsolidationGatewayResolution.
+ */
+export type VoiceProvisionGatewayResolution =
+  | { readonly available: true; readonly gateway: VoiceProvisionGateway }
+  | { readonly available: false; readonly reason: string };
+
+export interface VoiceProvisionGatewayDeps {
+  readonly configManager: ConfigManager;
+  readonly homeDirectory: string | (() => string);
+}
+
+/**
+ * Build the live voice-provisioning gateway over the generic operator invoke
+ * path — the same daemon resolution the command layer uses. Returns an honest
+ * unavailable reason when no daemon is reachable, so the surface refuses
+ * cleanly instead of throwing mid-render.
+ */
+export function createVoiceProvisionGateway(deps: VoiceProvisionGatewayDeps): VoiceProvisionGatewayResolution {
+  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: {
+      fetchStatus: () => sdk.operator.invoke('voice.local.status', {}),
+      runInstall: () => sdk.operator.invoke('voice.local.install', {}),
+    },
+  };
+}
+
+/** How a voice verb rejection should render. */
+export type VoiceProvisionFetchFailure =
+  | { readonly kind: 'unavailable'; readonly reason: string }
+  | { readonly kind: 'error'; readonly message: string };
+
+/**
+ * Classify a voice verb rejection: a 501 (a daemon that predates managed voice
+ * provisioning — cataloged but unhandled) or a 404 (an older daemon without the
+ * route) are both "verb unavailable", distinct from a generic request failure
+ * (network error, 401/403, 500). Reuses describeOperatorRpcError's wording so
+ * the call sites never diverge on how they describe the same daemon response.
+ */
+export function classifyVoiceProvisionError(error: unknown): VoiceProvisionFetchFailure {
+  if (error instanceof GoodVibesSdkError && (error.status === 501 || error.status === 404)) {
+    return { kind: 'unavailable', reason: 'this daemon does not serve managed voice provisioning yet.' };
+  }
+  return { kind: 'error', message: describeOperatorRpcError(error) };
+}
+
+/** The single one-act setup announcement shown before the (possibly long) install runs. */
+export const VOICE_SETUP_ANNOUNCEMENT = [
+  'Local Voice Setup',
+  '  provisioning the managed local voice runtime (piper TTS + a default voice; whisper STT where a bundle is published)…',
+  '  downloads are checksum-verified and resumable — re-run /voice setup to retry any failed component.',
+].join('\n');
+
+/**
+ * Render the /voice status or /voice setup RESULT block from an already-resolved
+ * gateway resolution — the testable core the command wraps. Kept separate from
+ * the live gateway construction so a wire test injects a fake resolution
+ * (available / unavailable / failing) with no HTTP, mirroring the Memory modal's
+ * injectable resolveConsolidationGateway seam. The caller prints
+ * VOICE_SETUP_ANNOUNCEMENT itself before awaiting a setup so the up-front notice
+ * shows during the (possibly long, multi-hundred-MB) install.
+ */
+export async function renderVoiceProvision(
+  sub: 'status' | 'setup',
+  resolution: VoiceProvisionGatewayResolution,
+): Promise<string> {
+  if (!resolution.available) {
+    const label = sub === 'status' ? 'Local Voice Runtime' : 'Local Voice Setup';
+    return `${label} unavailable: ${resolution.reason}`;
+  }
+  if (sub === 'status') {
+    try {
+      const status = await resolution.gateway.fetchStatus();
+      return ['Local Voice Runtime', ...voiceStatusLines(status)].join('\n');
+    } catch (error) {
+      const failure = classifyVoiceProvisionError(error);
+      return failure.kind === 'unavailable'
+        ? `Local Voice Runtime\n  ${failure.reason}`
+        : `Local Voice Runtime\n  could not read status: ${failure.message}`;
+    }
+  }
+  // setup
+  try {
+    const receipt = await resolution.gateway.runInstall();
+    return ['Local Voice Setup — receipt', ...voiceInstallReceiptLines(receipt)].join('\n');
+  } catch (error) {
+    const failure = classifyVoiceProvisionError(error);
+    return failure.kind === 'unavailable'
+      ? `Local Voice Setup\n  ${failure.reason}`
+      : `Local Voice Setup\n  install failed: ${failure.message}`;
+  }
+}
+
+export interface VoiceSetupProgressOptions {
+  /** Sink for each printed block (the command passes ctx.print). */
+  readonly print: (block: string) => void;
+  /** Poll interval while the install is in flight (default 800ms). */
+  readonly pollMs?: number;
+  /** Injectable delay (tests pass a fake; the command uses setTimeout). */
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+const realSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Run /voice setup with LIVE progress: kick off the (long, request/response)
+ * install and, while it is in flight, poll voice.local.status for its
+ * `installInProgress` snapshot, printing a per-component line each time a
+ * component's phase advances (download → verify → extract → done). When the
+ * install settles, print the final receipt (or an honest failure). The install
+ * verb streams nothing itself — this polling is exactly how the SDK intends
+ * surfaces to render real progress instead of busy→receipt.
+ *
+ * The caller prints VOICE_SETUP_ANNOUNCEMENT before calling this. gateway
+ * fetchStatus/runInstall and sleep are injectable so a wire test drives the
+ * whole flow with no real timers or HTTP.
+ */
+export async function runVoiceSetupWithProgress(
+  resolution: VoiceProvisionGatewayResolution,
+  opts: VoiceSetupProgressOptions,
+): Promise<void> {
+  if (!resolution.available) {
+    opts.print(`Local Voice Setup unavailable: ${resolution.reason}`);
+    return;
+  }
+  const { gateway } = resolution;
+  const pollMs = opts.pollMs ?? 800;
+  const sleep = opts.sleep ?? realSleep;
+
+  let settled = false;
+  const installPromise = gateway.runInstall().then(
+    (receipt) => { settled = true; return { ok: true as const, receipt }; },
+    (error) => { settled = true; return { ok: false as const, error }; },
+  );
+
+  // Print a component line only when its phase changes, so a slow install does
+  // not spam identical lines each poll.
+  const lastPhase = new Map<string, string>();
+  while (!settled) {
+    await sleep(pollMs);
+    if (settled) break;
+    try {
+      const status = await gateway.fetchStatus();
+      const progress = status.installInProgress;
+      if (!progress) continue;
+      const changed = progress.components.filter((c) => lastPhase.get(c.component) !== c.phase);
+      for (const c of changed) lastPhase.set(c.component, c.phase);
+      if (changed.length > 0) opts.print(changed.map(voiceInstallComponentLine).join('\n'));
+    } catch {
+      // A transient poll failure never aborts the install; the receipt/failure
+      // block below is the authoritative outcome.
+    }
+  }
+
+  const result = await installPromise;
+  if (result.ok) {
+    opts.print(['Local Voice Setup — receipt', ...voiceInstallReceiptLines(result.receipt)].join('\n'));
+  } else {
+    const failure = classifyVoiceProvisionError(result.error);
+    opts.print(failure.kind === 'unavailable'
+      ? `Local Voice Setup\n  ${failure.reason}`
+      : `Local Voice Setup\n  install failed: ${failure.message}`);
+  }
+}

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

@@ -0,0 +1,197 @@
+// ---------------------------------------------------------------------------
+// voice-provision-status.ts — the surface-facing projection of the managed
+// local-voice runtime (voice.local.status / voice.local.install).
+//
+// The SDK owns the provisioning policy: a one-act install that fetches the
+// piper TTS engine + a default voice (fully hosted) and, where a pinned bundle
+// is hosted for the platform, the whisper STT engine + model — atomic,
+// checksum-verified, resumable, and honest about every terminal state. This
+// module is the read-only projection the /voice surfaces render from: sizes
+// declared up front, a receipt of what was installed / skipped / failed, and
+// the honest "not yet published for this platform" line when a whisper bundle
+// is pinned but not yet hosted (its manifest url is unstamped).
+//
+// Pure formatting only (no I/O): the command layer fetches the typed verb
+// responses over the operator invoke seam (voice-provision-gateway.ts) and
+// hands them here, so these builders are unit-testable against fixture shapes.
+// ---------------------------------------------------------------------------
+
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+
+/** voice.local.status output — the no-network installed/available snapshot. */
+export type VoiceRuntimeStatusResult = OperatorMethodOutput<'voice.local.status'>;
+/** voice.local.install receipt — the one-act install outcome. */
+export type VoiceLocalInstallResult = OperatorMethodOutput<'voice.local.install'>;
+/** The live per-component progress carried on voice.local.status WHILE an install runs. */
+export type VoiceInstallProgress = NonNullable<VoiceRuntimeStatusResult['installInProgress']>;
+/** One live install component's progress (latest phase wins). */
+export type VoiceInstallComponentProgress = VoiceInstallProgress['components'][number];
+
+/** Human byte size (mirrors the local formatBytes idiom used across the renderer). */
+export function formatVoiceBytes(bytes: number | null | undefined): string {
+  if (bytes === null || bytes === undefined || !Number.isFinite(bytes) || bytes < 0) return 'unknown size';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${units[unit]}`;
+}
+
+/**
+ * True when a whisper STT bundle is PINNED for this platform (bytes + checksum
+ * fixed) but not yet hosted/sideloaded — the "supported but not yet published"
+ * state. The SDK signals it as supported === true with an unprovisioned state
+ * and an honest reason string; contrast an unsupported platform (supported ===
+ * false), which has no pin at all.
+ */
+export function isSttPinnedButUnpublished(status: VoiceRuntimeStatusResult): boolean {
+  const stt = status.stt;
+  return stt.supported === true && stt.state !== 'provisioned' && !stt.binaryPresent && !stt.modelPresent
+    && typeof stt.reason === 'string' && stt.reason.length > 0;
+}
+
+/** Whether the managed runtime still has something to offer to provision. */
+export function voiceRuntimeNeedsSetup(status: VoiceRuntimeStatusResult): boolean {
+  return status.state !== 'provisioned' || status.stt.state === 'not-provisioned' || status.stt.state === 'partial';
+}
+
+/**
+ * The /voice status lines — an honest, plain-language account of the managed
+ * local-voice runtime with sizes declared up front. Order: platform + overall
+ * state, then the TTS (piper) engine, then the STT (whisper) engine with its
+ * honest unsupported / not-yet-published wording, then the one-act offer size.
+ */
+export function voiceStatusLines(status: VoiceRuntimeStatusResult): string[] {
+  const lines: string[] = [];
+  lines.push(`  platform: ${status.platform ?? 'unrecognized (no managed voice build)'}`);
+  lines.push(`  runtime: ${status.state}`);
+
+  // TTS — piper, fully hosted where a platform build exists.
+  const tts = status.tts;
+  if (tts.binaryPresent && tts.voicePresent) {
+    lines.push(`  tts (${tts.engine}): installed`);
+  } else if (status.state === 'unsupported-platform') {
+    lines.push(`  tts (${tts.engine}): unsupported on this platform`);
+  } else {
+    const have = [tts.binaryPresent ? 'engine' : null, tts.voicePresent ? 'voice' : null].filter(Boolean);
+    lines.push(`  tts (${tts.engine}): not installed${have.length ? ` (have ${have.join(' + ')})` : ''}`);
+  }
+
+  // STT — whisper, hosted only where a pinned bundle is published. Render the
+  // REAL state honestly: a platform with no pinned build (supported === false,
+  // or state 'unsupported-platform' — every platform except linux-x64 today)
+  // reads "unsupported on this platform"; a platform whose bundle is pinned but
+  // not yet hosted (supported === true, unprovisioned, with a reason) reads
+  // "not yet published for this platform".
+  const stt = status.stt;
+  if (stt.binaryPresent && stt.modelPresent) {
+    lines.push(`  stt (${stt.engine}): installed`);
+  } else if (!stt.supported || stt.state === 'unsupported-platform') {
+    lines.push(`  stt (${stt.engine}): unsupported on this platform`);
+    if (stt.reason) lines.push(`    ${stt.reason}`);
+  } else if (isSttPinnedButUnpublished(status)) {
+    lines.push(`  stt (${stt.engine}): not yet published for this platform`);
+    if (stt.reason) lines.push(`    ${stt.reason}`);
+  } else {
+    lines.push(`  stt (${stt.engine}): not installed`);
+    if (stt.reason) lines.push(`    ${stt.reason}`);
+  }
+
+  if (status.offerBytes !== null && status.offerBytes !== undefined && voiceRuntimeNeedsSetup(status)) {
+    lines.push(`  setup download: ${formatVoiceBytes(status.offerBytes)} — run /voice setup to install`);
+  }
+  return lines;
+}
+
+/** A human phase label for a live install component. */
+export function voiceProgressPhaseLabel(phase: string): string {
+  switch (phase) {
+    case 'skip': return 'already present';
+    case 'download': return 'downloading';
+    case 'verify': return 'verifying';
+    case 'extract': return 'extracting';
+    case 'done': return 'done';
+    case 'error': return 'failed';
+    default: return phase;
+  }
+}
+
+/** One live progress line for an install component (size shown as done/total where known). */
+export function voiceInstallComponentLine(component: VoiceInstallComponentProgress): string {
+  let size = '';
+  if (component.bytesTotal !== undefined) {
+    const done = component.bytesDone !== undefined ? `${formatVoiceBytes(component.bytesDone)}/` : '';
+    size = ` (${done}${formatVoiceBytes(component.bytesTotal)})`;
+  }
+  const msg = component.message ? ` — ${component.message}` : '';
+  return `    ${component.component}: ${voiceProgressPhaseLabel(component.phase)}${size}${msg}`;
+}
+
+/** Render the live per-component install progress (voice.local.status installInProgress). */
+export function voiceInstallProgressLines(progress: VoiceInstallProgress): string[] {
+  return progress.components.map(voiceInstallComponentLine);
+}
+
+/** The honest per-terminal-state one-liner for a TTS/STT engine outcome. */
+export function voiceEngineOutcomeLine(engine: string, state: string, reason: string | undefined): string {
+  switch (state) {
+    case 'provisioned':
+      return `  ${engine}: installed`;
+    case 'download-failed':
+      return `  ${engine}: download failed${reason ? ` — ${reason}` : ''} (re-run /voice setup to retry; completed parts are kept)`;
+    case 'checksum-mismatch':
+      return `  ${engine}: checksum mismatch — the downloaded file did not match its pinned checksum and was discarded${reason ? ` (${reason})` : ''}`;
+    case 'bundle-unavailable':
+      return `  ${engine}: not yet published for this platform${reason ? ` — ${reason}` : ''}`;
+    case 'sideload-mismatch':
+      return `  ${engine}: a sideloaded bundle was present but did not match the pinned checksum${reason ? ` — ${reason}` : ''}`;
+    case 'unsupported-platform':
+      return `  ${engine}: unsupported on this platform${reason ? ` — ${reason}` : ''}`;
+    default:
+      return `  ${engine}: ${state}${reason ? ` — ${reason}` : ''}`;
+  }
+}
+
+/**
+ * The /voice setup receipt lines — the final one-act outcome. Renders the
+ * per-component breakdown (installed / skipped-as-present / failed with size),
+ * the TTS and STT terminal states with honest wording, and the config write
+ * receipt (which voice.local.* keys were configured vs skipped as user-set).
+ */
+export function voiceInstallReceiptLines(result: VoiceLocalInstallResult): string[] {
+  const lines: string[] = [];
+  lines.push(`  result: ${result.provisioned ? 'local voice provisioned' : 'not provisioned'}`);
+  lines.push(`  platform: ${result.platform ?? 'unrecognized (no managed voice build)'}`);
+
+  lines.push(voiceEngineOutcomeLine(`tts (${result.tts.engine})`, result.tts.state, result.tts.reason));
+  lines.push(voiceEngineOutcomeLine(`stt (${result.stt.engine})`, result.stt.state, result.stt.reason));
+
+  if (result.components.length > 0) {
+    lines.push('  components:');
+    for (const component of result.components) {
+      const size = component.bytes !== undefined ? ` (${formatVoiceBytes(component.bytes)})` : '';
+      const err = component.error ? ` — ${component.error}` : '';
+      const state = component.state === 'skipped' ? 'already present' : component.state;
+      lines.push(`    ${component.id}: ${state}${size}${err}`);
+    }
+  }
+
+  const set = result.configured.set;
+  const skipped = result.configured.skipped;
+  if (set.length > 0) {
+    lines.push(`  configured ${set.length} key${set.length === 1 ? '' : 's'}:`);
+    for (const entry of set) lines.push(`    ${entry.key} = ${entry.value}`);
+  }
+  if (skipped.length > 0) {
+    lines.push(`  left ${skipped.length} key${skipped.length === 1 ? '' : 's'} untouched:`);
+    for (const entry of skipped) lines.push(`    ${entry.key}: ${entry.reason}`);
+  }
+  if (set.length === 0 && skipped.length === 0) {
+    lines.push('  no config keys were written');
+  }
+  return lines;
+}

package/src/daemon/cli.ts

@@ -29,6 +29,9 @@ import {
 } from '@pellux/goodvibes-sdk/platform/discovery';
 import { createSafeHostServeFactory } from './safe-serve.ts';
 import { isDaemonServiceSubcommand, resolveInstalledDaemonBinary, runDaemonServiceCli } from './service-commands.ts';
+import { resolveConfiguredServiceName } from '../runtime/legacy-daemon-migration.ts';
+import { reconcileRedundantLegacyUnit } from '../runtime/legacy-daemon-reconcile.ts';
+import { resolveRuntimeEndpointBinding } from '../cli/endpoints.ts';
 import { resolveDaemonUpdateArtifact } from './lifecycle.ts';
 import { VERSION } from '../version.ts';
 
@@ -36,6 +39,7 @@ import {
   parseGoodVibesCli,
   renderGoodVibesDaemonHelp,
   renderGoodVibesVersion,
+  renderDaemonStartupBanner,
   applyRuntimeConfigOverrides,
   applyRuntimeConfigValue,
   applyRuntimeFeatureFlagOverrides,
@@ -141,15 +145,28 @@ async function main(): Promise<void> {
   // no runtime/services are constructed — and exit with the honest result code.
   const serviceSubcommand = cli.positionals[0];
   if (isDaemonServiceSubcommand(serviceSubcommand)) {
-    const host = String(process.env.GOODVIBES_DAEMON_HOST ?? config.get('controlPlane.host') ?? '127.0.0.1');
-    const port = Number(config.get('controlPlane.port'));
+    // The host/port baked into the unit's ExecStart (and displayed) come from
+    // the SAME hostMode-aware resolution the SDK bind path uses — never from
+    // the GOODVIBES_DAEMON_HOST env var, which nothing in the bind path reads
+    // (the --hostname flag already lands in config via
+    // applyRuntimeEndpointFlagOverrides above, so it is covered here).
+    const binding = resolveRuntimeEndpointBinding(config, 'controlPlane');
+    if (!binding.recognized) {
+      // The SDK bind path has no default case for an unrecognized hostMode —
+      // a daemon launched with this config throws before binding. Say so
+      // instead of presenting the fallback values as a real binding.
+      console.warn(
+        `[goodvibes-daemon] warning: controlPlane.hostMode '${binding.hostMode}' is not a recognized mode ` +
+          "(local|network|custom) — the daemon will fail to start until it is corrected.",
+      );
+    }
     const binaryPath = resolveInstalledDaemonBinary({ moduleUrl: import.meta.url });
     const result = await runDaemonServiceCli({
       subcommand: serviceSubcommand,
       binaryPath,
       homeDir: homeDirectory,
-      host,
-      port,
+      host: binding.host,
+      port: binding.port,
       // migrate-service only: never auto-migrate — requires the same explicit
       // consent as any other non-interactive destructive confirmation.
       confirmMigration: cliFlags.yes,
@@ -161,6 +178,28 @@ async function main(): Promise<void> {
     process.exit(result.exitCode);
   }
 
+  // Honest startup identity, printed for EVERY launch shape — including a bare
+  // (no-arg) systemd launch, and BEFORE any runtime construction so it still
+  // reaches the journal when a broken config makes the daemon throw during
+  // composition. It states the resolved version (never a placeholder) and the
+  // home/host/port the daemon will actually bind: the binding comes from the
+  // SAME hostMode-aware resolution the SDK bind path uses (resolveHostBinding:
+  // 'local' forces 127.0.0.1, 'network' forces 0.0.0.0, port 0/non-numeric
+  // falls back to the default) — never from controlPlane.host alone, and never
+  // from the GOODVIBES_DAEMON_HOST env var, which the bind path does not read.
+  const bannerBinding = resolveRuntimeEndpointBinding(config, 'controlPlane');
+  // eslint-disable-next-line no-console
+  console.log(renderDaemonStartupBanner(VERSION, { homeDir: homeDirectory, host: bannerBinding.host, port: bannerBinding.port }));
+  if (!bannerBinding.recognized) {
+    // An unrecognized hostMode has NO binding the SDK can produce (its
+    // resolver has no default case and the daemon will throw below, before
+    // serving). Warn here so the journaled crash is explained.
+    console.warn(
+      `[goodvibes-daemon] warning: controlPlane.hostMode '${bannerBinding.hostMode}' is not a recognized mode ` +
+        "(local|network|custom) — the daemon cannot bind until it is corrected; the host/port above are fallback values, not a real binding.",
+    );
+  }
+
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
   // Gate states derive from the domain settings keys; the bridge keeps live
@@ -295,6 +334,43 @@ async function main(): Promise<void> {
     httpListener: config.get('danger.httpListener'),
   });
 
+  // Cheap unattended reconcile: if this (canonical) daemon unit is confirmed
+  // serving AND a redundant installer-managed goodvibes-daemon.service (the
+  // retired unit name) sits enabled-but-NOT-running beside it — the exact
+  // production-incident state — auto-disable and remove it, printing a
+  // receipt. A RUNNING legacy daemon, a hand-written unit, or an unanswered
+  // configured endpoint all refuse with a notice instead. Best-effort: never
+  // let this block or crash daemon boot (per-call systemctl timeouts plus one
+  // cumulative pass deadline). The unit search root is the LOGIN user's home
+  // (where systemd user units live), never the daemon data home
+  // (GOODVIBES_DAEMON_HOME); the tracked name honors service.serviceName. The
+  // endpoint requirement uses the CLIENT view of the config — a fresh read of
+  // settings.json with none of this process's runtime flag overrides — because
+  // that is what clients resolve when they look for the daemon.
+  try {
+    const clientViewConfig = new ConfigManager({ workingDir, homeDir: homeDirectory, surfaceRoot: 'tui' });
+    const clientEndpoint = resolveRuntimeEndpointBinding(clientViewConfig, 'controlPlane');
+    const reconcile = await reconcileRedundantLegacyUnit({
+      homeDir: homedir(),
+      trackedServiceName: resolveConfiguredServiceName(clientViewConfig),
+      configuredEndpoint: { host: clientEndpoint.host, port: clientEndpoint.port },
+    });
+    if (reconcile.action !== 'noop') {
+      for (const line of reconcile.lines) {
+        // eslint-disable-next-line no-console
+        console.log(line);
+      }
+    }
+    if (reconcile.reason !== 'no-legacy-unit') {
+      // Breadcrumb for EVERY outcome where a legacy unit file exists —
+      // including guard refusals — so a persisting two-unit state is never
+      // silent about why nothing was reconciled.
+      logger.info('daemon: legacy-unit reconcile', { action: reconcile.action, reason: reconcile.reason });
+    }
+  } catch (error) {
+    logger.warn('daemon: legacy-unit reconcile failed (non-fatal)', { error: summarizeError(error) });
+  }
+
   // Print a device-pairing QR to stdout. The QR encodes the canonical
   // `#pair=<token>` deep link the web app consumes — a camera scan opens it
   // already signed in. No raw JSON connection blob is printed. This is also the