pr-shepherd 0.34.0 → 0.35.0

package/bin/commands/iterate/helpers.mjs

@@ -1,6 +1,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
+import { getExecutionCwd } from "../../execution-context.mjs";
 const execFile = promisify(execFileCb);
 export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mjs";
 export function buildSummary(report) {
@@ -114,7 +115,9 @@ export async function tryCancelRun(runId, owner, repo) {
 }
 export async function getCurrentHeadSha() {
     try {
-        const { stdout } = await execFile("git", ["rev-parse", "HEAD"]);
+        const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {
+            cwd: getExecutionCwd(),
+        });
         return stdout.trim();
     }
     catch {

package/bin/commands/iterate/index.d.mts

@@ -0,0 +1,2 @@
+import type { IterateCommandOptions, IterateResult } from "../../types.mts";
+export declare function runIterate(opts: IterateCommandOptions): Promise<IterateResult>;

package/bin/commands/iterate/index.mjs

@@ -25,7 +25,10 @@ export async function runIterate(opts) {
     const report = await runCheck({
         ...opts,
         prNumber,
-        autoResolve: config.actions.autoResolveOutdated,
+        // Outdated Shepherd-visible threads are always resolved by iterate. The
+        // old actions.autoResolveOutdated switch is retained only as an ignored
+        // compatibility key in the config loader.
+        autoResolve: true,
         autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
     });
     const [repoOwner, repoName] = report.repo.split("/");
@@ -48,7 +51,7 @@ export async function runIterate(opts) {
     // GitHub can still return a null/error/rate-limit result per ID without
     // throwing (autoMinimizeComments reports this via `errors`, not a rejection);
     // any ID it did not confirm minimized falls back into the agent-facing set so
-    // the resolve command remains a working fallback instead of silently dropping it.
+    // the apply command remains a working fallback instead of silently dropping it.
     let reviewSummaryIds = minimizeIds;
     if (selfMinimizeIds.length > 0) {
         const { minimized } = await autoMinimizeComments(selfMinimizeIds);

package/bin/commands/iterate/render.d.mts

@@ -0,0 +1,5 @@
+import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, FirstLookThread, FirstLookComment, ReviewThread } from "../../types.mts";
+/** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
+export declare function renderResolveCommand(rc: ResolveCommand): string;
+export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prNumber: number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+isBehind?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -32,14 +32,16 @@ isBehind = false) {
         if (changesRequestedReviews.length > 0)
             actionableSections.push("`## Changes-requested reviews`");
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
-        const resolveClause = resolveCommand.hasMutations ? ", then run the `resolve:` command" : "";
+        const resolveClause = resolveCommand.hasMutations
+            ? ", then run the `apply review:` command"
+            : "";
         if (hasConflicts) {
             // Conflicts make push mandatory regardless of whether code edits are needed.
             instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Apply any code edits for items ${sectionRef}, then commit and push${resolveClause}.`);
         }
         else {
             const skipClause = resolveCommand.hasMutations
-                ? "skip the commit/push and run the `resolve:` command"
+                ? "skip the commit/push and run the `apply review:` command"
                 : "no push is needed";
             instructions.push(`Decide for each item ${sectionRef} whether a code change is warranted. **If any code changes are needed:** apply edits, commit, push${resolveClause}. **If no code changes are needed:** ${skipClause}.`);
         }
@@ -59,12 +61,12 @@ isBehind = false) {
         // is only accurate when threads are present.
         const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
         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.`
+            ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`build-suggestion-patch\` 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 ${filesRef}.${suggestionFallback}`);
     }
     if (resolutionOnlyThreads.length > 0) {
-        instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`resolve:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
+        instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`apply review:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
     }
     instructions.push(...buildFailingCheckInstructions(checks));
     if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
@@ -74,7 +76,7 @@ isBehind = false) {
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.${staleClause}`);
         if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
-            instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`resolve:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);
+            instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`apply review:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);
@@ -84,7 +86,7 @@ isBehind = false) {
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, its ID is already included in the \`resolve:\` command; otherwise do not pass first-look-only IDs to mutation flags.`);
+        instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, its ID is already included in the \`apply review:\` command; otherwise do not pass first-look-only IDs to mutation flags.`);
     }
     if (firstLookSummaries.length > 0)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);

package/bin/commands/iterate/reruns.d.mts

@@ -0,0 +1,20 @@
+import type { ShepherdReport } from "../../types.mts";
+import type { ProtectedRun } from "../../types/protected-run.mts";
+type FailingCheck = ShepherdReport["checks"]["failing"][number];
+type InProgressCheck = ShepherdReport["checks"]["inProgress"][number];
+type CancellableCheck = FailingCheck | InProgressCheck;
+interface RunProtection {
+    protectedRunIds: Set<string>;
+    protectedRuns: ProtectedRun[];
+}
+interface BuildRunIdOptions {
+    protectedRunIds?: Set<string>;
+}
+export declare function buildAutoCancelRunIdsWithOptions(report: ShepherdReport, opts?: BuildRunIdOptions): string[];
+interface BuildInProgressRunIdOptions {
+    suppressProtectedFreshReruns?: boolean;
+    protectedRunIds?: Set<string>;
+}
+export declare function buildInProgressRunIds(report: ShepherdReport, cancelledSet: Set<string>, opts?: BuildInProgressRunIdOptions): string[];
+export declare function buildRunProtection(checks: CancellableCheck[], patterns?: string[]): RunProtection;
+export {};

package/bin/commands/iterate/stall.d.mts

@@ -0,0 +1,6 @@
+import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+export declare function applyStallGuard(stallKey: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, stallTimeoutSeconds: number, headSha: string, base: IterateResultBase, prNumber: number, prospectiveResult: IterateResult, report: ShepherdReport, reviewSummaryIds: string[]): Promise<IterateResult>;

package/bin/commands/journal/index.d.mts

@@ -0,0 +1,14 @@
+export interface RunJournalOptions {
+    prNumber: number | undefined;
+    rawItem: string;
+    dryRun: boolean;
+}
+export interface JournalResult {
+    prNumber: number;
+    mutated: boolean;
+    sectionExisted: boolean;
+    dryRun: boolean;
+    previewBody?: string;
+}
+/** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */
+export declare function runJournal(opts: RunJournalOptions): Promise<JournalResult>;

package/bin/commands/journal/index.mjs

@@ -1,5 +1,6 @@
 import { getRepoInfo, getPullRequestBody, updatePullRequestBody, getCurrentPrNumber, } from "../../github/client.mjs";
 import { validateJournalItem, appendJournalItem } from "./transform.mjs";
+/** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */
 export async function runJournal(opts) {
     const validation = validateJournalItem(opts.rawItem);
     if (!validation.ok) {

package/bin/commands/journal/transform.d.mts

@@ -0,0 +1,22 @@
+export interface AppendResult {
+    body: string;
+    mutated: boolean;
+    sectionExisted: boolean;
+}
+type ValidationOk = {
+    ok: true;
+    item: string;
+};
+type ValidationError = {
+    ok: false;
+    error: string;
+};
+export type ValidationResult = ValidationOk | ValidationError;
+/** Validates that the input is a properly formed markdown list item. */
+export declare function validateJournalItem(input: string): ValidationResult;
+/**
+ * Appends a validated list item to the ## Shepherd Journal section of a PR body.
+ * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
+ */
+export declare function appendJournalItem(body: string, item: string): AppendResult;
+export {};

package/bin/commands/log-file.d.mts

@@ -0,0 +1,5 @@
+interface LogFileResult {
+    path: string;
+}
+export declare function runLogFile(): Promise<LogFileResult>;
+export {};

package/bin/commands/mark-files-as-viewed.d.mts

@@ -0,0 +1,26 @@
+import { type ResolveRateLimitStop } from "../comments/rate-limit.mts";
+import type { GlobalOptions } from "../types.mts";
+export interface MarkFilesAsViewedOptions extends GlobalOptions {
+    prNumber?: number;
+    files: string[];
+    tests?: boolean;
+    matchPatterns?: string[];
+}
+export interface MarkFilesAsViewedResult {
+    repo: string;
+    prNumber: number;
+    pullRequestId: string;
+    requestedPaths: string[];
+    testSelector: boolean;
+    matchPatterns: string[];
+    matchedPaths: string[];
+    markedPaths: string[];
+    alreadyViewedPaths: string[];
+    missingPaths: string[];
+    unmatchedSelectors: string[];
+    errors: string[];
+    rateLimit?: ResolveRateLimitStop;
+    unmarkedPaths?: string[];
+}
+/** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
+export declare function runMarkFilesAsViewed(opts: MarkFilesAsViewedOptions): Promise<MarkFilesAsViewedResult>;

package/bin/commands/mark-files-as-viewed.mjs

@@ -23,6 +23,7 @@ const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr
 }`;
 const TEST_FILE_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[cm]?[jt]sx?$|_tests?\.rs$|(^|\/)tests?\.rs$/i;
 const BULK_CHUNK_SIZE = 10;
+/** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
 export async function runMarkFilesAsViewed(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());

package/bin/commands/poll.d.mts

@@ -0,0 +1,10 @@
+import type { IterateCommandOptions, IterateResult } from "../types.mts";
+interface PollCommandOptions extends IterateCommandOptions {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    quietStatus?: boolean;
+    untilTerminal?: boolean;
+}
+/** @deprecated Hidden implementation for the legacy `poll` alias. */
+export declare function runPoll(opts: PollCommandOptions): Promise<IterateResult>;
+export {};

package/bin/commands/poll.mjs

@@ -54,6 +54,7 @@ function writeWaitProgress(opts) {
     }
     return signature;
 }
+/** @deprecated Hidden implementation for the legacy `poll` alias. */
 export async function runPoll(opts) {
     const { intervalSeconds, timeoutSeconds, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);

package/bin/commands/ready-delay.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Ready-delay state machine for the shepherd iterate loop.
+ *
+ * When all READY conditions hold, shepherd writes a `ready-since.txt` marker
+ * to the state dir. The loop continues until the PR has been READY for
+ * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
+ */
+interface ReadyDelayState {
+    isReady: boolean;
+    /**
+     * When true, the loop should cancel itself — the PR has been READY for
+     * longer than the configured ready-delay.
+     */
+    shouldCancel: boolean;
+    /** How many seconds remain in the ready-delay. */
+    remainingSeconds: number;
+}
+/**
+ * Update the ready-delay state machine and return the current decision.
+ *
+ * Call this at the end of each sweep iteration:
+ *   - If `isReady == true`: start or continue the ready timer.
+ *   - If `isReady == false`: reset the timer.
+ *
+ * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
+ * the loop and tells one-shot agents to stop.
+ */
+export declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string): Promise<ReadyDelayState>;
+export {};

package/bin/commands/ready-mergeability.d.mts

@@ -0,0 +1,15 @@
+import { type RepoInfo } from "../github/client.mts";
+import type { CiVerdict } from "../checks/classify.mts";
+import type { BatchPrData, MergeStatusResult, ShepherdStatus } from "../types.mts";
+interface ReadyMergeabilityRefresh {
+    batchData: BatchPrData;
+    mergeStatus: MergeStatusResult;
+    status: ShepherdStatus;
+}
+export declare function refreshUnknownMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData): Promise<{
+    batchData: BatchPrData;
+    didRefresh: boolean;
+}>;
+export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number): Promise<ReadyMergeabilityRefresh>;
+export declare function isBlockedByFilteredCheck(mergeStatus: MergeStatusResult, verdict: CiVerdict): boolean;
+export {};

package/bin/commands/resolve-mutate.d.mts

@@ -0,0 +1,4 @@
+import type { ResolveOptions } from "../types.mts";
+import type { ResolveCommandOptions } from "./resolve.mts";
+/** @deprecated Hidden implementation for `resolve`; use `apply review`. */
+export declare function runResolveMutate(opts: ResolveCommandOptions & ResolveOptions): Promise<import("../comments/resolve.mts").ResolveResult>;

package/bin/commands/resolve-mutate.mjs

@@ -7,6 +7,7 @@ import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { addPrShepherdMarker } from "../comments/marker.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
+/** @deprecated Hidden implementation for `resolve`; use `apply review`. */
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());

package/bin/commands/resolve.d.mts

@@ -0,0 +1,4 @@
+import type { GlobalOptions } from "../types.mts";
+export { runResolveMutate } from "./resolve-mutate.mts";
+export interface ResolveCommandOptions extends GlobalOptions {
+}

package/bin/commands/shepherd-journal.d.mts

@@ -0,0 +1,7 @@
+export declare const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
+export declare const SHEPHERD_JOURNAL_SECTION_PATTERN: RegExp;
+export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
+export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` \u2014 you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the `apply review:` or `resolve-only:` command above; if any warrants a Shepherd Journal note, append it before applying review mutations.";
+export declare function buildShepherdJournalInstruction(prNumber: number, itemReferenceGuidance: string): string;
+export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.";
+export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.";

package/bin/commands/shepherd-journal.mjs

@@ -1,10 +1,10 @@
 export const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the resolve or resolve-only command above; if any warrants a Shepherd Journal note, append it before running resolve.";
+export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the `apply review:` or `resolve-only:` command above; if any warrants a Shepherd Journal note, append it before applying review mutations.";
 export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
     return [
-        `For any large decisions or rejections you made this iteration, run \`pr-shepherd journal ${prNumber} '- <decision>'\` to append an entry to the \`${SHEPHERD_JOURNAL_SECTION}\` section.`,
+        `For any large decisions or rejections you made this iteration, run \`pr-shepherd apply journal ${prNumber} '- <decision>'\` to append an entry to the \`${SHEPHERD_JOURNAL_SECTION}\` section.`,
         itemReferenceGuidance,
         `The command is idempotent — re-running with the same text is a no-op.`,
     ].join(" ");

package/bin/comments/authors.d.mts

@@ -0,0 +1,14 @@
+import type { AuthorType } from "../types.mts";
+export type NormalizedBotUsernames = ReadonlySet<string>;
+export declare function normalizeBotUsernames(botUsernames?: readonly string[] | undefined | null): NormalizedBotUsernames;
+export declare function normalizeAuthorType(typeName: string | undefined | null, login: string | undefined | null): AuthorType;
+export declare function isHumanAuthor(author: {
+    author?: string;
+    login?: string;
+    authorType?: AuthorType;
+}): boolean;
+export declare function isConfiguredBotAuthor(author: {
+    author?: string;
+    login?: string;
+    authorType?: AuthorType;
+}, botUsernames?: NormalizedBotUsernames): boolean;

package/bin/comments/marker.d.mts

@@ -0,0 +1,2 @@
+export declare function hasPrShepherdMarker(body: string): boolean;
+export declare function addPrShepherdMarker(body: string): string;

package/bin/comments/minimize-policy.d.mts

@@ -0,0 +1,4 @@
+import type { MinimizeCommentsPolicy } from "../config/load.mts";
+import type { AuthorType } from "../types.mts";
+import { type NormalizedBotUsernames } from "./authors.mts";
+export declare function shouldMinimizeAuthor(authorType: AuthorType | undefined, policy: MinimizeCommentsPolicy | undefined, author?: string, botUsernames?: NormalizedBotUsernames): boolean;

package/bin/comments/pending-ops.d.mts

@@ -0,0 +1,15 @@
+import type { ResolveResult } from "./resolve.mts";
+export type ResolveMutationOp = {
+    kind: "p";
+    id: string;
+} | {
+    kind: "r";
+    id: string;
+} | {
+    kind: "m";
+    id: string;
+} | {
+    kind: "d";
+    id: string;
+};
+export declare function setPendingOps(result: ResolveResult, ops: ResolveMutationOp[]): void;

package/bin/comments/rate-limit.d.mts

@@ -0,0 +1,18 @@
+export interface ResolveRateLimitStop {
+    message: string;
+    retryAfterSeconds?: number;
+    limit?: number;
+    remaining?: number;
+    resetAt?: number;
+}
+export declare function rateLimitFromError(err: unknown, fallbackMessage: string): ResolveRateLimitStop | null;
+export declare function rateLimitFromGraphQlResult(messages: string[], meta: {
+    rateLimit?: {
+        remaining?: unknown;
+        limit?: unknown;
+        resetAt?: unknown;
+    };
+    retryAfterSeconds?: unknown;
+    stopOnZeroRemaining?: boolean;
+}): ResolveRateLimitStop | undefined;
+export declare function isRateLimitMessage(message: string): boolean;

package/bin/comments/resolve.d.mts

@@ -0,0 +1,34 @@
+import { type RepoInfo } from "../github/client.mts";
+import type { ResolveOptions } from "../types.mts";
+import { type ResolveRateLimitStop } from "./rate-limit.mts";
+export interface ResolveResult {
+    repliedThreads: string[];
+    resolvedThreads: string[];
+    minimizedComments: string[];
+    dismissedReviews: string[];
+    errors: string[];
+    skippedDismissals?: string[];
+    skippedHumanResolves?: string[];
+    skippedHumanMinimizes?: string[];
+    skippedHumanDismissals?: string[];
+    skippedNonHumanReplies?: string[];
+    rateLimit?: ResolveRateLimitStop;
+    unrepliedThreads?: string[];
+    unresolvedThreads?: string[];
+    unminimizedComments?: string[];
+    undismissedReviews?: string[];
+}
+export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: ResolveOptions): Promise<ResolveResult>;
+/** @deprecated Compatibility alias; use `autoResolveThreads`. */
+export declare function autoResolveOutdated(threadIds: string[]): Promise<{
+    resolved: string[];
+    errors: string[];
+}>;
+export declare function autoResolveThreads(threadIds: string[]): Promise<{
+    resolved: string[];
+    errors: string[];
+}>;
+export declare function autoMinimizeComments(minimizeIds: string[]): Promise<{
+    minimized: string[];
+    errors: string[];
+}>;

