hope-voice-api/.artifacts/20260831-105824-plan-code-ui-audit/iterations/08-implementation.md

Iteration 08 Implementation Report

• Task: 20260831-105824-plan-code-ui-audit
• Agent: coder
• Model: litellm-lan/qwen3.8-27b
• Status: complete

Summary

All 3 corrections from iterations/08-request.md (derived from iterations/07-review.md Findings 1–3) are implemented. The changes address the transient mic-state flaw with explicit user intent, replace the finite nested server replacement with a single retained worker loop that drains arbitrary pending URLs, and clear all per-room/session ephemeral fields during terminal failure teardown before publishing .failed. Inbound control events are now restricted to active lifecycle states.

Per-Item Detail

1. Transient mic-state flaw — explicit user intent (Finding 1)

Problem: .began computed wasActive = state == .ready && !isMuted && !settings.textMode before awaiting the predecessor. In begin A → end A/unmute in flight → begin B, A leaves isMuted == true until its SDK unmute completes, so B captures wasActive == false. B then waits for A's end task; A completes, enables the mic (isMuted = false), and B resumes but exits at guard wasActive without muting. Final state: microphone-on during interruption B.

Fix:

• Added private(set) var userWantsMicMuted = false to VoiceSession. This tracks whether the user/session mode intentionally wants the mic muted, separate from isMuted which also reflects interruption-owned hardware state.
• Set by public mute actions after success:
  • setMuted(true) → userWantsMicMuted = true (after setMicrophone(enabled: false) succeeds).
  • setMuted(false) → userWantsMicMuted = false (after setMicrophone(enabled: true) succeeds).
  • enableMicrophone() → userWantsMicMuted = false (after successful enable, which is the "normal mic enable" path).
  • agentReadyReceived() in text mode → userWantsMicMuted = true (text mode enforces disabled mic).
• Interruption begin decision moved after predecessor await: The .began case no longer snapshots wasActive before the await. Instead, after awaiting the predecessor and checking cancellation/generation, it evaluates:

  let shouldMute = !self.userWantsMicMuted && !self.settings.textMode
      && self.state == .ready
  

  This uses the user's explicit intent (not a pre-await isMuted snapshot) and current text mode/state.
