pr-shepherd 0.9.0 → 0.10.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.9.0",
+  "version": "0.10.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -40,7 +40,7 @@ Loop args: `4m --max-turns 50 --expires 8h`
 after completing the actions below. The cron job handles the next fire.
 
 Run in a single Bash call:
-  npx pr-shepherd iterate 123 --no-cache
+  npx pr-shepherd iterate 123
 
 …(self-dedup guidance, error-handling instructions)…
 
@@ -231,7 +231,7 @@ actions:
   autoMarkReady: false # disable to stay draft until you manually promote
 ```
 
-Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state base dir).
+Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log).
 
 See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
 

package/bin/checks/triage.mjs

@@ -1,44 +1,16 @@
-/**
- * Triage failing check runs: call the jobs API once per runId to fetch
- * workflow name, job name, and the first failed step name. Then fetch the
- * last N lines of the failing job's log so the agent can diagnose failures
- * without a separate tool call.
- *
- * No heuristic classification is applied — the raw GitHub `conclusion` field
- * is preserved as-is. The agent decides whether a failure is transient or
- * real based on the log tail and other context.
- *
- * For checks with runId === null (external StatusContexts) no API calls are
- * made; workflowName, jobName, failedStep, and logTail are all absent.
- *
- * Jobs responses are cached by runId so checks that share a run (e.g. matrix
- * builds or multiple required steps in one workflow) make only one API call.
- * Log tails are fetched per job ID, not per runId.
- */
 import { rest, restText } from "../github/http.mjs";
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Triage each failing check: call the jobs API for each check with a non-null
- * runId to fetch workflow name, job name, and the first failed step name, then
- * fetch the last `logTailLines` lines of the failing job's log.
- */
-export function triageFailingChecks(failingChecks, repo, logTailLines) {
+export function triageFailingChecks(failingChecks, repo, logTailLines, logTailChars = 200) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, logTailLines)));
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, logTailLines, logTailChars)));
 }
-// ---------------------------------------------------------------------------
-// Internal
-// ---------------------------------------------------------------------------
-async function triageCheck(check, repo, jobsCache, logTailLines) {
+async function triageCheck(check, repo, jobsCache, logTailLines, logTailChars) {
     if (check.runId === null) {
         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)
+        ? await fetchLogTail(jobInfo.jobId, repo, logTailLines, logTailChars, jobInfo.failedStep)
         : undefined;
     return {
         ...check,
@@ -80,9 +52,6 @@ async function fetchJobsUncached(runId, repo) {
     return allJobs;
 }
 function pickJobInfo(jobs, checkName) {
-    // Match by name. For matrix jobs sharing a check name, prefer a failing one.
-    // Fall back to prefix matching for matrix jobs whose workflow-API name includes
-    // a suffix like "(ubuntu)" while checkName is just the base name.
     const exactMatches = jobs.filter((j) => j.name === checkName);
     const matchedJobs = exactMatches.length > 0 ? exactMatches : jobs.filter((j) => j.name.startsWith(checkName));
     const job = matchedJobs.find((j) => j.conclusion === "failure") ??
@@ -101,16 +70,39 @@ function pickJobInfo(jobs, checkName) {
         jobId: job.id,
     };
 }
-async function fetchLogTail(jobId, repo, logTailLines) {
+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 lines = text.split("\n");
-        if (lines.length <= logTailLines)
-            return text;
-        return lines.slice(-logTailLines).join("\n");
+        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/fence.mjs

@@ -0,0 +1,4 @@
+export function safeFence(content) {
+    const maxRun = Math.max(0, ...Array.from(content.matchAll(/`+/g), (m) => m[0].length));
+    return "`".repeat(Math.max(3, maxRun + 1));
+}

package/bin/cli/fix-formatter.mjs

@@ -1,23 +1,28 @@
 import { renderResolveCommand } from "../commands/iterate.mjs";
