pr-shepherd 0.21.0 → 0.22.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.21.0",
+  "version": "0.22.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -34,7 +34,9 @@ At a high level, the skill invokes `pr-shepherd <PR>` (which polls by default),
 
 ## Review threads
 
-### `PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice)
+### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice)
+
+#### `commentId=PRRC_kwDOSGizTs58XB1M` (@alice)
 
 > The variable name is misleading.
 >
@@ -97,7 +99,7 @@ Some other workflow improvements:
 
 Recommendations:
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling `pr-shepherd <PR>` until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling `pr-shepherd <PR>` until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures or CI that never starts).
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
 - Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
@@ -197,7 +199,7 @@ Iterate a PR from Codex:
 pr-shepherd iterate 42
 ```
 
-Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
+Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures or CI that never starts). `pr-shepherd iterate 42` remains supported for existing workflows.
 
 ## Configuration
 

package/bin/checks/triage.mjs

@@ -53,6 +53,7 @@ function workflowRunToCheckRun(run) {
         name: run.name?.trim() || `workflow run ${run.id}`,
         status: "COMPLETED",
         conclusion: "STARTUP_FAILURE",
+        source: "startup_failure",
         detailsUrl: run.html_url,
         event: run.event,
         runId: String(run.id),

package/bin/cli/fix-formatter.mjs

@@ -1,7 +1,7 @@
 import { renderResolveCommand } from "../commands/iterate/render.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
-import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
 import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instructions.mjs";
 export function formatFixCodeResult(header, result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
@@ -14,7 +14,7 @@ export function formatFixCodeResult(header, result, opts) {
             const heading = t.url ? `[threadId=${t.id}](${t.url})` : `\`threadId=${t.id}\``;
             const suggestionMarker = t.suggestion ? " [suggestion]" : "";
             sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}`);
-            sections.push(blockquote(t.body));
+            sections.push(renderThreadConversation(t));
             if (t.suggestion) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));
             }
@@ -57,6 +57,21 @@ export function formatFixCodeResult(header, result, opts) {
         });
         sections.push(bullets.join("\n\n"));
     }
+    const checksWithAnnotations = result.fix.checks.filter((ch) => (ch.annotations?.length ?? 0) > 0);
+    if (checksWithAnnotations.length > 0) {
+        sections.push("## Check annotations");
+        for (const ch of checksWithAnnotations) {
+            const workflowPrefix = ch.workflowName ? `${ch.workflowName} › ` : "";
+            const jobLabel = ch.jobName ? ch.jobName : ch.name;
+            const locator = ch.runId
+                ? `\`${ch.runId}\``
+                : ch.detailsUrl
+                    ? `external \`${ch.detailsUrl}\``
+                    : "(no runId)";
+            sections.push(`### ${locator} — \`${workflowPrefix}${jobLabel}\``);
+            sections.push(ch.annotations.map(renderCheckAnnotation).join("\n\n"));
+        }
+    }
     if (result.fix.changesRequestedReviews.length > 0) {
         sections.push("## Changes-requested reviews");
         sections.push(result.fix.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
@@ -112,10 +127,23 @@ export function formatFixCodeResult(header, result, opts) {
     sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix)));
     return joinSections(sections);
 }
-function blockquote(body) {
-    return body
-        .replace(/\r\n/g, "\n")
-        .split("\n")
-        .map((line) => (line === "" ? ">" : `> ${line}`))
-        .join("\n");
+function renderCheckAnnotation(a) {
+    const loc = `${a.path}:${renderAnnotationRange(a)}`;
+    const link = a.blobUrl ? ` [↗](${a.blobUrl})` : "";
+    const title = a.title ? ` — ${a.title}` : "";
+    const lines = [`- \`${a.id}\`${link} \`${loc}\` [${a.level}]${title}`];
+    if (a.message.trim() !== "")
+        lines.push(blockquote(a.message));
+    if (a.rawDetails !== undefined && a.rawDetails.trim() !== "")
+        lines.push(blockquote(a.rawDetails));
+    return lines.join("\n");
+}
+function renderAnnotationRange(a) {
+    if (a.startLine === null && a.endLine === null)
+        return "?";
+    const start = a.startLine ?? a.endLine;
+    const end = a.endLine ?? a.startLine;
+    if (start === end)
+        return String(start);
+    return `${start}-${end}`;
 }

package/bin/cli/iterate-lean.mjs

@@ -111,6 +111,10 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.escalate.changesRequestedReviews,
                     }),
