pr-shepherd 0.10.3 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/checks/triage.mjs

@@ -1,23 +1,19 @@
-import { rest, restText } from "../github/http.mjs";
-export function triageFailingChecks(failingChecks, repo, logTailLines, logTailChars = 200) {
+import { rest } from "../github/http.mjs";
+export function triageFailingChecks(failingChecks, repo) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, logTailLines, logTailChars)));
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
 }
-async function triageCheck(check, repo, jobsCache, logTailLines, logTailChars) {
-    if (check.runId === null) {
+async function triageCheck(check, repo, jobsCache) {
+    if (check.runId === null || check.conclusion === "CANCELLED") {
         return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
-    const logTail = jobInfo?.jobId !== undefined && logTailLines > 0
-        ? await fetchLogTail(jobInfo.jobId, repo, logTailLines, logTailChars, jobInfo.failedStep)
-        : undefined;
     return {
         ...check,
         ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
         ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
-        ...(logTail !== undefined && { logTail }),
     };
 }
 function fetchJobs(runId, repo, cache) {
@@ -67,42 +63,5 @@ function pickJobInfo(jobs, checkName) {
         workflowName: job.workflow_name,
         jobName: job.name,
         failedStep,
-        jobId: job.id,
     };
 }
-async function fetchLogTail(jobId, repo, logTailLines, logTailChars, failedStepName) {
-    const { owner, name } = repo;
-    try {
-        const text = await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`);
-        const allLines = text.split("\n");
-        const stepLines = failedStepName ? extractStepLines(allLines, failedStepName) : null;
-        const lines = stepLines ?? allLines;
-        const tail = lines.length <= logTailLines ? lines.join("\n") : lines.slice(-logTailLines).join("\n");
-        return tail.length <= logTailChars ? tail : tail.slice(-logTailChars);
-    }
-    catch {
-        return undefined;
-    }
-}
-// Extract the lines inside the ##[group]..##[endgroup] section for the named step.
-// Returns null when no matching group is found so the caller falls back to the full log.
-function extractStepLines(lines, stepName) {
-    const lowerStep = stepName.toLowerCase();
-    let inStep = false;
-    const result = [];
-    for (const line of lines) {
-        const content = line.replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z\s+/, "");
-        if (!inStep) {
-            if (content.startsWith("##[group]") && content.slice(9).toLowerCase().includes(lowerStep)) {
-                inStep = true;
-            }
-        }
-        else if (content.startsWith("##[endgroup]")) {
-            inStep = false;
-        }
-        else {
-            result.push(line);
-        }
-    }
-    return result.length > 0 ? result : null;
-}

package/bin/cli/fix-formatter.mjs

@@ -1,5 +1,4 @@
 import { renderResolveCommand } from "../commands/iterate.mjs";
-import { safeFence } from "./fence.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "./list-formatters.mjs";
@@ -37,16 +36,13 @@ export function formatFixCodeResult(header, result) {
                 : ch.detailsUrl
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
-            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\``];
-            if (ch.failedStep)
-                lines.push(`  > ${ch.failedStep}`);
-            if (ch.summary)
-                lines.push(`  > ${ch.summary}`);
-            if (ch.logTail) {
-                const fence = safeFence(ch.logTail);
-                lines.push(`  ${fence}`);
-                lines.push(ch.logTail.replace(/^/gm, "  ").trimEnd());
-                lines.push(`  ${fence}`);
+            const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
+            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}`];
+            if (ch.conclusion !== "CANCELLED") {
+                if (ch.failedStep)
+                    lines.push(`  > ${ch.failedStep}`);
+                if (ch.summary)
+                    lines.push(`  > ${ch.summary}`);
             }
             return lines.join("\n");
         });
@@ -96,6 +92,10 @@ export function formatFixCodeResult(header, result) {
         }
         sections.push(bullets.join("\n"));
     }
+    if (result.fix.inProgressRunIds.length > 0) {
+        sections.push("## In-progress runs");
+        sections.push(result.fix.inProgressRunIds.map((id) => `- \`${id}\``).join("\n"));
+    }
     if (result.cancelled.length > 0) {
         sections.push("## Cancelled runs");
         sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));

package/bin/cli/formatters.mjs

