Merge remote-tracking branch 'origin/main' into agent-2/issue-33-implement-graceful-shutdown

# Conflicts: # src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs # src/MxGateway.Worker/Ipc/WorkerPipeClient.cs # src/MxGateway.Worker/Ipc/WorkerPipeSession.cs
Implement graceful worker shutdown
2026-04-26 19:41:04 -04:00 · 2026-04-26 19:36:22 -04:00 · 2026-04-26 19:33:44 -04:00 · 2026-04-26 19:31:28 -04:00 · 2026-04-26 19:30:16 -04:00 · 2026-04-26 19:25:15 -04:00
32 changed files with 982 additions and 33 deletions
@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>
@@ -0,0 +1,48 @@
+using MxGateway.Client;
+
+namespace MxGateway.Client.Cli;
+
+public static class MxGatewayClientCli
+{
+    public static int Run(
+        string[] args,
+        TextWriter standardOutput,
+        TextWriter standardError)
+    {
+        ArgumentNullException.ThrowIfNull(args);
+        ArgumentNullException.ThrowIfNull(standardOutput);
+        ArgumentNullException.ThrowIfNull(standardError);
+
+        if (args.Length is 0 || IsHelp(args[0]))
+        {
+            WriteUsage(standardOutput);
+            return 0;
+        }
+
+        if (string.Equals(args[0], "version", StringComparison.OrdinalIgnoreCase))
+        {
+            standardOutput.WriteLine(
+                $"gateway-protocol={MxGatewayClientContractInfo.GatewayProtocolVersion}");
+            standardOutput.WriteLine(
+                $"worker-protocol={MxGatewayClientContractInfo.WorkerProtocolVersion}");
+            return 0;
+        }
+
+        standardError.WriteLine($"Unknown command '{args[0]}'.");
+        WriteUsage(standardError);
+        return 2;
+    }
+
+    private static bool IsHelp(string value)
+    {
+        return string.Equals(value, "-h", StringComparison.OrdinalIgnoreCase)
+            || string.Equals(value, "--help", StringComparison.OrdinalIgnoreCase)
+            || string.Equals(value, "help", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static void WriteUsage(TextWriter writer)
+    {
+        writer.WriteLine("mxgw-dotnet version");
+        writer.WriteLine("mxgw-dotnet --help");
+    }
+}
@@ -0,0 +1,3 @@
+using MxGateway.Client.Cli;
+
+return MxGatewayClientCli.Run(args, Console.Out, Console.Error);
@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
+    <ProjectReference Include="..\MxGateway.Client.Cli\MxGateway.Client.Cli.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,20 @@
+using MxGateway.Client.Cli;
+
+namespace MxGateway.Client.Tests;
+
+public sealed class MxGatewayClientCliTests
+{
+    [Fact]
+    public void Run_Version_PrintsCompiledProtocolVersions()
+    {
+        using var output = new StringWriter();
+        using var error = new StringWriter();
+
+        var exitCode = MxGatewayClientCli.Run(["version"], output, error);
+
+        Assert.Equal(0, exitCode);
+        Assert.Contains("gateway-protocol=1", output.ToString());
+        Assert.Contains("worker-protocol=1", output.ToString());
+        Assert.Equal(string.Empty, error.ToString());
+    }
+}
@@ -0,0 +1,22 @@
+using MxGateway.Contracts;
+
+namespace MxGateway.Client.Tests;
+
+public sealed class MxGatewayClientContractInfoTests
+{
+    [Fact]
+    public void GatewayProtocolVersion_MatchesSharedContract()
+    {
+        Assert.Equal(
+            GatewayContractInfo.GatewayProtocolVersion,
+            MxGatewayClientContractInfo.GatewayProtocolVersion);
+    }
+
+    [Fact]
+    public void WorkerProtocolVersion_MatchesSharedContract()
+    {
+        Assert.Equal(
+            GatewayContractInfo.WorkerProtocolVersion,
+            MxGatewayClientContractInfo.WorkerProtocolVersion);
+    }
+}
@@ -0,0 +1,28 @@
+namespace MxGateway.Client.Tests;
+
+public sealed class MxGatewayClientOptionsTests
+{
+    [Fact]
+    public void Validate_WithAbsoluteEndpointAndApiKey_Succeeds()
+    {
+        var options = new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+        };
+
+        options.Validate();
+    }
+
+    [Fact]
+    public void Validate_WithEmptyApiKey_Throws()
+    {
+        var options = new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "",
+        };
+
+        Assert.Throws<ArgumentException>(options.Validate);
+    }
+}
@@ -0,0 +1,18 @@
+namespace MxGateway.Client.Tests;
+
+public sealed class MxGatewayGeneratedContractTests
+{
+    [Fact]
+    public async Task GeneratedGrpcClient_CanBeConstructedFromClientFactory()
+    {
+        var options = new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+        };
+
+        await using var client = MxGatewayClient.Create(options);
+
+        Assert.NotNull(client.RawClient);
+    }
+}
@@ -0,0 +1,76 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client", "MxGateway.Client\MxGateway.Client.csproj", "{7CF9ED88-1F32-4040-BEB1-D0902E304C70}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Contracts", "..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj", "{9AB807A8-0469-40F7-A000-D240F36B6E5D}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Cli", "MxGateway.Client.Cli\MxGateway.Client.Cli.csproj", "{EB061E77-2475-4322-9257-3F2456DD141C}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Tests", "MxGateway.Client.Tests\MxGateway.Client.Tests.csproj", "{B77B5A8E-0C53-4419-9BCD-227C9753A074}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Debug|x64 = Debug|x64
+		Debug|x86 = Debug|x86
+		Release|Any CPU = Release|Any CPU
+		Release|x64 = Release|x64
+		Release|x86 = Release|x86
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.Build.0 = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.Build.0 = Debug|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.ActiveCfg = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.Build.0 = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.ActiveCfg = Release|Any CPU
+		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.Build.0 = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.Build.0 = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.Build.0 = Debug|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.ActiveCfg = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.Build.0 = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.ActiveCfg = Release|Any CPU
+		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.Build.0 = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.Build.0 = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.Build.0 = Debug|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.Build.0 = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.ActiveCfg = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.Build.0 = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.ActiveCfg = Release|Any CPU
+		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.Build.0 = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.Build.0 = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.Build.0 = Debug|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.ActiveCfg = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.Build.0 = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.ActiveCfg = Release|Any CPU
+		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal
@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Grpc.Net.Client" Version="2.76.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.7" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>
@@ -0,0 +1,41 @@
+using Grpc.Net.Client;
+using MxGateway.Contracts.Proto;
+
+namespace MxGateway.Client;
+
+/// <summary>
+/// Provides the initial .NET client entry point and raw generated gRPC client.
+/// </summary>
+public sealed class MxGatewayClient : IAsyncDisposable
+{
+    private readonly GrpcChannel _channel;
+
+    private MxGatewayClient(GrpcChannel channel)
+    {
+        _channel = channel;
+        RawClient = new MxAccessGateway.MxAccessGatewayClient(channel);
+    }
+
+    public MxAccessGateway.MxAccessGatewayClient RawClient { get; }
+
+    public static MxGatewayClient Create(MxGatewayClientOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        options.Validate();
+
+        var channel = GrpcChannel.ForAddress(
+            options.Endpoint,
+            new GrpcChannelOptions
+            {
+                LoggerFactory = options.LoggerFactory,
+            });
+
+        return new MxGatewayClient(channel);
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        _channel.Dispose();
+        return ValueTask.CompletedTask;
+    }
+}
@@ -0,0 +1,15 @@
+using MxGateway.Contracts;
+
+namespace MxGateway.Client;
+
+/// <summary>
+/// Exposes the protocol versions compiled into this client package.
+/// </summary>
+public static class MxGatewayClientContractInfo
+{
+    public const uint GatewayProtocolVersion =
+        GatewayContractInfo.GatewayProtocolVersion;
+
+    public const uint WorkerProtocolVersion =
+        GatewayContractInfo.WorkerProtocolVersion;
+}
@@ -0,0 +1,58 @@
+using Microsoft.Extensions.Logging;
+
+namespace MxGateway.Client;
+
+/// <summary>
+/// Configures the gRPC channel used by the .NET MXAccess Gateway client.
+/// </summary>
+public sealed class MxGatewayClientOptions
+{
+    public required Uri Endpoint { get; init; }
+
+    public required string ApiKey { get; init; }
+
+    public bool UseTls { get; init; }
+
+    public string? CaCertificatePath { get; init; }
+
+    public string? ServerNameOverride { get; init; }
+
+    public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(10);
+
+    public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
+
+    public ILoggerFactory? LoggerFactory { get; init; }
+
+    public void Validate()
+    {
+        ArgumentNullException.ThrowIfNull(Endpoint);
+
+        if (!Endpoint.IsAbsoluteUri)
+        {
+            throw new ArgumentException(
+                "The gateway endpoint must be an absolute URI.",
+                nameof(Endpoint));
+        }
+
+        if (string.IsNullOrWhiteSpace(ApiKey))
+        {
+            throw new ArgumentException(
+                "The gateway API key must not be empty.",
+                nameof(ApiKey));
+        }
+
+        if (ConnectTimeout <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(ConnectTimeout),
+                "The connect timeout must be greater than zero.");
+        }
+
+        if (DefaultCallTimeout <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(DefaultCallTimeout),
+                "The default call timeout must be greater than zero.");
+        }
+    }
+}
@@ -0,0 +1,24 @@
+# .NET Client Projects
+
+The .NET client workspace contains the MXAccess Gateway client library, test
+CLI, and unit tests.
+
+## Projects
+
+| Project | Purpose |
+|---------|---------|
+| `MxGateway.Client` | .NET 10 library entry point and raw gRPC client access. |
+| `MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
+| `MxGateway.Client.Tests` | Unit tests for the scaffold and generated contract wiring. |
+
+The projects reference `src/MxGateway.Contracts/MxGateway.Contracts.csproj` so
+the client compiles against the same generated protobuf and gRPC types as the
+gateway. `clients/dotnet/generated` remains reserved for generator output if a
+future client build switches to client-local `Grpc.Tools` generation.
+
+## Build And Test
+
+```powershell
+dotnet build clients/dotnet/MxGateway.Client.sln
+dotnet test clients/dotnet/MxGateway.Client.sln --no-build
+```
@@ -16,6 +16,7 @@ Recommended layout:

 ```text
 clients/dotnet/
