pr-shepherd 0.8.0 → 0.9.0

package/bin/commands/resolve.mjs

@@ -1,18 +1,3 @@
-/**
- * `shepherd resolve [PR] [flags]`
- *
- * Two modes:
- *
- *   Fetch mode (--fetch or no mutation flags):
- *     Auto-resolves outdated threads and returns all active threads,
- *     visible comments, and CHANGES_REQUESTED reviews for LLM triage.
- *     Sonnet reads this output, applies code fixes, pushes, then calls
- *     resolve in mutation mode to resolve/minimize/dismiss by ID.
- *
- *   Mutation mode (--resolve-thread-ids, --minimize-comment-ids, --dismiss-review-ids):
- *     Resolves/minimizes/dismisses by ID. Optionally verifies the push
- *     has landed on GitHub before mutating (--require-sha).
- */
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
@@ -20,6 +5,7 @@ import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mj
 import { loadConfig } from "../config/load.mjs";
 import { parseSuggestion } from "../suggestions/parse.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";
+import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
 /**
  * Fetch mode: auto-resolve outdated threads and return all active items for LLM triage.
  */
@@ -31,12 +17,26 @@ export async function runResolveFetch(opts) {
     }
     // Always bypass cache for resolve — we need fresh data before mutating.
     const { data } = await fetchPrBatch(prNumber, repo);
+    const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = data.comments.filter((c) => !c.isMinimized);
-    // Auto-resolve outdated.
+    // First-look: collect items that would normally be hidden and check seen markers.
+    const outdatedCandidates = data.reviewThreads.filter((t) => t.isOutdated);
+    const resolvedCandidates = data.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
+    const minimizedThreadCandidates = data.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
+    const minimizedCommentCandidates = data.comments.filter((c) => c.isMinimized);
+    const seenSet = await loadSeenSet(stateKey);
+    const unseenOutdated = outdatedCandidates.filter((t) => !seenSet.has(t.id));
+    const unseenResolved = resolvedCandidates.filter((t) => !seenSet.has(t.id));
+    const unseenMinimizedThreads = minimizedThreadCandidates.filter((t) => !seenSet.has(t.id));
+    const unseenMinimizedComments = minimizedCommentCandidates.filter((c) => !seenSet.has(c.id));
+    // Auto-resolve outdated (same as before — fires regardless of first-look status).
     const outdated = getOutdatedThreads(unresolvedThreads);
+    const autoResolvedIds = new Set();
     if (outdated.length > 0) {
-        const { errors } = await autoResolveOutdated(outdated.map((t) => t.id));
+        const { resolved: resolvedIds, errors } = await autoResolveOutdated(outdated.map((t) => t.id));
+        for (const id of resolvedIds)
+            autoResolvedIds.add(id);
         if (errors.length > 0) {
             process.stderr.write(`pr-shepherd: auto-resolve outdated threads failed (continuing): ${errors.join(", ")}\n`);
         }
@@ -50,10 +50,30 @@ export async function runResolveFetch(opts) {
             thread.suggestion = suggestion;
         return thread;
     });
+    const firstLookThreads = [
+        ...unseenOutdated.map((t) => ({
+            ...t,
+            firstLookStatus: "outdated",
+            autoResolved: autoResolvedIds.has(t.id),
+        })),
+        ...unseenResolved.map((t) => ({ ...t, firstLookStatus: "resolved" })),
+        ...unseenMinimizedThreads.map((t) => ({ ...t, firstLookStatus: "minimized" })),
+    ];
+    const firstLookComments = unseenMinimizedComments.map((c) => ({
+        ...c,
+        firstLookStatus: "minimized",
+    }));
+    // Mark first-look items as seen (best-effort — markSeen never throws).
+    await Promise.allSettled([
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
+        ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
+    ]);
     const result = {
         prNumber,
         actionableThreads,
+        firstLookThreads,
         actionableComments: visibleComments,
+        firstLookComments,
         changesRequestedReviews: data.changesRequestedReviews,
         reviewSummaries: cfg.resolve.fetchReviewSummaries ? data.reviewSummaries : [],
         commitSuggestionsEnabled: cfg.actions.commitSuggestions,

package/bin/commands/status.mjs

@@ -102,7 +102,7 @@ export function deriveVerdict(s) {
         s.reviewDecision !== "CHANGES_REQUESTED") {
         return "READY";
     }
-    if (s.mergeStateStatus === "BLOCKED")
+    if (s.mergeStateStatus === "BLOCKED" || s.mergeStateStatus === "HAS_HOOKS")
         return "BLOCKED";
     if (s.mergeStateStatus === "DIRTY")
         return "CONFLICTS";

package/bin/config.json

@@ -3,11 +3,7 @@
     "cooldownSeconds": 30,
     "fixAttemptsPerThread": 3,
     "stallTimeoutMinutes": 30,
-    "minimizeReviewSummaries": {
-      "bots": true,
-      "humans": true,
-      "approvals": false
-    }
+    "minimizeApprovals": false
   },
   "watch": {
     "interval": "4m",
@@ -24,7 +20,8 @@
     "fetchReviewSummaries": true
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"]
+    "ciTriggerEvents": ["pull_request", "pull_request_target"],
+    "logTailLines": 200
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]

