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

package/README.md

@@ -22,10 +22,10 @@ Example Workflow:
 
 The CLI emits unified recheck instructions. Generated commands call `pr-shepherd` directly.
 
-At a high level, the skill invokes `pr-shepherd poll <PR>`, which provides actionable feedback directly to the agent:
+At a high level, the skill invokes `pr-shepherd <PR>` (which polls by default), providing actionable feedback directly to the agent:
 
 ```text
-> pr-shepherd poll 123
+> pr-shepherd 123
 
 # PR #123 [FIX_CODE]
 
@@ -34,7 +34,9 @@ At a high level, the skill invokes `pr-shepherd poll <PR>`, which provides actio
 
 ## 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.
 >
@@ -61,7 +63,7 @@ _(schematic — actual steps depend on PR state)_
 4. Rebase and push: `git fetch origin && git rebase origin/main && git push --force-with-lease` — capture `HEAD_SHA=$(git rev-parse HEAD)`.
 5. Run the `resolve:` command above, substituting `"$HEAD_SHA"`.
 6. Add or update a `## Shepherd Journal` section in the PR description for any large decisions made, appending under the existing heading if it already exists.
-7. CI needs time to run on the new push. Run `pr-shepherd poll 123` again to continue until Shepherd returns `[CANCEL]` or `[ESCALATE]`.
+7. CI needs time to run on the new push. Run `pr-shepherd 123` again to continue until Shepherd returns `[CANCEL]` or `[ESCALATE]`.
 ```
 
 On every iteration, a command is returned to instruct the agent exactly what to do. No guessing, no thinking, as few agentic turns as possible:
@@ -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 poll` 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.
@@ -114,7 +116,7 @@ Recommendations:
 
 ### Iterate a PR to completion
 
-Poll dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section; the skill follows it, then invokes `pr-shepherd poll` again until `[CANCEL]` or `[ESCALATE]`.
+Poll dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section; the skill follows it, then invokes `pr-shepherd <PR>` again until `[CANCEL]` or `[ESCALATE]`.
 
 Claude Code (via `pr-shepherd` skill):
 
@@ -128,9 +130,9 @@ Codex or direct CLI:
 
 ```sh
 pr-shepherd 42
+pr-shepherd 42 --interval 45s --timeout 4m
 pr-shepherd 42 --ready-delay 15m
-pr-shepherd poll 42
-pr-shepherd iterate 42               # legacy-compatible spelling
+pr-shepherd iterate 42               # single tick
 ```
 
 ## Iterate decision loop
@@ -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/checks/triage.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Stub fetch globally so http.mts uses our mock.
 // ---------------------------------------------------------------------------

package/bin/cli/default-poll.mjs

@@ -0,0 +1,32 @@
+import { parsePrNumber } from "./args.mjs";
+import { validateDefaultArgs } from "./validate-default-args.mjs";
+import { USAGE } from "./help.mjs";
+const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--interval",
+    "--timeout",
+]);
+const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
+    "--verbose",
+    "--no-auto-mark-ready",
+    "--no-auto-cancel-actionable",
+]);
+export function isDefaultPollInvocation(subcommand) {
+    if (subcommand === "--help" || subcommand === "-h")
+        return false;
+    return (subcommand === undefined || parsePrNumber(subcommand) !== null || isDefaultPollFlag(subcommand));
+}
+export function validateDefaultPollArgs(args) {
+    return validateDefaultArgs(args, DEFAULT_POLL_FLAGS_WITH_VALUES, DEFAULT_POLL_BOOLEAN_FLAGS, writeDefaultUsageError);
+}
+function isDefaultPollFlag(arg) {
+    const name = arg.split("=", 1)[0];
+    return DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) || DEFAULT_POLL_BOOLEAN_FLAGS.has(arg);
+}
+function writeDefaultUsageError(arg) {
+    process.stderr.write(`Unknown subcommand: ${arg}\n`);
+    process.stderr.write(`${USAGE.top}\n`);
+    process.exitCode = 1;
+}

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/help-command-pages.mjs