+  MxGateway.Client.sln
  MxGateway.Client/
    MxGateway.Client.csproj
    GatewayClient.cs
@@ -41,6 +42,12 @@ Target framework:
 <TargetFramework>net10.0</TargetFramework>
 ```

+The scaffold uses a project reference to
+`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated protobuf and
+gRPC types. `clients/dotnet/generated` remains reserved for client-local
+generator output if the .NET client later needs to decouple from the contracts
+project.
+
 Expected packages:

 - `Grpc.Net.Client`
@@ -175,6 +175,12 @@ Behavior:
 `CloseSession` should be idempotent. Closing an already closed session should
 return a successful close result with the final known state.

+`WorkerClient.ShutdownAsync` sends `WorkerShutdown`, waits for the worker read,
+write, and heartbeat loops to stop, and waits for the launched worker process to
+exit within the same shutdown timeout. If the pipe loops or process exit exceed
+the timeout, the close operation fails with `ShutdownTimeout`; `GatewaySession`
+then kills the worker process tree before surfacing the close failure.
+
 ### Invoke

 `Invoke` forwards one MXAccess command to the worker that owns the session.
@@ -515,6 +521,11 @@ It handles:
 The write loop should fail the session if a pipe write fails outside normal
 shutdown.

+During shutdown the worker client treats `WorkerShutdownAck` as the protocol
+close signal, but the process handle remains authoritative for process lifetime.
+The client waits for both the protocol close and process exit before reporting a
+clean shutdown to `GatewaySession`.
+
 ## Command Correlation

 Each command gets:
@@ -321,6 +321,13 @@ If COM creation fails, the worker should send a structured fault with:
 when the exception exposes one, and does not send `WorkerReady` after a failed
 COM creation attempt.

+After `WorkerReady`, `WorkerPipeSession` continues reading gateway frames for
+the lifetime of the process. `WorkerCommand` frames are dispatched to
+`MxAccessStaSession`, replies are written as `WorkerCommandReply`, and queued
+worker events are drained after command replies. `WorkerShutdown` starts the
+graceful shutdown path and returns `WorkerShutdownAck` only after the STA
+cleanup path completes.
+
 ## Event Sink

 The worker must subscribe to every public MXAccess event family:
@@ -675,6 +682,29 @@ Graceful shutdown sequence:
 If shutdown wedges, the gateway kills the process. The worker should be written
 so process kill does not corrupt other sessions.

+`MxAccessStaSession.ShutdownGracefullyAsync` implements the current cleanup
+path. It first calls `StaCommandDispatcher.RequestShutdown()` so new commands
+are rejected and queued commands that have not started receive
+`ProtocolStatusCode.WorkerUnavailable`. The command already executing on the
+STA is allowed to finish until the shutdown grace period expires.
+
+After command dispatch is closed, cleanup runs on the STA in MXAccess handle
+order:
+
+1. one `UnAdvise` call per advised server/item pair,
+2. `RemoveItem` for active item handles,
+3. `Unregister` for active server handles,
+4. event sink detach,
+5. COM release.
+
+Each cleanup call is best effort. A failed cleanup operation is recorded as an
+`MxAccessShutdownFailure`, logged by `WorkerPipeSession`, and does not prevent
+later cleanup calls from running. A shutdown with cleanup failures still returns
+`WorkerShutdownAck` with `ProtocolStatusCode.Ok` because the worker reached the
+controlled release path. If the grace period expires before cleanup can run or
+finish, the worker reports `WorkerFaultCategory.ShutdownTimeout` when possible
+and relies on the gateway to kill the process.
+
 ## Fault Handling

 Worker fault categories:
@@ -227,6 +227,7 @@ public sealed class WorkerClient : IWorkerClient
        try
        {
            await WaitForBackgroundTasksAsync(timeoutCts.Token).ConfigureAwait(false);
+            await WaitForProcessExitAsync(timeoutCts.Token).ConfigureAwait(false);
            MarkClosed("shutdown");
        }
        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
@@ -717,6 +718,17 @@ public sealed class WorkerClient : IWorkerClient
        await Task.WhenAll(tasks).WaitAsync(cancellationToken).ConfigureAwait(false);
    }

+    private async Task WaitForProcessExitAsync(CancellationToken cancellationToken)
+    {
+        WorkerProcessHandle? processHandle = _connection.ProcessHandle;
+        if (processHandle is null || processHandle.Process.HasExited)
+        {
+            return;
+        }
+
+        await processHandle.Process.WaitForExitAsync(cancellationToken).ConfigureAwait(false);
+    }
+
    private void ThrowIfDisposed()
    {
        ObjectDisposedException.ThrowIf(_disposed, this);
@@ -86,6 +86,26 @@ public sealed class SessionManagerTests
        Assert.Equal(0, metrics.GetSnapshot().OpenSessions);
    }

+    [Fact]
+    public async Task CloseSessionAsync_WhenWorkerShutdownFails_KillsWorker()
+    {
+        FakeWorkerClient workerClient = new()
+        {
+            ShutdownException = new WorkerClientException(
+                WorkerClientErrorCode.ShutdownTimeout,
+                "Worker shutdown timed out."),
+        };
+        SessionManager manager = CreateManager(new FakeSessionWorkerClientFactory(workerClient));
+        GatewaySession session = await manager.OpenSessionAsync(CreateOpenRequest(), "client-1", CancellationToken.None);
+
+        SessionManagerException exception = await Assert.ThrowsAsync<SessionManagerException>(
+            async () => await manager.CloseSessionAsync(session.SessionId, CancellationToken.None));
+
+        Assert.Equal(SessionManagerErrorCode.CloseFailed, exception.ErrorCode);
+        Assert.Equal(1, workerClient.ShutdownCount);
+        Assert.Equal(1, workerClient.KillCount);
+    }
+
    [Fact]
    public async Task OpenSessionAsync_WhenWorkerCreationFails_RemovesSessionFromRegistry()
    {
@@ -266,6 +286,8 @@ public sealed class SessionManagerTests

        public int KillCount { get; private set; }

+        public Exception? ShutdownException { get; init; }
+
        public Task StartAsync(CancellationToken cancellationToken)
        {
            return Task.CompletedTask;
@@ -302,6 +324,11 @@ public sealed class SessionManagerTests
            CancellationToken cancellationToken)
        {
            ShutdownCount++;
+            if (ShutdownException is not null)
+            {
+                throw ShutdownException;
+            }
+
            State = WorkerClientState.Closed;
            return Task.CompletedTask;
        }
@@ -142,6 +142,13 @@ public sealed class WorkerPipeClientTests
        {
        }

+        public Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
+            TimeSpan timeout,
+            CancellationToken cancellationToken = default)
+        {
+            return Task.FromResult(new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>()));
+        }
+
        public void Dispose()
        {
        }
@@ -555,6 +555,14 @@ public sealed class WorkerPipeSessionTests
            releaseDispatch.Set();
        }

