feat(voice): play status cues while working or waiting

src-tauri/crates/berd-voice/PROTOCOL.md

@@ -3,8 +3,10 @@
 `berd-voice session` is a development, full-authority voice session. The child
 owns speech recognition, finalized-input order, confirmation, speak admission,
 synthesis, source-frame delivery, playback lifecycle, and barge-in. The parent
-owns capture and playback devices: it writes normalized microphone PCM on stdin
-and consumes synthesized PCM from a dedicated inherited pipe. The child writes
+owns capture and conversational playback devices: it writes normalized microphone PCM on
+stdin and consumes synthesized PCM from a dedicated inherited pipe. Status cues are
+the narrow exception: the child plays them on the output-device name supplied by the
+parent, or the system default when none is supplied. The child writes
 flushed JSONL events to stdout. Diagnostics go only to stderr.
 
 ## Startup
@@ -44,17 +46,19 @@ remain terminal speech events.
 has no device-owning or stdout-multiplexed fallback.
 
 The first request must be `hello`. `input_during_tts` is the host's resolved
-initial policy; a host-specific `auto` mode must be resolved before the request:
+initial policy; a host-specific `auto` mode must be resolved before the request.
+`status_sound_output_device` is the host's selected playback-device name; omitting it uses the system default:
 
 ```json
-{"type":"hello","id":1,"input_during_tts":"allow_barge_in"}
+{"type":"hello","id":1,"input_during_tts":"allow_barge_in","status_sound_output_device":"MacBook Pro Speakers"}
 ```
 
-The response uses `protocol:4` as the exact session message-set version. The
-parent must reject a version it does not support:
+The response uses `protocol:5` as the exact session message-set version. The
+parent must reject a version it does not support; the JSON version is independent
+of the fixed binary framing marker described below:
 
 ```json
-{"type":"ready","id":1,"protocol":4,"session":{"tts":{"revision":1,"backend":"siri","voice":"Aaron","language":"en-US","rate":1.0},"input_during_tts":{"revision":1,"policy":"allow_barge_in"}}}
+{"type":"ready","id":1,"protocol":5,"session":{"tts":{"revision":1,"backend":"siri","voice":"Aaron","language":"en-US","rate":1.0},"input_during_tts":{"revision":1,"policy":"allow_barge_in"}}}
 ```
 
 The `session.tts` object is the authoritative, sanitized TTS configuration.
@@ -64,7 +68,9 @@ and `rate`. Credentials, endpoints, and bundle paths never appear on stdout.
 Detailed backend errors are diagnostics on stderr only; protocol rejection and
 fatal messages are sanitized at the stdout boundary.
 `session.input_during_tts` is the authoritative effective assistant-input
-policy and has its own revision.
+policy and has its own revision. Status-sound settings are per-update parameters,
+not session snapshot configuration. The runtime owns cue cadence and playback; it
+does not persist preferences.
 
 ## Stdin framing
 
@@ -179,9 +185,10 @@ it never admits a replacement while old host audio may still be active.
 ## Parent requests
 
 ```text
-{"type":"hello","id":u64,"input_during_tts":"allow_barge_in"|"suppress_input"}
+{"type":"hello","id":u64,"input_during_tts":"allow_barge_in"|"suppress_input","status_sound_output_device":string?}
 {"type":"set_paused","active":bool}
 {"type":"set_input_muted","id":u64,"active":bool}
+{"type":"set_conversation_status","id":u64,"status":"working"|"waiting","settings":StatusSoundSettings}
 {"type":"set_tts_settings","id":u64,"expected_revision":u64,"settings":TtsSettings}
 {"type":"set_input_during_tts","id":u64,"expected_revision":u64,"policy":"allow_barge_in"|"suppress_input"}
 {"type":"reset_input","id":u64}
@@ -198,6 +205,12 @@ Unknown fields are rejected. IDs are positive. Speak text is at most 16 KiB.
 The parent cannot author speaking state or finalized input; those are derived
 only from PCM by the child runtime.
 
+`StatusSoundSettings` has a `mode` of `off`, `working`, or `working-and-waiting` and an optional per-session `volume` from 0 to 1 that defaults to `0.8`. No cue is emitted until the first `set_conversation_status` request. Cues play immediately on status transitions and repeat every five seconds; repeated identical updates preserve the cadence. After conversation audio ends, the current cue resumes immediately. `off` disables both cues; `working` repeats only the working cue and stays silent while waiting; `working-and-waiting` repeats the current working or waiting cue. Active user speech or assistant output suppresses playback without changing the working/waiting state. Pending recognition alone does not suppress playback. On macOS, working uses the system Pop sound and waiting uses Purr through the selected output device. The applied request is acknowledged with:
+
+```text
+{"type":"conversation_status_applied","id":u64,"status":"working"|"waiting","settings":StatusSoundSettings}
+```
+
 `set_tts_settings` accepts the same tagged public object projected by `ready`,
 without `revision`. It changes settings only for the already-active backend:
 

src-tauri/crates/berd-voice/README.md

@@ -18,8 +18,12 @@ Siri bridge emits normalized 48 kHz mono Float32 PCM without opening an audio
 device; the existing Berd Siri player and the CLI use the same decoder.
 
 `berd-voice session` exposes the development voice-session protocol documented
-in [PROTOCOL.md](PROTOCOL.md). Siri TTS and macOS speech recognition are the
-defaults:
+in [PROTOCOL.md](PROTOCOL.md). The host supplies persisted status-sound settings
+and semantic `working` / `waiting` updates through that protocol; the runtime
+owns the five-second cadence, speech suppression, and macOS Pop/Purr playback.
+The default mode is `working`; `working-and-waiting` also plays idle cues, and `off` disables both. Status sounds default to a gain of `0.8`. Cues play immediately on a status transition and repeat every five seconds. When conversation audio ends, the current cue resumes immediately. Repeated identical status updates preserve the cadence. The host determines when work begins; the chained client signals working on its first live tool call and stays working until the run ends.
+
+Siri TTS and macOS speech recognition are the defaults:
 
 ```text
 berd-voice session --voice Aaron --language en-US --rate 1.0

