docs(src): add missing XML docs and strip tracking-ID comments

Sweep of 203 source files resolving CommentChecker findings: add
<summary>/<param>/<returns>/<inheritdoc> where missing, and remove
resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN,
Task N) from code comments. Comment/doc-only — no logic changes.
Server+Tests build clean under TreatWarningsAsErrors.

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs

@@ -14,6 +14,7 @@ namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Sessions;
 public sealed class SessionManagerTests
 {
     /// <summary>Verifies that opening a session with a ready worker registers the session in ready state.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_WithWorkerReady_RegistersReadySession()
     {
@@ -37,6 +38,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that a session opened by an authenticated caller records that caller's API key id in OwnerKeyId.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_WithOwnerKeyId_RecordsOwnerKeyIdOnSession()
     {
@@ -52,6 +54,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that a session opened without an owner key id records null in OwnerKeyId.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_WithNullOwnerKeyId_RecordsNullOwnerKeyIdOnSession()
     {
@@ -67,6 +70,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that opening a session sets the initial lease expiry from the configured default lease.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_SetsInitialDefaultLease()
     {
@@ -83,6 +87,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that session generation creates client correlation ID from client name and session ID.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_GeneratesClientCorrelationIdFromClientNameAndSessionId()
     {
@@ -99,6 +104,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that opening a session without a client session name uses the client correlation prefix.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_WhenClientSessionNameMissing_UsesClientCorrelationPrefix()
     {
@@ -114,6 +120,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that invoking a command on a ready session forwards the command to the worker.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenSessionReady_ForwardsCommandToWorker()
     {
@@ -131,6 +138,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that invoking a command on a ready session refreshes its lease expiry.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenSessionReady_RefreshesLease()
     {
@@ -159,6 +167,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that gateway session subscribe bulk forwards one bulk command and returns results.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GatewaySessionSubscribeBulkAsync_ForwardsOneBulkCommandAndReturnsResults()
     {
@@ -204,6 +213,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that gateway session write bulk forwards one bulk command and returns results.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GatewaySessionWriteBulkAsync_ForwardsOneBulkCommandAndReturnsResults()
     {
@@ -269,6 +279,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that gateway session read bulk forwards one bulk command and returns results.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task GatewaySessionReadBulkAsync_ForwardsOneBulkCommandAndReturnsResults()
     {
@@ -319,6 +330,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that invoking a command on a faulted session rejects the command.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenSessionFaulted_RejectsCommand()
     {
@@ -338,12 +350,13 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    ///     Server-030 regression: when the gateway-side <c>SessionState</c> is
+    ///     When the gateway-side <c>SessionState</c> is
     ///     <c>Ready</c> but the worker client's own state is not, the diagnostic
     ///     must surface both states so the mismatch is actionable instead of
     ///     producing a self-contradictory "Session ... is not ready. Current
     ///     state is Ready." message.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenWorkerNotReadyButSessionReady_DiagnosticIncludesBothStates()
     {
@@ -372,6 +385,7 @@ public sealed class SessionManagerTests
     ///     <c>Handshaking</c> but flips to <c>Ready</c> within the timeout window must let the
     ///     command through rather than fail fast.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenWorkerHandshakingThenReadyWithinTimeout_Succeeds()
     {
@@ -402,6 +416,7 @@ public sealed class SessionManagerTests
     ///     A terminal worker state (<c>Faulted</c>) must fail fast even with a positive
     ///     worker-ready wait timeout, surfacing both states without burning the timeout.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenWorkerFaulted_FailsFastWithBothStates()
     {
@@ -431,6 +446,7 @@ public sealed class SessionManagerTests
     ///     When the worker stays transiently not-ready for the whole (small) timeout window,
     ///     the invoke fails after roughly the timeout with both states surfaced.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenTimeoutElapsesStillNotReady_FailsWithBothStates()
     {
@@ -460,6 +476,7 @@ public sealed class SessionManagerTests
     ///     Pins the default (timeout == 0) behavior: a transiently <c>Handshaking</c> worker
     ///     fails fast immediately, byte-for-byte like the original fail-fast path.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task InvokeAsync_WhenTimeoutZero_FailsFastUnchanged()
     {
@@ -486,6 +503,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that closing a session removes it from the registry.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseSessionAsync_RemovesClosedSession()
     {
@@ -507,6 +525,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that closing a session kills the worker when shutdown fails.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseSessionAsync_WhenWorkerShutdownFails_KillsWorker()
     {
@@ -528,6 +547,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that when worker shutdown fails, the session is removed and the slot is released.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseSessionAsync_WhenWorkerShutdownFails_RemovesSessionAndReleasesSlot()
     {
@@ -567,15 +587,13 @@ public sealed class SessionManagerTests
         Assert.Equal(1, failingWorkerClient.KillCount);
         Assert.Equal(1, failingWorkerClient.DisposeCount);
         GatewayMetricsSnapshot snapshot = metrics.GetSnapshot();
-        // Server-046: a close-that-failed now accounts as SessionClosed (counter += 1) rather
-        // than SessionRemoved (gauge -= 1, counter unchanged). The session is being removed
-        // from the registry on this path, so it must show up in the closed count.
         Assert.Equal(1, snapshot.SessionsClosed);
         Assert.False(snapshot.EventsBySession.ContainsKey(firstSession.SessionId));
         Assert.Equal(1, snapshot.OpenSessions);
     }
 
     /// <summary>Verifies that when the second close is canceled, the session is not removed if owned by the first close.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseSessionAsync_WhenSecondCloseIsCanceled_DoesNotRemoveSessionOwnedByFirstClose()
     {
@@ -626,10 +644,8 @@ public sealed class SessionManagerTests
 
     /// <summary>
     /// Verifies that killing a worker removes the session from the registry without calling shutdown.
-    /// Tests-028: also pins the <c>reason</c> argument propagating through
-    /// <c>SessionManager.KillWorkerAsync</c> → <c>session.KillWorker(reason)</c> →
-    /// <c>IWorkerClient.Kill(reason)</c>.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task KillWorkerAsync_KillsWorkerAndRemovesSession()
     {
@@ -651,11 +667,12 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    /// Tests-028: <see cref="SessionManager.KillWorkerAsync"/> guards its <c>reason</c> argument with
+    /// <see cref="SessionManager.KillWorkerAsync"/> guards its <c>reason</c> argument with
     /// <see cref="ArgumentException.ThrowIfNullOrWhiteSpace"/>. A blank or whitespace reason must throw
     /// <see cref="ArgumentException"/> before any session lookup or worker call runs.
     /// </summary>
     /// <param name="blankReason">A blank or whitespace reason string.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Theory]
     [InlineData("")]
     [InlineData(" ")]
@@ -674,10 +691,11 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    /// Tests-028: <see cref="ArgumentException.ThrowIfNullOrWhiteSpace"/> also rejects null.
+    /// <see cref="ArgumentException.ThrowIfNullOrWhiteSpace"/> also rejects null.
     /// <see cref="Theory"/> with <see cref="InlineDataAttribute"/> cannot carry <c>null</c> for a
     /// non-nullable string parameter on .NET 10, so the null case is its own fact.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task KillWorkerAsync_WithNullReason_ThrowsArgumentNullException()
     {
@@ -693,6 +711,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that killing the worker for an unknown session raises SessionNotFound.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task KillWorkerAsync_WhenSessionMissing_ThrowsSessionNotFound()
     {
@@ -705,10 +724,10 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    /// Regression for Server-044: when <c>session.KillWorker</c> throws, the catch path must still
-    /// decrement <c>mxgateway.sessions.open</c> (parity with the Server-006 fix in
-    /// <c>OpenSessionAsync</c>). Without the fix the gauge leaks one open session per failed kill.
+    /// When <c>session.KillWorker</c> throws, the catch path must still
+    /// decrement <c>mxgateway.sessions.open</c>. Without the fix the gauge leaks one open session per failed kill.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task KillWorkerAsync_WhenSessionKillThrows_DecrementsOpenSessionGauge()
     {
@@ -738,10 +757,11 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    /// Regression for Server-045 / Server-048: concurrent kills on the same session must not
+    /// Concurrent kills on the same session must not
     /// double-increment <c>mxgateway.sessions.closed</c>. The first kill wins, the second
     /// observes <c>wasClosed == true</c> (or a missing session after removal) and short-circuits.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task KillWorkerAsync_ConcurrentCallsOnSameSession_CountClosedExactlyOnce()
     {
@@ -777,12 +797,13 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    /// Regression for Server-046: <c>ShutdownAsync</c>'s graceful-close fallback (which calls
+    /// <c>ShutdownAsync</c>'s graceful-close fallback (which calls
     /// <c>KillWorker</c> + <c>RemoveSessionAsync</c> when <c>CloseSessionCoreAsync</c> throws)
     /// must still account a successful close: both the open-session gauge must drop to zero AND
     /// the <c>mxgateway.sessions.closed</c> counter must increment. Without the fix, the
     /// graceful-close failure path under-counts the closed counter.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ShutdownAsync_WhenSessionCloseThrows_StillDecrementsOpenSessionGaugeAndIncrementsClosedCounter()
     {
@@ -812,6 +833,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that when worker creation fails, the session is removed from the registry.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task OpenSessionAsync_WhenWorkerCreationFails_RemovesSessionFromRegistry()
     {
@@ -832,6 +854,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that closing expired leases only closes expired sessions.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseExpiredLeasesAsync_ClosesExpiredSessionsOnly()
     {
@@ -855,6 +878,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that an expired-lease sweep leaves a session with an active event subscriber open.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseExpiredLeasesAsync_DoesNotCloseActiveEventSubscriber()
     {
@@ -873,10 +897,11 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    ///     Task 11. With detach-grace enabled, a session whose last external subscriber dropped
+    ///     With detach-grace enabled, a session whose last external subscriber dropped
     ///     and whose detach-grace window has elapsed is closed by the lease sweep exactly like an
     ///     expired-lease session — even though its normal lease is still far in the future.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseExpiredLeasesAsync_ClosesSessionWhoseDetachGraceWindowExpired()
     {
@@ -909,11 +934,12 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>
-    ///     Task 11. TOCTOU race: a session whose detach-grace window has expired but that
+    ///     TOCTOU race: a session whose detach-grace window has expired but that
     ///     reattaches an external subscriber before the sweeper calls CloseSessionCoreAsync is
     ///     NOT closed — it remains Ready and usable. This validates that TryBeginCloseIfExpired
     ///     re-checks eligibility atomically so a reconnect that wins the race cancels the close.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CloseExpiredLeasesAsync_DoesNotCloseSessionThatReattachedBeforeSweepCloses()
     {
@@ -950,6 +976,7 @@ public sealed class SessionManagerTests
     }
 
     /// <summary>Verifies that shutdown closes all registered sessions.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ShutdownAsync_ClosesAllRegisteredSessions()
     {
@@ -1097,16 +1124,16 @@ public sealed class SessionManagerTests
 
     private sealed class FakeWorkerClient : IWorkerClient
     {
-        /// <summary>Gets the session ID for the fake worker client.</summary>
+        /// <inheritdoc />
         public string SessionId { get; init; } = "session-1";
 
-        /// <summary>Gets the process ID for the fake worker client.</summary>
+        /// <inheritdoc />
         public int? ProcessId { get; init; } = 1234;
 
-        /// <summary>Gets or sets the state of the fake worker client.</summary>
+        /// <inheritdoc />
         public WorkerClientState State { get; set; } = WorkerClientState.Ready;
 
-        /// <summary>Gets the last heartbeat timestamp for the fake worker client.</summary>
+        /// <inheritdoc />
         public DateTimeOffset LastHeartbeatAt { get; init; } = DateTimeOffset.UtcNow;
 
         /// <summary>Gets the number of times invoke was called on the fake worker client.</summary>
@@ -1118,13 +1145,7 @@ public sealed class SessionManagerTests
         /// <summary>Gets the number of times kill was called on the fake worker client.</summary>
         public int KillCount { get; private set; }
 
-        /// <summary>
-        /// Gets the last reason argument observed by <see cref="Kill"/>. Tests-028:
-        /// pins the reason-string propagation through
-        /// <c>SessionManager.KillWorkerAsync</c> → <c>session.KillWorker(reason)</c> →
-        /// <c>IWorkerClient.Kill(reason)</c>. Without this, the chain could silently
-        /// drop or substitute the reason argument and existing tests would still pass.
-        /// </summary>
+        /// <summary>Gets the last reason argument observed by <see cref="Kill"/>.</summary>
         public string? LastKillReason { get; private set; }
 
         /// <summary>Gets the number of times dispose was called on the fake worker client.</summary>
@@ -1222,7 +1243,8 @@ public sealed class SessionManagerTests
             State = WorkerClientState.Faulted;
         }
 
-        /// <inheritdoc />
+        /// <summary>Records that the fake worker client was disposed.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public ValueTask DisposeAsync()
         {
             DisposeCount++;
@@ -1230,6 +1252,7 @@ public sealed class SessionManagerTests
         }
 
         /// <summary>Waits for shutdown to start on the fake worker client.</summary>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public Task WaitForShutdownStartAsync()
         {
             return ShutdownStarted.Task.WaitAsync(TimeSpan.FromSeconds(5));