+        public Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
+            TimeSpan timeout,
+            CancellationToken cancellationToken = default)
+        {
+            releaseDispatch.Set();
+            return Task.FromResult(new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>()));
+        }
+
        public void ReleaseDispatch()
        {
            releaseDispatch.Set();
@@ -1,4 +1,6 @@
 using System;
+using System.Collections.Generic;
+using System.Linq;
 using System.Runtime.InteropServices;
 using System.Threading.Tasks;
 using MxGateway.Contracts.Proto;
@@ -414,6 +416,57 @@ public sealed class MxAccessCommandExecutorTests
        Assert.Equal(MxAccessAdviceKind.Plain, adviceHandle.AdviceKind);
    }

+    [Fact]
+    public async Task ShutdownGracefullyAsync_CleansHandlesInAdviceItemServerOrder()
+    {
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 58,
+            addItemHandle: 510);
+        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-shutdown", "client-a"));
+        await session.DispatchAsync(CreateAddItemCommand("add-before-shutdown", 58, "Galaxy.Tag.Value"));
+        await session.DispatchAsync(CreateAdviseCommand("advise-before-shutdown", 58, 510));
+        await session.DispatchAsync(CreateAdviseSupervisoryCommand("supervisory-before-shutdown", 58, 510));
+
+        MxAccessShutdownResult result = await session.ShutdownGracefullyAsync(TimeSpan.FromSeconds(2));
+
+        Assert.True(result.Succeeded);
+        Assert.Equal(
+            new[] { "UnAdvise:58:510", "RemoveItem:58:510", "Unregister:58" },
+            fakeComObject.OperationNames.Where(name => name.StartsWith("Un", StringComparison.Ordinal)
+                || name.StartsWith("Remove", StringComparison.Ordinal)));
+    }
+
+    [Fact]
+    public async Task ShutdownGracefullyAsync_RecordsCleanupFailuresAndContinues()
+    {
+        const int hresult = unchecked((int)0x80070057);
+        COMException cleanupException = new("Invalid handle.", hresult);
+        FakeMxAccessComObject fakeComObject = new(
+            registerHandle: 59,
+            addItemHandle: 511,
+            unregisterException: cleanupException,
+            removeItemException: cleanupException,
+            unAdviseException: cleanupException);
+        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-shutdown-failure", "client-a"));
+        await session.DispatchAsync(CreateAddItemCommand("add-before-shutdown-failure", 59, "Galaxy.Tag.Value"));
+        await session.DispatchAsync(CreateAdviseCommand("advise-before-shutdown-failure", 59, 511));
+
+        MxAccessShutdownResult result = await session.ShutdownGracefullyAsync(TimeSpan.FromSeconds(2));
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(new[] { "UnAdvise", "RemoveItem", "Unregister" }, result.Failures.Select(failure => failure.Operation));
+        Assert.All(result.Failures, failure => Assert.Equal(hresult, failure.HResult));
+        Assert.Contains("Unregister:59", fakeComObject.OperationNames);
+    }
+
    [Fact]
    public async Task DispatchAsync_RegisterWithoutPayload_ReturnsInvalidRequest()
    {
@@ -644,6 +697,7 @@ public sealed class MxAccessCommandExecutorTests
        private readonly Exception? adviseException;
        private readonly Exception? unAdviseException;
        private readonly Exception? adviseSupervisoryException;
+        private readonly List<string> operationNames = new();

        public FakeMxAccessComObject(
            int registerHandle,
@@ -715,8 +769,11 @@ public sealed class MxAccessCommandExecutorTests

        public int? AdviseSupervisoryThreadId { get; private set; }

+        public IReadOnlyList<string> OperationNames => operationNames.ToArray();
+
        public int Register(string clientName)
        {
+            operationNames.Add($"Register:{clientName}");
            RegisteredClientName = clientName;
            RegisterThreadId = Environment.CurrentManagedThreadId;

@@ -725,6 +782,7 @@ public sealed class MxAccessCommandExecutorTests

        public void Unregister(int serverHandle)
        {
+            operationNames.Add($"Unregister:{serverHandle}");
            UnregisteredServerHandle = serverHandle;
            UnregisterThreadId = Environment.CurrentManagedThreadId;

@@ -738,6 +796,7 @@ public sealed class MxAccessCommandExecutorTests
            int serverHandle,
            string itemDefinition)
        {
+            operationNames.Add($"AddItem:{serverHandle}:{itemDefinition}");
            AddItemServerHandle = serverHandle;
            AddItemDefinition = itemDefinition;
            AddItemThreadId = Environment.CurrentManagedThreadId;
@@ -755,6 +814,7 @@ public sealed class MxAccessCommandExecutorTests
            string itemDefinition,
            string itemContext)
        {
+            operationNames.Add($"AddItem2:{serverHandle}:{itemDefinition}:{itemContext}");
            AddItem2ServerHandle = serverHandle;
            AddItem2Definition = itemDefinition;
            AddItem2Context = itemContext;
@@ -772,6 +832,7 @@ public sealed class MxAccessCommandExecutorTests
            int serverHandle,
            int itemHandle)
        {
+            operationNames.Add($"RemoveItem:{serverHandle}:{itemHandle}");
            RemoveItemServerHandle = serverHandle;
            RemovedItemHandle = itemHandle;
            RemoveItemThreadId = Environment.CurrentManagedThreadId;
@@ -786,6 +847,7 @@ public sealed class MxAccessCommandExecutorTests
            int serverHandle,
            int itemHandle)
        {
+            operationNames.Add($"Advise:{serverHandle}:{itemHandle}");
            AdviseServerHandle = serverHandle;
            AdvisedItemHandle = itemHandle;
            AdviseThreadId = Environment.CurrentManagedThreadId;
@@ -800,6 +862,7 @@ public sealed class MxAccessCommandExecutorTests
            int serverHandle,
            int itemHandle)
        {
+            operationNames.Add($"UnAdvise:{serverHandle}:{itemHandle}");
            UnAdviseServerHandle = serverHandle;
            UnAdvisedItemHandle = itemHandle;
            UnAdviseThreadId = Environment.CurrentManagedThreadId;
@@ -814,6 +877,7 @@ public sealed class MxAccessCommandExecutorTests
            int serverHandle,
            int itemHandle)
        {
+            operationNames.Add($"AdviseSupervisory:{serverHandle}:{itemHandle}");
            AdviseSupervisoryServerHandle = serverHandle;
            AdviseSupervisoryItemHandle = itemHandle;
            AdviseSupervisoryThreadId = Environment.CurrentManagedThreadId;
@@ -110,6 +110,27 @@ public sealed class StaCommandDispatcherTests
        Assert.Equal("correlation-1", reply.CorrelationId);
    }

+    [Fact]
+    public async Task RequestShutdown_RejectsQueuedCommandButLetsCurrentCommandFinish()
+    {
+        using StaRuntime runtime = CreateRuntime();
+        runtime.Start();
+        BlockingCommandExecutor executor = new();
+        StaCommandDispatcher dispatcher = new(runtime, executor);
+        Task<MxCommandReply> current = dispatcher.DispatchAsync(CreateCommand("current", MxCommandKind.Register));
+        Assert.True(executor.Started.Wait(TimeSpan.FromSeconds(2)));
+        Task<MxCommandReply> pending = dispatcher.DispatchAsync(CreateCommand("pending", MxCommandKind.AddItem));
+
+        dispatcher.RequestShutdown();
+        MxCommandReply pendingReply = await pending;
+        executor.Release();
+        MxCommandReply currentReply = await current;
+
+        Assert.Equal(ProtocolStatusCode.WorkerUnavailable, pendingReply.ProtocolStatus.Code);
+        Assert.Equal(ProtocolStatusCode.Ok, currentReply.ProtocolStatus.Code);
+        Assert.Equal(new[] { "current" }, executor.CorrelationIds);
+    }
+
    [Fact]
    public async Task PopulateHeartbeat_ReportsCurrentCorrelationAndPendingCount()
    {
@@ -12,23 +12,48 @@ public sealed class WorkerPipeClient : IWorkerPipeClient
    public const int DefaultConnectTimeoutMilliseconds = 30000;

    private readonly int _connectTimeoutMilliseconds;
-    private readonly Func<Stream, WorkerFrameProtocolOptions, WorkerPipeSession> _sessionFactory;
+    private readonly Func<Stream, WorkerFrameProtocolOptions, IWorkerLogger?, WorkerPipeSession> _sessionFactory;
+    private readonly IWorkerLogger? _logger;

    public WorkerPipeClient()
-        : this(DefaultConnectTimeoutMilliseconds)
+        : this(null, DefaultConnectTimeoutMilliseconds)
+    {
+    }
+
+    public WorkerPipeClient(IWorkerLogger? logger)
+        : this(logger, DefaultConnectTimeoutMilliseconds)
    {
    }

    public WorkerPipeClient(int connectTimeoutMilliseconds)
-        : this(
-            connectTimeoutMilliseconds,
-            (stream, frameOptions) => new WorkerPipeSession(stream, frameOptions))
+        : this(null, connectTimeoutMilliseconds)
    {
    }

    public WorkerPipeClient(
        int connectTimeoutMilliseconds,
        Func<Stream, WorkerFrameProtocolOptions, WorkerPipeSession> sessionFactory)
+        : this(
+            null,
+            connectTimeoutMilliseconds,
+            (stream, frameOptions, _) => sessionFactory(stream, frameOptions))
+    {
+    }
+
+    public WorkerPipeClient(
+        IWorkerLogger? logger,
+        int connectTimeoutMilliseconds)
+        : this(
+            logger,
+            connectTimeoutMilliseconds,
+            (stream, frameOptions, workerLogger) => new WorkerPipeSession(stream, frameOptions, workerLogger))
+    {
+    }
+
+    public WorkerPipeClient(
+        IWorkerLogger? logger,
+        int connectTimeoutMilliseconds,
+        Func<Stream, WorkerFrameProtocolOptions, IWorkerLogger?, WorkerPipeSession> sessionFactory)
    {
        if (connectTimeoutMilliseconds <= 0)
        {
@@ -37,6 +62,7 @@ public sealed class WorkerPipeClient : IWorkerPipeClient
                "Worker pipe connect timeout must be greater than zero.");
        }

+        _logger = logger;
        _sessionFactory = sessionFactory ?? throw new ArgumentNullException(nameof(sessionFactory));
        _connectTimeoutMilliseconds = connectTimeoutMilliseconds;
    }
@@ -60,7 +86,7 @@ public sealed class WorkerPipeClient : IWorkerPipeClient

        await ConnectAsync(pipe, cancellationToken).ConfigureAwait(false);

-        WorkerPipeSession session = _sessionFactory(pipe, frameOptions);
+        WorkerPipeSession session = _sessionFactory(pipe, frameOptions, _logger);
        await session.RunAsync(cancellationToken).ConfigureAwait(false);
    }

@@ -1,10 +1,12 @@
 using System;
+using System.Collections.Generic;
 using System.Diagnostics;
 using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
 using Google.Protobuf.WellKnownTypes;
 using MxGateway.Contracts.Proto;
+using MxGateway.Worker.Bootstrap;
 using MxGateway.Worker.MxAccess;
 using MxGateway.Worker.Sta;

@@ -16,21 +18,27 @@ public sealed class WorkerPipeSession
    private readonly Func<int> _processIdProvider;
    private readonly Func<IWorkerRuntimeSession> _runtimeSessionFactory;
    private readonly WorkerPipeSessionOptions _sessionOptions;
+    private readonly IWorkerLogger? _logger;
    private readonly WorkerFrameReader _reader;
    private readonly WorkerFrameWriter _writer;
    private IWorkerRuntimeSession? _runtimeSession;
    private long _nextSequence;
    private WorkerState _state = WorkerState.Starting;
    private bool _watchdogFaultSent;
+    private bool _shutdownTimedOut;

    public WorkerPipeSession(
        Stream stream,
-        WorkerFrameProtocolOptions options)
+        WorkerFrameProtocolOptions options,
+        IWorkerLogger? logger = null)
        : this(
            new WorkerFrameReader(stream, options),
            new WorkerFrameWriter(stream, options),
            options,
-            () => Process.GetCurrentProcess().Id)
+            () => Process.GetCurrentProcess().Id,
+            new WorkerPipeSessionOptions(),
+            () => new MxAccessStaSession(),
+            logger)
    {
    }