@@ -67,48 +67,29 @@ export function formatCommitSuggestionResult(result) {
     const range = result.startLine === result.endLine
         ? `line ${result.startLine}`
         : `lines ${result.startLine}–${result.endLine}`;
-    function pushPatch(patch) {
-        const fence = safeFence(patch);
+    lines.push(`Suggestion from @${result.author} for PR #${result.pr} — thread ${result.threadId}:`);
+    lines.push(`  repo: ${result.repo}`);
+    lines.push(`  ${result.path} (${range})`);
+    if (result.patch) {
+        const fence = safeFence(result.patch);
         lines.push("");
         lines.push(`${fence}diff`);
-        lines.push(patch.trimEnd());
+        lines.push(result.patch.trimEnd());
         lines.push(fence);
     }
-    if (result.dryRun) {
-        if (result.valid) {
-            lines.push(`Dry-run: would apply suggestion from @${result.author}:`);
-            lines.push(`  ${result.path} (${range})`);
-        }
-        else {
-            lines.push(`Dry-run: suggestion cannot apply cleanly:`);
-            lines.push(`- path: ${result.path} (${range})`);
-            lines.push(`- author: @${result.author}`);
-            lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        }
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    else if (result.applied) {
-        lines.push(`Applied suggestion from @${result.author}:`);
-        lines.push(`  ${result.path} (${range})`);
-        if (result.commitSha)
-            lines.push(`Commit: ${result.commitSha}`);
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    else {
-        lines.push(`Failed to apply suggestion ${result.threadId}:`);
-        lines.push(`- path: ${result.path} (${range})`);
-        lines.push(`- author: @${result.author}`);
-        lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        if (result.patch)
-            pushPatch(result.patch);
-    }
-    if (result.postActionInstruction) {
+    lines.push("");
+    lines.push("## Suggested commit message");
+    lines.push("");
+    lines.push(result.commitMessage);
+    lines.push("");
+    lines.push(result.commitBody);
+    if (result.postActionInstructions.length > 0) {
         lines.push("");
         lines.push("## Instructions");
         lines.push("");
-        lines.push(`1. ${result.postActionInstruction}`);
+        result.postActionInstructions.forEach((inst, i) => {
+            lines.push(`${i + 1}. ${inst}`);
+        });
     }
     return lines.join("\n");
 }

package/bin/cli/handlers.mjs

@@ -11,14 +11,12 @@ export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
     if (!threadId) {
-        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID [--message MSG] [--description DESC] [--dry-run]\n" +
-            "       (--message is required unless --dry-run is set)\n");
+        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]\n");
         process.exitCode = 1;
         return;
     }
-    const dryRun = hasFlag(extra, "--dry-run");
     const message = getFlag(extra, "--message") ?? undefined;
-    if (!dryRun && (!message || message.trim() === "")) {
+    if (!message || message.trim() === "") {
         process.stderr.write("--message is required and must be non-empty\n");
         process.exitCode = 1;
         return;
@@ -30,17 +28,10 @@ export async function handleCommitSuggestion(args) {
         threadId,
         message,
         description,
-        dryRun,
     });
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatCommitSuggestionResult(result)}\n`);
-    if (result.dryRun) {
-        process.exitCode = result.valid ? 0 : 1;
-    }
-    else {
-        process.exitCode = result.applied ? 0 : 1;
-    }
 }
 export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);

package/bin/cli/iterate-lean.mjs

@@ -67,6 +67,9 @@ export function projectIterateLean(result) {
                     ...(result.fix.firstLookComments.length > 0 && {
                         firstLookComments: result.fix.firstLookComments,
                     }),
+                    ...(result.fix.inProgressRunIds.length > 0 && {
+                        inProgressRunIds: result.fix.inProgressRunIds,
+                    }),
                     ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
                     ...(result.fix.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.fix.changesRequestedReviews,

package/bin/cli-parser.iterate-fixtures.mjs

@@ -44,6 +44,7 @@ export function makeIterateResult(action = "wait") {
                 instructions: ["End this iteration."],
                 firstLookThreads: [],
                 firstLookComments: [],
+                inProgressRunIds: [],
             },
             cancelled: [],
         };

package/bin/commands/check.mjs

@@ -35,9 +35,7 @@ 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, config.checks.logTailLines, config.checks.logTailChars)
-        : failing;
+    const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);

package/bin/commands/commit-suggestion.mjs

@@ -1,11 +1,8 @@
 import { execFile as execFileCb } from "node:child_process";
-import { readFile, writeFile, unlink } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
-import { applyResolveOptions } from "../comments/resolve.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
 const execFile = promisify(execFileCb);
@@ -13,13 +10,9 @@ export async function runCommitSuggestion(opts) {
     if (!opts.threadId) {
         throw new Error("--thread-id is required");
     }
-    if (!opts.dryRun && (!opts.message || opts.message.trim() === "")) {
+    if (!opts.message || opts.message.trim() === "") {
         throw new Error("--message is required and must be non-empty");
     }
-    const { stdout: statusOut } = await execFile("git", ["status", "--porcelain"]);
-    if (statusOut.trim() !== "") {
-        throw new Error("Working tree has uncommitted changes. Commit or stash them before running commit-suggestion.");
-    }
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
@@ -56,6 +49,17 @@ export async function runCommitSuggestion(opts) {
     if (!thread.path || thread.line === null) {
         throw new Error(`Thread ${opts.threadId} has no file/line anchor.`);
     }
+    // Validate the target file is clean before generating the patch, so the emitted
+    // `git add -- <file>` instruction cannot accidentally stage unrelated local edits.
+    const { stdout: fileStatus } = await execFile("git", [
+        "status",
+        "--porcelain",
+        "--",
+        thread.path,
+    ]);
+    if (fileStatus.trim() !== "") {
+        throw new Error(`${thread.path} has uncommitted changes. Commit or stash them before running commit-suggestion.`);
+    }
     const parsed = parseSuggestion(thread.body);
     if (!parsed) {
         throw new Error(`Thread ${opts.threadId} has no suggestion block in the comment body.`);
@@ -75,74 +79,25 @@ export async function runCommitSuggestion(opts) {
         endLine,
         replacementLines: parsed.lines,
     });
-    const patchFile = join(tmpdir(), `pr-shepherd-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`);
-    let patchError = null;
-    try {
-        await writeFile(patchFile, patch, { mode: 0o600 });
-        try {
-            await execFile("git", ["apply", "--check", patchFile]);
-        }
-        catch (err) {
-            patchError = (err.stderr?.trim() || String(err)).trim();
-        }
-        if (opts.dryRun) {
-            return {
-                pr: prNumber,
-                repo: `${repo.owner}/${repo.name}`,
-                threadId: opts.threadId,
-                path: filePath,
-                startLine,
-                endLine,
-                author: thread.author,
-                applied: false,
-                dryRun: true,
-                valid: patchError === null,
-                reason: patchError !== null ? `git apply rejected the patch: ${patchError}` : null,
-                patch,
-                postActionInstruction: patchError === null ? "Re-run without --dry-run to apply and commit." : "",
-            };
-        }
-        if (patchError !== null) {
-            return {
-                pr: prNumber,
-                repo: `${repo.owner}/${repo.name}`,
-                threadId: opts.threadId,
-                path: filePath,
-                startLine,
-                endLine,
-                author: thread.author,
-                applied: false,
-                reason: `git apply rejected the patch: ${patchError}`,
-                patch,
-                postActionInstruction: "",
-            };
-        }
-        try {
-            await execFile("git", ["apply", patchFile]);
-        }
-        catch (applyErr) {
-            try {
-                await execFile("git", ["checkout", "--", filePath]);
-            }
-            catch {
-                // best-effort rollback
-            }
-            throw applyErr;
-        }
-    }
-    finally {
-        await unlink(patchFile).catch(() => undefined);
-    }
-    await execFile("git", ["add", "--", filePath]);
     const coAuthor = `Co-authored-by: ${thread.author} <${thread.author}@users.noreply.github.com>`;
     const commitBody = opts.description ? `${opts.description}\n\n${coAuthor}` : coAuthor;
-    await execFile("git", ["commit", "-m", opts.message, "-m", commitBody]);
-    const { stdout: shaOut } = await execFile("git", ["rev-parse", "HEAD"]);
-    const commitSha = shaOut.trim();
-    const resolveResult = await applyResolveOptions(prNumber, repo, {
-        resolveThreadIds: [opts.threadId],
-    });
-    const resolveErrors = resolveResult.errors;
+    const commitMessageArg = opts.message;
+    const commitBodyArg = commitBody;
+    const quotedPath = `'${filePath.replace(/'/g, "'\\''")}'`;
+    const range = startLine === endLine ? `line ${startLine}` : `lines ${startLine}–${endLine}`;
+    const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+    const commitCmd = [
+        "git commit",
+        `-m ${sq(commitMessageArg)}`,
+        ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
+    ].join(" ");
+    const postActionInstructions = [
+        `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
+        `Stage the file: \`git add -- ${quotedPath}\``,
+        `Commit: \`${commitCmd}\``,
+        `Resolve the thread on GitHub: \`npx pr-shepherd resolve ${prNumber} --resolve-thread-ids ${opts.threadId}\``,
+        `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
+    ];
     return {
         pr: prNumber,
         repo: `${repo.owner}/${repo.name}`,
@@ -151,11 +106,10 @@ export async function runCommitSuggestion(opts) {
         startLine,
         endLine,
         author: thread.author,
-        applied: true,
-        commitSha,
         patch,
-        postActionInstruction: resolveErrors.length > 0
-            ? `Commit created (${commitSha}), but failed to resolve thread ${opts.threadId}: ${resolveErrors.join("; ")}. Run \`git push\` then resolve manually.`
-            : "Run `git push` (or `git push --force-with-lease` after rebasing) to publish the commit.",
+        commitMessage: commitMessageArg,
+        commitBody: commitBodyArg,
+        filesToStage: [filePath],
+        postActionInstructions,
     };
 }

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

