feat(execution): execution_approved wake reason + self-approval fallback

- Emit an 'execution_approved' wake for the return-assignee agent when
  the execution workflow completes, so the executor gets a clean
  acknowledgement cycle instead of silently leaving the issue done
- Update renderPaperclipWakePrompt to produce a distinct prompt when
  lastDecisionOutcome === 'approved' (tell the agent the work was
  accepted and to wrap up handoff notes)
- Add 'execution_approved' to shouldResetTaskSessionForWake and
  describeSessionResetReason so the new wake type resets the task
  session consistently with other workflow transitions
- Fix selectStageParticipant to fall back to the full participant pool
  when excluding the return assignee would produce an empty set — lets
  an executor self-approve when the execution policy lists only that
  participant on the stage
- Add a regression test for the self-approval fallback

Author: ramonmatias19

packages/adapter-utils/src/server-utils.ts

@@ -689,11 +689,19 @@ export function renderPaperclipWakePrompt(
         "",
       );
     } else if (executionStage.wakeRole === "executor") {
-      lines.push(
-        "You are waking because changes were requested in the execution workflow.",
-        "Address the requested changes on this issue and resubmit when the work is ready.",
-        "",
-      );
+      if (executionStage.lastDecisionOutcome === "approved") {
+        lines.push(
+          "Your submitted work on this issue was APPROVED and the execution workflow is complete.",
+          "Acknowledge the approval, wrap up any remaining handoff notes, and do not continue executor work on this issue.",
+          "",
+        );
+      } else {
+        lines.push(
+          "You are waking because changes were requested in the execution workflow.",
+          "Address the requested changes on this issue and resubmit when the work is ready.",
+          "",
+        );
+      }
     }
   }
 

server/src/__tests__/issue-execution-policy.test.ts

@@ -1261,4 +1261,79 @@ describe("issue execution policy transitions", () => {
       });
     });
   });
+
+  describe("single-participant stage coinciding with return assignee", () => {
+    it("starts workflow by falling back to the sole participant even if it is the return assignee", () => {
+      const policy = makePolicy([
+        { type: "approval", participants: [{ type: "agent", agentId: coderAgentId }] },
+      ]);
+      const result = applyIssueExecutionPolicyTransition({
+        issue: {
+          status: "in_progress",
+          assigneeAgentId: coderAgentId,
+          assigneeUserId: null,
+          executionPolicy: policy,
+          executionState: null,
+        },
+        policy,
+        requestedStatus: "done",
+        requestedAssigneePatch: {},
+        actor: { agentId: coderAgentId },
+        commentBody: "Self-approval allowed because policy lists only this participant",
+      });
+
+      expect(result.patch).toMatchObject({
+        status: "in_review",
+        assigneeAgentId: coderAgentId,
+        executionState: {
+          status: "pending",
+          currentStageType: "approval",
+          currentParticipant: { type: "agent", agentId: coderAgentId },
+        },
+      });
+    });
+
+    it("advances to a next stage whose sole participant is the return assignee", () => {
+      const policy = makePolicy([
+        { type: "review", participants: [{ type: "agent", agentId: qaAgentId }] },
+        { type: "approval", participants: [{ type: "agent", agentId: coderAgentId }] },
+      ]);
+      const reviewStageId = policy.stages[0].id;
+      const result = applyIssueExecutionPolicyTransition({
+        issue: {
+          status: "in_review",
+          assigneeAgentId: qaAgentId,
+          assigneeUserId: null,
+          executionPolicy: policy,
+          executionState: {
+            status: "pending",
+            currentStageId: reviewStageId,
+            currentStageIndex: 0,
+            currentStageType: "review",
+            currentParticipant: { type: "agent", agentId: qaAgentId },
+            returnAssignee: { type: "agent", agentId: coderAgentId },
+            completedStageIds: [],
+            lastDecisionId: null,
+            lastDecisionOutcome: null,
+          },
+        },
+        policy,
+        requestedStatus: "done",
+        requestedAssigneePatch: {},
+        actor: { agentId: qaAgentId },
+        commentBody: "QA signoff",
+      });
+
+      expect(result.patch).toMatchObject({
+        status: "in_review",
+        assigneeAgentId: coderAgentId,
+        executionState: {
+          status: "pending",
+          currentStageType: "approval",
+          currentParticipant: { type: "agent", agentId: coderAgentId },
+        },
+      });
+      expect(result.decision?.outcome).toBe("approved");
+    });
+  });
 });

server/src/routes/issues.ts

@@ -372,6 +372,45 @@ function buildExecutionStageWakeup(input: {
     };
   }
 
