pr-shepherd 0.9.0 → 0.10.1

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

@@ -46,7 +46,6 @@ export async function runCheck(opts) {
             mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
         };
     }
-    // Classify checks.
     const classifiedChecks = classifyChecks(batchData.checks);
     const verdict = getCiVerdict(classifiedChecks);
     const passing = classifiedChecks.filter((c) => c.category === "passed");
@@ -54,12 +53,10 @@ export async function runCheck(opts) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
-    // 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.
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
     // Auto-resolve outdated threads.
@@ -97,10 +94,14 @@ export async function runCheck(opts) {
     const firstLookComments = minimizedCommentCandidates
         .filter((c) => !seenSet.has(c.id))
         .map((c) => ({ ...c, firstLookStatus: "minimized" }));
+    // Split review summaries into first-look (unseen — surface body) vs seen (minimize silently).
+    const firstLookSummaries = batchData.reviewSummaries.filter((r) => !seenSet.has(r.id));
+    const seenSummaries = batchData.reviewSummaries.filter((r) => seenSet.has(r.id));
     // 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)),
+        ...firstLookSummaries.map((r) => markSeen(stateKey, r.id)),
     ]);
     // Actionable: all active threads and all visible comments (no classification — LLM handles triage).
     const actionableThreads = activeThreads;
@@ -141,7 +142,8 @@ export async function runCheck(opts) {
             firstLook: firstLookComments,
         },
         changesRequestedReviews: batchData.changesRequestedReviews,
-        reviewSummaries: batchData.reviewSummaries,
+        reviewSummaries: seenSummaries,
+        firstLookSummaries,
         approvedReviews: batchData.approvedReviews,
     };
 }

package/bin/commands/commit-suggestion.mjs

@@ -3,7 +3,7 @@ import { readFile, writeFile, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
-import { getRepoInfo, getCurrentPrNumber, getPrHead, getCurrentBranch } from "../github/client.mjs";
+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";
@@ -25,19 +25,21 @@ export async function runCommitSuggestion(opts) {
     if (prNumber === null) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
-    const head = await getPrHead(prNumber, repo.owner, repo.name);
     const currentBranch = await getCurrentBranch();
-    if (currentBranch !== head.ref) {
-        throw new Error(`Current branch "${currentBranch}" does not match PR head branch "${head.ref}". ` +
-            `Check out "${head.ref}" before applying suggestions.`);
-    }
     const { stdout: localHeadOut } = await execFile("git", ["rev-parse", "HEAD"]);
     const localHeadSha = localHeadOut.trim();
-    if (localHeadSha !== head.sha) {
-        throw new Error(`Local HEAD ${localHeadSha} does not match PR head ${head.sha}. ` +
-            `Pull/rebase "${head.ref}" to the latest PR head and try again.`);
-    }
     const { data } = await fetchPrBatch(prNumber, repo);
+    if (!data.headRepoWithOwner) {
+        throw new Error(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`);
+    }
+    if (currentBranch !== data.headRefName) {
+        throw new Error(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
+            `Check out "${data.headRefName}" before applying suggestions.`);
+    }
+    if (localHeadSha !== data.headRefOid) {
+        throw new Error(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
+            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`);
+    }
     const thread = data.reviewThreads.find((t) => t.id === opts.threadId);
     if (!thread) {
         throw new Error(`Thread ${opts.threadId} not found on PR #${prNumber}.`);

package/bin/commands/iterate/classify.mjs

@@ -1,38 +1,15 @@
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
-    const minimizeIds = summaries.map((r) => r.id);
+    // Both first-look and seen summaries go into the minimize mutation; first-look bodies are
+    // rendered in the output so the agent sees them before the minimize happens.
+    const minimizeIds = [...summaries.firstLook, ...summaries.seen].map((r) => r.id);
     if (minimizeApprovals) {
         for (const r of approvals)
             minimizeIds.push(r.id);
-        return { minimizeIds, surfacedApprovals: [] };
+        return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: [] };
     }
-    return { minimizeIds, surfacedApprovals: approvals };
+    return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: approvals };
 }
