docs: reconcile alarms-over-gateway banner with audited source

The 'All 19 PRs merged' banner contradicted the warning paragraph in
the same block and overstated reality against the source tree. Audit
of the lmxopcua + mxaccessgw repos on 2026-05-01 found:

- 17 of 19 PRs merged. Four merged PRs ship inert scaffolds:
  - A.2: MxAccessAlarmEventSink.Attach is a no-op.
  - A.3 / A.4: NotWiredAlarmRpcDispatcher returns OK-with-diagnostic
    for AcknowledgeAlarm and an empty stream for QueryActiveAlarms.
  - C.1: SdkAlarmHistorianWriteBackend.WriteBatchAsync returns
    RetryPlease for every event with a placeholder log.
- The architectural decision the warning paragraph asks the operator
  to make was already resolved 2026-04-30. MxAccessAlarmEventSink.cs
  in mxaccessgw records that aaAlarmManagedClient.AlarmClient is x86
  net48 (same bitness as the worker), and pins the discovered API
  surface (RegisterConsumer / Subscribe / GetStatistics /
  GetAlarmExtendedRec / AlarmAckByGUID). What remains is wiring PRs
  in the worker, not architectural choice.
- D.1 smoke artifact (docs/plans/artifacts/d1-rollout-YYYY-MM-DD.md)
  not yet captured; directory does not exist.

Banner rewritten to split functional-end-to-end vs merged-but-inert
PRs explicitly so future readers don't have to reconcile the doc
against the source tree themselves.

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

docs/AlarmTracking.md