package/bin/comments/resolve.mjs

@@ -56,6 +56,7 @@ export async function applyResolveOptions(pr, repo, opts) {
     await bulkApply(replyThreadIds, resolveThreadIds, minimizeCommentIds, filteredDismissReviewIds, opts.dismissMessage ?? "", result);
     return result;
 }
+/** @deprecated Compatibility alias; use `autoResolveThreads`. */
 export async function autoResolveOutdated(threadIds) {
     return autoResolveThreads(threadIds);
 }

package/bin/comments/review-thread-markers.d.mts

@@ -0,0 +1,8 @@
+import type { ReviewThread } from "../types.mts";
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function markReviewInlineThreadMarkers(key: StateKey, threads: readonly ReviewThread[]): Promise<void>;
+export {};

package/bin/comments/review-visibility.d.mts

@@ -0,0 +1,28 @@
+import { type SeenMarker } from "../state/seen-comments.mts";
+import { type NormalizedBotUsernames } from "./authors.mts";
+import type { Review } from "../types.mts";
+interface ReviewVisibility {
+    visible: Review[];
+    toMarkSeen: Review[];
+}
+export declare function classifyReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>): ReviewVisibility;
+/**
+ * Bot CHANGES_REQUESTED reviews are different from every other surfaceable
+ * item: the agent — not the author — is responsible for dismissing them via
+ * `--dismiss-review-ids` after a fix push. If the agent forgets, the review
+ * stays in `CHANGES_REQUESTED` state and silently blocks the PR.
+ *
+ * The standard seen-gate (`classifyReviewsForDisplay`) suppresses items with
+ * unchanged bodies, which would also drop the bot CR ID from the
+ * `--dismiss-review-ids` flag — making the bug irrecoverable. This function
+ * keeps every bot CR in the visible set on every tick, using the seen-map
+ * only to pick the render form:
+ *
+ * - `new` / `edited` → full bullet (caller renders body normally).
+ * - `unchanged` → flagged `staleBotCr: true` so the formatter emits a terse
+ *   one-line reminder.
+ *
+ * Human-authored CR reviews continue to flow through the standard seen-gate.
+ */
+export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames): ReviewVisibility;
+export {};

