Resolve Client.Dotnet-018..021: README + bench-read-bulk hardening

Client.Dotnet-018  README CLI examples for stream-alarms / acknowledge-alarm
                   replaced with parser-correct flags; new theory test
                   parses each documented README example through the CLI.
Client.Dotnet-019  BenchReadBulkAsync routes through new
                   RequireRegisterServerHandle helper that fails loudly when
                   the OK register reply has no typed payload.
Client.Dotnet-020  Bench steady-state catch is now
                   catch (Exception ex) when (ex is not OperationCanceledException)
                   so user-driven cancellation exits promptly.
Client.Dotnet-021  --timeout-ms now flows through ParseTimeoutMs which
                   rejects negatives with a clear error in both read-bulk
                   and bench-read-bulk.

All resolved at 2026-05-24; 67/67 .NET client tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs

@@ -487,7 +487,7 @@ public static class MxGatewayClientCli
         ReadBulkCommand command = new()
         {
             ServerHandle = arguments.GetInt32("server-handle"),
-            TimeoutMs = (uint)arguments.GetInt32("timeout-ms", 0),
+            TimeoutMs = ParseTimeoutMs(arguments, defaultValue: 0),
         };
         command.TagAddresses.Add(ParseStringList(arguments.GetRequired("items")));
 
@@ -692,6 +692,49 @@ public static class MxGatewayClientCli
         }
     }
 
+    /// <summary>
+    ///     Parses the optional <c>--timeout-ms</c> argument as a non-negative
+    ///     unsigned millisecond count. Mirrors the SDK-side <c>(uint)Math.Min</c>
+    ///     guard on <c>MxGatewaySession.ReadBulkAsync</c>: a negative value
+    ///     (e.g. <c>-1</c>, an easy copy-paste mistake for "unbounded") is
+    ///     rejected loudly rather than silently wrapped to <c>~49.7 days</c>,
+    ///     which would park one worker thread per pending tag for hours.
+    ///     Resolves Client.Dotnet-021.
+    /// </summary>
+    private static uint ParseTimeoutMs(CliArguments arguments, int defaultValue)
+    {
+        int raw = arguments.GetInt32("timeout-ms", defaultValue);
+        if (raw < 0)
+        {
+            throw new ArgumentException(
+                "--timeout-ms must be a non-negative integer (use 0 for the gateway default).");
+        }
+
+        return (uint)raw;
+    }
+
+    /// <summary>
+    ///     Extracts the <c>ServerHandle</c> from a Register reply, throwing a
+    ///     descriptive <see cref="MxGatewayException"/> when the typed
+    ///     <c>Register</c> payload is absent on an otherwise-successful reply.
+    ///     The typed sub-message is the contract for the Register command, so
+    ///     its absence must not silently fall through to
+    ///     <c>ReturnValue.Int32Value</c> (which would be <c>0</c> for an empty
+    ///     reply, driving the rest of the bench against an invalid handle).
+    ///     Resolves Client.Dotnet-019.
+    /// </summary>
+    private static int RequireRegisterServerHandle(MxCommandReply reply, string sessionId)
+    {
+        if (reply.Register is null)
+        {
+            throw new MxGatewayException(
+                $"Gateway reply for Register on session '{sessionId}' (correlation '{reply.CorrelationId}') "
+                + "succeeded but is missing the typed 'register' payload required to read ServerHandle.");
+        }
+
+        return reply.Register.ServerHandle;
+    }
+
     /// <summary>
     ///     Cross-language stress benchmark for ReadBulk. Opens its own session,
     ///     subscribes to N tags so the worker's MxAccessValueCache populates from
@@ -712,7 +755,7 @@ public static class MxGatewayClientCli
         int tagStart = arguments.GetInt32("tag-start", 1);
         string tagPrefix = arguments.GetOptional("tag-prefix") ?? "TestMachine_";
         string tagAttribute = arguments.GetOptional("tag-attribute") ?? "TestChangingInt";
-        uint timeoutMs = (uint)arguments.GetInt32("timeout-ms", 1500);
+        uint timeoutMs = ParseTimeoutMs(arguments, defaultValue: 1500);
         string clientName = arguments.GetOptional("client-name") ?? "mxgw-dotnet-bench";
 
         string[] tags = new string[bulkSize];
@@ -742,7 +785,7 @@ public static class MxGatewayClientCli
                     }),
                     cancellationToken)
                 .ConfigureAwait(false);
-            int serverHandle = registerReply.Register?.ServerHandle ?? registerReply.ReturnValue.Int32Value;
+            int serverHandle = RequireRegisterServerHandle(registerReply, sessionId);
 
             SubscribeBulkCommand subscribe = new() { ServerHandle = serverHandle };
             subscribe.TagAddresses.Add(tags);
@@ -801,8 +844,13 @@ public static class MxGatewayClientCli
                         .ConfigureAwait(false);
                     sw.Stop();
                 }
-                catch
+                catch (Exception ex) when (ex is not OperationCanceledException)
                 {
+                    // Client.Dotnet-020: never swallow OperationCanceledException
+                    // here. A bare `catch` would let Ctrl+C / parent CTS /
+                    // wall-clock timeouts keep spinning until --duration-seconds
+                    // elapsed, burning CPU and skewing the p99/max latency numbers
+                    // with hundreds of immediate-OCE iterations.
                     sw.Stop();
                     failedCalls++;
                     latencyMillis.Add(sw.Elapsed.TotalMilliseconds);