pr-shepherd 0.45.0 → 0.46.1

package/bin/cli/safe-body-file.mjs

@@ -0,0 +1,42 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+const DEFAULT_DEPENDENCIES = {
+    platform: process.platform,
+    noFollow: constants.O_NOFOLLOW,
+    nonBlock: constants.O_NONBLOCK,
+    open,
+};
+/**
+ * Reads a regular file after rejecting unsafe final path entries without exposing its contents.
+ * Callers must trust parent directories: O_NOFOLLOW only protects the final path entry.
+ */
+export async function readSafeBodyFile(filePath, dependencies = DEFAULT_DEPENDENCIES) {
+    const flags = safeOpenFlags(dependencies);
+    if (flags === null)
+        throw noInput();
+    let handle;
+    try {
+        handle = await dependencies.open(filePath, flags);
+        if (!(await handle.stat()).isFile())
+            throw new Error("not a regular file");
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        throw noInput();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function safeOpenFlags(dependencies) {
+    if (dependencies.platform === "win32" ||
+        dependencies.noFollow === undefined ||
+        dependencies.nonBlock === undefined) {
+        return null;
+    }
+    return constants.O_RDONLY | dependencies.noFollow | dependencies.nonBlock;
+}
+function noInput() {
+    return new ShepherdError("body file could not be read safely", EXIT.NOINPUT);
+}

package/bin/cli-parser.mjs

@@ -10,6 +10,7 @@ import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
+import { handleJournalExtract } from "./cli/journal-extract-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { setupLog } from "./log/setup.mjs";
@@ -32,6 +33,12 @@ export async function main(argv) {
         await handleLogFile(args.slice(1));
         return;
     }
+    // Extraction deliberately precedes legacy warnings and logging: it is a local,
+    // GitHub/config/log-free read path for automation that already has a PR body.
+    if (subcommand === "journal" && args[1] === "extract") {
+        await handleJournalExtract(args.slice(2));
+        return;
+    }
     // The public command groups keep admin diagnostics out of the normal
     // command namespace. Keep this before setupLog because log-file reads the
     // log path and must not initialize/tee the log it is reporting.

package/bin/commands/check-status.mjs

@@ -9,15 +9,15 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
         return "FAILING";
     if (verdict.anyInProgress)
         return "IN_PROGRESS";
-    // BLOCKED with no remaining shepherd work — hand off via ready-delay regardless of why GitHub
+    // BLOCKED with no remaining shepherd work — enter ready-delay regardless of why GitHub
     // is BLOCKED (review pending, insufficient approvals, branch-protection rule, etc.).
     // Requires hasChecks so that a PR with zero relevant checks (CI never started, or all
     // filtered/skipped) doesn't prematurely trigger READY before any check has reported.
     // Exception: UNSTABLE with ignored checks — UNSTABLE means only non-required checks are
-    // pending/failing, and if those are all ignored the handoff is safe even with no other checks.
+    // pending/failing, and if those are all ignored the ready state is safe even with no other checks.
     // BLOCKED is excluded from the ignoredNames extension: BLOCKED can mean required checks haven't
-    // started, and handing off prematurely there risks a broken merge attempt.
-    // blockingBotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
+    // started, and entering READY prematurely there risks a broken merge attempt.
+    // blockingBotReviewInProgress is still excluded — a bot review is Shepherd work, not a READY state.
     const hasRelevantPassingChecks = verdict.hasChecks || (mergeStatus.status === "UNSTABLE" && verdict.ignoredNames.length > 0);
     if (verdict.allPassed &&
         hasRelevantPassingChecks &&

package/bin/commands/check.mjs

@@ -16,7 +16,8 @@ import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
-import { normalizeBotUsernames } from "../comments/authors.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
+import { buildThreadMutationRouting } from "./iterate/thread-mutation-routing.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -80,7 +81,17 @@ export async function runCheck(opts) {
     const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize !== true));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
     const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve !== true));
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id)), seenMap, botUsernames);
+    const visibleThreadCandidates = batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id));
+    const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds);
+    const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
+    const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
+    const repeatableThreadIds = new Set(visibleThreadCandidates
+        .filter((thread) => thread.path !== null &&
+        thread.line !== null &&
+        (!replyThreadIds.has(thread.id) || thread.viewerCanReply === true) &&
+        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true))
+        .map((thread) => thread.id));
+    const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -103,7 +114,7 @@ export async function runCheck(opts) {
         else
             seenSummaries.push(r);
     }
-    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
+    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, batchData.viewerAuthorization?.viewerCanAdminister === true);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     if (opts.persistSeen !== false) {
         const successfulAnnotations = [
@@ -145,12 +156,21 @@ export async function runCheck(opts) {
         ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
     };
     const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [
         ...authorizedRuleAutoResolveThreadIds,
-        ...deniedRuleAutoResolveThreadIds,
+        ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
     ];
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
-    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
+    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
+        if (partition.suppressedChangesRequestedIds.has(review.id))
+            return false;
+        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
+        return (!isBot ||
+            batchData.viewerAuthorization?.viewerCanAdminister === true ||
+            visibleChangesRequestedIds.has(review.id));
+    }).length;
     const approvedReviews = approvedReviewVisibility.visible;
     let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
     if (status === "READY" && !didRefreshMergeability) {

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 automatic mark-ready operation. Ask a repository maintainer to mark the pull request ready before resuming Shepherd.";
     }
     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) {