@@ -45,7 +53,8 @@ public sealed class WorkerPipeSession
            options,
            processIdProvider,
            new WorkerPipeSessionOptions(),
-            () => new MxAccessStaSession())
+            () => new MxAccessStaSession(),
+            logger: null)
    {
    }

@@ -55,7 +64,8 @@ public sealed class WorkerPipeSession
        WorkerFrameProtocolOptions options,
        Func<int> processIdProvider,
        WorkerPipeSessionOptions sessionOptions,
-        Func<IWorkerRuntimeSession> runtimeSessionFactory)
+        Func<IWorkerRuntimeSession> runtimeSessionFactory,
+        IWorkerLogger? logger = null)
    {
        _reader = reader ?? throw new ArgumentNullException(nameof(reader));
        _writer = writer ?? throw new ArgumentNullException(nameof(writer));
@@ -63,6 +73,7 @@ public sealed class WorkerPipeSession
        _processIdProvider = processIdProvider ?? throw new ArgumentNullException(nameof(processIdProvider));
        _sessionOptions = sessionOptions ?? throw new ArgumentNullException(nameof(sessionOptions));
        _runtimeSessionFactory = runtimeSessionFactory ?? throw new ArgumentNullException(nameof(runtimeSessionFactory));
+        _logger = logger;
        _sessionOptions.Validate();
    }