package/bin/comments/sha-poll.d.mts

@@ -0,0 +1,2 @@
+import { type RepoInfo } from "../github/client.mts";
+export declare function waitForSha(pr: number, repo: RepoInfo, expectedSha: string): Promise<void>;

package/bin/comments/thread-visibility.d.mts

@@ -0,0 +1,11 @@
+import { type SeenMarker } from "../state/seen-comments.mts";
+import { type NormalizedBotUsernames } from "./authors.mts";
+import type { FirstLookThread, ReviewThread } from "../types.mts";
+interface ThreadVisibility {
+    activeThreads: ReviewThread[];
+    resolutionOnlyThreads: ReviewThread[];
+    firstLookThreads: FirstLookThread[];
+    toMarkSeen: ReviewThread[];
+}
+export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames): ThreadVisibility;
+export {};

package/bin/comments/visible-comments.d.mts

@@ -0,0 +1,11 @@
+import { type SeenMarker } from "../state/seen-comments.mts";
+import type { MinimizeCommentsPolicy } from "../config/load.mts";
+import type { ActionableComment, PrComment } from "../types.mts";
+import type { NormalizedBotUsernames } from "./authors.mts";
+interface VisibleCommentClassification {
+    actionable: ActionableComment[];
+    minimizeIds: string[];
+    toMarkSeen: ActionableComment[];
+}
+export declare function classifyVisibleComments(comments: PrComment[], seenMap: Map<string, SeenMarker>, minimizeComments: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames): VisibleCommentClassification;
+export {};

