pr-shepherd 0.51.0 → 0.52.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.51.0",
+  "version": "0.52.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -36,7 +36,10 @@ Each tick returns exactly one action:
 - `FIX_CODE` — agent work is required; complete it, push when needed, then continue polling. Push access to the PR head branch is a usage precondition.
 - `MERGE` — run the emitted head-pinned auto-merge or queue command. Ordinary merges include a plain-merge fallback; queue merges include a GraphQL enqueue fallback. GitHub is authoritative for the result and reports any authorization failure.
 - `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
-- `ESCALATE` — stop polling until a human provides direction.
+- `ESCALATE` — stop polling until a human provides direction. Native stacks reach this only after their autonomous one-PR sessions are exhausted.
+
+Native-stack summaries additionally use stack-level `SHEPHERD`: run the listed one-PR sessions,
+then recheck the stack. It is not a per-PR `FIX_CODE` action.
 
 Example shape:
 
@@ -79,7 +82,7 @@ Conversations Resolved: No [Not Required]
 9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options; without code changes, complete the authorized review mutations and iterate immediately.
 ```
 
-See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
+See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`16`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
 
 ## Workflow Assumptions
 
@@ -129,7 +132,7 @@ pr-shepherd 42                         # poll until non-WAIT or timeout
 pr-shepherd 42 --interval 60s --timeout 270s
 pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshots
 pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
-pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE, then return one batched tick
+pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE or stack SHEPHERD, then return one batched tick
 pr-shepherd 42 --ready-delay 15m
 pr-shepherd 42 --merge                  # request head-pinned auto-merge/queue; GitHub reports the result
 pr-shepherd iterate 42                 # single tick
