pr-shepherd 0.34.0 → 0.36.0

package/bin/cli/journal-formatter.mjs

@@ -0,0 +1,15 @@
+export function formatJournalResult(result) {
+    if (result.dryRun) {
+        const lines = ["Dry run — no body change written."];
+        if (result.previewBody !== undefined) {
+            lines.push("", result.previewBody);
+        }
+        return lines.join("\n");
+    }
+    if (!result.mutated)
+        return "No change — entry already present.";
+    if (!result.sectionExisted) {
+        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
+    }
+    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
+}

package/bin/cli/journal-handler.d.mts

@@ -0,0 +1 @@
+export declare function handleJournal(args: string[], command?: "apply journal" | "journal"): Promise<void>;

package/bin/cli/journal-handler.mjs

@@ -3,7 +3,8 @@ import { EXIT, errorToExitCode } from "../exit-codes.mjs";
 import { runJournal } from "../commands/journal/index.mjs";
 import { getFlag, parsePrNumber } from "./args.mjs";
 import { USAGE } from "./help.mjs";
-export async function handleJournal(args) {
+import { formatJournalResult } from "./journal-formatter.mjs";
+export async function handleJournal(args, command = "apply journal") {
     for (const a of args) {
         if (!a.startsWith("--"))
             continue;
@@ -11,14 +12,14 @@ export async function handleJournal(args) {
             continue;
         if (a === "--file" || a.startsWith("--file="))
             continue;
-        process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
+        process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
     const { prNumber, extra } = parseJournalArgs(args);
     const filePath = getFlag(args, "--file");
     if (filePath !== null && extra[0]) {
-        process.stderr.write(`pr-shepherd: journal: provide the entry as a positional argument or via --file, not both\n`);
+        process.stderr.write(`pr-shepherd: ${command}: provide the entry as a positional argument or via --file, not both\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -27,12 +28,12 @@ export async function handleJournal(args) {
         rawItem = filePath !== null ? await readItemSource(filePath) : extra[0];
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.stderr.write(`pr-shepherd: ${command}: ${String(e)}\n`);
         process.exitCode = EXIT.NOINPUT;
         return;
     }
     if (rawItem === undefined) {
-        process.stderr.write(`${USAGE.journal}\n`);
+        process.stderr.write(`${USAGE[command]}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -49,7 +50,7 @@ export async function handleJournal(args) {
         }
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.stderr.write(`pr-shepherd: ${command}: ${String(e)}\n`);
         process.exitCode = errorToExitCode(e);
     }
 }
@@ -96,17 +97,3 @@ function parseJournalArgs(args) {
     }
     return { prNumber, extra };
 }
-function formatJournalResult(result) {
-    if (result.dryRun) {
-        const lines = ["Dry run — no body change written."];
-        if (result.previewBody !== undefined) {
-            lines.push("", result.previewBody);
-        }
-        return lines.join("\n");
-    }
-    if (!result.mutated)
-        return "No change — entry already present.";
-    if (!result.sectionExisted)
-        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
-    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
-}

package/bin/cli/list-formatters.d.mts

@@ -0,0 +1,76 @@
+import type { AuthorType, CommentAuthorAssociation, SuggestionBlock } from "../types.mts";
+import type { FirstLookThread, FirstLookComment } from "../types/report.mts";
+export declare function renderAuthor(author: string, authorType?: AuthorType, authorAssociation?: CommentAuthorAssociation): string;
+export declare function renderBodyPreview(body: string): string;
+export declare function renderThreadResolutionStatusTag(t: {
+    isOutdated?: boolean;
+    isMinimized?: boolean;
+}): string;
+interface ThreadBulletInput {
+    id: string;
+    reviewId?: string;
+    url?: string;
+    path?: string | null;
+    startLine?: number | null;
+    line?: number | null;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    comments?: Array<{
+        id: string;
+        author: string;
+        authorType?: AuthorType;
+        authorAssociation?: CommentAuthorAssociation;
+        body: string;
+        url: string;
+    }>;
+    suggestion?: SuggestionBlock;
+    edited?: boolean;
+}
+export declare function renderThreadBullet(t: ThreadBulletInput, opts?: {
+    statusTag?: string;
+    renderSuggestion?: boolean;
+    noBody?: boolean;
+    suppressEditedMarker?: boolean;
+}): string;
+export declare function renderThreadConversation(t: ThreadBulletInput): string;
+export declare function blockquote(body: string): string;
+export declare function renderCommentBullet(c: {
+    id: string;
+    url?: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+}, opts?: {
+    statusTag?: string;
+}): string;
+export declare function renderEditedCommentTag(c: {
+    edited?: boolean;
+}): string | undefined;
+export declare function renderReviewBullet(r: {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body?: string;
+    staleBotCr?: boolean;
+    staleReview?: boolean;
+}, opts?: {
+    includeBody?: boolean;
+}): string;
+export declare function renderReviewListSection(heading: string, items: {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body?: string;
+}[]): string | null;
+/**
+ * Build bullet strings for the `## First-look items` section.
+ * Threads that also appear in resolutionOnlyIds have their body suppressed
+ * (already shown in `## Review threads to resolve`).
+ */
+export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[]): string[];
+export {};

package/bin/cli/list-formatters.mjs

@@ -1,8 +1,8 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 import { threadComments } from "../threads/transcript.mjs";
 const BODY_PREVIEW_MAX = 100;
-export function renderAuthor(author, authorType) {
-    return authorType ? `@${author} · ${authorType}` : `@${author}`;
+export function renderAuthor(author, authorType, authorAssociation) {
+    return [`@${author}`, authorType, authorAssociation].filter(Boolean).join(" · ");
 }
 export function renderBodyPreview(body) {
     const normalizedBody = body.replace(/\r\n?/g, "\n");
@@ -30,7 +30,7 @@ export function renderThreadBullet(t, opts = {}) {
     const editedMarker = t.edited && !opts.suppressEditedMarker ? " [edited since first look]" : "";
     const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
     if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
         const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
         return t.suggestion && opts.renderSuggestion
@@ -53,9 +53,9 @@ export function renderThreadConversation(t) {
         .map((c) => {
         const heading = c.id
             ? c.url
-                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType)})`
-                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType)})`
-            : `#### (${renderAuthor(c.author, c.authorType)})`;
+                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
+                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
+            : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`;
         return `${heading}\n\n${blockquote(c.body)}`;
     })
         .join("\n\n");
@@ -73,7 +73,7 @@ function renderThreadCommentBullets(t) {
         const link = c.url ? ` [↗](${c.url})` : "";
         const id = c.id ? `\`commentId=${c.id}\`` : "comment";
         return [
-            `  - ${id}${link} (${renderAuthor(c.author, c.authorType)})`,
+            `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`,
             indentBlockquote(c.body, "    "),
         ].join("\n");
     })
@@ -88,13 +88,13 @@ function indentBlockquote(body, indent) {
 export function renderCommentBullet(c, opts = {}) {
     const link = c.url ? ` [↗](${c.url})` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
+    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
 export function renderEditedCommentTag(c) {
     return c.edited ? "[edited since first look]" : undefined;
 }
 export function renderReviewBullet(r, opts = {}) {
-    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`;
+    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`;
     const staleTag = r.staleReview
         ? " [stale — review is on an old commit, all threads resolved]"
         : "";

package/bin/cli/mark-files-as-viewed-flags.d.mts

@@ -0,0 +1,11 @@
+type ParseMarkFilesAsViewedResult = {
+    ok: true;
+    files: string[];
+    tests: boolean;
+    matchPatterns: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseMarkFilesAsViewedArgs(args: string[]): ParseMarkFilesAsViewedResult;
+export {};

package/bin/cli/mark-files-as-viewed-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { MarkFilesAsViewedResult } from "../commands/mark-files-as-viewed.mts";
+export declare function formatMarkFilesAsViewedResult(result: MarkFilesAsViewedResult): string;

package/bin/cli/mutate-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { ResolveResult } from "../comments/resolve.mts";
+export declare function formatMutateResult(result: ResolveResult): string;

package/bin/cli/poll-handler.d.mts

@@ -0,0 +1 @@
+export declare function handlePoll(args: string[]): Promise<void>;

package/bin/cli/poll-handler.mjs

@@ -7,6 +7,7 @@ import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
 const DEFAULT_POLL_INTERVAL_SECONDS = 60;
 const DEFAULT_POLL_TIMEOUT_SECONDS = 270;
+const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 export async function handlePoll(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
@@ -14,15 +15,20 @@ export async function handlePoll(args) {
     if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const intervalStr = getFlag(extra, "--interval");
-    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));
+    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd", "--interval", intervalStr, hasFlag(extra, "--interval"));
     if (intervalSuffix === null)
         return;
     const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", DEFAULT_POLL_INTERVAL_SECONDS);
     const timeoutStr = getFlag(extra, "--timeout");
-    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
+    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
     if (timeoutSuffix === null)
         return;
     const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", DEFAULT_POLL_TIMEOUT_SECONDS);
+    const debounceStr = getFlag(extra, "--debounce");
+    const debounceSuffix = validateSecondsDurationFlag("pr-shepherd", "--debounce", debounceStr, hasFlag(extra, "--debounce"), { allowZero: true });
+    if (debounceSuffix === null)
+        return;
+    const debounceSeconds = parseDurationToSeconds(debounceSuffix ?? "", DEFAULT_POLL_DEBOUNCE_SECONDS, { allowZero: true });
     const result = await runPoll({
         ...globalOpts,
         prNumber,
@@ -32,6 +38,7 @@ export async function handlePoll(args) {
         noAutoCancelActionable: flags.noAutoCancelActionable,
         intervalSeconds,
         timeoutSeconds,
+        debounceSeconds,
         quietStatus: hasFlag(extra, "--quiet-status"),
         untilTerminal: hasFlag(extra, "--until-terminal"),
     });

package/bin/cli/resolve-validators.d.mts

@@ -0,0 +1,3 @@
+export declare function rejectPrrcMinimizeIds(ids: string[]): string[];
+export declare function warnPrrcThreadIds(ids: string[]): string[];
+export declare function validateRequireSha(sha: string | undefined): boolean;

package/bin/cli/resolve-validators.mjs

@@ -2,7 +2,7 @@ import { EXIT } from "../exit-codes.mjs";
 export function rejectPrrcMinimizeIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
+        process.stderr.write(`pr-shepherd: apply review: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
         process.exitCode = EXIT.DATAERR;
     }
     return prrcIds;
@@ -10,7 +10,7 @@ export function rejectPrrcMinimizeIds(ids) {
 export function warnPrrcThreadIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
+        process.stderr.write(`pr-shepherd: apply review: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
     }
     return prrcIds;
 }
@@ -19,7 +19,7 @@ export function validateRequireSha(sha) {
         return true;
     if (/^[0-9a-f]{40}$/.test(sha))
         return true;
-    process.stderr.write(`pr-shepherd: resolve: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
+    process.stderr.write(`pr-shepherd: apply review: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
     process.exitCode = EXIT.DATAERR;
     return false;
 }

package/bin/cli/runner.d.mts

@@ -0,0 +1,7 @@
+interface PrShepherdCommand {
+    argv: string[];
+    text: string;
+}
+export declare function buildPrShepherdCommand(args: string[]): PrShepherdCommand;
+export declare function renderShellCommand(argv: string[]): string;
+export {};

package/bin/cli/suggestion-renderer.d.mts

@@ -0,0 +1,3 @@
+import type { SuggestionBlock } from "../types.mts";
+export declare function renderLineRange(startLine: number | undefined, endLine: number | null): string;
+export declare function renderSuggestionBlock(s: SuggestionBlock, indent?: string): string;

package/bin/cli/validate-default-args.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Validate args for default-dispatch paths (e.g. `pr-shepherd [PR] [flags]`).
+ * Returns false when an unexpected token is found; calls onError with the
+ * offending arg so callers can print their own usage message.
+ */
+export declare function validateDefaultArgs(args: string[], flagsWithValues: ReadonlySet<string>, booleanFlags: ReadonlySet<string>, onError: (arg: string) => void): boolean;

package/bin/cli-parser.d.mts

@@ -0,0 +1,2 @@
+/** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
+export declare function main(argv: string[]): Promise<void>;

package/bin/cli-parser.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
 import { EXIT, errorToExitCode } from "./exit-codes.mjs";
@@ -5,7 +6,7 @@ import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
-import { USAGE, maybePrintHelp } from "./cli/help.mjs";
+import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
@@ -31,19 +32,33 @@ export async function main(argv) {
         await handleLogFile(args.slice(1));
         return;
     }
+    // The public command groups keep admin diagnostics out of the normal
+    // command namespace. Keep this before setupLog because log-file reads the
+    // log path and must not initialize/tee the log it is reporting.
+    if (subcommand === "admin" && args[1] === "log-file") {
+        await handleLogFile(args.slice(2), "admin log-file");
+        return;
+    }
     // Short-circuit all --help/-h before any I/O or logging.
     if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
         if (isDefaultPollInvocation(subcommand)) {
-            process.stdout.write(`${USAGE.poll}\n`);
+            process.stdout.write(`${USAGE.default}\n`);
         }
         else {
-            const key = subcommand != null && subcommand in USAGE
-                ? subcommand
-                : "top";
-            process.stdout.write(`${USAGE[key]}\n`);
+            process.stdout.write(`${USAGE[helpKeyForArgs(args)]}\n`);
         }
         return;
     }
+    const legacyReplacement = {
+        poll: "pr-shepherd [PR] (the default PR polling command)",
+        resolve: "apply review",
+        "mark-files-as-viewed": "apply files",
+        journal: "apply journal",
+        "commit-suggestion": "build-suggestion-patch",
+    };
+    if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
+        warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
+    }
     // Initialize the per-worktree log and install a stdout tee.
     await setupLog(argv);
     if (isDefaultPollInvocation(subcommand)) {
@@ -53,14 +68,23 @@ export async function main(argv) {
         return;
     }
     switch (subcommand) {
+        case "apply":
+            await handleApply(args.slice(1));
+            break;
+        case "build-suggestion-patch":
+            await handleCommitSuggestion(args.slice(1));
+            break;
+        case "admin":
+            await handleAdmin(args.slice(1));
+            break;
         case "resolve":
-            await handleResolve(args.slice(1));
+            await handleResolve(args.slice(1), "resolve");
             break;
         case "commit-suggestion":
-            await handleCommitSuggestion(args.slice(1));
+            await handleCommitSuggestion(args.slice(1), "commit-suggestion");
             break;
         case "mark-files-as-viewed":
-            await handleMarkFilesAsViewed(args.slice(1));
+            await handleMarkFilesAsViewed(args.slice(1), "mark-files-as-viewed");
             break;
         case "iterate":
             await handleIterate(args.slice(1));
@@ -69,10 +93,10 @@ export async function main(argv) {
             await handlePoll(args.slice(1));
             break;
         case "clean":
-            await handleClean(args.slice(1));
+            await handleClean(args.slice(1), "clean");
             break;
         case "journal":
-            await handleJournal(args.slice(1));
+            await handleJournal(args.slice(1), "journal");
             break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
@@ -81,6 +105,38 @@ export async function main(argv) {
             return;
     }
 }
+function warnLegacyAlias(alias, replacement) {
+    process.stderr.write(`pr-shepherd: ${alias} is deprecated; use ${replacement.startsWith("pr-shepherd") ? replacement : `pr-shepherd ${replacement}`} instead.\n`);
+}
+async function handleApply(args) {
+    const action = args[0];
+    switch (action) {
+        case "review":
+            await handleResolve(args.slice(1));
+            return;
+        case "files":
+            await handleMarkFilesAsViewed(args.slice(1));
+            return;
+        case "journal":
+            await handleJournal(args.slice(1));
+            return;
+        default:
+            process.stderr.write(`Unknown apply action: ${action ?? "(none)"}\n`);
+            process.stderr.write(`${USAGE.apply}\n`);
+            process.exitCode = EXIT.USAGE;
+    }
+}
+async function handleAdmin(args) {
+    switch (args[0]) {
+        case "clean":
+            await handleClean(args.slice(1));
+            return;
+        default:
+            process.stderr.write(`Unknown admin command: ${args[0] ?? "(none)"}\n`);
+            process.stderr.write(`${USAGE.admin}\n`);
+            process.exitCode = EXIT.USAGE;
+    }
+}
 function readVersion() {
     const pkgUrl = new URL("../package.json", import.meta.url);
     const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
@@ -89,8 +145,8 @@ function readVersion() {
 // ---------------------------------------------------------------------------
 // Subcommand handlers
 // ---------------------------------------------------------------------------
-async function handleLogFile(args) {
-    if (maybePrintHelp(args, "log-file"))
+async function handleLogFile(args, usageKey = "log-file") {
+    if (maybePrintHelp(args, usageKey))
         return;
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {
@@ -106,7 +162,7 @@ async function handleLogFile(args) {
         process.exitCode = errorToExitCode(e);
     }
 }
-async function handleResolve(args) {
+async function handleResolve(args, command = "apply review") {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
     const replyThreadIds = parseList(getFlag(extra, "--reply-thread-ids"));
@@ -120,7 +176,7 @@ async function handleResolve(args) {
     if (rejectPrrcMinimizeIds(minimizeCommentIds).length > 0)
         return;
     if (hasFlag(extra, "--fetch")) {
-        process.stderr.write("pr-shepherd: resolve: --fetch has been removed; run pr-shepherd iterate or poll to fetch the next action.\n");
+        process.stderr.write(`pr-shepherd: ${command}: --fetch has been removed; run pr-shepherd iterate to fetch the next action.\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -129,7 +185,7 @@ async function handleResolve(args) {
         minimizeCommentIds.length > 0 ||
         dismissReviewIds.length > 0;
     if (!hasAction) {
-        process.stderr.write("pr-shepherd: resolve: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n");
+        process.stderr.write(`pr-shepherd: ${command}: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }

package/bin/commands/check-annotations.d.mts

@@ -0,0 +1,5 @@
+import type { CheckAnnotation, TriagedCheck } from "../types.mts";
+export declare function attachUnseenCheckAnnotations(checks: TriagedCheck[], seenMap: Map<string, {
+    seenAt: number;
+}>, prNumber: number): Promise<TriagedCheck[]>;
+export declare function annotationMarkerBody(a: CheckAnnotation): string;

package/bin/commands/check-status.d.mts

@@ -0,0 +1,3 @@
+import type { MergeStatusResult, ShepherdStatus } from "../types.mts";
+import type { CiVerdict } from "../checks/classify.mts";
+export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number): ShepherdStatus;

package/bin/commands/check-terminal-report.d.mts

@@ -0,0 +1,5 @@
+import type { BatchPrData, MergeStatusResult, ShepherdReport } from "../types.mts";
+export declare function buildTerminalReport(prNumber: number, repo: {
+    owner: string;
+    name: string;
+}, batchData: BatchPrData, mergeStatus: MergeStatusResult, status: "MERGED" | "CLOSED"): ShepherdReport;

package/bin/commands/check.d.mts

@@ -0,0 +1,7 @@
+import type { GlobalOptions, ShepherdReport } from "../types.mts";
+export declare function runCheck(opts: GlobalOptions & {
+    autoResolve?: boolean;
+    autoMinimizeSuppressed?: boolean;
+    skipTriage?: boolean;
+    persistSeen?: boolean;
+}): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -20,6 +20,7 @@ import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { getEffectiveCwd } from "../execution-context.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -37,7 +38,9 @@ export async function runCheck(opts) {
     if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
         return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
     }
-    const startupFailureChecks = await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
+    const startupFailureChecks = result.checkSuitesComplete
+        ? []
+        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedChecks = classifyChecks(allChecks);
     const verdict = getCiVerdict(classifiedChecks);
@@ -50,7 +53,7 @@ export async function runCheck(opts) {
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const seenMap = await loadSeenMap(stateKey);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const ruleSet = await loadRules(discoverRuleFiles(process.cwd()));
+    const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
     const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);
@@ -79,27 +82,29 @@ export async function runCheck(opts) {
     }
     const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
-    await Promise.allSettled([
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-        ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
-        ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-        ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-        ...batchData.comments
-            .filter((c) => partition.suppressedCommentIds.has(c.id))
-            .map((c) => markSeen(stateKey, c.id, c.body)),
-        ...batchData.reviewThreads
-            .filter((t) => partition.suppressedThreadIds.has(t.id))
-            .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-        ...batchData.reviewSummaries
-            .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
-            .map((r) => markSeen(stateKey, r.id, r.body)),
-        ...batchData.changesRequestedReviews
-            .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
-            .map((r) => markSeen(stateKey, r.id, r.body)),
-    ]);
-    await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
+    if (opts.persistSeen !== false) {
+        await Promise.allSettled([
+            ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+            ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+            ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
+            ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
+            ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ...batchData.comments
+                .filter((c) => partition.suppressedCommentIds.has(c.id))
+                .map((c) => markSeen(stateKey, c.id, c.body)),
+            ...batchData.reviewThreads
+                .filter((t) => partition.suppressedThreadIds.has(t.id))
+                .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+            ...batchData.reviewSummaries
+                .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
+                .map((r) => markSeen(stateKey, r.id, r.body)),
+            ...batchData.changesRequestedReviews
+                .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
+                .map((r) => markSeen(stateKey, r.id, r.body)),
+        ]);
+        await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
+    }
     const { threadIds: ruleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(partition, opts.autoMinimizeSuppressed);
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;

package/bin/commands/clean.d.mts

@@ -0,0 +1,21 @@
+export type CleanVariant = "pr" | "branch" | "current" | "repo" | "all";
+interface CleanOptions {
+    variant: CleanVariant;
+    /** PR number string (for "pr") or branch name (for "branch"). Defaults to current. */
+    value?: string;
+    dryRun?: boolean;
+}
+export interface CleanResult {
+    ok: boolean;
+    variant: CleanVariant;
+    dryRun: boolean;
+    base: string;
+    target: string;
+    /** Paths removed (actual delete) or that would be removed (dry-run). */
+    deleted: string[];
+    /** Target path when it did not exist. */
+    skipped: string[];
+    error?: string;
+}
+export declare function runClean(opts: CleanOptions): Promise<CleanResult>;
+export {};