@@ -78,7 +89,11 @@ public sealed class WorkerPipeSession
        }
        finally
        {
-            _runtimeSession?.Dispose();
+            if (!_shutdownTimedOut)
+            {
+                _runtimeSession?.Dispose();
+            }
+
            _runtimeSession = null;
            _state = WorkerState.Stopped;
        }
@@ -290,23 +305,38 @@ public sealed class WorkerPipeSession
        CancellationToken cancellationToken)
    {
        _state = WorkerState.ShuttingDown;
-        _runtimeSession?.RequestShutdown();
+        IWorkerRuntimeSession? runtimeSession = _runtimeSession;
+        if (runtimeSession is null)
+        {
+            await WriteShutdownAckAsync(
+                CreateShutdownAck(new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>()), shutdown),
+                cancellationToken).ConfigureAwait(false);
+            return;
+        }

-        await _writer
-            .WriteAsync(
-                CreateEnvelope(
-                    new WorkerShutdownAck
-                    {
-                        Status = new ProtocolStatus
-                        {
-                            Code = ProtocolStatusCode.Ok,
-                            Message = string.IsNullOrWhiteSpace(shutdown.Reason)
-                                ? "Worker shutdown accepted."
-                                : $"Worker shutdown accepted: {shutdown.Reason}",
-                        },
-                    }),
-                cancellationToken)
-            .ConfigureAwait(false);
+        TimeSpan gracePeriod = ResolveGracePeriod(shutdown);
+        try
+        {
+            MxAccessShutdownResult result = await runtimeSession
+                .ShutdownGracefullyAsync(gracePeriod, cancellationToken)
+                .ConfigureAwait(false);
+            LogShutdownFailures(result.Failures);
+            await WriteShutdownAckAsync(CreateShutdownAck(result, shutdown), cancellationToken).ConfigureAwait(false);
+        }
+        catch (TimeoutException exception)
+        {
+            _shutdownTimedOut = true;
+            _state = WorkerState.Faulted;
+            await TryWriteFaultAsync(CreateShutdownTimeoutFault(exception), cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    private Task WriteShutdownAckAsync(
+        WorkerShutdownAck shutdownAck,
+        CancellationToken cancellationToken)
+    {
+        return _writer.WriteAsync(CreateEnvelope(shutdownAck), cancellationToken);
    }

    private async Task RunHeartbeatLoopAsync(CancellationToken cancellationToken)
@@ -545,6 +575,57 @@ public sealed class WorkerPipeSession
        };
    }

+    private static TimeSpan ResolveGracePeriod(WorkerShutdown shutdown)
+    {
+        if (shutdown.GracePeriod is null)
+        {
+            return TimeSpan.FromSeconds(10);
+        }
+
+        TimeSpan gracePeriod = shutdown.GracePeriod.ToTimeSpan();
+        return gracePeriod <= TimeSpan.Zero
+            ? TimeSpan.FromSeconds(10)
+            : gracePeriod;
+    }
+
+    private static WorkerShutdownAck CreateShutdownAck(
+        MxAccessShutdownResult result,
+        WorkerShutdown shutdown)
+    {
+        string message = result.Succeeded
+            ? "Graceful shutdown completed."
+            : $"Graceful shutdown completed with {result.Failures.Count} cleanup failure(s).";
+        if (!string.IsNullOrWhiteSpace(shutdown.Reason))
+        {
+            message = $"{message} Reason: {shutdown.Reason}";
+        }
+
+        return new WorkerShutdownAck
+        {
+            Status = new ProtocolStatus
+            {
+                Code = ProtocolStatusCode.Ok,
+                Message = message,
+            },
+        };
+    }
+
+    private void LogShutdownFailures(IReadOnlyList<MxAccessShutdownFailure> failures)
+    {
+        foreach (MxAccessShutdownFailure failure in failures)
+        {
+            _logger?.Error("WorkerGracefulShutdownCleanupFailed", new Dictionary<string, object?>
+            {
+                ["session_id"] = _options.SessionId,
+                ["operation"] = failure.Operation,
+                ["server_handle"] = failure.ServerHandle,
+                ["item_handle"] = failure.ItemHandle,
+                ["exception_type"] = failure.ExceptionType,
+                ["hresult"] = failure.HResult,
+            });
+        }
+    }
+
    private static WorkerFault CreateFault(WorkerFrameProtocolException exception)
    {
        return new WorkerFault
@@ -619,6 +700,14 @@ public sealed class WorkerPipeSession
        };
    }