@@ -139,20 +142,25 @@ pr-shepherd 42 43 44                   # summarize an explicit same-repository s
 pr-shepherd --stack 43                 # summarize every PR in a native GitHub stack
 ```
 
-Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when any row
-needs agent work, all rows are terminal, the bounded timeout expires, or `--until-terminal` crosses
-a configured GraphQL quota-warning band. Check counts use the same ignored, protected-run,
-superseded-run, and event rules as singular iteration and include active merge-queue commit checks.
-Bounded review/check overflow remains visible without permanently forcing work, and clean rows use
-the configured ready-delay before becoming terminal. Explicit PR sets give each actionable row an
-exact single-PR `pollCommand`, so independent rows can proceed before the next aggregate poll.
-Stack rows are ordered bottom-to-top and follow the one ordered stack instruction block instead.
-The summary also checks that every open child was based on
-its direct parent's current head. A stale child/parent OID pair is actionable even when GitHub
-reports both PRs clean: without `--merge`, rebase the upstack branches from their parent and push
-them with the emitted `gh stack` commands; with `--merge`, finish the contiguous ready lower
-layers with the emitted `gh stack merge --squash` command, recheck, then repair the child. API and
-MCP aggregate calls perform one summary tick and leave recurrence to the caller.
+Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when work is
+needed, every selected PR is complete, the bounded timeout expires, or `--until-terminal` crosses a
+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 complete-stack 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. A queued stack
+returns `WAIT`. 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 fully reconciled and READY stack returns `MERGE` with a `gh stack merge`
+command for the agent to run, checking and installing the optional `github/gh-stack` extension first
+when necessary. It then rechecks until every layer merges and 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/checks/log-excerpt.d.mts

@@ -0,0 +1 @@
+export declare function buildLogExcerpt(raw: string): string | undefined;

package/bin/checks/log-excerpt.mjs

@@ -0,0 +1,192 @@
+import { loadConfig } from "../config/load.mjs";
+const LOG_EXCERPT_CONTEXT_LINES = 16;
+const LOG_EXCERPT_TAIL_LINES = 28;
+const LOG_EXCERPT_MAX_CHARS = 4_000;
+const TRUNCATED_MARK = "[truncated]";
+const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+const STEP_GROUP_RE = /^##\[group\](?:Run |Post )/;
+const GROUP_RE = /^##\[group\]/;
+const ENDGROUP_RE = /^##\[endgroup\]$/;
+const POST_JOB_RE = /^(?:Post job cleanup\.?|Cleaning up orphan processes)$/;
+export function buildLogExcerpt(raw) {
+    const ignorePatterns = compileIgnoreLogLinePatterns();
+    const prepared = raw
+        .split(/\r?\n/)
+        .map(cleanLogLine)
+        .filter((line) => line.trim() !== "");
+    if (prepared.length === 0)
+        return undefined;
+    const isolated = isolateFailedStep(prepared);
+    const lines = isolated.lines
+        .map(stripGroupMarkers)
+        .filter((line) => line.trim() !== "" && !isNoiseLine(line, ignorePatterns));
+    if (lines.length === 0)
+        return undefined;
+    const aggregateExcerpt = buildAggregateJobResultsExcerpt(lines);
+    if (aggregateExcerpt !== undefined)
+        return aggregateExcerpt;
+    if (isolated.isolated) {
+        const errorIndex = findLogExcerptAnchor(lines);
+        return truncateTail(lines.join("\n"), errorIndex === -1 ? undefined : lines[errorIndex]);
+    }
+    return boundFallbackExcerpt(lines);
+}
+function isolateFailedStep(lines) {
+    const postJob = lines.findIndex((line) => POST_JOB_RE.test(line));
+    const capped = postJob === -1 ? lines : lines.slice(0, postJob);
+    const anchor = findLogExcerptAnchor(capped);
+    const groupStart = findPrecedingStepGroup(capped, anchor === -1 ? capped.length - 1 : anchor);
+    if (groupStart === -1)
+        return { lines: capped, isolated: false };
+    const endgroup = findMatchingEndgroup(capped, groupStart);
+    const after = endgroup === -1 ? groupStart + 1 : endgroup + 1;
+    const next = findNextStepGroup(capped, after);
+    return { lines: capped.slice(after, next === -1 ? capped.length : next), isolated: true };
+}
+function findPrecedingStepGroup(lines, from) {
+    for (let i = Math.min(from, lines.length - 1); i >= 0; i--) {
+        if (STEP_GROUP_RE.test(lines[i] ?? ""))
+            return i;
+    }
+    return -1;
+}
+function findMatchingEndgroup(lines, groupStart) {
+    let depth = 0;
+    for (let i = groupStart; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (GROUP_RE.test(line))
+            depth++;
+        else if (ENDGROUP_RE.test(line) && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+function findNextStepGroup(lines, from) {
+    let depth = 0;
+    for (let i = from; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (GROUP_RE.test(line)) {
+            if (depth === 0 && STEP_GROUP_RE.test(line))
+                return i;
+            depth++;
+        }
+        else if (ENDGROUP_RE.test(line) && depth > 0)
+            depth--;
+    }
+    return -1;
+}
+function boundFallbackExcerpt(lines) {
+    const errorIndex = findLogExcerptAnchor(lines);
+    if (errorIndex === -1) {
+        return truncateLogExcerpt(lines.slice(-LOG_EXCERPT_TAIL_LINES).join("\n"));
+    }
+    const start = Math.max(0, errorIndex - LOG_EXCERPT_CONTEXT_LINES);
+    const excerpt = lines.slice(start, Math.min(lines.length, errorIndex + LOG_EXCERPT_CONTEXT_LINES + 1));
+    return truncateAnchoredExcerpt(excerpt, errorIndex - start);
+}
+function findLogExcerptAnchor(lines) {
+    const explicitError = lines.findIndex((line) => line.includes("##[error]"));
+    if (explicitError !== -1)
+        return explicitError;
+    return lines.findIndex((line) => /\b(error|failed|cancelled)\b/i.test(line));
+}
+function buildAggregateJobResultsExcerpt(lines) {
+    const jobResults = extractJobResults(lines);
+    if (jobResults === undefined)
+        return undefined;
+    const failed = Object.entries(jobResults)
+        .map(([name, value]) => ({ name, result: extractJobResult(value) }))
+        .filter((entry) => entry.result !== undefined && !["success", "skipped"].includes(entry.result));
+    if (failed.length === 0)
+        return undefined;
+    return truncateLogExcerpt([
+        ...lines.filter((line) => /required jobs failed|exit code \d+/i.test(line)),
+        "Job results (non-success):",
+        ...failed.map((entry) => `${entry.name}: ${entry.result}`),
+    ].join("\n"));
+}
+function extractJobResults(lines) {
+    const startIndex = lines.findIndex((line) => line.includes("Job results:"));
+    if (startIndex === -1)
+        return undefined;
+    const block = collectJsonBlock(lines, startIndex);
+    if (block === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(block);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectJsonBlock(lines, startIndex) {
+    const startLine = lines[startIndex] ?? "";
+    const objectStart = startLine.indexOf("{");
+    if (objectStart === -1)
+        return undefined;
+    const collected = [startLine.slice(objectStart)];
+    let depth = braceDepth(collected[0]);
+    for (let i = startIndex + 1; i < lines.length && depth > 0; i++) {
+        const line = lines[i] ?? "";
+        collected.push(line);
+        depth += braceDepth(line);
+    }
+    return depth === 0 ? collected.join("\n") : undefined;
+}
+function braceDepth(line) {
+    return [...line].reduce((depth, ch) => {
+        if (ch === "{")
+            return depth + 1;
+        if (ch === "}")
+            return depth - 1;
+        return depth;
+    }, 0);
+}
+function extractJobResult(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const result = value.result;
+    return typeof result === "string" ? result : undefined;
+}
+function truncateLogExcerpt(text) {
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    return `${text.slice(0, LOG_EXCERPT_MAX_CHARS - `\n${TRUNCATED_MARK}`.length).trimEnd()}\n${TRUNCATED_MARK}`;
+}
+function truncateAnchoredExcerpt(lines, anchorIndex) {
+    const text = lines.join("\n");
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    return truncateLogExcerpt(`${TRUNCATED_MARK}\n${lines.slice(anchorIndex).join("\n")}`);
+}
+function truncateTail(text, keep) {
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    const head = `${TRUNCATED_MARK}\n`;
+    const slice = text.slice(-(LOG_EXCERPT_MAX_CHARS - head.length));
+    const nl = slice.indexOf("\n");
+    const tail = `${head}${nl === -1 ? slice : slice.slice(nl + 1)}`;
+    if (!keep || tail.includes(keep))
+        return tail;
+    const from = text.lastIndexOf(keep);
+    return from === -1 ? tail : truncateLogExcerpt(`${head}${text.slice(from)}`);
+}
+function compileIgnoreLogLinePatterns() {
+    return loadConfig().checks.ignoreLogLines.map((pattern) => new RegExp(pattern));
+}
+function isNoiseLine(line, patterns) {
+    return patterns.some((re) => re.test(line));
+}
+function cleanLogLine(line) {
+    return line
+        .replace(/^\uFEFF/, "")
+        .replace(ANSI_SGR_RE, "")
+        .replace(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s*/, "")
+        .trimEnd();
+}
+function stripGroupMarkers(line) {
+    return line.replace(/##\[(?:group|endgroup)\]/g, "");
+}

package/bin/checks/triage.mjs

@@ -1,13 +1,8 @@
 /* eslint-disable max-lines */
 import { restWithRateLimit, restText } from "../github/http.mjs";
 import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
-import { loadConfig } from "../config/load.mjs";
+import { buildLogExcerpt } from "./log-excerpt.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
-const LOG_EXCERPT_CONTEXT_LINES = 16;
-const LOG_EXCERPT_TAIL_LINES = 28;
-const LOG_EXCERPT_MAX_CHARS = 4_000;
-const TRUNCATED_SUFFIX = "\n[truncated]";
-const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
 export function triageFailingChecks(failingChecks, repo, stateKey) {
     const jobsCache = new Map();
     return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, stateKey)));
@@ -163,7 +158,7 @@ function pickJobInfo(jobs, checkName) {
  * never gets frozen into the cache.
  */
 async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
-    const cacheName = `joblog-${jobId}`;
+    const cacheName = `joblog-v2-${jobId}`;
     if (stateKey && cacheable) {
         const cached = await loadDerived(stateKey, cacheName);
         if (cached)
@@ -181,117 +176,3 @@ async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
         return undefined;
     }
 }
-function buildLogExcerpt(raw) {
-    const ignorePatterns = compileIgnoreLogLinePatterns();
-    const lines = raw
-        .split(/\r?\n/)
-        .map(cleanLogLine)
-        .filter((line) => line.trim() !== "" && !isNoiseLine(line, ignorePatterns));
-    if (lines.length === 0)
-        return undefined;
-    const aggregateExcerpt = buildAggregateJobResultsExcerpt(lines);
-    if (aggregateExcerpt !== undefined)
-        return aggregateExcerpt;
-    const errorIndex = findLogExcerptAnchor(lines);
-    if (errorIndex === -1)
-        return truncateLogExcerpt(lines.slice(-LOG_EXCERPT_TAIL_LINES).join("\n"));
-    const start = Math.max(0, errorIndex - LOG_EXCERPT_CONTEXT_LINES);
-    const excerpt = lines.slice(start, Math.min(lines.length, errorIndex + LOG_EXCERPT_CONTEXT_LINES + 1));
-    return truncateAnchoredExcerpt(excerpt, errorIndex - start);
-}
-function findLogExcerptAnchor(lines) {
-    const explicitError = lines.findIndex((line) => line.includes("##[error]"));
-    if (explicitError !== -1)
-        return explicitError;
-    return lines.findIndex((line) => /\b(error|failed|cancelled)\b/i.test(line));
-}
-function buildAggregateJobResultsExcerpt(lines) {
-    const jobResults = extractJobResults(lines);
-    if (jobResults === undefined)
-        return undefined;
-    const failed = Object.entries(jobResults)
-        .map(([name, value]) => ({ name, result: extractJobResult(value) }))
-        .filter((entry) => entry.result !== undefined && !["success", "skipped"].includes(entry.result));
-    if (failed.length === 0)
-        return undefined;
-    const output = [
-        ...lines.filter((line) => /required jobs failed|exit code \d+/i.test(line)),
-        "Job results (non-success):",
-        ...failed.map((entry) => `${entry.name}: ${entry.result}`),
-    ];
-    return truncateLogExcerpt(output.join("\n"));
-}
-function extractJobResults(lines) {
-    const startIndex = lines.findIndex((line) => line.includes("Job results:"));
-    if (startIndex === -1)
-        return undefined;
-    const block = collectJsonBlock(lines, startIndex);
-    if (block === undefined)
-        return undefined;
-    try {
-        const parsed = JSON.parse(block);
-        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function collectJsonBlock(lines, startIndex) {
-    const startLine = lines[startIndex] ?? "";
-    const objectStart = startLine.indexOf("{");
-    if (objectStart === -1)
-        return undefined;
-    const collected = [startLine.slice(objectStart)];
-    let depth = braceDepth(collected[0]);
-    for (let i = startIndex + 1; i < lines.length && depth > 0; i++) {
-        const line = lines[i] ?? "";
-        collected.push(line);
-        depth += braceDepth(line);
-    }
-    return depth === 0 ? collected.join("\n") : undefined;
-}
-function braceDepth(line) {
-    return [...line].reduce((depth, ch) => {
-        if (ch === "{")
-            return depth + 1;
-        if (ch === "}")
-            return depth - 1;
-        return depth;
-    }, 0);
-}
-function extractJobResult(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const result = value.result;
-    return typeof result === "string" ? result : undefined;
-}
-function truncateLogExcerpt(text) {
-    if (text.length <= LOG_EXCERPT_MAX_CHARS)
-        return text;
-    return `${text.slice(0, LOG_EXCERPT_MAX_CHARS - TRUNCATED_SUFFIX.length).trimEnd()}${TRUNCATED_SUFFIX}`;
-}
-function truncateAnchoredExcerpt(lines, anchorIndex) {
-    const text = lines.join("\n");
-    if (text.length <= LOG_EXCERPT_MAX_CHARS)
-        return text;
-    return truncateLogExcerpt(`${TRUNCATED_SUFFIX.trim()}\n${lines.slice(anchorIndex).join("\n")}`);
-}
-// User-configured via `checks.ignoreLogLines` (regex source strings) — empty by
-// default. What counts as noise varies by CI toolchain, so Shepherd ships no
-// built-in patterns; a project opts in via `.pr-shepherdrc.yml`.
-function compileIgnoreLogLinePatterns() {
-    return loadConfig().checks.ignoreLogLines.map((pattern) => new RegExp(pattern));
-}
-function isNoiseLine(line, patterns) {
-    return patterns.some((re) => re.test(line));
-}
-function cleanLogLine(line) {
-    return line
-        .replace(/^\uFEFF/, "")
-        .replace(ANSI_SGR_RE, "")
-        .replace(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s*/, "")
-        .replace(/##\[(?:group|endgroup)\]/g, "")
-        .trimEnd();
-}

package/bin/cli/iterate-lean.mjs

@@ -183,9 +183,6 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.mergeQueueRemoval && {
                         mergeQueueRemoval: result.escalate.mergeQueueRemoval,
                     }),
-                    ...(result.escalate.stack && {
-                        stack: result.escalate.stack,
-                    }),
                     ...(result.escalate.authorization &&
                         result.escalate.authorization.length > 0 && {
                         authorization: result.escalate.authorization,

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

@@ -12,13 +12,12 @@ function pollSummaryExitCode(result) {
     if (result.nextAction) {
         const stackExitCode = {
             escalate: EXIT.ESCALATE,
-            fix_code: EXIT.FIX_CODE,
+            shepherd: EXIT.SHEPHERD,
             merge: EXIT.MERGE,
-            mark_ready: EXIT.MARK_READY,
             wait: EXIT.WAIT,
             cancel: EXIT.OK,
         };
-        return stackExitCode[result.nextAction] ?? EXIT.OK;
+        return stackExitCode[result.nextAction];
     }
     const actions = new Set(result.prs.map((item) => item.action));
     if (actions.has("escalate"))

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

@@ -7,7 +7,7 @@ export function formatPollSummaryResult(result) {
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
-        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.stackMergeable !== undefined ? ` · **stack mergeable** \`${result.stackMergeable}\`` : ""}${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
         "",
         "## Pull requests",
         "",
@@ -42,11 +42,13 @@ function formatItem(item) {
         ? " · blocking reviewer `in progress`"
         : "";
     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}${stack}`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${blockedBy}${stack}`,
         `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
@@ -54,6 +56,11 @@ function formatItem(item) {
         ...(review
             ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
             : []),
+        ...(item.queueRemoval
+            ? [
+                `  - queue removal: reason \`${item.queueRemoval.reason ?? "UNKNOWN"}\` · at \`${item.queueRemoval.createdAtUnix}\`${item.queueRemoval.actor ? ` · actor \`@${item.queueRemoval.actor}\`` : ""}${item.queueRemoval.beforeCommitOid ? ` · commit \`${item.queueRemoval.beforeCommitOid}\`` : ""}${item.queueRemoval.beforeCommitParentOids?.length ? ` · parents \`${item.queueRemoval.beforeCommitParentOids.join(",")}\`` : ""}`,
+            ]
+            : []),
         `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
         ...(item.pollCommand ? [`  - pollCommand: \`${item.pollCommand}\``] : []),
     ].join("\n");