@@ -51,11 +51,10 @@ Exit codes:
   1  validation, lookup, precondition, or suggestion parsing failure`,
     iterate: `pr-shepherd iterate
 
-Run one iterate tick for a pull request. This is an alias for 'pr-shepherd [PR]'.
+Run one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.
 The output contains one action and an action-specific ## Instructions section.
 
 Usage:
-  pr-shepherd [PR] [iterate-flags]
   pr-shepherd iterate [PR] [iterate-flags]
 
 Iterate flags:
@@ -98,11 +97,11 @@ Forwarded iterate flags:
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
   --format text|json             Output Markdown text or JSON. Default: text.
-  --verbose                      Include verbose iterate fields and always print poll progress.
+  --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
 
 Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
-WAIT progress is written to stderr when stderr is a TTY or --verbose is set.
+Each WAIT tick writes a single dot to stderr; --verbose emits the detailed per-tick line.
 
 Exit codes:
   0  WAIT timeout or MARK_READY

package/bin/cli/help-top-page.mjs

@@ -5,8 +5,8 @@ Autonomous PR CI monitor and review-comment resolver for agentic coding tools.
 Usage:
   pr-shepherd --version | -v
   pr-shepherd --help | -h
-  pr-shepherd [PR] [flags]
-  pr-shepherd iterate [PR] [flags]
+  pr-shepherd [PR] [poll-flags] [iterate-flags]
+  pr-shepherd iterate [PR] [iterate-flags]
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
   pr-shepherd resolve [PR] [resolve-flags]
   pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [flags]
@@ -14,8 +14,8 @@ Usage:
   pr-shepherd log-file [--format text|json]
 
 Commands:
-  [PR]                 Run one iterate tick. This is the default command.
-  iterate              Alias for the default one-tick iterate command.
+  [PR]                 Poll until non-WAIT or timeout. This is the default command.
+  iterate              Run one iterate tick (single-tick alias).
   poll                 Re-run iterate while the action is WAIT, then print the final tick.
   resolve              Fetch actionable review items, or resolve/minimize/dismiss IDs.
   commit-suggestion    Convert one GitHub suggestion thread into a patch and commit instructions.
@@ -28,7 +28,7 @@ PR argument:
 
 Common flags:
   --format text|json   Output Markdown text or JSON. Default: text.
-  --verbose            Include verbose iterate fields and poll progress.
+  --verbose            Include verbose iterate fields and detailed poll-tick lines.
   --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
 
 Iterate flags:

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/iterate-lean.test-support.mjs

@@ -1,5 +1,3 @@
-// @ts-nocheck
-import { describe, it, expect } from "vitest";
 import { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
 import { makeIterateResult } from "../cli-parser.iterate-fixtures.mjs";
 export { makeIterateResult, projectIterateLean, projectIterateVerbose };

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/cli/validate-default-args.mjs

@@ -0,0 +1,32 @@
+import { parsePrNumber } from "./args.mjs";
+/**
+ * Validate args for default-dispatch paths (e.g. `pr-shepherd [PR] [flags]`).
+ * Returns false when an unexpected token is found; calls onError with the
+ * offending arg so callers can print their own usage message.
+ */
+export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError) {
+    let sawPr = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (flagsWithValues.has(arg)) {
+            if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+                onError(arg);
+                return false;
+            }
+            i += 1;
+            continue;
+        }
+        const inlineFlag = arg.split("=", 1)[0];
+        if (flagsWithValues.has(inlineFlag))
+            continue;
+        if (booleanFlags.has(arg))
+            continue;
+        if (parsePrNumber(arg) !== null && !sawPr) {
+            sawPr = true;
+            continue;
+        }
+        onError(arg);
+        return false;
+    }
+    return true;
+}

package/bin/cli-parser.clean.test-support.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/clean.mts", () => ({
     runClean: vi.fn(),