src-tauri/crates/berd-voice/native/siri_tts_bridge.h

@@ -101,6 +101,16 @@ bool berd_siri_tts_speak(
     char **error_out
 );
 
+/// Decodes an audio file through AVFoundation into malloc-owned mono Float32 PCM.
+/// The caller releases successful samples with `berd_audio_free_samples`.
+float *berd_audio_file_load_mono_pcm(
+    const char *path,
+    uint32_t *sample_rate_out,
+    uint32_t *frame_count_out,
+    char **error_out
+);
+void berd_audio_free_samples(float *samples);
+
 /// Opaque Pocket PCM player backed by AVAudioUnitTimePitch. Samples are
 /// mono, noninterleaved float PCM. Device ID 0 uses the system default.
 void *berd_pocket_audio_player_create(

src-tauri/crates/berd-voice/native/siri_tts_bridge.m

@@ -1604,6 +1604,99 @@ bool berd_siri_tts_speak(
     }
 }
 
+float *berd_audio_file_load_mono_pcm(
+    const char *pathValue,
+    uint32_t *sampleRateOut,
+    uint32_t *frameCountOut,
+    char **errorOut
+) {
+    @autoreleasepool {
+        if (errorOut) *errorOut = NULL;
+        if (!pathValue || !sampleRateOut || !frameCountOut) {
+            BerdSetError(errorOut, BerdError(38, @"An audio path and output pointers are required."));
+            return NULL;
+        }
+        NSURL *url = [NSURL fileURLWithPath:[NSString stringWithUTF8String:pathValue]];
+        ExtAudioFileRef file = NULL;
+        OSStatus status = ExtAudioFileOpenURL((__bridge CFURLRef)url, &file);
+        if (status != noErr || !file) {
+            BerdSetError(errorOut, BerdError(39, @"Could not open the audio file."));
+            return NULL;
+        }
+        AudioStreamBasicDescription sourceFormat = {0};
+        UInt32 propertySize = sizeof(sourceFormat);
+        status = ExtAudioFileGetProperty(
+            file, kExtAudioFileProperty_FileDataFormat, &propertySize, &sourceFormat);
+        SInt64 sourceFrames = 0;
+        propertySize = sizeof(sourceFrames);
+        if (status == noErr) {
+            status = ExtAudioFileGetProperty(
+                file, kExtAudioFileProperty_FileLengthFrames, &propertySize, &sourceFrames);
+        }
+        AudioStreamBasicDescription clientFormat = {0};
+        clientFormat.mSampleRate = sourceFormat.mSampleRate;
+        clientFormat.mFormatID = kAudioFormatLinearPCM;
+        clientFormat.mFormatFlags = kAudioFormatFlagsNativeFloatPacked;
+        uint32_t channelCount = sourceFormat.mChannelsPerFrame;
+        clientFormat.mBytesPerPacket = sizeof(float) * channelCount;
+        clientFormat.mFramesPerPacket = 1;
+        clientFormat.mBytesPerFrame = sizeof(float) * channelCount;
+        clientFormat.mChannelsPerFrame = channelCount;
+        clientFormat.mBitsPerChannel = 8 * sizeof(float);
+        if (status == noErr) {
+            status = ExtAudioFileSetProperty(
+                file, kExtAudioFileProperty_ClientDataFormat,
+                sizeof(clientFormat), &clientFormat);
+        }
+        if (status != noErr || sourceFrames <= 0 || sourceFrames > UINT32_MAX) {
+            ExtAudioFileDispose(file);
+            BerdSetError(errorOut, BerdError(40, @"Could not prepare the audio file for decoding."));
+            return NULL;
+        }
+        uint32_t capacity = (uint32_t)sourceFrames;
+        float *samples = malloc((size_t)capacity * channelCount * sizeof(float));
+        if (!samples) {
+            ExtAudioFileDispose(file);
+            BerdSetError(errorOut, BerdError(41, @"Could not allocate decoded audio samples."));
+            return NULL;
+        }
+        uint32_t frameCount = 0;
+        while (frameCount < capacity) {
+            UInt32 requestedFrames = capacity - frameCount;
+            AudioBufferList buffers = {0};
+            buffers.mNumberBuffers = 1;
+            buffers.mBuffers[0].mNumberChannels = channelCount;
+            buffers.mBuffers[0].mDataByteSize = requestedFrames * channelCount * sizeof(float);
+            buffers.mBuffers[0].mData = samples + ((size_t)frameCount * channelCount);
+            status = ExtAudioFileRead(file, &requestedFrames, &buffers);
+            if (status != noErr || requestedFrames == 0) break;
+            frameCount += requestedFrames;
+        }
+        ExtAudioFileDispose(file);
+        if (status != noErr || frameCount != capacity) {
+            free(samples);
+            BerdSetError(errorOut, BerdError(42, @"Could not decode the audio file."));
+            return NULL;
+        }
+        if (channelCount > 1) {
+            for (uint32_t frame = 0; frame < frameCount; frame++) {
+                float mixed = 0;
+                for (uint32_t channel = 0; channel < channelCount; channel++) {
+                    mixed += samples[frame * channelCount + channel];
+                }
+                samples[frame] = mixed / channelCount;
+            }
+        }
+        *sampleRateOut = (uint32_t)clientFormat.mSampleRate;
+        *frameCountOut = frameCount;
+        return samples;
+    }
+}
+
+void berd_audio_free_samples(float *samples) {
+    free(samples);
+}
+
 void *berd_pocket_audio_player_create(
     uint32_t sampleRate,
     float rate,

src-tauri/crates/berd-voice/src/lib.rs

@@ -32,6 +32,7 @@ pub mod realtime_pipe;
 pub mod session;
 pub mod siri;
 pub mod spokesperson_voice_update;
+mod status_sounds;
 mod synthesis;
 mod tts;
 
@@ -54,6 +55,11 @@ pub use pocket::{
 };
 #[cfg(target_os = "macos")]
 pub use siri::SiriTts;
+pub use status_sounds::ConversationStatus;
+pub use status_sounds::ManagedStatusSoundRuntime;
+pub use status_sounds::StatusSoundMode;
+pub use status_sounds::StatusSoundRuntime;
+pub use status_sounds::StatusSoundSettings;
 pub use synthesis::{synthesize_pcm16_wav, WavSynthesis, WavSynthesisError, WavSynthesisErrorKind};
 pub use tts::{
     OpenAiTts, PocketTtsBackend, StreamingTextChunk, StreamingTextChunks, StreamingTtsText,

src-tauri/crates/berd-voice/src/macos_audio_output.rs

@@ -1,10 +1,17 @@
-//! Safe ownership wrapper for the shared macOS AVAudioUnitTimePitch PCM player.
+//! Safe wrappers for the shared macOS audio FFI boundary.
 
 use std::ffi::{c_char, c_void, CStr};
 
 use crate::PcmAudioOutput;
 
 unsafe extern "C" {
+    fn berd_audio_file_load_mono_pcm(
+        path: *const c_char,
+        sample_rate_out: *mut u32,
+        frame_count_out: *mut u32,
+        error_out: *mut *mut c_char,
+    ) -> *mut f32;
+    fn berd_audio_free_samples(samples: *mut f32);
     fn berd_pocket_audio_player_create(
         sample_rate: u32,
         rate: f32,
@@ -25,6 +32,30 @@ unsafe extern "C" {
     fn berd_siri_tts_free_string(value: *mut c_char);
 }
 
+pub(crate) fn load_mono_audio_file(path: &str) -> Result<(u32, Vec<f32>), String> {
+    let path = std::ffi::CString::new(path).map_err(|_| "audio path contains NUL".to_string())?;
+    let mut sample_rate = 0;
+    let mut frame_count = 0;
+    let mut error = std::ptr::null_mut();
+    // SAFETY: The bridge copies the path and returns an owned allocation with
+    // the reported frame count, released below by its paired free function.
+    let raw = unsafe {
+        berd_audio_file_load_mono_pcm(
+            path.as_ptr(),
+            &mut sample_rate,
+            &mut frame_count,
+            &mut error,
+        )
+    };
+    if raw.is_null() {
+        return Err(take_error(error, "Could not decode audio file"));
+    }
+    // SAFETY: A successful bridge call returns exactly `frame_count` initialized samples.
+    let samples = unsafe { std::slice::from_raw_parts(raw, frame_count as usize) }.to_vec();
+    unsafe { berd_audio_free_samples(raw) };
+    Ok((sample_rate, samples))
+}
+
 pub struct PocketAudioPlayer {
     raw: *mut c_void,
     delivery_safety_frames: u64,