Add structured freeform context payload + ExecutingTask/ready recovery

PrCopilot/src/PrCopilot/StateMachine/MonitorState.cs

@@ -96,6 +96,15 @@ public class MonitorState
     /// <summary>Reply text composed by the agent, to be posted by the server via the REST API.</summary>
     public string? PendingReplyText { get; set; }
 
+    /// <summary>
+    /// HEAD SHA snapshotted when the state most recently entered <see cref="MonitorStateId.ExecutingTask"/>.
+    /// Used by the recovery path for <c>(ExecutingTask, "ready")</c> to detect whether the agent
+    /// pushed during the task — if HEAD has advanced, "ready" is reinterpreted as a completion event
+    /// (<c>comment_addressed</c> in comment flows, <c>push_completed</c> in CI flows).
+    /// Set via <see cref="EnterExecutingTask"/>; null/empty means no snapshot was captured.
+    /// </summary>
+    public string? HeadShaAtTaskStart { get; set; }
+
     /// <summary>Transient: completion event set by sampling handler for MonitorFlowTools to feed back to state machine.</summary>
     public string? SamplingCompletionEvent { get; set; }
     /// <summary>Transient: completion event set by EmitComposeReplyAction for the sampling compose_reply handler.</summary>
@@ -130,4 +139,20 @@ public void ClearPendingCommentState()
     /// Set when ReviewerReplied terminal state is detected.
     /// </summary>
     public CommentInfo? RepliedComment { get; set; }
+
+    /// <summary>
+    /// Transition to <see cref="MonitorStateId.ExecutingTask"/> and snapshot the current
+    /// <see cref="HeadSha"/> as <see cref="HeadShaAtTaskStart"/>. The snapshot lets the
+    /// recovery path detect post-push resumes (where the agent pushed during the task and
+    /// then re-entered via the post-push <c>pr_monitor_start</c> hook with event=ready
+    /// instead of calling the documented completion event).
+    ///
+    /// Use this instead of assigning <c>CurrentState = MonitorStateId.ExecutingTask</c>
+    /// directly so the snapshot is never forgotten at a new task-entry site.
+    /// </summary>
+    public void EnterExecutingTask()
+    {
+        CurrentState = MonitorStateId.ExecutingTask;
+        HeadShaAtTaskStart = HeadSha;
+    }
 }

PrCopilot/src/PrCopilot/StateMachine/MonitorTransitions.cs