@@ -4,7 +4,7 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { tryCancelRun } from "./helpers.mjs";
+import { tryCancelRun, buildInProgressRunIds } from "./helpers.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;
@@ -46,12 +46,19 @@ export async function handleFixCode(ctx) {
         const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
         cancelled = results.filter((id) => id !== null);
     }
+    const cancelledSet = new Set(cancelled);
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const actionableComments = report.comments.actionable.map(toAgentComment);
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
+    const needsPush = threads.length > 0 ||
+        actionableComments.length > 0 ||
+        checks.length > 0 ||
+        changesRequestedReviews.length > 0 ||
+        hasConflicts;
+    const inProgressRunIds = needsPush ? buildInProgressRunIds(report, cancelledSet) : [];
     const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
     const resolveCommand = buildResolveCommand(threads, allCommentIds, changesRequestedReviews, checks, prNumber);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
@@ -73,7 +80,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);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -92,6 +99,7 @@ export async function handleFixCode(ctx) {
             instructions,
             firstLookThreads,
             firstLookComments,
+            inProgressRunIds,
         },
         cancelled,
     }, report, reviewSummaryIds);

package/bin/commands/iterate/helpers.mjs

@@ -2,6 +2,13 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
 const execFile = promisify(execFileCb);
+export function buildInProgressRunIds(report, cancelledSet) {
+    return [
+        ...new Set(report.checks.inProgress
+            .map((c) => c.runId)
+            .filter((id) => id !== null && !cancelledSet.has(id))),
+    ];
+}
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -84,6 +91,33 @@ export async function getCurrentHeadSha() {
         return null;
     }
 }