-// Patterns that indicate a comment is bot-generated noise rather than actionable feedback.
-// Conservative: only match explicit known patterns to avoid accidentally suppressing real reviews.
-const NOISE_PATTERNS = [
-    /you have reached your daily quota/i,
-    /please wait up to \d+ hours?/i,
-    /rate[\s-]?limit(?:ed)?\s*[-—:]\s*try again/i,
-    /resuming (monitoring|watch|checking)/i,
-    /restarting (monitoring|watch)/i,
-];
-function isNoiseComment(comment) {
-    return NOISE_PATTERNS.some((p) => p.test(comment.body));
-}
-export function classifyComments(comments) {
-    const actionable = [];
-    const noiseIds = [];
-    for (const c of comments) {
-        if (isNoiseComment(c)) {
-            noiseIds.push(c.id);
-        }
-        else {
-            actionable.push(c);
-        }
-    }
-    return { actionable, noiseIds };
-}
-export function buildResolveCommand(threads, actionableComments, allCommentIds, reviews, checks, prNumber) {
+export function buildResolveCommand(threads, allCommentIds, reviews, checks, prNumber) {
     const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];
     if (threads.length > 0) {
         argv.push("--resolve-thread-ids", threads.map((t) => t.id).join(","));
@@ -45,9 +22,10 @@ export function buildResolveCommand(threads, actionableComments, allCommentIds,
         argv.push("--dismiss-review-ids", reviews.map((r) => r.id).join(","));
         argv.push("--message", "$DISMISS_MESSAGE");
     }
-    // A push happens when there is code to change — threads, actionable comments, CI checks, or reviews.
-    // Noise-only comment minimization skips commit/push, so requiresHeadSha must be false.
-    const requiresHeadSha = threads.length > 0 || actionableComments.length > 0 || checks.length > 0 || reviews.length > 0;
+    // A push is required when threads, CI failures, or changes-requested reviews are present — the
+    // CLI knows those imply code edits. Comments are surfaced for the agent to evaluate; the CLI
+    // cannot know whether a given comment will require a push, so comments are excluded here.
+    const requiresHeadSha = threads.length > 0 || checks.length > 0 || reviews.length > 0;
     // hasMutations = we appended at least one of --resolve-thread-ids,
     // --minimize-comment-ids, or --dismiss-review-ids. Returned explicitly
     // (rather than derived from argv.length) so callers don't couple to the

package/bin/commands/iterate/escalate.mjs

@@ -31,8 +31,8 @@ export function checkEscalateTriggers(actionableThreads, actionableComments, cha
 /**
  * Validate the base branch name from the GraphQL batch (`report.baseBranch`)
  * and fall back safely if it's missing/unsafe. The branch is interpolated into
- * shell commands by `buildRebaseShellScript` and `buildFixInstructions`, so we
- * reject anything outside `[A-Za-z0-9._/-]` to prevent shell injection.
+ * shell commands by `buildFixInstructions`, so we reject anything outside
+ * `[A-Za-z0-9._/-]` to prevent shell injection.
  */
 export function validateBaseBranch(raw) {
     const trimmed = raw.trim();
@@ -52,18 +52,9 @@ export function validateBaseBranch(raw) {
     }
     return { branch: trimmed, isFallback: false };
 }
-export function buildRebaseShellScript(baseBranch) {
-    return [
-        `if ! git diff --quiet || ! git diff --cached --quiet; then`,
-        `  echo "SKIP rebase: dirty worktree (uncommitted changes present)"`,
-        `  exit 1`,
-        `fi`,
-        `git fetch origin && git rebase origin/${baseBranch} && git push --force-with-lease`,
-    ].join("\n");
-}
 export function buildEscalateHumanMessage(escalate, pr) {
     const lines = [];
-    lines.push("⚠️  /pr-shepherd:monitor paused — needs human direction");
+    lines.push("⚠️ /pr-shepherd:monitor paused — needs human direction");
     lines.push("");
     lines.push(`**Triggers:** ${escalate.triggers.map((t) => `\`${t}\``).join(", ")}`);
     lines.push("");

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

@@ -1,12 +1,12 @@
 import { readFixAttempts, writeFixAttempts } from "../../state/fix-attempts.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
-import { classifyComments, buildResolveCommand } from "./classify.mjs";
+import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -48,16 +48,12 @@ export async function handleFixCode(ctx) {
     }
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
-    const { actionable: actionableComments, noiseIds: noiseCommentIds } = classifyComments(report.comments.actionable.map(toAgentComment));
+    const actionableComments = report.comments.actionable.map(toAgentComment);
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
-    const allCommentIds = [
-        ...actionableComments.map((c) => c.id),
-        ...noiseCommentIds,
-        ...reviewSummaryIds,
-    ];
-    const resolveCommand = buildResolveCommand(threads, actionableComments, allCommentIds, changesRequestedReviews, checks, prNumber);
+    const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
+    const resolveCommand = buildResolveCommand(threads, allCommentIds, changesRequestedReviews, checks, prNumber);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
@@ -77,7 +73,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);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -86,8 +82,8 @@ export async function handleFixCode(ctx) {
             mode: "rebase-and-push",
             threads,
             actionableComments,
-            noiseCommentIds,
             reviewSummaryIds,
+            firstLookSummaries,
             surfacedApprovals,
             checks,
             changesRequestedReviews,

package/bin/commands/iterate/index.mjs

@@ -91,7 +91,7 @@ export async function runIterate(opts) {
     }
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const { minimizeIds: reviewSummaryIds, surfacedApprovals } = classifyReviewSummaries(report.reviewSummaries, report.approvedReviews, config.iterate.minimizeApprovals);
+    const { minimizeIds: reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = classifyReviewSummaries({ firstLook: report.firstLookSummaries, seen: report.reviewSummaries }, report.approvedReviews, config.iterate.minimizeApprovals);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
@@ -110,6 +110,7 @@ export async function runIterate(opts) {
             repoOwner,
             repoName,
             reviewSummaryIds,
+            firstLookSummaries,
             surfacedApprovals,
         });
     }

package/bin/commands/iterate/render.mjs

@@ -1,22 +1,23 @@
 /**
- * Render a ResolveCommand as a single-line command string for the monitor loop
- * to print or execute. This is NOT a general-purpose POSIX escaper — it wraps
- * the two known placeholders ($DISMISS_MESSAGE, $HEAD_SHA) and any whitespace-
- * bearing arg in double quotes so multi-word values don't split across flags.
+ * Render a resolve command as a shell snippet for the narrow placeholder-based
+ * invocation used by iterate.
  *
- * Contract for callers substituting placeholders: replace the entire quoted
- * token (including the surrounding `"`) with a properly shell-quoted literal.
- * Do not splice raw text inside the existing quotes — the output would then
- * re-expand `$…` / `$(…)` / embedded `"` and break.
+ * This is not a general-purpose shell escaper. It only wraps
+ * `$DISMISS_MESSAGE` and whitespace-bearing `rc.argv` entries in double quotes
+ * so the surrounding command template can later substitute placeholder values.
+ *
+ * Callers must preserve that contract:
+ * - placeholder substitution must replace the entire quoted token (for example,
+ *   replace `"$DISMISS_MESSAGE"` as a whole, not text inside the quotes);
+ * - `rc.argv` must not contain `"`, `$`, `` ` ``, or `\`, because this helper
+ *   does not escape them and will throw if they are present;
+ * - `$HEAD_SHA` must not appear in `rc.argv`; when `requiresHeadSha` is set it
+ *   is appended separately below as the already-quoted token `"$HEAD_SHA"`.
  */
 export function renderResolveCommand(rc) {
-    // `$HEAD_SHA` is never in `rc.argv` — it is appended pre-quoted below when
-    // `requiresHeadSha`. Only `$DISMISS_MESSAGE` (or whitespace-bearing values)
-    // need quoting here.
     const needsQuoting = (arg) => {
         if (arg === "$DISMISS_MESSAGE")
             return true;
-        // Assert no characters that would break the naive escaper are present in arg
         if (/["$`\\]/.test(arg)) {
             throw new Error(`Unexpected character in argv arg that needsQuoting can't handle: ${JSON.stringify(arg)}`);
         }
@@ -28,16 +29,23 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = []) {
     const instructions = [];
+    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.`);
+    }
     if (threads.length > 0 || actionableComments.length > 0) {
-        instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.`);
+        const suggestionFallback = hasSuggestions
+            ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`commit-suggestion\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
+            : "";
+        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 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 shown in the fenced block when available (or run \`gh run view <runId> --log-failed\` if the block is absent) to decide what to do. If the logs show a transient runner or infrastructure failure (e.g. network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\` and stop this iteration — CI will re-run automatically. If the logs show a real test or build failure, apply a code fix.`);
+        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 (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.`);
@@ -65,8 +73,13 @@ export function buildFixInstructions(threads, actionableComments, checks, review
             instructions.push(`Rebase and push: \`git fetch origin && git rebase origin/${baseBranch} && git push --force-with-lease\`${captureHint}`);
         }
     }
