diff --git a/docs/plans/2026-08-09-write-completion-correlation.md b/docs/plans/2026-08-09-write-completion-correlation.md
new file mode 100644
index 0000000..7626006
--- /dev/null
+++ b/docs/plans/2026-08-09-write-completion-correlation.md
@@ -0,0 +1,575 @@
+# WriteSecured Completion Correlation Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.
+
+**Goal:** Populate `MxCommandReply.statuses[0]` on unary `WriteSecured`/`WriteSecured2` replies with the correlated MXAccess `OnWriteComplete` outcome, bounded by a configurable wait (default 1.5 s), falling back to today's empty-statuses shape on timeout.
+
+**Architecture:** Worker-side only (plus one gateway config option). A versioned per-`(serverHandle, itemHandle)` completion cache (mirror of `MxAccessValueCache`) is populated by the event sink's `OnWriteComplete` post-publish hook; the STA command executor captures a version baseline before the COM call, then pump-waits (ReadBulk precedent) until a newer completion lands or the deadline passes. Design: `docs/plans/2026-08-09-write-completion-correlation-design.md`.
+
+**Tech Stack:** .NET Framework 4.8 x86 worker (no init-only props/positional records!), .NET 10 gateway, protobuf via Grpc.Tools regen. Worker builds/tests run ONLY on windev (10.100.0.48) — local macOS verification covers the gateway + contracts.
+
+---
+
+### Task 0: Create feature branch
+
+**Classification:** trivial
+**Estimated implement time:** ~1 min
+**Parallelizable with:** none
+
+```bash
+cd /Users/dohertj2/Desktop/MxAccessGateway && git checkout -b feat/write-completion-correlation
+```
+
+### Task 1: Proto contract comments + regen
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (everything builds on the regenerated contracts)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto` (~line 528 `statuses`, ~line 259 `WriteSecuredCommand`, ~line 269 `WriteSecured2Command`)
+- Regenerate: `src/ZB.MOM.WW.MxGateway.Contracts/Generated/*.cs`
+
+**Step 1:** On `repeated MxStatusProxy statuses = 7;` in `MxCommandReply`, add above the field:
+
+```proto
+ // Correlated per-item outcome rows. For WRITE_SECURED / WRITE_SECURED2
+ // replies the worker holds the reply for a bounded window (default 1.5 s,
+ // MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS) waiting for the matching
+ // MXAccess OnWriteComplete callback and copies its status rows here, so
+ // statuses[0] carries the real MXAccess commit outcome (success OR failure)
+ // while protocol_status/hresult still describe command acceptance only.
+ // Empty statuses on a write reply means the completion did not arrive
+ // within the window — the write is unconfirmed, not failed. Correlation is
+ // best-effort per (server_handle, item_handle): MXAccess's callback carries
+ // no transaction id, so concurrent writes to the same item within the
+ // window can swap rows. The OnWriteComplete event still flows on the event
+ // stream unchanged. Other command kinds leave this field as before.
+```
+
+**Step 2:** On `message WriteSecuredCommand` and `message WriteSecured2Command`, append to the existing leading comment (or add one): `// The unary reply's statuses field carries the correlated OnWriteComplete outcome when it arrives within the worker's bounded wait — see MxCommandReply.statuses.`
+
+**Step 3:** Regenerate + verify wire-identical build:
+
+```bash
+rm src/ZB.MOM.WW.MxGateway.Contracts/Generated/*.cs
+dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj
+```
+Expected: build succeeds, `git diff --stat` shows only comment-churn in Generated.
+
+**Step 4:** Commit: `git add src/ZB.MOM.WW.MxGateway.Contracts/Protos/mxaccess_gateway.proto src/ZB.MOM.WW.MxGateway.Contracts/Generated && git commit -m "docs(proto): document the correlated write-completion statuses contract"`
+(Comment-only proto change is wire-identical; other clients' generated code is intentionally not regenerated — no functional delta.)
+
+### Task 2: MxAccessWriteCompletionCache + tests
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 7
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessWriteCompletionCache.cs`
+- Create: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessWriteCompletionCacheTests.cs`
+
+**Step 1:** Create the cache — mirror `MxAccessValueCache`'s shape, locking, and net48 constraints (no init-only, plain struct/class):
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using Google.Protobuf.Collections;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
+
+///
+/// Per-session cache of the most recent OnWriteComplete status rows
+/// for each (server handle, item handle) pair. Written by the MXAccess
+/// event sink as completion callbacks arrive; read by the write command
+/// executor so a WriteSecured/WriteSecured2 reply can carry the correlated
+/// MXAccess outcome instead of proving command acceptance only.
+///
+///
+/// Same threading posture as : writers and
+/// readers run on the worker's STA thread (COM dispatches events on the
+/// apartment thread; commands also execute on the STA), so no internal
+/// locking is required. A single sync root keeps it nominally thread-safe
+/// for tests that drive it from a non-STA thread.
+///
+public sealed class MxAccessWriteCompletionCache
+{
+ private readonly Dictionary entries = new();
+ private readonly object syncRoot = new();
+
+ /// Records the status rows of a fresh OnWriteComplete callback for the given handle pair.
+ /// MXAccess server handle.
+ /// MXAccess item handle.
+ /// Status rows from the mapped OnWriteComplete event; cloned before storing.
+ public void Record(
+ int serverHandle,
+ int itemHandle,
+ RepeatedField statuses)
+ {
+ if (statuses is null)
+ {
+ throw new ArgumentNullException(nameof(statuses));
+ }
+
+ lock (syncRoot)
+ {
+ long key = CreateItemKey(serverHandle, itemHandle);
+ ulong version = entries.TryGetValue(key, out CompletionEntry existing)
+ ? existing.Version + 1
+ : 1UL;
+ entries[key] = new CompletionEntry(version, statuses.Clone());
+ }
+ }
+
+ /// Returns the current completion version for a handle pair, or 0 if none was recorded.
+ /// MXAccess server handle.
+ /// MXAccess item handle.
+ /// The current completion version, or 0 if no completion was recorded.
+ public ulong CurrentVersion(
+ int serverHandle,
+ int itemHandle)
+ {
+ lock (syncRoot)
+ {
+ return entries.TryGetValue(CreateItemKey(serverHandle, itemHandle), out CompletionEntry existing)
+ ? existing.Version
+ : 0UL;
+ }
+ }
+
+ ///
+ /// Polls for a completion newer than until it
+ /// arrives or the deadline elapses, calling on every
+ /// poll iteration so the worker's STA can dispatch the inbound MXAccess
+ /// OnWriteComplete message. Same loop shape as
+ /// .
+ ///
+ /// MXAccess server handle.
+ /// MXAccess item handle.
+ /// Version snapshot captured before the write COM call.
+ /// Absolute UTC deadline.
+ /// Action that pumps any pending Windows messages.
+ /// The recorded status rows if a completion arrived before the deadline.
+ /// How long to sleep between pump cycles. Default 5 ms.
+ /// if a completion newer than arrived before the deadline; otherwise .
+ public bool TryWaitForCompletion(
+ int serverHandle,
+ int itemHandle,
+ ulong sinceVersion,
+ DateTime deadlineUtc,
+ Action pumpStep,
+ out RepeatedField statuses,
+ int pollIntervalMs = 5)
+ {
+ if (pumpStep is null)
+ {
+ throw new ArgumentNullException(nameof(pumpStep));
+ }
+
+ while (true)
+ {
+ pumpStep();
+
+ lock (syncRoot)
+ {
+ if (entries.TryGetValue(CreateItemKey(serverHandle, itemHandle), out CompletionEntry entry)
+ && entry.Version > sinceVersion)
+ {
+ statuses = entry.Statuses;
+ return true;
+ }
+ }
+
+ if (DateTime.UtcNow >= deadlineUtc)
+ {
+ statuses = new RepeatedField();
+ return false;
+ }
+
+ Thread.Sleep(pollIntervalMs);
+ }
+ }
+
+ private static long CreateItemKey(
+ int serverHandle,
+ int itemHandle)
+ {
+ return ((long)serverHandle << 32) | (uint)itemHandle;
+ }
+
+ ///
+ /// Snapshot of the most recent OnWriteComplete status rows for a handle
+ /// pair. increments by one on every
+ /// call so the write executor can detect "a new
+ /// completion arrived since I captured my baseline".
+ ///
+ ///
+ /// Plain readonly struct (not a record) so this compiles under the
+ /// worker's net48 target, which lacks IsExternalInit.
+ ///
+ private readonly struct CompletionEntry
+ {
+ public CompletionEntry(
+ ulong version,
+ RepeatedField statuses)
+ {
+ Version = version;
+ Statuses = statuses;
+ }
+
+ public ulong Version { get; }
+
+ public RepeatedField Statuses { get; }
+ }
+}
+```
+
+**Step 2:** Tests (mirror `MxAccessValueCacheTests` style; build `MxStatusProxy` rows inline):
+
+- `Record_IncrementsVersionPerKey` — two `Record` calls on the same pair → `CurrentVersion` 1 then 2; a different pair stays independent.
+- `TryWaitForCompletion_WhenCompletionNewerThanBaseline_ReturnsStatuses` — record once, wait with `sinceVersion: 0`, deadline in the future → `true`, statuses round-trip (assert an `MxStatusProxy` field value survives the clone).
+- `TryWaitForCompletion_WhenOnlyStaleCompletion_TimesOut` — record once, wait with `sinceVersion: CurrentVersion(...)` and a deadline ~50 ms out → `false`, out statuses empty.
+- `TryWaitForCompletion_InvokesPumpStepEachIteration` — pumpStep increments a counter; on the counter's second call, `Record` the completion (this proves the pump loop is what lets the callback land); assert `true` and counter >= 2.
+- `Record_ClonesStatuses` — mutate the caller's `RepeatedField` after `Record`; waited-out statuses unaffected.
+
+**Step 3:** Cannot compile locally (worker is Windows-only) — defer build/test to Task 9 (windev). Commit: `git add src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessWriteCompletionCache.cs src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessWriteCompletionCacheTests.cs && git commit -m "feat(worker): versioned OnWriteComplete completion cache"`
+
+### Task 3: Sink records completions (+ provider seam)
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 7
+
+**Files:**
+- Create: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/IWriteCompletionCacheProvider.cs`
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessBaseEventSink.cs`
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessBaseEventSinkTests.cs`
+
+**Step 1:** New seam interface:
+
+```csharp
+namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
+
+///
+/// Exposes the per-session an
+/// event sink populates from OnWriteComplete callbacks, so
+/// can share one instance between the
+/// sink (writer) and the write command executor (reader). Implemented by
+/// and by test sinks that cannot
+/// attach to a live MXAccess COM object.
+///
+public interface IWriteCompletionCacheProvider
+{
+ /// The completion cache bound to this sink.
+ MxAccessWriteCompletionCache WriteCompletionCache { get; }
+}
+```
+
+**Step 2:** `MxAccessBaseEventSink` — declare `IWriteCompletionCacheProvider` on the class; add a `private readonly MxAccessWriteCompletionCache writeCompletionCache;` initialized in the widest ctor (add a new optional-most ctor overload following the existing chain pattern: the 3-arg `(eventQueue, eventMapper, valueCache)` ctor chains to a new 4-arg `(eventQueue, eventMapper, valueCache, writeCompletionCache)` with a fresh cache); expose `public MxAccessWriteCompletionCache WriteCompletionCache => writeCompletionCache;`. Change `OnWriteComplete` to use the post-publish hook (same pattern as `OnDataChange`'s value-cache publish — post-publish only runs after the event cleared the queue, and a queue overflow faults the session anyway):
+
+```csharp
+ MXSTATUS_PROXY[] statuses = pVars;
+ EnqueueEvent(
+ () => eventMapper.CreateOnWriteComplete(
+ sessionId,
+ hLMXServerHandle,
+ phItemHandle,
+ statuses),
+ mxEvent => writeCompletionCache.Record(hLMXServerHandle, phItemHandle, mxEvent.Statuses));
+```
+
+**Step 3:** Tests in `MxAccessBaseEventSinkTests` (mirror `OnDataChange_ComCallback_PopulatesValueCache` and `ValueCache_ReturnsTheInstanceBoundAtConstruction`):
+- `OnWriteComplete_ComCallback_RecordsCompletionAndStillEnqueuesEvent` — drive `sink.OnWriteComplete(7, 21, ref proxies)`; assert the queue got the OnWriteComplete event AND `cache.CurrentVersion(7, 21) == 1`.
+- `WriteCompletionCache_ReturnsTheInstanceBoundAtConstruction`.
+
+**Step 4:** Commit: `git commit -m "feat(worker): event sink records OnWriteComplete rows into the completion cache"` (explicit paths).
+
+### Task 4: MxAccessSession plumbing
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 7
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs` (private ctor ~line 18, `Create` ~line 145)
+
+**Step 1:** Add `private readonly MxAccessWriteCompletionCache writeCompletionCache;` + ctor param (after `valueCache`) + null guard; add property mirroring `ValueCache`:
+
+```csharp
+ ///
+ /// Per-session OnWriteComplete completion cache populated by the event
+ /// sink. The write command executor consults it after a
+ /// WriteSecured/WriteSecured2 COM call so the unary reply can carry
+ /// the correlated completion outcome.
+ ///
+ public MxAccessWriteCompletionCache WriteCompletionCache => writeCompletionCache;
+```
+
+**Step 2:** In `Create`, next to the value-cache sharing block:
+
+```csharp
+ // Share the sink's completion cache the same way (production sink
+ // and completion-aware test sinks implement the provider seam);
+ // fall back to a fresh cache for other fakes — the write executor
+ // then simply never observes a completion and replies unconfirmed.
+ MxAccessWriteCompletionCache writeCompletionCache = eventSink is IWriteCompletionCacheProvider provider
+ ? provider.WriteCompletionCache
+ : new MxAccessWriteCompletionCache();
+```
+
+Pass it to the ctor.
+
+**Step 3:** Commit: `git commit -m "feat(worker): share the completion cache between sink and session"`.
+
+### Task 5: Executor bounded wait + StaSession env plumbing
+
+**Classification:** high-risk (STA/pump semantics)
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (touches the same files as 6's tests exercise)
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs` (~lines 14-85 ctors, 447-497 write methods)
+- Modify: `src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs` (~line 205 executor construction)
+
+**Step 1:** Executor — next to `DefaultReadBulkTimeout`:
+
+```csharp
+ ///
+ /// Default bounded wait for the OnWriteComplete callback after a
+ /// WriteSecured/WriteSecured2 COM call. 1.5 s keeps the unary reply
+ /// inside the OtOpcUa driver's 2 s Tier A write-resilience budget (a
+ /// longer gateway wait must raise that consumer timeout in step) while
+ /// covering the common fast-commit case; on expiry the reply returns
+ /// with empty statuses — unconfirmed, not failed.
+ ///
+ internal static readonly TimeSpan DefaultWriteCompletionTimeout = TimeSpan.FromMilliseconds(1500);
+
+ private readonly TimeSpan writeCompletionTimeout;
+```
+
+Add `TimeSpan? writeCompletionTimeout = null` as a trailing optional parameter on the widest (4-arg) ctor; `this.writeCompletionTimeout = writeCompletionTimeout ?? DefaultWriteCompletionTimeout;`.
+
+**Step 2:** In `ExecuteWriteSecured`, replace the tail (`session.WriteSecured(...); return CreateOkReply(command);`) with:
+
+```csharp
+ MxAccessWriteCompletionCache completionCache = session.WriteCompletionCache;
+ // Baseline BEFORE the COM call: a completion that dispatches during or
+ // immediately after WriteSecured bumps the version past this snapshot,
+ // so a fast commit still correlates (no missed-callback window).
+ ulong completionBaseline = completionCache.CurrentVersion(
+ writeSecuredCommand.ServerHandle,
+ writeSecuredCommand.ItemHandle);
+
+ session.WriteSecured(
+ writeSecuredCommand.ServerHandle,
+ writeSecuredCommand.ItemHandle,
+ writeSecuredCommand.CurrentUserId,
+ writeSecuredCommand.VerifierUserId,
+ variantConverter.ConvertToComValue(writeSecuredCommand.Value));
+
+ MxCommandReply reply = CreateOkReply(command);
+ AwaitWriteCompletion(
+ reply,
+ completionCache,
+ writeSecuredCommand.ServerHandle,
+ writeSecuredCommand.ItemHandle,
+ completionBaseline);
+ return reply;
+```
+
+Mirror in `ExecuteWriteSecured2`. Shared private helper:
+
+```csharp
+ ///
+ /// Bounded pump-wait for the OnWriteComplete row matching a
+ /// WriteSecured/WriteSecured2 call, copied onto the reply when it
+ /// arrives in time. The executor holds the STA thread but pumps
+ /// Windows messages each poll (ReadBulk precedent) so the COM callback
+ /// can dispatch re-entrantly; on expiry the reply keeps its empty
+ /// statuses — the consumer's unconfirmed path, never a synthesized
+ /// failure. Protocol status/hresult stay acceptance-only either way.
+ ///
+ private void AwaitWriteCompletion(
+ MxCommandReply reply,
+ MxAccessWriteCompletionCache completionCache,
+ int serverHandle,
+ int itemHandle,
+ ulong completionBaseline)
+ {
+ if (writeCompletionTimeout <= TimeSpan.Zero)
+ {
+ return;
+ }
+
+ if (completionCache.TryWaitForCompletion(
+ serverHandle,
+ itemHandle,
+ completionBaseline,
+ DateTime.UtcNow + writeCompletionTimeout,
+ pumpStep,
+ out Google.Protobuf.Collections.RepeatedField statuses))
+ {
+ reply.Statuses.Add(statuses);
+ }
+ }
+```
+
+**Step 3:** `MxAccessStaSession` — add:
+
+```csharp
+ ///
+ /// Environment variable the gateway's WorkerProcessLauncher sets from
+ /// MxGateway:Worker:WriteCompletionWaitMilliseconds. 0 disables the
+ /// write-completion wait (pure fire-and-forget replies).
+ ///
+ internal const string WriteCompletionWaitEnvironmentVariableName =
+ "MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS";
+
+ ///
+ /// Bounded WriteSecured/WriteSecured2 completion wait handed to the
+ /// command executor at StartAsync. Internal-settable as a test seam so
+ /// Worker.Tests can shorten it without env-var plumbing.
+ ///
+ internal TimeSpan WriteCompletionTimeout { get; set; } = ResolveWriteCompletionTimeout();
+
+ internal static TimeSpan ResolveWriteCompletionTimeout()
+ {
+ string value = Environment.GetEnvironmentVariable(WriteCompletionWaitEnvironmentVariableName);
+ return int.TryParse(value, System.Globalization.NumberStyles.Integer, System.Globalization.CultureInfo.InvariantCulture, out int milliseconds)
+ && milliseconds >= 0
+ ? TimeSpan.FromMilliseconds(milliseconds)
+ : MxAccessCommandExecutor.DefaultWriteCompletionTimeout;
+ }
+```
+
+and pass `writeCompletionTimeout: WriteCompletionTimeout` when constructing `MxAccessCommandExecutor` in `StartAsync`. (net48: `Environment.GetEnvironmentVariable` returns `string` — keep nullable annotations consistent with the file.)
+
+**Step 4:** Commit: `git commit -m "feat(worker): bounded pump-wait correlates OnWriteComplete onto secured-write replies"`.
+
+### Task 6: Executor tests
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (depends on Tasks 2-5)
+
+**Files:**
+- Test: `src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs`
+
+**Step 1:** Test support inside the test class file:
+- New sink: `private sealed class CompletionCacheEventSink : IMxAccessEventSink, IWriteCompletionCacheProvider { public MxAccessWriteCompletionCache WriteCompletionCache { get; } = new MxAccessWriteCompletionCache(); public void Attach(object mxAccessComObject, string sessionId) { } public void Detach() { } }` (match the exact `IMxAccessEventSink` member list — read the interface first).
+- `FakeMxAccessComObject`: add `public Action OnWriteSecuredCallback { get; set; }` (nullable per file convention) invoked at the end of `WriteSecured` and `WriteSecured2`.
+
+**Step 2:** Tests (all through `MxAccessStaSession.DispatchAsync`, constructing the session with the completion sink; set `session.WriteCompletionTimeout` before `StartAsync`):
+
+- `DispatchAsync_WriteSecured_WhenCompletionArrivesDuringComCall_ReturnsStatuses` (fast-completion edge): wire `OnWriteSecuredCallback = () => sink.WriteCompletionCache.Record(82, 821, StatusRows(1))` (helper building a `RepeatedField` with a recognizable value); dispatch; assert `ProtocolStatus.Code == Ok`, `reply.Statuses.Count == 1`, row round-trips.
+- `DispatchAsync_WriteSecured_WhenCompletionArrivesWhileWaiting_ReturnsStatuses`: no fake callback; `WriteCompletionTimeout = TimeSpan.FromSeconds(10)`; start `Task pending = session.DispatchAsync(...)`, then `sink.WriteCompletionCache.Record(...)` from the test thread after a short `Task.Delay(50)`; await; assert statuses present. (No `.ConfigureAwait(false)` in `[Fact]` bodies — xUnit1030 fails the Windows build.)
+- `DispatchAsync_WriteSecured_WhenNoCompletion_TimesOutWithEmptyStatusesAndOkProtocol`: `WriteCompletionTimeout = TimeSpan.FromMilliseconds(100)`; assert Ok + `reply.Statuses.Count == 0`.
+- `DispatchAsync_WriteSecured2_WhenCompletionArrivesDuringComCall_ReturnsStatuses` (mirror of the fast test).
+- `DispatchAsync_Write_DoesNotWaitForCompletion`: `WriteCompletionTimeout = TimeSpan.FromSeconds(30)`, plain `Write` command, no completion recorded; assert `await` completes within a 5 s guard (`Task.WhenAny` with `Task.Delay`) — proving plain writes never enter the wait.
+- Baseline test `DispatchAsync_WriteSecured_IgnoresStaleCompletionFromBeforeTheCall`: `Record` once BEFORE dispatch, `WriteCompletionTimeout = 100 ms`, no new completion → empty statuses (stale row not misattributed).
+
+**Step 2b:** Confirm the two existing WriteSecured tests (`DispatchAsync_WriteSecured_ForwardsUserIds`, `..._WriteSecured2_...`) still pass unmodified — they use `NoopEventSink`, so the session falls back to a fresh cache, no completion ever arrives, and the default 1.5 s wait adds latency only; if that latency bothers the suite, switch them to the completion sink with `WriteCompletionTimeout = TimeSpan.Zero`.
+
+**Step 3:** Commit: `git commit -m "test(worker): write-completion correlation executor coverage"`.
+
+### Task 7: Gateway config option + launcher env var
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 2, Task 3, Task 4
+
+**Files:**
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Configuration/WorkerOptions.cs`
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs` (~line 224 block)
+- Modify: `src/ZB.MOM.WW.MxGateway.Server/Workers/WorkerProcessLauncher.cs` (~lines 18-22 consts, ~line 175 env block)
+- Test: `src/ZB.MOM.WW.MxGateway.Tests/Gateway/Workers/WorkerProcessLauncherTests.cs`, the `GatewayOptionsValidator` test file (find via `grep -rl GatewayOptionsValidatorTests src/ZB.MOM.WW.MxGateway.Tests`)
+
+**Step 1:** `WorkerOptions`:
+
+```csharp
+ ///
+ /// Bounded wait, in milliseconds, the worker holds a WriteSecured/WriteSecured2
+ /// reply for the matching MXAccess OnWriteComplete callback so the reply's
+ /// statuses carry the real commit outcome. 0 disables the wait. Deployments
+ /// raising this above consumer write-timeout budgets (e.g. OtOpcUa's 2 s Tier A
+ /// write resilience timeout) must raise those in step.
+ ///
+ public int WriteCompletionWaitMilliseconds { get; init; } = 1500;
+```
+
+**Step 2:** Validator (>= 0, not the positive helper):
+
+```csharp
+ if (options.WriteCompletionWaitMilliseconds < 0)
+ {
+ builder.Add("MxGateway:Worker:WriteCompletionWaitMilliseconds must be greater than or equal to zero.");
+ }
+```
+
+**Step 3:** Launcher — const `public const string WorkerWriteCompletionWaitEnvironmentVariableName = "MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS";` and in `CreateStartInfo` next to the pipe-connect env line:
+
+```csharp
+ startInfo.Environment[WorkerWriteCompletionWaitEnvironmentVariableName] =
+ _workerOptions.WriteCompletionWaitMilliseconds.ToString(System.Globalization.CultureInfo.InvariantCulture);
+```
+
+**Step 4:** Tests — mirror the existing pipe-connect-timeout launcher env assertion and an existing validator negative test; add: launcher exports `MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS=1500` by default / custom value when configured; validator rejects `-1`, accepts `0`.
+
+**Step 5:** Run locally:
+
+```bash
+dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter "FullyQualifiedName~WorkerProcessLauncherTests|FullyQualifiedName~GatewayOptionsValidator"
+```
+Expected: PASS.
+
+**Step 6:** Commit: `git commit -m "feat(gateway): configurable worker write-completion wait (MxGateway:Worker:WriteCompletionWaitMilliseconds)"`.
+
+### Task 8: Docs
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (write after code settles)
+
+**Files:**
+- Modify: `docs/GatewayConfiguration.md` (Worker options table, ~line 113 area)
+- Modify: `gateway.md` (command surface / write semantics section)
+- Modify: `docs/DesignDecisions.md` (new decision entry)
+
+Content: the option row (default 1500, 0 disables, consumer-budget pairing rule with OtOpcUa's Write resilience timeout); gateway.md note that WriteSecured/WriteSecured2 unary replies now carry correlated completion statuses (bounded wait, empty = unconfirmed, event stream unchanged); DesignDecisions entry summarizing the design doc (link it) including the best-effort per-(hItem) correlation caveat and why plain Write/Write2/bulk stay fire-and-forget. Follow `docs/style-guides/StyleGuide.md` (present tense, why not what).
+
+Commit: `git commit -m "docs: write-completion correlation configuration and semantics"`.
+
+### Task 9: Local + windev verification
+
+**Classification:** standard
+**Estimated implement time:** ~10 min (mostly remote build time)
+**Parallelizable with:** none
+
+**Step 1 (local):** `dotnet build src/ZB.MOM.WW.MxGateway.NonWindows.slnx` → succeeds; re-run the Task 7 filtered gateway tests.
+
+**Step 2 (push):** `git push -u origin feat/write-completion-correlation`.
+
+**Step 3 (windev):** Use the isolated `C:\build` worktree (NOT the Desktop checkout — dirty feature branch). Remote PS via base64 `-EncodedCommand`; no `$ErrorActionPreference='Stop'` around git. Sequence:
+
+```
+git fetch origin && git checkout feat/write-completion-correlation && git pull
+dotnet build src/ZB.MOM.WW.MxGateway.Worker/ZB.MOM.WW.MxGateway.Worker.csproj -p:Platform=x86
+dotnet test src/ZB.MOM.WW.MxGateway.Worker.Tests/ZB.MOM.WW.MxGateway.Worker.Tests.csproj -p:Platform=x86 --filter "FullyQualifiedName~MxAccessWriteCompletionCacheTests|FullyQualifiedName~MxAccessBaseEventSinkTests|FullyQualifiedName~MxAccessCommandExecutorTests"
+```
+Expected: build clean (TreatWarningsAsErrors — watch xUnit1030), all filtered tests PASS. Fix-and-push iterations happen from the Mac; windev only builds/tests.
+
+**Step 4:** Full worker test suite once green on the filter (`dotnet test ... -p:Platform=x86`, no filter) — one full pass before merge.
+
+### Task 10: Review, merge, notify
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+- Run a code review over the full branch diff (code-reviewer agent or /code-review) and address findings.
+- Merge: `git checkout main && git merge --no-ff feat/write-completion-correlation && git push origin main`.
+- Notify the OtOpcUa session (SendMessage) that the feature is on `main` and built/tested on windev; flag that the live ArchestrA leg needs the user's Windows deployment (wonder-app-vd03 / 10.100.0.48 redeploy is a separate user-approved step).
+- Surface to the user: deployed services (`MxAccessGw` on 10.100.0.48, wonder-app-vd03) do NOT pick this up until redeployed; OtOpcUa's end-to-end verification against a live gateway needs that redeploy.
diff --git a/docs/plans/2026-08-09-write-completion-correlation.md.tasks.json b/docs/plans/2026-08-09-write-completion-correlation.md.tasks.json
new file mode 100644
index 0000000..313b3e6
--- /dev/null
+++ b/docs/plans/2026-08-09-write-completion-correlation.md.tasks.json
@@ -0,0 +1,17 @@
+{
+ "planPath": "docs/plans/2026-08-09-write-completion-correlation.md",
+ "tasks": [
+ {"id": 0, "subject": "Task 0: Create feature branch", "status": "pending"},
+ {"id": 1, "subject": "Task 1: Proto contract comments + regen", "status": "pending", "blockedBy": [0]},
+ {"id": 2, "subject": "Task 2: MxAccessWriteCompletionCache + tests", "status": "pending", "blockedBy": [1]},
+ {"id": 3, "subject": "Task 3: Sink records completions (+ provider seam)", "status": "pending", "blockedBy": [2]},
+ {"id": 4, "subject": "Task 4: MxAccessSession plumbing", "status": "pending", "blockedBy": [3]},
+ {"id": 5, "subject": "Task 5: Executor bounded wait + StaSession env plumbing", "status": "pending", "blockedBy": [4]},
+ {"id": 6, "subject": "Task 6: Executor tests", "status": "pending", "blockedBy": [5]},
+ {"id": 7, "subject": "Task 7: Gateway config option + launcher env var", "status": "pending", "blockedBy": [0]},
+ {"id": 8, "subject": "Task 8: Docs", "status": "pending", "blockedBy": [6, 7]},
+ {"id": 9, "subject": "Task 9: Local + windev verification", "status": "pending", "blockedBy": [8]},
+ {"id": 10, "subject": "Task 10: Review, merge, notify", "status": "pending", "blockedBy": [9]}
+ ],
+ "lastUpdated": "2026-08-09"
+}