pr-shepherd 0.45.0 → 0.46.0

package/bin/commands/iterate/api-usage.mjs

@@ -3,11 +3,7 @@ import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
 import { evaluateWorktreeGraphqlQuotaWarning } from "../../state/graphql-quota-warnings.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
-    if (["wait", "mark_ready", "merge"].includes(result.action))
-        return true;
-    if (result.action !== "fix_code")
-        return false;
-    return !result.fix.instructions.some((instruction) => /stop polling|human direction/i.test(instruction));
+    return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
 }
 export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false) {
     const apiUsage = summarizeApiTelemetry();
@@ -34,9 +30,6 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
         if (/\[FIX_CODE\].*non-terminal/i.test(completion)) {
             instructions[instructions.length - 1] = buildQuotaAwareContinuation(quotaWarning, "`[FIX_CODE]` is non-terminal. After completing these steps,");
         }
-        else if (/\[FIX_CODE\].*is conditional:.*if you did not change code,/i.test(completion)) {
-            instructions[instructions.length - 1] = completion.replace(/if you did not change code,(.*?)\s+and iterate again with the same options\./i, (_, before) => `if you did not change code,${before.trimEnd()}. ${buildQuotaAwareContinuation(quotaWarning, "").trimStart()}`);
-        }
     }
     return { ...withWarning, fix: { ...withWarning.fix, instructions } };
 }

package/bin/commands/iterate/check-instructions.d.mts

@@ -27,7 +27,7 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
  * command run unmodified is already correct for them. The pointer below is load-bearing:
  * without it, nothing in CLI output tells the agent that playbook exists.
  */
-export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand, pushAuthorized?: boolean): string[];
+export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
 /** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
-export declare function buildFixCompletionInstruction(checks: AgentCheck[], requiresRemoteUpdateAuthorization?: boolean, hasShaGatedReviewMutations?: boolean, pushAuthorized?: boolean): string;
+export declare function buildFixCompletionInstruction(checks: AgentCheck[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -36,7 +36,7 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
  * command run unmodified is already correct for them. The pointer below is load-bearing:
  * without it, nothing in CLI output tells the agent that playbook exists.
  */
