Merge branch 'claudedo/f2f0c6ee1e974c09bc8a8261978cba34'

feat(worker): Handler-Session vor dem Usage-Limit sauber uebergeben (#275); Konflikte mit start_list_handler aufgeloest, WorkerLog-Aufruf im Fire-and-forget-Pfad wieder abgesichert

src/ClaudeDo.Localization/locales/de.json

@@ -338,6 +338,7 @@
     "closeSession": "Sitzung beenden",
     "conptyLaunchFailed": "Interaktive Sitzung konnte nicht geöffnet werden: {0}",
     "conptyStarting": "Sitzung wird gestartet…",
+    "usageWarningNotDelivered": "Die Listen-Handler-Sitzung konnte nicht vor dem Usage-Limit gewarnt werden.",
     "mergeHelperTitle": "Merge-Helfer",
     "mergeHelperHandoffTitleSuffix": " (Übergabe)",
     "mergeHelperTaskTitle": "Listen-Handler: {0}",

src/ClaudeDo.Localization/locales/en.json

@@ -338,6 +338,7 @@
     "closeSession": "Kill session",
     "conptyLaunchFailed": "Couldn't open interactive session: {0}",
     "conptyStarting": "Starting session…",
+    "usageWarningNotDelivered": "Couldn't warn the list-handler session about the usage limit.",
     "mergeHelperTitle": "Merge Helper",
     "mergeHelperHandoffTitleSuffix": " (Handoff)",
     "mergeHelperTaskTitle": "List handler: {0}",

src/ClaudeDo.Ui/Services/Interfaces/IWorkerClient.cs

@@ -33,6 +33,10 @@ public interface IWorkerClient : INotifyPropertyChanged
     /// <summary>start_list_handler was called through the external MCP: (listId, taskIds). The UI
     /// starts a list-handler run for them exactly like the "Let Claude handle it" button.</summary>
     event Action<string, IReadOnlyList<string>>? ListHandlerStartRequestedEvent;
+    /// <summary>The 5h usage window is running out under a running list-handler session:
+    /// (handlerTaskId, message). Mission Control types the message into that task's ConPTY pane so
+    /// the session can hand off cleanly; no pane for the task means nothing happens.</summary>
+    event Action<string, string>? HandlerUsageWarningEvent;
 
     /// <summary>An agent added a note through the MCP tool — an open notes editor reloads.</summary>
     event Action? NotesUpdatedEvent;

src/ClaudeDo.Ui/Services/PtyTerminalSession.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Reflection;
 using System.Threading;
 using System.Threading.Tasks;
 using Iciclecreek.Terminal;
@@ -93,6 +94,56 @@ public sealed class PtyTerminalSession : IDisposable
         ProcessExited?.Invoke(this, e.ExitCode);
     }
 
+    /// <summary>
+    /// Types <paramref name="text"/> into the running session and submits it, exactly as if the user
+    /// had typed it — used to warn a list-handler session before the usage limit
+    /// (<c>HandlerUsageWarning</c>). Verified against a real `claude` TUI, including while it was
+    /// mid-turn (the message is queued and acted on when the turn ends).
+    ///
+    /// Three non-obvious details, all established by that spike:
+    /// • <see cref="TerminalControl"/> exposes no public write path at all — its only public paste is
+    ///   <c>TerminalView.PasteAsync()</c>, which takes no argument and reads the clipboard. The
+    ///   private <c>SendToPtyAsync</c> on the inner view is the write seam, hence the reflection.
+    /// • The text and the Enter must be TWO writes. A single <c>text + "\r"</c> chunk lands in
+    ///   claude's composer but is never submitted — a chunk carrying an embedded CR reads as pasted
+    ///   text, not as a keypress.
+    /// • The Enter bytes come from the emulator (<c>GenerateKeyInput</c>) rather than a literal
+    ///   "\r", because claude turns Win32 input mode on and the emulator owns that encoding.
+    ///
+    /// Best-effort by design: a package upgrade that renames the private member costs a warning that
+    /// never arrives, never a crashed Mission Control.
+    /// </summary>
+    public async Task<bool> SendLineAsync(string text)
+    {
+        if (_control is not { } control || !IsRunning || string.IsNullOrEmpty(text)) return false;
+        try
+        {
+            await SendRawAsync(control, text);
+            await Task.Delay(SubmitDelay);
+            await SendRawAsync(control, control.Terminal.GenerateKeyInput(XTerm.Input.Key.Enter, XTerm.Input.KeyModifiers.None));
+            return true;
+        }
+        catch (Exception)
+        {
+            return false;
+        }
+    }
+
+    // Long enough that the two writes can't be read as one chunk by the child's stdin reader.
+    private static readonly TimeSpan SubmitDelay = TimeSpan.FromMilliseconds(150);
+
+    private static readonly FieldInfo? s_terminalViewField =
+        typeof(TerminalControl).GetField("_terminalView", BindingFlags.Instance | BindingFlags.NonPublic);
+    private static readonly MethodInfo? s_sendToPty =
+        typeof(TerminalView).GetMethod("SendToPtyAsync", BindingFlags.Instance | BindingFlags.NonPublic);
+
+    private static Task SendRawAsync(TerminalControl control, string data)
+    {
+        if (s_terminalViewField?.GetValue(control) is not TerminalView view || s_sendToPty is null)
+            throw new InvalidOperationException("Iciclecreek.Avalonia.Terminal no longer exposes a PTY write seam.");
+        return (Task)s_sendToPty.Invoke(view, new object[] { data, CancellationToken.None })!;
+    }
+
     public void Kill()
     {
         try { _control?.Kill(); }

src/ClaudeDo.Ui/Services/WorkerClient.cs

@@ -50,6 +50,7 @@ public partial class WorkerClient : ObservableObject, IAsyncDisposable, IWorkerC
     public event Action<string, string>? TaskQuestionResolvedEvent;
     public event Action<string, IReadOnlyList<string>, string>? HandoffRequestedEvent;
     public event Action<string, IReadOnlyList<string>>? ListHandlerStartRequestedEvent;
+    public event Action<string, string>? HandlerUsageWarningEvent;
     public event Action? ConnectionRestoredEvent;
     public event Action<string>? WorktreeUpdatedEvent;
     public event Action<string>? ListUpdatedEvent;
@@ -165,6 +166,11 @@ public partial class WorkerClient : ObservableObject, IAsyncDisposable, IWorkerC
             Dispatcher.UIThread.Post(() => ListHandlerStartRequestedEvent?.Invoke(listId, taskIds));
         });
 