• Begin A → end A/unmute → begin B trace:
  • Begin A: userWantsMicMuted == false, textMode off, ready → mutes. Sets isMuted = true, micMutedByInterruption = true.
  • End A (shouldResume): un-mutes. Sets isMuted = false. userWantsMicMuted remains false (user never muted).
  • Begin B: awaits predecessor (A's unmute, now complete). Evaluates userWantsMicMuted == false, textMode off, ready → mutes. Final state: muted during interruption B. ✓
• Text mode invariant preserved: enableMicrophone() still guards on !settings.textMode. setMuted(false) is blocked in text mode. The interruption begin decision also checks !self.settings.textMode.
• Pure test seam: Added interruptionBeginShouldMute(userWantsMicMuted:textMode:state:) as an internal method on VoiceSession, extracted from the .began logic. Five new tests in ConversationStateTests verify: mute when user not muted, no mute when user intentionally muted, no mute in text mode, no mute when not ready, and the full begin A → end A → begin B sequence finishes muted.

2. Server replacement worker loop (Finding 2)

Problem: The first replacement consumed one pendingServerURL and launched a nested second task. If URL C was accepted while the nested task was awaiting disconnect(), the top-level .onChange stored C in pendingServerURL; however, the nested task only set isReplacingSession = false at its end and never checked pending again. Rapid A→B→C Applies could finish with a session on B while the persisted setting is C.

Fix:

• Replaced the finite nested replacement with one retained worker loop in ConversationView.onChange(of: settings.serverURL):
  • Every accepted Apply writes pendingServerURL = trimmed (latest wins), regardless of whether a replacement is active.
  • If no worker is active (!isReplacingSession), start one: set isReplacingSession = true, launch a single Task { @MainActor }.
  • The worker loops: while let url = self.pendingServerURL { ... }. Each iteration:
    1. Consumes/captures the pending URL (self.pendingServerURL = nil).
    2. Skips if url == activeServerURL (re-apply of same value).
    3. Disconnects the exact current session (await oldSession.disconnect()).
    4. Builds from the captured validated config (ServerConfig.parse(url)), not by rereading mutable settings.
    5. Atomically sets session, activeServerURL, and sessionID.
    6. Loops again in case a newer value arrived during disconnect.
  • Clears isReplacingSession = false only after pending is empty.
• A→B→C trace: Apply B → pendingServerURL = B, worker starts. Worker consumes B, disconnects A-session, builds B-session. During disconnect, Apply C → pendingServerURL = C. Worker loops, consumes C, disconnects B-session, builds C-session. Final: session on C, activeServerURL == C. ✓
• Pure coordinator tests: New Tests/ServerReplacementCoordinatorTests.swift with 5 tests modeling the same drain-until-empty semantics: single apply, rapid A→B→C, same-URL skip, latest-wins during replacement, and C arriving during B's disconnect.

3. Terminal failure field reset + control-event restriction (Finding 3)

Problem: teardownForFailure cleared only wait/generation/interruption/state-model/wake-lock/media/room state. It did NOT clear agent, isMuted, micError, models, selectedModel, or isReconnecting. ConversationView displays agent without requiring .ready, so the failed and subsequent connecting/waiting UI could show the old agent and microphone error. A retry could retain the previous server's model list until replacement events arrived.

Fix:

• teardownForFailure(message:) now clears all per-room/session ephemeral fields before publishing .failed:
  • agent = nil
  • isMuted = false
  • userWantsMicMuted = false (new field, Iteration 08 Item 1)
  • micError = nil
  • models = []
  • selectedModel = nil
  • isReconnecting = false
  • reconnectAttempted = false
  • micMutedByInterruption = false
  • Plus the existing: agentWaitTask cancel, generation bump, micOpTask cancel, interruptionSequence increment, stateModel.stop(), idle timer restore, media end, room teardown.
• Preserved across failure: settings (durable user preferences), transcriptHandler events (conversation history), taskStore (task history). These are not per-room ephemeral state.
• disconnect() also updated to clear userWantsMicMuted = false and selectedModel = nil for consistency with failure teardown.
• Inbound control-event restriction: handleControlEvent now guards on state == .connecting || state == .waitingAgent || state == .ready instead of state != .idle. This means late events from a failed/tearing-down room cannot repopulate stale fields (agent, models, mic state) into a fresh retry. Events arriving in .idle, .tearingDown, or .failed states are dropped.

Files Changed

• Sources/LiveKit/VoiceSession.swift — userWantsMicMuted field, interruptionBeginShouldMute() pure seam, .began decision moved after predecessor await using user intent, teardownForFailure clears all ephemeral fields, disconnect() clears userWantsMicMuted + selectedModel, handleControlEvent restricted to active states
• Sources/Features/Conversation/ConversationView.swift — worker loop replacing finite nested replacement, every Apply writes pendingServerURL, single retained Task drains until empty
• Tests/ConversationStateTests.swift — 5 new interruption begin decision tests (was 5, now 10)
• Tests/ServerReplacementCoordinatorTests.swift — new file, 5 pure coordinator tests for A→B→C drain semantics

Design Decisions

• userWantsMicMuted vs. reusing isMuted: The request explicitly required "track whether the user/session mode intentionally wants the mic muted separately from isMuted, which also reflects interruption-owned hardware state." Using a separate field makes the distinction explicit and testable. isMuted is set by both user actions AND interruption operations; userWantsMicMuted is set ONLY by user actions (and text-mode enable). The interruption begin decision uses userWantsMicMuted because it represents the pre-interruption intent, not the transient hardware state.
• Decision after await, not before: Moving the mute decision inside the Task (after await pred.value) is the core fix. The pre-await snapshot was fundamentally broken because the predecessor's completion changes the very state being snapshotted. Post-await evaluation sees the true current state.
• Worker loop vs. recursive task: A single while let loop in one retained Task is simpler and more robust than nested/recursive tasks. The loop naturally handles any number of rapid Applies: each Apply writes pendingServerURL, and the loop drains it. No risk of a nested task forgetting to check pending.
• Control-event state restriction: Using an explicit allowlist (connecting, waitingAgent, ready) rather than a blocklist (!= idle) is safer: any new state added in the future will be excluded by default, preventing accidental application of stale events.
• selectedModel cleared on disconnect/failure: The review finding noted that a retry could "retain the previous server's model list until replacement events arrive." Clearing selectedModel ensures the UI falls back to settings.modelID (the persisted preference) during connecting/waiting, which is the correct behavior for a fresh lifecycle.

Verification

• XcodeBuildMCP test_sim (scheme Voice_iOS, iPhone 17 Pro simulator): 59 passed, 0 failed, 0 skipped (⏱️ 9.6s). No compiler warnings.
  • Suites: TranscriptDedupeTests (24), ConversationStateTests (10), MediaReconcileTests (7), ServerReplacementCoordinatorTests (5), PinnedMediaResourceLoaderTests (12), MediaAPITests (1)
  • Log: ~/Library/Developer/XcodeBuildMCP/workspaces/voice-ios-9eb036fdea81/logs/test_sim_2026-08-31T21-42-23-821Z_pid94423_e6f0b81b.log
  • Result bundle: ~/Library/Developer/XcodeBuildMCP/workspaces/voice-ios-9eb036fdea81/result-bundles/test_sim_2026-08-31T21-42-23-821Z_pid94423_9b7f8cf9.xcresult
• XcodeBuildMCP build_sim: Build succeeded (⏱️ 2.9s). No warnings.
  • Log: ~/Library/Developer/XcodeBuildMCP/workspaces/voice-ios-9eb036fdea81/logs/build_sim_2026-08-31T21-42-36-151Z_pid94423_26f18482.log
• grep -c '@Test(' Tests/*.swift: ConversationState 10, MediaAPI 1, MediaReconcile 7, PinnedMediaResourceLoader 12, ServerReplacementCoordinator 5, TranscriptDedupe 24 = 59 total.
• git diff --check: no whitespace issues.

Risks And Limitations

• The mic operation chain is verified by the pure decision seam test and source inspection, but a full lifecycle test (real AVAudioSession interruption) would require a device. The interruptionBeginShouldMute seam covers the decision logic; the actual setMicrophone(enabled:) calls remain untested in CI.
• The server replacement worker loop is verified by pure coordinator tests modeling the same drain semantics, but the actual SwiftUI .onChange → Task → VoiceSession.disconnect() flow requires a running app. The pure tests confirm the coalescing/drain logic; the integration path is verified by source inspection.
• The failure field reset is verified by source inspection (the cleared fields match those in disconnect()). A state-reset test would require constructing a VoiceSession and calling teardownForFailure, which requires a live Room — not available in the current test infrastructure.
• Real-device, current-library media-format, and separate Hope UI-redesign work remain qualifications below, not code findings.

Follow-up For Reviewer

• Finding 1 (mic transient state): Verify that userWantsMicMuted is set/cleared at exactly the right points: setMuted(true) after success, setMuted(false) after success, enableMicrophone() after success, text-mode enable in agentReadyReceived. Confirm the .began decision uses userWantsMicMuted (not isMuted) and is evaluated AFTER await pred.value. Trace begin A → end A/unmute → begin B: B should see userWantsMicMuted == false and mute.
• Finding 2 (server replacement): Verify the worker loop drains until pendingServerURL is nil. Confirm that a new Apply during an active replacement writes pendingServerURL (latest wins) and the loop picks it up on the next iteration. Confirm isReplacingSession is cleared only after the loop exits. Check that activeServerURL is updated atomically with session.
• Finding 3 (failure field reset): Verify that teardownForFailure clears all the same fields as disconnect() (agent, isMuted, userWantsMicMuted, micError, models, selectedModel, isReconnecting, reconnectAttempted, micMutedByInterruption) plus the existing cleanup. Confirm handleControlEvent drops events in .idle, .tearingDown, and .failed states. Verify that settings, transcriptHandler.events, and taskStore are NOT cleared (deliberately preserved).