pr-shepherd 0.44.1 → 0.46.0

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,8 +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 } 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
@@ -40,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);
@@ -120,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,
@@ -139,24 +107,57 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference, {
+                    merge: opts.merge,
+                }),
             },
         };
     }
     await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
-    // GitHub does not expose a per-run viewer capability for cancellation. Fail closed:
-    // do not issue or recommend an Actions mutation based only on repository role.
+    // GitHub does not expose a per-run viewer capability for cancellation, so Shepherd never
+    // issues or recommends a cancellation regardless of repository role. A rerun is different:
+    // GitHub's Actions rerun API requires actions:write, which rides with WRITE+ repo access, so
+    // repositoryPermission is a proxy for account-level rerun capability (see canRerunWorkflows) —
+    // it does not confirm the credential executing `gh` has that scope; an unauthorized rerun
+    // simply fails when the agent runs it, the same residual risk as every other CLI-recommended
+    // git/gh mutation in this codebase.
     const cancelled = [];
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
     const actionableComments = report.comments.actionable.map(toAgentComment);
-    const failingAgentChecks = toAgentChecks(failingChecks);
+    const rerunAuthorized = canRerunWorkflows(report.viewerAuthorization);
+    // A workflow run can only be rerun once it has fully completed; a runId still present among
+    // in-progress checks (a sibling job from the same run) is not yet eligible.
+    const inProgressWorkflowRunIds = new Set(report.checks.inProgress.flatMap((c) => (c.runId !== null ? [c.runId] : [])));
+    // Confirmed GitHub Actions provenance for a runId: `source: "startup_failure"` checks are
+    // fetched directly from the Actions REST API (always genuine), while `source: "check_run"`
+    // checks need `workflowName` — derived from the same `checkSuite.workflowRun.workflow` GraphQL
+    // path as the run's numeric ID — because a third-party GitHub App's CheckRun can carry a
+    // details-URL-parsed runId that merely looks like an Actions run number.
+    const actionsRunIds = new Set(failingChecks.flatMap((c) => c.runId !== null && (c.source === "startup_failure" || c.workflowName !== undefined)
+        ? [c.runId]
+        : []));
+    const failingAgentChecks = toAgentChecks(failingChecks).map((c) => rerunAuthorized &&
+        c.runId &&
+        actionsRunIds.has(c.runId) &&
+        // ACTION_REQUIRED means the run is paused pending manual workflow approval; rerunning does
+        // not grant that approval, so no rerun command applies.
+        c.conclusion !== "ACTION_REQUIRED" &&
+        !inProgressWorkflowRunIds.has(c.runId)
+        ? { ...c, rerunCommand: `gh run rerun ${c.runId} -R ${report.repo}` }
+        : c);
     const checks = [
         ...failingAgentChecks,
         ...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;
@@ -166,23 +167,57 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    // Conflict resolution necessarily changes the branch head, but Shepherd cannot verify
-    // authorization for the local Git credential that would publish it. Defer review mutations
-    // until an authorized push updates the PR and a fresh iteration can rebuild SHA-safe commands.
-    const { resolveCommand, resolveOnlyCommand } = hasConflicts
-        ? 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"],
@@ -196,7 +231,9 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...fallbackEscalateBase,
-                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prReference),
+                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prReference, {
+                    merge: opts.merge,
+                }),
             },
         };
     }

package/bin/commands/iterate/index.mjs