package/bin/github/batch-parsers.mjs

@@ -19,6 +19,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             startLine: comment?.startLine ?? null,
             author: comment?.author?.login ?? "unknown",
             body: comment?.body ?? "",
+            url: comment?.url ?? "",
             createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
         };
     });
@@ -27,6 +28,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         isMinimized: c.isMinimized,
         author: c.author?.login ?? "unknown",
         body: c.body,
+        url: c.url,
         createdAtUnix: parseCreatedAt(c.createdAt),
     }));
     const changesRequestedReviews = rawReviewNodes.map((r) => ({

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

@@ -58,6 +58,7 @@ query BatchPr(
             nodes {
               id
               isMinimized
+              url
               author {
                 login
               }
@@ -78,6 +79,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          url
           author {
             login
           }

package/bin/reporters/agent.mjs

@@ -8,38 +8,33 @@
  * The original domain types are preserved for check command output.
  */
 export function toAgentThread(t) {
-    return { id: t.id, path: t.path, line: t.line, author: t.author, body: t.body };
+    return { id: t.id, path: t.path, line: t.line, author: t.author, body: t.body, url: t.url };
 }
 export function toAgentComment(c) {
-    return { id: c.id, author: c.author, body: c.body };
+    return { id: c.id, author: c.author, body: c.body, url: c.url };
 }
 export function toAgentCheck(c) {
     return {
         name: c.name,
         runId: c.runId,
         detailsUrl: c.detailsUrl,
-        failureKind: c.failureKind,
         ...(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 }),
     };
 }
 /**
- * Project and deduplicate checks so the agent makes one `gh run view` call
- * per run (dedup by runId) and skips duplicate external status checks (dedup
- * by name when runId is null).
+ * Project failing checks for the agent. Deduplicates only null-runId external
+ * checks by name — when runId is present each check may have a distinct job and
+ * log tail, so they are all kept.
  */
 export function toAgentChecks(checks) {
-    const seenRunIds = new Set();
     const seenNames = new Set();
     const result = [];
     for (const c of checks) {
-        if (c.runId !== null) {
-            if (seenRunIds.has(c.runId))
-                continue;
-            seenRunIds.add(c.runId);
-        }
-        else {
+        if (c.runId === null) {
             if (seenNames.has(c.name))
                 continue;
             seenNames.add(c.name);

package/bin/reporters/check-instructions.mjs

@@ -26,20 +26,15 @@ export function buildCheckInstructions(report) {
     }
     // 3. CI budget policy — one instruction per failing check
     for (const c of checks.failing) {
-        if (c.failureKind === "actionable") {
-            const diagnosisHint = c.failedStep
-                ? `the failure was in step \`${c.failedStep}\` — fetch the run log with \`gh run view ${c.runId ?? "<runId>"} --log-failed\` to diagnose`
-                : c.runId
-                    ? `fetch the run log with \`gh run view ${c.runId} --log-failed\` to diagnose the failure`
-                    : `open the check details (${c.detailsUrl}) to diagnose the failure`;
-            instructions.push(`Fix code failure: \`${c.name}\` (actionable) — ${diagnosisHint} and apply a fix.`);
-        }
-        else if (c.failureKind === "cancelled" || c.failureKind === "timeout") {
-            const rerunCmd = c.runId
-                ? `gh run rerun ${c.runId} --failed`
-                : `gh run rerun <runId> --failed`;
-            instructions.push(`Re-run transient failure: \`${c.name}\` [${c.failureKind}] — run \`${rerunCmd}\`.`);
-        }
+        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`
+                : `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`
+                : `no run or details URL available — escalate to a human`;
+        instructions.push(`Failing check: \`${c.name}\` — ${diagnosisHint}.`);
     }
     // 4. Ready-to-merge gate
     const isClean = mergeStatus.mergeStateStatus === "CLEAN";

package/bin/reporters/text.mjs

@@ -1,12 +1,10 @@
 import { buildCheckInstructions } from "./check-instructions.mjs";
 export function formatText(report) {
     const parts = [];
-    // Header — scan-friendly status lines for quick at-a-glance review
     parts.push(`\nPR #${report.pr} — ${report.repo}`);
     parts.push(`Status: ${report.status}`);
     parts.push(`Base: ${report.baseBranch}`);
     parts.push("");
-    // Merge status
     const ms = report.mergeStatus;
     parts.push("## Merge Status");
     parts.push("");
@@ -17,7 +15,6 @@ export function formatText(report) {
     parts.push(`  isDraft:                 ${ms.isDraft}`);
     parts.push(`  copilotReviewInProgress: ${ms.copilotReviewInProgress}`);
     parts.push("");
-    // CI checks
     const { passing, failing, inProgress, skipped } = report.checks;
     const total = passing.length + failing.length + inProgress.length + skipped.length;
     parts.push("## CI Checks");
@@ -63,8 +60,7 @@ export function formatText(report) {
         }
         parts.push("");
     }
-    // Review threads
-    const { actionable: actionableThreads, autoResolved, autoResolveErrors } = report.threads;
+    const { actionable: actionableThreads, autoResolved, autoResolveErrors, firstLook: firstLookThreads, } = report.threads;
     const hasThreadSection = autoResolved.length > 0 || autoResolveErrors.length > 0 || actionableThreads.length > 0;
     if (hasThreadSection) {
         parts.push("## Review Threads");
@@ -94,8 +90,7 @@ export function formatText(report) {
             parts.push("");
         }
     }
-    // PR comments
-    const { actionable: actionableComments } = report.comments;
+    const { actionable: actionableComments, firstLook: firstLookComments } = report.comments;
     if (actionableComments.length > 0) {
         parts.push("## PR Comments");
         parts.push("");
@@ -106,7 +101,6 @@ export function formatText(report) {
         }
         parts.push("");
     }
-    // CHANGES_REQUESTED reviews
     if (report.changesRequestedReviews.length > 0) {
         parts.push("## CHANGES_REQUESTED Reviews");
         parts.push("");
@@ -115,7 +109,6 @@ export function formatText(report) {
         }
         parts.push("");
     }
-    // Review summaries
     if (report.reviewSummaries.length > 0) {
         parts.push("## Review Summaries");
         parts.push("");
@@ -124,7 +117,6 @@ export function formatText(report) {
         }
         parts.push("");
     }
-    // Approved reviews
     if (report.approvedReviews.length > 0) {
         parts.push("## Approved Reviews");
         parts.push("");
@@ -133,15 +125,35 @@ export function formatText(report) {
         }
         parts.push("");
     }
-    // Summary
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    if (firstLookTotal > 0) {
+        parts.push("## First-look items");
+        parts.push("");
+        for (const t of firstLookThreads) {
+            const statusTag = t.autoResolved
+                ? `[status: outdated, auto-resolved]`
+                : `[status: ${t.firstLookStatus}]`;
+            const loc = t.path ? `${t.path}:${t.line ?? "?"}` : "(no location)";
+            parts.push(`- threadId=${t.id} ${loc} (@${t.author}) ${statusTag}`);
+            parts.push(`  ${firstLine(t.body)}`);
+        }
+        for (const c of firstLookComments) {
+            parts.push(`- commentId=${c.id} (@${c.author}) [status: minimized]`);
+            parts.push(`  ${firstLine(c.body)}`);
+        }
+        parts.push("");
+    }
     const totalActionable = actionableThreads.length + actionableComments.length + report.changesRequestedReviews.length;
     parts.push("## Summary");
     parts.push("");
-    parts.push(totalActionable === 0
-        ? "0 actionable — all threads resolved/minimized"
-        : `${totalActionable} actionable item(s) remaining`);
+    const counts = [];
+    if (totalActionable > 0)
+        counts.push(`${totalActionable} actionable`);
+    if (firstLookTotal > 0)
+        counts.push(`${firstLookTotal} first-look`);
+    const summaryLine = counts.join(", ") || "0 actionable — all threads resolved/minimized";
+    parts.push(summaryLine);
     parts.push("");
-    // Instructions
     parts.push("## Instructions");
     parts.push("");
     const instructions = buildCheckInstructions(report);
@@ -150,9 +162,6 @@ export function formatText(report) {
     });
     return parts.join("\n");
 }
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
 function firstLine(text) {
     return (text.split("\n")[0] ?? "").trim().slice(0, 120);
 }

package/bin/state/seen-comments.mjs

@@ -0,0 +1,76 @@
+import { readFile, writeFile, mkdir, access, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read the seen/ directory once and return a Set of already-seen IDs.
+ * Prefer this over repeated hasSeen() calls to avoid EMFILE on large PRs.
+ * Returns an empty Set if the directory does not yet exist.
+ */
+export async function loadSeenSet(key) {
+    try {
+        const dir = resolveDir(key);
+        const entries = await readdir(dir);
+        return new Set(entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5)));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Return true if a "seen" marker exists for this id. */
+export async function hasSeen(key, id) {
+    try {
+        await access(resolvePath(key, id));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write a "seen" marker for this id. Idempotent — preserves original seenAt on double-write. */
+export async function markSeen(key, id) {
+    try {
+        const path = resolvePath(key, id);
+        await mkdir(dirname(path), { recursive: true });
+        // O_EXCL: create-only — EEXIST means already marked, which is the idempotent success case.
+        // seenAt is unix milliseconds (Date.now()), matching JS convention for this module.
+        await writeFile(path, JSON.stringify({ seenAt: Date.now() }), { flag: "wx", encoding: "utf8" });
+    }
+    catch {
+        // EEXIST = already seen. All other errors are best-effort.
+    }
+}
+/** Read the full marker for inspection (returns null on miss or error). */
+export async function readSeenMarker(key, id) {
+    try {
+        const raw = await readFile(resolvePath(key, id), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveDir(key) {
+    for (const [field, value] of [
+        ["owner", key.owner],
+        ["repo", key.repo],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid state key segment "${field}": ${value}`);
+        }
+    }
+    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "seen");
+}
+function resolvePath(key, id) {
+    if (!SAFE_SEGMENT.test(id)) {
+        throw new Error(`Invalid state key segment "id": ${id}`);
+    }
+    return join(resolveDir(key), `${id}.json`);
+}

package/bin/types/report.mjs

@@ -1,2 +1 @@
-// Shepherd-specific report types, agent projections, and CLI options.
 export {};

package/package.json

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

package/bin/commands/iterate/steps.mjs

@@ -1,31 +0,0 @@
-import { applyStallGuard } from "./stall.mjs";
-export async function buildRerunCiResult(transientChecks, base, prNumber, stallKey, stallTimeoutSeconds, headSha, report, reviewSummaryIds) {
-    const runMap = new Map();
-    for (const c of transientChecks) {
-        if (c.runId === null)
-            continue;
-        const existing = runMap.get(c.runId);
-        if (existing) {
-            existing.checkNames.push(c.name);
-        }
-        else {
-            runMap.set(c.runId, {
-                runId: c.runId,
-                checkNames: [c.name],
-                failureKind: c.failureKind,
-                workflowName: c.workflowName,
-            });
-        }
-    }
-    const reran = [...runMap.values()];
-    const runSummaries = reran.map(({ runId, checkNames, failureKind, workflowName }) => {
-        const prefix = workflowName ? `${workflowName} › ` : "";
-        return `${runId} (${prefix}${checkNames.join(", ")} — ${failureKind})`;
-    });
-    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
-        ...base,
-        action: "rerun_ci",
-        reran,
-        log: `RERUN NEEDED — ${reran.length} CI run${reran.length === 1 ? "" : "s"}: ${runSummaries.join(", ")}`,
-    }, report, reviewSummaryIds);
-}