+                    ...(result.escalate.stalledChecks &&
+                        result.escalate.stalledChecks.length > 0 && {
+                        stalledChecks: result.escalate.stalledChecks,
+                    }),
                     ...(result.escalate.thrashHistory &&
                         result.escalate.thrashHistory.length > 0 && {
                         thrashHistory: result.escalate.thrashHistory,

package/bin/cli/list-formatters.mjs

@@ -1,4 +1,5 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
+import { threadComments } from "../threads/transcript.mjs";
 const BODY_PREVIEW_MAX = 100;
 export function renderAuthor(author, authorType) {
     return authorType ? `@${author} · ${authorType}` : `@${author}`;
@@ -27,12 +28,60 @@ export function renderThreadBullet(t, opts = {}) {
         : "`(no location)`";
     const suggestionMarker = t.suggestion ? " [suggestion]" : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bodySuffix = opts.noBody ? "" : `: ${renderBodyPreview(t.body)}`;
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${statusSuffix}${bodySuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${statusSuffix}`;
+    if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
+        const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
+        return t.suggestion && opts.renderSuggestion
+            ? `${legacyLine}\n${renderSuggestionBlock(t.suggestion)}`
+            : legacyLine;
+    }
+    const parts = [bulletLine];
+    if (!opts.noBody) {
+        parts.push(renderThreadCommentBullets(t));
+    }
     if (t.suggestion && opts.renderSuggestion) {
-        return `${bulletLine}\n${renderSuggestionBlock(t.suggestion)}`;
+        parts.push(renderSuggestionBlock(t.suggestion));
     }
-    return bulletLine;
+    return parts.join("\n");
+}
+export function renderThreadConversation(t) {
+    if (!t.comments || t.comments.length === 0)
+        return blockquote(t.body);
+    return threadComments(t)
+        .map((c) => {
+        const heading = c.id
+            ? c.url
+                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType)})`
+                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType)})`
+            : `#### (${renderAuthor(c.author, c.authorType)})`;
+        return `${heading}\n\n${blockquote(c.body)}`;
+    })
+        .join("\n\n");
+}
+export function blockquote(body) {
+    return body
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => (line === "" ? ">" : `> ${line}`))
+        .join("\n");
+}
+function renderThreadCommentBullets(t) {
+    return threadComments(t)
+        .map((c) => {
+        const link = c.url ? ` [↗](${c.url})` : "";
+        const id = c.id ? `\`commentId=${c.id}\`` : "comment";
+        return [
+            `  - ${id}${link} (${renderAuthor(c.author, c.authorType)})`,
+            indentBlockquote(c.body, "    "),
+        ].join("\n");
+    })
+        .join("\n");
+}
+function indentBlockquote(body, indent) {
+    return blockquote(body)
+        .split("\n")
+        .map((line) => `${indent}${line}`)
+        .join("\n");
 }
 export function renderCommentBullet(c, opts = {}) {
     const link = c.url ? ` [↗](${c.url})` : "";

package/bin/commands/check-annotations.mjs

@@ -0,0 +1,40 @@
+import { fetchCheckRunAnnotations } from "../github/check-annotations.mjs";
+export async function attachUnseenCheckAnnotations(checks, seenMap, prNumber) {
+    const checksWithAnnotations = [];
+    for (const check of checks) {
+        // eslint-disable-next-line no-await-in-loop
+        checksWithAnnotations.push(await attachForCheck(check, seenMap, prNumber));
+    }
+    return checksWithAnnotations;
+}
+async function attachForCheck(check, seenMap, prNumber) {
+    if (check.id == null)
+        return check;
+    let annotations;
+    try {
+        annotations = await fetchCheckRunAnnotations(check.id);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`pr-shepherd: annotation fetch failed for PR #${prNumber} check "${check.name}" (ignored): ${msg}\n`);
+        return check;
+    }
+    const unseen = annotations.filter((a) => !seenMap.has(a.id));
+    if (unseen.length === 0)
+        return check;
+    return { ...check, annotations: unseen };
+}
+export function annotationMarkerBody(a) {
+    return JSON.stringify({
+        path: a.path,
+        startLine: a.startLine,
+        endLine: a.endLine,
+        startColumn: a.startColumn,
+        endColumn: a.endColumn,
+        level: a.level,
+        title: a.title,
+        message: a.message,
+        rawDetails: a.rawDetails,
+        blobUrl: a.blobUrl,
+    });
+}

package/bin/commands/check.mjs

@@ -9,9 +9,11 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
+import { attachUnseenCheckAnnotations } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
+import { threadTranscriptBody } from "../threads/transcript.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -38,8 +40,10 @@ export async function runCheck(opts) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
-    const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
+    const triagedBase = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
+    const seenMap = await loadSeenMap(stateKey);
+    const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved);
     const outdated = getOutdatedThreads(unresolvedThreads);
     let autoResolved = [];