package/bin/commands/check.mjs

@@ -249,6 +249,7 @@ export async function runCheck(opts) {
         ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
         status,
         baseBranch: batchData.baseRefName,
+        ...(batchData.baseRefOid && { baseRefOid: batchData.baseRefOid }),
         mergeStatus,
         checks: {
             passing: merged.passing,

package/bin/commands/iterate/escalate.mjs

@@ -1,5 +1,4 @@
 import { loadConfig } from "../../config/load.mjs";
-import { inlineCode } from "../../util/markdown.mjs";
 import { renderResolveCommand } from "./render.mjs";
 function renderEscalateAuthor(item) {
     return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
@@ -194,10 +193,6 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         if (removal.beforeCommitOid)
             lines.push(`- queue commit: \`${removal.beforeCommitOid}\``);
     }
-    if (escalate.stack) {
-        const s = escalate.stack;
-        lines.push("", "## GitHub stack", "", `- layer: \`${s.position}\` of \`${s.size}\` in stack \`${s.number}\``, `- stack base: ${inlineCode(s.baseRefName)}`);
-    }
     if (escalate.authorization && escalate.authorization.length > 0) {
         lines.push("");
         lines.push("## Authorization");
@@ -231,10 +226,6 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
-    if (triggers.includes("stacked-pr")) {
-        const selector = detail ?? "<pr>";
-        return `This PR belongs to a GitHub stack, so Shepherd will not emit a merge command. \`gh pr merge\` targets the PR's own base branch — for a mid-stack layer that is the unmerged parent branch, not the stack's base — and auto-merge is unsupported on stacked PRs. Merge from the GitHub stack UI, or run \`gh stack merge --squash ${selector}\` (requires the \`github/gh-stack\` extension — run \`gh extension install github/gh-stack\` first if it's not installed), which lands this PR and every unmerged layer below it.`;
-    }
     if (triggers.includes("check-follow-up-unavailable")) {
         return "One or more failing checks have no autonomous follow-up available. Use the displayed conclusion, run or URL, and included evidence to handle them manually.";
     }
@@ -257,9 +248,5 @@ export function buildEscalateSuggestion(triggers, detail) {
         const attempts = loadConfig().iterate.fixAttemptsPerThread;
         return `The same thread(s) remain unresolved after their pending review commands were returned for ${attempts} FIX_CODE ticks. Automated iteration is paused for a manual decision.`;
     }
-    if (triggers.includes("bot-cr-not-dismissed")) {
-        const ids = detail ? ` (review IDs: ${detail})` : "";
-        return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior apply command. Dismiss the review(s) manually (or re-run \`pr-shepherd apply review\` with the IDs) to unblock the PR.`;
-    }
     return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

package/bin/commands/iterate/fix-code.d.mts

@@ -20,6 +20,8 @@ interface HandleFixCodeContext {
     surfacedApprovals: Review[];
     botUsernames: NormalizedBotUsernames;
     ruleAutoResolveThreadIds?: string[];
+    /** Verified stack-repair guidance, when ancestry is stale. */
+    repairInstructions?: string[];
 }
 export declare function handleFixCode(ctx: HandleFixCodeContext): Promise<IterateResult>;
 export {};

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

@@ -1,6 +1,5 @@
 /* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts, } from "../../state/fix-attempts.mjs";
-import { readBotCrSeenState, writeBotCrSeenState, updateBotCrSeenState, } from "../../state/bot-cr-seen.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
@@ -17,15 +16,15 @@ import { formatPrUrl } from "../../pr-reference.mjs";
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
-    // Once GitHub advances beyond the original attempt, Shepherd's one autonomous rerun has
-    // already been consumed. Hand the repeated failure off even when logs are available; the
-    // human still receives that evidence in the escalation payload.
-    if (check.runAttempt !== undefined && check.runAttempt > 1)
-        return true;
     if (check.conclusion === "ACTION_REQUIRED" ||
         check.conclusion === "CANCELLED" ||
         check.conclusion === "STARTUP_FAILURE")
         return true;
+    // A later attempt cannot be rerun automatically, but its included log can still
+    // identify a code or configuration fix for the agent. Only a later failure with
+    // no actionable evidence needs a human handoff.
+    if (check.runAttempt !== undefined && check.runAttempt > 1)
+        return !check.logExcerpt?.trim();
     // An external check's direct URL is actionable evidence: the agent can inspect the
     // provider and/or reproduce the reported failure locally. Only a truly bare check
     // has no autonomous investigation path.
@@ -68,7 +67,7 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
@@ -105,37 +104,6 @@ export async function handleFixCode(ctx) {
         ...(report.comments.minimizeIds ?? report.comments.actionable.map((comment) => comment.id)),
         ...reviewSummaryIds,
     ], changesRequestedReviewsForWork, checks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
-    const botCrReviews = report.changesRequestedReviews.filter((r) => (!isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames)) &&
-        report.viewerAuthorization?.viewerCanAdminister === true);
-    const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const previousBotCrState = await readBotCrSeenState(botCrStateKey);
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    const { next: nextBotCrState, staleIds: staleBotCrIds } = updateBotCrSeenState(previousBotCrState, botCrReviews, nowSeconds, stallTimeoutSeconds);
-    await writeBotCrSeenState(botCrStateKey, nextBotCrState);
-    if (staleBotCrIds.length > 0) {
-        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
-        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
-        const escalateBase = {
-            triggers: ["bot-cr-not-dismissed"],
-            unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
-            ambiguousComments: report.comments.actionable.map(toAgentComment),
-            changesRequestedReviews: report.changesRequestedReviews,
-            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
-            ...(editedSummaries.length > 0 && { editedSummaries }),
-            ...(pending && { pendingReviewCommands: pending }),
-            suggestion: buildEscalateSuggestion(["bot-cr-not-dismissed"], staleBotCrIds.join(", ")),
-        };
-        return {
-            ...base,
-            action: "escalate",
-            escalate: {
-                ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prReference, {
-                    merge: opts.merge,
-                }),
-            },
-        };
-    }
     const escalateTriggers = countFixCodeAttempt
         ? checkEscalateTriggers(retryableActionableThreads, priorThreadAttempts)
         : { triggers: [], thrashHistory: undefined };
@@ -216,8 +184,9 @@ export async function handleFixCode(ctx) {
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
-    const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
-    const hasBehindBaseRecovery = isBehind && exhaustedAttempts.length > 0;
+    const exhaustedAttempts = failingAgentChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
+    const manualExhaustedAttempts = exhaustedAttempts.filter((check) => manualFollowUpChecks.includes(check));
+    const hasBehindBaseRecovery = isBehind && manualExhaustedAttempts.length > 0;
     const hasAutonomousWork = hasConflicts ||
         hasBehindBaseRecovery ||
         threads.length > 0 ||
@@ -235,8 +204,8 @@ export async function handleFixCode(ctx) {
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
         const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
         const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
-        const checkSuggestion = exhaustedAttempts.length > 0
-            ? `GitHub reports a later workflow attempt (${exhaustedAttempts
+        const checkSuggestion = manualExhaustedAttempts.length > 0
+            ? `GitHub reports a later workflow attempt (${manualExhaustedAttempts
                 .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
                 .join(", ")}), so Shepherd's single rerun allowance is exhausted. Use the included evidence to handle the repeated failure manually before resuming.`
             : buildEscalateSuggestion(["check-follow-up-unavailable"]);
@@ -303,6 +272,9 @@ export async function handleFixCode(ctx) {
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0);
+    if (repairInstructions && repairInstructions.length > 0) {
+        instructions.unshift(...repairInstructions);
+    }
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,