+        _hub.On<string, string>("HandlerUsageWarning", (taskId, message) =>
+        {
+            Dispatcher.UIThread.Post(() => HandlerUsageWarningEvent?.Invoke(taskId, message));
+        });
+
         _hub.On<string>("WorktreeUpdated", taskId =>
         {
             Dispatcher.UIThread.Post(() => WorktreeUpdatedEvent?.Invoke(taskId));

src/ClaudeDo.Ui/ViewModels/InteractiveTerminalViewModel.cs

@@ -131,6 +131,11 @@ public sealed partial class InteractiveTerminalViewModel : ViewModelBase, IDispo
         StartError = message;
     }
 
+    /// <summary>Types a line into the live session and submits it — see
+    /// <see cref="PtyTerminalSession.SendLineAsync"/>. False when there is no running process to
+    /// type into (or the write seam is gone).</summary>
+    public Task<bool> SendLineAsync(string text) => _session.SendLineAsync(text);
+
     public void Kill() => _session.Kill();
 
     public void Dispose()

src/ClaudeDo.Ui/ViewModels/MissionControl/ConPtyPaneViewModel.cs

@@ -123,6 +123,10 @@ public sealed partial class ConPtyPaneViewModel : ViewModelBase, IDisposable
         }
     }
 
+    /// <summary>Types a message into this pane's live session and submits it (the worker's
+    /// pre-usage-limit warning). False when the session isn't running.</summary>
+    public System.Threading.Tasks.Task<bool> SendLineAsync(string text) => Terminal.SendLineAsync(text);
+
     [RelayCommand]
     private void Close() => CloseRequested?.Invoke(this);
 

src/ClaudeDo.Ui/ViewModels/MissionControlViewModel.cs

@@ -22,6 +22,7 @@ public sealed partial class MissionControlViewModel : ViewModelBase, IDisposable
     private readonly Action _onConnectionRestored;
     private readonly Action<string, IReadOnlyList<string>, string> _onHandoffRequested;
     private readonly Action<string, IReadOnlyList<string>> _onListHandlerStartRequested;
+    private readonly Action<string, string> _onHandlerUsageWarning;
 
     // Embedded ConPTY sessions (task-based only) — a manual cockpit detached from the
     // review/merge/status machinery.
@@ -101,6 +102,8 @@ public sealed partial class MissionControlViewModel : ViewModelBase, IDisposable
 
         _onListHandlerStartRequested = (listId, taskIds) => { _ = OpenMergeHelperConPtySessionAsync(listId, taskIds); };
         _worker.ListHandlerStartRequestedEvent += _onListHandlerStartRequested;
+        _onHandlerUsageWarning = (taskId, message) => { _ = WarnHandlerSessionAsync(taskId, message); };
+        _worker.HandlerUsageWarningEvent += _onHandlerUsageWarning;
 
         _ = RefreshQueueAsync();
         _ = RefreshSessionTargetsAsync();
@@ -410,6 +413,19 @@ public sealed partial class MissionControlViewModel : ViewModelBase, IDisposable
             () => DescribeAsync(() => _worker.GetMergeHelperHandoffLaunchSpecAsync(taskId, survivingTaskIds, nextPhase))));
     }
 
+    // The 5h usage window is about to run out under this handler session: type the worker's warning
+    // into its pane so the session can hand off cleanly instead of dying mid-merge. The UI process
+    // owns the terminal, so this is the only place that can reach it at all. No pane (the tile was
+    // closed, or this is a second app instance) = nothing to warn, and that is not an error.
+    internal async System.Threading.Tasks.Task WarnHandlerSessionAsync(string taskId, string message)
+    {
+        if (string.IsNullOrEmpty(taskId) || string.IsNullOrEmpty(message)) return;
+        if (ConPtySessions.FirstOrDefault(s => s.TaskId == taskId) is not { } pane) return;
+
+        if (!await pane.SendLineAsync(message))
+            ErrorReported?.Invoke(Loc.T("missionControl.usageWarningNotDelivered"));
+    }
+
     // Wires a freshly built pane and shows it immediately — the pane resolves its own launch spec,
     // so the tile is on screen (spinner running) while the worker is still preparing the worktree.
     private void AddConPtyPane(ConPtyPaneViewModel pane)
