pr-shepherd 0.56.6 → 0.57.1

package/bin/commands/quota-selection.mjs

@@ -1,19 +1,24 @@
-import { withGraphqlCredentialFingerprint } from "../github/api-telemetry.mjs";
+import { withGraphqlCredentialFingerprint, withRestCoreCredentialFingerprint, } from "../github/api-telemetry.mjs";
 import { composeQuotaWarning } from "../quota-budgets.mjs";
 import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
 /** Claim GraphQL and REST core warnings separately, then present one result. */
-export async function selectQuotaWarning(key, bands, usage, persist) {
+export async function selectQuotaWarning(key, bands, usage, persist, transport) {
     const core = usage.rest?.find((item) => item.resource === "core");
-    const graphqlWarning = usage.graphql
-        ? await evaluateWorktreeGraphqlQuotaWarning(key, bands, withGraphqlCredentialFingerprint(usage.graphql), persist)
+    const graphql = transport === "rest" ? undefined : usage.graphql;
+    // Capture provenance together with this usage snapshot before either async
+    // state evaluation can yield while newer requests update telemetry.
+    const graphqlSample = graphql ? withGraphqlCredentialFingerprint(graphql) : undefined;
+    const coreSample = core ? withRestCoreCredentialFingerprint(core) : undefined;
+    const graphqlWarning = graphqlSample
+        ? await evaluateWorktreeGraphqlQuotaWarning(key, bands, graphqlSample, persist)
         : undefined;
-    const coreWarning = core
-        ? await evaluateWorktreeGraphqlQuotaWarning(key, bands, withGraphqlCredentialFingerprint(core), persist)
+    const coreWarning = coreSample
+        ? await evaluateWorktreeGraphqlQuotaWarning(key, bands, coreSample, persist)
         : undefined;
     return composeQuotaWarning({
         graphqlWarning,
         coreWarning,
-        graphql: usage.graphql,
+        graphql,
         core,
         bands,
     });

package/bin/commands/resolve-mutate.mjs

@@ -1,9 +1,11 @@
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { applyResolveOptions } from "../comments/resolve.mjs";
 import { fetchReplyThreadTranscripts } from "../github/reply-thread-transcripts.mjs";
+import { readApplyReviewPreflight, } from "../github/apply-review-preflight.mjs";
 import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBodies } from "../threads/transcript.mjs";
 import { addPrShepherdMarker } from "../comments/marker.mjs";
+import { adoptedReplyThreads } from "../comments/uncertain-replies.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 /** @deprecated Hidden implementation for `resolve`; use `apply review`. */
 export async function runResolveMutate(opts) {
@@ -15,9 +17,20 @@ export async function runResolveMutate(opts) {
     // Fetch only to retain the pre-reply transcript for successful-reply seen
     // markers. It never determines which user-supplied IDs are sent to GitHub.
     let transcriptById;
+    let preflight = null;
     if (opts.replyThreadIds?.length) {
         try {
-            transcriptById = await fetchReplyThreadTranscripts(prNumber, repo, opts.replyThreadIds);
+            preflight = await readApplyReviewPreflight(prNumber, repo, opts.replyThreadIds);
+        }
+        catch {
+            // The standalone reads below and in applyResolveOptions cover everything it would have.
+        }
+        transcriptById = new Map(preflight?.transcripts);
+        const missing = [...new Set(opts.replyThreadIds)].filter((id) => !transcriptById.has(id));
+        try {
+            if (missing.length)
+                for (const [id, body] of await fetchReplyThreadTranscripts(prNumber, repo, missing))
+                    transcriptById.set(id, body);
         }
         catch {
             // Seen-marker bookkeeping is best-effort. A failed read must not block
@@ -27,6 +40,7 @@ export async function runResolveMutate(opts) {
     // Iterate capability-checks and routes its generated commands. Direct apply
     // requests are user-directed: forward every supplied ID unchanged and let
     // GitHub report whether each requested mutation is permitted or applicable.
+    // Only generated durable-state commands carry `--adopt-existing-replies`.
     const result = await applyResolveOptions(prNumber, repo, {
         resolveThreadIds: opts.resolveThreadIds,
         replyThreadIds: opts.replyThreadIds,
@@ -34,14 +48,28 @@ export async function runResolveMutate(opts) {
         dismissReviewIds: opts.dismissReviewIds,
         dismissMessage: opts.dismissMessage,
         requireSha: opts.requireSha,
-    });
-    if (opts.dismissMessage && transcriptById) {
+        ...(opts.adoptExistingReplies && { adoptExistingReplies: true }),
+    }, ...(preflight ? [preflight] : []));
+    const adopted = new Set(adoptedReplyThreads(result));
+    let adoptedTranscripts;
+    if (adopted.size) {
+        try {
+            adoptedTranscripts = await fetchReplyThreadTranscripts(prNumber, repo, [...adopted]);
+        }
+        catch {
+            /* Never synthesize a transcript for an already-delivered reply. */
+        }
+    }
+    if (opts.dismissMessage && (transcriptById || adoptedTranscripts)) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {
-            const previousBody = transcriptById.get(id);
+            const previousBody = transcriptById?.get(id);
+            const currentBody = adopted.has(id) ? adoptedTranscripts?.get(id) : undefined;
+            if (adopted.has(id) && currentBody === undefined)
+                return Promise.resolve();
             if (previousBody === undefined)
                 return Promise.resolve();
-            return markReplySeen({ owner: repo.owner, repo: repo.name, pr: prNumber }, id, previousBody, threadTranscriptBodies([previousBody, markedMessage]), markedMessage);
+            return markReplySeen({ owner: repo.owner, repo: repo.name, pr: prNumber }, id, previousBody, currentBody ?? threadTranscriptBodies([previousBody, markedMessage]), markedMessage);
         }));
     }
     return result;

package/bin/commands/rest-stack-merge-readiness.d.mts

@@ -0,0 +1,4 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type RestMergeStackGuard } from "../github/rest-merge-stack-guard.mts";
+/** Validate the exact current native prefix before requesting a stack merge. */
+export declare function validateRestStackMergeReadiness(pr: number, repo: RepoInfo, sha: string, expectedStack?: RestMergeStackGuard): Promise<void>;

package/bin/commands/rest-stack-merge-readiness.mjs

@@ -0,0 +1,74 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { readRestStackMembership, readRestStackTopology } from "../github/rest-stack-read.mjs";
+import { fetchRawSummaryPr } from "../github/poll-summary.mjs";
+import { summarizePollSummaryPr } from "../github/poll-summary-projector.mjs";
+import { stackAncestryGaps } from "../github/stack-read.mjs";
+import { mapPool } from "../util/pool.mjs";
+import { restMergeStackGuardKey, } from "../github/rest-merge-stack-guard.mjs";
+/** Validate the exact current native prefix before requesting a stack merge. */
+export async function validateRestStackMergeReadiness(pr, repo, sha, expectedStack) {
+    const initialMembership = await readRestStackMembership(pr, repo);
+    if (!initialMembership) {
+        if (expectedStack)
+            fail("Expected native stack is no longer present");
+        return;
+    }
+    if (expectedStack &&
+        (initialMembership.number !== expectedStack.number ||
+            initialMembership.base.ref !== expectedStack.baseRefName))
+        fail("Expected native stack identity or trunk changed");
+    const topology = await readRestStackTopology(pr, repo);
+    const index = topology.ordered.findIndex((member) => member.number === pr);
+    if (index < 0 || topology.ordered[index]?.headRefOid !== sha)
+        fail("Stack head changed before merge");
+    const prefix = topology.ordered.slice(0, index + 1);
+    if (expectedStack &&
+        restMergeStackGuardKey(expectedStack) !==
+            restMergeStackGuardKey({
+                number: topology.stackNumber,
+                baseRefName: initialMembership.base.ref,
+                prefix: prefix.map(guardMember),
+            }))
+        fail("Expected native stack prefix or parent boundaries changed");
+    if (prefix.some((member) => !["OPEN", "MERGED"].includes(member.state)))
+        fail("Stack prefix has a closed or unverified dependency");
+    const open = prefix.filter((member) => member.state === "OPEN");
+    const membership = await readRestStackMembership(pr, repo);
+    if (membership &&
+        (membership.number !== initialMembership.number ||
+            membership.base.ref !== initialMembership.base.ref))
+        fail("Native stack identity or trunk changed while validating merge readiness");
+    if (!membership || open[0]?.baseRefName !== membership.base.ref)
+        fail("Bottom open stack layer does not target the trunk");
+    if (stackAncestryGaps(prefix).length > 0)
+        fail("Stack prefix has stale parent boundaries");
+    await mapPool(open, 4, async (member) => {
+        const raw = await fetchRawSummaryPr(member.number, repo);
+        const summary = await summarizePollSummaryPr(raw, repo, { stackPrNumber: pr });
+        if (raw.headRefOid !== member.headRefOid ||
+            raw.baseRefOid !== member.baseRefOid ||
+            summary.readyReceipt !== true)
+            fail(`PR #${member.number} has no current Shepherd READY receipt`);
+    });
+    const latest = await readRestStackTopology(pr, repo);
+    const finalMembership = await readRestStackMembership(pr, repo);
+    if (!finalMembership ||
+        finalMembership.number !== initialMembership.number ||
+        finalMembership.base.ref !== initialMembership.base.ref ||
+        JSON.stringify(finalMembership.pull_requests.map((member) => member.number)) !==
+            JSON.stringify(latest.ordered.map((member) => member.number)) ||
+        latest.stackNumber !== topology.stackNumber ||
+        JSON.stringify(latest.ordered) !== JSON.stringify(topology.ordered))
+        fail("Native stack changed while validating merge readiness");
+}
+function guardMember(member) {
+    return {
+        pr: member.number,
+        headRefName: member.headRefName,
+        headRefOid: member.headRefOid,
+        baseRefName: member.baseRefName,
+    };
+}
+function fail(message) {
+    throw new ShepherdError(`${message}; rerun the --stack --merge selector before applying this request`, EXIT.UNAVAILABLE);
+}

package/bin/commands/rule-auto-resolve.mjs

@@ -1,5 +1,6 @@
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { runJournal } from "./journal/index.mjs";
+import { canGenerateGithubMutation } from "../github/mutation-policy.mjs";
 import { decorateAutoResolveError, formatRuleAutoResolveJournalItem, minimizedItem, reasonClause, reasonsForError, resolvedThread, ruleAutoResolveBody, uniqueReasons, } from "./rule-auto-resolve-format.mjs";
 const EMPTY = {
     threadIds: [],
@@ -28,9 +29,14 @@ export async function applySuppressedRuleAutoResolve(input) {
             reviewSummaryIds: input.partition.ruleAutoResolveReviewSummaryIds,
         };
     }
-    const commentIds = input.partition.ruleAutoResolveCommentIds.filter((id) => input.partition.suppressedCommentIds.has(id));
-    const reviewSummaryIds = input.partition.ruleAutoResolveReviewSummaryIds.filter((id) => input.partition.suppressedReviewSummaryIds.has(id));
-    const threadIds = input.partition.ruleAutoResolveThreadIds.filter((id) => input.partition.suppressedThreadIds.has(id));
+    const canMinimize = (items, id) => canGenerateGithubMutation(items.find((item) => item.id === id)?.viewerCanMinimize, "minimize");
+    const threadFor = (id) => input.batch.reviewThreads.find((thread) => thread.id === id);
+    const commentIds = input.partition.ruleAutoResolveCommentIds.filter((id) => input.partition.suppressedCommentIds.has(id) && canMinimize(input.batch.comments, id));
+    const reviewSummaryIds = input.partition.ruleAutoResolveReviewSummaryIds.filter((id) => input.partition.suppressedReviewSummaryIds.has(id) &&
+        canMinimize(input.batch.reviewSummaries, id));
+    const threadIds = input.partition.ruleAutoResolveThreadIds.filter((id) => input.partition.suppressedThreadIds.has(id) &&
+        threadFor(id)?.isResolved === false &&
+        canGenerateGithubMutation(threadFor(id)?.viewerCanResolve, "resolve"));
     const minimizeIds = [...commentIds, ...reviewSummaryIds];
     const [minimized, resolved] = await Promise.all([
         minimizeIds.length > 0

package/bin/commands/shepherd-journal.d.mts

@@ -4,11 +4,12 @@ export declare const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE: string;
+export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Read each body under `## Review summaries (first look)` and journal any warranted note before review mutations.";
+/** The concrete `apply journal` command. The placeholder is single-quoted so a substituted decision stays literal in the shell. */
+export declare function buildShepherdJournalCommand(prReference: string | number): string;
 /**
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
- * threads/comments from their headings, cite reviews by ID) is invariant across every
- * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
- * of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts minimal").
+ * threads/comments by heading URL, cite reviews by ID) is a short clause, so it stays inline:
+ * a separate playbook would cost the agent an extra read turn that outweighs the clause.
  */
 export declare function buildShepherdJournalInstruction(prReference: string | number): string;

package/bin/commands/shepherd-journal.mjs

@@ -1,20 +1,21 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
-import { playbookPointer } from "./playbook-pointer.mjs";
 export const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = `Read each body under \`## Review summaries (first look)\` and journal any warranted note before review mutations. ${playbookPointer("Shepherd Journal")}`;
+export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = `Read each body under \`## Review summaries (first look)\` and journal any warranted note before review mutations.`;
+/** The concrete `apply journal` command. The placeholder is single-quoted so a substituted decision stays literal in the shell. */
+export function buildShepherdJournalCommand(prReference) {
+    return `${buildPrShepherdCommand(["apply", "journal", String(prReference)]).text} '- <decision>'`;
+}
 /**
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
- * threads/comments from their headings, cite reviews by ID) is invariant across every
- * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
- * of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts minimal").
+ * threads/comments by heading URL, cite reviews by ID) is a short clause, so it stays inline:
+ * a separate playbook would cost the agent an extra read turn that outweighs the clause.
  */
 export function buildShepherdJournalInstruction(prReference) {
-    // Single-quote the placeholder so a substituted decision stays literal in the shell.
-    const command = `${buildPrShepherdCommand(["apply", "journal", String(prReference)]).text} '- <decision>'`;
-    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`${command}\`. ${playbookPointer("Shepherd Journal")}`;
+    const command = buildShepherdJournalCommand(prReference);
+    return `Journal key decisions or rejections with URLs or IDs: \`${command}\``;
 }

package/bin/commands/stack-drain.d.mts

@@ -1,3 +1,4 @@
+export { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mts";
 import type { PollSummaryItem, PollSummaryResult, StackNextAction } from "../types.mts";
 export interface StackPlan {
     action: StackNextAction;
@@ -17,14 +18,5 @@ export declare function retargetWaitPlan(first: PollSummaryItem): StackPlan;
 export declare function idleWaitPlan(idle: PollSummaryItem[]): StackPlan;
 export declare function describeIdleLayers(idle: PollSummaryItem[]): string;
 export declare function appendAutonomousInstructions(instructions: string[], candidates: PollSummaryItem[]): void;
-/** Layers only a human can resolve: a closed dependency, an unverified state, or an escalation. */
-export interface HumanHandoffs {
-    closedDependency?: PollSummaryItem;
-    unverified?: PollSummaryItem;
-    escalated: PollSummaryItem[];
-}
-export declare function findHumanHandoffs(result: PollSummaryResult): HumanHandoffs | undefined;
-/** Name every human handoff; `stop` when no autonomous work precedes it. */
-export declare function appendHumanHandoffInstructions(instructions: string[], { closedDependency, unverified, escalated }: HumanHandoffs, stop: boolean): void;
 export declare function isStackLayerReady(item: PollSummaryItem): boolean;
 export declare function stackPosition(item: PollSummaryItem): number;

package/bin/commands/stack-drain.mjs

@@ -1,7 +1,10 @@
-import { playbookPointer } from "./playbook-pointer.mjs";
+import { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mjs";
+export { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mjs";
 import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
+import { buildMergeCommandPlan, renderMergeCommand } from "./iterate/merge.mjs";
 function readyPrefixTop(result) {
     const layers = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
     if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
@@ -40,17 +43,51 @@ export function planPrefixDrain(result, mergeRequested) {
         item.action !== "escalate" &&
         (!isStackLayerReady(item) || staleChildren.has(item.pr))), staleChildren);
     const span = open[0]?.pr === top.pr ? "that layer alone" : `PR #${top.pr} and every unmerged layer below it`;
-    const method = stackMergeFlag(result.allowedMergeMethods);
-    if ("unavailable" in method) {
-        return {
-            action: "escalate",
-            stackMergeable: false,
-            instructions: [`1. ${method.unavailable}`],
-        };
+    const instructions = [];
+    if (getGithubTransport() === "rest" || top.transport === "rest") {
+        // Upper layers target their parent; the prefix merges into the stack trunk.
+        const trunk = result.prs.find((item) => item.baseRefName === top.stack.baseRefName);
+        const plan = buildMergeCommandPlan({
+            transport: "rest",
+            pr: top.pr,
+            repo: result.repo,
+            nodeId: "",
+            headSha: top.headRefOid,
+            queue: trunk?.requiresMergeQueue === true,
+            queueKnown: trunk?.requiresMergeQueue !== undefined,
+            allowedMergeMethods: result.allowedMergeMethods,
+            expectedStack: {
+                number: top.stack.number,
+                baseRefName: top.stack.baseRefName,
+                prefix: [...result.prs]
+                    .sort((left, right) => stackPosition(left) - stackPosition(right))
+                    .filter((item) => stackPosition(item) <= stackPosition(top))
+                    .map((item) => ({
+                    pr: item.pr,
+                    headRefName: item.headRefName,
+                    headRefOid: item.headRefOid,
+                    baseRefName: item.baseRefName,
+                })),
+            },
+        });
+        if ("unavailable" in plan)
+            return {
+                action: "escalate",
+                stackMergeable: false,
+                instructions: [`1. ${plan.unavailable}`],
+            };
+        instructions[0] = `1. PR #${top.pr} is the highest ready layer of native stack #${top.stack.number}. Run \`${renderMergeCommand(plan.command)}\` to request merging ${span}. If status is \`pending\`, rerun that command at the configured cadence to resume its UUID. \`enqueued\` is not merged. Shepherd revalidates every open lower layer's READY receipt before submission.`;
+    }
+    else {
+        const method = stackMergeFlag(result.allowedMergeMethods);
+        if ("unavailable" in method)
+            return {
+                action: "escalate",
+                stackMergeable: false,
+                instructions: [`1. ${method.unavailable}`],
+            };
+        instructions[0] = `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\`, then rerun that merge command. Do not rebase, push, or run \`gh stack push\`.`;
     }
-    const instructions = [
-        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. ${playbookPointer("Stack merge")}`,
-    ];
     appendAutonomousInstructions(instructions, above.sessions);
     appendMarkReadyInstructions(instructions, above.markReady);
     const handoffs = findHumanHandoffs(result);
@@ -101,7 +138,7 @@ function sessionInstruction(item) {
     const queueNote = item.queueRemoval
         ? " That session fixes failing queue CI, or escalates when the removal has no concrete fix."
         : "";
-    return `${removal} Run \`${item.pollCommand}\` for PR #${item.pr}.${queueNote}`;
+    return `${removal} Run \`${item.pollCommand}\`.${queueNote}`;
 }
 export function describeIdleLayers(idle) {
     return idle.map((item) => `PR #${item.pr} (${item.reasons.join(", ")})`).join("; ");
@@ -109,35 +146,11 @@ export function describeIdleLayers(idle) {
 export function appendAutonomousInstructions(instructions, candidates) {
     if (candidates.length === 0)
         return;
-    instructions.push(`${instructions.length + 1}. Start or delegate one-PR sessions only for rows marked \`owned\`. Leave every other author's layer untouched. Owned layers can proceed concurrently.`);
+    instructions.push(`${instructions.length + 1}. Start or delegate concurrent one-PR sessions only for \`owned\` rows. Leave other layers untouched.`);
     for (const item of candidates) {
         instructions.push(`${instructions.length + 1}.${sessionInstruction(item)}`);
     }
 }
-export function findHumanHandoffs(result) {
-    const lastOpen = result.prs.filter((item) => item.state === "OPEN").at(-1);
-    const closedDependency = result.prs.find((item) => item.state === "CLOSED" && lastOpen && stackPosition(item) < stackPosition(lastOpen));
-    const unverified = result.prs.find((item) => item.state !== "OPEN" && item.state !== "MERGED");
-    const escalated = result.prs.filter((item) => item.action === "escalate");
-    return closedDependency || unverified || escalated.length > 0
-        ? { closedDependency, unverified, escalated }
-        : undefined;
-}
-/** Name every human handoff; `stop` when no autonomous work precedes it. */
-export function appendHumanHandoffInstructions(instructions, { closedDependency, unverified, escalated }, stop) {
-    const ask = stop ? "Stop and ask" : "After autonomous shepherding, ask";
-    if (closedDependency) {
-        instructions.push(`${instructions.length + 1}. PR #${closedDependency.pr} was closed without merging below an open layer. ${ask} the stack owner whether to restore that dependency or rebuild the upper branches.`);
-    }
-    if (unverified && unverified.pr !== closedDependency?.pr) {
-        instructions.push(`${instructions.length + 1}. PR #${unverified.pr} has state \`${unverified.state}\` rather than open or merged. ${ask} the stack owner to reconcile this layer before declaring the stack complete.`);
-    }
-    for (const item of escalated) {
-        if (item.pr === closedDependency?.pr || item.pr === unverified?.pr)
-            continue;
-        instructions.push(`${instructions.length + 1}. PR #${item.pr} requires human action (${item.reasons.join(", ")}). ${stop ? "Stop for that decision." : "Keep shepherding other PRs before the handoff."}`);
-    }
-}
 export function isStackLayerReady(item) {
     return item.stack !== undefined && stackLayerBlockReason(item) === undefined;
 }

package/bin/commands/stack-handoffs.d.mts

@@ -0,0 +1,10 @@
+import type { PollSummaryItem, PollSummaryResult } from "../types.mts";
+/** Layers only a human can resolve: a closed dependency, an unverified state, or an escalation. */
+export interface HumanHandoffs {
+    closedDependency?: PollSummaryItem;
+    unverified?: PollSummaryItem;
+    escalated: PollSummaryItem[];
+}
+export declare function findHumanHandoffs(result: PollSummaryResult): HumanHandoffs | undefined;
+/** Name every human handoff; `stop` when no autonomous work precedes it. */
+export declare function appendHumanHandoffInstructions(instructions: string[], { closedDependency, unverified, escalated }: HumanHandoffs, stop: boolean): void;

package/bin/commands/stack-handoffs.mjs

@@ -0,0 +1,25 @@
+import { stackPosition } from "./stack-drain.mjs";
+export function findHumanHandoffs(result) {
+    const lastOpen = result.prs.filter((item) => item.state === "OPEN").at(-1);
+    const closedDependency = result.prs.find((item) => item.state === "CLOSED" && lastOpen && stackPosition(item) < stackPosition(lastOpen));
+    const unverified = result.prs.find((item) => item.state !== "OPEN" && item.state !== "MERGED");
+    const escalated = result.prs.filter((item) => item.action === "escalate");
+    return closedDependency || unverified || escalated.length > 0
+        ? { closedDependency, unverified, escalated }
+        : undefined;
+}
+/** Name every human handoff; `stop` when no autonomous work precedes it. */
+export function appendHumanHandoffInstructions(instructions, { closedDependency, unverified, escalated }, stop) {
+    const ask = stop ? "Stop and ask" : "After autonomous shepherding, ask";
+    if (closedDependency) {
+        instructions.push(`${instructions.length + 1}. PR #${closedDependency.pr} was closed without merging below an open layer. ${ask} the stack owner whether to restore that dependency or rebuild the upper branches.`);
+    }
+    if (unverified && unverified.pr !== closedDependency?.pr) {
+        instructions.push(`${instructions.length + 1}. PR #${unverified.pr} has state \`${unverified.state}\` rather than open or merged. ${ask} the stack owner to reconcile this layer before declaring the stack complete.`);
+    }
+    for (const item of escalated) {
+        if (item.pr === closedDependency?.pr || item.pr === unverified?.pr)
+            continue;
+        instructions.push(`${instructions.length + 1}. PR #${item.pr} requires human action (${item.reasons.join(", ")}). ${stop ? "Stop for that decision." : "Keep shepherding other PRs before the handoff."}`);
+    }
+}

package/bin/commands/stack-stall.d.mts

@@ -12,3 +12,8 @@ export declare function applyStackStallGuard(planned: {
     owner: string;
     name: string;
 }, stallTimeoutSeconds: number): Promise<PollSummaryResult>;
+/**
+ * Unix seconds when an unchanged idle stack plan trips `stall-timeout`, or undefined when no
+ * stack timer is running. Event mode schedules its next tick no later than this.
+ */
+export declare function readStackStallDeadline(result: PollSummaryResult, stallTimeoutSeconds: number): Promise<number | undefined>;

package/bin/commands/stack-stall.mjs

@@ -42,6 +42,17 @@ export async function applyStackStallGuard(planned, repo, stallTimeoutSeconds) {
         ],
     };
 }
+/**
+ * Unix seconds when an unchanged idle stack plan trips `stall-timeout`, or undefined when no
+ * stack timer is running. Event mode schedules its next tick no later than this.
+ */
+export async function readStackStallDeadline(result, stallTimeoutSeconds) {
+    const [owner, repo] = result.repo.split("/");
+    if (result.selection.kind !== "stack" || stallTimeoutSeconds <= 0 || !owner || !repo)
+        return undefined;
+    const read = await readStackStallState({ owner, repo, stack: result.selection.stackNumber });
+    return read.ok && read.state ? read.state.firstSeenAt + stallTimeoutSeconds : undefined;
+}
 function stackStateUnavailable(result, reason) {
     return {
         ...result,

package/bin/commands/stack-work.d.mts

@@ -29,4 +29,9 @@ export declare function splitStackWork(candidates: PollSummaryItem[], staleChild
  * first because only the one-PR session reads the full review context.
  */
 export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
+/**
+ * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
+ * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ */
+export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string): "shepherd" | "escalate";
 export {};

package/bin/commands/stack-work.mjs

@@ -1,3 +1,5 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
 /**
  * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
  * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
@@ -30,9 +32,39 @@ export function splitStackWork(candidates, staleChildren) {
  */
 export function appendMarkReadyInstructions(instructions, layers) {
     for (const item of layers) {
+        if (!item.owned) {
+            instructions.push(`${instructions.length + 1}. PR #${item.pr} is not owned. Leave its draft state unchanged.`);
+            continue;
+        }
+        if (item.transport === "rest") {
+            const command = buildPrShepherdCommand([
+                "iterate",
+                formatPrUrl(item.repo, item.pr),
+                "--transport",
+                "rest",
+            ]).text;
+            instructions.push(`${instructions.length + 1}. Run \`${item.pollCommand}\` first for PR #${item.pr}. If it returns \`[WAIT]\` saying the draft is held only because automatic mark-ready is disabled, run \`${command}\` to authorize the CCR ready transition; otherwise follow the probe's instructions.`);
+            continue;
+        }
         instructions.push(`${instructions.length + 1}. Automatic mark-ready is disabled, so marking PR #${item.pr} ready for review is your step. Run \`${item.pollCommand}\` first. If it returns \`[WAIT]\` saying PR #${item.pr} stays in draft because ${AUTO_MARK_READY_DISABLED_HOLD}, run \`gh pr ready ${item.pr} -R ${item.repo}\`; otherwise complete its instructions and leave PR #${item.pr} in draft this round.`);
     }
 }
 function isProbed(item) {
     return item.pollProbe === true && item.pollCommand !== undefined;
 }
+/**
+ * Work exists, but every routed layer belongs to another author: rerunning the stack selector
+ * cannot change anything, so the caller reports the overview and stops instead.
+ */
+function onlyUnownedWork(layers) {
+    return layers.length > 0 && layers.every((item) => !item.owned);
+}
+/**
+ * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
+ * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ */
+export function appendStackRerunInstruction(instructions, layers, rerun) {
+    const stop = onlyUnownedWork(layers);
+    instructions.push(`${instructions.length + 1}. ${stop ? "No owned layer needs a session. Report this overview and stop." : rerun}`);
+    return stop ? "escalate" : "shepherd";
+}

package/bin/comments/existing-reply-scan.d.mts

@@ -0,0 +1,17 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type ReplyEvidence } from "../github/reply-recovery-read.mts";
+/**
+ * Threads whose last comment is already this exact Shepherd reply from the authenticated viewer.
+ *
+ * A cloud session can lose its state directory between ticks, taking the uncertain-reply
+ * records with it. With no local record to consult, GitHub is the only evidence of whether a
+ * reply already landed, so the `apply review` commands Shepherd generates in durable-state
+ * sessions opt in (`--adopt-existing-replies`) to checking it before posting. Direct apply
+ * requests never run this scan. A failed read never blocks the reply: it only means this
+ * safeguard had nothing to say. A batch fully covered by `preloaded` evidence (the
+ * apply-review preflight, read with no wait since) skips its read.
+ */
+export declare function findExistingReplies(context: {
+    repo: RepoInfo;
+    pr: number;
+}, ids: readonly string[], message: string, preloaded?: Map<string, ReplyEvidence>): Promise<string[]>;

package/bin/comments/existing-reply-scan.mjs

@@ -0,0 +1,41 @@
+import { readReplyRecoveryEvidence } from "../github/reply-recovery-read.mjs";
+import { addPrShepherdMarker } from "./marker.mjs";
+const BATCH = 10;
+/**
+ * Threads whose last comment is already this exact Shepherd reply from the authenticated viewer.
+ *
+ * A cloud session can lose its state directory between ticks, taking the uncertain-reply
+ * records with it. With no local record to consult, GitHub is the only evidence of whether a
+ * reply already landed, so the `apply review` commands Shepherd generates in durable-state
+ * sessions opt in (`--adopt-existing-replies`) to checking it before posting. Direct apply
+ * requests never run this scan. A failed read never blocks the reply: it only means this
+ * safeguard had nothing to say. A batch fully covered by `preloaded` evidence (the
+ * apply-review preflight, read with no wait since) skips its read.
+ */
+export async function findExistingReplies(context, ids, message, preloaded) {
+    if (ids.length === 0)
+        return [];
+    const marked = addPrShepherdMarker(message);
+    const found = [];
+    for (let offset = 0; offset < ids.length; offset += BATCH) {
+        const batch = ids.slice(offset, offset + BATCH);
+        try {
+            const evidence = batch.every((id) => preloaded?.has(id))
+                ? preloaded
+                : await readReplyRecoveryEvidence(context.repo, context.pr, batch);
+            for (const id of batch) {
+                const item = evidence.get(id);
+                const last = item?.comments.at(-1);
+                if (item &&
+                    last?.body === marked &&
+                    last.author?.toLowerCase() === item.viewer.toLowerCase()) {
+                    found.push(id);
+                }
+            }
+        }
+        catch {
+            /* Evidence is advisory here; the normal reply path still runs. */
+        }
+    }
+    return found;
+}

package/bin/comments/rate-limit.mjs

@@ -17,7 +17,7 @@ export function rateLimitFromGraphQlResult(messages, meta) {
     if (message)
         return buildRateLimitStop(message, meta);
     if (meta.stopOnZeroRemaining === true && meta.rateLimit?.remaining === 0) {
-        return buildRateLimitStop("GitHub GraphQL rate limit remaining is 0", meta);
+        return buildRateLimitStop(`GitHub ${meta.rateLimit?.resource === "core" ? "REST core" : "GraphQL"} rate limit remaining is 0`, meta);
     }
     return undefined;
 }
@@ -47,5 +47,5 @@ function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 export function isRateLimitMessage(message) {
-    return /rate limit|rate-limit|secondary limit|secondary rate/i.test(message);
+    return /rate limit|rate-limit|secondary limit|secondary rate|abuse detection/i.test(message);
 }

package/bin/comments/resolve.d.mts

@@ -1,6 +1,7 @@
 import { type RepoInfo } from "../github/client.mts";
 import type { ResolveOptions } from "../types.mts";
 import { type ResolveRateLimitStop } from "./rate-limit.mts";
+import { type ReplyEvidence } from "../github/reply-recovery-read.mts";
 export interface ResolveResult {
     repliedThreads: string[];
     resolvedThreads: string[];
@@ -26,12 +27,17 @@ export interface ResolveResult {
     /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
+    sessionRefusal?: string;
+    instructions?: string[];
     unrepliedThreads?: string[];
     unresolvedThreads?: string[];
     unminimizedComments?: string[];
     undismissedReviews?: string[];
 }
-export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: ResolveOptions): Promise<ResolveResult>;
+export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: ResolveOptions, preflight?: {
+    headSha?: string;
+    evidence: Map<string, ReplyEvidence>;
+}): Promise<ResolveResult>;
 /** @deprecated Compatibility alias; use `autoResolveThreads`. */
 export declare function autoResolveOutdated(threadIds: string[]): Promise<{
     resolved: string[];