@@ -0,0 +1,129 @@
+# Alarm tracking — v2 final architecture
+
+This document describes how OtOpcUa surfaces alarms to OPC UA Part 9
+clients after the **alarms-over-gateway** epic
+([docs/plans/alarms-over-gateway.md](plans/alarms-over-gateway.md))
+landed. The v1 architecture (Galaxy.Host's COM-side `GalaxyAlarmTracker`)
+is preserved at [docs/v1/AlarmTracking.md](v1/AlarmTracking.md) for
+historical reference.
+
+## Three alarm sources, one OPC UA Part 9 surface
+
+| Source                           | Driver capability        | Path |
+|----------------------------------|--------------------------|------|
+| **Galaxy MxAccess (driver-native)** | `GalaxyDriver : IAlarmSource` | gateway → worker → MxAccess alarm sink → `MX_EVENT_FAMILY_ON_ALARM_TRANSITION` → `EventPump` → driver `OnAlarmEvent` → `AlarmConditionService` |
+| **Galaxy sub-attribute fallback**  | `IWritable` writes to `$Alarm*` sub-attributes | gateway data subscription → driver `OnDataChange` → `DriverNodeManager` ConditionSink → `AlarmConditionService` |
+| **Scripted alarms**                | `Phase7EngineComposer` | server-side script evaluator → `Phase7EngineComposer.RouteToHistorianAsync` + `AlarmConditionService` |
+
+All three converge on `AlarmConditionService` (`src/ZB.MOM.WW.OtOpcUa.Server/Alarms/AlarmConditionService.cs`),
+which owns the OPC UA Part 9 state machine and dispatches transitions
+to the OPC UA condition node managers. Driver-native transitions take
+precedence over sub-attribute synthesis when both arrive for the same
+condition — the dedup logic prefers the richer driver-native record
+because it carries the full operator + raise-time + category metadata
+that the value-driven path collapses.
+
+## Galaxy driver path (driver-native)
+
+Restored in PR B.2 of the epic. `GalaxyDriver` implements
+`IAlarmSource` with these surfaces:
+
+- `SubscribeAlarmsAsync(sourceNodeIds)` → returns a sentinel handle.
+  The driver doesn't multiplex per source-node-id today; every
+  active handle observes the gateway's alarm-event stream. The
+  server-side `AlarmConditionService` filters by source-node before
+  raising the OPC UA condition.
+- `UnsubscribeAlarmsAsync(handle)` → symmetric handle removal.
+- `AcknowledgeAsync(requests)` → routes one gateway RPC per
+  acknowledgement through `IGalaxyAlarmAcknowledger`. Production
+  uses `GatewayGalaxyAlarmAcknowledger` calling
+  `MxGatewayClient.AcknowledgeAlarmAsync` (PR E.2 SDK method).
+- `OnAlarmEvent` → bridges `EventPump.OnAlarmTransition` (PR B.1)
+  onto `AlarmEventArgs`. Suppressed when no alarm subscription is
+  active so untracked transitions don't leak through.
+
+The proto contract carries the rich payload — alarm full reference,
+source-object reference, alarm-type-name, transition kind (Raise /
+Acknowledge / Clear / Retrigger), severity (raw MxAccess scale),
+original raise timestamp, transition timestamp, operator user,
+operator comment, alarm category, description. `MxAccessSeverityMapper`
+(PR B.1) translates the raw severity onto the four-bucket
+`AlarmSeverity` ladder — boundaries match v1's `GalaxyAlarmTracker`
+so customers see no surprise re-classification.
+
+The richer fields surface on `Core.Abstractions.AlarmEventArgs` via
+the optional properties added in PR E.7 (`OperatorComment`,
+`OriginalRaiseTimestampUtc`, `AlarmCategory`). Consumers that don't
+need them are unaffected; consumers that do (Client.UI, Client.CLI
+verbose mode) read the new fields when present.
+
+## Galaxy sub-attribute fallback
+
+For Galaxy templates without `$Alarm*` extensions, the value-driven
+path stays in place: `DriverNodeManager` registers an
+`AlarmConditionState` per Galaxy variable that bears alarm-bearing
+sub-attributes (`InAlarm`, `Acked`, `Priority`, `Description`),
+subscribes to those sub-attributes, and synthesizes Part 9 transitions
+when the values change. This path operated as the only Galaxy alarm
+path between PR 7.2 and the alarms-over-gateway epic; it remains the
+fallback today.
+
+When both paths report the same condition,
+`AlarmConditionService.AlarmConditionState` keeps the
+driver-native record and discards the duplicate sub-attribute
+synthesis. Driver-native transitions are richer (carry operator
+comment + original raise time) and arrive lower-latency (no
+publishing-interval delay on the sub-attribute reads), so they win
+the dedup.
+
+## Acknowledge routing
+
+`DriverNodeManager` picks the acknowledger when registering each
+condition (PR B.3 logic):
+
+- Driver implements `IAlarmSource` →
+  `DriverAlarmSourceAcknowledger` routes the operator comment
+  through `IAlarmSource.AcknowledgeAsync` via the existing
+  `AlarmSurfaceInvoker` (Phase 6.1 resilience pipeline; no-retry
+  per decision #143). End-to-end operator-comment fidelity is
+  preserved.
+- Driver doesn't implement `IAlarmSource` →
+  `DriverWritableAcknowledger` writes the comment into the
+  `AckMsgWriteRef` sub-attribute via `IWritable.WriteAsync`. Same
+  resilience pipeline; collapses the comment into a single string
+  write at the wire level.
+
+The OPC UA Part 9 `AlarmConditionState.OnAcknowledge` delegate
+already validates the session's `AlarmAck` role before dispatching,
+so the gateway-side ack RPC only sees authenticated, authorised
+calls.
+
+## Historian write-back (non-Galaxy alarms)
+
+Scripted alarms (and any future non-Galaxy `IAlarmSource` like
+AB CIP ALMD) route to AVEVA Historian via the Wonderware sidecar:
+
+- `Phase7Composer.ResolveHistorianSink` resolves an
+  `IAlarmHistorianWriter` from either a driver that natively
+  implements it or the DI-registered `WonderwareHistorianClient`
+  (the sidecar IPC client). Driver-provided wins when both are
+  present.
+- `SqliteStoreAndForwardSink` queues each transition to a local
+  SQLite database and drains in the background via the resolved
+  writer.
+- Sidecar (PR C.1 + C.2) forwards the events to `aahClientManaged`'s
+  alarm-event write API; the live SDK call site is pinned during
+  PR D.1's deploy-rig validation.
+
+Galaxy-native alarms with `$Alarm*` extensions reach AVEVA Historian
+directly via System Platform's `HistorizeToAveva` toggle on the
+alarm primitive — no involvement from OtOpcUa. This sidecar path is
+exclusively for non-Galaxy alarm producers.
+
+## Cross-references
+
+- Plan: [docs/plans/alarms-over-gateway.md](plans/alarms-over-gateway.md)
+- v1 archive: [docs/v1/AlarmTracking.md](v1/AlarmTracking.md)
+- Galaxy driver: [docs/drivers/Galaxy.md](drivers/Galaxy.md)
+- Phase 7 scripting + alarming: [docs/v2/implementation/phase-7-scripting-and-alarming.md](v2/implementation/phase-7-scripting-and-alarming.md)
+- Security + ACL: [docs/Security.md](Security.md)

docs/drivers/Galaxy.md

@@ -15,7 +15,8 @@ For the driver spec (capability surface, config shape, addressing), see [docs/v2
                     |    ITagDiscovery / IReadable /        |
                     |    IWritable / ISubscribable /        |
                     |    IRediscoverable /                  |
-                    |    IHostConnectivityProbe             |
+                    |    IHostConnectivityProbe /           |
+                    |    IAlarmSource                       |
                     +-------------------+-------------------+
                                         |
                                        gRPC (default http://localhost:5120)
@@ -33,7 +34,18 @@ For the driver spec (capability surface, config shape, addressing), see [docs/v2
                     +---------------------------------------+
 ```
 
-History reads + alarm-condition tracking moved server-side in PR 7.2 (`IHistoryRouter`, `AlarmConditionService`). Galaxy no longer implements `IHistoryProvider` or `IAlarmSource` of its own.
+History reads moved server-side in PR 7.2 (`IHistoryRouter`). Galaxy no longer implements `IHistoryProvider` of its own.
+
+`IAlarmSource` was retired with PR 7.2 and **restored in PR B.2** of the
+alarms-over-gateway epic ([docs/plans/alarms-over-gateway.md](../plans/alarms-over-gateway.md)).
+Alarm transitions arrive on the same gateway `StreamEvents` channel as
+data-change events under the new `MX_EVENT_FAMILY_ON_ALARM_TRANSITION`
+family; acknowledgements route through the gateway's
+`AcknowledgeAlarm` RPC. The previous value-driven sub-attribute path
+remains as a fallback for Galaxy templates without `$Alarm*`
+extensions — the server-side `AlarmConditionService` dedups when both
+paths fire on the same condition. See [docs/AlarmTracking.md](../AlarmTracking.md)
+for the v2-final architecture.
 
 ## Project Layout
 

docs/plans/alarms-over-gateway.md

@@ -1,5 +1,63 @@
 # Plan — alarms over the mxaccessgw gateway
 
+> **17 of 19 PRs merged. Public contract surface and the lmxopcua /
+> sidecar consumers are live; four merged PRs ship as scaffolds
+> pending worker-side wiring.** Status reconciled against the source
+> tree on 2026-05-01.
+>
+> **Functional end-to-end today:** B.1 / B.2 / B.3 / B.4 / B.5
+> (EventPump branch, GalaxyDriver `IAlarmSource`, DriverNodeManager
+> ack routing, `WonderwareHistorianClient : IAlarmHistorianWriter`,
+> docs sweep), C.2 (sidecar wires the alarm-write slot), D.1 script
+> (`scripts/install/Refresh-Services.ps1`), E.1 – E.7 (proto regen +
+> .NET / Python / Go / Java / Rust SDK alarm methods + lmxopcua client
+> surface). The value-driven sub-attribute fallback path keeps Galaxy
+> alarms functional today.
+>
+> **Merged-but-inert scaffolds (gated on worker AlarmClient wiring):**
+>
+> - **A.2** — `MxAccessAlarmEventSink.Attach` is a no-op; the COM-side
+>   `aaAlarmManagedClient.AlarmClient` registration / subscription has
+>   not landed yet, so the gateway's
+>   `MX_EVENT_FAMILY_ON_ALARM_TRANSITION` is reserved on the wire but
+>   never emitted.
+> - **A.3** AcknowledgeAlarm + **A.4** QueryActiveAlarms — public RPC
+>   handlers in `MxAccessGatewayService.cs` route through
+>   `NotWiredAlarmRpcDispatcher` (Ack returns OK with a `worker dispatch
+>   pending dev-rig wiring` diagnostic; Query yields an empty stream).
+> - **C.1** sidecar — `AahClientManagedAlarmEventWriter` exists and the
+>   IPC slot is wired, but the production backend
+>   `SdkAlarmHistorianWriteBackend.WriteBatchAsync` returns
+>   `RetryPlease` for every event with a placeholder log — the live
+>   `aahClientManaged` SDK call site is pinned during the D.1 dev-rig
+>   smoke. Effect: scripted-alarm transitions queue locally in
+>   `SqliteStoreAndForwardSink` and the drain worker repeatedly retries.
+>
+> **Architectural decision RESOLVED 2026-04-30** (recorded in the
+> mxaccessgw repo at `src/MxGateway.Worker/MxAccess/MxAccessAlarmEventSink.cs`
+> xmldoc): the worker hosts `aaAlarmManagedClient.AlarmClient` (x86
+> .NET Framework 4.8 — same bitness as the existing MxAccess COM
+> consumer) alongside the COM consumer, sharing the worker's STA +
+> WM_APP message pump. The discovered API surface
+> (`RegisterConsumer`, `Subscribe`, `GetStatistics`,
+> `GetAlarmExtendedRec`, `AlarmAckByGUID`) is documented in that
+> file's xmldoc. The earlier concern that AVEVA's alarm SDK was
+> x64-only proved wrong against the deployed assemblies. What remains
+> is wiring PRs in the worker — session-startup `RegisterConsumer` +
+> `Subscribe`, an STA WM_APP handler that routes
+> alarm-changed messages into `EnqueueTransition`, and the worker
+> command path that calls `AlarmAckByGUID` from a gateway
+> `AcknowledgeAlarm` RPC.
+>
+> **D.1 smoke artifact**
+> (`docs/plans/artifacts/d1-rollout-YYYY-MM-DD.md`, called for in the
+> Track D test plan below) not yet captured — gated on the worker
+> AlarmClient wiring being live on the dev rig so the smoke can
+> exercise the alarm scenarios end-to-end and pin the
+> `SdkAlarmHistorianWriteBackend` SDK entry point.
+>
+> The remainder of this document is preserved as the design record.
+
 Coordinated epic across two repos:
 
 - **`lmxopcua`** (this repo) — `c:\Users\dohertj2\Desktop\lmxopcua\`

docs/v1/AlarmTracking.md

@@ -1,4 +1,12 @@
-# Alarm Tracking
+# Alarm Tracking — v1 archive
+
+> **Historical record.** This document describes the v1 / pre-PR-7.2
+> Galaxy alarm path that ran inside `Galaxy.Host`'s STA pump as
+> `GalaxyAlarmTracker`. PR 7.2 retired the in-process Galaxy stack; the
+> alarms-over-gateway epic (B.2 / B.3 / E.7) restored Galaxy's
+> `IAlarmSource` capability against the new gateway-mediated transport.
+> See [docs/AlarmTracking.md](../AlarmTracking.md) for the v2 final
+> architecture — that is the document to read for current behaviour.
 
 Alarm surfacing is an optional driver capability exposed via `IAlarmSource` (`src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAlarmSource.cs`). Drivers whose backends have an alarm concept implement it — today: Galaxy (MXAccess alarms), FOCAS (CNC alarms), OPC UA Client (A&C events from the upstream server). Modbus / S7 / AB CIP / AB Legacy / TwinCAT do not implement the interface and the feature is simply absent from their subtrees.
 

docs/v2/dev-environment.md

@@ -408,6 +408,49 @@ For production:
 - Per-NodeId credentials in `ClusterNodeCredential` table (per decision #83)
 - Admin app uses LDAP (no SQL credential at all on the user-facing side)
 
+## Service Refresh — `Refresh-Services.ps1`
+
+The deploy host hosts three NSSM-wrapped services (`MxAccessGw`,
+`OtOpcUaWonderwareHistorian`, `OtOpcUa`) that consume binaries from
+`C:\publish\`. After landing changes in either repo, refresh the
+deployed bits with `scripts\install\Refresh-Services.ps1`:
+
+```powershell
+# Default invocation (dev rig).
+& C:\Users\dohertj2\Desktop\lmxopcua\scripts\install\Refresh-Services.ps1
+
+# Skip the timestamped backup (faster on iterative dev cycles).
+& Refresh-Services.ps1 -SkipBackup
+
+# Dry-run — print the actions without doing them.
+& Refresh-Services.ps1 -WhatIf
+```
+
+The script:
+
+1. Stops services in reverse-dependency order (`OtOpcUa` →
+   `OtOpcUaWonderwareHistorian` → `MxAccessGw`) and force-kills
+   any residual processes.
+2. Snapshots the existing `C:\publish\mxaccessgw\` and
+   `C:\publish\lmxopcua\` trees to `C:\publish\.backup-<timestamp>\`
+   for rollback (skip with `-SkipBackup`).
+3. Builds + copies mxaccessgw worker (x86 net48) + server (net10.0)
+   binaries from the sibling repo.
+4. `dotnet publish`-es the OtOpcUa server + Wonderware historian
+   sidecar from this repo.
+5. Ensures `OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=true` is set on
+   the historian service env block (PR C.2 toggle).
+6. Starts services in forward-dependency order (`MxAccessGw` →
+   `OtOpcUaWonderwareHistorian` → `OtOpcUa`).
+7. Smoke-verifies — service status, listening ports (5120 / 4840 /
+   4841), recent log tails.
+
+Functional verification (alarm raise / scripted alarm historian
+round-trip / sub-attribute fallback) is the operator's next step
+after the refresh; see
+[docs/plans/alarms-over-gateway.md](../plans/alarms-over-gateway.md)
+§Track D for the scenarios.
+
 ## Test Data Seed
 
 Each environment needs a baseline data set so cross-developer tests are reproducible. Lives in `tests/ZB.MOM.WW.OtOpcUa.IntegrationTests/SeedData/`:

scripts/install/Refresh-Services.ps1

@@ -0,0 +1,210 @@
+[CmdletBinding()]
+param(
+    [string]$RepoRoot = "C:\Users\dohertj2\Desktop\lmxopcua",
+    [string]$GatewayRoot = "C:\Users\dohertj2\Desktop\mxaccessgw",
+    [string]$PublishRoot = "C:\publish",
+    [switch]$SkipBackup,
+    [switch]$WhatIf
+)
+
+# PR D.1 — refresh C:\publish + restart services for the alarms-over-gateway
+# epic. Stops services in reverse-dependency order (OtOpcUa →
+# OtOpcUaWonderwareHistorian → MxAccessGw), refreshes binaries from the
+# repos, then starts in forward order. A timestamped backup of the existing
+# C:\publish trees lands under C:\publish\.backup-YYYY-MM-DD\ unless
+# -SkipBackup is supplied.
+#
+# Designed to run as a single elevated PowerShell session on the deploy host
+# (the dev rig today; production refresh is a separate runbook).
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Step([string]$Message) {
+    Write-Host ""
+    Write-Host "==> $Message" -ForegroundColor Cyan
+}
+
+function Run([scriptblock]$Block, [string]$Description) {
+    if ($WhatIf) {
+        Write-Host "  (skip) $Description" -ForegroundColor DarkYellow
+        return
+    }
+    Write-Host "  $Description"
+    & $Block
+}
+
+function Test-NssmService([string]$Name) {
+    $svc = Get-Service -Name $Name -ErrorAction SilentlyContinue
+    return $null -ne $svc
+}
+
+# ------------------------------------------------------------------------
+# Step 1: Stop in reverse dependency order
+# ------------------------------------------------------------------------
+
+Step "Stopping services (OtOpcUa → OtOpcUaWonderwareHistorian → MxAccessGw)"
+
+foreach ($name in @('OtOpcUa', 'OtOpcUaWonderwareHistorian', 'MxAccessGw')) {
+    if (Test-NssmService $name) {
+        Run { nssm stop $name } "stop $name"
+    }
+    else {
+        Write-Host "  ($name not installed; skipping)" -ForegroundColor DarkGray
+    }
+}
+
+if (-not $WhatIf) {
+    Start-Sleep -Seconds 3
+    Get-Process MxGateway.Server, MxGateway.Worker, OtOpcUa.Server, OtOpcUa.Driver.Historian.Wonderware -ErrorAction SilentlyContinue |
+        ForEach-Object {
+            Write-Host "  killing residual process $($_.ProcessName) (PID=$($_.Id))" -ForegroundColor DarkYellow
+            Stop-Process -Id $_.Id -Force -ErrorAction SilentlyContinue
+        }
+}
+
+# ------------------------------------------------------------------------
+# Step 2: Backup existing C:\publish trees
+# ------------------------------------------------------------------------
+
+if (-not $SkipBackup -and (Test-Path $PublishRoot)) {
+    $backupRoot = Join-Path $PublishRoot ".backup-$((Get-Date).ToString('yyyy-MM-dd-HHmmss'))"
+    Step "Backing up $PublishRoot → $backupRoot"
+
+    Run {
+        New-Item -ItemType Directory -Path $backupRoot | Out-Null
+        foreach ($subdir in @('mxaccessgw', 'lmxopcua')) {
+            $src = Join-Path $PublishRoot $subdir
+            if (Test-Path $src) {
+                Copy-Item -Recurse -Path $src -Destination (Join-Path $backupRoot $subdir)
+            }
+        }
+    } "snapshot publish dirs (rollback target)"
+}
+else {
+    Write-Host "  (backup skipped)" -ForegroundColor DarkGray
+}
+
+# ------------------------------------------------------------------------
+# Step 3: Refresh mxaccessgw binaries (Track A output)
+# ------------------------------------------------------------------------
+
+Step "Building + copying mxaccessgw binaries from $GatewayRoot"
+
+Run {
+    & dotnet build "$GatewayRoot\src\MxGateway.Worker" -c Release | Out-Null
+    & dotnet build "$GatewayRoot\src\MxGateway.Server" -c Release | Out-Null
+} "dotnet build (Worker x86 net48 + Server net10.0)"
+
+Run {
+    $serverDest = Join-Path $PublishRoot "mxaccessgw\Server"
+    $workerDest = Join-Path $PublishRoot "mxaccessgw\Worker"
+    if (-not (Test-Path $serverDest)) { New-Item -ItemType Directory -Path $serverDest -Force | Out-Null }
+    if (-not (Test-Path $workerDest)) { New-Item -ItemType Directory -Path $workerDest -Force | Out-Null }
+    Copy-Item -Recurse -Force "$GatewayRoot\src\MxGateway.Server\bin\Release\net10.0\*" $serverDest
+    Copy-Item -Recurse -Force "$GatewayRoot\src\MxGateway.Worker\bin\x86\Release\net48\*" $workerDest
+} "copy gateway server + worker outputs"
+
+# ------------------------------------------------------------------------
+# Step 4: Refresh OtOpcUa + Wonderware historian sidecar
+# ------------------------------------------------------------------------
+
+Step "Publishing OtOpcUa server + Wonderware historian sidecar from $RepoRoot"
+
+Run {
+    & dotnet publish "$RepoRoot\src\ZB.MOM.WW.OtOpcUa.Server" `
+        -c Release -o (Join-Path $PublishRoot "lmxopcua") | Out-Null
+    & dotnet publish "$RepoRoot\src\ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware" `
+        -c Release -o (Join-Path $PublishRoot "lmxopcua\WonderwareHistorian") | Out-Null
+} "dotnet publish (Server + sidecar)"
+
+# ------------------------------------------------------------------------
+# Step 5: Service env block — ensure OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED
+# is set on the Wonderware historian service (PR C.2 toggle).
+# ------------------------------------------------------------------------
+
+if (Test-NssmService 'OtOpcUaWonderwareHistorian') {
+    Step "Ensuring OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED is set on the historian service"
+
+    Run {
+        $existing = nssm get OtOpcUaWonderwareHistorian AppEnvironmentExtra
+        if ($existing -notmatch 'OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED') {
+            $combined = $existing + "`r`nOTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=true"
+            nssm set OtOpcUaWonderwareHistorian AppEnvironmentExtra $combined | Out-Null
+            Write-Host "    appended OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=true" -ForegroundColor DarkGreen
+        }
+        else {
+            Write-Host "    already present; leaving service env block untouched"
+        }
+    } "patch service env block"
+}
+
+# ------------------------------------------------------------------------
+# Step 6: Start in forward dependency order
+# ------------------------------------------------------------------------
+
+Step "Starting services (MxAccessGw → OtOpcUaWonderwareHistorian → OtOpcUa)"
+
+foreach ($pair in @(
+    @{ Name = 'MxAccessGw';                  Wait = 4 },
+    @{ Name = 'OtOpcUaWonderwareHistorian';  Wait = 4 },
+    @{ Name = 'OtOpcUa';                     Wait = 8 }
+)) {
+    $name = $pair.Name
+    if (Test-NssmService $name) {
+        Run { nssm start $name } "start $name"
+        if (-not $WhatIf) { Start-Sleep -Seconds $pair.Wait }
+    }
+    else {
+        Write-Host "  ($name not installed; skipping)" -ForegroundColor DarkGray
+    }
+}
+
+# ------------------------------------------------------------------------
+# Step 7: Smoke verification
+# ------------------------------------------------------------------------
+
+Step "Smoke verification"
+
+if (-not $WhatIf) {
+    foreach ($name in @('MxAccessGw', 'OtOpcUaWonderwareHistorian', 'OtOpcUa')) {
+        if (Test-NssmService $name) {
+            $status = (Get-Service $name).Status
+            $color = if ($status -eq 'Running') { 'Green' } else { 'Red' }
+            Write-Host "  $name = $status" -ForegroundColor $color
+        }
+    }
+
+    foreach ($port in @(5120, 4840, 4841)) {
+        $listening = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
+        $color = if ($listening) { 'Green' } else { 'DarkYellow' }
+        Write-Host "  TCP $port listening = $($null -ne $listening)" -ForegroundColor $color
+    }
+
+    Write-Host ""
+    Write-Host "  Recent log tails:" -ForegroundColor DarkCyan
+    $tails = @(
+        "$PublishRoot\lmxopcua\logs\otopcua-*.log",
+        "$PublishRoot\mxaccessgw\stdout.log",
+        "$env:ProgramData\OtOpcUa\historian-wonderware-*.log"
+    )
+    foreach ($pattern in $tails) {
+        $latest = Get-ChildItem -Path $pattern -ErrorAction SilentlyContinue |
+            Sort-Object LastWriteTime -Descending |
+            Select-Object -First 1
+        if ($null -ne $latest) {
+            Write-Host ""
+            Write-Host "  --- $($latest.FullName) (last 10 lines) ---" -ForegroundColor DarkGray
+            Get-Content $latest.FullName -Tail 10 | ForEach-Object { Write-Host "    $_" }
+        }
+    }
+}
+
+Write-Host ""
+Write-Host "Refresh complete." -ForegroundColor Green
+Write-Host ""
+Write-Host "Next: run the functional verification scenarios from"
+Write-Host "  docs\plans\alarms-over-gateway.md §Track D §6 'Functional verification'"
+Write-Host "  - Galaxy-native alarm raise"
+Write-Host "  - Scripted alarm → AVEVA Historian round-trip"
+Write-Host "  - Sub-attribute fallback path with IAlarmSource disabled"

src/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/AlarmEventArgs.cs

@@ -15,7 +15,10 @@ public sealed class AlarmEventArgs : EventArgs
         bool ackedState,
         DateTime time,
         byte[]? eventId = null,
-        string? conditionNodeId = null)
+        string? conditionNodeId = null,
+        string? operatorComment = null,
+        DateTime? originalRaiseTimestampUtc = null,
+        string? alarmCategory = null)
     {
         SourceName = sourceName;
         ConditionName = conditionName;
@@ -27,6 +30,9 @@ public sealed class AlarmEventArgs : EventArgs
         Time = time;
         EventId = eventId;
         ConditionNodeId = conditionNodeId;
+        OperatorComment = operatorComment;
+        OriginalRaiseTimestampUtc = originalRaiseTimestampUtc;
+        AlarmCategory = alarmCategory;
     }
 
     /// <summary>The name of the source object that raised the alarm.</summary>
@@ -58,4 +64,25 @@ public sealed class AlarmEventArgs : EventArgs
 
     /// <summary>The NodeId of the condition instance (SourceNode), used for acknowledgment.</summary>
     public string? ConditionNodeId { get; }
+
+    /// <summary>
+    ///     PR E.7 — Operator-supplied comment recorded by the upstream alarm system on
+    ///     Acknowledge transitions. Null on raise / clear, or when the upstream path
+    ///     can't surface the comment (sub-attribute fallback path collapses comments
+    ///     into a single string write).
+    /// </summary>
+    public string? OperatorComment { get; }
+
+    /// <summary>
+    ///     PR E.7 — When the alarm originally entered the active state. Preserved
+    ///     across Acknowledge transitions so OPC UA Part 9 conditions keep the
+    ///     original raise time. Null when the upstream path doesn't surface it.
+    /// </summary>
+    public DateTime? OriginalRaiseTimestampUtc { get; }
+
+    /// <summary>
+    ///     PR E.7 — Upstream alarm taxonomy bucket (e.g. <c>Process</c> /
+    ///     <c>Safety</c> / <c>Diagnostics</c>). Null when not surfaced.
+    /// </summary>
+    public string? AlarmCategory { get; }
 }

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAlarmSource.cs

@@ -41,6 +41,30 @@ public sealed record AlarmAcknowledgeRequest(
     string? Comment);
 
 /// <summary>Event payload for <see cref="IAlarmSource.OnAlarmEvent"/>.</summary>
+/// <param name="SubscriptionHandle">Subscription this event belongs to.</param>
+/// <param name="SourceNodeId">Driver-side identifier for the alarm source.</param>
+/// <param name="ConditionId">Stable id correlating raise / ack / clear of the same condition.</param>
+/// <param name="AlarmType">Driver-defined alarm type name (e.g. AnalogLimitAlarm.HiHi).</param>
+/// <param name="Message">Human-readable alarm description.</param>
+/// <param name="Severity">Four-bucket severity ladder.</param>
+/// <param name="SourceTimestampUtc">When this transition occurred.</param>
+/// <param name="OperatorComment">
+///     Operator-supplied comment recorded by the upstream alarm system on Acknowledge
+///     transitions. Null on raise / clear, or when the upstream path can't surface
+///     the comment (the Galaxy sub-attribute fallback path collapses comments into a
+///     single string write — null on that path; the driver-native gateway path
+///     populates this).
+/// </param>
+/// <param name="OriginalRaiseTimestampUtc">
+///     When the alarm originally entered the active state. Preserved across
+///     Acknowledge transitions so OPC UA Part 9 conditions keep the original raise
+///     time in <c>Time</c>. Null when the upstream path doesn't surface it.
+/// </param>
+/// <param name="AlarmCategory">
+///     Upstream alarm taxonomy bucket (e.g. <c>Process</c> / <c>Safety</c> /
+///     <c>Diagnostics</c>). Maps to OPC UA <c>ConditionClassName</c> downstream when
+///     a class mapping is configured. Null when the upstream path doesn't carry it.
+/// </param>
 public sealed record AlarmEventArgs(
     IAlarmSubscriptionHandle SubscriptionHandle,
     string SourceNodeId,
@@ -48,7 +72,10 @@ public sealed record AlarmEventArgs(
     string AlarmType,
     string Message,
     AlarmSeverity Severity,
-    DateTime SourceTimestampUtc);
+    DateTime SourceTimestampUtc,
+    string? OperatorComment = null,
+    DateTime? OriginalRaiseTimestampUtc = null,
+    string? AlarmCategory = null);
 
 /// <summary>Mirrors the <c>NodePermissions</c> alarm-severity enum in <c>docs/v2/acl-design.md</c>.</summary>
 public enum AlarmSeverity { Low, Medium, High, Critical }

src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/GalaxyDriver.cs

@@ -837,7 +837,10 @@ public sealed class GalaxyDriver
             AlarmType: transition.AlarmTypeName,
             Message: transition.Description,
             Severity: transition.SeverityBucket,
-            SourceTimestampUtc: transition.TransitionTimestampUtc);
+            SourceTimestampUtc: transition.TransitionTimestampUtc,
+            OperatorComment: string.IsNullOrEmpty(transition.OperatorComment) ? null : transition.OperatorComment,
+            OriginalRaiseTimestampUtc: transition.OriginalRaiseTimestampUtc,
+            AlarmCategory: string.IsNullOrEmpty(transition.Category) ? null : transition.Category);
         try
         {
             OnAlarmEvent?.Invoke(this, args);

tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Tests/GalaxyDriverAlarmEventArgsExtensionTests.cs

@@ -0,0 +1,138 @@
+using System.Threading.Channels;
+using Google.Protobuf.WellKnownTypes;
+using MxGateway.Contracts.Proto;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;
+using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Runtime;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Tests;
+
+/// <summary>
+///     PR E.7 — pins that the GalaxyDriver populates the extended AlarmEventArgs
+///     fields (OperatorComment, OriginalRaiseTimestampUtc, AlarmCategory) when the
+///     gateway emits a transition with the rich payload, and leaves them null on
+///     events that don't carry them.
+/// </summary>
+public sealed class GalaxyDriverAlarmEventArgsExtensionTests
+{
+    [Fact]
+    public async Task Acknowledge_transition_with_full_payload_populates_extended_fields()
+    {
+        var subscriber = new ManualSubscriber();
+        using var driver = NewDriver(subscriber);
+
+        await driver.SubscribeAlarmsAsync(["Tank01"], CancellationToken.None);
+        var observed = new List<AlarmEventArgs>();
+        driver.OnAlarmEvent += (_, args) => observed.Add(args);
+        await driver.SubscribeAsync(["Tank01.Level"], TimeSpan.Zero, CancellationToken.None);
+
+        var raise = new DateTime(2026, 5, 1, 12, 0, 0, DateTimeKind.Utc);
+        var ack = raise.AddSeconds(45);
+        await subscriber.EmitAlarmAsync(new MxEvent
+        {
+            Family = MxEventFamily.OnAlarmTransition,
+            OnAlarmTransition = new OnAlarmTransitionEvent
+            {
+                AlarmFullReference = "Tank01.Level.HiHi",
+                SourceObjectReference = "Tank01",
+                AlarmTypeName = "AnalogLimitAlarm.HiHi",
+                TransitionKind = AlarmTransitionKind.Acknowledge,
+                Severity = 750,
+                OriginalRaiseTimestamp = Timestamp.FromDateTime(raise),
+                TransitionTimestamp = Timestamp.FromDateTime(ack),
+                OperatorUser = "alice",
+                OperatorComment = "investigating",
+                Category = "Process",
+                Description = "Tank 01 high-high level",
+            },
+        });
+
+        for (var i = 0; i < 20 && observed.Count == 0; i++)
+        {
+            await Task.Delay(50);
+        }
+        observed.ShouldHaveSingleItem();
+        observed[0].OperatorComment.ShouldBe("investigating");
+        observed[0].OriginalRaiseTimestampUtc.ShouldBe(raise);
+        observed[0].AlarmCategory.ShouldBe("Process");
+    }
+
+    [Fact]
+    public async Task Raise_transition_without_optional_fields_leaves_them_null()
+    {
+        var subscriber = new ManualSubscriber();
+        using var driver = NewDriver(subscriber);
+
+        await driver.SubscribeAlarmsAsync(["Tank01"], CancellationToken.None);
+        var observed = new List<AlarmEventArgs>();
+        driver.OnAlarmEvent += (_, args) => observed.Add(args);
+        await driver.SubscribeAsync(["Tank01.Level"], TimeSpan.Zero, CancellationToken.None);
+
+        await subscriber.EmitAlarmAsync(new MxEvent
+        {
+            Family = MxEventFamily.OnAlarmTransition,
+            OnAlarmTransition = new OnAlarmTransitionEvent
+            {
+                AlarmFullReference = "Tank01.Level.HiHi",
+                AlarmTypeName = "AnalogLimitAlarm.HiHi",
+                TransitionKind = AlarmTransitionKind.Raise,
+                Severity = 750,
+                TransitionTimestamp = Timestamp.FromDateTime(DateTime.UtcNow),
+            },
+        });
+
+        for (var i = 0; i < 20 && observed.Count == 0; i++)
+        {
+            await Task.Delay(50);
+        }
+        observed.ShouldHaveSingleItem();
+        observed[0].OperatorComment.ShouldBeNull();
+        observed[0].OriginalRaiseTimestampUtc.ShouldBeNull();
+        observed[0].AlarmCategory.ShouldBeNull();
+    }
+
+    private static GalaxyDriver NewDriver(ManualSubscriber subscriber)
+    {
+        var options = new GalaxyDriverOptions(
+            new GalaxyGatewayOptions("http://localhost:5000", "literal-api-key"),
+            new GalaxyMxAccessOptions("AlarmExtensionTest"),
+            new GalaxyRepositoryOptions(),
+            new GalaxyReconnectOptions());
+        return new GalaxyDriver(
+            driverInstanceId: "drv-1",
+            options: options,
+            hierarchySource: null,
+            dataReader: null,
+            dataWriter: null,
+            subscriber: subscriber,
+            alarmAcknowledger: null);
+    }
+
+    private sealed class ManualSubscriber : IGalaxySubscriber
+    {
+        private readonly Channel<MxEvent> _stream =
+            Channel.CreateUnbounded<MxEvent>(new UnboundedChannelOptions { SingleReader = true });
+
+        public Task<IReadOnlyList<SubscribeResult>> SubscribeBulkAsync(
+            IReadOnlyList<string> fullReferences, int bufferedUpdateIntervalMs, CancellationToken cancellationToken)
+        {
+            var results = new List<SubscribeResult>();
+            var nextHandle = 100;
+            foreach (var r in fullReferences)
+            {
+                results.Add(new SubscribeResult { TagAddress = r, ItemHandle = nextHandle++, WasSuccessful = true });
+            }
+            return Task.FromResult<IReadOnlyList<SubscribeResult>>(results);
+        }
+
+        public Task UnsubscribeBulkAsync(IReadOnlyList<int> itemHandles, CancellationToken cancellationToken)
+            => Task.CompletedTask;
+
+        public IAsyncEnumerable<MxEvent> StreamEventsAsync(CancellationToken cancellationToken)
+            => _stream.Reader.ReadAllAsync(cancellationToken);
+
+        public ValueTask EmitAlarmAsync(MxEvent ev) => _stream.Writer.WriteAsync(ev);
+    }
+}