@@ -524,6 +540,7 @@ public sealed partial class MissionControlViewModel : ViewModelBase, IDisposable
         _worker.ConnectionRestoredEvent -= _onConnectionRestored;
         _worker.HandoffRequestedEvent -= _onHandoffRequested;
         _worker.ListHandlerStartRequestedEvent -= _onListHandlerStartRequested;
+        _worker.HandlerUsageWarningEvent -= _onHandlerUsageWarning;
         ConPtySessions.CollectionChanged -= OnConPtySessionsChanged;
         Panes.CollectionChanged -= OnPanesChanged;
         foreach (var c in ConPtySessions.ToList())

src/ClaudeDo.Worker/External/HandoffMcpTools.cs

@@ -11,7 +11,11 @@ namespace ClaudeDo.Worker.External;
 // Coerced=true means nextPhase asked for a non-final phase but the server-side round cap
 // (HandoffRoundTracker) forced it to its "_final" counterpart instead -- NextPhase already
 // reflects the effective (post-coercion) value in that case.
-public sealed record HandoffListHandlerResult(bool Requested, string TaskId, int Number, int SurvivingCount, string NextPhase, bool Coerced = false);
+// DeferredUntil set means the next session was NOT opened yet: the 5h usage window is exhausted and
+// the handoff is parked until it resets (HandlerUsageGuard).
+public sealed record HandoffListHandlerResult(
+    bool Requested, string TaskId, int Number, int SurvivingCount, string NextPhase, bool Coerced = false,
+    DateTimeOffset? DeferredUntil = null);
 
 public sealed record HandoffStatusResult(string TaskId, int Number, int Round, int Remaining, bool Final);
 
@@ -22,17 +26,20 @@ public sealed class HandoffMcpTools
     private readonly HubBroadcaster _broadcaster;
     private readonly HandoffRoundTracker _rounds;
     private readonly IDbContextFactory<ClaudeDoDbContext> _dbFactory;
