fix(client/python): cap setuptools<77 so dist stays metadata 2.2 for Gitea PyPI feed; proprietary via classifier

chore(clients): bump all five clients 0.1.0 -> 0.1.1 for release
docs(code-review): regenerate index — all re-review findings resolved
2026-06-15 05:30:22 -04:00 · 2026-06-15 05:07:17 -04:00 · 2026-06-15 03:04:37 -04:00 · 2026-06-15 03:01:13 -04:00 · 2026-06-15 02:56:15 -04:00 · 2026-06-15 02:56:15 -04:00
87 changed files with 4359 additions and 326 deletions
@@ -1,4 +1,17 @@
 <Project>
+  <PropertyGroup>
+    <!-- Build-quality enforcement floor, mirroring src/Directory.Build.props so the
+         .NET client tree is held to the same baseline CLAUDE.md mandates (warnings as
+         errors, code-style enforced at build, latest analyzers, deterministic builds). -->
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AnalysisLevel>latest</AnalysisLevel>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <Deterministic>true</Deterministic>
+  </PropertyGroup>
+
  <PropertyGroup>
    <!-- Shared package metadata for clients/dotnet/. Individual projects opt in via <IsPackable>true</IsPackable>. -->
    <Authors>Joseph Doherty</Authors>
@@ -10,11 +23,15 @@
    <PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/mxaccessgw</PackageProjectUrl>
    <PackageTags>mxaccess;mxgateway;grpc;client;archestra</PackageTags>
    <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
+    <!-- Proprietary/internal package, consistent with the Rust ("Proprietary") and
+         Python ("Proprietary") client license declarations. A LicenseRef SPDX expression
+         is rejected by the current NuGet toolset (NU5124), so the proprietary terms ship
+         as a packaged license file instead. -->
+    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
    <!-- Versioning: bump per release. Symbols ship as snupkg. -->
-    <Version>0.1.0</Version>
+    <Version>0.1.1</Version>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <!-- Default: do NOT pack. Each project opts in. -->
    <IsPackable>false</IsPackable>
  </PropertyGroup>
@@ -0,0 +1,12 @@
+Proprietary License
+
+Copyright (c) ZB MOM WW. All rights reserved.
+
+This software and its source code are proprietary and confidential. They are
+licensed, not sold, for internal use within ZB MOM WW and its authorized
+partners only. No part of this package may be reproduced, distributed, or
+transmitted to third parties without the prior written permission of ZB MOM WW.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
@@ -328,7 +328,7 @@ dotnet nuget add source https://gitea.dohertylan.com/api/packages/dohertj2/nuget
 Then add the package to your project:

 ````bash
-dotnet add package ZB.MOM.WW.MxGateway.Client --version 0.1.0
+dotnet add package ZB.MOM.WW.MxGateway.Client --version 0.1.1
 ````

 The `ZB.MOM.WW.MxGateway.Contracts` package is pulled in transitively.
@@ -135,25 +135,35 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
    /// <summary>Queue of exceptions to throw from BrowseChildren; dequeued in FIFO order.</summary>
    public Queue<Exception> BrowseChildrenExceptions { get; } = new();

+    /// <summary>
+    /// Optional hook awaited inside BrowseChildren before the reply is produced. Lets a
+    /// test hold an RPC mid-flight to exercise concurrent reads of the in-progress node.
+    /// </summary>
+    public Func<Task>? BrowseChildrenGate { get; set; }
+
    /// <summary>
    /// Records the request and either throws a queued exception or returns the configured reply.
    /// </summary>
    /// <param name="request">The BrowseChildrenRequest to process.</param>
    /// <param name="callOptions">Call options specifying RPC behavior.</param>
-    public Task<BrowseChildrenReply> BrowseChildrenAsync(
+    public async Task<BrowseChildrenReply> BrowseChildrenAsync(
        BrowseChildrenRequest request,
        CallOptions callOptions)
    {
        BrowseChildrenCalls.Add((request, callOptions));
        if (BrowseChildrenExceptions.TryDequeue(out Exception? exception))
        {
-            return Task.FromException<BrowseChildrenReply>(exception);
+            throw exception;
        }

-        return Task.FromResult(
-            BrowseChildrenReplies.TryDequeue(out BrowseChildrenReply? reply)
-                ? reply
-                : BrowseChildrenReply);
+        if (BrowseChildrenGate is { } gate)
+        {
+            await gate().ConfigureAwait(false);
+        }
+
+        return BrowseChildrenReplies.TryDequeue(out BrowseChildrenReply? reply)
+            ? reply
+            : BrowseChildrenReply;
    }

    /// <summary>
@@ -175,6 +175,96 @@ public sealed class LazyBrowseNodeTests
        Assert.Equal(2, transport.BrowseChildrenCalls.Count);
    }

+    /// <summary>
+    /// Verifies that reading Children/IsExpanded concurrently with an in-flight ExpandAsync
+    /// never throws (no torn enumeration of a mid-append list) and, once IsExpanded flips to
+    /// true, the published Children snapshot is fully populated. Pins the safe-publication
+    /// contract on the lock-free readers (Client.Dotnet-025).
+    /// </summary>
+    [Fact]
+    public async Task Expand_ConcurrentReadOfChildren_NeverTearsAndPublishesAtomically()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(1, "Plant", isArea: true)],
+            childHasChildren: [true],
+            cacheSequence: 1));
+
+        // Multi-page child set so the expand loop spends meaningful time appending,
+        // widening the window for a concurrent reader to observe a torn list.
+        BrowseChildrenReply childPage1 = BuildReply(
+            children: [BuildObject(10, "A"), BuildObject(11, "B"), BuildObject(12, "C")],
+            childHasChildren: [false, false, false],
+            cacheSequence: 1);
+        childPage1.NextPageToken = "1:p:3";
+        transport.BrowseChildrenReplies.Enqueue(childPage1);
+        transport.BrowseChildrenReplies.Enqueue(BuildReply(
+            children: [BuildObject(13, "D"), BuildObject(14, "E")],
+            childHasChildren: [false, false],
+            cacheSequence: 1));
+
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+        IReadOnlyList<LazyBrowseNode> roots = await client.BrowseAsync();
+        LazyBrowseNode node = roots[0];
+
+        // Gate the child-page RPCs so the expand stays mid-flight while the reader spins.
+        using SemaphoreSlim release = new(0, 1);
+        bool firstChildCall = true;
+        transport.BrowseChildrenGate = async () =>
+        {
+            if (firstChildCall)
+            {
+                firstChildCall = false;
+                await release.WaitAsync().ConfigureAwait(false);
+            }
+        };
+
+        using CancellationTokenSource readerStop = new();
+        Exception? readerFailure = null;
+        Task reader = Task.Run(() =>
+        {
+            try
+            {
+                while (!readerStop.IsCancellationRequested)
+                {
+                    bool expanded = node.IsExpanded;
+
+                    // Enumerate the snapshot; a torn/mid-append list would throw here.
+                    int count = 0;
+                    foreach (LazyBrowseNode _ in node.Children)
+                    {
+                        count++;
+                    }
+
+                    // If the node reports expanded, the published snapshot must be complete.
+                    if (expanded)
+                    {
+                        Assert.Equal(5, count);
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                readerFailure = ex;
+            }
+        });
+
+        Task expand = node.ExpandAsync();
+        // Let the reader spin against the empty pre-publication snapshot for a moment.
+        await Task.Delay(50);
+        release.Release();
+        await expand;
+
+        // Let the reader observe the post-publication state, then stop it.
+        await Task.Delay(50);
+        readerStop.Cancel();
+        await reader;
+
+        Assert.Null(readerFailure);
+        Assert.True(node.IsExpanded);
+        Assert.Equal(5, node.Children.Count);
+    }
+
    /// <summary>
    /// Verifies that BrowseChildrenOptions filter fields are forwarded to the BrowseChildren request.
    /// </summary>
@@ -12,9 +12,14 @@ public sealed class LazyBrowseNode
 {
    private readonly GalaxyRepositoryClient _client;
    private readonly BrowseChildrenOptions _options;
-    private readonly List<LazyBrowseNode> _children = [];
    private readonly SemaphoreSlim _expandLock = new(1, 1);
-    private bool _isExpanded;
+
+    // Published once, under _expandLock, when expansion completes. Lock-free readers
+    // see either the empty pre-expansion snapshot or the fully-populated post-expansion
+    // snapshot — never a partially-filled list — because the snapshot is built in a local
+    // and handed off via Volatile.Write (release) paired with Volatile.Read (acquire).
+    private IReadOnlyList<LazyBrowseNode> _children = [];
+    private volatile bool _isExpanded;

    internal LazyBrowseNode(
        GalaxyRepositoryClient client,
@@ -35,7 +40,7 @@ public sealed class LazyBrowseNode
    public bool HasChildrenHint { get; }

    /// <summary>Direct children loaded by <see cref="ExpandAsync"/>; empty until then.</summary>
-    public IReadOnlyList<LazyBrowseNode> Children => _children;
+    public IReadOnlyList<LazyBrowseNode> Children => Volatile.Read(ref _children);

    /// <summary>True after the first <see cref="ExpandAsync"/> call completes.</summary>
    public bool IsExpanded => _isExpanded;
@@ -46,7 +51,13 @@ public sealed class LazyBrowseNode
    /// </summary>
    /// <remarks>
    ///     Thread-safe: concurrent callers see exactly one fetch; subsequent callers
-    ///     (after the first completes) return immediately.
+    ///     (after the first completes) return immediately. <see cref="Children"/> and
+    ///     <see cref="IsExpanded"/> may be read concurrently with an in-flight
+    ///     <see cref="ExpandAsync"/> on another thread; the populated children are
+    ///     published as an immutable snapshot under a release barrier, so a reader that
+    ///     observes <see cref="IsExpanded"/> as <see langword="true"/> always sees the
+    ///     fully-populated <see cref="Children"/>, and a reader never enumerates a
+    ///     partially-built list.
    /// </remarks>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    public async Task ExpandAsync(CancellationToken cancellationToken = default)
@@ -64,6 +75,10 @@ public sealed class LazyBrowseNode
                return;
            }

+            // Accumulate into a local list, never the published field, so a lock-free
+            // reader can never observe a half-populated collection or enumerate a list
+            // that is being mutated mid-append.
+            List<LazyBrowseNode> children = [];
            string pageToken = string.Empty;
            HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
            do
@@ -79,7 +94,7 @@ public sealed class LazyBrowseNode
                for (int i = 0; i < reply.Children.Count; i++)
                {
                    bool hint = i < reply.ChildHasChildren.Count && reply.ChildHasChildren[i];
-                    _children.Add(new LazyBrowseNode(_client, reply.Children[i], hint, _options));
+                    children.Add(new LazyBrowseNode(_client, reply.Children[i], hint, _options));
                }

                pageToken = reply.NextPageToken;
@@ -91,6 +106,10 @@ public sealed class LazyBrowseNode
            }
            while (!string.IsNullOrWhiteSpace(pageToken));

+            // Publish the completed, immutable snapshot (release) before marking the node
+            // expanded (the volatile write below). A reader that observes IsExpanded == true
+            // is guaranteed to also observe the fully-populated Children.
+            Volatile.Write(ref _children, children);
            _isExpanded = true;
        }
        finally
@@ -21,10 +21,15 @@
    <PackageId>ZB.MOM.WW.MxGateway.Client</PackageId>
    <Description>.NET 10 gRPC client for the MxAccessGateway service. Provides typed wrappers, retry, and a lazy-browse walker over the Galaxy Repository hierarchy.</Description>
    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <!-- Only the shipped library generates XML docs (matching src/Contracts). The Cli and
+         Tests projects are not packable and do not document their public surface, so this
+         stays out of the shared Directory.Build.props to avoid CS1591 on test classes. -->
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="..\README.md" Pack="true" PackagePath="\" />
+    <None Include="..\LICENSE.txt" Pack="true" PackagePath="\" />
  </ItemGroup>

  <ItemGroup>
@@ -288,7 +288,7 @@ go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key
 The module is resolved directly from the git repo — no package registry:

 ````bash
-go get gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go@v0.1.0
+go get gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go@v0.1.1
 ````

 Then import:
@@ -299,8 +299,11 @@ import "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway"

 If your build environment cannot reach `gitea.dohertylan.com` directly,
 configure `GOPROXY` to point at an internal proxy that fronts the Gitea
-repo, or use `GONOSUMCHECK` + `GOPRIVATE` to bypass the checksum database
-for the internal module path.
+repo, or set `GOPRIVATE=gitea.dohertylan.com/*` to fetch the module
+straight from the VCS — this both bypasses the public module proxy and
+disables checksum-database (`sum.golang.org`) verification for that path.
+Add `GOINSECURE=gitea.dohertylan.com/*` if the host serves the module over
+plain HTTP rather than HTTPS.

 ## Releasing a new version

@@ -128,18 +128,20 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-discover --endpoint localhost

 ### Browsing lazily

-For UI trees or OPC UA bridges, use `browseChildren` to walk one level at a
+For UI trees or OPC UA bridges, use `browseChildrenRaw` to walk one level at a
 time instead of loading the full hierarchy with `discoverHierarchy`. Pass a
 default request for root objects; subsequent calls set `parentGobjectId`,
 `parentTagName`, or `parentContainedPath`. Filter fields match
 `DiscoverHierarchy`. Each response pairs `getChildrenList()` with
 `getChildHasChildrenList()` so you know which nodes to expand. See
 [Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
-request and filter semantics. This snippet documents the API as it appears once
-the Java client is regenerated on the Windows host.
+request and filter semantics. For most callers the high-level
+`browse()`/`LazyBrowseNode` walker below is the preferred surface;
+`browseChildrenRaw` exposes the single underlying RPC when you need direct
+control of paging.

 ```java
-BrowseChildrenReply reply = galaxy.browseChildren(
+BrowseChildrenReply reply = galaxy.browseChildrenRaw(
        BrowseChildrenRequest.newBuilder().build());

 List<GalaxyObject> children = reply.getChildrenList();
@@ -248,8 +250,11 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint localhost:5000 --ap
 ```

 The CLI accepts `--api-key`, `--api-key-env`, `--plaintext`, `--ca-file`,
-`--server-name-override`, `--timeout`, and `--json` on gateway commands. JSON
-output redacts API keys.
+`--server-name-override`, `--require-certificate-validation`, `--timeout`, and
+`--json` on gateway commands. JSON output redacts API keys. TLS is lenient by
+default (the certificate is not verified unless you pin a CA with `--ca-file`);
+pass `--require-certificate-validation` to verify the server certificate against
+the JVM trust store without pinning.

 Use TLS options for a secured gateway:

@@ -311,7 +316,7 @@ repositories {
 }

 dependencies {
-    implementation 'com.zb.mom.ww.mxgateway:zb-mom-ww-mxgateway-client:0.1.0'
+    implementation 'com.zb.mom.ww.mxgateway:zb-mom-ww-mxgateway-client:0.1.1'
 }
 ````

@@ -13,7 +13,7 @@ ext {

 subprojects {
    group = 'com.zb.mom.ww.mxgateway'
-    version = '0.1.0'
+    version = '0.1.1'

    pluginManager.withPlugin('java') {
        java {
@@ -37,6 +37,7 @@ import java.util.concurrent.atomic.AtomicReference;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply;
 import mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest;
 import mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot;
+import mxaccess_gateway.v1.MxaccessGateway.AlarmProviderStatus;
 import mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage;
 import mxaccess_gateway.v1.MxaccessGateway.BulkReadResult;
 import mxaccess_gateway.v1.MxaccessGateway.BulkWriteResult;
@@ -1366,6 +1367,13 @@ public final class MxGatewayCli implements Callable<Integer> {
        @Option(names = "--server-name-override", description = "TLS server name override.")
        String serverNameOverride = "";

+        @Option(
+                names = "--require-certificate-validation",
+                description =
+                        "Verify the server certificate against the JVM trust store "
+                                + "(disables the lenient default; ignored with --plaintext or --ca-file pinning).")
+        boolean requireCertificateValidation;
+
        @Option(names = "--timeout", defaultValue = "30s", description = "Per-call timeout.")
        String timeout;

@@ -1388,6 +1396,7 @@ public final class MxGatewayCli implements Callable<Integer> {
                    .plaintext(plaintext)
                    .caCertificatePath(caFile)
                    .serverNameOverride(serverNameOverride)
+                    .requireCertificateValidation(requireCertificateValidation)
                    .callTimeout(resolvedTimeout)
                    .build();
        }
@@ -1400,6 +1409,7 @@ public final class MxGatewayCli implements Callable<Integer> {
            values.put("plaintext", plaintext);
            values.put("caFile", caFile == null ? "" : caFile.toString());
            values.put("serverNameOverride", serverNameOverride);
+            values.put("requireCertificateValidation", requireCertificateValidation);
            values.put("timeout", timeout);
            return values;
        }
@@ -1703,6 +1713,12 @@ public final class MxGatewayCli implements Callable<Integer> {
                        transition.getTransitionKind().name(),
                        transition.getSeverity());
            }
+            case PROVIDER_STATUS -> {
+                AlarmProviderStatus status = message.getProviderStatus();
+                yield String.format(
+                        "provider-status mode=%s degraded=%b reason=%s",
+                        status.getMode().name(), status.getDegraded(), status.getReason());
+            }
            case PAYLOAD_NOT_SET -> "unknown";
        };
    }
@@ -5,6 +5,7 @@ import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;

 import com.zb.mom.ww.mxgateway.client.MxGatewayAlarmFeedSubscription;
+import com.zb.mom.ww.mxgateway.client.MxGatewayClientOptions;
 import io.grpc.stub.StreamObserver;
 import java.io.ByteArrayInputStream;
 import java.io.InputStream;
@@ -289,6 +290,51 @@ final class MxGatewayCliTests {
        }
    }

+    @Test
+    void requireCertificateValidationFlagPropagatesThroughToClientOptions() {
+        // Client.Java-038 regression — the --require-certificate-validation
+        // CLI flag must reach MxGatewayClientOptions.requireCertificateValidation
+        // via CommonOptions.toClientOptions(), so CLI users can opt into strict
+        // JVM-trust verification without pinning a CA.
+        CapturingClientFactory factory = new CapturingClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--endpoint",
+                "localhost:5000",
+                "--api-key-env",
+                "MXGATEWAY_API_KEY",
+                "--require-certificate-validation",
+                "--reference",
+                "Tank01.Level.HiHi");
+
+        assertEquals(0, run.exitCode(), "errors:\n" + run.errors());
+        assertTrue(
+                factory.capturedClientOptions.requireCertificateValidation(),
+                "--require-certificate-validation did not propagate into MxGatewayClientOptions");
+    }
+
+    @Test
+    void requireCertificateValidationDefaultsToLenientWhenFlagAbsent() {
+        // Without the flag, the lenient-by-default trust posture must be
+        // preserved (requireCertificateValidation == false).
+        CapturingClientFactory factory = new CapturingClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--endpoint",
+                "localhost:5000",
+                "--api-key-env",
+                "MXGATEWAY_API_KEY",
+                "--reference",
+                "Tank01.Level.HiHi");
+
+        assertEquals(0, run.exitCode(), "errors:\n" + run.errors());
+        assertFalse(
+                factory.capturedClientOptions.requireCertificateValidation(),
+                "requireCertificateValidation should default to false (lenient)");
+    }
+
    @Test
    void streamAlarmsCommandFailsFastOnQueueOverflow() {
        // Client.Java-033 regression — the CLI's stream-alarms bounded queue
@@ -435,6 +481,23 @@ final class MxGatewayCliTests {
        }
    }

+    /**
+     * Factory that records the {@link MxGatewayClientOptions} produced by
+     * {@link MxGatewayCli.CommonOptions#toClientOptions()} so a test can assert
+     * how CLI flags map onto the library option surface. Wraps the standard
+     * {@link FakeClient} so the command body still completes. Used by the
+     * Client.Java-038 option-flow regression.
+     */
+    private static final class CapturingClientFactory implements MxGatewayCli.MxGatewayCliClientFactory {
+        private MxGatewayClientOptions capturedClientOptions;
+
+        @Override
+        public MxGatewayCli.MxGatewayCliClient connect(MxGatewayCli.CommonOptions options) {
+            capturedClientOptions = options.toClientOptions();
+            return new FakeClient(options.spec.commandLine().getOut());
+        }
+    }
+
    /**
     * Factory whose fake client floods the {@code streamAlarms} observer with
     * 2000 messages synchronously, exceeding the CLI's bounded 1024-element
@@ -238,7 +238,11 @@ left `False`, the client fetches the gateway's presented certificate once
 to `localhost` (the generated certificate always carries a `localhost` SAN) when
 none was supplied. To verify instead, pass `ca_file` to verify against a specific
 CA, or set `require_certificate_validation=True` to verify against the system
-trust roots. See
+trust roots. The strict posture is reachable through every documented entry
+point: the `require_certificate_validation=True` keyword on
+`GatewayClient.connect(...)` / `GalaxyRepositoryClient.connect(...)`, the
+`ClientOptions(require_certificate_validation=True)` struct, and the
+`--require-certificate-validation` CLI flag. See
 [Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).

 ## CLI
@@ -267,6 +271,13 @@ Use TLS options for a secured gateway:
 mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Object.Attribute --json
 ```

+To force certificate validation against the system trust store instead of the
+lenient trust-on-first-use default, add `--require-certificate-validation`:
+
+```powershell
+mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --require-certificate-validation --api-key-env MXGATEWAY_API_KEY --item Object.Attribute --json
+```
+
 ## Integration Checks

 Run live checks only when a gateway and MXAccess-backed worker are available:
@@ -1,10 +1,12 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+# setuptools >=77 emits core-metadata 2.4 (PEP 639 License-Expression), which the
+# Gitea PyPI feed does not yet accept; cap below that so the dist stays <=2.3.
+requires = ["setuptools>=69,<77", "wheel"]
 build-backend = "setuptools.build_meta"

 [project]
 name = "zb-mom-ww-mxaccess-gateway-client"
-version = "0.1.0"
+version = "0.1.1"
 description = "Async Python client scaffold for MXAccess Gateway."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -16,11 +18,10 @@ dependencies = [
 authors = [
  { name = "Joseph Doherty" },
 ]
-license = { text = "Proprietary" }
 keywords = ["mxaccess", "mxgateway", "grpc", "client", "archestra"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
  "License :: Other/Proprietary License",
+  "Development Status :: 3 - Alpha",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
@@ -54,3 +55,6 @@ where = ["src"]
 addopts = "-ra"
 pythonpath = ["src"]
 testpaths = ["tests"]
+markers = [
+  "tls: loopback TLS tests, opt-in via MXGATEWAY_RUN_TLS_TESTS=1",
+]
@@ -40,6 +40,7 @@ class GatewayClient:
        api_key: str | None = None,
        plaintext: bool = False,
        ca_file: str | None = None,
+        require_certificate_validation: bool = False,
        server_name_override: str | None = None,
        stub: Any | None = None,
    ) -> "GatewayClient":
@@ -50,13 +51,16 @@ class GatewayClient:
            api_key=api_key,
            plaintext=plaintext,
            ca_file=ca_file,
+            require_certificate_validation=require_certificate_validation,
            server_name_override=server_name_override,
        )

        if stub is not None:
            return cls(options=resolved, stub=stub)

-        channel = create_channel(resolved)
+        # create_channel may perform a blocking TLS certificate probe (TOFU
+        # default); run it off the event loop so connect never freezes the loop.
+        channel = await asyncio.to_thread(create_channel, resolved)
        return cls(
            options=resolved,
            stub=pb_grpc.MxAccessGatewayStub(channel),
@@ -52,6 +52,7 @@ class GalaxyRepositoryClient:
        api_key: str | None = None,
        plaintext: bool = False,
        ca_file: str | None = None,
+        require_certificate_validation: bool = False,
        server_name_override: str | None = None,
        stub: Any | None = None,
    ) -> "GalaxyRepositoryClient":
@@ -62,13 +63,16 @@ class GalaxyRepositoryClient:
            api_key=api_key,
            plaintext=plaintext,
            ca_file=ca_file,
+            require_certificate_validation=require_certificate_validation,
            server_name_override=server_name_override,
        )

        if stub is not None:
            return cls(options=resolved, stub=stub)

-        channel = create_channel(resolved)
+        # create_channel may perform a blocking TLS certificate probe (TOFU
+        # default); run it off the event loop so connect never freezes the loop.
+        channel = await asyncio.to_thread(create_channel, resolved)
        return cls(
            options=resolved,
            stub=galaxy_pb_grpc.GalaxyRepositoryStub(channel),
@@ -12,6 +12,10 @@ import grpc
 from .auth import REDACTED, ApiKey
 from .errors import MxGatewayTransportError

+# Fallback bound for the TOFU certificate probe when no call_timeout is set, so a
+# black-holed host fails fast instead of hanging on the OS default connect timeout.
+_TOFU_PROBE_TIMEOUT_SECONDS = 10.0
+

@dataclass(frozen=True)
 class ClientOptions:
@@ -88,8 +92,17 @@ def _split_authority(endpoint: str) -> tuple[str, int]:
        remainder = target[bracket_end + 1 :]  # ":5120" or ""
        port_str = remainder.lstrip(":")
        return (host, int(port_str) if port_str else 443)
-    host, _, port = target.rpartition(":")
-    return (host or "localhost", int(port) if port else 443)
+    host, sep, port = target.rpartition(":")
+    if not sep:
+        # No colon at all (e.g. a bare hostname "mygateway"): the whole target
+        # is the host; default the port rather than raising on int("mygateway").
+        return (target or "localhost", 443)
+    if not port.isdigit():
+        # A colon with a non-numeric / empty tail (e.g. a trailing ":") is not
+        # an explicit port — keep the left side as the host and default the
+        # port so a typo cannot raise an uncaught ValueError on the TOFU path.
+        return (host or "localhost", 443)
+    return (host or "localhost", int(port))


 def create_channel(options: ClientOptions) -> grpc.aio.Channel:
@@ -120,9 +133,15 @@ def create_channel(options: ClientOptions) -> grpc.aio.Channel:
    else:
        # Lenient default: grpc-python has no per-channel skip-verify, so fetch the
        # server's certificate (unverified) and pin it for this channel (TOFU).
+        # The probe opens a real blocking TCP+TLS socket, so it MUST be bounded —
+        # a black-holed / firewall-drop host would otherwise hang on the OS default
+        # connect timeout (minutes). Bound it by call_timeout (or a short fixed
+        # fallback) so the dial fails fast as a transport error. The async
+        # `connect` classmethods run this off the event loop (asyncio.to_thread).
        host, port = _split_authority(options.endpoint)
+        probe_timeout = options.call_timeout if options.call_timeout else _TOFU_PROBE_TIMEOUT_SECONDS
        try:
-            presented = ssl.get_server_certificate((host, port))
+            presented = ssl.get_server_certificate((host, port), timeout=probe_timeout)
        except OSError as error:
            raise MxGatewayTransportError(
                f"failed to fetch TLS certificate from {options.endpoint}: {error}"
@@ -170,6 +170,13 @@ def gateway_options(command: Callable[..., Any]) -> Callable[..., Any]:
    command = click.option("--plaintext", is_flag=True, help="Use plaintext gRPC.")(command)
    command = click.option("--tls", "use_tls", is_flag=True, help="Use TLS gRPC.")(command)
    command = click.option("--ca-file", default=None, help="Custom root certificate file.")(command)
+    command = click.option(
+        "--require-certificate-validation",
+        "require_certificate_validation",
+        is_flag=True,
+        help="Verify the TLS certificate against the system trust store "
+        "instead of the lenient trust-on-first-use default.",
+    )(command)
    command = click.option(
        "--server-name-override",
        default=None,
@@ -923,6 +930,7 @@ async def _connect(kwargs: dict[str, Any]) -> GatewayClient:
            api_key=api_key,
            plaintext=_use_plaintext(kwargs),
            ca_file=kwargs.get("ca_file"),
+            require_certificate_validation=bool(kwargs.get("require_certificate_validation")),
            server_name_override=kwargs.get("server_name_override"),
            call_timeout=kwargs.get("call_timeout"),
            stream_timeout=kwargs.get("stream_timeout"),
@@ -1,9 +1,12 @@
 """Tests for auth metadata and connection options."""

+import socket
+
 import pytest

 from zb_mom_ww_mxgateway.auth import REDACTED, ApiKey, auth_metadata, redact_secret
 from zb_mom_ww_mxgateway import options as options_module
+from zb_mom_ww_mxgateway.errors import MxGatewayTransportError
 from zb_mom_ww_mxgateway.options import ClientOptions, create_channel


@@ -80,7 +83,9 @@ def test_create_channel_uses_tls_channel_tofu_default(monkeypatch: pytest.Monkey
    _DUMMY_PEM = "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
    get_cert_calls: list[tuple[str, int]] = []

-    def fake_get_server_certificate(addr: tuple[str, int]) -> str:
+    def fake_get_server_certificate(
+        addr: tuple[str, int], *, timeout: float | None = None
+    ) -> str:
        get_cert_calls.append(addr)
        return _DUMMY_PEM

@@ -133,7 +138,7 @@ def test_create_channel_uses_tls_channel_tofu_respects_server_name_override(
    monkeypatch.setattr(
        options_module.ssl,
        "get_server_certificate",
-        lambda addr: _DUMMY_PEM,
+        lambda addr, *, timeout=None: _DUMMY_PEM,
    )
    cred_calls: list[object] = []

@@ -276,3 +281,46 @@ def test_create_channel_uses_tls_channel_ca_file(
            ],
        ),
    ]
+
+
+def test_tofu_probe_passes_a_bounded_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The TOFU cert pre-fetch must be bounded so a black-holed host fails fast."""
+    captured: dict[str, object] = {}
+
+    def fake_get_server_certificate(addr: object, *, timeout: float | None = None) -> str:
+        captured["timeout"] = timeout
+        return "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", lambda **_: "creds")
+    monkeypatch.setattr(
+        options_module.grpc.aio,
+        "secure_channel",
+        lambda endpoint, credentials, *, options: "tls-channel",
+    )
+
+    create_channel(ClientOptions(endpoint="gateway.example:5001", call_timeout=7.5))
+
+    # A finite, positive timeout must be supplied (bounded by call_timeout here).
+    assert isinstance(captured["timeout"], (int, float))
+    assert 0 < captured["timeout"] <= 7.5
+
+
+@pytest.mark.parametrize(
+    "raised",
+    [socket.timeout("timed out"), TimeoutError("timed out"), OSError("connection refused")],
+)
+def test_tofu_probe_timeout_raises_transport_error(
+    monkeypatch: pytest.MonkeyPatch, raised: Exception
+) -> None:
+    """A timed-out / failed probe surfaces as MxGatewayTransportError, not a raw error."""
+
+    def fake_get_server_certificate(addr: object, *, timeout: float | None = None) -> str:
+        raise raised
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+
+    options = ClientOptions(endpoint="gateway.example:5001")
+    with pytest.raises(MxGatewayTransportError) as excinfo:
+        create_channel(options)
+    assert options.endpoint in str(excinfo.value)
@@ -2,14 +2,79 @@

 import json

+import pytest
 from click.testing import CliRunner

 from zb_mom_ww_mxgateway import __version__
+from zb_mom_ww_mxgateway_cli import commands as commands_module
 from zb_mom_ww_mxgateway_cli.commands import main

 _BATCH_EOR = "__MXGW_BATCH_EOR__"


+def test_require_certificate_validation_flag_flows_through_connect(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The --require-certificate-validation CLI flag must reach ClientOptions (Client.Python-027)."""
+    captured: dict[str, object] = {}
+
+    async def fake_connect(options, **_kwargs):
+        captured["options"] = options
+        # Return a minimal object that supports the async context-manager protocol
+        # used by every CLI command body (async with await _connect(...) as client).
+        return _FakeAsyncClient()
+
+    monkeypatch.setattr(commands_module.GatewayClient, "connect", fake_connect)
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "open-session",
+            "--endpoint",
+            "gateway.example:5001",
+            "--require-certificate-validation",
+            "--json",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured["options"].require_certificate_validation is True
+
+
+def test_require_certificate_validation_defaults_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Without the flag the strict-validation posture stays off (TOFU default)."""
+    captured: dict[str, object] = {}
+
+    async def fake_connect(options, **_kwargs):
+        captured["options"] = options
+        return _FakeAsyncClient()
+
+    monkeypatch.setattr(commands_module.GatewayClient, "connect", fake_connect)
+
+    result = CliRunner().invoke(
+        main,
+        ["open-session", "--endpoint", "gateway.example:5001", "--plaintext", "--json"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured["options"].require_certificate_validation is False
+
+
+class _FakeAsyncClient:
+    """Minimal async-context-manager fake satisfying the open-session command body."""
+
+    async def __aenter__(self) -> "_FakeAsyncClient":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        return None
+
+    async def open_session_raw(self, *_args, **_kwargs):
+        from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+
+        return pb.OpenSessionReply(session_id="cli-test-session")
+
+
 def test_version_json_is_deterministic() -> None:
    runner = CliRunner()

@@ -8,9 +8,107 @@ from typing import Any
 import pytest

 from zb_mom_ww_mxgateway import ClientOptions, GatewayClient, MxAccessError
+from zb_mom_ww_mxgateway import client as client_module
+from zb_mom_ww_mxgateway import galaxy as galaxy_module
+from zb_mom_ww_mxgateway.galaxy import GalaxyRepositoryClient
 from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb


+@pytest.mark.asyncio
+async def test_gateway_connect_forwards_require_certificate_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The connect convenience kwarg must reach ClientOptions (Client.Python-027)."""
+    captured: dict[str, Any] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        captured["options"] = options
+        return object()
+
+    monkeypatch.setattr(client_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(client_module.pb_grpc, "MxAccessGatewayStub", lambda channel: object())
+
+    await GatewayClient.connect(
+        endpoint="gateway.example:5001",
+        require_certificate_validation=True,
+    )
+
+    assert captured["options"].require_certificate_validation is True
+
+
+@pytest.mark.asyncio
+async def test_galaxy_connect_forwards_require_certificate_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """GalaxyRepositoryClient.connect must thread the flag too (Client.Python-027)."""
+    captured: dict[str, Any] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        captured["options"] = options
+        return object()
+
+    monkeypatch.setattr(galaxy_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(
+        galaxy_module.galaxy_pb_grpc, "GalaxyRepositoryStub", lambda channel: object()
+    )
+
+    await GalaxyRepositoryClient.connect(
+        endpoint="gateway.example:5001",
+        require_certificate_validation=True,
+    )
+
+    assert captured["options"].require_certificate_validation is True
+
+
+@pytest.mark.asyncio
+async def test_gateway_connect_runs_create_channel_off_the_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """connect must run the blocking channel factory off the loop (Client.Python-028)."""
+    ran_in_thread: dict[str, bool] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        # If this runs on the event loop thread, get_running_loop() succeeds.
+        try:
+            asyncio.get_running_loop()
+            ran_in_thread["off_loop"] = False
+        except RuntimeError:
+            ran_in_thread["off_loop"] = True
+        return object()
+
+    monkeypatch.setattr(client_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(client_module.pb_grpc, "MxAccessGatewayStub", lambda channel: object())
+
+    await GatewayClient.connect(endpoint="gateway.example:5001")
+
+    assert ran_in_thread["off_loop"] is True
+
+
+@pytest.mark.asyncio
+async def test_galaxy_connect_runs_create_channel_off_the_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """GalaxyRepositoryClient.connect must also run the probe off the loop (Client.Python-028)."""
+    ran_in_thread: dict[str, bool] = {}
+
+    def fake_create_channel(options: ClientOptions) -> object:
+        try:
+            asyncio.get_running_loop()
+            ran_in_thread["off_loop"] = False
+        except RuntimeError:
+            ran_in_thread["off_loop"] = True
+        return object()
+
+    monkeypatch.setattr(galaxy_module, "create_channel", fake_create_channel)
+    monkeypatch.setattr(
+        galaxy_module.galaxy_pb_grpc, "GalaxyRepositoryStub", lambda channel: object()
+    )
+
+    await GalaxyRepositoryClient.connect(endpoint="gateway.example:5001")
+
+    assert ran_in_thread["off_loop"] is True
+
+
@pytest.mark.asyncio
 async def test_session_helpers_send_auth_metadata_and_preserve_raw_replies() -> None:
    stub = FakeGatewayStub()
@@ -134,6 +134,17 @@ def test_split_authority_parses_host_and_port() -> None:
    assert _split_authority(":5120") == ("localhost", 5120)


+def test_split_authority_defaults_port_for_portless_endpoint() -> None:
+    from zb_mom_ww_mxgateway.options import _split_authority
+
+    # A bare hostname (no ":port") must default to 443, not crash on int("mygateway").
+    assert _split_authority("mygateway") == ("mygateway", 443)
+    # Scheme-prefixed bare hostname behaves the same.
+    assert _split_authority("https://mygateway") == ("mygateway", 443)
+    # A non-numeric tail after a colon is treated as no explicit port.
+    assert _split_authority("mygateway:") == ("mygateway", 443)
+
+
 def test_split_authority_strips_ipv6_brackets() -> None:
    from zb_mom_ww_mxgateway.options import _split_authority

@@ -207,6 +207,22 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"

+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -574,7 +590,7 @@ checksum = "1d87ecb2933e8aeadb3e3a02b828fed80a7528047e68b4f424523a0981a3a084"

 [[package]]
 name = "mxgw-cli"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
 "clap",
 "futures-util",
@@ -597,6 +613,12 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"

+[[package]]
+name = "openssl-probe"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
+
 [[package]]
 name = "percent-encoding"
 version = "2.3.2"
@@ -796,6 +818,18 @@ dependencies = [
 "zeroize",
 ]

+[[package]]
+name = "rustls-native-certs"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "612460d5f7bea540c490b2b6395d8e34a953e52b491accd6c86c8164c5932a63"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
 [[package]]
 name = "rustls-pki-types"
 version = "1.14.1"
@@ -816,6 +850,38 @@ dependencies = [
 "untrusted",
 ]

+[[package]]
+name = "schannel"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "891d81b926048e76efe18581bf793546b4c0eaf8448d72be8de2bbee5fd166e1"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags",
+ "core-foundation",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "semver"
 version = "1.0.28"
@@ -1056,6 +1122,7 @@ dependencies = [
 "percent-encoding",
 "pin-project",
 "prost",
+ "rustls-native-certs",
 "socket2 0.5.10",
 "tokio",
 "tokio-rustls",
@@ -1423,7 +1490,7 @@ dependencies = [

 [[package]]
 name = "zb-mom-ww-mxgateway-client"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
 "futures-core",
 "futures-util",
@@ -1,6 +1,6 @@
 [package]
 name = "zb-mom-ww-mxgateway-client"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 authors = ["Joseph Doherty"]
 description = "Async Rust client for the MxAccessGateway gRPC service, including a lazy-browse walker over the Galaxy Repository hierarchy."
@@ -20,7 +20,7 @@ resolver = "2"

 [workspace.package]
 edition = "2021"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Joseph Doherty"]
 license = "Proprietary"
 repository = "https://gitea.dohertylan.com/dohertj2/mxaccessgw"
@@ -37,7 +37,7 @@ serde_json = "1.0.145"
 thiserror = "2.0.17"
 tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread", "sync", "time"] }
 tokio-stream = { version = "0.1.17", features = ["net"] }
-tonic = { version = "0.13.1", features = ["transport", "tls-ring"] }
+tonic = { version = "0.13.1", features = ["transport", "tls-ring", "tls-native-roots"] }
 tonic-build = "0.13.1"

 [dependencies]
@@ -81,11 +81,19 @@ cargo run -p mxgw-cli -- smoke --endpoint https://mxgateway.example.local:5001 -
 The gateway can auto-generate its own self-signed certificate (it has no PKI).
 Unlike the other clients, the Rust client is **not** lenient: tonic 0.13.1
 exposes no public hook to inject a custom certificate verifier, so TLS over Rust
-is pin-only. A TLS connection requires either `--ca-file` /
-`ClientOptions::with_ca_file(...)` to pin a CA (export the gateway's self-signed
-certificate and pin it), or `--require-certificate-validation` /
-`with_require_certificate_validation(true)` to verify against the system trust
-roots. TLS with neither set fails `connect` with a clear, actionable error rather
+cannot accept an *arbitrary* self-signed certificate. A TLS connection requires
+one of two trust paths:
+
+- `--ca-file` / `ClientOptions::with_ca_file(...)` to pin a CA (export the
+  gateway's self-signed certificate and pin it). This is the path for a
+  self-signed gateway.
+- `--require-certificate-validation` / `with_require_certificate_validation(true)`
+  to verify against the operating system's trust roots (`tls-native-roots`). This
+  only succeeds for a certificate that chains to a root the host already trusts —
+  i.e. a gateway fronted by a publicly- or enterprise-CA-issued certificate, not a
+  bare self-signed one.
+
+TLS with neither set fails `connect` with a clear, actionable error rather
 than accepting the certificate. See
 [Gateway Configuration](../../docs/GatewayConfiguration.md#automatic-self-signed-certificate).

@@ -271,5 +279,5 @@ Then add the dependency:

 ```toml
 [dependencies]
-zb-mom-ww-mxgateway-client = { version = "0.1.0", registry = "dohertj2-gitea" }
+zb-mom-ww-mxgateway-client = { version = "0.1.1", registry = "dohertj2-gitea" }
 ```
@@ -162,12 +162,73 @@ impl GatewayClient {

 `stream_alarms` opens with one `active_alarm` per currently-active alarm
 (the ConditionRefresh snapshot), then a single `snapshot_complete`, then a
-`transition` for every subsequent raise / acknowledge / clear. The feed is
-served by the gateway's always-on alarm monitor — no worker session is
-opened — so any number of clients may attach. Dropping the stream cancels
-the gRPC call cooperatively. `acknowledge_alarm` is idempotent at the
-MxAccess layer; the returned `AcknowledgeAlarmReply` carries the native
-MxStatus from the worker.
+`transition` for every subsequent raise / acknowledge / clear. A fourth
+`provider_status` oneof case (`AlarmProviderStatus`: `mode`, `degraded`,
+`reason`, `since`) is emitted once on stream open and again on every
+failover/failback so late joiners learn the current alarm-provider mode.
+The CLI renders all four cases in both its one-line summary and its
+protobuf-JSON output (`alarm_feed_message_summary` /
+`alarm_feed_message_to_json`). The feed is served by the gateway's always-on
+alarm monitor — no worker session is opened — so any number of clients may
+attach. Dropping the stream cancels the gRPC call cooperatively.
+`acknowledge_alarm` is idempotent at the MxAccess layer; the returned
+`AcknowledgeAlarmReply` carries the native MxStatus from the worker.
+
+## Galaxy Repository
+
+`GalaxyClient` is a session-less metadata client (requires the
+`metadata:read` API-key scope). Alongside `test_connection`,
+`get_last_deploy_time`, `discover_hierarchy`, and `watch_deploy_events`, it
+exposes a lazy hierarchy walker built on the `BrowseChildren` RPC:
+
+```rust
+impl GalaxyClient {
+    pub async fn browse(&mut self, options: Option<BrowseChildrenOptions>) -> Result<Vec<LazyBrowseNode>, Error>;
+    pub async fn browse_children_raw(&mut self, request: BrowseChildrenRequest) -> Result<BrowseChildrenReply, Error>;
+}
+
+pub struct BrowseChildrenOptions {
+    pub category_ids: Vec<i32>,
+    pub template_chain_contains: Vec<String>,
+    pub tag_name_glob: Option<String>,
+    pub include_attributes: Option<bool>,
+    pub alarm_bearing_only: bool,
+    pub historized_only: bool,
+}
+
+impl LazyBrowseNode {
+    pub fn object(&self) -> &GalaxyObject;
+    pub fn has_children_hint(&self) -> bool;
+    pub async fn children(&self) -> Vec<LazyBrowseNode>;
+    pub async fn is_expanded(&self) -> bool;
+    pub async fn expand(&self) -> Result<(), Error>;
+}
+```
+
+- `browse(options)` returns the root objects as `LazyBrowseNode`s. The
+  supplied `BrowseChildrenOptions` filter is captured and reused when any
+  returned node is expanded, so a single filter set scopes the entire walk.
+- `BrowseChildrenOptions` mirrors the request-level filters on the wire and
+  combines them with **AND**: a child appears only when it satisfies every
+  populated criterion (`category_ids` membership, every
+  `template_chain_contains` substring, the `tag_name_glob`, plus the
+  `alarm_bearing_only` / `historized_only` flags). `include_attributes` is a
+  tri-state (`None` = server default). Empty/`None` fields impose no
+  restriction. See
+  [Galaxy Repository — BrowseChildren](../../docs/GalaxyRepository.md#browsechildren)
+  for the wire-level semantics.
+- `LazyBrowseNode` is cheap to clone — clones share state through an internal
+  `Arc`, so expanding one clone makes the children visible to every clone.
+  `has_children_hint()` exposes the server's `child_has_children` hint so a UI
+  can draw an expand affordance without issuing an RPC. `expand()` is
+  idempotent: the first call issues a paged `BrowseChildren` walk (page size
+  500) under an async mutex held across the await, sets the `is_expanded`
+  flag, and caches the children; subsequent calls are no-ops and re-hit
+  nothing. The internal paged loop guards against a server returning a
+  repeated `next_page_token` by failing with `Error::InvalidArgument` rather
+  than looping forever.
+- `browse_children_raw` issues a single `BrowseChildren` RPC and returns the
+  raw reply for callers that want to drive paging themselves.

 ## Authentication

@@ -200,13 +261,20 @@ Rust client is therefore **pin-only** — it requires either:
 - `ClientOptions::with_ca_file(...)` to pin a CA (the supported path for the
  gateway's self-signed certificate; export the certificate and pin it), or
 - `ClientOptions::with_require_certificate_validation(true)` to verify against the
-  system trust roots.
+  operating system's trust roots. This enables the `tonic` `tls-native-roots`
+  feature and calls `ClientTlsConfig::with_native_roots()`, so the handshake
+  validates a certificate that chains to a root the host already trusts. It does
+  **not** accept a bare self-signed gateway certificate — that still needs
+  `with_ca_file`.

-With TLS enabled (`with_plaintext(false)`), no pinned CA, and certificate
-validation not required, `GatewayClient::connect` rejects the connection with a
-clear, actionable error pointing at `with_ca_file` /
-`require_certificate_validation` rather than silently accepting the certificate.
-The CLI exposes `--ca-file` and `--require-certificate-validation`.
+`build_tls_config` computes the trust posture with the pure `tls_trust_decision`
+helper (`None` / `PinnedCa` / `SystemRoots` / `RejectNoCa`) so the posture is
+unit-testable without a live handshake. With TLS enabled (`with_plaintext(false)`),
+no pinned CA, and certificate validation not required (`RejectNoCa`),
+`GatewayClient::connect` rejects the connection with a clear, actionable error
+pointing at `with_ca_file` / `require_certificate_validation` rather than building
+a config with zero trust anchors. The CLI exposes `--ca-file` and
+`--require-certificate-validation`.

 ## Streaming

@@ -1726,7 +1726,7 @@ fn event_value_to_json(value: &ProtoMxValue) -> Value {
 }

 /// Render a streamed [`AlarmFeedMessage`] as a terse one-line summary that
-/// distinguishes the three `payload` oneof cases.
+/// distinguishes the four `payload` oneof cases.
 fn alarm_feed_message_summary(message: &AlarmFeedMessage) -> String {
    match &message.payload {
        Some(alarm_feed_message::Payload::ActiveAlarm(snapshot)) => {
@@ -1746,6 +1746,14 @@ fn alarm_feed_message_summary(message: &AlarmFeedMessage) -> String {
                AlarmEnumName::transition_kind(transition.transition_kind)
            )
        }
+        Some(alarm_feed_message::Payload::ProviderStatus(status)) => {
+            format!(
+                "provider-status mode={} degraded={} reason={:?}",
+                AlarmEnumName::provider_mode(status.mode),
+                status.degraded,
+                status.reason
+            )
+        }
        None => "(empty)".to_owned(),
    }
 }
@@ -1784,6 +1792,17 @@ fn alarm_feed_message_to_json(message: &AlarmFeedMessage) -> Value {
                "description": transition.description,
            }
        }),
+        Some(alarm_feed_message::Payload::ProviderStatus(status)) => json!({
+            "providerStatus": {
+                "mode": AlarmEnumName::provider_mode(status.mode),
+                "degraded": status.degraded,
+                "reason": status.reason,
+                "since": status.since.as_ref().map(|ts| json!({
+                    "seconds": ts.seconds,
+                    "nanos": ts.nanos,
+                })),
+            }
+        }),
        None => Value::Null,
    }
 }
@@ -1806,6 +1825,13 @@ impl AlarmEnumName {
            .map(|kind| kind.as_str_name().to_owned())
            .unwrap_or_else(|_| value.to_string())
    }
+
+    fn provider_mode(value: i32) -> String {
+        use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::AlarmProviderMode;
+        AlarmProviderMode::try_from(value)
+            .map(|mode| mode.as_str_name().to_owned())
+            .unwrap_or_else(|_| value.to_string())
+    }
 }

 /// Render an [`AcknowledgeAlarmReply`] as a terse line or a JSON document.
@@ -2165,4 +2191,40 @@ mod tests {
        assert_eq!(frac.seconds, utc.seconds);
        assert_eq!(frac.nanos, 250_000_000);
    }
+
+    #[test]
+    fn alarm_feed_provider_status_renders_in_summary_and_json() {
+        use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::{
+            alarm_feed_message, AlarmFeedMessage, AlarmProviderMode, AlarmProviderStatus,
+        };
+
+        let message = AlarmFeedMessage {
+            payload: Some(alarm_feed_message::Payload::ProviderStatus(
+                AlarmProviderStatus {
+                    mode: AlarmProviderMode::Subtag as i32,
+                    degraded: true,
+                    reason: "alarmmgr unavailable".to_owned(),
+                    since: Some(prost_types::Timestamp {
+                        seconds: 1_777_995_000,
+                        nanos: 0,
+                    }),
+                },
+            )),
+        };
+
+        let summary = super::alarm_feed_message_summary(&message);
+        assert!(summary.contains("provider-status"), "summary: {summary}");
+        assert!(
+            summary.contains("ALARM_PROVIDER_MODE_SUBTAG"),
+            "summary: {summary}"
+        );
+        assert!(summary.contains("degraded=true"), "summary: {summary}");
+
+        let value = super::alarm_feed_message_to_json(&message);
+        let provider = &value["providerStatus"];
+        assert_eq!(provider["mode"], "ALARM_PROVIDER_MODE_SUBTAG");
+        assert_eq!(provider["degraded"], true);
+        assert_eq!(provider["reason"], "alarmmgr unavailable");
+        assert_eq!(provider["since"]["seconds"], 1_777_995_000_i64);
+    }
 }
@@ -74,16 +74,22 @@ impl ClientOptions {
    }

    /// Require TLS certificate verification even without a pinned CA. Default
-    /// false: the gateway's self-signed certificate is accepted (internal-tool
-    /// posture). Setting a CA file always verifies.
+    /// false. Setting a CA file always verifies against that CA.
    ///
    /// Note for Rust: tonic 0.13's `ClientTlsConfig` exposes no hook for a
-    /// custom rustls verifier, so the Rust client cannot accept an arbitrary
+    /// custom rustls verifier, so the Rust client cannot accept an *arbitrary*
    /// self-signed certificate the way the other clients do. With the default
    /// (false) and no pinned CA, [`crate::client::GatewayClient::connect`]
-    /// rejects the TLS connection and asks for a CA file. Either pin a CA via
-    /// [`ClientOptions::with_ca_file`] (the supported lenient path on Rust) or
-    /// set this `true` to verify against the system trust roots.
+    /// rejects the TLS connection and asks for a CA file. There are two
+    /// supported TLS paths:
+    ///
+    /// - Pin the gateway certificate with [`ClientOptions::with_ca_file`] (the
+    ///   lenient pin-only path; works for a self-signed gateway cert).
+    /// - Set this `true` to verify against the operating system's trust roots
+    ///   (`tls-native-roots`). This only succeeds for a certificate that chains
+    ///   to a root the host already trusts, so it is for gateways fronted by a
+    ///   publicly- or enterprise-CA-issued certificate, not a bare self-signed
+    ///   one.
    pub fn with_require_certificate_validation(mut self, require: bool) -> Self {
        self.require_certificate_validation = require;
        self
@@ -175,26 +181,63 @@ impl ClientOptions {
    }
 }

+/// Where the TLS handshake gets its trust anchors for a given set of options.
+/// Computed by [`tls_trust_decision`] and applied by [`build_tls_config`];
+/// split out so the trust posture is unit-testable without a live handshake.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum TlsTrustDecision {
+    /// Plaintext transport — no TLS, no trust anchors.
+    None,
+    /// Validate against the CA pinned with [`ClientOptions::with_ca_file`].
+    PinnedCa,
+    /// Validate against the operating system's trust roots
+    /// (`require_certificate_validation == true`, no pinned CA).
+    SystemRoots,
+    /// Reject up front: TLS requested with neither a pinned CA nor strict
+    /// verification (the Rust pin-only lenient default).
+    RejectNoCa,
+}
+
+/// Decide the TLS trust posture from `options` without touching the filesystem
+/// or the network.
+pub(crate) fn tls_trust_decision(options: &ClientOptions) -> TlsTrustDecision {
+    if options.plaintext() {
+        TlsTrustDecision::None
+    } else if options.ca_file().is_some() {
+        TlsTrustDecision::PinnedCa
+    } else if options.require_certificate_validation() {
+        TlsTrustDecision::SystemRoots
+    } else {
+        TlsTrustDecision::RejectNoCa
+    }
+}
+
 /// Build the [`ClientTlsConfig`] for a non-plaintext connection described by
 /// `options`, applying the lenient-default guard that is the **Rust
 /// pin-only exception**.
 ///
 /// Returns `Ok(None)` when `options.plaintext()` is `true` (no TLS needed).
-/// Returns `Ok(Some(tls))` when a valid TLS config can be assembled.
+/// Returns `Ok(Some(tls))` when a valid TLS config can be assembled — either
+/// pinned to the CA from [`ClientOptions::with_ca_file`], or, when
+/// `require_certificate_validation` is set with no pinned CA, verifying against
+/// the operating system's trust roots (`tls-native-roots`).
 /// Returns `Err(Error::InvalidEndpoint)` when TLS is requested but no pinned
 /// CA was provided and `require_certificate_validation` is `false`.
 ///
-/// # Why this guard exists
+/// # Why the no-CA guard exists
 ///
 /// `tonic` 0.13's `ClientTlsConfig` builds its rustls verifier inside a
 /// crate-private connector and exposes no hook for a custom
-/// `ServerCertVerifier`. The Rust client therefore cannot accept an arbitrary
+/// `ServerCertVerifier`. The Rust client therefore cannot accept an *arbitrary*
 /// self-signed certificate the way the other language clients do. Rather than
-/// silently falling back to system-root verification (which always fails
-/// against a self-signed gateway certificate), we reject the configuration
-/// early with an actionable error.
+/// silently falling back to a verifier with no trust anchors (which rejects
+/// every certificate with a confusing handshake error), the lenient default
+/// rejects the configuration early with an actionable error. The strict opt-in
+/// instead loads the system trust roots so a certificate chaining to an
+/// already-trusted root validates.
 pub(crate) fn build_tls_config(options: &ClientOptions) -> Result<Option<ClientTlsConfig>, Error> {
-    if options.plaintext() {
+    let decision = tls_trust_decision(options);
+    if decision == TlsTrustDecision::None {
        return Ok(None);
    }

@@ -202,37 +245,46 @@ pub(crate) fn build_tls_config(options: &ClientOptions) -> Result<Option<ClientT
    if let Some(server_name) = options.server_name_override() {
        tls = tls.domain_name(server_name.to_owned());
    }
-    if let Some(ca_file) = options.ca_file() {
-        let certificate = fs::read(ca_file).map_err(|source| Error::InvalidEndpoint {
-            endpoint: options.endpoint().to_owned(),
-            detail: format!("failed to read CA file {}: {source}", ca_file.display()),
-        })?;
-        tls = tls.ca_certificate(Certificate::from_pem(certificate));
-    } else if !options.require_certificate_validation() {
-        // Lenient-default fallback (Rust pin-only exception): tonic
-        // 0.13's `ClientTlsConfig` builds its rustls verifier inside a
-        // crate-private connector and exposes no hook for a custom
-        // `ServerCertVerifier`, so — unlike the other clients — the
-        // Rust client cannot accept an arbitrary self-signed cert. Pin
-        // the gateway's CA instead, or opt into strict verification
-        // against the system trust roots. We reject here rather than
-        // silently verifying against system roots (which would fail a
-        // self-signed gateway with a confusing handshake error).
-        //
-        // Note: a server-name override affects SNI (the hostname sent
-        // in the TLS ClientHello) but does NOT pin trust. Overriding
-        // the server name alone does not bypass certificate validation.
-        return Err(Error::InvalidEndpoint {
-            endpoint: options.endpoint().to_owned(),
-            detail: "TLS requested without a pinned CA. The Rust client cannot accept an \
-                     arbitrary self-signed certificate (tonic 0.13 exposes no custom \
-                     rustls verifier). Pin the gateway certificate with \
-                     ClientOptions::with_ca_file, or call \
-                     ClientOptions::with_require_certificate_validation(true) to verify \
-                     against the system trust roots. Note: a server-name override \
-                     affects SNI but does not pin trust."
-                .to_owned(),
-        });
+    match decision {
+        TlsTrustDecision::PinnedCa => {
+            let ca_file = options.ca_file().expect("PinnedCa implies a CA file");
+            let certificate = fs::read(ca_file).map_err(|source| Error::InvalidEndpoint {
+                endpoint: options.endpoint().to_owned(),
+                detail: format!("failed to read CA file {}: {source}", ca_file.display()),
+            })?;
+            tls = tls.ca_certificate(Certificate::from_pem(certificate));
+        }
+        TlsTrustDecision::SystemRoots => {
+            // Strict opt-in with no pinned CA: verify against the OS trust
+            // store. Without this the bare `ClientTlsConfig` carries zero
+            // trust anchors and rejects every certificate, so the documented
+            // "verify against the system trust roots" behaviour would be
+            // unreachable. Only a certificate chaining to an already-trusted
+            // root validates — a bare self-signed gateway cert still needs
+            // `with_ca_file`.
+            tls = tls.with_native_roots();
+        }
+        TlsTrustDecision::RejectNoCa => {
+            // Lenient-default fallback (Rust pin-only exception): the Rust
+            // client cannot accept an arbitrary self-signed cert. Pin the
+            // gateway's CA, or opt into strict verification against the
+            // system trust roots.
+            //
+            // Note: a server-name override affects SNI (the hostname sent in
+            // the TLS ClientHello) but does NOT pin trust.
+            return Err(Error::InvalidEndpoint {
+                endpoint: options.endpoint().to_owned(),
+                detail: "TLS requested without a pinned CA. The Rust client cannot accept an \
+                         arbitrary self-signed certificate (tonic 0.13 exposes no custom \
+                         rustls verifier). Pin the gateway certificate with \
+                         ClientOptions::with_ca_file, or call \
+                         ClientOptions::with_require_certificate_validation(true) to verify \
+                         against the system trust roots. Note: a server-name override \
+                         affects SNI but does not pin trust."
+                    .to_owned(),
+            });
+        }
+        TlsTrustDecision::None => unreachable!("handled above"),
    }
    Ok(Some(tls))
 }
@@ -269,6 +321,8 @@ mod tests {
    use super::ClientOptions;
    use crate::auth::ApiKey;

+    use super::{build_tls_config, tls_trust_decision, TlsTrustDecision};
+
    #[test]
    fn debug_redacts_api_key() {
        let options =
@@ -279,4 +333,47 @@ mod tests {
        assert!(debug.contains("<redacted>"));
        assert!(!debug.contains("mxgw_secret"));
    }
+
+    #[test]
+    fn plaintext_needs_no_tls() {
+        let options = ClientOptions::new("http://127.0.0.1:5000").with_plaintext(true);
+        assert_eq!(tls_trust_decision(&options), TlsTrustDecision::None);
+        assert!(build_tls_config(&options).unwrap().is_none());
+    }
+
+    #[test]
+    fn pinned_ca_uses_pinned_trust() {
+        let options = ClientOptions::new("https://127.0.0.1:5000")
+            .with_plaintext(false)
+            .with_ca_file("/some/ca.pem");
+        assert_eq!(tls_trust_decision(&options), TlsTrustDecision::PinnedCa);
+    }
+
+    #[test]
+    fn strict_without_ca_uses_system_roots() {
+        // Regression for Client.Rust-031: strict verification with no pinned CA
+        // must verify against the system trust roots, not produce a config with
+        // zero trust anchors. The trust decision proves roots are consulted; the
+        // build then succeeds (no no-CA guard error) and emits a config.
+        let options = ClientOptions::new("https://127.0.0.1:5000")
+            .with_plaintext(false)
+            .with_require_certificate_validation(true);
+
+        assert_eq!(
+            tls_trust_decision(&options),
+            TlsTrustDecision::SystemRoots,
+            "strict-no-CA must request the system trust roots"
+        );
+        assert!(
+            build_tls_config(&options).unwrap().is_some(),
+            "strict-no-CA must build a usable TLS config"
+        );
+    }
+
+    #[test]
+    fn lenient_without_ca_is_rejected() {
+        let options = ClientOptions::new("https://127.0.0.1:5000").with_plaintext(false);
+        assert_eq!(tls_trust_decision(&options), TlsTrustDecision::RejectNoCa);
+        assert!(build_tls_config(&options).is_err());
+    }
 }
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/dotnet` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -383,6 +383,40 @@ Re-review pass at `42b0037`. Diff against `d692232` consists of four commits:
 | 9 | Testing coverage | No new issues — `RunAsync_StreamAlarms_*`, `RunAsync_AcknowledgeAlarm_*`, and `RunAsync_Batch_*` give the new surface unit coverage. `bench-read-bulk` is the same stress-harness-not-SDK shape called out in the prior re-review and is not flagged here. |
 | 10 | Documentation & comments | Issue found (this review): the README examples for the two new alarm CLI subcommands cite wrong flag names and a non-existent `--session-id` (Client.Dotnet-018). The new XML docs on `StreamAlarmsAsync` / `AcknowledgeAlarmAsync` and on the bulk SDK methods are accurate and complete. |

+#### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff against `42b0037` is packaging/release metadata
+(NuGet/Gitea feed), a TLS trust-posture option (`RequireCertificateValidation` + a
+lenient accept-all default for the gateway's auto-generated self-signed cert), the
+Galaxy `BrowseChildren` RPC plumbing plus a `LazyBrowseNode` lazy-browse walker, and
+in-source resolutions of the prior pass's Client.Dotnet-018..021 (CLI flag-name README
+fix, `RequireRegisterServerHandle`, `ParseTimeoutMs` negative guard, steady-state OCE
+filter). The alarm-provider-fallback proto surface mentioned in the review brief is
+**not** present in this diff — no `AlarmProviderMode` / `AlarmProviderStatus` /
+`source_provider` / provider-mode-changed event reaches the .NET client here.
+
+Build is green (`dotnet build … .slnx` succeeds) and all 78 unit tests pass (1 skipped
+live smoke). The build now emits **10 CS1591 warnings** that do not break the build,
+because the `clients/dotnet/Directory.Build.props` enforcement floor recorded as
+resolved under Client.Dotnet-012 (`TreatWarningsAsErrors` / `EnforceCodeStyleInBuild` /
+`AnalysisLevel` / `Deterministic`) is **absent** from the history that reaches HEAD —
+the props file at HEAD is packaging-metadata-only (Client.Dotnet-022). `git merge-base
+--is-ancestor a020350 HEAD` is false: the 2026-05-20 review-sweep commit that resolved
+012 is not in this line of history.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No new issues. The Galaxy `BrowseAsync` / `LazyBrowseNode.ExpandAsync` pagination correctly drains `next_page_token`, re-binds the same parent selector + filter set per page (matching the opaque-token contract), and guards against repeated tokens; the per-child `child_has_children` hint is read with an index-bounds check. The Client.Dotnet-019/021 in-source fixes (`RequireRegisterServerHandle`, `ParseTimeoutMs`) are correctly applied. |
+| 2 | mxaccessgw conventions | Issue found (this review): the `clients/dotnet/Directory.Build.props` enforcement floor (warnings-as-errors / code-style enforcement) mandated by CLAUDE.md and recorded resolved under Client.Dotnet-012 is missing at HEAD; the new props file carries only packaging metadata (Client.Dotnet-022). Consumes the shared contracts project, no forked proto, `authorization: Bearer` metadata correct. |
+| 3 | Concurrency & thread safety | Issue found (this review): `LazyBrowseNode.Children` and `IsExpanded` are read lock-free while `ExpandAsync` mutates `_children` and writes `_isExpanded` under `_expandLock`, with no release/acquire barrier to a concurrent reader (Client.Dotnet-025). `ExpandAsync`'s one-RPC dedup itself is correct (double-checked under the lock). |
+| 4 | Error handling & resilience | No new issues — `BrowseChildrenAsync` routes `RpcException` through the shared `MapRpcException`; the bench steady-state OCE filter (Client.Dotnet-020) is correctly applied. |
+| 5 | Security | No committed secret — the README Gitea-feed `dotnet nuget add source` example uses `<gitea-username>` / `<gitea-token-or-password>` placeholders. Note: TLS is lenient-by-default (accept-all callback when `UseTls` and no pinned CA), which disables certificate verification / MITM protection; this is an explicit, documented design choice for the gateway's auto-generated self-signed cert and is opt-out via `RequireCertificateValidation` or CA pinning, so not flagged as a finding. |
+| 6 | Performance & resource management | No issues found — `LazyBrowseNode` holds one `SemaphoreSlim` per node (never disposed, but it owns no unmanaged handle and the node lifetime is the tree's); browse paging caps at 500/page. |
+| 7 | Design-document adherence | No issues found — `BrowseChildren` / lazy-browse match `docs/GalaxyRepository.md#browsechildren`; the TLS posture matches `docs/GatewayConfiguration.md` (`RequireCertificateValidation` default `false`) and `DotnetClientDesign.md`. |
+| 8 | Code organization & conventions | Issue found (this review): Client.Dotnet-022 (lost enforcement props); the new `GenerateDocumentationFile=true` in the shared props also applies to the Cli and Tests projects, surfacing CS1591 on `IMxGatewayCliClient` and every test class (Client.Dotnet-023); the client (and Contracts) NuGet package ships with no `<license>` metadata despite setting `PackageRequireLicenseAcceptance=false` (Client.Dotnet-024). The nuspec correctly emits the transitive `ZB.MOM.WW.MxGateway.Contracts 0.1.0` dependency, so the README "pulled in transitively" claim holds. |
+| 9 | Testing coverage | No new issues — `LazyBrowseNodeTests` (7 cases incl. multi-page, concurrent-expand-one-RPC, filter forwarding), `MxGatewayClientTlsHandlerTests` / `GalaxyRepositoryClientTlsHandlerTests`, and the README-example parse tests give the new surface good coverage. |
+| 10 | Documentation & comments | No new issues — README NuGet-install / lazy-browse / TLS-trust sections are accurate, cross-doc anchors (`#automatic-self-signed-certificate`, `#browsechildren`) resolve, and the new XML docs on `BrowseAsync` / `LazyBrowseNode` / `RequireCertificateValidation` are complete. (The CS1591-surfaced missing docs are tracked under Client.Dotnet-023.) |
+
 ### Client.Dotnet-018

 | Field | Value |
@@ -507,3 +541,65 @@ uint timeoutMs = (uint)timeoutMsRaw;
 A single shared helper (e.g. `ParseTimeoutMs(CliArguments, string, int)`) on `MxGatewayClientCli` would cover both call sites and remove the duplication.

 **Resolution:** 2026-05-24 — Confirmed against source: both `ReadBulkAsync` (line 490) and `BenchReadBulkAsync` (line 715) cast `arguments.GetInt32("timeout-ms", ...)` straight to `uint`, so `--timeout-ms -1` silently wrapped to `0xFFFFFFFF` (~49.7 days). Added a single shared private helper `ParseTimeoutMs(CliArguments arguments, int defaultValue)` on `MxGatewayClientCli` that reads the int32, rejects negatives with a clear `ArgumentException` ("--timeout-ms must be a non-negative integer (use 0 for the gateway default)."), and returns the safe `(uint)`. Both call sites now route through the helper. Regression test `MxGatewayClientCliTests.RunAsync_TimeoutMs_NegativeValue_RejectsWithClearError` (xUnit `[Theory]` over `read-bulk` and `bench-read-bulk`) drives the CLI with `--timeout-ms -1` and asserts the exit code is non-zero, that stderr contains "timeout-ms", and that the "non-negative" guard text is present. Verified red against the original `(uint)arguments.GetInt32(...)` casts (the bench proceeded past the timeout parse and tripped a downstream "Queue empty" error rather than the descriptive guard message) and green after the helper landed.
+
+### Client.Dotnet-022
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | mxaccessgw conventions |
+| Location | `clients/dotnet/Directory.Build.props:1-21` |
+| Status | Resolved |
+
+**Description:** Client.Dotnet-012 was recorded resolved (2026-05-20, commit `a020350`) by adding `clients/dotnet/Directory.Build.props` mirroring `src/Directory.Build.props` — `TreatWarningsAsErrors=true`, `EnforceCodeStyleInBuild=true`, `AnalysisLevel=latest`, `Deterministic=true`, `LangVersion=latest`, `Nullable=enable`, `ImplicitUsings=enable` — to restore the build-quality floor that `CLAUDE.md` calls a baseline for the .NET client. That enforcement props file is **not present in the line of history that reaches HEAD**: `git merge-base --is-ancestor a020350 HEAD` is false (the 2026-05-20 review-sweep commit was dropped during the `ZB.MOM.WW` rename / history rebuild). At `42b0037` the file did not exist at all (`git show 42b0037:clients/dotnet/Directory.Build.props` fails), and at HEAD commit `523f944` introduced a **new** `clients/dotnet/Directory.Build.props` that carries only NuGet packaging metadata (Authors/Company/RepositoryUrl/Version/etc.) — none of the enforcement properties. None of the three client `.csproj` files set `TreatWarningsAsErrors` or `EnforceCodeStyleInBuild` independently (they set only `TargetFramework` and `Nullable`).
+
+Net effect at HEAD: `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` **succeeds with 10 CS1591 warnings** instead of failing. The mandated quality gate that would turn new warnings (missing docs, analyzer findings, code-style violations) into build breaks is gone for the entire client tree. This is a regression of the previously-closed Client.Dotnet-012; recorded as a fresh finding at the new commit per the re-review process.
+
+**Recommendation:** Restore the enforcement properties in `clients/dotnet/Directory.Build.props` alongside the packaging metadata (they can coexist in the same `<Project>`), or add a sibling `clients/dotnet/Directory.Build.props` import. Re-run `dotnet build …slnx` and confirm 0 warnings / 0 errors (which will require closing Client.Dotnet-023 too, since the CS1591 warnings would otherwise become errors). Add a guard so the floor is not silently dropped again — e.g. assert the property is set in a small build test or CI check.
+
+**Resolution:** 2026-06-15 — Confirmed at HEAD: `clients/dotnet/Directory.Build.props` carried only packaging metadata; none of the three client `.csproj` files set the enforcement properties, so `dotnet build …slnx` succeeded with 10 CS1591 warnings instead of failing. Restored the enforcement floor in `clients/dotnet/Directory.Build.props` mirroring `src/Directory.Build.props` (`LangVersion=latest`, `Nullable=enable`, `ImplicitUsings=enable`, `TreatWarningsAsErrors=true`, `AnalysisLevel=latest`, `EnforceCodeStyleInBuild=true`, `Deterministic=true`) in a second `<PropertyGroup>` alongside the existing packaging metadata. Resolved jointly with Client.Dotnet-023 (the CS1591 warnings would otherwise become errors under the restored `TreatWarningsAsErrors`). `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx -t:Rebuild` now reports 0 Warning(s) / 0 Error(s).
+
+### Client.Dotnet-023
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/dotnet/Directory.Build.props:17`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/IMxGatewayCliClient.cs:6`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/*.cs` |
+| Status | Resolved |
+
+**Description:** The new shared `clients/dotnet/Directory.Build.props` sets `GenerateDocumentationFile=true` at the directory level, so it applies to all three projects — including `ZB.MOM.WW.MxGateway.Client.Cli` and `ZB.MOM.WW.MxGateway.Client.Tests`, which are not packable and were not previously generating an XML doc file. Turning it on surfaces 10 CS1591 "missing XML comment" warnings: `IMxGatewayCliClient` (the public CLI interface, never documented at the type level — note Client.Dotnet-013's resolution claimed a type-level summary was added, but it is absent in the history reaching HEAD for the same reason as Client.Dotnet-022) plus every public xUnit test class (`GalaxyRepositoryClientTests`, `MxGatewayClientTlsHandlerTests`, `GalaxyRepositoryClientTlsHandlerTests`, and seven others). Today these are only warnings because the enforcement floor is missing (Client.Dotnet-022); once that floor is restored they become build-breaking errors.
+
+**Recommendation:** Scope `GenerateDocumentationFile=true` to the packable library project only (move it from the shared props into `ZB.MOM.WW.MxGateway.Client.csproj`, which is the only project that ships a `.nupkg`), or keep it directory-wide but suppress CS1591 on the non-public test/CLI assemblies (`<NoWarn>$(NoWarn);CS1591</NoWarn>` in those two `.csproj` files) and add the one-line type summary to `IMxGatewayCliClient`. The first option is cleaner and avoids documenting test classes.
+
+**Resolution:** 2026-06-15 — Confirmed via `-t:Rebuild`: the directory-wide `GenerateDocumentationFile=true` surfaced exactly 10 CS1591 warnings — `IMxGatewayCliClient` plus nine xUnit test classes (`GalaxyRepositoryClientTests`, `MxCommandReplyExtensionsTests`, `MxGatewayClientContractInfoTests`, `MxGatewayClientOptionsTests`, `MxGatewayClientTlsHandlerTests`, `GalaxyRepositoryClientTlsHandlerTests`, `MxGatewayGeneratedContractTests`, `MxStatusProxyExtensionsTests`, `MxValueExtensionsTests`); the shipped Client library itself emitted zero (its public surface was already fully documented). Took the first (cleaner) option, matching how `src/` handles this — only the packable `src/ZB.MOM.WW.MxGateway.Contracts.csproj` sets `GenerateDocumentationFile` directly. Removed `GenerateDocumentationFile=true` from the shared `clients/dotnet/Directory.Build.props` and moved it into the packable `ZB.MOM.WW.MxGateway.Client.csproj` only, so the Cli and Tests projects no longer generate doc files and CS1591 is not raised against them. No doc comments were added to test classes. With the Client.Dotnet-022 floor restored, the rebuild is clean (0 warnings / 0 errors).
+
+### Client.Dotnet-024
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/dotnet/Directory.Build.props:12`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj:19-24` |
+| Status | Resolved |
+
+**Description:** The client package sets `PackageRequireLicenseAcceptance=false` but declares **no license at all** — there is no `PackageLicenseExpression` and no `PackageLicenseFile` in `clients/dotnet/Directory.Build.props` or in the packable `.csproj`. Confirmed by packing: the emitted `ZB.MOM.WW.MxGateway.Client.0.1.0.nuspec` has no `<license>` element, so the produced package carries no license metadata and a NuGet feed renders it as "License: not specified." The sibling `ZB.MOM.WW.MxGateway.Contracts` package (the transitive dependency) has the same gap. `dotnet pack` does not warn (a missing license is allowed), so the omission is silent. Setting `PackageRequireLicenseAcceptance=false` while shipping no license is internally inconsistent — that flag exists to control acceptance of a license that should be present.
+
+**Recommendation:** Add the intended license to `clients/dotnet/Directory.Build.props` (and to `ZB.MOM.WW.MxGateway.Contracts.csproj` for parity) — either `<PackageLicenseExpression>` with an SPDX id (e.g. a proprietary marker or the actual license) or `<PackageLicenseFile>` pointing at a committed `LICENSE`. If the package is intentionally unlicensed/internal-only, document that explicitly rather than leaving the field blank.
+
+**Resolution:** 2026-06-15 — Confirmed via pack: the emitted nuspec had no `<license>` element. Marked the package "Proprietary" consistent with the other clients' decision (Rust `license = "Proprietary"`, Python `license = { text = "Proprietary" }` + `License :: Other/Proprietary License`). A `<PackageLicenseExpression>LicenseRef-Proprietary</PackageLicenseExpression>` was tried first but the current NuGet toolset rejects `LicenseRef-*` (NU5124), which the restored `TreatWarningsAsErrors` escalates to a pack failure — so the proprietary terms ship as a committed license file instead: added `clients/dotnet/LICENSE.txt` (proprietary/internal-use terms), set `<PackageLicenseFile>LICENSE.txt</PackageLicenseFile>` in the shared `clients/dotnet/Directory.Build.props`, and packed it at the package root via a `<None Include="..\LICENSE.txt" Pack="true" PackagePath="\" />` item in the packable `ZB.MOM.WW.MxGateway.Client.csproj`. `dotnet pack` now succeeds and the nuspec carries `<license type="file">LICENSE.txt</license>` with `LICENSE.txt` present in the `.nupkg`. Scope was limited to Client.Dotnet per the constraints — the sibling `ZB.MOM.WW.MxGateway.Contracts` package has the same gap and is NOT touched here (it is a different module; flagging it for that module's review).
+
+### Client.Dotnet-025
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `clients/dotnet/ZB.MOM.WW.MxGateway.Client/LazyBrowseNode.cs:38,41,54,82,94` |
+| Status | Resolved |
+
+**Description:** `LazyBrowseNode.ExpandAsync` is explicitly documented as thread-safe ("concurrent callers see exactly one fetch"), and its one-RPC dedup is correct: it double-checks `_isExpanded` under `_expandLock`. But the *readers* of the results are lock-free. `Children => _children` returns the live backing `List<LazyBrowseNode>` reference, and `IsExpanded => _isExpanded` reads the plain `bool` field — neither takes `_expandLock` nor uses `Volatile`. A thread that observes `IsExpanded == true` (or simply enumerates `Children`) concurrently with the writer thread inside `ExpandAsync` has no release/acquire barrier guaranteeing it sees the fully-populated `_children` contents that were appended under the lock. On x86/x64 the bool read and the list-reference read are atomic and the practical risk is low, but the published-state visibility is not guaranteed by the memory model, and a reader enumerating `Children` while a concurrent `ExpandAsync` is mid-append can throw `InvalidOperationException` ("collection was modified"). This is inconsistent with the type's own thread-safety claim.
+
+**Recommendation:** Either (a) tighten the documented contract to "ExpandAsync is safe to call concurrently, but Children/IsExpanded must only be read after the awaited ExpandAsync completes (no concurrent reader/expander)", or (b) make the publication safe: write `_isExpanded` via `Volatile.Write` and read via `Volatile.Read`, and return an immutable snapshot from `Children` (e.g. assign a completed `IReadOnlyList` under the lock and expose that field) so lock-free readers never observe a partially-populated list. Option (a) is the smallest change and matches the realistic usage (UI thread expands then renders).
+
+**Resolution:** 2026-06-15 — Confirmed against source: `Children => _children` returned the live mutable backing `List<LazyBrowseNode>` and `IsExpanded => _isExpanded` read a plain `bool`, while `ExpandAsync` appended to that same list under `_expandLock` with no release/acquire barrier to lock-free readers — so a concurrent reader could enumerate a mid-append list and throw `InvalidOperationException` ("collection was modified"). Applied option (b) (safe publication): `ExpandAsync` now accumulates children into a method-local `List<LazyBrowseNode>` and, only when fully drained across all pages, publishes it via `Volatile.Write(ref _children, children)` (release) immediately before setting the now-`volatile bool _isExpanded = true`. The `_children` field is an `IReadOnlyList<LazyBrowseNode>` read via `Volatile.Read` from the `Children` getter (acquire), so a reader that observes `IsExpanded == true` always sees the fully-populated snapshot and never enumerates a partially-built list. Updated the `ExpandAsync` `<remarks>` to document the strengthened concurrent-read guarantee. Regression test `LazyBrowseNodeTests.Expand_ConcurrentReadOfChildren_NeverTearsAndPublishesAtomically` gates the child-page RPCs (via a new `FakeGalaxyRepositoryTransport.BrowseChildrenGate` hook) to hold the expand mid-flight while a background reader spins enumerating `Children` and reading `IsExpanded`, asserting no exception escapes and that once `IsExpanded` is true the published snapshot has all five children. Verified red against the pre-fix code (the reader threw `InvalidOperationException: Collection was modified` deterministically across three runs) and green after the fix.
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/go` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -83,6 +83,39 @@ that earlier commit.
 | 9 | Testing coverage | New issue: the five new bulk SDK methods and `Client.StreamAlarms` have no unit tests in `mxgateway/` (Client.Go-024). |
 | 10 | Documentation & comments | No issues found in this diff. README documents the new `StreamAlarms`/`AcknowledgeAlarm` SDK calls; `Session.ReadBulk` documents the cached-vs-snapshot semantics and `timeout=0` default; `WriteSecuredBulk` flags credential sensitivity. |

+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff is larger than the brief suggested:
+`82996aa` resolved Client.Go-022..027 (already closed). On top of that,
+`fd2a0ac`/`4a19854`/`da3aa7b`/`92cc468`/`75610e3` added a `LazyBrowseNode`
+lazy-hierarchy walker (`Browse`/`Expand`/`BrowseChildrenRaw`) over the new
+`BrowseChildren` RPC and paginated `DiscoverHierarchy`; `c463b49`/`2eb8137`/
+`9bdb899` made the TLS path lenient-by-default (accept the gateway's
+self-signed cert unless `RequireCertificateValidation` or `CACertFile` is set);
+`6df373a` added the release docs + `scripts/tag-go-module.ps1`. `gofmt -l .`,
+`go vet ./...`, `go build ./...`, and `go test ./...` are all clean at HEAD.
+
+Two new low/medium issues in the release-helper and install docs. The
+lenient-TLS default is an intentional, documented project posture
+(`docs/GatewayConfiguration.md` "clients are lenient" to pair with the
+auto-generated self-signed cert) and the `//nolint:gosec` is correctly
+justified — not a finding. The `LazyBrowseNode` concurrency model
+(coalesced in-flight Expand, non-sticky failures, snapshot copies under
+`RWMutex`) is sound and well-tested, including a 10-goroutine race test.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | New issue: `tag-go-module.ps1`'s clean-tree guard is order-dependent and silently permits tagging with uncommitted tracked changes when an untracked path sorts first (Client.Go-028). `DiscoverHierarchy`/`browseChildrenInner` pagination, the `child_has_children` hint mapping, and the duplicate-page-token guard are all correct. |
+| 2 | mxaccessgw conventions | No issues found. `gofmt -l .` / `go vet ./...` clean; the `//nolint:gosec` on `InsecureSkipVerify` carries a narrow justified reason per the suppression convention. |
+| 3 | Concurrency & thread safety | No issues found — `LazyBrowseNode.Expand` runs the RPC outside both locks, coalesces concurrent callers onto one in-flight RPC, publishes the result before `close(done)`, and leaves failures retryable; verified by `TestGalaxyBrowseExpandConcurrentCallersOnlyFireOneRpc` (`-race`-shaped). |
+| 4 | Error handling & resilience | No issues found — `BrowseChildrenRaw` wraps transport failures in `*GatewayError`; both paginating loops guard against a repeated page token. |
+| 5 | Security | No issues found — no committed secrets (only `"test"` / `"test-api-key"` fixtures); the lenient-TLS default is the documented project posture with an opt-in strict mode (`RequireCertificateValidation`). |
+| 6 | Performance & resource management | No issues found — `DiscoverHierarchy` cancels each page's call context promptly inside the loop; `Children()` returns a defensive copy. |
+| 7 | Design-document adherence | No issues found — lazy browse matches `docs/GalaxyRepository.md#browsechildren`; lenient TLS matches `docs/GatewayConfiguration.md`. |
+| 8 | Code organization & conventions | No issues found — additive API (`Browse`/`BrowseChildrenOptions`/`RequireCertificateValidation`); `tlsConfigForOptions` cleanly extracted for testability. |
+| 9 | Testing coverage | No issues found — new walker, pagination, dup-token, filter-forwarding, and TLS-posture paths are all covered. |
+| 10 | Documentation & comments | New issue: README "Installing the Go client" recommends the `GONOSUMCHECK` env var, which was removed from the Go toolchain in 1.13 and is a no-op on Go 1.26 (Client.Go-029). |
+
 ## Findings

 ### Client.Go-001
@@ -625,3 +658,51 @@ The two cases the empty-line check seems to cover — (a) operator pressing Ente
 **Recommendation:** Change `if line == "" { break }` to `if line == "" { continue }` (alongside the existing `len(args) == 0` continue, which is then redundant — keep one, drop the other for clarity). Update the `runBatch` doc-comment to read "only stdin EOF ends the session" and drop the "or an empty line" clause. If the interactive ergonomic is genuinely wanted, gate it on `isatty(stdin)` so the batch-from-pipe case isn't affected.

 **Resolution:** 2026-05-24 — `runBatch` no longer treats a blank line as end-of-session. The `if line == "" { break }` early-exit was removed; blank or whitespace-only lines now fall through the existing `if len(args) == 0 { continue }` guard (kept as the single blank-line skip rule for clarity), so only stdin EOF ends the session. The doc-comment was updated to read "Blank lines are skipped; only stdin EOF ends the session." Regression test `TestRunBatchSkipsBlankLinesAndContinuesUntilEOF` in `cmd/mxgw-go/main_test.go` feeds `version --json\n\nversion --json\n` (a stray blank line between two commands) and asserts two EOR sentinels are emitted — pre-fix the test failed with "EOR sentinel count = 1, want 2" because the blank line broke the loop and the second command never ran; post-fix both commands run.
+
+### Client.Go-028
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Correctness & logic bugs |
+| Location | `scripts/tag-go-module.ps1:42-46` |
+| Status | Resolved |
+
+**Description:** The release helper's clean-working-tree guard is order-dependent and can silently let a release tag be created on top of uncommitted tracked changes — the exact thing it advertises it prevents (the README at `clients/go/README.md` says "The script ... refuses to tag with uncommitted tracked changes"). The check is:
+
+```powershell
+$status = (git status --porcelain) -join "`n"
+if ($status -and -not ($status -match '^\?\?')) {
+    throw "Working tree has tracked changes. Commit or stash before tagging."
+}
+```
+
+`git status --porcelain` emits one line per path (`XY path`), with untracked entries prefixed `??`. The lines are joined into a single string and matched against `'^\?\?'` with PowerShell `-match`, which by default is single-line (no `(?m)` multiline flag), so `^` anchors to the start of the *whole* joined string. The guard therefore inspects only the **first** status line: if that first line is an untracked file (`??`), the `-not (... -match '^\?\?')` clause is false and the throw is skipped — even when later lines are tracked modifications (` M file.go`, `A  file.go`, etc.). Because `git status --porcelain` orders entries by pathname, an untracked file whose name sorts ahead of a modified tracked file (e.g. an untracked `AAA-notes.md` alongside a modified `mxgateway/session.go`) puts the `??` line first and the tag is created from a dirty tree. This was confirmed empirically: with `"?? untracked.md\n M tracked.go"` the script allows the tag; with the tracked line first it correctly throws. The whole point of the guard — reproducible release tags that match a committed state — is defeated in this ordering.
+
+**Recommendation:** Test each status entry individually rather than the first line of a joined blob. For example, iterate the porcelain lines and throw if any line does **not** start with `??`:
+
+```powershell
+$dirty = (git status --porcelain) | Where-Object { $_ -and ($_ -notmatch '^\?\?') }
+if ($dirty) {
+    throw "Working tree has tracked changes. Commit or stash before tagging.`n$($dirty -join "`n")"
+}
+```
+
+(Equivalently, keep the joined string but use the multiline flag and negate per-line: `($status -split "`n") | ? { $_ -notmatch '^\?\?' }`.) Including the offending lines in the thrown message also helps the operator see what is dirty.
+
+**Resolution:** 2026-06-15 — Replaced the order-dependent joined-blob check in `tag-go-module.ps1` with a per-line filter (`git status --porcelain | Where-Object { $_ -and ($_ -notmatch '^\?\?') }`) that throws on any tracked change regardless of ordering, listing the offending lines. Verified under pwsh 7.5.4 that an untracked path sorting ahead of a modified tracked file is now correctly rejected, while untracked-only and clean trees are still allowed.
+
+### Client.Go-029
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `clients/go/README.md:300-303` |
+| Status | Resolved |
+
+**Description:** The "Installing the Go client" section advises, for build environments that cannot reach `gitea.dohertylan.com` directly, to "use `GONOSUMCHECK` + `GOPRIVATE` to bypass the checksum database for the internal module path." `GONOSUMCHECK` is a dead environment variable — it was removed from the Go toolchain in Go 1.13 (its short-lived successor `GONOSUMDB` was also removed), and on the Go 1.26 toolchain this client targets (`go.mod` says `go 1.26`) setting it has no effect. The actual mechanism is `GOPRIVATE` (or the finer-grained `GONOSUMCHECK`-replacement `GONOSUMDB`→now `GONOSUMCHECK` is gone) — `GOPRIVATE=gitea.dohertylan.com/*` alone already both skips the checksum database and bypasses the public proxy for matching module paths, so the `GONOSUMCHECK` half of the recommendation is inert and misleading. A reader who copies the advice and finds checksum-db verification still failing has no working escape hatch from this doc.
+
+**Recommendation:** Drop `GONOSUMCHECK` and document the current knobs: set `GOPRIVATE=gitea.dohertylan.com/*` (covers both sum-db bypass and direct VCS fetch), or for the checksum database specifically `GONOSUMCHECK`'s modern equivalent `GONOSUMDB` is also gone — use `GONOSUMCHECK`→`GOFLAGS=-insecure` only for plaintext, and `GONOSUMCHECK`. Concretely: "set `GOPRIVATE=gitea.dohertylan.com/*` (this disables both the checksum database and the public module proxy for that path); add `GOINSECURE=gitea.dohertylan.com/*` if the host serves the module over plain HTTP."
+
+**Resolution:** 2026-06-15 — Dropped the dead `GONOSUMCHECK` advice from the "Installing the Go client" section of `clients/go/README.md`; it now documents `GOPRIVATE=gitea.dohertylan.com/*` (which bypasses both the public module proxy and checksum-database verification for that path) plus `GOINSECURE=gitea.dohertylan.com/*` for plain-HTTP hosts.
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/java` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -77,6 +77,35 @@ Client.Java-001..031 are unchanged.
 | 9 | Testing coverage | Issue found: the new `MxGatewayClient.streamAlarms` SDK method has no library-side test in `zb-mom-ww-mxgateway-client/src/test/...` — only the CLI test exercises the path via a `FakeClient.streamAlarms` override that bypasses the production `subscription.wrap(observer)` glue (Client.Java-035). |
 | 10 | Documentation & comments | Issue found: README (`clients/java/README.md:182-183`) documents the new `stream-alarms` and `acknowledge-alarm` commands with `--session-id <id>` (neither command has that option) and `acknowledge-alarm --alarm-reference …` (actual flag is `--reference`) — every documented invocation fails at picocli parse time (Client.Java-032). |

+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. Diff against `42b0037` is eleven commits touching
+`clients/java`: `d3cb311` (Client.Java-032..036 fixes — shared subscription
+base + batch tokenizer), `0d6193c`/`803a207`/`b4bc2df`/`4a19854`/`b244851`/
+`68f905a` (the `BrowseChildren` lazy-browse SDK surface: `GalaxyRepositoryClient.browse()`,
+`browse(BrowseChildrenOptions)`, `browseChildrenRaw`, `browseChildrenInner`,
+plus the `LazyBrowseNode` walker and `BrowseChildrenOptions`), `a276f46`/
+`ba82afe`/`2eb8137` (lenient-by-default TLS: new `requireCertificateValidation`
+option, `InsecureTrustManagerFactory` fallback, foojay toolchain resolver), and
+`fe44e3c` (maven-publish wiring for the Gitea Maven feed). Generated
+protobuf/gRPC Java is excluded. `gradle test` could not be run here — this macOS
+host has no Java runtime (the module builds on the Windows host per project
+memory); findings below are from source inspection. Prior findings
+Client.Java-001..036 are unchanged.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found in this diff. `LazyBrowseNode.expand()` leader/coalesce logic is correct (single in-flight future, slot cleared on failure for retry); `browseChildrenInner` pagination handles the empty/null next-page token and guards against repeated page tokens; the `child_has_children` parallel array is bounds-checked (`i < getChildHasChildrenCount()`), defaulting absent hints to false. |
+| 2 | mxaccessgw conventions | No issues found. No MXAccess COM, no synthesized events, generated code untouched. The lenient-TLS default is a documented repo-wide design decision (`docs/DesignDecisions.md` "TLS Auto-Certificate and Lenient Client Trust"), not a Java-specific deviation. |
+| 3 | Concurrency & thread safety | No issues found. `LazyBrowseNode` does not hold the `expandLock` monitor across the BrowseChildren RPC (fixed in `68f905a`); readers use a separate `ReentrantReadWriteLock` so `getChildren()`/`isExpanded()` never block on the in-flight RPC; `BrowseChildrenOptions` is immutable. The shared `MxGatewayStreamSubscription` base (Client.Java-036) is covered. |
+| 4 | Error handling & resilience | No issues found. `browseChildrenRaw` normalises non-`MxGatewayException` gRPC errors via `MxGatewayErrors.fromGrpc`; the non-leader `expand()` path rethrows the leader's `MxGatewayException`/`RuntimeException` and restores the interrupt flag on `InterruptedException`. |
+| 5 | Security | No issues found. maven-publish credentials come from `GITEA_USERNAME`/`GITEA_TOKEN` env vars with empty-string fallback — no committed secrets. The lenient-TLS `InsecureTrustManagerFactory` default is the documented, intentional design for this PKI-less internal tool; strict verification is reachable via `caCertificatePath` (pin) or `requireCertificateValidation(true)`, both tested in `MxGatewayClientTlsTests`. |
+| 6 | Performance & resource management | No issues found. |
+| 7 | Design-document adherence | No issues found. The browse surface matches `docs/GalaxyRepository.md#browsechildren` (cache-served lazy expand, `has_children` hint, repeated-page-token → error); the TLS posture matches `docs/GatewayConfiguration.md` and `JavaClientDesign.md`. |
+| 8 | Code organization & conventions | Issue found: the new `requireCertificateValidation` library option is not exposed or propagated by the CLI `CommonOptions.toClientOptions()`, so CLI users cannot opt into JVM-trust-store verification — same additive-surface gap pattern as the resolved Client.Java-025 (Client.Java-038). |
+| 9 | Testing coverage | No issues found. The browse surface has thorough library tests in `GalaxyRepositoryClientTests` (roots, expand-populates, idempotent-single-RPC, unknown-parent not-found, multi-page gather, concurrent-callers-one-RPC, filter forwarding, repeated-page-token rejection); TLS lenient/strict paths are covered by `MxGatewayClientTlsTests` against a real in-process TLS server. |
+| 10 | Documentation & comments | Issue found: the README "Browsing lazily" first code snippet calls `galaxy.browseChildren(BrowseChildrenRequest…)`, but no such method exists on `GalaxyRepositoryClient` — the raw single-RPC method is `browseChildrenRaw(BrowseChildrenRequest)`; the documented snippet does not compile (Client.Java-037). |
+
 ## Findings

 ### Client.Java-001
@@ -662,4 +691,56 @@ This is the same maintenance-hazard pattern Client.Java-009 / Client.Java-016 id

 **Resolution:** 2026-05-24 — Extracted a package-private abstract base `MxGatewayStreamSubscription<TRequest, TResponse> implements AutoCloseable` (new file `clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayStreamSubscription.java`). It holds the shared `AtomicReference<ClientCallStreamObserver<TRequest>>` and `AtomicBoolean cancelled` pair, the `wrap(StreamObserver<TResponse>)` factory that returns a `ClientResponseObserver` with the Client.Java-014 close-before-beforeStart fix baked in, the `cancel()` / `close()` implementation, and an immutable `cancelMessage` injected by the subclass constructor. The four prior 60-line near-clones (`MxGatewayEventSubscription`, `MxGatewayAlarmFeedSubscription`, `MxGatewayActiveAlarmsSubscription`, `DeployEventSubscription`) collapse to ~10-line subclasses that only declare their `<Request, Response>` type parameters and supply the cancel-message string to `super(...)`. Public API surface is preserved: each subclass remains a `public final class` with a public no-arg constructor (the constructor was implicit on the original classes; I made it explicit `public` on the subclasses so the existing CLI `FakeClient.streamAlarms` in a different package can still `new MxGatewayAlarmFeedSubscription()`). The `wrap(...)` method is `final` and package-private on the base — same accessibility the four subclasses had before — so production callers in `MxGatewayClient`/`GalaxyRepositoryClient` see no change. New test file `MxGatewayStreamSubscriptionContractTests` exercises the lifecycle/cancellation contract identically across all four subclasses (16 tests, four per scenario): (a) cancel-before-beforeStart eagerly cancels the stream once it attaches with the subclass-specific message, (b) cancel-after-beforeStart forwards directly to the stream, (c) `close()` delegates to `cancel()`, (d) the wrapped observer forwards `onNext`/`onError`/`onCompleted` verbatim, and a compile-time `typeBoundsCheck` helper that asserts each subclass still binds its `<Req, Resp>` parameters to the right proto types. TDD red phase confirmed: temporarily breaking one subclass's `super(...)` message to `"BROKEN MESSAGE"` made the contract test for that subclass fail with `expected: <client cancelled alarm feed> but was: <BROKEN MESSAGE>`; restoring the correct value turned all 16 contract tests green. Future fixes to the shared lifecycle now live in one place — the next Client.Java-014/021-style race fix cannot drift across the four classes.

+### Client.Java-037

+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Documentation & comments |
+| Location | `clients/java/README.md:138-149` |
+| Status | Resolved |
+
+**Description:** The "Browsing lazily" section's first (low-level) code snippet documents a `browseChildren` method that does not exist on the public client surface:
+
+```java
+BrowseChildrenReply reply = galaxy.browseChildren(
+        BrowseChildrenRequest.newBuilder().build());
+```
+
+`GalaxyRepositoryClient` exposes only `browse()`, `browse(BrowseChildrenOptions)`, and the raw single-RPC method `browseChildrenRaw(BrowseChildrenRequest)` (verified at `GalaxyRepositoryClient.java:227,238,251`). There is no `browseChildren(BrowseChildrenRequest)`, so the documented snippet fails to compile — a user copy-pasting the primary low-level example hits a missing-symbol error immediately. The README hedges the snippet with "This snippet documents the API as it appears once the Java client is regenerated on the Windows host," but the discrepancy is not a regeneration artifact: the hand-written wrapper method is named `browseChildrenRaw`, not `browseChildren`. The adjacent "High-level walker" snippet (`galaxy.browse()`, `root.expand()`, `root.getChildren()`, `child.hasChildrenHint()`, `child.getObject().getTagName()`) is correct against the actual API; only the low-level snippet is wrong.
+
+**Recommendation:** Change `galaxy.browseChildren(` to `galaxy.browseChildrenRaw(` in the low-level snippet so it matches the real method name, or replace the low-level example with the `browse()`/`LazyBrowseNode` walker that the SDK actually intends as the primary surface. Drop the "as it appears once regenerated" caveat once the snippet compiles against the current source. Consider an `installDist`-based or compile-checked doc snippet test to prevent README API drift, mirroring the parse-only assertions added for Client.Java-032.
+
+**Resolution:** 2026-06-15 — Confirmed against source: `GalaxyRepositoryClient` (`zb-mom-ww-mxgateway-client/.../GalaxyRepositoryClient.java:227,238,251`) exposes only `browse()`, `browse(BrowseChildrenOptions)`, and the raw single-RPC `browseChildrenRaw(BrowseChildrenRequest)` — there is no `browseChildren(BrowseChildrenRequest)`, so the documented snippet did not compile. Fixed the README "Browsing lazily" low-level snippet at `clients/java/README.md` by renaming `galaxy.browseChildren(` to `galaxy.browseChildrenRaw(`; the surrounding accessors (`BrowseChildrenReply`/`BrowseChildrenRequest` types, `getChildrenList()`, `getChildHasChildrenList()`, `getTagName()`) are all valid proto accessors and were left unchanged. Replaced the misleading "as it appears once the Java client is regenerated on the Windows host" caveat (the discrepancy was a hand-written wrapper name, not a codegen artifact) with prose steering callers to the high-level `browse()`/`LazyBrowseNode` walker as the preferred surface and `browseChildrenRaw` as the direct-paging escape hatch. Documentation-only change; no test added (no compile-checked doc-snippet harness exists yet — left as the noted future enhancement).
+
+### Client.Java-038
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1347-1393` |
+| Status | Resolved |
+
+**Description:** Commit `a276f46` added `requireCertificateValidation` to `MxGatewayClientOptions` as a first-class TLS-trust toggle (lenient-by-default; set `true` to verify against the JVM trust store without pinning a CA). The CLI `CommonOptions` exposes `--plaintext`, `--ca-file`, and `--server-name-override` and propagates them through `toClientOptions()`, but it neither declares a `--require-certificate-validation` option nor sets `builder.requireCertificateValidation(...)`. CLI users therefore have no way to request strict verification short of supplying a pinned CA via `--ca-file`; the lenient `InsecureTrustManagerFactory` default is forced on every non-pinned TLS CLI connection. This is the same additive-surface gap pattern as the resolved Client.Java-025 (`shutdownTimeout` not propagated to the CLI). `docs/CrossLanguageSmokeMatrix.md` documents `--require-certificate-validation` for the Rust CLI's pin-only stack but not Java, so this is not a direct README contradiction; it is a library-vs-CLI surface inconsistency. Severity is Low because the secure-by-pinning path (`--ca-file`) remains available and the lenient default is the documented intended behaviour for this internal tool.
+
+**Recommendation:** Add a `--require-certificate-validation` boolean option to `CommonOptions` (default unset/false to preserve the lenient default) and propagate it into `toClientOptions()` via `builder.requireCertificateValidation(value)`. Include the resolved value in `redactedJsonMap()` so `--json` output reflects the effective trust posture. Add a CLI parse-only assertion exercising the flag to keep the CLI surface tracking the library surface.
+
+**Resolution:** 2026-06-15 — Confirmed against source: `MxGatewayClientOptions` (`zb-mom-ww-mxgateway-client/.../MxGatewayClientOptions.java:108,260`) exposes `requireCertificateValidation()` and a `Builder.requireCertificateValidation(boolean)`, but the CLI `CommonOptions` in `MxGatewayCli.java` declared no flag and `toClientOptions()` never set it, forcing the lenient default on every non-pinned TLS CLI connection. Added a bare-boolean `@Option(names = "--require-certificate-validation")` field to `CommonOptions` (defaults to `false`, preserving the lenient default; mirrors the existing `--plaintext` flag-style option), propagated it through `toClientOptions()` via `.requireCertificateValidation(requireCertificateValidation)`, and added it to `redactedJsonMap()` so `--json` output reflects the effective trust posture. Documented the new flag and the lenient-by-default trust posture in `clients/java/README.md`. Note: the Client.Java-025 precedent (`shutdownTimeout`) was applied to the pre-rename `mxgateway-cli` module and is not present in this renamed `zb-mom-ww-mxgateway-cli` `toClientOptions()`; I mirrored the live `--ca-file`/`--server-name-override` TLS-option plumbing pattern instead, which is the correct precedent here. Regression tests in `MxGatewayCliTests`: `requireCertificateValidationFlagPropagatesThroughToClientOptions` (drives `acknowledge-alarm --require-certificate-validation` through a new `CapturingClientFactory` that records `options.toClientOptions()` and asserts `MxGatewayClientOptions.requireCertificateValidation()` is `true`) and `requireCertificateValidationDefaultsToLenientWhenFlagAbsent` (asserts the flag defaults to `false`). The capturing factory exercises the real `toClientOptions()` propagation, stronger than a parse-only check.
+
+
+
+### Client.Java-039
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1699` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto`, `AlarmFeedMessage.payload` provider-status arm added in commit `1d85db7`) |
+| Status | Resolved |
+
+**Description:** The Java CLI does not compile at HEAD `410acc9`. `formatAlarmFeedMessage` switches over `message.getPayloadCase()` as an exhaustive switch *expression* with no `default`, covering only `ACTIVE_ALARM`, `SNAPSHOT_COMPLETE`, `TRANSITION`, and `PAYLOAD_NOT_SET`. The alarm-provider-fallback contract change `1d85db7` added a fourth `AlarmFeedMessage.payload` oneof arm (`AlarmProviderStatus provider_status`), so the generated `PayloadCase` enum now has a `PROVIDER_STATUS` value the switch does not handle — `javac` rejects it with "the switch expression does not cover all possible input values" and `gradle :zb-mom-ww-mxgateway-cli:compileJava` fails. This is the same class of cross-component contract-propagation break as Client.Rust-030 and IntegrationTests-026: a new contract field that left a downstream exhaustive consumer uncompilable. The original re-review (Client.Java-037/038) missed it because there is no JVM on the macOS review host and `gradle` could not be run; the break surfaced when the fixes were verified on the Windows host. Because the CLI is the cross-language e2e driver, the whole Java client artifact set cannot build and no Java e2e smoke can run.
+
+**Recommendation:** Add a `PROVIDER_STATUS` arm to `formatAlarmFeedMessage` that renders the provider status (mode / degraded / reason) consistently with the other alarm-feed arms — do not add a `default ->` that silently drops it, since the provider status is meaningful and the exhaustive switch is the compiler-enforced guard that catches exactly this kind of future contract drift.
+
+**Resolution:** 2026-06-15 — Confirmed via `gradle :zb-mom-ww-mxgateway-cli:compileJava` failing with "the switch expression does not cover all possible input values" at `MxGatewayCli.java:1699` on the Windows host. Added a `case PROVIDER_STATUS ->` arm to `formatAlarmFeedMessage` yielding `provider-status mode=%s degraded=%b reason=%s` (from `AlarmProviderStatus.getMode().name()` / `getDegraded()` / `getReason()`), plus the `import mxaccess_gateway.v1.MxaccessGateway.AlarmProviderStatus;`. No `default` arm — the exhaustive switch expression remains the compile-time guard against future `payload` oneof additions. Verified `gradle test` builds and passes on the Windows host (Java 21).
@@ -4,16 +4,48 @@
 |---|---|
 | Module | `clients/python` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

 ## Checklist coverage

+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff against the previous review base
+`42b0037` covers: PyPI metadata + Gitea PyPI-feed install instructions in
+`pyproject.toml` / `README.md`; a new lazy Galaxy browse surface
+(`GalaxyRepositoryClient.browse_children_raw` / `browse` / `_iter_browse_children`,
+the `LazyBrowseNode` walker, and `BrowseChildrenOptions`); a TLS
+trust-on-first-use (TOFU) default in `options.py` gated by a new
+`ClientOptions.require_certificate_validation` flag; the `_use_plaintext`
+TLS-default contract carried forward; and the `batch` `CliRunner`-removal
+follow-through. The new browse / TOFU surface is well tested
+(`tests/test_galaxy.py`, `tests/test_auth_options.py`, `tests/test_tls.py`).
+
+`python -m pytest` passes (80 passed, 1 skipped — the loopback-TLS test is
+opt-in via `MXGATEWAY_RUN_TLS_TESTS=1`). `python -m pip wheel .` builds the
+wheel cleanly against the installed setuptools 82.0.1.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: `_split_authority` raises an uncaught `ValueError` for a port-less endpoint instead of a transport error (Client.Python-029). |
+| 2 | mxaccessgw conventions | No new issues found — secrets still redacted, generated code untouched, no committed tokens in the new Gitea feed URLs (placeholders only). |
+| 3 | Concurrency & thread safety | No new issues found — `LazyBrowseNode.expand` uses a per-node `asyncio.Lock` with a double-checked guard and is verified concurrent-safe by `test_browse_expand_concurrent_callers_only_fire_one_rpc`. |
+| 4 | Error handling & resilience | Issue found: the TOFU branch calls the blocking `ssl.get_server_certificate` with no timeout from inside the `async def connect` path, blocking the event loop and hanging indefinitely on a black-holed host (Client.Python-028). |
+| 5 | Security | Issue found: the new `require_certificate_validation` security flag is not reachable through the documented `connect(...)` convenience kwargs or any CLI flag, so callers using those paths are locked into TOFU and cannot force certificate validation (Client.Python-027). TOFU itself is design-sanctioned (`docs/GatewayConfiguration.md` line 470). |
+| 6 | Performance & resource management | No new issues found beyond the blocking TLS probe captured in Client.Python-028. |
+| 7 | Design-document adherence | No new issues found — TOFU default, `require_certificate_validation` naming, and the BrowseChildren surface match `docs/GatewayConfiguration.md` / `docs/GalaxyRepository.md`; both README doc anchors resolve. |
+| 8 | Code organization & conventions | Issue found: `pyproject.toml` uses the PEP 639-deprecated `license = { text = ... }` table form (Client.Python-030). pyproject metadata is otherwise correct and the wheel builds. |
+| 9 | Testing coverage | Issue found: the `tls` pytest mark used by `tests/test_tls.py` is not registered in `[tool.pytest.ini_options]`, emitting a `PytestUnknownMarkWarning` (Client.Python-031). New browse / TOFU paths are otherwise well covered. |
+| 10 | Documentation & comments | No new issues found — README TLS/browse/Gitea-feed prose matches the code; the alarm-CLI README examples corrected under Client.Python-022 remain correct. |
+
+### Prior coverage (commit a020350)
+
 A re-review at commit `a020350` over the same module. Prior findings
 (Client.Python-001 — Client.Python-017) remain closed and are kept as
-history. This section reflects categories evaluated in this pass.
+history. This section reflects categories evaluated in that pass.

 | # | Category | Result |
 |---|---|---|
@@ -1171,3 +1203,238 @@ scope; `test_commands_module_bench_read_bulk_does_not_use_bare_except_pass`
 greps the function source for the `except Exception:\n    pass` pattern
 and rejects it. Both tests failed against the pre-fix source and pass
 against the fix.
+
+### Client.Python-027
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Security |
+| Location | `clients/python/src/zb_mom_ww_mxgateway/client.py:36-54`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:47-66`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:165-172,918-930` |
+| Status | Resolved |
+
+**Description:** This commit adds `ClientOptions.require_certificate_validation`
+(default `False`) so a caller can force system-trust certificate verification
+instead of the new lenient trust-on-first-use (TOFU) default. The flag is
+honoured inside `create_channel`, but it is not surfaced through either of the
+two documented ways a normal caller dials the gateway:
+
+1. `GatewayClient.connect(...)` and `GalaxyRepositoryClient.connect(...)` accept
+   the convenience kwargs `endpoint` / `api_key` / `plaintext` / `ca_file` /
+   `server_name_override` and build the `ClientOptions` internally, but do **not**
+   accept or forward `require_certificate_validation`. The README's high-level
+   examples (e.g. the lazy-browse walker) use exactly this kwarg form
+   (`GalaxyRepositoryClient.connect(endpoint=..., api_key=..., plaintext=True)`),
+   so the kwarg path is the primary documented entry point.
+2. The CLI exposes `--plaintext`, `--tls`, and `--ca-file` but no
+   `--require-certificate-validation` flag, and `_connect` constructs
+   `ClientOptions(...)` without setting the field. A CLI user connecting to a
+   TLS gateway is therefore locked into TOFU.
+
+The net effect is that the *only* way to opt into real certificate validation is
+to construct a `ClientOptions` instance directly and pass it as the positional
+`options=` argument — a path neither the README nor the CLI documents. A
+security-sensitive deployment that wants the strict (verify-against-system-trust)
+posture cannot select it through the documented surface, so it silently stays on
+TOFU. TOFU itself is design-sanctioned (`docs/GatewayConfiguration.md` line 470
+explicitly says "Python uses trust-on-first-use"), so this is an opt-in-to-strict
+reachability gap rather than an insecure default — hence Medium with a workaround.
+
+**Recommendation:** Add a `require_certificate_validation: bool = False` kwarg to
+both `GatewayClient.connect` and `GalaxyRepositoryClient.connect` and forward it
+into the constructed `ClientOptions`. Add a `--require-certificate-validation`
+(or `--verify-tls`) flag to the shared CLI option set and wire it through
+`_connect`. Add a test asserting the flag flows through to
+`ClientOptions.require_certificate_validation` and a README note documenting how
+to select the strict posture.
+
+**Resolution:** 2026-06-15 — Confirmed: `connect` built `ClientOptions` from a
+fixed kwarg set that omitted `require_certificate_validation`, and the CLI had no
+flag, so the strict posture was only reachable via a hand-built `options=`. Added
+a `require_certificate_validation: bool = False` kwarg to both
+`GatewayClient.connect` and `GalaxyRepositoryClient.connect` (forwarded into the
+constructed `ClientOptions`), a `--require-certificate-validation` flag to the
+shared `gateway_options` CLI option set, and wired it through `_connect`. README
+TLS section now documents the strict posture is reachable via the connect kwarg,
+the options struct, and the CLI flag. Tests:
+`tests/test_client_session.py::test_gateway_connect_forwards_require_certificate_validation`,
+`::test_galaxy_connect_forwards_require_certificate_validation`,
+`tests/test_cli.py::test_require_certificate_validation_flag_flows_through_connect`,
+`::test_require_certificate_validation_defaults_off` — all failed before the fix
+and pass after.
+
+### Client.Python-028
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/python/src/zb_mom_ww_mxgateway/options.py:120-130`, `clients/python/src/zb_mom_ww_mxgateway/client.py:59`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:71` |
+| Status | Resolved |
+
+**Description:** The TOFU branch of `create_channel` calls
+`ssl.get_server_certificate((host, port))` to pre-fetch the server certificate.
+`create_channel` is a synchronous function, but it is invoked exclusively from
+inside the `async def connect` classmethods of `GatewayClient` and
+`GalaxyRepositoryClient` (`client.py:59`, `galaxy.py:71`). `ssl.get_server_certificate`
+opens a real blocking TCP+TLS socket on the calling thread, so:
+
+1. It **blocks the asyncio event loop** for the full duration of the connect/handshake.
+   This is at odds with the rest of the client, which is fully `async`.
+2. It passes **no `timeout`** to `ssl.get_server_certificate`. The `test_tofu_connect_failure_raises_transport_error`
+   test only proves the *connection-refused* case (a closed port returns fast).
+   A black-holed / firewall-drop host (packets silently dropped) makes the
+   underlying `socket.create_connection` hang on the OS default connect timeout,
+   which can be minutes, with the event loop frozen the whole time. A caller that
+   wrapped `connect` in `asyncio.wait_for(...)` cannot cancel it because the block
+   is in synchronous C, not at an `await` point.
+
+The other TLS branches (`ca_file`, `require_certificate_validation`) build the
+channel lazily and return immediately, so only the lenient default — the most
+common path — has this hazard.
+
+**Recommendation:** Pass an explicit `timeout=` to `ssl.get_server_certificate`
+(it accepts one), bounded by `options.call_timeout` or a short fixed value, so a
+black-holed host fails fast as a `MxGatewayTransportError` instead of hanging.
+Better, run the synchronous probe off the event loop — make the TOFU pre-fetch
+path awaitable (e.g. wrap it in `asyncio.get_running_loop().run_in_executor(...)`
+from an `async` channel factory, or document that `connect` must not be called
+from a running loop). Add a regression test that asserts the probe honours a
+timeout.
+
+**Resolution:** 2026-06-15 — Confirmed: the TOFU branch called
+`ssl.get_server_certificate((host, port))` with no timeout from the synchronous
+`create_channel`, which both `connect` classmethods invoked directly on the event
+loop. Fix is two-part: (1) `create_channel` now passes
+`timeout=options.call_timeout` (falling back to a fixed
+`_TOFU_PROBE_TIMEOUT_SECONDS = 10.0` when no call_timeout is set) to
+`ssl.get_server_certificate`, and the existing `except OSError` wraps a
+timeout/connect failure into `MxGatewayTransportError` (TimeoutError/socket.timeout
+are OSError subclasses); (2) both `GatewayClient.connect` and
+`GalaxyRepositoryClient.connect` now run the blocking factory off the loop via
+`await asyncio.to_thread(create_channel, resolved)`, so the event loop is never
+frozen and a caller's `asyncio.wait_for` can cancel the connect. Tests:
+`tests/test_auth_options.py::test_tofu_probe_passes_a_bounded_timeout`,
+`::test_tofu_probe_timeout_raises_transport_error` (parametrized over
+socket.timeout / TimeoutError / OSError), and
+`tests/test_client_session.py::test_gateway_connect_runs_create_channel_off_the_event_loop`,
+`::test_galaxy_connect_runs_create_channel_off_the_event_loop`. The timeout and
+off-loop tests failed before the fix and pass after.
+
+### Client.Python-029
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Correctness & logic bugs |
+| Location | `clients/python/src/zb_mom_ww_mxgateway/options.py:78-90` |
+| Status | Resolved |
+
+**Description:** `_split_authority` parses a non-bracketed target with
+`host, _, port = target.rpartition(":")` and returns
+`(host or "localhost", int(port) if port else 443)`. For a port-less endpoint
+such as `"mygateway"`, `rpartition(":")` returns `("", "", "mygateway")`, so
+`host` becomes `""` (→ `"localhost"`) and `port` becomes `"mygateway"`, and
+`int("mygateway")` raises an uncaught `ValueError: invalid literal for int()`.
+Because `_split_authority` is called *before* the `try/except OSError` guard in
+`create_channel`, the failure escapes as a raw `ValueError` rather than the
+intended `MxGatewayTransportError`, and the message does not name the endpoint.
+Verified at runtime:
+`_split_authority("mygateway")` → `ValueError: invalid literal for int() with base 10: 'mygateway'`.
+gRPC targets normally carry an explicit port (`host:port`), so impact is narrow,
+but a typo or a bare-hostname endpoint produces a confusing crash on the TOFU
+default path. The bracketed-IPv6 and `host:port` cases are covered by tests; the
+port-less case is not.
+
+**Recommendation:** Treat a non-numeric / missing port as the default (443) and
+keep the whole string as the host, e.g. detect a trailing `:<digits>` explicitly
+rather than assuming the `rpartition` tail is numeric, or wrap the `int(port)`
+conversion so a non-numeric tail falls back to host-only with the default port.
+Add a `_split_authority("mygateway")` case to `tests/test_tls.py`.
+
+**Resolution:** 2026-06-15 — Confirmed: `_split_authority("mygateway")` raised
+`ValueError: invalid literal for int() with base 10: 'mygateway'` because
+`rpartition(":")` put the whole string in the port slot. Rewrote the
+non-bracketed branch to inspect the `rpartition` separator and the tail: no colon
+→ whole target is the host with default port 443; a colon with a non-digit/empty
+tail → left side is the host with default port 443; a digit tail → parse the
+port. The bare-hostname case now returns `("mygateway", 443)` instead of raising,
+and the existing `":5120"` / `"localhost:5120"` / IPv6 cases are unchanged. Test:
+`tests/test_tls.py::test_split_authority_defaults_port_for_portless_endpoint`
+(covers `"mygateway"`, `"https://mygateway"`, and `"mygateway:"`) — failed before
+the fix and passes after.
+
+### Client.Python-030
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `clients/python/pyproject.toml:17` |
+| Status | Resolved |
+
+**Description:** This commit re-adds a `license` key to `pyproject.toml` as the
+table form `license = { text = "Proprietary" }`. Under PEP 639 (active in the
+installed setuptools 82.0.1), the `[project.license]` **table** forms (`text` and
+`file`) are deprecated in favour of the SPDX string expression, and a future
+setuptools major may reject them — the same class of regression that
+Client.Python-018 (the earlier `license = "Proprietary"` string, rejected because
+`Proprietary` is not a valid SPDX identifier) recorded for this exact field. The
+build currently succeeds (verified: `python -m pip wheel .` produces
+`zb_mom_ww_mxaccess_gateway_client-0.1.0-py3-none-any.whl` and the metadata
+carries `License: Proprietary` plus the `License :: Other/Proprietary License`
+classifier), so this is a forward-looking maintainability flag, not a present
+breakage. Note that pairing a `license` table with a `License ::` trove
+classifier is also flagged by PyPI/twine as redundant under the new metadata
+rules.
+
+**Recommendation:** Prefer the PEP 639 SPDX-string form with a `LicenseRef-*`
+custom identifier for an unlisted licence (`license = "LicenseRef-Proprietary"`)
+— this is the future-proof equivalent of the intent and avoids the deprecated
+table form — or drop the `license` key entirely and rely on the existing
+`License :: Other/Proprietary License` classifier (the Client.Python-018
+resolution chose this). The `tests/test_packaging.py::test_pip_wheel_build_succeeds`
+guard (added under Client.Python-020) will catch the day a setuptools upgrade
+turns the deprecation into a hard error.
+
+**Resolution:** 2026-06-15 — Switched the deprecated `license = { text =
+"Proprietary" }` table form to the PEP 639 SPDX-string form
+`license = "LicenseRef-Proprietary"` (the future-proof custom identifier for an
+unlisted/proprietary licence). Also removed the now-redundant
+`License :: Other/Proprietary License` trove classifier, which setuptools >= 77
+flags as conflicting when a `License-Expression` is present. The built wheel
+metadata now carries `License-Expression: LicenseRef-Proprietary` and no
+`Classifier: License ::` line. Verified by `python -m pip wheel . --no-deps`,
+which builds cleanly; the existing
+`tests/test_packaging.py::test_pip_wheel_build_succeeds` guard exercises the same
+build and passes.
+
+### Client.Python-031
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `clients/python/tests/test_tls.py:34`, `clients/python/pyproject.toml:53-56` |
+| Status | Resolved |
+
+**Description:** `tests/test_tls.py` applies a module-level
+`pytestmark = pytest.mark.tls`, but the `tls` marker is not registered in
+`[tool.pytest.ini_options]` (which declares only `addopts`, `pythonpath`, and
+`testpaths`). Every run emits a `PytestUnknownMarkWarning: Unknown
+pytest.mark.tls - is this a typo?`. The warning is benign today, but (a) it is
+exactly the kind of typo the warning exists to catch, so a future genuine
+mistyped marker would be lost in the noise, and (b) if the suite ever adopts
+`filterwarnings = ["error"]` (a common hardening step), the unregistered marker
+would turn into a hard collection failure.
+
+**Recommendation:** Register the marker, e.g.
+`markers = ["tls: loopback TLS tests, opt-in via MXGATEWAY_RUN_TLS_TESTS=1"]`
+under `[tool.pytest.ini_options]` in `clients/python/pyproject.toml`.
+
+**Resolution:** 2026-06-15 — Registered the `tls` marker by adding
+`markers = ["tls: loopback TLS tests, opt-in via MXGATEWAY_RUN_TLS_TESTS=1"]`
+under `[tool.pytest.ini_options]` in `clients/python/pyproject.toml`.
+`python -m pytest` now reports no `PytestUnknownMarkWarning` (full run: 91
+passed, 1 skipped, 0 warnings; previously 1 warning). The `tls`-marked
+`tests/test_tls.py` module is the guard — its run is now warning-free.
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `clients/rust` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -96,6 +96,25 @@ under review does not address them.
 | 9 | Testing coverage | Issue found: zero tests cover `stream_alarms` on `GatewayClient`, the new bulk read/write SDK methods, or the `BenchReadBulk` flow; the fake gateway's `stream_alarms` impl drops the sender immediately (Client.Rust-024). |
 | 10 | Documentation & comments | Issue found: `.cargo/config.toml`'s comment promises "Release builds are unaffected" but the `link-arg=/STACK:8388608` setting is unconditional under `cfg(windows)` and only applies to the MSVC linker (Client.Rust-027). |

+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9`. The diff against `42b0037` (`git diff 42b0037..HEAD -- clients/rust/`) covers: Cargo metadata + Gitea alternative-registry config (`Cargo.toml`, `.cargo/config.toml`, README install section); a `[registries.dohertj2-gitea]` index entry and `publish = ["dohertj2-gitea"]` with `mxgw-cli` set `publish = false`; the resolution work for Client.Rust-022..029 (malformed-reply `Result` plumbing, `next_correlation_id` re-export, clippy fixes, `read_bulk<S: AsRef<str>>`); a **new** Galaxy lazy-browse walker (`browse`, `browse_children_raw`, `browse_children_inner`, `BrowseChildrenOptions`, `LazyBrowseNode`) with six unit tests; a **new** TLS pin-only guard (`build_tls_config` + `ClientOptions::with_require_certificate_validation` + `--require-certificate-validation` CLI flag) with a new `tests/tls.rs`; and the alarm-provider-fallback proto surface (`AlarmFeedMessage.provider_status`, added contracts-side in `1d85db7`).
+
+`cargo fmt --check` is clean. `cargo check -p zb-mom-ww-mxgateway-client`, `cargo test -p zb-mom-ww-mxgateway-client` (24 lib + integration, 4 proto-fixture, 4 tls — all pass), and the library half of the workspace are clean. **`cargo clippy --workspace --all-targets -- -D warnings` and `cargo check --workspace` both FAIL at HEAD** — not on a lint but on a hard `E0004` compile error: the `mxgw-cli` binary's two `match &message.payload` blocks (`crates/mxgw-cli/src/main.rs:1731,1757`) are non-exhaustive after the proto added `AlarmFeedMessage.payload::ProviderStatus` (Client.Rust-030). The library crate compiles and all its tests pass; the break is confined to the CLI binary. No committed registry tokens — `.cargo/config.toml` carries only the sparse index URL; the README documents the token living in `~/.cargo/credentials.toml`.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: `mxgw-cli` fails to compile at HEAD — non-exhaustive `AlarmFeedMessage.payload` match missing the new `ProviderStatus` arm (Client.Rust-030). The library `read_bulk`/galaxy-walker/TLS-guard logic is correct and tested. |
+| 2 | mxaccessgw conventions | Issue found: `cargo clippy --workspace --all-targets -- -D warnings` / `cargo check --workspace` do not pass — CLAUDE.md mandates they do (Client.Rust-030). The prior 029 clippy regressions are resolved; this is a new build break from the alarm-provider proto change. |
+| 3 | Concurrency & thread safety | No issues found — `LazyBrowseNode` shares state via `Arc<…AsyncMutex<…>>`; `expand()` holds the mutex across the `browse_children_inner` await so concurrent expanders serialize and the idempotency check is race-free. `CORRELATION_SEQUENCE` is still `AtomicU64`/`Relaxed`. No `unsafe`. |
+| 4 | Error handling & resilience | Issue found: the strict TLS path (`require_certificate_validation(true)` with no CA) builds a `ClientTlsConfig` with zero trust roots (no `tls-native-roots`/`tls-webpki-roots` feature, no `.with_*_roots()` call), so it cannot validate any certificate — contradicting the documented "verify against the system trust roots" behaviour (Client.Rust-031). The galaxy page-token loop has a correct repeated-token guard. |
+| 5 | Security | No issues found in the registry/secret surface — `.cargo/config.toml` holds only the sparse index URL, no token; README puts the Bearer token in `~/.cargo/credentials.toml` (uncommitted). (See Client.Rust-031 for the strict-TLS validation gap, classified under error handling.) |
+| 6 | Performance & resource management | No issues found — `read_bulk` is now borrow-based (`&[S]`), the bench loop reuses `tags_ref` (Client.Rust-026 resolved). The walker clones the `GalaxyClient` channel handle per node, which is the intended cheap `Channel` clone. |
+| 7 | Design-document adherence | Issue found: `RustClientDesign.md` is not updated for the new Galaxy lazy-browse SDK surface (`browse` / `browse_children_raw` / `LazyBrowseNode` / `BrowseChildrenOptions`); CLAUDE.md requires docs to change with the source (Client.Rust-032). The TLS pin-only section pre-dates this diff but repeats the inaccurate "system trust roots" claim (cross-referenced from Client.Rust-031). |
+| 8 | Code organization & conventions | No issues found — Cargo metadata (name/version/license/repository/keywords/categories) is well-formed; `publish = ["dohertj2-gitea"]` on the library and `publish = false` on `mxgw-cli` is the right split. `license = "Proprietary"` is non-SPDX but cargo accepts it and it is a deliberate closed-source marker. |
+| 9 | Testing coverage | No issues found in the new surface — the walker has six unit tests (roots, expand, idempotency, NotFound, multi-page, filter-forwarding) and TLS has four. Gap noted: `tls_with_require_certificate_validation_does_not_short_circuit` connects to a dead address, so it only asserts the guard does not fire and never exercises a real handshake — which is why the no-trust-roots defect in Client.Rust-031 is not caught by a test. |
+| 10 | Documentation & comments | Issue found: the `alarm_feed_message_summary` / `alarm_feed_message_to_json` doc comments still say "three `payload` oneof cases" (`main.rs:1729,1755`) although the proto now has four; folded into Client.Rust-030's fix. The TLS doc inaccuracy is Client.Rust-031. |
+
 ## Findings

 ### Client.Rust-001
@@ -687,3 +706,59 @@ The third error (`BulkReplyKind` enum-variant-names) is also touched by the diff
 **Recommendation:** Re-apply Client.Rust-001 (add doc comments on `with_max_grpc_message_bytes` / `max_grpc_message_bytes` in `options.rs`), Client.Rust-002 (drop the `Bulk` suffix from `BulkReplyKind`'s variants so they become `AddItem` / `AdviseItem` / …, or add a narrowly-scoped `#[allow(clippy::enum_variant_names)]` with a reason comment), and Client.Rust-012 (replace `last_deploy.lock().unwrap().clone()` with `*last_deploy.lock().unwrap()` in `galaxy.rs:282`). Verify with `cargo clippy --workspace --all-targets -- -D warnings`. Consider adding a pre-commit / CI gate so the next reviewer never has to discover the regression by running clippy.

 **Resolution:** 2026-05-24 — Re-applied all three resolutions. `clients/rust/src/options.rs` now has `///` doc comments on `with_max_grpc_message_bytes` and `max_grpc_message_bytes`. `clients/rust/src/galaxy.rs:282` uses `*self.state.last_deploy.lock().unwrap()` instead of `.clone()`. `clients/rust/src/session.rs`'s `BulkReplyKind` variants are renamed to `AddItem` / `AdviseItem` / `RemoveItem` / `UnAdviseItem` / `Subscribe` / `Unsubscribe` (no shared `Bulk` suffix), with the call sites in `add_item_bulk` / `advise_item_bulk` / `remove_item_bulk` / `un_advise_item_bulk` / `subscribe_bulk` / `unsubscribe_bulk` updated accordingly. The sibling `BulkWriteReplyKind` already had non-suffix-sharing variants (`Write` / `Write2` / `WriteSecured` / `WriteSecured2`) and required no rename. `cargo clippy --workspace --all-targets -- -D warnings` is clean at HEAD.
+
+### Client.Rust-030
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `clients/rust/crates/mxgw-cli/src/main.rs:1731,1757` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:909-924`, added in commit `1d85db7`) |
+| Status | Resolved |
+
+**Description:** The `mxgw-cli` binary does not compile at HEAD `410acc9`. `cargo check --workspace`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo build --workspace`, and `cargo test --workspace` all fail with a hard `E0004` (non-exhaustive patterns), so the entire documented Rust build/test/clippy workflow that CLAUDE.md mandates is broken:
+
+```
+error[E0004]: non-exhaustive patterns: `&Some(...alarm_feed_message::Payload::ProviderStatus(_))` not covered
+    --> crates/mxgw-cli/src/main.rs:1731:11
+error[E0004]: non-exhaustive patterns: `&Some(...alarm_feed_message::Payload::ProviderStatus(_))` not covered
+    --> crates/mxgw-cli/src/main.rs:1757:11
+```
+
+The alarm-provider-fallback contract change (`1d85db7`, within the reviewed range) added a fourth `AlarmFeedMessage.payload` oneof arm — `AlarmProviderStatus provider_status = 4`. tonic-build regenerates the Rust enum with the new `ProviderStatus` variant, but `alarm_feed_message_summary` (`main.rs:1731`) and `alarm_feed_message_to_json` (`main.rs:1757`) each `match &message.payload` exhaustively over only `ActiveAlarm` / `SnapshotComplete` / `Transition` / `None` with no wildcard arm. Because they are exhaustive matches on a now-larger enum, the binary fails to compile rather than silently mishandling the new variant. The library crate (`zb-mom-ww-mxgateway-client`) itself compiles cleanly and all 32 of its tests pass; the break is confined to the CLI — but the CLI is the cross-language e2e matrix driver, so the whole `clients/rust` workspace is unbuildable and no Rust e2e smoke can run against the gateway at this commit. This is the alarm-surface gap the review request asked to check: the `ProviderStatus` payload is unhandled in the only place the Rust client renders the alarm feed.
+
+**Recommendation:** Add a `Some(alarm_feed_message::Payload::ProviderStatus(status))` arm to both `alarm_feed_message_summary` and `alarm_feed_message_to_json` (render the provider-status fields — mode, degraded/provenance, reference — consistent with how the .NET/Go/Java/Python CLIs serialise it so the cross-language parity matcher recognises the payload). While there, update the two doc comments that still say "three `payload` oneof cases" (`main.rs:1729,1755`) to four. Verify with `cargo clippy --workspace --all-targets -- -D warnings` and `cargo test --workspace`. Consider a CI gate so a contract change that adds a oneof arm cannot leave the Rust CLI unbuildable again.
+
+**Resolution:** 2026-06-15 — Root cause confirmed: the contract's new fourth `AlarmFeedMessage.payload` oneof arm (`AlarmProviderStatus provider_status`, proto fields `mode`/`degraded`/`reason`/`since`) left both `match &message.payload` blocks non-exhaustive (`E0004`). Added a `Some(alarm_feed_message::Payload::ProviderStatus(status))` arm to both `alarm_feed_message_summary` (`mode`/`degraded`/`reason` one-liner) and `alarm_feed_message_to_json` (a `providerStatus` object with `mode`/`degraded`/`reason`/`since`), added an `AlarmEnumName::provider_mode` enum-name helper consistent with the existing `condition_state`/`transition_kind` renderers, and updated the summary doc comment to "four payload oneof cases". No `_ => {}` wildcard. Test: `alarm_feed_provider_status_renders_in_summary_and_json` (in `crates/mxgw-cli/src/main.rs`). All four cargo commands now pass.
+
+### Client.Rust-031
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `clients/rust/src/options.rs:196-240` (`build_tls_config`); `clients/rust/Cargo.toml:40` (tonic features); docs: `clients/rust/src/options.rs:76-101`, `clients/rust/README.md` (TLS trust section), `clients/rust/crates/mxgw-cli/src/main.rs:429-431`, `clients/rust/RustClientDesign.md:202` |
+| Status | Resolved |
+
+**Description:** The new strict-verification escape hatch does not do what it documents. `build_tls_config` only configures trust roots when a CA file is pinned: with `require_certificate_validation(true)` and no `ca_file`, it returns a bare `ClientTlsConfig::new()` and never calls `.with_native_roots()`, `.with_webpki_roots()`, or `.with_enabled_roots()`. The crate also enables only `tonic` feature `tls-ring` (`Cargo.toml:40`) — neither `tls-native-roots` nor `tls-webpki-roots` is on, so even if the code wanted to enable system roots the methods are feature-gated out. A `ClientTlsConfig` with zero trust anchors rejects every server certificate during the rustls handshake, so the strict path cannot connect to any TLS gateway — not even one whose certificate is genuinely chained to a system root. Yet `with_require_certificate_validation`'s doc comment (`options.rs:80-89`), the README "TLS trust (pin-only)" section, the `--require-certificate-validation` CLI flag help (`main.rs:429-431`), and `RustClientDesign.md:202` all tell the user this option will "verify against the system trust roots." The documented behaviour is unreachable; the only working TLS path is CA pinning (`with_ca_file`).
+
+This is masked by the tests: `tls_with_require_certificate_validation_does_not_short_circuit` (`tests/tls.rs`) dials a dead address (`https://127.0.0.1:1`) and only asserts the no-CA guard error does *not* fire — it never reaches a handshake, so the absent-roots defect is invisible to the suite.
+
+**Recommendation:** Either (a) make the strict path actually load system roots — add the `tls-native-roots` (and/or `tls-webpki-roots`) feature to the `tonic` dependency and call `tls = tls.with_native_roots()` (or `.with_enabled_roots()`) in the `require_certificate_validation == true && ca_file.is_none()` branch of `build_tls_config` — and add a test that pins a self-signed cert as a CA and asserts a system-root-only connection to that same server is *rejected* (proving roots are actually consulted); or (b) if loading system roots is intentionally out of scope for v1, correct every doc site (the `with_require_certificate_validation` doc comment, README, CLI flag help, and `RustClientDesign.md`) to state that the strict flag does not currently enable any trust roots and that CA pinning is the only supported TLS path. Option (a) is the better fix because the flag otherwise has no working effect.
+
+**Resolution:** 2026-06-15 — Took option (a). Root cause confirmed: strict-on/no-CA returned a bare `ClientTlsConfig::new()` with zero trust anchors and the crate only enabled tonic `tls-ring`, so the documented "verify against the system trust roots" path could never validate any certificate. Added `tls-native-roots` to the `tonic` features in `Cargo.toml` and refactored `build_tls_config` to compute the trust posture via a new pure `tls_trust_decision` helper returning `TlsTrustDecision::{None,PinnedCa,SystemRoots,RejectNoCa}`; the `SystemRoots` branch now calls `ClientTlsConfig::with_native_roots()` so a cert chaining to an OS-trusted root validates. Corrected every doc site to state the strict flag verifies against OS roots (not a bare self-signed cert, which still needs `with_ca_file`): the `with_require_certificate_validation` doc comment and `build_tls_config` docs (`options.rs`), README "TLS trust" section, and `RustClientDesign.md` "Trust posture"; the CLI flag help was already accurate. TDD: added failing-first unit tests then the fix — `strict_without_ca_uses_system_roots`, `lenient_without_ca_is_rejected`, `pinned_ca_uses_pinned_trust`, `plaintext_needs_no_tls` (in `src/options.rs`). All four cargo commands pass.
+
+### Client.Rust-032
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `clients/rust/RustClientDesign.md`; surface in `clients/rust/src/galaxy.rs:281-379` |
+| Status | Resolved |
+
+**Description:** The diff under review adds substantial new public Galaxy SDK surface — `GalaxyClient::browse`, `GalaxyClient::browse_children_raw`, the `BrowseChildrenOptions` filter struct, and the `LazyBrowseNode` lazy walker (`object`, `has_children_hint`, `children`, `is_expanded`, `expand`) — none of which is described in `RustClientDesign.md`. The README was updated with a "Browsing lazily" / "High-level walker" section, but CLAUDE.md requires the design docs to change in the same change as the public API. A reader consulting the detailed design to understand the Galaxy client surface will not learn that lazy browsing, sibling pagination, the `child_has_children` hint, or the idempotent `expand` contract exist.
+
+**Recommendation:** Add a "Lazy browse" subsection to the Galaxy section of `RustClientDesign.md` enumerating `browse`, `browse_children_raw`, `BrowseChildrenOptions` (its filter fields and AND semantics), and `LazyBrowseNode` (the `Arc`-shared clone semantics, the idempotent single-RPC `expand`, the `has_children_hint`, and the internal paged `BrowseChildren` loop with its repeated-page-token guard). Cross-reference `docs/GalaxyRepository.md#browsechildren` for the wire-level request/filter semantics the README already links.
+
+**Resolution:** 2026-06-15 — Confirmed by inspection that `RustClientDesign.md` had no Galaxy library-API coverage at all. Added a new "Galaxy Repository" section documenting `browse`, `browse_children_raw`, the `BrowseChildrenOptions` filter struct (all six fields, AND combination semantics, `include_attributes` tri-state), and `LazyBrowseNode` (`Arc`-shared clone semantics, `has_children_hint`, the idempotent single-RPC `expand` under an async mutex with page size 500, and the repeated-page-token `Error::InvalidArgument` guard), cross-referencing `docs/GalaxyRepository.md#browsechildren`. Also noted the fourth alarm `provider_status` oneof case in the Alarms section while resolving Client.Rust-030. Doc-only change verified by inspection; design-doc anchor target confirmed present.
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Contracts` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -50,6 +50,43 @@ Python and Go descriptors. No fields renumbered or repurposed.
 | 9 | Testing coverage | No issues found — `ProtobufContractRoundTripTests` and `GatewayContractInfoTests` continue to pin the protocol version; new `QueryActiveAlarmsRequest` lacks a round-trip test but the RPC type is generated and exercised end-to-end by the gRPC client tests in each language. |
 | 10 | Documentation & comments | Issues found: Contracts-017 (the `rpc QueryActiveAlarms` comment block does not mention the `alarm_filter_prefix` request field). |

+#### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9` scoped to the contract changes since `42b0037`
+(`git diff 42b0037..HEAD -- src/ZB.MOM.WW.MxGateway.Contracts/`). The window
+contains two unrelated additive contract features. The brief targets the
+**alarm-provider fallback** surface in `mxaccess_gateway.proto`: the new
+`AlarmProviderMode` enum (`UNSPECIFIED=0`/`ALARMMGR=1`/`SUBTAG=2`), the
+`AlarmSubtagTarget` watch-list message, `AlarmFailoverConfig`, the three new
+`SubscribeAlarmsCommand` fields (`forced_mode=2`, `watch_list=3`, `failover=4`),
+the `OnAlarmProviderModeChangedEvent` (`MxEvent.body` oneof tag 25,
+`MxEventFamily=6`), the `degraded=14`/`source_provider=15` provenance fields on
+`OnAlarmTransitionEvent` **and** `ActiveAlarmSnapshot`, and the
+`AlarmFeedMessage.provider_status=4` oneof case carrying `AlarmProviderStatus`.
+The same window also adds the Galaxy `BrowseChildren` lazy-browse RPC
+(`galaxy_repository.proto`) and three XML doc comments on `GatewayContractInfo`
+constants — both outside the brief's alarm focus but checked for additive-only
+hygiene (clean). `Generated/*.cs` is build output and was not reviewed as
+hand-written. `mxaccess_worker.proto` is unchanged (the alarm additions live in
+the gateway proto the worker imports — matches the design doc's Superseded note).
+
+Verified against `docs/plans/2026-06-13-alarm-subtag-fallback-design.md`,
+`docs/plans/2026-06-15-forced-subtag-mode-fix.md`, and the worker/gateway source
+(`AlarmDispatcher.cs:213`, `MxAccessEventMapper.cs:151`, `GatewayAlarmMonitor.cs`).
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found. Field semantics are correct against source: `AlarmProviderStatus.degraded`/`OnAlarmTransitionEvent.degraded` track `mode == SUBTAG` (worker `AlarmDispatcher.cs:213` sets `SourceProvider = Degraded ? Subtag : Alarmmgr`; gateway `GatewayAlarmMonitor._providerDegraded = toMode == Subtag`). `OnAlarmProviderModeChangedEvent.hresult` "0 on failback" matches the Auto-mode failover/failback path that emits it; forced mode is seeded gateway-side and emits no worker event, so the comment is not contradicted. |
+| 2 | mxaccessgw conventions | No issues found. The subtag fallback synthesizes events **inside the worker** and marks every synthesized transition `degraded`, satisfying the CLAUDE.md "gateway forwards only worker-emitted events; synthesizing is an explicit opt-in non-parity mode" rule. `snake_case` fields, `PascalCase` messages, the `ALARM_PROVIDER_MODE_`/`MX_EVENT_FAMILY_` enum-prefix discipline, and the top-of-file wire-compatibility policy block (Contracts-005) are all honoured. Generated code regenerated, not hand-edited. |
+| 3 | Concurrency & thread safety | N/A — pure contract definitions plus a static constants class. |
+| 4 | Error handling & resilience | No issues found. The degraded/provider-status surface lets clients distinguish the lower-fidelity subtag feed from the authoritative alarmmgr feed; `AlarmProviderStatus` is emitted on stream open and every switch so late joiners learn the mode. |
+| 5 | Security | No issues found — none of the new fields carry credentials or secrets. `AlarmSubtagTarget` carries only item-address strings. |
+| 6 | Performance & resource management | No issues found. `repeated AlarmSubtagTarget watch_list` is sent once at subscribe time, not per-event; provenance fields are scalars. No hot-path bloat. |
+| 7 | Design-document adherence | No drift. The shipped contract matches `docs/plans/2026-06-13-alarm-subtag-fallback-design.md` (including its Superseded notes: additions in the gateway proto, not the worker proto). |
+| 8 | Code organization & conventions | No issues found. Every addition uses a new, contiguous field number — `SubscribeAlarmsCommand` 2-4, `MxEvent.body` 25, `MxEventFamily` 6, `OnAlarmTransitionEvent`/`ActiveAlarmSnapshot` 14-15, `AlarmFeedMessage.payload` 4 — with no reuse, renumbering, or type narrowing of any existing field. Enum zero-values are `UNSPECIFIED`. Additive-only invariant preserved. |
+| 9 | Testing coverage | Issues found: Contracts-018 — `ProtobufContractRoundTripTests` covers the new `AlarmProviderStatus` (via `AlarmFeedMessage`) and the `OnAlarmTransitionEvent` `degraded`/`source_provider` fields, but has no round-trip coverage for the `ActiveAlarmSnapshot` provenance fields, the `SubscribeAlarmsCommand` extensions (`forced_mode`/`watch_list`/`failover`), or `OnAlarmProviderModeChangedEvent`. |
+| 10 | Documentation & comments | Issues found: Contracts-019 — the `ActiveAlarmSnapshot.degraded`/`source_provider` fields carry no in-proto comment while the byte-identical fields on `OnAlarmTransitionEvent` are documented; and the `AlarmProviderMode` enum doc explains `UNSPECIFIED` only for the `forced_mode` use, not for the provenance (`source_provider`) reuse. |
+
 ## Findings

 ### Contracts-001
@@ -341,3 +378,33 @@ additive-only with no reuse, renumbering, or type narrowing.
 Re-review: no new findings. Open finding count remains 0. All seventeen
 recorded Contracts findings (Contracts-001..017) remain closed
 (Resolved / Won't Fix).
+
+### Contracts-018
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs:396` (`ActiveAlarmSnapshot_RoundTripsAllFields`) |
+| Status | Resolved |
+
+**Description:** The alarm-provider fallback feature added several new wire fields to `mxaccess_gateway.proto`. `ProtobufContractRoundTripTests` was extended with `AlarmFeedMessage_RoundTripsProviderStatus` (covers `AlarmProviderStatus` + the `provider_status` oneof case) and `Transition_RoundTripsDegradedProvenance` (covers `OnAlarmTransitionEvent.degraded`/`source_provider`), but three pieces of the new contract surface have no round-trip coverage: (a) `ActiveAlarmSnapshot.degraded` (14) / `source_provider` (15) — `ActiveAlarmSnapshot_RoundTripsAllFields` stops at `OperatorComment` (field 11) and never sets or asserts the two new provenance fields, so a future renumber/type change to them would not be caught; (b) the `SubscribeAlarmsCommand` extensions `forced_mode` (2), `watch_list` (3, `repeated AlarmSubtagTarget`), and `failover` (4, `AlarmFailoverConfig`) — no test exercises these, and the live `forced_mode` enum-drop concern that prompted the `2026-06-15-forced-subtag-mode-fix` investigation is exactly the kind of wire shape prior contract tests have been written to pin; (c) `OnAlarmProviderModeChangedEvent` (the `MxEvent.body` oneof tag 25 / `MxEventFamily=6` worker→gateway event). This is the same class of gap previously flagged for the bulk family (Contracts-007 / Contracts-010): new wire shapes shipped without round-trip pinning.
+
+**Recommendation:** Extend `ActiveAlarmSnapshot_RoundTripsAllFields` (or add a focused test) to set and assert `degraded = true` + `source_provider = AlarmProviderMode.Subtag`; add a round-trip test for `SubscribeAlarmsCommand` populating `forced_mode`, a `watch_list` entry (all six `AlarmSubtagTarget` string fields), and a `failover` `AlarmFailoverConfig`; and add a round-trip / `MxEvent` oneof-case test for `OnAlarmProviderModeChangedEvent` pinning `MxEvent.BodyCase == OnAlarmProviderModeChanged` for `MxEventFamily.OnAlarmProviderModeChanged`.
+
+**Resolution:** _(2026-06-15)_ Verified the three coverage gaps against the proto — `ActiveAlarmSnapshot.degraded`/`source_provider` (14/15), `SubscribeAlarmsCommand.forced_mode`/`watch_list`/`failover` (2/3/4), and the `MxEvent.body` oneof tag 25 / `MxEventFamily=6` `OnAlarmProviderModeChangedEvent` were all unpinned. Added three focused round-trip tests to `ProtobufContractRoundTripTests`: `ActiveAlarmSnapshot_RoundTripsDegradedProvenance` (sets/asserts `degraded = true` + `source_provider = AlarmProviderMode.Subtag`), `SubscribeAlarmsCommand_RoundTripsForcedModeWatchListAndFailover` (populates `forced_mode`, a `watch_list` entry with all six `AlarmSubtagTarget` string fields, and a `failover` `AlarmFailoverConfig`), and `MxEvent_RoundTripsOnAlarmProviderModeChangedBody` (pins `MxEvent.BodyCase == OnAlarmProviderModeChanged` + `Family == OnAlarmProviderModeChanged`). All fields round-trip — no contract bug found. The full `ProtobufContractRoundTrip` filter is 49/49 green.
+
+### Contracts-019
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:850-851` (`ActiveAlarmSnapshot`), `:318-324` (`AlarmProviderMode`) |
+| Status | Resolved |
+
+**Description:** Two in-proto documentation gaps on the new alarm-provider surface. (1) `OnAlarmTransitionEvent.degraded` (line 805-808) and `source_provider` (809-810) carry clear comments ("True when this transition came from the subtag-monitoring fallback … synthesized from data changes, reduced fidelity"; "Which provider produced this transition."), but the byte-identical `ActiveAlarmSnapshot.degraded` (850) and `source_provider` (851) are declared bare with no comment. The two messages model the same provenance concept and a reader of `ActiveAlarmSnapshot` alone gets no signal that a non-`UNSPECIFIED` `source_provider` plus `degraded = true` means the snapshot came from the lower-fidelity subtag source. (2) The `AlarmProviderMode` enum comment (318-319) documents the zero value only for one use site — "UNSPECIFIED on a SubscribeAlarmsCommand means auto: alarmmgr primary with subtag fallback" — but the same enum is reused as a provenance field on `OnAlarmTransitionEvent.source_provider`, `ActiveAlarmSnapshot.source_provider`, `OnAlarmProviderModeChangedEvent.mode`, and `AlarmProviderStatus.mode`. The worker always sets `source_provider` to `ALARMMGR` or `SUBTAG` (never `UNSPECIFIED`; `MxAccessEventMapper.cs:151` defaults to `Alarmmgr`, `AlarmDispatcher.cs:213` picks `Subtag`/`Alarmmgr`), so `UNSPECIFIED` as a provenance value has no defined meaning and the comment does not say so. The ProtobufStyleGuide rule "comment fields carrying MXAccess parity / non-obvious semantics" applies — this is a non-parity provenance marker.
+
+**Recommendation:** (1) Add comments to `ActiveAlarmSnapshot.degraded` / `source_provider` mirroring the wording already on `OnAlarmTransitionEvent` (or a one-line cross-reference). (2) Extend the `AlarmProviderMode` enum comment to note that as a `source_provider` / `mode` provenance value the field is always `ALARMMGR` or `SUBTAG` on the wire and `UNSPECIFIED` should be treated as "unknown / not yet determined", so the zero value is unambiguous at every use site. Comment-only changes; no wire-format impact.
+
+**Resolution:** _(2026-06-15)_ Confirmed both gaps in `mxaccess_gateway.proto`: `ActiveAlarmSnapshot.degraded`/`source_provider` (14/15) were bare while the byte-identical `OnAlarmTransitionEvent` fields were documented, and the `AlarmProviderMode` enum comment only explained `UNSPECIFIED` for the `forced_mode` use. (1) Added comments to `ActiveAlarmSnapshot.degraded`/`source_provider` mirroring the `OnAlarmTransitionEvent` wording (subtag-fallback / reduced-fidelity, always ALARMMGR or SUBTAG, never UNSPECIFIED). (2) Extended the `AlarmProviderMode` enum comment to distinguish its two use sites: as `forced_mode`, `UNSPECIFIED` = auto; as a provenance value (`OnAlarmTransitionEvent.source_provider`, `ActiveAlarmSnapshot.source_provider`, `OnAlarmProviderModeChangedEvent.mode`, `AlarmProviderStatus.mode`) the worker always emits ALARMMGR/SUBTAG and `UNSPECIFIED` should be read as "unknown / not yet determined". Comment-only changes; no wire-format impact. NOTE: on this dev box the `csharp` protoc generator DOES emit proto leading comments into `Generated/MxaccessGateway.cs` `<summary>` XML doc (contrary to the brief's assumption), so the build regenerated `Generated/MxaccessGateway.cs` with the new doc comments only — diff is `///`-comment lines exclusively, zero code/wire/type changes. `dotnet build -f net10.0` succeeds with 0 warnings / 0 errors.
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.IntegrationTests` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -14,6 +14,34 @@
 A comprehensive review completes every category, recording "No issues found" where
 a category produced nothing rather than leaving it blank.

+### 2026-06-15 re-review (commit `410acc9`)
+
+Scope: `git diff 42b0037..HEAD -- src/ZB.MOM.WW.MxGateway.IntegrationTests/`
+(5 files). The substantive change is the `DashboardLdapLiveTests` cutover to the
+shared `ZB.MOM.WW.Auth.Ldap.LdapAuthService` + `DashboardGroupRoleMapper`
+(matching the production `DashboardAuthenticator` ctor split); plus the
+`ResolveRepositoryRoot` `stopBoundary` parameter and its new regression test
+(IntegrationTests-025 resolution), and XML-doc backfill on
+`LiveLdapFactAttribute` / `WorkerLiveMxAccessSmokeTests`. NOTE: the review
+brief's "live alarm-subtag smoke test(s)" do not exist in this diff — no new
+alarm-subtag tests landed here. Instead the in-window Server alarm-monitor
+evolution (`ebf1d95`/`9208225`/`410acc9`) changed `GatewayAlarmMonitor`'s
+constructor without updating its IntegrationTests caller, leaving the whole
+module non-compiling (IntegrationTests-026).
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issue found: IntegrationTests-026 (the entire IntegrationTests project fails to compile at HEAD — `WorkerLiveMxAccessSmokeTests` constructs `GatewayAlarmMonitor` with the stale 3-arg form `(sessionManager, options, logger)` while the production ctor now requires 5 args `(ISessionManager, IAlarmWatchListResolver, GatewayMetrics, IOptions<GatewayOptions>, ILogger)`; verified by `dotnet build` → CS7036). |
+| 2 | mxaccessgw conventions | No issues found. Live opt-in gating, `[Collection]`/`[Trait]` discipline, "no synthesized events", and the credential-redaction contract for the LDAP failure-path assertions are all preserved; the cutover keeps the existing skip-by-default behaviour. |
+| 3 | Concurrency & thread safety | No issues found in this diff. |
+| 4 | Error handling & resilience | No issues found. The `ServerUnreachable` test still asserts the connect failure is absorbed into a `Fail` result; the fail-closed contract now lives in the shared `LdapAuthService` and the test exercises it via `Port = 1`. |
+| 5 | Security | No issues found. The wrong-password / unknown-user / unreachable tests still assert no credential leak into `FailureMessage`; the cutover adds no new credential surface and writes no secrets to evidence/probe logs. |
+| 6 | Performance & resource management | No issues found. |
+| 7 | Design-document adherence | Issue found: IntegrationTests-028 (the live test hand-rolls a field-by-field `LibraryLdapOptions` from the gateway shadow `LdapOptions` defaults instead of binding `MxGateway:Ldap` the way production's `AddZbLdapAuth(configuration, "MxGateway:Ldap")` does, so the live test no longer exercises the production option-binding path and silently omits `ConnectionTimeoutMs` / `ServerCertificateValidationCallback`). |
+| 8 | Code organization & conventions | Issue found: IntegrationTests-027 (`DashboardLdapLiveTests` directly consumes `LdapAuthService` / `LdapOptions` from `ZB.MOM.WW.Auth.Ldap` but the IntegrationTests `.csproj` has no direct `PackageReference` — it compiles only via transitive flow through the Server `ProjectReference`). |
+| 9 | Testing coverage | No issues found beyond IntegrationTests-026 — the role-claim and stop-boundary assertions added in this window strengthen coverage; but the module cannot build, so none of the IntegrationTests run until IntegrationTests-026 is fixed. |
+| 10 | Documentation & comments | Issue found: IntegrationTests-029 (`docs/GatewayTesting.md` "Live LDAP" still describes the old in-`DashboardAuthenticator` branches — "rejected by the candidate bind", "yields no candidate" — that the library cutover moved into the shared `LdapAuthService`; the test comments were updated in this diff but the doc prose was not, contrary to CLAUDE.md's same-commit doc rule). |
+
 ### 2026-05-20 re-review (commit `a020350`)

 | # | Category | Result |
@@ -506,3 +534,77 @@ The current dev box layout (`C:\Users\dohertj2\Desktop\mxaccessgw`) is safe beca
 **Recommendation:** Isolate the walker from any ambient ancestor by either (a) constructing an `isolatedRoot` directly under a drive root and pointing the walker at a chain entirely under it (e.g. create `<isolatedRoot>\level1\level2\level3` and start the walk at `level3`, then assert the throw — the walker stops at the drive root regardless of what is on it), (b) refactoring `ResolveRepositoryRoot` to accept an injectable `stopBoundary` parameter for tests and pass `isolatedRoot` as the boundary, or (c) replacing the `Assert.Throws` shape with an explicit upward-walk check that the test owns. Option (a) is the smallest change: prepend a sentinel — e.g. create a dummy `<isolatedRoot>\sentinel-no-markers` and assert nothing about Temp ancestors — and pass the test only when the walker reaches that sentinel without finding a marker. The current shape is acceptable on the documented dev box but should not be the sole regression coverage for IntegrationTests-022.

 **Resolution:** Resolved 2026-05-24 — Took option (b) (inject a stop-boundary) because option (a) does not actually solve the leak: a sentinel chain under `Path.GetTempPath()` still leaves the walker free to ascend past it into Temp / AppData / Users / C:\, so any ambient ancestor with `src/` + `.git`/`.sln`/`.slnx` still wins. Added an optional `stopBoundary` parameter to `IntegrationTestEnvironment.ResolveRepositoryRoot(string startDirectory, string? stopBoundary = null)`. When supplied, the walker checks the boundary for markers and then stops, refusing to ascend past it; production callers (the `MXGATEWAY_LIVE_MXACCESS_WORKER_EXE` resolution path) continue to pass `null` so the walk to drive-root behavior is unchanged. Updated both existing tests (`ResolveRepositoryRoot_AcceptsGitWorktreeFile` and `ResolveRepositoryRoot_NoMarkers_ThrowsInvalidOperationExceptionNamingStartAndMarkers`) to pass their owned temp directory as the boundary, sealing the walker inside a chain the test fully controls. Added a new regression test `ResolveRepositoryRoot_StopBoundary_IsolatesWalkerFromAmbientAncestorMarkers` that deliberately constructs an outer marker-bearing ancestor (`outerRoot/src` + `outerRoot/.git`), an inner boundary, and an isolated start beneath the boundary; first asserts that without the boundary the walker leaks up to `outerRoot` (the precise IntegrationTests-025 failure mode), then asserts that *with* the boundary the same call throws — proving the boundary is the load-bearing isolation. TDD red/green confirmed: the new regression test fails against the pre-fix walker (`Assert.Throws() Failure: No exception was thrown`) and passes once the boundary handling is restored. Re-ran the full `IntegrationTestEnvironmentTests` slice with `TMP` / `TEMP` redirected under a deliberately constructed `<temp>\fake-repo-ancestor` directory carrying `src/` and a `.git` file — the original flake repro from the finding — and confirmed all 5 tests pass (the same redirection produced `Assert.Throws() Failure` on the pre-fix code). Build: 0 warnings / 0 errors.
+
+### IntegrationTests-026
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Correctness & logic bugs |
+| Location | `src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:1098-1101`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:55-60` |
+| Status | Resolved |
+
+**Description:** The entire IntegrationTests project fails to compile at HEAD (`410acc9`). `GatewayServiceFixture` (in `WorkerLiveMxAccessSmokeTests.cs`) constructs the `GatewayAlarmMonitor` it passes into `MxAccessGatewayService` with the stale three-argument form:
+
+```csharp
+new ZB.MOM.WW.MxGateway.Server.Alarms.GatewayAlarmMonitor(
+    sessionManager,
+    options,
+    _loggerFactory.CreateLogger<...GatewayAlarmMonitor>())
+```
+
+but the production constructor (evolved in-window by `ebf1d95` "monitor resolves watch-list, sends ForcedMode/failover, reflects provider mode into feed + metrics", with later refinements in `9208225` and `410acc9`) now requires **five** parameters: `GatewayAlarmMonitor(ISessionManager sessionManager, IAlarmWatchListResolver watchListResolver, GatewayMetrics metrics, IOptions<GatewayOptions> options, ILogger<GatewayAlarmMonitor> logger)`. `dotnet build src/ZB.MOM.WW.MxGateway.IntegrationTests/...` fails with `CS7036: There is no argument given that corresponds to the required parameter 'options'`. Because this is the only `MxAccessGatewayService` assembly site in the fixture, the whole module — every live opt-in test *and* the non-live `IntegrationTestEnvironmentTests` — cannot build or run. This is a CLAUDE.md "Source Update Workflow" violation: a cross-component Server alarm-monitor change was not propagated to its IntegrationTests caller in the same commit, and "build each affected component" was not honored for the IntegrationTests project. It also silently masks the verification basis for IntegrationTests-022..025's "build is green" resolution claims at this HEAD.
+
+**Recommendation:** Update the `GatewayAlarmMonitor` construction in `GatewayServiceFixture` to the current 5-arg signature: supply an `IAlarmWatchListResolver` (a minimal test stub returning an empty/representative watch list, or the production resolver if cheap to construct), the existing `_metrics` (`GatewayMetrics`), the existing `options` wrapped as `IOptions<GatewayOptions>` (e.g. `Options.Create(...)`), and the logger. Then run `dotnet build src/ZB.MOM.WW.MxGateway.IntegrationTests/...` to confirm 0 errors and `dotnet test ... --filter FullyQualifiedName~IntegrationTestEnvironmentTests` to confirm the non-live tests pass and the live tests still skip cleanly when the env vars are unset. Add a build of the IntegrationTests project to the verification step whenever `GatewayAlarmMonitor` / `MxAccessGatewayService` constructors change.
+
+**Resolution:** Resolved 2026-06-15: Confirmed the project failed to build at HEAD (CS7036 on the stale 3-arg `GatewayAlarmMonitor` ctor call in `GatewayServiceFixture`). Updated the construction to the current 5-arg signature — added a new `TestSupport/EmptyAlarmWatchListResolver` singleton stub (`IAlarmWatchListResolver` returning an empty watch-list, avoiding the production resolver's `IGalaxyRepository` dependency), and passed the fixture's existing `_metrics` (`GatewayMetrics`) and `options` (`IOptions<GatewayOptions>`). `dotnet build` now succeeds with 0 errors/warnings; non-live tests pass (5) and all 15 live tests skip cleanly with the env vars unset.
+
+### IntegrationTests-027
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/ZB.MOM.WW.MxGateway.IntegrationTests/ZB.MOM.WW.MxGateway.IntegrationTests.csproj`, `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:4-5,134` |
+| Status | Resolved |
+
+**Description:** After the cutover, `DashboardLdapLiveTests` directly consumes `ZB.MOM.WW.Auth.Ldap.LdapAuthService` and `ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions` (`using ZB.MOM.WW.Auth.Ldap; using ZB.MOM.WW.Auth.Abstractions.Ldap;` and `new LdapAuthService(ldapOptions)`). But the IntegrationTests `.csproj` declares no direct `PackageReference` to `ZB.MOM.WW.Auth.Ldap` or `ZB.MOM.WW.Auth.Abstractions` — it has only `ProjectReference`s to Contracts and Server. It compiles solely because the Server's `PackageReference`s to those packages flow transitively (the Server csproj sets no `PrivateAssets`). A project that directly references a library's public types should declare a direct dependency on it; the current shape means the build silently depends on the Server never marking those packages `PrivateAssets="compile"` and on the transitive compile-asset flow staying enabled. If either changes, the IntegrationTests build breaks with a confusing CS0246 far from the cause.
+
+**Recommendation:** Add explicit `<PackageReference Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.2" />` and `<PackageReference Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.2" />` (matching the Server's pinned versions, ideally via a shared `Directory.Packages.props` if central package management is in use) to the IntegrationTests project so its direct use of those types is backed by a direct dependency.
+
+**Resolution:** Resolved 2026-06-15: Confirmed the csproj had only `ProjectReference`s and pulled `LdapAuthService`/`LdapOptions` transitively. Added direct `PackageReference`s `ZB.MOM.WW.Auth.Abstractions` and `ZB.MOM.WW.Auth.Ldap` at `0.1.2` (matching the Server's pinned versions; no central package management exists in this repo). Build remains clean. (The IntegrationTests-028 fix also added `Microsoft.Extensions.Configuration.Json`/`.Binder` at `10.0.7`, pinned to the resolved transitive version to avoid an NU1605 downgrade.)
+
+### IntegrationTests-028
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Design-document adherence |
+| Location | `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:120-161`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs:35` |
+| Status | Resolved |
+
+**Description:** Production wires the shared LDAP provider by binding the `MxGateway:Ldap` configuration section straight onto the shared `LdapOptions` via `AddZbLdapAuth(configuration, "MxGateway:Ldap")`. The live test instead hand-rolls a `LibraryLdapOptions` instance by copying the eleven fields of the gateway *shadow* `LdapOptions` defaults (the `LibraryOptions()` helper). Two consequences:
+
+1. The shared `LdapOptions` actually exposes **thirteen** settable properties — the hand-copy omits `ConnectionTimeoutMs` and `ServerCertificateValidationCallback` (verified by reflecting `ZB.MOM.WW.Auth.Abstractions` 0.1.2). `ConnectionTimeoutMs` has a non-zero default and directly governs the `AuthenticateAsync_ServerUnreachable_FailsWithoutThrowing` (`Port = 1`) test's timing, so the live test exercises the *shared default* timeout, not whatever an operator (or the gateway config) would set — diverging from the production-bound value.
+2. It adds a third manual copy of the shadow→shared field mapping on top of the documented "Review C2 DRIFT WARNING" seam in `Server/Configuration/LdapOptions.cs`. A field added to the shared type is silently dropped by this test until someone remembers to extend `LibraryOptions()`.
+
+The prior `DashboardAuthenticator` ctor took `IOptions<GatewayOptions>`, so the old test shared the same options object production used; the cutover lost that fidelity. CLAUDE.md treats the live tests as the parity check against the real seeded directory — they should bind options the way production does.
+
+**Recommendation:** Have the test build the shared `LdapOptions` the same way production does — bind it from the `MxGateway:Ldap` section (e.g. load the gateway `appsettings.json` / a minimal in-memory config and call the same `AddZbLdapAuth` binding path, or resolve the bound `IOptions<LdapOptions>` from a DI container that ran `AddZbLdapAuth`). At minimum, document why the two extra shared fields are intentionally left at their defaults, and add `ConnectionTimeoutMs` to the copy so the unreachable-server test's timeout matches production. Prefer eliminating the hand-copy so the shadow-drift surface does not grow.
+
+**Resolution:** Resolved 2026-06-15: Confirmed by reflecting `ZB.MOM.WW.Auth.Abstractions` 0.1.2 that the shared `LdapOptions` exposes 13 settable properties while the hand-copy populated only 11 (omitting `ConnectionTimeoutMs` and `ServerCertificateValidationCallback`). Eliminated the field-by-field hand-copy: `LibraryOptions()` now binds the real `MxGateway:Ldap` section from the Server's `appsettings.json` (resolved via `IntegrationTestEnvironment.ResolveRepositoryRoot`) onto the shared `LdapOptions` with `configuration.GetSection("MxGateway:Ldap").Get<LdapOptions>()` — the same section/binding path production's `AddZbLdapAuth(configuration, "MxGateway:Ldap")` uses. Verified the bind yields `ConnectionTimeoutMs=10000` (the shared default the unreachable-server test relies on) and the dev directory connection (localhost:3893, Transport=None, AllowInsecure). A new shared field is now picked up automatically rather than silently dropped.
+
+### IntegrationTests-029
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `docs/GatewayTesting.md:218-224` |
+| Status | Resolved |
+
+**Description:** The "Live LDAP" section of `docs/GatewayTesting.md` still describes the failure branches in terms of the old `DashboardAuthenticator` internals: "`admin` with a wrong password is rejected by the **candidate bind**" and "an unknown username yields **no candidate**". After the cutover in this diff, the bind/search mechanics (and therefore the "candidate bind" / "candidate is null" branches) live in the shared `LdapAuthService`, not in `DashboardAuthenticator` — which is exactly why the test comments in `DashboardLdapLiveTests.cs` were reworded in this same diff from "Exercises the `LdapException` branch" / "the `candidate is null` branch" to "user-bind-failure branch" / "user-not-found branch". The doc prose was not updated to match. CLAUDE.md requires docs that describe security/auth behavior to change in the same commit as the source; the comments moved but the doc did not, leaving the doc describing branches that no longer exist in `DashboardAuthenticator`.
+
+**Recommendation:** Reword the `docs/GatewayTesting.md` "Live LDAP" failure-branch sentences to describe observable behavior without referencing the now-internal "candidate bind" mechanics (e.g. "a wrong password is rejected without leaking the password", "an unknown username fails authentication"), and note that bind/search is delegated to the shared `ZB.MOM.WW.Auth.Ldap` provider so the prose stays accurate after the cutover.
+
+**Resolution:** Resolved 2026-06-15: Reworded the "Live LDAP" failure-branch prose to describe observable behavior ("fails authentication without leaking the password", "an unknown username fails authentication") instead of the now-internal "candidate bind" / "no candidate" mechanics, and added a sentence noting `DashboardAuthenticator` delegates the bind/search to the shared `ZB.MOM.WW.Auth.Ldap` provider (`LdapAuthService`) and only maps groups to roles — matching the in-source test-comment cutover. Verified by inspection.
@@ -10,17 +10,17 @@ Each module's `findings.md` is the source of truth; this file is generated from

 | Module | Reviewer | Date | Commit | Status | Open | Total |
 |---|---|---|---|---|---|---|
-| [Client.Dotnet](Client.Dotnet/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 21 |
-| [Client.Go](Client.Go/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 27 |
-| [Client.Java](Client.Java/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 36 |
-| [Client.Python](Client.Python/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 26 |
-| [Client.Rust](Client.Rust/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 29 |
-| [Contracts](Contracts/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 17 |
-| [IntegrationTests](IntegrationTests/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 25 |
-| [Server](Server/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 50 |
-| [Tests](Tests/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 31 |
-| [Worker](Worker/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 25 |
-| [Worker.Tests](Worker.Tests/findings.md) | Claude Code | 2026-05-24 | `42b0037` | Re-reviewed | 0 | 30 |
+| [Client.Dotnet](Client.Dotnet/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 25 |
+| [Client.Go](Client.Go/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 29 |
+| [Client.Java](Client.Java/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 39 |
+| [Client.Python](Client.Python/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 31 |
+| [Client.Rust](Client.Rust/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 32 |
+| [Contracts](Contracts/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 19 |
+| [IntegrationTests](IntegrationTests/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 29 |
+| [Server](Server/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 53 |
+| [Tests](Tests/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 35 |
+| [Worker](Worker/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 28 |
+| [Worker.Tests](Worker.Tests/findings.md) | Claude Code | 2026-06-15 | `410acc9` | Re-reviewed | 0 | 33 |

 ## Pending findings

@@ -38,6 +38,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Go-001 | High | Resolved | Correctness & logic bugs | `clients/go/mxgateway/errors.go:88-93`, `clients/go/mxgateway/errors.go:117-128` |
 | Client.Java-013 | High | Resolved | Testing coverage | `clients/java/mxgateway-cli/src/test/java/com/dohertylan/mxgateway/cli/MxGatewayCliTests.java:212-304`, `clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java:1214-1244` |
 | Client.Java-032 | High | Resolved | Documentation & comments | `clients/java/README.md:182-183` |
+| Client.Java-039 | High | Resolved | Correctness & logic bugs | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1699` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto`, `AlarmFeedMessage.payload` provider-status arm added in commit `1d85db7`) |
 | Client.Python-018 | High | Resolved | Code organization & conventions | `clients/python/pyproject.toml:11` |
 | Client.Python-022 | High | Resolved | Documentation & comments | `clients/python/README.md:201-202`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:389-420` |
 | Client.Rust-001 | High | Resolved | mxaccessgw conventions | `clients/rust/src/options.rs:98,143` |
@@ -46,8 +47,10 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Rust-012 | High | Resolved | mxaccessgw conventions | `clients/rust/src/galaxy.rs:282` |
 | Client.Rust-013 | High | Resolved | mxaccessgw conventions | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:414-424` (origin); `clients/rust/src/generated.rs:11-31` (suppression site) |
 | Client.Rust-029 | High | Resolved | mxaccessgw conventions | `clients/rust/src/options.rs:98,143`; `clients/rust/src/galaxy.rs:282`; `clients/rust/src/session.rs:664-671` |
+| Client.Rust-030 | High | Resolved | Correctness & logic bugs | `clients/rust/crates/mxgw-cli/src/main.rs:1731,1757` (origin: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:909-924`, added in commit `1d85db7`) |
 | IntegrationTests-001 | High | Resolved | Design-document adherence | `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs:7`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs` |
 | IntegrationTests-002 | High | Resolved | Design-document adherence | `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:13`, `src/MxGateway.Server/Configuration/LdapOptions.cs:27` |
+| IntegrationTests-026 | High | Resolved | Correctness & logic bugs | `src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:1098-1101`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:55-60` |
 | Server-003 | High | Resolved | Security | `src/MxGateway.Server/Dashboard/DashboardAuthorizationHandler.cs:39,54-59`, `src/MxGateway.Server/Dashboard/DashboardAuthenticator.cs:236-258` |
 | Server-017 | High | Resolved | Security | `src/MxGateway.Server/Security/Authorization/GatewayGrpcScopeResolver.cs:13-27`, `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:173-247`, `docs/Authorization.md:108-110` |
 | Tests-001 | High | Resolved | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:483-489` |
@@ -55,16 +58,19 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker-001 | High | Resolved | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/WnWrapAlarmConsumer.cs:204-207` |
 | Worker-002 | High | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:545-549` |
 | Worker-003 | High | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:399-403`, `:416-419` |
+| Worker-026 | High | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs:289-338`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs:307-320` |
 | Worker.Tests-001 | High | Resolved | Testing coverage | `src/MxGateway.Worker.Tests/Sta/` (no `StaMessagePumpTests.cs`) |
 | Worker.Tests-002 | High | Resolved | Testing coverage | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs`, `src/MxGateway.Worker.Tests/MxAccess/MxAccessEventMapperTests.cs` |
 | Client.Dotnet-001 | Medium | Resolved | Error handling & resilience | `clients/dotnet/MxGateway.Client/GrpcMxGatewayClientTransport.cs:190-199`, `clients/dotnet/MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs:131-140` |
 | Client.Dotnet-002 | Medium | Resolved | Testing coverage | `clients/dotnet/MxGateway.Client.Tests/FakeGatewayTransport.cs:145-148`, `clients/dotnet/MxGateway.Client.Tests/MxGatewayClientSessionTests.cs:236-256` |
 | Client.Dotnet-003 | Medium | Resolved | Concurrency & thread safety | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:659-663`, `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:230-240` |
 | Client.Dotnet-018 | Medium | Resolved | Documentation & comments | `clients/dotnet/README.md:137-138` |
+| Client.Dotnet-022 | Medium | Resolved | mxaccessgw conventions | `clients/dotnet/Directory.Build.props:1-21` |
 | Client.Go-002 | Medium | Resolved | Error handling & resilience | `clients/go/mxgateway/session.go:440-516` |
 | Client.Go-003 | Medium | Resolved | Correctness & logic bugs | `clients/go/cmd/mxgw-go/main.go:517-532` |
 | Client.Go-022 | Medium | Resolved | Code organization & conventions | `clients/go/cmd/mxgw-go/main.go:398-412,417-519` |
 | Client.Go-023 | Medium | Resolved | Concurrency & thread safety | `clients/go/cmd/mxgw-go/main.go:604-606,616-632` |
+| Client.Go-028 | Medium | Resolved | Correctness & logic bugs | `scripts/tag-go-module.ps1:42-46` |
 | Client.Java-001 | Medium | Resolved | Security | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySecrets.java:30-32` |
 | Client.Java-002 | Medium | Resolved | Concurrency & thread safety | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxEventStream.java:31,66-92` |
 | Client.Java-003 | Medium | Resolved | mxaccessgw conventions | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:119-140` |
@@ -77,12 +83,15 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Java-028 | Medium | Resolved | Documentation & comments | `clients/java/JavaClientDesign.md:23-27` |
 | Client.Java-033 | Medium | Resolved | Correctness & logic bugs | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1078-1098` |
 | Client.Java-034 | Medium | Resolved | Correctness & logic bugs | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:182-198` |
+| Client.Java-037 | Medium | Resolved | Documentation & comments | `clients/java/README.md:138-149` |
 | Client.Python-003 | Medium | Resolved | Error handling & resilience | `clients/python/src/mxgateway/client.py:125-137,155-173` |
 | Client.Python-005 | Medium | Resolved | Performance & resource management | `clients/python/src/mxgateway/galaxy.py:117-140` |
 | Client.Python-009 | Medium | Resolved | Testing coverage | `clients/python/tests/` |
 | Client.Python-013 | Medium | Resolved | Security | `clients/python/src/mxgateway_cli/commands.py:757-762` |
 | Client.Python-023 | Medium | Resolved | Security | `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:901-906` |
 | Client.Python-024 | Medium | Resolved | Code organization & conventions | `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:13,48-119` |
+| Client.Python-027 | Medium | Resolved | Security | `clients/python/src/zb_mom_ww_mxgateway/client.py:36-54`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:47-66`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:165-172,918-930` |
+| Client.Python-028 | Medium | Resolved | Error handling & resilience | `clients/python/src/zb_mom_ww_mxgateway/options.py:120-130`, `clients/python/src/zb_mom_ww_mxgateway/client.py:59`, `clients/python/src/zb_mom_ww_mxgateway/galaxy.py:71` |
 | Client.Rust-005 | Medium | Resolved | Correctness & logic bugs | `clients/rust/src/session.rs:489-520` |
 | Client.Rust-006 | Medium | Resolved | Error handling & resilience | `clients/rust/src/session.rs:531-555` |
 | Client.Rust-015 | Medium | Resolved | Error handling & resilience | `clients/rust/crates/mxgw-cli/src/main.rs:1053-1070` |
@@ -90,6 +99,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Rust-018 | Medium | Resolved | Error handling & resilience | `clients/rust/crates/mxgw-cli/src/main.rs:1098-1170`; `scripts/bench-read-bulk.ps1:347-365`; siblings: `clients/go/cmd/mxgw-go/main.go:600-648`, `clients/python/src/mxgateway_cli/commands.py:614-662`, `clients/dotnet/MxGateway.Client.Cli/MxGatewayClientCli.cs:685-770`, `clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java:855-940` |
 | Client.Rust-022 | Medium | Resolved | Correctness & logic bugs | `clients/rust/src/session.rs:369-391,403-420,427-444,452-469,476-493,631-696,706-724` |
 | Client.Rust-024 | Medium | Resolved | Testing coverage | `clients/rust/tests/client_behavior.rs:405-415`; `clients/rust/src/session.rs:369-493`; `clients/rust/src/client.rs:265-291`; `clients/rust/crates/mxgw-cli/src/main.rs:1310-1505` |
+| Client.Rust-031 | Medium | Resolved | Error handling & resilience | `clients/rust/src/options.rs:196-240` (`build_tls_config`); `clients/rust/Cargo.toml:40` (tonic features); docs: `clients/rust/src/options.rs:76-101`, `clients/rust/README.md` (TLS trust section), `clients/rust/crates/mxgw-cli/src/main.rs:429-431`, `clients/rust/RustClientDesign.md:202` |
 | Contracts-002 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:384-385`, `:95` |
 | Contracts-009 | Medium | Resolved | Design-document adherence | `docs/Contracts.md:13-24` |
 | IntegrationTests-003 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:89-97` |
@@ -113,6 +123,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Server-033 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Server/Galaxy/GalaxyHierarchyCache.cs:265-323` (`TryRestoreFromDiskAsync`), `:84-99` (`_firstLoad` / `WaitForFirstLoadAsync`); `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:141-163` (`WaitForCacheBootstrap`) |
 | Server-038 | Medium | Resolved | Security | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Hubs/EventsHub.cs:23-44` |
 | Server-044 | Medium | Resolved | Correctness & logic bugs | `src/ZB.MOM.WW.MxGateway.Server/Sessions/SessionManager.cs:216-254` |
+| Server-051 | Medium | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:64-78` |
 | Tests-003 | Medium | Resolved | Performance & resource management | `src/MxGateway.Tests/Security/Authentication/SqliteAuthStoreTests.cs:170-176`, `src/MxGateway.Tests/Security/Authentication/ApiKeyAdminCliRunnerTests.cs:252-258` |
 | Tests-004 | Medium | Resolved | Testing coverage | `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs` |
 | Tests-005 | Medium | Resolved | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/EventStreamServiceTests.cs:239-261`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs` |
@@ -122,6 +133,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Tests-020 | Medium | Resolved | Testing coverage | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceConstraintTests.cs:275-347`, `src/MxGateway.Server/Grpc/MxAccessGatewayService.cs:803-829` |
 | Tests-026 | Medium | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Grpc/EventStreamServiceTests.cs`, `src/ZB.MOM.WW.MxGateway.Server/Grpc/EventStreamService.cs:123-126` |
 | Tests-027 | Medium | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:199-240`, `src/ZB.MOM.WW.MxGateway.Server/Metrics/GatewayMetrics.cs:8,73,246-251` |
+| Tests-032 | Medium | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:435-441`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs` |
 | Worker-004 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:565-588` |
 | Worker-005 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:205-258` (production alarm poll loop) |
 | Worker-006 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:117-124`, `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:386-491` |
@@ -130,6 +142,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker-016 | Medium | Resolved | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:261-265` |
 | Worker-017 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Worker/Sta/StaRuntime.cs:280-288`, `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:602-631` |
 | Worker-023 | Medium | Resolved | Error handling & resilience | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:610-668`, `src/MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs:124-153` |
+| Worker-027 | Medium | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SyntheticAlarmGuid.cs:38-40` |
 | Worker.Tests-003 | Medium | Resolved | Concurrency & thread safety | `src/MxGateway.Worker.Tests/Sta/StaRuntimeTests.cs:46-48` |
 | Worker.Tests-004 | Medium | Resolved | Concurrency & thread safety | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:281-329` |
 | Worker.Tests-005 | Medium | Resolved | Performance & resource management | `src/MxGateway.Worker.Tests/Ipc/WorkerFrameProtocolTests.cs:20-31,103-105`, `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:28-31` |
@@ -138,6 +151,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker.Tests-016 | Medium | Resolved | Code organization & conventions | `src/MxGateway.Worker.Tests/MxAccess/AlarmCommandExecutorTests.cs:317-393` |
 | Worker.Tests-017 | Medium | Resolved | Testing coverage | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs` |
 | Worker.Tests-018 | Medium | Resolved | Correctness & logic bugs | `src/MxGateway.Worker.Tests/MxAccess/MxAccessLiveComCreationTests.cs:18-31, 35-73, 75-145, 148-220, 222-342` |
+| Worker.Tests-031 | Medium | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` (all `FailoverSettings` constructions) |
 | Client.Dotnet-004 | Low | Resolved | Error handling & resilience | `clients/dotnet/MxGateway.Client/MxGatewayClient.cs:283-294`, `clients/dotnet/MxGateway.Client/GalaxyRepositoryClient.cs:392-403` |
 | Client.Dotnet-005 | Low | Resolved | Correctness & logic bugs | `clients/dotnet/MxGateway.Client/MxGatewaySession.cs:82,124,175` |
 | Client.Dotnet-006 | Low | Resolved | Code organization & conventions | `clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs:50`, `clients/dotnet/MxGateway.Client/MxGatewayClientContractInfo.cs:10-14` |
@@ -155,6 +169,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Dotnet-019 | Low | Resolved | Correctness & logic bugs | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:745` |
 | Client.Dotnet-020 | Low | Resolved | Error handling & resilience | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:792-810`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:774-780` |
 | Client.Dotnet-021 | Low | Resolved | Correctness & logic bugs | `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:487`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs:715` |
+| Client.Dotnet-023 | Low | Resolved | Code organization & conventions | `clients/dotnet/Directory.Build.props:17`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/IMxGatewayCliClient.cs:6`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/*.cs` |
+| Client.Dotnet-024 | Low | Resolved | Code organization & conventions | `clients/dotnet/Directory.Build.props:12`, `clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj:19-24` |
+| Client.Dotnet-025 | Low | Resolved | Concurrency & thread safety | `clients/dotnet/ZB.MOM.WW.MxGateway.Client/LazyBrowseNode.cs:38,41,54,82,94` |
 | Client.Go-004 | Low | Resolved | mxaccessgw conventions | `clients/go/mxgateway/alarms_test.go:153-154`, `clients/go/mxgateway/galaxy_test.go:58-59` |
 | Client.Go-005 | Low | Resolved | Design-document adherence | `clients/go/mxgateway/client.go:64,68`, `clients/go/mxgateway/galaxy.go:83,87` |
 | Client.Go-006 | Low | Resolved | Error handling & resilience | `clients/go/mxgateway/errors.go:9-130` |
@@ -177,6 +194,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Go-025 | Low | Resolved | Correctness & logic bugs | `clients/go/mxgateway/session.go:395-485,495-525` |
 | Client.Go-026 | Low | Resolved | Error handling & resilience | `clients/go/cmd/mxgw-go/main.go:1196-1222` |
 | Client.Go-027 | Low | Resolved | Code organization & conventions | `clients/go/cmd/mxgw-go/main.go:1195-1206` |
+| Client.Go-029 | Low | Resolved | Documentation & comments | `clients/go/README.md:300-303` |
 | Client.Java-006 | Low | Resolved | Performance & resource management | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:323-328`, `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/GalaxyRepositoryClient.java:279-284` |
 | Client.Java-007 | Low | Resolved | Testing coverage | `clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/` |
 | Client.Java-008 | Low | Resolved | Error handling & resilience | `clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClient.java:298-304` |
@@ -199,6 +217,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Java-031 | Low | Resolved | mxaccessgw conventions | `clients/java/README.md:13,17,26` |
 | Client.Java-035 | Low | Resolved | Testing coverage | `clients/java/zb-mom-ww-mxgateway-client/src/test/java/com/zb/mom/ww/mxgateway/client/MxGatewayClientSessionTests.java` |
 | Client.Java-036 | Low | Resolved | Code organization & conventions | `clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayAlarmFeedSubscription.java`, `MxGatewayEventSubscription.java`, `MxGatewayActiveAlarmsSubscription.java`, `DeployEventSubscription.java` |
+| Client.Java-038 | Low | Resolved | Code organization & conventions | `clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java:1347-1393` |
 | Client.Python-001 | Low | Resolved | Documentation & comments | `clients/python/pyproject.toml:8,25`, `clients/python/src/mxgateway_cli/commands.py:25` |
 | Client.Python-002 | Low | Resolved | Code organization & conventions | `clients/python/src/mxgateway/__init__.py:27` |
 | Client.Python-004 | Low | Resolved | Correctness & logic bugs | `clients/python/src/mxgateway_cli/commands.py:386,402-404` |
@@ -217,6 +236,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Python-021 | Low | Resolved | Documentation & comments | `clients/python/src/mxgateway_cli/commands.py`, `clients/python/README.md:235-258` |
 | Client.Python-025 | Low | Resolved | Testing coverage | `clients/python/tests/test_cli.py`, `clients/python/src/zb_mom_ww_mxgateway/{client.py,session.py}`, `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py` |
 | Client.Python-026 | Low | Resolved | Correctness & logic bugs | `clients/python/src/zb_mom_ww_mxgateway_cli/commands.py:674-738` |
+| Client.Python-029 | Low | Resolved | Correctness & logic bugs | `clients/python/src/zb_mom_ww_mxgateway/options.py:78-90` |
+| Client.Python-030 | Low | Resolved | Code organization & conventions | `clients/python/pyproject.toml:17` |
+| Client.Python-031 | Low | Resolved | Testing coverage | `clients/python/tests/test_tls.py:34`, `clients/python/pyproject.toml:53-56` |
 | Client.Rust-004 | Low | Resolved | Documentation & comments | `clients/rust/src/version.rs:7` |
 | Client.Rust-007 | Low | Resolved | Design-document adherence | `clients/rust/RustClientDesign.md:14-55` |
 | Client.Rust-008 | Low | Resolved | Performance & resource management | `clients/rust/src/value.rs:161-261` |
@@ -233,6 +255,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Client.Rust-026 | Low | Resolved | Performance & resource management | `clients/rust/crates/mxgw-cli/src/main.rs:1402-1406,1419-1423` |
 | Client.Rust-027 | Low | Resolved | Documentation & comments | `clients/rust/.cargo/config.toml:1-9` |
 | Client.Rust-028 | Low | Resolved | mxaccessgw conventions | `clients/rust/crates/mxgw-cli/src/main.rs:1126-1166` |
+| Client.Rust-032 | Low | Resolved | Design-document adherence | `clients/rust/RustClientDesign.md`; surface in `clients/rust/src/galaxy.rs:281-379` |
 | Contracts-001 | Low | Resolved | Design-document adherence | `docs/Grpc.md:13` (and `:3`, `:32`, `:39`) |
 | Contracts-003 | Low | Won't Fix | Code organization & conventions | `src/MxGateway.Contracts/MxGateway.Contracts.csproj:10` |
 | Contracts-004 | Low | Resolved | Documentation & comments | `src/MxGateway.Contracts/GatewayContractInfo.cs:3-6` |
@@ -248,6 +271,8 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Contracts-015 | Low | Resolved | Documentation & comments | `src/MxGateway.Contracts/Protos/mxaccess_gateway.proto:571-582` |
 | Contracts-016 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:31-41` (`QueryActiveAlarmsRequest`) |
 | Contracts-017 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:23-29` (the `rpc QueryActiveAlarms` block) |
+| Contracts-018 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Contracts/ProtobufContractRoundTripTests.cs:396` (`ActiveAlarmSnapshot_RoundTripsAllFields`) |
+| Contracts-019 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto:850-851` (`ActiveAlarmSnapshot`), `:318-324` (`AlarmProviderMode`) |
 | IntegrationTests-007 | Low | Resolved | Concurrency & thread safety | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:20`, `src/MxGateway.IntegrationTests/Galaxy/GalaxyRepositoryLiveTests.cs:5`, `src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:9` |
 | IntegrationTests-008 | Low | Resolved | Code organization & conventions | `src/MxGateway.IntegrationTests/LiveLdapFactAttribute.cs`, `src/MxGateway.IntegrationTests/Galaxy/LiveGalaxyRepositoryFactAttribute.cs`, `src/MxGateway.IntegrationTests/LiveMxAccessFactAttribute.cs` |
 | IntegrationTests-009 | Low | Resolved | Documentation & comments | `src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs:372-375` |
@@ -263,6 +288,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | IntegrationTests-023 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:14-29` |
 | IntegrationTests-024 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs` (`NullDashboardEventBroadcaster` private class at end of file) |
 | IntegrationTests-025 | Low | Resolved | Correctness & logic bugs | `src/ZB.MOM.WW.MxGateway.IntegrationTests/IntegrationTestEnvironmentTests.cs:57-84` (`ResolveRepositoryRoot_NoMarkers_ThrowsInvalidOperationExceptionNamingStartAndMarkers`) |
+| IntegrationTests-027 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.IntegrationTests/ZB.MOM.WW.MxGateway.IntegrationTests.csproj`, `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:4-5,134` |
+| IntegrationTests-028 | Low | Resolved | Design-document adherence | `src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs:120-161`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs:35` |
+| IntegrationTests-029 | Low | Resolved | Documentation & comments | `docs/GatewayTesting.md:218-224` |
 | Server-007 | Low | Resolved | Performance & resource management | `src/MxGateway.Server/Galaxy/GalaxyHierarchyProjector.cs:55-70` |
 | Server-008 | Low | Resolved | Performance & resource management | `src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs:111-134,160-189` |
 | Server-009 | Low | Resolved | Error handling & resilience | `src/MxGateway.Server/Security/Authentication/AuthSqliteConnectionFactory.cs:15-32` |
@@ -297,6 +325,8 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Server-048 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs:463-498` |
 | Server-049 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/IDashboardSessionAdminService.cs:5-18`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs:8-25` |
 | Server-050 | Low | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs:42-75,92-125` |
+| Server-052 | Low | Resolved | Documentation & comments | `src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs:24-30`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:101-114`, `docs/GatewayConfiguration.md:247` |
+| Server-053 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmWatchListResolverTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs` |
 | Tests-007 | Low | Resolved | Code organization & conventions | `src/MxGateway.Tests/Gateway/Grpc/MxAccessGatewayServiceTests.cs:682`, `src/MxGateway.Tests/Gateway/Grpc/GalaxyRepositoryGrpcServiceTests.cs:324`, `src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs:460`, `src/MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs:233` |
 | Tests-008 | Low | Resolved | mxaccessgw conventions | `src/MxGateway.Tests/Gateway/Sessions/WorkerAlarmRpcDispatcherTests.cs:1-9`, `src/MxGateway.Tests/Gateway/Sessions/NotWiredAlarmRpcDispatcherTests.cs:1-3`, `src/MxGateway.Tests/Gateway/Sessions/SessionManagerAlarmAutoSubscribeTests.cs:1` |
 | Tests-009 | Low | Resolved | Documentation & comments | `src/MxGateway.Tests/Gateway/Sessions/SessionManagerTests.cs:36-37,99,365` |
@@ -317,6 +347,9 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Tests-029 | Low | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSessionAdminServiceTests.cs:61-106,139-222`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs:77-125` |
 | Tests-030 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardApiKeyManagementServiceTests.cs:115-163`, `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs:146-177` |
 | Tests-031 | Low | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSnapshotPublisherTests.cs:22-61` |
+| Tests-033 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAlarmProviderStatus.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardBrowseAndAlarmModelTests.cs:140-195` |
+| Tests-034 | Low | Resolved | mxaccessgw conventions | `src/ZB.MOM.WW.MxGateway.Tests/Diagnostics/GatewayLogRedactorSeamTests.cs:1-15` |
+| Tests-035 | Low | Resolved | Concurrency & thread safety | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs:315-329` |
 | Worker-009 | Low | Resolved | Performance & resource management | `src/MxGateway.Worker/Ipc/WorkerFrameReader.cs:31,49`, `src/MxGateway.Worker/Ipc/WorkerFrameWriter.cs:57-58` |
 | Worker-010 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Conversion/VariantConverter.cs:204-226` |
 | Worker-011 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeClient.cs:169-171` |
@@ -331,6 +364,7 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker-022 | Low | Resolved | Code organization & conventions | `src/MxGateway.Worker/MxAccess/MxAlarmSnapshot.cs:12`, `:26`, `:49` |
 | Worker-024 | Low | Resolved | Concurrency & thread safety | `src/MxGateway.Worker/MxAccess/AlarmCommandHandler.cs:63-187`, `src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs:191-323` |
 | Worker-025 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker/Ipc/WorkerPipeSession.cs:111-117` |
+| Worker-028 | Low | Resolved | Code organization & conventions | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs:43-52`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmConsumer.cs:70-75` |
 | Worker.Tests-008 | Low | Resolved | Documentation & comments | `src/MxGateway.Worker.Tests/Conversion/VariantConverterTests.cs:175-182` |
 | Worker.Tests-009 | Low | Resolved | Code organization & conventions | `src/MxGateway.Worker.Tests/MxAccess/AlarmCommandHandlerTests.cs`, `AlarmDispatcherTests.cs`, `AlarmCommandExecutorTests.cs`, `AlarmRecordTransitionMapperTests.cs`, `WnWrapAlarmConsumerXmlTests.cs` |
 | Worker.Tests-010 | Low | Resolved | Correctness & logic bugs | `src/MxGateway.Worker.Tests/MxAccess/MxAccessStaSessionTests.cs:230-258` |
@@ -351,3 +385,5 @@ Findings with status `Resolved`, `Won't Fix`, or `Deferred`.
 | Worker.Tests-028 | Low | Resolved | Design-document adherence | `docs/GatewayTesting.md`, `src/MxGateway.Worker.Tests/Probes/` |
 | Worker.Tests-029 | Low | Resolved | Code organization & conventions | `src/MxGateway.Worker.Tests/Probes/AlarmsLiveSmokeTests.cs:9`, `src/MxGateway.Worker.Tests/Probes/AlarmClientWmProbeTests.cs:14`, `src/MxGateway.Worker.Tests/Probes/WnWrapConsumerProbeTests.cs:10` |
 | Worker.Tests-030 | Low | Resolved | Documentation & comments | `src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs:862-890` |
+| Worker.Tests-032 | Low | Resolved | Error handling & resilience | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` |
+| Worker.Tests-033 | Low | Resolved | Testing coverage | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmStateMachineTests.cs` |
@@ -4,8 +4,8 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Server` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

@@ -120,6 +120,38 @@ contention nor the bounded `_events` channel saw any changes in this wave.
 | 9 | Testing coverage | No issues found in this module — see Tests-026 in the Tests module for the missing EventsHub broadcast coverage. |
 | 10 | Documentation & comments | Issues found: Server-040, Server-043 (both documentation gaps). |

+### 2026-06-15 re-review (commit 410acc9)
+
+Re-review pass at `410acc9` over the `42b0037..HEAD` diff. The diff is large (~137 files)
+but the bulk is vendored theme/CSS/font asset swaps (`wwwroot`), generated code, and the
+shared-library auth refactor / TLS cert-autogen / lazy-browse / canonical-audit waves that
+each carry their own design+plan and were verified in passing only. This pass is scoped to
+the **alarm-provider subtag-fallback** wave the task called out: the central
+`GatewayAlarmMonitor` provider-mode seeding + failover/failback handling, the new
+`AlarmWatchListResolver` / `IAlarmWatchListResolver`, `AlarmFallbackOptions` /
+`AlarmDiscoveryOptions` / `AlarmSubtagNameOptions` and their `GatewayOptionsValidator`
+wiring, the `DashboardAlarmProviderStatus` badge + `AlarmsPage.razor` hub attach, the
+provider-mode gauge + `provider_switches` counter (`GatewayMetrics`,
+`AlarmProviderSwitchReason`), the Galaxy alarm-attribute discovery query
+(`GalaxyRepository.GetAlarmAttributesAsync` / `AlarmAttributesSql` / `GalaxyAlarmAttributeRow`),
+the `/auth/login` POST move + configurable `Dashboard:CookieName`, and the
+`BrowseChildrenRequest` scope-resolver entry. Prior findings Server-044 through Server-050
+are confirmed resolved by the SessionManager/GatewaySession changes in range and remain
+closed. New findings filed against this pass: Server-051..053.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | Issues found: Server-051 (`AlarmWatchListResolver.ResolveAsync`'s broad `catch (Exception)` swallows `OperationCanceledException`, contradicting the `IAlarmWatchListResolver` cancellation contract). |
+| 2 | mxaccessgw conventions | No issues found — file-scoped namespaces, `sealed`, `Async` suffix, Options pattern, MXAccess-aligned naming all hold; no UI component libraries (badge is Bootstrap-only); the alarm SQL is a parameterless constant; no secret/tag-value logging; well-known reason strings centralised in `AlarmProviderReasons`. |
+| 3 | Concurrency & thread safety | No issues found — `_providerMode`/`_providerDegraded`/`_providerReason`/`_providerSince` are read/written only under `_sync`; `BroadcastToAll` runs under `_sync`; the reconcile after a mode change is intentionally awaited outside `_sync` to avoid the documented self-deadlock; the provider-mode gauge is serialized on `GatewayMetrics._syncRoot`. |
+| 4 | Error handling & resilience | Issues found: Server-051 (cancellation swallowed in the resolver — also an error-handling/contract concern). |
+| 5 | Security | No issues found — `BrowseChildren` runs the same `ResolveBrowseSubtrees()` constraint scoping and `MetadataRead` scope as `DiscoverHierarchy`; the configurable `Dashboard:CookieName` falls back to the canonical default and cannot be blanked; the `/auth/login` POST keeps antiforgery + return-URL sanitisation. |
+| 6 | Performance & resource management | No issues found in the alarm-fallback code — discovery is a one-shot per subscribe lifecycle; the watch-list is composed once. |
+| 7 | Design-document adherence | No issues found — `docs/GatewayConfiguration.md`, `docs/Metrics.md`, `docs/GalaxyRepository.md`, and the `docs/plans/2026-06-13-alarm-subtag-fallback*` / `2026-06-15-forced-subtag-mode-fix.md` plans were landed in the same range and match the code. |
+| 8 | Code organization & conventions | No issues found — new alarm types live under `Alarms/`, options under `Configuration/`, metric helper under `Metrics/`, registered via `AddGatewayAlarms`. |
+| 9 | Testing coverage | Issues found: Server-053 (`AlarmWatchListResolver` `ExcludeAttributes`-vs-`IncludeAttributes` precedence and the resolver's cancellation contract are untested; no redundant-mode-change guard test). |
+| 10 | Documentation & comments | Issues found: Server-052 (`IAlarmWatchListResolver` XML contract claims cancellation propagates while the implementation swallows it; the `Discovery:ExcludeAttributes` doc says "Repository-derived watch-list" while the code also removes matching explicit `IncludeAttributes`). |
+
 ## Findings

 ### Server-001
@@ -929,3 +961,64 @@ Today neither call site has a Blazor error boundary, so an unhandled exception l
 **Recommendation:** Add a general `catch (Exception exception)` after the `SessionManagerException` catch in both `CloseSessionAsync` and `KillWorkerAsync`, log a warning (matching the SessionManagerException pattern), and return `DashboardSessionAdminResult.Fail($"{operation} failed unexpectedly. See the gateway log for details.")`. This makes the result type truly the only output the page sees. Add a regression test using a `ThrowingSessionManager` that throws e.g. `InvalidOperationException` from `KillWorkerAsync` and asserts the service returns a failing result rather than propagating.

 **Resolution:** 2026-05-24 — Added the recommended general `catch (Exception)` arms to both `DashboardSessionAdminService.CloseSessionAsync` and `KillWorkerAsync` (`src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSessionAdminService.cs`), placed after the `SessionManagerException` catches and behind a `catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) throw;` so caller cancellation still propagates cleanly. The new catches log a warning with actor + session id and return `DashboardSessionAdminResult.Fail("{Operation} failed unexpectedly for session {SessionId}. See the gateway log for details.")`, mirroring the SessionManagerException pattern. Regression tests in `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSessionAdminServiceTests.cs`: `CloseSessionAsync_WhenManagerThrowsUnexpected_ReturnsFriendlyFail` (the `ISessionManager` throws `InvalidOperationException("unexpected")`) and `KillWorkerAsync_WhenManagerThrowsUnexpected_ReturnsFriendlyFail` (throws `IOException("pipe broken")`); both assert the service returns a failing result with a non-blank message rather than propagating. The fake's new `CloseThrowsUnexpected` / `KillThrowsUnexpected` properties hold the configured exception. Confirmed to fail before the fix (raw exception propagated) and pass after.
+
+### Server-051
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:64-78` |
+| Status | Resolved |
+
+**Description:** `AlarmWatchListResolver.ResolveAsync` wraps the Galaxy Repository discovery call in a bare `catch (Exception ex)` that logs a warning and continues with an empty (config-only) discovery set:
+
+```csharp
+try { rows = await _repository.GetAlarmAttributesAsync(cancellationToken)...; }
+catch (Exception ex) { _logger.LogWarning(ex, "...continuing with configuration-only watch-list."); rows = []; }
+```
+
+`OperationCanceledException` / `TaskCanceledException` derive from `Exception`, so a cancellation triggered while `GetAlarmAttributesAsync` is awaiting SQL is **swallowed**, not propagated. The resolver then returns a (config-only or empty) watch-list as though the call completed normally. This directly contradicts the `IAlarmWatchListResolver.ResolveAsync` XML contract, which states: *"Cancellation is the one exception: a triggered cancellationToken still propagates an OperationCanceledException."* In practice the resolver is called from `GatewayAlarmMonitor.SubscribeAlarmsAsync` on the monitor's lifecycle token; if the gateway is shutting down (or the monitor lifecycle is being torn down) mid-discovery, the resolver hides the cancellation and the monitor proceeds to issue `SubscribeAlarms` with a wrong (empty) watch-list instead of unwinding promptly. The `GalaxyRepository.GetAlarmAttributesAsync` SQL path does honour the token (`OpenAsync(ct)` / `ExecuteReaderAsync(ct)` / `ReadAsync(ct)`), so a real cancellation can land inside this catch.
+
+**Recommendation:** Add a `catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }` ahead of the general catch (or filter the general catch with `when (ex is not OperationCanceledException)`), so cancellation propagates per the documented contract while genuine discovery failures still degrade to a config-only list. Add a regression test that cancels the token mid-`GetAlarmAttributesAsync` and asserts `OperationCanceledException` propagates.
+
+**Resolution:** Resolved 2026-06-15. Confirmed against source: the bare `catch (Exception ex)` swallowed `OperationCanceledException`. Filtered the catch with `when (ex is not OperationCanceledException)` so a real cancellation propagates per the `IAlarmWatchListResolver` contract while genuine discovery failures still degrade to a config-only list. Regression test: `AlarmWatchListResolverTests.ResolveAsync_RepositoryCancelled_PropagatesOperationCanceled` (failed before the fix, passes after).
+
+### Server-052
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Documentation & comments |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs:24-30`, `src/ZB.MOM.WW.MxGateway.Server/Alarms/AlarmWatchListResolver.cs:101-114`, `docs/GatewayConfiguration.md:247` |
+| Status | Resolved |
+
+**Description:** Two prose-vs-code mismatches in the watch-list resolver:
+
+1. The `IAlarmWatchListResolver.ResolveAsync` XML `<returns>` promises that a triggered `cancellationToken` propagates an `OperationCanceledException`, but the implementation swallows it (see Server-051). Whichever way Server-051 is resolved, exactly one of the doc or the code is currently wrong; right now the doc over-promises.
+
+2. `AlarmDiscoveryOptions.ExcludeAttributes` and `docs/GatewayConfiguration.md:247` both describe `ExcludeAttributes` as removing entries from the **"Repository-derived"** watch-list. The implementation's `ordered.RemoveAll(e => excluded.Contains(e.Reference))` runs over the combined list — Galaxy-Repository rows **and** the explicit `Discovery:IncludeAttributes` entries appended just above it — so an exclude entry that matches an explicit include silently removes that include too. The behaviour is defensible (excludes win) but is not what the "Repository-derived" wording says, and an operator who adds an attribute via `IncludeAttributes` and also lists it in `ExcludeAttributes` would be surprised it disappears.
+
+**Recommendation:** For (1), align the `IAlarmWatchListResolver` doc with whatever Server-051 settles on. For (2), either restrict the exclude to GR-discovered rows (apply `RemoveAll` before appending the `IncludeAttributes` entries) or update the option XML doc and `GatewayConfiguration.md` to say excludes are applied to the merged GR-plus-include list and therefore also suppress matching explicit includes.
+
+**Resolution:** Resolved 2026-06-15. (1) No longer over-promises: the Server-051 fix makes the implementation propagate `OperationCanceledException`, so the `IAlarmWatchListResolver.ResolveAsync` `<returns>` doc is now accurate and was left unchanged. (2) Kept the "excludes win" code behaviour (excludes applied to the merged GR-plus-include list) and corrected the prose to match: `AlarmDiscoveryOptions.ExcludeAttributes` XML doc and `docs/GatewayConfiguration.md:247` now state the exclude runs after the GR rows and explicit `IncludeAttributes` are combined, so an exclude matching an explicit include suppresses it too. The "excludes win" precedence is pinned by `AlarmWatchListResolverTests.ResolveAsync_ExcludeAlsoSuppressesMatchingExplicitInclude`.
+
+### Server-053
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmWatchListResolverTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs` |
+| Status | Resolved |
+
+**Description:** The new alarm-fallback surface is broadly well-tested (`AlarmWatchListResolverTests`, `GatewayAlarmMonitorProviderModeTests`, `DashboardBrowseAndAlarmModelTests`, `GalaxyAlarmAttributeMappingTests`, `GatewayOptionsValidatorTests`), but two behaviours that the diff introduced have no coverage:
+
+- **Resolver cancellation contract (Server-051):** no test cancels the token mid-discovery and asserts `OperationCanceledException` propagates. Because the existing `ResolveAsync_RepositoryThrows_LogsAndReturnsConfigOnlySet` asserts the swallow path, the cancellation regression is precisely the case that would catch the Server-051 bug — and its absence is why the contract violation went unnoticed.
+- **Exclude-vs-include precedence (Server-052 item 2):** no test exercises a `Discovery:IncludeAttributes` entry that also appears in `ExcludeAttributes`, so the "excludes also drop explicit includes" behaviour is unpinned and would silently change if the merge order were edited.
+
+Additionally, `GatewayAlarmMonitor.ApplyProviderModeChangeAsync` increments the `mxgateway.alarms.provider_switches` counter and resets `_providerSince` unconditionally on every `OnAlarmProviderModeChanged` event, with no guard for a redundant event whose `toMode` equals the current mode; there is no test asserting the from==to / no-op behaviour either way.
+
+**Recommendation:** Add resolver tests for (a) cancellation propagation and (b) an include that is also excluded; and a `GatewayAlarmMonitorProviderMode` test pinning the provider-switch counter behaviour for a same-mode repeat event (whichever semantics the team intends). These lock down the contracts the Server-051/052 findings expose.
+
+**Resolution:** Resolved 2026-06-15. Added all three missing tests: (a) `AlarmWatchListResolverTests.ResolveAsync_RepositoryCancelled_PropagatesOperationCanceled` (cancellation propagation, also covers Server-051); (b) `AlarmWatchListResolverTests.ResolveAsync_ExcludeAlsoSuppressesMatchingExplicitInclude` (exclude-vs-include precedence, also Server-052 item 2); and (c) `GatewayAlarmMonitorProviderModeTests.ProviderModeChange_RepeatedSameMode_RecordsASwitchForEachEvent`, which pins the existing semantics — each worker-reported `OnAlarmProviderModeChanged` event records a `provider_switches` increment (and resets `_providerSince`) even when `toMode` equals the current mode, since the worker is the authority on when a mode change occurred and the gateway does not synthesize or suppress it.
@@ -4,13 +4,43 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Tests` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

 ## Checklist coverage

+### 2026-06-15 re-review (commit `410acc9`)
+
+Re-review of the `42b0037..410acc9` diff (≈57 files), scoped to the alarm-provider
+fallback feature: the end-to-end failover/failback lifecycle test
+(`AlarmFailoverEndToEndTests`), the provider-mode/metric tests
+(`GatewayAlarmMonitorProviderModeTests`), the watch-list resolver tests
+(`AlarmWatchListResolverTests`), the validator additions
+(`GatewayOptionsValidatorTests` AlarmFallback block), the dashboard badge model
+(`DashboardBrowseAndAlarmModelTests`), the alarm metric tests
+(`GatewayMetricsTests`), the Galaxy alarm mapper (`GalaxyAlarmAttributeMappingTests`),
+and the new `provider_status` / degraded-provenance protobuf round-trips. The
+non-alarm churn in the diff (kill/shutdown SessionManager tests closing prior
+Tests-028/029, XML-doc-only additions to `SessionManagerBulkTests`/`GatewaySessionTests`,
+browse-tab and TLS tests) was walked but is not the review focus.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found in this diff. The lifecycle test correctly disambiguates the recovery `ProviderStatus` from the baseline by matching on `Reason == "recovered"`; the `ModeString_MapsToForcedProviderMode` `Assert.Empty(WatchList)` is weak (the stub resolver returns `[]` regardless of mode) but not wrong. |
+| 2 | mxaccessgw conventions | Issue found: Tests-034 (`GatewayLogRedactorSeamTests.cs` is in the global namespace with redundant `System.Collections.Generic`/`Xunit` usings, `var`, and a non-`sealed` `public class` — the same C# style drift family as the resolved Tests-008). |
+| 3 | Concurrency & thread safety | Issue found: Tests-035 (`AlarmFailoverEndToEndTests.DegradedTransition_*`'s second-subscriber `await foreach`-to-`SnapshotComplete` has no `WaitTimeout`, so a regression that never emits `SnapshotComplete` hangs the test instead of failing cleanly). The metric/feed reader races are correctly gated by `baselineReceived` TCS before emitting events. |
+| 4 | Error handling & resilience | No issues found in this diff. `AlarmWatchListResolverTests.ResolveAsync_RepositoryThrows_LogsAndReturnsConfigOnlySet` covers the discovery-unavailable degradation path; validator failure paths are well covered. |
+| 5 | Security | No issues found in this diff. The redaction seam assertion in `GatewayLogRedactorSeamTests` (despite its style drift) meaningfully pins API-key masking in `ClientIdentity`; secured-bulk credential round-trips are pinned. |
+| 6 | Performance & resource management | No issues found in this diff. Monitors/CTSs are disposed; `using GatewayMetrics`/`using GatewayAlarmMonitor` throughout. |
+| 7 | Design-document adherence | No issues found in this diff. Tests match the alarm-fallback plan and the forced-vs-failover-degraded badge distinction. |
+| 8 | Code organization & conventions | See Tests-034. The two alarm-monitor test files replicate (not share) the `FakeSessionManager`/`StubWatchListResolver` harness; the in-file remark documents this is deliberate to keep the sibling untouched — acceptable, not filed. |
+| 9 | Testing coverage | Issues found: Tests-032 (the monitor's `toMode`→`AlarmProviderSwitchReason` derivation — Subtag→Failover, Alarmmgr→Failback — is untested: `Failback` is asserted nowhere and the monitor tests check only the switch *count*, so a swapped/`Unknown` reason regression passes), Tests-033 (`DashboardAlarmProviderStatus.FromFeed` and its non-provider-status `ArgumentException` guard, the `SinceUtc` mapping, the `DegradedLabel` text, and the `Degraded && Mode==Alarmmgr` guard branch are all uncovered). |
+| 10 | Documentation & comments | No issues found in this diff. New alarm test files carry orienting class-level summaries; `GalaxyAlarmAttributeMappingTests`'s "derivation" framing slightly overstates the pass-through mapper but is harmless. |
+
+### 2026-05-24 re-review of the Tests-013–019 batch
+
 This pass (commit `a020350`) re-reviews the module after the Tests-013–019 batch was resolved alongside Server-017, Server-021, and Contracts-010.

 | # | Category | Result |
@@ -557,3 +587,63 @@ The cancellation tests for `WorkerClient` in `WorkerClientTests` *do* exercise t
 **Recommendation:** (a) The cheap fix: have `ThrowOnceThenYieldSnapshotService` record `_firstThrowAt = DateTimeOffset.UtcNow` immediately before the `throw`, and change the assertion to `secondSubscribeAt - firstThrowAt >= reconnectDelay - 10ms` — the gap then measures only the reconnect delay, eliminating the variable scheduling baseline. (b) The deeper fix: extend `DashboardSnapshotPublisher` to accept an `ITimeProvider`-style delay seam (or a virtual `DelayAsync` hook) so a `ManualTimeProvider` could advance time deterministically. (a) is preferred for now; (b) belongs as a follow-up if more reconnect-loop tests are added.

 **Resolution:** 2026-05-24 — Applied option (a). Added `FirstThrowAt` to `ThrowOnceThenYieldSnapshotService` and set it via `FirstThrowAt = DateTimeOffset.UtcNow;` immediately before the first-call `throw`. Removed the pre-`StartAsync` `startedAt` baseline; the assertion now reads `gap = secondSubscribeAt - firstThrowAt` (both timestamps captured inside the fake), and the 10 ms slack absorbs the Windows `Task.Delay` quantum without the variable `StartAsync` / scheduling overhead in the baseline. This is the same flake-isolation pattern Tests-006 / Tests-017 used (measuring only the production delay, not test-side setup). Suite green; the test passes deterministically across repeated runs.
+
+### Tests-032
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs:435-441`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs` |
+| Status | Resolved |
+
+**Description:** `GatewayAlarmMonitor.HandleProviderModeChanged` derives the provider-switch reason from the target mode: `toMode switch { Subtag => Failover, Alarmmgr => Failback, _ => Unknown }` (lines 435-439), then calls `_metrics.AlarmProviderSwitched(fromModeInt, toModeInt, switchReason)`. No test in the diff asserts this derivation. `GatewayAlarmMonitorProviderModeTests.ProviderModeChange_BroadcastsDegradedStatus_AndIncrementsSwitchMetric` only asserts the switch *count* (`switchCount == 1`) — it never inspects the `from`/`to`/`reason` tags on the measurement. `AlarmFailoverEndToEndTests.ProviderFailoverAndFailback_FullLifecycle` drives both a failover (alarmmgr→subtag) and a failback (subtag→alarmmgr) but asserts only on feed `ProviderStatus` messages, not on the metric tags. The only place the `reason` tag is read is `GatewayMetricsTests.AlarmProviderSwitched_IncrementsCounterWithExpectedTags`, which passes `AlarmProviderSwitchReason.Failover` *explicitly* to the metrics layer — that pins the metrics-side tag formatting, not the monitor's `toMode→reason` mapping. `AlarmProviderSwitchReason.Failback` is asserted nowhere in the suite. A regression that swapped the Failover/Failback arms, or collapsed them to `Unknown`, would pass every existing test while emitting wrong dashboard/observability data for every failback.
+
+**Recommendation:** Extend `GatewayAlarmMonitorProviderModeTests` (or add a failback case) to capture the `reason` tag through a `MeterListener` and assert it equals `"failover"` on an alarmmgr→subtag change and `"failback"` on a subtag→alarmmgr change, mirroring the tag-capturing pattern already in `GatewayMetricsTests.AlarmProviderSwitched_IncrementsCounterWithExpectedTags`. This pins the monitor's `toMode→AlarmProviderSwitchReason` derivation, not just the count.
+
+**Resolution:** 2026-06-15 — Confirmed root cause: the existing monitor tests asserted only the switch *count*, and `Failback` was asserted nowhere in the suite, so a swapped/`Unknown` reason arm would pass. Added `GatewayAlarmMonitorProviderModeTests.ProviderModeChange_FailoverThenFailback_RecordsCorrectReasonTags`, which captures the `reason` tag off the `mxgateway.alarms.provider_switches` counter via a `MeterListener` and drives an alarmmgr→subtag change then a subtag→alarmmgr change, asserting the captured reasons are exactly `["failover", "failback"]`. This pins the monitor's `toMode→AlarmProviderSwitchReason` derivation (`ApplyProviderModeChangeAsync`). Test passes against current production code (no production change); no bug found.
+
+### Tests-033
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAlarmProviderStatus.cs`, `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardBrowseAndAlarmModelTests.cs:140-195` |
+| Status | Resolved |
+
+**Description:** The three new badge-mapping tests cover `FromProviderStatus` for green (Alarmmgr/not-degraded), amber (Subtag/degraded), and cyan (Subtag/forced). Several adjacent behaviours of the same projection are uncovered: (1) `DashboardAlarmProviderStatus.FromFeed(AlarmFeedMessage)` — the public entry the dashboard SignalR snapshot path actually calls — and its `ArgumentException` thrown when the message is not a `ProviderStatus` payload have zero coverage in the suite (a grep for `FromFeed` across the test project returns no hits). (2) The `SinceUtc` field (`status.Since?.ToDateTimeOffset()`) is never asserted, so a regression dropping or mis-converting the badge timestamp would not be caught. (3) The `DegradedLabel` constant text ("Subtag monitoring (degraded)") is asserted nowhere — the amber test only checks the `bg-warning` CSS class, so a label swap would pass. (4) The `degraded = status.Degraded || status.Mode == AlarmProviderMode.Subtag` guard's second branch (`Degraded == true` while `Mode == Alarmmgr`) — an explicitly-degraded alarmmgr status — is untested, so the "guard against either being set independently" comment in the product code is unverified.
+
+**Recommendation:** Add `FromFeed_NonProviderStatusPayload_Throws` (asserting `ArgumentException`) and `FromFeed_ProviderStatusPayload_ProjectsBadge`; assert `SinceUtc` on a status carrying a `Since` timestamp; assert `model.Label == DashboardAlarmProviderStatus.DegradedLabel` in the amber test; and add a `Degraded=true, Mode=Alarmmgr` case asserting it maps to the degraded (amber) badge per the independent-flag guard.
+
+**Resolution:** 2026-06-15 — Confirmed the four coverage gaps against `DashboardAlarmProviderStatus`. Added to `DashboardBrowseAndAlarmModelTests`: `FromFeed_ProviderStatusPayload_ProjectsBadge` and `FromFeed_NonProviderStatusPayload_Throws` (the latter asserts `ArgumentException` for a `SnapshotComplete` feed message); `FromProviderStatus_WithSinceTimestamp_MapsSinceUtc` (pins `SinceUtc` round-trips the protobuf `Since` timestamp); `FromProviderStatus_Alarmmgr_DegradedFlagSet_WarningBadge` (the `Degraded && Mode==Alarmmgr` independent-flag branch maps to the amber degraded badge); and a `DegradedLabel` text assertion added to the existing amber `FromProviderStatus_Subtag_Degraded_WarningBadge`. All pass against current production code (no production change); no bug found.
+
+### Tests-034
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | mxaccessgw conventions |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Diagnostics/GatewayLogRedactorSeamTests.cs:1-15` |
+| Status | Resolved |
+
+**Description:** `GatewayLogRedactorSeamTests.cs` diverges from the project's C# style guide and the rest of the test suite: it declares no file-scoped namespace (the class lands in the global namespace, unlike every other test file which sits under `ZB.MOM.WW.MxGateway.Tests.*`); it carries redundant explicit `using System.Collections.Generic;` and `using Xunit;` (both are implicit global usings in this project, enforced elsewhere — see the resolved Tests-008); it uses `var` for `redactor`/`props` where the suite uses explicit types per `docs/style-guides/CSharpStyleGuide.md`; and it declares `public class` rather than the project's `sealed`-by-default convention. The redaction assertion itself is sound (it meaningfully pins API-key masking in `ClientIdentity`), so this is purely the same style-drift family as the previously-filed-and-resolved Tests-008, not a correctness issue.
+
+**Recommendation:** Add `namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;` (file-scoped), drop the redundant `System.Collections.Generic`/`Xunit` usings, mark the class `public sealed class`, and replace the two `var` declarations with explicit types (`GatewayLogRedactorSeam` / `Dictionary<string, object?>`).
+
+**Resolution:** 2026-06-15 — Confirmed the style drift. Rewrote `GatewayLogRedactorSeamTests.cs` to add the file-scoped `namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;`, dropped the redundant `using System.Collections.Generic;`/`using Xunit;` (both implicit global usings), marked the class `public sealed class`, and replaced the two `var` declarations with explicit `GatewayLogRedactorSeam` / `Dictionary<string, object?>` types. The single `Redact_MasksApiKeyInClientIdentity` assertion is unchanged and still passes.
+
+### Tests-035
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Concurrency & thread safety |
+| Location | `src/ZB.MOM.WW.MxGateway.Tests/Alarms/AlarmFailoverEndToEndTests.cs:315-329` |
+| Status | Resolved |
+
+**Description:** In `DegradedTransition_CachedThenReplayed_CarriesDegradedAndSourceProviderToNewSubscriber`, the second-subscriber loop iterates `monitor.StreamAsync(null, newStreamCts.Token)` with no timeout, breaking only when a `SnapshotComplete` payload arrives (lines 317-329). Every other wait in this file routes through `WaitForAsync(..., WaitTimeout)` or `Task.WaitAsync(WaitTimeout)`; this `await foreach` does not. If a regression caused the monitor to stop emitting `SnapshotComplete` for a new subscriber (e.g. a snapshot-replay path that throws before the terminal message), the test would hang on the `await foreach` rather than fail with a `TimeoutException`, relying on the xUnit `longRunningTestSeconds` warning or the CI hard-kill instead of a clean assertion failure. The first subscriber in the same test is correctly bounded by `WaitForAsync`.
+
+**Recommendation:** Bound the second-subscriber drain with the same `WaitTimeout` used elsewhere — e.g. link `newStreamCts` to a `CancellationTokenSource.CreateLinkedTokenSource` plus `CancelAfter(WaitTimeout)`, or wrap the drain in a `Task` awaited via `WaitAsync(WaitTimeout)` — so a missing `SnapshotComplete` surfaces as a deterministic failure rather than a hang.
+
+**Resolution:** 2026-06-15 — Confirmed the unbounded `await foreach` in `DegradedTransition_CachedThenReplayed_CarriesDegradedAndSourceProviderToNewSubscriber`. Bounded the second-subscriber drain with a `CancellationTokenSource.CreateLinkedTokenSource(newStreamCts.Token, drainTimeoutCts.Token)` where `drainTimeoutCts.CancelAfter(WaitTimeout)`, and wrapped the loop in a `try/catch (OperationCanceledException) when (drainTimeoutCts.IsCancellationRequested)` that rethrows a `TimeoutException`. A regression that never emits `SnapshotComplete` now fails cleanly instead of hanging. Test still passes.
@@ -4,11 +4,48 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Worker.Tests` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

+## 2026-06-15 re-review (commit `410acc9`)
+
+Re-review of the alarm-fallback test additions in `git diff 42b0037..HEAD --
+src/ZB.MOM.WW.MxGateway.Worker.Tests/`. New unit suites land for the subtag
+fallback (`SubtagAlarmConsumerTests`, `SubtagAlarmStateMachineTests`,
+`SyntheticAlarmGuidTests`, `LmxSubtagAlarmSourceTests`) and the auto-failover
+composite (`FailoverAlarmConsumerTests`); the existing alarm suites are updated
+for the `SubscribeAlarmsCommand`-based handler signature, the
+`(eq, affinity, comFactory)` handler-factory delegate, and the new
+degraded/source-provider fields. Most of the change is genuinely new coverage
+plus a large volume of XML-doc additions on existing test doubles (benign).
+
+Findings: the failover state-machine transitions (failover at threshold,
+failback after stable probes, intermittent-failure reset, before/after-switch
+forwarding, ack delegation, `ProbeOnce`-never-re-Subscribes) are all covered;
+the acked latch (`OutOfOrderAckThenClear_StillEmitsAckRtn`), the dup-address
+guard (`DuplicateActiveSubtag_Throws`), and the exact-match-vs-substring ack
+resolution (`AcknowledgeByName_PrefixNameDoesNotFalseMatch`,
+`AcknowledgeByGuid_*`) are all pinned. Three coverage gaps remain
+(Worker.Tests-031/032/033), all in new alarm-fallback code paths. The two
+newest files (`SyntheticAlarmGuidTests`, `LmxSubtagAlarmSourceTests`) omit an
+explicit `using Xunit;` but compile via the `<Using Include="Xunit" />` global
+using in the csproj, so that is not a finding.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found — failover/state-machine/ack tests assert meaningful post-conditions (mode, emitted state, target subtag address) and do not pass for the wrong reason; the prefix-name and unknown-guid negative cases pin the exact-match contract. |
+| 2 | mxaccessgw conventions | No issues found — new test methods follow `Method_Scenario_Expectation`; STA-affinity respected (state machine / consumer driven synchronously through internal seams). |
+| 3 | Concurrency & thread safety | No issues found — new failover/subtag suites are single-threaded and event-driven; no wall-clock floors or fixed sleeps were introduced (the `MxAccessValueCacheTests` change only deletes the old Worker.Tests-020 comment block). |
+| 4 | Error handling & resilience | Issues found: Worker.Tests-032 — the `RunPrimary` `when (ex is not OutOfMemoryException)` filter (the OOM-safe catch path) and the `FailoverSettings` clamp branches are untested. |
+| 5 | Security | No issues found — no secrets/credentials; ack-operator identity fields are sentinels. |
+| 6 | Performance & resource management | No issues found — `IDisposable` test subjects use `using`; the `LmxSubtagAlarmSource` dispose-idempotency / unadvise-only-advised-handles teardown is regression-tested. |
+| 7 | Design-document adherence | No issues found — tests mirror the alarm-fallback plan (degraded flag, synthetic GUID, subtag-ack via ack-comment, single-subscribe primary). |
+| 8 | Code organization & conventions | No issues found — new suites live under `MxAccess/`; test doubles are per-file (acceptable for these narrow fakes). |
+| 9 | Testing coverage | Issues found: Worker.Tests-031 (`ProbeIntervalSeconds` throttle-active branch never exercised — every test uses `probeIntervalSeconds: 0`), Worker.Tests-033 (`SubtagAlarmStateMachine` ack-while-inactive and priority-subtag branches uncovered). |
+| 10 | Documentation & comments | No issues found — test XML docs match assertions; no misleading names observed. |
+
 ## 2026-05-24 re-review (commit `42b0037`)

 **Re-review: no new findings.** `git diff --name-only d692232..42b0037 -- src/ZB.MOM.WW.MxGateway.Worker.Tests` returns empty — the Worker.Tests module has zero source changes since the previous review. All ten checklist categories therefore inherit "No issues found" from the `d692232` pass. The header is bumped to track the latest reviewed commit; Worker.Tests-001..030 remain closed.
@@ -533,3 +570,48 @@ findings (Worker.Tests-001 through -030) are unaffected.
 **Recommendation:** Either (a) reassign `CreateCancelEnvelope` to a sequence value `>` shutdown (or pass the sequence as a parameter, matching `CreateGatewayHelloEnvelope`'s parameter style), so the wire trace reads in ascending order; (b) add an XML-doc note on the cancel test stating that the worker has no inbound monotonicity check and the test ignores envelope sequence ordering; (c) parameterise all four helper methods so each test passes its desired sequence and the literal numbers stop carrying implicit meaning. Option (c) is the cleanest because `CreateGatewayHelloEnvelope` is already parameter-driven for nonce/version.

 **Resolution:** 2026-05-20 — Took option (c): parameterised `CreateGatewayHelloEnvelope`/`CreateCommandEnvelope`/`CreateCancelEnvelope`/`CreateShutdownEnvelope` with a `ulong sequence` argument (defaults 1/2/2/3 respectively, matching the typical Hello/Command/Cancel/Shutdown ordering), so the literal sequence values no longer carry implicit meaning. Updated the cancel-correlation test's wire trace to ascend (Hello=1, Cancel=2, Shutdown=3) and added a comment noting that the worker has no inbound monotonicity check — the parameter exists so multi-frame tests can pin the trace ordering explicitly when needed.
+
+### Worker.Tests-031
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` (all `FailoverSettings` constructions) |
+| Status | Resolved |
+
+**Description:** Every `FailoverSettings` in `FailoverAlarmConsumerTests` is built with `probeIntervalSeconds: 0`, which deliberately *disables* the probe throttle. The throttle-active branch in `FailoverAlarmConsumer.ProbeOnce` (`src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs:211-215`) — where a probe is *skipped* because fewer than `ProbeIntervalSeconds` have elapsed since `lastProbeAtUtc` — is therefore never exercised. This is a genuine production behaviour: the failback cadence is the only thing preventing a degraded worker from hammering the broken primary with a `PollOnce` on every timer tick, and `AlarmCommandHandlerTests.Subscribe_AutoModeWithWatchList_...` wires a real non-zero `FailbackProbeIntervalSeconds = 1` into the handler, so the throttle is on the live path. A regression that inverted the comparison (probing only *after* the interval became `>=` instead of skipping while `<`), dropped the `lastProbeAtUtc` update, or removed the throttle entirely would not be caught by any test. The task brief named "ProbeIntervalSeconds enforcement" as an explicit focus area.
+
+**Recommendation:** Add a test that constructs `FailoverSettings(threshold: 1, probeIntervalSeconds: <N>, stableProbes: 1)` with a non-zero interval, forces failover, makes the primary healthy, then calls `ProbeOnce()` twice in quick succession and asserts the second call did *not* probe (e.g. assert `primary.Polls` advanced by exactly one and `Mode` is still `Subtag`). Because the throttle reads `DateTime.UtcNow` directly, either accept a coarse same-wall-clock-instant assertion (two back-to-back calls reliably fall inside any interval ≥ 1s) or, preferably, refactor `ProbeOnce` to take an injectable clock so the throttle boundary can be pinned deterministically without wall-clock dependence (consistent with the Worker.Tests-020 manual-time-source approach).
+
+**Resolution:** 2026-06-15 — Took the coarse same-wall-clock-instant approach (no production-code clock injection needed). Added `FailoverAlarmConsumerTests.ProbeOnce_WithNonZeroInterval_ThrottlesSecondProbeWithinInterval`: builds `FailoverSettings(threshold: 1, probeIntervalSeconds: 3600, stableProbes: 5)`, forces failover to Subtag, makes the primary healthy, then calls `ProbeOnce()` twice back-to-back. The first probe re-polls the primary (`primary.Polls == 1`); the second falls inside the 3600s interval and is throttled, so `primary.Polls` is unchanged and `Mode` stays `Subtag`. `stableProbes: 5` keeps a single clean probe from failing back, so the throttled `ProbeOnce` path stays in scope. A 1-hour interval makes the two back-to-back calls reliably fall inside the window without any timing flakiness.
+
+### Worker.Tests-032
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Error handling & resilience |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/FailoverAlarmConsumerTests.cs` |
+| Status | Resolved |
+
+**Description:** Two resilience branches of `FailoverAlarmConsumer` are uncovered by the new tests. (1) `RunPrimary` catches `Exception ex when (ex is not OutOfMemoryException)` (`FailoverAlarmConsumer.cs:295`) — the OOM-safe catch path the task brief explicitly called out. No test throws `OutOfMemoryException` from the primary to verify it *propagates* (rather than being swallowed and counted toward the failover threshold like every other exception); the `FlakyPrimary` fake throws only `COMException`. A regression that broadened the filter to swallow OOM would convert a fatal allocation failure into a silent failover. (2) The `FailoverSettings` constructor clamps `threshold < 1 → 1` and `stableProbes < 1 → 1` (`FailoverSettings.cs:38-40`); no test passes a sub-1 value to confirm the clamp, so a misconfigured `ConsecutiveFailureThreshold = 0` from the gateway could change failover semantics undetected.
+
+**Recommendation:** Add a `FlakyPrimary`-style fake (or a flag on the existing one) that throws `OutOfMemoryException` from `PollOnce`, and assert `sut.PollOnce()` rethrows it via `Assert.Throws<OutOfMemoryException>` and that no `ProviderModeChanged` fired. Add a small `FailoverSettings` fact (or `[Theory]`) asserting `new FailoverSettings(0, 0, 0).Threshold == 1` and `.StableProbes == 1` to pin the clamp.
+
+**Resolution:** 2026-06-15 — Added a `ThrowOutOfMemoryOnPoll` flag to the existing `FlakyPrimary` fake (its `PollOnce` throws `OutOfMemoryException` when set, checked before the `COMException` branch). Regression test `FailoverAlarmConsumerTests.RunPrimary_WhenPrimaryThrowsOutOfMemory_PropagatesAndDoesNotFailOver` drives `PollOnce` through the primary, asserts `Assert.Throws<OutOfMemoryException>`, and asserts no `ProviderModeChanged` fired and `Mode` stays `Alarmmgr` — pinning that the `when (ex is not OutOfMemoryException)` filter lets OOM propagate rather than swallowing it and counting it toward the failover threshold. The clamp is pinned by `FailoverSettings_ClampsSubMinimumValues` (a `[Theory]`): `(0,0,0)→(1,0,1)`, `(-5,-5,-5)→(1,0,1)`, and a pass-through `(3,7,2)→(3,7,2)` to confirm in-range values are not altered.
+
+### Worker.Tests-033
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Testing coverage |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/SubtagAlarmStateMachineTests.cs` |
+| Status | Resolved |
+
+**Description:** `SubtagAlarmStateMachineTests` covers the core transition matrix and the acked latch well, but two branches of the new state machine are unexercised. (1) The ack-while-inactive path in `SubtagAlarmStateMachine.ApplyAcked` (`src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs:156-164`): when `.acked` flips true while the alarm is *not* active, the machine must emit nothing and must *not* set `AckedDuringEpisode` — otherwise a stale ack from a prior episode could mis-latch the next raise into a spurious `ACK_RTN`. No test drives an `.acked` change without a preceding active raise. (2) The priority-subtag path (`SubtagRole.Priority` → `state.Priority = CoerceInt(...)`, line 76-78): `SubtagAlarmConsumerTests.Subscribe_AdvisesAllSubtagsIncludingAckComment` confirms the priority subtag is *advised*, but no test raises a priority value change and asserts it flows into the emitted/snapshot record's `Priority`, so `CoerceInt` and the priority assignment are untested in the state-machine layer.
+
+**Recommendation:** Add (a) `AckedTrueWhileInactive_EmitsNothingAndDoesNotLatch` — apply `.acked=true` with no prior active raise, assert `Apply` returns empty, then raise active and clear and assert the clear emits `UnackRtn` (proving the stale ack did not latch); and (b) `PriorityChange_FlowsIntoEmittedRecord` — apply a priority value then an active raise and assert the emitted record's `Priority` equals the supplied value (and a `CoerceInt` string/garbage case falls back).
+
+**Resolution:** 2026-06-15 — Added both tests to `SubtagAlarmStateMachineTests`. `AckedTrueWhileInactive_EmitsNothingAndDoesNotLatch` applies `.acked=true` with no preceding active raise (asserts `Apply` returns empty), then drives a fresh raise→clear episode and asserts the clear emits `UnackRtn` — proving the stale inactive ack did not latch `AckedDuringEpisode`. `PriorityChange_FlowsIntoEmittedRecord` (the target now includes a `PrioritySubtag`) applies an `int` priority `750` (asserts the priority change emits nothing), raises active and asserts the emitted record's `Priority == 750` (exercising `CoerceInt`'s `int` path and the priority assignment), then applies a non-numeric `"not-a-number"` priority and asserts the snapshot `Priority` is still `750` (the `CoerceInt` string fallback keeps the prior value, not zero).
@@ -4,11 +4,38 @@
 |---|---|
 | Module | `src/ZB.MOM.WW.MxGateway.Worker` |
 | Reviewer | Claude Code |
-| Review date | 2026-05-24 |
-| Commit reviewed | `42b0037` |
+| Review date | 2026-06-15 |
+| Commit reviewed | `410acc9` |
 | Status | Re-reviewed |
 | Open findings | 0 |

+## 2026-06-15 re-review (commit `410acc9`)
+
+Re-review of the `42b0037..410acc9` diff — the alarm-provider subtag-fallback
+feature (`git diff 42b0037..410acc9 -- src/ZB.MOM.WW.MxGateway.Worker/`). New
+substantive code: `SubtagAlarmConsumer`, `SubtagAlarmStateMachine`,
+`FailoverAlarmConsumer`, `LmxSubtagAlarmSource`, `SyntheticAlarmGuid`,
+`AlarmProviderModeChange`, `FailoverSettings`, `ISubtagAlarmSource` /
+`SubtagValueChange`, plus the degraded/`source_provider` propagation in
+`AlarmDispatcher` / `MxAccessAlarmEventSink` / `MxAccessEventMapper`, the
+`ForcedMode`/watch-list routing and STA-COM-factory threading in
+`AlarmCommandHandler` / `MxAccessStaSession`, and the `SubscribeAlarmsCommand`
+re-plumb in `MxAccessCommandExecutor`. Three new findings: **Worker-026** (High),
+**Worker-027** (Medium), **Worker-028** (Low). Worker-001..025 remain closed.
+
+| # | Category | Result |
+|---|---|---|
+| 1 | Correctness & logic bugs | No issues found. Subtag synthesis (`SubtagAlarmStateMachine` raise/ack/clear, `AckedDuringEpisode` latch, segment-boundary name derivation), exact-match ack resolution (`ResolveTargetByName` avoids the prefix false-positive), and `MapTransition`'s `Unspecified→*Alm` raise path are all sound. |
+| 2 | mxaccessgw conventions | No issues found. The synthesis is worker-side and every degraded record/event carries `degraded=true` + `source_provider=SUBTAG`, satisfying the explicit opt-in non-parity exception to the "never synthesize events" rule. The gateway never instantiates COM. net48 constraint respected — `AlarmProviderModeChange`/`FailoverSettings` are plain classes with get-only ctor-assigned props (no init/positional records); no `WriteRecord`-style init usage introduced. |
+| 3 | Concurrency & thread safety | Issue found: Worker-026 (an exception in the failover switch path — `SwitchToStandby`'s priming snapshot or either switch's `ProviderModeChanged` handler — escapes the state machine after `active` has already flipped, killing the STA alarm-poll loop with no mode-changed event). STA affinity itself is sound: `LmxSubtagAlarmSource` owns its own apartment-bound `LMXProxyServerClass`, all consumer calls are STA-confined via `AlarmCommandHandler`'s affinity guard, and `Dispose` UnAdvises before tearing handles down so a late pump callback cannot re-enter. |
+| 4 | Error handling & resilience | Issue found: Worker-027 (`SyntheticAlarmGuid` uses `MD5.Create()`, which throws on a net48 FIPS-policy host — breaking every subtag transition stamp and snapshot, and feeding Worker-026's poll-loop-kill path). `FailoverSettings` clamps tunables to safe minimums; `LmxSubtagAlarmSource` teardown is best-effort/idempotent. |
+| 5 | Security | No issues found. No secret/credential logging on the alarm path; ack comments are operator-supplied alarm metadata, not secrets. Synthetic GUID is non-cryptographic by design and not a security control. |
+| 6 | Performance & resource management | No issues found. `LmxSubtagAlarmSource` releases its COM object via `FinalReleaseComObject` and tracks advised-vs-added handles so `Dispose` only UnAdvises what it advised. The standby is armed once and gated-by-active rather than churning subscribe/unsubscribe per switch. |
+| 7 | Design-document adherence | No issues found. Implementation matches `docs/plans/2026-06-13-alarm-subtag-fallback-design.md` (auto-failover/failback, ack-comment-write ack, worker-side synthesis, additive proto fields). The probe re-polls the still-subscribed primary (single-subscribe constraint) as the design's "Superseded" notes describe. |
+| 8 | Code organization & conventions | Issue found: Worker-028 (the dup-subtag-address guard in `SubtagAlarmStateMachine.Bind` does not cover duplicate `AlarmFullReference` entries, which silently overwrite in `targetsByReference`/`_statesByReference`). One-public-type-per-file is otherwise respected for the new files. |
+| 9 | Testing coverage | No standalone finding. New unit suites exist for each major component (`SubtagAlarmConsumerTests`, `SubtagAlarmStateMachineTests`, `FailoverAlarmConsumerTests`, `LmxSubtagAlarmSourceTests`, `SyntheticAlarmGuidTests`), matching the design's test matrix. The switch-path exception fragility (Worker-026) and the dup-reference case (Worker-028) are untested edge cases noted in those findings. |
+| 10 | Documentation & comments | No issues found. The new types carry accurate XML docs; the net48-constraint rationale is documented inline on `FailoverSettings`/`AlarmProviderModeChange`; the "why PollOnce only, no re-Subscribe" and probe-throttle behaviour are documented on `FailoverAlarmConsumer.ProbeOnce`. |
+
 ## 2026-05-24 re-review (commit `42b0037`)

 **Re-review: no new findings.** `git diff --name-only d692232..42b0037 -- src/ZB.MOM.WW.MxGateway.Worker` returns empty — the Worker module has zero source changes since the previous review. All ten checklist categories therefore inherit "No issues found" from the `d692232` pass. The header is bumped to track the latest reviewed commit; Worker-001..025 remain closed.
@@ -464,3 +491,50 @@ _runtimeSession = _runtimeSessionFactory()
 Match the pattern `AlarmCommandHandler.Subscribe` already uses for `consumerFactory()` (`AlarmCommandHandler.cs:76-77`).

 **Resolution:** 2026-05-20 — `WorkerPipeSession.RunAsync` now uses `_runtimeSession = _runtimeSessionFactory() ?? throw new InvalidOperationException("Worker runtime session factory returned null.");`, matching the pattern `AlarmCommandHandler.Subscribe` uses for its `consumerFactory()`. A null factory return now produces a clear diagnostic exception at the call site instead of NRE-ing on the next dereference (and the `finally` block's `_runtimeSession?.Dispose()` silently no-oping on a half-initialized session). Regression test `WorkerPipeSessionTests.RunAsync_WhenRuntimeSessionFactoryReturnsNull_ThrowsDiagnosticException` drives `RunAsync` with `() => null!` and asserts the diagnostic `InvalidOperationException` is thrown with the expected message.
+
+### Worker-026
+
+| Field | Value |
+|---|---|
+| Severity | High |
+| Category | Concurrency & thread safety |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/FailoverAlarmConsumer.cs:289-338`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs:307-320` |
+| Status | Resolved |
+
+**Description:** `FailoverAlarmConsumer.SwitchToStandby` flips `active = Active.Standby` / `mode = Subtag` first, then calls `_ = standby.SnapshotActiveAlarms();` (the priming side-effect), and only then calls `RaiseModeChanged(...)`. If `standby.SnapshotActiveAlarms()` throws, the exception escapes `SwitchToStandby`, escapes the `catch` in `RunPrimary`, and escapes `FailoverAlarmConsumer.PollOnce`/`Subscribe`. The `SubtagAlarmConsumer.SnapshotActiveAlarms` path is not exception-free: it calls `StampSynthetic` → `SyntheticAlarmGuid.ForReference` (which throws on a FIPS host — see Worker-027) and walks live state. The same exposure exists for `RaiseModeChanged` itself: the attached `AlarmCommandHandler.OnProviderModeChanged` handler runs synchronously and calls `eventQueue.Enqueue(...)`, which throws `MxAccessEventQueueOverflowException` at capacity; that also propagates out of both `SwitchToStandby` and `SwitchToPrimary`.
+
+When this happens the consumer has **already** transitioned `active`/`mode` to Standby (or Primary) but the `ProviderModeChanged` event is never emitted — so the gateway never learns the feed went degraded. Worse, because the failover calls run on the worker's STA inside `RunAlarmPollLoopAsync`, the escaping exception lands in that loop's trailing `catch (Exception)` arm (`MxAccessStaSession.cs:307-320`), which records a single fault and **permanently stops the alarm poll loop**. The standby is then never pumped or probed again — i.e. a transient primary COM fault that should have produced a clean degraded-mode handoff instead produces a total, undetected alarm outage for the session, defeating the entire purpose of the fallback feature. There is no safe operator workaround short of restarting the session.
+
+**Recommendation:** Make the switch atomic and exception-isolated: raise `ProviderModeChanged` (and perform the priming snapshot) inside their own `try`/`catch` so a snapshot or handler failure cannot abort the switch or unwind into the poll loop. Order the state flip so the mode-changed notification is guaranteed to fire even if priming fails (e.g. flip state, raise mode-changed in a guarded block, then attempt the priming snapshot in a separate guarded block whose failure is logged/faulted but non-fatal). Add a regression test where the standby's `SnapshotActiveAlarms` throws on the first call after failover, asserting (a) `ProviderModeChanged` still fires and (b) `PollOnce` does not rethrow.
+
+**Resolution:** 2026-06-15 — Reordered and exception-isolated the failover switch in `FailoverAlarmConsumer`. `SwitchToStandby` now flips `active`/`mode`, then raises `ProviderModeChanged` FIRST (so the gateway always learns the feed went degraded), then primes the standby snapshot via a new `TryPrimeStandbySnapshot()` whose failure is swallowed (`catch when ex is not OutOfMemoryException`) — a priming failure can no longer abort the switch or unwind into the poll loop. `RaiseModeChanged` itself now wraps `ProviderModeChanged?.Invoke` in a `try`/`catch (when ex is not OutOfMemoryException)` so a subscriber handler exception (e.g. `AlarmCommandHandler.OnProviderModeChanged`'s `eventQueue.Enqueue` overflowing) cannot escape `SwitchToStandby`/`SwitchToPrimary` into `RunAlarmPollLoopAsync`'s trailing catch and permanently stop alarm polling. `OutOfMemoryException` is deliberately allowed to propagate. The MXAccessStaSession poll-loop arm is unchanged — the fix prevents the escape rather than catching it there. Regression tests in `FailoverAlarmConsumerTests`: `Failover_WhenStandbyPrimingSnapshotThrows_StillRaisesModeChangeAndDoesNotRethrow` (standby `SnapshotActiveAlarms` throws on the priming call → `ProviderModeChanged` still fires, `Mode` is Subtag, `Subscribe`/`PollOnce` do not rethrow) and `Failover_WhenModeChangedHandlerThrows_SwitchStillTakesEffectAndDoesNotRethrow` (a throwing `ProviderModeChanged` subscriber → switch still takes effect, no rethrow).
+
+### Worker-027
+
+| Field | Value |
+|---|---|
+| Severity | Medium |
+| Category | Error handling & resilience |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SyntheticAlarmGuid.cs:38-40` |
+| Status | Resolved |
+
+**Description:** `SyntheticAlarmGuid.ForReference` derives the deterministic alarm GUID via `using MD5 md5 = MD5.Create();`. The worker targets .NET Framework 4.8, where `MD5.Create()` returns `MD5CryptoServiceProvider`. When the host has the Windows FIPS-compliance policy enabled (`Enabled=1` under `HKLM\System\CurrentControlSet\Control\Lsa\FIPSAlgorithmPolicy`), the non-validated `MD5CryptoServiceProvider` constructor throws `InvalidOperationException` ("This implementation is not part of the Windows Platform FIPS validated cryptographic algorithms."). `SyntheticAlarmGuid.ForReference` is on the hot path of the subtag fallback: `SubtagAlarmConsumer.StampSynthetic` calls it for **every** synthesized transition and **every** snapshot record. On a FIPS host the subtag fallback therefore throws on first use; combined with Worker-026 that exception kills the STA alarm-poll loop, so the fallback is not merely degraded but completely non-functional exactly when it is needed (after the primary alarmmgr provider has failed). The comment already notes MD5 is "never for security" — the issue is availability under FIPS policy, not cryptographic strength. The regulated deployment hosts (Zimmer) are a plausible FIPS environment.
+
+**Recommendation:** Replace `MD5.Create()` with a FIPS-agnostic non-cryptographic 128-bit hash that does not route through the crypto FIPS gate — e.g. compute the 16 GUID bytes from a stable hash that does not use `System.Security.Cryptography` (a fixed FNV-1a / xxHash-style derivation over the UTF-8 bytes), or use `SHA256` truncated to 16 bytes via the managed `SHA256Managed`/`IncrementalHash` only if confirmed FIPS-safe on net48 (it is not guaranteed — prefer the non-crypto route). The mapping only needs determinism and collision resistance for distinct references, not cryptographic properties. Add a test that exercises `ForReference` without depending on a crypto provider.
+
+**Resolution:** 2026-06-15 — Replaced the `MD5.Create()` derivation in `SyntheticAlarmGuid.ForReference` with a pure-managed FNV-1a hash: two independent 64-bit FNV-1a passes over the UTF-8 bytes (the high pass mixes the byte index into its accumulator to decorrelate the halves) fill the low/high 64 bits of the 128-bit GUID, and the input length is folded in so the empty string is non-degenerate (never `Guid.Empty`). The `using System.Security.Cryptography;` import is gone, so no FIPS-gated `MD5CryptoServiceProvider` is ever constructed — the subtag fallback no longer throws on a FIPS-policy host. The derivation stays deterministic and distinct-per-reference. The existing `SyntheticAlarmGuidTests` (`SameReference_SameGuid`, `DifferentReference_DifferentGuid`, `Reference_ProducesNonEmptyGuid`) pin only those properties — not a specific GUID literal — so they continue to pass unchanged; no test needed a value update. Added regression tests `SyntheticAlarmGuidTests.EmptyReference_ProducesNonEmptyGuid` (length-fold guard against a degenerate all-zero result) and `ForReference_UnderFipsEnforcement_DoesNotThrowAndStaysDeterministic` (sets the managed `UseLegacyFipsThrow` AppContext switch and asserts the derivation still succeeds deterministically; a regression reintroducing a FIPS-gated provider would throw here).
+
+### Worker-028
+
+| Field | Value |
+|---|---|
+| Severity | Low |
+| Category | Code organization & conventions |
+| Location | `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmStateMachine.cs:43-52`, `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/SubtagAlarmConsumer.cs:70-75` |
+| Status | Resolved |
+
+**Description:** `SubtagAlarmStateMachine.Bind` throws `ArgumentException` on a duplicate subtag **item address** (the documented dup-address guard), but neither the state machine nor `SubtagAlarmConsumer` guards against a duplicate `AlarmFullReference` in the watch list. When two `AlarmSubtagTarget` entries share an `AlarmFullReference` but use different subtag addresses, `_statesByReference[target.AlarmFullReference] = state` and `targetsByReference[reference] = target` each silently overwrite the earlier entry, while the earlier target's subtag addresses are still bound to an orphaned `AlarmState`. The orphaned state is mutated by incoming value changes but is invisible to `SnapshotActive` (which iterates only the surviving `_statesByReference.Values`) and to ack resolution (which uses the surviving `targetsByReference`). The result is silently inconsistent synthesized state for that reference. This is a watch-list configuration error (the gateway resolves the watch list), so impact is limited, but the asymmetry — addresses are guarded, references are not — is surprising and silent.
+
+**Recommendation:** Add a duplicate-`AlarmFullReference` guard symmetric with the dup-address guard: throw a descriptive `ArgumentException` from the `SubtagAlarmStateMachine` (or `SubtagAlarmConsumer`) constructor when two watch-list entries share a reference, so a misconfigured watch list fails fast at subscribe time rather than producing silently inconsistent state. Cover it with a unit test.
+
+**Resolution:** 2026-06-15 — Added a duplicate-`AlarmFullReference` guard in the `SubtagAlarmStateMachine` constructor symmetric with the existing dup-address guard in `Bind`: before adding each target's `_statesByReference` entry it checks `ContainsKey` (the dictionary is `OrdinalIgnoreCase`, matching the consumer's `targetsByReference` lookup) and throws a descriptive `ArgumentException` ("Duplicate alarm full reference '{reference}' is bound to more than one alarm target."). Because `SubtagAlarmConsumer` constructs the state machine before populating its own `targetsByReference`, this guard fires before the consumer's silent overwrite too, covering both dictionaries from one canonical check. Regression test `SubtagAlarmStateMachineTests.DuplicateAlarmFullReference_Throws` (two targets sharing a reference but using distinct active subtags → `ArgumentException`).
@@ -818,6 +818,16 @@ subtags (confirmed AVEVA `AlarmExtension` field names, verified against the live
 ZB Galaxy `attribute_definition` rows). The gateway re-runs discovery on its
 reconcile cadence and pushes an updated watch-list when the model changes.

+Each target's canonical `AlarmFullReference` is composed as
+`Galaxy!{area}.{reference}` (literal `Galaxy` provider). The `{area}` is the
+alarm object's **real Galaxy area** — discovered per object via
+`gobject.area_gobject_id` (`GetAlarmAttributesAsync` projects it as `area_name`)
+— so the synthesized reference's group matches exactly the area the native
+alarmmgr (wnwrap) emits for the same alarm (e.g. `TestMachine_001` in `TestArea`
+yields `Galaxy!TestArea.TestMachine_001.TestAlarm001`). The configured
+`Discovery.Area` / `DefaultArea` is **only** the fallback for explicit
+`IncludeAttributes` entries, which carry no discovered area.
+
 ### Subtag advise and `LmxSubtagAlarmSource`

 `LmxSubtagAlarmSource` (implements `ISubtagAlarmSource`) owns a separate
@@ -881,6 +891,25 @@ returns a failure code that the gateway surfaces as `FailedPrecondition`.
 `AcknowledgeByGuid` maps the synthetic GUID back to its reference via an
 internal dictionary, then calls the same write path.

+`SubtagAlarmConsumer.Subscribe` advises the ack-comment subtag alongside the
+observed ones (active/acked/priority). This is required: MXAccess rejects a
+write to an item that has been added but not advised with `E_INVALIDARG`
+("Value does not fall within the expected range"). Advising it at subscribe
+time makes it an active item so the later ack write succeeds — its value
+changes carry no transition (the state machine ignores unmapped addresses).
+
+### Live validation
+
+The subtag path was validated against live MXAccess on the dev rig
+(`DESKTOP-6JL3KKO`, Galaxy `DEV`, `TestMachine_001.TestAlarm001`):
+
+- `….InAlarm` → `True` (Boolean), `….Acked` → `False` (Boolean),
+  `….Priority` → `500` (Int32), `….AckMsg` → string — confirming the field
+  names **and** the runtime reference shape `<Object>.<AlarmAttr>.<field>`
+  with **no** intermediate alarm-condition segment.
+- `AcknowledgeByName` (AckMsg write) returned `0` once the ack-comment subtag
+  was advised — confirming the ack-by-comment-write mechanism end to end.
+
 ### Fidelity limitations

 The following fields are not available or have lower quality in subtag mode:
@@ -242,9 +242,9 @@ native wnwrap alarm-manager provider and the subtag-monitoring fallback.
 | `MxGateway:Alarms:Fallback:FailbackProbeIntervalSeconds` | `30` | While in subtag mode, how often (in seconds) the monitor probes the wnwrap provider to detect recovery. Floored at 1. |
 | `MxGateway:Alarms:Fallback:FailbackStableProbes` | `3` | Number of consecutive clean wnwrap probes required before the monitor switches back to the alarm manager. Floored at 1. |
 | `MxGateway:Alarms:Fallback:Discovery:UseGalaxyRepository` | `true` | When `true`, the monitor queries the Galaxy Repository SQL database to build the subtag watch-list for the configured area. |
-| `MxGateway:Alarms:Fallback:Discovery:Area` | _(empty)_ | Galaxy area to scope the Repository query to. Falls back to `MxGateway:Alarms:DefaultArea` when empty. Ignored when `UseGalaxyRepository` is `false`. |
+| `MxGateway:Alarms:Fallback:Discovery:Area` | _(empty)_ | Galaxy area to scope the Repository query to. Falls back to `MxGateway:Alarms:DefaultArea` when empty. Ignored when `UseGalaxyRepository` is `false`. This area is **not** used to compose a Repository-derived alarm's canonical `Galaxy!{area}.{reference}`: each discovered alarm uses its object's real Galaxy area (discovered via `gobject.area_gobject_id`), so the reference's group matches what the native alarmmgr emits. `Discovery:Area` / `DefaultArea` is used as the composition area only for explicit `IncludeAttributes` entries, which carry no discovered area. |
 | `MxGateway:Alarms:Fallback:Discovery:IncludeAttributes` | _(empty)_ | Explicit MXAccess attribute paths to add to the subtag watch-list, supplementing (or replacing, when `UseGalaxyRepository` is `false`) the Repository-derived list. |
-| `MxGateway:Alarms:Fallback:Discovery:ExcludeAttributes` | _(empty)_ | Attribute paths to remove from the Repository-derived watch-list. Ignored when `UseGalaxyRepository` is `false`. |
+| `MxGateway:Alarms:Fallback:Discovery:ExcludeAttributes` | _(empty)_ | Attribute paths to remove from the merged watch-list (case-insensitive). The exclude is applied after the Repository-derived rows and the explicit `IncludeAttributes` entries are combined, so an exclude that matches an explicit include suppresses it too — excludes win. Ignored when `UseGalaxyRepository` is `false`. |
 | `MxGateway:Alarms:Fallback:Subtags:Active` | `InAlarm` | Subtag name for the in-alarm boolean. Confirmed AVEVA `AlarmExtension` field name. |
 | `MxGateway:Alarms:Fallback:Subtags:Acked` | `Acked` | Subtag name for the acknowledged boolean. Confirmed AVEVA `AlarmExtension` field name. |
 | `MxGateway:Alarms:Fallback:Subtags:AckComment` | `AckMsg` | Subtag name for the acknowledgement comment write target. Writing this subtag performs the acknowledge in AVEVA. Confirmed AVEVA `AlarmExtension` field name. When empty, the ack-comment write path is disabled. |
@@ -215,13 +215,18 @@ beyond "LDAP is up." See the "Adding a gw-specific group" section of
 `glauth.md` for the provisioning step that adds `GwAdmin` and grants it to
 `admin`.

-The suite covers both the success path and the `DashboardAuthenticator` failure
-branches: `admin` whose LDAP groups resolve to the `Admin` role succeeds and
-emits the role claim; `readonly` is denied because no group in their `memberOf`
-appears in `GroupToRole`; `admin` with a wrong password is rejected by the
-candidate bind without leaking the password into `FailureMessage`; an unknown
-username yields no candidate; and an unreachable LDAP server is absorbed into a
-failed result rather than throwing.
+`DashboardAuthenticator` delegates the LDAP bind and group search to the shared
+`ZB.MOM.WW.Auth.Ldap` provider (`LdapAuthService`) and only maps the resulting
+groups to dashboard roles via `DashboardGroupRoleMapper`; the bind/search
+mechanics that decide each outcome live in that shared provider, not in
+`DashboardAuthenticator`.
+
+The suite covers both the success path and the failure outcomes: `admin` whose
+LDAP groups resolve to the `Admin` role succeeds and emits the role claim;
+`readonly` is denied because no group in their `memberOf` appears in
+`GroupToRole`; `admin` with a wrong password fails authentication without leaking
+the password into `FailureMessage`; an unknown username fails authentication; and
+an unreachable LDAP server is absorbed into a failed result rather than throwing.

 Run the LDAP live tests explicitly:

@@ -1,7 +1,10 @@
 # Alarm Subtag-Monitoring Fallback — Design

 **Date:** 2026-06-13
-**Status:** Approved (brainstorming), ready for implementation planning
+**Status:** Superseded by implementation (merged to `main`). This is the original
+brainstorming design; a few details below were refined during implementation —
+see the inline **Superseded** notes. The shipped behaviour is documented in
+`docs/AlarmClientDiscovery.md`, the client READMEs, and the contracts.
 **Branch:** `feat/alarm-subtag-fallback`

 ## Problem
@@ -162,6 +165,11 @@ reconcile cadence and pushes an updated watch-list when the model changes.

 **`mxaccess_worker.proto`:**

+> **Superseded:** these additions shipped in `mxaccess_gateway.proto`, not
+> `mxaccess_worker.proto` — the worker imports the gateway proto and the alarm
+> commands/events live there (`AlarmSubtagTarget`,
+> `OnAlarmProviderModeChangedEvent`, the extended subscribe command).
+
 - Extend the alarm-subscribe command with: `AlarmProviderMode forced_mode`
  (`UNSPECIFIED` = auto), `int32 consecutive_failure_threshold`,
  `int32 failback_probe_interval_seconds`, `int32 failback_stable_probes`, and
@@ -240,6 +248,12 @@ to `/hubs/alarms`, (c) update metrics, (d) force a reconcile.
 - `mxgateway_alarm_provider_switch_total{from,to,reason}` (counter)
 - `mxgateway_alarm_fallback_watchlist_size` (gauge)

+> **Superseded:** the shipped meter names are `mxgateway.alarms.provider_mode`
+> (gauge) and `mxgateway.alarms.provider_switches{from,to,reason}` (counter,
+> `reason` bounded to `failover`/`failback`/`unknown`). The watch-list-size /
+> watch-list-empty gauges were not implemented; an empty watch-list is surfaced
+> via a warning log and the feed's degraded `ProviderStatus` instead.
+
 ## Configuration

 ```jsonc
@@ -0,0 +1,270 @@
+# Deferred Follow-ups Implementation Plan
+
+**Date:** 2026-06-14
+**Status:** Plan only — NOT yet executed. Saved for review.
+**Context:** After the alarm-subtag-fallback cleanup (merged `5976770`) and its redeploy to
+windev (10.100.0.48), five items remain deferred. This plan handles all five. They are
+independent — execute in any order, or cherry-pick. Items D1–D2 are code (branch off `main`);
+D3 is a dev-rig validation; D4–D5 are ops on the deployed hosts (no code).
+
+Source of the deferred list: the post-deploy review on 2026-06-14. See also memory
+`project_deploy_mechanics`, `project_wonder_deployment`, `project_alarm_subtag_fallback`,
+`project_rig_alarms_object_driven`.
+
+---
+
+## D1 — Surface `AlarmProviderSwitchCount` on the dashboard metric list
+
+**Classification:** small · **Est:** ~10 min · **Where:** Server (net10), build+test on macOS
+**Why deferred:** the dashboard reads provider *state* from the feed's `ProviderStatus` badge,
+not the metrics snapshot, so the snapshot field (added in B1) and the OTEL counter were enough.
+This makes the cumulative switch count visible in the dashboard's metric table too.
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSnapshotService.cs` (`CreateMetricSummaries`, ~line 178–198)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardSnapshotServiceTests.cs` (or the existing snapshot test file)
+
+**Steps:**
+1. In `CreateMetricSummaries`, add to the `metrics` list (near the other counters):
+   `new("mxgateway.alarms.provider_switches", snapshot.AlarmProviderSwitchCount),`
+   Also consider adding the current mode as a gauge row if useful:
+   the snapshot does not carry the mode int (only the feed does), so DO NOT invent one —
+   only add the switch count, which the snapshot already exposes.
+2. Add/extend a unit test asserting the summary list contains a
+   `mxgateway.alarms.provider_switches` row equal to the snapshot's `AlarmProviderSwitchCount`
+   after calling `metrics.AlarmProviderSwitched(...)`.
+3. Verify: `dotnet build src/ZB.MOM.WW.MxGateway.Server` (macOS) and
+   `dotnet test src/ZB.MOM.WW.MxGateway.Tests --filter FullyQualifiedName~DashboardSnapshot`.
+4. Commit.
+
+**Rollback:** revert the one-line list addition.
+
+---
+
+## D2 — Reproduce and fix the `AmbiguousMatchException` on `GET /`
+
+**Classification:** standard · **Est:** ~30–45 min (repro + fix) · **Where:** Server (net10)
+**Why deferred:** observed only in *old* (06/05, Development) logs:
+`AmbiguousMatchException: The request matched multiple endpoints. Matches: / (/) / (/)`.
+Unauthenticated `GET /` safely 302s to `/login`; the ambiguity would only throw for an
+*authenticated* request that reaches routing. Pre-existing and unrelated to the alarm work,
+but it would surface as a dashboard-home 500. Confirm it still reproduces before fixing.
+
+**Root-cause candidates (the two endpoints both matching `/`):**
+- `DashboardHome.razor` (`@page "/"`) mapped by `MapRazorComponents<App>()`
+  (`Dashboard/DashboardEndpointRouteBuilderExtensions.cs:92`).
+- `MapStaticAssets(...)` (`GatewayApplication.cs:190`) — in .NET 8–10 the static-assets
+  endpoint can register a fingerprinted root that collides with the home page.
+
+**Step 0 — Reproduce (do this first; if it does NOT repro, downgrade to a documentation note):**
+1. Log into the dashboard as `multi-role`/`password` (Administrator) at
+   `http://10.100.0.48:5130/login`.
+2. Navigate to `http://10.100.0.48:5130/` (the "Dashboard" home).
+3. If it renders the Overview page → not a live bug on this build; record that and stop
+   (the dev error-page throw was a Development-only artifact). If it 500s with
+   `AmbiguousMatchException` → proceed to fix.
+
+**Fix (only if it reproduces):**
+- Files: `src/ZB.MOM.WW.MxGateway.Server/GatewayApplication.cs` (endpoint mapping order/region),
+  `src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs`,
+  `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor`.
+- Candidate fixes, in order of preference:
+  1. Inspect the actual two matched endpoint display names at runtime (the exception lists
+     them) — temporarily enable detailed errors or read the stderr `Matches:` block — to learn
+     exactly which two collide.
+  2. If `MapStaticAssets` owns the second `/`: it must run, but confirm it isn't double-mapping
+     the home route; if it is, move `MapStaticAssets` ordering or scope it so it doesn't claim
+     the literal `/` content path. (Do NOT remove `MapStaticAssets` — Blazor needs it.)
+  3. If two component pages both declare `@page "/"`: give the non-home one a distinct route.
+  4. Last resort: give `DashboardHome` an explicit route (e.g. `@page "/overview"`) and add a
+     trivial `MapGet("/", () => Results.Redirect("/overview"))` with `.RequireAuthorization(...)`.
+- Add a test that exercises the root route once resolved (a WebApplicationFactory-based
+  integration test asserting authenticated `GET /` returns 200, if the dashboard test harness
+  supports auth; otherwise a routing-uniqueness assertion).
+- Verify: `dotnet build src/ZB.MOM.WW.MxGateway.Server`; re-run the authenticated `GET /` repro.
+
+**Rollback:** revert the routing change; the home page returns to its prior (ambiguous) state.
+
+**Note:** this fix ships only via a Server redeploy (D-deploy applies, see D5/windev redeploy
+procedure in `project_deploy_mechanics`). Decide whether to bundle it with the next redeploy.
+
+---
+
+## D3 — Validate the failover path end-to-end on the dev rig (ForceSubtag)
+
+**Classification:** standard (validation, no production code) · **Est:** ~30–45 min · **Where:** dev rig / windev
+**Why deferred:** `provider_mode 1` (healthy alarmmgr) is verified in production, but the actual
+alarmmgr→subtag **failover**, the **degraded badge**, the synthesized subtag alarms, and the
+`provider_switches{from,to,reason}` counter (with the new bounded `failover`/`failback`/`unknown`
+tag) have never fired live — a healthy system never switches, and the rig's alarms can't be made
+to fail COM on demand. Use the explicit `ForceSubtag` config mode to exercise the degraded path
+deterministically without an alarmmgr fault.
+
+**Approach:** run a *temporary* gateway instance (NOT the production service) in `ForceSubtag`
+mode against the dev Galaxy, drive it with the operator/IDE alarm toggle, and confirm the
+degraded surface. Do this on windev in a throwaway run so production stays on `Auto`.
+
+**Steps:**
+1. On windev, from a build worktree at `main`, run the Server locally (or a second instance on
+   alt ports) with `MxGateway:Alarms:Fallback:Mode=ForceSubtag` (env
+   `MxGateway__Alarms__Fallback__Mode=ForceSubtag`), pointed at the dev Galaxy
+   (`\\DESKTOP-6JL3KKO\Galaxy!DEV`). Use distinct Kestrel ports to avoid clashing with the
+   production service on 5120/5130.
+2. Subscribe an alarm client (or open the dashboard alarms page for that instance) and confirm:
+   - The provider badge shows **"Subtag monitoring (degraded)"** (amber `bg-warning`).
+   - `curl .../metrics` shows `mxgateway_alarms_provider_mode 2`.
+   - Active alarms appear with `degraded=true` and a synthetic (MD5-derived) GUID, with the
+     reference shape `Galaxy!<realArea>.<object>.<attr>` (e.g. `Galaxy!TestArea.TestMachine_001.TestAlarm001`).
+3. Drive a transition: have the operator/IDE toggle a `TestMachine_NNN.TestAlarmNNN` true→false
+   (external MXAccess writes are ignored — see `project_rig_alarms_object_driven`); confirm a
+   synthesized Raise then Clear, and an `AckMsg` write via AcknowledgeByName returns 0.
+4. (Optional, to exercise the switch counter) run in `Auto` and induce a primary fault if a safe
+   way exists; otherwise document that the counter is unit-tested only and `ForceSubtag` covers
+   the degraded surface. Note: `ForceSubtag` may not increment `provider_switches` (no runtime
+   switch) — that counter's live exercise remains the one gap; record it explicitly rather than
+   claiming coverage.
+5. Tear down the temporary instance. Production service is untouched (stays `Auto`).
+6. Record results in `project_alarm_subtag_fallback` memory (degraded badge + synthesized
+   subtag alarms now live-validated; switch-counter still unit-test-only if not exercised).
+
+**Rollback:** none — temporary instance only; nothing in production changes.
+
+---
+
+## D4 — Prune stale deploy backups on windev
+
+**Classification:** trivial (ops) · **Est:** ~10 min · **Where:** windev (10.100.0.48), no code
+**Why deferred:** backups accumulate on every deploy; harmless but cluttering
+`C:\publish\mxaccessgw\`.
+
+**Current backups observed (2026-06-14):**
+- `Server.bak-20260526T143341`, `Server.bak-20260529T090320`, `Server.bak529.20260604T122616`,
+  `Server.bak-theme030-20260605-053056`, `Server.bak-theme031-20260605-083410`,
+  `Server.bak-20260614-prefallback` (today's), `Worker.bak-20260614-prefallback` (today's).
+- Inside `Server\`: `ZB.MOM.WW.MxGateway.Server.dll.bak-20260604-loginfix`,
+  `appsettings.json.bak-20260604-{glauth35,ldapkeys}`.
+
+**Steps:**
+1. **Keep** `Server.bak-20260614-prefallback` and `Worker.bak-20260614-prefallback` — the
+   immediate rollback for the current deploy. Keep until the new build has soaked (e.g. a few
+   days / one business cycle).
+2. Delete the clearly-superseded older backups: the `Server.bak-2026052*`, `Server.bak529.*`,
+   and `Server.bak-theme03*` dirs. Confirm each is a Server dir (not something live) before
+   `rmdir /s /q`.
+3. Optionally remove the in-`Server` `.bak-*` sidecar files (`*.dll.bak-*`,
+   `appsettings.json.bak-*`) — but FIRST confirm the live `appsettings.json` is correct (it is,
+   post-deploy) so the `.bak` ldap/glauth copies aren't the only record of a needed value.
+4. Verify the service is unaffected: `Get-Service MxAccessGw` Running, `/health/ready` 200.
+
+**Rollback:** none needed (deletions only; the current-deploy backup is retained). If unsure
+about any single dir, skip it.
+
+---
+
+## D5 — Redeploy the wonder host to bring it to parity
+
+**Classification:** high-risk (separate production-ish box, fiddly access, divergent build) · **Est:** ~1–2 h · **Where:** wonder-app-vd03.zmr.zimmer.com (10.220.157.247)
+**Why deferred:** wonder still runs the pre-feature build — it lacks the entire alarm-fallback
+feature and the cleanup. Bring it to `5976770` if parity is wanted. This box is materially
+different from windev (read `project_wonder_deployment` fully before starting).
+
+**Key differences from windev (do NOT reuse the windev recipe blindly):**
+- Access: no usable `ssh host "cmd"` exec. Port 22 OpenSSH (PowerShell) was observed CLOSED
+  2026-05-26; the reliable path is **servecli on port 2222** (cmd.exe PTY + SFTP only) using the
+  base64-`-EncodedCommand` pattern in `project_wonder_deployment` / `~/Desktop/servecli/instructions.md`.
+  Re-test port 22 first; if up, prefer it.
+- Build shape: wonder runs a **self-contained single-file win-x64** Server (~118 MB), renamed to
+  `MxGateway.Server.exe` for the NSSM path `E:\ApiInstall\MxGateway\Server\MxGateway.Server.exe`.
+  So publish must be `-r win-x64 --self-contained -p:PublishSingleFile=true` (NOT the
+  framework-dependent windev recipe), then rename the exe to `MxGateway.Server.exe`.
+- Static assets quirk: ship BOTH `ZB.MOM.WW.MxGateway.Server.staticwebassets.endpoints.json` and
+  `MxGateway.Server.staticwebassets.endpoints.json` next to the exe (the ZB-named one is used).
+- Config: wonder's `appsettings.json` carries HTTP-switched Kestrel (`http://0.0.0.0:5130`),
+  `Dashboard.GroupToRole` = `{ SCADA-Admins/Designers/Deploy-All → Admin }`,
+  `Dashboard.RequireHttpsCookie:false`, LDAP base `dc=scadalink,dc=local`. **Preserve wonder's
+  appsettings.json** exactly like windev (do not ship the repo default). Note: wonder's
+  GroupToRole values are `"Admin"` — VERIFY the current build's validator accepts `"Admin"` (the
+  windev crash showed it requires `'Administrator'`/`'Viewer'`). **If the validator rejects
+  `"Admin"`, wonder's appsettings GroupToRole values must be updated to `Administrator` BEFORE/with
+  the deploy or the new build will crash-loop.** This is the single biggest risk — resolve it first.
+- Worker: wonder's x86 worker is the original; the alarm-fallback adds new subscribe fields. To
+  use subtag fallback on wonder, the **x86 worker must also be redeployed** (publish x86, rename
+  if needed). If only the Server is updated, confirm worker IPC protobuf compat (contracts changed
+  for alarms — a stale worker may not understand the extended SubscribeAlarms). Safer to deploy
+  both Server and Worker together.
+
+**Steps (high level — expand against the runbook before executing):**
+1. Confirm parity is actually wanted on wonder, and whether the dashboard (disabled there) and
+   the alarm monitor are even in scope for that box. If alarms/dashboard are off on wonder, this
+   may reduce to "Server binary parity only."
+2. Resolve the **GroupToRole value compatibility** question (Admin vs Administrator) — inspect
+   the current build's `GatewayOptionsValidator` and decide whether to patch wonder's appsettings.
+3. Build self-contained Server (`-r win-x64 --self-contained -p:PublishSingleFile=true`) and x86
+   Worker from `main` (`5976770`).
+4. Transfer via SFTP (servecli) to a staging dir on `E:\ApiInstall\MxGateway\`.
+5. Stop `MxAccessGw`; back up `Server` → `Server.bak.<ts>` and `Worker` → `Worker.bak.<ts>`;
+   swap in the new build; **restore wonder's `appsettings.json`** (+ patched GroupToRole if
+   needed); ensure both staticwebassets manifests are present; rename Server exe to
+   `MxGateway.Server.exe`.
+6. Start `MxAccessGw` (no dependents). Verify stderr line count does not grow (no crash loop),
+   `curl -k https://...:5130/health/live` (or HTTP per current config) Healthy, gRPC 5120 up.
+7. Verify the new metric is present if the metrics endpoint is exposed there.
+
+**Rollback (documented in memory):** stop service,
+`Move-Item Server Server.failed; Move-Item Server.bak.<ts> Server`, restore appsettings from the
+backup, start.
+
+---
+
+## Suggested order
+
+1. **D2 repro** (5 min — just log in and hit `/`): decides whether D2 is a real fix or a no-op.
+2. **D1** (small code) + **D2 fix if needed** — bundle into one Server branch; they ship together
+   on the next Server redeploy.
+3. **D4** (prune windev backups) — quick ops, independent.
+4. **D3** (ForceSubtag validation) — exercises the degraded surface; do before/after the D1+D2
+   redeploy so you also confirm the new Server build is healthy.
+5. **D5** (wonder) — largest and riskiest; do last, only if parity is wanted, and resolve the
+   GroupToRole-value compatibility question first.
+
+## Execution note
+
+This plan is intentionally NOT executed. When ready, execute on a branch off `main`
+(`feat/deferred-followups` or per-item branches) — do not commit to `main` directly. D1/D2 need a
+Server redeploy to take effect; D4/D5 are host operations; D3 touches nothing permanent.
+
+---
+
+## D2 — Resolution (2026-06-14)
+
+Static source determination on build `5976770` (runtime repro out of scope). What was checked:
+
+- **Razor `@page "/"` count:** exactly ONE — `Dashboard/Components/Pages/DashboardHome.razor`.
+  All other pages declare distinct routes (`/login`, `/sessions`, `/galaxy`, `/browse`,
+  `/apikeys`, `/workers`, `/events`, `/alarms`, `/settings`, `/sessions/{SessionId}`).
+- **No root index.html:** `src/ZB.MOM.WW.MxGateway.Server/wwwroot/` contains only `css/` and
+  `lib/` subdirectories; no `index.html` anywhere under `wwwroot/`.
+- **No `UseDefaultFiles` / no `MapFallback`:** neither appears anywhere in the Server project.
+- **`MapStaticAssets` mapped once** (`GatewayApplication.cs:190`) and `UseStaticFiles()` once
+  (`:41`); the static-assets manifest serves fingerprinted CSS/JS assets, not a literal `/`.
+- **No `MapGet("/")`:** the dashboard endpoint builder
+  (`Dashboard/DashboardEndpointRouteBuilderExtensions.cs`) maps only `/auth/login`, `/logout`,
+  `/denied`, `/hubs/{snapshot,alarms,events}`, `/hubs/token`, then `MapRazorComponents<App>()`.
+  None use pattern `/`.
+- **`MapZbHealth` / `MapZbMetrics`** come from the external `ZB.MOM.WW.Health` shared library
+  (not in this repo) and map health/metrics paths, not `/`.
+
+**Root cause of the 2026-06-05 log:** `code-reviews/Server/findings.md` (re-review at `42b0037`,
+2026-05-24) records that commit `de7639a` **removed the legacy `MapGet("/", ...)` redirect that
+was colliding with the Blazor `@page "/"` (a real 500)**. That legacy registration was the source
+of the `AmbiguousMatchException`. It is gone on the current build, so the second `/` endpoint no
+longer exists.
+
+**Conclusion:** No duplicate `/` endpoint on build `5976770`. The AmbiguousMatchException is not
+reproducible from source — it was a stale Development-only artifact from before `de7639a` reached
+the deployed instance. **No source change made** (no-op).
+
+**Residual:** A 100% confirmation still requires an authenticated runtime `GET /` against a
+deployed instance (the only path that exercises routing past the unauthenticated 302-to-`/login`).
+Recommend a spot-check of authenticated `GET /` after the next Server redeploy; if it returns 200
+(not 500), this item can be fully closed.
@@ -0,0 +1,116 @@
+# ForceSubtag Mode Fix Implementation Plan
+
+> Fixes the two defects surfaced by the D3 live validation (2026-06-15): forced-subtag
+> doesn't actually run subtag (#1), and the gateway never reflects a forced provider mode
+> into the gauge/feed (#2).
+
+**Goal:** Make `MxGateway:Alarms:Fallback:Mode=ForceSubtag` actually serve degraded subtag
+alarms AND have the gateway advertise `provider_mode=2` / degraded badge.
+
+**Evidence:** Live ForceSubtag run returned alarmmgr-sourced active alarms (May raise
+timestamps, `degraded=false`) and `provider_mode` stuck at 1, despite ForceSubtag binding
+(proven by invalid-value crash) and the deployed worker containing the ForcedMode routing
+(`3f5e5fc` ∈ `5976770`, worker dated 2026-06-14).
+
+---
+
+## Defect #2 (CONFIRMED code defect) — gateway never reflects forced mode
+
+**Root cause:** `GatewayAlarmMonitor.RunMonitorAsync` hard-baselines `_providerMode=Alarmmgr`
+and sets the gauge to 1, ignoring `_options.Fallback.Mode`. `_providerMode` only advances on a
+worker `OnAlarmProviderModeChanged` event, which is raised ONLY by `FailoverAlarmConsumer`
+(Auto mode). Forced-subtag builds `SubtagAlarmConsumer` directly → no event → gauge/feed stay
+Alarmmgr forever.
+
+### Task 2: Seed provider mode from configured forced mode (gateway, net10)
+**Classification:** small · **Parallelizable with:** none (precedes the diagnostic build)
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Alarms/GatewayAlarmMonitor.cs` (`RunMonitorAsync`, ~lines 160-172; add a permanent observability log in `SubscribeAlarmsAsync` ~line 257)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Alarms/GatewayAlarmMonitorProviderModeTests.cs`
+
+**Change:** in `RunMonitorAsync`, compute `initialMode = MapForcedMode(_options.Fallback.Mode)`
+mapped as `Subtag→Subtag`, `Alarmmgr→Alarmmgr`, `Unspecified→Alarmmgr` (Auto starts on the
+alarmmgr primary). Set `_providerMode/_providerDegraded(=Subtag)/_providerReason/_providerSince`
+and `_metrics.SetAlarmProviderMode(ModeToInt(initialMode))` — using the existing no-switch gauge
+seam so `provider_switches` does NOT increment. Add a log in `SubscribeAlarmsAsync`:
+`"Alarm subscribe forcedMode={ForcedMode} (configMode={ConfigMode}) watchList={Count}"`.
+
+**Tests (fake-worker, no MXAccess):** with `Fallback:Mode=ForceSubtag` assert (a) first
+`StreamAlarms` message is `ProviderStatus{Mode=Subtag,Degraded=true}`; (b) gauge==2; (c)
+`provider_switches`==0. Add `ForceAlarmManager`→gauge 1 and `Auto`→gauge 1 baseline cases.
+
+**Verify:** `dotnet build src/ZB.MOM.WW.MxGateway.Server`; `dotnet test src/ZB.MOM.WW.MxGateway.Tests --filter FullyQualifiedName~GatewayAlarmMonitorProviderMode`.
+
+---
+
+## Defect #1 (runtime bug — needs diagnosis) — ForceSubtag runs alarmmgr
+
+The HEAD source path (gateway `MapForcedMode` → `SubscribeAlarmsCommand.ForcedMode=Subtag` →
+IPC → worker `AlarmCommandHandler.BuildConsumer` → `SubtagAlarmConsumer`) is statically correct,
+yet the runtime ran alarmmgr. A runtime diagnostic must locate where `forcedMode` becomes
+`Unspecified`.
+
+### Task 1: Add worker BuildConsumer observability log (worker, net48 x86)
+**Classification:** small (net48 — no init-only props) · **Parallelizable with:** Task 2
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmCommandHandler.cs` (`BuildConsumer`, ~line 206)
+
+**Change:** log at entry of `BuildConsumer`:
+`"BuildConsumer forcedMode={ForcedMode} watchList={Count}"`. This is permanent observability.
+
+**Verify (windev only):** `dotnet build src/ZB.MOM.WW.MxGateway.Worker -p:Platform=x86`.
+
+### Task 3: Diagnostic run — capture the real forcedMode
+**Classification:** standard (ops/diagnostic on windev) · **Parallelizable with:** none
+**Steps:** rebuild worker (x86) + server from the branch, stand up the D3-style temp ForceSubtag
+instance (alt ports 5122/5132, isolated `.D3` worker name, WMI-detached, Http2, Development env
+for file logs), trigger the always-on monitor, and read the two new log lines:
+- Gateway `Alarm subscribe forcedMode=...` — what the gateway SENDS.
+- Worker `BuildConsumer forcedMode=...` — what the worker RECEIVES.
+
+Decision matrix:
+- Gateway logs `Subtag`, worker logs `Unspecified` → IPC/serialization drops the enum → fix the
+  send/translation path (likely a worker-proto vs gateway-proto `SubscribeAlarmsCommand` mismatch
+  in the named-pipe envelope).
+- Worker logs `Subtag` but alarmmgr data appears → bug in `BuildStandby`/`SubtagAlarmConsumer`/
+  `AlarmDispatcher` snapshot path.
+- Gateway logs `Unspecified` despite config ForceSubtag → gateway config/options read.
+
+### Task 4: Fix #1 per Task 3 diagnosis
+**Classification:** standard/high-risk (depends on where the defect is) · the exact change is
+determined by Task 3. Add a regression test at the identified layer (worker unit test for
+BuildConsumer→SubtagAlarmConsumer, or a contract/IPC round-trip test if the enum is dropped).
+
+---
+
+## Final: build, test, redeploy, re-validate
+- Build gateway (macOS) + worker (windev x86); run gateway + worker test suites.
+- Redeploy windev Server (and Worker if Task 4 changed it) per `project_deploy_mechanics`,
+  preserving appsettings.
+- Re-validate live with the temp ForceSubtag instance: active alarms `degraded=true` /
+  `source_provider=SUBTAG` with recent timestamps, `provider_mode 2`. Tear down temp instance;
+  production untouched.
+
+## Execution note
+Branch off `main`. #2 is the clean confirmed fix; #1 is diagnose-then-fix. Net48 worker
+constraints apply (no init-only props/positional records). Do NOT increment `provider_switches`
+on an initial forced-mode set.
+
+---
+
+## Resolution (2026-06-15)
+
+**#1 was NOT a bug — it was a grpcurl proto-mismatch artifact.** End-to-end instrumentation
+proved: the gateway sends `forcedMode=Subtag`, the worker's `BuildConsumer` builds the
+`SubtagAlarmConsumer`, and the worker `QueryActive` + gateway `ApplyReconcile`/`StreamAlarms`
+all carry `degraded=true` / `source_provider=SUBTAG`. The original "degraded=false" observation
+came from running grpcurl against the host checkout's proto (branch `feat/lazy-browse-children`),
+which predates the feature and lacks the `degraded`/`source_provider` fields — grpcurl silently
+dropped them. With the matching proto, every active alarm shows `degraded=true`. No code change.
+Tasks 1/3/4 (worker diagnostics + #1 fix) were dropped; the temporary diagnostics were reverted.
+
+**#2 was a real defect — fixed.** Gateway now seeds `_providerMode`/gauge/feed from the configured
+forced mode (`fix: gateway reflects configured forced provider mode`). Verified live:
+`provider_mode=2`, first `ProviderStatus` = `Mode=Subtag, degraded=true,
+reason="Forced subtag mode (configuration)"`. Auto mode unchanged → windev production (Auto)
+unaffected; no redeploy required. Gateway tests: 163 passed.
@@ -188,8 +188,12 @@ used as before.
 `OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto fields. The
 `AlarmFeedMessage` feed emits an `AlarmProviderStatus` message (the
 `provider_status` oneof case) on stream open and on every switch. The
-dashboard shows a Bootstrap badge (green for alarm manager, amber when
-degraded). Metrics: `mxgateway.alarms.provider_mode` gauge (1 = alarmmgr,
+dashboard shows a Bootstrap badge: green ("Alarm Manager") when healthy, amber
+("Subtag monitoring (degraded)") on an unexpected failover, and cyan ("Subtag
+monitoring (forced)") when subtag mode is the configured `Fallback:Mode=ForceSubtag`
+— the latter distinguished by the well-known `AlarmProviderStatus.reason`
+(`AlarmProviderReasons.ForcedSubtag`) so an intentional configuration is not shown
+as a fault. Metrics: `mxgateway.alarms.provider_mode` gauge (1 = alarmmgr,
 2 = subtag) and `mxgateway.alarms.provider_switches` counter.

 Forced modes are available via `MxGateway:Alarms:Fallback:Mode`:
@@ -39,10 +39,14 @@ if ($Version -notmatch '^v\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?$') {
 $tag = "clients/go/$Version"
 Write-Host "Creating Go-module tag: $tag" -ForegroundColor Cyan

-# Verify we're on a clean checkout — refuse to tag with uncommitted changes.
-$status = (git status --porcelain) -join "`n"
-if ($status -and -not ($status -match '^\?\?')) {
-    throw "Working tree has tracked changes. Commit or stash before tagging."
+# Verify we're on a clean checkout — refuse to tag with uncommitted tracked
+# changes. Test each porcelain line individually: any entry that is not an
+# untracked file (`??`) is a tracked change, regardless of how the entries
+# happen to sort. Joining and anchoring `^\?\?` against the whole blob would
+# only inspect the first line and miss tracked changes behind an untracked one.
+$dirty = (git status --porcelain) | Where-Object { $_ -and ($_ -notmatch '^\?\?') }
+if ($dirty) {
+    throw "Working tree has tracked changes. Commit or stash before tagging.`n$($dirty -join "`n")"
 }

 # Verify the tag doesn't already exist.
@@ -668,8 +668,15 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
  }

  /// <summary>
-  /// Provider selection / current provider for the alarm feed. UNSPECIFIED on a
-  /// SubscribeAlarmsCommand means auto: alarmmgr primary with subtag fallback.
+  /// Provider selection / current provider for the alarm feed. The zero value
+  /// has two distinct meanings depending on the use site:
+  ///   - As SubscribeAlarmsCommand.forced_mode, UNSPECIFIED means auto: alarmmgr
+  ///     primary with subtag fallback.
+  ///   - As a provenance value (OnAlarmTransitionEvent.source_provider,
+  ///     ActiveAlarmSnapshot.source_provider, OnAlarmProviderModeChangedEvent.mode,
+  ///     AlarmProviderStatus.mode), the worker always emits ALARMMGR or SUBTAG and
+  ///     never UNSPECIFIED; clients should treat a UNSPECIFIED provenance value as
+  ///     "unknown / not yet determined".
  /// </summary>
  public enum AlarmProviderMode {
    [pbr::OriginalName("ALARM_PROVIDER_MODE_UNSPECIFIED")] Unspecified = 0,
@@ -26528,6 +26535,12 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
    /// <summary>Field number for the "degraded" field.</summary>
    public const int DegradedFieldNumber = 14;
    private bool degraded_;
+    /// <summary>
+    /// True when this snapshot came from the subtag-monitoring fallback rather
+    /// than the native alarmmgr provider — synthesized from data changes, reduced
+    /// fidelity (synthetic GUID, no native raise time). Mirrors
+    /// OnAlarmTransitionEvent.degraded.
+    /// </summary>
    [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
    [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)]
    public bool Degraded {
@@ -26540,6 +26553,11 @@ namespace ZB.MOM.WW.MxGateway.Contracts.Proto {
    /// <summary>Field number for the "source_provider" field.</summary>
    public const int SourceProviderFieldNumber = 15;
    private global::ZB.MOM.WW.MxGateway.Contracts.Proto.AlarmProviderMode sourceProvider_ = global::ZB.MOM.WW.MxGateway.Contracts.Proto.AlarmProviderMode.Unspecified;
+    /// <summary>
+    /// Which provider produced this snapshot. Mirrors
+    /// OnAlarmTransitionEvent.source_provider; always ALARMMGR or SUBTAG on the
+    /// wire (never UNSPECIFIED).
+    /// </summary>
    [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
    [global::System.CodeDom.Compiler.GeneratedCode("protoc", null)]
    public global::ZB.MOM.WW.MxGateway.Contracts.Proto.AlarmProviderMode SourceProvider {
@@ -315,8 +315,15 @@ message SubscribeBulkCommand {
  repeated string tag_addresses = 2;
 }

-// Provider selection / current provider for the alarm feed. UNSPECIFIED on a
-// SubscribeAlarmsCommand means auto: alarmmgr primary with subtag fallback.
+// Provider selection / current provider for the alarm feed. The zero value
+// has two distinct meanings depending on the use site:
+//   - As SubscribeAlarmsCommand.forced_mode, UNSPECIFIED means auto: alarmmgr
+//     primary with subtag fallback.
+//   - As a provenance value (OnAlarmTransitionEvent.source_provider,
+//     ActiveAlarmSnapshot.source_provider, OnAlarmProviderModeChangedEvent.mode,
+//     AlarmProviderStatus.mode), the worker always emits ALARMMGR or SUBTAG and
+//     never UNSPECIFIED; clients should treat a UNSPECIFIED provenance value as
+//     "unknown / not yet determined".
 enum AlarmProviderMode {
  ALARM_PROVIDER_MODE_UNSPECIFIED = 0;
  ALARM_PROVIDER_MODE_ALARMMGR = 1;
@@ -847,7 +854,14 @@ message ActiveAlarmSnapshot {
  string operator_comment = 11;
  MxValue current_value = 12;
  MxValue limit_value = 13;
+  // True when this snapshot came from the subtag-monitoring fallback rather
+  // than the native alarmmgr provider — synthesized from data changes, reduced
+  // fidelity (synthetic GUID, no native raise time). Mirrors
+  // OnAlarmTransitionEvent.degraded.
  bool degraded = 14;
+  // Which provider produced this snapshot. Mirrors
+  // OnAlarmTransitionEvent.source_provider; always ALARMMGR or SUBTAG on the
+  // wire (never UNSPECIFIED).
  AlarmProviderMode source_provider = 15;
 }

@@ -7,7 +7,7 @@
  <PropertyGroup>
    <IsPackable>true</IsPackable>
    <PackageId>ZB.MOM.WW.MxGateway.Contracts</PackageId>
-    <Version>0.1.0</Version>
+    <Version>0.1.1</Version>
    <Authors>Joseph Doherty</Authors>
    <Company>ZB MOM WW</Company>
    <Copyright>Copyright (c) ZB MOM WW. All rights reserved.</Copyright>
@@ -1,4 +1,5 @@
 using System.Security.Claims;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
@@ -137,26 +138,35 @@ public sealed class DashboardLdapLiveTests
    }

    /// <summary>
-    /// Builds the shared library <see cref="LibraryLdapOptions"/> from the gateway's
-    /// default LDAP settings so the live tests exercise the same seeded directory the
-    /// gateway connects to (localhost:3893, plaintext, with AllowInsecure for dev).
+    /// Builds the shared library <see cref="LibraryLdapOptions"/> by binding the real
+    /// <c>MxGateway:Ldap</c> configuration section the same way production does in
+    /// <c>AddZbLdapAuth(configuration, "MxGateway:Ldap")</c>, rather than hand-copying the
+    /// gateway shadow <c>LdapOptions</c> defaults field by field (IntegrationTests-028).
+    /// Binding the section directly onto the shared type means the live tests exercise the
+    /// exact option-binding path production uses, pick up every shared field (including
+    /// <see cref="LibraryLdapOptions.ConnectionTimeoutMs"/>, which governs the
+    /// unreachable-server test's timing) at whatever value the operator configured, and
+    /// cannot silently drop a field added to the shared type. The gateway's
+    /// <c>appsettings.json</c> seeds the dev directory connection (localhost:3893,
+    /// plaintext, AllowInsecure).
    /// </summary>
    private static LibraryLdapOptions LibraryOptions()
    {
-        ZB.MOM.WW.MxGateway.Server.Configuration.LdapOptions gateway = new();
-        return new LibraryLdapOptions
-        {
-            Enabled = gateway.Enabled,
-            Server = gateway.Server,
-            Port = gateway.Port,
-            Transport = gateway.Transport,
-            AllowInsecure = gateway.AllowInsecure,
-            SearchBase = gateway.SearchBase,
-            ServiceAccountDn = gateway.ServiceAccountDn,
-            ServiceAccountPassword = gateway.ServiceAccountPassword,
-            UserNameAttribute = gateway.UserNameAttribute,
-            DisplayNameAttribute = gateway.DisplayNameAttribute,
-            GroupAttribute = gateway.GroupAttribute,
-        };
+        string repositoryRoot = IntegrationTestEnvironment.ResolveRepositoryRoot(AppContext.BaseDirectory);
+        string appSettingsPath = Path.Combine(
+            repositoryRoot,
+            "src",
+            "ZB.MOM.WW.MxGateway.Server",
+            "appsettings.json");
+
+        IConfiguration configuration = new ConfigurationBuilder()
+            .AddJsonFile(appSettingsPath, optional: false)
+            .Build();
+
+        // Same section production binds in AddZbLdapAuth(configuration, "MxGateway:Ldap").
+        // Get<T> returns null only when the section is absent; appsettings.json always
+        // carries it, so fall back to shared defaults defensively rather than throw.
+        return configuration.GetSection("MxGateway:Ldap").Get<LibraryLdapOptions>()
+            ?? new LibraryLdapOptions();
    }
 }
@@ -0,0 +1,35 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Server.Alarms;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.IntegrationTests.TestSupport;
+
+/// <summary>
+/// No-op <see cref="IAlarmWatchListResolver"/> for integration tests that
+/// construct a <see cref="GatewayAlarmMonitor"/> only to satisfy the
+/// <see cref="ZB.MOM.WW.MxGateway.Server.Grpc.MxAccessGatewayService"/>
+/// constructor. The live MXAccess smoke tests never exercise the alarm
+/// monitor, so the resolver always yields an empty watch-list rather than
+/// touching the Galaxy Repository the production
+/// <see cref="AlarmWatchListResolver"/> requires. Singleton because the type
+/// holds no state — every consumer can share <see cref="Instance"/>.
+/// </summary>
+public sealed class EmptyAlarmWatchListResolver : IAlarmWatchListResolver
+{
+    /// <summary>Shared no-op instance.</summary>
+    public static readonly EmptyAlarmWatchListResolver Instance = new();
+
+    private static readonly IReadOnlyList<AlarmSubtagTarget> Empty = [];
+
+    private EmptyAlarmWatchListResolver()
+    {
+    }
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<AlarmSubtagTarget>> ResolveAsync(
+        AlarmsOptions options,
+        CancellationToken cancellationToken = default)
+    {
+        return Task.FromResult(Empty);
+    }
+}
@@ -1097,6 +1097,8 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
                _loggerFactory.CreateLogger<MxAccessGatewayService>(),
                new ZB.MOM.WW.MxGateway.Server.Alarms.GatewayAlarmMonitor(
                    sessionManager,
+                    EmptyAlarmWatchListResolver.Instance,
+                    _metrics,
                    options,
                    _loggerFactory.CreateLogger<ZB.MOM.WW.MxGateway.Server.Alarms.GatewayAlarmMonitor>()));
        }
@@ -12,6 +12,22 @@
    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
  </ItemGroup>

+  <!--
+    DashboardLdapLiveTests directly references the shared LDAP provider's public
+    types (LdapAuthService / LdapOptions), so declare direct dependencies rather
+    than rely on the transitive flow through the Server ProjectReference
+    (IntegrationTests-027). Versions match the Server's pinned 0.1.2. The
+    configuration packages back the production-fidelity MxGateway:Ldap binding the
+    live-test fixture uses in place of the old field-by-field hand-copy
+    (IntegrationTests-028).
+  -->
+  <ItemGroup>
+    <PackageReference Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.2" />
+    <PackageReference Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.2" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.7" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.7" />
+  </ItemGroup>
+
  <ItemGroup>
    <Using Include="Xunit" />
  </ItemGroup>
@@ -0,0 +1,18 @@
+namespace ZB.MOM.WW.MxGateway.Server.Alarms;
+
+/// <summary>
+///     Well-known <c>reason</c> strings carried on the alarm feed's
+///     <c>AlarmProviderStatus</c> message. Shared between the producer
+///     (<see cref="GatewayAlarmMonitor" />) and consumers (e.g. the dashboard
+///     provider badge) so the two cannot drift on a magic string.
+/// </summary>
+public static class AlarmProviderReasons
+{
+    /// <summary>
+    ///     Reason set when the monitor starts in subtag mode because
+    ///     <c>MxGateway:Alarms:Fallback:Mode</c> is <c>ForceSubtag</c> — a
+    ///     deliberate configuration, not a runtime failover. Lets the dashboard
+    ///     distinguish a forced subtag mode from an unexpected degraded failover.
+    /// </summary>
+    public const string ForcedSubtag = "Forced subtag mode (configuration)";
+}
@@ -13,7 +13,11 @@ namespace ZB.MOM.WW.MxGateway.Server.Alarms;
 // NOTE: The exact subtag names and the canonical AlarmFullReference shape
 // ("Galaxy!{area}.{reference}") are validated against a live Galaxy in the
 // Task 17 live smoke test. The config Subtags block exists precisely so these
-// names are not hard-coded here.
+// names are not hard-coded here. The {area} is the alarm object's REAL Galaxy
+// area discovered via gobject.area_gobject_id (the alarm group the native
+// alarmmgr emits), giving exact reference parity with wnwrap. The configured
+// Discovery.Area/DefaultArea is only the fallback for explicit IncludeAttributes
+// entries, which carry no discovered area.
 public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
 {
    private const string ProviderLiteral = "Galaxy";
@@ -43,9 +47,16 @@ public sealed class AlarmWatchListResolver : IAlarmWatchListResolver

        AlarmDiscoveryOptions discovery = options.Fallback.Discovery;

+        // Config fallback area used only for explicit IncludeAttributes entries (which
+        // carry no discovered area): discovery area, else the default area (may be empty).
+        string configFallbackArea = string.IsNullOrEmpty(discovery.Area) ? options.DefaultArea : discovery.Area;
+
        // 1. Build the ordered, de-duplicated attribute reference set.
-        //    Each entry carries the reference plus the source-object reference.
-        List<(string Reference, string SourceObject)> ordered = [];
+        //    Each entry carries the reference, the source-object reference, and the
+        //    per-entry area used to compose the canonical reference. GR rows contribute
+        //    the object's real Galaxy area; config includes contribute the config
+        //    fallback area (Discovery.Area else DefaultArea).
+        List<(string Reference, string SourceObject, string Area)> ordered = [];
        HashSet<string> seen = new(StringComparer.OrdinalIgnoreCase);

        if (discovery.UseGalaxyRepository)
@@ -55,11 +66,13 @@ public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
            {
                rows = await _repository.GetAlarmAttributesAsync(cancellationToken).ConfigureAwait(false);
            }
-            catch (Exception ex)
+            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                // Discovery being unavailable must not crash the resolver: log and
                // continue with an empty discovery set. The caller decides what to
-                // do with the (possibly config-only) result.
+                // do with the (possibly config-only) result. Cancellation is the one
+                // exception — an OperationCanceledException propagates per the
+                // IAlarmWatchListResolver contract so the caller unwinds promptly.
                _logger.LogWarning(
                    ex,
                    "Galaxy Repository alarm-attribute discovery failed; continuing with configuration-only watch-list.");
@@ -73,7 +86,7 @@ public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
                    continue;
                }

-                ordered.Add((row.FullTagReference, row.SourceObjectReference));
+                ordered.Add((row.FullTagReference, row.SourceObjectReference, row.Area));
            }
        }

@@ -84,7 +97,7 @@ public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
                continue;
            }

-            ordered.Add((include, DeriveSourceObject(include)));
+            ordered.Add((include, DeriveSourceObject(include), configFallbackArea));
        }

        // Remove excluded references (case-insensitive), but only when GR discovery
@@ -112,12 +125,11 @@ public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
        string priority = options.Fallback.Subtags.Priority;
        string ackComment = options.Fallback.Subtags.AckComment;

-        // 3. Resolve the area: discovery area, else the default area (may be empty).
-        string area = string.IsNullOrEmpty(discovery.Area) ? options.DefaultArea : discovery.Area;
-
-        // 4. Compose one target per reference.
+        // 3. Compose one target per reference, using the PER-ENTRY area: the GR row's
+        //    real Galaxy area (matching the alarmmgr group), or the config fallback for
+        //    explicit includes.
        List<AlarmSubtagTarget> targets = new(ordered.Count);
-        foreach ((string reference, string sourceObject) in ordered)
+        foreach ((string reference, string sourceObject, string area) in ordered)
        {
            targets.Add(new AlarmSubtagTarget
            {
@@ -130,7 +142,7 @@ public sealed class AlarmWatchListResolver : IAlarmWatchListResolver
            });
        }

-        // 5. Report the resolved count; warn when subtag mode was expected to cover
+        // 4. Report the resolved count; warn when subtag mode was expected to cover
        //    something (GR enabled, or explicit includes were configured) but resolved
        //    to nothing. Only emit the Debug line when there is at least one target,
        //    to avoid a confusing "0 target(s)" noise line.
@@ -157,19 +157,48 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
    private async Task RunMonitorAsync(string subscription, CancellationToken stoppingToken)
    {
        _state = GatewayAlarmMonitorState.Starting;
+
+        // Derive the lifecycle baseline from the configured forced mode so a
+        // ForceSubtag / ForceAlarmManager start advertises the correct mode even
+        // though no OnAlarmProviderModeChanged event is raised in those modes
+        // (only Auto/failover produces that event). ForceSubtag starts degraded.
+        AlarmProviderMode initialMode;
+        bool initialDegraded;
+        string initialReason;
+        switch (MapForcedMode(_options.Fallback.Mode))
+        {
+            case AlarmProviderMode.Subtag:
+                initialMode = AlarmProviderMode.Subtag;
+                initialDegraded = true;
+                initialReason = AlarmProviderReasons.ForcedSubtag;
+                break;
+            case AlarmProviderMode.Alarmmgr:
+                initialMode = AlarmProviderMode.Alarmmgr;
+                initialDegraded = false;
+                initialReason = string.Empty;
+                break;
+            default:
+                // Unspecified (Auto): the failover consumer starts on the
+                // alarm-manager primary and only degrades to subtag on failure.
+                initialMode = AlarmProviderMode.Alarmmgr;
+                initialDegraded = false;
+                initialReason = string.Empty;
+                break;
+        }
+
        lock (_sync)
        {
            // Re-baseline the provider status for this lifecycle so a restarted
-            // monitor advertises alarm-manager/not-degraded until told otherwise.
-            _providerMode = AlarmProviderMode.Alarmmgr;
-            _providerDegraded = false;
-            _providerReason = string.Empty;
+            // monitor advertises the configured mode until told otherwise.
+            _providerMode = initialMode;
+            _providerDegraded = initialDegraded;
+            _providerReason = initialReason;
            _providerSince = DateTimeOffset.UtcNow;
        }

-        // Align the observable gauge with the Alarmmgr baseline without recording
+        // Align the observable gauge with the lifecycle baseline without recording
        // a switch — the gauge was 0 (unknown) from construction until now.
-        _metrics.SetAlarmProviderMode(ModeToInt(AlarmProviderMode.Alarmmgr));
+        _metrics.SetAlarmProviderMode(ModeToInt(initialMode));

        GatewaySession session = await _sessionManager.OpenSessionAsync(
                new SessionOpenRequest(BackendName, MonitorClientName, Guid.NewGuid().ToString("N"), CommandTimeout: null),
@@ -256,6 +285,10 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic

        AlarmProviderMode forcedMode = MapForcedMode(_options.Fallback.Mode);

+        _logger.LogInformation(
+            "Alarm subscribe: forcedMode={ForcedMode} configMode={ConfigMode} watchList={WatchListCount}.",
+            forcedMode, _options.Fallback.Mode, watchList.Count);
+
        // When the forced mode is Unspecified (the "Auto" case) and the resolved
        // watch-list is empty — the common alarmmgr-only deployment — the command
        // is identical-in-effect to the historical SubscribeAlarms (wnwrap only):
@@ -399,7 +432,13 @@ public sealed class GatewayAlarmMonitor : BackgroundService, IGatewayAlarmServic
            BroadcastToAll(new AlarmFeedMessage { ProviderStatus = status });
        }

-        _metrics.AlarmProviderSwitched(fromModeInt, ModeToInt(toMode), reason);
+        AlarmProviderSwitchReason switchReason = toMode switch
+        {
+            AlarmProviderMode.Subtag => AlarmProviderSwitchReason.Failover,
+            AlarmProviderMode.Alarmmgr => AlarmProviderSwitchReason.Failback,
+            _ => AlarmProviderSwitchReason.Unknown,
+        };
+        _metrics.AlarmProviderSwitched(fromModeInt, ModeToInt(toMode), switchReason);

        _logger.LogInformation(
            "Alarm provider mode changed to {Mode} (degraded={Degraded}): {Reason}",
@@ -19,8 +19,10 @@ public interface IAlarmWatchListResolver
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    /// <returns>
    ///     The resolved <see cref="AlarmSubtagTarget"/> watch-list, possibly empty.
-    ///     Discovery being unavailable never throws; the caller decides what to do
-    ///     with an empty list.
+    ///     Discovery being unavailable never throws — it yields an empty (or
+    ///     config-only) list and the caller decides what to do with it. Cancellation
+    ///     is the one exception: a triggered <paramref name="cancellationToken"/>
+    ///     still propagates an <see cref="OperationCanceledException"/>.
    /// </returns>
    Task<IReadOnlyList<AlarmSubtagTarget>> ResolveAsync(
        AlarmsOptions options,
@@ -86,7 +86,10 @@ public sealed class AlarmDiscoveryOptions
    public string[] IncludeAttributes { get; init; } = Array.Empty<string>();

    /// <summary>
-    ///     Attribute paths to exclude from the Repository-derived poll list.
+    ///     Attribute paths to remove from the merged poll list (case-insensitive).
+    ///     The exclude runs after the Repository-derived rows and the explicit
+    ///     <see cref="IncludeAttributes"/> entries are combined, so an exclude that
+    ///     matches an explicit include suppresses it too — excludes win.
    ///     Ignored when <see cref="UseGalaxyRepository"/> is <c>false</c>.
    ///     Default empty.
    /// </summary>
@@ -1,4 +1,5 @@
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Server.Alarms;

 namespace ZB.MOM.WW.MxGateway.Server.Dashboard;

@@ -22,9 +23,20 @@ public sealed record DashboardAlarmProviderStatus(
    /// <summary>Badge label shown when the feed has fallen back to subtag monitoring.</summary>
    public const string DegradedLabel = "Subtag monitoring (degraded)";

+    /// <summary>
+    ///     Badge label shown when the feed is in subtag monitoring because it was
+    ///     deliberately configured (<c>Fallback:Mode=ForceSubtag</c>), as opposed
+    ///     to an unexpected failover. A stable, intended state rather than a fault.
+    /// </summary>
+    public const string ForcedSubtagLabel = "Subtag monitoring (forced)";
+
    private const string HealthyBadge = "bg-success";
    private const string DegradedBadge = "bg-warning text-dark";

+    // Cyan/info badge: visually distinct from the amber failover-degraded badge —
+    // forced subtag is an intentional configuration, not an alarm-manager fault.
+    private const string ForcedSubtagBadge = "bg-info text-dark";
+
    /// <summary>
    ///     The default status assumed before the first provider-status message
    ///     arrives: healthy alarm-manager mode.
@@ -48,13 +60,24 @@ public sealed record DashboardAlarmProviderStatus(
        // the contract sets degraded=true whenever mode == SUBTAG, but guard
        // against either being set independently.
        bool degraded = status.Degraded || status.Mode == AlarmProviderMode.Subtag;
+        string reason = status.Reason ?? string.Empty;
+
+        // A configured ForceSubtag start carries the well-known forced reason and
+        // is a deliberate mode, not a failover — render it distinctly so an
+        // operator isn't alarmed by a "(degraded)" badge for an intended config.
+        bool forced = degraded
+            && status.Mode == AlarmProviderMode.Subtag
+            && string.Equals(reason, AlarmProviderReasons.ForcedSubtag, StringComparison.Ordinal);
+
+        string label = !degraded ? AlarmManagerLabel : forced ? ForcedSubtagLabel : DegradedLabel;
+        string badge = !degraded ? HealthyBadge : forced ? ForcedSubtagBadge : DegradedBadge;

        return new DashboardAlarmProviderStatus(
            Mode: status.Mode,
            IsDegraded: degraded,
-            Label: degraded ? DegradedLabel : AlarmManagerLabel,
-            BadgeCssClass: degraded ? DegradedBadge : HealthyBadge,
-            Reason: status.Reason ?? string.Empty,
+            Label: label,
+            BadgeCssClass: badge,
+            Reason: reason,
            SinceUtc: status.Since?.ToDateTimeOffset());
    }

@@ -195,6 +195,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
            new("mxgateway.workers.exited", snapshot.WorkerExits),
            new("mxgateway.heartbeats.failed", snapshot.HeartbeatFailures),
            new("mxgateway.grpc.streams.disconnected", snapshot.StreamDisconnects),
+            new("mxgateway.alarms.provider_switches", snapshot.AlarmProviderSwitchCount),
        ];

        metrics.AddRange(snapshot.CommandFailuresByMethod
@@ -23,6 +23,18 @@ public sealed class GalaxyAlarmAttributeRow
    /// </summary>
    public string SourceObjectReference { get; init; } = string.Empty;

+    /// <summary>
+    ///     Gets the owning object's Galaxy area (e.g. <c>TestArea</c>) — the alarm group.
+    ///     <para>
+    ///     Resolved via <c>gobject.area_gobject_id</c> in <c>AlarmAttributesSql</c>. The
+    ///     watch-list resolver composes the canonical <c>Galaxy!{area}.{reference}</c> from
+    ///     this so the synthesized reference's group matches the native alarmmgr (wnwrap)
+    ///     for reference parity. May be <see cref="string.Empty"/> when the object has no
+    ///     area; the resolver then falls back to the configured area.
+    ///     </para>
+    /// </summary>
+    public string Area { get; init; } = string.Empty;
+
    /// <summary>
    ///     Gets the writable ack-comment attribute address.
    ///     <para>
@@ -135,7 +135,8 @@ public sealed class GalaxyRepository(GalaxyRepositoryOptions options) : IGalaxyR
        {
            rows.Add(MapAlarmRow(
                fullTagReference: reader.GetString(0),
-                sourceObjectReference: reader.GetString(1)));
+                sourceObjectReference: reader.GetString(1),
+                area: reader.GetString(2)));
        }
        return rows;
    }
@@ -151,16 +152,23 @@ public sealed class GalaxyRepository(GalaxyRepositoryOptions options) : IGalaxyR
    ///     schema does not expose an ack-comment address and the watch-list resolver
    ///     composes it later.
    ///     </para>
+    ///     <paramref name="area"/> is the owning object's real Galaxy area (its alarm
+    ///     group), resolved via <c>gobject.area_gobject_id</c>; the watch-list resolver
+    ///     composes the canonical reference from it so the synthesized reference's group
+    ///     matches what the native alarmmgr (wnwrap) emits.
    ///     Exposed internally so the derivation can be unit-tested without a database.
    /// </summary>
    /// <param name="fullTagReference">The alarm-bearing attribute reference.</param>
    /// <param name="sourceObjectReference">The owning object reference (tag name).</param>
+    /// <param name="area">The owning object's Galaxy area (the alarm group).</param>
    internal static GalaxyAlarmAttributeRow MapAlarmRow(
        string fullTagReference,
-        string sourceObjectReference) => new()
+        string sourceObjectReference,
+        string area) => new()
        {
            FullTagReference = fullTagReference,
            SourceObjectReference = sourceObjectReference,
+            Area = area,
            AckCommentSubtag = string.Empty,
        };

@@ -300,14 +308,18 @@ LEFT JOIN data_type dt ON dt.mx_data_type = r.mx_data_type
 WHERE r.rn = 1
 ORDER BY r.tag_name, r.attribute_name";

-    // Alarm-only discovery for the subtag-fallback watch-list. This deliberately reuses the
-    // exact candidate/ranked CTE structure and the same `AlarmExtension`-based is_alarm
-    // detection as AttributesSql so the two queries cannot drift: a row qualifies only when
-    // its user attribute (src_pri 0) anchors an `AlarmExtension` primitive on the owning
-    // object. It projects just what the watch-list needs — full_tag_reference (tag_name +
+    // Alarm-only discovery for the subtag-fallback watch-list. This reuses the candidate/ranked
+    // CTE shape and the same `AlarmExtension`-based detection as AttributesSql. Unlike
+    // AttributesSql it keeps only the user-attribute (dynamic_attribute) candidate branch: an
+    // alarm anchor is always a user attribute, so the primitive-instance branch AttributesSql
+    // carries would be filtered out here anyway — a row qualifies only when its user attribute
+    // anchors an `AlarmExtension` primitive on the owning object. It projects just what the
+    // watch-list needs — full_tag_reference (tag_name +
    // '.' + attribute_name, matching AttributesSql) and the owning object's tag_name as
    // source_object_reference. The array `[]` suffix is intentionally omitted: an
-    // alarm-bearing attribute is a scalar anchor, not an array body.
+    // alarm-bearing attribute is a scalar anchor, not an array body. It also projects the
+    // owning object's real Galaxy area (via gobject.area_gobject_id) as area_name so the
+    // watch-list resolver composes a reference whose group matches the native alarmmgr.
    private const string AlarmAttributesSql = @"
 ;WITH deployed_package_chain AS (
    SELECT g.gobject_id, p.package_id, p.derived_from_package_id, 0 AS depth
@@ -322,7 +334,7 @@ ORDER BY r.tag_name, r.attribute_name";
 ),
 candidate AS (
    SELECT
-        dpc.gobject_id, g.tag_name, da.attribute_name, dpc.depth, 0 AS src_pri
+        dpc.gobject_id, g.tag_name, da.attribute_name, dpc.depth
    FROM deployed_package_chain dpc
    INNER JOIN dynamic_attribute da ON da.package_id = dpc.package_id
    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
@@ -331,33 +343,20 @@ candidate AS (
        AND da.attribute_name NOT LIKE '[_]%'
        AND da.attribute_name NOT LIKE '%.Description'
        AND da.mx_attribute_category IN (2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 24)
-    UNION ALL
-    SELECT
-        dpc.gobject_id, g.tag_name,
-        CASE WHEN pi.primitive_name IS NULL OR pi.primitive_name = ''
-             THEN ad.attribute_name
-             ELSE pi.primitive_name + '.' + ad.attribute_name END AS attribute_name,
-        dpc.depth, 1 AS src_pri
-    FROM deployed_package_chain dpc
-    INNER JOIN primitive_instance pi ON pi.package_id = dpc.package_id
-    INNER JOIN attribute_definition ad ON ad.primitive_definition_id = pi.primitive_definition_id
-    INNER JOIN gobject g ON g.gobject_id = dpc.gobject_id
-    INNER JOIN template_definition td ON td.template_definition_id = g.template_definition_id
-    WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
-        AND ad.attribute_name NOT LIKE '[_]%'
-        AND ad.attribute_name NOT LIKE '%.Description'
 ),
 ranked AS (
    SELECT c.*, ROW_NUMBER() OVER (
-        PARTITION BY c.gobject_id, c.attribute_name ORDER BY c.src_pri, c.depth) AS rn
+        PARTITION BY c.gobject_id, c.attribute_name ORDER BY c.depth) AS rn
    FROM candidate c
 )
 SELECT
    r.tag_name + '.' + r.attribute_name AS full_tag_reference,
-    r.tag_name AS source_object_reference
+    r.tag_name AS source_object_reference,
+    ISNULL(area.tag_name, '') AS area_name
 FROM ranked r
+INNER JOIN gobject g ON g.gobject_id = r.gobject_id
+LEFT JOIN gobject area ON area.gobject_id = g.area_gobject_id
 WHERE r.rn = 1
-    AND r.src_pri = 0
    AND EXISTS (
        SELECT 1 FROM deployed_package_chain dpc2
        INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = r.attribute_name
@@ -0,0 +1,20 @@
+namespace ZB.MOM.WW.MxGateway.Server.Metrics;
+
+/// <summary>
+///     Bounded classification of an alarm-provider switch, used as the low-cardinality
+///     <c>reason</c> tag on the <c>mxgateway.alarms.provider_switches</c> counter. The
+///     worker supplies a free-text reason (e.g. <c>"primary PollOnce failed"</c>) that
+///     stays in the structured log; only this bounded value reaches the metric tag so the
+///     time series cannot fan out on operation-specific text.
+/// </summary>
+public enum AlarmProviderSwitchReason
+{
+    /// <summary>The switch direction could not be classified.</summary>
+    Unknown = 0,
+
+    /// <summary>Switched from the primary (alarmmgr) provider to the subtag standby — degraded.</summary>
+    Failover = 1,
+
+    /// <summary>Switched back from the subtag standby to the primary (alarmmgr) provider — recovered.</summary>
+    Failback = 2,
+}
@@ -50,6 +50,7 @@ public sealed class GatewayMetrics : IDisposable
    private long _heartbeatFailures;
    private long _streamDisconnects;
    private long _retryAttempts;
+    private long _alarmProviderSwitches;
    private bool _disposed;

    /// <summary>
@@ -383,25 +384,34 @@ public sealed class GatewayMetrics : IDisposable
    }

    /// <summary>
-    /// Records that the alarm provider switched modes and updates the current provider mode gauge.
+    /// Records that the alarm provider switched modes, increments the switch count, and updates the
+    /// current provider mode gauge.
    /// </summary>
    /// <param name="fromMode">Provider mode before the switch (1=alarmmgr, 2=subtag, 0=unknown).</param>
    /// <param name="toMode">Provider mode after the switch (1=alarmmgr, 2=subtag, 0=unknown).</param>
-    /// <param name="reason">Human-readable reason for the switch.</param>
-    public void AlarmProviderSwitched(int fromMode, int toMode, string reason)
+    /// <param name="reason">Bounded switch classification used as the counter's <c>reason</c> tag.</param>
+    public void AlarmProviderSwitched(int fromMode, int toMode, AlarmProviderSwitchReason reason)
    {
        lock (_syncRoot)
        {
            _alarmProviderMode = toMode;
+            _alarmProviderSwitches++;
        }

        _alarmProviderSwitchesCounter.Add(
            1,
            new KeyValuePair<string, object?>("from", fromMode.ToString(CultureInfo.InvariantCulture)),
            new KeyValuePair<string, object?>("to", toMode.ToString(CultureInfo.InvariantCulture)),
-            new KeyValuePair<string, object?>("reason", reason));
+            new KeyValuePair<string, object?>("reason", ReasonTag(reason)));
    }

+    private static string ReasonTag(AlarmProviderSwitchReason reason) => reason switch
+    {
+        AlarmProviderSwitchReason.Failover => "failover",
+        AlarmProviderSwitchReason.Failback => "failback",
+        _ => "unknown",
+    };
+
    /// <summary>Sets the current alarm provider-mode gauge without recording a switch (e.g. startup baseline).</summary>
    public void SetAlarmProviderMode(int mode)
    {
@@ -433,6 +443,7 @@ public sealed class GatewayMetrics : IDisposable
                HeartbeatFailures: _heartbeatFailures,
                StreamDisconnects: _streamDisconnects,
                RetryAttempts: _retryAttempts,
+                AlarmProviderSwitchCount: _alarmProviderSwitches,
                CommandFailuresByMethod: new Dictionary<string, long>(_commandFailuresByMethod, StringComparer.OrdinalIgnoreCase),
                EventsByFamily: new Dictionary<string, long>(_eventsByFamily, StringComparer.OrdinalIgnoreCase),
                EventsBySession: new Dictionary<string, long>(_eventsBySession, StringComparer.Ordinal),
@@ -18,6 +18,7 @@ public sealed record GatewayMetricsSnapshot(
    long HeartbeatFailures,
    long StreamDisconnects,
    long RetryAttempts,
+    long AlarmProviderSwitchCount,
    IReadOnlyDictionary<string, long> CommandFailuresByMethod,
    IReadOnlyDictionary<string, long> EventsByFamily,
    IReadOnlyDictionary<string, long> EventsBySession,
@@ -312,21 +312,35 @@ public sealed class AlarmFailoverEndToEndTests
            WaitTimeout);

        // New subscriber: its initial cache snapshot must carry the degraded flags.
+        // Bound the drain so a regression that never emits SnapshotComplete fails
+        // with a clean TimeoutException (via cancellation) instead of hanging.
        using CancellationTokenSource newStreamCts = new();
+        using CancellationTokenSource drainTimeoutCts = new();
+        drainTimeoutCts.CancelAfter(WaitTimeout);
+        using CancellationTokenSource linkedDrainCts =
+            CancellationTokenSource.CreateLinkedTokenSource(newStreamCts.Token, drainTimeoutCts.Token);
        ActiveAlarmSnapshot? initialActiveAlarm = null;
-        await foreach (AlarmFeedMessage message in monitor.StreamAsync(null, newStreamCts.Token))
+        try
        {
-            if (message.PayloadCase == AlarmFeedMessage.PayloadOneofCase.ActiveAlarm
-                && message.ActiveAlarm.AlarmFullReference == "Galaxy!Area.Tank02.Lo")
+            await foreach (AlarmFeedMessage message in monitor.StreamAsync(null, linkedDrainCts.Token))
            {
-                initialActiveAlarm = message.ActiveAlarm;
-            }
+                if (message.PayloadCase == AlarmFeedMessage.PayloadOneofCase.ActiveAlarm
+                    && message.ActiveAlarm.AlarmFullReference == "Galaxy!Area.Tank02.Lo")
+                {
+                    initialActiveAlarm = message.ActiveAlarm;
+                }

-            if (message.PayloadCase == AlarmFeedMessage.PayloadOneofCase.SnapshotComplete)
-            {
-                break;
+                if (message.PayloadCase == AlarmFeedMessage.PayloadOneofCase.SnapshotComplete)
+                {
+                    break;
+                }
            }
        }
+        catch (OperationCanceledException) when (drainTimeoutCts.IsCancellationRequested)
+        {
+            throw new TimeoutException(
+                "The new subscriber did not receive a SnapshotComplete message within the timeout.");
+        }

        Assert.NotNull(initialActiveAlarm);
        Assert.True(initialActiveAlarm!.Degraded);
@@ -44,10 +44,10 @@ public sealed class AlarmWatchListResolverTests
    {
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank02.Level.HiHi", SourceObjectReference = "Tank02" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "TestArea" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank02.Level.HiHi", SourceObjectReference = "Tank02", Area = "TestArea" },
            // Duplicate of an include below (case-insensitive) — should appear once.
-            new GalaxyAlarmAttributeRow { FullTagReference = "Pump01.Fault", SourceObjectReference = "Pump01" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Pump01.Fault", SourceObjectReference = "Pump01", Area = "TestArea" },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);
@@ -68,7 +68,7 @@ public sealed class AlarmWatchListResolverTests
    {
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "TestArea" },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);
@@ -94,7 +94,7 @@ public sealed class AlarmWatchListResolverTests
    {
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "TestArea" },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);
@@ -111,27 +111,37 @@ public sealed class AlarmWatchListResolverTests
    }

    [Fact]
-    public async Task ResolveAsync_ComposesCanonicalFullReference_WithArea()
+    public async Task ResolveAsync_ComposesCanonicalFullReference_FromRealGalaxyArea_NotConfigArea()
    {
+        // The GR row carries the object's real Galaxy area (the alarmmgr group). The
+        // composed reference must use that area, NOT the configured Discovery.Area.
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
+            new GalaxyAlarmAttributeRow
+            {
+                FullTagReference = "TestMachine_001.TestAlarm001",
+                SourceObjectReference = "TestMachine_001",
+                Area = "TestArea",
+            },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);

-        IReadOnlyList<AlarmSubtagTarget> result = await resolver.ResolveAsync(Options(area: "Site_A"));
+        // Config area "DEV" must be ignored for a GR row that has a discovered area.
+        IReadOnlyList<AlarmSubtagTarget> result = await resolver.ResolveAsync(
+            Options(area: "DEV", defaultArea: "DEV"));

        AlarmSubtagTarget target = Assert.Single(result);
-        Assert.Equal("Galaxy!Site_A.Tank01.Level.HiHi", target.AlarmFullReference);
+        Assert.Equal("Galaxy!TestArea.TestMachine_001.TestAlarm001", target.AlarmFullReference);
    }

    [Fact]
    public async Task ResolveAsync_ComposesCanonicalFullReference_WithoutArea()
    {
+        // GR row with no discovered area and no config area -> bare Galaxy!{reference}.
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "" },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);
@@ -144,16 +154,34 @@ public sealed class AlarmWatchListResolverTests
    }

    [Fact]
-    public async Task ResolveAsync_FallsBackToDefaultArea_WhenDiscoveryAreaEmpty()
+    public async Task ResolveAsync_ConfigInclude_UsesDiscoveryAreaFallback()
    {
-        StubGalaxyRepository repo = new(
-        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
-        ]);
+        // A config IncludeAttributes entry has no discovered area, so it uses the
+        // config fallback: Discovery.Area when set.
+        StubGalaxyRepository repo = new([]);

        AlarmWatchListResolver resolver = CreateResolver(repo);

-        IReadOnlyList<AlarmSubtagTarget> result = await resolver.ResolveAsync(Options(area: "", defaultArea: "Plant"));
+        IReadOnlyList<AlarmSubtagTarget> result = await resolver.ResolveAsync(Options(
+            area: "Site_A",
+            include: ["Tank01.Level.HiHi"]));
+
+        AlarmSubtagTarget target = Assert.Single(result);
+        Assert.Equal("Galaxy!Site_A.Tank01.Level.HiHi", target.AlarmFullReference);
+    }
+
+    [Fact]
+    public async Task ResolveAsync_ConfigInclude_FallsBackToDefaultArea_WhenDiscoveryAreaEmpty()
+    {
+        // A config IncludeAttributes entry with no Discovery.Area uses DefaultArea.
+        StubGalaxyRepository repo = new([]);
+
+        AlarmWatchListResolver resolver = CreateResolver(repo);
+
+        IReadOnlyList<AlarmSubtagTarget> result = await resolver.ResolveAsync(Options(
+            area: "",
+            defaultArea: "Plant",
+            include: ["Tank01.Level.HiHi"]));

        AlarmSubtagTarget target = Assert.Single(result);
        Assert.Equal("Galaxy!Plant.Tank01.Level.HiHi", target.AlarmFullReference);
@@ -239,8 +267,8 @@ public sealed class AlarmWatchListResolverTests
    {
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank02.Level.HiHi", SourceObjectReference = "Tank02" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "TestArea" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank02.Level.HiHi", SourceObjectReference = "Tank02", Area = "TestArea" },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);
@@ -263,7 +291,7 @@ public sealed class AlarmWatchListResolverTests
    {
        StubGalaxyRepository repo = new(
        [
-            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01" },
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "TestArea" },
        ]);

        AlarmWatchListResolver resolver = CreateResolver(repo);
@@ -278,6 +306,56 @@ public sealed class AlarmWatchListResolverTests
        Assert.Contains("Tank01", target.ActiveSubtag, StringComparison.Ordinal);
    }

+    /// <summary>
+    ///     Server-051: a cancellation triggered while Galaxy Repository discovery is
+    ///     awaiting must propagate as <see cref="OperationCanceledException"/>, not be
+    ///     swallowed into a config-only watch-list, per the <see cref="IAlarmWatchListResolver"/>
+    ///     contract.
+    /// </summary>
+    [Fact]
+    public async Task ResolveAsync_RepositoryCancelled_PropagatesOperationCanceled()
+    {
+        using CancellationTokenSource cts = new();
+        // Repository observes the token, cancels the source, then throws the matching
+        // OperationCanceledException — exactly what the live SQL path does on shutdown.
+        CancellingGalaxyRepository repo = new(cts);
+
+        AlarmWatchListResolver resolver = CreateResolver(repo);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(() =>
+            resolver.ResolveAsync(
+                Options(include: ["Tank01.Level.HiHi"]),
+                cts.Token));
+    }
+
+    /// <summary>
+    ///     Server-052 item 2 / Server-053: an entry that appears in both
+    ///     <c>IncludeAttributes</c> and <c>ExcludeAttributes</c> is removed — excludes
+    ///     win over explicit includes (the documented "excludes also suppress matching
+    ///     explicit includes" behaviour).
+    /// </summary>
+    [Fact]
+    public async Task ResolveAsync_ExcludeAlsoSuppressesMatchingExplicitInclude()
+    {
+        StubGalaxyRepository repo = new(
+        [
+            new GalaxyAlarmAttributeRow { FullTagReference = "Tank01.Level.HiHi", SourceObjectReference = "Tank01", Area = "TestArea" },
+        ]);
+
+        AlarmWatchListResolver resolver = CreateResolver(repo);
+
+        // Pump01.Fault is an explicit include AND an exclude (case-insensitive). It must
+        // be dropped; the GR row Tank01 survives.
+        IReadOnlyList<AlarmSubtagTarget> result = await resolver.ResolveAsync(Options(
+            useGalaxyRepository: true,
+            include: ["Pump01.Fault"],
+            exclude: ["pump01.fault"]));
+
+        AlarmSubtagTarget target = Assert.Single(result);
+        Assert.Contains("Tank01", target.ActiveSubtag, StringComparison.Ordinal);
+        Assert.DoesNotContain(result, t => t.ActiveSubtag.Contains("Pump01", StringComparison.OrdinalIgnoreCase));
+    }
+
    /// <summary>In-memory <see cref="IGalaxyRepository"/> returning a fixed alarm rowset.</summary>
    private sealed class StubGalaxyRepository(List<GalaxyAlarmAttributeRow> rows) : IGalaxyRepository
    {
@@ -329,4 +407,35 @@ public sealed class AlarmWatchListResolverTests
        public Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default) =>
            Task.FromException<List<GalaxyAlarmAttributeRow>>(toThrow);
    }
+
+    /// <summary>
+    ///     <see cref="IGalaxyRepository"/> whose alarm-attribute query cancels the
+    ///     supplied source and throws a token-bound <see cref="OperationCanceledException"/>,
+    ///     mirroring the live SQL path being cancelled mid-await.
+    /// </summary>
+    private sealed class CancellingGalaxyRepository(CancellationTokenSource source) : IGalaxyRepository
+    {
+        /// <inheritdoc />
+        public Task<bool> TestConnectionAsync(CancellationToken ct = default) => Task.FromResult(true);
+
+        /// <inheritdoc />
+        public Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default) =>
+            Task.FromResult<DateTime?>(null);
+
+        /// <inheritdoc />
+        public Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default) =>
+            Task.FromResult(new List<GalaxyHierarchyRow>());
+
+        /// <inheritdoc />
+        public Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default) =>
+            Task.FromResult(new List<GalaxyAttributeRow>());
+
+        /// <inheritdoc />
+        public Task<List<GalaxyAlarmAttributeRow>> GetAlarmAttributesAsync(CancellationToken ct = default)
+        {
+            source.Cancel();
+            ct.ThrowIfCancellationRequested();
+            return Task.FromResult(new List<GalaxyAlarmAttributeRow>());
+        }
+    }
 }
@@ -120,6 +120,224 @@ public sealed class GatewayAlarmMonitorProviderModeTests
        await monitor.StopAsync(CancellationToken.None);
    }

+    /// <summary>
+    ///     Server-053: a redundant <c>OnAlarmProviderModeChanged</c> event whose target
+    ///     mode equals the current mode still records a provider switch. The worker is the
+    ///     authority on when a mode change occurred; the gateway does not second-guess it,
+    ///     so each event the worker emits increments <c>provider_switches</c> (no from==to
+    ///     suppression). This test pins that semantics so it cannot drift silently.
+    /// </summary>
+    [Fact]
+    public async Task ProviderModeChange_RepeatedSameMode_RecordsASwitchForEachEvent()
+    {
+        using GatewayMetrics metrics = new();
+        long switchCount = 0;
+        using MeterListener listener = new();
+        listener.InstrumentPublished = (instrument, meterListener) =>
+        {
+            if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                && instrument.Name == "mxgateway.alarms.provider_switches")
+            {
+                meterListener.EnableMeasurementEvents(instrument);
+            }
+        };
+        listener.SetMeasurementEventCallback<long>(
+            (instrument, measurement, _, _) =>
+            {
+                if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                    && instrument.Name == "mxgateway.alarms.provider_switches")
+                {
+                    Interlocked.Add(ref switchCount, measurement);
+                }
+            });
+        listener.Start();
+
+        FakeSessionManager sessions = new();
+        using GatewayAlarmMonitor monitor = CreateMonitor(sessions, metrics);
+
+        using CancellationTokenSource cts = new();
+        await monitor.StartAsync(cts.Token);
+        await sessions.WaitForSubscribeAsync(WaitTimeout);
+
+        List<AlarmFeedMessage> received = [];
+        TaskCompletionSource baselineReceived = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        using CancellationTokenSource streamCts = new();
+        Task reader = Task.Run(async () =>
+        {
+            try
+            {
+                await foreach (AlarmFeedMessage message in monitor.StreamAsync(null, streamCts.Token))
+                {
+                    lock (received)
+                    {
+                        received.Add(message);
+                        if (received.Count == 1)
+                        {
+                            baselineReceived.TrySetResult();
+                        }
+                    }
+                }
+            }
+            catch (OperationCanceledException)
+            {
+                // Expected when the test cancels the stream.
+            }
+        });
+
+        await baselineReceived.Task.WaitAsync(WaitTimeout);
+
+        // First subtag-mode event.
+        sessions.EmitEvent(new MxEvent
+        {
+            OnAlarmProviderModeChanged = new OnAlarmProviderModeChangedEvent
+            {
+                Mode = AlarmProviderMode.Subtag,
+                Reason = "alarmmgr failed",
+                At = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+            },
+        });
+        await WaitUntilAsync(() => Interlocked.Read(ref switchCount) >= 1, WaitTimeout);
+
+        // Second subtag-mode event — same mode, but still a worker-reported switch.
+        sessions.EmitEvent(new MxEvent
+        {
+            OnAlarmProviderModeChanged = new OnAlarmProviderModeChangedEvent
+            {
+                Mode = AlarmProviderMode.Subtag,
+                Reason = "still degraded",
+                At = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+            },
+        });
+        await WaitUntilAsync(() => Interlocked.Read(ref switchCount) >= 2, WaitTimeout);
+
+        Assert.Equal(2, Interlocked.Read(ref switchCount));
+
+        await streamCts.CancelAsync();
+        await reader;
+        await cts.CancelAsync();
+        await monitor.StopAsync(CancellationToken.None);
+    }
+
+    /// <summary>
+    ///     Tests-032: pins the monitor's <c>toMode → AlarmProviderSwitchReason</c>
+    ///     derivation (<c>GatewayAlarmMonitor.ApplyProviderModeChangeAsync</c>): an
+    ///     alarmmgr→subtag change must emit <c>reason=failover</c> and a subtag→alarmmgr
+    ///     change must emit <c>reason=failback</c>. Captures the <c>reason</c> tag off the
+    ///     <c>mxgateway.alarms.provider_switches</c> counter — a regression that swapped
+    ///     the Failover/Failback arms or collapsed them to Unknown would be caught here,
+    ///     whereas the count-only tests above would still pass.
+    /// </summary>
+    [Fact]
+    public async Task ProviderModeChange_FailoverThenFailback_RecordsCorrectReasonTags()
+    {
+        using GatewayMetrics metrics = new();
+        List<string> capturedReasons = [];
+        using MeterListener listener = new();
+        listener.InstrumentPublished = (instrument, meterListener) =>
+        {
+            if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                && instrument.Name == "mxgateway.alarms.provider_switches")
+            {
+                meterListener.EnableMeasurementEvents(instrument);
+            }
+        };
+        listener.SetMeasurementEventCallback<long>(
+            (instrument, _, tags, _) =>
+            {
+                if (!ReferenceEquals(instrument.Meter, metrics.Meter)
+                    || instrument.Name != "mxgateway.alarms.provider_switches")
+                {
+                    return;
+                }
+
+                foreach (KeyValuePair<string, object?> tag in tags)
+                {
+                    if (tag.Key == "reason" && tag.Value is string reasonTag)
+                    {
+                        lock (capturedReasons)
+                        {
+                            capturedReasons.Add(reasonTag);
+                        }
+                    }
+                }
+            });
+        listener.Start();
+
+        FakeSessionManager sessions = new();
+        using GatewayAlarmMonitor monitor = CreateMonitor(sessions, metrics);
+
+        using CancellationTokenSource cts = new();
+        await monitor.StartAsync(cts.Token);
+        await sessions.WaitForSubscribeAsync(WaitTimeout);
+
+        // Register a live subscriber and gate the mode-change events until the baseline
+        // ProviderStatus message has been drained, so neither event is dropped.
+        List<AlarmFeedMessage> received = [];
+        TaskCompletionSource baselineReceived = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        using CancellationTokenSource streamCts = new();
+        Task reader = Task.Run(async () =>
+        {
+            try
+            {
+                await foreach (AlarmFeedMessage message in monitor.StreamAsync(null, streamCts.Token))
+                {
+                    lock (received)
+                    {
+                        received.Add(message);
+                        if (received.Count == 1)
+                        {
+                            baselineReceived.TrySetResult();
+                        }
+                    }
+                }
+            }
+            catch (OperationCanceledException)
+            {
+                // Expected when the test cancels the stream.
+            }
+        });
+
+        await baselineReceived.Task.WaitAsync(WaitTimeout);
+
+        // alarmmgr (baseline) → subtag: must classify as a failover.
+        sessions.EmitEvent(new MxEvent
+        {
+            OnAlarmProviderModeChanged = new OnAlarmProviderModeChangedEvent
+            {
+                Mode = AlarmProviderMode.Subtag,
+                Reason = "alarmmgr failed",
+                At = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+            },
+        });
+        await WaitUntilAsync(
+            () => { lock (capturedReasons) { return capturedReasons.Count >= 1; } },
+            WaitTimeout);
+
+        // subtag → alarmmgr: must classify as a failback.
+        sessions.EmitEvent(new MxEvent
+        {
+            OnAlarmProviderModeChanged = new OnAlarmProviderModeChangedEvent
+            {
+                Mode = AlarmProviderMode.Alarmmgr,
+                Reason = "alarmmgr recovered",
+                At = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+            },
+        });
+        await WaitUntilAsync(
+            () => { lock (capturedReasons) { return capturedReasons.Count >= 2; } },
+            WaitTimeout);
+
+        lock (capturedReasons)
+        {
+            Assert.Equal(new[] { "failover", "failback" }, capturedReasons);
+        }
+
+        await streamCts.CancelAsync();
+        await reader;
+        await cts.CancelAsync();
+        await monitor.StopAsync(CancellationToken.None);
+    }
+
    [Fact]
    public async Task NewSubscriber_ReceivesProviderStatusAsFirstMessage()
    {
@@ -156,6 +374,151 @@ public sealed class GatewayAlarmMonitorProviderModeTests
        await monitor.StopAsync(CancellationToken.None);
    }

+    [Fact]
+    public async Task ForceSubtagConfig_BaselinesProviderStatusToSubtagDegraded_WithoutSwitch()
+    {
+        using GatewayMetrics metrics = new();
+        long switchCount = 0;
+        int gaugeValue = -1;
+        using MeterListener listener = new();
+        listener.InstrumentPublished = (instrument, meterListener) =>
+        {
+            if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                && (instrument.Name == "mxgateway.alarms.provider_switches"
+                    || instrument.Name == "mxgateway.alarms.provider_mode"))
+            {
+                meterListener.EnableMeasurementEvents(instrument);
+            }
+        };
+        listener.SetMeasurementEventCallback<long>(
+            (instrument, measurement, _, _) =>
+            {
+                if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                    && instrument.Name == "mxgateway.alarms.provider_switches")
+                {
+                    Interlocked.Add(ref switchCount, measurement);
+                }
+            });
+        listener.SetMeasurementEventCallback<int>(
+            (instrument, measurement, _, _) =>
+            {
+                if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                    && instrument.Name == "mxgateway.alarms.provider_mode")
+                {
+                    Interlocked.Exchange(ref gaugeValue, measurement);
+                }
+            });
+        listener.Start();
+
+        FakeSessionManager sessions = new();
+        using GatewayAlarmMonitor monitor = CreateMonitor(sessions, metrics, "ForceSubtag");
+
+        using CancellationTokenSource cts = new();
+        await monitor.StartAsync(cts.Token);
+        await sessions.WaitForSubscribeAsync(WaitTimeout);
+
+        using CancellationTokenSource streamCts = new();
+        AlarmFeedMessage? first = null;
+        Task reader = Task.Run(async () =>
+        {
+            await foreach (AlarmFeedMessage message in monitor.StreamAsync(null, streamCts.Token))
+            {
+                first = message;
+                break;
+            }
+        });
+
+        await WaitUntilAsync(() => first is not null, WaitTimeout);
+
+        Assert.NotNull(first);
+        Assert.Equal(AlarmFeedMessage.PayloadOneofCase.ProviderStatus, first!.PayloadCase);
+        Assert.Equal(AlarmProviderMode.Subtag, first.ProviderStatus.Mode);
+        Assert.True(first.ProviderStatus.Degraded);
+
+        // The observable gauge must read subtag (2) after start.
+        listener.RecordObservableInstruments();
+        Assert.Equal(2, Volatile.Read(ref gaugeValue));
+
+        // The initial set must not record a provider switch.
+        Assert.Equal(0, Interlocked.Read(ref switchCount));
+
+        await streamCts.CancelAsync();
+        await reader;
+        await cts.CancelAsync();
+        await monitor.StopAsync(CancellationToken.None);
+    }
+
+    [Fact]
+    public async Task ForceAlarmManagerConfig_BaselinesProviderStatusToAlarmmgr_WithoutSwitch()
+    {
+        using GatewayMetrics metrics = new();
+        long switchCount = 0;
+        int gaugeValue = -1;
+        using MeterListener listener = new();
+        listener.InstrumentPublished = (instrument, meterListener) =>
+        {
+            if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                && (instrument.Name == "mxgateway.alarms.provider_switches"
+                    || instrument.Name == "mxgateway.alarms.provider_mode"))
+            {
+                meterListener.EnableMeasurementEvents(instrument);
+            }
+        };
+        listener.SetMeasurementEventCallback<long>(
+            (instrument, measurement, _, _) =>
+            {
+                if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                    && instrument.Name == "mxgateway.alarms.provider_switches")
+                {
+                    Interlocked.Add(ref switchCount, measurement);
+                }
+            });
+        listener.SetMeasurementEventCallback<int>(
+            (instrument, measurement, _, _) =>
+            {
+                if (ReferenceEquals(instrument.Meter, metrics.Meter)
+                    && instrument.Name == "mxgateway.alarms.provider_mode")
+                {
+                    Interlocked.Exchange(ref gaugeValue, measurement);
+                }
+            });
+        listener.Start();
+
+        FakeSessionManager sessions = new();
+        using GatewayAlarmMonitor monitor = CreateMonitor(sessions, metrics, "ForceAlarmManager");
+
+        using CancellationTokenSource cts = new();
+        await monitor.StartAsync(cts.Token);
+        await sessions.WaitForSubscribeAsync(WaitTimeout);
+
+        using CancellationTokenSource streamCts = new();
+        AlarmFeedMessage? first = null;
+        Task reader = Task.Run(async () =>
+        {
+            await foreach (AlarmFeedMessage message in monitor.StreamAsync(null, streamCts.Token))
+            {
+                first = message;
+                break;
+            }
+        });
+
+        await WaitUntilAsync(() => first is not null, WaitTimeout);
+
+        Assert.NotNull(first);
+        Assert.Equal(AlarmFeedMessage.PayloadOneofCase.ProviderStatus, first!.PayloadCase);
+        Assert.Equal(AlarmProviderMode.Alarmmgr, first.ProviderStatus.Mode);
+        Assert.False(first.ProviderStatus.Degraded);
+
+        listener.RecordObservableInstruments();
+        Assert.Equal(1, Volatile.Read(ref gaugeValue));
+        Assert.Equal(0, Interlocked.Read(ref switchCount));
+
+        await streamCts.CancelAsync();
+        await reader;
+        await cts.CancelAsync();
+        await monitor.StopAsync(CancellationToken.None);
+    }
+
    [Fact]
    public async Task SubscribeAlarms_SendsForcedModeAndWatchList_FromConfiguration()
    {
@@ -259,6 +622,22 @@ public sealed class GatewayAlarmMonitorProviderModeTests
            NullLogger<GatewayAlarmMonitor>.Instance);
    }

+    private static GatewayAlarmMonitor CreateMonitor(FakeSessionManager sessions, GatewayMetrics metrics, string mode)
+    {
+        AlarmsOptions options = new()
+        {
+            Enabled = true,
+            SubscriptionExpression = @"\\NODE\Galaxy!Area",
+            Fallback = new AlarmFallbackOptions { Mode = mode },
+        };
+        return new GatewayAlarmMonitor(
+            sessions,
+            new StubWatchListResolver([]),
+            metrics,
+            Microsoft.Extensions.Options.Options.Create(new GatewayOptions { Alarms = options }),
+            NullLogger<GatewayAlarmMonitor>.Instance);
+    }
+
    private static async Task<AlarmFeedMessage> WaitForAsync(
        List<AlarmFeedMessage> received,
        Func<AlarmFeedMessage, bool> predicate,
@@ -1427,4 +1427,120 @@ public sealed class ProtobufContractRoundTripTests
        Assert.Single(parsed.ReadBulk.Results);
        Assert.True(parsed.ReadBulk.Results[0].WasCached);
    }
+
+    /// <summary>
+    ///     Verifies that an <see cref="ActiveAlarmSnapshot"/> carrying the
+    ///     alarm-provider provenance fields <c>degraded</c> (14) and
+    ///     <c>source_provider</c> (15) round-trips with their values preserved,
+    ///     pinning the wire shape of the byte-identical provenance fields that
+    ///     also appear on <see cref="OnAlarmTransitionEvent"/>.
+    /// </summary>
+    [Fact]
+    public void ActiveAlarmSnapshot_RoundTripsDegradedProvenance()
+    {
+        var raise = Timestamp.FromDateTime(new DateTime(2026, 6, 13, 12, 0, 0, DateTimeKind.Utc));
+        var original = new ActiveAlarmSnapshot
+        {
+            AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+            SourceObjectReference = "Tank01",
+            AlarmTypeName = "AnalogLimitAlarm.HiHi",
+            Severity = 750,
+            OriginalRaiseTimestamp = raise,
+            CurrentState = AlarmConditionState.Active,
+            Degraded = true,
+            SourceProvider = AlarmProviderMode.Subtag,
+        };
+
+        var parsed = ActiveAlarmSnapshot.Parser.ParseFrom(original.ToByteArray());
+
+        Assert.Equal(original, parsed);
+        Assert.True(parsed.Degraded);
+        Assert.Equal(AlarmProviderMode.Subtag, parsed.SourceProvider);
+    }
+
+    /// <summary>
+    ///     Verifies that a <see cref="SubscribeAlarmsCommand"/> populating the
+    ///     alarm-provider fallback extensions — <c>forced_mode</c> (2), a
+    ///     <c>watch_list</c> entry with all six <see cref="AlarmSubtagTarget"/>
+    ///     string fields (3), and a <c>failover</c>
+    ///     <see cref="AlarmFailoverConfig"/> (4) — round-trips end to end,
+    ///     pinning the wire shape that the forced-subtag-mode fix depends on.
+    /// </summary>
+    [Fact]
+    public void SubscribeAlarmsCommand_RoundTripsForcedModeWatchListAndFailover()
+    {
+        var original = new SubscribeAlarmsCommand
+        {
+            SubscriptionExpression = @"\\node\Galaxy!Area",
+            ForcedMode = AlarmProviderMode.Subtag,
+            WatchList =
+            {
+                new AlarmSubtagTarget
+                {
+                    AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+                    SourceObjectReference = "Tank01",
+                    ActiveSubtag = "Tank01.Level.HiHi.InAlarm",
+                    AckedSubtag = "Tank01.Level.HiHi.Acked",
+                    AckCommentSubtag = "Tank01.Level.HiHi.AckMsg",
+                    PrioritySubtag = "Tank01.Level.HiHi.Priority",
+                },
+            },
+            Failover = new AlarmFailoverConfig
+            {
+                ConsecutiveFailureThreshold = 3,
+                FailbackProbeIntervalSeconds = 10,
+                FailbackStableProbes = 5,
+            },
+        };
+
+        var parsed = SubscribeAlarmsCommand.Parser.ParseFrom(original.ToByteArray());
+
+        Assert.Equal(original, parsed);
+        Assert.Equal(AlarmProviderMode.Subtag, parsed.ForcedMode);
+        var target = Assert.Single(parsed.WatchList);
+        Assert.Equal("Galaxy!Area.Tank01.Level.HiHi", target.AlarmFullReference);
+        Assert.Equal("Tank01", target.SourceObjectReference);
+        Assert.Equal("Tank01.Level.HiHi.InAlarm", target.ActiveSubtag);
+        Assert.Equal("Tank01.Level.HiHi.Acked", target.AckedSubtag);
+        Assert.Equal("Tank01.Level.HiHi.AckMsg", target.AckCommentSubtag);
+        Assert.Equal("Tank01.Level.HiHi.Priority", target.PrioritySubtag);
+        Assert.Equal(3, parsed.Failover.ConsecutiveFailureThreshold);
+        Assert.Equal(10, parsed.Failover.FailbackProbeIntervalSeconds);
+        Assert.Equal(5, parsed.Failover.FailbackStableProbes);
+    }
+
+    /// <summary>
+    ///     Verifies that an <see cref="MxEvent"/> carrying an
+    ///     <see cref="OnAlarmProviderModeChangedEvent"/> body (the
+    ///     <c>MxEvent.body</c> oneof tag 25 paired with
+    ///     <see cref="MxEventFamily.OnAlarmProviderModeChanged"/>, family 6)
+    ///     round-trips and resolves to
+    ///     <see cref="MxEvent.BodyOneofCase.OnAlarmProviderModeChanged"/>.
+    /// </summary>
+    [Fact]
+    public void MxEvent_RoundTripsOnAlarmProviderModeChangedBody()
+    {
+        var at = Timestamp.FromDateTime(new DateTime(2026, 6, 13, 9, 30, 0, DateTimeKind.Utc));
+        var original = new MxEvent
+        {
+            Family = MxEventFamily.OnAlarmProviderModeChanged,
+            SessionId = "session-1",
+            WorkerSequence = 42,
+            OnAlarmProviderModeChanged = new OnAlarmProviderModeChangedEvent
+            {
+                Mode = AlarmProviderMode.Subtag,
+                Reason = "wnwrap poll failed 3x",
+                Hresult = unchecked((int)0x80004005),
+                At = at,
+            },
+        };
+
+        var parsed = MxEvent.Parser.ParseFrom(original.ToByteArray());
+
+        Assert.Equal(original, parsed);
+        Assert.Equal(MxEvent.BodyOneofCase.OnAlarmProviderModeChanged, parsed.BodyCase);
+        Assert.Equal(MxEventFamily.OnAlarmProviderModeChanged, parsed.Family);
+        Assert.Equal(AlarmProviderMode.Subtag, parsed.OnAlarmProviderModeChanged.Mode);
+        Assert.Equal(unchecked((int)0x80004005), parsed.OnAlarmProviderModeChanged.Hresult);
+    }
 }
@@ -1,14 +1,14 @@
-using System.Collections.Generic;
 using ZB.MOM.WW.MxGateway.Server.Diagnostics;
-using Xunit;

-public class GatewayLogRedactorSeamTests
+namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;
+
+public sealed class GatewayLogRedactorSeamTests
 {
    [Fact]
    public void Redact_MasksApiKeyInClientIdentity()
    {
-        var redactor = new GatewayLogRedactorSeam();
-        var props = new Dictionary<string, object?> { ["ClientIdentity"] = "Bearer mxgw_operator01_super-secret" };
+        GatewayLogRedactorSeam redactor = new();
+        Dictionary<string, object?> props = new() { ["ClientIdentity"] = "Bearer mxgw_operator01_super-secret" };
        redactor.Redact(props);
        Assert.Equal("Bearer mxgw_operator01_[redacted]", props["ClientIdentity"]);
    }
@@ -11,16 +11,18 @@ namespace ZB.MOM.WW.MxGateway.Tests.Galaxy;
 /// </summary>
 public sealed class GalaxyAlarmAttributeMappingTests
 {
-    /// <summary>Verifies the mapper copies both projected columns onto the row.</summary>
+    /// <summary>Verifies the mapper copies all projected columns onto the row.</summary>
    [Fact]
    public void MapAlarmRow_CopiesProjectedColumns()
    {
        GalaxyAlarmAttributeRow row = GalaxyRepository.MapAlarmRow(
            fullTagReference: "Tank01.Level.HiHi",
-            sourceObjectReference: "Tank01");
+            sourceObjectReference: "Tank01",
+            area: "TestArea");

        Assert.Equal("Tank01.Level.HiHi", row.FullTagReference);
        Assert.Equal("Tank01", row.SourceObjectReference);
+        Assert.Equal("TestArea", row.Area);
    }

    /// <summary>
@@ -33,7 +35,8 @@ public sealed class GalaxyAlarmAttributeMappingTests
    {
        GalaxyAlarmAttributeRow row = GalaxyRepository.MapAlarmRow(
            fullTagReference: "Tank01.Level.HiHi",
-            sourceObjectReference: "Tank01");
+            sourceObjectReference: "Tank01",
+            area: "TestArea");

        Assert.Equal(string.Empty, row.AckCommentSubtag);
    }
@@ -55,10 +58,11 @@ public sealed class GalaxyAlarmAttributeMappingTests
        // Mirror the AlarmAttributesSql projection: full_tag_reference = tag_name + '.' + attribute_name.
        string fullTagReference = tagName + "." + attributeName;

-        GalaxyAlarmAttributeRow row = GalaxyRepository.MapAlarmRow(fullTagReference, tagName);
+        GalaxyAlarmAttributeRow row = GalaxyRepository.MapAlarmRow(fullTagReference, tagName, area: "TestArea");

        Assert.Equal(expectedFullReference, row.FullTagReference);
        Assert.Equal(tagName, row.SourceObjectReference);
+        Assert.Equal("TestArea", row.Area);
        Assert.Equal(row.FullTagReference, row.SourceObjectReference + "." + attributeName);
    }
 }
@@ -1,3 +1,4 @@
+using Google.Protobuf.WellKnownTypes;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
@@ -170,6 +171,116 @@ public sealed class DashboardBrowseAndAlarmModelTests
        Assert.True(model.IsDegraded);
        Assert.Contains("bg-warning", model.BadgeCssClass, StringComparison.Ordinal);
        Assert.Equal("x", model.Reason);
+        // Tests-033: pin the amber label text, not just the CSS class — a label swap
+        // would otherwise pass this test.
+        Assert.Equal(DashboardAlarmProviderStatus.DegradedLabel, model.Label);
+    }
+
+    /// <summary>
+    ///     Tests-033: an explicitly-degraded status whose mode is still Alarmmgr (the
+    ///     <c>Degraded || Mode==Subtag</c> guard's second, independent branch) must still
+    ///     map to the degraded amber badge.
+    /// </summary>
+    [Fact]
+    public void FromProviderStatus_Alarmmgr_DegradedFlagSet_WarningBadge()
+    {
+        AlarmProviderStatus status = new()
+        {
+            Mode = AlarmProviderMode.Alarmmgr,
+            Degraded = true,
+            Reason = "independently degraded",
+        };
+
+        DashboardAlarmProviderStatus model = DashboardAlarmProviderStatus.FromProviderStatus(status);
+
+        Assert.True(model.IsDegraded);
+        Assert.Equal(DashboardAlarmProviderStatus.DegradedLabel, model.Label);
+        Assert.Contains("bg-warning", model.BadgeCssClass, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    ///     Tests-033: the <c>SinceUtc</c> field must carry the protobuf <c>Since</c>
+    ///     timestamp converted to a <see cref="DateTimeOffset" />.
+    /// </summary>
+    [Fact]
+    public void FromProviderStatus_WithSinceTimestamp_MapsSinceUtc()
+    {
+        DateTimeOffset since = new(2026, 6, 15, 12, 30, 0, TimeSpan.Zero);
+        AlarmProviderStatus status = new()
+        {
+            Mode = AlarmProviderMode.Subtag,
+            Degraded = true,
+            Reason = "x",
+            Since = Timestamp.FromDateTimeOffset(since),
+        };
+
+        DashboardAlarmProviderStatus model = DashboardAlarmProviderStatus.FromProviderStatus(status);
+
+        Assert.Equal(since, model.SinceUtc);
+    }
+
+    /// <summary>
+    ///     Tests-033: <see cref="DashboardAlarmProviderStatus.FromFeed" /> — the entry the
+    ///     dashboard SignalR snapshot path actually calls — projects a provider-status
+    ///     feed message into the badge model.
+    /// </summary>
+    [Fact]
+    public void FromFeed_ProviderStatusPayload_ProjectsBadge()
+    {
+        AlarmFeedMessage message = new()
+        {
+            ProviderStatus = new AlarmProviderStatus
+            {
+                Mode = AlarmProviderMode.Subtag,
+                Degraded = true,
+                Reason = "alarmmgr failed",
+            },
+        };
+
+        DashboardAlarmProviderStatus model = DashboardAlarmProviderStatus.FromFeed(message);
+
+        Assert.Equal(AlarmProviderMode.Subtag, model.Mode);
+        Assert.True(model.IsDegraded);
+        Assert.Equal(DashboardAlarmProviderStatus.DegradedLabel, model.Label);
+        Assert.Equal("alarmmgr failed", model.Reason);
+    }
+
+    /// <summary>
+    ///     Tests-033: <see cref="DashboardAlarmProviderStatus.FromFeed" /> throws
+    ///     <see cref="ArgumentException" /> when the feed message does not carry a
+    ///     provider-status payload.
+    /// </summary>
+    [Fact]
+    public void FromFeed_NonProviderStatusPayload_Throws()
+    {
+        AlarmFeedMessage message = new()
+        {
+            SnapshotComplete = true,
+        };
+
+        Assert.Throws<ArgumentException>(() => DashboardAlarmProviderStatus.FromFeed(message));
+    }
+
+    /// <summary>
+    ///     Verifies that a configured forced-subtag provider status renders the
+    ///     distinct "forced" badge (cyan/info), not the amber failover-degraded one.
+    /// </summary>
+    [Fact]
+    public void FromProviderStatus_Subtag_ForcedReason_ForcedBadge()
+    {
+        AlarmProviderStatus status = new()
+        {
+            Mode = AlarmProviderMode.Subtag,
+            Degraded = true,
+            Reason = ZB.MOM.WW.MxGateway.Server.Alarms.AlarmProviderReasons.ForcedSubtag,
+        };
+
+        DashboardAlarmProviderStatus model = DashboardAlarmProviderStatus.FromProviderStatus(status);
+
+        Assert.True(model.IsDegraded);
+        Assert.Equal(DashboardAlarmProviderStatus.ForcedSubtagLabel, model.Label);
+        Assert.Contains("bg-info", model.BadgeCssClass, StringComparison.Ordinal);
+        Assert.DoesNotContain("bg-warning", model.BadgeCssClass, StringComparison.Ordinal);
    }

    /// <summary>Verifies that the formatter renders array elements and element type correctly.</summary>
@@ -94,6 +94,24 @@ public sealed class DashboardSnapshotServiceTests
        Assert.Equal("worker pipe disconnected", fault.Message);
    }

+    /// <summary>
+    /// Verifies snapshot metrics include the cumulative alarm provider switch count.
+    /// </summary>
+    [Fact]
+    public void GetSnapshot_IncludesAlarmProviderSwitchCountMetric()
+    {
+        SessionRegistry registry = new();
+        using GatewayMetrics metrics = new();
+        metrics.AlarmProviderSwitched(1, 2, AlarmProviderSwitchReason.Failover);
+        DashboardSnapshotService service = CreateService(registry, metrics);
+
+        DashboardSnapshot snapshot = service.GetSnapshot();
+
+        Assert.Contains(
+            snapshot.Metrics,
+            metric => metric.Name == "mxgateway.alarms.provider_switches" && metric.Value == 1);
+    }
+
    /// <summary>
    /// Verifies snapshot redacts sensitive values from client identity, session name, and fault messages.
    /// </summary>
@@ -111,12 +111,13 @@ public sealed class GatewayMetricsTests
            });
        listener.Start();

-        metrics.AlarmProviderSwitched(1, 2, "test");
+        metrics.AlarmProviderSwitched(1, 2, AlarmProviderSwitchReason.Failover);

        Assert.Equal(1, capturedValue);
        Assert.Equal("1", capturedFrom);
        Assert.Equal("2", capturedTo);
-        Assert.Equal("test", capturedReason);
+        Assert.Equal("failover", capturedReason);
+        Assert.Equal(1, metrics.GetSnapshot().AlarmProviderSwitchCount);
    }

    /// <summary>
@@ -150,7 +151,7 @@ public sealed class GatewayMetricsTests
            });
        listener.Start();

-        metrics.AlarmProviderSwitched(1, 2, "test");
+        metrics.AlarmProviderSwitched(1, 2, AlarmProviderSwitchReason.Failover);
        listener.RecordObservableInstruments();

        Assert.Equal(2, capturedMode);
@@ -27,6 +27,15 @@ public sealed class FailoverAlarmConsumerTests
        public event EventHandler<MxAlarmTransitionEvent>? AlarmTransitionEmitted;

        public bool ThrowOnPoll = true;
+
+        /// <summary>
+        ///     When set, <see cref="PollOnce"/> throws
+        ///     <see cref="OutOfMemoryException"/> instead of a
+        ///     <see cref="System.Runtime.InteropServices.COMException"/>, to
+        ///     exercise the OOM-safe exception filter (Worker.Tests-032).
+        /// </summary>
+        public bool ThrowOutOfMemoryOnPoll;
+
        public int Polls;

        /// <summary>
@@ -48,6 +57,11 @@ public sealed class FailoverAlarmConsumerTests
        public void PollOnce()
        {
            Polls++;
+            if (ThrowOutOfMemoryOnPoll)
+            {
+                throw new OutOfMemoryException("simulated allocation failure");
+            }
+
            if (ThrowOnPoll)
            {
                throw new System.Runtime.InteropServices.COMException("boom", unchecked((int)0x80004005));
@@ -75,6 +89,15 @@ public sealed class FailoverAlarmConsumerTests

        public bool Subscribed;

+        /// <summary>
+        ///     When set, <see cref="SnapshotActiveAlarms"/> throws — modeling a
+        ///     priming-snapshot failure during failover (Worker-026).
+        /// </summary>
+        public bool ThrowOnSnapshot;
+
+        /// <summary>Number of <see cref="SnapshotActiveAlarms"/> calls.</summary>
+        public int SnapshotCalls;
+
        public void Subscribe(string s) => Subscribed = true;

        public void PollOnce() { }
@@ -83,7 +106,16 @@ public sealed class FailoverAlarmConsumerTests

        public int AcknowledgeByName(string n, string p, string gr, string c, string a, string b, string d, string e) => 22;

-        public IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms() => Array.Empty<MxAlarmSnapshotRecord>();
+        public IReadOnlyList<MxAlarmSnapshotRecord> SnapshotActiveAlarms()
+        {
+            SnapshotCalls++;
+            if (ThrowOnSnapshot)
+            {
+                throw new InvalidOperationException("priming snapshot failed");
+            }
+
+            return Array.Empty<MxAlarmSnapshotRecord>();
+        }

        public void Dispose() { }

@@ -291,4 +323,151 @@ public sealed class FailoverAlarmConsumerTests
        sut.ProbeOnce();  // clean 3 → failback
        Assert.Equal(AlarmProviderMode.Alarmmgr, sut.Mode);
    }
+
+    /// <summary>
+    ///     Worker-026 regression: when the standby's priming
+    ///     <c>SnapshotActiveAlarms</c> throws during failover, the switch must
+    ///     still (a) fire <c>ProviderModeChanged</c> so the gateway learns the
+    ///     feed went degraded, (b) leave <see cref="FailoverAlarmConsumer.Mode"/>
+    ///     in Subtag, and (c) not rethrow out of <c>PollOnce</c> (which on the
+    ///     real STA would land in the poll loop's trailing catch and permanently
+    ///     stop alarm delivery).
+    /// </summary>
+    [Fact]
+    public void Failover_WhenStandbyPrimingSnapshotThrows_StillRaisesModeChangeAndDoesNotRethrow()
+    {
+        FlakyPrimary primary = new FlakyPrimary { ThrowOnPoll = true };
+        StubStandby standby = new StubStandby { ThrowOnSnapshot = true };
+        FailoverSettings settings = new FailoverSettings(threshold: 1, probeIntervalSeconds: 0, stableProbes: 1);
+        using FailoverAlarmConsumer sut = new FailoverAlarmConsumer(primary, standby, settings);
+
+        List<AlarmProviderModeChange> changes = new List<AlarmProviderModeChange>();
+        sut.ProviderModeChanged += (_, e) => changes.Add(e);
+
+        // threshold=1 → the Subscribe failure triggers the switch, which primes
+        // the standby snapshot (throwing). The exception must be contained.
+        Exception? escaped = Record.Exception(() => sut.Subscribe(@"\\HOST\Galaxy!Area"));
+
+        Assert.Null(escaped);
+        Assert.Single(changes);
+        Assert.Equal(AlarmProviderMode.Subtag, changes[0].Mode);
+        Assert.Equal(AlarmProviderMode.Subtag, sut.Mode);
+        Assert.True(standby.SnapshotCalls >= 1); // priming was attempted
+
+        // A subsequent degraded PollOnce (standby.PollOnce + ProbeOnce) must also
+        // not rethrow the snapshot failure.
+        Exception? pollEscaped = Record.Exception(() => sut.PollOnce());
+        Assert.Null(pollEscaped);
+    }
+
+    /// <summary>
+    ///     Worker-026 regression: when a <c>ProviderModeChanged</c> subscriber's
+    ///     handler throws (modeling the AlarmCommandHandler's event-queue enqueue
+    ///     overflowing at capacity), the switch must still take effect and the
+    ///     exception must not escape the switch path into the poll loop.
+    /// </summary>
+    [Fact]
+    public void Failover_WhenModeChangedHandlerThrows_SwitchStillTakesEffectAndDoesNotRethrow()
+    {
+        FlakyPrimary primary = new FlakyPrimary { ThrowOnPoll = true };
+        StubStandby standby = new StubStandby();
+        FailoverSettings settings = new FailoverSettings(threshold: 1, probeIntervalSeconds: 0, stableProbes: 1);
+        using FailoverAlarmConsumer sut = new FailoverAlarmConsumer(primary, standby, settings);
+
+        int handlerInvocations = 0;
+        sut.ProviderModeChanged += (_, _) =>
+        {
+            handlerInvocations++;
+            throw new InvalidOperationException("subscriber handler blew up");
+        };
+
+        Exception? escaped = Record.Exception(() => sut.Subscribe(@"\\HOST\Galaxy!Area"));
+
+        Assert.Null(escaped);
+        Assert.Equal(1, handlerInvocations);          // the event still fired
+        Assert.Equal(AlarmProviderMode.Subtag, sut.Mode); // the switch still took effect
+    }
+
+    /// <summary>
+    ///     Worker.Tests-031 regression: with a non-zero
+    ///     <see cref="FailoverSettings.ProbeIntervalSeconds"/>, two back-to-back
+    ///     <c>ProbeOnce</c> calls must throttle — the second falls inside the
+    ///     interval and must NOT re-poll the primary. Two consecutive calls
+    ///     reliably fall inside any interval of one second or more, so this needs
+    ///     no injected clock.
+    /// </summary>
+    [Fact]
+    public void ProbeOnce_WithNonZeroInterval_ThrottlesSecondProbeWithinInterval()
+    {
+        FlakyPrimary primary = new FlakyPrimary { ThrowOnPoll = true };
+        StubStandby standby = new StubStandby();
+        // stableProbes high enough that a single clean probe cannot fail back,
+        // so Mode stays Subtag and ProbeOnce remains the throttled path.
+        FailoverSettings settings = new FailoverSettings(threshold: 1, probeIntervalSeconds: 3600, stableProbes: 5);
+        using FailoverAlarmConsumer sut = new FailoverAlarmConsumer(primary, standby, settings);
+
+        sut.Subscribe(@"\\HOST\Galaxy!Area"); // threshold=1 → switch to Subtag
+        Assert.Equal(AlarmProviderMode.Subtag, sut.Mode);
+
+        primary.ThrowOnPoll = false; // primary healthy so a probe would poll cleanly
+
+        sut.ProbeOnce(); // first probe runs: re-polls the primary
+        int pollsAfterFirstProbe = primary.Polls;
+        Assert.Equal(1, pollsAfterFirstProbe);
+
+        sut.ProbeOnce(); // within the 3600s interval → throttled, must NOT re-poll
+
+        Assert.Equal(pollsAfterFirstProbe, primary.Polls);
+        Assert.Equal(AlarmProviderMode.Subtag, sut.Mode);
+    }
+
+    /// <summary>
+    ///     Worker.Tests-032 regression: <c>RunPrimary</c>'s
+    ///     <c>when (ex is not OutOfMemoryException)</c> filter must let an
+    ///     <see cref="OutOfMemoryException"/> propagate rather than swallowing it
+    ///     and counting it toward the failover threshold. No mode change must
+    ///     fire — a fatal allocation failure is not a clean degraded handoff.
+    /// </summary>
+    [Fact]
+    public void RunPrimary_WhenPrimaryThrowsOutOfMemory_PropagatesAndDoesNotFailOver()
+    {
+        FlakyPrimary primary = new FlakyPrimary { ThrowOnPoll = false, ThrowOutOfMemoryOnPoll = true };
+        StubStandby standby = new StubStandby();
+        FailoverSettings settings = new FailoverSettings(threshold: 1, probeIntervalSeconds: 0, stableProbes: 1);
+        using FailoverAlarmConsumer sut = new FailoverAlarmConsumer(primary, standby, settings);
+
+        bool modeChanged = false;
+        sut.ProviderModeChanged += (_, _) => modeChanged = true;
+
+        sut.Subscribe(@"\\HOST\Galaxy!Area"); // Subscribe path does not poll; no throw here
+
+        Assert.Throws<OutOfMemoryException>(() => sut.PollOnce());
+        Assert.False(modeChanged);
+        Assert.Equal(AlarmProviderMode.Alarmmgr, sut.Mode);
+    }
+
+    /// <summary>
+    ///     Worker.Tests-032 regression: <see cref="FailoverSettings"/> clamps
+    ///     sub-1 <c>threshold</c> and <c>stableProbes</c> (and sub-0
+    ///     <c>probeIntervalSeconds</c>) to their safe minimums so a misconfigured
+    ///     bind cannot change failover semantics.
+    /// </summary>
+    [Theory]
+    [InlineData(0, 0, 0, 1, 0, 1)]
+    [InlineData(-5, -5, -5, 1, 0, 1)]
+    [InlineData(3, 7, 2, 3, 7, 2)]
+    public void FailoverSettings_ClampsSubMinimumValues(
+        int threshold,
+        int probeInterval,
+        int stableProbes,
+        int expectedThreshold,
+        int expectedProbeInterval,
+        int expectedStableProbes)
+    {
+        FailoverSettings settings = new FailoverSettings(threshold, probeInterval, stableProbes);
+
+        Assert.Equal(expectedThreshold, settings.Threshold);
+        Assert.Equal(expectedProbeInterval, settings.ProbeIntervalSeconds);
+        Assert.Equal(expectedStableProbes, settings.StableProbes);
+    }
 }
@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using ZB.MOM.WW.MxGateway.Worker.MxAccess;

 namespace ZB.MOM.WW.MxGateway.Worker.Tests.MxAccess;
@@ -133,6 +134,60 @@ public sealed class LmxSubtagAlarmSourceTests
        Assert.Single(server.Writes);
    }

+    /// <summary>
+    ///     Verifies <see cref="LmxSubtagAlarmSource.Dispose"/> UnAdvises only the
+    ///     handles that were actually advised — a write-only item (added by
+    ///     <see cref="LmxSubtagAlarmSource.Write"/> but never advised) is removed
+    ///     but not unadvised — and unregisters the server exactly once.
+    /// </summary>
+    [Fact]
+    public void Dispose_UnAdvisesOnlyAdvisedHandles_RemovesAll_AndUnregistersOnce()
+    {
+        var server = new RecordingMxAccessServer();
+        var source = new LmxSubtagAlarmSource(server, FakeServerHandle);
+
+        source.Advise(new[] { "Tank1.Alarm.Subtag", "Tank2.Alarm.Subtag" });
+        // A write-only subtag: added by Write, never advised.
+        source.Write("Tank1.Alarm.AckComment", "acknowledged");
+
+        int advised1 = server.LastItemHandleFor("Tank1.Alarm.Subtag");
+        int advised2 = server.LastItemHandleFor("Tank2.Alarm.Subtag");
+        int writeOnly = server.LastItemHandleFor("Tank1.Alarm.AckComment");
+
+        source.Dispose();
+
+        // Only the two advised handles are unadvised — never the write-only one.
+        Assert.Equal(new[] { advised1, advised2 }, server.UnAdvisedItemHandles);
+        Assert.DoesNotContain(writeOnly, server.UnAdvisedItemHandles);
+        // Every added item (advised + write-only) is removed.
+        Assert.Equal(
+            new[] { advised1, advised2, writeOnly }.OrderBy(h => h),
+            server.RemovedItemHandles.OrderBy(h => h));
+        Assert.Equal(1, server.UnregisterCount);
+    }
+
+    /// <summary>
+    ///     Verifies <see cref="LmxSubtagAlarmSource.Dispose"/> is idempotent: a
+    ///     second call performs no further teardown.
+    /// </summary>
+    [Fact]
+    public void Dispose_IsIdempotent()
+    {
+        var server = new RecordingMxAccessServer();
+        var source = new LmxSubtagAlarmSource(server, FakeServerHandle);
+
+        source.Advise(new[] { "Tank1.Alarm.Subtag" });
+
+        source.Dispose();
+        int unadviseAfterFirst = server.UnAdvisedItemHandles.Count;
+        int unregisterAfterFirst = server.UnregisterCount;
+
+        source.Dispose();
+
+        Assert.Equal(unadviseAfterFirst, server.UnAdvisedItemHandles.Count);
+        Assert.Equal(unregisterAfterFirst, server.UnregisterCount);
+    }
+
    /// <summary>
    ///     Recording <see cref="IMxAccessServer"/> test double that captures the
    ///     AddItem/Advise/Write/UnAdvise/RemoveItem/Unregister calls
@@ -152,13 +207,17 @@ public sealed class LmxSubtagAlarmSourceTests

        public List<WriteRecord> Writes { get; } = new();

+        public List<int> UnAdvisedItemHandles { get; } = new();
+
+        public List<int> RemovedItemHandles { get; } = new();
+
+        public int UnregisterCount { get; private set; }
+
        public int LastItemHandleFor(string itemAddress) => handlesByAddress[itemAddress];

        public int Register(string clientName) => FakeServerHandle;

-        public void Unregister(int serverHandle)
-        {
-        }
+        public void Unregister(int serverHandle) => UnregisterCount++;

        public int AddItem(int serverHandle, string itemDefinition)
        {
@@ -171,9 +230,7 @@ public sealed class LmxSubtagAlarmSourceTests
        public int AddItem2(int serverHandle, string itemDefinition, string itemContext)
            => AddItem(serverHandle, itemDefinition);

-        public void RemoveItem(int serverHandle, int itemHandle)
-        {
-        }
+        public void RemoveItem(int serverHandle, int itemHandle) => RemovedItemHandles.Add(itemHandle);

        public void Advise(int serverHandle, int itemHandle)
        {
@@ -181,9 +238,7 @@ public sealed class LmxSubtagAlarmSourceTests
            AdvisedServerHandles.Add(serverHandle);
        }

-        public void UnAdvise(int serverHandle, int itemHandle)
-        {
-        }
+        public void UnAdvise(int serverHandle, int itemHandle) => UnAdvisedItemHandles.Add(itemHandle);

        public void AdviseSupervisory(int serverHandle, int itemHandle)
        {
@@ -40,9 +40,9 @@ public sealed class SubtagAlarmConsumerTests
        return new SubtagAlarmConsumer(source, new[] { BuildTarget() });
    }

-    /// <summary>Verifies Subscribe advises the active, acked, and priority subtags but not the ack-comment subtag.</summary>
+    /// <summary>Verifies Subscribe advises the active, acked, priority, and ack-comment subtags (the ack-comment is advised so it is an active, writable MXAccess item).</summary>
    [Fact]
-    public void Subscribe_AdvisesActiveAndAckedSubtags()
+    public void Subscribe_AdvisesAllSubtagsIncludingAckComment()
    {
        FakeSource source = new FakeSource();
        using SubtagAlarmConsumer consumer = BuildConsumer(source);
@@ -52,7 +52,7 @@ public sealed class SubtagAlarmConsumerTests
        Assert.Contains(ActiveSubtag, source.Advised);
        Assert.Contains(AckedSubtag, source.Advised);
        Assert.Contains(PrioritySubtag, source.Advised);
-        Assert.DoesNotContain(AckCommentSubtag, source.Advised);
+        Assert.Contains(AckCommentSubtag, source.Advised);
    }

    /// <summary>Verifies an active=true value change raises a degraded, GUID-stamped UNACK_ALM transition.</summary>
@@ -37,6 +37,28 @@ public sealed class SubtagAlarmStateMachineTests
        Assert.Equal("Area", e.Record.Group);
    }

+    [Fact]
+    public void ActiveFalseToTrue_AlarmMgrShape_EmitsNativeProviderGroupTagName()
+    {
+        // Reference parity: a subtag target composed from the object's real Galaxy
+        // area must round-trip to exactly the native alarmmgr (wnwrap) record fields:
+        // Provider "Galaxy", Group = the real area "TestArea", and the object-rooted
+        // TagName "TestMachine_001.TestAlarm001".
+        var target = new AlarmSubtagTarget
+        {
+            AlarmFullReference = "Galaxy!TestArea.TestMachine_001.TestAlarm001",
+            SourceObjectReference = "TestMachine_001",
+            ActiveSubtag = "TestMachine_001.TestAlarm001.InAlarm",
+        };
+        var sm = new SubtagAlarmStateMachine(new[] { target });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+        var events = sm.Apply("TestMachine_001.TestAlarm001.InAlarm", true, ts);
+        var e = Assert.Single(events);
+        Assert.Equal("Galaxy", e.Record.ProviderName);
+        Assert.Equal("TestArea", e.Record.Group);
+        Assert.Equal("TestMachine_001.TestAlarm001", e.Record.TagName);
+    }
+
    [Fact]
    public void ActiveFalseToTrue_NoProviderBang_UsesWholeReferenceAsTagName()
    {
@@ -87,6 +109,31 @@ public sealed class SubtagAlarmStateMachineTests
        Assert.Throws<ArgumentException>(() => new SubtagAlarmStateMachine(new[] { first, second }));
    }

+    /// <summary>
+    ///     Worker-028 regression: two watch-list entries sharing an
+    ///     <see cref="AlarmSubtagTarget.AlarmFullReference"/> (but using distinct
+    ///     subtag addresses) must throw at construction, symmetric with the
+    ///     duplicate-address guard, rather than silently overwriting the earlier
+    ///     reference's state and orphaning its bound addresses.
+    /// </summary>
+    [Fact]
+    public void DuplicateAlarmFullReference_Throws()
+    {
+        var first = new AlarmSubtagTarget
+        {
+            AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+            SourceObjectReference = "Tank01",
+            ActiveSubtag = "Tank01.Level.HiHi.active",
+        };
+        var second = new AlarmSubtagTarget
+        {
+            AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+            SourceObjectReference = "Tank01",
+            ActiveSubtag = "Other.active",
+        };
+        Assert.Throws<ArgumentException>(() => new SubtagAlarmStateMachine(new[] { first, second }));
+    }
+
    [Fact]
    public void AckedTrueWhileActive_EmitsAck()
    {
@@ -140,4 +187,64 @@ public sealed class SubtagAlarmStateMachineTests
        var events = sm.Apply("Some.Other.Tag.active", true, DateTime.UtcNow);
        Assert.Empty(events);
    }
+
+    /// <summary>
+    ///     Worker.Tests-033 regression: an ack arriving while the alarm is NOT
+    ///     active must emit nothing and must NOT latch
+    ///     <c>AckedDuringEpisode</c> — otherwise a stale ack from a prior episode
+    ///     would mis-latch the next raise into a spurious ACK_RTN on clear. The
+    ///     subsequent raise/clear must therefore still emit UNACK_RTN.
+    /// </summary>
+    [Fact]
+    public void AckedTrueWhileInactive_EmitsNothingAndDoesNotLatch()
+    {
+        var sm = new SubtagAlarmStateMachine(new[] { Target() });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+
+        // Ack with no preceding active raise: must be a no-op.
+        var ackEvents = sm.Apply("Tank01.Level.HiHi.acked", true, ts);
+        Assert.Empty(ackEvents);
+
+        // A fresh episode: raise then clear. Because the earlier ack must not
+        // have latched AckedDuringEpisode, the clear must be UNACK_RTN.
+        sm.Apply("Tank01.Level.HiHi.active", true, ts.AddSeconds(5));
+        var clearEvents = sm.Apply("Tank01.Level.HiHi.active", false, ts.AddSeconds(10));
+        var clear = Assert.Single(clearEvents);
+        Assert.Equal(MxAlarmStateKind.UnackRtn, clear.Record.State);
+    }
+
+    /// <summary>
+    ///     Worker.Tests-033 regression: a priority-subtag value change must flow
+    ///     through <c>CoerceInt</c> into the emitted record's
+    ///     <see cref="MxAlarmSnapshotRecord.Priority"/>. A non-numeric value must
+    ///     leave the prior priority unchanged (the CoerceInt fallback path).
+    /// </summary>
+    [Fact]
+    public void PriorityChange_FlowsIntoEmittedRecord()
+    {
+        var target = new AlarmSubtagTarget
+        {
+            AlarmFullReference = "Galaxy!Area.Tank01.Level.HiHi",
+            SourceObjectReference = "Tank01",
+            ActiveSubtag = "Tank01.Level.HiHi.active",
+            AckedSubtag = "Tank01.Level.HiHi.acked",
+            PrioritySubtag = "Tank01.Level.HiHi.priority",
+        };
+        var sm = new SubtagAlarmStateMachine(new[] { target });
+        var ts = new DateTime(2026, 6, 13, 9, 0, 0, DateTimeKind.Utc);
+
+        // A priority change alone emits nothing but records the priority.
+        var priorityEvents = sm.Apply("Tank01.Level.HiHi.priority", 750, ts);
+        Assert.Empty(priorityEvents);
+
+        // Raise: the emitted record carries the recorded priority.
+        var raiseEvents = sm.Apply("Tank01.Level.HiHi.active", true, ts.AddSeconds(1));
+        var raise = Assert.Single(raiseEvents);
+        Assert.Equal(750, raise.Record.Priority);
+
+        // A non-numeric priority must fall back to the existing value, not zero.
+        sm.Apply("Tank01.Level.HiHi.priority", "not-a-number", ts.AddSeconds(2));
+        var snap = Assert.Single(sm.SnapshotActive());
+        Assert.Equal(750, snap.Priority);
+    }
 }
@@ -24,4 +24,43 @@ public sealed class SyntheticAlarmGuidTests
    [Fact]
    public void Reference_ProducesNonEmptyGuid() =>
        Assert.NotEqual(Guid.Empty, SyntheticAlarmGuid.ForReference("A.B.C"));
+
+    /// <summary>
+    ///     Verifies the empty string still derives a non-empty GUID. The length
+    ///     fold in the derivation prevents a degenerate all-zero (Guid.Empty)
+    ///     result, which would collide with the unset-record default downstream.
+    /// </summary>
+    [Fact]
+    public void EmptyReference_ProducesNonEmptyGuid() =>
+        Assert.NotEqual(Guid.Empty, SyntheticAlarmGuid.ForReference(string.Empty));
+
+    /// <summary>
+    ///     Worker-027 regression: <see cref="SyntheticAlarmGuid.ForReference"/>
+    ///     must derive its GUID without routing through
+    ///     <see cref="System.Security.Cryptography"/>, because on net48
+    ///     <c>MD5.Create()</c> throws under the Windows FIPS-compliance policy.
+    ///     This test enables the per-AppContext FIPS-enforcement switch (which the
+    ///     managed crypto factories honour) and asserts the derivation still
+    ///     succeeds deterministically — a regression that reintroduced a FIPS-gated
+    ///     provider would throw here instead of returning a stable GUID.
+    /// </summary>
+    [Fact]
+    public void ForReference_UnderFipsEnforcement_DoesNotThrowAndStaysDeterministic()
+    {
+        const string switchName = "Switch.System.Security.Cryptography.UseLegacyFipsThrow";
+        bool original = AppContext.TryGetSwitch(switchName, out bool value) && value;
+        AppContext.SetSwitch(switchName, true);
+        try
+        {
+            Guid first = SyntheticAlarmGuid.ForReference("Galaxy!Area.Tank01.Level.HiHi");
+            Guid second = SyntheticAlarmGuid.ForReference("Galaxy!Area.Tank01.Level.HiHi");
+
+            Assert.NotEqual(Guid.Empty, first);
+            Assert.Equal(first, second);
+        }
+        finally
+        {
+            AppContext.SetSwitch(switchName, original);
+        }
+    }
 }
@@ -16,9 +16,12 @@
 //   1. On the dev rig with AVEVA System Platform installed and Galaxy running:
 //      $env:MXGATEWAY_RUN_LIVE_MXACCESS_TESTS = "1"
 //   2. Remove (or set to null) the Skip parameter on the [Fact] below.
-//   3. Run with an alarm flip script (same one used by AlarmsLiveSmokeTests)
-//      so that TestMachine_001.TestAlarm001 toggles its Active/Acked subtags
-//      on a ~10 s cadence.
+//   3. Drive a TestMachine alarm so its Active/Acked subtags toggle — either an
+//      alarm flip script (same one used by AlarmsLiveSmokeTests, ~10 s cadence)
+//      or a manual operator/IDE toggle of the alarm attribute. The rig's
+//      TestAlarm attributes are object-driven, so an external MXAccess Write
+//      cannot toggle them (confirmed live 2026-06-14 by toggling TestAlarm002
+//      from the IDE).
 //
 // net48/x86 constraints:
 //   - No init-only properties, records, index/range operators, C# 8+ pattern
@@ -34,6 +37,7 @@ using System.Runtime.InteropServices;
 using System.Threading;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Worker.MxAccess;
+using ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport;
 using Xunit.Abstractions;

 namespace ZB.MOM.WW.MxGateway.Worker.Tests.Probes;
@@ -48,8 +52,9 @@ namespace ZB.MOM.WW.MxGateway.Worker.Tests.Probes;
 ///     <see cref="SubtagAlarmConsumer.AcknowledgeByName"/> writes the
 ///     ack-comment subtag (AckMsg) successfully.
 ///
-///     Skip-gated; flip <c>Skip=null</c> on the dev rig with the alarm flip
-///     script running. The remaining live-validation item is confirming that
+///     Skip-gated; flip <c>Skip=null</c> on the dev rig with an alarm being
+///     driven (flip script or a manual operator/IDE toggle of the alarm
+///     attribute). The remaining live-validation item is confirming that
 ///     the runtime MXAccess item reference path requires no intermediate
 ///     alarm-condition segment (i.e. <c>&lt;Object&gt;.&lt;AlarmAttr&gt;.InAlarm</c>
 ///     resolves as-is).
@@ -116,7 +121,7 @@ public sealed class AlarmSubtagLiveSmokeTests
    ///     the Degraded flag and synthetic GUID are stamped, then
    ///     AcknowledgeByName and verifies the ack-comment write returns 0.
    /// </summary>
-    [Fact(Skip = "Live dev-rig smoke test — flip Skip=null with AVEVA + an alarm flip script running. Subtag fallback path. Field names confirmed (InAlarm/Acked/AckMsg/Priority); live-validate runtime path resolves without intermediate alarm-condition segment.")]
+    [Fact(Skip = "Live dev-rig smoke test — flip Skip=null with AVEVA + an alarm being driven (flip script or manual operator/IDE toggle of the alarm attribute). Subtag fallback path. Field names confirmed (InAlarm/Acked/AckMsg/Priority); live-validate runtime path resolves without intermediate alarm-condition segment.")]
    public void SubtagFallback_FullPipelineRoundTrip_SynthesizesRaiseAndAcknowledges()
    {
        Exception? threadException = null;
@@ -146,6 +151,147 @@ public sealed class AlarmSubtagLiveSmokeTests
        }
    }

+    /// <summary>
+    ///     Runtime-path resolution probe. Unlike the full lifecycle test this
+    ///     does NOT require an active alarm: it advises the four subtags and
+    ///     observes the initial values MXAccess delivers on advise, then writes
+    ///     the AckMsg subtag. It confirms the runtime item-reference path
+    ///     (<c>&lt;Object&gt;.&lt;AlarmAttr&gt;.&lt;field&gt;</c>) resolves with
+    ///     no intermediate alarm-condition segment — the last open item from the
+    ///     design. Runs only when <c>MXGATEWAY_RUN_LIVE_MXACCESS_TESTS=1</c>.
+    ///     Reports "inconclusive" (without failing) when no values are delivered,
+    ///     e.g. the Galaxy engine for the test object is not running.
+    /// </summary>
+    [LiveMxAccessFact]
+    public void LiveProbe_AlarmSubtagsResolve_AndAckMsgWriteSucceeds()
+    {
+        Exception? threadException = null;
+        ManualResetEventSlim done = new ManualResetEventSlim(false);
+        Thread thread = new Thread(() =>
+        {
+            try { RunProbe(); }
+            catch (Exception ex) { threadException = ex; }
+            finally { done.Set(); }
+        });
+        thread.IsBackground = false;
+        thread.SetApartmentState(ApartmentState.STA);
+        thread.Start();
+        done.Wait();
+        thread.Join();
+
+        List<string> lines = new List<string>();
+        output.WriteLine(string.Format("Captured {0} log line(s):", log.Count));
+        string? line;
+        while (log.TryDequeue(out line))
+        {
+            output.WriteLine(line);
+            lines.Add(line);
+        }
+
+        // Also persist to a file so the evidence survives shell-logger quirks
+        // when run over SSH. Path overridable via PROBE_LOG.
+        string logPath = Environment.GetEnvironmentVariable("PROBE_LOG")
+            ?? System.IO.Path.Combine(System.IO.Path.GetTempPath(), "alarm-subtag-probe.log");
+        try { System.IO.File.WriteAllLines(logPath, lines); }
+        catch (Exception writeEx) { output.WriteLine("probe-log write failed: " + writeEx.Message); }
+
+        if (threadException != null)
+        {
+            throw threadException;
+        }
+    }
+
+    private void RunProbe()
+    {
+        Log("=== Subtag runtime-path resolution probe ===");
+        Log("AlarmFullReference: " + AlarmFullReference);
+        Log("Subtag addresses under test:");
+        Log("  active  = " + PlaceholderActiveSubtag);
+        Log("  acked   = " + PlaceholderAckedSubtag);
+        Log("  ackMsg  = " + PlaceholderAckCommentSubtag);
+        Log("  priority= " + PlaceholderPrioritySubtag);
+
+        AlarmSubtagTarget target = new AlarmSubtagTarget
+        {
+            AlarmFullReference = AlarmFullReference,
+            SourceObjectReference = AlarmTagName,
+            ActiveSubtag = PlaceholderActiveSubtag,
+            AckedSubtag = PlaceholderAckedSubtag,
+            AckCommentSubtag = PlaceholderAckCommentSubtag,
+            PrioritySubtag = PlaceholderPrioritySubtag,
+        };
+        List<AlarmSubtagTarget> watchList = new List<AlarmSubtagTarget> { target };
+
+        MxAccessComObjectFactory factory = new MxAccessComObjectFactory();
+        LmxSubtagAlarmSource source = new LmxSubtagAlarmSource(factory, clientName: null);
+        using SubtagAlarmConsumer consumer = new SubtagAlarmConsumer(source, watchList);
+
+        // Hook the RAW source so every advised subtag's value-change is seen,
+        // including the initial value MXAccess delivers on advise (the state
+        // machine itself only emits on active/acked transitions).
+        Dictionary<string, string> lastValues =
+            new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        source.ValueChanged += (_, c) =>
+        {
+            string v = c.Value == null
+                ? "<null>"
+                : string.Format("{0} ({1})", c.Value, c.Value.GetType().Name);
+            lastValues[c.ItemAddress] = v;
+            Log(string.Format("ValueChanged: {0} = {1}", c.ItemAddress, v));
+        };
+
+        Log("Subscribe (advise InAlarm/Acked/Priority) ...");
+        consumer.Subscribe(string.Format(@"\\{0}\Galaxy!{1}", Environment.MachineName, Group));
+        Log("Subscribe returned OK.");
+
+        // Pump the STA for ~6s to receive each advised subtag's initial value.
+        DateTime deadline = DateTime.UtcNow + TimeSpan.FromSeconds(6);
+        while (DateTime.UtcNow < deadline)
+        {
+            PumpMessages();
+            Thread.Sleep(100);
+        }
+
+        Log(string.Format("Distinct subtags that delivered a value: {0}", lastValues.Count));
+        bool inAlarmResolved = lastValues.ContainsKey(PlaceholderActiveSubtag);
+        Log("InAlarm subtag delivered a value: " + inAlarmResolved);
+
+        // Decisive write: AckMsg. Returns 0 only if the address resolves and is writable.
+        Log("AcknowledgeByName (writes AckMsg subtag) ...");
+        int rc = consumer.AcknowledgeByName(
+            alarmName: AlarmTagName,
+            providerName: Provider,
+            groupName: Group,
+            ackComment: "subtag-resolution-probe",
+            ackOperatorName: Environment.UserName,
+            ackOperatorNode: Environment.MachineName,
+            ackOperatorDomain: Environment.UserDomainName ?? string.Empty,
+            ackOperatorFullName: Environment.UserName);
+        Log(string.Format("AcknowledgeByName(AckMsg write) -> rc={0}", rc));
+
+        DateTime settle = DateTime.UtcNow + TimeSpan.FromSeconds(2);
+        while (DateTime.UtcNow < settle)
+        {
+            PumpMessages();
+            Thread.Sleep(100);
+        }
+
+        if (lastValues.Count == 0)
+        {
+            Log("INCONCLUSIVE: no subtag values delivered within the window. The Galaxy "
+                + "engine hosting TestMachine_001 may be stopped, or the runtime path needs "
+                + "an intermediate segment. Re-run with the engine running. (Field names "
+                + "remain confirmed from the ZB AlarmExtension model.)");
+            return;
+        }
+
+        // Live data arrived — assert the in-alarm subtag resolved and the ack write succeeded.
+        Assert.True(inAlarmResolved,
+            "InAlarm subtag delivered no value while other subtags did — the runtime path for InAlarm may differ.");
+        Assert.Equal(0, rc);
+        Log("CONFIRMED: runtime subtag path resolves and the AckMsg write succeeded.");
+    }
+
    private void RunSmoke()
    {
        Log(string.Format("AlarmFullReference: {0}", AlarmFullReference));
@@ -200,9 +346,10 @@ public sealed class AlarmSubtagLiveSmokeTests
        consumer.Subscribe(subscriptionExpression);
        Log("Subscribe returned OK.");

-        // 1. Wait for a Raise transition.  The alarm flip script (same one
-        //    used by AlarmsLiveSmokeTests) writes the active subtag on a
-        //    ~10 s cadence.  LmxSubtagAlarmSource delivers OnDataChange via
+        // 1. Wait for a Raise transition.  Whatever is driving the alarm — a
+        //    flip script (same one used by AlarmsLiveSmokeTests, ~10 s cadence)
+        //    or a manual operator/IDE toggle — writes the active subtag.
+        //    LmxSubtagAlarmSource delivers OnDataChange via
        //    the Windows message pump on the STA, so we must pump messages
        //    here while we wait — mirroring how AlarmsLiveSmokeTests drives
        //    its WnWrapAlarmConsumer.PollOnce() from the STA in a tight loop.
@@ -65,13 +65,6 @@ public sealed class FailoverAlarmConsumer : IMxAccessAlarmConsumer
    private bool disposed;
    private DateTime lastProbeAtUtc = DateTime.MinValue;

-    /// <summary>
-    ///     The subscription expression passed to <see cref="Subscribe"/>.
-    ///     Stored for documentation and potential future full re-subscribe
-    ///     scenarios; the primary is NOT re-subscribed during probing.
-    /// </summary>
-    private string subscriptionExpression = string.Empty;
-
    /// <summary>
    ///     Composes the failover consumer over its two children.
    /// </summary>
@@ -119,9 +112,9 @@ public sealed class FailoverAlarmConsumer : IMxAccessAlarmConsumer
    {
        if (disposed) throw new ObjectDisposedException(nameof(FailoverAlarmConsumer));

-        // Store for documentation; the primary is not torn down on failover
-        // and is therefore not re-subscribed during ProbeOnce.
-        subscriptionExpression = subscription;
+        // The primary is not torn down on failover and is therefore never
+        // re-subscribed during ProbeOnce, so the subscription expression does
+        // not need to be retained here.

        // Arm the standby first so it is warm regardless of primary outcome.
        // A standby subscribe failure is a hard fault (the fallback itself is
@@ -320,12 +313,20 @@ public sealed class FailoverAlarmConsumer : IMxAccessAlarmConsumer
        consecutiveFailures = 0;
        cleanProbes = 0;

+        // Emit the mode-changed notification FIRST and in a guarded block, so
+        // the gateway always learns the feed went degraded even if the priming
+        // snapshot below throws. A handler exception here must never escape the
+        // switch — escaping would (a) leave `active` flipped with no
+        // notification and (b) unwind into RunAlarmPollLoopAsync's trailing
+        // catch, which permanently stops alarm polling (Worker-026).
+        RaiseModeChanged(AlarmProviderMode.Subtag, reason, hresult);
+
        // Warm the standby snapshot for the gateway hand-off. The gateway
        // reconciles state from this snapshot, so the return value is not
-        // consumed here — the call exists for its priming side effect.
-        _ = standby.SnapshotActiveAlarms();
-
-        RaiseModeChanged(AlarmProviderMode.Subtag, reason, hresult);
+        // consumed here — the call exists for its priming side effect. A
+        // failure to prime is non-fatal: the switch has already completed and
+        // been announced, and the standby's live transitions will still flow.
+        TryPrimeStandbySnapshot();
    }

    private void SwitchToPrimary(string reason, int hresult)
@@ -334,14 +335,49 @@ public sealed class FailoverAlarmConsumer : IMxAccessAlarmConsumer
        mode = AlarmProviderMode.Alarmmgr;
        consecutiveFailures = 0;
        cleanProbes = 0;
+
+        // Guarded so a ProviderModeChanged handler exception cannot escape into
+        // the STA poll loop and kill alarm delivery (Worker-026).
        RaiseModeChanged(AlarmProviderMode.Alarmmgr, reason, hresult);
    }

+    /// <summary>
+    ///     Primes the standby snapshot for the gateway hand-off, swallowing any
+    ///     failure. The switch has already completed and the mode change has
+    ///     already been announced before this runs, so a priming failure must
+    ///     not abort the switch or unwind into the poll loop.
+    /// </summary>
+    private void TryPrimeStandbySnapshot()
+    {
+        try
+        {
+            _ = standby.SnapshotActiveAlarms();
+        }
+        catch (Exception ex) when (ex is not OutOfMemoryException)
+        {
+            // Non-fatal: the standby is active and its live transitions still
+            // flow; the gateway will reconcile from subsequent records. Do not
+            // let a transient snapshot failure escape and stop the poll loop.
+        }
+    }
+
    private void RaiseModeChanged(AlarmProviderMode newMode, string reason, int hresult)
    {
-        ProviderModeChanged?.Invoke(
-            this,
-            new AlarmProviderModeChange(newMode, reason, hresult, DateTime.UtcNow));
+        try
+        {
+            ProviderModeChanged?.Invoke(
+                this,
+                new AlarmProviderModeChange(newMode, reason, hresult, DateTime.UtcNow));
+        }
+        catch (Exception ex) when (ex is not OutOfMemoryException)
+        {
+            // A subscriber's OnProviderModeChanged handler threw (e.g. the
+            // AlarmCommandHandler's eventQueue.Enqueue hitting capacity). The
+            // switch itself has already taken effect; swallow so the failure
+            // cannot unwind into RunAlarmPollLoopAsync and permanently stop
+            // alarm polling (Worker-026). The event-queue overflow it most
+            // likely signals is already surfaced as a fault on the IPC path.
+        }
    }

    private void OnChildTransition(object? sender, MxAlarmTransitionEvent e)
@@ -46,6 +46,12 @@ public sealed class LmxSubtagAlarmSource : ISubtagAlarmSource
    private readonly Dictionary<int, string> addressesByItemHandle =
        new Dictionary<int, string>();

+    // Handles that were actually Advise()d, tracked separately from the added
+    // set so Dispose only UnAdvises advised items. Write() can AddItem a
+    // write-only subtag (e.g. an ack-comment that was never advised); calling
+    // UnAdvise on such a handle would be an unbalanced teardown.
+    private readonly HashSet<int> advisedItemHandles = new HashSet<int>();
+
    private object? mxAccessComObject;
    private IMxAccessServer? server;
    private LMXProxyServerClass? comEventSource;
@@ -134,6 +140,7 @@ public sealed class LmxSubtagAlarmSource : ISubtagAlarmSource
            mxServer.Advise(serverHandle, itemHandle);
            itemHandlesByAddress[itemAddress!] = itemHandle;
            addressesByItemHandle[itemHandle] = itemAddress!;
+            advisedItemHandles.Add(itemHandle);
        }
    }

@@ -225,7 +232,13 @@ public sealed class LmxSubtagAlarmSource : ISubtagAlarmSource
        {
            foreach (KeyValuePair<int, string> entry in addressesByItemHandle)
            {
-                try { mxServer.UnAdvise(serverHandle, entry.Key); } catch { /* swallow — best effort */ }
+                // Only UnAdvise handles that were actually advised; a write-only
+                // item (added by Write but never Advise'd) was never advised.
+                if (advisedItemHandles.Contains(entry.Key))
+                {
+                    try { mxServer.UnAdvise(serverHandle, entry.Key); } catch { /* swallow — best effort */ }
+                }
+
                try { mxServer.RemoveItem(serverHandle, entry.Key); } catch { /* swallow — best effort */ }
            }

@@ -234,6 +247,7 @@ public sealed class LmxSubtagAlarmSource : ISubtagAlarmSource

        itemHandlesByAddress.Clear();
        addressesByItemHandle.Clear();
+        advisedItemHandles.Clear();

        object? comToRelease = mxAccessComObject;
        mxAccessComObject = null;
@@ -78,10 +78,15 @@ public sealed class SubtagAlarmConsumer : IMxAccessAlarmConsumer
    }

    /// <summary>
-    ///     Advises every observable alarm subtag (active / acked / priority —
-    ///     the ack-comment subtag is a write-only target and is not advised)
-    ///     and begins listening for value changes. The <paramref name="subscription"/>
-    ///     expression is ignored: the subtag set is fixed by the watch list.
+    ///     Advises every alarm subtag (active / acked / priority, plus the
+    ///     ack-comment subtag) and begins listening for value changes. The
+    ///     ack-comment subtag is advised so it is an active MXAccess item by the
+    ///     time <see cref="AcknowledgeByName"/> writes it — MXAccess rejects a
+    ///     write to an added-but-not-advised item with E_INVALIDARG (confirmed
+    ///     against live MXAccess). Its value changes carry no transition (the
+    ///     state machine ignores addresses it does not map to active/acked).
+    ///     The <paramref name="subscription"/> expression is ignored: the subtag
+    ///     set is fixed by the watch list.
    /// </summary>
    /// <param name="subscription">The subscription expression (unused in subtag mode).</param>
    public void Subscribe(string subscription)
@@ -97,6 +102,7 @@ public sealed class SubtagAlarmConsumer : IMxAccessAlarmConsumer
            AddIfNotEmpty(addresses, target.ActiveSubtag);
            AddIfNotEmpty(addresses, target.AckedSubtag);
            AddIfNotEmpty(addresses, target.PrioritySubtag);
+            AddIfNotEmpty(addresses, target.AckCommentSubtag);
        }

        source.Advise(addresses);
@@ -42,8 +42,22 @@ public sealed class SubtagAlarmStateMachine

        foreach (AlarmSubtagTarget target in targets)
        {
+            // Guard duplicate references symmetrically with the dup-address guard
+            // in Bind: two watch-list entries that share an AlarmFullReference but
+            // differ in subtag addresses would otherwise silently overwrite the
+            // earlier _statesByReference entry while its addresses stay bound to an
+            // orphaned (and therefore invisible) AlarmState, producing silently
+            // inconsistent synthesized state. Fail fast at subscribe time instead.
+            string reference = target.AlarmFullReference ?? string.Empty;
+            if (_statesByReference.ContainsKey(reference))
+            {
+                throw new ArgumentException(
+                    $"Duplicate alarm full reference '{reference}' is bound to more than one alarm target.",
+                    nameof(targets));
+            }
+
            var state = new AlarmState(target);
-            _statesByReference[target.AlarmFullReference] = state;
+            _statesByReference[reference] = state;

            Bind(target.ActiveSubtag, state, SubtagRole.Active);
            Bind(target.AckedSubtag, state, SubtagRole.Acked);
@@ -1,5 +1,4 @@
 using System;
-using System.Security.Cryptography;
 using System.Text;

 namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
@@ -11,8 +10,29 @@ namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
 ///     repeated transitions for the same alarm reference correlate downstream
 ///     (acknowledge, snapshot, OPC UA mapping) without an alarmmgr-supplied GUID.
 /// </summary>
+/// <remarks>
+///     The 128-bit value is computed with a fixed FNV-1a hash over the UTF-8
+///     bytes of the reference, deliberately <strong>not</strong> via
+///     <c>System.Security.Cryptography</c>. On .NET Framework 4.8
+///     <c>MD5.Create()</c> returns the non-validated
+///     <c>MD5CryptoServiceProvider</c>, whose constructor throws under the
+///     Windows FIPS-compliance policy ("not part of the Windows Platform FIPS
+///     validated cryptographic algorithms"). Because this derivation needs only
+///     determinism and distinctness — never cryptographic strength — a plain
+///     non-crypto hash avoids the FIPS gate entirely, so the subtag fallback
+///     keeps working on regulated (FIPS-enabled) hosts exactly when it is needed.
+/// </remarks>
 internal static class SyntheticAlarmGuid
 {
+    // 64-bit FNV-1a constants (RFC-style; widely used reference values).
+    private const ulong FnvOffsetBasis = 14695981039346656037UL;
+    private const ulong FnvPrime = 1099511628211UL;
+
+    // A second independent seed for the high 8 bytes so the full 128-bit value
+    // is well-distributed across distinct references rather than two correlated
+    // halves of the same single-pass hash.
+    private const ulong FnvSecondSeed = 1469598103934665603UL;
+
    /// <summary>
    ///     Produces a stable <see cref="Guid"/> for the given alarm reference.
    ///     The same reference always maps to the same GUID; distinct references
@@ -32,11 +52,39 @@ internal static class SyntheticAlarmGuid

        byte[] bytes = Encoding.UTF8.GetBytes(reference);

-        // MD5 is used purely for a stable, non-cryptographic identity mapping
-        // (reference -> 16-byte GUID), never for security. Its 128-bit output
-        // fits a GUID exactly, which is why it is preferred here.
-        using MD5 md5 = MD5.Create();
-        byte[] hash = md5.ComputeHash(bytes);
-        return new Guid(hash);
+        // Two independent FNV-1a passes fill the low and high 64 bits of the
+        // 128-bit value. The second pass mixes the running length into its seed
+        // so single-character differences and re-orderings still diverge in both
+        // halves, avoiding correlated-half collisions a single pass would risk.
+        ulong low = FnvOffsetBasis;
+        ulong high = FnvSecondSeed;
+        for (int i = 0; i < bytes.Length; i++)
+        {
+            byte b = bytes[i];
+
+            low ^= b;
+            low *= FnvPrime;
+
+            high ^= unchecked(b + (ulong)i);
+            high *= FnvPrime;
+        }
+
+        // Fold the length in so the empty string and other short inputs are not
+        // degenerate (an all-zero / Guid.Empty result is undesirable downstream).
+        low ^= (ulong)bytes.Length;
+        low *= FnvPrime;
+
+        byte[] guidBytes = new byte[16];
+        WriteUInt64(guidBytes, 0, low);
+        WriteUInt64(guidBytes, 8, high);
+        return new Guid(guidBytes);
+    }
+
+    private static void WriteUInt64(byte[] buffer, int offset, ulong value)
+    {
+        for (int i = 0; i < 8; i++)
+        {
+            buffer[offset + i] = (byte)(value >> (i * 8));
+        }
    }
 }
Author	SHA1	Message	Date
Joseph Doherty	c7f754c77b	fix(client/python): cap setuptools<77 so dist stays metadata 2.2 for Gitea PyPI feed; proprietary via classifier	2026-06-15 05:30:22 -04:00
Joseph Doherty	144c293f05	chore(clients): bump all five clients 0.1.0 -> 0.1.1 for release	2026-06-15 05:07:17 -04:00
Joseph Doherty	7c957908f8	docs(code-review): regenerate index — all re-review findings resolved	2026-06-15 03:04:37 -04:00
Joseph Doherty	6659653673	fix(client/java): handle PROVIDER_STATUS alarm-feed arm — CLI build break (Client.Java-039)	2026-06-15 03:01:13 -04:00
Joseph Doherty	75a39f5a8c	fix(client/java): correct browseChildrenRaw README; CLI --require-certificate-validation (Client.Java-037,038)	2026-06-15 02:56:15 -04:00
Joseph Doherty	cebe67e9bd	fix(worker): resilient failover switch; FIPS-safe synthetic GUID; dup-reference guard + tests (Worker-026..028, Worker.Tests-031..033)	2026-06-15 02:56:15 -04:00
Joseph Doherty	ddf2d84fbc	contracts: round-trip degraded provenance/watch-list/mode-changed; proto doc (Contracts-018,019)	2026-06-15 02:46:06 -04:00
Joseph Doherty	56dd56954b	test(gateway): cover failback reason, FromFeed/SinceUtc badge paths; style + bounded drain (Tests-032..035)	2026-06-15 02:46:06 -04:00
Joseph Doherty	b57d02cc4d	fix(client/rust): handle provider_status arm (build break); real system-roots TLS; design doc (Client.Rust-030..032)	2026-06-15 02:39:11 -04:00
Joseph Doherty	47062c1a6e	fix(client/python): reachable cert-validation flag; bounded off-loop TOFU probe; license/marker fixes (Client.Python-027..031)	2026-06-15 02:39:11 -04:00
Joseph Doherty	d0d1dcef15	fix(client/go): correct tag-go-module dirty-tree guard; GOPRIVATE docs (Client.Go-028,029)	2026-06-15 02:39:11 -04:00
Joseph Doherty	fb2b1a4a52	fix(client/dotnet): restore warnings-as-errors floor; license metadata; LazyBrowseNode publication (Client.Dotnet-022..025)	2026-06-15 02:39:11 -04:00
Joseph Doherty	d2c776901b	fix(integrationtests): repair GatewayAlarmMonitor ctor build break; LDAP bind + docs (IntegrationTests-026..029)	2026-06-15 02:39:11 -04:00
Joseph Doherty	258e09e0de	fix(server): propagate watch-list cancellation; doc + test gaps (Server-051..053)	2026-06-15 02:39:11 -04:00
Joseph Doherty	410acc92eb	feat(dashboard): distinct 'forced' subtag provider badge Render Fallback:Mode=ForceSubtag as a cyan 'Subtag monitoring (forced)' badge, distinct from the amber failover 'degraded' badge, so an intentional configuration isn't shown as a fault. Distinguished by the shared AlarmProviderReasons.ForcedSubtag reason carried on the provider-status feed.	2026-06-15 01:43:17 -04:00
Joseph Doherty	b40aaeef05	docs: forced-subtag fix resolution (#1 proto artifact, #2 fixed)	2026-06-15 01:33:14 -04:00
Joseph Doherty	9208225f9c	fix: gateway reflects configured forced provider mode into gauge/feed (#2 )	2026-06-15 01:10:04 -04:00
Joseph Doherty	c6f17557f6	docs: forced-subtag mode fix plan	2026-06-15 01:04:46 -04:00
Joseph Doherty	bbbef4d098	D2: document no current duplicate / endpoint (no-op)	2026-06-14 23:49:47 -04:00
Joseph Doherty	4af24b9518	D1: surface AlarmProviderSwitchCount on dashboard metric list	2026-06-14 23:49:02 -04:00
Joseph Doherty	371ce53409	docs: add deferred follow-ups plan (D1-D5)	2026-06-14 23:46:21 -04:00
Joseph Doherty	597677025f	Merge alarm-fallback cleanup: metrics snapshot/reason, SQL prune, teardown, doc drift Implements the actionable deferred items from pending.md (B1-B5, C6-C7): - B1/B2 metrics: provider-switch count in snapshot + bounded reason enum - B5: drop dead primitive branch from AlarmAttributesSql - B3/B4 worker: UnAdvise only advised handles (+Dispose tests); remove dead field - C6/C7: doc clarifications and design-doc superseded notes Verified: gateway tests on macOS, net48/x86 worker suite (318 passed) on windev.	2026-06-14 02:39:10 -04:00
Joseph Doherty	393e326275	docs(alarms): note operator/IDE toggle drives the live subtag smoke test C6a: the rig's TestAlarm attributes are object-driven; a flip script OR a manual operator/IDE toggle drives them (confirmed live 2026-06-14). Update the how-to-run comments and Skip reason accordingly.	2026-06-14 02:35:59 -04:00
Joseph Doherty	986dcee14a	worker(alarms): UnAdvise only advised handles in LmxSubtagAlarmSource teardown B3: track advised handles separately from added handles so Dispose only UnAdvises items that were actually advised — a write-only subtag (e.g. ack-comment added by Write, never advised) is removed but not unadvised. Add Dispose tests covering the advised/write-only split, full removal, single Unregister, and double-dispose idempotency.	2026-06-14 02:35:59 -04:00
Joseph Doherty	a3752799de	worker(alarms): remove dead FailoverAlarmConsumer.subscriptionExpression B4: the field was stored in Subscribe but never read — the primary is never re-subscribed during probing. Drop it and keep the rationale as a comment.	2026-06-14 02:35:59 -04:00
Joseph Doherty	37aadf72b3	docs(alarms): clarify resolver cancellation contract; mark design doc superseded C6b: IAlarmWatchListResolver.ResolveAsync doc now notes that while discovery being unavailable never throws, a triggered cancellation token still propagates. C7: annotate the original design doc where it drifted from the shipped code — metric names / unimplemented watch-list gauges, and the proto-type location (gateway proto, not worker proto).	2026-06-14 02:33:14 -04:00
Joseph Doherty	5573f2a229	galaxy(alarms): drop dead primitive branch from AlarmAttributesSql B5: the candidate CTE's src_pri=1 (primitive-instance) UNION ALL branch was always excluded by the final WHERE r.src_pri=0, so it added work with no output change. Remove the branch and the now-constant src_pri column/filter. An alarm anchor is always a user attribute, so output is identical.	2026-06-14 02:33:14 -04:00
Joseph Doherty	56abd64c6c	metrics(alarms): expose provider-switch count in snapshot, bound the reason tag B1: add AlarmProviderSwitchCount to GatewayMetricsSnapshot so the switch total is readable without scraping the OTEL counter. B2: replace the free-text reason tag on mxgateway.alarms.provider_switches with a bounded AlarmProviderSwitchReason enum (failover/failback/unknown); the human-readable reason stays in the structured log.	2026-06-14 02:33:02 -04:00
Joseph Doherty	5b31e99ab6	alarms: compose subtag reference from object's real Galaxy area for exact alarmmgr parity	2026-06-14 02:12:11 -04:00
Joseph Doherty	64db828d71	docs(alarms): record live confirmation of subtag path + ack; advise-before-write requirement	2026-06-13 11:26:08 -04:00
Joseph Doherty	1a9367b5de	worker(alarms): advise ack-comment subtag so the ack write targets an active MXAccess item	2026-06-13 11:23:39 -04:00
Joseph Doherty	98e997b573	test(alarms): probe writes evidence log to PROBE_LOG file	2026-06-13 11:15:05 -04:00
Joseph Doherty	0e8d911fd8	test(alarms): live runtime-path resolution probe (LiveMxAccessFact) for alarm subtags	2026-06-13 11:14:12 -04:00