pr-shepherd 0.56.5 → 0.57.0

package/bin/comments/review-visibility.mjs

@@ -31,7 +31,7 @@ export function classifyReviewsForDisplay(reviews, seenMap) {
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames, repeatBotReviews = true) {
+export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames, repeatBotReviews = true, deniedDismissalIds = new Set()) {
     const visible = [];
     const toMarkSeen = [];
     for (const review of reviews) {
@@ -39,8 +39,9 @@ export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botU
         const cls = classifyItem(review.id, review.body, seenMap);
         if (isBot) {
             if (cls === "unchanged") {
-                if (repeatBotReviews)
+                if (repeatBotReviews && !deniedDismissalIds.has(review.id)) {
                     visible.push({ ...review, staleBotCr: true });
+                }
             }
             else if (cls === "edited") {
                 visible.push({ ...review, edited: true });

package/bin/comments/sha-poll.mjs

@@ -3,11 +3,12 @@ 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;
+    let lastSha;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
         try {
             // eslint-disable-next-line no-await-in-loop
-            const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
-            if (currentSha === expectedSha)
+            lastSha = await getPrHeadSha(pr, repo.owner, repo.name);
+            if (lastSha === expectedSha)
                 return;
         }
         catch (err) {
@@ -19,5 +20,8 @@ export async function waitForSha(pr, repo, expectedSha) {
             await sleep(SHA_POLL_INTERVAL_MS);
         }
     }
-    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
+    // Iterate prints a `--require-sha` that reads the current checkout's HEAD. Name that cause,
+    // so a run from another checkout can recover from this error alone.
+    const current = lastSha ? ` (currently ${lastSha})` : "";
+    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly. If this command ran outside the PR head checkout, rerun it with \`--require-sha\` set to the PR head SHA you pushed${current}.`);
 }

package/bin/comments/thread-visibility.mjs

@@ -23,9 +23,10 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
 export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds, resolveOtherHumanThreads = "none") {
     const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
     const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
-    const unresolvedThreads = threads.filter((t) => !t.isResolved);
+    const unknownStatusThreads = threads.filter((thread) => thread.isResolved === undefined || thread.isOutdated === undefined);
+    const unresolvedThreads = threads.filter((thread) => thread.isResolved === false && thread.isOutdated !== undefined);
     const activeThreads = unresolvedThreads
-        .filter((t) => !t.isOutdated && !t.isMinimized)
+        .filter((t) => t.isOutdated === false && t.isMinimized !== true)
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
@@ -56,23 +57,27 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
     });
     const firstLookThreads = [
         ...threads.flatMap((t) => {
-            if (!t.isOutdated)
+            if (t.isOutdated !== true || t.isResolved === undefined)
                 return [];
             const visible = classifyFirstLookThread(t, seenMap, "outdated");
             return visible ? [visible] : [];
         }),
         ...threads.flatMap((t) => {
-            if (!t.isResolved || t.isOutdated)
+            if (t.isResolved !== true || t.isOutdated !== false)
                 return [];
             const visible = classifyFirstLookThread(t, seenMap, "resolved");
             return visible ? [visible] : [];
         }),
         ...threads.flatMap((t) => {
-            if (!t.isMinimized || t.isResolved || t.isOutdated)
+            if (!t.isMinimized || t.isResolved !== false || t.isOutdated !== false)
                 return [];
             const visible = classifyFirstLookThread(t, seenMap, "minimized");
             return visible ? [visible] : [];
         }),
+        ...unknownStatusThreads.flatMap((thread) => {
+            const visible = classifyFirstLookThread(thread, seenMap, "unknown");
+            return visible ? [visible] : [];
+        }),
     ];
     const seenMarkerIds = new Set();
     const toMarkSeen = [...activeThreads, ...resolutionOnlyThreads, ...firstLookThreads].filter((thread) => {

package/bin/comments/uncertain-replies.d.mts

@@ -0,0 +1,11 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type ReplyEvidence } from "../github/reply-recovery-read.mts";
+interface ReplyContext {
+    repo: RepoInfo;
+    pr: number;
+}
+export declare function trackAdoptedReplyThreads(result: object, ids: readonly string[]): void;
+export declare function adoptedReplyThreads(result: object): readonly string[];
+export declare function assertReplyOutcomeKnown(context: ReplyContext, ids: string[], message: string): Promise<string[]>;
+export declare function rememberUncertainReplies(context: ReplyContext, ids: string[], message: string, evidence?: Map<string, ReplyEvidence>): Promise<void>;
+export {};

package/bin/comments/uncertain-replies.mjs

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "../state/base.mjs";
+import { resolveRestThreadRoot } from "../github/rest-identities.mjs";
+import { readReplyRecoveryEvidence } from "../github/reply-recovery-read.mjs";
+import { addPrShepherdMarker } from "./marker.mjs";
+import { prepareUnmappedIntents, rememberUnmappedIntent } from "./uncertain-reply-guards.mjs";
+const adoptedReplies = new WeakMap();
+export function trackAdoptedReplyThreads(result, ids) {
+    adoptedReplies.set(result, ids);
+}
+export function adoptedReplyThreads(result) {
+    return adoptedReplies.get(result) ?? [];
+}
+async function paths(context, id, message) {
+    const identities = [id];
+    try {
+        identities.push(`rest-thread-${await resolveRestThreadRoot(context.repo, context.pr, id)}`);
+    }
+    catch { }
+    return [...new Set(identities)].map((identity) => resolvePrStatePath({ owner: context.repo.owner, repo: context.repo.name, pr: context.pr }, "uncertain-replies", `${createHash("sha256").update(`${identity}\n${message}`).digest("hex")}.json`));
+}
+export async function assertReplyOutcomeKnown(context, ids, message) {
+    await prepareUnmappedIntents(context, ids, message, paths);
+    const pending = new Map();
+    for (const id of ids) {
+        const present = [];
+        let record;
+        for (const path of await paths(context, id, message)) {
+            try {
+                const raw = await readFile(path, "utf8");
+                present.push(path);
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed.id === "string" && typeof parsed.message === "string")
+                    record = parsed;
+            }
+            catch (error) {
+                if (error instanceof SyntaxError)
+                    continue;
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        if (present.length)
+            pending.set(id, { paths: present, record: record ?? { id, message } });
+    }
+    const adopted = [];
+    const pendingIds = [...pending.keys()].filter((id) => {
+        const record = pending.get(id).record;
+        if (typeof record.adoptedCommentId === "string" &&
+            record.adoptedCommentId &&
+            record.message === message) {
+            adopted.push(id);
+            return false;
+        }
+        return true;
+    });
+    for (let offset = 0; offset < pendingIds.length; offset += 10) {
+        let evidence = new Map();
+        try {
+            evidence = await readReplyRecoveryEvidence(context.repo, context.pr, pendingIds.slice(offset, offset + 10));
+        }
+        catch {
+            /* Failed reads cannot authorize a duplicate reply. */
+        }
+        for (const id of pendingIds.slice(offset, offset + 10)) {
+            const item = pending.get(id);
+            const current = evidence.get(id);
+            const record = item.record;
+            const before = new Set(Array.isArray(record.beforeIds) ? record.beforeIds : []);
+            const matches = record.id &&
+                record.message === message &&
+                typeof record.viewer === "string" &&
+                record.viewer &&
+                Array.isArray(record.beforeIds) &&
+                record.beforeIds.every((value) => typeof value === "string") &&
+                current?.viewer.toLowerCase() === record.viewer.toLowerCase()
+                ? current.comments.filter((comment) => !before.has(comment.id) &&
+                    comment.body === addPrShepherdMarker(message) &&
+                    comment.author?.toLowerCase() === record.viewer.toLowerCase())
+                : [];
+            if (matches.length !== 1) {
+                const recoveryPaths = [
+                    ...new Set([...item.paths, ...(await paths(context, record.id, message))]),
+                ];
+                const command = `rm -- ${recoveryPaths.map((path) => `'${path.replaceAll("'", "'\\''")}'`).join(" ")}`;
+                throw new Error(`Previous GraphQL reply outcome is uncertain for ${id}; no duplicate reply was sent.\n` +
+                    "1. Inspect the complete thread transcript and verify whether the previous reply was delivered.\n" +
+                    "2. If you verified non-delivery and no request remains in flight, clear only this reply's markers and run:\n" +
+                    `   ${command}\n` +
+                    "3. Rerun the original reply command; do not clear all PR state or change the disposition to bypass this check.");
+            }
+            // Keep confirmed outcomes durable: another pending ID or a later resolve can still fail.
+            const outcomePaths = new Set([...item.paths, ...(await paths(context, record.id, message))]);
+            for (const path of outcomePaths)
+                await writeFile(path, JSON.stringify({ ...record, adoptedCommentId: matches[0].id }));
+            adopted.push(id);
+        }
+    }
+    await prepareUnmappedIntents(context, ids, message, paths);
+    return adopted;
+}
+export async function rememberUncertainReplies(context, ids, message, evidence = new Map()) {
+    for (const id of ids) {
+        for (const path of await paths(context, id, message)) {
+            await mkdir(dirname(path), { recursive: true });
+            const baseline = evidence.get(id);
+            await writeFile(path, JSON.stringify({
+                id,
+                message,
+                recordedAt: Date.now(),
+                ...(baseline && {
+                    viewer: baseline.viewer,
+                    beforeIds: baseline.comments.map((comment) => comment.id),
+                }),
+            }));
+        }
+        await rememberUnmappedIntent(context, id, message);
+    }
+}

package/bin/comments/uncertain-reply-guards.d.mts

@@ -0,0 +1,10 @@
+import type { RepoInfo } from "../github/client.mts";
+interface Context {
+    repo: RepoInfo;
+    pr: number;
+}
+type Paths = (context: Context, id: string, message: string) => Promise<string[]>;
+/** One guard per unresolved intent: clearing one never clears another pending reply. */
+export declare function rememberUnmappedIntent(context: Context, id: string, message: string): Promise<void>;
+export declare function prepareUnmappedIntents(context: Context, ids: string[], message: string, paths: Paths): Promise<void>;
+export {};

package/bin/comments/uncertain-reply-guards.mjs

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolvePrStatePath } from "../state/base.mjs";
+import { resolveRestThreadRoot } from "../github/rest-identities.mjs";
+import { readReplyRecoveryEvidence } from "../github/reply-recovery-read.mjs";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function directory(context, message) {
+    return resolvePrStatePath({ owner: context.repo.owner, repo: context.repo.name, pr: context.pr }, "unmapped-reply-intents", hash(message));
+}
+/** One guard per unresolved intent: clearing one never clears another pending reply. */
+export async function rememberUnmappedIntent(context, id, message) {
+    try {
+        await resolveRestThreadRoot(context.repo, context.pr, id);
+        return;
+    }
+    catch { }
+    const dir = directory(context, message);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${hash(id)}.json`), JSON.stringify({ id, message }));
+}
+export async function prepareUnmappedIntents(context, ids, message, paths) {
+    const dir = directory(context, message);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (entries.length > 1000)
+        throw new Error("Too many unresolved reply intents; inspect this PR's state before replying");
+    const requestedHaveMarkers = (await Promise.all(ids.map(async (id) => {
+        for (const path of await paths(context, id, message)) {
+            try {
+                await readFile(path);
+                return true;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        return false;
+    }))).every(Boolean);
+    for (const entry of entries) {
+        const guard = join(dir, entry);
+        const intent = JSON.parse(await readFile(guard, "utf8"));
+        if (typeof intent.id !== "string" || intent.message !== message)
+            throw new Error("Invalid unresolved reply intent");
+        let root;
+        try {
+            root = await resolveRestThreadRoot(context.repo, context.pr, intent.id);
+        }
+        catch { }
+        if (!root && !requestedHaveMarkers) {
+            try {
+                await readReplyRecoveryEvidence(context.repo, context.pr, [intent.id]);
+                root = await resolveRestThreadRoot(context.repo, context.pr, intent.id);
+            }
+            catch { }
+        }
+        if (!root) {
+            if (requestedHaveMarkers)
+                continue;
+            const files = [guard, ...(await paths(context, intent.id, message))];
+            const command = `rm -- ${files.map((file) => `'${file.replaceAll("'", "'\\''")}'`).join(" ")}`;
+            throw new Error(`Previous GraphQL reply outcome is uncertain for ${intent.id}; its REST identity is unknown. ` +
+                "This PR's identical reply message is blocked through unproven aliases; other messages remain independent.\n" +
+                "1. Inspect the original thread's complete transcript and verify non-delivery and that no request remains in flight.\n" +
+                `2. Only after that verification, clear this original intent's markers and guard: ${command}\n` +
+                "3. Rerun the original command.");
+        }
+        const locations = await paths(context, intent.id, message);
+        let record;
+        for (const path of locations) {
+            try {
+                record = await readFile(path, "utf8");
+                break;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        // A removed marker is explicit targeted recovery; otherwise preserve the original outcome.
+        if (record)
+            for (const path of locations)
+                await writeFile(path, record);
+        await unlink(guard);
+    }
+}

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

