pr-shepherd 0.52.1 → 0.53.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -147,22 +147,24 @@ needed, every selected PR is complete, the bounded timeout expires, or `--until-
 configured GraphQL quota-warning band. Explicit PR sets give each actionable row an exact single-PR
 `pollCommand`, so independent rows can proceed before the next aggregate poll.
 
-Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself; only
-`--stack --merge` can emit a bottom-layer merge command for the agent. An unready layer (draft, missing a READY
-receipt, conflicting, failing, or stale) returns stack-level `SHEPHERD` with one-PR Shepherd instructions for
-the affected layers. A draft or other unready lower layer marks every higher open layer with
-`blockedByPr`; review and CI sessions on independent layers may proceed concurrently, but an upper
-draft cannot transition to ready until every lower layer has its READY receipt. With automatic
-mark-ready disabled, the instructions ask the agent to mark a clean, unblocked draft layer ready. A
-queued stack, or one whose remaining layers can only wait, returns `WAIT`; an idle `WAIT` that stays unchanged past the stall timeout returns `ESCALATE` with `stall-timeout`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
+Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself. Every
+layer that still has work gets its own one-PR session on the same tick, including a clean draft
+whose session marks it ready. Layers do not wait for a lower layer's READY receipt, so their
+ready-delays overlap. With automatic mark-ready disabled, the instructions ask the agent to mark
+a clean draft ready after its probe. A queued stack, or one whose remaining layers can only wait,
+returns `WAIT`; an idle `WAIT` that stays unchanged past the stall timeout returns `ESCALATE` with
+`stall-timeout`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
 topology returns `ESCALATE` for human direction after any other shepherdable PRs are handled;
 until then, `SHEPHERD` remains the immediate action and lists the human blockers too.
 
-With `--stack --merge`, a READY bottom open layer that GitHub has retargeted onto the stack base
-returns `MERGE` with `gh stack merge <PR number> --yes --squash`, which merges or enqueues that layer
-alone; unready upper layers keep their one-PR sessions alongside it. After each merge, GitHub
-retargets the next layer, so the rerun drains the stack layer by layer until it returns `CANCEL`. API and MCP aggregate calls perform one summary tick and leave recurrence to the
-caller.
+With `--stack --merge`, the highest open layer whose open lower layers all have current READY
+receipts, and whose bottom open layer GitHub has retargeted onto the stack base, returns `MERGE`
+with `gh stack merge <that PR number> --yes --squash`. That lands the named layer and every
+unmerged layer below it. When the base uses a merge queue, the same command queues the prefix
+together and GitHub evaluates each layer from the bottom; a failure ejects that layer and those
+above it. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
+the next layer, so the rerun continues until the stack returns `CANCEL`. API and MCP aggregate
+calls perform one summary tick and leave recurrence to the caller.
 
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 

package/bin/cli/iterate-instructions.mjs

@@ -4,18 +4,6 @@ import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
 import { AUTO_MARK_READY_DISABLED_HOLD } from "../commands/stack-work.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-const STACK_LAYER_BLOCK_REASONS = {
-    closed: "was closed without merging",
-    draft: "is still a draft",
-    conflicting: "has merge conflicts",
-    "queue-removal": "has an unacknowledged merge-queue removal",
-    "failing-checks": "has failing checks",
-    "review-work": "has unresolved review work",
-    "checks-in-progress": "has checks in progress",
-    "merge-state": "is not in a mergeable state",
-    "no-ready-receipt": "has no current Shepherd READY receipt",
-    "stale-ancestry": "is not rebased onto its parent layer's current head",
-};
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
@@ -76,20 +64,13 @@ function buildStackDraftHoldInstruction(result, hold) {
         formatPrUrl(result.repo, result.pr),
         "--until-terminal",
     ]).text;
-    const lowerLayer = hold.kind === "lower-layer-not-ready" ? hold.lowerLayer : undefined;
     const handoff = `a \`--stack\` selector listed this session, finish that selector's remaining steps and rerun it with its original flags; otherwise run ${inlineCode(stackCommand)}, adding \`--merge\` when merging was requested.`;
-    const instruction = lowerLayer
-        ? `PR #${result.pr} stays in draft because lower stack layer PR #${lowerLayer.pr} ${STACK_LAYER_BLOCK_REASONS[lowerLayer.reason]}, so repeating this one-PR session cannot advance it. Advance PR #${lowerLayer.pr} first: if ${handoff}`
-        : `PR #${result.pr} stays in draft because ${holdReason(hold)}, so repeating this one-PR session cannot advance it. If ${handoff}`;
+    const reason = hold.kind === "auto-mark-ready-disabled" ? AUTO_MARK_READY_DISABLED_HOLD : hold.kind;
+    const instruction = `PR #${result.pr} stays in draft because ${reason}, so repeating this one-PR session cannot advance it. If ${handoff}`;
     return result.quotaWarning
         ? buildQuotaAwareContinuation(result.quotaWarning, instruction)
         : instruction;
 }
-function holdReason(hold) {
-    return hold.kind === "auto-mark-ready-disabled"
-        ? AUTO_MARK_READY_DISABLED_HOLD
-        : "its lower stack layers could not be verified";
-}
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }

package/bin/cli/poll-summary-formatter.mjs