+    private readonly HandlerUsageGuard _usageGuard;
 
     public HandoffMcpTools(
         TaskRepository tasks,
         HubBroadcaster broadcaster,
         HandoffRoundTracker rounds,
-        IDbContextFactory<ClaudeDoDbContext> dbFactory)
+        IDbContextFactory<ClaudeDoDbContext> dbFactory,
+        HandlerUsageGuard usageGuard)
     {
         _tasks = tasks;
         _broadcaster = broadcaster;
         _rounds = rounds;
         _dbFactory = dbFactory;
+        _usageGuard = usageGuard;
     }
 
     [McpServerTool, Description(
@@ -47,8 +54,10 @@ public sealed class HandoffMcpTools
         "4 by default, i.e. two " +
         "full wait/merge cycles) for a given handler task: once reached, a \"wait\"/\"merge\" request is " +
         "silently coerced to its \"_final\" counterpart instead (check the result's coerced field), and " +
-        "any handoff at all after a merge_final round for this task throws. The current tile stays " +
-        "open; you must end your own turn immediately after calling this.")]
+        "any handoff at all after a merge_final round for this task throws. If the 5h usage window is " +
+        "already exhausted the next session is NOT opened right away -- the handoff is parked until " +
+        "the window resets and the result carries deferredUntil; say so in your summary. The current " +
+        "tile stays open; you must end your own turn immediately after calling this either way.")]
     public async Task<HandoffListHandlerResult> HandoffListHandler(
         [Description("This session's own handler task id.")] string taskId,
         [Description("The tasks that made it past dedupe, in the order to run them.")] IReadOnlyList<string> survivingTaskIds,
@@ -77,8 +86,15 @@ public sealed class HandoffMcpTools
         if (round.Rejected)
             throw new InvalidOperationException(round.Error);
 
-        await _broadcaster.HandoffRequested(taskId, survivingTaskIds, round.EffectivePhase);
-        return new HandoffListHandlerResult(true, taskId, task.Number, survivingTaskIds.Count, round.EffectivePhase, round.Coerced);
+        // The round is registered either way (the budget is spent by asking, not by the tile
+        // opening); only the broadcast waits when the 5h window is exhausted.
+        var deferredUntil = await _usageGuard.TryDeferHandoffAsync(
+            taskId, survivingTaskIds, round.EffectivePhase, cancellationToken);
+        if (deferredUntil is null)
+            await _broadcaster.HandoffRequested(taskId, survivingTaskIds, round.EffectivePhase);
+
+        return new HandoffListHandlerResult(
+            true, taskId, task.Number, survivingTaskIds.Count, round.EffectivePhase, round.Coerced, deferredUntil);
     }
 
     [McpServerTool, Description(

src/ClaudeDo.Worker/Hub/HubBroadcaster.cs

@@ -41,6 +41,11 @@ public sealed class HubBroadcaster : IPrimeBroadcaster, IRefineBroadcaster
     // tile, exactly like the "Let Claude handle it" button.
     public Task ListHandlerStartRequested(string listId, IReadOnlyList<string> taskIds) =>
         _hub.Clients.All.SendAsync("ListHandlerStartRequested", listId, taskIds);
+    // The 5h usage window is about to run out under a running list-handler session (HandlerUsageGuard).
+    // Mission Control types `message` straight into that task's ConPTY pane, so the session can hand
+    // off cleanly instead of dying mid-merge. No pane for the task = nothing happens.
+    public Task HandlerUsageWarning(string handlerTaskId, string message) =>
+        _hub.Clients.All.SendAsync("HandlerUsageWarning", handlerTaskId, message);
 
     /// <summary>An agent wrote a note through MCP — the open notes editor reloads.</summary>
     public Task NotesUpdated() =>

src/ClaudeDo.Worker/Program.cs

@@ -97,6 +97,8 @@ builder.Services.AddSingleton<ISessionSkillSeeder, SessionSkillSeeder>();
 builder.Services.AddSingleton<HandoffRoundTracker>();
 builder.Services.AddSingleton<HandlerRoundState>();
 builder.Services.AddSingleton<HandlerRestartCoordinator>();
+builder.Services.AddSingleton<HandlerUsageGuard>();
+builder.Services.AddHostedService(sp => sp.GetRequiredService<HandlerUsageGuard>());
 builder.Services.AddSingleton<InteractiveLaunchSpecService>();
 builder.Services.AddSingleton<TaskRunner>();
 builder.Services.AddSingleton<WorktreeMaintenanceService>();
@@ -339,6 +341,7 @@ if (cfg.ExternalMcpPort > 0)
     Share<AttachmentStore>();
     Share<FindingsStore>();
     Share<HandoffRoundTracker>();
+    Share<HandlerUsageGuard>();
 
     externalBuilder.Services.AddScoped<ClaudeDoDbContext>(sp =>
         sp.GetRequiredService<IDbContextFactory<ClaudeDoDbContext>>().CreateDbContext());

src/ClaudeDo.Worker/Runner/HandlerRestartCoordinator.cs

@@ -20,17 +20,14 @@ namespace ClaudeDo.Worker.Runner;
 ///
 /// Fails CLOSED, unlike the usage gate: every missing signal means "don't relaunch". An interactive
 /// session that pops back up at 3am uninvited is worse than one that stays dead.
+///
+/// It does not wait here. The restart is <b>parked in <see cref="HandlerRoundState"/></b> and fired
+/// by <see cref="HandlerUsageGuard"/> — the same slot a session that handed off cleanly before the
+/// limit uses, so exactly one of the two reopens a round. Parking it also survives a worker restart
+/// during the hours-long wait, which an in-process <c>Task.Delay</c> did not.
 /// </summary>
 public sealed class HandlerRestartCoordinator
 {
-    // The corroborating signal that this exit really was the usage limit. A ConPTY session gives us
-    // nothing but an exit code -- there is no stdout to match against, so TaskRunner's
-    // IsUsageLimitMessage regex (which reads the CLI's own "session limit reached" text) has nothing
-    // to read here. The 5h utilization at the moment of death is the one independent witness we do
-    // have, and it is pinned at 100% when the limit is what stopped the session. A crash, a manual
-    // Ctrl-C, or a bad launch at 40% utilization is therefore NOT restarted.
-    internal const int UsageLimitProofPct = 95;
-
     private readonly IDbContextFactory<ClaudeDoDbContext> _dbFactory;
     private readonly UsageState _usageState;
     private readonly HandlerRoundState _rounds;
@@ -51,14 +48,10 @@ public sealed class HandlerRestartCoordinator
         _logger = logger;
     }
 
-    /// <summary>Test seams — a real 5h wait is not a test.</summary>
-    internal Func<DateTimeOffset> NowUtc { get; set; } = () => DateTimeOffset.UtcNow;
-    internal Func<TimeSpan, CancellationToken, Task> Delay { get; set; } = (d, ct) => Task.Delay(d, ct);
-
-    /// <summary>Handles a ConPTY session's process exit. Returns true when a restart was claimed and
-    /// carried out (the returned task completes only after the wait, so a caller that wants
-    /// fire-and-forget must not await it). Any non-handler task, clean exit, non-usage-limit death,
-    /// PowerUse-off list, or already-used round is a silent no-op.</summary>
+    /// <summary>Handles a ConPTY session's process exit. Returns true when a restart was parked for
+    /// the reset (HandlerUsageGuard fires it). Any non-handler task, clean exit, non-usage-limit
+    /// death, PowerUse-off list, already-used round, or round that already has a handoff parked is a
+    /// silent no-op.</summary>
     public async Task<bool> OnSessionExitedAsync(string taskId, int exitCode, CancellationToken ct = default)
     {
         if (exitCode == 0 || string.IsNullOrEmpty(taskId)) return false;
@@ -71,7 +64,6 @@ public sealed class HandlerRestartCoordinator
 
         var snapshot = _usageState.Snapshot;
         if (snapshot?.FiveHour is not { } fiveHour) return false;
-        if (fiveHour.Utilization < UsageLimitProofPct) return false;
         if (fiveHour.ResetsAt is not { } resetsAt) return false;
 
         int number;
@@ -85,8 +77,18 @@ public sealed class HandlerRestartCoordinator
             // Both PowerUse keys, exactly as ComposeHandlerPromptAsync gates the PowerUse prompt
             // addendum: the global switch alone must not make an interactive run on some unrelated
             // list restart itself overnight.
-            if (!(await new AppSettingsRepository(ctx).GetAsync(ct)).PowerUseEnabled) return false;
+            var settings = await new AppSettingsRepository(ctx).GetAsync(ct);
+            if (!settings.PowerUseEnabled) return false;
             if ((await new ListRepository(ctx).GetConfigAsync(task.ListId, ct))?.PowerUseAllowed != true) return false;
+
+            // The corroborating signal that this exit really was the usage limit. A ConPTY session
+            // gives us nothing but an exit code -- there is no stdout to match against, so
+            // TaskRunner's IsUsageLimitMessage regex (which reads the CLI's own "session limit
+            // reached" text) has nothing to read here. The 5h utilization at the moment of death is
+            // the one independent witness we do have. Same threshold the warning and the withheld
+            // handoff use (PowerUseHandoffPct) so all three agree on where "at the limit" starts;
+            // a crash or a manual Ctrl-C well below it is NOT restarted.
+            if (fiveHour.Utilization < Math.Clamp(settings.PowerUseHandoffPct, 50, 99)) return false;
         }
         catch (Exception ex)
         {
@@ -94,36 +96,25 @@ public sealed class HandlerRestartCoordinator
             return false;
         }
 
-        // One restart per round, claimed before the wait -- a restart that dies again lands back
-        // here and must stop, not relaunch.
-        if (!_rounds.TryClaimAutoRestart(taskId)) return false;
+        // One restart per round, and never on top of a handoff the session itself already parked.
+        // The budget is NOT spent here -- HandlerUsageGuard spends it when the broadcast goes out,
+        // so a worker that dies during the wait doesn't leave the round marked "restart used".
+        var dueAt = resetsAt + HandlerUsageGuard.ResetGrace;
+        if (!_rounds.TryScheduleAutoRestart(taskId, dueAt, round.Phase, round.TaskIds)) return false;
 
+        // Fire-and-forget caller (WorkerHub): an unobserved exception here would be invisible, so
+        // the log line must not be able to throw past this point.
         try
         {
             await _broadcaster.WorkerLog(
                 $"List handler #{number} died at the usage limit (5h {fiveHour.Utilization:0}%) — " +
-                $"restarting phase {round.Phase} after the reset at {resetsAt.ToLocalTime():HH:mm}",
+                $"restarting phase {round.Phase} after the reset, at {dueAt.ToLocalTime():HH:mm}",
                 WorkerLogLevel.Warn, DateTime.UtcNow);
-
-            var wait = resetsAt - NowUtc();
-            if (wait > TimeSpan.Zero) await Delay(wait, ct);
-
-            await _broadcaster.HandoffRequested(taskId, round.TaskIds, round.Phase);
-            await _broadcaster.WorkerLog(
-                $"Auto-restarting list handler #{number} at phase {round.Phase} after usage-limit reset",
-                WorkerLogLevel.Info, DateTime.UtcNow);
-            return true;
-        }
-        catch (OperationCanceledException)
-        {
-            return false;
         }
         catch (Exception ex)
         {
-            // Callers fire-and-forget this (WorkerHub.ReportInteractiveSessionExited), so an
-            // unobserved throw here would be invisible.
-            _logger.LogError(ex, "HandlerRestartCoordinator: auto-restart of handler task {TaskId} failed", taskId);
-            return false;
+            _logger.LogWarning(ex, "HandlerRestartCoordinator: restart of #{Number} is parked, but the WorkerLog broadcast failed", number);
         }
+        return true;
     }
 }

