pr-shepherd 0.60.1 → 1.1.0

package/bin/github/poll-summary.mjs

@@ -8,11 +8,13 @@ import { missingRepositoryError } from "./errors.mjs";
 import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { refreshUnknownSummaryMergeability } from "./poll-summary-mergeability.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
+import { hydrateRowsIsolated, summarizeRowsIsolated, } from "./poll-summary-row-error.mjs";
 import { trunkRequiredContexts } from "./poll-summary-unreported.mjs";
 import { loadStackSizeHint, storeStackSizeHint } from "./stack-size-hint.mjs";
 import { POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
 import { stackAncestryGaps } from "./stack-read.mjs";
 import { readGraphqlStackSummary } from "./poll-summary-stack-page.mjs";
+import { patchHandoffLayers } from "./poll-summary-rule-handoff.mjs";
 import { stackHandoffSource } from "./stack-handoff.mjs";
 const MAX_EXPLICIT_PRS_PER_QUERY = 50;
 async function fetchSelectedPollSummary(opts, repo) {
@@ -20,24 +22,30 @@ async function fetchSelectedPollSummary(opts, repo) {
         return fetchStackSummary(opts, repo);
     const requested = [...new Set(opts.prNumbers ?? [])];
     if (requested.length === 0) {
-        throw new ShepherdError("Aggregate poll requires at least two PRs or --stack <PR>", EXIT.USAGE);
+        throw new ShepherdError("Aggregate poll requires at least two PRs or a stack PR", EXIT.USAGE);
     }
     const raw = [];
+    const failures = new Map();
     let viewerCanAdminister;
     for (let offset = 0; offset < requested.length; offset += MAX_EXPLICIT_PRS_PER_QUERY) {
         const chunk = requested.slice(offset, offset + MAX_EXPLICIT_PRS_PER_QUERY);
         const fetched = await fetchExplicitChunk(chunk, repo);
         viewerCanAdminister = fetched.viewerCanAdminister;
         raw.push(...fetched.prs);
+        for (const [pr, error] of fetched.failures ?? [])
+            failures.set(pr, error);
     }
     return {
         selection: { kind: "prs", requested },
-        prs: await Promise.all(raw.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
+        // One explicit PR's failed read becomes a row; stack selections stay fail-closed.
+        prs: await summarizeRowsIsolated(raw, failures, repo, opts, (pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, undefined, null, true)),
     };
 }
 /** Fresh, read-only snapshot used to bind a one-PR READY receipt to stack routing. */
 export async function fetchRawSummaryPr(pr, repo) {
     const fetched = await fetchExplicitChunk([pr], repo);
+    if (fetched.failures?.has(pr))
+        throw fetched.failures.get(pr);
     return fetched.prs[0];
 }
 async function fetchGraphqlExplicitChunk(prs, repo) {
@@ -60,11 +68,8 @@ async function fetchGraphqlExplicitChunk(prs, repo) {
             throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
         return raw;
     });
-    for (const raw of rawPrs) {
-        await hydratePollSummaryChecks(raw, repo);
-        await refreshUnknownSummaryMergeability(raw, repo);
-    }
-    return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
+    const failures = await hydrateRowsIsolated(rawPrs, repo);
+    return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister, failures };
 }
 async function fetchExplicitChunk(prs, repo) {
     return githubOperation("PollSummary", () => runWithGithubTransport("graphql", () => fetchGraphqlExplicitChunk(prs, repo)), async () => ({
@@ -101,9 +106,12 @@ async function fetchStackSummary(opts, repo) {
     const handoffSource = getGithubTransport() === "rest" ? undefined : stackHandoffSource(read);
     const stackAncestry = stackAncestryGaps(ordered);
     const required = await trunkRequiredContexts(ordered, repo);
+    const prs = await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin, true)));
+    if (handoffSource)
+        patchHandoffLayers(handoffSource.layers, prs);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
-        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),
+        prs,
         ...(stackAncestry.length > 0 && { stackAncestry }),
         ...(allowedMergeMethods && { allowedMergeMethods }),
         ...(handoffSource && { handoffSource }),

package/bin/github/queries.d.mts

@@ -43,7 +43,7 @@ export declare const POLL_STACK_TOPOLOGY_QUERY: string;
 export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
 /** Merged PRs whose head may be the stale base of a non-stack conflict. */
 export declare const MERGED_BASE_PULL_REQUESTS_QUERY: string;
-/** PR head fields plus a single review thread for `commit-suggestion`. */
+/** PR head fields plus the requested review threads for `suggest`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;

package/bin/github/queries.mjs

@@ -48,7 +48,7 @@ export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
 export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-target.gql");
 /** Merged PRs whose head may be the stale base of a non-stack conflict. */
 export const MERGED_BASE_PULL_REQUESTS_QUERY = gql("merged-base-pull-requests.gql");
-/** PR head fields plus a single review thread for `commit-suggestion`. */
+/** PR head fields plus the requested review threads for `suggest`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");

package/bin/github/rest-reader-core.mjs

@@ -101,7 +101,9 @@ function nextRestPage(link, original) {
     if (!match)
         malformedRest(`invalid pagination link for ${original}`);
     const url = new URL(match[1], "https://api.github.com");
-    if (url.origin !== "https://api.github.com" || url.pathname !== original.split("?")[0])
+    const originalPath = original.split("?")[0];
+    if (url.origin !== "https://api.github.com" ||
+        !samePaginationResource(url.pathname, originalPath))
         malformedRest(`unsafe pagination link for ${original}`);
     if (url.searchParams.get("per_page") !== "100")
         malformedRest(`changed page size for ${original}`);
@@ -113,7 +115,16 @@ function nextRestPage(link, original) {
                 JSON.stringify(source.searchParams.getAll(key)))
             malformedRest(`changed pagination filter for ${original}`);
     }
-    return `${url.pathname}${url.search}`;
+    // Rebuild on the requested path so the repository id in a /repositories/{id} link is never trusted.
+    return `${originalPath}${url.search}`;
+}
+/** GitHub may link `/repos/{owner}/{repo}/…` pages through `/repositories/{id}/…`. */
+function samePaginationResource(linkPath, originalPath) {
+    if (linkPath === originalPath)
+        return true;
+    const linkSuffix = /^\/repositories\/\d+(\/.*)$/.exec(linkPath)?.[1];
+    const originalSuffix = /^\/repos\/[^/]+\/[^/]+(\/.*)$/.exec(originalPath)?.[1];
+    return linkSuffix !== undefined && linkSuffix === originalSuffix;
 }
 /** A pull request whose mergeability GitHub is still computing must be re-read, never replayed. */
 function isSettledBody(body) {

package/bin/github/rest-summary-read.mjs

@@ -99,7 +99,7 @@ export function restSummary(data, pull, feedback, checks, baseRef) {
                             nodes: checks.suites.map((suite) => ({
                                 status: suite.status.toUpperCase(),
                                 conclusion: suite.conclusion?.toUpperCase() ?? null,
-                                workflowRun: checks.workflowRuns.find((run) => run.check_suite_id === suite.id) ?? null,
+                                workflowRun: restSuiteWorkflowRun(checks.workflowRuns.find((run) => run.check_suite_id === suite.id)),
                             })),
                         },
                     },
@@ -110,3 +110,14 @@ export function restSummary(data, pull, feedback, checks, baseRef) {
         transportUnavailable: data.transportUnavailable,
     };
 }
+/** The GraphQL `workflowRun` shape, so summary readers see one suite format on either transport. */
+function restSuiteWorkflowRun(run) {
+    if (!run)
+        return null;
+    return {
+        databaseId: run.id,
+        event: run.event,
+        url: run.html_url,
+        workflow: { name: run.name },
+    };
+}

package/bin/mcp/server.mjs

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
 import { isRepositoryQualifiedPrReference, normalizeRepositoryIdentity, parsePrReference, } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
-import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
+import { formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
 import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
 import { projectStackOverview } from "../cli/stack-overview.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
@@ -13,6 +13,7 @@ import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 import { formatApplyMergeResult } from "../cli/apply-merge-handler.mjs";
 import { extractShepherdJournal } from "../journal/index.mjs";
 import { formatPlaybookResult, runPlaybook } from "../commands/playbook.mjs";
+import { formatCheckBlockerResult } from "../commands/apply-check-blocker.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
     .string()
@@ -20,12 +21,8 @@ const pr = z
     .describe("GitHub pull-request URL or owner/repo#number; the explicit repository may differ from the server working directory");
 const ids = z.array(z.string().min(1)).optional();
 const transport = z.enum(["auto", "graphql", "rest"]).optional();
-const iterateInputSchema = z
-    .object({
+const tickOptionsSchema = {
     transport,
-    pr: pr.optional(),
-    prs: z.array(pr).min(1).optional(),
-    stack: pr.optional(),
     readyDelaySeconds: z.number().nonnegative().optional(),
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
@@ -33,25 +30,20 @@ const iterateInputSchema = z
     instructions: z
         .enum(["playbook", "inline"])
         .optional()
-        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit and push into the Fix-code loop playbook."),
-    pollMode: z
-        .enum(["auto", "poll", "event"])
-        .optional()
-        .describe("Overrides poll.mode. event returns one tick with pollMode and nextCheck so the caller owns the wake-up; auto (default) selects event when CLAUDE_CODE_REMOTE=true."),
-    noAutoCancelActionable: z
-        .boolean()
-        .optional()
-        .describe("Deprecated no-op; Shepherd never cancels workflow runs."),
-    neverCancelRuns: z
-        .array(z.string())
-        .optional()
-        .describe("Deprecated per-call no-op retained for compatibility."),
+        .describe("triage instruction style. inline (default) prints every step each tick; playbook folds commit and push into the Triage loop playbook."),
+};
+const iterateInputSchema = z
+    .object({
+    ...tickOptionsSchema,
+    pr: pr.optional(),
+    prs: z.array(pr).min(1).optional(),
 })
-    .refine((input) => [input.pr, input.prs, input.stack].filter((value) => value !== undefined).length === 1, {
-    message: "exactly one of pr, prs, or stack is required",
+    .refine((input) => (input.pr === undefined) !== (input.prs === undefined), {
+    message: "exactly one of pr or prs is required",
 })
     .refine((input) => !input.prs ||
     new Set(input.prs.map((ref) => normalizeRepositoryIdentity(parsePrReference(ref)?.repository ?? ""))).size === 1, { message: "all prs must belong to the same repository" });
+const stackInputSchema = z.object({ ...tickOptionsSchema, pr });
 const reviewMutationsOperationSchema = z.object({
     type: z.literal("review_mutations"),
     resolveThreadIds: ids,
@@ -78,6 +70,16 @@ const acknowledgeQueueRemovalOperationSchema = z.object({
     queueCommitOid: z.string().regex(/^[0-9a-f]{40}$/),
     removedAtUnix: z.number().int().positive().safe(),
 });
+const checkBlockerOperationSchema = z.object({
+    type: z.literal("check_blocker"),
+    check: z.string().min(1).describe("Exact check name."),
+    blockedBy: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Blocking PR/issue URL, owner/repo#N, or issue:owner/repo#N."),
+    clear: z.boolean().optional().describe("Clear the recorded blocker instead of setting one."),
+});
 const mergeOperationSchema = z.object({
     type: z.literal("merge"),
     requireSha: z.string().regex(/^[0-9a-f]{40}$/),
@@ -109,17 +111,11 @@ const applyInputSchema = z.object({
         markFilesViewedOperationSchema,
         appendJournalOperationSchema,
         acknowledgeQueueRemovalOperationSchema,
+        checkBlockerOperationSchema,
     ]))
         .min(1),
 });
-const suggestionPatchInputSchema = z.object({
-    transport,
-    pr,
-    threadId: z.string().min(1),
-    message: z.string().min(1),
-    description: z.string().optional(),
-});
-const suggestionPatchesInputSchema = z.object({
+const suggestInputSchema = z.object({
     transport,
     pr,
     suggestions: z
@@ -136,7 +132,7 @@ export function createPrShepherdMcpServer(options = {}) {
     const getShepherd = () => (shepherd ??= createPrShepherd({ cwd: options.cwd, transport: options.transport }));
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
-        description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
+        description: "Inspect one pull request (pr) or an explicit same-repository set (prs) and return one Shepherd tick.",
         inputSchema: iterateInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -151,14 +147,20 @@ export function createPrShepherdMcpServer(options = {}) {
         };
         return runTool(() => runIterateSelector(getShepherd(), requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
             ? formatPollSummaryResult(result)
-            : formatIterateResult(result, opts), (result) => isPollSummary(result)
-            ? result.selection.kind === "stack"
-                ? projectStackOverview(result)
-                : result
-            : projectIterateLean(result, opts));
+            : formatIterateResult(result, opts), (result) => isPollSummary(result) ? result : projectIterateLean(result, opts));
     });
+    server.registerTool("stack", {
+        description: "Inspect the native stack containing one pull request and return one aggregate Shepherd tick.",
+        inputSchema: stackInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => getShepherd().stack(requireRepositoryQualifiedPr(input)), formatPollSummaryResult, projectStackOverview));
     server.registerTool("apply", {
-        description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
+        description: "Apply ordered merge, review, file-view, journal, check-blocker, and queue-removal operations after prevalidation; explicit requests rely on GitHub's mutation response.",
         inputSchema: applyInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -202,38 +204,28 @@ export function createPrShepherdMcpServer(options = {}) {
             openWorldHint: false,
         },
     }, async (input) => runTool(async () => runPlaybook(input.name), formatPlaybookResult));
-    server.registerTool("build_suggestion_patches", {
+    server.registerTool("suggest", {
         description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
-        inputSchema: suggestionPatchesInputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
-    }, async (input) => runTool(() => getShepherd().buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
-    server.registerTool("build_suggestion_patch", {
-        description: "Deprecated: use build_suggestion_patches with a one-item suggestions array.",
-        inputSchema: suggestionPatchInputSchema,
+        inputSchema: suggestInputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => getShepherd().buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
+    }, async (input) => runTool(() => getShepherd().suggest(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
     return server;
 }
 function runIterateSelector(shepherd, input) {
-    return "prs" in input || "stack" in input
+    return "prs" in input && input.prs !== undefined
         ? shepherd.iterate(input)
         : shepherd.iterate(input);
 }
 function requireRepositoryQualifiedIterate(input) {
-    if ([input.pr, input.prs, input.stack].filter((value) => value !== undefined).length !== 1) {
-        throw new PrShepherdValidationError("exactly one of pr, prs, or stack is required");
+    if ((input.pr === undefined) === (input.prs === undefined)) {
+        throw new PrShepherdValidationError("exactly one of pr or prs is required");
     }
-    const refs = Array.isArray(input.prs) ? input.prs : [input.pr ?? input.stack];
+    const refs = Array.isArray(input.prs) ? input.prs : [input.pr];
     if (refs.length === 0 || refs.some((ref) => !isRepositoryQualifiedPrReference(ref))) {
         throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);
     }
@@ -264,7 +256,7 @@ function toolResult(structured, text) {
 }
 /**
  * `project` mirrors the CLI's `--format=json` treatment of the same result. Tools
- * whose CLI JSON is the raw result object (apply, build_suggestion_patch(es) — see
+ * whose CLI JSON is the raw result object (apply, suggest — see
  * handlers.mts and cli-parser.mts, which JSON.stringify the result directly) omit
  * `project` and return the result unchanged, matching their own CLI JSON output.
  */
@@ -290,6 +282,8 @@ function formatApplyResult(result) {
                 return `${heading}\n\n${formatMarkFilesAsViewedResult(operation.result)}`;
             case "append_journal":
                 return `${heading}\n\n${formatJournalResult(operation.result)}`;
+            case "check_blocker":
+                return `${heading}\n\n${formatCheckBlockerResult(operation.result)}`;
             case "acknowledge_queue_removal": {
                 const result = operation.result;
                 return [

package/bin/merge-status/derive.mjs

@@ -70,7 +70,7 @@ function detectBlockingBotReview(pr) {
     // A blocking bot review is "in progress" when:
     //   1. Any reviewRequest has a login starting with one of the configured prefixes, OR
     //   2. Any latestReview has such a login AND state == "PENDING"
-    const prefixes = loadConfig().mergeStatus.blockingReviewerLogins.map((l) => l.toLowerCase());
+    const prefixes = loadConfig()["mark-ready"]["blocking-reviewer-logins"].map((l) => l.toLowerCase());
     const isBlocking = (login) => prefixes.some((p) => login.toLowerCase().startsWith(p));
     const requested = pr.reviewRequests.some((r) => isBlocking(r.login));
     const pendingReview = pr.latestReviews.some((r) => isBlocking(r.login) && r.state === "PENDING");

package/bin/state/durable-state.d.mts

@@ -1,6 +1,4 @@
-/** Run work whose state (seen markers, stall timers, reply records) must outlive a temp dir. */
-export declare function runWithDurableState<T>(work: () => T): T;
-/** Cloud sessions are always durable; other callers opt in through `runWithDurableState`. */
+/** Cloud sessions keep state (seen markers, stall timers, reply records) beyond a temp dir. */
 export declare function durableStateRequested(): boolean;
 /** `<git-common-dir>/pr-shepherd-state`, or null when not requested or outside a repository. */
 export declare function resolveDurableStateBase(): string | null;

package/bin/state/durable-state.mjs

@@ -1,5 +1,4 @@
 import { execFileSync } from "node:child_process";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { join, resolve } from "node:path";
 import { getEffectiveCwd } from "../execution-context.mjs";
 /**
@@ -7,15 +6,10 @@ import { getEffectiveCwd } from "../execution-context.mjs";
  * directory lives with the repository checkout, so state stored there survives whatever the
  * session does with `TMPDIR`. Only a read-only `git rev-parse` is ever invoked.
  */
-const durableScope = new AsyncLocalStorage();
 const commonDirByCwd = new Map();
-/** Run work whose state (seen markers, stall timers, reply records) must outlive a temp dir. */
-export function runWithDurableState(work) {
-    return durableScope.run(true, work);
-}
-/** Cloud sessions are always durable; other callers opt in through `runWithDurableState`. */
+/** Cloud sessions keep state (seen markers, stall timers, reply records) beyond a temp dir. */
 export function durableStateRequested() {
-    return durableScope.getStore() === true || process.env["CLAUDE_CODE_REMOTE"] === "true";
+    return process.env["CLAUDE_CODE_REMOTE"] === "true";
 }
 /** `<git-common-dir>/pr-shepherd-state`, or null when not requested or outside a repository. */
 export function resolveDurableStateBase() {

package/bin/state/fix-attempts.d.mts

@@ -2,14 +2,14 @@
  * Persistent attempt counter for the iterate escalation guard.
  *
  * Tracks how many caller-visible times each review thread has been dispatched to
- * the fix_code handler without being resolved. Body edits reset the count.
+ * the triage handler without being resolved. Body edits reset the count.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/fix-attempts.json`.
  */
 export interface FixAttemptsState {
     /** HEAD SHA at the time the counts were last written, retained for observability/compatibility. */
     headSha: string;
-    /** Map from thread ID → number of fix_code dispatches that included this thread. */
+    /** Map from thread ID → number of triage dispatches that included this thread. */
     threadAttempts: Record<string, number>;
     /** Map from thread ID → body hash used for the associated attempt count. */
     threadBodyHashes?: Record<string, string>;

package/bin/state/fix-attempts.mjs

@@ -2,7 +2,7 @@
  * Persistent attempt counter for the iterate escalation guard.
  *
  * Tracks how many caller-visible times each review thread has been dispatched to
- * the fix_code handler without being resolved. Body edits reset the count.
+ * the triage handler without being resolved. Body edits reset the count.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/fix-attempts.json`.
  */

package/bin/state/merge-request.mjs

@@ -100,7 +100,7 @@ export async function replaceFailedMergeRequest(key, previous, next) {
                 throw error;
             persisted = parseRecord(await readFile(`${stem}.json`, "utf8"));
             if (!persisted.replacementToken)
-                throw new Error("Legacy merge successor has no recovery token; reconcile its outcome");
+                throw new Error("Merge successor has no recovery token; reconcile its outcome");
             if (persisted.options.requireSha !== next.options.requireSha ||
                 persisted.options.mergeAction !== next.options.mergeAction ||
                 persisted.options.mergeMethod !== next.options.mergeMethod ||

package/bin/state/pr-fingerprint.mjs

@@ -5,7 +5,7 @@ import { dirname } from "node:path";
 import { resolvePrStatePath } from "./base.mjs";
 import { discoverRuleFiles } from "../classify/loader.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
-const VERSION = 4;
+const VERSION = 5;
 let packageVersion;
 /** Bundled standard rules change with the package, so their digest input is its version. */
 function readPackageVersion() {
@@ -15,18 +15,11 @@ function readPackageVersion() {
 export function fingerprintInputDigest(config) {
     const hash = createHash("sha256");
     hash.update(JSON.stringify({
-        ignoreChecks: config.ignoreChecks,
-        botUsernames: config.botUsernames,
+        "bot-usernames": config["bot-usernames"],
         iterate: config.iterate,
-        watch: { readyDelayMinutes: config.watch.readyDelayMinutes },
         checks: config.checks,
-        mergeStatus: config.mergeStatus,
-        actions: {
-            autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
-            autoMarkReady: config.actions.autoMarkReady,
-            neverCancelRuns: config.actions.neverCancelRuns,
-            workWhileQueued: config.actions.workWhileQueued,
-        },
+        "mark-ready": config["mark-ready"],
+        actions: config.actions,
         standardRules: (config.standardRules?.length ?? 0) > 0
             ? { names: config.standardRules, version: readPackageVersion() }
             : undefined,

package/bin/state/seen-comments.d.mts

@@ -16,8 +16,8 @@ export declare function hashBody(body: string): string;
  * - "new"       — no marker exists; surface the body and write the marker.
  * - "edited"    — marker exists but stored hash differs from the current body;
  *                 surface the updated body and update the marker hash.
- * - "unchanged" — marker exists and hash matches (or marker has no hash, which
- *                 is treated conservatively as unchanged).
+ * - "unchanged" — marker exists and hash matches (or marker has no hash and no
+ *                 inline thread IDs, which is treated conservatively as unchanged).
  */
 export declare function classifyItem(id: string, body: string, map: Map<string, SeenMarker>): "new" | "edited" | "unchanged";
 /**
@@ -31,9 +31,8 @@ export declare function loadSeenSet(key: StateKey): Promise<Set<string>>;
  * Used when the caller needs the stored bodyHash to detect in-place edits.
  * Returns an empty Map if the directory does not yet exist.
  *
- * Map keys are the stored `id` field when present (guarding against
- * case-insensitive filesystem collisions), falling back to the filename for
- * legacy markers that predate this field.
+ * Map keys are the stored `id` field (guarding against case-insensitive
+ * filesystem collisions); markers without one are skipped.
  */
 export declare function loadSeenMap(key: StateKey): Promise<Map<string, SeenMarker>>;
 /** Return true if a "seen" marker exists for this id. */

package/bin/state/seen-comments.mjs

@@ -17,8 +17,8 @@ export function hashBody(body) {
  * - "new"       — no marker exists; surface the body and write the marker.
  * - "edited"    — marker exists but stored hash differs from the current body;
  *                 surface the updated body and update the marker hash.
- * - "unchanged" — marker exists and hash matches (or marker has no hash, which
- *                 is treated conservatively as unchanged).
+ * - "unchanged" — marker exists and hash matches (or marker has no hash and no
+ *                 inline thread IDs, which is treated conservatively as unchanged).
  */
 export function classifyItem(id, body, map) {
     const m = map.get(id);
@@ -48,9 +48,8 @@ export async function loadSeenSet(key) {
  * Used when the caller needs the stored bodyHash to detect in-place edits.
  * Returns an empty Map if the directory does not yet exist.
  *
- * Map keys are the stored `id` field when present (guarding against
- * case-insensitive filesystem collisions), falling back to the filename for
- * legacy markers that predate this field.
+ * Map keys are the stored `id` field (guarding against case-insensitive
+ * filesystem collisions); markers without one are skipped.
  */
 export async function loadSeenMap(key) {
     const map = new Map();
@@ -63,14 +62,8 @@ export async function loadSeenMap(key) {
             try {
                 const raw = await readFile(join(dir, entry), "utf8");
                 const marker = JSON.parse(raw);
-                // Prefer the stored id field; fall back to filename stem for legacy markers.
-                const mapKey = typeof marker.id === "string" ? marker.id : entry.slice(0, -5);
-                // Hash-based markers (those with an id field) take priority over legacy
-                // filename-based markers so that a stale legacy file cannot overwrite a
-                // newer hash-based entry that maps to the same key.
-                if (!map.has(mapKey) || typeof marker.id === "string") {
-                    map.set(mapKey, marker);
-                }
+                if (typeof marker.id === "string")
+                    map.set(marker.id, marker);
             }
             catch {
                 // unreadable or malformed — skip
@@ -155,7 +148,8 @@ async function writeSeenMarker(key, id, markerFields) {
             // no existing marker — will create below
         }
         const unchanged = Object.entries(markerFields).every(([field, value]) => markerFieldEqual(existing?.[field], value));
-        if (existing !== null && unchanged)
+        // A marker without its `id` is ignored by loadSeenMap, so rewrite it even when unchanged.
+        if (existing !== null && unchanged && existing.id === id)
             return;
         const seenAt = existing?.seenAt ?? Date.now();
         tmp = `${path}.${randomUUID()}.tmp`;

package/bin/state/stack-stall.d.mts

@@ -1,5 +1,5 @@
 /**
- * Persistent stall-detection state for an aggregate `--stack` selection whose open layers can
+ * Persistent stall-detection state for an aggregate `stack` selection whose open layers can
  * only wait. Keyed by native stack number because the anchor PR can merge or change.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/stack-stall.json`.

package/bin/state/stack-stall.mjs

@@ -1,5 +1,5 @@
 /**
- * Persistent stall-detection state for an aggregate `--stack` selection whose open layers can
+ * Persistent stall-detection state for an aggregate `stack` selection whose open layers can
  * only wait. Keyed by native stack number because the anchor PR can merge or change.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/stack-stall.json`.

package/bin/state/stall-state-store.d.mts

@@ -27,7 +27,7 @@ export interface StallStateStore<Key> {
     clear(key: Key): Promise<void>;
 }
 /**
- * `{fingerprint, firstSeenAt}` files behind the one-PR and `--stack` stall guards.
+ * `{fingerprint, firstSeenAt}` files behind the one-PR and `stack` stall guards.
  * A missing file is a miss. An unwritable directory or an unsafe key is a persistence failure
  * so the caller can hand off instead of treating every tick as the first sighting.
  * `ENOENT` is the only read error treated as a miss. Corrupt JSON is also a miss, so one

package/bin/state/stall-state-store.mjs

@@ -2,7 +2,7 @@ import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 /**
- * `{fingerprint, firstSeenAt}` files behind the one-PR and `--stack` stall guards.
+ * `{fingerprint, firstSeenAt}` files behind the one-PR and `stack` stall guards.
  * A missing file is a miss. An unwritable directory or an unsafe key is a persistence failure
  * so the caller can hand off instead of treating every tick as the first sighting.
  * `ENOENT` is the only read error treated as a miss. Corrupt JSON is also a miss, so one

package/bin/types/escalate.d.mts

@@ -2,7 +2,7 @@ import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "transport-unsupported" | "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
+export type EscalateTrigger = "transport-unsupported" | "triage-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -32,7 +32,7 @@ export interface EscalateDetails {
         attempts: number;
     }>;
     /**
-     * Set only when `iterate.reviewOutputMaxChars` held review items back on the tick that
+     * Set only when `iterate.review-output-max-chars` held review items back on the tick that
      * escalated: `shown` of `total` review items appear here. The held items stay unmarked, so the
      * next run shows them.
      */

package/bin/types/github.d.mts

@@ -60,6 +60,8 @@ export interface CheckRun {
     workflowId?: string;
     /** True when GraphQL reported at least one CheckRun annotation. Omitted when false. */
     hasAnnotations?: boolean;
+    /** Annotation total GraphQL reported for this CheckRun. Internal: validates cached lists. */
+    annotationCount?: number;
     /**
      * Every annotation on this run, when BatchPr's `annotations(first: 1)` page already held all
      * of them. Internal: lets the check path skip `CheckRunAnnotationsBatch`; never rendered.