Phase 2 PR 4 — close the 4 open high/medium MXAccess findings from exit-gate-phase-2-final.md. High 1 (ReadAsync subscription-leak on cancel): the one-shot read now wraps subscribe→first-OnDataChange→unsubscribe in try/finally so the per-tag callback is always detached, and if the read installed the underlying MXAccess subscription itself (the prior _addressToHandle key was absent) it tears it down on the way out — no leaked probe item handles when the caller cancels or times out. High 2 (no reconnect loop): MxAccessClient gets a MxAccessClientOptions {AutoReconnect, MonitorInterval=5s, StaleThreshold=60s} + a background MonitorLoopAsync started at first ConnectAsync. The loop wakes every MonitorInterval, checks _lastObservedActivityUtc (bumped by every OnDataChange callback), and if stale probes the proxy with a no-op COM AddItem("$Heartbeat") on the StaPump; if the probe throws or returns false, the loop reconnects-with-replay — Unregister (best-effort), Register, snapshot _addressToHandle.Keys + clear, re-AddItem every previously-active subscription, ConnectionStateChanged events fire for the false→true transition, ReconnectCount bumps. Medium 3 (subscriptions don't push frames back to Proxy): IGalaxyBackend gains OnDataChange/OnAlarmEvent/OnHostStatusChanged events; new IFrameHandler.AttachConnection(FrameWriter) is called per-connection by PipeServer after Hello + the returned IDisposable disposes at connection close; GalaxyFrameHandler.ConnectionSink subscribes the events for the connection lifetime, fire-and-forget pushes them as MessageKind.OnDataChangeNotification / AlarmEvent / RuntimeStatusChange frames through the writer, swallows ObjectDisposedException for the dispose race, and unsubscribes in Dispose to prevent leaked invocation list refs across reconnects. MxAccessGalaxyBackend's existing SubscribeAsync (which previously discarded values via a (_, __) => {} callback) now wires OnTagValueChanged that fans out per-tag value changes to every subscription ID listening (one MXAccess subscription, multi-fan-out — _refToSubs reverse map). UnsubscribeAsync also reverse-walks the map to only call mx.UnsubscribeAsync when the LAST sub for a tag drops. Stub + DbBacked backends declare the events with #pragma warning disable CS0067 because they never raise them but must satisfy the interface (treat-warnings-as-errors would otherwise fail). Medium 4 (WriteValuesAsync doesn't await OnWriteComplete): MxAccessClient.WriteAsync rewritten to return Task<bool> via the v1-style TaskCompletionSource-keyed-by-item-handle pattern in _pendingWrites — adds the TCS before the Write call, awaits it with a configurable timeout (default 5s), removes the TCS in finally, returns true only when OnWriteComplete reported success. MxAccessGalaxyBackend.WriteValuesAsync now reports per-tag Bad_InternalError ("MXAccess runtime reported write failure") when the bool returns false, instead of false-positive Good. PipeServer's IFrameHandler interface adds the AttachConnection(FrameWriter):IDisposable method + a public NoopAttachment nested class (net48 doesn't support default interface methods so the empty-attach is exposed for stub implementations). StubFrameHandler returns IFrameHandler.NoopAttachment.Instance. RunOneConnectionAsync calls AttachConnection after HelloAck and usings the returned disposable so it disposes at the connection scope's finally. ConnectionStateChanged event added on MxAccessClient (caller-facing diagnostics for false→true reconnect transitions). docs/v2/implementation/pr-4-body.md is the Gitea web-UI paste-in for opening PR 4 once pushed; includes 2 new low-priority adversarial findings (probe item-handle leak; replay-loop silently swallows per-subscription failures) flagged as follow-ups not PR 4 blockers. Full solution 460 pass / 7 skip (E2E on admin shell) / 1 pre-existing Phase 0 baseline. No regressions vs PR 2's baseline.

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

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Host/Backend/MxAccess/MxAccessClient.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Concurrent;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using ArchestrA.MxAccess;
@@ -20,6 +21,7 @@ public sealed class MxAccessClient : IDisposable
     private readonly StaPump _pump;
     private readonly IMxProxy _proxy;
     private readonly string _clientName;
+    private readonly MxAccessClientOptions _options;
 
     // Galaxy attribute reference → MXAccess item handle (set on first Subscribe/Read).
     private readonly ConcurrentDictionary<string, int> _addressToHandle = new(StringComparer.OrdinalIgnoreCase);
@@ -30,39 +32,148 @@ public sealed class MxAccessClient : IDisposable
 
     private int _connectionHandle;
     private bool _connected;
+    private DateTime _lastObservedActivityUtc = DateTime.UtcNow;
+    private CancellationTokenSource? _monitorCts;
+    private int _reconnectCount;
+    private bool _disposed;
 
-    public MxAccessClient(StaPump pump, IMxProxy proxy, string clientName)
+    /// <summary>Fires whenever the connection transitions Connected ↔ Disconnected.</summary>
+    public event EventHandler<bool>? ConnectionStateChanged;
+
+    public MxAccessClient(StaPump pump, IMxProxy proxy, string clientName, MxAccessClientOptions? options = null)
     {
         _pump = pump;
         _proxy = proxy;
         _clientName = clientName;
+        _options = options ?? new MxAccessClientOptions();
         _proxy.OnDataChange += OnDataChange;
         _proxy.OnWriteComplete += OnWriteComplete;
     }
 
     public bool IsConnected => _connected;
     public int SubscriptionCount => _subscriptions.Count;
+    public int ReconnectCount => _reconnectCount;
 
-    /// <summary>Connects on the STA thread. Idempotent.</summary>
-    public Task<int> ConnectAsync() => _pump.InvokeAsync(() =>
+    /// <summary>Connects on the STA thread. Idempotent. Starts the reconnect monitor on first call.</summary>
+    public async Task<int> ConnectAsync()
     {
-        if (_connected) return _connectionHandle;
-        _connectionHandle = _proxy.Register(_clientName);
-        _connected = true;
-        return _connectionHandle;
-    });
-
-    public Task DisconnectAsync() => _pump.InvokeAsync(() =>
-    {
-        if (!_connected) return;
-        try { _proxy.Unregister(_connectionHandle); }
-        finally
+        var handle = await _pump.InvokeAsync(() =>
         {
-            _connected = false;
-            _addressToHandle.Clear();
-            _handleToAddress.Clear();
+            if (_connected) return _connectionHandle;
+            _connectionHandle = _proxy.Register(_clientName);
+            _connected = true;
+            return _connectionHandle;
+        });
+
+        ConnectionStateChanged?.Invoke(this, true);
+
+        if (_options.AutoReconnect && _monitorCts is null)
+        {
+            _monitorCts = new CancellationTokenSource();
+            _ = Task.Run(() => MonitorLoopAsync(_monitorCts.Token));
         }
-    });
+
+        return handle;
+    }
+
+    public async Task DisconnectAsync()
+    {
+        _monitorCts?.Cancel();
+        _monitorCts = null;
+
+        await _pump.InvokeAsync(() =>
+        {
+            if (!_connected) return;
+            try { _proxy.Unregister(_connectionHandle); }
+            finally
+            {
+                _connected = false;
+                _addressToHandle.Clear();
+                _handleToAddress.Clear();
+            }
+        });
+
+        ConnectionStateChanged?.Invoke(this, false);
+    }
+
+    /// <summary>
+    ///     Background loop that watches for connection liveness signals and triggers
+    ///     reconnect-with-replay when the connection appears dead. Per Phase 2 high finding #2:
+    ///     v1's MxAccessClient.Monitor pattern lifted into the new pump-based client. Uses
+    ///     observed-activity timestamp + optional probe-tag subscription. Without an explicit
+    ///     probe tag, falls back to "no data change in N seconds + no successful read in N
+    ///     seconds = unhealthy" — same shape as v1.
+    /// </summary>
+    private async Task MonitorLoopAsync(CancellationToken ct)
+    {
+        while (!ct.IsCancellationRequested)
+        {
+            try { await Task.Delay(_options.MonitorInterval, ct); }
+            catch (OperationCanceledException) { break; }
+
+            if (!_connected || _disposed) continue;
+
+            var idle = DateTime.UtcNow - _lastObservedActivityUtc;
+            if (idle <= _options.StaleThreshold) continue;
+
+            // Probe: try a no-op COM call. If the proxy is dead, the call will throw — that's
+            // our reconnect signal.
+            bool probeOk;
+            try
+            {
+                probeOk = await _pump.InvokeAsync(() =>
+                {
+                    // AddItem on the connection handle is cheap and round-trips through COM.
+                    // We use a sentinel "$Heartbeat" reference; if it fails the connection is gone.
+                    try { _proxy.AddItem(_connectionHandle, "$Heartbeat"); return true; }
+                    catch { return false; }
+                });
+            }
+            catch { probeOk = false; }
+
+            if (probeOk)
+            {
+                _lastObservedActivityUtc = DateTime.UtcNow;
+                continue;
+            }
+
+            // Connection appears dead — reconnect-with-replay.
+            try
+            {
+                await _pump.InvokeAsync(() =>
+                {
+                    try { _proxy.Unregister(_connectionHandle); } catch { /* dead anyway */ }
+                    _connected = false;
+                });
+                ConnectionStateChanged?.Invoke(this, false);
+
+                await _pump.InvokeAsync(() =>
+                {
+                    _connectionHandle = _proxy.Register(_clientName);
+                    _connected = true;
+                });
+                _reconnectCount++;
+                ConnectionStateChanged?.Invoke(this, true);
+
+                // Replay every subscription that was active before the disconnect.
+                var snapshot = _addressToHandle.Keys.ToArray();
+                _addressToHandle.Clear();
+                _handleToAddress.Clear();
+                foreach (var fullRef in snapshot)
+                {
+                    try { await SubscribeOnPumpAsync(fullRef); }
+                    catch { /* skip — operator can re-subscribe */ }
+                }
+
+                _lastObservedActivityUtc = DateTime.UtcNow;
+            }
+            catch
+            {
+                // Reconnect failed; back off and retry on the next tick.
+                _connected = false;
+            }
+        }
+    }
 
     /// <summary>
     ///     One-shot read implemented as a transient subscribe + unsubscribe.