package/bin/config/load.d.mts

@@ -0,0 +1,60 @@
+declare const MINIMIZE_COMMENTS_POLICIES: readonly ["all", "bots", "users", "none"];
+export type MinimizeCommentsPolicy = (typeof MINIMIZE_COMMENTS_POLICIES)[number];
+interface PrShepherdConfig {
+    /** Optional user classification configuration; preserved for rule consumers. */
+    classify?: unknown;
+    /** GitHub logins that should be treated as bots even when GitHub reports User/Unknown. */
+    botUsernames: string[];
+    /** Case-insensitive glob patterns for check/status context names Shepherd should ignore. */
+    ignoreChecks: string[];
+    iterate: {
+        fixAttemptsPerThread: number;
+        stallTimeoutMinutes: number;
+        /**
+         * When `true`, APPROVED-state reviews are also eligible for minimization — defaults to `false`
+         * so approvals stay visible. `minimizeComments` still filters by GitHub author type.
+         */
+        minimizeApprovals: boolean;
+        /**
+         * Which GitHub author classes should be auto-minimized for minimizable PR comments and review
+         * summaries. Items excluded by this policy are still surfaced once (and after edits) via seen
+         * markers so they do not repeat forever.
+         */
+        minimizeComments: MinimizeCommentsPolicy;
+        /**
+         * One-liner hint appended to the `fix_code` push instruction when the branch is behind its
+         * base — e.g. "rebase --force-with-lease" or "see .agents/skills/git-and-prs.md". Empty
+         * (default) omits the hint entirely; the CLI never prescribes rebase/merge mechanics itself.
+         */
+        behindBaseHint: string;
+    };
+    watch: {
+        readyDelayMinutes: number;
+    };
+    resolve: {
+        shaPoll: {
+            intervalMs: number;
+            maxAttempts: number;
+        };
+    };
+    checks: {
+        ciTriggerEvents: string[];
+    };
+    mergeStatus: {
+        blockingReviewerLogins: string[];
+    };
+    actions: {
+        autoMinimizeSuppressed: boolean;
+        autoMarkReady: boolean;
+        /** Case-insensitive glob patterns for workflow/check names Shepherd must not cancel. */
+        neverCancelRuns: string[];
+        /** @deprecated Accepted for compatibility, ignored by the loader. */
+        autoResolveOutdated?: boolean;
+        /** @deprecated Accepted for compatibility, ignored by the loader. */
+        commitSuggestions?: boolean;
+    };
+}
+export declare function loadConfig(): PrShepherdConfig;
+/** Reset the config cache — for use in tests that change directories. */
+export declare function _resetConfigCache(): void;
+export {};