+    private static WorkerFault CreateShutdownTimeoutFault(TimeoutException exception)
+    {
+        return CreateFault(
+            WorkerFaultCategory.ShutdownTimeout,
+            commandMethod: string.Empty,
+            exception);
+    }
+
    private static WorkerFaultCategory MapFaultCategory(WorkerFrameProtocolErrorCode errorCode)
    {
        return errorCode switch
@@ -18,4 +18,8 @@ public interface IWorkerRuntimeSession : IDisposable
    WorkerRuntimeHeartbeatSnapshot CaptureHeartbeat();

    void RequestShutdown();
+
+    Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default);
 }
@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Runtime.InteropServices;
 using Google.Protobuf.WellKnownTypes;
 using MxGateway.Contracts.Proto;
@@ -188,6 +189,23 @@ public sealed class MxAccessSession : IDisposable
            MxAccessAdviceKind.Supervisory);
    }

+    public MxAccessShutdownResult ShutdownGracefully()
+    {
+        if (disposed)
+        {
+            return new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>());
+        }
+
+        List<MxAccessShutdownFailure> failures = new();
+
+        CleanupAdviceHandles(failures);
+        CleanupItemHandles(failures);
+        CleanupServerHandles(failures);
+        DisposeCore(failures);
+
+        return new MxAccessShutdownResult(failures);
+    }
+
    public void Dispose()
    {
        if (disposed)
@@ -195,11 +213,112 @@ public sealed class MxAccessSession : IDisposable
            return;
        }

-        eventSink.Detach();
+        DisposeCore(failures: null);
+    }

-        if (Marshal.IsComObject(mxAccessComObject))
+    private void CleanupAdviceHandles(ICollection<MxAccessShutdownFailure> failures)
+    {
+        HashSet<long> cleanedPairs = new();
+        foreach (RegisteredAdviceHandle adviceHandle in handleRegistry.AdviceHandles)
        {
-            Marshal.FinalReleaseComObject(mxAccessComObject);
+            long key = CreateItemKey(adviceHandle.ServerHandle, adviceHandle.ItemHandle);
+            if (!cleanedPairs.Add(key))
+            {
+                continue;
+            }
+
+            try
+            {
+                mxAccessServer.UnAdvise(adviceHandle.ServerHandle, adviceHandle.ItemHandle);
+                handleRegistry.RemoveAdviceHandles(adviceHandle.ServerHandle, adviceHandle.ItemHandle);
+            }
+            catch (Exception exception)
+            {
+                failures.Add(new MxAccessShutdownFailure(
+                    nameof(UnAdvise),
+                    adviceHandle.ServerHandle,
+                    adviceHandle.ItemHandle,
+                    exception));
+            }
+        }
+    }
+
+    private void CleanupItemHandles(ICollection<MxAccessShutdownFailure> failures)
+    {
+        foreach (RegisteredItemHandle itemHandle in handleRegistry.ItemHandles)
+        {
+            try
+            {
+                mxAccessServer.RemoveItem(itemHandle.ServerHandle, itemHandle.ItemHandle);
+                handleRegistry.RemoveItemHandle(itemHandle.ServerHandle, itemHandle.ItemHandle);
+            }
+            catch (Exception exception)
+            {
+                failures.Add(new MxAccessShutdownFailure(
+                    nameof(RemoveItem),
+                    itemHandle.ServerHandle,
+                    itemHandle.ItemHandle,
+                    exception));
+            }
+        }
+    }
+
+    private void CleanupServerHandles(ICollection<MxAccessShutdownFailure> failures)
+    {
+        foreach (RegisteredServerHandle serverHandle in handleRegistry.ServerHandles)
+        {
+            try
+            {
+                mxAccessServer.Unregister(serverHandle.ServerHandle);
+                handleRegistry.UnregisterServerHandle(serverHandle.ServerHandle);
+            }
+            catch (Exception exception)
+            {
+                failures.Add(new MxAccessShutdownFailure(
+                    nameof(Unregister),
+                    serverHandle.ServerHandle,
+                    itemHandle: null,
+                    exception));
+            }
+        }
+    }
+
+    private static long CreateItemKey(
+        int serverHandle,
+        int itemHandle)
+    {
+        return ((long)serverHandle << 32) | (uint)itemHandle;
+    }
+
+    private void DisposeCore(ICollection<MxAccessShutdownFailure>? failures)
+    {
+        try
+        {
+            eventSink.Detach();
+        }
+        catch (Exception exception) when (failures is not null)
+        {
+            failures.Add(new MxAccessShutdownFailure(
+                "DetachEvents",
+                serverHandle: null,
+                itemHandle: null,
+                exception));
+        }
+
+        try
+        {
+            if (Marshal.IsComObject(mxAccessComObject))
+            {
+                Marshal.FinalReleaseComObject(mxAccessComObject);
+            }
+        }
+        catch (Exception exception) when (failures is not null)
+        {
+            failures.Add(new MxAccessShutdownFailure(
+                "ReleaseComObject",
+                serverHandle: null,
+                itemHandle: null,
+                exception));
        }

        disposed = true;
@@ -0,0 +1,34 @@
+using System;
+
+namespace MxGateway.Worker.MxAccess;
+
+public sealed class MxAccessShutdownFailure
+{
+    public MxAccessShutdownFailure(
+        string operation,
+        int? serverHandle,
+        int? itemHandle,
+        Exception exception)
+    {
+        if (string.IsNullOrWhiteSpace(operation))
+        {
+            throw new ArgumentException("Shutdown failure operation is required.", nameof(operation));
+        }
+
+        Operation = operation;
+        ServerHandle = serverHandle;
+        ItemHandle = itemHandle;
+        ExceptionType = exception?.GetType().FullName ?? string.Empty;
+        HResult = exception?.HResult;
+    }
+
+    public string Operation { get; }
+
+    public int? ServerHandle { get; }
+
+    public int? ItemHandle { get; }
+
+    public string ExceptionType { get; }
+
+    public int? HResult { get; }
+}
@@ -0,0 +1,16 @@
+using System;
+using System.Collections.Generic;
+
+namespace MxGateway.Worker.MxAccess;
+
+public sealed class MxAccessShutdownResult
+{
+    public MxAccessShutdownResult(IReadOnlyList<MxAccessShutdownFailure> failures)
+    {
+        Failures = failures ?? throw new ArgumentNullException(nameof(failures));
+    }
+
+    public IReadOnlyList<MxAccessShutdownFailure> Failures { get; }
+
+    public bool Succeeded => Failures.Count == 0;
+}
@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Threading;
 using System.Threading.Tasks;
 using MxGateway.Contracts.Proto;
@@ -165,6 +166,61 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
            cancellationToken);
    }