src/ClaudeDo.Worker/Runner/HandlerRoundState.cs

@@ -9,17 +9,26 @@ namespace ClaudeDo.Worker.Runner;
 /// <c>HandoffRequested</c> broadcast that is the only other place these ids exist.</summary>
 /// <param name="Phase">A <see cref="MergeHelperPhase"/> value, or "triage" for the initial session
 /// (which has no handoff spec and therefore cannot be reopened — see HandlerRestartCoordinator).</param>
-/// <param name="AutoRestartUsed">Claimed once per round by HandlerRestartCoordinator, so a handler
-/// that dies again after its auto-restart stays dead instead of relaunching all night.</param>
-/// <param name="DeferredHandoffAt">Reserved for the "hand off cleanly before the usage limit"
-/// follow-up, which parks a handoff until the 5h reset and needs to survive a worker restart.</param>
+/// <param name="AutoRestartUsed">Spent once per round, and only once the deferred
+/// <c>HandoffRequested</c> broadcast has actually gone out — a restart that is merely *scheduled*
+/// must not count, or a worker that dies during the hours-long wait leaves the round permanently
+/// marked "restart used" without one ever having happened.</param>
+/// <param name="DeferredHandoffAt">Due time of a handoff parked until the 5h usage window resets.
+/// One slot per round, shared by both producers: a session that handed off cleanly just before the
+/// limit (HandlerUsageGuard) and a session that died at it (HandlerRestartCoordinator) — so the two
+/// can never reopen the same round twice. Fired by HandlerUsageGuard, which re-picks it up after a
+/// worker restart because it lives in this file rather than in a timer.</param>
 public sealed record HandlerRound(
     string HandlerTaskId,
     string Phase,
     IReadOnlyList<string> TaskIds,
     DateTime StartedAtUtc,
     bool AutoRestartUsed = false,
-    DateTimeOffset? DeferredHandoffAt = null);
+    DateTimeOffset? DeferredHandoffAt = null,
+    string? DeferredPhase = null,
+    IReadOnlyList<string>? DeferredTaskIds = null,
+    bool DeferredIsAutoRestart = false,
+    bool UsageWarningSent = false);
 
 /// <summary>
 /// File-backed store for <see cref="HandlerRound"/>, one entry per handler task. Deliberately a