-export function buildResolveCommandInstruction(resolveCommand, pushAuthorized = false) {
+export function buildResolveCommandInstruction(resolveCommand) {
     if (!resolveCommand.hasMutations)
         return [];
     const instructions = [];
@@ -44,9 +44,7 @@ export function buildResolveCommandInstruction(resolveCommand, pushAuthorized =
         instructions.push("Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an established Shepherd reply; a marked viewer-authored human thread is emitted resolve-only, not for another reply.");
     }
     if (resolveCommand.requiresHeadSha) {
-        instructions.push(pushAuthorized
-            ? "If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA."
-            : "If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, do not run this command until an authorized push updates the remote PR head; then replace `$HEAD_SHA` with that pushed commit SHA.");
+        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.");
     }
     if (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
@@ -69,39 +67,17 @@ export function buildFailingCheckInstructions(checks) {
         instructions.push('A `[rerun authorized]` check includes a `rerun:` command. See "CI failure triage" in the pr-shepherd skill for which conclusions warrant a rerun versus a code fix.');
     }
     if (hasBare) {
-        instructions.push("For each `(no runId)` failure, escalate to a human because no log or URL is available.");
+        instructions.push("For each `(no runId)` failure, preserve the displayed metadata; Shepherd will escalate when no other autonomous work remains.");
     }
     return instructions;
 }
-export function buildFixCompletionInstruction(checks, requiresRemoteUpdateAuthorization = false, hasShaGatedReviewMutations = false, pushAuthorized = false) {
-    if (requiresRemoteUpdateAuthorization) {
-        if (pushAuthorized) {
-            return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate again with the same options.";
-        }
-        return "`[FIX_CODE]` requires a human handoff for an authorized push after conflict resolution. Shepherd cannot verify the Git credential's push authorization. Stop polling after committing, and resume only after the remote PR head changes.";
-    }
-    const hasUninspectableFailure = checks.some((check) => !check.runId && !check.detailsUrl);
-    if (hasUninspectableFailure) {
-        return "`[FIX_CODE]` requires a human handoff for an uninspectable failing check. Stop polling after escalating, and resume only after human direction.";
-    }
-    // Checks that would otherwise need a workflow-run mutation (rerun) to move forward.
-    // `rerunCommand` is only populated when the viewer's repository role grants Actions
-    // rerun capability (see canRerunWorkflows) — unauthorized checks stay a terminal handoff.
-    const ciHandoffChecks = checks.filter((check) => check.conclusion === "CANCELLED" ||
-        check.conclusion === "STARTUP_FAILURE" ||
-        (check.runId === null && Boolean(check.detailsUrl)) ||
-        (check.runId !== null && !check.logExcerpt?.trim()));
-    const hasUnauthorizedCiHandoff = ciHandoffChecks.some((check) => !check.rerunCommand);
-    if (hasUnauthorizedCiHandoff) {
-        return "`[FIX_CODE]` requires a human handoff for a failing check with no authorized follow-up action. Stop polling after escalating, and resume only after human direction.";
-    }
+export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false) {
+    if (hasConflicts)
+        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate again with the same options.";
     if (hasShaGatedReviewMutations) {
-        if (pushAuthorized) {
-            return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate again with the same options; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
-        }
-        return "`[FIX_CODE]` is conditional: if you changed code, stop after committing and resume only after an authorized push changes the remote PR head; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
+        return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate again with the same options; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
     }
-    if (ciHandoffChecks.some((check) => check.rerunCommand)) {
+    if (checks.some((check) => check.rerunCommand)) {
         return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate again with the same options to continue.";
     }
     return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";

package/bin/commands/iterate/classify.mjs

@@ -67,7 +67,8 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     const canResolve = new Set(authorizationThreads
         .filter((thread) => thread.viewerCanResolve === true)
         .map((thread) => thread.id));
-    const replyThreadIds = routed.replyThreadIds.filter((id) => canReply.has(id));
+    const pairedResolveIds = new Set(routed.pairedResolveThreadIds);
+    const replyThreadIds = routed.replyThreadIds.filter((id) => canReply.has(id) && (!pairedResolveIds.has(id) || canResolve.has(id)));
     // Viewer-authored human resolves stay paired with an authorized reply. Marker-ended
     // viewer-authored retries and bot/non-human resolves need only resolve authorization.
     const pairedResolveThreadIds = routed.pairedResolveThreadIds.filter((id) => canReply.has(id) && canResolve.has(id));

package/bin/commands/iterate/escalate.mjs

@@ -2,6 +2,61 @@ import { loadConfig } from "../../config/load.mjs";
 function renderEscalateAuthor(item) {
     return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
 }
+function renderCheckTarget(check) {
+    const parts = [];
+    if (check.runId)
+        parts.push(`run \`${check.runId}\``);
+    if (check.detailsUrl)
+        parts.push(`URL \`${check.detailsUrl}\``);
+    return parts.length > 0 ? parts.join(", ") : "no run ID or URL";
+}
+function renderCheckScope(check) {
+    if (!check.scope)
+        return "";
+    const commit = check.commitOid ? ` at \`${check.commitOid}\`` : "";
+    return `, scope \`${check.scope}\`${commit}`;
+}
+function renderBlockquoteLines(value, indent) {
+    return value.split("\n").map((line) => `${indent}> ${line}`);
+}
+function renderEscalateAnnotation(annotation) {
+    const start = annotation.startLine ?? annotation.endLine ?? "?";
+    const end = annotation.endLine ?? annotation.startLine ?? "?";
+    const range = start === end ? String(start) : `${start}-${end}`;
+    const columns = annotation.startColumn == null && annotation.endColumn == null
+        ? ""
+        : `, columns ${annotation.startColumn ?? "?"}-${annotation.endColumn ?? "?"}`;
+    const title = annotation.title ? ` — ${annotation.title}` : "";
+    const link = annotation.blobUrl ? ` [source](${annotation.blobUrl})` : "";
+    const lines = [
+        `  - annotation \`${annotation.id}\`${link} — \`${annotation.path}:${range}\` [${annotation.level}${columns}]${title}`,
+        ...renderBlockquoteLines(annotation.message, "    "),
+    ];
+    if (annotation.rawDetails) {
+        lines.push(...renderBlockquoteLines(annotation.rawDetails, "    "));
+    }
+    return lines;
+}
+function renderEscalateCheck(check) {
+    const workflowPrefix = check.workflowName ? `${check.workflowName} › ` : "";
+    const jobLabel = check.jobName ?? check.name;
+    const conclusion = check.conclusion ?? "UNKNOWN";
+    const lines = [
+        `- ${renderCheckTarget(check)} — \`${workflowPrefix}${jobLabel}\` [conclusion: ${conclusion}]${renderCheckScope(check)}`,
+    ];
+    if (check.failedStep)
+        lines.push(`  > failed step: ${check.failedStep}`);
+    if (check.summary)
+        lines.push(`  > ${check.summary}`);
+    if (check.logExcerpt)
+        lines.push(...renderBlockquoteLines(check.logExcerpt, "  "));
+    if (check.rerunCommand)
+        lines.push(`  rerun: \`${check.rerunCommand}\``);
+    for (const annotation of check.annotations ?? []) {
+        lines.push(...renderEscalateAnnotation(annotation));
+    }
+    return lines;
+}
 export function checkEscalateTriggers(actionableThreads, threadAttempts) {
     const triggers = [];
     const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
@@ -10,11 +65,6 @@ export function checkEscalateTriggers(actionableThreads, threadAttempts) {
     if (thrashThreads.length > 0) {
         triggers.push("fix-thrash");
     }
-    // Trigger 2: actionable thread has no file/line — cannot locate code to edit.
-    const unlocatable = actionableThreads.filter((t) => t.path === null || t.line === null);
-    if (unlocatable.length > 0) {
-        triggers.push("thread-missing-location");
-    }
     return {
         triggers,
         thrashHistory: thrashThreads.length > 0
@@ -69,6 +119,7 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     const hasItems = escalate.unresolvedThreads.length > 0 ||
         escalate.changesRequestedReviews.length > 0 ||
         escalate.ambiguousComments.length > 0 ||
+        (escalate.checks?.length ?? 0) > 0 ||
         (escalate.stalledChecks?.length ?? 0) > 0;
     if (hasItems) {
         lines.push("");
@@ -86,6 +137,9 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         }
         if ((escalate.stalledChecks?.length ?? 0) > 0)
             lines.push("");
+        for (const check of escalate.checks ?? []) {
+            lines.push(...renderEscalateCheck(check), "");
+        }
         for (const t of escalate.unresolvedThreads) {
             const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
             lines.push(`- thread \`${t.id}\` — ${loc} (${renderEscalateAuthor(t)}):`);
@@ -144,8 +198,11 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
+    if (triggers.includes("check-follow-up-unavailable")) {
+        return "One or more failing checks have no autonomous follow-up available. Use the displayed conclusion, run or URL, and included evidence to handle them manually.";
+    }
     if (triggers.includes("authorization-required")) {
-        return "GitHub did not confirm that the current viewer may perform one or more required actions. Ask a repository maintainer to handle the listed items; Shepherd will not recommend commands that would be denied.";
+        return "GitHub did not confirm that the current viewer may perform the requested mark-ready or merge/enqueue operation. Ask a repository maintainer to perform that state change; Shepherd will not recommend a command that would be denied.";
     }
     if (triggers.includes("merge-queue-removed")) {
         const reason = detail ? ` GitHub reason: ${detail}.` : "";
@@ -162,9 +219,6 @@ export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("fix-thrash")) {
         return "Same thread(s) reached the automated attempt limit — treat this as a manual handoff. Apply the fix by hand.";
     }
-    if (triggers.includes("thread-missing-location")) {
-        return "Review thread has no file/line reference — automated location routing failed and manual handling is required.";
-    }
     if (triggers.includes("bot-cr-not-dismissed")) {
         const ids = detail ? ` (review IDs: ${detail})` : "";
         return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior apply command. Dismiss the review(s) manually (or re-run \`pr-shepherd apply review\` with the IDs) to unblock the PR.`;

package/bin/commands/iterate/fix-code.mjs

@@ -11,9 +11,23 @@ import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
-import { canRerunWorkflows, canPushToHead } from "../../checks/conclusions.mjs";
+import { canRerunWorkflows } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
+function checkRequiresHumanFollowUp(check) {
+    if (check.rerunCommand)
+        return false;
+    if (check.conclusion === "ACTION_REQUIRED" ||
+        check.conclusion === "CANCELLED" ||
+        check.conclusion === "STARTUP_FAILURE")
+        return true;
+    // An external check's direct URL is actionable evidence: the agent can inspect the
+    // provider and/or reproduce the reported failure locally. Only a truly bare check
+    // has no autonomous investigation path.
+    if (check.runId === null)
+        return !check.detailsUrl?.trim();
+    return !check.logExcerpt?.trim();
+}
 function nextFixAttempts(stored, headSha, threads) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
@@ -41,66 +55,17 @@ export async function handleFixCode(ctx) {
     ]);
     const replyIdSet = new Set(routedThreadMutations.replyThreadIds);
     const resolveIdSet = new Set(routedThreadMutations.resolveThreadIds);
-    const unauthorizedReplies = allThreads.filter((thread) => report.viewerAuthorization !== undefined &&
-        replyIdSet.has(thread.id) &&
-        thread.viewerCanReply !== true);
-    const unauthorizedResolves = allThreads.filter((thread) => report.viewerAuthorization !== undefined &&
-        resolveIdSet.has(thread.id) &&
-        thread.viewerCanResolve !== true);
-    const unauthorizedDismissals = report.changesRequestedReviews.filter((review) => report.viewerAuthorization !== undefined &&
-        (!isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames)) &&
+    const unauthorizedReplies = allThreads.filter((thread) => replyIdSet.has(thread.id) && thread.viewerCanReply !== true);
+    const unauthorizedResolves = allThreads.filter((thread) => resolveIdSet.has(thread.id) && thread.viewerCanResolve !== true);
+    const unauthorizedDismissals = report.changesRequestedReviews.filter((review) => (!isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames)) &&
         report.viewerAuthorization?.viewerCanAdminister !== true);
-    const authorization = [
-        ...(unauthorizedReplies.length > 0
-            ? [
-                {
-                    action: "reply-thread",
-                    targetIds: unauthorizedReplies.map((thread) => thread.id),
-                    reason: "denied-or-unverifiable",
-                },
-            ]
-            : []),
-        ...(unauthorizedResolves.length > 0
-            ? [
-                {
-                    action: "resolve-thread",
-                    targetIds: unauthorizedResolves.map((thread) => thread.id),
-                    reason: "denied-or-unverifiable",
-                },
-            ]
-            : []),
-        ...(unauthorizedDismissals.length > 0
-            ? [
-                {
-                    action: "dismiss-review",
-                    targetIds: unauthorizedDismissals.map((review) => review.id),
-                    reason: "denied-or-unverifiable",
-                },
-            ]
-            : []),
-    ];
-    if (authorization.length > 0) {
-        const authorizationEscalateBase = {
-            triggers: ["authorization-required"],
-            unresolvedThreads: allThreads.map(toAgentThread),
-            ambiguousComments: report.comments.actionable.map(toAgentComment),
-            changesRequestedReviews: report.changesRequestedReviews,
-            authorization,
-            suggestion: buildEscalateSuggestion(["authorization-required"]),
-        };
-        return {
-            ...base,
-            action: "escalate",
-            escalate: {
-                ...authorizationEscalateBase,
-                humanMessage: buildEscalateHumanMessage(authorizationEscalateBase, prReference),
-            },
-        };
-    }
+    const skippedThreadIds = new Set([...unauthorizedReplies, ...unauthorizedResolves].map((thread) => thread.id));
+    const retryableActionableThreads = report.threads.actionable.filter((thread) => !skippedThreadIds.has(thread.id) && thread.path !== null && thread.line !== null);
     const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
-    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
-    const botCrReviews = report.changesRequestedReviews.filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames));
+    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, retryableActionableThreads);
+    const botCrReviews = report.changesRequestedReviews.filter((r) => (!isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames)) &&
+        report.viewerAuthorization?.viewerCanAdminister === true);
     const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
     const previousBotCrState = await readBotCrSeenState(botCrStateKey);
     const nowSeconds = Math.floor(Date.now() / 1000);
@@ -121,11 +86,13 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference, {
+                    merge: opts.merge,
+                }),
             },
         };
     }
