pr-shepherd 0.7.0 → 0.8.0

package/bin/cli-parser.mjs

@@ -0,0 +1,110 @@
+/**
+ * CLI argument parsing and subcommand dispatch for pr-shepherd.
+ *
+ * Usage:
+ *   pr-shepherd --version
+ *   pr-shepherd check [PR] [--format text|json]
+ *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
+ *                            [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]
+ *   pr-shepherd commit-suggestion [PR] --thread-id ID [--message MSG] [--description DESC]
+ *                                      [--dry-run] [--format text|json]
+ *   (--message is required unless --dry-run is set)
+ *   pr-shepherd iterate [PR] [--format text|json] [--cooldown-seconds N] [--ready-delay Nm]
+ *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
+ *                              [--no-auto-cancel-actionable]
+ *   pr-shepherd monitor [PR] [--format text|json]
+ *   pr-shepherd status PR1 [PR2 …]
+ */
+import { readFileSync } from "node:fs";
+import { runCheck } from "./commands/check.mjs";
+import { runResolveFetch, runResolveMutate } from "./commands/resolve.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";
+// ---------------------------------------------------------------------------
+// Entry
+// ---------------------------------------------------------------------------
+export async function main(argv) {
+    const args = argv.slice(2); // strip node + script path
+    const subcommand = args[0];
+    if (subcommand === "--version" || subcommand === "-v") {
+        process.stdout.write(`${readVersion()}\n`);
+        return;
+    }
+    switch (subcommand) {
+        case "check":
+            await handleCheck(args.slice(1));
+            break;
+        case "resolve":
+            await handleResolve(args.slice(1));
+            break;
+        case "commit-suggestion":
+            await handleCommitSuggestion(args.slice(1));
+            break;
+        case "iterate":
+            await handleIterate(args.slice(1));
+            break;
+        case "monitor":
+            await handleMonitor(args.slice(1));
+            break;
+        case "status":
+            await handleStatus(args.slice(1));
+            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" +
+                "       pr-shepherd --version | -v\n");
+            process.exitCode = 1;
+            return;
+    }
+}
+function readVersion() {
+    const pkgUrl = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+    return pkg.version;
+}
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+async function handleCheck(args) {
+    const { prNumber, global: globalOpts } = parseCommonArgs(args);
+    const report = await runCheck({ ...globalOpts, prNumber, autoResolve: false });
+    const output = globalOpts.format === "json" ? formatJson(report) : formatText(report);
+    process.stdout.write(`${output}\n`);
+    process.exitCode = statusToExitCode(report.status);
+}
+async function handleResolve(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
+    const minimizeCommentIds = parseList(getFlag(extra, "--minimize-comment-ids"));
+    const dismissReviewIds = parseList(getFlag(extra, "--dismiss-review-ids"));
+    const dismissMessage = getFlag(extra, "--message") ?? undefined;
+    const requireSha = getFlag(extra, "--require-sha") ?? undefined;
+    const fetchMode = hasFlag(extra, "--fetch") ||
+        (resolveThreadIds.length === 0 &&
+            minimizeCommentIds.length === 0 &&
+            dismissReviewIds.length === 0);
+    if (fetchMode) {
+        const result = await runResolveFetch({ ...globalOpts, prNumber });
+        process.stdout.write(globalOpts.format === "json"
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatFetchResult(result));
+    }
+    else {
+        const result = await runResolveMutate({
+            ...globalOpts,
+            prNumber,
+            resolveThreadIds,
+            minimizeCommentIds,
+            dismissReviewIds,
+            dismissMessage,
+            requireSha,
+        });
+        process.stdout.write(globalOpts.format === "json"
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatMutateResult(result));
+    }
+}

package/bin/commands/check-status.mjs

