pr-shepherd 0.47.0 → 0.49.0

package/bin/cli/poll-summary-formatter.mjs

@@ -0,0 +1,96 @@
+import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
+import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+export function formatPollSummaryResult(result) {
+    const selection = result.selection.kind === "stack"
+        ? `stack #${result.selection.stackNumber} anchored at PR #${result.selection.anchor} (${result.selection.stackSize} PRs)`
+        : `PRs ${result.selection.requested.map((pr) => `#${pr}`).join(", ")}`;
+    const lines = [
+        `# Poll summary [${result.reason.toUpperCase()}]`,
+        "",
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\``,
+        "",
+        "## Pull requests",
+        "",
+        ...result.prs.map(formatItem),
+    ];
+    const apiUsage = result.apiUsage ? formatApiUsage(result.apiUsage) : null;
+    const quotaWarning = formatQuotaWarning(result.quotaWarning);
+    if (quotaWarning)
+        lines.push("", quotaWarning);
+    if (apiUsage)
+        lines.push("", apiUsage);
+    lines.push("", "## Instructions", "", ...formatInstructions(result));
+    return lines.join("\n");
+}
+function formatInstructions(result) {
+    if (result.reason === "all_terminal")
+        return ["1. Stop — every selected PR is terminal."];
+    if (result.quotaWarning && result.reason !== "actionable") {
+        return [
+            buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
+        ];
+    }
+    if (result.reason === "waiting" || result.reason === "timeout") {
+        return ["1. Run this aggregate selector again when the caller is ready to recheck."];
+    }
+    const instructions = [
+        "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",
+        "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
+        "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
+    ];
+    if (result.quotaWarning) {
+        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
+    }
+    return instructions;
+}
+function formatItem(item) {
+    const flags = [item.isDraft ? "draft" : null, item.isInMergeQueue ? "queued" : null]
+        .filter((value) => value !== null)
+        .join(", ");
+    const stack = item.stack
+        ? ` · stack \`${item.stack.number}\` position \`${item.stack.position}/${item.stack.size}\` base \`${item.stack.baseRefName}\``
+        : "";
+    const reviewDecision = item.reviewDecision ? ` · reviewDecision \`${item.reviewDecision}\`` : "";
+    const stateFlags = flags ? ` · flags \`${flags}\`` : "";
+    const blockingReviewer = item.blockingReviewerInProgress
+        ? " · blocking reviewer `in progress`"
+        : "";
+    const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
+    const checks = item.checks;
+    const review = item.review;
+    return [
+        `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${stack}`,
+        `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
+        ...(checks
+            ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
+            : []),
+        ...(review
+            ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
+            : []),
+        `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
+        ...(item.pollCommand ? [`  - pollCommand: \`${item.pollCommand}\``] : []),
+    ].join("\n");
+}
+function formatCounts(counts, suffix) {
+    const plural = { inProgress: "in progress" };
+    const singular = {
+        comments: "comment",
+        inProgress: "in progress",
+        reviews: "review",
+        threads: "thread",
+    };
+    const rendered = Object.entries(counts)
+        .filter(([, count]) => typeof count === "number")
+        .map(([name, count]) => `${count} ${count === 1 ? (singular[name] ?? name) : (plural[name] ?? name)}`)
+        .join(", ");
+    return rendered ? `${rendered}${suffix}` : suffix.replace(/^, /, "");
+}
+function escapeMarkdownText(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/[\r\n]+/g, " ")
+        .replace(/([\\[\]])/g, "\\$1");
+}

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

@@ -0,0 +1,15 @@
+import { type RepoInfo } from "../github/client.mts";
+import { type ParsedPrReference } from "../pr-reference.mts";
+import type { GlobalOptions } from "../types.mts";
+export interface ParsedPollTargets {
+    refs: ParsedPrReference[];
+    stack: ParsedPrReference | undefined;
+    global: GlobalOptions;
+    extra: string[];
+}
+export declare function parsePollTargets(args: string[]): ParsedPollTargets | null;
+export declare function resolvePollTargets(parsed: ParsedPollTargets): Promise<{
+    prNumbers: number[];
+    stackPrNumber?: number;
+    targetRepository?: RepoInfo;
+}>;