-    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, threadAttempts);
+    const escalateTriggers = checkEscalateTriggers(retryableActionableThreads, threadAttempts);
     if (escalateTriggers.triggers.length > 0) {
         const escalateBase = {
             triggers: escalateTriggers.triggers,
@@ -140,7 +107,9 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference, {
+                    merge: opts.merge,
+                }),
             },
         };
     }
@@ -183,40 +152,72 @@ export async function handleFixCode(ctx) {
         ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
     ];
     const { changesRequestedReviews } = report;
+    const actionableChangesRequestedReviews = changesRequestedReviews.filter((review) => review.staleReview !== true ||
+        !isHumanAuthor(review) ||
+        isConfiguredBotAuthor(review, botUsernames));
+    const skippedDismissalIds = new Set(unauthorizedDismissals.map((review) => review.id));
+    const changesRequestedReviewsForWork = actionableChangesRequestedReviews.filter((review) => !skippedDismissalIds.has(review.id));
+    const resolutionOnlyThreadsForWork = resolutionOnlyThreads.filter((thread) => !skippedThreadIds.has(thread.id) && thread.path !== null && thread.line !== null);
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
-    // Whether GitHub reports the viewer can push to the PR head branch (own-repo write
-    // access, or a fork with viewerCanEditFiles/head-repo write for a fork PR). Drives
-    // whether the fix instructions push autonomously or hand off for an authorized push —
-    // see canPushToHead.
-    const pushAuthorized = canPushToHead(report.viewerAuthorization);
     // Only surface in-progress runs when a push is plausible — resolution-only and
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    // Conflict resolution necessarily changes the branch head. When the viewer cannot push,
-    // Shepherd cannot verify authorization for the local Git credential that would publish
-    // it, so review mutations are deferred until an authorized push updates the PR and a
-    // fresh iteration can rebuild SHA-safe commands. When the viewer can push, the agent
-    // pushes as part of this fix_code tick, so mutations can be built normally (SHA-gated
-    // like any other push-requiring tick).
-    const { resolveCommand, resolveOnlyCommand } = hasConflicts && !pushAuthorized
-        ? buildResolveCommand([], [], [], [], [], prReference, botUsernames, [], undefined, [])
-        : buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
+    const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
+    const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
+    const hasAutonomousWork = hasConflicts ||
+        threads.length > 0 ||
+        resolutionOnlyThreads.length > 0 ||
+        actionableComments.length > 0 ||
+        commentMinimizeIds.length > 0 ||
+        actionableChangesRequestedReviews.length > 0 ||
+        reviewSummaryIds.length > 0 ||
+        firstLookSummaries.length > 0 ||
+        editedSummaries.length > 0 ||
+        report.threads.firstLook.length > 0 ||
+        report.comments.firstLook.length > 0 ||
+        checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
+        failingAgentChecks.some((check) => belongsToActiveWorkflowRun(check) || !checkRequiresHumanFollowUp(check));
+    if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
+        const checkEscalateBase = {
+            triggers: ["check-follow-up-unavailable"],
+            unresolvedThreads: [],
+            ambiguousComments: [],
+            changesRequestedReviews,
+            checks: manualFollowUpChecks,
+            suggestion: buildEscalateSuggestion(["check-follow-up-unavailable"]),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                ...checkEscalateBase,
+                humanMessage: buildEscalateHumanMessage(checkEscalateBase, prReference, {
+                    merge: opts.merge,
+                }),
+            },
+        };
+    }
+    // Push access to the PR head branch is a usage precondition. Build review mutations for
+    // conflict ticks normally so the caller can push and complete the same fix_code cycle.
+    const retryableActionableIds = new Set(retryableActionableThreads.map((thread) => thread.id));
+    const retryableAgentThreads = threads.filter((thread) => retryableActionableIds.has(thread.id));
+    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(retryableAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
     // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
     // resolution-only threads also need a known base in case the agent does push.
-    const pushIsPlausible = threads.length > 0 ||
+    const pushIsPlausible = retryableActionableThreads.length > 0 ||
         failingAgentChecks.length > 0 ||
         annotatedExtra.length > 0 ||
         hasConflicts ||
-        changesRequestedReviews.length > 0 ||
+        changesRequestedReviewsForWork.length > 0 ||
         actionableComments.length > 0 ||
-        resolutionOnlyThreads.length > 0;
+        resolutionOnlyThreadsForWork.length > 0;
     if (baseLookup.isFallback && pushIsPlausible) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
@@ -230,13 +231,15 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...fallbackEscalateBase,
-                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prReference),
+                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prReference, {
+                    merge: opts.merge,
+                }),
             },
         };
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, pushAuthorized);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -81,8 +81,8 @@ async function runIterateCore(opts) {
         editedSummaries.length > 0 ||
         (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
     const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
-    const isCleanReadyHandoff = report.status === "READY" && !hasActionableWork && !activeMerge;
-    const readyState = await updateReadyDelay(report.pr, isCleanReadyHandoff, readyDelaySeconds, repoOwner, repoName);
+    const isCleanReadyState = report.status === "READY" && !hasActionableWork && !activeMerge;
+    const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
     const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     if (hasActionableWork) {

package/bin/commands/iterate/render.d.mts

@@ -2,4 +2,4 @@ import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, Fir
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean, pushAuthorized?: boolean): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -11,8 +11,10 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
+isBehind = false, viewerCanUpdate = false) {
     const instructions = [];
+    const locatedThreads = threads.filter((thread) => thread.path !== null && thread.line !== null);
+    const unlocatedThreads = threads.filter((thread) => thread.path === null || thread.line === null);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
@@ -23,8 +25,10 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     // Start with interpretation. The agent decides what raw feedback warrants a code change.
     if (hasNonConflictHints) {
         const actionableSections = [];
-        if (threads.length > 0)
+        if (locatedThreads.length > 0)
             actionableSections.push("`## Review threads`");
+        if (unlocatedThreads.length > 0)
+            actionableSections.push("`## Unlocated review threads (logged once — no mutation)`");
         if (actionableComments.length > 0)
             actionableSections.push("`## Actionable comments`");
         if (failingChecks.length > 0)
@@ -53,17 +57,20 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     if (editedTotal > 0) {
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     }
+    if (unlocatedThreads.length > 0) {
+        instructions.push("Acknowledge each item under `## Unlocated review threads (logged once — no mutation)`. Shepherd cannot route a code fix or review mutation without a path and line; the unchanged item will be skipped on later ticks.");
+    }
     // GitHub exposes no exact viewer capability for workflow-run cancellation, so the
     // informational run lists never produce a cancellation recommendation.
     void inProgressRunIds;
     void cancelledCount;
-    const hasSuggestions = threads.some((t) => t.suggestion);
+    const hasSuggestions = locatedThreads.some((t) => t.suggestion);
     if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
-    if (threads.length > 0 || actionableComments.length > 0) {
+    if (locatedThreads.length > 0 || actionableComments.length > 0) {
         // Actionable comments carry no file/line location (unlike threads), so "referenced above"
         // is only accurate when threads are present.
-        const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
+        const filesRef = locatedThreads.length > 0 ? "each file referenced above" : "the relevant files";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
     }
     if (resolutionOnlyThreads.length > 0) {
@@ -81,14 +88,10 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts) {
-        instructions.push(pushAuthorized
-            ? `Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`
-            : `Commit any remaining conflict-resolution changes${mutationSuffix}.`);
+        instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
     }
     else if (hasNonConflictHints) {
-        instructions.push(pushAuthorized
-            ? "If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps."
-            : "If you changed code, commit any remaining changes, then stop and hand off for a push whose authorization is established outside Shepherd; do not run the remaining review mutations or iterate until the remote PR head changes. Shepherd cannot verify the Git credential's push authorization. If you did not change code, do not commit and continue with the remaining steps.");
+        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps.");
     }
     if (viewerCanUpdate &&
         (hasReviewMutations ||
@@ -100,7 +103,7 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand, pushAuthorized));
-    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha, pushAuthorized));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand));
+    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
     return instructions;
 }

