Merge remote-tracking branch 'origin/main' into agent-3/issue-32-implement-heartbeat-and-watchdog

# Conflicts:
#	src/MxGateway.Worker/Ipc/WorkerPipeSession.cs
#	src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs

docs/mxaccess-worker-instance-design.md

@@ -348,9 +348,28 @@ Event handling rules:
 - Enqueue to the outbound event queue.
 - Return quickly to preserve message pumping.
 
-If event conversion throws, catch it inside the event handler, enqueue a
-structured `WorkerFault` or diagnostic event, and keep the worker alive only if
-the fault policy allows it.
+`MxAccessBaseEventSink` implements the COM connection-point handlers and keeps
+the handlers limited to event argument conversion plus enqueue. It uses
+`MxAccessEventMapper` to create `MxEvent` DTOs for `OnDataChange`,
+`OnWriteComplete`, `OperationComplete`, and `OnBufferedDataChange`. The mapper
+converts scalar and array values through `VariantConverter`, converts
+`MXSTATUS_PROXY[]` through `MxStatusProxyConverter`, and maps installed
+`MxDataType` values to the public protobuf enum while preserving the raw data
+type on buffered events. `OperationComplete` is only emitted from the native
+`OperationComplete` handler; write completion does not synthesize it.
+
+`MxAccessEventQueue` is the bounded outbound event queue for one worker
+session. It assigns the monotonic `WorkerSequence` and `WorkerTimestamp` when an
+event is accepted, preserving the order in which MXAccess handlers enqueue
+events. The default capacity is `10000`. When the queue reaches capacity it
+records a `WorkerFaultCategory.QueueOverflow` fault and rejects further events.
+The event handler catches conversion and enqueue failures, records the first
+fault on the queue, and returns to the STA message pump instead of writing to
+the pipe.
+
+If event conversion throws, catch it inside the event handler, record a
+structured `WorkerFault`, and keep the worker alive only if the fault policy
+allows it.
 
 ## Command Queue
 
@@ -451,6 +470,26 @@ cross-server handle behavior remains owned by MXAccess. COM exceptions continue
 through `StaCommandDispatcher`, which preserves the HRESULT and leaves
 diagnostic registry state unchanged for failed cleanup calls.
 
+`MxAccessCommandExecutor` implements advice lifecycle commands on the same STA
+path:
+
+- `Advise` calls `LMXProxyServerClass.Advise` with the requested server handle
+  and item handle.
+- `AdviseSupervisory` calls `LMXProxyServerClass.AdviseSupervisory` with the
+  requested server handle and item handle. This remains a distinct command from
+  plain `Advise` even though observed scalar captures share the same lower-level
+  subscription body.
+- `UnAdvise` calls `LMXProxyServerClass.UnAdvise` with the requested server
+  handle and item handle.
+
+The worker records plain and supervisory advice separately only after the COM
+call returns normally. Successful `UnAdvise` removes all tracked advice for the
+server and item pair because the public MXAccess cleanup method has no plain
+versus supervisory selector. Successful `RemoveItem` and `Unregister` also clear
+related advice state from the worker registry. Failed advice and cleanup calls
+leave registry state unchanged so diagnostics continue to reflect the last
+successful MXAccess-owned state transition.
+
 ## Handle Registry
 
 The worker should track MXAccess state for diagnostics and cleanup, while still
@@ -475,6 +514,9 @@ Rules:
 - Remove server handles only after `Unregister` succeeds.
 - Record item handles only after `AddItem` or `AddItem2` succeeds.
 - Remove item handles only after `RemoveItem` succeeds.
+- Record advice state only after `Advise` or `AdviseSupervisory` succeeds.
+- Remove advice state only after `UnAdvise`, `RemoveItem`, or `Unregister`
+  succeeds.
 - Preserve invalid-handle behavior from MXAccess.
 - Preserve cross-server handle behavior from MXAccess.
 - Use registry state for cleanup and diagnostics, not semantic correction.