@@ -7,5 +7,5 @@ interface VisibleCommentClassification {
     minimizeIds: string[];
     toMarkSeen: ActionableComment[];
 }
-export declare function classifyVisibleComments(comments: PrComment[], seenMap: Map<string, SeenMarker>, minimizeComments: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames): VisibleCommentClassification;
+export declare function classifyVisibleComments(comments: PrComment[], seenMap: Map<string, SeenMarker>, minimizeComments: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames, deniedMinimizeIds?: ReadonlySet<string>): VisibleCommentClassification;
 export {};

package/bin/comments/visible-comments.mjs

@@ -1,11 +1,13 @@
 import { shouldMinimizeAuthor } from "./minimize-policy.mjs";
 import { classifyItem } from "../state/seen-comments.mjs";
-export function classifyVisibleComments(comments, seenMap, minimizeComments, botUsernames = new Set()) {
+import { canGenerateGithubMutation } from "../github/mutation-policy.mjs";
+export function classifyVisibleComments(comments, seenMap, minimizeComments, botUsernames = new Set(), deniedMinimizeIds = new Set()) {
     const actionable = [];
     const minimizeIds = [];
     const toMarkSeen = [];
     for (const c of comments.filter((comment) => !comment.isMinimized)) {
-        if (c.viewerCanMinimize === true &&
+        if (!deniedMinimizeIds.has(c.id) &&
+            canGenerateGithubMutation(c.viewerCanMinimize, "minimize") &&
             shouldMinimizeAuthor(c.authorType, minimizeComments, c.author, botUsernames)) {
             actionable.push(c);
             minimizeIds.push(c.id);

package/bin/config/load.d.mts

@@ -1,8 +1,23 @@
 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"];
+/**
+ * How `fix_code` `## Instructions` render invariant procedure text. `inline` (default)
+ * prints every step each tick; `playbook` points at the shipped "Fix-code loop" playbook.
+ */
+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;
@@ -14,10 +29,25 @@ interface PollConfig {
     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 {
-    /** Optional user classification configuration; preserved for rule consumers. */
+    /** 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. */
@@ -50,6 +80,12 @@ export interface PrShepherdConfig {
          * also resolves when GitHub reports `isOutdated`; `always` pairs reply-and-resolve.
          */
         resolveOtherHumanThreads: ResolveOtherHumanThreads;
+        /**
+         * `inline` (default) prints the commit/push and journal steps of `fix_code` instructions
+         * every tick; `playbook` folds them 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: {

package/bin/config/load.mjs

@@ -7,8 +7,18 @@ import builtins from "../config.json" with { type: "json" };
 import { getEffectiveCwd } from "../execution-context.mjs";
 import { findMergeStrategies } from "./merge-command-args.mjs";
 import { parseMergeMethod } from "./merge-method.mjs";
+import { parseGithubTransport } from "../github/transport-mode.mjs";
+import { STANDARD_RULE_NAMES } from "../classify/standard/index.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RESOLVE_OTHER_HUMAN_THREADS = ["none", "outdated", "always"];
+export const INSTRUCTION_STYLES = ["playbook", "inline"];
+export function isInstructionStyle(value) {
+    return INSTRUCTION_STYLES.some((style) => style === value);
+}
+export const POLL_MODES = ["auto", "poll", "event"];
+export function isPollMode(value) {
+    return POLL_MODES.some((mode) => mode === value);
+}
 const RC_FILENAME = ".pr-shepherdrc.yml";
 /**
  * Collect `.pr-shepherdrc.yml` files from `startDir` toward `$HOME` (closest first).
@@ -77,6 +87,11 @@ function parseResolveOtherHumanThreads(value) {
     }
     throw new Error(`Invalid config: iterate.resolveOtherHumanThreads must be one of "none", "outdated", or "always", got ${JSON.stringify(value)}`);
 }
+function parseInstructionStyle(value) {
+    if (isInstructionStyle(value))
+        return value;
+    throw new Error(`Invalid config: iterate.instructions must be "playbook" or "inline", got ${JSON.stringify(value)}`);
+}
 function parseCliCommand(value) {
     if (!Array.isArray(value) ||
         value.length === 0 ||
@@ -154,13 +169,26 @@ function parsePollConfig(value) {
     const intervalSeconds = parsePollDuration(record["intervalSeconds"], "intervalSeconds");
     const timeoutSeconds = parsePollDuration(record["timeoutSeconds"], "timeoutSeconds");
     const debounceSeconds = parsePollDuration(record["debounceSeconds"], "debounceSeconds", true);
+    const reconcileSeconds = parsePollDuration(record["reconcileSeconds"], "reconcileSeconds", true);
     const stackIntervalFactor = parseStackIntervalFactor(record["stackIntervalFactor"]);
     assertAggregateIntervalFits(intervalSeconds, stackIntervalFactor);
     const quietStatus = record["quietStatus"];
     if (typeof quietStatus !== "boolean") {
         throw new Error(`Invalid config: poll.quietStatus must be a boolean, got ${JSON.stringify(quietStatus)}`);
     }
-    return { intervalSeconds, stackIntervalFactor, timeoutSeconds, debounceSeconds, quietStatus };
+    const mode = record["mode"];
+    if (!isPollMode(mode)) {
+        throw new Error(`Invalid config: poll.mode must be one of ${POLL_MODES.join(", ")}, got ${JSON.stringify(mode)}`);
+    }
+    return {
+        intervalSeconds,
+        stackIntervalFactor,
+        timeoutSeconds,
+        debounceSeconds,
+        quietStatus,
+        mode,
+        reconcileSeconds,
+    };
 }
 function parseStackIntervalFactor(value) {
     if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
@@ -247,6 +275,7 @@ function parseGraphqlQuotaWarnings(value, pollIntervalSeconds) {
     return parsed;
 }
 const KNOWN_CONFIG_KEYS = new Set([
+    "github",
     "classify",
     "cliCommand",
     "botUsernames",
@@ -261,6 +290,7 @@ const KNOWN_CONFIG_KEYS = new Set([
     "actions",
 ]);
 const KNOWN_NESTED_KEYS = {
+    github: new Set(["transport"]),
     iterate: new Set([
         "fixAttemptsPerThread",
         "stallTimeoutMinutes",
@@ -268,6 +298,7 @@ const KNOWN_NESTED_KEYS = {
         "minimizeComments",
         "behindBaseHint",
         "resolveOtherHumanThreads",
+        "instructions",
     ]),
     poll: new Set([
         "intervalSeconds",
@@ -275,6 +306,8 @@ const KNOWN_NESTED_KEYS = {
         "timeoutSeconds",
         "debounceSeconds",
         "quietStatus",
+        "mode",
+        "reconcileSeconds",
     ]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
@@ -314,8 +347,45 @@ function warnUnknownConfigKeys(config) {
     }
 }
 const rawDefaults = builtins;
+/**
+ * Resolves `classify.standard` (`{ all?: boolean, <rule>?: boolean }`) to enabled rule names.
+ * A named entry overrides `all`. Unknown names and non-boolean values warn and are ignored.
+ */
+function parseStandardRules(classify) {
+    if (classify === null || typeof classify !== "object" || Array.isArray(classify))
+        return [];
+    const standard = classify["standard"];
+    if (standard === undefined)
+        return [];
+    if (standard === null || typeof standard !== "object" || Array.isArray(standard)) {
+        process.stderr.write("pr-shepherd: config: classify.standard must be a map of rule name to boolean; ignored.\n");
+        return [];
+    }
+    const entries = standard;
+    const flags = new Map();
+    for (const [name, value] of Object.entries(entries)) {
+        if (name !== "all" && !STANDARD_RULE_NAMES.includes(name)) {
+            process.stderr.write(`pr-shepherd: config: unknown standard classification rule "classify.standard.${name}" ignored.\n`);
+            continue;
+        }
+        if (typeof value !== "boolean") {
+            process.stderr.write(`pr-shepherd: config: classify.standard.${name} must be a boolean; ignored.\n`);
+            continue;
+        }
+        flags.set(name, value);
+    }
+    const all = flags.get("all") ?? false;
+    return STANDARD_RULE_NAMES.filter((name) => flags.get(name) ?? all).sort();
+}
 function parseConfig(value, normalizeMergeArgs = true) {
     const config = value;
+    const github = value["github"];
+    if (github === null || typeof github !== "object" || Array.isArray(github)) {
+        throw new Error("Invalid config: github must be a plain object");
+    }
+    config.github = {
+        transport: parseGithubTransport(github["transport"] ?? "auto"),
+    };
     config.cliCommand = parseCliCommand(config.cliCommand);
     config.botUsernames = parseBotUsernames(config.botUsernames);
     config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
@@ -333,7 +403,9 @@ function parseConfig(value, normalizeMergeArgs = true) {
     config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings, config.poll.intervalSeconds);
     config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
     config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
+    config.iterate.instructions = parseInstructionStyle(config.iterate.instructions);
     config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
+    config.standardRules = parseStandardRules(config.classify);
     return config;
 }
 const defaults = parseConfig(structuredClone(rawDefaults), false);

package/bin/config.json

@@ -1,4 +1,5 @@
 {
+  "github": { "transport": "auto" },
   "cliCommand": ["pr-shepherd"],
   "botUsernames": [
     "chatgpt-connector",
@@ -21,14 +22,17 @@
     "minimizeApprovals": false,
     "minimizeComments": "all",
     "behindBaseHint": "",
-    "resolveOtherHumanThreads": "none"
+    "resolveOtherHumanThreads": "none",
+    "instructions": "inline"
   },
   "poll": {
     "intervalSeconds": 60,
     "stackIntervalFactor": 2,
     "timeoutSeconds": 270,
     "debounceSeconds": 60,
-    "quietStatus": false
+    "quietStatus": false,
+    "mode": "auto",
+    "reconcileSeconds": 900
   },
   "watch": {
     "readyDelayMinutes": 10,

package/bin/exit-codes.d.mts

@@ -10,6 +10,7 @@
  * ran to completion and is reporting PR state. See docs/exit-codes.md.
  */
 import type { IterateResult } from "./types.mts";
+import type { ResolveResult } from "./comments/resolve.mts";
 export declare const EXIT: Readonly<{
     /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
     readonly OK: 0;
@@ -52,4 +53,6 @@ export declare class ShepherdError extends Error {
     });
 }
 export declare function iterateResultToExitCode(result: IterateResult): number;
+/** Exit code for a completed `apply review` run: 77 on a session refusal, 75/69 on errors, else 0. */
+export declare function applyReviewResultToExitCode(result: Pick<ResolveResult, "sessionRefusal" | "errors" | "rateLimit">): number;
 export declare function errorToExitCode(err: unknown): number;

package/bin/exit-codes.mjs

@@ -74,6 +74,14 @@ export function iterateResultToExitCode(result) {
             return EXIT.MERGE;
     }
 }
+/** Exit code for a completed `apply review` run: 77 on a session refusal, 75/69 on errors, else 0. */
+export function applyReviewResultToExitCode(result) {
+    if (result.sessionRefusal)
+        return EXIT.NOPERM;
+    if (result.errors.length > 0)
+        return result.rateLimit ? EXIT.TEMPFAIL : EXIT.UNAVAILABLE;
+    return EXIT.OK;
+}
 export function errorToExitCode(err) {
     if (err instanceof ShepherdError)
         return err.exitCode;

package/bin/github/api-telemetry-aggregate.d.mts

@@ -1,5 +1,16 @@
 import type { ApiTelemetryEvent } from "./api-telemetry.mts";
 import type { RateLimitInfo } from "./http-utils.mts";
+interface RestTelemetryGroup {
+    /** Quota-consuming requests; 304 Not Modified responses are tallied separately. */
+    requestCount: number;
+    notModifiedCount: number;
+    rateLimit?: RateLimitInfo;
+    /** Fingerprint for the credential that produced the selected quota sample. */
+    credentialFingerprint?: string;
+    /** Newest observed credential and sequence, even if its sample did not win quota selection. */
+    latestCredentialFingerprint?: string;
+    latestCredentialSequence?: number;
+}
 export interface TelemetryAggregate {
     eventCount: number;
     credentialSources: Map<string, number>;
@@ -11,10 +22,9 @@ export interface TelemetryAggregate {
         rateLimit?: RateLimitInfo;
         credentialFingerprint?: string;
     };
-    rest: Map<string, {
-        requestCount: number;
-        rateLimit?: RateLimitInfo;
-    }>;
+    rest: Map<string, RestTelemetryGroup>;
+    /** Headerless REST responses (not 304s), kept out of every resource group: the proxy's `ccr` routes. */
+    unmeteredRestRequestCount: number;
 }
 export interface SequencedApiTelemetryEvent extends ApiTelemetryEvent {
     sequence: number;
@@ -31,3 +41,4 @@ export declare function emptyAggregate(): TelemetryAggregate;
 export declare function aggregateEvents(events: SequencedApiTelemetryEvent[]): TelemetryAggregate;
 export declare function mergeAggregate(target: TelemetryAggregate, source: TelemetryAggregate): void;
 export declare function aggregateStore(active: TelemetryStore): TelemetryAggregate;
+export {};