package/bin/cli/poll-targets.mjs

@@ -0,0 +1,114 @@
+import { parseArgs } from "node:util";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { getRepoInfo } from "../github/client.mjs";
+import { parseCliPrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "../pr-reference.mjs";
+const VALUE_FLAGS = new Set([
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--interval",
+    "--timeout",
+    "--debounce",
+    "--stack",
+]);
+export function parsePollTargets(args) {
+    const { values } = parseArgs({
+        args,
+        strict: false,
+        allowPositionals: true,
+        options: { format: { type: "string" }, verbose: { type: "boolean" } },
+    });
+    const consumed = new Set();
+    const refs = [];
+    let stack;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (VALUE_FLAGS.has(arg)) {
+            if (arg === "--format" || arg === "--stack") {
+                consumed.add(index);
+                if (index + 1 < args.length)
+                    consumed.add(index + 1);
+            }
+            if (arg === "--stack") {
+                const parsed = parseCliPrReference(args[index + 1] ?? "");
+                if (!parsed)
+                    return usage(`invalid --stack PR reference: ${args[index + 1] ?? "(missing)"}`);
+                if (stack)
+                    return usage("--stack may only be specified once");
+                stack = parsed;
+            }
+            index += 1;
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        const name = equals < 0 ? arg : arg.slice(0, equals);
+        if (VALUE_FLAGS.has(name)) {
+            if (name === "--format" || name === "--stack")
+                consumed.add(index);
+            if (name === "--stack") {
+                const parsed = parseCliPrReference(arg.slice(equals + 1));
+                if (!parsed)
+                    return usage(`invalid --stack PR reference: ${arg.slice(equals + 1)}`);
+                if (stack)
+                    return usage("--stack may only be specified once");
+                stack = parsed;
+            }
+            continue;
+        }
+        if (arg === "--verbose") {
+            consumed.add(index);
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        const parsed = parseCliPrReference(arg);
+        if (!parsed)
+            continue;
+        refs.push(parsed);
+        consumed.add(index);
+    }
+    if (stack && refs.length > 0)
+        return usage("--stack cannot be combined with explicit PRs");
+    const format = (values.format ?? "text");
+    return {
+        refs,
+        stack,
+        global: { format, verbose: values.verbose === true },
+        extra: args.filter((_, index) => !consumed.has(index)),
+    };
+}
+export async function resolvePollTargets(parsed) {
+    const all = parsed.stack ? [parsed.stack] : parsed.refs;
+    if (all.length === 0)
+        return { prNumbers: [] };
+    const checkoutRepo = all.some((ref) => ref.repository === undefined)
+        ? await getRepoInfo()
+        : undefined;
+    let selectedRepo;
+    const prNumbers = [];
+    for (const ref of all) {
+        const target = resolveParsedPrTarget(ref);
+        if (target.prNumber === undefined)
+            return usageThrow("PR number is required");
+        const repo = target.targetRepository ?? checkoutRepo;
+        if (selectedRepo &&
+            normalizeRepositoryIdentity(`${selectedRepo.owner}/${selectedRepo.name}`) !==
+                normalizeRepositoryIdentity(`${repo.owner}/${repo.name}`)) {
+            return usageThrow("aggregate poll only supports PRs from one repository");
+        }
+        selectedRepo = repo;
+        if (!prNumbers.includes(target.prNumber))
+            prNumbers.push(target.prNumber);
+    }
+    return parsed.stack
+        ? { prNumbers: [], stackPrNumber: prNumbers[0], targetRepository: selectedRepo }
+        : { prNumbers, targetRepository: selectedRepo };
+}
+function usage(message) {
+    process.stderr.write(`pr-shepherd: ${message}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}
+function usageThrow(message) {
+    throw new ShepherdError(message, EXIT.USAGE);
+}

package/bin/cli/validate-default-args.mjs

@@ -5,7 +5,6 @@ import { parsePrNumber } from "./args.mjs";
  * offending arg so callers can print their own usage message.
  */
 export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError) {
-    let sawPr = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (flagsWithValues.has(arg)) {
@@ -21,10 +20,8 @@ export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError
             continue;
         if (booleanFlags.has(arg))
             continue;
-        if (parsePrNumber(arg) !== null && !sawPr) {
-            sawPr = true;
+        if (parsePrNumber(arg) !== null)
             continue;
-        }
         onError(arg);
         return false;
     }

package/bin/commands/iterate/api-usage.d.mts

@@ -1,2 +1,2 @@
 import type { IterateResult } from "../../types.mts";
-export declare function attachApiUsage(result: IterateResult, persistWarning: boolean, preservePersistedWarning?: boolean): Promise<IterateResult>;
+export declare function attachApiUsage(result: IterateResult, persistWarning: boolean, preservePersistedWarning?: boolean, minimumPollIntervalMinutes?: number): Promise<IterateResult>;

package/bin/commands/iterate/api-usage.mjs

@@ -5,7 +5,7 @@ import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
     return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
 }
-export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false) {
+export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false, minimumPollIntervalMinutes = 0) {
     const apiUsage = summarizeApiTelemetry();
     if (apiUsage === undefined)
         return result;
@@ -13,7 +13,11 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
     if (quotaWarning === undefined && apiUsage.graphql !== undefined && shouldWarn(result)) {
         const [owner, repo] = result.repo.split("/");
         if (owner && repo) {
-            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, loadConfig().watch.graphqlQuotaWarnings, apiUsage.graphql, persistWarning);
+            const bands = loadConfig().watch.graphqlQuotaWarnings.map((band) => ({
+                ...band,
+                pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
+            }));
+            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, apiUsage.graphql, persistWarning);
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;

package/bin/commands/iterate/run.mjs

@@ -3,6 +3,6 @@ import { attachApiUsage } from "./api-usage.mjs";
 export function withIterateApiUsage(opts, runCore) {
     return withApiTelemetryScope(async () => {
         const result = await runCore();
-        return attachApiUsage(result, opts.deferQuotaWarning !== true);
+        return attachApiUsage(result, opts.deferQuotaWarning !== true, false, opts.quotaWarningMinimumPollIntervalMinutes);
     });
 }

package/bin/commands/poll-run.d.mts

@@ -1,2 +1,2 @@
 import type { IterateResult } from "../types.mts";
-export declare function withPollApiUsage(runCore: () => Promise<IterateResult>, preservePersistedWarning: boolean): Promise<IterateResult>;
+export declare function withPollApiUsage(runCore: () => Promise<IterateResult>, preservePersistedWarning: boolean, minimumPollIntervalMinutes: number): Promise<IterateResult>;

package/bin/commands/poll-run.mjs

@@ -1,8 +1,8 @@
 import { withApiTelemetryScope } from "../github/api-telemetry.mjs";
 import { attachApiUsage } from "./iterate/api-usage.mjs";
-export function withPollApiUsage(runCore, preservePersistedWarning) {
+export function withPollApiUsage(runCore, preservePersistedWarning, minimumPollIntervalMinutes) {
     return withApiTelemetryScope(async () => {
         const result = await runCore();
-        return attachApiUsage(result, true, preservePersistedWarning);
+        return attachApiUsage(result, true, preservePersistedWarning, minimumPollIntervalMinutes);
     });
 }

package/bin/commands/poll-summary.d.mts

@@ -0,0 +1,10 @@
+import type { PollSummaryCommandOptions, PollSummaryResult } from "../types.mts";
+export interface AggregatePollCommandOptions extends PollSummaryCommandOptions {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    debounceSeconds?: number;
+    quietStatus?: boolean;
+    untilTerminal?: boolean;
+}
+export declare function runPollSummary(opts: PollSummaryCommandOptions): Promise<PollSummaryResult>;
+export declare function runAggregatePoll(opts: AggregatePollCommandOptions): Promise<PollSummaryResult>;

package/bin/commands/poll-summary.mjs

@@ -0,0 +1,163 @@
+import { loadConfig } from "../config/load.mjs";
+import { ShepherdError } from "../exit-codes.mjs";
+import { getRepoInfo } from "../github/client.mjs";
+import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
+import { fetchPollSummary } from "../github/poll-summary.mjs";
+import { sleep } from "../util/sleep.mjs";
+import { graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs } from "./poll-quota.mjs";
+import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const TIMER_DRIFT_TOLERANCE_MS = 500;
+export function runPollSummary(opts) {
+    return withApiTelemetryScope(async () => attachUsage(await runPollSummaryCore(opts)));
+}
+export function runAggregatePoll(opts) {
+    return withApiTelemetryScope(() => runAggregatePollCore(opts));
+}
+async function runPollSummaryCore(opts) {
+    const repo = opts.targetRepository ?? (await getRepoInfo());
+    const fetched = await fetchPollSummary(opts, repo);
+    const allTerminal = fetched.prs.every((item) => item.action === "cancel");
+    const actionable = fetched.prs.some((item) => item.action !== "wait" && item.action !== "cancel");
+    return {
+        mode: "summary",
+        repo: `${repo.owner}/${repo.name}`,
+        selection: fetched.selection,
+        reason: allTerminal ? "all_terminal" : actionable ? "actionable" : "waiting",
+        prs: fetched.prs,
+    };
+}
+async function runAggregatePollCore(opts) {
+    const intervalMs = Math.min(opts.intervalSeconds * 1000, MAX_TIMER_MS);
+    const timeoutMs = Math.min(opts.timeoutSeconds * 1000, MAX_TIMER_MS);
+    const debounceMs = Math.min((opts.debounceSeconds ?? 60) * 1000, MAX_TIMER_MS);
+    const quotaBands = loadConfig().watch.graphqlQuotaWarnings;
+    const start = Date.now();
+    let tick = 0;
+    let debounceUntil = null;
+    let last;
+    let lastStatusSignature = null;
+    let rateLimitRetries = 0;
+    let pendingQuotaWarning;
+    while (true) {
+        tick += 1;
+        try {
+            last = await runPollSummaryCore(opts);
+            rateLimitRetries = 0;
+        }
+        catch (error) {
+            if (last?.selection.kind === "stack" && isMissingStack(error)) {
+                const explicit = await runPollSummaryCore({
+                    ...opts,
+                    stackPrNumber: undefined,
+                    prNumbers: last.prs.map((item) => item.pr),
+                });
+                if (explicit.prs.every((item) => item.action === "cancel")) {
+                    const warning = await aggregateQuotaWarning(explicit, quotaBands, opts.intervalSeconds);
+                    if (warning)
+                        pendingQuotaWarning = warning;
+                    return attachUsage({
+                        ...explicit,
+                        reason: "all_terminal",
+                        ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                    });
+                }
+            }
+            const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
+            if (retryMs === null || rateLimitRetries >= 1)
+                throw error;
+            rateLimitRetries += 1;
+            process.stderr.write(`[aggregate poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
+            await sleep(retryMs);
+            continue;
+        }
+        const allTerminal = last.prs.every((item) => item.action === "cancel");
+        const immediate = last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
+        const hasFix = last.prs.some((item) => item.action === "fix_code");
+        const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
+        if (warning)
+            pendingQuotaWarning = warning;
+        if (allTerminal) {
+            return attachUsage({
+                ...last,
+                reason: "all_terminal",
+                ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+            });
+        }
+        if (immediate) {
+            return attachUsage({
+                ...last,
+                reason: "actionable",
+                ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+            });
+        }
+        if (hasFix) {
+            if (debounceMs === 0)
+                return attachUsage({
+                    ...last,
+                    reason: "actionable",
+                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                });
+            debounceUntil ??= Date.now() + debounceMs;
+            if (Date.now() >= debounceUntil)
+                return attachUsage({
+                    ...last,
+                    reason: "actionable",
+                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                });
+        }
+        else {
+            debounceUntil = null;
+            if (opts.untilTerminal && pendingQuotaWarning) {
+                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning });
+            }
+        }
+        const elapsedMs = Date.now() - start;
+        const sleepMs = debounceUntil
+            ? Math.min(intervalMs, Math.max(debounceUntil - Date.now(), 0))
+            : graphqlQuotaPollIntervalMs(quotaBands, summarizeApiTelemetry()?.graphql, intervalMs, MAX_TIMER_MS);
+        if (!opts.untilTerminal && debounceUntil === null) {
+            const remainingMs = timeoutMs - elapsedMs;
+            if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
+                return attachUsage({ ...last, reason: "timeout" });
+            }
+        }
+        const statusSignature = summaryStatusSignature(last);
+        if (!opts.quietStatus || hasFix || statusSignature !== lastStatusSignature) {
+            process.stderr.write(`[aggregate poll tick ${tick} / +${Math.round(elapsedMs / 1000)}s] ${last.prs
+                .map((item) => `#${item.pr} ${item.action.toUpperCase()}`)
+                .join(", ")}\n`);
+        }
+        lastStatusSignature = statusSignature;
+        await sleep(sleepMs);
+    }
+}
+async function aggregateQuotaWarning(result, bands, intervalSeconds) {
+    const usage = summarizeApiTelemetry()?.graphql;
+    const [owner, repo] = result.repo.split("/");
+    if (!usage || !owner || !repo)
+        return undefined;
+    return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
+        ...band,
+        pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
+    })), usage, true);
+}
+function summaryStatusSignature(result) {
+    return JSON.stringify(result.prs.map((item) => ({
+        pr: item.pr,
+        action: item.action,
+        state: item.state,
+        mergeable: item.mergeable,
+        mergeStateStatus: item.mergeStateStatus,
+        reviewDecision: item.reviewDecision,
+        checks: item.checks,
+        review: item.review,
+    })));
+}
+function isMissingStack(error) {
+    return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
+}
+function attachUsage(result) {
+    const apiUsage = summarizeApiTelemetry();
+    return apiUsage ? { ...result, apiUsage } : result;
+}

package/bin/commands/poll.mjs

@@ -9,7 +9,7 @@ const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
 export function runPoll(opts) {
-    return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true);
+    return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true, opts.intervalSeconds / 60);
 }
 async function runPollCore(opts) {
     const { intervalSeconds, timeoutSeconds, debounceSeconds: debounceSecondsOpt, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
@@ -45,6 +45,7 @@ async function runPollCore(opts) {
             persistSeen: debounceSeconds === 0 || pastDebounce,
             fingerprintCache,
             deferQuotaWarning: !untilTerminal,
+            quotaWarningMinimumPollIntervalMinutes: intervalSeconds / 60,
         });
         const runTick = async (fingerprintCache) => {
             try {

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

@@ -25,5 +25,7 @@ interface ReadyDelayState {
  * 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 declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string, options?: {
+    retainElapsed?: boolean;
+}): Promise<ReadyDelayState>;
 export {};

package/bin/commands/ready-delay.mjs

@@ -18,7 +18,7 @@ import { resolvePrStatePath } from "../state/base.mjs";
  * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
  * the loop and tells one-shot agents to stop.
  */
-export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo) {
+export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo, options = {}) {
     const markerPath = readySincePath(prNumber, owner, repo);
     if (!isReady) {
         // Reset the timer.
@@ -47,7 +47,8 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
     const elapsed = now - readySince;
     const remaining = readyDelaySeconds - elapsed;
     if (remaining <= 0) {
-        await safeUnlink(markerPath);
+        if (!options.retainElapsed)
+            await safeUnlink(markerPath);
         return { isReady: true, shouldCancel: true, remainingSeconds: 0 };
     }
     return { isReady: true, shouldCancel: false, remainingSeconds: remaining };

package/bin/config/load.d.mts

@@ -6,6 +6,12 @@ export interface GraphqlQuotaWarningBand {
     remainingPercent: number;
     pollIntervalMinutes: number;
 }
+interface PollConfig {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    debounceSeconds: number;
+    quietStatus: boolean;
+}
 export interface PrShepherdConfig {
     /** Optional user classification configuration; preserved for rule consumers. */
     classify?: unknown;
@@ -40,6 +46,7 @@ export interface PrShepherdConfig {
          */
         resolveOtherHumanThreads: ResolveOtherHumanThreads;
     };
+    poll: PollConfig;
     watch: {
         readyDelayMinutes: number;
         graphqlQuotaWarnings: GraphqlQuotaWarningBand[];