fix(ios): keep the voice-processing graph up instead of rebuilding it

Joining voice on the voice-chat preset was unreliable: audio arrived after
several seconds of the route flipping back and forth, sometimes not at all, and
VoiceOver went quiet while it happened. Device logs show why. A graph with
voice processing enabled reports a successful start and is then torn down
within a second, roughly three times in four; every configuration without voice
processing — both microphone presets, and voice chat with processing off — comes
up first time and runs indefinitely.

With voice processing the input and output are one IO unit, and it only stays up
while the input is part of the render chain. The input node carried a tap and no
connection, which leaves it out of that chain. Route the input through a silent
mixer so it is genuinely rendered.

The rest of this is the amplifier rather than the cause, and each part of it
turned one failed start into a storm:

The stall watchdog rebuilt on every missed tick, without bound. That converted a
graph that could not start into endless session reconfiguration, which is what
the user heard and what hid the reason from the log. It now backs off after each
failed attempt and stops after four, logging VC_WATCHDOG exhausted, so a
transient freeze still recovers and a graph that will not start fails visibly.

Nothing waited for a graph to start before judging it dead. Enabling voice
processing rebuilds both halves of the IO, which posts a configuration change
and reads as not running for several hundred milliseconds, so the
configuration-change handler and the watchdog both tore down graphs that were
about to run. A settling window holds them off for two seconds.

A route change forced a full rebuild, and every rebuild moves the route, so one
notification produced the next. Route changes now take the non-forcing path,
which rebuilds a stopped graph and leaves a healthy one alone; the hardware test
it uses reads the input node's format, not AVAudioSession, whose reported rate
and channel count do not settle until after the graph has started.

The input side is built once per session instead of being added when voice is
joined, so joining and leaving voice set a stream id rather than replacing the
graph, and a mono voice-chat apply no longer clears a stereo capsule
configuration it never applied.

Every rebuild now logs its cause, and VC_START/VC_START_CHECK record whether the
graph survived its start. The first-attempt failure is not fixed and is recorded
in PROGRESS.md as a release gate: capture still comes up on a watchdog rebuild
rather than immediately.

The changed logic sits on AVAudioSession and AVAudioEngine, which the net10.0
test project cannot reference, so the behaviour is covered by the existing
source assertions; verification is on device.

clients/apple/VoiceCat.iOS/IosAudioEngine.cs

@@ -39,13 +39,42 @@ internal sealed class IosAudioEngine
     private AVAudioConverterInputHandler? inputProvider;
     private bool inputProvided;
     private bool tapInstalled;
+    private AVAudioMixerNode? captureSink;
     // The voice-processing state the live graph was actually built with, so Reconfigure can tell
     // a settings change apart from a re-check of an unchanged graph.
     private bool voiceProcessing;
+    // The input format the tap, the converter and the ring capacity were all built for. Asked of
+    // the input node rather than of AVAudioSession: the session's reported rate and channel count
+    // do not settle until after the graph has started, so comparing against them reports a change
+    // that has not happened and every rebuild reports it again.
+    private long lastRebuildAt;
+    // How long a freshly built graph is given to produce its first render callback. Enabling voice
+    // processing rebuilds both halves of the IO, which takes several hundred milliseconds, posts a
+    // configuration change and reports the engine as not running while it happens. Everything that
+    // judges a graph dead has to wait this out, or it tears down the graph it just built and the
+    // replacement reports exactly the same thing.
+    private const int SettlingMilliseconds = 2_000;
+    private double builtInputRate;
+    private uint builtInputChannels;
+    // The capture width the tap and converter were built for. The input side of the graph exists
+    // for the whole session, so this is what decides whether joining voice needs a rebuild at all.
+    private int builtCaptureChannels;
     private long captureCallbacks, capturedFrames, convertedFrames, rejectedFeeds, converterFailures, stereoFrames, stereoDifferentFrames;
     private long renderCallbacks, lastRenderTimestamp;
     internal bool IsConnected { get; private set; }
     internal bool IsRunning => engine?.Running == true;
