agent-cli 0.105.1__tar.gz → 0.106.0__tar.gz

{agent_cli-0.105.1 → agent_cli-0.106.0}/.github/workflows/docker.yml

@@ -49,7 +49,7 @@ jobs:
           fetch-depth: 0  # Full history for version detection
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to Container Registry
         uses: docker/login-action@v4.5.1
@@ -79,7 +79,7 @@ jobs:
             type=sha,suffix=-${{ matrix.suffix }}
 
       - name: Build and push
-        uses: docker/build-push-action@v7.3.0
+        uses: docker/build-push-action@v7.4.0
         with:
           context: .
           file: ${{ matrix.dockerfile }}
@@ -122,7 +122,7 @@ jobs:
           fetch-depth: 0  # Full history for version detection
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to Container Registry
         uses: docker/login-action@v4.5.1
@@ -152,7 +152,7 @@ jobs:
             type=sha
 
       - name: Build and push
-        uses: docker/build-push-action@v7.3.0
+        uses: docker/build-push-action@v7.4.0
         with:
           context: .
           file: ${{ matrix.dockerfile }}

{agent_cli-0.105.1 → agent_cli-0.106.0}/.github/workflows/pytest.yml

@@ -43,6 +43,6 @@ jobs:
         run: uv run --extra audio --extra diarization --extra llm --extra rag --extra memory --extra vad --extra faster-whisper --extra piper --extra kokoro --extra server --extra speed --extra test pytest -vvv
       - name: Upload coverage reports to Codecov
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
-        uses: codecov/codecov-action@v7.0.0
+        uses: codecov/codecov-action@v7.1.1
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

