Merge remote-tracking branch 'origin/main' into agent-1/issue-16-implement-blazor-server-dashboard

Issue #19: gateway end-to-end smoke with fake worker

docs/GatewayTesting.md

@@ -0,0 +1,58 @@
+# Gateway Testing
+
+Gateway tests run without installed MXAccess by using fake workers, fake
+transports, and in-process gRPC service fakes. Live MXAccess verification belongs
+in opt-in integration tests because it depends on installed COM components and
+provider state.
+
+## Fake Worker Harness
+
+`FakeWorkerHarness` in `src/MxGateway.Tests/Gateway/Workers/Fakes/` provides an
+in-process worker side for named-pipe IPC tests. It uses the same
+`WorkerFrameReader`, `WorkerFrameWriter`, and `WorkerEnvelope` contract as the
+gateway so tests exercise real frame validation and worker-client state changes.
+
+Use the harness when a gateway or session test needs worker behavior without
+starting `MxGateway.Worker.exe` or loading MXAccess COM. The harness scripts:
+
+- `WorkerHello` and `WorkerReady` startup,
+- command replies with matching correlation ids,
+- ordered `WorkerEvent` frames,
+- `WorkerFault` frames,
+- shutdown acknowledgements,
+- malformed protobuf payloads and oversized frame headers,
+- slow or hung workers by withholding a reply.
+
+Session-level tests can connect the harness to the pipe created by
+`SessionWorkerClientFactory` with `ConnectToGatewayPipeAsync`. Lower-level
+`WorkerClient` tests can use `CreateConnectedPairAsync` to create both pipe ends
+inside the test.
+
+`GatewayEndToEndFakeWorkerSmokeTests` composes the real gRPC service,
+`SessionManager`, `SessionWorkerClientFactory`, `WorkerClient`, and
+`EventStreamService` with a scripted fake worker launcher. The smoke test covers
+`OpenSession`, `Register`, `AddItem`, `Advise`, one streamed `OnDataChange`
+event, and `CloseSession` without loading MXAccess COM.
+
+## Focused Commands
+
+Run the fake worker tests after changing gateway worker IPC, session startup, or
+event streaming behavior:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~FakeWorkerHarnessTests
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~SessionWorkerClientFactoryFakeWorkerTests
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
+```
+
+Run the gateway test project after shared gateway test infrastructure changes:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj
+```
+
+## Related Documentation
+
+- [Gateway Process Design](./gateway-process-design.md)
+- [Worker Frame Protocol](./WorkerFrameProtocol.md)
+- [MXAccess Worker Instance Detailed Design](./mxaccess-worker-instance-design.md)

docs/gateway-dashboard-design.md

@@ -34,9 +34,13 @@ SignalR circuit. Bootstrap is sufficient for a basic dashboard.
 
 ## Hosting Model
 
-The dashboard is hosted by `MxGateway.Server` alongside the gRPC API.
+The dashboard is hosted by `MxGateway.Server` alongside the gRPC API. When
+`MxGateway:Dashboard:Enabled` is `true`, `MapGatewayDashboard()` maps the
+configured `Dashboard:PathBase` to the Blazor Server app and maps the login,
+logout, and access-denied HTTP endpoints beside it. When dashboard hosting is
+disabled, those routes are not mapped.
 
-Suggested endpoint layout:
+Endpoint layout:
 
 ```text
 /dashboard
@@ -45,7 +49,7 @@ Suggested endpoint layout:
 /dashboard/workers
 /dashboard/events
 /dashboard/settings
-/_blazor
+/dashboard/_blazor
 ```
 
 The app should redirect `/` to `/dashboard` only if the deployment wants the
@@ -59,9 +63,10 @@ MxGateway.Server
     Components/
       App.razor
       Routes.razor
+      DashboardPageBase.cs
+      DashboardDisplay.cs
       Layout/
         DashboardLayout.razor
-        NavMenu.razor
       Pages/
         DashboardHome.razor
         SessionsPage.razor
@@ -69,26 +74,21 @@ MxGateway.Server
         WorkersPage.razor
         EventsPage.razor
         SettingsPage.razor
-      Components/
+      Shared/
         MetricCard.razor
-        SessionTable.razor
-        WorkerTable.razor
-        EventRatePanel.razor
+        StatusBadge.razor
         FaultList.razor