+  if (nextState.status === "completed") {
+    const agentId = nextState.returnAssignee?.type === "agent" ? (nextState.returnAssignee.agentId ?? null) : null;
+    const becameCompleted =
+      previousState?.status !== "completed" ||
+      previousState?.lastDecisionId !== nextState.lastDecisionId;
+    if (!agentId || !becameCompleted) return null;
+
+    const executionStage = buildExecutionStageWakeContext({
+      state: nextState,
+      wakeRole: "executor",
+      allowedActions: ["acknowledge_completion"],
+    });
+
+    return {
+      agentId,
+      wakeup: {
+        source: "assignment" as const,
+        triggerDetail: "system" as const,
+        reason: "execution_approved",
+        payload: {
+          issueId,
+          mutation: "update",
+          executionStage,
+          ...(interruptedRunId ? { interruptedRunId } : {}),
+        },
+        requestedByActorType: input.requestedByActorType,
+        requestedByActorId: input.requestedByActorId,
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          wakeReason: "execution_approved",
+          source: "issue.execution_stage",
+          executionStage,
+          ...(interruptedRunId ? { interruptedRunId } : {}),
+        },
+      },
+    };
+  }
+
   return null;
 }
 

server/src/services/heartbeat.ts

@@ -1326,7 +1326,8 @@ export function shouldResetTaskSessionForWake(
     wakeReason === "issue_assigned" ||
     wakeReason === "execution_review_requested" ||
     wakeReason === "execution_approval_requested" ||
-    wakeReason === "execution_changes_requested"
+    wakeReason === "execution_changes_requested" ||
+    wakeReason === "execution_approved"
   ) {
     return true;
   }
@@ -1401,6 +1402,7 @@ function describeSessionResetReason(
   if (wakeReason === "execution_review_requested") return "wake reason is execution_review_requested";
   if (wakeReason === "execution_approval_requested") return "wake reason is execution_approval_requested";
   if (wakeReason === "execution_changes_requested") return "wake reason is execution_changes_requested";
+  if (wakeReason === "execution_approved") return "wake reason is execution_approved";
   return null;
 }
 

server/src/services/issue-execution-policy.ts

@@ -403,10 +403,26 @@ export function applyIssueExecutionPolicyTransition(input: TransitionInput): Tra
           };
         }
 
-        const participant = selectStageParticipant(nextStage, {
+        let participant = selectStageParticipant(nextStage, {
           preferred: explicitAssignee,
           exclude: existingState?.returnAssignee ?? null,
         });
+        // Fall back to the return assignee when the next stage has no other
+        // eligible participants and cannot be auto-skipped — the policy
+        // lists only the return assignee on this stage, so self-approval is
+        // intentional. Skippable stages (e.g. review with only the return
+        // assignee) are handled by the start-workflow skip loop on the
+        // next transition instead.
+        if (
+          !participant &&
+          !canAutoSkipPendingStage({
+            stage: nextStage,
+            returnAssignee: existingState?.returnAssignee ?? null,
+            requestedStatus,
+          })
+        ) {
+          participant = selectStageParticipant(nextStage, { preferred: explicitAssignee });
+        }
         if (!participant) {
           throw unprocessable(`No eligible ${nextStage.type} participant is configured for this issue`);
         }
@@ -502,13 +518,26 @@ export function applyIssueExecutionPolicyTransition(input: TransitionInput): Tra
 
   const returnAssignee = existingState?.returnAssignee ?? currentAssignee;
   const skippedStageIds = [...(existingState?.completedStageIds ?? [])];
+  const selectPreferred =
+    existingState?.status === CHANGES_REQUESTED_STATUS
+      ? explicitAssignee ?? existingState.currentParticipant ?? null
+      : explicitAssignee;
   let participant = selectStageParticipant(pendingStage, {
-    preferred:
-      existingState?.status === CHANGES_REQUESTED_STATUS
-        ? explicitAssignee ?? existingState.currentParticipant ?? null
-        : explicitAssignee,
+    preferred: selectPreferred,
     exclude: returnAssignee,
   });
+  // When the pending stage's only eligible participant is the return
+  // assignee and the stage cannot be auto-skipped (e.g. an approval stage),
+  // fall back to self-assignment — policies that list only one participant
+  // on a non-skippable stage imply self-approval is intentional.
+  if (
+    !participant &&
+    !canAutoSkipPendingStage({ stage: pendingStage, returnAssignee, requestedStatus })
+  ) {
+    participant = selectStageParticipant(pendingStage, {
+      preferred: selectPreferred,
+    });
+  }
   while (!participant && canAutoSkipPendingStage({ stage: pendingStage, returnAssignee, requestedStatus })) {
     skippedStageIds.push(pendingStage.id);
     pendingStage = nextPendingStage(