@@ -115,6 +115,7 @@ public static MonitorAction BuildTerminalAction(MonitorState state, TerminalStat
         ["I'll handle the comments myself"] = "handle_myself",
         ["I'll handle them myself"] = "handle_myself",
         ["Skip this comment"] = "skip",
+        ["Treat as comment addressed"] = "treat_as_addressed",
         ["Done — resume monitoring"] = "done",
         ["Address next comment"] = "continue",
         ["I'll handle the rest myself"] = "done",
@@ -126,6 +127,7 @@ public static MonitorAction BuildTerminalAction(MonitorState state, TerminalStat
         ["Re-run failed jobs"] = "rerun",
         ["Apply the recommendation"] = "apply_fix",
         ["Run a new build"] = "run_new",
+        ["Treat as push completed"] = "treat_as_pushed",
 
         // Waiting-for-reply comment choices (ProcessWaitingCommentChoice)
         ["Resolve this thread"] = "resolve",
@@ -182,6 +184,14 @@ public static MonitorAction ProcessEvent(MonitorState state, string eventType, s
             // LLM finished executing a generic task
             (MonitorStateId.ExecutingTask, "task_complete") => ProcessTaskComplete(state),
 
+            // Recovery: agent skipped the documented completion event and re-entered with
+            // event=ready (commonly because the user's post-push custom-instruction hook
+            // fires pr_monitor_start + ready instead of the Path B comment_addressed/
+            // push_completed events). Returns an auto_execute that fetches HEAD; if HEAD
+            // advanced during the task, the wrapper re-dispatches as the right completion
+            // event, otherwise falls through to flow-aware recovery prompt.
+            (MonitorStateId.ExecutingTask, "ready") => BuildRecoverFromReadyAction(state),
+
             // Recovery: agent sent task_complete from AwaitingUser (skipped a tool call)
             (MonitorStateId.AwaitingUser, "task_complete") => RecoverFromUnexpectedTaskComplete(state),
 
@@ -331,8 +341,20 @@ private static MonitorAction RecoverFromUnexpectedTaskComplete(MonitorState stat
     private static MonitorAction RecoverFromUnexpectedState(MonitorState state, string eventType)
     {
         var priorState = state.CurrentState;
+        var priorCommentFlow = state.CommentFlow;
+        var priorCiFailureFlow = state.CiFailureFlow;
         DebugLogger.Log("StateMachine", $"RECOVERY: Unexpected state {priorState}/{eventType}. Transitioning to AwaitingUser so next user_chose can recover.");
         state.CurrentState = MonitorStateId.AwaitingUser;
+
+        // Preserve flow context when recovering from ExecutingTask — the user is mid-flow
+        // and may want to resume by treating the task as completed (e.g., comment addressed).
+        // Wiping the flow state would force them to start the comment loop from scratch and
+        // lose their place. For other prior states, keep the original aggressive cleanup.
+        if (priorState == MonitorStateId.ExecutingTask)
+        {
+            return BuildExecutingTaskRecoveryPrompt(state, eventType, priorCommentFlow, priorCiFailureFlow);
+        }
+
         state.CommentFlow = CommentFlowState.None;
         state.CiFailureFlow = CiFailureFlowState.None;
         state.ActiveWaitingComment = null;
@@ -344,6 +366,83 @@ private static MonitorAction RecoverFromUnexpectedState(MonitorState state, stri
         };
     }
 
+    /// <summary>
+    /// Recovery prompt for unexpected events arriving while in <see cref="MonitorStateId.ExecutingTask"/>.
+    /// Offers flow-aware choices so the user can mark the task done in-flow rather than
+    /// being forced to "Resume monitoring" (which would wipe the flow state and restart polling).
+    /// Flow state (CommentFlow / CiFailureFlow / current comment index) is preserved so the
+    /// follow-up <c>user_chose</c> can dispatch into the correct flow handler.
+    /// </summary>
+    private static MonitorAction BuildExecutingTaskRecoveryPrompt(
+        MonitorState state,
+        string eventType,
+        CommentFlowState priorCommentFlow,
+        CiFailureFlowState priorCiFailureFlow)
+    {
+        if (priorCommentFlow != CommentFlowState.None)
+        {
+            return new MonitorAction
+            {
+                Action = "ask_user",
+                Question = $"Unexpected event '{eventType}' while addressing a comment. " +
+                    "If you finished the work, pick how to mark it; otherwise resume or stop.",
+                Choices =
+                [
+                    "Treat as comment addressed",
+                    "Skip this comment",
+                    "Resume monitoring",
+                    "Stop monitoring"
+                ]
+            };
+        }
+
+        if (priorCiFailureFlow != CiFailureFlowState.None)
+        {
+            return new MonitorAction
+            {
+                Action = "ask_user",
+                Question = $"Unexpected event '{eventType}' while investigating a CI failure. " +
+                    "If you finished the work, pick how to mark it; otherwise resume or stop.",
+                Choices =
+                [
+                    "Treat as push completed",
+                    "Resume monitoring",
+                    "Stop monitoring"
+                ]
+            };
+        }
+
+        // No active flow — same as the generic recovery
+        state.ActiveWaitingComment = null;
+        return new MonitorAction
+        {
+            Action = "ask_user",
+            Question = $"Unexpected state: ExecutingTask/{eventType}. What would you like to do?",
+            Choices = ["Resume monitoring", "Stop monitoring"]
+        };
+    }
+
+    /// <summary>
+    /// Returns an <c>auto_execute</c> action that the MCP wrapper handles by fetching the
+    /// latest HEAD SHA from GitHub. If HEAD advanced since <see cref="MonitorState.HeadShaAtTaskStart"/>,
+    /// the wrapper re-dispatches the event as <c>comment_addressed</c> (comment flow) or
+    /// <c>push_completed</c> (CI flow) — recovering automatically from the post-push hook
+    /// that called <c>ready</c> instead of the documented completion event. If HEAD did
+    /// not advance, the wrapper falls back to <see cref="BuildExecutingTaskRecoveryPrompt"/>.
+    /// </summary>
+    private static MonitorAction BuildRecoverFromReadyAction(MonitorState state)
+    {
+        DebugLogger.Log("StateMachine", $"ExecutingTask/ready: dispatching auto_execute recover_from_ready_in_executing_task (snapshot HEAD={ShortSha(state.HeadShaAtTaskStart)})");
+        return new MonitorAction
+        {
+            Action = "auto_execute",
+            Task = "recover_from_ready_in_executing_task"
+        };
+    }
+
+    private static string ShortSha(string? sha) =>
+        string.IsNullOrEmpty(sha) ? "(none)" : sha.Length <= 7 ? sha : sha[..7];
+
     private static MonitorAction TransitionToPolling(MonitorState state)
     {
         state.CurrentState = MonitorStateId.Polling;
@@ -435,6 +534,12 @@ private static MonitorAction BuildCommentAction(MonitorState state, string times
 
     private static MonitorAction ProcessCommentChoice(MonitorState state, string? choice)
     {
+        // Recovery shortcut available from any comment-flow sub-state — the (ExecutingTask, "ready")
+        // recovery path offers this when HEAD did NOT advance during the task. Routes through
+        // ProcessCommentAddressed which gracefully composes a reply if PendingReplyText is empty.
+        if (choice == "treat_as_addressed")
+            return ProcessCommentAddressed(state, null);
+
         return (state.CommentFlow, choice) switch
         {
             (CommentFlowState.MultiCommentPrompt, "address_all") => BeginAddressAll(state),
@@ -514,7 +619,7 @@ private static MonitorAction BeginExplainAll(MonitorState state)
     private static MonitorAction EmitExplainForCurrentComment(MonitorState state)
     {
         var c = state.UnresolvedComments[state.CurrentCommentIndex];
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         state.PendingExplainResult = true;
         state.LastRecommendation = null;
         return new MonitorAction
@@ -573,7 +678,7 @@ private static MonitorAction HandlePickedComment(MonitorState state, string? cho
 
     private static MonitorAction BeginAddressCurrentComment(MonitorState state)
     {
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         return EmitAddressCommentAction(state);
     }
 
@@ -583,7 +688,7 @@ private static MonitorAction BeginApplyRecommendation(MonitorState state)
             return TransitionToPolling(state);
 
         var c = state.UnresolvedComments[state.CurrentCommentIndex];
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         return new MonitorAction
         {
             Action = "execute",
@@ -604,7 +709,7 @@ private static MonitorAction BeginApplyRecommendation(MonitorState state)
     private static MonitorAction BeginExplainComment(MonitorState state, bool isReplyEvent = false)
     {
         var c = state.UnresolvedComments[state.CurrentCommentIndex];
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         state.PendingExplainResult = true;
         state.LastRecommendation = null;
         var replyContext = isReplyEvent && !string.IsNullOrEmpty(c.LastReplyAuthor)
@@ -633,7 +738,7 @@ private static MonitorAction EmitAddressCommentAction(MonitorState state)
         }
 
         var c = state.UnresolvedComments[state.CurrentCommentIndex];
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         return new MonitorAction
         {
             Action = "execute",
@@ -853,7 +958,7 @@ private static MonitorAction BuildPostReplyAction(MonitorState state, CommentInf
     /// </summary>
     private static MonitorAction EmitComposeReplyAction(MonitorState state, CommentInfo c, string completionEvent)
     {
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         state.PendingCompletionEvent = completionEvent;
         return new MonitorAction
         {
@@ -946,6 +1051,12 @@ private static MonitorAction BuildCiFailureAction(MonitorState state)
 
     private static MonitorAction ProcessCiFailureChoice(MonitorState state, string? choice)
     {
+        // Recovery shortcut from any CI-failure sub-state — the (ExecutingTask, "ready")
+        // recovery path offers this when HEAD did NOT advance during the task. Surfaces the
+        // documented push_completed behavior: clear failure state and resume polling.
+        if (choice == "treat_as_pushed")
+            return TransitionToPolling(state);
+
         return (state.CiFailureFlow, choice) switch
         {
             (CiFailureFlowState.InvestigationResults, "apply_fix") => BeginApplyFix(state),
@@ -1060,7 +1171,7 @@ private static MonitorAction BuildRerunAction(MonitorState state)
         // Azure DevOps has no API for rerun-failed-only; only the web UI supports it.
         state.PendingRerunWhenChecksComplete = false;
         var buildUrl = state.FailedChecks.FirstOrDefault()?.Url;
-        state.CurrentState = MonitorStateId.ExecutingTask;
+        state.EnterExecutingTask();
         state.CommentFlow = CommentFlowState.None;
         state.CiFailureFlow = CiFailureFlowState.None;
         return new MonitorAction

PrCopilot/src/PrCopilot/Tools/CiFailureContext.cs

@@ -0,0 +1,15 @@
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+
+namespace PrCopilot.Tools;
+
+/// <summary>
+/// CI failure context, attached to <see cref="FreeformInterpretContext"/> when the
+/// user is replying about a failed CI check.
+/// </summary>
+internal sealed class CiFailureContext
+{
+    [JsonPropertyName("failedChecks")]
+    public List<FailedCheckContext> FailedChecks { get; set; } = [];
+}

PrCopilot/src/PrCopilot/Tools/CommentContext.cs

@@ -0,0 +1,28 @@
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+
+namespace PrCopilot.Tools;
+
+/// <summary>
+/// The active comment thread context, attached to <see cref="FreeformInterpretContext"/>
+/// when the user is replying about a code review comment.
+/// </summary>
+internal sealed class CommentContext
+{
+    [JsonPropertyName("author")]
+    public string Author { get; set; } = "";
+
+    [JsonPropertyName("filePath")]
+    public string FilePath { get; set; } = "";
+
+    [JsonPropertyName("line")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public int? Line { get; set; }
+
+    [JsonPropertyName("body")]
+    public string Body { get; set; } = "";
+
+    [JsonPropertyName("url")]
+    public string Url { get; set; } = "";
+}

PrCopilot/src/PrCopilot/Tools/ElicitationChoiceContext.cs

@@ -0,0 +1,21 @@
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+
+namespace PrCopilot.Tools;
+
+/// <summary>
+/// A single choice from an elicitation prompt. <see cref="Display"/> is what the
+/// user saw; <see cref="Value"/> is the internal mapped value the agent should
+/// pass back as <c>choice</c> for a Path A clean choice match.
+/// </summary>
+internal sealed class ElicitationChoiceContext
+{
+    /// <summary>Human-readable choice label as shown to the user.</summary>
+    [JsonPropertyName("display")]
+    public string Display { get; set; } = "";
+
+    /// <summary>Internal mapped value (what would be passed back as <c>choice</c>).</summary>
+    [JsonPropertyName("value")]
+    public string Value { get; set; } = "";
+}

PrCopilot/src/PrCopilot/Tools/ElicitationContext.cs

@@ -0,0 +1,19 @@
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+
+namespace PrCopilot.Tools;
+
+/// <summary>
+/// The elicitation prompt that was shown to the user, captured for the
+/// <see cref="FreeformInterpretContext"/> payload so the agent knows what
+/// question the user was responding to.
+/// </summary>
+internal sealed class ElicitationContext
+{
+    [JsonPropertyName("question")]
+    public string Question { get; set; } = "";
+
+    [JsonPropertyName("choices")]
+    public List<ElicitationChoiceContext> Choices { get; set; } = [];
+}

PrCopilot/src/PrCopilot/Tools/FailedCheckContext.cs

@@ -0,0 +1,20 @@
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+
+namespace PrCopilot.Tools;
+
+/// <summary>
+/// A single failed CI check entry in <see cref="CiFailureContext.FailedChecks"/>.
+/// </summary>
+internal sealed class FailedCheckContext
+{
+    [JsonPropertyName("name")]
+    public string Name { get; set; } = "";
+
+    [JsonPropertyName("conclusion")]
+    public string Conclusion { get; set; } = "";
+
+    [JsonPropertyName("url")]
+    public string Url { get; set; } = "";
+}