+export function buildWaitLog(base) {
+    const { summary, remainingSeconds } = base;
+    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
+    switch (base.mergeStatus) {
+        case "BLOCKED":
+            if (base.reviewDecision === "REVIEW_REQUIRED")
+                parts.push("awaiting human review");
+            else if (base.reviewDecision === "APPROVED")
+                parts.push("awaiting additional approvals");
+            else
+                parts.push("awaiting human review or branch protection");
+            break;
+        case "BEHIND":
+            parts.push("branch is behind base");
+            break;
+        case "DRAFT":
+            parts.push("PR is a draft");
+            break;
+        case "UNSTABLE":
+            parts.push("some checks are unstable");
+            break;
+    }
+    if (remainingSeconds > 0) {
+        parts.push(`${remainingSeconds}s until auto-cancel`);
+    }
+    return parts.join(" — ");
+}
 export function buildCooldownResult(prNumber, readyDelaySeconds) {
     return {
         action: "cooldown",

package/bin/commands/iterate/index.mjs

@@ -4,10 +4,9 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, } from "./helpers.mjs";
+import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, buildWaitLog, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { buildWaitLog } from "./render.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();

package/bin/commands/iterate/render.mjs

@@ -18,11 +18,14 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = []) {
     const instructions = [];
+    if (inProgressRunIds.length > 0) {
+        instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\`. Do this before applying any code fixes — the push at the end of this iteration will supersede those runs anyway, so letting them continue burns CI minutes for results no one will read. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
+    }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
-        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` the CLI already resolved the thread — remove its ID from \`--resolve-thread-ids\` in the \`resolve:\` command below. On \`applied: false\` read \`reason\` and \`patch\`, fall through to the manual-edit step, and do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) to preview the patch without mutating the working tree.`);
+        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the \`resolve:\` command below (the thread is not auto-resolved). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions
@@ -30,11 +33,17 @@ export function buildFixInstructions(threads, actionableComments, checks, review
             : "";
         instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.${suggestionFallback}`);
     }