-    // Only tell the agent to run `resolve:` if the command actually mutates
-    // GitHub state. A CONFLICTS-only flow has nothing to mutate on GitHub.
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    if (firstLookTotal > 0) {
+        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
+    }
+    if (firstLookSummaries.length > 0) {
+        instructions.push(`Review the bodies shown under \`## Review summaries (first look — to be minimized)\` — you are seeing these for the first time. Their IDs are already included in the \`resolve:\` command's \`--minimize-comment-ids\`; if any warrants a \`## Shepherd Journal\` entry, record it before running resolve.`);
+    }
     if (resolveCommand.hasMutations) {
         const substituteParts = [];
         if (resolveCommand.requiresHeadSha) {
@@ -81,10 +94,6 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (needsPush && cancelledCount > 0) {
         instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — the CLI cancelled those runs before your push, and your push has already triggered new runs with different IDs.`);
     }
-    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
-    if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
-    }
     if (resolveCommand.hasMutations) {
         instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.`);
     }

package/bin/commands/log-file.mjs

@@ -0,0 +1,7 @@
+import { getRepoInfo } from "../github/client.mjs";
+import { resolveLogPath } from "../log/log-file.mjs";
+export async function runLogFile() {
+    const { owner, name } = await getRepoInfo();
+    const path = await resolveLogPath({ owner, repo: name });
+    return { path };
+}

package/bin/commands/monitor.mjs

@@ -16,7 +16,12 @@ export async function runMonitor(opts) {
     if (!Number.isFinite(maxTurns) || maxTurns <= 0 || !Number.isInteger(maxTurns)) {
         throw new Error(`Invalid config: watch.maxTurns must be a positive integer, got ${JSON.stringify(maxTurns)}`);
     }
-    const loopTag = `# pr-shepherd-loop:pr=${prNumber}`;
+    // No space after `#` — `# text` is a CommonMark ATX heading; `#text` is not.
+    // Trailing `:` prevents substring false positives: without it, the dedup grep
+    // for pr=1 would match a cron prompt for pr=135. Both the CronList check in
+    // step 1 of formatMonitorResult's ## Instructions and the in-prompt Self-dedup
+    // block depend on this exact string — don't change the format.
+    const loopTag = `#pr-shepherd-loop:pr=${prNumber}:`;
     const loopPrompt = buildLoopPrompt(prNumber, loopTag, opts.readyDelaySuffix);
     const loopArgs = `${interval} --max-turns ${maxTurns} --expires ${expiresHours}h`;
     return { prNumber, loopTag, loopArgs, loopPrompt };
@@ -56,9 +61,7 @@ function validateReadyDelaySuffix(readyDelaySuffix) {
 }
 function buildLoopPrompt(prNumber, loopTag, readyDelaySuffix) {
     const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
-    const iterateCmd = validatedDelay
-        ? `npx pr-shepherd iterate ${prNumber} --no-cache --ready-delay ${validatedDelay}`
-        : `npx pr-shepherd iterate ${prNumber} --no-cache`;
+    const iterateCmd = `npx pr-shepherd iterate ${prNumber}${validatedDelay ? ` --ready-delay ${validatedDelay}` : ""}`;
     return [
         loopTag,
         "",

package/bin/commands/ready-delay.mjs

@@ -7,8 +7,8 @@
  */
 import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
 import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveStateBase } from "../state/base.mjs";
 /**
  * Update the ready-delay state machine and return the current decision.
  *
@@ -64,7 +64,7 @@ function readySincePath(pr, owner, repo) {
             throw new Error(`Invalid path segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const base = resolveStateBase();
     return join(base, `${owner}-${repo}`, String(pr), "ready-since.txt");
 }
 async function safeUnlink(path) {

package/bin/commands/resolve-instructions.mjs

@@ -28,10 +28,13 @@ export function buildFetchInstructions(prNumber, result) {
     }
     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.`);
-        instructions.push(`Commit changed files: \`git add <files>\` (not \`git add -A\`) \`&& git commit -m "<descriptive message>"\`. If the fixes alter the PR's scope or intent, run \`gh pr edit ${prNumber} --title "<new title>" --body "<new body>"\` to reflect them. Then rebase and push: \`BASE_BRANCH=$(gh pr view ${prNumber} --json baseRefName --jq .baseRefName) && git fetch origin && git rebase "origin/$BASE_BRANCH" && git push --force-with-lease\`. Cancel stale in-progress runs: \`BRANCH=$(git rev-parse --abbrev-ref HEAD) && gh run list --branch "$BRANCH" --status in_progress --json databaseId --jq '.[].databaseId' | xargs -I{} gh run cancel {}\`.`);
+        instructions.push(`Commit changed files: \`git add <files>\` (not \`git add -A\`) \`&& git commit -m "<descriptive message>"\`.`);
+        instructions.push(`Keep the PR title and description current: if the fixes alter the PR's scope or intent, run \`gh pr edit ${prNumber} --title "<new title>" --body "<new body>"\` to reflect them. Skip if the existing title/body still accurately describe the PR.`);
+        instructions.push(`Rebase and push: \`BASE_BRANCH=$(gh pr view ${prNumber} --json baseRefName --jq .baseRefName) && git fetch origin && git rebase "origin/$BASE_BRANCH" && git push --force-with-lease\`.`);
+        instructions.push(`Cancel stale in-progress runs: \`BRANCH=$(git rev-parse --abbrev-ref HEAD) && CURRENT_SHA=$(git rev-parse HEAD) && gh run list --branch "$BRANCH" --status in_progress --json databaseId,headSha --jq ".[] | select(.headSha != \\"$CURRENT_SHA\\") | .databaseId" | xargs -I{} gh run cancel {}\`.`);
     }
     const requireShaHint = hasCodeItems
-        ? ` Include \`--require-sha $(git rev-parse HEAD)\` only when the commit-and-push step above ran.`
+        ? ` Include \`--require-sha $(git rev-parse HEAD)\` only when the rebase-and-push step above ran.`
         : "";
     const dismissNote = changesRequestedReviews.length > 0
         ? ` For \`--dismiss-review-ids\`: \`--message\` is required with one specific sentence describing the fix or the reason for not acting (no boilerplate like "address review comments"); omit \`--message\` when not dismissing. Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`, never \`--dismiss-review-ids\`.`

package/bin/commands/resolve.mjs

@@ -3,7 +3,7 @@ import { fetchPrBatch } from "../github/batch.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
 import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mjs";
 import { loadConfig } from "../config/load.mjs";
-import { parseSuggestion } from "../suggestions/parse.mjs";
+import { extractSuggestion } from "../suggestions/extract.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";
 import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
 /**
@@ -80,25 +80,6 @@ export async function runResolveFetch(opts) {
     };
     return { ...result, instructions: buildFetchInstructions(prNumber, result) };
 }
-/**
- * Attach a parsed suggestion block to a thread if the comment body contains one
- * and the thread has a resolvable line anchor. Threads without `path`/`line`
- * (rare — usually file-level comments) can't accept a suggestion commit.
- */
-function extractSuggestion(thread) {
-    if (!thread.path || thread.line === null)
-        return null;
-    const parsed = parseSuggestion(thread.body);
-    if (!parsed)
-        return null;
-    const startLine = thread.startLine ?? thread.line;
-    return {
-        startLine,
-        endLine: thread.line,
-        lines: parsed.lines,
-        author: thread.author,
-    };
-}
 /**
  * Mutation mode: resolve/minimize/dismiss by ID.
  */

package/bin/commands/status.mjs

@@ -2,35 +2,46 @@
  * `shepherd status PR1 [PR2 PR3 …]`
  *
  * Fetches readiness status for one or more PRs and prints a table.
- * Uses a separate lightweight GraphQL query (MULTI_PR_STATUS_QUERY) per PR
- * rather than the heavy batch query, since we only need summary data.
+ * Issues a single GraphQL request with one alias per PR number rather than
+ * N separate requests, so the round-trip count is always 1 (plus optional
+ * per-PR pagination calls when a PR has > 100 review threads).
  *
  * Exit code: 0 if all PRs are READY, non-zero otherwise.
  */
 import { graphql, getRepoInfo } from "../github/client.mjs";
-import { MULTI_PR_STATUS_QUERY, MULTI_PR_STATUS_QUERY_WITH_CURSOR } from "../github/queries.mjs";
+import { MULTI_PR_STATUS_QUERY_WITH_CURSOR } from "../github/queries.mjs";
 export async function runStatus(opts) {
+    if (opts.prNumbers.length === 0)
+        return [];
     const repo = await getRepoInfo();
-    const summaries = await Promise.all(opts.prNumbers.map((pr) => fetchSummary(pr, repo.owner, repo.name)));
+    const doc = buildBatchStatusQuery(opts.prNumbers);
+    const result = await graphql(doc, {
+        owner: repo.owner,
+        repo: repo.name,
+    });
+    const summaries = await Promise.all(opts.prNumbers.map((pr) => {
+        const rawPr = result.data.repository[`pr_${pr}`];
+        if (!rawPr) {
+            throw new Error(`PR #${pr} not found in ${repo.owner}/${repo.name}`);
+        }
+        return paginateAndBuild(pr, rawPr, repo.owner, repo.name);
+    }));
     return summaries;
 }
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
-async function fetchSummary(pr, owner, repo) {
-    const result = await graphql(MULTI_PR_STATUS_QUERY, {
-        owner,
-        repo,
-        pr,
-    });
-    const p = result.data.repository.pullRequest;
-    if (!p) {
-        throw new Error(`PR #${pr} not found in ${owner}/${repo}`);
-    }
+function buildBatchStatusQuery(prNumbers) {
+    const uniquePrs = [...new Set(prNumbers.filter((n) => n > 0))];
+    const f = "number title state isDraft mergeStateStatus reviewDecision " +
+        "reviewThreads(last:100){totalCount pageInfo{hasPreviousPage startCursor} nodes{isResolved}} " +
+        "commits(last:1){nodes{commit{statusCheckRollup{state}}}}";
+    const aliases = uniquePrs.map((n) => `pr_${n}:pullRequest(number:${n}){${f}}`).join(" ");
+    return `query MultiPrStatusBatch($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){${aliases}}}`;
+}
+async function paginateAndBuild(pr, p, owner, repo) {
     let allNodes = p.reviewThreads.nodes;
-    // If the response was truncated, fetch additional pages to get the full count.
     if (p.reviewThreads.totalCount > p.reviewThreads.nodes.length) {
-        // Fetch additional pages backward until we have all threads.
         const MAX_THREAD_PAGES = 10;
         let pagesFetched = 0;
         const totalCount = p.reviewThreads.totalCount;
@@ -59,7 +70,6 @@ async function fetchSummary(pr, owner, repo) {
     }
     const unresolvedThreads = allNodes.filter((n) => !n.isResolved).length;
     const ciState = p.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null;
-    // If we still have fewer nodes than totalCount, report truncation.
     const threadsTruncated = p.reviewThreads.totalCount > allNodes.length;
     return {
         number: p.number,
@@ -77,17 +87,19 @@ async function fetchSummary(pr, owner, repo) {
 // Output helpers
 // ---------------------------------------------------------------------------
 export function formatStatusTable(summaries, repoFull) {
-    const lines = [`\n# ${repoFull} — PR status (${summaries.length})\n`];
-    for (const s of summaries) {
-        const verdict = deriveVerdict(s);
-        const ciLabel = s.ciState ?? "—";
-        const title = s.title.slice(0, 50);
-        const truncNote = s.threadsTruncated
-            ? " (threads truncated — run shepherd check for full count)"
-            : "";
-        lines.push(`PR #${String(s.number).padEnd(5)} ${title.padEnd(52)} ${verdict.padEnd(12)} ${ciLabel}${truncNote}`);
-    }
-    return lines.join("\n");
+    const heading = `# ${repoFull} — PR status (${summaries.length})`;
+    if (summaries.length === 0)
+        return heading;
+    const rows = summaries.map((s) => {
+        const raw = s.title.length > 50 ? `${s.title.slice(0, 47)}...` : s.title;
+        const title = raw.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, " ");
+        return `| #${s.number} | ${title} | ${deriveVerdict(s)} | ${s.ciState ?? "—"} |`;
+    });
+    const table = ["| PR | Title | Verdict | CI |", "| --- | --- | --- | --- |", ...rows].join("\n");
+    const footnotes = summaries
+        .filter((s) => s.threadsTruncated)
+        .map((s) => `> Note: PR #${s.number} threads truncated — run \`pr-shepherd check ${s.number}\` for full count.`);
+    return [heading, table, ...footnotes].join("\n\n");
 }
 export function deriveVerdict(s) {
     if (s.state === "MERGED")