package/bin/cli-parser.commit-suggestion.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),

package/bin/cli-parser.iterate-fix.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),

package/bin/cli-parser.iterate.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),

package/bin/cli-parser.mjs

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   pr-shepherd --version
- *   pr-shepherd [PR] [--format text|json] [--ready-delay Nm]
+ *   pr-shepherd [PR] [--interval 45s] [--timeout 4m] [--format text|json] [--ready-delay Nm]
  *                  [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                  [--no-auto-cancel-actionable]
  *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
@@ -22,7 +22,7 @@ import { readFileSync } from "node:fs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
-import { isDefaultIterateInvocation, validateDefaultIterateArgs } from "./cli/default-iterate.mjs";
+import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, maybePrintHelp } from "./cli/help.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
@@ -49,8 +49,8 @@ export async function main(argv) {
     }
     // Short-circuit all --help/-h before any I/O or logging.
     if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
-        if (isDefaultIterateInvocation(subcommand)) {
-            process.stdout.write(`${USAGE.iterate}\n`);
+        if (isDefaultPollInvocation(subcommand)) {
+            process.stdout.write(`${USAGE.poll}\n`);
         }
         else {
             const key = subcommand != null && subcommand in USAGE
@@ -62,10 +62,10 @@ export async function main(argv) {
     }
     // Initialize the per-worktree log and install a stdout tee.
     await setupLog(argv);
-    if (isDefaultIterateInvocation(subcommand)) {
-        if (!validateDefaultIterateArgs(args))
+    if (isDefaultPollInvocation(subcommand)) {
+        if (!validateDefaultPollArgs(args))
             return;
-        await handleIterate(args);
+        await handlePoll(args);
         return;
     }
     switch (subcommand) {

package/bin/cli-parser.test-support.mjs

@@ -1,6 +1,5 @@
-// @ts-nocheck
 import { readFileSync } from "node:fs";
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { vi, beforeEach, afterEach } from "vitest";
 vi.mock("./commands/resolve.mts", () => ({
     runResolveFetch: vi.fn(),
     runResolveMutate: vi.fn(),

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,15 +40,18 @@ 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 = [];
     let autoResolveErrors = [];
     if (opts.autoResolve && outdated.length > 0) {
         const { resolved: resolvedIds, errors } = await autoResolveOutdated(outdated.map((t) => t.id));
-        autoResolved = outdated.filter((t) => resolvedIds.includes(t.id));
+        const resolvedIdsSet = new Set(resolvedIds); // ⚡ Bolt optimization: O(1) lookup
+        autoResolved = outdated.filter((t) => resolvedIdsSet.has(t.id));
         autoResolveErrors = errors;
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated && !t.isMinimized);
@@ -54,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 = {
@@ -70,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" };
@@ -104,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

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 vi.mock("../github/batch.mts", () => ({ fetchPrBatch: vi.fn() }));
 vi.mock("../github/client.mts", () => ({
     getRepoInfo: vi.fn().mockResolvedValue({ owner: "owner", name: "repo" }),
@@ -10,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: [] }),
 }));
@@ -27,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);
@@ -34,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);
@@ -42,7 +46,7 @@ function defaultConfig() {
     return {
         iterate: {
             fixAttemptsPerThread: 3,
-            stallTimeoutMinutes: 30,
+            stallTimeoutMinutes: 60,
             minimizeApprovals: false,
             minimizeComments: "all",
         },
@@ -64,6 +68,7 @@ function defaultConfig() {
 }
 function makeCheck(overrides = {}) {
     return {
+        id: null,
         name: "tests",
         status: "COMPLETED",
         conclusion: "SUCCESS",
@@ -136,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/clean.test-support.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { vi, beforeEach, afterEach } from "vitest";
 import { join } from "node:path";
 import { mkdtemp, realpath, rm, mkdir, writeFile, stat } from "node:fs/promises";