@@ -43,12 +43,11 @@ function formatItem(item) {
         : "";
     const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
     const readyReceipt = item.readyReceipt ? " · Shepherd READY completion `verified`" : "";
-    const blockedBy = item.blockedByPr ? ` · stack blocked by PR #${item.blockedByPr}` : "";
     const checks = item.checks;
     const review = item.review;
     return [
         `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
-        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${blockedBy}${stack}`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${stack}`,
         `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]

package/bin/commands/iterate/api-usage.mjs

@@ -1,5 +1,5 @@
 import { loadConfig } from "../../config/load.mjs";
-import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
+import { summarizeApiTelemetry, withGraphqlCredentialFingerprint, } from "../../github/api-telemetry.mjs";
 import { evaluateWorktreeGraphqlQuotaWarning } from "../../state/graphql-quota-warnings.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
@@ -17,7 +17,7 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
                 ...band,
                 pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
             }));
-            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, apiUsage.graphql, persistWarning);
+            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, withGraphqlCredentialFingerprint(apiUsage.graphql), persistWarning);
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;

package/bin/commands/iterate/index.mjs

@@ -22,7 +22,7 @@ import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.m
 import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
 import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
-import { findParentMarkReadyBlock, heldByLowerLayer, stackDraftHold } from "./parent-first.mjs";
+import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
@@ -175,11 +175,8 @@ async function runIterateCore(opts) {
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    const parentBlock = canMarkReady
-        ? await findParentMarkReadyBlock(report, { owner: repoOwner, name: repoName })
-        : undefined;
     const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
-    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !parentBlock && autoMarkReady, base, report);
+    const markReadyResult = await markReadyIfAuthorized(canMarkReady && autoMarkReady, base, report);
     if (markReadyResult)
         return markReadyResult;
     if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
@@ -209,19 +206,13 @@ async function runIterateCore(opts) {
             log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
-    const hold = stackDraftHold(report, autoMarkReady, parentBlock);
+    const hold = stackDraftHold(report, autoMarkReady);
     const wait = {
         ...base,
         action: "wait",
         log: buildWaitLog(base),
         ...(hold && { stackDraftHold: hold }),
     };
-    // The lower layer's own session owns progress here, so this draft cannot
-    // stall; its stall clock restarts once that layer releases it.
-    if (heldByLowerLayer(wait)) {
-        await clearStallState(stallKey);
-        return wait;
-    }
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, report, reviewSummaryIds);
 }
 async function recordReadyReceipt(key, report) {

package/bin/commands/iterate/parent-first.d.mts

@@ -1,25 +1,8 @@
-import type { RepoInfo } from "../../github/client.mts";
-import type { IterateResult, ShepherdReport, StackDraftHold, StackLowerLayerBlock } from "../../types.mts";
+import type { ShepherdReport, StackDraftHold } from "../../types.mts";
 /**
- * What keeps a draft child from being marked ready: the lowest blocking lower layer,
- * or a stack read that could not attribute the block to one.
+ * A native stack draft this one-PR session cannot promote because it is ready
+ * and automatic mark-ready is off. A draft that is not ready yet keeps the
+ * ordinary wait. A clean draft is marked ready on its own, without waiting
+ * for lower layers.
  */
-export type ParentMarkReadyBlock = StackLowerLayerBlock | "unverifiable";
-/**
- * Draft children may only be converted after their immediate parent has
- * independently completed a one-PR ready-delay and the stack boundary is
- * still linear.  A failed or incomplete stack read blocks this mutation but
- * does not block ordinary review/CI work in the caller.
- */
-export declare function findParentMarkReadyBlock(report: ShepherdReport, repo: RepoInfo): Promise<ParentMarkReadyBlock | undefined>;
-/**
- * A native stack draft this one-PR session cannot promote: a lower layer blocks it, or
- * automatic mark-ready is off. Undefined when the session can still advance the PR by
- * iterating.
- */
-export declare function stackDraftHold(report: ShepherdReport, autoMarkReady: boolean, parentBlock: ParentMarkReadyBlock | undefined): StackDraftHold | undefined;
-/**
- * The lower layer a held draft waits on. That layer's own session owns this draft's
- * progress, so the draft neither stalls nor keeps polling while it waits.
- */
-export declare function heldByLowerLayer(result: IterateResult): StackLowerLayerBlock | undefined;
+export declare function stackDraftHold(report: ShepherdReport, autoMarkReady: boolean): StackDraftHold | undefined;

package/bin/commands/iterate/parent-first.mjs

@@ -1,70 +1,13 @@
-import { fetchPollSummary } from "../../github/poll-summary.mjs";
-import { stackLayerBlockReason } from "../stack-layer-readiness.mjs";
 /**
- * Draft children may only be converted after their immediate parent has
- * independently completed a one-PR ready-delay and the stack boundary is
- * still linear.  A failed or incomplete stack read blocks this mutation but
- * does not block ordinary review/CI work in the caller.
+ * A native stack draft this one-PR session cannot promote because it is ready
+ * and automatic mark-ready is off. A draft that is not ready yet keeps the
+ * ordinary wait. A clean draft is marked ready on its own, without waiting
+ * for lower layers.
  */
-export async function findParentMarkReadyBlock(report, repo) {
-    const stack = report.mergeStatus.mergeRequirements?.stack;
-    if (!stack || stack.position === 1)
-        return undefined;
-    if (stack.position < 1)
-        return "unverifiable";
-    try {
-        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
-        const child = summary.prs.find((item) => item.pr === report.pr);
-        const lowerLayers = summary.prs
-            .filter((item) => (item.stack?.position ?? Number.MAX_SAFE_INTEGER) < stack.position)
-            .sort((left, right) => (left.stack?.position ?? Number.MAX_SAFE_INTEGER) -
-            (right.stack?.position ?? Number.MAX_SAFE_INTEGER));
-        if (!child || child.state !== "OPEN" || lowerLayers.length !== stack.position - 1)
-            return "unverifiable";
-        // A stale boundary means that layer is no longer based on the parent it was
-        // reviewed against. Gaps above this child do not affect its promotion boundary.
-        const staleChildren = new Set(summary.stackAncestry?.map((gap) => gap.childPr));
-        for (const layer of lowerLayers) {
-            // A merged layer is already satisfied; GitHub may have retargeted the
-            // layer above it to the trunk as part of the merge.
-            if (layer.state === "MERGED")
-                continue;
-            const reason = staleChildren.has(layer.pr) ? "stale-ancestry" : stackLayerBlockReason(layer);
-            if (reason)
-                return { pr: layer.pr, reason };
-        }
-        // This layer's own stale boundary belongs to its own session's repair; the
-        // earlier stale-ancestry read missed it, so this snapshot is unsettled.
-        return staleChildren.has(report.pr) ? "unverifiable" : undefined;
-    }
-    catch {
-        // Never convert a child draft based on an unverifiable parent.
-        return "unverifiable";
-    }
-}
-/**
- * A native stack draft this one-PR session cannot promote: a lower layer blocks it, or
- * automatic mark-ready is off. Undefined when the session can still advance the PR by
- * iterating.
- */
-export function stackDraftHold(report, autoMarkReady, parentBlock) {
+export function stackDraftHold(report, autoMarkReady) {
     if (!report.mergeStatus.mergeRequirements?.stack || !report.mergeStatus.isDraft)
         return undefined;
-    // Any lower-layer block outranks the session flag: even with automatic
-    // mark-ready enabled, this draft cannot advance until that layer does, and a
-    // lower-layer read that failed must not hide behind the flag.
-    if (parentBlock === "unverifiable")
-        return { kind: "lower-layer-not-ready" };
-    if (parentBlock)
-        return { kind: "lower-layer-not-ready", lowerLayer: parentBlock };
+    if (report.status !== "READY" || report.mergeStatus.blockingBotReviewInProgress)
+        return undefined;
     return autoMarkReady ? undefined : { kind: "auto-mark-ready-disabled" };
 }
-/**
- * The lower layer a held draft waits on. That layer's own session owns this draft's
- * progress, so the draft neither stalls nor keeps polling while it waits.
- */
-export function heldByLowerLayer(result) {
-    return result.action === "wait" && result.stackDraftHold?.kind === "lower-layer-not-ready"
-        ? result.stackDraftHold.lowerLayer
-        : undefined;
-}

package/bin/commands/poll-quota.mjs

@@ -1,5 +1,5 @@
 import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
-import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
+import { summarizeApiTelemetry, withGraphqlCredentialFingerprint, } 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;
@@ -44,5 +44,5 @@ export async function aggregateQuotaWarning(result, bands, intervalSeconds) {
     return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
         ...band,
         pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
-    })), usage, true);
+    })), withGraphqlCredentialFingerprint(usage), true);
 }

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