@@ -55,12 +59,11 @@ export async function runCheck(opts) {
     const resolvedCandidates = batchData.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
     const minimizedThreadCandidates = batchData.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
-    const seenMap = await loadSeenMap(stateKey);
     const visibleCommentClassification = classifyVisibleComments(batchData.comments, seenMap, config.iterate.minimizeComments);
     const autoResolvedIds = new Set(autoResolved.map((t) => t.id));
     const firstLookThreads = [
         ...outdatedCandidates.flatMap((t) => {
-            const cls = classifyItem(t.id, t.body, seenMap);
+            const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
             if (cls === "unchanged")
                 return [];
             const base = {
@@ -71,14 +74,14 @@ export async function runCheck(opts) {
             return cls === "edited" ? [{ ...base, edited: true }] : [base];
         }),
         ...resolvedCandidates.flatMap((t) => {
-            const cls = classifyItem(t.id, t.body, seenMap);
+            const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
             if (cls === "unchanged")
                 return [];
             const base = { ...t, firstLookStatus: "resolved" };
             return cls === "edited" ? [{ ...base, edited: true }] : [base];
         }),
         ...minimizedThreadCandidates.flatMap((t) => {
-            const cls = classifyItem(t.id, t.body, seenMap);
+            const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
             if (cls === "unchanged")
                 return [];
             const base = { ...t, firstLookStatus: "minimized" };
@@ -105,7 +108,7 @@ export async function runCheck(opts) {
             seenSummaries.push(r);
     }
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
         ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
         ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),

package/bin/commands/check.test-support.mjs

@@ -9,6 +9,9 @@ vi.mock("../checks/triage.mts", () => ({
     triageFailingChecks: vi.fn((checks) => Promise.resolve(checks)),
     fetchStartupFailureChecks: vi.fn().mockResolvedValue([]),
 }));
+vi.mock("../github/check-annotations.mts", () => ({
+    fetchCheckRunAnnotations: vi.fn().mockResolvedValue([]),
+}));
 vi.mock("../comments/resolve.mts", () => ({
     autoResolveOutdated: vi.fn().mockResolvedValue({ resolved: [], errors: [] }),
 }));
@@ -26,6 +29,7 @@ import { runCheck } from "./check.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
 import { fetchStartupFailureChecks, triageFailingChecks } from "../checks/triage.mjs";
+import { fetchCheckRunAnnotations } from "../github/check-annotations.mjs";
 import { loadSeenMap, markSeen, hashBody } from "../state/seen-comments.mjs";
 import { autoResolveOutdated } from "../comments/resolve.mjs";
 const mockFetchPrBatch = vi.mocked(fetchPrBatch);
@@ -33,6 +37,7 @@ const mockGetCurrentPrNumber = vi.mocked(getCurrentPrNumber);
 const mockGetMergeableState = vi.mocked(getMergeableState);
 const mockTriageFailingChecks = vi.mocked(triageFailingChecks);
 const mockFetchStartupFailureChecks = vi.mocked(fetchStartupFailureChecks);
+const mockFetchCheckRunAnnotations = vi.mocked(fetchCheckRunAnnotations);
 const mockLoadSeenMap = vi.mocked(loadSeenMap);
 const mockMarkSeen = vi.mocked(markSeen);
 const mockAutoResolveOutdated = vi.mocked(autoResolveOutdated);
@@ -41,7 +46,7 @@ function defaultConfig() {
     return {
         iterate: {
             fixAttemptsPerThread: 3,
-            stallTimeoutMinutes: 30,
+            stallTimeoutMinutes: 60,
             minimizeApprovals: false,
             minimizeComments: "all",
         },
@@ -63,6 +68,7 @@ function defaultConfig() {
 }
 function makeCheck(overrides = {}) {
     return {
+        id: null,
         name: "tests",
         status: "COMPLETED",
         conclusion: "SUCCESS",
@@ -135,6 +141,7 @@ export function registerHooks() {
         mockFetchPrBatch.mockResolvedValue({ data: makeBatchData() });
         mockGetMergeableState.mockResolvedValue({ mergeable: "MERGEABLE", mergeStateStatus: "CLEAN" });
         mockFetchStartupFailureChecks.mockResolvedValue([]);
+        mockFetchCheckRunAnnotations.mockResolvedValue([]);
     });
 }
-export { BASE_OPTS, autoResolveOutdated, defaultConfig, fetchPrBatch, fetchStartupFailureChecks, getCurrentPrNumber, getMergeableState, hashBody, loadSeenMap, makeBatchData, makeCheck, makeComment, makeThread, markSeen, mockAutoResolveOutdated, mockFetchPrBatch, mockFetchStartupFailureChecks, mockGetCurrentPrNumber, mockGetMergeableState, mockLoadConfig, mockLoadSeenMap, mockMarkSeen, mockTriageFailingChecks, runCheck, triageFailingChecks, };
+export { BASE_OPTS, autoResolveOutdated, defaultConfig, fetchPrBatch, fetchStartupFailureChecks, fetchCheckRunAnnotations, getCurrentPrNumber, getMergeableState, hashBody, loadSeenMap, makeBatchData, makeCheck, makeComment, makeThread, markSeen, mockAutoResolveOutdated, mockFetchPrBatch, mockFetchStartupFailureChecks, mockFetchCheckRunAnnotations, mockGetCurrentPrNumber, mockGetMergeableState, mockLoadConfig, mockLoadSeenMap, mockMarkSeen, mockTriageFailingChecks, runCheck, triageFailingChecks, };

package/bin/commands/iterate/escalate.mjs

@@ -52,11 +52,25 @@ export function buildEscalateHumanMessage(escalate, pr) {
     lines.push(escalate.suggestion);
     const hasItems = escalate.unresolvedThreads.length > 0 ||
         escalate.changesRequestedReviews.length > 0 ||
-        escalate.ambiguousComments.length > 0;
+        escalate.ambiguousComments.length > 0 ||
+        (escalate.stalledChecks?.length ?? 0) > 0;
     if (hasItems) {
         lines.push("");
         lines.push("## Items needing attention");
         lines.push("");
+        for (const c of escalate.stalledChecks ?? []) {
+            const target = c.runId
+                ? `run \`${c.runId}\``
+                : c.detailsUrl
+                    ? `external \`${c.detailsUrl}\``
+                    : "no run ID";
+            const ageMinutes = Math.floor(c.ageSeconds / 60);
+            lines.push(`- check \`${c.name}\` — ${c.status} ${c.source}, ${target}, waiting ${ageMinutes} minute${ageMinutes === 1 ? "" : "s"}`);
+            if (c.summary)
+                lines.push(`  > ${c.summary}`);
+        }
+        if ((escalate.stalledChecks?.length ?? 0) > 0)
+            lines.push("");
         for (const t of escalate.unresolvedThreads) {
             const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
             lines.push(`- thread \`${t.id}\` — ${loc} (@${t.author}):`);
@@ -96,7 +110,7 @@ export function buildEscalateHumanMessage(escalate, pr) {
 }
 export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("stall-timeout")) {
-        const mins = detail ?? "30";
+        const mins = detail ?? "60";
         return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
     if (triggers.includes("base-branch-unknown")) {

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

@@ -1,11 +1,13 @@
 /* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts } from "../../state/fix-attempts.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
+import { markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
 import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
+import { annotationMarkerBody } from "../check-annotations.mjs";
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
@@ -101,7 +103,7 @@ 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, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads);
-    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
+    const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
         action: "fix_code",
@@ -122,5 +124,10 @@ export async function handleFixCode(ctx) {
             inProgressRunIds,
         },
         cancelled,
-    }, report, reviewSummaryIds);
+    };
+    const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
+    if (result.action === "fix_code") {
+        await Promise.allSettled(result.fix.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
+    }
+    return result;
 }

package/bin/commands/iterate/helpers.mjs

@@ -53,6 +53,7 @@ export function buildRelevantChecks(report) {
                 ...(c.jobName !== undefined && { jobName: c.jobName }),
                 ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
                 ...(c.summary !== undefined && { summary: c.summary }),
+                ...(c.annotations !== undefined && { annotations: c.annotations }),
             },
         ];
     });

package/bin/commands/iterate/render.mjs

@@ -30,6 +30,9 @@ export function buildFixInstructions(threads, actionableComments, checks, change
             actionableSections.push("`## Actionable comments`");
         if (checks.length > 0)
             actionableSections.push("`## Failing checks`");
+        if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
+            actionableSections.push("`## Check annotations`");
+        }
         if (changesRequestedReviews.length > 0)
             actionableSections.push("`## Changes-requested reviews`");
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
@@ -65,6 +68,9 @@ export function buildFixInstructions(threads, actionableComments, checks, change
         instructions.push(`Resolve the threads under \`## Review threads to resolve\` with the \`resolve:\` command shown below. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
     }
     instructions.push(...buildFailingCheckInstructions(checks));
+    if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
+        instructions.push(`For each item under \`## Check annotations\`: inspect the referenced file range and decide whether the annotation requires a code change. These annotations are surfaced once per PR and do not need any resolve/minimize mutation.`);
+    }
     if (changesRequestedReviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }

package/bin/commands/iterate/stall.mjs

@@ -1,5 +1,5 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
-import { toAgentThread, toAgentComment } from "../../reporters/agent.mjs";
+import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage } from "./escalate.mjs";
 export function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
@@ -27,8 +27,31 @@ export function computeStallFingerprint(action, headSha, base, report, reviewSum
     });
 }
 export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {
-    const fingerprint = computeStallFingerprint(prospectiveResult.action, headSha, base, report, reviewSummaryIds);
     const nowSeconds = Math.floor(Date.now() / 1000);
+    const stalledChecks = findCiStartStalledChecks(report.checks.inProgress, nowSeconds, {
+        stallTimeoutSeconds,
+        action: prospectiveResult.action,
+    });
+    if (stalledChecks.length > 0) {
+        const stalledMinutes = Math.floor(Math.max(...stalledChecks.map((c) => c.ageSeconds)) / 60);
+        const escalateBase = {
+            triggers: ["stall-timeout"],
+            unresolvedThreads: [],
+            ambiguousComments: [],
+            changesRequestedReviews: [],
+            stalledChecks,
+            suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                ...escalateBase,
+                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+            },
+        };
+    }
+    const fingerprint = computeStallFingerprint(prospectiveResult.action, headSha, base, report, reviewSummaryIds);
     const stored = await readStallState(stallKey);
     if (stored && stored.fingerprint === fingerprint) {
         const ageSeconds = nowSeconds - stored.firstSeenAt;
@@ -65,3 +88,21 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
     await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
     return prospectiveResult;
 }
+function findCiStartStalledChecks(checks, nowSeconds, opts) {
+    if (opts.stallTimeoutSeconds <= 0 || opts.action !== "wait")
+        return [];
+    return checks
+        .filter((c) => isUnstartedCheck(c))
+        .map((c) => toAgentStalledCheck(c, nowSeconds))
+        .filter((c) => c.createdAtUnix !== undefined && c.ageSeconds >= opts.stallTimeoutSeconds);
+}
+function isUnstartedCheck(check) {
+    if (check.source === "status_context")
+        return true;
+    if (check.startedAtUnix !== undefined)
+        return false;
+    return (check.status === "PENDING" ||
+        check.status === "QUEUED" ||
+        check.status === "REQUESTED" ||
+        check.status === "WAITING");
+}

package/bin/commands/iterate-test-support.mjs

@@ -103,7 +103,7 @@ function defaultConfig() {
     return {
         iterate: {
             fixAttemptsPerThread: 3,
-            stallTimeoutMinutes: 30,
+            stallTimeoutMinutes: 60,
             minimizeApprovals: false,
             minimizeComments: "all",
         },

package/bin/commands/iterate.fix-code-in-progress.test-support.mjs

@@ -23,6 +23,9 @@ vi.mock("../state/iterate-stall.mts", () => ({
     readStallState: vi.fn().mockResolvedValue(null),
     writeStallState: vi.fn().mockResolvedValue(undefined),
 }));
+vi.mock("../state/seen-comments.mts", () => ({
+    markSeen: vi.fn().mockResolvedValue(undefined),
+}));
 const { mockLoadConfig } = vi.hoisted(() => ({ mockLoadConfig: vi.fn() }));
 vi.mock("../config/load.mts", () => ({ loadConfig: mockLoadConfig }));
 import { runIterate } from "./iterate/index.mjs";
@@ -30,12 +33,14 @@ import { runCheck } from "./check.mjs";
 import { updateReadyDelay } from "./ready-delay.mjs";
 import { readFixAttempts, writeFixAttempts } from "../state/fix-attempts.mjs";
 import { readStallState, writeStallState } from "../state/iterate-stall.mjs";
+import { markSeen } from "../state/seen-comments.mjs";
 const mockRunCheck = vi.mocked(runCheck);
 const mockUpdateReadyDelay = vi.mocked(updateReadyDelay);
 const mockReadFixAttempts = vi.mocked(readFixAttempts);
 const mockWriteFixAttempts = vi.mocked(writeFixAttempts);
 const mockReadStallState = vi.mocked(readStallState);
 const mockWriteStallState = vi.mocked(writeStallState);
+const mockMarkSeen = vi.mocked(markSeen);
 function makeReport(overrides = {}) {
     return {
         pr: 42,
@@ -115,4 +120,4 @@ export function registerHooks() {
         vi.restoreAllMocks();
     });
 }
-export { makeOpts, makeReport, mockExecFile, mockFetch, mockLoadConfig, mockReadFixAttempts, mockReadStallState, mockRunCheck, mockUpdateReadyDelay, mockWriteFixAttempts, mockWriteStallState, readFixAttempts, readStallState, runCheck, runIterate, updateReadyDelay, writeFixAttempts, writeStallState, };
+export { makeOpts, makeReport, mockExecFile, mockFetch, mockLoadConfig, mockReadFixAttempts, mockReadStallState, mockMarkSeen, mockRunCheck, mockUpdateReadyDelay, mockWriteFixAttempts, mockWriteStallState, readFixAttempts, readStallState, runCheck, runIterate, updateReadyDelay, writeFixAttempts, writeStallState, };

package/bin/commands/resolve.mjs

@@ -7,6 +7,7 @@ import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { extractSuggestion } from "../suggestions/extract.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
+import { threadTranscriptBody } from "../threads/transcript.mjs";
 export { runResolveMutate } from "./resolve-mutate.mjs";
 export async function runResolveFetch(opts) {
     const repo = await getRepoInfo();
@@ -25,7 +26,7 @@ export async function runResolveFetch(opts) {
     const unseenOutdated = [];
     const editedOutdated = [];
     for (const t of outdatedCandidates) {
-        const cls = classifyItem(t.id, t.body, seenMap);
+        const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
         if (cls === "new")
             unseenOutdated.push(t);
         else if (cls === "edited")
@@ -34,7 +35,7 @@ export async function runResolveFetch(opts) {
     const unseenResolved = [];
     const editedResolved = [];
     for (const t of resolvedCandidates) {
-        const cls = classifyItem(t.id, t.body, seenMap);
+        const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
         if (cls === "new")
             unseenResolved.push(t);
         else if (cls === "edited")
@@ -43,7 +44,7 @@ export async function runResolveFetch(opts) {
     const unseenMinimizedThreads = [];
     const editedMinimizedThreads = [];
     for (const t of minimizedThreadCandidates) {
-        const cls = classifyItem(t.id, t.body, seenMap);
+        const cls = classifyItem(t.id, threadTranscriptBody(t), seenMap);
         if (cls === "new")
             unseenMinimizedThreads.push(t);
         else if (cls === "edited")
@@ -114,7 +115,7 @@ export async function runResolveFetch(opts) {
     ];
     // Mark new and edited items as seen (best-effort — markSeen never throws).
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
         ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
     ]);

package/bin/config.json

@@ -1,7 +1,7 @@
 {
   "iterate": {
     "fixAttemptsPerThread": 3,
-    "stallTimeoutMinutes": 30,
+    "stallTimeoutMinutes": 60,
     "minimizeApprovals": false,
     "minimizeComments": "all"
   },

package/bin/github/batch-parsers.mjs

@@ -10,19 +10,29 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
     }));
     const reviewThreads = rawThreadPages.map((t) => {
         const comment = t.comments.nodes[0];
+        const comments = t.comments.nodes.map((c) => ({
+            id: c.id,
+            isMinimized: c.isMinimized,
+            author: c.author?.login ?? "unknown",
+            authorType: mapAuthorType(c.author?.__typename),
+            body: c.body,
+            url: c.url,
+            createdAtUnix: parseCreatedAt(c.createdAt),
+        }));
         return {
             id: t.id,
             isResolved: t.isResolved,
             isOutdated: t.isOutdated,
             isMinimized: comment?.isMinimized ?? false,
-            path: comment?.path ?? null,
-            line: comment?.line ?? null,
-            startLine: comment?.startLine ?? null,
+            path: t.path ?? comment?.path ?? null,
+            line: t.line ?? comment?.line ?? null,
+            startLine: t.startLine ?? comment?.startLine ?? null,
             author: comment?.author?.login ?? "unknown",
             authorType: mapAuthorType(comment?.author?.__typename),
             body: comment?.body ?? "",
             url: comment?.url ?? "",
             createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
+            comments,
         };
     });
     const comments = rawCommentNodes.map((c) => ({
@@ -64,14 +74,28 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             const event = node.checkSuite?.workflowRun?.event ?? null;
             const runId = extractRunId(node.detailsUrl);
             const summary = extractCheckRunSummary(node.title, node.summary);
+            const rawCreatedAt = node.checkSuite
+                ? (node.checkSuite.workflowRun?.createdAt ?? node.checkSuite.createdAt)
+                : undefined;
+            const rawUpdatedAt = node.checkSuite
+                ? (node.checkSuite.workflowRun?.updatedAt ?? node.checkSuite.updatedAt)
+                : undefined;
+            const createdAtUnix = rawCreatedAt ? parseCreatedAt(rawCreatedAt) : undefined;
+            const startedAtUnix = node.startedAt ? parseCreatedAt(node.startedAt) : undefined;
+            const updatedAtUnix = rawUpdatedAt ? parseCreatedAt(rawUpdatedAt) : undefined;
             return [
                 {
+                    id: node.id,
                     name: node.name,
                     status: node.status,
                     conclusion: node.conclusion,
+                    source: "check_run",
                     detailsUrl: node.detailsUrl ?? "",
                     event,
                     runId,
+                    ...(createdAtUnix !== undefined && { createdAtUnix }),
+                    ...(startedAtUnix !== undefined && { startedAtUnix }),
+                    ...(updatedAtUnix !== undefined && { updatedAtUnix }),
                     ...(summary !== undefined && { summary }),
                 },
             ];
@@ -79,14 +103,17 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         if (node.__typename === "StatusContext") {
             const { status, conclusion } = mapStatusContextState(node.state);
             const summary = node.description?.trim() || undefined;
+            const createdAtUnix = node.createdAt ? parseCreatedAt(node.createdAt) : undefined;
             return [
                 {
                     name: node.context,
                     status,
                     conclusion,
+                    source: "status_context",
                     detailsUrl: node.targetUrl ?? "",
                     event: null,
                     runId: null,
+                    ...(createdAtUnix !== undefined && { createdAtUnix }),
                     ...(summary !== undefined && { summary }),
                 },
             ];

package/bin/github/batch.mjs

@@ -1,5 +1,6 @@
 import { graphql, graphqlWithRateLimit } from "./client.mjs";
 import { paginateForward, paginateBackward } from "./pagination.mjs";
+import { hydrateThreadCommentPages } from "./thread-comments.mjs";
 import { BATCH_PR_QUERY } from "./queries.mjs";
 import { parseRawPr } from "./batch-parsers.mjs";
 /**
@@ -36,6 +37,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
         // extra contains pages before the first page.
         rawThreadPages = [...extra, ...rawThreadPages];
     }
+    rawThreadPages = await hydrateThreadCommentPages(rawThreadPages);
     // Paginate comments backward if the first page is incomplete.
     let rawCommentNodes = raw.comments.nodes;
     if (raw.comments.pageInfo.hasPreviousPage && raw.comments.pageInfo.startCursor) {

package/bin/github/check-annotations.mjs

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { graphql } from "./client.mjs";
+import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
+const ANNOTATIONS_PER_PAGE = 100;
+const MAX_ANNOTATION_PAGES = 10;
+export async function fetchCheckRunAnnotations(checkRunId) {
+    let cursor = null;
+    const nodes = [];
+    for (let page = 1; page <= MAX_ANNOTATION_PAGES; page++) {
+        // eslint-disable-next-line no-await-in-loop
+        const result = await fetchAnnotationPage(checkRunId, cursor);
+        nodes.push(...result.nodes);
+        if (!result.pageInfo.hasNextPage || !result.pageInfo.endCursor)
+            break;
+        if (page === MAX_ANNOTATION_PAGES) {
+            process.stderr.write(`pr-shepherd: annotation pagination cap (${MAX_ANNOTATION_PAGES * ANNOTATIONS_PER_PAGE} annotations) reached for check run ${checkRunId} — annotation output may be incomplete\n`);
+            break;
+        }
+        cursor = result.pageInfo.endCursor;
+    }
+    return nodes.map((node) => toCheckAnnotation(checkRunId, node));
+}
+async function fetchAnnotationPage(checkRunId, cursor) {
+    const res = await graphql(CHECK_RUN_ANNOTATIONS_QUERY, {
+        id: checkRunId,
+        ...(cursor ? { cursor } : {}),
+    });
+    const node = res.data.node;
+    if (node?.__typename !== "CheckRun" || node.annotations === undefined) {
+        return { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+    }
+    return node.annotations;
+}
+function toCheckAnnotation(checkRunId, raw) {
+    const id = `check_annotation_${raw.fullDatabaseId ?? fallbackId(checkRunId, raw)}`;
+    const title = raw.title?.trim() || undefined;
+    const rawDetails = raw.rawDetails?.trim() || undefined;
+    const blobUrl = raw.blobUrl?.trim() || undefined;
+    return {
+        id,
+        path: raw.path,
+        startLine: raw.location?.start.line ?? null,
+        endLine: raw.location?.end.line ?? raw.location?.start.line ?? null,
+        ...(raw.location?.start.column !== undefined && {
+            startColumn: raw.location.start.column,
+        }),
+        ...(raw.location?.end.column !== undefined && {
+            endColumn: raw.location.end.column,
+        }),
+        level: raw.annotationLevel,
+        ...(title !== undefined && { title }),
+        message: raw.message,
+        ...(rawDetails !== undefined && { rawDetails }),
+        ...(blobUrl !== undefined && { blobUrl }),
+    };
+}
+function fallbackId(checkRunId, raw) {
+    const start = raw.location?.start;
+    const end = raw.location?.end;
+    const parts = [
+        checkRunId,
+        raw.path,
+        raw.annotationLevel,
+        raw.title ?? "",
+        raw.message,
+        raw.rawDetails ?? "",
+        raw.blobUrl ?? "",
+        String(start?.line ?? ""),
+        String(start?.column ?? ""),
+        String(end?.line ?? ""),
+        String(end?.column ?? ""),
+    ];
+    const input = parts.map((part) => `${part.length}:${part}`).join("|");
+    return createHash("sha256").update(input).digest("hex").slice(0, 24);
+}

package/bin/github/client.test-support.mjs

@@ -0,0 +1,55 @@
+import { vi, beforeEach, afterEach } from "vitest";
+import { _resetTokenCache } from "./http.mjs";
+export const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+const { _mockExecFile } = vi.hoisted(() => ({ _mockExecFile: vi.fn() }));
+export const mockExecFile = _mockExecFile;
+vi.mock("node:child_process", () => ({
+    execFile: (cmd, args, optsOrCb, maybeCb) => {
+        const cb = typeof optsOrCb === "function" ? optsOrCb : maybeCb;
+        _mockExecFile(cmd, args)
+            .then((result) => cb(null, result))
+            .catch((err) => cb(err, { stdout: "", stderr: "" }));
+    },
+}));
+export function gqlOk(data) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve({ data }),
+        text: () => Promise.resolve(JSON.stringify({ data })),
+    };
+}
+export function restOk(data) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve(data),
+        text: () => Promise.resolve(JSON.stringify(data)),
+    };
+}
+export function gqlErrors(errors) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve({ data: null, errors }),
+        text: () => Promise.resolve(JSON.stringify({ data: null, errors })),
+    };
+}
+export function registerClientHooks() {
+    beforeEach(() => {
+        mockFetch.mockReset();
+        mockExecFile.mockReset();
+        _resetTokenCache();
+        delete process.env["GITHUB_TOKEN"];
+        delete process.env["GITHUB_PERSONAL_ACCESS_TOKEN"];
+        process.env["GH_TOKEN"] = "test-token";
+    });
+    afterEach(() => {
+        delete process.env["GH_TOKEN"];
+        _resetTokenCache();
+    });
+}

package/bin/github/gql/batch-pr.gql

@@ -67,8 +67,14 @@ query BatchPr(
           id
           isResolved
           isOutdated
-          # first: 1 — we want the reviewer's original comment, not the latest reply.
-          comments(first: 1) {
+          path
+          line
+          startLine
+          comments(first: 100) {
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
             nodes {
               id
               isMinimized
@@ -164,21 +170,28 @@ query BatchPr(
                 nodes {
                   __typename
                   ... on CheckRun {
+                    id
                     name
                     status
                     conclusion
                     detailsUrl
+                    startedAt
                     title
                     summary
                     checkSuite {
+                      createdAt
+                      updatedAt
                       workflowRun {
                         event
+                        createdAt
+                        updatedAt
                       }
                     }
                   }
                   ... on StatusContext {
                     context
                     state
+                    createdAt
                     targetUrl
                     description
                   }

package/bin/github/gql/check-run-annotations.gql

@@ -0,0 +1,32 @@
+query CheckRunAnnotations($id: ID!, $cursor: String) {
+  node(id: $id) {
+    __typename
+    ... on CheckRun {
+      annotations(first: 100, after: $cursor) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          fullDatabaseId
+          path
+          annotationLevel
+          title
+          message
+          rawDetails
+          blobUrl
+          location {
+            start {
+              line
+              column
+            }
+            end {
+              line
+              column
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/review-thread-comments.gql

@@ -0,0 +1,27 @@
+query ReviewThreadComments($threadId: ID!, $commentsCursor: String) {
+  node(id: $threadId) {
+    __typename
+    ... on PullRequestReviewThread {
+      comments(first: 100, after: $commentsCursor) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          id
+          isMinimized
+          url
+          author {
+            __typename
+            login
+          }
+          body
+          path
+          line
+          startLine
+          createdAt
+        }
+      }
+    }
+  }
+}

package/bin/github/queries.mjs

@@ -11,6 +11,10 @@ import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export const BATCH_PR_QUERY = gql("batch-pr.gql");
+/** Fetches additional comments for a single review thread when its nested connection paginates. */
+export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
+/** Fetch inline annotations for a single CheckRun by node ID. */
+export const CHECK_RUN_ANNOTATIONS_QUERY = gql("check-run-annotations.gql");
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
 export const GET_PR_HEAD_SHA_QUERY = gql("get-pr-head-sha.gql");
 /** Look up PR number by branch name (for getCurrentPrNumber). */

package/bin/github/thread-comments.mjs

@@ -0,0 +1,34 @@
+import { graphql } from "./client.mjs";
+import { paginateForward } from "./pagination.mjs";
+import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
+export async function hydrateThreadCommentPages(threads) {
+    const hydrated = [];
+    for (const thread of threads) {
+        hydrated.push(await hydrateThreadCommentPage(thread));
+    }
+    return hydrated;
+}
+async function hydrateThreadCommentPage(thread) {
+    const pageInfo = thread.comments.pageInfo;
+    if (!pageInfo?.hasNextPage || !pageInfo.endCursor)
+        return thread;
+    const extra = await paginateForward(async (cursor) => {
+        const res = await graphql(REVIEW_THREAD_COMMENTS_QUERY, {
+            threadId: thread.id,
+            ...(cursor ? { commentsCursor: cursor } : {}),
+        });
+        const node = res.data.node;
+        if (!node?.comments) {
+            const nodeType = node?.__typename ?? "null";
+            throw new Error(`Review thread ${thread.id} did not resolve to PullRequestReviewThread while paginating comments (node type: ${nodeType})`);
+        }
+        return node.comments;
+    }, pageInfo.endCursor);
+    return {
+        ...thread,
+        comments: {
+            pageInfo: { hasNextPage: false, endCursor: null },
+            nodes: [...thread.comments.nodes, ...extra],
+        },
+    };
+}

package/bin/reporters/agent.mjs

@@ -22,6 +22,15 @@ export function toAgentThread(t) {
         ...(t.authorType !== undefined && { authorType: t.authorType }),
         body: t.body,
         url: t.url,
+        ...(t.comments !== undefined && {
+            comments: t.comments.map((c) => ({
+                id: c.id,
+                author: c.author,
+                ...(c.authorType !== undefined && { authorType: c.authorType }),
+                body: c.body,
+                url: c.url,
+            })),
+        }),
         ...(suggestion !== undefined && { suggestion }),
     };
 }
@@ -48,6 +57,23 @@ export function toAgentCheck(c) {
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
+        ...(c.annotations !== undefined && { annotations: c.annotations }),
+    };
+}
+export function toAgentStalledCheck(c, nowSeconds) {
+    const createdAtUnix = c.createdAtUnix ?? nowSeconds;
+    const activityAtUnix = c.updatedAtUnix ?? createdAtUnix;
+    return {
+        name: c.name,
+        status: c.status,
+        source: c.source ?? "check_run",
+        runId: c.runId,
+        detailsUrl: c.detailsUrl || null,
+        ...(c.createdAtUnix !== undefined && { createdAtUnix: c.createdAtUnix }),
+        ...(c.startedAtUnix !== undefined && { startedAtUnix: c.startedAtUnix }),
+        ...(c.updatedAtUnix !== undefined && { updatedAtUnix: c.updatedAtUnix }),
+        ageSeconds: Math.max(0, nowSeconds - activityAtUnix),
+        ...(c.summary !== undefined && { summary: c.summary }),
     };
 }
 /**

package/bin/state/seen-comments.test-support.mjs

@@ -0,0 +1,19 @@
+import { beforeEach, afterEach } from "vitest";
+import { randomBytes, createHash } from "node:crypto";
+import { rm } from "node:fs/promises";
+export function idToFilename(id) {
+    return createHash("sha256").update(id, "utf8").digest("hex") + ".json";
+}
+export const testKey = { owner: "test-owner", repo: "test-repo", pr: 123 };
+export const testId = "PRRT_kwDOTest123";
+export let testStateDir;
+export function registerHooks() {
+    beforeEach(() => {
+        testStateDir = `${process.env["TMPDIR"] ?? "/tmp"}/shepherd-seen-test-${randomBytes(4).toString("hex")}`;
+        process.env["PR_SHEPHERD_STATE_DIR"] = testStateDir;
+    });
+    afterEach(async () => {
+        delete process.env["PR_SHEPHERD_STATE_DIR"];
+        await rm(testStateDir, { recursive: true, force: true });
+    });
+}

package/bin/threads/transcript.mjs

@@ -0,0 +1,31 @@
+export function threadComments(thread) {
+    if (thread.comments && thread.comments.length > 0) {
+        return thread.comments.map((c) => ({
+            id: c.id,
+            isMinimized: c.isMinimized ?? false,
+            author: c.author,
+            authorType: c.authorType ?? "Unknown",
+            body: c.body,
+            url: c.url,
+            createdAtUnix: c.createdAtUnix ?? 0,
+        }));
+    }
+    return [
+        {
+            id: "",
+            isMinimized: false,
+            author: thread.author,
+            authorType: thread.authorType ?? "Unknown",
+            body: thread.body,
+            url: thread.url ?? "",
+            createdAtUnix: thread.createdAtUnix ?? 0,
+        },
+    ];
+}
+export function threadTranscriptBody(thread) {
+    if (!thread.comments || thread.comments.length === 0)
+        return thread.body;
+    return threadComments(thread)
+        .map((c) => `${c.id}\n${c.body}`)
+        .join("\n\n--- thread comment ---\n\n");
+}

package/bin/types/agent-thread.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/check-annotations.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/review-thread.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types.mjs

@@ -1,4 +1,7 @@
 /** Shared type definitions for the shepherd CLI. */
 export * from "./types/github.mjs";
+export * from "./types/review-thread.mjs";
+export * from "./types/agent-thread.mjs";
+export * from "./types/check-annotations.mjs";
 export * from "./types/report.mjs";
 export * from "./types/iterate.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -39,5 +39,5 @@ Poll dispatcher for iterating a PR to completion.
 
 4. **Stop conditions (terminal states):**
    - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
-   - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
+   - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures or CI that never starts.
    - **Do NOT merge the pull request** unless the human has explicitly requested or allowed it.