@@ -0,0 +1,35 @@
+export function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews) {
+    // Merge conflicts are always terminal regardless of CI state.
+    if (mergeStatus.status === "CONFLICTS")
+        return "FAILING";
+    // Check CI state before merge-blocking states: BLOCKED/UNSTABLE/BEHIND are
+    // often caused by CI not having passed yet, so they shouldn't mask IN_PROGRESS.
+    // These merge-blocking states become PENDING (not FAILING) once CI is resolved.
+    if (verdict.anyFailing)
+        return "FAILING";
+    if (verdict.anyInProgress)
+        return "IN_PROGRESS";
+    // BLOCKED solely because a human reviewer hasn't approved yet — shepherd is done, hand off.
+    // copilotReviewInProgress means a bot still owes a review, which is not this case.
+    if (verdict.allPassed &&
+        unresolvedThreads === 0 &&
+        unresolvedComments === 0 &&
+        changesRequestedReviews === 0 &&
+        mergeStatus.status === "BLOCKED" &&
+        !mergeStatus.copilotReviewInProgress &&
+        mergeStatus.reviewDecision === "REVIEW_REQUIRED") {
+        return "READY";
+    }
+    if (mergeStatus.status === "BLOCKED" ||
+        mergeStatus.status === "UNSTABLE" ||
+        mergeStatus.status === "BEHIND")
+        return "PENDING";
+    if (mergeStatus.status === "UNKNOWN")
+        return "UNKNOWN";
+    if (changesRequestedReviews > 0 || unresolvedThreads > 0 || unresolvedComments > 0)
+        return "UNRESOLVED_COMMENTS";
+    // DRAFT is treated the same as CLEAN for readiness — marking the PR ready resolves it.
+    if ((mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT") && verdict.allPassed)
+        return "READY";
+    return "UNKNOWN";
+}

package/bin/commands/check.mjs

@@ -14,43 +14,35 @@
  */
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
-import { cacheGet, cacheSet } from "../cache/file-cache.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { triageFailingChecks } from "../checks/triage.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
 import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { computeStatus } from "./check-status.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
-    const cacheKey = { owner: repo.owner, repo: repo.name, pr: prNumber, shape: "check" };
-    // When autoResolve is enabled the command will mutate (resolve threads, minimize
-    // comments) — always bypass cache so we act on fresh data, not a stale snapshot.
-    const cacheOpts = {
-        disabled: opts.noCache || opts.autoResolve,
-        ttlSeconds: opts.cacheTtlSeconds,
-    };
-    // Try cache first.
-    let batchData = await cacheGet(cacheKey, cacheOpts);
-    if (batchData === null) {
-        const result = await fetchPrBatch(prNumber, repo);
-        batchData = result.data;
-        // Don't cache UNKNOWN merge state — it's transient and would poison the
-        // cache for the full TTL window, causing stale UNKNOWN on the next sweep.
-        if (batchData.mergeable !== "UNKNOWN" && batchData.mergeStateStatus !== "UNKNOWN") {
-            await cacheSet(cacheKey, batchData, cacheOpts);
-        }
-    }
+    // Only paginate APPROVED reviews when the caller will actually minimize them.
+    // Otherwise the first-page cap of 50 (already in the batch) is plenty — no extra round-trip.
+    const paginateApprovedReviews = loadConfig().iterate.minimizeReviewSummaries.approvals;
+    const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
+    let batchData = result.data;
     // GraphQL sometimes returns UNKNOWN for mergeable/mergeStateStatus while the
     // REST API already has the correct value. Fall back to REST in that case.
     // Skip for non-OPEN PRs — REST also returns UNKNOWN for merged/closed PRs.
     if ((batchData.state ?? "OPEN") === "OPEN" &&
         (batchData.mergeable === "UNKNOWN" || batchData.mergeStateStatus === "UNKNOWN")) {
         const restState = await getMergeableState(prNumber, repo.owner, repo.name);
-        batchData = { ...batchData, ...restState };
+        batchData = {
+            ...batchData,
+            mergeable: restState.mergeable ?? batchData.mergeable,
+            mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
+        };
     }
     // Classify checks.
     const classifiedChecks = classifyChecks(batchData.checks);
@@ -112,46 +104,7 @@ export async function runCheck(opts) {
             actionable: actionableComments,
         },
         changesRequestedReviews: batchData.changesRequestedReviews,
-        lastPushTime: opts.lastPushTime,
+        reviewSummaries: batchData.reviewSummaries,
+        approvedReviews: batchData.approvedReviews,
     };
 }
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews) {
-    // Merge conflicts are always terminal regardless of CI state.
-    if (mergeStatus.status === "CONFLICTS")
-        return "FAILING";
-    // Check CI state before merge-blocking states: BLOCKED/UNSTABLE/BEHIND are
-    // often caused by CI not having passed yet, so they shouldn't mask IN_PROGRESS.
-    // These merge-blocking states become PENDING (not FAILING) once CI is resolved.
-    if (verdict.anyFailing)
-        return "FAILING";
-    if (verdict.anyInProgress)
-        return "IN_PROGRESS";
-    // BLOCKED solely because a human reviewer hasn't approved yet — shepherd is done, hand off.
-    // copilotReviewInProgress means a bot still owes a review, which is not this case.
-    if (verdict.allPassed &&
-        unresolvedThreads === 0 &&
-        unresolvedComments === 0 &&
-        changesRequestedReviews === 0 &&
-        mergeStatus.status === "BLOCKED" &&
-        !mergeStatus.copilotReviewInProgress &&
-        mergeStatus.reviewDecision === "REVIEW_REQUIRED") {
-        return "READY";
-    }
-    if (mergeStatus.status === "BLOCKED" ||
-        mergeStatus.status === "UNSTABLE" ||
-        mergeStatus.status === "BEHIND")
-        return "PENDING";
-    if (mergeStatus.status === "UNKNOWN")
-        return "UNKNOWN";
-    if (changesRequestedReviews > 0)
-        return "UNRESOLVED_COMMENTS";
-    if (unresolvedThreads > 0 || unresolvedComments > 0)
-        return "UNRESOLVED_COMMENTS";
-    // DRAFT is treated the same as CLEAN for readiness — marking the PR ready resolves it.
-    if ((mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT") && verdict.allPassed)
-        return "READY";
-    return "UNKNOWN";
-}

package/bin/commands/commit-suggestion.mjs

@@ -0,0 +1,159 @@
+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 { promisify } from "node:util";
+import { getRepoInfo, getCurrentPrNumber, getPrHead, 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);
+export async function runCommitSuggestion(opts) {
+    if (!opts.threadId) {
+        throw new Error("--thread-id is required");
+    }
+    if (!opts.dryRun && (!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) {
+        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);
+    const thread = data.reviewThreads.find((t) => t.id === opts.threadId);
+    if (!thread) {
+        throw new Error(`Thread ${opts.threadId} not found on PR #${prNumber}.`);
+    }
+    if (thread.isResolved) {
+        throw new Error(`Thread ${opts.threadId} is already resolved.`);
+    }
+    if (thread.isOutdated) {
+        throw new Error(`Thread ${opts.threadId} is outdated.`);
+    }
+    if (thread.isMinimized) {
+        throw new Error(`Thread ${opts.threadId} is minimized.`);
+    }
+    if (!thread.path || thread.line === null) {
+        throw new Error(`Thread ${opts.threadId} has no file/line anchor.`);
+    }
+    const parsed = parseSuggestion(thread.body);
+    if (!parsed) {
+        throw new Error(`Thread ${opts.threadId} has no suggestion block in the comment body.`);
+    }
+    if (!isCommittableSuggestion(parsed)) {
+        throw new Error(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
+            `3+ backtick fences — refusing to apply (could silently truncate).`);
+    }
+    const startLine = thread.startLine ?? thread.line;
+    const endLine = thread.line;
+    const filePath = thread.path;
+    const originalContent = await readFile(filePath, "utf8");
+    const patch = buildUnifiedDiff({
+        path: filePath,
+        originalContent,
+        startLine,
+        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;
+    return {
+        pr: prNumber,
+        repo: `${repo.owner}/${repo.name}`,
+        threadId: opts.threadId,
+        path: filePath,
+        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.",
+    };
+}

package/bin/commands/iterate/classify.mjs

@@ -0,0 +1,77 @@
+// Logins treated as bot authors regardless of the GitHub Bot/User user type.
+// Mirrors plugin/skills/resolve/SKILL.md §3 — kept in sync with the resolve triage guidance.
+const KNOWN_BOT_LOGINS = new Set([
+    "copilot-pull-request-reviewer",
+    "gemini-code-assist",
+    "coderabbitai",
+]);
+function isBotAuthor(login) {
+    const bare = login.replace(/\[bot\]$/, "");
+    if (bare !== login)
+        return true;
+    return KNOWN_BOT_LOGINS.has(bare);
+}
+export function classifyReviewSummaries(summaries, approvals, cfg) {
+    const minimizeIds = [];
+    const surfacedSummaries = [];
+    for (const r of summaries) {
+        const enabled = isBotAuthor(r.author) ? cfg.bots : cfg.humans;
+        if (enabled)
+            minimizeIds.push(r.id);
+        else
+            surfacedSummaries.push(r);
+    }
+    if (cfg.approvals) {
+        for (const r of approvals)
+            minimizeIds.push(r.id);
+    }
+    return { minimizeIds, surfacedSummaries };
+}
+// 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) {
+    const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];
+    if (threads.length > 0) {
+        argv.push("--resolve-thread-ids", threads.map((t) => t.id).join(","));
+    }
+    if (allCommentIds.length > 0) {
+        argv.push("--minimize-comment-ids", allCommentIds.join(","));
+    }
+    const hasDismiss = reviews.length > 0;
+    if (hasDismiss) {
+        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;
+    // 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
+    // base-argv shape.
+    const hasMutations = threads.length > 0 || allCommentIds.length > 0 || reviews.length > 0;
+    return { argv, requiresHeadSha, requiresDismissMessage: hasDismiss, hasMutations };
+}

package/bin/commands/iterate/escalate.mjs

@@ -0,0 +1,124 @@
+import { loadConfig } from "../../config/load.mjs";
+export function checkEscalateTriggers(actionableThreads, actionableComments, changesRequestedReviews, actionableChecks, threadAttempts, hasConflicts) {
+    const triggers = [];
+    const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
+    // Trigger 1: fix thrash — same thread dispatched too many times without resolving.
+    const thrashThreads = actionableThreads.filter((t) => (threadAttempts[t.id] ?? 0) >= maxAttempts);
+    if (thrashThreads.length > 0) {
+        triggers.push("fix-thrash");
+    }
+    // Trigger 2: PR-level CHANGES_REQUESTED with no inline threads/comments/CI to act on.
+    // Skip when there are merge conflicts — fix_code handles conflict resolution, not escalation.
+    if (changesRequestedReviews.length > 0 &&
+        actionableThreads.length === 0 &&
+        actionableComments.length === 0 &&
+        actionableChecks.length === 0 &&
+        !hasConflicts) {
+        triggers.push("pr-level-changes-requested");
+    }
+    // Trigger 3: actionable thread has no file/line — cannot locate code to edit.
+    const unlocatable = actionableThreads.filter((t) => t.path === null || t.line === null);
+    if (unlocatable.length > 0) {
+        triggers.push("thread-missing-location");
+    }
+    return {
+        triggers,
+        thrashHistory: thrashThreads.length > 0
+            ? thrashThreads.map((t) => ({ threadId: t.id, attempts: threadAttempts[t.id] ?? 0 }))
+            : undefined,
+    };
+}
+/**
+ * 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.
+ */
+export function validateBaseBranch(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        return {
+            branch: "main",
+            isFallback: true,
+            failureReason: "GraphQL batch returned an empty base branch name",
+        };
+    }
+    if (!/^[A-Za-z0-9._/-]+$/.test(trimmed)) {
+        return {
+            branch: "main",
+            isFallback: true,
+            failureReason: `base branch ${JSON.stringify(trimmed)} contains unsafe characters`,
+        };
+    }
+    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("");
+    lines.push(`**Triggers:** ${escalate.triggers.map((t) => `\`${t}\``).join(", ")}`);
+    lines.push("");
+    lines.push(escalate.suggestion);
+    const hasItems = escalate.unresolvedThreads.length > 0 ||
+        escalate.changesRequestedReviews.length > 0 ||
+        escalate.ambiguousComments.length > 0;
+    if (hasItems) {
+        lines.push("");
+        lines.push("## Items needing attention");
+        for (const t of escalate.unresolvedThreads) {
+            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
+            const firstLine = t.body.split("\n")[0] ?? "";
+            lines.push(`- thread \`${t.id}\` — ${loc} (@${t.author}): ${firstLine}`);
+        }
+        for (const r of escalate.changesRequestedReviews) {
+            const firstLine = r.body.split("\n")[0] ?? "";
+            lines.push(`- review \`${r.id}\` (@${r.author}): ${firstLine}`);
+        }
+        for (const c of escalate.ambiguousComments) {
+            const firstLine = c.body.split("\n")[0] ?? "";
+            lines.push(`- comment \`${c.id}\` (@${c.author}): ${firstLine}`);
+        }
+    }
+    if (escalate.attemptHistory && escalate.attemptHistory.length > 0) {
+        lines.push("");
+        lines.push("## Fix attempts");
+        for (const a of escalate.attemptHistory) {
+            lines.push(`- thread \`${a.threadId}\` attempted ${a.attempts} times`);
+        }
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(`Run \`/pr-shepherd:check ${pr}\` to see current state.`);
+    lines.push(`After fixing manually, rerun \`/pr-shepherd:monitor ${pr}\` to resume.`);
+    return lines.join("\n");
+}
+export function buildEscalateSuggestion(triggers, detail) {
+    if (triggers.includes("stall-timeout")) {
+        const mins = detail ?? "30";
+        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. Inspect the PR and resume manually once the blocking issue is resolved.`;
+    }
+    if (triggers.includes("base-branch-unknown")) {
+        const reason = detail ? ` (${detail})` : "";
+        return `Could not determine the PR's base branch${reason} — refusing to emit a rebase that could force-push onto the wrong base. Run the rebase manually against the PR's real target branch.`;
+    }
+    if (triggers.includes("fix-thrash")) {
+        return "Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:monitor";
+    }
+    if (triggers.includes("pr-level-changes-requested")) {
+        return "Reviewer requested changes but left no inline comments — read the review and act manually";
+    }
+    if (triggers.includes("thread-missing-location")) {
+        return "Review thread has no file/line reference — cannot locate code to edit automatically";
+    }
+    return "Ambiguous state — inspect the PR and act manually";
+}