@@ -79,26 +190,72 @@ public sealed class MxAccessClient : IDisposable
 
         // Stash the one-shot handler before sending the subscribe, then remove it after firing.
         _subscriptions.AddOrUpdate(fullReference, oneShot, (_, existing) => Combine(existing, oneShot));
+        var addedToReadOnlyAttribute = !_addressToHandle.ContainsKey(fullReference);
 
-        var itemHandle = await SubscribeOnPumpAsync(fullReference);
+        try
+        {
+            await SubscribeOnPumpAsync(fullReference);
 
-        using var _ = ct.Register(() => tcs.TrySetCanceled());
-        var raceTask = await Task.WhenAny(tcs.Task, Task.Delay(timeout, ct));
-        if (raceTask != tcs.Task) throw new TimeoutException($"MXAccess read of {fullReference} timed out after {timeout}");
+            using var _ = ct.Register(() => tcs.TrySetCanceled());
+            var raceTask = await Task.WhenAny(tcs.Task, Task.Delay(timeout, ct));
+            if (raceTask != tcs.Task) throw new TimeoutException($"MXAccess read of {fullReference} timed out after {timeout}");
 
-        // Detach the one-shot handler.
-        _subscriptions.AddOrUpdate(fullReference, _ => default!, (_, existing) => Remove(existing, oneShot));
-
-        return await tcs.Task;
+            return await tcs.Task;
+        }
+        finally
+        {
+            // High 1 — always detach the one-shot handler, even on cancellation/timeout/throw.
+            // If we were the one who added the underlying MXAccess subscription (no other
+            // caller had it), tear it down too so we don't leak a probe item handle.
+            _subscriptions.AddOrUpdate(fullReference, _ => default!, (_, existing) => Remove(existing, oneShot));
+            if (addedToReadOnlyAttribute)
+            {
+                try { await UnsubscribeAsync(fullReference); }
+                catch { /* shutdown-best-effort */ }
+            }
+        }
     }
 