+    // True while the last rebuild is still starting up, and so cannot be judged.
+    internal bool Settling => Environment.TickCount64 - Volatile.Read(ref lastRebuildAt) < SettlingMilliseconds;
+    // True when the graph's own input no longer has the format its tap and converter were built
+    // for, which is the only thing a route change can do that AVAudioEngine cannot absorb on its
+    // own. The engine's view is the one that is stable: it changes when the hardware actually
+    // changes, which is precisely what a configuration change reports.
+    internal bool HardwareChanged()
+    {
+        if (engine is not { } live || !tapInstalled) return false;
+        AVAudioFormat format = live.InputNode.GetBusOutputFormat(0);
+        return format.SampleRate != builtInputRate || format.ChannelCount != builtInputChannels;
+    }
     // The watchdog compares this across ticks: a graph that stops calling back while it still
     // reports Running leaves the whole device-clocked pipeline frozen until it is rebuilt.
     internal long RenderCallbacks => Interlocked.Read(ref renderCallbacks);
@@ -78,29 +107,33 @@ internal sealed class IosAudioEngine
 
     internal void StartMicrophone(uint streamId, int channels)
     {
-        MicrophoneRoute? current = Volatile.Read(ref microphone);
-        // Restoring voice after a reconnect only changes which stream id the existing capture
-        // feeds. Reuse a running tap of the same width instead of rebuilding the graph around it.
-        if (current is { StreamId: 0 } && current.Channels == Math.Clamp(channels, 1, 2) && tapInstalled && engine?.Running == true)
-        {
-            current.Ring.Resynchronize();
-            Volatile.Write(ref microphone, CreateMicrophoneRoute(streamId, channels)); return;
-        }
-        Volatile.Write(ref microphone, CreateMicrophoneRoute(streamId, channels)); Rebuild();
+        // Capture is already running: the graph carries the tap for the whole session. Joining voice
+        // only names the stream the frames belong to, so it is a state change and not a rebuild. The
+        // width is the one exception, because the tap format and converter are built around it.
+        MicrophoneRoute next = CreateMicrophoneRoute(streamId, channels);
+        bool reusable = tapInstalled && engine?.Running == true && builtCaptureChannels == next.Channels;
+        Volatile.Write(ref microphone, next);
+        if (!reusable) Rebuild();
     }
 
-    internal void StopMicrophone() { Volatile.Write(ref microphone, null); Rebuild(); }
+    // Leaving voice never rebuilds. Capture keeps running into a route nobody reads, exactly as it
+    // does between connecting and joining, which costs one discarded conversion per callback and
+    // saves tearing down the voice-processing IO only to build it again on the next join.
+    internal void StopMicrophone() { Volatile.Write(ref microphone, null); }
 
     // `force` rebuilds unconditionally, which is what a route change, a media-services reset and
     // the stall watchdog all need. Callers that are only re-checking a graph they expect to be
     // healthy — foregrounding, above all — pass false and get a no-op when nothing has changed.
-    internal void Reconfigure(bool force = true)
+    internal void Reconfigure(bool force = true, string cause = "reconfigure")
     {
         if (!IsConnected) return;
+        // A graph that has not finished starting is not a graph to replace. Only an explicit
+        // configuration change forces its way past this.
+        if (!force && Settling) return;
         MicrophoneRoute? current = Volatile.Read(ref microphone);
         int channels = IosAudioRouter.Shared.CaptureChannels;
-        if (!force && engine?.Running == true && tapInstalled == (current is not null) &&
-            (current?.Channels ?? channels) == channels && voiceProcessing == IosAudioRouter.Shared.UsesVoiceProcessing) return;
+        if (!force && engine?.Running == true && tapInstalled && builtCaptureChannels == channels
+            && voiceProcessing == IosAudioRouter.Shared.UsesVoiceProcessing && !HardwareChanged()) return;
         if (current is not null)
         {
             // Stop the old tap before publishing a route with a different sample width. Otherwise
@@ -109,7 +142,7 @@ internal sealed class IosAudioEngine
             if (current.Channels != channels && current.StreamId != 0) client?.Audio.SetCaptureChannels(current.StreamId, channels);
             Volatile.Write(ref microphone, CreateMicrophoneRoute(current.StreamId, channels));
         }
-        Rebuild();
+        Rebuild(cause);
     }
 
     private static MicrophoneRoute CreateMicrophoneRoute(uint streamId, int channels)
