pr-shepherd 0.56.5 → 0.57.0

package/bin/commands/poll.mjs

@@ -2,18 +2,14 @@ import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
 import { loadConfig } from "../config/load.mjs";
-import { quotaPollIntervalMs } from "./poll-quota.mjs";
+import { carryQuotaWarning, quotaPollIntervalMs } from "./poll-quota.mjs";
 import { onePrCancelFromPulls, onePrRateLimitTargets } from "./poll-rate-limit-cancel.mjs";
 import { createUntilTerminalRateLimitRetry } from "./poll-rate-limit-wait.mjs";
-import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
-function noteRuleAutoResolve(result) {
-    if (result.ruleAutoResolve?.summary)
-        process.stderr.write(`${result.ruleAutoResolve.summary}\n`);
-}
+import { writeDebounceProgress, writeRuleAutoResolveProgress, writeWaitProgress, } from "./poll-progress.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
-/** @deprecated Hidden implementation for the legacy `poll` alias. */
 export function runPoll(opts) {
     return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true, opts.intervalSeconds / 60);
 }
@@ -32,7 +28,6 @@ async function runPollCore(opts) {
     const untilTerminal = untilTerminalOpt === true;
     let lastWaitSignature = null;
     let pendingQuotaWarning;
-    // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
     const rateLimitRetry = createUntilTerminalRateLimitRetry();
@@ -42,7 +37,6 @@ async function runPollCore(opts) {
         const remainingBefore = untilTerminal
             ? Number.POSITIVE_INFINITY
             : timeoutMs - (Date.now() - start);
-        // Cache only internal continuation ticks; returned ticks must fetch BatchPr.
         const allowCache = debounceUntil === null && remainingBefore + TIMER_DRIFT_TOLERANCE_MS >= intervalMs;
         const iterateTick = (fingerprintCache) => runIterate({
             ...iterateOpts,
@@ -75,14 +69,12 @@ async function runPollCore(opts) {
         };
         lastResult = await runTick(allowCache);
         prNumber ??= lastResult.pr;
-        if (lastResult.quotaWarning !== undefined)
-            pendingQuotaWarning = lastResult.quotaWarning;
+        pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, lastResult.quotaWarning);
         const refreshIfReturning = async () => {
             if (lastResult?.fingerprintReused !== true)
                 return;
             lastResult = await runTick(false);
-            if (lastResult.quotaWarning !== undefined)
-                pendingQuotaWarning = lastResult.quotaWarning;
+            pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, lastResult.quotaWarning);
         };
         if (untilTerminal &&
             pendingQuotaWarning !== undefined &&
@@ -92,7 +84,7 @@ async function runPollCore(opts) {
             if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
                 debounceUntil ??= Date.now() + debounceMs;
                 const remainingMs = Math.max(debounceUntil - Date.now(), 0);
-                noteRuleAutoResolve(lastResult);
+                writeRuleAutoResolveProgress(lastResult);
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
                 continue;
@@ -110,7 +102,7 @@ async function runPollCore(opts) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;
-            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS);
+            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS, getGithubTransport());
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
                 if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
@@ -127,7 +119,7 @@ async function runPollCore(opts) {
                 verbose,
                 lastWaitSignature,
             });
-            noteRuleAutoResolve(lastResult);
+            writeRuleAutoResolveProgress(lastResult);
             await sleep(sleepMs);
             continue;
         }
@@ -136,7 +128,7 @@ async function runPollCore(opts) {
             !pastDebounce) {
             debounceUntil = null;
             const elapsedMs = Date.now() - start;
-            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS);
+            const sleepMs = quotaPollIntervalMs(quotaBands, lastResult.apiUsage, intervalMs, MAX_TIMER_MS, getGithubTransport());
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
                 if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
@@ -144,12 +136,12 @@ async function runPollCore(opts) {
                     break;
                 }
             }
-            noteRuleAutoResolve(lastResult);
+            writeRuleAutoResolveProgress(lastResult);
             await sleep(sleepMs);
             continue;
         }
         if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
-            noteRuleAutoResolve(lastResult);
+            writeRuleAutoResolveProgress(lastResult);
             debounceUntil ??= Date.now() + debounceMs;
             const remainingMs = debounceUntil - Date.now();
             if (remainingMs > 0) {

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

@@ -1,7 +1,8 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
 import type { ApiUsage, GraphqlQuotaWarning } from "../types.mts";
+import type { GithubTransport } from "../github/transport.mts";
 /** Claim GraphQL and REST core warnings separately, then present one result. */
 export declare function selectQuotaWarning(key: {
     owner: string;
     repo: string;
-}, bands: GraphqlQuotaWarningBand[], usage: ApiUsage, persist: boolean): Promise<GraphqlQuotaWarning | undefined>;
+}, bands: GraphqlQuotaWarningBand[], usage: ApiUsage, persist: boolean, transport?: Exclude<GithubTransport, "auto">): Promise<GraphqlQuotaWarning | undefined>;

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 {};