patchrelay 0.35.16 → 0.36.0

package/dist/run-orchestrator.js

@@ -33,6 +33,7 @@ function lowerCaseFirst(value) {
 const WORKFLOW_FILES = {
     implementation: "IMPLEMENTATION_WORKFLOW.md",
     review_fix: "REVIEW_WORKFLOW.md",
+    branch_upkeep: "REVIEW_WORKFLOW.md",
     ci_repair: "IMPLEMENTATION_WORKFLOW.md",
     queue_repair: "IMPLEMENTATION_WORKFLOW.md",
 };
@@ -151,6 +152,17 @@ function appendLinearContext(lines, context) {
         lines.push("## Human Follow-up Comment", "", userComment, "");
     }
 }
+function isRequestedChangesRunType(runType) {
+    return runType === "review_fix" || runType === "branch_upkeep";
+}
+function resolveRequestedChangesMode(runType, context) {
+    if (runType === "branch_upkeep") {
+        return "branch_upkeep";
+    }
+    return context?.reviewFixMode === "branch_upkeep" || context?.branchUpkeepRequired === true
+        ? "branch_upkeep"
+        : "address_review_feedback";
+}
 function readReviewFixComments(context) {
     const raw = context?.reviewComments;
     if (!Array.isArray(raw)) {
@@ -199,7 +211,7 @@ function appendStructuredReviewContext(lines, context) {
         lines.push("No inline review comments were captured for this review.", "");
         return;
     }
-    lines.push(`Inline review comments captured: ${reviewComments.length}`, "Resolve each comment below or verify it is already fixed on the current head before you stop.", "");
+    lines.push(`Inline review comments captured: ${reviewComments.length}`, "Resolve each comment below or verify it is already fixed on the current head before you stop.", "A requested-changes turn is only complete if you push a newer PR head or deliberately escalate because you are blocked.", "");
     for (const comment of reviewComments) {
         const location = comment.path
             ? `${comment.path}${comment.line !== undefined ? `:${comment.line}` : ""}${comment.side ? ` (${comment.side})` : ""}`
@@ -239,6 +251,8 @@ function resolveFollowUpWhy(runType, context) {
             return "An operator supplied new guidance for this issue.";
         case "review_changes_requested":
             return "GitHub review requested changes on the current PR head.";
+        case "branch_upkeep":
+            return "GitHub still shows the PR branch as needing upkeep after the requested code change was addressed.";
         case "settled_red_ci":
             return "Required CI settled red for the current PR head.";
         case "merge_steward_incident":
@@ -248,8 +262,11 @@ function resolveFollowUpWhy(runType, context) {
                 ? "This is the first implementation turn for the delegated issue."
                 : `This turn continues ${runType.replaceAll("_", " ")} work for the delegated issue.`;
         default:
-            if (runType === "review_fix")
-                return "This turn continues requested-changes work on the existing PR.";
+            if (isRequestedChangesRunType(runType)) {
+                return resolveRequestedChangesMode(runType, context) === "branch_upkeep"
+                    ? "This turn continues branch upkeep on the existing PR after requested changes."
+                    : "This turn continues requested-changes work on the existing PR.";
+            }
             if (runType === "ci_repair")
                 return "This turn continues CI repair work on the existing PR.";
             if (runType === "queue_repair")
@@ -261,13 +278,15 @@ function resolveFollowUpAction(runType, context) {
     if (context?.directReplyMode === true) {
         return "Apply the latest human answer, continue from the current branch/session context, and only ask another question if you are still blocked.";
     }
-    if (runType === "review_fix" && context?.branchUpkeepRequired === true) {
-        const baseBranch = typeof context.baseBranch === "string" ? context.baseBranch : "main";
-        return `Update the existing PR branch onto latest ${baseBranch}, resolve conflicts if needed, rerun narrow verification, and push the same branch.`;
+    if (isRequestedChangesRunType(runType) && resolveRequestedChangesMode(runType, context) === "branch_upkeep") {
+        const baseBranch = typeof context?.baseBranch === "string" ? context.baseBranch : "main";
+        return `Update the existing PR branch onto latest ${baseBranch}, resolve conflicts if needed, rerun narrow verification, and push a newer head on the same branch.`;
     }
     switch (runType) {
         case "review_fix":
-            return "Address the review feedback on the current PR branch, verify the fix, and push the same branch.";
+            return "Address the review feedback on the current PR branch, verify the fix, and push a newer head on the same branch.";
+        case "branch_upkeep":
+            return "Repair the existing PR branch after requested changes, rerun narrow verification, and push a newer head on the same branch.";
         case "ci_repair":
             return "Fix the failing CI root cause on the current PR branch, verify it locally, and push the same branch.";
         case "queue_repair":
@@ -373,6 +392,15 @@ function appendFollowUpPromptPrelude(lines, issue, runType, context) {
     appendFactFreshness(lines, issue, runType, context);
     appendAuthoritativeGitHubFacts(lines, issue, runType, context);
 }
+function appendRequestedChangesInstructions(lines, runType, context) {
+    if (resolveRequestedChangesMode(runType, context) === "branch_upkeep") {
+        const baseBranch = typeof context?.baseBranch === "string" ? context.baseBranch : "main";
+        lines.push("## Branch Upkeep After Requested Changes", "", "The requested code change may already be present, but the PR branch still needs upkeep before review can continue.", typeof context?.mergeStateStatus === "string" ? `Current merge state: ${String(context.mergeStateStatus)}` : "", "", "Steps:", `1. Update the existing PR branch onto latest ${baseBranch}.`, "2. Resolve conflicts or branch drift without reopening the review-feedback debate unless the merge introduces a new issue.", "3. Run the narrowest verification that proves the branch is healthy again.", "4. Commit and push a newer head on the existing PR branch.", "5. If you cannot produce a new pushed head, stop and surface the exact blocker.", "");
+        return;
+    }
+    lines.push("## Review Changes Requested", "", "A reviewer has requested changes on your PR. Address the feedback and push.", context?.reviewerName ? `Reviewer: ${String(context.reviewerName)}` : "", context?.reviewBody ? `\n## Review comment\n\n${String(context.reviewBody)}` : "", "", "Steps:", "1. Start with the structured review context below. Treat the inline review comments as the primary repair checklist for this turn.", "2. Check the current diff (`git diff origin/main`) — a prior rebase may have already resolved some concerns (e.g., scope-bundling from stale commits).", "3. For each review point: if already resolved on the current head, note why. If not, fix it.", "4. If the structured review context looks incomplete, inspect the latest GitHub review threads directly before deciding you are done.", "5. Run verification, commit, and push a newer head on the existing PR branch.", "6. Do not try to hand the same head back to review. If you cannot produce a new pushed head, stop and surface the blocker clearly.", "7. GitHub review happens after the new head is pushed and CI is green. Do not use `gh pr edit --add-reviewer` as part of this workflow.", "");
+    appendStructuredReviewContext(lines, context);
+}
 export function buildInitialRunPrompt(issue, runType, repoPath, context) {
     const lines = buildPromptHeader(issue);
     appendTaskObjective(lines, issue);
@@ -391,8 +419,8 @@ export function buildInitialRunPrompt(issue, runType, repoPath, context) {
             break;
         }
         case "review_fix":
-            lines.push("## Review Changes Requested", "", "A reviewer has requested changes on your PR. Address the feedback and push.", context?.reviewerName ? `Reviewer: ${String(context.reviewerName)}` : "", context?.reviewBody ? `\n## Review comment\n\n${String(context.reviewBody)}` : "", "", "Steps:", "1. Start with the structured review context below. Treat the inline review comments as the primary repair checklist for this turn.", "2. Check the current diff (`git diff origin/main`) — a prior rebase may have already resolved some concerns (e.g., scope-bundling from stale commits).", "3. For each review point: if already resolved on the current head, note why. If not, fix it.", "4. If the structured review context looks incomplete, inspect the latest GitHub review threads directly before deciding you are done.", "5. Run verification, commit and push.", "6. If you believe all concerns are resolved, request a re-review: `gh pr edit <PR#> --add-reviewer <reviewer>`.", "   Do NOT just post a comment saying \"resolved\" — the reviewer must re-review to dismiss the CHANGES_REQUESTED state.", "");
-            appendStructuredReviewContext(lines, context);
+        case "branch_upkeep":
+            appendRequestedChangesInstructions(lines, runType, context);
             break;
         case "queue_repair":
             appendQueueRepairContext(lines, context);
@@ -426,8 +454,8 @@ export function buildFollowUpRunPrompt(issue, runType, repoPath, context) {
             break;
         }
         case "review_fix":
-            lines.push("## Review Changes Requested", "", "A reviewer has requested changes on your PR. Address the feedback and push.", context?.reviewerName ? `Reviewer: ${String(context.reviewerName)}` : "", context?.reviewBody ? `\n## Review comment\n\n${String(context.reviewBody)}` : "", "", "Steps:", "1. Start with the structured review context below. Treat the inline review comments as the primary repair checklist for this turn.", "2. Check the current diff (`git diff origin/main`) — a prior rebase may have already resolved some concerns (e.g., scope-bundling from stale commits).", "3. For each review point: if already resolved on the current head, note why. If not, fix it.", "4. If the structured review context looks incomplete, inspect the latest GitHub review threads directly before deciding you are done.", "5. Run verification, commit and push.", "6. If you believe all concerns are resolved, request a re-review: `gh pr edit <PR#> --add-reviewer <reviewer>`.", "   Do NOT just post a comment saying \"resolved\" — the reviewer must re-review to dismiss the CHANGES_REQUESTED state.", "");
-            appendStructuredReviewContext(lines, context);
+        case "branch_upkeep":
+            appendRequestedChangesInstructions(lines, runType, context);
             break;
         case "queue_repair":
             appendQueueRepairContext(lines, context);
@@ -529,9 +557,9 @@ export class RunOrchestrator {
             eventType = "settled_red_ci";
             dedupeKey = `${dedupeScope ?? "wake"}:ci_repair:${issue.linearIssueId}:${issue.lastGitHubFailureSignature ?? issue.prHeadSha ?? "unknown-sha"}`;
         }
-        else if (runType === "review_fix") {
+        else if (runType === "review_fix" || runType === "branch_upkeep") {
             eventType = "review_changes_requested";
-            dedupeKey = `${dedupeScope ?? "wake"}:review_fix:${issue.linearIssueId}:${issue.prHeadSha ?? "unknown-sha"}`;
+            dedupeKey = `${dedupeScope ?? "wake"}:${runType}:${issue.linearIssueId}:${issue.prHeadSha ?? "unknown-sha"}`;
         }
         else {
             eventType = "delegated";
@@ -591,10 +619,14 @@ export class RunOrchestrator {
             return;
         }
         const { runType, context, resumeThread } = wake;
-        const effectiveContext = runType === "review_fix"
-            ? await this.resolveReviewFixWakeContext(issue, context, project)
+        const effectiveContext = isRequestedChangesRunType(runType)
+            ? await this.resolveRequestedChangesWakeContext(issue, runType, context, project)
             : context;
-        const isReviewFixBranchUpkeep = runType === "review_fix" && isBranchUpkeepRequired(effectiveContext);
+        const sourceHeadSha = typeof effectiveContext?.failureHeadSha === "string"
+            ? effectiveContext.failureHeadSha
+            : typeof effectiveContext?.headSha === "string"
+                ? effectiveContext.headSha
+                : issue.prHeadSha;
         // Check repair budgets
         if (runType === "ci_repair" && issue.ciRepairAttempts >= DEFAULT_CI_REPAIR_BUDGET) {
             this.escalate(issue, runType, `CI repair budget exhausted (${DEFAULT_CI_REPAIR_BUDGET} attempts)`);
@@ -604,7 +636,7 @@ export class RunOrchestrator {
             this.escalate(issue, runType, `Queue repair budget exhausted (${DEFAULT_QUEUE_REPAIR_BUDGET} attempts)`);
             return;
         }
-        if (runType === "review_fix" && !isReviewFixBranchUpkeep && issue.reviewFixAttempts >= DEFAULT_REVIEW_FIX_BUDGET) {
+        if (runType === "review_fix" && issue.reviewFixAttempts >= DEFAULT_REVIEW_FIX_BUDGET) {
             this.escalate(issue, runType, `Review fix budget exhausted (${DEFAULT_REVIEW_FIX_BUDGET} attempts)`);
             return;
         }
@@ -623,7 +655,7 @@ export class RunOrchestrator {
                 return;
             }
         }
-        if (runType === "review_fix" && !isReviewFixBranchUpkeep) {
+        if (runType === "review_fix") {
             const updated = this.db.upsertIssueWithLease({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, leaseId }, { projectId: issue.projectId, linearIssueId: issue.linearIssueId, reviewFixAttempts: issue.reviewFixAttempts + 1 });
             if (!updated) {
                 this.releaseIssueSessionLease(item.projectId, item.issueId);
@@ -652,6 +684,7 @@ export class RunOrchestrator {
                 projectId: item.projectId,
                 linearIssueId: item.issueId,
                 runType,
+                ...(sourceHeadSha ? { sourceHeadSha } : {}),
                 promptText: prompt,
             });
             const failureHeadSha = typeof effectiveContext?.failureHeadSha === "string"
@@ -668,7 +701,7 @@ export class RunOrchestrator {
                 worktreePath,
                 factoryState: runType === "implementation" ? "implementing"
                     : runType === "ci_repair" ? "repairing_ci"
-                        : runType === "review_fix" ? "changes_requested"
+                        : runType === "review_fix" || runType === "branch_upkeep" ? "changes_requested"
                             : runType === "queue_repair" ? "repairing_queue"
                                 : "implementing",
                 ...((runType === "ci_repair" || runType === "queue_repair") && failureSignature
@@ -772,6 +805,7 @@ export class RunOrchestrator {
             const message = error instanceof Error ? error.message : String(error);
             const lostLease = error instanceof Error && error.name === "IssueSessionLeaseLostError";
             if (!lostLease) {
+                const nextState = isRequestedChangesRunType(runType) ? "escalated" : "failed";
                 this.db.finishRunWithLease({ projectId: item.projectId, linearIssueId: item.issueId, leaseId }, run.id, {
                     status: "failed",
                     failureReason: message,
@@ -780,7 +814,7 @@ export class RunOrchestrator {
                     projectId: item.projectId,
                     linearIssueId: item.issueId,
                     activeRunId: null,
-                    factoryState: "failed",
+                    factoryState: nextState,
                 });
             }
             this.logger.error({ issueKey: issue.issueKey, runType, error: message }, `Failed to launch ${runType} run`);
@@ -949,6 +983,7 @@ export class RunOrchestrator {
         const completedTurnId = extractTurnId(notification.params);
         const status = resolveRunCompletionStatus(notification.params);
         if (status === "failed") {
+            const nextState = isRequestedChangesRunType(run.runType) ? "escalated" : "failed";
             const updated = this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, (lease) => {
                 this.db.finishRunWithLease(lease, run.id, {
                     status: "failed",
@@ -960,7 +995,7 @@ export class RunOrchestrator {
                     projectId: run.projectId,
                     linearIssueId: run.linearIssueId,
                     activeRunId: null,
-                    factoryState: "failed",
+                    factoryState: nextState,
                 });
                 return true;
             });
@@ -1012,6 +1047,26 @@ export class RunOrchestrator {
             this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
             return;
         }
+        const missingReviewFixHeadError = await this.verifyReviewFixAdvancedHead(run, freshIssue);
+        if (missingReviewFixHeadError) {
+            this.failRunAndClear(run, missingReviewFixHeadError, "escalated");
+            const failedIssue = this.db.getIssue(run.projectId, run.linearIssueId) ?? freshIssue;
+            this.feed?.publish({
+                level: "error",
+                kind: "turn",
+                issueKey: freshIssue.issueKey,
+                projectId: run.projectId,
+                stage: run.runType,
+                status: "same_head_review_handoff_blocked",
+                summary: missingReviewFixHeadError,
+            });
+            void this.linearSync.emitActivity(failedIssue, buildRunFailureActivity(run.runType, missingReviewFixHeadError));
+            void this.linearSync.syncSession(failedIssue, { activeRunType: run.runType });
+            this.linearSync.clearProgress(run.id);
+            this.activeThreadId = undefined;
+            this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
+            return;
+        }
         const publishedOutcomeError = await this.verifyPublishedRunOutcome(run, freshIssue);
         if (publishedOutcomeError) {
             this.failRunAndClear(run, publishedOutcomeError, "failed");
@@ -1192,6 +1247,36 @@ export class RunOrchestrator {
         const fresh = this.db.getIssue(issue.projectId, issue.linearIssueId);
         if (!fresh)
             return;
+        if (isRequestedChangesRunType(runType)) {
+            const updated = this.withHeldIssueSessionLease(fresh.projectId, fresh.linearIssueId, (lease) => {
+                this.db.clearPendingIssueSessionEventsWithLease(lease);
+                this.db.upsertIssueWithLease(lease, {
+                    projectId: fresh.projectId,
+                    linearIssueId: fresh.linearIssueId,
+                    pendingRunType: null,
+                    pendingRunContextJson: null,
+                    factoryState: "escalated",
+                });
+                return true;
+            });
+            if (!updated) {
+                this.logger.warn({ issueKey: fresh.issueKey, reason }, "Skipping review-fix recovery escalation after losing issue-session lease");
+                this.releaseIssueSessionLease(fresh.projectId, fresh.linearIssueId);
+                return;
+            }
+            this.logger.warn({ issueKey: fresh.issueKey, reason }, "Requested-changes run failed before a new head was published — escalating");
+            this.feed?.publish({
+                level: "error",
+                kind: "workflow",
+                issueKey: fresh.issueKey,
+                projectId: fresh.projectId,
+                stage: runType,
+                status: "escalated",
+                summary: `Requested-changes run failed before publishing a new head (${reason})`,
+            });
+            this.releaseIssueSessionLease(fresh.projectId, fresh.linearIssueId);
+            return;
+        }
         // If PR already merged, transition to done — no retry needed
         if (fresh.prState === "merged") {
             const updated = this.withHeldIssueSessionLease(fresh.projectId, fresh.linearIssueId, (lease) => {
@@ -1404,6 +1489,25 @@ export class RunOrchestrator {
                 this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
                 return;
             }
+            if (isRequestedChangesRunType(run.runType)) {
+                const interruptedMessage = "Requested-changes run was interrupted before PatchRelay could verify that a new PR head was published";
+                this.failRunAndClear(run, interruptedMessage, "escalated");
+                await this.restoreIdleWorktree(issue);
+                const failedIssue = this.db.getIssue(run.projectId, run.linearIssueId) ?? issue;
+                this.feed?.publish({
+                    level: "error",
+                    kind: "workflow",
+                    issueKey: issue.issueKey,
+                    projectId: run.projectId,
+                    stage: "review_fix",
+                    status: "escalated",
+                    summary: interruptedMessage,
+                });
+                void this.linearSync.emitActivity(failedIssue, buildRunFailureActivity(run.runType, interruptedMessage));
+                void this.linearSync.syncSession(failedIssue, { activeRunType: run.runType });
+                this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
+                return;
+            }
             const recoveredState = resolveRecoverablePostRunState(this.db.getIssue(run.projectId, run.linearIssueId) ?? issue);
             this.failRunAndClear(run, "Codex turn was interrupted", recoveredState);
             await this.restoreIdleWorktree(issue);
@@ -1450,6 +1554,24 @@ export class RunOrchestrator {
                 this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
                 return;
             }
+            const missingReviewFixHeadError = await this.verifyReviewFixAdvancedHead(run, freshIssue);
+            if (missingReviewFixHeadError) {
+                this.failRunAndClear(run, missingReviewFixHeadError, "escalated");
+                const failedIssue = this.db.getIssue(run.projectId, run.linearIssueId) ?? freshIssue;
+                this.feed?.publish({
+                    level: "error",
+                    kind: "turn",
+                    issueKey: freshIssue.issueKey,
+                    projectId: run.projectId,
+                    stage: run.runType,
+                    status: "same_head_review_handoff_blocked",
+                    summary: missingReviewFixHeadError,
+                });
+                void this.linearSync.emitActivity(failedIssue, buildRunFailureActivity(run.runType, missingReviewFixHeadError));
+                void this.linearSync.syncSession(failedIssue, { activeRunType: run.runType });
+                this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
+                return;
+            }
             const publishedOutcomeError = await this.verifyPublishedRunOutcome(run, freshIssue);
             if (publishedOutcomeError) {
                 this.failRunAndClear(run, publishedOutcomeError, "failed");
@@ -1556,6 +1678,7 @@ export class RunOrchestrator {
             if (issue.activeRunId) {
                 this.db.finishRunWithLease(lease, issue.activeRunId, { status: "released" });
             }
+            this.db.clearPendingIssueSessionEventsWithLease(lease);
             this.db.upsertIssueWithLease(lease, {
                 projectId: issue.projectId,
                 linearIssueId: issue.linearIssueId,
@@ -1589,8 +1712,11 @@ export class RunOrchestrator {
         this.releaseIssueSessionLease(issue.projectId, issue.linearIssueId);
     }
     failRunAndClear(run, message, nextState = "failed") {
-        const updated = this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, () => {
+        const updated = this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, (lease) => {
             this.db.finishRun(run.id, { status: "failed", failureReason: message });
+            if (nextState === "failed" || nextState === "escalated" || nextState === "awaiting_input" || nextState === "done") {
+                this.db.clearPendingIssueSessionEventsWithLease(lease);
+            }
             this.db.upsertIssue({
                 projectId: run.projectId,
                 linearIssueId: run.linearIssueId,
@@ -1642,8 +1768,43 @@ export class RunOrchestrator {
             return undefined;
         }
     }
+    async verifyReviewFixAdvancedHead(run, issue) {
+        if (!isRequestedChangesRunType(run.runType)) {
+            return undefined;
+        }
+        if (!issue.prNumber || issue.prState !== "open") {
+            return undefined;
+        }
+        if (!run.sourceHeadSha) {
+            return `Requested-changes run finished for PR #${issue.prNumber} without a recorded starting head SHA. PatchRelay cannot verify that a new head was published.`;
+        }
+        const project = this.config.projects.find((entry) => entry.id === run.projectId);
+        if (!project?.github?.repoFullName) {
+            return undefined;
+        }
+        try {
+            const pr = await this.loadRemotePrState(project.github.repoFullName, issue.prNumber);
+            if (!pr || pr.state?.toUpperCase() !== "OPEN")
+                return undefined;
+            if (!pr.headRefOid) {
+                return `Requested-changes run finished for PR #${issue.prNumber} but GitHub did not report a current head SHA.`;
+            }
+            if (pr.headRefOid === run.sourceHeadSha) {
+                return `Requested-changes run finished for PR #${issue.prNumber} without pushing a new head; PatchRelay must not hand the same SHA back to review.`;
+            }
+            return undefined;
+        }
+        catch (error) {
+            this.logger.debug({
+                issueKey: issue.issueKey,
+                prNumber: issue.prNumber,
+                error: error instanceof Error ? error.message : String(error),
+            }, "Failed to verify PR head advancement after requested-changes work");
+            return undefined;
+        }
+    }
     async refreshIssueAfterReactivePublish(run, issue) {
-        if (run.runType !== "ci_repair" && run.runType !== "queue_repair") {
+        if (run.runType !== "ci_repair" && run.runType !== "queue_repair" && !isRequestedChangesRunType(run.runType)) {
             return this.db.getIssue(run.projectId, run.linearIssueId) ?? issue;
         }
         if (!issue.prNumber) {
@@ -1663,13 +1824,15 @@ export class RunOrchestrator {
             const nextReviewState = normalizeRemoteReviewDecision(pr.reviewDecision);
             const gateCheckName = project?.gateChecks?.find((entry) => entry.trim())?.trim() ?? "verify";
             const headAdvanced = Boolean(pr.headRefOid && pr.headRefOid !== issue.lastGitHubFailureHeadSha);
+            const reviewFixHeadAdvanced = isRequestedChangesRunType(run.runType)
+                && Boolean(pr.headRefOid && run.sourceHeadSha && pr.headRefOid !== run.sourceHeadSha);
             this.upsertIssueIfLeaseHeld(run.projectId, run.linearIssueId, {
                 projectId: run.projectId,
                 linearIssueId: run.linearIssueId,
                 ...(nextPrState ? { prState: nextPrState } : {}),
                 ...(pr.headRefOid ? { prHeadSha: pr.headRefOid } : {}),
                 ...(nextReviewState ? { prReviewState: nextReviewState } : {}),
-                ...(headAdvanced
+                ...((headAdvanced || reviewFixHeadAdvanced)
                     ? {
                         prCheckStatus: "pending",
                         lastGitHubFailureSource: null,
@@ -1710,8 +1873,8 @@ export class RunOrchestrator {
             return undefined;
         return JSON.parse(stdout);
     }
-    async resolveReviewFixWakeContext(issue, context, project) {
-        if (isBranchUpkeepRequired(context)) {
+    async resolveRequestedChangesWakeContext(issue, runType, context, project) {
+        if (runType === "branch_upkeep" || isBranchUpkeepRequired(context)) {
             return context;
         }
         if (!issue.prNumber || issue.prState !== "open" || issue.prReviewState !== "changes_requested") {
@@ -1747,7 +1910,7 @@ export class RunOrchestrator {
                 issueKey: issue.issueKey,
                 prNumber: issue.prNumber,
                 error: error instanceof Error ? error.message : String(error),
-            }, "Failed to resolve review-fix wake context");
+            }, "Failed to resolve requested-changes wake context");
             return context;
         }
     }
@@ -1786,7 +1949,7 @@ export class RunOrchestrator {
             if (!isDirtyMergeStateStatus(pr.mergeStateStatus))
                 return undefined;
             return {
-                pendingRunType: "review_fix",
+                pendingRunType: "branch_upkeep",
                 factoryState: "changes_requested",
                 context: buildReviewFixBranchUpkeepContext(issue.prNumber, project?.github?.baseBranch ?? "main", pr),
                 summary: `PR #${issue.prNumber} is still dirty after review fix; queued branch upkeep`,
@@ -2135,13 +2298,15 @@ function isDirtyMergeStateStatus(value) {
 }
 function buildReviewFixBranchUpkeepContext(prNumber, baseBranch, pr, context) {
     const promptContext = [
-        `The requested review change is already addressed, but GitHub still reports PR #${prNumber} as ${String(pr.mergeStateStatus)} against latest ${baseBranch}.`,
-        `Before stopping, update the existing PR branch onto latest ${baseBranch}, resolve any conflicts, rerun the narrowest relevant verification, and push again.`,
-        "Do not stop just because the requested code change is already present.",
+        `The requested code change may already be present, but GitHub still reports PR #${prNumber} as ${String(pr.mergeStateStatus)} against latest ${baseBranch}.`,
+        `This turn is branch upkeep on the existing PR branch: update onto latest ${baseBranch}, resolve any conflicts, rerun the narrowest relevant verification, and push a newer head.`,
+        "Do not stop just because the requested code change is already present. Review can only move forward after a new pushed head.",
     ].join(" ");
     return {
         ...(context ?? {}),
         branchUpkeepRequired: true,
+        reviewFixMode: "branch_upkeep",
+        wakeReason: "branch_upkeep",
         promptContext,
         ...(pr.mergeStateStatus ? { mergeStateStatus: pr.mergeStateStatus } : {}),
         ...(pr.headRefOid ? { failingHeadSha: pr.headRefOid } : {}),

package/dist/service.js

@@ -362,7 +362,7 @@ export class PatchRelayService {
           s.project_id, s.linear_issue_id, s.issue_key, i.title,
           i.current_linear_state, i.factory_state, s.session_state, s.waiting_reason, s.summary_text, s.updated_at,
           i.pending_run_type,
-          i.pr_number, i.pr_review_state, i.pr_check_status,
+          i.pr_number, i.pr_head_sha, i.pr_review_state, i.pr_check_status, i.last_blocking_review_head_sha,
           i.last_github_ci_snapshot_json,
           i.last_github_failure_source,
           i.last_github_failure_head_sha,
@@ -452,8 +452,10 @@ export class PatchRelayService {
                 factoryState: String(row.factory_state ?? "delegated"),
                 ...(row.pending_run_type !== null ? { pendingRunType: String(row.pending_run_type) } : {}),
                 ...(row.pr_number !== null ? { prNumber: Number(row.pr_number) } : {}),
+                ...(row.pr_head_sha !== null ? { prHeadSha: String(row.pr_head_sha) } : {}),
                 ...(row.pr_review_state !== null ? { prReviewState: String(row.pr_review_state) } : {}),
                 ...(row.pr_check_status !== null ? { prCheckStatus: String(row.pr_check_status) } : {}),
+                ...(row.last_blocking_review_head_sha !== null ? { lastBlockingReviewHeadSha: String(row.last_blocking_review_head_sha) } : {}),
                 ...(row.last_github_failure_check_name !== null ? { latestFailureCheckName: String(row.last_github_failure_check_name) } : {}),
             });
             const latestRun = row.latest_run_type !== null && row.latest_run_status !== null
@@ -614,6 +616,7 @@ export class PatchRelayService {
             return undefined;
         if (issue.activeRunId)
             return { error: "Issue already has an active run" };
+        const issueSession = this.db.getIssueSession(issue.projectId, issue.linearIssueId);
         if (issue.prState === "merged") {
             this.db.upsertIssueRespectingActiveLease(issue.projectId, issue.linearIssueId, {
                 projectId: issue.projectId,
@@ -634,7 +637,9 @@ export class PatchRelayService {
             factoryState = "repairing_ci";
         }
         else if (issue.prNumber && issue.prReviewState === "changes_requested") {
-            runType = "review_fix";
+            runType = issue.pendingRunType === "branch_upkeep" || issueSession?.lastRunType === "branch_upkeep"
+                ? "branch_upkeep"
+                : "review_fix";
             factoryState = "changes_requested";
         }
         else if (issue.prNumber) {
@@ -693,16 +698,19 @@ export class PatchRelayService {
             });
             return;
         }
-        if (runType === "review_fix") {
+        if (runType === "review_fix" || runType === "branch_upkeep") {
             this.db.appendIssueSessionEventRespectingActiveLease(issue.projectId, issue.linearIssueId, {
                 projectId: issue.projectId,
                 linearIssueId: issue.linearIssueId,
                 eventType: "review_changes_requested",
                 eventJson: JSON.stringify({
-                    reviewBody: "Operator requested retry of review-fix work.",
+                    reviewBody: runType === "branch_upkeep"
+                        ? "Operator requested retry of branch upkeep after requested changes."
+                        : "Operator requested retry of review-fix work.",
+                    ...(runType === "branch_upkeep" ? { branchUpkeepRequired: true, wakeReason: "branch_upkeep" } : {}),
                     source: "operator_retry",
                 }),
-                dedupeKey: `operator_retry:review_fix:${issue.linearIssueId}:${issue.prHeadSha ?? "unknown-sha"}`,
+                dedupeKey: `operator_retry:${runType}:${issue.linearIssueId}:${issue.prHeadSha ?? "unknown-sha"}`,
             });
             return;
         }

package/dist/waiting-reason.js

@@ -2,7 +2,8 @@ export const PATCHRELAY_WAITING_REASONS = {
     activeWork: "PatchRelay is actively working",
     waitingForOperatorInput: "Waiting on operator input",
     waitingForReviewFeedback: "Waiting to address review feedback",
-    waitingForRereview: "Waiting on re-review after requested changes",
+    waitingForReviewOnNewHead: "Waiting on review of a newer pushed head",
+    sameHeadStillBlocked: "Requested changes still block the current head",
     waitingForMergeStewardRepair: "Waiting to repair a merge-steward incident",
     waitingForDownstreamAutomation: "Waiting on downstream review/merge automation",
     workComplete: "PatchRelay work is complete",
@@ -45,7 +46,12 @@ export function derivePatchRelayWaitingReason(params) {
     }
     if (params.prReviewState === "changes_requested") {
         if (params.prCheckStatus === "passed" || params.prCheckStatus === "success") {
-            return PATCHRELAY_WAITING_REASONS.waitingForRereview;
+            if (params.prHeadSha
+                && params.lastBlockingReviewHeadSha
+                && params.prHeadSha !== params.lastBlockingReviewHeadSha) {
+                return PATCHRELAY_WAITING_REASONS.waitingForReviewOnNewHead;
+            }
+            return PATCHRELAY_WAITING_REASONS.sameHeadStillBlocked;
         }
         return PATCHRELAY_WAITING_REASONS.waitingForReviewFeedback;
     }