-    public Task WriteAsync(string fullReference, object value, int securityClassification = 0) =>
-        _pump.InvokeAsync(() =>
+    /// <summary>
+    ///     Writes <paramref name="value"/> to the runtime and AWAITS the OnWriteComplete
+    ///     callback so the caller learns the actual write status. Per Phase 2 medium finding #4
+    ///     in <c>exit-gate-phase-2.md</c>: the previous fire-and-forget version returned a
+    ///     false-positive Good even when the runtime rejected the write post-callback.
+    /// </summary>
+    public async Task<bool> WriteAsync(string fullReference, object value,
+        int securityClassification = 0, TimeSpan? timeout = null)
+    {
+        if (!_connected) throw new InvalidOperationException("MxAccessClient not connected");
+        var actualTimeout = timeout ?? TimeSpan.FromSeconds(5);
+
+        var itemHandle = await _pump.InvokeAsync(() => ResolveItem(fullReference));
+
+        var tcs = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
+        if (!_pendingWrites.TryAdd(itemHandle, tcs))
         {
-            if (!_connected) throw new InvalidOperationException("MxAccessClient not connected");
-            var itemHandle = ResolveItem(fullReference);
-            _proxy.Write(_connectionHandle, itemHandle, value, securityClassification);
-        });
+            // A prior write to the same item handle is still pending — uncommon but possible
+            // if the caller spammed writes. Replace it: the older TCS observes a Cancelled task.
+            if (_pendingWrites.TryRemove(itemHandle, out var prior))
+                prior.TrySetCanceled();
+            _pendingWrites[itemHandle] = tcs;
+        }
+
+        try
+        {
+            await _pump.InvokeAsync(() =>
+                _proxy.Write(_connectionHandle, itemHandle, value, securityClassification));
+
+            var raceTask = await Task.WhenAny(tcs.Task, Task.Delay(actualTimeout));
+            if (raceTask != tcs.Task)
+                throw new TimeoutException($"MXAccess write of {fullReference} timed out after {actualTimeout}");
+
+            return await tcs.Task;
+        }
+        finally
+        {
+            _pendingWrites.TryRemove(itemHandle, out _);
+        }
+    }
 
     public async Task SubscribeAsync(string fullReference, Action<string, Vtq> callback)
     {
@@ -148,6 +305,9 @@ public sealed class MxAccessClient : IDisposable
     {
         if (!_handleToAddress.TryGetValue(phItemHandle, out var fullRef)) return;
 
+        // Liveness: any data-change event is proof the connection is alive.
+        _lastObservedActivityUtc = DateTime.UtcNow;
+
         var ts = pftItemTimeStamp is DateTime dt ? dt.ToUniversalTime() : DateTime.UtcNow;
         var quality = (byte)Math.Min(255, Math.Max(0, pwItemQuality));
         var vtq = new Vtq(pvItemValue, ts, quality);
@@ -169,10 +329,30 @@ public sealed class MxAccessClient : IDisposable
 
     public void Dispose()
     {
+        _disposed = true;
+        _monitorCts?.Cancel();
+
         try { DisconnectAsync().GetAwaiter().GetResult(); }
         catch { /* swallow */ }
 
         _proxy.OnDataChange -= OnDataChange;
         _proxy.OnWriteComplete -= OnWriteComplete;
+        _monitorCts?.Dispose();
     }
 }
+
+/// <summary>
+///     Tunables for <see cref="MxAccessClient"/>'s reconnect monitor. Defaults match the v1
+///     monitor's polling cadence so behavior is consistent across the lift.
+/// </summary>
+public sealed class MxAccessClientOptions
+{
+    /// <summary>Whether to start the background monitor at connect time.</summary>
+    public bool AutoReconnect { get; init; } = true;
+
+    /// <summary>How often the monitor wakes up to check liveness.</summary>
+    public TimeSpan MonitorInterval { get; init; } = TimeSpan.FromSeconds(5);
+
+    /// <summary>If no data-change activity in this window, the monitor probes the connection.</summary>
+    public TimeSpan StaleThreshold { get; init; } = TimeSpan.FromSeconds(60);
+}