pr-shepherd 0.34.0 → 0.36.0

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,12 @@
+import type { IterateCommandOptions, IterateResult } from "../types.mts";
+interface PollCommandOptions extends IterateCommandOptions {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    /** Settle window after first FIX_CODE before returning. Default 60. 0 disables. */
+    debounceSeconds?: 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

@@ -1,5 +1,6 @@
 import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
+const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
     if (verbose) {
         process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
@@ -54,10 +55,18 @@ function writeWaitProgress(opts) {
     }
     return signature;
 }
+function writeDebounceProgress(tick, elapsedMs, remainingMs) {
+    const elapsedSeconds = Math.round(elapsedMs / 1000);
+    const remainingSeconds = Math.round(remainingMs / 1000);
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
+}
+/** @deprecated Hidden implementation for the legacy `poll` alias. */
 export async function runPoll(opts) {
-    const { intervalSeconds, timeoutSeconds, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
+    const { intervalSeconds, timeoutSeconds, debounceSeconds: debounceSecondsOpt, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
     const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
+    const debounceSeconds = debounceSecondsOpt ?? DEFAULT_POLL_DEBOUNCE_SECONDS;
+    const debounceMs = Math.min(debounceSeconds * 1000, MAX_TIMER_MS);
     const start = Date.now();
     let tick = 0;
     let lastResult;
@@ -72,27 +81,30 @@ export async function runPoll(opts) {
     // terminal CANCEL/merged result. Pin the PR resolved by the first tick so later ticks target it
     // directly and never re-run branch discovery.
     let prNumber = opts.prNumber;
+    let debounceUntil = null;
     while (true) {
         tick += 1;
-        lastResult = await runIterate({ ...iterateOpts, prNumber });
+        const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
+        lastResult = await runIterate({
+            ...iterateOpts,
+            prNumber,
+            persistSeen: debounceSeconds === 0 || pastDebounce,
+        });
         prNumber ??= lastResult.pr;
-        if (lastResult.action !== "wait" && !(untilTerminal && lastResult.action === "mark_ready")) {
-            break;
-        }
-        const elapsedMs = Date.now() - start;
-        if (!untilTerminal) {
-            const remainingMs = timeoutMs - elapsedMs;
-            if (remainingMs <= 0)
-                break;
-            if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
-                break;
-        }
-        const nextSleepMs = intervalMs;
-        if (lastResult.action === "wait") {
+        if (lastResult.action === "wait" && !pastDebounce) {
+            debounceUntil = null;
+            const elapsedMs = Date.now() - start;
+            if (!untilTerminal) {
+                const remainingMs = timeoutMs - elapsedMs;
+                if (remainingMs <= 0)
+                    break;
+                if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
+                    break;
+            }
             lastWaitSignature = writeWaitProgress({
                 tick,
                 elapsedMs,
-                sleepMs: nextSleepMs,
+                sleepMs: intervalMs,
                 result: lastResult,
                 quietStatus,
                 verbose,
@@ -100,8 +112,31 @@ export async function runPoll(opts) {
             });
             if (!quietStatus && !verbose)
                 dotsPrinted = true;
+            await sleep(intervalMs);
+            continue;
+        }
+        if (untilTerminal && lastResult.action === "mark_ready" && !pastDebounce) {
+            debounceUntil = null;
+            await sleep(intervalMs);
+            continue;
+        }
+        if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+            debounceUntil ??= Date.now() + debounceMs;
+            const remainingMs = debounceUntil - Date.now();
+            if (remainingMs > 0) {
+                if (dotsPrinted) {
+                    process.stderr.write("\n");
+                    dotsPrinted = false;
+                }
+                writeDebounceProgress(tick, Date.now() - start, remainingMs);
+                await sleep(Math.min(intervalMs, remainingMs));
+            }
+            // Always continue so a tick that *started* before debounceUntil but *finished*
+            // after it cannot return with persistSeen: false. The next loop iteration
+            // sees pastDebounce and persists.
+            continue;
         }
-        await sleep(nextSleepMs);
+        break;
     }
     if (dotsPrinted)
         process.stderr.write("\n");

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-delay.mjs

@@ -6,9 +6,8 @@
  * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
  */
 import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
-import { join, dirname } from "node:path";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "../state/base.mjs";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "../state/base.mjs";
 /**
  * Update the ready-delay state machine and return the current decision.
  *
@@ -57,16 +56,7 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
 // Helpers
 // ---------------------------------------------------------------------------
 function readySincePath(pr, owner, repo) {
-    for (const [field, value] of [
-        ["owner", owner],
-        ["repo", repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid path segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${owner}-${repo}`, String(pr), "ready-since.txt");
+    return resolvePrStatePath({ owner, repo, pr }, "ready-since.txt");
 }
 async function safeUnlink(path) {
     try {

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 {};