@pellux/goodvibes-agent 1.5.8 → 1.6.0

package/docs/README.md

@@ -1,6 +1,6 @@
 # GoodVibes Agent Docs
 
-These are the package-facing docs for the GoodVibes Agent `1.5.x` release line.
+These are the package-facing docs for the GoodVibes Agent `1.6.x` release line.
 
 ## Current Docs
 

package/docs/voice-and-live-tts.md

@@ -53,3 +53,50 @@ Leaving `tts.voice` empty lets the provider choose its default voice.
 Spoken responses are conversation output. They are not automatically written to Agent Knowledge, local memory, default knowledge, or any other product segment.
 
 If a spoken result should become durable, store it through an explicit Agent memory command or an Agent Knowledge ingestion path.
+
+## Platform Voice-Config Cohesion
+
+The `tts.*` config keys (`tts.provider`, `tts.voice`, `tts.speed`, `tts.llmProvider`,
+`tts.llmModel`) are defined once, in the shared GoodVibes SDK config schema, and read
+identically by every surface — Agent, TUI, and the daemon. Agent does not define its
+own voice-config schema and does not read tts.* through any path other than the
+standard `ConfigManager.get`/`set` API that every other Agent setting uses. Changing
+`tts.provider` through `/config tts.provider` or `settings action:"set"` changes the
+exact same key a TUI user would change through its own `/config` surface — the
+key name, type, and default are one contract, not two independently-maintained ones.
+`src/test/audio/voice-config-cohesion.test.ts` is the regression guard: it fails if
+the Agent ever reads a tts.* key that isn't in the shared schema, or if a tts.*
+reader stops importing `ConfigManager` from the shared SDK package.
+
+What "shared" does **not** mean here: each surface still persists its *values* to its
+own settings file (Agent's under its own surface root, TUI's under its own) — that is
+the existing, general-purpose per-surface config storage model, not something voice-
+specific, and changing it is out of scope for this ruling. "Shared" means the
+schema/contract (the key names, types, and defaults) is one definition used by every
+surface, so the same key always means the same thing and takes the same kind of
+value everywhere — a user (or an operator script) setting `tts.voice` on one surface
+is setting the same conceptual value the other surfaces would read under that name,
+even though each surface keeps its own copy of the setting today.
+
+Two related rulings, made for this parity pass:
+
+- **Local synthesis stays local.** Agent synthesizes speech directly against the
+  configured provider (through the shared `VoiceService`/`VoiceProviderRegistry`) via
+  a local `mpv`/`ffplay` subprocess, rather than routing playback through the daemon's
+  `voice.tts`/`voice.tts.stream` HTTP routes. This is deliberate, not an oversight:
+  Agent is a terminal tool that must keep working when there is no daemon running
+  (offline use), so voice output cannot depend on a daemon round-trip. The daemon's
+  voice routes exist for network consumers (the web UI); Agent's local-first design
+  is the reason it doesn't use them, and the config it reads to pick a provider is
+  still the one shared contract described above.
+- **Mic/STT input is an honest no-op in Agent, not a gap.** Agent has no
+  `getUserMedia`-equivalent microphone capture and does not call `voice.stt` or
+  `voice.realtime.session`. This is by design: Agent is a terminal application with
+  keyboard/text as its primary input surface, and the web UI is the platform's
+  intended owner of mic-based voice input (browser `getUserMedia`/`MediaRecorder`).
+  Agent already reports this honestly rather than implying a capability that doesn't
+  exist — see the wake-word/always-listening `not-published` posture described above,
+  which applies to mic input broadly, not only wake-word. If a future certified,
+  permission-scoped mic contract is published for terminal surfaces, this ruling is
+  the one to revisit; until then, building a partial mic flow in Agent would be
+  worse than not building one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.5.8",
+  "version": "1.6.0",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",
@@ -92,7 +92,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@pellux/goodvibes-sdk": "1.0.0",
+    "@pellux/goodvibes-sdk": "1.3.1",
     "sql.js": "^1.14.1",
     "sqlite-vec": "^0.1.9",
     "zustand": "^5.0.12",

package/src/agent/memory-prompt.ts