package/bin/commands/poll.mjs

@@ -99,10 +99,7 @@ async function runPollCore(opts) {
             pendingQuotaWarning !== undefined &&
             !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
             !(debounceUntil !== null && !pastDebounce)) {
-            const terminalOrHandoff = ["cancel", "escalate"].includes(lastResult.action) ||
-                (lastResult.action === "fix_code" &&
-                    lastResult.fix.instructions.some((instruction) => /stop polling|human direction/i.test(instruction)));
-            if (terminalOrHandoff) {
+            if (["cancel", "escalate"].includes(lastResult.action)) {
                 const { quotaWarning: _quotaWarning, ...withoutQuotaWarning } = lastResult;
                 lastResult = withoutQuotaWarning;
             }

package/bin/comments/review-visibility.d.mts

@@ -24,5 +24,5 @@ export declare function classifyReviewsForDisplay(reviews: Review[], seenMap: Ma
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames): ReviewVisibility;
+export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames, repeatBotReviews?: boolean): ReviewVisibility;
 export {};

package/bin/comments/review-visibility.mjs

@@ -31,7 +31,7 @@ export function classifyReviewsForDisplay(reviews, seenMap) {
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames) {
+export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames, repeatBotReviews = true) {
     const visible = [];
     const toMarkSeen = [];
     for (const review of reviews) {
@@ -39,7 +39,8 @@ export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botU
         const cls = classifyItem(review.id, review.body, seenMap);
         if (isBot) {
             if (cls === "unchanged") {
-                visible.push({ ...review, staleBotCr: true });
+                if (repeatBotReviews)
+                    visible.push({ ...review, staleBotCr: true });
             }
             else if (cls === "edited") {
                 visible.push({ ...review, edited: true });

package/bin/comments/thread-visibility.d.mts

@@ -7,5 +7,5 @@ interface ThreadVisibility {
     firstLookThreads: FirstLookThread[];
     toMarkSeen: ReviewThread[];
 }
-export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames): ThreadVisibility;
+export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>): ThreadVisibility;
 export {};