fix(sdcard): run the SD bus switch as a prepare phase inside the exchange lock

src/Daqifi.Core.Tests/Device/DaqifiDeviceDrainErrorQueueTests.cs

@@ -203,17 +203,25 @@ public override void Send<T>(IOutboundMessage<T> message)
                 }
             }
 
-            protected override Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
+            protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
                 Action setupAction,
                 int responseTimeoutMs = 1000,
                 int completionTimeoutMs = 250,
-                CancellationToken cancellationToken = default)
+                CancellationToken cancellationToken = default,
+                Func<CancellationToken, Task>? prepareAsync = null)
             {
+                // Honor the exchange's prepare phase the way the real device does: it runs first,
+                // before anything this exchange sends (#396).
+                if (prepareAsync != null)
+                {
+                    await prepareAsync(cancellationToken).ConfigureAwait(false);
+                }
+
                 cancellationToken.ThrowIfCancellationRequested();
                 setupAction();
                 ExecuteTextCommandCallCount++;
                 var reply = Replies.Count > 0 ? Replies.Dequeue() : Array.Empty<string>();
-                return Task.FromResult(reply);
+                return reply;
             }
         }
     }

src/Daqifi.Core.Tests/Device/DaqifiDeviceInitializeTests.cs

@@ -428,23 +428,30 @@ public override void Send<T>(IOutboundMessage<T> message)
                 }
             }
 
-            protected override Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
+            protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
                 Action setupAction,
                 int responseTimeoutMs = 1000,
                 int completionTimeoutMs = 250,
-                CancellationToken cancellationToken = default)
+                CancellationToken cancellationToken = default,
+                Func<CancellationToken, Task>? prepareAsync = null)
             {
+                // Honor the exchange's prepare phase the way the real device does: it runs first,
+                // before anything this exchange sends (#396).
+                if (prepareAsync != null)
+                {
+                    await prepareAsync(cancellationToken).ConfigureAwait(false);
+                }
+
                 // Run the setup action so that Send() calls inside it are captured
                 setupAction();
                 TextCommandAttemptCount++;
 
                 if (_failFirstAttempt && TextCommandAttemptCount == 1)
                 {
-                    return Task.FromResult<IReadOnlyList<string>>(
-                        new[] { "**ERROR: -200, \"Execution error\"\r\n" });
+                    return new[] { "**ERROR: -200, \"Execution error\"\r\n" };
                 }
 
-                return Task.FromResult(_textCommandResponse);
+                return _textCommandResponse;
             }
         }
 
@@ -501,12 +508,20 @@ public override void Send<T>(IOutboundMessage<T> message)
                 }
             }
 
-            protected override Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
+            protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
                 Action setupAction,
                 int responseTimeoutMs = 1000,
                 int completionTimeoutMs = 250,
-                CancellationToken cancellationToken = default)
+                CancellationToken cancellationToken = default,
+                Func<CancellationToken, Task>? prepareAsync = null)
             {
+                // Honor the exchange's prepare phase the way the real device does: it runs first,
+                // before anything this exchange sends (#396).
+                if (prepareAsync != null)
+                {
+                    await prepareAsync(cancellationToken).ConfigureAwait(false);
+                }
+
                 var before = _sent.Count;
                 setupAction();
                 var sentThisCall = _sent.Skip(before).ToList();
@@ -519,21 +534,19 @@ protected override Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
                     switch (_usbStepBehavior)
                     {
                         case UsbStepBehavior.ScpiError:
-                            return Task.FromResult<IReadOnlyList<string>>(
-                                new[] { "**ERROR: -200, \"Execution error\"\r\n" });
+                            return new[] { "**ERROR: -200, \"Execution error\"\r\n" };
                         case UsbStepBehavior.ScpiErrorThenSucceed:
                             if (UsbStepAttemptCount == 1)
                             {
-                                return Task.FromResult<IReadOnlyList<string>>(
-                                    new[] { "**ERROR: -200, \"Execution error\"\r\n" });
+                                return new[] { "**ERROR: -200, \"Execution error\"\r\n" };
                             }
                             break;
                         case UsbStepBehavior.Cancel:
                             throw new OperationCanceledException();
                     }
                 }
 
-                return Task.FromResult<IReadOnlyList<string>>(Array.Empty<string>());
+                return Array.Empty<string>();
             }
         }
     }

src/Daqifi.Core.Tests/Device/DaqifiDeviceStaleTextLineTests.cs

@@ -55,7 +55,106 @@ public async Task ExecuteTextCommand_KeepsLinesThatArriveAfterTheExchangeSentSom
         device.Disconnect();
     }
 