-    Services/
-      DashboardSnapshotService.cs
-      DashboardUpdateHub.cs
-      DashboardAuthorization.cs
-    Models/
-      DashboardSnapshot.cs
-      SessionSummary.cs
-      WorkerSummary.cs
-      MetricSummary.cs
+    DashboardSnapshotService.cs
+    DashboardAuthorizationHandler.cs
+    DashboardAuthenticator.cs
+    DashboardSnapshot.cs
+    DashboardSessionSummary.cs
+    DashboardWorkerSummary.cs
+    DashboardMetricSummary.cs
 ```
 
-`DashboardUpdateHub` here means an internal application update service, not a
-separate public SignalR hub unless implementation proves one is needed. Blazor
-Server already uses SignalR for UI circuits.
+Blazor Server provides the SignalR circuit for UI updates. The implementation
+does not add a separate public dashboard hub.
 
 ## Dashboard Data Source
 
@@ -137,7 +137,7 @@ gateway internals.
 
 Use Blazor Server component state updates for real-time dashboard refresh.
 
-Recommended pattern:
+Implemented pattern:
 
 1. Page/component subscribes to `WatchSnapshotsAsync`.
 2. Snapshot service emits updates from a bounded channel or timer.
@@ -147,10 +147,8 @@ Recommended pattern:
 
 Default update cadence:
 
-- immediate update on session create/close/fault,
-- immediate update on worker fault,
 - periodic metrics refresh every 1 second,
-- event-rate windows updated every 1 second.
+- event counters update on the next snapshot tick.
 
 Avoid pushing every MXAccess data-change event to the dashboard. Aggregate event
 counts and rates instead.
@@ -320,7 +318,9 @@ Suggested configuration:
 
 ## Styling
 
-Use Bootstrap utility classes and a small local stylesheet.
+The dashboard serves Bootstrap 5.3.3 assets from
+`src/MxGateway.Server/wwwroot/lib/bootstrap/` and local layout/status styling
+from `src/MxGateway.Server/wwwroot/css/dashboard.css`.
 
 Recommended visual language:
 
@@ -361,15 +361,18 @@ Integration tests should verify:
 
 ## Initial Implementation Slice
 
-The first dashboard slice should implement:
+The first dashboard slice implements:
 
 1. Blazor Server hosting in `MxGateway.Server`.
-2. Bootstrap static assets.
+2. local Bootstrap static assets.
 3. dashboard configuration binding.
 4. dashboard auth using API key login and HTTP-only cookie.
 5. read-only `DashboardSnapshotService`.
 6. home page with metric cards.
-7. sessions page with active session table.
+7. sessions page with active session table and session details.
 8. workers page with worker table.
-9. 1-second realtime refresh through Blazor Server.
-10. redaction tests for secrets.
+9. events page with aggregate counters.
+10. settings page with redacted effective configuration.
+11. periodic realtime refresh through Blazor Server.
+12. route-mapping tests, disabled-dashboard tests, auth tests, and snapshot
+    projection/redaction tests.

docs/gateway-process-design.md

@@ -891,6 +891,11 @@ behavior unless an explicit non-parity backend is designed.
 Gateway tests should be able to run without installed MXAccess by using fake
 workers and fake transports.
 
+Use `FakeWorkerHarness` for tests that need real gateway-to-worker framing,
+handshake, command, event, fault, or malformed-protocol behavior without loading
+MXAccess COM. See [Gateway Testing](./GatewayTesting.md) for the harness scope
+and focused test commands.
+
 Focused tests:
 
 - session state transitions,

docs/implementation-plan-mxaccess-worker.md

@@ -218,6 +218,8 @@ Live tests:
 
 Labels: `area:worker`, `type:feature`, `priority:p0`
 
+Status: implemented.
+
 Deliverables:
 
 - `AddItem`,

docs/mxaccess-worker-instance-design.md

@@ -432,6 +432,25 @@ HRESULT and converts the reply to `ProtocolStatusCode.MxaccessFailure`.
 `MxAccessStaSession.GetRegisteredServerHandlesAsync` returns an STA-read
 snapshot of tracked server handles for diagnostics and future cleanup logic.
 
+`MxAccessCommandExecutor` also implements the item lifecycle commands:
+
+- `AddItem` calls `LMXProxyServerClass.AddItem` with the requested server
+  handle and item definition. It preserves the returned item handle in both
+  `ReturnValue` and `AddItemReply.ItemHandle`.
+- `AddItem2` calls `LMXProxyServerClass.AddItem2` with the requested server
+  handle, item definition, and context string. The context string is passed to
+  MXAccess exactly as received.
+- `RemoveItem` calls `LMXProxyServerClass.RemoveItem` with the requested server
+  handle and item handle. The reply has no method-specific payload because the
+  public MXAccess method returns `void`.
+
+The worker records item handles only after `AddItem` or `AddItem2` returns
+normally, and removes item handles only after `RemoveItem` returns normally.
+The registry does not prevalidate server or item handles, so invalid and
+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.
+
 ## Handle Registry
 
 The worker should track MXAccess state for diagnostics and cleanup, while still
@@ -454,6 +473,8 @@ Rules:
 - Do not rewrite handles returned by MXAccess.
 - Record server handles only after `Register` succeeds.
 - Remove server handles only after `Unregister` succeeds.
+- Record item handles only after `AddItem` or `AddItem2` succeeds.
+- Remove item handles only after `RemoveItem` succeeds.
 - Preserve invalid-handle behavior from MXAccess.
 - Preserve cross-server handle behavior from MXAccess.
 - Use registry state for cleanup and diagnostics, not semantic correction.
@@ -697,6 +718,10 @@ Live MXAccess tests:
 
 Live tests should be opt-in and clearly marked because they depend on installed
 MXAccess COM and provider state.
+The worker test suite uses `MXGATEWAY_RUN_LIVE_MXACCESS_TESTS=1` for these
+tests. `AddItem` uses `TestChildObject.TestInt` by default and accepts an
+override through `MXGATEWAY_LIVE_MXACCESS_ITEM`; `AddItem2` uses the captured
+parity fixture shape `AddItem2("TestInt", "TestChildObject")`.
 
 ## Initial Implementation Slice
 

gateway.md

@@ -109,13 +109,22 @@ histograms through .NET `Meter` and a snapshot API that dashboard services can
 project without binding to a metrics exporter.
 `DashboardSnapshotService` projects sessions, workers, metrics, faults, and
 effective configuration into immutable DTOs for read-only dashboard rendering.
+The Blazor Server dashboard renders those snapshots at `/dashboard`,
+`/dashboard/sessions`, `/dashboard/workers`, `/dashboard/events`, and
+`/dashboard/settings`. Components subscribe to
+`IDashboardSnapshotService.WatchSnapshotsAsync()` and update on the configured
+snapshot interval without mutating session or worker state. The dashboard uses
+local Bootstrap CSS and JavaScript plus a small local stylesheet; it does not
+use a Blazor UI component library.
+
 Dashboard routes use the same API-key verifier as gRPC. `/dashboard/login`
 accepts the API key in a form body, validates the configured `admin` scope,
 and issues an HTTP-only secure cookie for subsequent dashboard requests.
 `/dashboard/logout` clears that cookie. Login and logout posts validate
 anti-forgery tokens, and API keys are never accepted through query strings.
 `Dashboard:AllowAnonymousLocalhost` can bypass the cookie requirement for
-loopback requests only when explicitly enabled.
+loopback requests only when explicitly enabled. Setting
+`MxGateway:Dashboard:Enabled` to `false` leaves the dashboard routes unmapped.
 
 ### Worker Process
 

src/MxGateway.Server/Dashboard/Components/App.razor

@@ -0,0 +1,34 @@
+@inject IOptions<GatewayOptions> GatewayOptions
+
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <base href="@DashboardBaseHref" />
+    <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
+    <link rel="stylesheet" href="/css/dashboard.css" />
+    <HeadOutlet @rendermode="InteractiveServer" />
+</head>
+<body class="dashboard-body">
+    <Routes @rendermode="InteractiveServer" />
+    <script src="/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
+    <script src="_framework/blazor.web.js"></script>
+</body>
+</html>
+
+@code {
+    private string DashboardBaseHref
+    {
+        get
+        {
+            string pathBase = GatewayOptions.Value.Dashboard.PathBase.TrimEnd('/');
+            if (string.IsNullOrWhiteSpace(pathBase))
+            {
+                pathBase = "/dashboard";
+            }
+
+            return $"{pathBase}/";
+        }
+    }
+}

src/MxGateway.Server/Dashboard/Components/DashboardDisplay.cs

@@ -0,0 +1,30 @@
+namespace MxGateway.Server.Dashboard.Components;
+
+public static class DashboardDisplay
+{
+    public static string DateTime(DateTimeOffset? value)
+    {
+        return value.HasValue
+            ? value.Value.UtcDateTime.ToString("yyyy-MM-dd HH:mm:ss 'UTC'", System.Globalization.CultureInfo.InvariantCulture)
+            : "-";
+    }
+
+    public static string Duration(TimeSpan value)
+    {
+        return value.TotalDays >= 1
+            ? value.ToString(@"d\.hh\:mm\:ss", System.Globalization.CultureInfo.InvariantCulture)
+            : value.ToString(@"hh\:mm\:ss", System.Globalization.CultureInfo.InvariantCulture);
+    }
+
+    public static string Text(string? value)
+    {
+        return string.IsNullOrWhiteSpace(value) ? "-" : value;
+    }
+
+    public static long MetricValue(DashboardSnapshot snapshot, string name, string? dimension = null)
+    {
+        return snapshot.Metrics.FirstOrDefault(metric =>
+            string.Equals(metric.Name, name, StringComparison.Ordinal)
+            && string.Equals(metric.Dimension, dimension, StringComparison.Ordinal))?.Value ?? 0;
+    }
+}

src/MxGateway.Server/Dashboard/Components/DashboardPageBase.cs

@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Components;
+
+namespace MxGateway.Server.Dashboard.Components;
+
+public abstract class DashboardPageBase : ComponentBase, IAsyncDisposable
+{
+    private readonly CancellationTokenSource _disposeCancellation = new();
+    private Task? _watchTask;
+
+    [Inject]
+    protected IDashboardSnapshotService SnapshotService { get; set; } = null!;
+
+    protected DashboardSnapshot? Snapshot { get; private set; }
+
+    protected override void OnInitialized()
+    {
+        _watchTask = WatchSnapshotsAsync();
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await _disposeCancellation.CancelAsync().ConfigureAwait(false);
+        if (_watchTask is not null)
+        {
+            await _watchTask.ConfigureAwait(false);
+        }
+
+        _disposeCancellation.Dispose();
+        GC.SuppressFinalize(this);
+    }
+
+    private async Task WatchSnapshotsAsync()
+    {
+        try
+        {
+            await foreach (DashboardSnapshot snapshot in SnapshotService
+                .WatchSnapshotsAsync(_disposeCancellation.Token)
+                .ConfigureAwait(false))
+            {
+                Snapshot = snapshot;
+                await InvokeAsync(StateHasChanged).ConfigureAwait(false);
+            }
+        }
+        catch (OperationCanceledException) when (_disposeCancellation.IsCancellationRequested)
+        {
+        }
+    }
+}

src/MxGateway.Server/Dashboard/Components/Layout/DashboardLayout.razor

@@ -0,0 +1,53 @@
+@inherits LayoutComponentBase
+@inject IOptions<GatewayOptions> GatewayOptions
+
+<div class="dashboard-shell">
+    <nav class="navbar navbar-expand-lg bg-body border-bottom dashboard-navbar">
+        <div class="container-fluid">
+            <a class="navbar-brand" href="">MXAccess Gateway</a>
+            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#dashboardNav"
+                    aria-controls="dashboardNav" aria-expanded="false" aria-label="Toggle navigation">
+                <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="dashboardNav">
+                <ul class="navbar-nav me-auto mb-2 mb-lg-0">
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="" Match="NavLinkMatch.All">Overview</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="sessions">Sessions</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="workers">Workers</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="events">Events</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="settings">Settings</NavLink>
+                    </li>
+                </ul>
+                <form method="post" action="@DashboardPath("/logout")" class="d-flex">
+                    <AntiforgeryToken />
+                    <button class="btn btn-outline-secondary btn-sm" type="submit">Sign out</button>
+                </form>
+            </div>
+        </div>
+    </nav>
+    <main class="container-fluid dashboard-content">
+        @Body
+    </main>
+</div>
+
+@code {
+    private string DashboardPath(string relativePath)
+    {
+        string pathBase = GatewayOptions.Value.Dashboard.PathBase.TrimEnd('/');
+        if (string.IsNullOrWhiteSpace(pathBase))
+        {
+            pathBase = "/dashboard";
+        }
+
+        return $"{pathBase}{relativePath}";
+    }
+}

src/MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor

@@ -0,0 +1,37 @@
+@page "/"
+@inherits DashboardPageBase
+
+<PageTitle>MXAccess Gateway Dashboard</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading dashboard snapshot.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Overview</h1>
+            <div class="text-secondary">Generated @DashboardDisplay.DateTime(Snapshot.GeneratedAt)</div>
+        </div>
+        <StatusBadge Text="@Snapshot.GatewayStatus" />
+    </div>
+
+    <section class="metric-grid">
+        <MetricCard Label="Uptime" Value="@DashboardDisplay.Duration(Snapshot.GatewayUptime)" Detail="@Snapshot.GatewayVersion" />
+        <MetricCard Label="Open Sessions" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.sessions.open").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Workers Running" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.workers.running").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Event Queue Depth" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.queue.depth").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Commands Failed" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.commands.failed").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Events Received" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.received").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Faults" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.faults").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Queue Overflows" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.queues.overflows").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Recent Faults</h2>
+        </div>
+        <FaultList Faults="@Snapshot.Faults" />
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Pages/EventsPage.razor

@@ -0,0 +1,64 @@
+@page "/events"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Events</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading event diagnostics.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Events</h1>
+            <div class="text-secondary">Generated @DashboardDisplay.DateTime(Snapshot.GeneratedAt)</div>
+        </div>
+    </div>
+
+    <section class="metric-grid compact">
+        <MetricCard Label="Events Received" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.received").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Event Queue Depth" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.queue.depth").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Queue Overflows" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.queues.overflows").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Stream Disconnects" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.grpc.streams.disconnected").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Event Families</h2>
+        </div>
+        @if (EventFamilyMetrics.Count == 0)
+        {
+            <div class="empty-state">No event family counters recorded.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Family</th>
+                            <th scope="col">Count</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardMetricSummary metric in EventFamilyMetrics)
+                        {
+                            <tr>
+                                <td>@metric.Dimension</td>
+                                <td>@metric.Value</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}
+
+@code {
+    private IReadOnlyList<DashboardMetricSummary> EventFamilyMetrics => Snapshot?.Metrics
+        .Where(metric => metric.Name == "mxgateway.events.received" && metric.Dimension is not null)
+        .OrderBy(metric => metric.Dimension, StringComparer.OrdinalIgnoreCase)
+        .ToArray() ?? [];
+}

src/MxGateway.Server/Dashboard/Components/Pages/SessionDetailsPage.razor

@@ -0,0 +1,69 @@
+@page "/sessions/{SessionId}"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Session</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading session.</div>
+}
+else if (CurrentSession is null)
+{
+    <section class="dashboard-section">
+        <h1 class="h4 mb-3">Session Not Found</h1>
+        <p class="mb-0">The session is not present in the current snapshot.</p>
+    </section>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Session Details</h1>
+            <div class="text-secondary"><code>@CurrentSession.SessionId</code></div>
+        </div>
+        <StatusBadge Text="@CurrentSession.State.ToString()" />
+    </div>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Session</h2>
+        </div>
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Backend</th><td>@CurrentSession.BackendName</td></tr>
+                    <tr><th scope="row">Client identity</th><td>@DashboardDisplay.Text(CurrentSession.ClientIdentity)</td></tr>
+                    <tr><th scope="row">Client session</th><td>@DashboardDisplay.Text(CurrentSession.ClientSessionName)</td></tr>
+                    <tr><th scope="row">Client correlation</th><td>@DashboardDisplay.Text(CurrentSession.ClientCorrelationId)</td></tr>
+                    <tr><th scope="row">Opened</th><td>@DashboardDisplay.DateTime(CurrentSession.OpenedAt)</td></tr>
+                    <tr><th scope="row">Last activity</th><td>@DashboardDisplay.DateTime(CurrentSession.LastClientActivityAt)</td></tr>
+                    <tr><th scope="row">Lease expires</th><td>@DashboardDisplay.DateTime(CurrentSession.LeaseExpiresAt)</td></tr>
+                    <tr><th scope="row">Last fault</th><td>@DashboardDisplay.Text(CurrentSession.LastFault)</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Worker</h2>
+        </div>
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Process id</th><td>@(CurrentSession.WorkerProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")</td></tr>
+                    <tr><th scope="row">State</th><td><StatusBadge Text="@(CurrentSession.WorkerState?.ToString() ?? "-")" /></td></tr>
+                    <tr><th scope="row">Last heartbeat</th><td>@DashboardDisplay.DateTime(CurrentSession.LastWorkerHeartbeatAt)</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+}
+
+@code {
+    [Parameter]
+    public string SessionId { get; set; } = string.Empty;
+
+    private DashboardSessionSummary? CurrentSession => Snapshot?.Sessions.FirstOrDefault(session =>
+        string.Equals(session.SessionId, SessionId, StringComparison.Ordinal));
+}

src/MxGateway.Server/Dashboard/Components/Pages/SessionsPage.razor

@@ -0,0 +1,67 @@
+@page "/sessions"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Sessions</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading sessions.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Sessions</h1>
+            <div class="text-secondary">@Snapshot.Sessions.Count session rows</div>
+        </div>
+    </div>
+
+    <section class="dashboard-section">
+        @if (Snapshot.Sessions.Count == 0)
+        {
+            <div class="empty-state">No sessions are active or retained.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm align-middle dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Session</th>
+                            <th scope="col">State</th>
+                            <th scope="col">Client</th>
+                            <th scope="col">Backend</th>
+                            <th scope="col">Worker</th>
+                            <th scope="col">Opened</th>
+                            <th scope="col">Activity</th>
+                            <th scope="col">Heartbeat</th>
+                            <th scope="col">Fault</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardSessionSummary session in Snapshot.Sessions)
+                        {
+                            <tr>
+                                <td><NavLink href="@($"sessions/{Uri.EscapeDataString(session.SessionId)}")"><code>@session.SessionId</code></NavLink></td>
+                                <td><StatusBadge Text="@session.State.ToString()" /></td>
+                                <td>@DashboardDisplay.Text(session.ClientIdentity)</td>
+                                <td>@session.BackendName</td>
+                                <td>
+                                    @(session.WorkerProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")
+                                    @if (session.WorkerState is not null)
+                                    {
+                                        <span class="ms-1"><StatusBadge Text="@session.WorkerState.ToString()" /></span>
+                                    }
+                                </td>
+                                <td>@DashboardDisplay.DateTime(session.OpenedAt)</td>
+                                <td>@DashboardDisplay.DateTime(session.LastClientActivityAt)</td>
+                                <td>@DashboardDisplay.DateTime(session.LastWorkerHeartbeatAt)</td>
+                                <td>@DashboardDisplay.Text(session.LastFault)</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Pages/SettingsPage.razor

@@ -0,0 +1,47 @@
+@page "/settings"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Settings</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading settings.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Settings</h1>
+            <div class="text-secondary">Effective gateway configuration</div>
+        </div>
+    </div>
+
+    <section class="dashboard-section">
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Authentication mode</th><td>@Snapshot.Configuration.Authentication.Mode</td></tr>
+                    <tr><th scope="row">Auth database</th><td><code>@Snapshot.Configuration.Authentication.SqlitePath</code></td></tr>
+                    <tr><th scope="row">Pepper secret</th><td>@Snapshot.Configuration.Authentication.PepperSecretName</td></tr>
+                    <tr><th scope="row">Run migrations</th><td>@Snapshot.Configuration.Authentication.RunMigrationsOnStartup</td></tr>
+                    <tr><th scope="row">Worker executable</th><td><code>@Snapshot.Configuration.Worker.ExecutablePath</code></td></tr>
+                    <tr><th scope="row">Worker architecture</th><td>@Snapshot.Configuration.Worker.RequiredArchitecture</td></tr>
+                    <tr><th scope="row">Startup timeout</th><td>@Snapshot.Configuration.Worker.StartupTimeoutSeconds seconds</td></tr>
+                    <tr><th scope="row">Shutdown timeout</th><td>@Snapshot.Configuration.Worker.ShutdownTimeoutSeconds seconds</td></tr>
+                    <tr><th scope="row">Heartbeat grace</th><td>@Snapshot.Configuration.Worker.HeartbeatGraceSeconds seconds</td></tr>
+                    <tr><th scope="row">Default command timeout</th><td>@Snapshot.Configuration.Sessions.DefaultCommandTimeoutSeconds seconds</td></tr>
+                    <tr><th scope="row">Max sessions</th><td>@Snapshot.Configuration.Sessions.MaxSessions</td></tr>
+                    <tr><th scope="row">Event queue capacity</th><td>@Snapshot.Configuration.Events.QueueCapacity</td></tr>
+                    <tr><th scope="row">Backpressure policy</th><td>@Snapshot.Configuration.Events.BackpressurePolicy</td></tr>
+                    <tr><th scope="row">Dashboard enabled</th><td>@Snapshot.Configuration.Dashboard.Enabled</td></tr>
+                    <tr><th scope="row">Dashboard path</th><td>@Snapshot.Configuration.Dashboard.PathBase</td></tr>
+                    <tr><th scope="row">Require admin scope</th><td>@Snapshot.Configuration.Dashboard.RequireAdminScope</td></tr>
+                    <tr><th scope="row">Anonymous localhost</th><td>@Snapshot.Configuration.Dashboard.AllowAnonymousLocalhost</td></tr>
+                    <tr><th scope="row">Snapshot interval</th><td>@Snapshot.Configuration.Dashboard.SnapshotIntervalMilliseconds ms</td></tr>
+                    <tr><th scope="row">Show tag values</th><td>@Snapshot.Configuration.Dashboard.ShowTagValues</td></tr>
+                    <tr><th scope="row">Worker protocol</th><td>@Snapshot.Configuration.Protocol.WorkerProtocolVersion</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Pages/WorkersPage.razor

@@ -0,0 +1,53 @@
+@page "/workers"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Workers</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading workers.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Workers</h1>
+            <div class="text-secondary">@Snapshot.Workers.Count worker rows</div>
+        </div>
+    </div>
+
+    <section class="dashboard-section">
+        @if (Snapshot.Workers.Count == 0)
+        {
+            <div class="empty-state">No worker processes are attached.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm align-middle dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Process</th>
+                            <th scope="col">State</th>
+                            <th scope="col">Session</th>
+                            <th scope="col">Heartbeat</th>
+                            <th scope="col">Fault</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardWorkerSummary worker in Snapshot.Workers)
+                        {
+                            <tr>
+                                <td>@(worker.ProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")</td>
+                                <td><StatusBadge Text="@worker.State.ToString()" /></td>
+                                <td><NavLink href="@($"sessions/{Uri.EscapeDataString(worker.SessionId)}")"><code>@worker.SessionId</code></NavLink></td>
+                                <td>@DashboardDisplay.DateTime(worker.LastHeartbeatAt)</td>
+                                <td>@DashboardDisplay.Text(worker.LastFault)</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Routes.razor

@@ -0,0 +1,15 @@
+<Router AppAssembly="@typeof(Routes).Assembly">
+    <Found Context="routeData">
+        <RouteView RouteData="@routeData" DefaultLayout="@typeof(DashboardLayout)" />
+        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
+    </Found>
+    <NotFound>
+        <LayoutView Layout="@typeof(DashboardLayout)">
+            <PageTitle>Dashboard - Not Found</PageTitle>
+            <section class="dashboard-section">
+                <h1 class="h4 mb-3">Not Found</h1>
+                <p class="mb-0">The requested dashboard page does not exist.</p>
+            </section>
+        </LayoutView>
+    </NotFound>
+</Router>

src/MxGateway.Server/Dashboard/Components/Shared/FaultList.razor

@@ -0,0 +1,39 @@
+@if (Faults.Count == 0)
+{
+    <div class="empty-state">No faults recorded.</div>
+}
+else
+{
+    <div class="table-responsive">
+        <table class="table table-sm align-middle dashboard-table">
+            <thead>
+                <tr>
+                    <th scope="col">Observed</th>
+                    <th scope="col">Source</th>
+                    <th scope="col">Session</th>
+                    <th scope="col">Worker</th>
+                    <th scope="col">State</th>
+                    <th scope="col">Message</th>
+                </tr>
+            </thead>
+            <tbody>
+                @foreach (DashboardFaultSummary fault in Faults)
+                {
+                    <tr>
+                        <td>@DashboardDisplay.DateTime(fault.ObservedAt)</td>
+                        <td>@fault.Source</td>
+                        <td><code>@DashboardDisplay.Text(fault.SessionId)</code></td>
+                        <td>@(fault.WorkerProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")</td>
+                        <td><StatusBadge Text="@fault.State" /></td>
+                        <td>@fault.Message</td>
+                    </tr>
+                }
+            </tbody>
+        </table>
+    </div>
+}
+
+@code {
+    [Parameter]
+    public IReadOnlyList<DashboardFaultSummary> Faults { get; set; } = [];
+}

src/MxGateway.Server/Dashboard/Components/Shared/MetricCard.razor

@@ -0,0 +1,21 @@
+<div class="card metric-card h-100">
+    <div class="card-body">
+        <div class="metric-label">@Label</div>
+        <div class="metric-value">@Value</div>
+        @if (!string.IsNullOrWhiteSpace(Detail))
+        {
+            <div class="metric-detail">@Detail</div>
+        }
+    </div>
+</div>
+
+@code {
+    [Parameter]
+    public string Label { get; set; } = string.Empty;
+
+    [Parameter]
+    public string Value { get; set; } = string.Empty;
+
+    [Parameter]
+    public string? Detail { get; set; }
+}

src/MxGateway.Server/Dashboard/Components/Shared/StatusBadge.razor

@@ -0,0 +1,15 @@
+<span class="badge @CssClass">@Text</span>
+
+@code {
+    [Parameter]
+    public string? Text { get; set; }
+
+    private string CssClass => Text switch
+    {
+        "Ready" or "Healthy" => "text-bg-success",
+        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing" => "text-bg-info",
+        "Closed" => "text-bg-secondary",
+        "Faulted" => "text-bg-danger",
+        _ => "text-bg-light text-dark border"
+    };
+}

src/MxGateway.Server/Dashboard/Components/_Imports.razor

@@ -0,0 +1,12 @@
+@using Microsoft.AspNetCore.Components.Authorization
+@using Microsoft.AspNetCore.Components.Forms
+@using Microsoft.AspNetCore.Components.Routing
+@using Microsoft.AspNetCore.Components.Web
+@using Microsoft.Extensions.Options
+@using MxGateway.Contracts.Proto
+@using MxGateway.Server.Configuration
+@using MxGateway.Server.Dashboard
+@using MxGateway.Server.Dashboard.Components.Layout
+@using MxGateway.Server.Dashboard.Components.Shared
+@using MxGateway.Server.Workers
+@using static Microsoft.AspNetCore.Components.Web.RenderMode

src/MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs

@@ -3,6 +3,7 @@ using Microsoft.AspNetCore.Antiforgery;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Http.HttpResults;
 using MxGateway.Server.Configuration;
+using MxGateway.Server.Dashboard.Components;
 
 namespace MxGateway.Server.Dashboard;
 
@@ -22,13 +23,6 @@ public static class DashboardEndpointRouteBuilderExtensions
         string pathBase = NormalizePathBase(dashboardSection["PathBase"] ?? new DashboardOptions().PathBase);
         RouteGroupBuilder dashboard = endpoints.MapGroup(pathBase);
 
-        dashboard.MapGet(
-                "/",
-                (HttpContext httpContext, IAntiforgery antiforgery, IDashboardSnapshotService snapshotService) =>
-                    GetDashboardHomeAsync(httpContext, antiforgery, snapshotService, pathBase))
-            .RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy)
-            .WithName("DashboardHome");
-
         dashboard.MapGet(
                 "/login",
                 (HttpContext httpContext, IAntiforgery antiforgery) => GetLoginAsync(httpContext, antiforgery, pathBase))
@@ -54,36 +48,13 @@ public static class DashboardEndpointRouteBuilderExtensions
             .AllowAnonymous()
             .WithName("DashboardAccessDenied");
 
+        dashboard.MapRazorComponents<App>()
+            .AddInteractiveServerRenderMode()
+            .RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy);
+
         return endpoints;
     }
 
-    private static ContentHttpResult GetDashboardHomeAsync(
-        HttpContext httpContext,
-        IAntiforgery antiforgery,
-        IDashboardSnapshotService snapshotService,
-        string pathBase)
-    {
-        AntiforgeryTokenSet tokens = antiforgery.GetAndStoreTokens(httpContext);
-        DashboardSnapshot snapshot = snapshotService.GetSnapshot();
-        string requestToken = tokens.RequestToken ?? string.Empty;
-        string body = $"""
-            <form method="post" action="{HtmlEncoder.Default.Encode(pathBase + "/logout")}" class="mb-3">
-                <input name="{tokens.FormFieldName}" type="hidden" value="{HtmlEncoder.Default.Encode(requestToken)}" />
-                <button type="submit">Sign out</button>
-            </form>
-            <dl>
-                <dt>Open sessions</dt>
-                <dd>{snapshot.Sessions.Count}</dd>
-                <dt>Workers</dt>
-                <dd>{snapshot.Workers.Count}</dd>
-                <dt>Faults</dt>
-                <dd>{snapshot.Faults.Count}</dd>
-            </dl>
-            """;
-
-        return TypedResults.Content(RenderPage("MXAccess Gateway Dashboard", body), "text/html");
-    }
-
     private static Task<ContentHttpResult> GetLoginAsync(
         HttpContext httpContext,
         IAntiforgery antiforgery,
@@ -159,14 +130,20 @@ public static class DashboardEndpointRouteBuilderExtensions
             : $"<p role=\"alert\">{HtmlEncoder.Default.Encode(failureMessage)}</p>";
 
         string body = $"""
-            {alert}
-            <form method="post" action="{HtmlEncoder.Default.Encode(pathBase + "/login")}">
-                <input name="{tokens.FormFieldName}" type="hidden" value="{HtmlEncoder.Default.Encode(requestToken)}" />
-                <input name="returnUrl" type="hidden" value="{HtmlEncoder.Default.Encode(returnUrl)}" />
-                <label for="apiKey">API key</label>
-                <input id="apiKey" name="apiKey" type="password" autocomplete="off" />
-                <button type="submit">Sign in</button>
-            </form>
+            <section class="dashboard-login">
+                {alert}
+                <form method="post" action="{HtmlEncoder.Default.Encode(pathBase + "/login")}" class="card login-card">
+                    <div class="card-body">
+                        <input name="{tokens.FormFieldName}" type="hidden" value="{HtmlEncoder.Default.Encode(requestToken)}" />
+                        <input name="returnUrl" type="hidden" value="{HtmlEncoder.Default.Encode(returnUrl)}" />
+                        <div class="mb-3">
+                            <label for="apiKey" class="form-label">API key</label>
+                            <input id="apiKey" name="apiKey" type="password" autocomplete="off" class="form-control" />
+                        </div>
+                        <button type="submit" class="btn btn-primary">Sign in</button>
+                    </div>
+                </form>
+            </section>
             """;
 
         return RenderPage("Dashboard Sign In", body);
@@ -181,12 +158,15 @@ public static class DashboardEndpointRouteBuilderExtensions
                 <meta charset="utf-8" />
                 <meta name="viewport" content="width=device-width, initial-scale=1" />
                 <title>{HtmlEncoder.Default.Encode(title)}</title>
+                <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
+                <link rel="stylesheet" href="/css/dashboard.css" />
             </head>
-            <body>
-                <main>
-                    <h1>{HtmlEncoder.Default.Encode(title)}</h1>
+            <body class="dashboard-body">
+                <main class="container py-5">
+                    <h1 class="h3 mb-4">{HtmlEncoder.Default.Encode(title)}</h1>
                     {body}
                 </main>
+                <script src="/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
             </body>
             </html>
             """;

src/MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs

@@ -13,6 +13,9 @@ public static class DashboardServiceCollectionExtensions
         services.AddSingleton<IDashboardAuthenticator, DashboardAuthenticator>();
         services.AddHttpContextAccessor();
         services.AddAntiforgery();
+        services.AddCascadingAuthenticationState();
+        services.AddRazorComponents()
+            .AddInteractiveServerComponents();
         services
             .AddAuthentication(DashboardAuthenticationDefaults.AuthenticationScheme)
             .AddCookie(DashboardAuthenticationDefaults.AuthenticationScheme);

src/MxGateway.Server/GatewayApplication.cs

@@ -19,8 +19,10 @@ public static class GatewayApplication
         WebApplication app = builder.Build();
 
         app.UseGatewayRequestLoggingScope();
+        app.UseStaticFiles();
         app.UseAuthentication();
         app.UseAuthorization();
+        app.UseAntiforgery();
         app.MapGatewayEndpoints();
 
         return app;

src/MxGateway.Server/libman.json

@@ -0,0 +1,14 @@
+{
+  "version": "1.0",
+  "defaultProvider": "cdnjs",
+  "libraries": [
+    {
+      "library": "bootstrap@5.3.3",
+      "destination": "wwwroot/lib/bootstrap/",
+      "files": [
+        "css/bootstrap.min.css",
+        "js/bootstrap.bundle.min.js"
+      ]
+    }
+  ]
+}

src/MxGateway.Server/wwwroot/css/dashboard.css

@@ -0,0 +1,138 @@
+:root {
+    --mxgw-surface: #f7f8fa;
+    --mxgw-border: #d8dee6;
+    --mxgw-ink-muted: #667085;
+    --mxgw-accent: #146c64;
+}
+
+.dashboard-body {
+    background: var(--mxgw-surface);
+    color: #1f2933;
+}
+
+.dashboard-navbar {
+    min-height: 3.5rem;
+}
+
+.dashboard-content {
+    padding: 1.25rem;
+}
+
+.dashboard-page-header {
+    align-items: center;
+    display: flex;
+    gap: 1rem;
+    justify-content: space-between;
+    margin-bottom: 1rem;
+}
+
+.dashboard-page-header h1,
+.section-heading h2 {
+    font-size: 1.35rem;
+    font-weight: 650;
+    letter-spacing: 0;
+    margin: 0;
+}
+
+.section-heading {
+    margin-bottom: .75rem;
+}
+
+.dashboard-section {
+    background: #fff;
+    border-top: 1px solid var(--mxgw-border);
+    margin-top: 1rem;
+    padding: 1rem 0 0;
+}
+
+.metric-grid {
+    display: grid;
+    gap: .75rem;
+    grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+}
+
+.metric-grid.compact {
+    grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+}
+
+.metric-card {
+    border-color: var(--mxgw-border);
+    border-radius: .375rem;
+    box-shadow: none;
+}
+
+.metric-label {
+    color: var(--mxgw-ink-muted);
+    font-size: .78rem;
+    font-weight: 650;
+    letter-spacing: 0;
+    text-transform: uppercase;
+}
+
+.metric-value {
+    color: var(--mxgw-accent);
+    font-size: 1.7rem;
+    font-weight: 700;
+    letter-spacing: 0;
+    line-height: 1.25;
+    overflow-wrap: anywhere;
+}
+
+.metric-detail {
+    color: var(--mxgw-ink-muted);
+    font-size: .85rem;
+    overflow-wrap: anywhere;
+}
+
+.dashboard-table {
+    --bs-table-bg: #fff;
+    border-color: var(--mxgw-border);
+    margin-bottom: 0;
+}
+
+.dashboard-table th {
+    color: #344054;
+    font-weight: 650;
+    white-space: nowrap;
+}
+
+.dashboard-table td {
+    max-width: 24rem;
+    overflow-wrap: anywhere;
+}
+
+.details-table th {
+    width: 14rem;
+}
+
+.empty-state {
+    background: #fff;
+    border: 1px dashed var(--mxgw-border);
+    border-radius: .375rem;
+    color: var(--mxgw-ink-muted);
+    padding: 1rem;
+}
+
+.dashboard-login {
+    max-width: 28rem;
+}
+
+.login-card {
+    border-color: var(--mxgw-border);
+    border-radius: .375rem;
+}
+
+@media (max-width: 700px) {
+    .dashboard-content {
+        padding: .75rem;
+    }
+
+    .dashboard-page-header {
+        align-items: flex-start;
+        flex-direction: column;
+    }
+
+    .details-table th {
+        width: 9rem;
+    }
+}

src/MxGateway.Tests/Gateway/GatewayApplicationTests.cs

@@ -33,6 +33,37 @@ public sealed class GatewayApplicationTests
         Assert.NotNull(metrics);
     }
 
+    [Fact]
+    public void Build_WhenDashboardEnabled_MapsBlazorDashboardAndAuthEndpoints()
+    {
+        WebApplication app = GatewayApplication.Build([]);
+        IReadOnlyList<RouteEndpoint> endpoints = GetRouteEndpoints(app);
+
+        Assert.Contains(endpoints, endpoint => endpoint.RoutePattern.RawText == "/dashboard/");
+        Assert.Contains(endpoints, endpoint => endpoint.RoutePattern.RawText == "/dashboard/sessions");
+        Assert.Contains(endpoints, endpoint => endpoint.RoutePattern.RawText == "/dashboard/workers");
+        Assert.Contains(endpoints, endpoint => endpoint.RoutePattern.RawText == "/dashboard/events");
+        Assert.Contains(endpoints, endpoint => endpoint.RoutePattern.RawText == "/dashboard/settings");
+        Assert.Contains(endpoints, endpoint =>
+            endpoint.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName == "DashboardLogin");
+        Assert.Contains(endpoints, endpoint =>
+            endpoint.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName == "DashboardLogout");
+    }
+
+    [Fact]
+    public void Build_WhenDashboardDisabled_DoesNotMapDashboardRoutes()
+    {
+        WebApplication app = GatewayApplication.Build(["--MxGateway:Dashboard:Enabled=false"]);
+        IReadOnlyList<RouteEndpoint> endpoints = GetRouteEndpoints(app);
+
+        Assert.DoesNotContain(endpoints, endpoint =>
+            endpoint.RoutePattern.RawText?.StartsWith("/dashboard", StringComparison.Ordinal) == true);
+        Assert.DoesNotContain(endpoints, endpoint =>
+            endpoint.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName?.StartsWith(
+                "Dashboard",
+                StringComparison.Ordinal) == true);
+    }
+
     [Theory]
     [InlineData(
         "MxGateway:Worker:ExecutablePath",
@@ -65,4 +96,12 @@ public sealed class GatewayApplicationTests
             exception.Failures,
             failure => failure.Contains(expectedFailure, StringComparison.Ordinal));
     }
+
+    private static IReadOnlyList<RouteEndpoint> GetRouteEndpoints(WebApplication app)
+    {
+        return ((IEndpointRouteBuilder)app).DataSources
+            .SelectMany(dataSource => dataSource.Endpoints)
+            .OfType<RouteEndpoint>()
+            .ToArray();
+    }
 }

src/MxGateway.Tests/Gateway/GatewayEndToEndFakeWorkerSmokeTests.cs

@@ -0,0 +1,439 @@
+using System.Collections.Concurrent;
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using MxGateway.Contracts;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Grpc;
+using MxGateway.Server.Metrics;
+using MxGateway.Server.Security.Authorization;
+using MxGateway.Server.Sessions;
+using MxGateway.Server.Workers;
+using MxGateway.Tests.Gateway.Workers.Fakes;
+
+namespace MxGateway.Tests.Gateway;
+
+public sealed class GatewayEndToEndFakeWorkerSmokeTests
+{
+    private static readonly TimeSpan TestTimeout = TimeSpan.FromSeconds(5);
+    private const int ServerHandle = 1001;
+    private const int ItemHandle = 2002;
+
+    [Fact]
+    public async Task GatewayService_WithFakeWorker_CompletesSessionCommandEventAndClosePath()
+    {
+        ScriptedFakeWorkerProcessLauncher launcher = new();
+        await using GatewayServiceFixture fixture = new(launcher);
+
+        OpenSessionReply openReply = await fixture.Service.OpenSession(
+            new OpenSessionRequest
+            {
+                ClientSessionName = "fake-worker-e2e",
+                ClientCorrelationId = "open-correlation",
+                CommandTimeout = Duration.FromTimeSpan(TestTimeout),
+            },
+            new TestServerCallContext());
+
+        RecordingServerStreamWriter<MxEvent> eventWriter = new();
+        Task streamTask = fixture.Service.StreamEvents(
+            new StreamEventsRequest { SessionId = openReply.SessionId },
+            eventWriter,
+            new TestServerCallContext());
+
+        MxCommandReply registerReply = await fixture.Service.Invoke(
+            CreateRegisterRequest(openReply.SessionId),
+            new TestServerCallContext());
+        MxCommandReply addItemReply = await fixture.Service.Invoke(
+            CreateAddItemRequest(openReply.SessionId, registerReply.Register.ServerHandle),
+            new TestServerCallContext());
+        MxCommandReply adviseReply = await fixture.Service.Invoke(
+            CreateAdviseRequest(openReply.SessionId, registerReply.Register.ServerHandle, addItemReply.AddItem.ItemHandle),
+            new TestServerCallContext());
+
+        MxEvent dataChange = await eventWriter.WaitForFirstMessageAsync(TestTimeout);
+
+        CloseSessionReply closeReply = await fixture.Service.CloseSession(
+            new CloseSessionRequest
+            {
+                SessionId = openReply.SessionId,
+                ClientCorrelationId = "close-correlation",
+            },
+            new TestServerCallContext());
+
+        await streamTask.WaitAsync(TestTimeout);
+        await launcher.WorkerTask.WaitAsync(TestTimeout);
+
+        Assert.Equal(ProtocolStatusCode.Ok, openReply.ProtocolStatus.Code);
+        Assert.Equal(GatewayContractInfo.DefaultBackendName, openReply.BackendName);
+        Assert.Equal(ScriptedFakeWorkerProcessLauncher.ProcessId, openReply.WorkerProcessId);
+        Assert.Equal(ProtocolStatusCode.Ok, registerReply.ProtocolStatus.Code);
+        Assert.Equal(ServerHandle, registerReply.Register.ServerHandle);
+        Assert.Equal(ProtocolStatusCode.Ok, addItemReply.ProtocolStatus.Code);
+        Assert.Equal(ItemHandle, addItemReply.AddItem.ItemHandle);
+        Assert.Equal(ProtocolStatusCode.Ok, adviseReply.ProtocolStatus.Code);
+        Assert.Equal(MxEventFamily.OnDataChange, dataChange.Family);
+        Assert.Equal(openReply.SessionId, dataChange.SessionId);
+        Assert.Equal(ServerHandle, dataChange.ServerHandle);
+        Assert.Equal(ItemHandle, dataChange.ItemHandle);
+        Assert.Equal("scripted-value", dataChange.Value.StringValue);
+        Assert.Equal(ProtocolStatusCode.Ok, closeReply.ProtocolStatus.Code);
+        Assert.Equal(SessionState.Closed, closeReply.FinalState);
+        Assert.True(launcher.Process.HasExited);
+        Assert.Equal(
+            [MxCommandKind.Register, MxCommandKind.AddItem, MxCommandKind.Advise],
+            launcher.CommandKinds);
+    }
+
+    private static MxCommandRequest CreateRegisterRequest(string sessionId)
+    {
+        return new MxCommandRequest
+        {
+            SessionId = sessionId,
+            ClientCorrelationId = "register-correlation",
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.Register,
+                Register = new RegisterCommand { ClientName = "fake-worker-e2e-client" },
+            },
+        };
+    }
+
+    private static MxCommandRequest CreateAddItemRequest(
+        string sessionId,
+        int serverHandle)
+    {
+        return new MxCommandRequest
+        {
+            SessionId = sessionId,
+            ClientCorrelationId = "add-item-correlation",
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.AddItem,
+                AddItem = new AddItemCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemDefinition = "Galaxy.Tag.Value",
+                },
+            },
+        };
+    }
+
+    private static MxCommandRequest CreateAdviseRequest(
+        string sessionId,
+        int serverHandle,
+        int itemHandle)
+    {
+        return new MxCommandRequest
+        {
+            SessionId = sessionId,
+            ClientCorrelationId = "advise-correlation",
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.Advise,
+                Advise = new AdviseCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemHandle = itemHandle,
+                },
+            },
+        };
+    }
+
+    private sealed class GatewayServiceFixture : IAsyncDisposable
+    {
+        private readonly GatewayMetrics _metrics = new();
+        private readonly SessionRegistry _registry = new();
+
+        public GatewayServiceFixture(IWorkerProcessLauncher launcher)
+        {
+            IOptions<GatewayOptions> options = Options.Create(CreateOptions());
+            SessionWorkerClientFactory workerClientFactory = new(
+                launcher,
+                options,
+                _metrics,
+                NullLoggerFactory.Instance);
+            SessionManager sessionManager = new(
+                _registry,
+                workerClientFactory,
+                options,
+                _metrics,
+                logger: NullLogger<SessionManager>.Instance);
+            MxAccessGrpcMapper mapper = new();
+            EventStreamService eventStreamService = new(
+                sessionManager,
+                options,
+                mapper,
+                _metrics,
+                NullLogger<EventStreamService>.Instance);
+
+            Service = new MxAccessGatewayService(
+                sessionManager,
+                new GatewayRequestIdentityAccessor(),
+                new MxAccessGrpcRequestValidator(),
+                mapper,
+                eventStreamService,
+                NullLogger<MxAccessGatewayService>.Instance);
+        }
+
+        public MxAccessGatewayService Service { get; }
+
+        public async ValueTask DisposeAsync()
+        {
+            foreach (GatewaySession session in _registry.Snapshot())
+            {
+                await session.DisposeAsync();
+            }
+
+            _metrics.Dispose();
+        }
+
+        private static GatewayOptions CreateOptions()
+        {
+            return new GatewayOptions
+            {
+                Worker = new WorkerOptions
+                {
+                    StartupTimeoutSeconds = 5,
+                    ShutdownTimeoutSeconds = 5,
+                    HeartbeatIntervalSeconds = 30,
+                    HeartbeatGraceSeconds = 30,
+                    MaxMessageBytes = WorkerFrameProtocolOptions.DefaultMaxMessageBytes,
+                },
+                Sessions = new SessionOptions
+                {
+                    DefaultCommandTimeoutSeconds = 5,
+                    MaxSessions = 4,
+                },
+                Events = new EventOptions
+                {
+                    QueueCapacity = 16,
+                },
+            };
+        }
+    }
+
+    private sealed class ScriptedFakeWorkerProcessLauncher : IWorkerProcessLauncher
+    {
+        public const int ProcessId = 4680;
+        private readonly ConcurrentQueue<MxCommandKind> _commandKinds = new();
+
+        public FakeWorkerProcess Process { get; } = new(ProcessId);
+
+        public IReadOnlyCollection<MxCommandKind> CommandKinds => _commandKinds.ToArray();
+
+        public Task WorkerTask { get; private set; } = Task.CompletedTask;
+
+        public Task<WorkerProcessHandle> LaunchAsync(
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken = default)
+        {
+            WorkerTask = RunWorkerAsync(request, cancellationToken);
+
+            return Task.FromResult(new WorkerProcessHandle(
+                Process,
+                new WorkerProcessCommandLine("fake-worker.exe", []),
+                DateTimeOffset.UtcNow));
+        }
+
+        private async Task RunWorkerAsync(
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken)
+        {
+            await using FakeWorkerHarness harness = await FakeWorkerHarness.ConnectToGatewayPipeAsync(
+                request.SessionId,
+                request.Nonce,
+                request.PipeName,
+                request.ProtocolVersion,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+            await harness.CompleteStartupAsync(ProcessId, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                WorkerEnvelope envelope = await harness.ReadGatewayEnvelopeAsync(cancellationToken).ConfigureAwait(false);
+                if (envelope.BodyCase == WorkerEnvelope.BodyOneofCase.WorkerCommand)
+                {
+                    await ReplyToCommandAsync(harness, envelope, cancellationToken).ConfigureAwait(false);
+                    continue;
+                }
+
+                if (envelope.BodyCase == WorkerEnvelope.BodyOneofCase.WorkerShutdown)
+                {
+                    await harness.SendShutdownAckAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+                    Process.MarkExited(0);
+                    return;
+                }
+
+                throw new InvalidOperationException($"Unexpected gateway envelope {envelope.BodyCase}.");
+            }
+        }
+
+        private async Task ReplyToCommandAsync(
+            FakeWorkerHarness harness,
+            WorkerEnvelope commandEnvelope,
+            CancellationToken cancellationToken)
+        {
+            MxCommand command = commandEnvelope.WorkerCommand.Command;
+            _commandKinds.Enqueue(command.Kind);
+
+            await harness.ReplyToCommandAsync(
+                commandEnvelope,
+                configureReply: reply => ConfigureReply(reply, command.Kind),
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+
+            if (command.Kind == MxCommandKind.Advise)
+            {
+                await harness.EmitEventAsync(
+                    MxEventFamily.OnDataChange,
+                    cancellationToken,
+                    mxEvent =>
+                    {
+                        mxEvent.ServerHandle = command.Advise.ServerHandle;
+                        mxEvent.ItemHandle = command.Advise.ItemHandle;
+                        mxEvent.Quality = 192;
+                        mxEvent.Value = new MxValue
+                        {
+                            DataType = MxDataType.String,
+                            StringValue = "scripted-value",
+                        };
+                        mxEvent.OnDataChange = new OnDataChangeEvent();
+                    }).ConfigureAwait(false);
+            }
+        }
+
+        private static void ConfigureReply(
+            MxCommandReply reply,
+            MxCommandKind kind)
+        {
+            switch (kind)
+            {
+                case MxCommandKind.Register:
+                    reply.Register = new RegisterReply { ServerHandle = ServerHandle };
+                    break;
+                case MxCommandKind.AddItem:
+                    reply.AddItem = new AddItemReply { ItemHandle = ItemHandle };
+                    break;
+            }
+        }
+    }
+
+    private sealed class FakeWorkerProcess(int processId) : IWorkerProcess
+    {
+        public int Id { get; } = processId;
+
+        public bool HasExited { get; private set; }
+
+        public int? ExitCode { get; private set; }
+
+        public ValueTask WaitForExitAsync(CancellationToken cancellationToken)
+        {
+            HasExited = true;
+            ExitCode ??= 0;
+            return ValueTask.CompletedTask;
+        }
+
+        public void Kill(bool entireProcessTree)
+        {
+            MarkExited(-1);
+        }
+
+        public void Dispose()
+        {
+        }
+
+        public void MarkExited(int exitCode)
+        {
+            HasExited = true;
+            ExitCode = exitCode;
+        }
+    }
+
+    private sealed class RecordingServerStreamWriter<T> : IServerStreamWriter<T>
+    {
+        private readonly object _syncRoot = new();
+        private readonly TaskCompletionSource<T> _firstMessage = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        private readonly List<T> _messages = [];
+
+        public IReadOnlyList<T> Messages
+        {
+            get
+            {
+                lock (_syncRoot)
+                {
+                    return _messages.ToArray();
+                }
+            }
+        }
+
+        public WriteOptions? WriteOptions { get; set; }
+
+        public Task WriteAsync(T message)
+        {
+            lock (_syncRoot)
+            {
+                _messages.Add(message);
+            }
+
+            _firstMessage.TrySetResult(message);
+            return Task.CompletedTask;
+        }
+
+        public async Task<T> WaitForFirstMessageAsync(TimeSpan timeout)
+        {
+            return await _firstMessage.Task.WaitAsync(timeout).ConfigureAwait(false);
+        }
+    }
+
+    private sealed class TestServerCallContext(CancellationToken cancellationToken = default) : ServerCallContext
+    {
+        private readonly Metadata _requestHeaders = [];
+        private readonly Metadata _responseTrailers = [];
+        private readonly Dictionary<object, object> _userState = [];
+        private Status _status;
+        private WriteOptions? _writeOptions;
+
+        protected override string MethodCore => "/mxaccess_gateway.v1.MxAccessGateway/Test";
+
+        protected override string HostCore => "localhost";
+
+        protected override string PeerCore => "ipv4:127.0.0.1:5000";
+
+        protected override DateTime DeadlineCore => DateTime.UtcNow.AddMinutes(1);
+
+        protected override Metadata RequestHeadersCore => _requestHeaders;
+
+        protected override CancellationToken CancellationTokenCore => cancellationToken;
+
+        protected override Metadata ResponseTrailersCore => _responseTrailers;
+
+        protected override Status StatusCore
+        {
+            get => _status;
+            set => _status = value;
+        }
+
+        protected override WriteOptions? WriteOptionsCore
+        {
+            get => _writeOptions;
+            set => _writeOptions = value;
+        }
+
+        protected override AuthContext AuthContextCore { get; } = new(
+            string.Empty,
+            new Dictionary<string, List<AuthProperty>>(StringComparer.Ordinal));
+
+        protected override IDictionary<object, object> UserStateCore => _userState;
+
+        protected override Task WriteResponseHeadersAsyncCore(Metadata responseHeaders)
+        {
+            return Task.CompletedTask;
+        }
+
+        protected override ContextPropagationToken CreatePropagationTokenCore(
+            ContextPropagationOptions? options)
+        {
+            throw new NotSupportedException();
+        }
+    }
+}

src/MxGateway.Tests/Gateway/Sessions/SessionWorkerClientFactoryFakeWorkerTests.cs

@@ -0,0 +1,216 @@
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using MxGateway.Contracts;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Metrics;
+using MxGateway.Server.Sessions;
+using MxGateway.Server.Workers;
+using MxGateway.Tests.Gateway.Workers.Fakes;
+
+namespace MxGateway.Tests.Gateway.Sessions;
+
+public sealed class SessionWorkerClientFactoryFakeWorkerTests
+{
+    private static readonly TimeSpan TestTimeout = TimeSpan.FromSeconds(5);
+
+    [Fact]
+    public async Task CreateAsync_WithScriptedFakeWorker_ReturnsReadyClient()
+    {
+        ScriptedFakeWorkerProcessLauncher launcher = new();
+        using GatewayMetrics metrics = new();
+        SessionWorkerClientFactory factory = new(
+            launcher,
+            Options.Create(CreateOptions()),
+            metrics,
+            NullLoggerFactory.Instance);
+        GatewaySession session = CreateSession();
+
+        await using IWorkerClient workerClient = await factory.CreateAsync(
+            session,
+            CancellationToken.None);
+
+        Assert.Equal(WorkerClientState.Ready, workerClient.State);
+        Assert.Equal(ScriptedFakeWorkerProcessLauncher.ProcessId, workerClient.ProcessId);
+        Assert.NotNull(launcher.Harness);
+
+        Task<WorkerCommandReply> invokeTask = workerClient.InvokeAsync(
+            CreateCommand(MxCommandKind.Ping),
+            TestTimeout,
+            CancellationToken.None);
+        WorkerEnvelope commandEnvelope = await launcher.Harness.ReadCommandAsync();
+        await launcher.Harness.ReplyToCommandAsync(commandEnvelope);
+        WorkerCommandReply reply = await invokeTask.WaitAsync(TestTimeout);
+
+        Assert.Equal(MxCommandKind.Ping, reply.Reply.Kind);
+        Assert.Equal(ProtocolStatusCode.Ok, reply.Reply.ProtocolStatus.Code);
+    }
+
+    [Fact]
+    public async Task CreateAsync_WhenFakeWorkerStartupFails_ThrowsWorkerClientException()
+    {
+        FailingStartupWorkerProcessLauncher launcher = new();
+        using GatewayMetrics metrics = new();
+        SessionWorkerClientFactory factory = new(
+            launcher,
+            Options.Create(CreateOptions()),
+            metrics,
+            NullLoggerFactory.Instance);
+        GatewaySession session = CreateSession();
+
+        WorkerClientException exception = await Assert.ThrowsAsync<WorkerClientException>(
+            async () => await factory.CreateAsync(session, CancellationToken.None).WaitAsync(TestTimeout));
+
+        Assert.Equal(WorkerClientErrorCode.ProtocolViolation, exception.ErrorCode);
+        Assert.True(launcher.Process.IsDisposed);
+    }
+
+    private static GatewayOptions CreateOptions()
+    {
+        return new GatewayOptions
+        {
+            Worker = new WorkerOptions
+            {
+                StartupTimeoutSeconds = 5,
+                ShutdownTimeoutSeconds = 5,
+                HeartbeatIntervalSeconds = 30,
+                HeartbeatGraceSeconds = 30,
+                MaxMessageBytes = WorkerFrameProtocolOptions.DefaultMaxMessageBytes,
+            },
+            Events = new EventOptions
+            {
+                QueueCapacity = 16,
+            },
+        };
+    }
+
+    private static GatewaySession CreateSession()
+    {
+        return new GatewaySession(
+            FakeWorkerHarness.DefaultSessionId,
+            GatewayContractInfo.DefaultBackendName,
+            $"mxaccessgw-session-fake-worker-{Guid.NewGuid():N}",
+            FakeWorkerHarness.DefaultNonce,
+            "test-client",
+            "fake-worker-session-test",
+            "client-correlation-1",
+            TestTimeout,
+            TestTimeout,
+            TestTimeout,
+            DateTimeOffset.UtcNow);
+    }
+
+    private static WorkerCommand CreateCommand(MxCommandKind kind)
+    {
+        return new WorkerCommand
+        {
+            Command = new MxCommand
+            {
+                Kind = kind,
+            },
+        };
+    }
+
+    private sealed class ScriptedFakeWorkerProcessLauncher : IWorkerProcessLauncher
+    {
+        public const int ProcessId = 2468;
+        private readonly FakeWorkerProcess _process = new(ProcessId);
+
+        public FakeWorkerHarness? Harness { get; private set; }
+
+        public Task<WorkerProcessHandle> LaunchAsync(
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken = default)
+        {
+            _ = RunWorkerAsync(request, cancellationToken);
+
+            return Task.FromResult(CreateHandle(_process));
+        }
+
+        private async Task RunWorkerAsync(
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken)
+        {
+            Harness = await FakeWorkerHarness.ConnectToGatewayPipeAsync(
+                request.SessionId,
+                request.Nonce,
+                request.PipeName,
+                request.ProtocolVersion,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+            await Harness.CompleteStartupAsync(ProcessId, cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    private sealed class FailingStartupWorkerProcessLauncher : IWorkerProcessLauncher
+    {
+        public FakeWorkerProcess Process { get; } = new(processId: 3579);
+
+        public Task<WorkerProcessHandle> LaunchAsync(
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken = default)
+        {
+            _ = RunWorkerAsync(request, cancellationToken);
+
+            return Task.FromResult(CreateHandle(Process));
+        }
+
+        private async Task RunWorkerAsync(
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken)
+        {
+            await using FakeWorkerHarness harness = await FakeWorkerHarness.ConnectToGatewayPipeAsync(
+                request.SessionId,
+                request.Nonce,
+                request.PipeName,
+                request.ProtocolVersion,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+            _ = await harness.ReadGatewayEnvelopeAsync(cancellationToken).ConfigureAwait(false);
+            await harness.SendWorkerHelloAsync(
+                workerProcessId: Process.Id,
+                workerProtocolVersion: request.ProtocolVersion + 1,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    private static WorkerProcessHandle CreateHandle(IWorkerProcess process)
+    {
+        return new WorkerProcessHandle(
+            process,
+            new WorkerProcessCommandLine("fake-worker.exe", []),
+            DateTimeOffset.UtcNow);
+    }
+
+    private sealed class FakeWorkerProcess(int processId) : IWorkerProcess
+    {
+        private bool _disposed;
+
+        public int Id { get; } = processId;
+
+        public bool HasExited { get; private set; }
+
+        public int? ExitCode { get; private set; }
+
+        public int KillCount { get; private set; }
+
+        public ValueTask WaitForExitAsync(CancellationToken cancellationToken)
+        {
+            HasExited = true;
+            ExitCode = 0;
+            return ValueTask.CompletedTask;
+        }
+
+        public void Kill(bool entireProcessTree)
+        {
+            KillCount++;
+            HasExited = true;
+            ExitCode = -1;
+        }
+
+        public void Dispose()
+        {
+            _disposed = true;
+        }
+
+        public bool IsDisposed => _disposed;
+    }
+}

src/MxGateway.Tests/Gateway/Workers/FakeWorkerHarnessTests.cs

@@ -0,0 +1,190 @@
+using MxGateway.Contracts;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Workers;
+using MxGateway.Tests.Gateway.Workers.Fakes;
+
+namespace MxGateway.Tests.Gateway.Workers;
+
+public sealed class FakeWorkerHarnessTests
+{
+    private static readonly TimeSpan TestTimeout = TimeSpan.FromSeconds(5);
+
+    [Fact]
+    public async Task CompleteStartupAsync_WithHelloAndReady_TransitionsClientToReady()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+
+        Task startTask = client.StartAsync(CancellationToken.None);
+        WorkerEnvelope gatewayHello = await fakeWorker.CompleteStartupAsync();
+        await startTask.WaitAsync(TestTimeout);
+
+        Assert.Equal(WorkerEnvelope.BodyOneofCase.GatewayHello, gatewayHello.BodyCase);
+        Assert.Equal(FakeWorkerHarness.DefaultNonce, gatewayHello.GatewayHello.Nonce);
+        Assert.Equal(WorkerClientState.Ready, client.State);
+        Assert.Equal(FakeWorkerHarness.DefaultWorkerProcessId, client.ProcessId);
+    }
+
+    [Fact]
+    public async Task StartAsync_WithProtocolMismatch_FailsStartup()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+
+        Task startTask = client.StartAsync(CancellationToken.None);
+        WorkerEnvelope gatewayHello = await fakeWorker.ReadGatewayEnvelopeAsync();
+        Assert.Equal(WorkerEnvelope.BodyOneofCase.GatewayHello, gatewayHello.BodyCase);
+        await fakeWorker.SendWorkerHelloAsync(
+            workerProtocolVersion: GatewayContractInfo.WorkerProtocolVersion + 1);
+
+        WorkerClientException exception = await Assert.ThrowsAsync<WorkerClientException>(
+            async () => await startTask.WaitAsync(TestTimeout));
+
+        Assert.Equal(WorkerClientErrorCode.ProtocolViolation, exception.ErrorCode);
+    }
+
+    [Fact]
+    public async Task InvokeAsync_WithScriptedReply_CompletesCommand()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+        await StartClientAsync(fakeWorker, client);
+
+        Task<WorkerCommandReply> invokeTask = client.InvokeAsync(
+            CreateCommand(MxCommandKind.Ping),
+            TestTimeout,
+            CancellationToken.None);
+        WorkerEnvelope commandEnvelope = await fakeWorker.ReadCommandAsync();
+        await fakeWorker.ReplyToCommandAsync(commandEnvelope);
+
+        WorkerCommandReply reply = await invokeTask.WaitAsync(TestTimeout);
+
+        Assert.Equal(commandEnvelope.CorrelationId, reply.Reply.CorrelationId);
+        Assert.Equal(MxCommandKind.Ping, reply.Reply.Kind);
+        Assert.Equal(ProtocolStatusCode.Ok, reply.Reply.ProtocolStatus.Code);
+    }
+
+    [Fact]
+    public async Task ReadEventsAsync_WithScriptedEvents_YieldsOrderedEvents()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+        await StartClientAsync(fakeWorker, client);
+        using CancellationTokenSource cancellationTokenSource = new(TestTimeout);
+
+        await using IAsyncEnumerator<WorkerEvent> events =
+            client.ReadEventsAsync(cancellationTokenSource.Token).GetAsyncEnumerator(cancellationTokenSource.Token);
+
+        await fakeWorker.EmitEventAsync(MxEventFamily.OnDataChange, cancellationTokenSource.Token);
+        await fakeWorker.EmitEventAsync(MxEventFamily.OperationComplete, cancellationTokenSource.Token);
+
+        Assert.True(await events.MoveNextAsync());
+        Assert.Equal((ulong)3, events.Current.Event.WorkerSequence);
+        Assert.Equal(MxEventFamily.OnDataChange, events.Current.Event.Family);
+
+        Assert.True(await events.MoveNextAsync());
+        Assert.Equal((ulong)4, events.Current.Event.WorkerSequence);
+        Assert.Equal(MxEventFamily.OperationComplete, events.Current.Event.Family);
+    }
+
+    [Fact]
+    public async Task ReadLoop_WithScriptedFault_FaultsClient()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+        await StartClientAsync(fakeWorker, client);
+
+        await fakeWorker.EmitFaultAsync(
+            WorkerFaultCategory.MxaccessCommandFailed,
+            "scripted MXAccess command fault");
+
+        await WaitUntilAsync(
+            () => client.State == WorkerClientState.Faulted,
+            TestTimeout);
+
+        Assert.Equal(WorkerClientState.Faulted, client.State);
+    }
+
+    [Fact]
+    public async Task InvokeAsync_WithHungWorker_TimesOutPendingCommand()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+        await StartClientAsync(fakeWorker, client);
+
+        Task<WorkerCommandReply> invokeTask = client.InvokeAsync(
+            CreateCommand(MxCommandKind.Ping),
+            TimeSpan.FromMilliseconds(50),
+            CancellationToken.None);
+        WorkerEnvelope commandEnvelope = await fakeWorker.ReadCommandAsync();
+
+        WorkerClientException exception = await Assert.ThrowsAsync<WorkerClientException>(
+            async () => await invokeTask.WaitAsync(TestTimeout));
+
+        Assert.Equal(WorkerEnvelope.BodyOneofCase.WorkerCommand, commandEnvelope.BodyCase);
+        Assert.Equal(WorkerClientErrorCode.CommandTimeout, exception.ErrorCode);
+    }
+
+    [Fact]
+    public async Task ReadLoop_WithMalformedFrame_FaultsClient()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+        await StartClientAsync(fakeWorker, client);
+
+        await fakeWorker.WriteMalformedPayloadAsync(new byte[] { 0x08, 0x96, 0x01 });
+
+        await WaitUntilAsync(
+            () => client.State == WorkerClientState.Faulted,
+            TestTimeout);
+
+        Assert.Equal(WorkerClientState.Faulted, client.State);
+    }
+
+    [Fact]
+    public async Task ShutdownAsync_WithShutdownAck_ClosesClient()
+    {
+        await using FakeWorkerHarness fakeWorker = await FakeWorkerHarness.CreateConnectedPairAsync();
+        await using WorkerClient client = fakeWorker.CreateClient();
+        await StartClientAsync(fakeWorker, client);
+
+        Task shutdownTask = client.ShutdownAsync(TestTimeout, CancellationToken.None);
+        WorkerEnvelope shutdownEnvelope = await fakeWorker.ReadShutdownAsync();
+        await fakeWorker.SendShutdownAckAsync();
+        await shutdownTask.WaitAsync(TestTimeout);
+
+        Assert.Equal(WorkerEnvelope.BodyOneofCase.WorkerShutdown, shutdownEnvelope.BodyCase);
+        Assert.Equal(WorkerClientState.Closed, client.State);
+    }
+
+    private static async Task StartClientAsync(
+        FakeWorkerHarness fakeWorker,
+        WorkerClient client)
+    {
+        Task startTask = client.StartAsync(CancellationToken.None);
+        await fakeWorker.CompleteStartupAsync().ConfigureAwait(false);
+        await startTask.WaitAsync(TestTimeout).ConfigureAwait(false);
+    }
+
+    private static WorkerCommand CreateCommand(MxCommandKind kind)
+    {
+        return new WorkerCommand
+        {
+            Command = new MxCommand
+            {
+                Kind = kind,
+            },
+        };
+    }
+
+    private static async Task WaitUntilAsync(
+        Func<bool> predicate,
+        TimeSpan timeout)
+    {
+        using CancellationTokenSource cancellationTokenSource = new(timeout);
+        while (!predicate())
+        {
+            await Task.Delay(TimeSpan.FromMilliseconds(10), cancellationTokenSource.Token);
+        }
+    }
+}

src/MxGateway.Tests/Gateway/Workers/Fakes/FakeWorkerHarness.cs

@@ -0,0 +1,386 @@
+using System.Buffers.Binary;
+using System.IO.Pipes;
+using Google.Protobuf.WellKnownTypes;
+using MxGateway.Contracts;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Metrics;
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Tests.Gateway.Workers.Fakes;
+
+public sealed class FakeWorkerHarness : IAsyncDisposable
+{
+    public const string DefaultSessionId = "session-fake-worker";
+    public const string DefaultNonce = "nonce-fake-worker";
+    public const int DefaultWorkerProcessId = 9321;
+
+    private readonly NamedPipeServerStream? _gatewayStream;
+    private readonly NamedPipeClientStream _workerStream;
+    private readonly WorkerFrameProtocolOptions _frameOptions;
+    private readonly WorkerFrameReader _reader;
+    private readonly WorkerFrameWriter _writer;
+    private bool _workerSideDisposed;
+
+    private FakeWorkerHarness(
+        string sessionId,
+        string nonce,
+        NamedPipeServerStream? gatewayStream,
+        NamedPipeClientStream workerStream,
+        WorkerFrameProtocolOptions frameOptions)
+    {
+        SessionId = sessionId;
+        Nonce = nonce;
+        _gatewayStream = gatewayStream;
+        _workerStream = workerStream;
+        _frameOptions = frameOptions;
+        _reader = new WorkerFrameReader(_workerStream, frameOptions);
+        _writer = new WorkerFrameWriter(_workerStream, frameOptions);
+    }
+
+    public string SessionId { get; }
+
+    public string Nonce { get; }
+
+    public ulong NextWorkerSequence { get; private set; }
+
+    public static async Task<FakeWorkerHarness> CreateConnectedPairAsync(
+        string sessionId = DefaultSessionId,
+        string nonce = DefaultNonce,
+        uint protocolVersion = GatewayContractInfo.WorkerProtocolVersion,
+        int maxMessageBytes = WorkerFrameProtocolOptions.DefaultMaxMessageBytes,
+        CancellationToken cancellationToken = default)
+    {
+        string pipeName = $"mxaccessgw-fake-worker-{Guid.NewGuid():N}";
+        NamedPipeServerStream gatewayStream = new(
+            pipeName,
+            PipeDirection.InOut,
+            maxNumberOfServerInstances: 1,
+            PipeTransmissionMode.Byte,
+            PipeOptions.Asynchronous);
+        NamedPipeClientStream workerStream = CreateWorkerStream(pipeName);
+
+        Task waitForConnectionTask = gatewayStream.WaitForConnectionAsync(cancellationToken);
+        await workerStream.ConnectAsync(cancellationToken).ConfigureAwait(false);
+        await waitForConnectionTask.ConfigureAwait(false);
+
+        return new FakeWorkerHarness(
+            sessionId,
+            nonce,
+            gatewayStream,
+            workerStream,
+            new WorkerFrameProtocolOptions(sessionId, protocolVersion, maxMessageBytes));
+    }
+
+    public static async Task<FakeWorkerHarness> ConnectToGatewayPipeAsync(
+        string sessionId,
+        string nonce,
+        string pipeName,
+        uint protocolVersion = GatewayContractInfo.WorkerProtocolVersion,
+        int maxMessageBytes = WorkerFrameProtocolOptions.DefaultMaxMessageBytes,
+        CancellationToken cancellationToken = default)
+    {
+        NamedPipeClientStream workerStream = CreateWorkerStream(pipeName);
+        await workerStream.ConnectAsync(cancellationToken).ConfigureAwait(false);
+
+        return new FakeWorkerHarness(
+            sessionId,
+            nonce,
+            gatewayStream: null,
+            workerStream,
+            new WorkerFrameProtocolOptions(sessionId, protocolVersion, maxMessageBytes));
+    }
+
+    public WorkerClient CreateClient(
+        WorkerClientOptions? options = null,
+        GatewayMetrics? metrics = null,
+        TimeProvider? timeProvider = null)
+    {
+        if (_gatewayStream is null)
+        {
+            throw new InvalidOperationException("This fake worker is connected to a gateway-owned pipe.");
+        }
+
+        WorkerClientConnection connection = new(
+            SessionId,
+            Nonce,
+            _gatewayStream,
+            _frameOptions);
+
+        return new WorkerClient(connection, options, metrics, timeProvider);
+    }
+
+    public async Task<WorkerEnvelope> CompleteStartupAsync(
+        int workerProcessId = DefaultWorkerProcessId,
+        string workerVersion = "fake-worker",
+        string mxaccessProgid = "LMXProxy.LMXProxyServer.1",
+        string mxaccessClsid = "{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}",
+        CancellationToken cancellationToken = default)
+    {
+        WorkerEnvelope gatewayHello = await ReadGatewayEnvelopeAsync(cancellationToken).ConfigureAwait(false);
+        if (gatewayHello.BodyCase != WorkerEnvelope.BodyOneofCase.GatewayHello)
+        {
+            throw new InvalidOperationException($"Expected GatewayHello but received {gatewayHello.BodyCase}.");
+        }
+
+        await SendWorkerHelloAsync(
+            workerProcessId,
+            workerVersion,
+            cancellationToken: cancellationToken).ConfigureAwait(false);
+        await SendWorkerReadyAsync(
+            workerProcessId,
+            mxaccessProgid,
+            mxaccessClsid,
+            cancellationToken).ConfigureAwait(false);
+
+        return gatewayHello;
+    }
+
+    public async Task<WorkerEnvelope> ReadGatewayEnvelopeAsync(CancellationToken cancellationToken = default)
+    {
+        return await _reader.ReadAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task<WorkerEnvelope> ReadCommandAsync(CancellationToken cancellationToken = default)
+    {
+        WorkerEnvelope envelope = await ReadGatewayEnvelopeAsync(cancellationToken).ConfigureAwait(false);
+        if (envelope.BodyCase != WorkerEnvelope.BodyOneofCase.WorkerCommand)
+        {
+            throw new InvalidOperationException($"Expected WorkerCommand but received {envelope.BodyCase}.");
+        }
+
+        return envelope;
+    }
+
+    public async Task<WorkerEnvelope> ReadShutdownAsync(CancellationToken cancellationToken = default)
+    {
+        WorkerEnvelope envelope = await ReadGatewayEnvelopeAsync(cancellationToken).ConfigureAwait(false);
+        if (envelope.BodyCase != WorkerEnvelope.BodyOneofCase.WorkerShutdown)
+        {
+            throw new InvalidOperationException($"Expected WorkerShutdown but received {envelope.BodyCase}.");
+        }
+
+        return envelope;
+    }
+
+    public async Task SendWorkerHelloAsync(
+        int workerProcessId = DefaultWorkerProcessId,
+        string workerVersion = "fake-worker",
+        uint? workerProtocolVersion = null,
+        string? nonce = null,
+        CancellationToken cancellationToken = default)
+    {
+        await _writer.WriteAsync(
+            CreateEnvelope(
+                correlationId: string.Empty,
+                envelope => envelope.WorkerHello = new WorkerHello
+                {
+                    ProtocolVersion = workerProtocolVersion ?? _frameOptions.ProtocolVersion,
+                    Nonce = nonce ?? Nonce,
+                    WorkerProcessId = workerProcessId,
+                    WorkerVersion = workerVersion,
+                }),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task SendWorkerReadyAsync(
+        int workerProcessId = DefaultWorkerProcessId,
+        string mxaccessProgid = "LMXProxy.LMXProxyServer.1",
+        string mxaccessClsid = "{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}",
+        CancellationToken cancellationToken = default)
+    {
+        await _writer.WriteAsync(
+            CreateEnvelope(
+                correlationId: string.Empty,
+                envelope => envelope.WorkerReady = new WorkerReady
+                {
+                    WorkerProcessId = workerProcessId,
+                    MxaccessProgid = mxaccessProgid,
+                    MxaccessClsid = mxaccessClsid,
+                    ReadyTimestamp = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+                }),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task ReplyToCommandAsync(
+        WorkerEnvelope commandEnvelope,
+        ProtocolStatusCode statusCode = ProtocolStatusCode.Ok,
+        string statusMessage = "OK",
+        Action<MxCommandReply>? configureReply = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (commandEnvelope.BodyCase != WorkerEnvelope.BodyOneofCase.WorkerCommand)
+        {
+            throw new ArgumentException("Command envelope must contain WorkerCommand.", nameof(commandEnvelope));
+        }
+
+        MxCommandKind kind = commandEnvelope.WorkerCommand.Command?.Kind ?? MxCommandKind.Unspecified;
+        MxCommandReply reply = new()
+        {
+            SessionId = SessionId,
+            CorrelationId = commandEnvelope.CorrelationId,
+            Kind = kind,
+            ProtocolStatus = new ProtocolStatus
+            {
+                Code = statusCode,
+                Message = statusMessage,
+            },
+        };
+        configureReply?.Invoke(reply);
+
+        await _writer.WriteAsync(
+            CreateEnvelope(
+                commandEnvelope.CorrelationId,
+                envelope => envelope.WorkerCommandReply = new WorkerCommandReply
+                {
+                    Reply = reply,
+                    CompletedTimestamp = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+                }),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task EmitEventAsync(
+        MxEventFamily family,
+        CancellationToken cancellationToken = default,
+        Action<MxEvent>? configureEvent = null)
+    {
+        ulong sequence = NextWorkerSequence + 1;
+        MxEvent mxEvent = new()
+        {
+            SessionId = SessionId,
+            Family = family,
+            WorkerSequence = sequence,
+            WorkerTimestamp = Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
+        };
+        configureEvent?.Invoke(mxEvent);
+
+        await _writer.WriteAsync(
+            CreateEnvelope(
+                correlationId: string.Empty,
+                envelope => envelope.WorkerEvent = new WorkerEvent
+                {
+                    Event = mxEvent,
+                }),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task EmitFaultAsync(
+        WorkerFaultCategory category,
+        string diagnosticMessage,
+        CancellationToken cancellationToken = default)
+    {
+        await _writer.WriteAsync(
+            CreateEnvelope(
+                correlationId: string.Empty,
+                envelope => envelope.WorkerFault = new WorkerFault
+                {
+                    Category = category,
+                    DiagnosticMessage = diagnosticMessage,
+                    ProtocolStatus = new ProtocolStatus
+                    {
+                        Code = ProtocolStatusCode.WorkerUnavailable,
+                        Message = diagnosticMessage,
+                    },
+                }),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task SendShutdownAckAsync(
+        ProtocolStatusCode statusCode = ProtocolStatusCode.Ok,
+        CancellationToken cancellationToken = default)
+    {
+        await _writer.WriteAsync(
+            CreateEnvelope(
+                correlationId: string.Empty,
+                envelope => envelope.WorkerShutdownAck = new WorkerShutdownAck
+                {
+                    Status = new ProtocolStatus
+                    {
+                        Code = statusCode,
+                        Message = statusCode.ToString(),
+                    },
+                }),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task WriteMalformedPayloadAsync(
+        ReadOnlyMemory<byte> payload,
+        CancellationToken cancellationToken = default)
+    {
+        if (payload.IsEmpty)
+        {
+            throw new ArgumentException("Malformed payload must include at least one byte.", nameof(payload));
+        }
+
+        byte[] lengthPrefix = new byte[sizeof(uint)];
+        BinaryPrimitives.WriteUInt32LittleEndian(lengthPrefix, (uint)payload.Length);
+        await _workerStream.WriteAsync(lengthPrefix, cancellationToken).ConfigureAwait(false);
+        await _workerStream.WriteAsync(payload, cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task WriteOversizedFrameHeaderAsync(
+        uint payloadLength,
+        CancellationToken cancellationToken = default)
+    {
+        if (payloadLength <= _frameOptions.MaxMessageBytes)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(payloadLength),
+                payloadLength,
+                "Payload length must exceed the configured maximum.");
+        }
+
+        byte[] lengthPrefix = new byte[sizeof(uint)];
+        BinaryPrimitives.WriteUInt32LittleEndian(lengthPrefix, payloadLength);
+        await _workerStream.WriteAsync(lengthPrefix, cancellationToken).ConfigureAwait(false);
+    }
+
+    public async ValueTask DisposeWorkerSideAsync()
+    {
+        if (_workerSideDisposed)
+        {
+            return;
+        }
+
+        await _workerStream.DisposeAsync().ConfigureAwait(false);
+        _workerSideDisposed = true;
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await DisposeWorkerSideAsync().ConfigureAwait(false);
+        if (_gatewayStream is not null)
+        {
+            await _gatewayStream.DisposeAsync().ConfigureAwait(false);
+        }
+    }
+
+    private WorkerEnvelope CreateEnvelope(
+        string correlationId,
+        Action<WorkerEnvelope> setBody)
+    {
+        WorkerEnvelope envelope = new()
+        {
+            ProtocolVersion = _frameOptions.ProtocolVersion,
+            SessionId = SessionId,
+            Sequence = AdvanceSequence(),
+            CorrelationId = correlationId,
+        };
+        setBody(envelope);
+
+        return envelope;
+    }
+
+    private ulong AdvanceSequence()
+    {
+        return ++NextWorkerSequence;
+    }
+
+    private static NamedPipeClientStream CreateWorkerStream(string pipeName)
+    {
+        return new NamedPipeClientStream(
+            ".",
+            pipeName,
+            PipeDirection.InOut,
+            PipeOptions.Asynchronous);
+    }
+}

src/MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs

@@ -78,6 +78,166 @@ public sealed class MxAccessCommandExecutorTests
         Assert.Equal(44, registeredServerHandle.ServerHandle);
     }
 
+    [Fact]
+    public async Task DispatchAsync_AddItem_CallsMxAccessOnStaAndTracksItemHandle()
+    {
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 46,
+            addItemHandle: 501);
+        FakeMxAccessComObjectFactory factory = new(fakeComObject);
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+        await session.StartAsync(workerProcessId: 1234);
+        await session.DispatchAsync(CreateRegisterCommand("register-before-add", "client-a"));
+
+        MxCommandReply reply = await session.DispatchAsync(CreateAddItemCommand(
+            "add-item",
+            46,
+            "Galaxy.Tag.Value"));
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.True(reply.HasHresult);
+        Assert.Equal(0, reply.Hresult);
+        Assert.Equal(501, reply.AddItem.ItemHandle);
+        Assert.Equal(MxDataType.Integer, reply.ReturnValue.DataType);
+        Assert.Equal(501, reply.ReturnValue.Int32Value);
+        Assert.Equal(46, fakeComObject.AddItemServerHandle);
+        Assert.Equal("Galaxy.Tag.Value", fakeComObject.AddItemDefinition);
+        Assert.Equal(runtime.StaThreadId, fakeComObject.AddItemThreadId);
+
+        RegisteredItemHandle registeredItemHandle = Assert.Single(
+            await session.GetRegisteredItemHandlesAsync());
+        Assert.Equal(46, registeredItemHandle.ServerHandle);
+        Assert.Equal(501, registeredItemHandle.ItemHandle);
+        Assert.Equal("Galaxy.Tag.Value", registeredItemHandle.ItemDefinition);
+        Assert.Equal(string.Empty, registeredItemHandle.ItemContext);
+        Assert.False(registeredItemHandle.HasItemContext);
+    }
+
+    [Fact]
+    public async Task DispatchAsync_AddItem2_PassesContextExactlyAndTracksItemHandle()
+    {
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 47,
+            addItem2Handle: 502);
+        FakeMxAccessComObjectFactory factory = new(fakeComObject);
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+        await session.StartAsync(workerProcessId: 1234);
+        await session.DispatchAsync(CreateRegisterCommand("register-before-add2", "client-a"));
+
+        MxCommandReply reply = await session.DispatchAsync(CreateAddItem2Command(
+            "add-item2",
+            47,
+            "TestInt",
+            "TestChildObject"));
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.Equal(502, reply.AddItem2.ItemHandle);
+        Assert.Equal(MxDataType.Integer, reply.ReturnValue.DataType);
+        Assert.Equal(502, reply.ReturnValue.Int32Value);
+        Assert.Equal(47, fakeComObject.AddItem2ServerHandle);
+        Assert.Equal("TestInt", fakeComObject.AddItem2Definition);
+        Assert.Equal("TestChildObject", fakeComObject.AddItem2Context);
+        Assert.Equal(runtime.StaThreadId, fakeComObject.AddItem2ThreadId);
+
+        RegisteredItemHandle registeredItemHandle = Assert.Single(
+            await session.GetRegisteredItemHandlesAsync());
+        Assert.Equal(47, registeredItemHandle.ServerHandle);
+        Assert.Equal(502, registeredItemHandle.ItemHandle);
+        Assert.Equal("TestInt", registeredItemHandle.ItemDefinition);
+        Assert.Equal("TestChildObject", registeredItemHandle.ItemContext);
+        Assert.True(registeredItemHandle.HasItemContext);
+    }
+
+    [Fact]
+    public async Task DispatchAsync_RemoveItem_CallsMxAccessOnStaAndRemovesTrackedItemHandle()
+    {
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 48,
+            addItemHandle: 503);
+        FakeMxAccessComObjectFactory factory = new(fakeComObject);
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+        await session.StartAsync(workerProcessId: 1234);
+        await session.DispatchAsync(CreateRegisterCommand("register-before-remove", "client-a"));
+        await session.DispatchAsync(CreateAddItemCommand("add-before-remove", 48, "Galaxy.Tag.Value"));
+
+        MxCommandReply reply = await session.DispatchAsync(CreateRemoveItemCommand(
+            "remove-item",
+            48,
+            503));
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.True(reply.HasHresult);
+        Assert.Equal(0, reply.Hresult);
+        Assert.Equal(48, fakeComObject.RemoveItemServerHandle);
+        Assert.Equal(503, fakeComObject.RemovedItemHandle);
+        Assert.Equal(runtime.StaThreadId, fakeComObject.RemoveItemThreadId);
+        Assert.Empty(await session.GetRegisteredItemHandlesAsync());
+    }
+
+    [Fact]
+    public async Task DispatchAsync_RemoveItemWithCrossServerHandle_PreservesHResultAndKeepsTrackedItemHandle()
+    {
+        const int hresult = unchecked((int)0x80070057);
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 49,
+            addItemHandle: 504,
+            removeItemException: new COMException("Invalid item handle.", hresult));
+        FakeMxAccessComObjectFactory factory = new(fakeComObject);
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+        await session.StartAsync(workerProcessId: 1234);
+        await session.DispatchAsync(CreateRegisterCommand("register-before-remove-failure", "client-a"));
+        await session.DispatchAsync(CreateAddItemCommand("add-before-remove-failure", 49, "Galaxy.Tag.Value"));
+
+        MxCommandReply reply = await session.DispatchAsync(CreateRemoveItemCommand(
+            "remove-item-failure",
+            999,
+            504));
+
+        Assert.Equal(ProtocolStatusCode.MxaccessFailure, reply.ProtocolStatus.Code);
+        Assert.True(reply.HasHresult);
+        Assert.Equal(hresult, reply.Hresult);
+        Assert.Contains("0x80070057", reply.DiagnosticMessage);
+        Assert.Equal(999, fakeComObject.RemoveItemServerHandle);
+        Assert.Equal(504, fakeComObject.RemovedItemHandle);
+
+        RegisteredItemHandle registeredItemHandle = Assert.Single(
+            await session.GetRegisteredItemHandlesAsync());
+        Assert.Equal(49, registeredItemHandle.ServerHandle);
+        Assert.Equal(504, registeredItemHandle.ItemHandle);
+    }
+
+    [Fact]
+    public async Task DispatchAsync_AddItem2WhenMxAccessThrows_PreservesHResultAndDoesNotTrackItemHandle()
+    {
+        const int hresult = unchecked((int)0x80070057);
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 50,
+            addItem2Exception: new COMException("Invalid server handle.", hresult));
+        FakeMxAccessComObjectFactory factory = new(fakeComObject);
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+        await session.StartAsync(workerProcessId: 1234);
+
+        MxCommandReply reply = await session.DispatchAsync(CreateAddItem2Command(
+            "add-item2-failure",
+            9001,
+            "TestInt",
+            "TestChildObject"));
+
+        Assert.Equal(ProtocolStatusCode.MxaccessFailure, reply.ProtocolStatus.Code);
+        Assert.True(reply.HasHresult);
+        Assert.Equal(hresult, reply.Hresult);
+        Assert.Contains("0x80070057", reply.DiagnosticMessage);
+        Assert.Equal(9001, fakeComObject.AddItem2ServerHandle);
+        Assert.Equal("TestInt", fakeComObject.AddItem2Definition);
+        Assert.Equal("TestChildObject", fakeComObject.AddItem2Context);
+        Assert.Empty(await session.GetRegisteredItemHandlesAsync());
+    }
+
     [Fact]
     public async Task DispatchAsync_RegisterWithoutPayload_ReturnsInvalidRequest()
     {
@@ -98,6 +258,26 @@ public sealed class MxAccessCommandExecutorTests
         Assert.Null(factory.FakeComObject.RegisteredClientName);
     }
 
+    [Fact]
+    public async Task DispatchAsync_AddItemWithoutPayload_ReturnsInvalidRequest()
+    {
+        FakeMxAccessComObjectFactory factory = new(new FakeMxAccessComObject(registerHandle: 51));
+        using StaRuntime runtime = CreateRuntime();
+        using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+        await session.StartAsync(workerProcessId: 1234);
+
+        MxCommandReply reply = await session.DispatchAsync(new StaCommand(
+            "session-1",
+            "missing-add-payload",
+            new MxCommand
+            {
+                Kind = MxCommandKind.AddItem,
+            }));
+
+        Assert.Equal(ProtocolStatusCode.InvalidRequest, reply.ProtocolStatus.Code);
+        Assert.Null(factory.FakeComObject.AddItemDefinition);
+    }
+
     private static StaCommand CreateRegisterCommand(
         string correlationId,
         string clientName)
@@ -132,6 +312,65 @@ public sealed class MxAccessCommandExecutorTests
             });
     }
 
+    private static StaCommand CreateAddItemCommand(
+        string correlationId,
+        int serverHandle,
+        string itemDefinition)
+    {
+        return new StaCommand(
+            "session-1",
+            correlationId,
+            new MxCommand
+            {
+                Kind = MxCommandKind.AddItem,
+                AddItem = new AddItemCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemDefinition = itemDefinition,
+                },
+            });
+    }
+
+    private static StaCommand CreateAddItem2Command(
+        string correlationId,
+        int serverHandle,
+        string itemDefinition,
+        string itemContext)
+    {
+        return new StaCommand(
+            "session-1",
+            correlationId,
+            new MxCommand
+            {
+                Kind = MxCommandKind.AddItem2,
+                AddItem2 = new AddItem2Command
+                {
+                    ServerHandle = serverHandle,
+                    ItemDefinition = itemDefinition,
+                    ItemContext = itemContext,
+                },
+            });
+    }
+
+    private static StaCommand CreateRemoveItemCommand(
+        string correlationId,
+        int serverHandle,
+        int itemHandle)
+    {
+        return new StaCommand(
+            "session-1",
+            correlationId,
+            new MxCommand
+            {
+                Kind = MxCommandKind.RemoveItem,
+                RemoveItem = new RemoveItemCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemHandle = itemHandle,
+                },
+            });
+    }
+
     private static StaRuntime CreateRuntime()
     {
         return new StaRuntime(
@@ -143,14 +382,29 @@ public sealed class MxAccessCommandExecutorTests
     private sealed class FakeMxAccessComObject
     {
         private readonly int registerHandle;
+        private readonly int addItemHandle;
+        private readonly int addItem2Handle;
         private readonly Exception? unregisterException;
+        private readonly Exception? addItemException;
+        private readonly Exception? addItem2Exception;
+        private readonly Exception? removeItemException;
 
         public FakeMxAccessComObject(
             int registerHandle,
-            Exception? unregisterException = null)
+            int addItemHandle = 0,
+            int addItem2Handle = 0,
+            Exception? unregisterException = null,
+            Exception? addItemException = null,
+            Exception? addItem2Exception = null,
+            Exception? removeItemException = null)
         {
             this.registerHandle = registerHandle;
+            this.addItemHandle = addItemHandle;
+            this.addItem2Handle = addItem2Handle;
             this.unregisterException = unregisterException;
+            this.addItemException = addItemException;
+            this.addItem2Exception = addItem2Exception;
+            this.removeItemException = removeItemException;
         }
 
         public string? RegisteredClientName { get; private set; }
@@ -161,6 +415,26 @@ public sealed class MxAccessCommandExecutorTests
 
         public int? UnregisterThreadId { get; private set; }
 
+        public int? AddItemServerHandle { get; private set; }
+
+        public string? AddItemDefinition { get; private set; }
+
+        public int? AddItemThreadId { get; private set; }
+
+        public int? AddItem2ServerHandle { get; private set; }
+
+        public string? AddItem2Definition { get; private set; }
+
+        public string? AddItem2Context { get; private set; }
+
+        public int? AddItem2ThreadId { get; private set; }
+
+        public int? RemoveItemServerHandle { get; private set; }
+
+        public int? RemovedItemHandle { get; private set; }
+
+        public int? RemoveItemThreadId { get; private set; }
+
         public int Register(string clientName)
         {
             RegisteredClientName = clientName;
@@ -179,6 +453,54 @@ public sealed class MxAccessCommandExecutorTests
                 throw unregisterException;
             }
         }
+
+        public int AddItem(
+            int serverHandle,
+            string itemDefinition)
+        {
+            AddItemServerHandle = serverHandle;
+            AddItemDefinition = itemDefinition;
+            AddItemThreadId = Environment.CurrentManagedThreadId;
+
+            if (addItemException is not null)
+            {
+                throw addItemException;
+            }
+
+            return addItemHandle;
+        }
+
+        public int AddItem2(
+            int serverHandle,
+            string itemDefinition,
+            string itemContext)
+        {
+            AddItem2ServerHandle = serverHandle;
+            AddItem2Definition = itemDefinition;
+            AddItem2Context = itemContext;
+            AddItem2ThreadId = Environment.CurrentManagedThreadId;
+
+            if (addItem2Exception is not null)
+            {
+                throw addItem2Exception;
+            }
+
+            return addItem2Handle;
+        }
+
+        public void RemoveItem(
+            int serverHandle,
+            int itemHandle)
+        {
+            RemoveItemServerHandle = serverHandle;
+            RemovedItemHandle = itemHandle;
+            RemoveItemThreadId = Environment.CurrentManagedThreadId;
+
+            if (removeItemException is not null)
+            {
+                throw removeItemException;
+            }
+        }
     }
 
     private sealed class FakeMxAccessComObjectFactory : IMxAccessComObjectFactory

src/MxGateway.Worker.Tests/MxAccess/MxAccessLiveComCreationTests.cs

@@ -8,6 +8,11 @@ namespace MxGateway.Worker.Tests.MxAccess;
 
 public sealed class MxAccessLiveComCreationTests
 {
+    private const string LiveClientName = "MxGateway.Worker.Tests";
+    private const string DefaultLiveAddItemReference = "TestChildObject.TestInt";
+    private const string DefaultLiveAddItem2Definition = "TestInt";
+    private const string DefaultLiveAddItem2Context = "TestChildObject";
+
     [Fact]
     public async Task StartAsync_WhenOptedIn_CreatesInstalledMxAccessComObjectOnSta()
     {
@@ -43,7 +48,7 @@ public sealed class MxAccessLiveComCreationTests
                 Kind = MxCommandKind.Register,
                 Register = new RegisterCommand
                 {
-                    ClientName = "MxGateway.Worker.Tests",
+                    ClientName = LiveClientName,
                 },
             }));
 
@@ -65,6 +70,151 @@ public sealed class MxAccessLiveComCreationTests
         Assert.Equal(ProtocolStatusCode.Ok, unregisterReply.ProtocolStatus.Code);
     }
 
+    [Fact]
+    public async Task AddItemAndRemoveItem_WhenOptedIn_RoundTripsInstalledMxAccessItemHandle()
+    {
+        if (!RunLiveMxAccessTests())
+        {
+            return;
+        }
+
+        using MxAccessStaSession session = new();
+        await session.StartAsync(workerProcessId: 1234);
+
+        MxCommandReply registerReply = await RegisterLiveSessionAsync(session, "live-add-register");
+        int serverHandle = registerReply.Register.ServerHandle;
+        int itemHandle = 0;
+
+        try
+        {
+            MxCommandReply addItemReply = await session.DispatchAsync(new StaCommand(
+                "session-1",
+                "live-add-item",
+                new MxCommand
+                {
+                    Kind = MxCommandKind.AddItem,
+                    AddItem = new AddItemCommand
+                    {
+                        ServerHandle = serverHandle,
+                        ItemDefinition = GetLiveAddItemReference(),
+                    },
+                }));
+
+            Assert.Equal(ProtocolStatusCode.Ok, addItemReply.ProtocolStatus.Code);
+            Assert.True(addItemReply.AddItem.ItemHandle > 0);
+            itemHandle = addItemReply.AddItem.ItemHandle;
+
+            MxCommandReply removeItemReply = await session.DispatchAsync(new StaCommand(
+                "session-1",
+                "live-remove-item",
+                new MxCommand
+                {
+                    Kind = MxCommandKind.RemoveItem,
+                    RemoveItem = new RemoveItemCommand
+                    {
+                        ServerHandle = serverHandle,
+                        ItemHandle = itemHandle,
+                    },
+                }));
+
+            Assert.Equal(ProtocolStatusCode.Ok, removeItemReply.ProtocolStatus.Code);
+            itemHandle = 0;
+        }
+        finally
+        {
+            if (itemHandle > 0)
+            {
+                await session.DispatchAsync(new StaCommand(
+                    "session-1",
+                    "live-remove-item-cleanup",
+                    new MxCommand
+                    {
+                        Kind = MxCommandKind.RemoveItem,
+                        RemoveItem = new RemoveItemCommand
+                        {
+                            ServerHandle = serverHandle,
+                            ItemHandle = itemHandle,
+                        },
+                    }));
+            }
+
+            await UnregisterLiveSessionAsync(session, serverHandle, "live-add-unregister");
+        }
+    }
+
+    [Fact]
+    public async Task AddItem2AndRemoveItem_WhenOptedIn_PreservesContextForInstalledMxAccess()
+    {
+        if (!RunLiveMxAccessTests())
+        {
+            return;
+        }
+
+        using MxAccessStaSession session = new();
+        await session.StartAsync(workerProcessId: 1234);
+
+        MxCommandReply registerReply = await RegisterLiveSessionAsync(session, "live-add2-register");
+        int serverHandle = registerReply.Register.ServerHandle;
+        int itemHandle = 0;
+
+        try
+        {
+            MxCommandReply addItem2Reply = await session.DispatchAsync(new StaCommand(
+                "session-1",
+                "live-add-item2",
+                new MxCommand
+                {
+                    Kind = MxCommandKind.AddItem2,
+                    AddItem2 = new AddItem2Command
+                    {
+                        ServerHandle = serverHandle,
+                        ItemDefinition = DefaultLiveAddItem2Definition,
+                        ItemContext = DefaultLiveAddItem2Context,
+                    },
+                }));
+
+            Assert.Equal(ProtocolStatusCode.Ok, addItem2Reply.ProtocolStatus.Code);
+            Assert.True(addItem2Reply.AddItem2.ItemHandle > 0);
+            itemHandle = addItem2Reply.AddItem2.ItemHandle;
+
+            MxCommandReply removeItemReply = await session.DispatchAsync(new StaCommand(
+                "session-1",
+                "live-remove-item2",
+                new MxCommand
+                {
+                    Kind = MxCommandKind.RemoveItem,
+                    RemoveItem = new RemoveItemCommand
+                    {
+                        ServerHandle = serverHandle,
+                        ItemHandle = itemHandle,
+                    },
+                }));
+
+            Assert.Equal(ProtocolStatusCode.Ok, removeItemReply.ProtocolStatus.Code);
+            itemHandle = 0;
+        }
+        finally
+        {
+            if (itemHandle > 0)
+            {
+                await session.DispatchAsync(new StaCommand(
+                    "session-1",
+                    "live-remove-item2-cleanup",
+                    new MxCommand
+                    {
+                        Kind = MxCommandKind.RemoveItem,
+                        RemoveItem = new RemoveItemCommand
+                        {
+                            ServerHandle = serverHandle,
+                            ItemHandle = itemHandle,
+                        },
+                    }));
+            }
+
+            await UnregisterLiveSessionAsync(session, serverHandle, "live-add2-unregister");
+        }
+    }
+
     private static bool RunLiveMxAccessTests()
     {
         return string.Equals(
@@ -72,4 +222,55 @@ public sealed class MxAccessLiveComCreationTests
             "1",
             StringComparison.Ordinal);
     }
+
+    private static string GetLiveAddItemReference()
+    {
+        string itemReference = Environment.GetEnvironmentVariable("MXGATEWAY_LIVE_MXACCESS_ITEM");
+
+        return string.IsNullOrWhiteSpace(itemReference)
+            ? DefaultLiveAddItemReference
+            : itemReference;
+    }
+
+    private static async Task<MxCommandReply> RegisterLiveSessionAsync(
+        MxAccessStaSession session,
+        string correlationId)
+    {
+        MxCommandReply reply = await session.DispatchAsync(new StaCommand(
+            "session-1",
+            correlationId,
+            new MxCommand
+            {
+                Kind = MxCommandKind.Register,
+                Register = new RegisterCommand
+                {
+                    ClientName = LiveClientName,
+                },
+            }));
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.True(reply.Register.ServerHandle > 0);
+
+        return reply;
+    }
+
+    private static async Task UnregisterLiveSessionAsync(
+        MxAccessStaSession session,
+        int serverHandle,
+        string correlationId)
+    {
+        MxCommandReply unregisterReply = await session.DispatchAsync(new StaCommand(
+            "session-1",
+            correlationId,
+            new MxCommand
+            {
+                Kind = MxCommandKind.Unregister,
+                Unregister = new UnregisterCommand
+                {
+                    ServerHandle = serverHandle,
+                },
+            }));
+
+        Assert.Equal(ProtocolStatusCode.Ok, unregisterReply.ProtocolStatus.Code);
+    }
 }

src/MxGateway.Worker/MxAccess/IMxAccessServer.cs

@@ -5,4 +5,17 @@ public interface IMxAccessServer
     int Register(string clientName);
 
     void Unregister(int serverHandle);
+
+    int AddItem(
+        int serverHandle,
+        string itemDefinition);
+
+    int AddItem2(
+        int serverHandle,
+        string itemDefinition,
+        string itemContext);
+
+    void RemoveItem(
+        int serverHandle,
+        int itemHandle);
 }

src/MxGateway.Worker/MxAccess/MxAccessComServer.cs

@@ -35,6 +35,44 @@ public sealed class MxAccessComServer : IMxAccessServer
         Invoke(nameof(Unregister), serverHandle);
     }
 
+    public int AddItem(
+        int serverHandle,
+        string itemDefinition)
+    {
+        if (mxAccessComObject is ILMXProxyServer mxAccessServer)
+        {
+            return mxAccessServer.AddItem(serverHandle, itemDefinition);
+        }
+
+        return (int)Invoke(nameof(AddItem), serverHandle, itemDefinition);
+    }
+
+    public int AddItem2(
+        int serverHandle,
+        string itemDefinition,
+        string itemContext)
+    {
+        if (mxAccessComObject is ILMXProxyServer3 mxAccessServer)
+        {
+            return mxAccessServer.AddItem2(serverHandle, itemDefinition, itemContext);
+        }
+
+        return (int)Invoke(nameof(AddItem2), serverHandle, itemDefinition, itemContext);
+    }
+
+    public void RemoveItem(
+        int serverHandle,
+        int itemHandle)
+    {
+        if (mxAccessComObject is ILMXProxyServer mxAccessServer)
+        {
+            mxAccessServer.RemoveItem(serverHandle, itemHandle);
+            return;
+        }
+
+        Invoke(nameof(RemoveItem), serverHandle, itemHandle);
+    }
+
     private object Invoke(
         string methodName,
         params object[] arguments)

src/MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs

@@ -34,6 +34,9 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
         {
             MxCommandKind.Register => ExecuteRegister(command),
             MxCommandKind.Unregister => ExecuteUnregister(command),
+            MxCommandKind.AddItem => ExecuteAddItem(command),
+            MxCommandKind.AddItem2 => ExecuteAddItem2(command),
+            MxCommandKind.RemoveItem => ExecuteRemoveItem(command),
             _ => CreateInvalidRequestReply(command, $"Unsupported MXAccess command kind {command.Kind}."),
         };
     }
@@ -67,6 +70,66 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
         return CreateOkReply(command);
     }
 
+    private MxCommandReply ExecuteAddItem(StaCommand command)
+    {
+        if (command.Command.PayloadCase != MxCommand.PayloadOneofCase.AddItem)
+        {
+            return CreateInvalidRequestReply(command, "AddItem command payload is required.");
+        }
+
+        AddItemCommand addItemCommand = command.Command.AddItem;
+        int itemHandle = session.AddItem(
+            addItemCommand.ServerHandle,
+            addItemCommand.ItemDefinition);
+
+        MxCommandReply reply = CreateOkReply(command);
+        reply.ReturnValue = variantConverter.Convert(itemHandle);
+        reply.AddItem = new AddItemReply
+        {
+            ItemHandle = itemHandle,
+        };
+
+        return reply;
+    }
+
+    private MxCommandReply ExecuteAddItem2(StaCommand command)
+    {
+        if (command.Command.PayloadCase != MxCommand.PayloadOneofCase.AddItem2)
+        {
+            return CreateInvalidRequestReply(command, "AddItem2 command payload is required.");
+        }
+
+        AddItem2Command addItem2Command = command.Command.AddItem2;
+        int itemHandle = session.AddItem2(
+            addItem2Command.ServerHandle,
+            addItem2Command.ItemDefinition,
+            addItem2Command.ItemContext);
+
+        MxCommandReply reply = CreateOkReply(command);
+        reply.ReturnValue = variantConverter.Convert(itemHandle);
+        reply.AddItem2 = new AddItem2Reply
+        {
+            ItemHandle = itemHandle,
+        };
+
+        return reply;
+    }
+
+    private MxCommandReply ExecuteRemoveItem(StaCommand command)
+    {
+        if (command.Command.PayloadCase != MxCommand.PayloadOneofCase.RemoveItem)
+        {
+            return CreateInvalidRequestReply(command, "RemoveItem command payload is required.");
+        }
+
+        RemoveItemCommand removeItemCommand = command.Command.RemoveItem;
+        session.RemoveItem(
+            removeItemCommand.ServerHandle,
+            removeItemCommand.ItemHandle);
+
+        return CreateOkReply(command);
+    }
+
     private static MxCommandReply CreateOkReply(StaCommand command)
     {
         return new MxCommandReply

src/MxGateway.Worker/MxAccess/MxAccessHandleRegistry.cs

@@ -6,12 +6,19 @@ namespace MxGateway.Worker.MxAccess;
 public sealed class MxAccessHandleRegistry
 {
     private readonly Dictionary<int, RegisteredServerHandle> serverHandles = new();
+    private readonly Dictionary<long, RegisteredItemHandle> itemHandles = new();
 
     public IReadOnlyList<RegisteredServerHandle> ServerHandles => serverHandles
         .Values
         .OrderBy(handle => handle.ServerHandle)
         .ToArray();
 
+    public IReadOnlyList<RegisteredItemHandle> ItemHandles => itemHandles
+        .Values
+        .OrderBy(handle => handle.ServerHandle)
+        .ThenBy(handle => handle.ItemHandle)
+        .ToArray();
+
     public void RegisterServerHandle(
         int serverHandle,
         string clientName)
@@ -22,10 +29,54 @@ public sealed class MxAccessHandleRegistry
     public void UnregisterServerHandle(int serverHandle)
     {
         serverHandles.Remove(serverHandle);
+
+        foreach (long key in itemHandles
+            .Where(pair => pair.Value.ServerHandle == serverHandle)
+            .Select(pair => pair.Key)
+            .ToArray())
+        {
+            itemHandles.Remove(key);
+        }
     }
 
     public bool ContainsServerHandle(int serverHandle)
     {
         return serverHandles.ContainsKey(serverHandle);
     }
+
+    public void RegisterItemHandle(
+        int serverHandle,
+        int itemHandle,
+        string itemDefinition,
+        string itemContext,
+        bool hasItemContext)
+    {
+        itemHandles[CreateItemKey(serverHandle, itemHandle)] = new RegisteredItemHandle(
+            serverHandle,
+            itemHandle,
+            itemDefinition,
+            itemContext,
+            hasItemContext);
+    }
+
+    public void RemoveItemHandle(
+        int serverHandle,
+        int itemHandle)
+    {
+        itemHandles.Remove(CreateItemKey(serverHandle, itemHandle));
+    }
+
+    public bool ContainsItemHandle(
+        int serverHandle,
+        int itemHandle)
+    {
+        return itemHandles.ContainsKey(CreateItemKey(serverHandle, itemHandle));
+    }
+
+    private static long CreateItemKey(
+        int serverHandle,
+        int itemHandle)
+    {
+        return ((long)serverHandle << 32) | (uint)itemHandle;
+    }
 }

src/MxGateway.Worker/MxAccess/MxAccessSession.cs

@@ -106,6 +106,51 @@ public sealed class MxAccessSession : IDisposable
         handleRegistry.UnregisterServerHandle(serverHandle);
     }
 
+    public int AddItem(
+        int serverHandle,
+        string itemDefinition)
+    {
+        ThrowIfDisposed();
+
+        int itemHandle = mxAccessServer.AddItem(serverHandle, itemDefinition);
+        handleRegistry.RegisterItemHandle(
+            serverHandle,
+            itemHandle,
+            itemDefinition,
+            string.Empty,
+            hasItemContext: false);
+
+        return itemHandle;
+    }
+
+    public int AddItem2(
+        int serverHandle,
+        string itemDefinition,
+        string itemContext)
+    {
+        ThrowIfDisposed();
+
+        int itemHandle = mxAccessServer.AddItem2(serverHandle, itemDefinition, itemContext);
+        handleRegistry.RegisterItemHandle(
+            serverHandle,
+            itemHandle,
+            itemDefinition,
+            itemContext,
+            hasItemContext: true);
+
+        return itemHandle;
+    }
+
+    public void RemoveItem(
+        int serverHandle,
+        int itemHandle)
+    {
+        ThrowIfDisposed();
+
+        mxAccessServer.RemoveItem(serverHandle, itemHandle);
+        handleRegistry.RemoveItemHandle(serverHandle, itemHandle);
+    }
+
     public void Dispose()
     {
         if (disposed)

src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs

@@ -81,6 +81,19 @@ public sealed class MxAccessStaSession : IDisposable
             cancellationToken);
     }
 
+    public Task<IReadOnlyList<RegisteredItemHandle>> GetRegisteredItemHandlesAsync(
+        CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new InvalidOperationException("MXAccess COM session has not been started.");
+        }
+
+        return staRuntime.InvokeAsync(
+            () => session.HandleRegistry.ItemHandles,
+            cancellationToken);
+    }
+
     public void Dispose()
     {
         if (disposed)

src/MxGateway.Worker/MxAccess/RegisteredItemHandle.cs

@@ -0,0 +1,28 @@
+namespace MxGateway.Worker.MxAccess;
+
+public sealed class RegisteredItemHandle
+{
+    public RegisteredItemHandle(
+        int serverHandle,
+        int itemHandle,
+        string itemDefinition,
+        string itemContext,
+        bool hasItemContext)
+    {
+        ServerHandle = serverHandle;
+        ItemHandle = itemHandle;
+        ItemDefinition = itemDefinition;
+        ItemContext = itemContext;
+        HasItemContext = hasItemContext;
+    }
+
+    public int ServerHandle { get; }
+
+    public int ItemHandle { get; }
+
+    public string ItemDefinition { get; }
+
+    public string ItemContext { get; }
+
+    public bool HasItemContext { get; }
+}