pr-shepherd 0.33.0 → 0.35.0

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

@@ -2,6 +2,7 @@
 import { graphql, graphqlWithRateLimit, getCurrentPrNumber, getRepoInfo, } from "../github/client.mjs";
 import { paginateForward } from "../github/pagination.mjs";
 import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "../comments/rate-limit.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
@@ -22,11 +23,13 @@ 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());
-    if (!prNumber)
-        throw new Error("No PR number provided and no current branch PR found");
+    if (!prNumber) {
+        throw new ShepherdError("No PR number provided and no current branch PR found", EXIT.UNAVAILABLE);
+    }
     const matchPatterns = opts.matchPatterns ?? [];
     const matchRegexes = matchPatterns.map((pattern) => compilePattern(pattern));
     const fetched = await fetchPullRequestFiles(prNumber, repo);
@@ -61,7 +64,7 @@ async function fetchPullRequestFiles(pr, repo) {
     });
     const raw = first.data.repository?.pullRequest;
     if (!raw)
-        throw new Error(`PR #${pr} not found`);
+        throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
     let files = raw.files.nodes;
     if (raw.files.pageInfo.hasNextPage && raw.files.pageInfo.endCursor) {
         const extra = await paginateForward(async (cursor) => {
@@ -73,7 +76,7 @@ async function fetchPullRequestFiles(pr, repo) {
             });
             const pr2 = res.data.repository?.pullRequest;
             if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+                throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
             return pr2.files;
         }, raw.files.pageInfo.endCursor);
         files = [...files, ...extra];
@@ -86,7 +89,7 @@ function compilePattern(pattern) {
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        throw new Error(`Invalid --match regex ${JSON.stringify(pattern)}: ${msg}`);
+        throw new ShepherdError(`Invalid --match regex ${JSON.stringify(pattern)}: ${msg}`, EXIT.USAGE);
     }
 }
 function selectChangedFiles(changedFiles, opts) {

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

@@ -6,11 +6,13 @@ import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "..
 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());
     if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const { data } = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true });
     const config = loadConfig();

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

package/bin/config/load.mjs

@@ -1,8 +1,10 @@
+/* eslint-disable max-lines */
 import { readFileSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
+import { getEffectiveCwd } from "../execution-context.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 function findRcFile(startDir) {
@@ -41,6 +43,10 @@ function isMinimizeCommentsPolicy(value) {
     return MINIMIZE_COMMENTS_POLICIES.some((policy) => policy === value);
 }
 function parseMinimizeCommentsPolicy(value) {
+    if (value === "users") {
+        process.stderr.write('pr-shepherd: config: iterate.minimizeComments: "users" is deprecated and is now treated as "none".\n');
+        return "none";
+    }
     if (isMinimizeCommentsPolicy(value))
         return value;
     throw new Error(`Invalid config: iterate.minimizeComments must be one of "all", "bots", "users", or "none", got ${JSON.stringify(value)}`);
@@ -63,10 +69,64 @@ function parseNeverCancelRuns(value) {
     }
     return value;
 }
+const KNOWN_CONFIG_KEYS = new Set([
+    "classify",
+    "botUsernames",
+    "ignoreChecks",
+    "iterate",
+    "watch",
+    "resolve",
+    "checks",
+    "mergeStatus",
+    "actions",
+]);
+const KNOWN_NESTED_KEYS = {
+    iterate: new Set([
+        "fixAttemptsPerThread",
+        "stallTimeoutMinutes",
+        "minimizeApprovals",
+        "minimizeComments",
+        "behindBaseHint",
+    ]),
+    watch: new Set(["readyDelayMinutes"]),
+    resolve: new Set(["shaPoll"]),
+    checks: new Set(["ciTriggerEvents"]),
+    mergeStatus: new Set(["blockingReviewerLogins"]),
+    actions: new Set([
+        "autoMinimizeSuppressed",
+        "autoMarkReady",
+        "neverCancelRuns",
+        "autoResolveOutdated",
+        "commitSuggestions",
+    ]),
+};
+function warnUnknownConfigKeys(config) {
+    for (const key of Object.keys(config)) {
+        if (!KNOWN_CONFIG_KEYS.has(key)) {
+            process.stderr.write(`pr-shepherd: config: unknown key "${key}" ignored.\n`);
+            delete config[key];
+            continue;
+        }
+        const value = config[key];
+        const nested = KNOWN_NESTED_KEYS[key];
+        if (nested === undefined ||
+            value === null ||
+            typeof value !== "object" ||
+            Array.isArray(value)) {
+            continue;
+        }
+        for (const child of Object.keys(value)) {
+            if (!nested.has(child)) {
+                process.stderr.write(`pr-shepherd: config: unknown key "${key}.${child}" ignored.\n`);
+                delete value[child];
+            }
+        }
+    }
+}
 const defaults = builtins;
 const configCache = new Map();
 export function loadConfig() {
-    const cwd = process.cwd();
+    const cwd = getEffectiveCwd();
     if (configCache.has(cwd))
         return configCache.get(cwd);
     const rcPath = findRcFile(cwd);
@@ -77,6 +137,17 @@ export function loadConfig() {
     try {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
+        const rawActions = parsed.actions;
+        if (rawActions !== null && typeof rawActions === "object" && !Array.isArray(rawActions)) {
+            const actions = rawActions;
+            for (const key of ["autoResolveOutdated", "commitSuggestions"]) {
+                if (key in actions) {
+                    process.stderr.write(`pr-shepherd: config: actions.${key} is deprecated and ignored.\n`);
+                    delete actions[key];
+                }
+            }
+        }
+        warnUnknownConfigKeys(parsed);
         const config = deepMerge(defaults, parsed);
         config.botUsernames = parseBotUsernames(config.botUsernames);
         config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);

package/bin/config.json

@@ -37,10 +37,8 @@
     "blockingReviewerLogins": ["copilot"]
   },
   "actions": {
-    "autoResolveOutdated": true,
     "autoMinimizeSuppressed": true,
     "autoMarkReady": true,
-    "commitSuggestions": true,
     "neverCancelRuns": []
   }
 }

package/bin/execution-context.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Runs work with an optional working directory without changing Node's global
+ * process state. This keeps independent API/MCP requests safe to run together.
+ */
+export declare function runWithExecutionCwd<T>(cwd: string | undefined, work: () => T): T;
+/** The caller-scoped working directory, when one was supplied. */
+export declare function getExecutionCwd(): string | undefined;
+/** The caller-scoped working directory, falling back to the CLI process cwd. */
+export declare function getEffectiveCwd(): string;

package/bin/execution-context.mjs

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const executionContext = new AsyncLocalStorage();
+/**
+ * Runs work with an optional working directory without changing Node's global
+ * process state. This keeps independent API/MCP requests safe to run together.
+ */
+export function runWithExecutionCwd(cwd, work) {
+    if (cwd === undefined)
+        return work();
+    return executionContext.run({ cwd }, work);
+}
+/** The caller-scoped working directory, when one was supplied. */
+export function getExecutionCwd() {
+    return executionContext.getStore()?.cwd;
+}
+/** The caller-scoped working directory, falling back to the CLI process cwd. */
+export function getEffectiveCwd() {
+    return getExecutionCwd() ?? process.cwd();
+}