@@ -74,22 +83,95 @@ public sealed class HandlerRoundState
         }
     }
 
-    /// <summary>Takes this round's single auto-restart budget. False when there is no round for the
-    /// task or its budget is already spent — the same "never twice" discipline
-    /// <c>TaskRepository.TryClaimUsageLimitAutoContinueAsync</c> enforces for headless runs.</summary>
-    public bool TryClaimAutoRestart(string handlerTaskId)
+    public IReadOnlyList<HandlerRound> All()
+    {
+        lock (_lock)
+            return Rounds().Values.ToList();
+    }
+
+    /// <summary>Claims this round's single "warn the session before the usage limit" shot. True only
+    /// the first time, so a monitor that keeps ticking above the threshold does not retype the same
+    /// warning into the session every 30 seconds.</summary>
+    public bool TryMarkUsageWarned(string handlerTaskId)
     {
         lock (_lock)
         {
             var rounds = Rounds();
-            if (!rounds.TryGetValue(handlerTaskId, out var round) || round.AutoRestartUsed) return false;
+            if (!rounds.TryGetValue(handlerTaskId, out var round) || round.UsageWarningSent) return false;
 
-            rounds[handlerTaskId] = round with { AutoRestartUsed = true };
+            rounds[handlerTaskId] = round with { UsageWarningSent = true };
             Persist(rounds);
             return true;
         }
     }
 