-    const checksWithRunId = checks.filter((c) => c.runId);
+    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
+    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED");
     const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
     const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (checksWithRunId.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID, examine the log tail in the fenced block to decide what to do:\n   - If the log tail shows a transient runner or infrastructure failure (network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\` and stop this iteration — CI will re-run automatically.\n   - If the log tail shows a real test or build failure, apply a code fix.\n   - If the fenced log block is absent, run \`gh run view <runId> --log-failed\` first to fetch it, then choose between rerun and fix above.`);
+    if (failedRunIdChecks.length > 0) {
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`);
+        instructions.push(`If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`);
+        instructions.push(`If the log shows a real test/build failure: apply a code fix.`);
+    }
+    if (cancelledRunIdChecks.length > 0) {
+        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
     }
     if (externalChecks.length > 0) {
         instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
@@ -103,30 +112,3 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     }
     return instructions;
 }
-export function buildWaitLog(base) {
-    const { summary, remainingSeconds } = base;
-    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
-    switch (base.mergeStatus) {
-        case "BLOCKED":
-            if (base.reviewDecision === "REVIEW_REQUIRED")
-                parts.push("awaiting human review");
-            else if (base.reviewDecision === "APPROVED")
-                parts.push("awaiting additional approvals");
-            else
-                parts.push("awaiting human review or branch protection");
-            break;
-        case "BEHIND":
-            parts.push("branch is behind base");
-            break;
-        case "DRAFT":
-            parts.push("PR is a draft");
-            break;
-        case "UNSTABLE":
-            parts.push("some checks are unstable");
-            break;
-    }
-    if (remainingSeconds > 0) {
-        parts.push(`${remainingSeconds}s until auto-cancel`);
-    }
-    return parts.join(" — ");
-}

package/bin/commands/resolve-instructions.mjs

@@ -29,7 +29,7 @@ export function buildFetchInstructions(prNumber, result) {
         instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body. Do **not** include their IDs in \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
     }
     if (hasSuggestions) {
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` mark it Fixed — the CLI already resolved the thread, so exclude the ID from \`--resolve-thread-ids\`. On \`applied: false\` read \`reason\` and \`patch\`, then fall through to the manual fix step — do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) if you want to inspect the unified diff before it mutates the working tree — the CLI validates with \`git apply --check\`, returns the patch and \`valid: true/false\`, and exits \`1\` on drift without committing or resolving the thread.`);
+        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
     }
     if (hasCodeItems) {
         instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);

package/bin/config.json

@@ -17,9 +17,7 @@
     "fetchReviewSummaries": true
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"],
-    "logTailLines": 5,
-    "logTailChars": 200
+    "ciTriggerEvents": ["pull_request", "pull_request_target"]
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]

package/bin/reporters/agent.mjs

@@ -3,7 +3,8 @@
  *
  * These strip fields that are always-false by the time items reach iterate
  * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
- * monitor prompt never reads (event, status, conclusion, category).
+ * monitor prompt never reads (event, status, category).
+ * conclusion is preserved on AgentCheck so the formatter can branch on CANCELLED.
  * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
  * The original domain types are preserved for check command output.
  */
@@ -27,15 +28,18 @@ export function toAgentComment(c) {
     return { id: c.id, author: c.author, body: c.body, url: c.url };
 }
 export function toAgentCheck(c) {
+    if (c.conclusion === "SKIPPED" || c.conclusion === "NEUTRAL") {
+        throw new Error(`Unexpected conclusion ${c.conclusion} in toAgentCheck`);
+    }
     return {
         name: c.name,
         runId: c.runId,
         detailsUrl: c.detailsUrl,
+        conclusion: c.conclusion,
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
-        ...(c.logTail !== undefined && { logTail: c.logTail }),
     };
 }
 /**

package/bin/reporters/check-instructions.mjs

@@ -28,8 +28,8 @@ export function buildCheckInstructions(report) {
     for (const c of checks.failing) {
         const stepHint = c.failedStep ? ` (failed step: \`${c.failedStep}\`)` : "";
         const diagnosisHint = c.runId
-            ? c.logTail !== undefined
-                ? `examine the log tail${stepHint} — if transient, run \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
+            ? c.conclusion === "CANCELLED"
+                ? `cancelled — if unintended, rerun with \`gh run rerun ${c.runId}\``
                 : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
             : c.detailsUrl
                 ? `open the check details (${c.detailsUrl}) to diagnose the failure`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",