@@ -14,7 +14,11 @@ import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { buildReadyMergeResult, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
-export async function runIterate(opts) {
+import { withIterateApiUsage } from "./run.mjs";
+export function runIterate(opts) {
+    return withIterateApiUsage(opts, () => runIterateCore(opts));
+}
+async function runIterateCore(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
@@ -48,8 +52,7 @@ export async function runIterate(opts) {
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
     }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly], report.ruleAutoResolveReviewSummaryIds);
-    // Already-seen review summaries have no new content to surface — minimize them
-    // in-process so they never register as agent-facing actionable work (#313).
+    // Minimize already-seen review summaries in-process so they never become agent-facing work.
     // GitHub can still return a null/error/rate-limit result per ID without
     // throwing (autoMinimizeComments reports this via `errors`, not a rejection);
     // any ID it did not confirm minimized falls back into the agent-facing set so
@@ -78,8 +81,8 @@ export async function runIterate(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/merge-state.mjs

@@ -7,7 +7,10 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
         return null;
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
-    if (!queue && report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
+    // A merge queue is enrolled the same way auto-merge is granted: enabling
+    // auto-merge on a queue-required PR is what adds it to the queue, so
+    // viewerCanEnableAutoMerge authorizes both the plain-merge and enqueue paths.
+    if (report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
         return {
             ...base,
             action: "merge",
@@ -16,7 +19,7 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
                 repo: report.repo,
                 nodeId: report.nodeId,
                 headSha: report.headSha ?? "unknown",
-                queue: false,
+                queue,
             }),
         };
     }

package/bin/commands/iterate/render.mjs

@@ -13,6 +13,8 @@ export function renderResolveCommand(rc) {
 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) {
     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) {
     // 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) {
     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,10 +88,10 @@ isBehind = false, viewerCanUpdate = false) {
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts) {
-        instructions.push(`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("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 ||

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

@@ -0,0 +1,2 @@
+import type { IterateCommandOptions, IterateResult } from "../../types.mts";
+export declare function withIterateApiUsage(opts: IterateCommandOptions, runCore: () => Promise<IterateResult>): Promise<IterateResult>;

package/bin/commands/iterate/run.mjs

@@ -0,0 +1,8 @@
+import { withApiTelemetryScope } from "../../github/api-telemetry.mjs";
+import { attachApiUsage } from "./api-usage.mjs";
+export function withIterateApiUsage(opts, runCore) {
+    return withApiTelemetryScope(async () => {
+        const result = await runCore();
+        return attachApiUsage(result, opts.deferQuotaWarning !== true);
+    });
+}

package/bin/commands/mark-files-as-viewed.mjs

@@ -3,6 +3,14 @@ import { graphql, getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
 import { paginateForward } from "../github/pagination.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       id

package/bin/commands/poll-run.d.mts

@@ -0,0 +1,2 @@
+import type { IterateResult } from "../types.mts";
+export declare function withPollApiUsage(runCore: () => Promise<IterateResult>, preservePersistedWarning: boolean): Promise<IterateResult>;

package/bin/commands/poll-run.mjs

@@ -0,0 +1,8 @@
+import { withApiTelemetryScope } from "../github/api-telemetry.mjs";
+import { attachApiUsage } from "./iterate/api-usage.mjs";
+export function withPollApiUsage(runCore, preservePersistedWarning) {
+    return withApiTelemetryScope(async () => {
+        const result = await runCore();
+        return attachApiUsage(result, true, preservePersistedWarning);
+    });
+}

package/bin/commands/poll.d.mts

@@ -1,5 +1,5 @@
 import type { IterateCommandOptions, IterateResult } from "../types.mts";
-interface PollCommandOptions extends IterateCommandOptions {
+export interface PollCommandOptions extends IterateCommandOptions {
     intervalSeconds: number;
     timeoutSeconds: number;
     /** Settle window after first FIX_CODE before returning. Default 60. 0 disables. */
@@ -9,4 +9,3 @@ interface PollCommandOptions extends IterateCommandOptions {
 }
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
 export declare function runPoll(opts: PollCommandOptions): Promise<IterateResult>;
-export {};

package/bin/commands/poll.mjs

@@ -1,5 +1,6 @@
 import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
+import { withPollApiUsage } from "./poll-run.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
     if (verbose) {
@@ -61,7 +62,10 @@ function writeDebounceProgress(tick, elapsedMs, remainingMs) {
     process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
 }
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
-export async function runPoll(opts) {
+export function runPoll(opts) {
+    return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true);
+}
+async function runPollCore(opts) {
     const { intervalSeconds, timeoutSeconds, debounceSeconds: debounceSecondsOpt, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
@@ -74,11 +78,8 @@ export async function runPoll(opts) {
     const quietStatus = quietStatusOpt === true;
     const untilTerminal = untilTerminalOpt === true;
     let lastWaitSignature = null;
-    // When prNumber is omitted, iterateOpts.prNumber starts undefined and each tick would otherwise
-    // re-infer the PR from the current branch. That inference query only matches OPEN PRs, so once
-    // the monitored PR merges it returns nothing and runIterate throws instead of reporting the
-    // terminal CANCEL/merged result. Pin the PR resolved by the first tick so later ticks target it
-    // directly and never re-run branch discovery.
+    let pendingQuotaWarning;
+    // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
     while (true) {
@@ -88,10 +89,28 @@ export async function runPoll(opts) {
             ...iterateOpts,
             prNumber,
             persistSeen: debounceSeconds === 0 || pastDebounce,
+            // Until-terminal must persist before deciding to return.
+            deferQuotaWarning: !untilTerminal,
         });
         prNumber ??= lastResult.pr;
+        if (lastResult.quotaWarning !== undefined)
+            pendingQuotaWarning = lastResult.quotaWarning;
+        if (untilTerminal &&
+            pendingQuotaWarning !== undefined &&
+            !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
+            !(debounceUntil !== null && !pastDebounce)) {
+            if (["cancel", "escalate"].includes(lastResult.action)) {
+                const { quotaWarning: _quotaWarning, ...withoutQuotaWarning } = lastResult;
+                lastResult = withoutQuotaWarning;
+            }
+            else if (lastResult.quotaWarning === undefined) {
+                lastResult = { ...lastResult, quotaWarning: pendingQuotaWarning };
+            }
+            break;
+        }
         if (lastResult.action === "wait" && !pastDebounce) {
-            debounceUntil = null;
+            if (pendingQuotaWarning === undefined)
+                debounceUntil = null;
             const elapsedMs = Date.now() - start;
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
@@ -126,9 +145,6 @@ export async function runPoll(opts) {
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
             }
-            // Always continue so a tick that *started* before debounceUntil but *finished*
-            // after it cannot return with persistSeen: false. The next loop iteration
-            // sees pastDebounce and persists.
             continue;
         }
         break;

package/bin/comments/rate-limit.d.mts

@@ -2,15 +2,19 @@ export interface ResolveRateLimitStop {
     message: string;
     retryAfterSeconds?: number;
     limit?: number;
+    used?: number;
     remaining?: number;
     resetAt?: number;
+    resource?: string;
 }
 export declare function rateLimitFromError(err: unknown, fallbackMessage: string): ResolveRateLimitStop | null;
 export declare function rateLimitFromGraphQlResult(messages: string[], meta: {
     rateLimit?: {
         remaining?: unknown;
         limit?: unknown;
+        used?: unknown;
         resetAt?: unknown;
+        resource?: unknown;
     };
     retryAfterSeconds?: unknown;
     stopOnZeroRemaining?: boolean;