-    /// <summary>Exposes the protected text-exchange entry point.</summary>
+    [Fact]
+    public async Task ExecuteTextCommandWithPrepare_RunsPrepareBeforeTheSetupAction()
+    {
+        using var transport = new ReleaseOnStreamAccessMockTransport("0,\"No error\"\r\n");
+        using var device = new StaleLineTestableDevice("Prepared Device", transport);
+
+        device.Connect();
+
+        var order = new List<string>();
+        await device.CallWithPrepareAsync(
+            _ => { order.Add("prepare"); return Task.CompletedTask; },
+            () => order.Add("setup"));
+
+        Assert.Equal(new[] { "prepare", "setup" }, order);
+
+        device.Disconnect();
+    }
+
+    [Fact]
+    public async Task ExecuteTextCommandWithPrepare_RunsPrepareInsideTheExchange()
+    {
+        // The property that matters for the SD card operations: the prepare phase holds the
+        // device-wide text-exchange lock, so no competing exchange can interleave between the SPI
+        // bus switch it performs and the commands that depend on it. Asserted through the
+        // exchange's own re-entrancy guard rather than by racing two threads — if prepare runs
+        // inside the critical section, a nested exchange must be refused, and if it had been
+        // hoisted back outside the lock this would silently succeed instead.
+        using var transport = new ReleaseOnStreamAccessMockTransport("0,\"No error\"\r\n");
+        using var device = new StaleLineTestableDevice("Nested Device", transport);
+
+        device.Connect();
+
+        var ex = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => device.CallWithPrepareAsync(
+                async _ => await device.CallExecuteTextCommandAsync(() => { }),
+                () => { }));
+
+        Assert.Contains("not re-entrant", ex.Message);
+
+        device.Disconnect();
+    }
+
+    [Fact]
+    public async Task ExecuteTextCommand_CarryingAPreparePhase_IsStillCaughtByASubclassOverride()
+    {
+        // The prepare phase is a parameter on the existing virtual rather than a second virtual
+        // method, so a subclass that overrides ExecuteTextCommandAsync keeps intercepting the SD
+        // operations that use it. A parallel seam would route past such an override with no compile
+        // error and no runtime signal — an instrumented device or test double would simply stop
+        // seeing SD traffic. If this ever regresses to a sibling method, this test fails.
+        using var transport = new ReleaseOnStreamAccessMockTransport("0,\"No error\"\r\n");
+        using var device = new InterceptingTestableDevice("Intercepting Device", transport);
+
+        device.Connect();
+
+        var prepared = false;
+        var lines = await device.CallWithPrepareAsync(
+            _ => { prepared = true; return Task.CompletedTask; },
+            () => { });
+
+        Assert.True(device.Intercepted, "The subclass override did not see the call.");
+        Assert.True(prepared, "The override was handed the prepare phase and ran it.");
+        Assert.Equal(new[] { "from the override" }, lines);
+
+        device.Disconnect();
+    }
+
+    /// <summary>
+    /// Stands in for a downstream subclass or test double that intercepts the text exchange —
+    /// the case the single-seam design protects.
+    /// </summary>
+    private sealed class InterceptingTestableDevice : StaleLineTestableDevice
+    {
+        public InterceptingTestableDevice(string name, IStreamTransport transport)
+            : base(name, transport)
+        {
+        }
+
+        public bool Intercepted { get; private set; }
+
+        protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
+            Action setupAction,
+            int responseTimeoutMs = 1000,
+            int completionTimeoutMs = 250,
+            CancellationToken cancellationToken = default,
+            Func<CancellationToken, Task>? prepareAsync = null)
+        {
+            Intercepted = true;
+
+            if (prepareAsync != null)
+            {
+                await prepareAsync(cancellationToken).ConfigureAwait(false);
+            }
+
+            setupAction();
+            return new List<string> { "from the override" };
+        }
+    }
+
+    /// <summary>Exposes the protected text-exchange entry points.</summary>
     private class StaleLineTestableDevice : DaqifiDevice
     {
         public StaleLineTestableDevice(string name, IStreamTransport transport)
@@ -67,6 +166,17 @@ public Task<IReadOnlyList<string>> CallExecuteTextCommandAsync(Action setupActio
         {
             return ExecuteTextCommandAsync(setupAction, responseTimeoutMs: 500, completionTimeoutMs: 150);
         }
+
+        public Task<IReadOnlyList<string>> CallWithPrepareAsync(
+            Func<CancellationToken, Task> prepareAsync,
+            Action setupAction)
+        {
+            return ExecuteTextCommandAsync(
+                setupAction,
+                responseTimeoutMs: 500,
+                completionTimeoutMs: 150,
+                prepareAsync: prepareAsync);
+        }
     }
 
     /// <summary>

src/Daqifi.Core.Tests/Device/Diagnostics/DeviceDiagnosticsTests.cs

@@ -302,15 +302,23 @@ public override void Send<T>(IOutboundMessage<T> message)
             }
         }
 
-        protected override Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
+        protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
             Action setupAction,
             int responseTimeoutMs = 1000,
             int completionTimeoutMs = 250,
-            CancellationToken cancellationToken = default)
+            CancellationToken cancellationToken = default,
+            Func<CancellationToken, Task>? prepareAsync = null)
         {
+            // Honor the exchange's prepare phase the way the real device does: it runs first,
+            // before anything this exchange sends (#396).
+            if (prepareAsync != null)
+            {
+                await prepareAsync(cancellationToken).ConfigureAwait(false);
+            }
+
             cancellationToken.ThrowIfCancellationRequested();
             setupAction();
-            return Task.FromResult<IReadOnlyList<string>>(CannedTextResponse.ToList());
+            return CannedTextResponse.ToList();
         }
 
         protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(

src/Daqifi.Core.Tests/Device/GetLanChipInfoAsyncTests.cs

@@ -90,15 +90,23 @@ public override void Send<T>(IOutboundMessage<T> message)
             }
         }
 
-        protected override Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
+        protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(
             Action setupAction,
             int responseTimeoutMs = 1000,
             int completionTimeoutMs = 250,
-            CancellationToken cancellationToken = default)
+            CancellationToken cancellationToken = default,
+            Func<CancellationToken, Task>? prepareAsync = null)
         {
+            // Honor the exchange's prepare phase the way the real device does: it runs first,
+            // before anything this exchange sends (#396).
+            if (prepareAsync != null)
+            {
+                await prepareAsync(cancellationToken).ConfigureAwait(false);
+            }
+
             cancellationToken.ThrowIfCancellationRequested();
             setupAction();
-            return Task.FromResult<IReadOnlyList<string>>(CannedTextResponse.ToList());
+            return CannedTextResponse.ToList();
         }
 
         protected override async Task<IReadOnlyList<string>> ExecuteTextCommandAsync(