@@ -119,16 +152,31 @@ internal sealed class IosAudioEngine
     internal bool EnsureRunning()
     {
         if (!IsConnected || engine?.Running == true) return true;
+        // Still starting: report it as running rather than replacing it, since that is what it is
+        // about to be, and a rebuild here would start the cycle over.
+        if (Settling) return true;
         Rebuild(); return engine?.Running == true;
     }
 
-    private void Rebuild()
+    private void Rebuild([System.Runtime.CompilerServices.CallerMemberName] string cause = "")
     {
-        DestroyGraph(); MicrophoneRoute? route = Volatile.Read(ref microphone); IosAudioRouter.Shared.Apply(route is not null);
+        Console.Error.WriteLine($"VC_REBUILD cause={cause} running={engine?.Running == true} callbacks={RenderCallbacks}");
+        DestroyGraph(); MicrophoneRoute? route = Volatile.Read(ref microphone);
+        // The input node, voice processing and the tap are built once and kept for the session, not
+        // added when voice is joined. Adding them later means replacing a running graph that has no
+        // voice processing with one that has it, and that transition is what fails: the new IO unit
+        // starts and is torn down again within a second, non-deterministically, which is the
+        // rebuild storm the watchdog then chases. Steady-state voice processing is reliable; only
+        // the change into it is not. So capture always runs, and joining voice only decides which
+        // stream its frames belong to — Capture and PumpMicrophoneChunk both discard without one.
+        bool captures = IsConnected;
+        int captureChannels = route?.Channels ?? Math.Clamp(IosAudioRouter.Shared.CaptureChannels, 1, 2);
+        IosAudioRouter.Shared.Apply(captures);
         voiceProcessing = IosAudioRouter.Shared.UsesVoiceProcessing;
+        builtInputRate = 0; builtInputChannels = 0;
         var next = new AVAudioEngine();
         AVAudioInputNode? input = null;
-        if (route is not null)
+        if (captures)
         {
             // Enabling voice processing rebuilds both sides of AVAudioEngine. Do it before any
             // formats are queried or nodes are connected so the graph is built from the final IO.
@@ -144,12 +192,14 @@ internal sealed class IosAudioEngine
         if (OperatingSystem.IsIOSVersionAtLeast(27)) next.Connect(source, next.MainMixerNode, outputFormat, out connectionError);
         else next.Connect(source, next.MainMixerNode, outputFormat);
         if (connectionError is not null) throw new InvalidOperationException(connectionError.LocalizedDescription);
-        if (route is not null)
+        if (captures)
         {
             AVAudioFormat inputFormat = input!.GetBusOutputFormat(0);
-            Console.Error.WriteLine($"VC_GRAPH vpio={IosAudioRouter.Shared.UsesVoiceProcessing} requestedCh={route.Channels} " +
+            Console.Error.WriteLine($"VC_GRAPH vpio={IosAudioRouter.Shared.UsesVoiceProcessing} requestedCh={captureChannels} " +
                 $"inputCh={inputFormat.ChannelCount} inputRate={inputFormat.SampleRate}");
-            microphoneFormat = new(AVAudioCommonFormat.PCMInt16, 48_000, (uint)route.Channels, true);
+            builtInputRate = inputFormat.SampleRate; builtInputChannels = inputFormat.ChannelCount;
+            microphoneFormat = new(AVAudioCommonFormat.PCMInt16, 48_000, (uint)captureChannels, true);
+            builtCaptureChannels = captureChannels;
             microphoneConverter = new(inputFormat, microphoneFormat);
             uint capacity = checked((uint)Math.Ceiling(MaximumCaptureCallbackFrames * 48_000 / inputFormat.SampleRate) + 64);
             convertedMicrophone = new(microphoneFormat, capacity);
@@ -159,17 +209,64 @@ internal sealed class IosAudioEngine
             else input.InstallTapOnBus(0, 960, inputFormat, Capture);
             if (tapError is not null) throw new InvalidOperationException(tapError.LocalizedDescription);
             tapInstalled = true;
+            // With voice processing the input and output run as one IO unit, and the unit only stays
+            // up while the input is part of the render chain. A tap alone does not put it there: the
+            // engine starts and the IO is torn down again within a second, which is why a graph with
+            // voice processing came up perhaps one time in four. Route the input through a silent
+            // mixer so it is genuinely rendered, contributing nothing audible.
+            captureSink = new AVAudioMixerNode();
+            next.AttachNode(captureSink);
+            NSError? sinkError = null;
+            if (OperatingSystem.IsIOSVersionAtLeast(27))
+            {
+                next.Connect(input, captureSink, inputFormat, out sinkError);
+                if (sinkError is null) next.Connect(captureSink, next.MainMixerNode, outputFormat, out sinkError);
+            }
+            else
+            {
+                next.Connect(input, captureSink, inputFormat);
+                next.Connect(captureSink, next.MainMixerNode, outputFormat);
+            }
+            if (sinkError is not null) throw new InvalidOperationException(sinkError.LocalizedDescription);
+            captureSink.OutputVolume = 0f;
         }
         next.Prepare();
         if (!next.StartAndReturnError(out NSError? error)) { next.Dispose(); throw new InvalidOperationException(error.LocalizedDescription); }
         engine = next;
+        {
+            AVAudioSession live = AVAudioSession.SharedInstance();
+            Console.Error.WriteLine($"VC_START running={next.Running} builtCh={builtInputChannels} sessionRate={live.SampleRate} " +
+                $"sessionInCh={live.InputNumberOfChannels} sessionOutCh={live.OutputNumberOfChannels} inputAvailable={live.InputAvailable} " +
+                $"other={live.OtherAudioPlaying} mode={live.Mode} options={live.CategoryOptions} io={live.IOBufferDuration:F4} " +
+                $"out={string.Join(',', live.CurrentRoute.Outputs.Select(value => value.PortType.ToString()))} " +
+                $"in={string.Join(',', live.CurrentRoute.Inputs.Select(value => value.PortType.ToString()))}");
+            // A graph that starts and then stops on its own is the failure that matters, and it is
+            // invisible at start: check again once the IO has had time to come up.
+            AVAudioEngine started = next;
+            System.Threading.Tasks.Task.Delay(750).ContinueWith(_ =>
+                UIApplication.SharedApplication.BeginInvokeOnMainThread(() =>
+                {
+                    if (!ReferenceEquals(engine, started)) return;
+                    Console.Error.WriteLine($"VC_START_CHECK running={started.Running} render={RenderCallbacks} capture={Interlocked.Read(ref captureCallbacks)}");
+                }));
+        }
+        Volatile.Write(ref lastRebuildAt, Environment.TickCount64);
         engineConfigurationObserver = Foundation.NSNotificationCenter.DefaultCenter.AddObserver(
             AVAudioEngine.ConfigurationChangeNotification, notification =>
             {
                 if (!ReferenceEquals(notification.Object, next)) return;
                 UIApplication.SharedApplication.BeginInvokeOnMainThread(() =>
                 {
-                    if (IsConnected && ReferenceEquals(engine, next) && !next.Running) Rebuild();
+                    if (!IsConnected || !ReferenceEquals(engine, next)) return;
+                    // Building this graph is itself what posted most of these: enabling voice
+                    // processing rebuilds the IO, and the engine reads as stopped until that
+                    // finishes. Rebuilding then replaces a graph that was about to run with one
+                    // that reports the same thing, without end.
+                    if (Settling) return;
+                    // A configuration change with the graph still running is usually one
+                    // AVAudioEngine has already absorbed; it matters here only when the hardware
+                    // the tap and converter were built around moved.
+                    if (!next.Running || HardwareChanged()) Rebuild("configuration change");
                 });
             }, next);
     }
@@ -296,7 +393,9 @@ internal sealed class IosAudioEngine
         if (engine is { } old)
         {
             if (tapInstalled) old.InputNode.RemoveTapOnBus(0);
-            old.Stop(); if (source is not null) old.DetachNode(source); old.Dispose();
+            old.Stop(); if (source is not null) old.DetachNode(source);
+            if (captureSink is not null) { old.DetachNode(captureSink); captureSink.Dispose(); captureSink = null; }
+            old.Dispose();
         }
         tapInstalled = false; pendingInput = null; inputProvider = null; lastRenderTimestamp = 0; microphoneCredit = 0;
         convertedMicrophone?.Dispose(); convertedMicrophone = null;