+    public async Task<MxAccessShutdownResult> ShutdownGracefullyAsync(
+        TimeSpan timeout,
+        CancellationToken cancellationToken = default)
+    {
+        if (timeout <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(timeout),
+                "MXAccess graceful shutdown timeout must be greater than zero.");
+        }
+
+        if (disposed)
+        {
+            return new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>());
+        }
+
+        commandDispatcher?.RequestShutdown();
+
+        Stopwatch stopwatch = Stopwatch.StartNew();
+        MxAccessShutdownResult result;
+        if (session is null)
+        {
+            result = new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>());
+        }
+        else
+        {
+            using CancellationTokenSource shutdownCancellation =
+                CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            shutdownCancellation.CancelAfter(timeout);
+
+            Task<MxAccessShutdownResult> cleanupTask = staRuntime.InvokeAsync(
+                () => session.ShutdownGracefully(),
+                shutdownCancellation.Token);
+            Task delayTask = Task.Delay(timeout, cancellationToken);
+            Task completedTask = await Task.WhenAny(cleanupTask, delayTask).ConfigureAwait(false);
+            if (completedTask != cleanupTask)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                throw new TimeoutException($"MXAccess graceful shutdown exceeded {timeout}.");
+            }
+
+            result = await cleanupTask.ConfigureAwait(false);
+        }
+
+        TimeSpan remaining = timeout - stopwatch.Elapsed;
+        if (remaining <= TimeSpan.Zero || !staRuntime.Shutdown(remaining))
+        {
+            throw new TimeoutException($"MXAccess graceful shutdown exceeded {timeout}.");
+        }
+
+        staRuntime.Dispose();
+        disposed = true;
+        return result;
+    }
+
    public void Dispose()
    {
        if (disposed)
@@ -91,6 +91,14 @@ public sealed class StaCommandDispatcher
        lock (gate)
        {
            shutdownRequested = true;
+            while (commandQueue.Count > 0)
+            {
+                QueuedStaCommand queuedCommand = commandQueue.Dequeue();
+                queuedCommand.Complete(CreateRejectedReply(
+                    queuedCommand.Command,
+                    ProtocolStatusCode.WorkerUnavailable,
+                    "The STA command dispatcher is shutting down."));
+            }
        }
    }

@@ -13,8 +13,7 @@ public static class WorkerApplication
        return Run(
            args,
            new EnvironmentVariableWorkerEnvironment(),
-            new WorkerConsoleLogger(Console.Error),
-            new WorkerPipeClient());
+            new WorkerConsoleLogger(Console.Error));
    }

    public static int Run(
@@ -26,7 +25,7 @@ public static class WorkerApplication
            args,
            environment,
            logger,
-            new WorkerPipeClient());
+            new WorkerPipeClient(logger));
    }

    public static int Run(
Author	SHA1	Message	Date
Joseph Doherty	f7929cc12f	Merge remote-tracking branch 'origin/main' into agent-2/issue-33-implement-graceful-shutdown # Conflicts: # src/MxGateway.Worker.Tests/Ipc/WorkerPipeSessionTests.cs # src/MxGateway.Worker/Ipc/WorkerPipeClient.cs # src/MxGateway.Worker/Ipc/WorkerPipeSession.cs	2026-04-26 19:41:04 -04:00
Joseph Doherty	d890eff862	Implement graceful worker shutdown	2026-04-26 19:36:22 -04:00
dohertj2	9dcd4baff2	Merge pull request #86 from agent-3/issue-41-scaffold-go-module Issue #41: scaffold Go module	2026-04-26 19:33:44 -04:00
dohertj2	7a0743496f	Merge pull request #87 from agent-1/issue-38-scaffold-dotnet-client-projects Issue #38: scaffold .NET client projects	2026-04-26 19:31:28 -04:00
Joseph Doherty	bcfbd1cfc8	Merge remote-tracking branch 'origin/main' into agent-3/issue-41-scaffold-go-module	2026-04-26 19:30:16 -04:00
Joseph Doherty	bd4be85f26	Merge remote-tracking branch 'origin/main' into agent-1/issue-38-scaffold-dotnet-client-projects	2026-04-26 19:25:15 -04:00
Joseph Doherty	7331c6157a	Scaffold .NET client projects	2026-04-26 19:25:07 -04:00