-function safeFence(content) {
-    const maxRun = Math.max(0, ...Array.from(content.matchAll(/`+/g), (m) => m[0].length));
-    return "`".repeat(Math.max(3, maxRun + 1));
-}
+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";
 export function formatFixCodeResult(header, result) {
     const sections = [header];
     if (result.fix.threads.length > 0) {
         sections.push("## Review threads");
         for (const t of result.fix.threads) {
-            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
-            const heading = t.url ? `[${t.id}](${t.url})` : `\`${t.id}\``;
-            sections.push(`### ${heading} — ${loc} (@${t.author})`);
+            const lineLabel = renderLineRange(t.startLine, t.line);
+            const loc = t.path ? `\`${t.path}:${lineLabel}\`` : "(no location)";
+            const heading = t.url ? `[threadId=${t.id}](${t.url})` : `\`threadId=${t.id}\``;
+            const suggestionMarker = t.suggestion ? " [suggestion]" : "";
+            sections.push(`### ${heading} — ${loc} (@${t.author})${suggestionMarker}`);
             sections.push(blockquote(t.body));
+            if (t.suggestion) {
+                sections.push(renderSuggestionBlock(t.suggestion, ""));
+            }
         }
     }
     if (result.fix.actionableComments.length > 0) {
         sections.push("## Actionable comments");
         for (const c of result.fix.actionableComments) {
-            const heading = c.url ? `[${c.id}](${c.url})` : `\`${c.id}\``;
+            const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
             sections.push(`### ${heading} (@${c.author})`);
             sections.push(blockquote(c.body));
         }
@@ -49,20 +54,16 @@ export function formatFixCodeResult(header, result) {
     }
     if (result.fix.changesRequestedReviews.length > 0) {
         sections.push("## Changes-requested reviews");
-        sections.push(result.fix.changesRequestedReviews.map((r) => `- \`${r.id}\` (@${r.author})`).join("\n"));
-    }
-    if (result.fix.noiseCommentIds.length > 0) {
-        sections.push("## Noise (minimize only)");
-        sections.push(result.fix.noiseCommentIds.map((id) => `\`${id}\``).join(", "));
+        sections.push(result.fix.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
     }
     if (result.fix.reviewSummaryIds.length > 0) {
         sections.push("## Review summaries (minimize only)");
-        sections.push(result.fix.reviewSummaryIds.map((id) => `\`${id}\``).join(", "));
+        sections.push(result.fix.reviewSummaryIds.map((id) => `- \`${id}\``).join("\n"));
     }
     if (result.fix.surfacedApprovals.length > 0) {
         sections.push("## Approvals (surfaced — not minimized)");
         for (const r of result.fix.surfacedApprovals) {
-            sections.push(`### \`${r.id}\` (@${r.author})`);
+            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
@@ -71,20 +72,16 @@ export function formatFixCodeResult(header, result) {
         sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
         const bullets = [];
         for (const t of result.fix.firstLookThreads) {
-            const statusTag = t.autoResolved
-                ? `[status: outdated, auto-resolved]`
-                : `[status: ${t.firstLookStatus}]`;
-            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
-            bullets.push(`- \`${t.id}\` ${loc} (@${t.author}) ${statusTag}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+            bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of result.fix.firstLookComments) {
-            bullets.push(`- \`${c.id}\` (@${c.author}) [status: minimized]: ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
         }
         sections.push(bullets.join("\n"));
     }
     if (result.cancelled.length > 0) {
         sections.push("## Cancelled runs");
-        sections.push(result.cancelled.map((id) => `\`${id}\``).join(", "));
+        sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));
     }
     sections.push("## Post-fix push");
     const postFixLines = [`- base: \`${result.baseBranch}\``];
@@ -94,9 +91,9 @@ export function formatFixCodeResult(header, result) {
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
     sections.push(result.fix.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
-    return sections.join("\n\n");
+    return joinSections(sections);
 }
-export function blockquote(body) {
+function blockquote(body) {
     return body
         .replace(/\r\n/g, "\n")
         .split("\n")

package/bin/cli/formatters.mjs

@@ -1,5 +1,8 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
 export { projectIterateLean } from "./iterate-lean.mjs";
+import { safeFence } from "./fence.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "./list-formatters.mjs";
+import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
     const activeTotal = result.actionableThreads.length +
         result.actionableComments.length +
@@ -19,44 +22,29 @@ export function formatFetchResult(result) {
         sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
             (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
         sections.push(result.actionableThreads
-            .map((t) => {
-            const suggestionMarker = t.suggestion ? " [suggestion]" : "";
-            const link = t.url ? ` [↗](${t.url})` : "";
-            return `- \`threadId=${t.id}\`${link} \`${t.path ?? ""}:${t.line ?? "?"}\` (@${t.author})${suggestionMarker}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`;
-        })
-            .join("\n"));
+            .map((t) => renderThreadBullet(t, { renderSuggestion: true }))
+            .join("\n\n"));
     }
     if (result.actionableComments.length > 0) {
         sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
-        sections.push(result.actionableComments
-            .map((c) => {
-            const link = c.url ? ` [↗](${c.url})` : "";
-            return `- \`commentId=${c.id}\`${link} (@${c.author}): ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`;
-        })
-            .join("\n"));
+        sections.push(result.actionableComments.map((c) => renderCommentBullet(c)).join("\n"));
     }
     if (result.changesRequestedReviews.length > 0) {
         sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);
-        sections.push(result.changesRequestedReviews.map((r) => `- \`reviewId=${r.id}\` (@${r.author})`).join("\n"));
+        sections.push(result.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
     }
     if (result.reviewSummaries.length > 0) {
         sections.push(`## Review summaries (${result.reviewSummaries.length})`);
-        sections.push(result.reviewSummaries
-            .map((r) => `- \`reviewId=${r.id}\` (@${r.author}): ${r.body.split("\n")[0].slice(0, 100)}`)
-            .join("\n"));
+        sections.push(result.reviewSummaries.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n"));
     }
     if (firstLookTotal > 0) {
         sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
         const bullets = [];
         for (const t of result.firstLookThreads) {
-            const statusTag = t.autoResolved
-                ? `[status: outdated, auto-resolved]`
-                : `[status: ${t.firstLookStatus}]`;
-            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
-            bullets.push(`- \`threadId=${t.id}\` ${loc} (@${t.author}) ${statusTag}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+            bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of result.firstLookComments) {
-            bullets.push(`- \`commentId=${c.id}\` (@${c.author}) [status: minimized]: ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
         }
         sections.push(bullets.join("\n"));
     }
@@ -71,14 +59,21 @@ export function formatFetchResult(result) {
             .join(", "));
     sections.push("## Instructions");
     sections.push(result.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
-    return `${sections.join("\n\n")}\n`;
+    return joinSections(sections);
 }
 export function formatCommitSuggestionResult(result) {
     const lines = [];
+    const range = result.startLine === result.endLine
+        ? `line ${result.startLine}`
+        : `lines ${result.startLine}–${result.endLine}`;
+    function pushPatch(patch) {
+        const fence = safeFence(patch);
+        lines.push("");
+        lines.push(`${fence}diff`);
+        lines.push(patch.trimEnd());
+        lines.push(fence);
+    }
     if (result.dryRun) {
-        const range = result.startLine === result.endLine
-            ? `line ${result.startLine}`
-            : `lines ${result.startLine}-${result.endLine}`;
         if (result.valid) {
             lines.push(`Dry-run: would apply suggestion from @${result.author}:`);
             lines.push(`  ${result.path} (${range})`);
@@ -89,45 +84,32 @@ export function formatCommitSuggestionResult(result) {
             lines.push(`- author: @${result.author}`);
             lines.push(`- reason: ${result.reason ?? "unknown"}`);
         }
-        if (result.patch) {
-            lines.push("");
-            lines.push("```diff");
-            lines.push(result.patch.trimEnd());
-            lines.push("```");
-        }
+        if (result.patch)
+            pushPatch(result.patch);
     }
     else if (result.applied) {
         lines.push(`Applied suggestion from @${result.author}:`);
-        const range = result.startLine === result.endLine
-            ? `line ${result.startLine}`
-            : `lines ${result.startLine}-${result.endLine}`;
         lines.push(`  ${result.path} (${range})`);
         if (result.commitSha)
             lines.push(`Commit: ${result.commitSha}`);
-        if (result.patch) {
-            lines.push("");
-            lines.push("```diff");
-            lines.push(result.patch.trimEnd());
-            lines.push("```");
-        }
+        if (result.patch)
+            pushPatch(result.patch);
     }
     else {
         lines.push(`Failed to apply suggestion ${result.threadId}:`);
-        lines.push(`- path: ${result.path} (lines ${result.startLine}–${result.endLine})`);
+        lines.push(`- path: ${result.path} (${range})`);
         lines.push(`- author: @${result.author}`);
         lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        if (result.patch) {
-            lines.push("");
-            lines.push("```diff");
-            lines.push(result.patch.trimEnd());
-            lines.push("```");
-        }
+        if (result.patch)
+            pushPatch(result.patch);
     }
     if (result.postActionInstruction) {
         lines.push("");
-        lines.push(result.postActionInstruction);
+        lines.push("## Instructions");
+        lines.push("");
+        lines.push(`1. ${result.postActionInstruction}`);
     }
-    return `${lines.join("\n")}\n`;
+    return lines.join("\n");
 }
 export function formatMutateResult(result) {
     const lines = [];
@@ -139,5 +121,5 @@ export function formatMutateResult(result) {
         lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
     if (result.errors.length)
         lines.push(`Errors:\n  ${result.errors.join("\n  ")}`);
-    return `${lines.join("\n")}\n`;
+    return lines.join("\n");
 }

package/bin/cli/handlers.mjs

@@ -34,7 +34,7 @@ export async function handleCommitSuggestion(args) {
     });
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
-        : formatCommitSuggestionResult(result));
+        : `${formatCommitSuggestionResult(result)}\n`);
     if (result.dryRun) {
         process.exitCode = result.valid ? 0 : 1;
     }

package/bin/cli/iterate-formatter.mjs

@@ -1,4 +1,5 @@
 import { formatFixCodeResult } from "./fix-formatter.mjs";
+import { joinSections } from "../util/markdown.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
  *
@@ -48,51 +49,35 @@ export function formatIterateResult(result, opts) {
         case "cooldown":
             // In default mode: suppress base/summary lines — cooldown carries UNKNOWN/empty
             // placeholders that add no value. Emit only heading + log + Instructions.
-            return [
+            return joinSections([
                 verbose ? header : heading,
-                "",
                 result.log,
-                "",
-                "## Instructions",
-                "",
-                "1. End this iteration — the next cron fire will recheck once CI starts reporting.",
-            ].join("\n");
-        case "wait": {
-            const parts = [
+                "## Instructions\n\n1. End this iteration — the next cron fire will recheck once CI starts reporting.",
+            ]);
+        case "wait":
+            return joinSections([
                 header,
                 result.log,
-                "## Instructions",
-                "1. End this iteration — the next cron fire will recheck.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "mark_ready": {
-            const parts = [
+                "## Instructions\n\n1. End this iteration — the next cron fire will recheck.",
+            ]);
+        case "mark_ready":
+            return joinSections([
                 header,
                 result.log,
-                "## Instructions",
-                "1. The CLI already marked the PR ready for review — end this iteration.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "cancel": {
-            const parts = [
+                "## Instructions\n\n1. The CLI already marked the PR ready for review — end this iteration.",
+            ]);
+        case "cancel":
+            return joinSections([
                 [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
                 result.log,
-                "## Instructions",
-                "1. Invoke `/loop cancel` via the Skill tool.\n2. Stop.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "escalate": {
-            const parts = [
+                "## Instructions\n\n1. Invoke `/loop cancel` via the Skill tool.\n2. Stop.",
+            ]);
+        case "escalate":
+            return joinSections([
                 header,
                 result.escalate.humanMessage,
-                "## Instructions",
-                "1. Invoke `/loop cancel` via the Skill tool.\n2. Stop — the PR needs human direction before monitoring can resume.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
+                "## Instructions\n\n1. Invoke `/loop cancel` via the Skill tool.\n2. Stop — the PR needs human direction before monitoring can resume.",
+            ]);
         case "fix_code":
             return formatFixCodeResult(header, result);
     }

package/bin/cli/iterate-lean.mjs

@@ -49,9 +49,6 @@ export function projectIterateLean(result) {
                     ...(result.fix.actionableComments.length > 0 && {
                         actionableComments: result.fix.actionableComments,
                     }),
-                    ...(result.fix.noiseCommentIds.length > 0 && {
-                        noiseCommentIds: result.fix.noiseCommentIds,
-                    }),
                     ...(result.fix.reviewSummaryIds.length > 0 && {
                         reviewSummaryIds: result.fix.reviewSummaryIds,
                     }),

package/bin/cli/list-formatters.mjs

@@ -0,0 +1,32 @@
+import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
+const BODY_PREVIEW_MAX = 100;
+export function renderBodyPreview(body) {
+    const normalizedBody = body.replace(/\r\n?/g, "\n");
+    const firstLine = normalizedBody.split("\n")[0]?.trim() ?? "";
+    return firstLine.slice(0, BODY_PREVIEW_MAX);
+}
+export function renderFirstLookStatusTag(t) {
+    return t.autoResolved ? "[status: outdated, auto-resolved]" : `[status: ${t.firstLookStatus}]`;
+}
+export function renderThreadBullet(t, opts = {}) {
+    const link = t.url ? ` [↗](${t.url})` : "";
+    const loc = t.path
+        ? `\`${t.path}:${renderLineRange(t.startLine ?? undefined, t.line ?? null)}\``
+        : "`(no location)`";
+    const suggestionMarker = t.suggestion ? " [suggestion]" : "";
+    const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (@${t.author})${suggestionMarker}${statusSuffix}: ${renderBodyPreview(t.body)}`;
+    if (t.suggestion && opts.renderSuggestion) {
+        return `${bulletLine}\n${renderSuggestionBlock(t.suggestion)}`;
+    }
+    return bulletLine;
+}
+export function renderCommentBullet(c, opts = {}) {
+    const link = c.url ? ` [↗](${c.url})` : "";
+    const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
+    return `- \`commentId=${c.id}\`${link} (@${c.author})${statusSuffix}: ${renderBodyPreview(c.body)}`;
+}
+export function renderReviewBullet(r, opts = {}) {
+    const bodySuffix = opts.includeBody && r.body != null && r.body !== "" ? `: ${renderBodyPreview(r.body)}` : "";
+    return `- \`reviewId=${r.id}\` (@${r.author})${bodySuffix}`;
+}

package/bin/cli/suggestion-renderer.mjs

@@ -0,0 +1,31 @@
+import { safeFence } from "./fence.mjs";
+export function renderLineRange(startLine, endLine) {
+    if (endLine === null)
+        return "?";
+    if (startLine !== undefined && startLine !== endLine)
+        return `${startLine}-${endLine}`;
+    return String(endLine);
+}
+export function renderSuggestionBlock(s, indent = "  ") {
+    const rangeLabel = s.startLine !== s.endLine ? `lines ${s.startLine}–${s.endLine}` : `line ${s.startLine}`;
+    const content = s.lines.join("\n");
+    const fence = safeFence(content);
+    const label = s.lines.length === 0
+        ? `Replaces ${rangeLabel} with nothing:`
+        : s.lines.length === 1 && s.lines[0] === ""
+            ? `Replaces ${rangeLabel} with a blank line:`
+            : `Replaces ${rangeLabel}:`;
+    return [
+        `${indent}${label}`,
+        `${indent}${fence}`,
+        ...(content === ""
+            ? []
+            : [
+                content
+                    .split("\n")
+                    .map((l) => `${indent}${l}`)
+                    .join("\n"),
+            ]),
+        `${indent}${fence}`,
+    ].join("\n");
+}

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

@@ -29,7 +29,6 @@ export function makeIterateResult(action = "wait") {
                 mode: "rebase-and-push",
                 threads: [],
                 actionableComments: [],
-                noiseCommentIds: [],
                 reviewSummaryIds: [],
                 surfacedApprovals: [],
                 checks: [],
@@ -64,7 +63,7 @@ export function makeIterateResult(action = "wait") {
                 ambiguousComments: [],
                 changesRequestedReviews: [],
                 suggestion: "check manually",
-                humanMessage: "⚠️  /pr-shepherd:monitor paused — needs human direction",
+                humanMessage: "⚠️ /pr-shepherd:monitor paused — needs human direction",
             },
         };
     }

package/bin/cli-parser.mjs

@@ -18,12 +18,14 @@
 import { readFileSync } from "node:fs";
 import { runCheck } from "./commands/check.mjs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
+import { runLogFile } from "./commands/log-file.mjs";
 import { formatJson } from "./reporters/json.mjs";
 import { formatText } from "./reporters/text.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { statusToExitCode } from "./cli/exit-codes.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleCommitSuggestion, handleIterate, handleMonitor, handleStatus, } from "./cli/handlers.mjs";
+import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
@@ -34,6 +36,13 @@ export async function main(argv) {
         process.stdout.write(`${readVersion()}\n`);
         return;
     }
+    // log-file must run before the stdout tee and log init to avoid recursion.
+    if (subcommand === "log-file") {
+        await handleLogFile(args.slice(1));
+        return;
+    }
+    // Initialize the per-worktree log and install a stdout tee.
+    await setupLog(argv);
     switch (subcommand) {
         case "check":
             await handleCheck(args.slice(1));
@@ -55,7 +64,7 @@ export async function main(argv) {
             break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
-            process.stderr.write("Usage: pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status> [options]\n" +
+            process.stderr.write("Usage: pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status|log-file> [options]\n" +
                 "       pr-shepherd --version | -v\n");
             process.exitCode = 1;
             return;
@@ -76,6 +85,21 @@ async function handleCheck(args) {
     process.stdout.write(`${output}\n`);
     process.exitCode = statusToExitCode(report.status);
 }
+async function handleLogFile(args) {
+    const jsonOut = args.some((a) => a === "--format=json") ||
+        (() => {
+            const idx = args.indexOf("--format");
+            return idx !== -1 && args[idx + 1] === "json";
+        })();
+    try {
+        const result = await runLogFile();
+        process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${result.path}\n`);
+    }
+    catch (e) {
+        process.stderr.write(`pr-shepherd: log-file: ${String(e)}\n`);
+        process.exitCode = 1;
+    }
+}
 async function handleResolve(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
@@ -91,7 +115,7 @@ async function handleResolve(args) {
         const result = await runResolveFetch({ ...globalOpts, prNumber });
         process.stdout.write(globalOpts.format === "json"
             ? `${JSON.stringify(result, null, 2)}\n`
-            : formatFetchResult(result));
+            : `${formatFetchResult(result)}\n`);
     }
     else {
         const result = await runResolveMutate({
@@ -105,6 +129,6 @@ async function handleResolve(args) {
         });
         process.stdout.write(globalOpts.format === "json"
             ? `${JSON.stringify(result, null, 2)}\n`
-            : formatMutateResult(result));
+            : `${formatMutateResult(result)}\n`);
     }
 }

package/bin/commands/check.mjs

@@ -54,9 +54,8 @@ 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");
-    // Triage failures (fetch job info + log tails) — skipped when caller short-circuits early.
     const triaged = failing.length > 0 && !opts.skipTriage
-        ? await triageFailingChecks(failing, repo, config.checks.logTailLines)
+        ? await triageFailingChecks(failing, repo, config.checks.logTailLines, config.checks.logTailChars)
         : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     // Resolve threads and comments.