@@ -149,11 +149,22 @@ export interface BuildReviewedMemoryPromptOptions {
   /** The current turn's raw text (the seam this comes from: TURN_SUBMITTED's `prompt`).
    *  Used only to RANK the already-eligible set — never to admit an otherwise-ineligible record. */
   readonly turnText?: string | null;
+  /**
+   * Pre-fetched record set to use instead of `memoryRegistry.getAll()` — e.g. a
+   * memory-spine recall snapshot's records (SDK 1.2.0 sync-recall seam; see
+   * prompt-context-receipts.ts's `resolveMemoryRecords`). `memoryRegistry` is still
+   * used for the per-turn semantic ranking query (`rankMemoryForTurn`'s
+   * `vectorStats`/`searchSemantic` calls stay local-direct regardless of where the
+   * record set came from) — only the raw eligible set that ranking runs OVER is
+   * swappable, so the injected prompt text and any receipt describing it are always
+   * derived from the exact same record set instead of two independent reads.
+   */
+  readonly records?: readonly MemoryRecord[];
 }
 
 export function buildReviewedMemoryPrompt(memoryRegistry: MemoryRegistry, options: BuildReviewedMemoryPromptOptions = {}): string | null {
   const limit = options.limit ?? DEFAULT_LIMIT;
-  const eligible = memoryRegistry.getAll().filter(isPromptActiveMemory);
+  const eligible = (options.records ?? memoryRegistry.getAll()).filter(isPromptActiveMemory);
   const ranking = rankMemoryForTurn(memoryRegistry, eligible, options.turnText);
   const records = ranking.records.slice(0, Math.max(0, limit));
 

package/src/agent/prompt-context-receipts.ts

@@ -1,7 +1,8 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { dirname } from 'node:path';
-import type { MemoryRegistry } from '@pellux/goodvibes-sdk/platform/state';
+import type { MemoryRecord, MemoryRegistry } from '@pellux/goodvibes-sdk/platform/state';
+import type { MemoryRecallSnapshot } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
 import { getTierForContextWindow, getTierPromptSupplement } from '@pellux/goodvibes-sdk/platform/providers';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { buildReviewedMemoryPrompt, describeMemoryPromptEligibility, isPromptActiveMemory, rankMemoryForTurn, relevanceBand } from './memory-prompt.ts';
@@ -77,6 +78,26 @@ export interface RuntimePromptCompositionInput {
    *  already-eligible memory set by relevance to this turn — see rankMemoryForTurn.
    *  Null/undefined when there is no active turn (e.g. a follow-up composition). */
   readonly turnText?: string | null;
+  /**
+   * The memory spine's cached recall snapshot (SDK 1.2.0 sync-recall seam), when the
+   * caller has one to offer.
+   *
+   * SYNC-RECALL SEAM (memory-spine full-detach adoption, SDK 1.2.0): this function is
+   * called synchronously from the SDK's `Orchestrator.getSystemPrompt` callback, which
+   * the SDK defines as non-async, while a wire client's memory reads are async. Rather
+   * than reading `memoryRegistry.getAll()` directly (a frozen local snapshot that would
+   * silently miss whatever the daemon wrote after this process last opened its own
+   * copy — the exact failure the 1.1.0-era `memorySpineMode` degrade note used to flag),
+   * the caller drives an ASYNC pre-turn hook (`MemorySpineClient.refreshRecallSnapshot`)
+   * and passes the resulting freshness-stamped `MemoryRecallSnapshot` in here. When
+   * present, its `records` (captured with `{ recall: false }` — an unfiltered browse
+   * set, matching the old `getAll()` semantics exactly) replace the direct registry
+   * read, and its own honest `stale`/`mode`/`note` fields drive the 'memory' receipt
+   * segment's note instead of the old blanket "client mode is always degraded" note.
+   * `undefined` falls back to reading `memoryRegistry` directly (e.g. a caller that
+   * has not wired the spine, or an existing test) — the pre-1.2.0 behavior, unchanged.
+   */
+  readonly memoryRecallSnapshot?: MemoryRecallSnapshot;
 }
 
 const RECEIPT_STORE_LIMIT = 200;
@@ -104,6 +125,29 @@ function joinPromptParts(...parts: Array<string | null | undefined>): string {
   return parts.map((part) => part?.trim()).filter((part): part is string => Boolean(part)).join('\n\n');
 }
 
+/**
+ * The honest freshness note for the 'memory' receipt segment, sourced from the
+ * memory spine's own recall snapshot (see RuntimePromptCompositionInput.
+ * memoryRecallSnapshot). Surfaced only when there is something worth flagging —
+ * the snapshot came from a wire-adopted daemon (worth knowing regardless of
+ * freshness, since the wire's own copy is what was captured, not this process's),
+ * or the snapshot is stale (including "never yet captured", which the snapshot
+ * itself always reports as stale). `undefined` for the boring common case (local
+ * mode, freshly captured) — matching the pre-1.2.0 note's "nothing to degrade"
+ * behavior — or when the caller passed no snapshot at all.
+ */
+function memoryRecallSnapshotNote(snapshot: MemoryRecallSnapshot | undefined): string | undefined {
+  if (!snapshot) return undefined;
+  if (snapshot.mode !== 'client' && !snapshot.stale) return undefined;
+  return snapshot.note;
+}
+
+/** Combines up to two optional short notes with a single separator; undefined when both are absent. */
+function combineNotes(first: string | null | undefined, second: string | null | undefined): string | undefined {
+  const parts = [first, second].map((part) => part?.trim()).filter((part): part is string => Boolean(part));
+  return parts.length > 0 ? parts.join(' — also: ') : undefined;
+}
+
 function modelLabel(model: unknown): string {
   if (typeof model === 'string' && model.trim()) return model.trim();
   if (typeof model === 'object' && model !== null) {
@@ -138,6 +182,18 @@ function receiptSegment(input: Omit<PromptContextReceiptSegment, 'approxTokens'>
   };
 }
 
+/**
+ * Read via the memory spine's cached recall snapshot when the caller has one (SDK
+ * 1.2.0 sync-recall seam — see RuntimePromptCompositionInput.memoryRecallSnapshot);
+ * fall back to the direct registry read otherwise (unchanged pre-1.2.0 behavior).
+ * Shared by the prompt text build and the receipt segment build so both derive
+ * from the exact same record set — the receipt must describe what was actually
+ * injected, never a different snapshot than the prompt text itself used.
+ */
+function resolveMemoryRecords(input: RuntimePromptCompositionInput): readonly MemoryRecord[] {
+  return input.memoryRecallSnapshot ? input.memoryRecallSnapshot.records : input.memoryRegistry.getAll();
+}
+
 function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput): readonly PromptContextReceiptSegment[] {
   const vibe = discoverVibeFiles(input.shellPaths);
   // The VIBE prompt is a PROJECTION of persona/constraint records, not a
@@ -145,13 +201,13 @@ function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput)
   const vibePrompt = buildVibeProjectionPrompt(input.memoryRegistry) ?? '';
   const projectContext = discoverProjectContextFiles(input.shellPaths);
   const projectContextPrompt = buildProjectContextPrompt(input.shellPaths) ?? '';
-  const memoryRecords = input.memoryRegistry.getAll();
+  const memoryRecords = resolveMemoryRecords(input);
   const eligibleMemory = memoryRecords.filter(isPromptActiveMemory);
   const memoryRanking = rankMemoryForTurn(input.memoryRegistry, eligibleMemory, input.turnText);
   const activeMemory = memoryRanking.records.slice(0, 10);
   const activeMemoryIds = new Set(activeMemory.map((record) => record.id));
   const suppressedMemory = memoryRecords.filter((record) => !activeMemoryIds.has(record.id));
-  const memoryPrompt = buildReviewedMemoryPrompt(input.memoryRegistry, { turnText: input.turnText }) ?? '';
+  const memoryPrompt = buildReviewedMemoryPrompt(input.memoryRegistry, { turnText: input.turnText, records: memoryRecords }) ?? '';
   const routineSnapshot = AgentRoutineRegistry.fromShellPaths(input.shellPaths).snapshot();
   const activeRoutines = routineSnapshot.enabledRoutines.filter((routine) => routine.reviewState === 'reviewed' && evaluateAgentRoutineReadiness(routine).ready);
   const suppressedRoutines = routineSnapshot.enabledRoutines.filter((routine) => !activeRoutines.some((active) => active.id === routine.id));
@@ -237,8 +293,17 @@ function buildRuntimePromptReceiptSegments(input: RuntimePromptCompositionInput)
       // Honest degrade note: when per-turn relevance scoring did not
       // run — no active-turn text, semantic index unavailable, or no vector match —
       // say so instead of silently presenting the fallback confidence/recency order as
-      // if it were a relevance ranking.
-      note: memoryRanking.scored ? undefined : (memoryRanking.degradedReason ?? undefined),
+      // if it were a relevance ranking. Combined with the memory spine's own
+      // freshness note (see memoryRecallSnapshotNote) when the recall snapshot is
+      // wire-sourced or stale — the ranking itself still runs against
+      // `input.memoryRegistry` directly (rankMemoryForTurn's per-turn semantic query
+      // needs a live vectorStats/searchSemantic call, which stays local-direct by the
+      // same vector-diagnostics ruling used elsewhere in the 1.2.0 adoption), so this
+      // note is about the RECORD SET's freshness, not the ranking.
+      note: combineNotes(
+        memoryRanking.scored ? undefined : memoryRanking.degradedReason,
+        memoryRecallSnapshotNote(input.memoryRecallSnapshot),
+      ),
       selected: activeMemory.map((record) => ({
         id: record.id,
         scope: record.scope,
@@ -346,7 +411,7 @@ export function composeRuntimePromptWithReceipt(input: RuntimePromptCompositionI
     buildVibeProjectionPrompt(input.memoryRegistry),
     buildProjectContextPrompt(input.shellPaths),
     input.operatorPolicy,
-    buildReviewedMemoryPrompt(input.memoryRegistry, { turnText: input.turnText }),
+    buildReviewedMemoryPrompt(input.memoryRegistry, { turnText: input.turnText, records: resolveMemoryRecords(input) }),
     buildEnabledRoutinesPrompt(input.shellPaths),
     buildEnabledSkillsPrompt(input.shellPaths),
     buildActivePersonaPrompt(input.shellPaths),

package/src/agent/vibe-file.ts

@@ -10,7 +10,11 @@ import { parseMarkdownFrontmatter, stripMarkdownFrontmatter } from './markdown-f
 // the same '## VIBE.md' block from those records (caveat preserved); the file is
 // demoted to an import/export FORMAT folded in via vibeBodyToConstraintOptions.
 import { renderVibeProjection, vibeBodyToConstraintOptions } from '@pellux/goodvibes-sdk/platform/state';
-import type { MemoryRecord, MemoryRegistry, MemoryScope } from '@pellux/goodvibes-sdk/platform/state';
+import type { MemoryRecord, MemoryScope } from '@pellux/goodvibes-sdk/platform/state';
+// Writes go through the memory-spine's MemoryAccess surface (add), not the raw
+// MemoryRegistry, so this import folds correctly whether the agent is local or has
+// adopted a daemon — see services.ts's memorySpineClient.
+import type { MemoryAccess } from '@pellux/goodvibes-sdk/platform/runtime/memory-spine';
 
 export type AgentVibeScope = 'project' | 'global';
 
@@ -235,7 +239,7 @@ export function buildVibeProjectionPrompt(memoryRecords: { getAll(): readonly Me
  * this as a one-time migration, not every boot (mirrors the memory fold precedent).
  */
 export async function importVibeFilesIntoMemory(
-  memoryRegistry: MemoryRegistry,
+  memorySpine: MemoryAccess,
   shellPaths: AgentVibePaths,
 ): Promise<number> {
   const snapshot = discoverVibeFiles(shellPaths);
@@ -249,7 +253,7 @@ export async function importVibeFilesIntoMemory(
       sourceRef: file.path,
     });
     for (const opts of options) {
-      await memoryRegistry.add(opts);
+      await memorySpine.add(opts);
       created += 1;
     }
   }
@@ -306,7 +310,7 @@ function hashVibeBody(body: string): string {
  * Returns the number of records created this run (0 when everything is already migrated).
  */
 export async function importVibeFilesIntoMemoryOnce(
-  memoryRegistry: MemoryRegistry,
+  memorySpine: MemoryAccess,
   shellPaths: AgentVibePaths,
 ): Promise<number> {
   const markerPath = vibeImportMarkerPath(shellPaths);
@@ -326,7 +330,7 @@ export async function importVibeFilesIntoMemoryOnce(
       sourceRef: file.path,
     });
     for (const opts of options) {
-      await memoryRegistry.add(opts);
+      await memorySpine.add(opts);
       created += 1;
     }
     marker.migrated[key] = hash;

package/src/audio/player.ts

@@ -15,6 +15,14 @@ export interface StreamingAudioPlayer {
   readonly available: boolean;
   play(chunks: AsyncIterable<VoiceAudioChunk>, options: StreamingAudioPlaybackOptions): Promise<void>;
   stop(): void;
+  /**
+   * Resolves once the currently playing sink has finished naturally (its
+   * process closed) or after `timeoutMs`, whichever comes first; resolves
+   * immediately when nothing is playing. The exit path uses this to let the
+   * audio the user is already hearing finish inside a short bounded window
+   * instead of killing it mid-drain. stop() remains the instant cut.
+   */
+  waitForDrain(timeoutMs: number): Promise<void>;
 }
 
 export interface StreamingAudioPlaybackOptions {
@@ -25,6 +33,8 @@ export interface StreamingAudioPlaybackOptions {
 interface SpawnProcess {
   readonly stdin: Writable;
   once(event: 'close', listener: () => void): this;
+  once(event: 'spawn', listener: () => void): this;
+  once(event: 'error', listener: (error: unknown) => void): this;
   kill(signal?: NodeJS.Signals | number): boolean;
 }
 type SpawnProcessFactory = (command: string, args: readonly string[]) => SpawnProcess;
@@ -32,6 +42,13 @@ type SpawnProcessFactory = (command: string, args: readonly string[]) => SpawnPr
 export interface LocalStreamingAudioPlayerOptions {
   readonly env?: NodeJS.ProcessEnv;
   readonly spawnProcess?: SpawnProcessFactory;
+  /**
+   * Injected player command — the test seam companion to `spawnProcess`.
+   * When set, the constructor uses it verbatim instead of scanning PATH, so
+   * deterministic fake-sink tests never depend on mpv/ffplay being installed
+   * on the machine running them. Pass null to model "no player found".
+   */
+  readonly command?: StreamingAudioPlayerCommand | null;
 }
 
 export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
@@ -40,7 +57,9 @@ export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
   private readonly spawnProcess: SpawnProcessFactory;
 
   constructor(options: LocalStreamingAudioPlayerOptions = {}) {
-    this.command = resolveStreamingAudioPlayerCommand(options.env ?? process.env);
+    this.command = options.command !== undefined
+      ? options.command
+      : resolveStreamingAudioPlayerCommand(options.env ?? process.env);
     this.spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
   }
 
@@ -67,12 +86,27 @@ export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
     options.signal?.addEventListener('abort', abort, { once: true });
 
     try {
+      // Head survival: hold the first audio byte until the sink has actually
+      // started (its 'spawn' event) instead of writing into a process that has
+      // not exec'd yet. Writing before the player is up is the spawn race that
+      // clipped the beginning of playback. A spawn failure rejects here so the
+      // caller can report it honestly rather than swallowing a dead player.
+      await awaitReady(proc, options.signal);
+      if (options.signal?.aborted) return;
+
       for await (const chunk of chunks) {
         if (options.signal?.aborted) break;
         if (chunk.data.byteLength === 0) continue;
         await writeStdin(proc, chunk.data);
       }
-      proc.stdin.end();
+
+      // An intentional interrupt (turn cancel / quit chord / /tts stop) has
+      // already torn the process down via `abort` and must cut immediately —
+      // do not wait on a graceful drain. A natural end-of-speech, by contrast,
+      // closes stdin and waits for the sink to play out every buffered sample
+      // so the tail of the response is never truncated.
+      if (options.signal?.aborted) return;
+      try { proc.stdin.end(); } catch { /* ignore */ }
       await waitForExit(proc);
     } finally {
       options.signal?.removeEventListener('abort', abort);
@@ -87,14 +121,33 @@ export class LocalStreamingAudioPlayer implements StreamingAudioPlayer {
     try { proc.stdin.destroy(); } catch { /* ignore */ }
     try { proc.kill('SIGTERM'); } catch { /* ignore */ }
   }
+
+  waitForDrain(timeoutMs: number): Promise<void> {
+    const proc = this.activeProcess;
+    if (!proc) return Promise.resolve();
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(settle, timeoutMs);
+      proc.once('close', settle);
+    });
+  }
 }
 
 export function resolveStreamingAudioPlayerCommand(env: NodeJS.ProcessEnv = process.env): StreamingAudioPlayerCommand | null {
   const mpv = findExecutable('mpv', env);
   if (mpv) {
+    // No --cache=no: mpv's read-ahead cache buffers the incoming pipe so the
+    // opening audio survives device-open latency and network jitter instead of
+    // underrunning while the output device is still spinning up.
     return {
       command: mpv,
-      args: ['--no-terminal', '--really-quiet', '--force-window=no', '--cache=no', '-'],
+      args: ['--no-terminal', '--really-quiet', '--force-window=no', '-'],
       label: 'mpv',
     };
   }
@@ -102,18 +155,51 @@ export function resolveStreamingAudioPlayerCommand(env: NodeJS.ProcessEnv = proc
   if (ffplay) {
     return {
       command: ffplay,
-      args: ['-nodisp', '-autoexit', '-loglevel', 'error', '-i', 'pipe:0'],
+      args: FFPLAY_BASE_ARGS,
       label: 'ffplay',
     };
   }
   return null;
 }
 
+// ffplay -autoexit quits as soon as its input ends, before the audio output
+// buffer has drained — that clips the tail of the response. `apad` appends a
+// short run of silence so the real audio is fully played out and only the
+// trailing silence gets trimmed.
+const FFPLAY_APAD = ['-af', 'apad=pad_dur=0.3'] as const;
+const FFPLAY_BASE_ARGS = ['-nodisp', '-autoexit', '-loglevel', 'error', ...FFPLAY_APAD, '-i', 'pipe:0'] as const;
+
 function buildPlayerArgs(command: StreamingAudioPlayerCommand, format?: string): readonly string[] {
   if (command.label !== 'ffplay' || !format) return command.args;
   const normalized = format.trim().toLowerCase();
   if (!normalized || normalized.includes('/')) return command.args;
-  return ['-nodisp', '-autoexit', '-loglevel', 'error', '-f', normalized, '-i', 'pipe:0'];
+  return ['-nodisp', '-autoexit', '-loglevel', 'error', ...FFPLAY_APAD, '-f', normalized, '-i', 'pipe:0'];
+}
+
+/**
+ * awaitReady — resolves once the spawned player has actually started (its
+ * 'spawn' event), rejects if it fails to start ('error'), and resolves early
+ * if the caller aborts during startup so an intentional interrupt is never
+ * blocked. This is the readiness gate that keeps the first audio byte from
+ * being written into a not-yet-running sink.
+ */
+function awaitReady(proc: SpawnProcess, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const settle = (action: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener('abort', onAbort);
+      action();
+    };
+    const onSpawn = () => settle(resolve);
+    const onError = (error: unknown) => settle(() => reject(error instanceof Error ? error : new Error(String(error))));
+    const onAbort = () => settle(resolve);
+    proc.once('spawn', onSpawn);
+    proc.once('error', onError);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
 }
 
 function findExecutable(name: string, env: NodeJS.ProcessEnv): string | null {

package/src/audio/spoken-turn-wiring.ts

@@ -1,13 +1,17 @@
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import type { VoiceService } from '@pellux/goodvibes-sdk/platform/voice';
+import { SpokenTurnController } from '@pellux/goodvibes-sdk/platform/voice';
+import type { StreamingAudioPlayer } from './player.ts';
 import { LocalStreamingAudioPlayer } from './player.ts';
-import { SpokenTurnController } from './spoken-turn-controller.ts';
 
 export interface SpokenTurnRuntime {
   readonly unsubs: readonly (() => void)[];
   submitNextTurn(prompt: string): boolean;
-  stop(message?: string): void;
+  /** Returns whether speech was actually active (see controller.stop). */
+  stop(message?: string): boolean;
+  /** Exit-path stop: lets the audio already playing drain, bounded (see controller.stopForExit). */
+  stopForExit(drainTimeoutMs?: number): Promise<void>;
 }
 
 export interface WireSpokenTurnRuntimeOptions {
@@ -15,14 +19,21 @@ export interface WireSpokenTurnRuntimeOptions {
   readonly configManager: ConfigManager;
   readonly events: UiRuntimeEvents;
   readonly notify: (message: string) => void;
+  /**
+   * Optional player factory — injected in tests to avoid spawning real
+   * subprocesses. Defaults to LocalStreamingAudioPlayer.
+   */
+  readonly playerFactory?: () => StreamingAudioPlayer;
 }
 
 export function wireSpokenTurnRuntime(options: WireSpokenTurnRuntimeOptions): SpokenTurnRuntime {
+  const player = options.playerFactory ? options.playerFactory() : new LocalStreamingAudioPlayer();
   const controller = new SpokenTurnController({
     voiceService: options.voiceService,
     configManager: options.configManager,
-    player: new LocalStreamingAudioPlayer(),
+    sink: player,
     notify: options.notify,
+    source: 'goodvibes-agent',
   });
 
   const turns = options.events.turns;
@@ -40,5 +51,6 @@ export function wireSpokenTurnRuntime(options: WireSpokenTurnRuntimeOptions): Sp
     unsubs,
     submitNextTurn: (prompt) => controller.submitNextTurn(prompt),
     stop: (message) => controller.stop(message),
+    stopForExit: (drainTimeoutMs) => controller.stopForExit(drainTimeoutMs),
   };
 }