refactor(battle-node): scripted bot drives the handshake as a real participant

Implements IHasHandshakePhase and emits client-shaped InitNetwork/InitBattle/
Loaded/Swap (reacting to the session's pushes) instead of being a passive
TurnEnd-only fixture the session narrates around. This is what lets the
type-agnostic mulligan barrier (next task) work in Scripted mode.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

SVSim.BattleNode/Sessions/Participants/ScriptedBotParticipant.cs

@@ -6,11 +6,14 @@ using SVSim.BattleNode.Protocol;
 namespace SVSim.BattleNode.Sessions.Participants;
 
 /// <summary>
-/// Server-scripted opponent (today's v1.2 testing-harness behavior, repackaged).
+/// Server-scripted opponent that drives a client-shaped emit chain so the session brokers
-/// On <see cref="PushAsync"/> with <c>TurnEnd</c> or <c>TurnEndFinal</c>, fires
+/// it through the same handshake arms as a human. <see cref="RunAsync"/> kicks off
-/// <see cref="FrameEmitted"/> three times: <c>OpponentTurnStart</c>,
+/// <c>InitNetwork</c>; the session's pushes then drive <see cref="PushAsync"/> reactively:
-/// <c>OpponentTurnEnd</c>, <c>OpponentJudge</c>. All other URIs are swallowed
+/// <c>InitNetwork</c>(ack)→<c>InitBattle</c>, <c>Matched</c>→<c>Loaded</c>, <c>Deal</c>→<c>Swap</c>
-/// (no opponent reaction needed for v1.2 behavior).
+/// (empty mulligan). After the player's <c>TurnEnd</c> it fires the v1.2 three-frame burst
+/// (<c>OpponentTurnStart</c>, <c>OpponentTurnEnd</c>, <c>OpponentJudge</c>). All other URIs
+/// are swallowed. Implementing <see cref="IHasHandshakePhase"/> is what makes the session
+/// treat it as a real handshake participant (mulligan-barrier swapper included).
 /// </summary>
 /// <remarks>
 /// ViewerId, Context are fixtures matching <see cref="ScriptedLifecycle.FakeOpponentViewerId"/>
@@ -19,9 +22,10 @@ namespace SVSim.BattleNode.Sessions.Participants;
 /// <see cref="BattleSession.ComputeFrames"/> reads <c>other.Context</c> for those frames.
 /// Deal still uses fixed scripted frames that ignore Context.
 /// </remarks>
-public sealed class ScriptedBotParticipant : IBattleParticipant
+public sealed class ScriptedBotParticipant : IBattleParticipant, IHasHandshakePhase
 {
     public long ViewerId => ScriptedLifecycle.FakeOpponentViewerId;
+
     public MatchContext Context { get; } = new(
         // 30 dummy card ids so oppoCtx.SelfDeckCardIds.Count == 30 — prod frame[2] (Matched)
         // shipped OppoDeckCount: 30.
@@ -33,24 +37,43 @@ public sealed class ScriptedBotParticipant : IBattleParticipant
         EmblemId: "400001100", DegreeId: "120027", FieldId: 5, IsOfficial: 0,
         BattleType: 0);
 
+    // Session reads/advances this through its phase-gated handshake arms, exactly as it
+    // does for a RealParticipant. The bot doesn't read it — it reacts to pushed URIs —
+    // but implementing IHasHandshakePhase is what makes the session treat the bot as a
+    // real handshake participant (so its InitNetwork/InitBattle/Loaded/Swap emissions are
+    // processed, and the mulligan barrier counts it as a swapper).
+    public BattleSessionPhase Phase { get; set; } = BattleSessionPhase.AwaitingInitNetwork;
+
     public event Func<MsgEnvelope, CancellationToken, Task>? FrameEmitted;
 
+    // Kick off the handshake like a connecting client. The session acks InitNetwork,
+    // which drives PushAsync below through InitBattle → Loaded → Swap.
+    public Task RunAsync(CancellationToken ct) => EmitAsync(ScriptedLifecycle.BuildClientInitNetwork(), ct);
+
     public async Task PushAsync(MsgEnvelope envelope, bool noStock, CancellationToken ct)
     {
-        // React to the player's TurnEnd with the three-frame burst (TurnStart / TurnEnd /
+        switch (envelope.Uri)
-        // Judge) — that's the v1.2 "scripted bot takes its turn" behavior. Everything else
-        // (including TurnEndFinal) is silently swallowed: TurnEndFinal is the player's
-        // game-end signal and is handled directly by the BattleSession dispatch arm, which
-        // pushes BattleFinish per-side; the bot doesn't need to react.
-        if (envelope.Uri is NetworkBattleUri.TurnEnd)
         {
-            await EmitAsync(ScriptedLifecycle.BuildOpponentTurnStart(), ct).ConfigureAwait(false);
+            case NetworkBattleUri.InitNetwork: // the ack
-            await EmitAsync(ScriptedLifecycle.BuildOpponentTurnEnd(), ct).ConfigureAwait(false);
+                await EmitAsync(ScriptedLifecycle.BuildClientInitBattle(), ct).ConfigureAwait(false);
-            await EmitAsync(ScriptedLifecycle.BuildOpponentJudge(), ct).ConfigureAwait(false);
+                break;
+            case NetworkBattleUri.Matched:
+                await EmitAsync(ScriptedLifecycle.BuildClientLoaded(), ct).ConfigureAwait(false);
+                break;
+            case NetworkBattleUri.Deal:
+                await EmitAsync(ScriptedLifecycle.BuildClientSwap(), ct).ConfigureAwait(false);
+                break;
+            case NetworkBattleUri.TurnEnd:
+                // v1.2 scripted-turn burst, taken AFTER the player's turn (bot is second).
+                await EmitAsync(ScriptedLifecycle.BuildOpponentTurnStart(), ct).ConfigureAwait(false);
+                await EmitAsync(ScriptedLifecycle.BuildOpponentTurnEnd(), ct).ConfigureAwait(false);
+                await EmitAsync(ScriptedLifecycle.BuildOpponentJudge(), ct).ConfigureAwait(false);
+                break;
+            // Everything else (BattleStart, our own Swap-response, Ready, TurnEndFinal,
+            // Judge, BattleFinish, …) needs no bot reaction.
         }
     }
 
-    public Task RunAsync(CancellationToken ct) => Task.CompletedTask;
     public Task TerminateAsync(BattleFinishReason reason) => Task.CompletedTask;
     public ValueTask DisposeAsync() => ValueTask.CompletedTask;
 

SVSim.UnitTests/BattleNode/Sessions/Participants/ScriptedBotParticipantTests.cs

@@ -1,5 +1,5 @@
 using NUnit.Framework;
-using SVSim.BattleNode.Bridge;
+using SVSim.BattleNode.Lifecycle;
 using SVSim.BattleNode.Protocol;
 using SVSim.BattleNode.Protocol.Bodies;
 using SVSim.BattleNode.Sessions;
@@ -10,6 +10,33 @@ namespace SVSim.UnitTests.BattleNode.Sessions.Participants;
 [TestFixture]
 public class ScriptedBotParticipantTests
 {
+    [Test]
+    public async Task RunAsync_emits_InitNetwork_to_kick_off_handshake()
+    {
+        var p = new ScriptedBotParticipant();
+        var emitted = new List<NetworkBattleUri>();
+        p.FrameEmitted += (env, _) => { emitted.Add(env.Uri); return Task.CompletedTask; };
+
+        await p.RunAsync(CancellationToken.None);
+
+        Assert.That(emitted, Is.EqualTo(new[] { NetworkBattleUri.InitNetwork }));
+    }
+
+    [TestCase(NetworkBattleUri.InitNetwork, NetworkBattleUri.InitBattle)]
+    [TestCase(NetworkBattleUri.Matched, NetworkBattleUri.Loaded)]
+    [TestCase(NetworkBattleUri.Deal, NetworkBattleUri.Swap)]
+    public async Task PushAsync_handshake_push_emits_next_client_frame(
+        NetworkBattleUri pushed, NetworkBattleUri expectedEmit)
+    {
+        var p = new ScriptedBotParticipant();
+        var emitted = new List<NetworkBattleUri>();
+        p.FrameEmitted += (env, _) => { emitted.Add(env.Uri); return Task.CompletedTask; };
+
+        await p.PushAsync(NewEnvelope(pushed), noStock: false, CancellationToken.None);
+
+        Assert.That(emitted, Is.EqualTo(new[] { expectedEmit }));
+    }
+
     [Test]
     public async Task PushAsync_TurnEnd_fires_three_FrameEmitted_in_order()
     {
@@ -21,31 +48,12 @@ public class ScriptedBotParticipantTests
 
         Assert.That(emitted, Is.EqualTo(new[]
         {
-            NetworkBattleUri.TurnStart,
+            NetworkBattleUri.TurnStart, NetworkBattleUri.TurnEnd, NetworkBattleUri.Judge,
-            NetworkBattleUri.TurnEnd,
-            NetworkBattleUri.Judge,
         }));
     }
 
     [Test]
-    public async Task PushAsync_TurnEndFinal_does_NOT_fire_burst()
+    public async Task PushAsync_non_reactive_uris_emit_nothing()
-    {
-        // TurnEndFinal is the game-end signal — owned by BattleSession's TurnEndFinal
-        // dispatch arm, which pushes BattleFinish per-side. The bot no longer reacts to
-        // it; reacting would race the BattleFinish with the no-longer-needed 3-frame
-        // burst. Only regular TurnEnd triggers the burst.
-        var p = new ScriptedBotParticipant();
-        var fired = 0;
-        p.FrameEmitted += (_, _) => { fired++; return Task.CompletedTask; };
-
-        await p.PushAsync(NewEnvelope(NetworkBattleUri.TurnEndFinal), noStock: false, CancellationToken.None);
-
-        Assert.That(fired, Is.EqualTo(0),
-            "TurnEndFinal must not trigger the bot's burst — the dispatch arm pushes BattleFinish directly.");
-    }
-
-    [Test]
-    public async Task PushAsync_other_uris_do_not_fire()
     {
         var p = new ScriptedBotParticipant();
         var fired = 0;
@@ -53,10 +61,9 @@ public class ScriptedBotParticipantTests
 
         foreach (var uri in new[]
         {
-            NetworkBattleUri.Matched, NetworkBattleUri.BattleStart, NetworkBattleUri.Deal,
+            NetworkBattleUri.BattleStart, NetworkBattleUri.Swap, NetworkBattleUri.Ready,
-            NetworkBattleUri.Swap, NetworkBattleUri.Ready, NetworkBattleUri.PlayActions,
+            NetworkBattleUri.PlayActions, NetworkBattleUri.TurnStart, NetworkBattleUri.Echo,
-            NetworkBattleUri.TurnStart, NetworkBattleUri.TurnEndActions, NetworkBattleUri.Echo,
+            NetworkBattleUri.Judge, NetworkBattleUri.BattleFinish, NetworkBattleUri.TurnEndFinal,
-            NetworkBattleUri.Judge, NetworkBattleUri.BattleFinish,
         })
         {
             await p.PushAsync(NewEnvelope(uri), noStock: false, CancellationToken.None);
@@ -66,11 +73,11 @@ public class ScriptedBotParticipantTests
     }
 
     [Test]
-    public async Task RunAsync_returns_immediately()
+    public void Implements_IHasHandshakePhase_starting_at_AwaitingInitNetwork()
     {
         var p = new ScriptedBotParticipant();
-        await p.RunAsync(CancellationToken.None);
+        Assert.That(p, Is.InstanceOf<IHasHandshakePhase>());
-        Assert.Pass();
+        Assert.That(((IHasHandshakePhase)p).Phase, Is.EqualTo(BattleSessionPhase.AwaitingInitNetwork));
     }
 
     private static MsgEnvelope NewEnvelope(NetworkBattleUri uri) =>