pr-shepherd 0.60.1 → 1.0.0

package/bin/commands/{event-mode.mjs → tick.mjs}

@@ -1,54 +1,30 @@
 import { loadConfig } from "../config/load.mjs";
 import { readStallState } from "../state/iterate-stall.mjs";
-import { runWithDurableState } from "../state/durable-state.mjs";
-import { eventAggregateStep, eventFixContinuation } from "./event-instructions.mjs";
+import { tickAggregateStep } from "./tick-instructions.mjs";
 import { earliestNextCheck, MERGE_QUEUE_RECHECK_SECONDS, nextCheckCandidates, SAFETY_NET_SECONDS, } from "./next-check.mjs";
-import { isFixCodeContinuation } from "./iterate/check-instructions.mjs";
 import { isHandedOffSelection, onlyDraftVerificationSelection, } from "./poll-summary-explicit-instructions.mjs";
 import { runIterate } from "./iterate/index.mjs";
-import { resolvePollMode } from "./poll-mode.mjs";
+import { runsSingleTick } from "./single-tick.mjs";
 import { readStackStallDeadline } from "./stack-stall.mjs";
 import { runPoll } from "./poll.mjs";
 import { runAggregatePoll, runPollSummary, } from "./poll-summary.mjs";
-function isEventMode(requested) {
-    return resolvePollMode(requested, loadConfig().poll.mode) === "event";
-}
 /**
- * One iterate tick. In event mode the tick runs exactly once with no settle window and no
- * sleeping, persists seen markers immediately, and reports when to come back.
+ * One iterate tick: no settle window and no sleeping, seen markers persist immediately, and
+ * `nextCheck` reports when to come back if no GitHub event arrives first. The tick's result is
+ * never discarded, so edited-comment markers are written on the result it returns.
  */
