pr-shepherd 0.49.0 → 0.51.0

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

@@ -33,7 +33,7 @@ function checkRequiresHumanFollowUp(check) {
         return !check.detailsUrl?.trim();
     return !check.logExcerpt?.trim();
 }
-function nextFixAttempts(stored, headSha, threads) {
+function nextFixAttempts(stored, threads, countAttempt) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
         ? { ...stored.threadBodyHashes }
@@ -41,13 +41,32 @@ function nextFixAttempts(stored, headSha, threads) {
     for (const t of threads) {
         const bodyHash = hashBody(threadTranscriptBody(t));
         const previousHash = threadBodyHashes[t.id];
-        if (stored?.headSha === headSha && (previousHash === undefined || previousHash === bodyHash))
+        if (!countAttempt)
             continue;
         threadAttempts[t.id] = previousHash === bodyHash ? (threadAttempts[t.id] ?? 0) + 1 : 1;
         threadBodyHashes[t.id] = bodyHash;
     }
     return { threadAttempts, threadBodyHashes };
 }
+function previousFixAttempts(stored, threads) {
+    if (!stored?.threadBodyHashes)
+        return {};
+    const attempts = {};
+    for (const thread of threads) {
+        const bodyHash = hashBody(threadTranscriptBody(thread));
+        if (stored.threadBodyHashes[thread.id] === bodyHash) {
+            attempts[thread.id] = stored.threadAttempts[thread.id] ?? 0;
+        }
+    }
+    return attempts;
+}
+function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
+    const pending = {
+        ...(resolveOnlyCommand?.hasMutations && { resolveOnlyCommand }),
+        ...(resolveCommand.hasMutations && { resolveCommand }),
+    };
+    return Object.keys(pending).length > 0 ? pending : undefined;
+}
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
@@ -70,7 +89,22 @@ export async function handleFixCode(ctx) {
     const retryableActionableThreads = mutationActionableThreads.filter((thread) => thread.path !== null && thread.line !== null);
     const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
-    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, retryableActionableThreads);
+    const countFixCodeAttempt = opts.persistSeen !== false;
+    const priorThreadAttempts = previousFixAttempts(stored, retryableActionableThreads);
+    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, retryableActionableThreads, countFixCodeAttempt);
+    const resolutionOnlyThreadsForWork = report.threads.resolutionOnly.filter((thread) => !skippedThreadIds.has(thread.id) &&
+        ((thread.path !== null && thread.line !== null) ||
+            threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
+    const actionableChangesRequestedReviews = report.changesRequestedReviews.filter((review) => review.staleReview !== true ||
+        !isHumanAuthor(review) ||
+        isConfiguredBotAuthor(review, botUsernames));
+    const changesRequestedReviewsForWork = actionableChangesRequestedReviews.filter((review) => !unauthorizedDismissals.some((candidate) => candidate.id === review.id));
+    const buildReviewCommands = (checks) => buildResolveCommand(report.threads.actionable
+        .filter((thread) => mutationActionableThreads.some((candidate) => candidate.id === thread.id))
+        .map(toAgentThread), resolutionOnlyThreadsForWork, [
+        ...(report.comments.minimizeIds ?? report.comments.actionable.map((comment) => comment.id)),
+        ...reviewSummaryIds,
+    ], changesRequestedReviewsForWork, checks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
     const botCrReviews = report.changesRequestedReviews.filter((r) => (!isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames)) &&
         report.viewerAuthorization?.viewerCanAdminister === true);
     const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
@@ -79,13 +113,16 @@ export async function handleFixCode(ctx) {
     const { next: nextBotCrState, staleIds: staleBotCrIds } = updateBotCrSeenState(previousBotCrState, botCrReviews, nowSeconds, stallTimeoutSeconds);
     await writeBotCrSeenState(botCrStateKey, nextBotCrState);
     if (staleBotCrIds.length > 0) {
-        const staleSet = new Set(staleBotCrIds);
-        const staleReviews = botCrReviews.filter((r) => staleSet.has(r.id));
+        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const escalateBase = {
             triggers: ["bot-cr-not-dismissed"],
             unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
             ambiguousComments: report.comments.actionable.map(toAgentComment),
-            changesRequestedReviews: staleReviews,
+            changesRequestedReviews: report.changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(["bot-cr-not-dismissed"], staleBotCrIds.join(", ")),
         };
         return {
@@ -99,14 +136,21 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    const escalateTriggers = checkEscalateTriggers(retryableActionableThreads, threadAttempts);
+    const escalateTriggers = countFixCodeAttempt
+        ? checkEscalateTriggers(retryableActionableThreads, priorThreadAttempts)
+        : { triggers: [], thrashHistory: undefined };
     if (escalateTriggers.triggers.length > 0) {
+        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const escalateBase = {
             triggers: escalateTriggers.triggers,
             unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
             ambiguousComments: report.comments.actionable.map(toAgentComment),
             changesRequestedReviews: report.changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
             thrashHistory: escalateTriggers.thrashHistory,
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(escalateTriggers.triggers),
         };
         return {
@@ -120,7 +164,6 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
     // 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
@@ -163,14 +206,6 @@ 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) ||
-            threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
@@ -179,7 +214,6 @@ export async function handleFixCode(ctx) {
     // unnecessary cancellation.
     const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
-    const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
     const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
@@ -199,6 +233,8 @@ export async function handleFixCode(ctx) {
         checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
         failingAgentChecks.some((check) => belongsToActiveWorkflowRun(check) || !checkRequiresHumanFollowUp(check));
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
+        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const checkSuggestion = exhaustedAttempts.length > 0
             ? `GitHub reports a later workflow attempt (${exhaustedAttempts
                 .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
@@ -209,7 +245,10 @@ export async function handleFixCode(ctx) {
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
             checks: manualFollowUpChecks,
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: checkSuggestion,
         };
         return {
@@ -225,9 +264,7 @@ export async function handleFixCode(ctx) {
     }
     // 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 mutationActionableIds = new Set(mutationActionableThreads.map((thread) => thread.id));
-    const mutationAgentThreads = threads.filter((thread) => mutationActionableIds.has(thread.id));
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(mutationAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
+    const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
     // 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. Located resolution-only threads retain that guard;
@@ -241,11 +278,15 @@ export async function handleFixCode(ctx) {
         actionableComments.length > 0 ||
         locatedResolutionOnlyThreadsForWork.length > 0;
     if (baseLookup.isFallback && pushIsPlausible) {
+        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
             unresolvedThreads: [...threads, ...resolutionOnlyThreads.map(toAgentThread)],
             ambiguousComments: actionableComments,
             changesRequestedReviews,
+            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
+            ...(editedSummaries.length > 0 && { editedSummaries }),
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(["base-branch-unknown"], baseLookup.failureReason),
         };
         return {
@@ -288,6 +329,7 @@ export async function handleFixCode(ctx) {
     };
     const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
     if (result.action === "fix_code" && opts.persistSeen !== false) {
+        await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
         await Promise.allSettled(result.fix.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
     }
     return result;

package/bin/commands/iterate/render.mjs

@@ -69,7 +69,7 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
     }
     if (resolutionOnlyThreads.length > 0) {
-        instructions.push('Review the threads under `## Review threads to resolve` before running mutations. Use the generated commands as shown — see "Review-mutation routing" in the pr-shepherd skill for which flag applies to which ID.');
+        instructions.push("Review the threads under `## Review threads to resolve` before running the generated mutations.");
     }
     instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions);
     if (hasAnnotations) {

package/bin/commands/iterate/stall.mjs

@@ -1,8 +1,32 @@
+/* eslint-disable max-lines */
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
+function pendingReviewCommandsFromResult(result) {
+    if (result.action !== "fix_code")
+        return undefined;
+    const pending = {
+        ...(result.fix.resolveOnlyCommand?.hasMutations && {
+            resolveOnlyCommand: result.fix.resolveOnlyCommand,
+        }),
+        ...(result.fix.resolveCommand.hasMutations && { resolveCommand: result.fix.resolveCommand }),
+    };
+    return Object.keys(pending).length > 0 ? pending : undefined;
+}
+function surfacedSummariesFromResult(result) {
+    if (result.action !== "fix_code")
+        return {};
+    return {
+        ...(result.fix.firstLookSummaries.length > 0 && {
+            firstLookSummaries: result.fix.firstLookSummaries,
+        }),
+        ...(result.fix.editedSummaries.length > 0 && {
+            editedSummaries: result.fix.editedSummaries,
+        }),
+    };
+}
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}:${f.runId ?? "no-run"}:${f.runAttempt ?? "unknown"}`),
@@ -44,13 +68,16 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         action: prospectiveResult.action,
     });
     if (stalledChecks.length > 0) {
+        const pending = pendingReviewCommandsFromResult(prospectiveResult);
         const stalledDuration = formatDurationApprox(Math.max(...stalledChecks.map((c) => c.ageSeconds)));
         const escalateBase = {
             triggers: ["stall-timeout"],
             unresolvedThreads: [],
             ambiguousComments: [],
             changesRequestedReviews: [],
+            ...surfacedSummariesFromResult(prospectiveResult),
             stalledChecks,
+            ...(pending && { pendingReviewCommands: pending }),
             suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
         };
         return {
@@ -76,11 +103,14 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
         }
         else if (ageSeconds >= stallTimeoutSeconds) {
             const stalledDuration = formatDurationApprox(ageSeconds);
+            const pending = pendingReviewCommandsFromResult(prospectiveResult);
             const escalateBase = {
                 triggers: ["stall-timeout"],
                 unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
                 ambiguousComments: report.comments.actionable.map(toAgentComment),
                 changesRequestedReviews: report.changesRequestedReviews,
+                ...surfacedSummariesFromResult(prospectiveResult),
+                ...(pending && { pendingReviewCommands: pending }),
                 suggestion: buildEscalateSuggestion(["stall-timeout"], stalledDuration),
             };
             return {

package/bin/commands/iterate/thread-mutation-routing.d.mts

@@ -1,8 +1,6 @@
 import { type NormalizedBotUsernames } from "../../comments/authors.mts";
-import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mts";
 import type { ResolveOtherHumanThreads } from "../../config/load.mts";
 import type { AgentThread, ReviewThread } from "../../types.mts";
-export { shouldResolveOtherHumanThread };
 export type RoutableThread = AgentThread | ReviewThread;
 export interface ThreadMutationRouting {
     replyThreadIds: string[];

package/bin/commands/iterate/thread-mutation-routing.mjs

@@ -1,7 +1,6 @@
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "../../comments/authors.mjs";
 import { threadEndedByShepherd } from "../../comments/marker.mjs";
 import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mjs";
-export { shouldResolveOtherHumanThread };
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
@@ -32,7 +31,7 @@ export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolv
         .filter((thread) => shouldPairResolve(thread, botUsernames, policy) && !threadEndedByShepherd(thread))
         .map((thread) => thread.id));
     const pairedResolveIdSet = new Set(pairedResolveThreadIds);
-    // Rule-matched threads bypass author routing; resolve-mutate retains the human-author guard.
+    // Rule-matched threads bypass the generated-command author routing.
     const standaloneResolveThreadIds = dedupeIds([
         ...threads
             .filter((thread) => shouldPairResolve(thread, botUsernames, policy) && threadEndedByShepherd(thread))

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

@@ -1,5 +1,5 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
-import type { GraphqlApiUsage } from "../types.mts";
+import type { GraphqlApiUsage, PollSummaryResult } from "../types.mts";
 /** Sleep at least `--interval`, and at least the active crossed quota band. */
 export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: Pick<GraphqlApiUsage, "remaining" | "limit"> | undefined, fallbackMs: number, maxMs: number): number;
 /**
@@ -7,3 +7,4 @@ export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBan
  * limit. `null` means the error is not a retryable rate limit.
  */
 export declare function pollGraphQlRetryAfterMs(err: unknown): number | null;
+export declare function aggregateQuotaWarning(result: PollSummaryResult, bands: GraphqlQuotaWarningBand[], intervalSeconds: number): Promise<PollSummaryResult["quotaWarning"]>;

package/bin/commands/poll-quota.mjs

@@ -1,3 +1,5 @@
+import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
+import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
 import { isRateLimitMessage } from "../comments/rate-limit.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
@@ -34,3 +36,13 @@ export function pollGraphQlRetryAfterMs(err) {
     }
     return GRAPHQL_RETRY_AFTER_DEFAULT_MS;
 }
+export async function aggregateQuotaWarning(result, bands, intervalSeconds) {
+    const usage = summarizeApiTelemetry()?.graphql;
+    const [owner, repo] = result.repo.split("/");
+    if (!usage || !owner || !repo)
+        return undefined;
+    return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
+        ...band,
+        pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
+    })), usage, true);
+}

package/bin/commands/poll-summary-explicit-instructions.d.mts

@@ -0,0 +1,2 @@
+import type { PollSummaryResult } from "../types.mts";
+export declare function explicitInstructions(result: PollSummaryResult): string[];

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -0,0 +1,22 @@
+import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+export function explicitInstructions(result) {
+    if (result.reason === "all_terminal")
+        return ["1. Stop — every selected PR is terminal."];
+    if (result.quotaWarning && result.reason !== "actionable") {
+        return [
+            buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
+        ];
+    }
+    if (result.reason === "waiting" || result.reason === "timeout") {
+        return ["1. Run this aggregate selector again when the caller is ready to recheck."];
+    }
+    const instructions = [
+        "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",
+        "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
+        "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
+    ];
+    if (result.quotaWarning) {
+        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
+    }
+    return instructions;
+}

package/bin/commands/poll-summary-instructions.d.mts

@@ -0,0 +1,3 @@
+import type { PollSummaryResult } from "../types.mts";
+/** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
+export declare function withPollSummaryInstructions(result: PollSummaryResult, mergeRequested: boolean): PollSummaryResult;

package/bin/commands/poll-summary-instructions.mjs

@@ -0,0 +1,139 @@
+import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
+/** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
+export function withPollSummaryInstructions(result, mergeRequested) {
+    if (result.selection.kind !== "stack") {
+        return { ...result, instructions: explicitInstructions(result) };
+    }
+    const planned = planStack(result, mergeRequested);
+    const reason = planned.action === "cancel"
+        ? "all_terminal"
+        : planned.action === "wait"
+            ? result.reason === "timeout"
+                ? "timeout"
+                : "waiting"
+            : "actionable";
+    const instructions = [...planned.instructions];
+    if (result.quotaWarning && planned.action !== "wait" && planned.action !== "cancel") {
+        instructions.push(buildQuotaAwareContinuation(result.quotaWarning, `${instructions.length + 1}. After completing the stack action,`));
+    }
+    return { ...result, reason, nextAction: planned.action, instructions };
+}
+function planStack(result, mergeRequested) {
+    const open = result.prs.filter((item) => item.state === "OPEN");
+    if (open.length === 0) {
+        return { action: "cancel", instructions: ["1. Stop — every selected PR is terminal."] };
+    }
+    const lastOpenPosition = positionOf(result, open.at(-1).pr);
+    const closedBelowOpen = result.prs.find((item) => item.state === "CLOSED" && positionOf(result, item.pr) < lastOpenPosition);
+    if (closedBelowOpen) {
+        return {
+            action: "escalate",
+            instructions: [
+                `1. PR #${closedBelowOpen.pr} is closed without merging below an open stack layer. Stop stack merge and rebase operations here; the closed dependency must be restored or the higher branches rebuilt on a valid base.`,
+                "2. Ask the stack owner which recovery path to take, then rerun the same aggregate `--stack` selector after the stack is repaired.",
+            ],
+        };
+    }
+    const gap = result.stackAncestry?.[0];
+    const firstOpen = open[0];
+    if (firstOpen.mergeStateStatus === "BEHIND")
+        return rebaseWholeStack(result, firstOpen);
+    if (mergeRequested) {
+        const mergeTarget = readyLowerStackTarget(open, result.stackAncestry ?? []);
+        if (mergeTarget) {
+            const stackNumber = result.selection.kind === "stack" ? result.selection.stackNumber : 0;
+            return {
+                action: "merge",
+                instructions: [
+                    `1. The contiguous ready lower stack ends at PR #${mergeTarget.pr}. Merge the native stack through that PR with \`gh stack merge --squash ${mergeTarget.pr}\`; verify that the selector names PR #${mergeTarget.pr} in stack #${stackNumber} before running it. This includes still-open lower layers and leaves higher layers open.`,
+                    "2. After GitHub completes the stack merge and updates the remaining branches, rerun the same aggregate `--stack` selector. If an ancestry mismatch remains, follow the rebase instructions returned then.",
+                ],
+            };
+        }
+        if (firstOpen.action === "wait") {
+            return waitingStack(result);
+        }
+    }
+    const firstWork = open.find((item) => ["fix_code", "mark_ready", "escalate"].includes(item.action));
+    if (firstWork && (!gap || positionOf(result, firstWork.pr) <= positionOf(result, gap.childPr))) {
+        return pollOneLayer(firstWork);
+    }
+    if (gap) {
+        return {
+            action: "fix_code",
+            instructions: [
+                `1. PR #${gap.childPr} still records base \`${gap.childBaseRefName}\` at \`${gap.childBaseRefOid}\`, while parent PR #${gap.parentPr} now ends at \`${gap.parentHeadRefName}\` \`${gap.parentHeadRefOid}\`. From a clean checkout of \`${result.repo}\`, check out the parent stack branch \`${gap.parentHeadRefName}\`.`,
+                "2. Rebase the upstack branches onto that parent with `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten branches with `gh stack push`.",
+                "3. Rerun the same aggregate `--stack` selector and follow the next returned action.",
+            ],
+        };
+    }
+    const behind = open.find((item) => item.mergeStateStatus === "BEHIND");
+    if (behind)
+        return rebaseWholeStack(result, behind);
+    if (firstWork)
+        return pollOneLayer(firstWork);
+    if (!mergeRequested && open.every((item) => item.action === "cancel")) {
+        return {
+            action: "cancel",
+            instructions: ["1. Stop — every open stack layer is ready and the stack is linear."],
+        };
+    }
+    return waitingStack(result);
+}
+function rebaseWholeStack(result, behind) {
+    return {
+        action: "fix_code",
+        instructions: [
+            `1. GitHub reports PR #${behind.pr} is behind its base \`${behind.baseRefName}\`. From a clean checkout of \`${result.repo}\`, check out its stack branch \`${behind.headRefName}\`.`,
+            "2. Rebase that native stack from its trunk with `gh stack rebase`, resolving any conflicts.",
+            "3. Push the updated stack with `gh stack push` and rerun the same aggregate `--stack` selector.",
+        ],
+    };
+}
+function readyLowerStackTarget(open, gaps) {
+    const mismatchedChildren = new Set(gaps.map((gap) => gap.childPr));
+    let target;
+    for (const item of open) {
+        if (mismatchedChildren.has(item.pr) || item.action !== "merge")
+            break;
+        target = item;
+    }
+    return target;
+}
+function positionOf(result, pr) {
+    return result.prs.find((item) => item.pr === pr)?.stack?.position ?? Number.MAX_SAFE_INTEGER;
+}
+function pollOneLayer(item) {
+    if (!item.pollCommand) {
+        return {
+            action: "escalate",
+            instructions: [
+                `1. PR #${item.pr} needs attention, but GitHub returned no one-PR poll command.`,
+            ],
+        };
+    }
+    return {
+        action: item.action,
+        instructions: [
+            `1. Work on the lowest actionable layer, PR #${item.pr}: run \`${item.pollCommand}\`.`,
+            "2. Follow that one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
+            "3. Rerun the aggregate `--stack` selector before acting on a higher layer.",
+        ],
+    };
+}
+function waitingStack(result) {
+    if (result.quotaWarning) {
+        return {
+            action: "wait",
+            instructions: [
+                buildQuotaAwareContinuation(result.quotaWarning, "1. This native stack is non-terminal. Before continuing,"),
+            ],
+        };
+    }
+    return {
+        action: "wait",
+        instructions: ["1. Recheck this native stack after the lowest open layer changes state."],
+    };
+}

package/bin/commands/poll-summary-signature.d.mts

@@ -0,0 +1,2 @@
+import type { PollSummaryResult } from "../types.mts";
+export declare function summaryStatusSignature(result: PollSummaryResult): string;

package/bin/commands/poll-summary-signature.mjs

@@ -0,0 +1,16 @@
+export function summaryStatusSignature(result) {
+    return JSON.stringify({
+        nextAction: result.nextAction,
+        stackAncestry: result.stackAncestry,
+        prs: result.prs.map((item) => ({
+            pr: item.pr,
+            action: item.action,
+            state: item.state,
+            mergeable: item.mergeable,
+            mergeStateStatus: item.mergeStateStatus,
+            reviewDecision: item.reviewDecision,
+            checks: item.checks,
+            review: item.review,
+        })),
+    });
+}