@@ -1,7 +1,7 @@
 /* eslint-disable max-lines */
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
-import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planBottomDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
+import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planPrefixDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export function withPollSummaryInstructions(result, mergeRequested) {
@@ -14,59 +14,44 @@ export function planPollSummary(result, mergeRequested) {
     }
     const prs = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
     const staleChildren = new Set(result.stackAncestry?.map((gap) => gap.childPr) ?? []);
-    const firstUnready = prs.find((item) => item.state === "OPEN" && (!isStackLayerReady(item) || staleChildren.has(item.pr)));
-    const blocked = prs.map((item) => firstUnready && item.state === "OPEN" && stackPosition(item) > stackPosition(firstUnready)
-        ? {
-            ...item,
-            ...(["cancel", "mark_ready", "merge"].includes(item.action) && {
-                action: "wait",
-                reasons: [...item.reasons, "lower-layer-not-ready"],
-            }),
-            blockedByPr: firstUnready.pr,
-            ...(item.isDraft &&
-                item.pollCommand && {
-                pollCommand: item.pollCommand.replace(" --until-terminal", " --timeout 1s --debounce 0s") +
-                    (item.pollCommand.includes("--no-auto-mark-ready") ? "" : " --no-auto-mark-ready"),
-                pollProbe: true,
-            }),
-        }
-        : item.state === "OPEN" &&
-            (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
-            ["cancel", "merge"].includes(item.action)
-            ? {
-                ...item,
-                action: "fix_code",
-                reasons: [
-                    ...item.reasons,
-                    staleChildren.has(item.pr) ? "stale-ancestry" : "ready-receipt-required",
-                ],
-            }
-            : item);
     const projected = {
         ...result,
-        prs: blocked.map((item) => {
-            if (item.state === "OPEN" && item.isInMergeQueue && item.action === "cancel") {
-                return {
+        prs: prs.map((item) => {
+            const needsOwnSession = item.state === "OPEN" &&
+                (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
+                ["cancel", "merge"].includes(item.action);
+            const layer = needsOwnSession
+                ? {
                     ...item,
+                    action: "fix_code",
+                    reasons: [
+                        ...item.reasons,
+                        staleChildren.has(item.pr) ? "stale-ancestry" : "ready-receipt-required",
+                    ],
+                }
+                : item;
+            if (layer.state === "OPEN" && layer.isInMergeQueue && layer.action === "cancel") {
+                return {
+                    ...layer,
                     action: "wait",
-                    reasons: [...item.reasons, "already-in-merge-queue"],
+                    reasons: [...layer.reasons, "already-in-merge-queue"],
                 };
             }
-            if (item.state === "CLOSED" && closedDependency(blocked, item.pr)) {
+            if (layer.state === "CLOSED" && closedDependency(prs, layer.pr)) {
                 return {
-                    ...item,
+                    ...layer,
                     action: "escalate",
-                    reasons: [...item.reasons, "closed-unmerged-dependency"],
+                    reasons: [...layer.reasons, "closed-unmerged-dependency"],
                 };
             }
-            if (item.state !== "OPEN" && item.state !== "MERGED") {
+            if (layer.state !== "OPEN" && layer.state !== "MERGED") {
                 return {
-                    ...item,
+                    ...layer,
                     action: "escalate",
-                    reasons: [...item.reasons, "unverified-stack-state"],
+                    reasons: [...layer.reasons, "unverified-stack-state"],
                 };
             }
-            return item;
+            return layer;
         }),
     };
     const planned = planStack(projected, mergeRequested);
@@ -100,7 +85,7 @@ function planStack(result, mergeRequested) {
     const runnableCandidates = work.sessions.filter((item) => item.pollCommand);
     const missingCommands = work.sessions.filter((item) => !item.pollCommand);
     const agentWork = runnableCandidates.length > 0 || work.markReady.length > 0;
-    const drain = planBottomDrain(result, mergeRequested);
+    const drain = planPrefixDrain(result, mergeRequested);
     if (drain)
         return drain;
     const handoffs = findHumanHandoffs(result);

package/bin/commands/poll.mjs

@@ -1,5 +1,4 @@
 import { runIterate } from "./iterate/index.mjs";
-import { heldByLowerLayer } from "./iterate/parent-first.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
 import { loadConfig } from "../config/load.mjs";
@@ -98,8 +97,7 @@ async function runPollCore(opts) {
             }
             break;
         }
-        // A held draft waits on another layer's session, so hand it straight back.
-        if (lastResult.action === "wait" && !pastDebounce && !heldByLowerLayer(lastResult)) {
+        if (lastResult.action === "wait" && !pastDebounce) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;

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

@@ -8,17 +8,17 @@ export interface StackPlan {
     instructions: string[];
 }
 /**
- * Merge the ready bottom layer by PR number. `gh stack merge <n>` tries a stack
- * number first, but stack numbers come from the repository's issue and pull
- * request sequence, so a PR number never names a stack.
+ * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
+ * stack number first, but stack numbers come from the repository's issue and
+ * pull request sequence, so a PR number never names a stack.
  */
-export declare function planBottomDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
+export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
 /**
  * A merge-requested, fully ready stack whose bottom open layer still targets
  * the merged layer below it until GitHub retargets it onto the stack base.
  */
 export declare function retargetWaitPlan(first: PollSummaryItem): StackPlan;
-/** Every remaining layer only waits: on CI or merge state, or on a lower layer that does. */
+/** Every remaining layer only waits on CI or merge state. */
 export declare function idleWaitPlan(idle: PollSummaryItem[]): StackPlan;
 export declare function describeIdleLayers(idle: PollSummaryItem[]): string;
 export declare function appendAutonomousInstructions(instructions: string[], candidates: PollSummaryItem[]): void;

package/bin/commands/stack-drain.mjs

@@ -1,51 +1,63 @@
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
 /**
- * The lowest open layer when it can merge by itself: every layer below it
- * merged, GitHub retargeted it onto the stack base, it holds a current READY
- * receipt, and no layer is already in the merge queue.
+ * Highest open layer such that it and every open layer below it are ready to
+ * merge together. `gh stack merge <PR>` lands that PR and every unmerged layer
+ * below it. A merge queue accepts the same prefix and evaluates each layer
+ * from the bottom; a failure ejects that layer and those above it.
  */
-function drainableBottom(result) {
+function readyPrefixTop(result) {
     const layers = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
-    const bottom = layers.find((item) => item.state !== "MERGED");
-    if (!bottom || !isStackLayer(bottom) || bottom.state !== "OPEN")
+    if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
         return undefined;
-    if (bottom.action === "escalate" || !isStackLayerReady(bottom))
+    const open = layers.filter((item) => item.state === "OPEN");
+    const bottom = open[0];
+    if (!bottom || !isStackLayer(bottom) || bottom.state !== "OPEN")
         return undefined;
     if (bottom.baseRefName !== bottom.stack.baseRefName)
         return undefined;
-    if (result.stackAncestry?.some((gap) => gap.childPr === bottom.pr))
-        return undefined;
-    if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
-        return undefined;
-    return bottom;
+    const stale = new Set((result.stackAncestry ?? []).map((gap) => gap.childPr));
+    let top;
+    for (const item of open) {
+        if (!isStackLayer(item))
+            break;
+        if (item.action === "escalate" || !isStackLayerReady(item) || stale.has(item.pr))
+            break;
+        if (layers.some((layer) => layer.state === "CLOSED" && stackPosition(layer) < stackPosition(item)))
+            break;
+        top = item;
+    }
+    return top;
 }
 /**
- * Merge the ready bottom layer by PR number. `gh stack merge <n>` tries a stack
- * number first, but stack numbers come from the repository's issue and pull
- * request sequence, so a PR number never names a stack.
+ * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
+ * stack number first, but stack numbers come from the repository's issue and
+ * pull request sequence, so a PR number never names a stack.
  */
-export function planBottomDrain(result, mergeRequested) {
+export function planPrefixDrain(result, mergeRequested) {
     if (!mergeRequested)
         return undefined;
-    const bottom = drainableBottom(result);
-    if (!bottom)
+    const top = readyPrefixTop(result);
+    if (!top)
         return undefined;
     const gaps = result.stackAncestry ?? [];
     const staleChildren = new Set(gaps.map((gap) => gap.childPr));
-    const open = result.prs.filter((item) => item.state === "OPEN");
-    const uppers = splitStackWork(open.filter((item) => item.pr !== bottom.pr &&
+    const open = result.prs
+        .filter((item) => item.state === "OPEN")
+        .sort((left, right) => stackPosition(left) - stackPosition(right));
+    const above = splitStackWork(open.filter((item) => stackPosition(item) > stackPosition(top) &&
         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 instructions = [
-        `1. PR #${bottom.pr} is the bottom open layer of stack #${bottom.stack.number} in \`${result.repo}\` and is ready. Run \`GH_REPO=${result.repo} gh stack merge ${bottom.pr} --yes --squash\` to merge that layer alone, or to enqueue it when the base uses a merge queue. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
+        `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 --squash\` to merge ${span}. When the base uses a merge queue, the same command queues that prefix together and GitHub evaluates each layer from the bottom; a failure ejects that layer and the layers above it. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
     ];
-    appendAutonomousInstructions(instructions, uppers.sessions);
-    appendMarkReadyInstructions(instructions, uppers.markReady);
+    appendAutonomousInstructions(instructions, above.sessions);
+    appendMarkReadyInstructions(instructions, above.markReady);
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);
-    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`--stack --merge\` selector; GitHub retargets the next layer onto \`${bottom.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
+    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`--stack --merge\` selector; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
     return {
         action: "merge",
         stackMergeable: gaps.length === 0 && open.every(isStackLayerReady),
@@ -66,7 +78,7 @@ export function retargetWaitPlan(first) {
         ],
     };
 }
-/** Every remaining layer only waits: on CI or merge state, or on a lower layer that does. */
+/** Every remaining layer only waits on CI or merge state. */
 export function idleWaitPlan(idle) {
     return {
         action: "wait",
@@ -79,9 +91,7 @@ export function idleWaitPlan(idle) {
     };
 }
 export function describeIdleLayers(idle) {
-    return idle
-        .map((item) => `PR #${item.pr} (${item.blockedByPr ? `stack-blocked by PR #${item.blockedByPr}` : item.reasons.join(", ")})`)
-        .join("; ");
+    return idle.map((item) => `PR #${item.pr} (${item.reasons.join(", ")})`).join("; ");
 }
 export function appendAutonomousInstructions(instructions, candidates) {
     if (candidates.length === 0)
@@ -89,10 +99,9 @@ export function appendAutonomousInstructions(instructions, candidates) {
     instructions.push(`${instructions.length + 1}. Start or delegate the relevant one-PR sessions below; review and CI work on separate layers can proceed concurrently.`);
     for (const item of candidates) {
         instructions.push(item.pollCommand
-            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.blockedByPr ? ` (stack-blocked by PR #${item.blockedByPr})` : ""}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
+            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
             : `${instructions.length + 1}. PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`);
     }
-    instructions.push(`${instructions.length + 1}. Keep upper draft PRs in draft until every lower layer has completed Shepherd READY.`);
 }
 export function findHumanHandoffs(result) {
     const lastOpen = result.prs.filter((item) => item.state === "OPEN").at(-1);

package/bin/commands/stack-layer-readiness.d.mts

@@ -1,7 +1,6 @@
 import type { PollSummaryItem, StackLayerBlockReason } from "../types.mts";
 /**
- * Why a native stack layer does not yet let the layers above it advance, or undefined
- * when it does. The stack selector and an upper draft's parent-first mark-ready check
- * share this predicate so both always name the same blocking layer.
+ * Why a native stack layer is not ready to merge, or undefined when it is.
+ * A draft is marked ready by its own session; this predicate does not gate that.
  */
 export declare function stackLayerBlockReason(item: PollSummaryItem): StackLayerBlockReason | undefined;

package/bin/commands/stack-layer-readiness.mjs

@@ -1,7 +1,6 @@
 /**
- * Why a native stack layer does not yet let the layers above it advance, or undefined
- * when it does. The stack selector and an upper draft's parent-first mark-ready check
- * share this predicate so both always name the same blocking layer.
+ * Why a native stack layer is not ready to merge, or undefined when it is.
+ * A draft is marked ready by its own session; this predicate does not gate that.
  */
 export function stackLayerBlockReason(item) {
     if (item.state !== "OPEN")
@@ -13,7 +12,7 @@ export function stackLayerBlockReason(item) {
     // A receipt only establishes readiness after a merge-queue removal once
     // the one-PR session has observed and acknowledged that exact removal.
     // The aggregate projection preserves an unacknowledged removal here, so
-    // do not let its otherwise-current receipt promote a child draft.
+    // the layer is not ready to merge.
     if (item.queueRemoval)
         return "queue-removal";
     if ((item.checks?.failing ?? 0) > 0)
@@ -30,6 +29,6 @@ export function stackLayerBlockReason(item) {
             return "merge-state";
     }
     // A layer that looks ready but has not completed its own one-PR receipt
-    // is not sufficient evidence for the layers above it.
+    // is not ready to merge.
     return item.readyReceipt === true ? undefined : "no-ready-receipt";
 }

package/bin/commands/stack-stall.mjs

@@ -63,7 +63,6 @@ function stackStallFingerprint(result) {
             isDraft: item.isDraft,
             readyReceipt: item.readyReceipt,
             reasons: item.reasons,
-            blockedByPr: item.blockedByPr,
         })),
     });
 }

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

@@ -19,14 +19,14 @@ export interface StackWork {
 }
 /**
  * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A clean draft
- * that no lower layer blocks becomes an agent ready-for-review step instead. A stale-ancestry
- * child keeps its session, which returns the ancestry repair.
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
+ * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
 /**
  * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context and current lower layers.
+ * first because only the one-PR session reads the full review context.
  */
 export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
 export {};

package/bin/commands/stack-work.mjs

@@ -5,9 +5,9 @@
 export const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
 /**
  * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A clean draft
- * that no lower layer blocks becomes an agent ready-for-review step instead. A stale-ancestry
- * child keeps its session, which returns the ancestry repair.
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
+ * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export function splitStackWork(candidates, staleChildren) {
     const work = { sessions: [], markReady: [], idle: [] };
@@ -15,8 +15,7 @@ export function splitStackWork(candidates, staleChildren) {
         if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
             work.sessions.push(item);
         }
-        else if (item.blockedByPr === undefined &&
-            item.reasons.includes("draft-auto-mark-ready-disabled")) {
+        else if (item.reasons.includes("draft-auto-mark-ready-disabled")) {
             work.markReady.push(item);
         }
         else {
@@ -27,7 +26,7 @@ export function splitStackWork(candidates, staleChildren) {
 }
 /**
  * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context and current lower layers.
+ * first because only the one-PR session reads the full review context.
  */
 export function appendMarkReadyInstructions(instructions, layers) {
     for (const item of layers) {

package/bin/github/api-telemetry-aggregate.d.mts

@@ -9,6 +9,7 @@ export interface TelemetryAggregate {
         unmeasuredRequestCount: number;
         nodeCount: number;
         rateLimit?: RateLimitInfo;
+        credentialFingerprint?: string;
     };
     rest: Map<string, {
         requestCount: number;

package/bin/github/api-telemetry-aggregate.mjs

@@ -21,7 +21,7 @@ export function aggregateEvents(events) {
                 aggregate.graphql.measuredQueryCost += event.rateLimit.cost;
             aggregate.graphql.nodeCount += event.rateLimit?.nodeCount ?? 0;
             if (event.rateLimit !== undefined) {
-                aggregate.graphql.rateLimit = selectAuthoritativeRateLimit(aggregate.graphql.rateLimit, event.rateLimit);
+                adoptGraphqlRateLimit(aggregate.graphql, event.rateLimit, event.credentialFingerprint);
             }
             continue;
         }
@@ -48,7 +48,7 @@ export function mergeAggregate(target, source) {
     target.graphql.unmeasuredRequestCount += source.graphql.unmeasuredRequestCount;
     target.graphql.nodeCount += source.graphql.nodeCount;
     if (source.graphql.rateLimit !== undefined) {
-        target.graphql.rateLimit = selectAuthoritativeRateLimit(target.graphql.rateLimit, source.graphql.rateLimit);
+        adoptGraphqlRateLimit(target.graphql, source.graphql.rateLimit, source.graphql.credentialFingerprint);
     }
     for (const [resource, sourceGroup] of source.rest) {
         const targetGroup = target.rest.get(resource) ?? { requestCount: 0 };
@@ -65,6 +65,12 @@ export function aggregateStore(active) {
     mergeAggregate(all, aggregateEvents(active.events));
     return all;
 }
+function adoptGraphqlRateLimit(graphql, candidate, fingerprint) {
+    const next = selectAuthoritativeRateLimit(graphql.rateLimit, candidate);
+    if (next !== graphql.rateLimit)
+        graphql.credentialFingerprint = fingerprint;
+    graphql.rateLimit = next;
+}
 function selectAuthoritativeRateLimit(current, candidate) {
     if (current === undefined)
         return { ...candidate };

package/bin/github/api-telemetry.d.mts

@@ -4,10 +4,14 @@ export interface ApiTelemetryEvent {
     kind: "GraphQL" | "REST";
     method: string;
     authSource: string;
+    /** Truncated SHA-256 of the credential that produced this request. */
+    credentialFingerprint?: string;
     rateLimit?: RateLimitInfo;
 }
 /** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
 export declare function withApiTelemetryScope<T>(fn: () => Promise<T>): Promise<T>;
 export declare function recordApiTelemetry(event: ApiTelemetryEvent): void;
 export declare function mergeGraphqlRateLimit(headerRateLimit: RateLimitInfo | null, data: unknown): RateLimitInfo | null;
+/** Attach the credential fingerprint without adding it when this command has none. */
+export declare function withGraphqlCredentialFingerprint<T extends object>(sample: T): T;
 export declare function summarizeApiTelemetry(): ApiUsage | undefined;

package/bin/github/api-telemetry.mjs

@@ -65,6 +65,18 @@ export function mergeGraphqlRateLimit(headerRateLimit, data) {
         ...(payload !== null && Number.isFinite(payload.nodeCount) && { nodeCount: payload.nodeCount }),
     };
 }
+/** Fingerprint of the credential that owns the authoritative GraphQL rate-limit sample. */
+function graphqlQuotaCredentialFingerprint() {
+    const active = store();
+    if (active === undefined)
+        return undefined;
+    return aggregateStore(active).graphql.credentialFingerprint;
+}
+/** Attach the credential fingerprint without adding it when this command has none. */
+export function withGraphqlCredentialFingerprint(sample) {
+    const credentialFingerprint = graphqlQuotaCredentialFingerprint();
+    return credentialFingerprint === undefined ? sample : { ...sample, credentialFingerprint };
+}
 export function summarizeApiTelemetry() {
     const active = store();
     if (active === undefined)

package/bin/github/graphql-http.mjs

@@ -22,9 +22,11 @@ async function graphqlInner(query, vars, opts) {
     }));
     const t0 = performance.now();
     let authSource = "unknown";
+    let credentialFingerprint;
     const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
+        credentialFingerprint = auth.fingerprint;
         return fetch(url, {
             method: "POST",
             headers: auth.headers,
@@ -38,6 +40,7 @@ async function graphqlInner(query, vars, opts) {
         response,
         durationMs,
         authSource,
+        credentialFingerprint,
     }));
     const durationMs = Math.round(performance.now() - retryT0);
     const headerRateLimit = parseRateLimit(res.headers);
@@ -61,6 +64,7 @@ async function graphqlInner(query, vars, opts) {
             kind: "GraphQL",
             method: "POST",
             authSource,
+            credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
         throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
@@ -93,6 +97,7 @@ async function graphqlInner(query, vars, opts) {
             kind: "GraphQL",
             method: "POST",
             authSource,
+            credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
         throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
@@ -123,6 +128,7 @@ async function graphqlInner(query, vars, opts) {
         kind: "GraphQL",
         method: "POST",
         authSource,
+        credentialFingerprint,
         rateLimit: rateLimit ?? undefined,
     });
     const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);

package/bin/github/http-auth.d.mts

@@ -2,6 +2,8 @@ export type AuthSource = "GH_TOKEN" | "GITHUB_TOKEN" | "gh auth token" | "GITHUB
 export declare function _resetTokenCache(): void;
 export declare function hasCachedToken(): boolean;
 export declare function clearTokenCache(): void;
+/** Truncated SHA-256. Callers persist this instead of the token or its full hash. */
+export declare function credentialFingerprint(token: string): string;
 /**
  * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
  * conditional REST requests) on top of the standard auth/version headers.
@@ -9,4 +11,5 @@ export declare function clearTokenCache(): void;
 export declare function makeAuthHeaders(extra?: Record<string, string>): Promise<{
     headers: Record<string, string>;
     source: AuthSource;
+    fingerprint: string;
 }>;

package/bin/github/http-auth.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -15,6 +16,10 @@ export function clearTokenCache() {
     _token = undefined;
     _tokenSource = undefined;
 }
+/** Truncated SHA-256. Callers persist this instead of the token or its full hash. */
+export function credentialFingerprint(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
 async function resolveToken() {
     if (_token && _tokenSource)
         return { token: _token, source: _tokenSource };
@@ -58,6 +63,7 @@ export async function makeAuthHeaders(extra) {
     const { token, source } = await resolveToken();
     return {
         source,
+        fingerprint: credentialFingerprint(token),
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: "application/vnd.github+json",

package/bin/github/http-intermediate.d.mts

@@ -6,4 +6,5 @@ export declare function recordIntermediateResponse(opts: {
     response: Response;
     durationMs: number;
     authSource: string;
+    credentialFingerprint?: string;
 }): void;

package/bin/github/http-intermediate.mjs

@@ -15,6 +15,9 @@ export function recordIntermediateResponse(opts) {
         kind: opts.kind === "GraphQL" ? "GraphQL" : "REST",
         method: opts.method,
         authSource: opts.authSource,
+        ...(opts.credentialFingerprint !== undefined && {
+            credentialFingerprint: opts.credentialFingerprint,
+        }),
         rateLimit,
     });
 }

package/bin/state/graphql-quota-policy.d.mts

@@ -7,11 +7,17 @@ export interface GraphqlQuotaWarningState {
     lastRemaining: number;
     resetAt: number;
     warnedThresholds: number[];
+    /** Truncated SHA-256 of the credential. Absent in state written before fingerprints. */
+    credentialFingerprint?: string;
     rearmEpoch?: number;
 }
-export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt">, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
+type GraphqlQuotaSample = Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt"> & {
+    credentialFingerprint?: string;
+};
+export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: GraphqlQuotaSample, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
     warning?: GraphqlQuotaWarning;
     state: GraphqlQuotaWarningState & {
         rearmEpoch: number;
     };
 };
+export {};

package/bin/state/graphql-quota-policy.mjs

@@ -4,25 +4,28 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
         previous.resource !== sample.resource ||
         previous.limit !== sample.limit ||
         windowRolled ||
-        (sample.used !== undefined && previous.lastUsed !== undefined
-            ? sample.used < previous.lastUsed
-            : sample.remaining > previous.lastRemaining);
-    const warned = new Set(rearm ? [] : previous.warnedThresholds);
+        fingerprintChanged(previous, sample);
+    const effective = !rearm && previous !== null && usageRegressed(previous, sample)
+        ? newerSavedSample(previous)
+        : sample;
+    const warned = new Set(rearm || previous === null ? [] : previous.warnedThresholds);
     const rearmEpoch = rearm ? (previous?.rearmEpoch ?? 0) + 1 : (previous?.rearmEpoch ?? 0);
-    const crossed = bands.filter((band) => sample.remaining * 100 <= sample.limit * band.remainingPercent);
+    const crossed = bands.filter((band) => effective.remaining * 100 <= effective.limit * band.remainingPercent);
     const newCrossed = crossed.filter((band) => !warned.has(band.remainingPercent));
     for (const band of crossed)
         warned.add(band.remainingPercent);
     const active = newCrossed.at(-1);
+    const credentialFingerprint = effective.credentialFingerprint ?? previous?.credentialFingerprint;
     const state = {
-        resource: sample.resource,
-        limit: sample.limit,
-        ...(sample.used !== undefined && { lastUsed: sample.used }),
-        lastRemaining: sample.remaining,
-        resetAt: sample.resetAt,
+        resource: effective.resource,
+        limit: effective.limit,
+        ...(effective.used !== undefined && { lastUsed: effective.used }),
+        lastRemaining: effective.remaining,
+        resetAt: effective.resetAt,
         warnedThresholds: bands
             .map((band) => band.remainingPercent)
             .filter((threshold) => warned.has(threshold)),
+        ...(credentialFingerprint !== undefined && { credentialFingerprint }),
         rearmEpoch,
     };
     if (active === undefined)
@@ -31,13 +34,37 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
         warning: {
             resource: "graphql",
             thresholdPercent: active.remainingPercent,
-            remaining: sample.remaining,
-            limit: sample.limit,
-            ...(sample.used !== undefined && { used: sample.used }),
-            resetAt: sample.resetAt,
+            remaining: effective.remaining,
+            limit: effective.limit,
+            ...(effective.used !== undefined && { used: effective.used }),
+            resetAt: effective.resetAt,
             pollIntervalMinutes: active.pollIntervalMinutes,
             pollTimeoutMinutes: active.pollIntervalMinutes * 2,
         },
         state,
     };
 }
+function fingerprintChanged(previous, sample) {
+    return (previous.credentialFingerprint !== undefined &&
+        sample.credentialFingerprint !== undefined &&
+        previous.credentialFingerprint !== sample.credentialFingerprint);
+}
+/** An older observation of the same window: lower used, or higher remaining when used is absent. */
+function usageRegressed(previous, sample) {
+    if (sample.used !== undefined && previous.lastUsed !== undefined) {
+        return sample.used < previous.lastUsed;
+    }
+    return sample.remaining > previous.lastRemaining;
+}
+function newerSavedSample(previous) {
+    return {
+        resource: previous.resource,
+        limit: previous.limit,
+        ...(previous.lastUsed !== undefined && { used: previous.lastUsed }),
+        remaining: previous.lastRemaining,
+        resetAt: previous.resetAt,
+        ...(previous.credentialFingerprint !== undefined && {
+            credentialFingerprint: previous.credentialFingerprint,
+        }),
+    };
+}

package/bin/state/graphql-quota-warnings.mjs

@@ -70,6 +70,8 @@ async function readState(path) {
             !Array.isArray(parsed.warnedThresholds)) {
             return null;
         }
+        if (typeof parsed.credentialFingerprint !== "string")
+            delete parsed.credentialFingerprint;
         return parsed;
     }
     catch {

package/bin/types/api-usage.d.mts

@@ -13,6 +13,8 @@ export interface GraphqlApiUsage extends ApiResourceUsage {
     unmeasuredRequestCount: number;
     /** Exact sum reported by rateLimit.nodeCount for measured GraphQL queries. */
     nodeCount: number;
+    /** Truncated SHA-256 of the credential. Quota state only; summarized usage omits it. */
+    credentialFingerprint?: string;
 }
 export interface ApiUsage {
     credentialSources: string[];

package/bin/types/merge-requirements.d.mts

@@ -39,23 +39,13 @@ export interface StackStatus {
     position: number;
     baseRefName: string;
 }
-/** Why an open native stack layer does not yet let the layers above it advance. */
+/** Why an open native stack layer is not ready to merge. */
 export type StackLayerBlockReason = "closed" | "draft" | "conflicting" | "queue-removal" | "failing-checks" | "review-work" | "checks-in-progress" | "merge-state" | "no-ready-receipt" | "stale-ancestry";
-/** The lowest native stack layer that keeps an upper draft from being marked ready. */
-export interface StackLowerLayerBlock {
-    pr: number;
-    reason: StackLayerBlockReason;
-}
 /**
- * Why a native stack layer stays in draft on a WAIT tick. Repeating the same one-PR
- * session cannot advance it, so the caller returns to the stack selector. A named
- * `lowerLayer` is the layer to advance first; without one, the lower layers could not
- * be verified.
+ * A native stack draft stays in draft on a WAIT tick because this session will not
+ * mark it ready. The caller returns to the stack selector.
  */
 export type StackDraftHold = {
-    kind: "lower-layer-not-ready";
-    lowerLayer?: StackLowerLayerBlock;
-} | {
     kind: "auto-mark-ready-disabled";
 };
 /** Extra batch-PR fields for merge-queue, stacks, and folded branch rules. */

package/bin/types/poll-summary.d.mts

@@ -65,8 +65,6 @@ export interface PollSummaryItem {
     pollProbe?: true;
     /** A current one-PR READY-after-delay completion was verified. */
     readyReceipt?: true;
-    /** Lowest unready ancestor that prevents this layer from being stack-mergeable. */
-    blockedByPr?: number;
 }
 export type PollSummarySelection = {
     kind: "prs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.52.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.53.0", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.52.1", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.53.0", "pr-shepherd-mcp"]
   }
 }