-export function runIterateForMode(opts) {
-    if (!isEventMode(opts.pollMode))
-        return runIterate(opts);
-    return runWithDurableState(() => runIterateEvent(opts));
-}
-/** One aggregate tick; event mode adds `pollMode` and `nextCheck`. */
-export function runPollSummaryForMode(opts) {
-    if (!isEventMode(opts.pollMode))
-        return runPollSummary(opts);
-    const eventOpts = { ...opts, pollMode: "event" };
-    return runWithDurableState(async () => withAggregateNextCheck(await runPollSummary(eventOpts), eventOpts));
-}
-/** The default poll command: the sleeping loop in poll mode, one tick in event mode. */
-export function runPollForMode(opts) {
-    if (!isEventMode(opts.pollMode))
-        return runPoll(opts);
-    const { intervalSeconds: _intervalSeconds, timeoutSeconds: _timeoutSeconds, debounceSeconds: _debounceSeconds, quietStatus: _quietStatus, untilTerminal: _untilTerminal, ...tick } = opts;
-    return runIterateForMode(tick);
-}
-/** The aggregate poll command: the sleeping loop in poll mode, one tick in event mode. */
-export function runAggregatePollForMode(opts) {
-    return isEventMode(opts.pollMode) ? runPollSummaryForMode(opts) : runAggregatePoll(opts);
-}
-async function runIterateEvent(opts) {
-    const { pollMode: _pollMode, ...iterateOpts } = opts;
+export async function runIterateTick(opts) {
     const sink = {};
     const result = await runIterate({
-        ...iterateOpts,
+        ...opts,
         persistSeen: true,
+        deferEditedCommentMarkers: false,
         fingerprintCache: false,
         stallDeadlineSink: sink,
     });
+    // `[TRIAGE]` already reruns at once, and that rerun reports its own `nextCheck`.
+    if (result.action === "triage")
+        return result;
     const nowMs = Date.now();
     const stallDeadlineSeconds = earliestDeadline(await readStallDeadline(result, opts.stallTimeoutSeconds), result.action === "wait" ? sink.ciStartDeadlineSeconds : undefined);
     const nextCheck = earliestNextCheck(nextCheckCandidates({
@@ -57,17 +33,23 @@ async function runIterateEvent(opts) {
         queued: result.mergeQueue?.inQueue === true,
         restMerge: result.action === "merge" && result.merge.mode === "rest",
         stallDeadlineSeconds,
-    }, nowMs), nowMs);
-    const tagged = { ...result, pollMode: "event", ...(nextCheck && { nextCheck }) };
-    if (tagged.action !== "fix_code" || !nextCheck)
-        return tagged;
-    return {
-        ...tagged,
-        fix: {
-            ...tagged.fix,
-            instructions: tagged.fix.instructions.map((step) => isFixCodeContinuation(step) ? eventFixContinuation(nextCheck) : step),
-        },
-    };
+    }, nowMs), nowMs, quotaFloorSeconds(result.quotaWarning));
+    return nextCheck ? { ...result, nextCheck } : result;
+}
+/** One aggregate tick, with `nextCheck` unless nothing remains to wait for. */
+export async function runPollSummaryTick(opts) {
+    return withAggregateNextCheck(await runPollSummary({ ...opts, tick: true }), opts);
+}
+/** The default command: the sleeping loop, or one tick in a cloud session. */
+export function runPollCommand(opts) {
+    if (!runsSingleTick())
+        return runPoll(opts);
+    const { intervalSeconds: _intervalSeconds, timeoutSeconds: _timeoutSeconds, debounceSeconds: _debounceSeconds, quietStatus: _quietStatus, untilTerminal: _untilTerminal, ...tick } = opts;
+    return runIterateTick(tick);
+}
+/** The aggregate loop (`stack`, several PRs), or one tick in a cloud session. */
+export function runAggregatePollCommand(opts) {
+    return runsSingleTick() ? runPollSummaryTick(opts) : runAggregatePoll(opts);
 }
 function earliestDeadline(...deadlines) {
     const known = deadlines.filter((d) => d !== undefined);
@@ -75,9 +57,9 @@ function earliestDeadline(...deadlines) {
 }
 /** When an unchanged state would trip the stall timeout, or undefined when no timer is running. */
 async function readStallDeadline(result, stallTimeoutSeconds) {
-    if (!["wait", "fix_code"].includes(result.action))
+    if (result.action !== "wait")
         return undefined;
-    const timeout = stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60;
+    const timeout = stallTimeoutSeconds ?? loadConfig().iterate["stall-timeout-minutes"] * 60;
     const [owner, repo] = result.repo.split("/");
     if (timeout <= 0 || !owner || !repo)
         return undefined;
@@ -85,23 +67,22 @@ async function readStallDeadline(result, stallTimeoutSeconds) {
     return read.ok && read.state ? read.state.firstSeenAt + timeout : undefined;
 }
 async function withAggregateNextCheck(result, opts) {
-    const tagged = { ...result, pollMode: "event" };
-    const stallDeadlineSeconds = await readStackStallDeadline(result, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
+    const stallDeadlineSeconds = await readStackStallDeadline(result, opts.stallTimeoutSeconds ?? loadConfig().iterate["stall-timeout-minutes"] * 60);
     const nextCheck = aggregateNextCheck(result, stallDeadlineSeconds);
     if (!nextCheck)
-        return tagged;
+        return result;
     const instructions = (result.instructions ?? []).map(withoutPollingCadence);
     const waiting = result.reason === "waiting" || result.reason === "timeout";
     return {
-        ...tagged,
+        ...result,
         nextCheck,
         instructions: [
             ...instructions,
-            `${instructions.length + 1}. ${eventAggregateStep(nextCheck, waiting)}`,
+            `${instructions.length + 1}. ${tickAggregateStep(nextCheck, waiting)}`,
         ],
     };
 }
-/** The appended event step owns timing, including pending stack merges. */
+/** The appended tick step owns timing, including pending stack merges. */
 function withoutPollingCadence(step) {
     return step
         .replace(/ Recheck(?: them)? at the configured polling cadence\./g, "")
@@ -130,5 +111,8 @@ function aggregateNextCheck(result, stallDeadlineSeconds) {
     if (stallDeadlineSeconds !== undefined) {
         candidates.push({ reason: "stall-timeout", seconds: stallDeadlineSeconds - nowMs / 1000 });
     }
-    return earliestNextCheck(candidates, nowMs);
+    return earliestNextCheck(candidates, nowMs, quotaFloorSeconds(result.quotaWarning));
+}
+function quotaFloorSeconds(warning) {
+    return warning === undefined ? 0 : warning.pollIntervalMinutes * 60;
 }

package/bin/comments/minimize-policy.mjs

@@ -9,11 +9,9 @@ export function shouldMinimizeAuthor(authorType, policy, author, botUsernames =
             return authorType !== "User" || isConfiguredBot;
         case "bots":
             return isConfiguredBot;
-        case "users":
-            return false;
         case "none":
             return false;
         default:
-            throw new Error(`Invalid minimizeComments policy: ${String(policy)}`);
+            throw new Error(`Invalid iterate.minimize-comments policy: ${String(policy)}`);
     }
 }

package/bin/comments/resolve.d.mts

@@ -8,24 +8,6 @@ export interface ResolveResult {
     minimizedComments: string[];
     dismissedReviews: string[];
     errors: string[];
-    /** @deprecated Direct apply forwards every supplied dismissal ID to GitHub. */
-    skippedDismissals?: string[];
-    /** @deprecated Direct apply no longer applies author policy. */
-    skippedHumanResolves?: string[];
-    /** @deprecated Direct apply no longer applies author policy. */
-    skippedHumanMinimizes?: string[];
-    /** @deprecated Direct apply no longer applies author policy. */
-    skippedHumanDismissals?: string[];
-    /** @deprecated Direct apply forwards every supplied reply ID to GitHub. */
-    skippedNonHumanReplies?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedReplies?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedResolves?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedMinimizes?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
     sessionRefusal?: string;
     instructions?: string[];
@@ -38,11 +20,6 @@ export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: Re
     headSha?: string;
     evidence: Map<string, ReplyEvidence>;
 }): 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[];

package/bin/comments/resolve.mjs

@@ -88,10 +88,6 @@ export async function applyResolveOptions(pr, repo, opts, preflight) {
         ];
     return result;
 }
-/** @deprecated Compatibility alias; use `autoResolveThreads`. */
-export async function autoResolveOutdated(threadIds) {
-    return autoResolveThreads(threadIds);
-}
 export async function autoResolveThreads(threadIds) {
     if (threadIds.length === 0)
         return { resolved: [], errors: [] };

package/bin/comments/review-output-budget.d.mts

@@ -1,5 +1,5 @@
 /**
- * Per-tick output budget for review items (see `iterate.reviewOutputMaxChars`).
+ * Per-tick output budget for review items (see `iterate.review-output-max-chars`).
  *
  * Fetching is complete; only the rendered volume is capped. When the bodies of every surfaced
  * review item fit the budget, nothing changes. Otherwise items are taken in a fixed priority

package/bin/comments/review-output-budget.mjs

@@ -1,5 +1,5 @@
 /**
- * Per-tick output budget for review items (see `iterate.reviewOutputMaxChars`).
+ * Per-tick output budget for review items (see `iterate.review-output-max-chars`).
  *
  * Fetching is complete; only the rendered volume is capped. When the bodies of every surfaced
  * review item fit the budget, nothing changes. Otherwise items are taken in a fixed priority

package/bin/comments/sha-poll.mjs

@@ -2,7 +2,9 @@ import { getPrHeadSha } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { sleep } from "../util/sleep.mjs";
 export async function waitForSha(pr, repo, expectedSha) {
-    const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
+    const apply = loadConfig().apply;
+    const SHA_POLL_INTERVAL_MS = apply["sha-poll-interval-seconds"] * 1000;
+    const SHA_POLL_MAX_ATTEMPTS = apply["sha-poll-max-attempts"];
     let lastSha;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
         try {

package/bin/config/default-bot-usernames.d.mts

@@ -0,0 +1,2 @@
+/** Built-in `bot-usernames`: known code-review bot logins treated as bots. */
+export declare const DEFAULT_BOT_USERNAMES: string[];

package/bin/config/default-bot-usernames.mjs

@@ -0,0 +1,15 @@
+/** Built-in `bot-usernames`: known code-review bot logins treated as bots. */
+export const DEFAULT_BOT_USERNAMES = [
+    "chatgpt-connector",
+    "openai-codex",
+    "codex",
+    "claude",
+    "copilot-pull-request-reviewer",
+    "gemini-code-assist",
+    "coderabbitai",
+    "greptile-apps",
+    "qodo-merge-pro",
+    "deepsource-io",
+    "sonarqubecloud",
+    "what-the-diff",
+];

package/bin/config/load.d.mts

@@ -1,143 +1,9 @@
-import { type MergeMethod } from "./merge-method.mts";
-import { type GithubTransport } from "../github/transport-mode.mts";
-declare const MINIMIZE_COMMENTS_POLICIES: readonly ["all", "bots", "users", "none"];
-export type MinimizeCommentsPolicy = (typeof MINIMIZE_COMMENTS_POLICIES)[number];
-declare const RESOLVE_OTHER_HUMAN_THREADS: readonly ["none", "outdated", "always"];
-export type ResolveOtherHumanThreads = (typeof RESOLVE_OTHER_HUMAN_THREADS)[number];
-export declare const INSTRUCTION_STYLES: readonly ["playbook", "inline"];
+import { type PrShepherdConfig } from "./resolve.mts";
+export type { GraphqlQuotaWarningBand, InstructionStyle, MinimizeCommentsPolicy, PrShepherdConfig, ResolveOtherHumanThreads, } from "./resolve.mts";
 /**
- * How `fix_code` `## Instructions` render invariant procedure text. `inline` (default)
- * prints every step each tick; `playbook` points at the shipped "Fix-code loop" playbook.
+ * Load the config for the effective cwd: built-in defaults, then `$HOME`, then each ancestor
+ * down to cwd, closest file winning. Any invalid file throws a `ShepherdError` (exit 78).
  */
-export type InstructionStyle = (typeof INSTRUCTION_STYLES)[number];
-export declare function isInstructionStyle(value: unknown): value is InstructionStyle;
-export declare const POLL_MODES: readonly ["auto", "poll", "event"];
-/**
- * `poll` blocks and loops. `event` runs one tick and reports `nextCheck`. `auto` resolves to
- * `event` when `CLAUDE_CODE_REMOTE=true` and to `poll` everywhere else.
- */
-export type PollMode = (typeof POLL_MODES)[number];
-export declare function isPollMode(value: unknown): value is PollMode;
-export interface GraphqlQuotaWarningBand {
-    remainingPercent: number;
-    pollIntervalMinutes: number;
-}
-interface PollConfig {
-    intervalSeconds: number;
-    /** Multiplier for aggregate polls when `--interval` is omitted. Finite and at least 1. */
-    stackIntervalFactor: number;
-    timeoutSeconds: number;
-    debounceSeconds: number;
-    quietStatus: boolean;
-    mode: PollMode;
-    /**
-     * Longest gap between GraphQL snapshots while conditional REST reads report an idle PR
-     * unchanged. `0` disables the REST change detectors on the GraphQL transport.
-     */
-    reconcileSeconds: number;
-}
-export interface PrShepherdConfig {
-    /** GitHub API settings; auto prefers GraphQL outside Claude Code cloud sessions. */
-    github?: {
-        transport?: GithubTransport;
-    };
-    /**
-     * Optional user classification configuration; preserved for rule consumers. Shepherd reads
-     * only `classify.standard`, a map of bundled rule name (or `all`) to boolean.
-     */
-    classify?: unknown;
-    /** Bundled classification rules enabled by `classify.standard`, resolved and sorted by name. */
-    standardRules: string[];
-    /** Argv prefix for every pr-shepherd command Shepherd emits, e.g. `["pnpm", "exec", "pr-shepherd"]`. */
-    cliCommand: string[];
-    /** 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;
-        /**
-         * Per-tick budget for review-item bodies in `fix_code` output, in characters. Over budget,
-         * iterate shows a priority-ordered subset and holds the rest (unmarked) for later ticks.
-         * `0` disables the cap.
-         */
-        reviewOutputMaxChars: number;
-        /**
-         * When to resolve other-human inline threads after Shepherd replies. Own and bot threads
-         * always reply-and-resolve. `none` (default) keeps other humans reply-only; `outdated`
-         * also resolves when GitHub reports `isOutdated`; `always` pairs reply-and-resolve.
-         */
-        resolveOtherHumanThreads: ResolveOtherHumanThreads;
-        /**
-         * `inline` (default) prints the commit/push step of `fix_code` instructions
-         * every tick; `playbook` folds it into one `Playbook: "Fix-code loop"` pointer. The
-         * default is inline because the token bench measured playbook as a net cost: it adds a read. The `--instructions` flag and MCP `instructions` input override per call.
-         */
-        instructions: InstructionStyle;
-    };
-    poll: PollConfig;
-    watch: {
-        readyDelayMinutes: number;
-        graphqlQuotaWarnings: GraphqlQuotaWarningBand[];
-    };
-    resolve: {
-        shaPoll: {
-            intervalMs: number;
-            maxAttempts: number;
-        };
-    };
-    checks: {
-        ciTriggerEvents: string[];
-        /** Regex patterns matched against each raw log line; matching lines are dropped from log excerpts. Empty by default — no lines are stripped unless configured. */
-        ignoreLogLines: string[];
-    };
-    mergeStatus: {
-        blockingReviewerLogins: string[];
-    };
-    merge?: {
-        /** Preferred merge method. Used only when the repository allows it. */
-        method?: MergeMethod;
-        /** Options added to ordinary `gh pr merge` commands. Queue commands never use these. */
-        commandArgs: string[];
-    };
-    actions: {
-        autoMinimizeSuppressed: boolean;
-        autoMarkReady: boolean;
-        /** Legacy-named patterns that keep matching Actions checks visible despite ignoreChecks. */
-        neverCancelRuns: string[];
-        /**
-         * When `false` (default), `iterate --merge` defers non-CI actionable work
-         * (review threads, comments, changes-requested reviews, review summaries)
-         * while the PR sits in the merge queue, since a Shepherd-initiated push
-         * would eject it. When `true`, restores pre-existing behavior: actionable
-         * work is handled immediately regardless of queue membership.
-         */
-        workWhileQueued: boolean;
-        /** @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 {};