feat(testrun): route WaitForAttribute in the Test-Run sandbox (deferred #14)

Closes deferred-work register item #14 with full fidelity. The Central UI Test-Run
sandbox previously threw ScriptSandboxException for Attributes.WaitAsync/WaitForAsync;
now the value-equality forms route to the bound deployed instance over the same
cross-site path inbound Route.To().WaitForAttribute() uses.

- Commons: additive trailing RouteToWaitForAttributeRequest.RequireGoodQuality
  (default false; message-evolution safe) so quality-gated waits route too.
- SiteRuntime: DeploymentManagerActor's routed-wait handler now threads
  request.RequireGoodQuality into the InstanceActor WaitForAttributeRequest
  (previously hard-coded to default).
- CentralUI sandbox: ISandboxInstanceGateway.WaitForAttributeAsync +
  SandboxInstanceGateway impl (via CommunicationService.RouteToWaitForAttributeAsync);
  SandboxAttributeAccessor value-equality WaitAsync/WaitForAsync route through it
  (codec-encoded target, scope-resolved name). Predicate overloads stay unsupported
  (an in-process lambda can't be routed) and throw a clearer, dedicated message.
- Tests: sandbox accessor routing + predicate/unbound rejection (CentralUI);
  site-handler RequireGoodQuality threading (SiteRuntime). Register + the historical
  waitfor-deferred plan doc updated.

Full slnx build 0/0; CentralUI 59, SiteRuntime routed-wait 4, InboundAPI wait 32 green.

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj

tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/ScriptAnalysis/SandboxWaitForAttributeTests.cs

@@ -0,0 +1,80 @@
+using NSubstitute;
+using ZB.MOM.WW.ScadaBridge.CentralUI.ScriptAnalysis;
+using ZB.MOM.WW.ScadaBridge.Commons.Types;
+
+namespace ZB.MOM.WW.ScadaBridge.CentralUI.Tests.ScriptAnalysis;
+
+/// <summary>
+/// Deferred-work #14 (full fidelity): the Test-Run sandbox routes value-equality
+/// <c>WaitAsync</c>/<c>WaitForAsync</c> to the bound instance via
+/// <see cref="ISandboxInstanceGateway"/>; predicate overloads and unbound runs still
+/// throw a clearly-labelled <see cref="ScriptSandboxException"/>.
+/// </summary>
+public class SandboxWaitForAttributeTests
+{
+    private static SandboxAttributeAccessor BoundAccessor(ISandboxInstanceGateway gateway) =>
+        new(new SandboxInstanceContext(gateway), prefix: string.Empty);
+
+    [Fact]
+    public async Task WaitAsync_ValueForm_RoutesThroughGateway_AndReturnsMatched()
+    {
+        var gateway = Substitute.For<ISandboxInstanceGateway>();
+        gateway.WaitForAttributeAsync("Flag", Arg.Any<string?>(), Arg.Any<TimeSpan>(), false, Arg.Any<CancellationToken>())
+            .Returns(new WaitResult(true, true, "Good", false));
+        var accessor = BoundAccessor(gateway);
+
+        var matched = await accessor.WaitAsync("Flag", true, TimeSpan.FromSeconds(5));
+
+        Assert.True(matched);
+        // The target is codec-encoded and the resolved (root-scope) name is passed through.
+        await gateway.Received(1).WaitForAttributeAsync(
+            "Flag", AttributeValueCodec.Encode(true), TimeSpan.FromSeconds(5), false, Arg.Any<CancellationToken>());
+    }
+
+    [Fact]
+    public async Task WaitForAsync_ValueForm_PassesRequireGoodQuality_AndReturnsFullResult()
+    {
+        var gateway = Substitute.For<ISandboxInstanceGateway>();
+        gateway.WaitForAttributeAsync("Done", Arg.Any<string?>(), Arg.Any<TimeSpan>(), true, Arg.Any<CancellationToken>())
+            .Returns(new WaitResult(true, 7, "Good", false));
+        var accessor = BoundAccessor(gateway);
+
+        var result = await accessor.WaitForAsync("Done", 7, TimeSpan.FromSeconds(3), requireGoodQuality: true);
+
+        Assert.True(result.Matched);
+        Assert.Equal(7, result.Value);
+        Assert.Equal("Good", result.Quality);
+        await gateway.Received(1).WaitForAttributeAsync(
+            "Done", AttributeValueCodec.Encode(7), TimeSpan.FromSeconds(3), true, Arg.Any<CancellationToken>());
+    }
+
+    [Fact]
+    public async Task WaitAsync_PredicateForm_Throws()
+    {
+        var accessor = BoundAccessor(Substitute.For<ISandboxInstanceGateway>());
+
+        var ex = await Assert.ThrowsAsync<ScriptSandboxException>(
+            () => accessor.WaitAsync("Done", v => v != null, TimeSpan.FromSeconds(1)));
+        Assert.Contains("predicate", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task WaitForAsync_PredicateForm_Throws()
+    {
+        var accessor = BoundAccessor(Substitute.For<ISandboxInstanceGateway>());
+
+        await Assert.ThrowsAsync<ScriptSandboxException>(
+            () => accessor.WaitForAsync("Done", v => v != null, TimeSpan.FromSeconds(1)));
+    }
+
+    [Fact]
+    public async Task WaitAsync_ValueForm_UnboundInstance_Throws()
+    {
+        // No gateway bound → the sandbox has no instance to route to.
+        var accessor = new SandboxAttributeAccessor(new SandboxInstanceContext(), prefix: string.Empty);
+
+        var ex = await Assert.ThrowsAsync<ScriptSandboxException>(
+            () => accessor.WaitAsync("Flag", true, TimeSpan.FromSeconds(1)));
+        Assert.Contains("deployed instance", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+}

tests/ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests/Actors/DeploymentManagerActorTests.cs

@@ -551,6 +551,35 @@ public class DeploymentManagerActorTests : TestKit, IDisposable
         Assert.Equal("Good", response.Quality);
     }
 
+    [Fact]
+    public async Task RouteInboundApiWaitForAttribute_RequireGoodQuality_IsThreadedToInstanceActor()
+    {
+        // #14 (full fidelity): the additive RouteToWaitForAttributeRequest.RequireGoodQuality
+        // flag must reach the InstanceActor's wait. A static attribute is Good quality, so a
+        // quality-gated wait whose target equals the current value still matches — proving the
+        // flag threads through (and does not spuriously reject a Good value).
+        var actor = CreateDeploymentManager();
+        await Task.Delay(500);
+
+        actor.Tell(new DeployInstanceCommand(
+            "dep-wait-gq", "WaitPumpGq", "sha256:wait-gq",
+            MakeConfigJson("WaitPumpGq"), "admin", DateTimeOffset.UtcNow));
+        ExpectMsg<DeploymentStatusResponse>(TimeSpan.FromSeconds(5));
+        await Task.Delay(1000);
+
+        var encodedTarget = AttributeValueCodec.Encode("42");
+        actor.Tell(new RouteToWaitForAttributeRequest(
+            "wait-corr-gq", "WaitPumpGq", "TestAttr", encodedTarget,
+            TimeSpan.FromSeconds(5), DateTimeOffset.UtcNow,
+            ParentExecutionId: null, RequireGoodQuality: true));
+
+        var response = ExpectMsg<RouteToWaitForAttributeResponse>(TimeSpan.FromSeconds(10));
+        Assert.Equal("wait-corr-gq", response.CorrelationId);
+        Assert.True(response.Success, $"Routed quality-gated wait failed: {response.ErrorMessage}");
+        Assert.True(response.Matched, "A Good-quality attribute at target must satisfy a RequireGoodQuality wait.");
+        Assert.Equal("Good", response.Quality);
+    }
+
     [Fact]
     public async Task RouteInboundApiWaitForAttribute_UnknownInstance_RepliesNotFound()
     {