+    /// <summary>Parks a handoff the running session asked for until <paramref name="dueAt"/>.
+    /// Overwrites any existing slot: the live session's own request is the most recent word on what
+    /// the next round should be.</summary>
+    public void SetDeferredHandoff(
+        string handlerTaskId, DateTimeOffset dueAt, string phase, IReadOnlyList<string> taskIds)
+        => WriteDeferred(handlerTaskId, dueAt, phase, taskIds, isAutoRestart: false);
+
+    /// <summary>Schedules this round's single auto-restart (the session died at the limit). False
+    /// when there is no round, the restart budget is already spent, or a handoff is *already* parked
+    /// for this round — the deferred handoff and the auto-restart are one trigger, not two.
+    /// <see cref="HandlerRound.AutoRestartUsed"/> is deliberately NOT set here; only
+    /// <see cref="ClearDeferredHandoff"/> spends it, once the broadcast really went out.</summary>
+    public bool TryScheduleAutoRestart(
+        string handlerTaskId, DateTimeOffset dueAt, string phase, IReadOnlyList<string> taskIds)
+    {
+        lock (_lock) // Monitor is reentrant — WriteDeferred takes the same lock.
+        {
+            var rounds = Rounds();
+            if (!rounds.TryGetValue(handlerTaskId, out var round)) return false;
+            if (round.AutoRestartUsed || round.DeferredHandoffAt is not null) return false;
+
+            WriteDeferred(handlerTaskId, dueAt, phase, taskIds, isAutoRestart: true);
+            return true;
+        }
+    }
+
+    /// <summary>Clears the parked handoff. <paramref name="spendAutoRestart"/> marks the round's
+    /// restart budget as used — pass the slot's own <see cref="HandlerRound.DeferredIsAutoRestart"/>,
+    /// so a clean pre-limit handoff never costs the next session its restart.</summary>
+    public void ClearDeferredHandoff(string handlerTaskId, bool spendAutoRestart)
+    {
+        lock (_lock)
+        {
+            var rounds = Rounds();
+            if (!rounds.TryGetValue(handlerTaskId, out var round)) return;
+
+            rounds[handlerTaskId] = round with
+            {
+                DeferredHandoffAt = null,
+                DeferredPhase = null,
+                DeferredTaskIds = null,
+                DeferredIsAutoRestart = false,
+                AutoRestartUsed = round.AutoRestartUsed || spendAutoRestart,
+            };
+            Persist(rounds);
+        }
+    }
+
+    private void WriteDeferred(
+        string handlerTaskId, DateTimeOffset dueAt, string phase, IReadOnlyList<string> taskIds, bool isAutoRestart)
+    {
+        lock (_lock)
+        {
+            var rounds = Rounds();
+            if (!rounds.TryGetValue(handlerTaskId, out var round)) return;
+
+            rounds[handlerTaskId] = round with
+            {
+                DeferredHandoffAt = dueAt,
+                DeferredPhase = phase,
+                DeferredTaskIds = taskIds.ToList(),
+                DeferredIsAutoRestart = isAutoRestart,
+            };
+            Persist(rounds);
+        }
+    }
+
     public void Remove(string handlerTaskId)
     {
         lock (_lock)

src/ClaudeDo.Worker/Runner/HandlerUsageGuard.cs

@@ -0,0 +1,207 @@
+using ClaudeDo.Data;
+using ClaudeDo.Data.Models;
+using ClaudeDo.Data.Repositories;
+using ClaudeDo.Worker.External;
+using ClaudeDo.Worker.Hub;
+using ClaudeDo.Worker.Usage;
+using Microsoft.EntityFrameworkCore;
+
+namespace ClaudeDo.Worker.Runner;
+
+/// <summary>
+/// Hands a PowerUse list-handler round over cleanly across the 5h usage limit, instead of letting it
+/// die mid-merge:
+///
+/// 1. <b>Warn</b> — once per round, as soon as the 5h window crosses
+///    <c>AppSettings.PowerUseHandoffPct</c>, a message is typed straight into the live ConPTY session
+///    (<c>HandlerUsageWarning</c> → Mission Control) telling it to finish what it is doing and call
+///    <c>handoff_list_handler</c> itself. A session that hands off on its own leaves no half-merged
+///    tree behind; an auto-restart after the fact cannot clean one up.
+/// 2. <b>Withhold</b> — the resulting handoff is not broadcast immediately (the next session would
+///    open straight into the same exhausted window) but parked in <see cref="HandlerRoundState"/>
+///    until the window resets. Same slot the auto-restart of a session that *did* die uses
+///    (<see cref="HandlerRestartCoordinator"/>), so the two can never reopen one round twice.
+/// 3. <b>Fire</b> — this service's tick is also what releases a parked handoff. Deliberately a poll
+///    over the persisted state rather than a timer: a worker restart mid-wait re-picks the parked
+///    handoff up on the next tick, and an overdue one goes out immediately, for free.
+/// </summary>
+public sealed class HandlerUsageGuard : BackgroundService
+{
+    internal static readonly TimeSpan TickInterval = TimeSpan.FromSeconds(30);
+
+    // Small cushion past ResetsAt: the reported reset time is the server's, and reopening a session
+    // one second early buys nothing but another dead tile.
+    internal static readonly TimeSpan ResetGrace = TimeSpan.FromSeconds(60);
+
+    private readonly IDbContextFactory<ClaudeDoDbContext> _dbFactory;
+    private readonly UsageState _usageState;
+    private readonly HandlerRoundState _rounds;
+    private readonly HandoffRoundTracker _handoffRounds;
+    private readonly HubBroadcaster _broadcaster;
+    private readonly ILogger<HandlerUsageGuard> _logger;
+
+    public HandlerUsageGuard(
+        IDbContextFactory<ClaudeDoDbContext> dbFactory,
+        UsageState usageState,
+        HandlerRoundState rounds,
+        HandoffRoundTracker handoffRounds,
+        HubBroadcaster broadcaster,
+        ILogger<HandlerUsageGuard> logger)
+    {
+        _dbFactory = dbFactory;
+        _usageState = usageState;
+        _rounds = rounds;
+        _handoffRounds = handoffRounds;
+        _broadcaster = broadcaster;
+        _logger = logger;
+    }
+
+    /// <summary>Test seam — a real 5h wait is not a test.</summary>
+    internal Func<DateTimeOffset> NowUtc { get; set; } = () => DateTimeOffset.UtcNow;
+
+    /// <summary>PowerUse verdict for one handler task: both PowerUse switches on, a 5h bucket
+    /// available, plus the configured threshold and the task's display number.</summary>
+    internal sealed record Policy(int HandoffPct, UsageBucket FiveHour, int Number);
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                await TickAsync(stoppingToken);
+                await Task.Delay(TickInterval, stoppingToken);
+            }
+            catch (OperationCanceledException)
+            {
+                return;
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex, "HandlerUsageGuard: tick failed");
+                await Task.Delay(TickInterval, stoppingToken);
+            }
+        }
+    }
+
+    internal async Task TickAsync(CancellationToken ct)
+    {
+        foreach (var round in _rounds.All())
+        {
+            await FireIfDueAsync(round);
+            await WarnIfNearLimitAsync(round, ct);
+        }
+    }
+
+    /// <summary>Called by <c>handoff_list_handler</c>. Returns the time the handoff was parked until
+    /// when it must be withheld, or null when it should go out now (PowerUse off for this list, well
+    /// below the threshold, or no reset time to wait for).</summary>
+    public async Task<DateTimeOffset?> TryDeferHandoffAsync(
+        string handlerTaskId, IReadOnlyList<string> survivingTaskIds, string phase, CancellationToken ct)
+    {
+        var policy = await EvaluateAsync(handlerTaskId, ct);
+        if (policy is null) return null;
+
+        // The warning flag matters on its own: utilization can dip back under the threshold between
+        // the warning and the session actually finishing its merge, and a handoff produced *because*
+        // of the warning must still wait for the reset.
+        var warned = _rounds.Get(handlerTaskId)?.UsageWarningSent == true;
+        if (policy.FiveHour.Utilization < policy.HandoffPct && !warned) return null;
+
+        if (policy.FiveHour.ResetsAt is not { } resetsAt)
+        {
+            _logger.LogWarning(
+                "HandlerUsageGuard: 5h window at {Pct}% has no reset time; handing off {TaskId} immediately",
+                policy.FiveHour.Utilization, handlerTaskId);
+            return null;
+        }
+
+        var dueAt = resetsAt + ResetGrace;
+        _rounds.SetDeferredHandoff(handlerTaskId, dueAt, phase, survivingTaskIds);
+        await _broadcaster.WorkerLog(
+            $"List handler #{policy.Number}: handoff to phase {phase} withheld until " +
+            $"{dueAt.ToLocalTime():HH:mm} (5h window at {policy.FiveHour.Utilization:0}%)",
+            WorkerLogLevel.Warn, DateTime.UtcNow);
+        return dueAt;
+    }
+
+    private async Task FireIfDueAsync(HandlerRound round)
+    {
+        if (round.DeferredHandoffAt is not { } dueAt || dueAt > NowUtc()) return;
+
+        if (round.DeferredPhase is not { Length: > 0 } phase || round.DeferredTaskIds is not { Count: > 0 } taskIds)
+        {
+            _rounds.ClearDeferredHandoff(round.HandlerTaskId, spendAutoRestart: false);
+            return;
+        }
+
+        // Cleared BEFORE the broadcast so a throw on the way out can't leave a slot that re-fires on
+        // every tick; the restart budget is spent here too, which is the point of the whole
+        // rework -- it is now only spent once a handoff really went out.
+        _rounds.ClearDeferredHandoff(round.HandlerTaskId, spendAutoRestart: round.DeferredIsAutoRestart);
+
+        await _broadcaster.HandoffRequested(round.HandlerTaskId, taskIds, phase);
+        await _broadcaster.WorkerLog(
+            $"Reopening list handler at phase {phase} after the usage-limit reset",
+            WorkerLogLevel.Info, DateTime.UtcNow);
+    }
+
+    private async Task WarnIfNearLimitAsync(HandlerRound round, CancellationToken ct)
+    {
+        if (round.UsageWarningSent) return;
+        // A sealed chain has no further handoff to ask for -- telling it to call
+        // handoff_list_handler would only earn the session an exception.
+        if (_handoffRounds.GetState(round.HandlerTaskId).Sealed) return;
+
+        var policy = await EvaluateAsync(round.HandlerTaskId, ct);
+        if (policy is null || policy.FiveHour.Utilization < policy.HandoffPct) return;
+        if (!_rounds.TryMarkUsageWarned(round.HandlerTaskId)) return;
+
+        await _broadcaster.HandlerUsageWarning(
+            round.HandlerTaskId, BuildWarning(round.HandlerTaskId, round.Phase, policy.FiveHour.Utilization));
+        await _broadcaster.WorkerLog(
+            $"List handler #{policy.Number}: warned the session at 5h {policy.FiveHour.Utilization:0}% " +
+            $"(handoff threshold {policy.HandoffPct}%)",
+            WorkerLogLevel.Warn, DateTime.UtcNow);
+    }
+
+    // Plain ASCII on purpose: this is typed character-by-character into a PTY, not rendered by us.
+    internal static string BuildWarning(string handlerTaskId, string phase, double utilization) =>
+        $"USAGE LIMIT IMMINENT ({utilization:0}% of the 5h window). Finish or abort the merge you are " +
+        "in - never leave conflict markers in the tree - then call " +
+        $"handoff_list_handler(taskId: \"{handlerTaskId}\", survivingTaskIds: <every task not yet Done>, " +
+        $"nextPhase: \"{NextPhaseFor(phase)}\") right now. Do not start anything new. " +
+        "The next session opens automatically after the limit resets.";
+
+    // The session should resume where it is, so the warning names its own phase back. The opening
+    // triage round is the exception: "triage" is not a handoff phase, and what follows triage is
+    // always the wait phase.
+    private static string NextPhaseFor(string phase) =>
+        MergeHelperPhase.All.Contains(phase, StringComparer.Ordinal) ? phase : MergeHelperPhase.Wait;
+
+    /// <summary>Both PowerUse switches, exactly as <c>ComposeHandlerPromptAsync</c> and
+    /// <see cref="HandlerRestartCoordinator"/> gate them — the global toggle alone must not make an
+    /// unrelated list's handler session get typed into. Null = leave this round alone.</summary>
+    private async Task<Policy?> EvaluateAsync(string handlerTaskId, CancellationToken ct)
+    {
+        if (_usageState.Snapshot?.FiveHour is not { } fiveHour) return null;
+
+        try
+        {
+            await using var ctx = await _dbFactory.CreateDbContextAsync(ct);
+            var task = await new TaskRepository(ctx).GetByIdAsync(handlerTaskId, ct);
+            if (task is null) return null;
+
+            var settings = await new AppSettingsRepository(ctx).GetAsync(ct);
+            if (!settings.PowerUseEnabled) return null;
+            if ((await new ListRepository(ctx).GetConfigAsync(task.ListId, ct))?.PowerUseAllowed != true) return null;
+
+            return new Policy(Math.Clamp(settings.PowerUseHandoffPct, 50, 99), fiveHour, task.Number);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "HandlerUsageGuard: could not evaluate handler task {TaskId}", handlerTaskId);
+            return null;
+        }
+    }
+}