{agent_cli-0.105.1 → agent_cli-0.106.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-cli
-Version: 0.105.1
+Version: 0.106.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>

{agent_cli-0.105.1 → agent_cli-0.106.0}/agent_cli/agents/transcribe.py

@@ -477,6 +477,9 @@ async def _async_main(  # noqa: PLR0912, PLR0915, C901
                     live_preview_config=live_preview_config,
                 )
 
+        if transcript and not transcript.strip():
+            transcript = None
+
         elapsed = time.monotonic() - start_time
 
         # Apply diarization if enabled
@@ -554,6 +557,9 @@ async def _async_main(  # noqa: PLR0912, PLR0915, C901
                 live=live,
                 context=combined_context,
             )
+            if general_cfg.clipboard and not (processed_transcript or "").strip():
+                # Keep the raw speech recoverable if cleanup overwrote it with blank text.
+                pyperclip.copy(transcript)
 
             # Log transcription if requested
             if transcription_log:
@@ -615,6 +621,21 @@ async def _async_main(  # noqa: PLR0912, PLR0915, C901
     )
 
 
+def _require_transcript(result: TranscriptResult, provider: str) -> None:
+    """Do not report successful dictation when the backend produced no text."""
+    if not (result.get("transcript") or "").strip():
+        if result.get("raw_transcript"):
+            message = "LLM cleanup returned no text. Retry with --no-llm to use the raw transcript."
+        else:
+            message = f"No transcript returned by {provider}. Check the microphone and ASR server."
+        typer.echo(
+            f"{message} "
+            "If a recording was saved, retry with agent-cli transcribe --last-recording.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
 @app.command("transcribe", rich_help_panel="Voice Commands")
 @requires_extras("audio", "llm", process_name="transcribe")
 def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
@@ -896,6 +917,7 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
             LOGGER.exception("Diarization failed")
             _print_diarization_error(exc)
             raise typer.Exit(1) from None
+        _require_transcript(result, asr_provider)
         if json_output:
             print(json.dumps(result))
         return
@@ -937,6 +959,7 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
     ):
         return
 
+    result = TranscriptResult(raw_transcript=None, transcript=None, llm_enabled=False)
     # Use context manager before audio setup so --stop can target startup reliably.
     try:
         with process.pid_file_context(process_name), suppress(KeyboardInterrupt):
@@ -992,5 +1015,6 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
         LOGGER.exception("Diarization failed")
         _print_diarization_error(exc)
         raise typer.Exit(1) from None
+    _require_transcript(result, asr_provider)
     if json_output:
         print(json.dumps(result))

{agent_cli-0.105.1 → agent_cli-0.106.0}/agent_cli/core/audio_format.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import io
 import logging
 import shutil
@@ -152,13 +153,13 @@ def convert_audio_to_wyoming_format(
             output_path.unlink(missing_ok=True)
 
 
-def convert_audio_to_wav_format(
+async def convert_audio_to_wav_format(
     audio_data: bytes,
     source_filename: str,
     *,
-    timeout: int | None = 60,
+    timeout: int | None = 60,  # noqa: ASYNC109 - bounds and cleans up the child process
 ) -> bytes:
-    """Convert audio data to a 16kHz mono 16-bit PCM WAV container using FFmpeg."""
+    """Convert to 16kHz mono 16-bit WAV, stopping FFmpeg on cancellation or timeout."""
     if not shutil.which("ffmpeg"):
         msg = "FFmpeg not found in PATH. Please install FFmpeg to convert audio formats."
         raise RuntimeError(msg)
@@ -185,20 +186,23 @@ def convert_audio_to_wav_format(
         ]
 
         logger.debug("Running FFmpeg WAV conversion: %s", " ".join(cmd))
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
         try:
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=False,
-                check=False,
-                timeout=timeout,
-            )
-        except subprocess.TimeoutExpired as e:
+            _, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
+        except TimeoutError as e:
             msg = f"FFmpeg conversion timed out after {timeout} seconds"
             raise RuntimeError(msg) from e
+        finally:
+            if process.returncode is None:
+                process.kill()
+                await process.communicate()
 
-        if result.returncode != 0:
-            stderr_text = result.stderr.decode("utf-8", errors="replace")
+        if process.returncode != 0:
+            stderr_text = (stderr or b"").decode("utf-8", errors="replace")
             logger.error("FFmpeg WAV conversion failed: %s", stderr_text)
             msg = f"FFmpeg WAV conversion failed: {stderr_text}"
             raise RuntimeError(msg)

agent_cli-0.106.0/agent_cli/server/whisper/backends/audio.py

@@ -0,0 +1,44 @@
+"""Audio preparation for ASR backends that require PCM WAV input."""
+
+from __future__ import annotations
+
+import io
+import wave
+
+from agent_cli import constants
+from agent_cli.core.audio_format import convert_audio_to_wav_format
+from agent_cli.server.whisper.backends.base import InvalidAudioError
+
+
+async def prepare_wav_audio(
+    audio: bytes,
+    source_filename: str | None,
+    *,
+    backend_label: str,
+) -> bytes:
+    """Return 16kHz mono 16-bit PCM WAV bytes, converting only when needed.
+
+    Container validity alone is insufficient: Transformers reads samples as
+    int16 mono. Normalize other sample formats before model-worker dispatch.
+    Backends with their own decoders, such as faster-whisper, do not need this.
+    """
+    try:
+        with wave.open(io.BytesIO(audio), "rb") as wav_file:
+            if (
+                wav_file.getsampwidth() == constants.AUDIO_FORMAT_WIDTH
+                and wav_file.getnchannels() == constants.AUDIO_CHANNELS
+                and wav_file.getframerate() == constants.AUDIO_RATE
+            ):
+                return audio
+    except (wave.Error, EOFError, RuntimeError):
+        # wave can raise RuntimeError when a malformed RIFF chunk seeks past EOF.
+        pass
+
+    try:
+        return await convert_audio_to_wav_format(audio, source_filename or "audio")
+    except RuntimeError as exc:
+        msg = (
+            f"Unsupported audio format for {backend_label}. "
+            "Provide a valid WAV file or install ffmpeg to convert uploads."
+        )
+        raise InvalidAudioError(msg) from exc

{agent_cli-0.105.1 → agent_cli-0.106.0}/agent_cli/server/whisper/backends/base.py

@@ -89,7 +89,7 @@ class WhisperBackend(Protocol):
         """Transcribe audio data.
 
         Args:
-            audio: Audio data as bytes (WAV format, 16kHz, 16-bit, mono)
+            audio: Encoded audio bytes (16kHz mono 16-bit PCM WAV preferred).
             source_filename: Optional filename to help detect audio format.
             language: Language code or None for auto-detection
             task: "transcribe" or "translate" (to English)

{agent_cli-0.105.1 → agent_cli-0.106.0}/agent_cli/server/whisper/backends/nemo.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import asyncio
 import inspect
-import io
 import logging
 import os
 import sys
@@ -18,11 +17,10 @@ from multiprocessing import get_context
 from pathlib import Path
 from typing import Any, Literal
 
-from agent_cli.core.audio_format import convert_audio_to_wav_format
 from agent_cli.core.process import set_process_title
+from agent_cli.server.whisper.backends.audio import prepare_wav_audio
 from agent_cli.server.whisper.backends.base import (
     BackendConfig,
-    InvalidAudioError,
     TranscriptionResult,
 )
 
@@ -182,26 +180,6 @@ def _audio_duration_seconds(wav_path: str) -> float:
         return 0.0
 
 
-def _prepare_audio_for_nemo(audio_bytes: bytes, source_filename: str | None) -> bytes:
-    """Return a WAV container suitable for NeMo file-path transcription."""
-    try:
-        with wave.open(io.BytesIO(audio_bytes), "rb"):
-            return audio_bytes
-    except (wave.Error, EOFError):
-        pass
-
-    filename = source_filename or "audio"
-    try:
-        return convert_audio_to_wav_format(audio_bytes, filename)
-    except RuntimeError as exc:
-        logger.warning("FFmpeg conversion failed for NeMo Whisper: %s", exc)
-        msg = (
-            "Unsupported audio format for NeMo Whisper. "
-            "Provide a WAV file or install ffmpeg to convert uploads."
-        )
-        raise InvalidAudioError(msg) from exc
-
-
 def _build_transcribe_kwargs(
     transcribe_func: Any,
     *,
@@ -433,7 +411,11 @@ class NemoWhisperBackend:
             )
             self._warned_initial_prompt_ignored = True
 
-        audio = await asyncio.to_thread(_prepare_audio_for_nemo, audio, source_filename)
+        audio = await prepare_wav_audio(
+            audio,
+            source_filename,
+            backend_label="NeMo Whisper",
+        )
 
         kwargs: dict[str, Any] = {
             "language": language,

{agent_cli-0.105.1 → agent_cli-0.106.0}/agent_cli/server/whisper/backends/transformers.py

@@ -15,6 +15,7 @@ from pathlib import Path
 from typing import Any, Literal
 
 from agent_cli.core.process import set_process_title
+from agent_cli.server.whisper.backends.audio import prepare_wav_audio
 from agent_cli.server.whisper.backends.base import (
     BackendConfig,
     TranscriptionResult,
@@ -593,7 +594,7 @@ class TransformersWhisperBackend:
         self,
         audio: bytes,
         *,
-        source_filename: str | None = None,  # noqa: ARG002
+        source_filename: str | None = None,
         language: str | None = None,
         task: Literal["transcribe", "translate"] = "transcribe",
         initial_prompt: str | None = None,
@@ -606,6 +607,12 @@ class TransformersWhisperBackend:
             msg = "Model not loaded. Call load() first."
             raise RuntimeError(msg)
 
+        audio = await prepare_wav_audio(
+            audio,
+            source_filename,
+            backend_label="transformers ASR",
+        )
+
         # Write audio to temp file for wave parsing in subprocess
         with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
             tmp.write(audio)

{agent_cli-0.105.1 → agent_cli-0.106.0}/macos/AgentCLI/Sources/AgentCLI/AgentCommandRunner.swift

@@ -252,7 +252,12 @@ final class AgentCommandRunner: ObservableObject {
                 }
             }
 
-            let result = AgentRuntime.shared.runAgentCLI(arguments: commandArguments)
+            let commandResult = AgentRuntime.shared.runAgentCLI(arguments: commandArguments)
+            // A stop acknowledgement may be empty; a completed recording must contain text.
+            // Validate here too because user-installed CLIs can predate the CLI-side check.
+            let result = shouldStartRecording && command.identifier == AgentCommand.toggleTranscription.identifier
+                ? commandResult.requiringTranscript()
+                : commandResult
             let message = Self.statusMessage(for: command, result: result)
             let notificationTitle = Self.notificationTitle(for: command, result: result)
             let notificationBody = Self.notificationBody(for: command, result: result, statusMessage: message)

agent_cli-0.106.0/macos/AgentCLI/Sources/AgentCLI/CommandResult.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+struct CommandResult {
+    let exitCode: Int32
+    let output: String
+
+    func requiringTranscript() -> CommandResult {
+        guard exitCode == 0, output.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            return self
+        }
+        return CommandResult(
+            exitCode: 1,
+            output: "No transcript returned. Check the microphone and ASR server, then try again. "
+                + "If a recording was saved, recover it with agent-cli transcribe --last-recording."
+        )
+    }
+}

{agent_cli-0.105.1 → agent_cli-0.106.0}/macos/AgentCLI/Sources/AgentCLI/VoiceLevelOverlay.swift

@@ -3,7 +3,7 @@ import Foundation
 import SwiftUI
 
 enum VoiceLevelOverlayLayout {
-    static let pillSize = CGSize(width: 147, height: 38)
+    static let pillSize = CGSize(width: 190, height: 38)
     static let textWidth = CGFloat(420)
     static let textHeight = CGFloat(86)
     static let shadowRadius = CGFloat(13)
@@ -72,41 +72,57 @@ struct VoiceLevelOverlayView: View {
             height: VoiceLevelOverlayLayout.panelSize(showsPreviewSpace: showsPreviewSpace).height,
             alignment: .bottom
         )
-        .accessibilityLabel(Text("Voice level"))
+        .accessibilityElement(children: .ignore)
+        .accessibilityLabel(Text(meter.captureState == .recording
+            ? "Recording \(meter.recordingDuration)"
+            : meter.captureState.label))
+        .accessibilityValue(Text(showsPreviewSpace ? preview.text : ""))
     }
 
     private var levelMeter: some View {
-        HStack(alignment: .center, spacing: 3.5) {
+        HStack(spacing: 8) {
+            if meter.captureState == .recording {
+                Text(meter.recordingDuration)
+                    .font(.system(size: 12, weight: .semibold))
+                    .monospacedDigit()
+                waveform
+            } else {
+                ProgressView()
+                    .controlSize(.small)
+                Text(meter.captureState.label)
+                    .font(.system(size: 12, weight: .semibold))
+            }
+        }
+        .foregroundStyle(statusColor)
+        .frame(width: VoiceLevelOverlayLayout.pillSize.width, height: VoiceLevelOverlayLayout.pillSize.height)
+        .background(Capsule().fill(statusColor.opacity(isLightMode ? 0.10 : 0.14)))
+        .background(Capsule().fill(backgroundColor))
+        .overlay(Capsule().stroke(statusColor.opacity(0.55), lineWidth: 1))
+        .shadow(
+            color: shadowColor,
+            radius: VoiceLevelOverlayLayout.shadowRadius,
+            y: VoiceLevelOverlayLayout.shadowYOffset
+        )
+    }
+
+    private var waveform: some View {
+        HStack(alignment: .center, spacing: 2) {
             ForEach(Array(meter.amplitudes.enumerated()), id: \.offset) { _, amplitude in
                 Capsule()
                     .fill(
                         LinearGradient(
                             colors: [
-                                barGradientStart,
-                                barGradientEnd
+                                statusColor.opacity(0.65),
+                                statusColor
                             ],
                             startPoint: .bottom,
                             endPoint: .top
                         )
                     )
-                    .frame(width: 3.5, height: max(5, 25 * amplitude))
+                    .frame(width: 2, height: max(5, 25 * amplitude))
                     .animation(.easeOut(duration: 0.11), value: amplitude)
             }
         }
-        .frame(width: VoiceLevelOverlayLayout.pillSize.width, height: VoiceLevelOverlayLayout.pillSize.height)
-        .background(
-            Capsule()
-                .fill(backgroundColor)
-        )
-        .overlay(
-            Capsule()
-                .stroke(borderColor, lineWidth: 1)
-        )
-        .shadow(
-            color: shadowColor,
-            radius: VoiceLevelOverlayLayout.shadowRadius,
-            y: VoiceLevelOverlayLayout.shadowYOffset
-        )
     }
 
     private var isLightMode: Bool {
@@ -133,12 +149,15 @@ struct VoiceLevelOverlayView: View {
         Color.black.opacity(isLightMode ? 0.16 : 0.24)
     }
 
-    private var barGradientStart: Color {
-        isLightMode ? Color(red: 0.04, green: 0.45, blue: 0.95) : Color(red: 0.18, green: 0.82, blue: 0.92)
-    }
-
-    private var barGradientEnd: Color {
-        isLightMode ? Color(red: 0.07, green: 0.72, blue: 0.68) : Color(red: 0.64, green: 0.96, blue: 0.58)
+    private var statusColor: Color {
+        if meter.captureState == .recording {
+            return isLightMode
+                ? Color(red: 0.04, green: 0.40, blue: 0.18)
+                : Color(red: 0.42, green: 0.91, blue: 0.58)
+        }
+        return isLightMode
+            ? Color(red: 0.62, green: 0.34, blue: 0.0)
+            : Color(red: 1.0, green: 0.74, blue: 0.25)
     }
 }
 
@@ -306,10 +325,28 @@ enum VoiceLevelLog {
     }()
 }
 
+enum VoiceCaptureState {
+    case idle
+    case connecting
+    case recording
+    case waitingForAudio
+
+    var label: String {
+        switch self {
+        case .idle: return "Ready"
+        case .connecting: return "Connecting…"
+        case .recording: return "Recording"
+        case .waitingForAudio: return "Waiting for audio…"
+        }
+    }
+}
+
 final class VoiceLevelMeter: ObservableObject {
     static let shared = VoiceLevelMeter()
 
     @Published private(set) var amplitudes = VoiceLevelMeter.idleAmplitudes
+    @Published private(set) var captureState = VoiceCaptureState.idle
+    @Published private(set) var recordingDuration = "00:00"
 
     private static let barCount = 16
     private static let idleAmplitudes = Array(repeating: CGFloat(0.16), count: barCount)
@@ -319,6 +356,7 @@ final class VoiceLevelMeter: ObservableObject {
     private let levelLogURL: URL
     private let now: () -> Date
     private var timer: Timer?
+    private var recordingStartedAt: Date?
     private var phase = 0.0
     private var smoothedLevel = CGFloat(0.16)
 
@@ -330,6 +368,9 @@ final class VoiceLevelMeter: ObservableObject {
     func start() {
         guard timer == nil else { return }
         VoiceLevelLog.reset(levelLogURL)
+        captureState = .connecting
+        recordingStartedAt = nil
+        recordingDuration = "00:00"
         phase = 0
         smoothedLevel = Self.idleLevel
         amplitudes = Self.idleAmplitudes
@@ -345,13 +386,29 @@ final class VoiceLevelMeter: ObservableObject {
     func stop() {
         timer?.invalidate()
         timer = nil
+        captureState = .idle
+        recordingStartedAt = nil
+        recordingDuration = "00:00"
         phase = 0
         smoothedLevel = Self.idleLevel
         amplitudes = Self.idleAmplitudes
     }
 
-    private func pollLevel() {
-        let level = VoiceLevelLog.latestLevel(from: levelLogURL, now: now()) ?? Self.idleLevel
+    func pollLevel() {
+        guard timer != nil else { return }
+        let now = now()
+        guard let level = VoiceLevelLog.latestLevel(from: levelLogURL, now: now) else {
+            if captureState == .recording {
+                captureState = .waitingForAudio
+            }
+            amplitudes = Self.idleAmplitudes
+            return
+        }
+        captureState = .recording
+        let startedAt = recordingStartedAt ?? now
+        recordingStartedAt = startedAt
+        let elapsedSeconds = max(0, Int(now.timeIntervalSince(startedAt)))
+        recordingDuration = String(format: "%02d:%02d", elapsedSeconds / 60, elapsedSeconds % 60)
         updateDisplay(level: level)
     }
 

agent_cli-0.106.0/macos/AgentCLI/Tests/AgentCLITests/TranscriptionResultTests.swift

@@ -0,0 +1,23 @@
+#if canImport(XCTest)
+import XCTest
+@testable import AgentCLI
+
+final class TranscriptionResultTests: XCTestCase {
+    func testEmptySuccessfulRecordingBecomesFailure() {
+        for output in ["", " \n\t"] {
+            let result = CommandResult(exitCode: 0, output: output).requiringTranscript()
+            XCTAssertNotEqual(result.exitCode, 0)
+            XCTAssertTrue(result.output.contains("No transcript"))
+        }
+    }
+
+    func testTranscriptAndBackendFailureArePreserved() {
+        let success = CommandResult(exitCode: 0, output: "Hello world").requiringTranscript()
+        XCTAssertEqual(success.exitCode, 0)
+        XCTAssertEqual(success.output, "Hello world")
+        let failure = CommandResult(exitCode: 7, output: "Connection lost").requiringTranscript()
+        XCTAssertEqual(failure.exitCode, 7)
+        XCTAssertEqual(failure.output, "Connection lost")
+    }
+}
+#endif

{agent_cli-0.105.1 → agent_cli-0.106.0}/macos/AgentCLI/Tests/AgentCLITests/VoiceLevelMeterTests.swift

@@ -4,6 +4,95 @@ import XCTest
 @testable import AgentCLI
 
 final class VoiceLevelMeterTests: XCTestCase {
+    func testRecordingTimerExcludesStartupAndResetsBetweenRecordings() throws {
+        let logURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        var now = try XCTUnwrap(Self.iso8601.date(from: "2026-06-04T12:00:00Z"))
+        let meter = VoiceLevelMeter(levelLogURL: logURL, now: { now })
+        defer {
+            meter.stop()
+            try? FileManager.default.removeItem(at: logURL)
+        }
+        meter.start()
+        now = now.addingTimeInterval(10)
+        meter.pollLevel()
+        XCTAssertEqual(meter.recordingDuration, "00:00")
+
+        func publishAudio() throws {
+            try "{\"timestamp\":\"\(Self.iso8601.string(from: now))\",\"level\":0}"
+                .write(to: logURL, atomically: true, encoding: .utf8)
+            meter.pollLevel()
+        }
+        try publishAudio()
+        XCTAssertEqual(meter.recordingDuration, "00:00")
+        now = now.addingTimeInterval(9)
+        try publishAudio()
+        XCTAssertEqual(meter.recordingDuration, "00:09")
+        now = now.addingTimeInterval(56)
+        try publishAudio()
+        XCTAssertEqual(meter.recordingDuration, "01:05")
+        now = now.addingTimeInterval(3600)
+        try publishAudio()
+        XCTAssertEqual(meter.recordingDuration, "61:05")
+
+        meter.stop()
+        XCTAssertEqual(meter.recordingDuration, "00:00")
+        meter.start()
+        try publishAudio()
+        XCTAssertEqual(meter.recordingDuration, "00:00")
+    }
+
+    func testRecordingReadinessFollowsFreshAudioIncludingSilence() throws {
+        let logURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        var now = try XCTUnwrap(Self.iso8601.date(from: "2026-06-04T12:00:00Z"))
+        let meter = VoiceLevelMeter(levelLogURL: logURL, now: { now })
+        defer {
+            meter.stop()
+            try? FileManager.default.removeItem(at: logURL)
+        }
+
+        // A previous recording must not make a new request look ready.
+        try #"{"timestamp":"2026-06-04T12:00:00Z","level":0.9}"#
+            .write(to: logURL, atomically: true, encoding: .utf8)
+        meter.start()
+        XCTAssertEqual(meter.captureState, .connecting)
+
+        try #"{"timestamp":"2026-06-04T12:00:00Z","level":0}"#
+            .write(to: logURL, atomically: true, encoding: .utf8)
+        meter.pollLevel()
+        XCTAssertEqual(meter.captureState, .recording, "Silent audio still proves capture is running.")
+
+        now = now.addingTimeInterval(2)
+        meter.pollLevel()
+        XCTAssertEqual(meter.captureState, .waitingForAudio)
+
+        try #"{"timestamp":"2026-06-04T12:00:02Z","level":0.6}"#
+            .write(to: logURL, atomically: true, encoding: .utf8)
+        meter.pollLevel()
+        XCTAssertEqual(meter.captureState, .recording)
+
+        meter.stop()
+        meter.pollLevel()
+        XCTAssertEqual(meter.captureState, .idle, "Late polling must not revive a released overlay.")
+        meter.start()
+        XCTAssertEqual(meter.captureState, .connecting)
+    }
+
+    func testConnectingDoesNotAnimateFakeMicrophoneActivity() throws {
+        let logURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        let meter = VoiceLevelMeter(levelLogURL: logURL)
+        defer {
+            meter.stop()
+            try? FileManager.default.removeItem(at: logURL)
+        }
+        meter.start()
+        let initialAmplitudes = meter.amplitudes
+        meter.pollLevel()
+        XCTAssertEqual(meter.captureState, .connecting)
+        XCTAssertEqual(meter.amplitudes, initialAmplitudes)
+        meter.stop()
+        XCTAssertEqual(meter.captureState, .idle)
+    }
+
     func testDisplayAmplitudesUseSineWaveShape() {
         let amplitudes = VoiceLevelMeter.displayAmplitudes(level: 0.6, phase: 0.22)