feat(worker): surface the handoff round budget in the merge-helper handoff brief

A handler session only learned the chain was capped when handoff_list_handler
threw at the end of its work, stranding open tasks. The round count already
lived in HandoffRoundTracker the whole time -- it just never reached the
brief. InteractiveLaunchSpecService now reads HandoffRoundTracker.GetState
(read-only, doesn't advance the round) and renders round N of MaxHandoffs
plus the remaining count into the handoff brief, replacing the old one-line
finalNote. The rejection error also names the next action (start a new
handler run) instead of just failing.

tests/ClaudeDo.Worker.Tests/External/HandoffMcpToolsTests.cs

@@ -198,6 +198,63 @@ public sealed class HandoffMcpToolsTests : IDisposable
             secondSut.HandoffListHandler(handlerTask.Id, survivors, "wait", CancellationToken.None));
     }
 
+    [Theory]
+    [InlineData(1, 3)]
+    [InlineData(2, 2)]
+    [InlineData(4, 0)]
+    public void HandoffRoundTracker_GetState_ReportsCountAfterNRegistrations(int registrations, int expectedRemaining)
+    {
+        var tracker = new HandoffRoundTracker();
+        var taskId = Guid.NewGuid().ToString();
+
+        for (var i = 0; i < registrations; i++)
+            tracker.Register(taskId, "wait");
+
+        var (count, sealedState) = tracker.GetState(taskId);
+        Assert.Equal(registrations, count);
+        Assert.Equal(expectedRemaining, HandoffRoundTracker.MaxHandoffs - count);
+        Assert.False(sealedState);
+    }
+
+    [Fact]
+    public void HandoffRoundTracker_GetState_UnregisteredTask_ReturnsZero()
+    {
+        var tracker = new HandoffRoundTracker();
+        var (count, sealedState) = tracker.GetState(Guid.NewGuid().ToString());
+        Assert.Equal(0, count);
+        Assert.False(sealedState);
+    }
+
+    [Fact]
+    public void HandoffRoundTracker_Register_DoesNotMutateStateVisibleFromGetState_BeyondItsOwnCall()
+    {
+        var tracker = new HandoffRoundTracker();
+        var taskId = Guid.NewGuid().ToString();
+
+        tracker.Register(taskId, "wait");
+        var (beforeCount, _) = tracker.GetState(taskId);
+        Assert.Equal(1, beforeCount);
+
+        // GetState itself must be read-only -- calling it repeatedly must not advance the round.
+        tracker.GetState(taskId);
+        tracker.GetState(taskId);
+        var (afterCount, _) = tracker.GetState(taskId);
+        Assert.Equal(beforeCount, afterCount);
+    }
+
+    [Fact]
+    public void HandoffRoundTracker_RejectedHandoff_ErrorNamesTheNextAction()
+    {
+        var tracker = new HandoffRoundTracker();
+        var taskId = Guid.NewGuid().ToString();
+        tracker.Register(taskId, "merge_final");
+
+        var result = tracker.Register(taskId, "wait");
+
+        Assert.True(result.Rejected);
+        Assert.Contains("new handler run", result.Error, StringComparison.OrdinalIgnoreCase);
+    }
+
     [Fact]
     public async Task HandoffListHandler_TwoHandlerTasks_DoNotShareACounter()
     {

tests/ClaudeDo.Worker.Tests/Hub/MergeHelperTaskHubTests.cs

@@ -64,7 +64,7 @@ public sealed class MergeHelperTaskHubTests : IDisposable
         var wtManager = new WorktreeManager(git, factory, new WorkerConfig(), NullLogger<WorktreeManager>.Instance);
         var interactiveLaunchSpec = new InteractiveLaunchSpecService(
             factory, new FakeSessionSkillSeeder(), new FakeSessionSkillRegistry(), wtManager, git,
-            new WorkerConfig { ClaudeBin = "claude" });
+            new WorkerConfig { ClaudeBin = "claude" }, new ClaudeDo.Worker.External.HandoffRoundTracker());
         var built = TaskStateServiceBuilder.Build(factory);
         var reviewSubmission = new InteractiveReviewSubmissionService(factory, git, built.State, wtManager);
 

tests/ClaudeDo.Worker.Tests/Runner/InteractiveLaunchSpecServiceTests.cs

@@ -3,6 +3,7 @@ using ClaudeDo.Data.Git;
 using ClaudeDo.Data.Models;
 using ClaudeDo.Data.Repositories;
 using ClaudeDo.Worker.Config;
+using ClaudeDo.Worker.External;
 using ClaudeDo.Worker.Planning;
 using ClaudeDo.Worker.Runner;
 using ClaudeDo.Worker.Skills;
@@ -72,11 +73,12 @@ public sealed class InteractiveLaunchSpecServiceTests : IDisposable
             => Task.FromResult<IReadOnlyList<SessionSkillEntity>>(Installed);
     }
 
-    private InteractiveLaunchSpecService BuildService() =>
+    private InteractiveLaunchSpecService BuildService(HandoffRoundTracker? handoffRounds = null) =>
         new(_db.CreateFactory(), _seeder, _registry,
             new WorktreeManager(new GitService(), _db.CreateFactory(), new WorkerConfig(), NullLogger<WorktreeManager>.Instance),
             new GitService(),
-            new WorkerConfig { ClaudeBin = _claudeStubPath });
+            new WorkerConfig { ClaudeBin = _claudeStubPath },
+            handoffRounds ?? new HandoffRoundTracker());
 
     private async Task<string> SeedListAsync(string? workingDir = null, string name = "L")
     {
@@ -1043,7 +1045,13 @@ public sealed class InteractiveLaunchSpecServiceTests : IDisposable
 
         var beforeCount = await CountTasksAsync();
 
-        var svc = BuildService();
+        // In production, HandoffMcpTools.HandoffListHandler calls Register BEFORE the hub asks
+        // this service to build the spec -- simulate that here so the brief's round info is
+        // demonstrably read from HandoffRoundTracker, not recomputed.
+        var tracker = new HandoffRoundTracker();
+        tracker.Register(handlerTaskId, nextPhase);
+
+        var svc = BuildService(tracker);
         var spec = await svc.BuildForMergeHelperHandoffAsync(handlerTaskId, new[] { survivor }, nextPhase, CancellationToken.None);
         var sessionDir = TrackSessionDir(spec);
 
@@ -1090,6 +1098,10 @@ public sealed class InteractiveLaunchSpecServiceTests : IDisposable
         Assert.Contains(survivor, handoffBrief);
         Assert.Contains("phase 3", handoffBrief, StringComparison.OrdinalIgnoreCase);
 
+        // Round info always names the current round and the total cap -- this is the ONE
+        // Register call above, so round 1 of MaxHandoffs.
+        Assert.Contains($"round 1 of {HandoffRoundTracker.MaxHandoffs}", handoffBrief);
+
         if (expectFinalNote)
         {
             Assert.Contains("FINAL round", handoffBrief);