pr-shepherd 0.34.0 → 0.35.0

package/bin/github/gql/batch-pr.gql

@@ -82,6 +82,7 @@ query BatchPr(
               id
               isMinimized
               url
+              authorAssociation
               author {
                 __typename
                 login
@@ -107,6 +108,7 @@ query BatchPr(
           id
           isMinimized
           url
+          authorAssociation
           author {
             __typename
             login
@@ -126,6 +128,7 @@ query BatchPr(
         }
         nodes {
           id
+          authorAssociation
           author {
             __typename
             login
@@ -145,6 +148,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          authorAssociation
           author {
             __typename
             login
@@ -164,6 +168,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          authorAssociation
           author {
             __typename
             login

package/bin/github/gql/review-thread-comments.gql

@@ -11,6 +11,7 @@ query ReviewThreadComments($threadId: ID!, $commentsCursor: String) {
           id
           isMinimized
           url
+          authorAssociation
           author {
             __typename
             login

package/bin/github/graphql-http.d.mts

@@ -0,0 +1,19 @@
+import { type GitHubGraphQlError } from "./errors.mts";
+import { type RateLimitInfo } from "./http-utils.mts";
+interface GraphQlResult<T = unknown> {
+    data: T;
+    rateLimit?: RateLimitInfo;
+    retryAfterSeconds?: number;
+    errors?: GitHubGraphQlError[];
+}
+export interface GraphQlRequestOptions {
+    /**
+     * Mutation batches use partial GraphQL data to preserve per-alias successes.
+     * Read paths must keep the strict default so incomplete snapshots never drive
+     * PR state transitions.
+     */
+    allowPartialData?: boolean;
+}
+export declare function graphql<T = unknown>(query: string, vars?: Record<string, unknown>, opts?: GraphQlRequestOptions): Promise<GraphQlResult<T>>;
+export declare function graphqlWithRateLimit<T = unknown>(query: string, vars?: Record<string, unknown>, opts?: GraphQlRequestOptions): Promise<GraphQlResult<T>>;
+export {};

package/bin/github/graphql-response.d.mts

@@ -0,0 +1,7 @@
+import { type GitHubGraphQlError } from "./errors.mts";
+import type { RateLimitInfo } from "./http-utils.mts";
+export declare function parseGraphQlPayload<T>(parsed: unknown, status: number, rateLimit: RateLimitInfo | null, retryAfterSeconds: number | undefined): {
+    data: T | null;
+    errors?: GitHubGraphQlError[];
+};
+export declare function formatGraphQlErrors(errors: GitHubGraphQlError[] | undefined): string;

package/bin/github/http-auth.d.mts

@@ -0,0 +1,4 @@
+export declare function _resetTokenCache(): void;
+export declare function hasCachedToken(): boolean;
+export declare function clearTokenCache(): void;
+export declare function makeHeaders(): Promise<Record<string, string>>;

package/bin/github/http-request.d.mts

@@ -0,0 +1,7 @@
+type RetryLogFn = (status: number, durationMs: number) => void;
+export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn): Promise<{
+    res: Response;
+    attempt: number;
+    retryT0: number;
+}>;
+export {};

package/bin/github/http-utils.d.mts

@@ -0,0 +1,11 @@
+export declare function isTransportError(err: unknown): boolean;
+export interface RateLimitInfo {
+    remaining: number;
+    limit: number;
+    resetAt: number;
+}
+export declare function sanitizeBody(body: string): string;
+export declare function redactToken(body: string): string;
+export declare function redactUrl(url: string): string;
+export declare function parseRateLimit(headers: Headers): RateLimitInfo | null;
+export declare function parseRetryAfter(headers: Headers): number | undefined;

package/bin/github/http.d.mts

@@ -0,0 +1,5 @@
+export { GitHubRequestError } from "./errors.mts";
+export { _resetTokenCache } from "./http-auth.mts";
+export { graphql, graphqlWithRateLimit } from "./graphql-http.mts";
+export { rest, restText } from "./rest-http.mts";
+export type { RateLimitInfo } from "./http-utils.mts";

package/bin/github/pagination.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Generic GraphQL cursor-based paginator for shepherd.
+ *
+ * Both paginators accept a `fetchFn` instead of calling `graphql` directly,
+ * which makes them testable without any mocking — tests supply a pure function
+ * that returns pages of fake data.
+ *
+ * GitHub's GraphQL connections support two cursor directions:
+ *   - Forward (`after` + `first`) — used by check contexts.
+ *   - Backward (`before` + `last`) — used by reviewThreads (default GitHub order).
+ */
+interface PageInfo {
+    hasNextPage?: boolean;
+    hasPreviousPage?: boolean;
+    endCursor?: string | null;
+    startCursor?: string | null;
+}
+export interface Connection<T> {
+    pageInfo: PageInfo;
+    nodes: T[];
+}
+/**
+ * Paginate forward through a GraphQL connection (`first` / `after` cursors).
+ *
+ * @param fetchFn       Called once per page. Receives the cursor (or null for
+ *                      the very first page) and returns a Connection<T>.
+ * @param initialCursor Start from this cursor instead of null. Pass the
+ *                      `endCursor` of an already-fetched page to fetch only
+ *                      the pages *after* it, avoiding a duplicate re-fetch.
+ */
+export declare function paginateForward<T>(fetchFn: (cursor: string | null) => Promise<Connection<T>>, initialCursor?: string | null): Promise<T[]>;
+/**
+ * Paginate backward through a GraphQL connection (`last` / `before` cursors).
+ *
+ * Used for `reviewThreads(last: 100, before: $before)`.
+ *
+ * @param fetchFn       Called once per page. Receives the cursor (or null for
+ *                      the very first page). Returns a Connection<T> with
+ *                      `hasPreviousPage` and `startCursor` in pageInfo.
+ * @param initialCursor Start from this cursor instead of null. Pass the
+ *                      `startCursor` of an already-fetched page to avoid
+ *                      re-fetching it (fetch only the pages *before* it).
+ */
+export declare function paginateBackward<T>(fetchFn: (cursor: string | null) => Promise<Connection<T>>, initialCursor?: string | null): Promise<T[]>;
+export {};

package/bin/github/queries.d.mts

@@ -0,0 +1,24 @@
+/**
+ * GraphQL query strings used by pr-shepherd.
+ *
+ * Static query strings live in src/github/gql/*.gql and are loaded here.
+ * Dynamic documents whose content varies per call (e.g. BulkApply in
+ * src/comments/resolve.mts) are built at runtime and are exempt — they
+ * cannot be expressed as static files.
+ */
+/** The primary batch query that fetches CI + comments + merge status in one round-trip. */
+export declare const BATCH_PR_QUERY: string;
+/** Fetches additional comments for a single review thread when its nested connection paginates. */
+export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
+/** Fetch inline annotations for a single CheckRun by node ID. */
+export declare const CHECK_RUN_ANNOTATIONS_QUERY: string;
+/** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
+export declare const GET_PR_HEAD_SHA_QUERY: string;
+/** Look up PR number by branch name (for getCurrentPrNumber). */
+export declare const PR_NUMBER_BY_BRANCH_QUERY: string;
+/** Convert a draft PR to ready for review. */
+export declare const MARK_PR_READY_MUTATION: string;
+/** Fetch the PR body and node ID. */
+export declare const GET_PR_BODY_QUERY: string;
+/** Update the PR body. */
+export declare const UPDATE_PR_BODY_MUTATION: string;

package/bin/github/rest-http.d.mts

@@ -0,0 +1,2 @@
+export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+export declare function restText(path: string): Promise<string>;

package/bin/github/thread-comments.d.mts

@@ -0,0 +1,2 @@
+import type { RawThread } from "./batch-raw-types.mts";
+export declare function hydrateThreadCommentPages(threads: RawThread[]): Promise<RawThread[]>;

package/bin/index.d.mts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * pr-shepherd — unified GitHub PR status + auto-resolve CLI
+ *
+ * Usage:
+ *   pr-shepherd [PR]
+ *   pr-shepherd apply review [PR]
+ *   pr-shepherd iterate [PR]
+ */
+export {};

package/bin/index.mjs

@@ -4,7 +4,7 @@
  *
  * Usage:
  *   pr-shepherd [PR]
- *   pr-shepherd resolve [PR]
+ *   pr-shepherd apply review [PR]
  *   pr-shepherd iterate [PR]
  */
 import { main } from "./cli-parser.mjs";

package/bin/log/log-file.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Append-only per-worktree markdown log.
+ *
+ * Log path: $PR_SHEPHERD_STATE_DIR/<owner>-<repo>/worktrees/<basename>-<sha8>.md
+ *
+ * Always-on by default. Set PR_SHEPHERD_LOG_DISABLED=1 or CI=true to disable.
+ * Write failures flip an internal disabled flag so the CLI never crashes because
+ * logging failed.
+ */
+/** Returns the next monotonically-increasing entry number for the current session. */
+export declare function nextEntry(): number;
+interface RepoKey {
+    owner: string;
+    repo: string;
+}
+export declare function getLogFilePath(key: RepoKey): string;
+/**
+ * Initialize the log for this process. Must be called before appendEntry().
+ * Silently disables logging on any error (no git repo, bad repo name, etc.).
+ */
+export declare function initLog(repoKey: RepoKey): Promise<string | null>;
+/** Append a pre-formatted markdown chunk to the log. No-op if disabled. */
+export declare function appendEntry(markdown: string): void;
+/** Resolve the log path without initializing (for the log-file subcommand). */
+export declare function resolveLogPath(repoKey: RepoKey): Promise<string>;
+/** Exposed for tests to reset module state. */
+export declare function _resetLogState(): void;
+export {};

package/bin/log/session.d.mts

@@ -0,0 +1,31 @@
+/** Builds the session header markdown block. */
+export declare function buildSessionHeader(argv: string[]): {
+    markdown: string;
+};
+interface HttpRequestEntry {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    body?: unknown;
+}
+interface HttpResponseEntry {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    /** Parsed response body. Omit for restText. */
+    body?: unknown;
+    /** Raw text response body. Omit for restText. */
+    textBody?: string;
+    contentType?: string;
+    contentLength?: number;
+    /** Set on 401-retry invocations. */
+    attempt?: number;
+}
+export declare function formatRequestEntry(entry: HttpRequestEntry): string;
+export declare function formatResponseEntry(entry: HttpResponseEntry): string;
+export declare function formatOutputEntry(text: string, format: "text" | "json"): string;
+export {};

package/bin/log/setup.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Initialize the per-worktree log, write the session header, and install a
+ * stdout tee that routes all CLI output to the log. No-op after the first call.
+ * Silently skips logging when not in a git repo or on any other error.
+ */
+export declare function setupLog(argv: string[]): Promise<void>;

package/bin/mcp/index.d.mts

@@ -0,0 +1,5 @@
+import { type CreatePrShepherdMcpServerOptions } from "./server.mts";
+export { createPrShepherdMcpServer } from "./server.mts";
+export type { CreatePrShepherdMcpServerOptions } from "./server.mts";
+/** Starts the local stdio-only MCP transport. */
+export declare function runPrShepherdMcpStdio(options?: CreatePrShepherdMcpServerOptions): Promise<void>;

package/bin/mcp/index.mjs

@@ -0,0 +1,8 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createPrShepherdMcpServer } from "./server.mjs";
+export { createPrShepherdMcpServer } from "./server.mjs";
+/** Starts the local stdio-only MCP transport. */
+export async function runPrShepherdMcpStdio(options = {}) {
+    const server = createPrShepherdMcpServer(options);
+    await server.connect(new StdioServerTransport());
+}

package/bin/mcp/server.d.mts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CreatePrShepherdOptions, type PrShepherd } from "../api.mts";
+export interface CreatePrShepherdMcpServerOptions extends CreatePrShepherdOptions {
+    /** Optional injection point for embedding hosts and focused tests. */
+    shepherd?: PrShepherd;
+}
+/** Creates a local-only MCP server with the three public Shepherd operations. */
+export declare function createPrShepherdMcpServer(options?: CreatePrShepherdMcpServerOptions): McpServer;

package/bin/mcp/server.mjs

@@ -0,0 +1,157 @@
+/* eslint-disable max-lines */
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
+import { formatJournalResult } from "../cli/journal-formatter.mjs";
+import { formatCommitSuggestionResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { errorToExitCode, EXIT } from "../exit-codes.mjs";
+const pr = z.union([z.number().int().positive(), z.string().url()]).optional();
+const ids = z.array(z.string().min(1)).optional();
+const iterateInputSchema = z.object({
+    pr,
+    readyDelaySeconds: z.number().nonnegative().optional(),
+    stallTimeoutSeconds: z.number().nonnegative().optional(),
+    noAutoMarkReady: z.boolean().optional(),
+    noAutoCancelActionable: z.boolean().optional(),
+    neverCancelRuns: z.array(z.string()).optional(),
+});
+const reviewMutationsOperationSchema = z.object({
+    type: z.literal("review_mutations"),
+    resolveThreadIds: ids,
+    replyThreadIds: ids,
+    minimizeCommentIds: ids,
+    dismissReviewIds: ids,
+    message: z.string().optional(),
+    requireSha: z.string().optional(),
+});
+const markFilesViewedOperationSchema = z.object({
+    type: z.literal("mark_files_viewed"),
+    files: z.array(z.string().min(1)).optional(),
+    tests: z.boolean().optional(),
+    matchPatterns: z.array(z.string().min(1)).optional(),
+});
+const appendJournalOperationSchema = z.object({
+    type: z.literal("append_journal"),
+    item: z.string(),
+    dryRun: z.boolean().optional(),
+});
+const applyInputSchema = z.object({
+    pr,
+    operations: z
+        .array(z.discriminatedUnion("type", [
+        reviewMutationsOperationSchema,
+        markFilesViewedOperationSchema,
+        appendJournalOperationSchema,
+    ]))
+        .min(1),
+});
+const suggestionPatchInputSchema = z.object({
+    pr,
+    threadId: z.string().min(1),
+    message: z.string().min(1),
+    description: z.string().optional(),
+});
+/** Creates a local-only MCP server with the three public Shepherd operations. */
+export function createPrShepherdMcpServer(options = {}) {
+    const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
+    const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
+    server.registerTool("iterate", {
+        description: "Inspect the current pull request and return the next Shepherd state.",
+        inputSchema: iterateInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.iterate(input), formatIterateResult));
+    server.registerTool("apply", {
+        description: "Apply ordered review, file-view, and journal operations after prevalidation.",
+        inputSchema: applyInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.apply(input), formatApplyResult));
+    server.registerTool("build_suggestion_patch", {
+        description: "Build, but never apply, a patch from an eligible review suggestion.",
+        inputSchema: suggestionPatchInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.buildSuggestionPatch(input), formatCommitSuggestionResult));
+    return server;
+}
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}
+function toolResult(result, text) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: result,
+    };
+}
+async function runTool(work, format) {
+    try {
+        const result = await work();
+        return toolResult(result, format(result));
+    }
+    catch (error) {
+        return toolError(error);
+    }
+}
+function formatApplyResult(result) {
+    return result.operations
+        .map((operation, index) => {
+        const heading = `## Operation ${index + 1}: ${operation.type}`;
+        switch (operation.type) {
+            case "review_mutations":
+                return `${heading}\n\n${formatMutateResult(operation.result)}`;
+            case "mark_files_viewed":
+                return `${heading}\n\n${formatMarkFilesAsViewedResult(operation.result)}`;
+            case "append_journal":
+                return `${heading}\n\n${formatJournalResult(operation.result)}`;
+        }
+    })
+        .join("\n\n");
+}
+function toolError(error) {
+    const code = error instanceof PrShepherdValidationError
+        ? EXIT.USAGE
+        : error instanceof PartialApplyError
+            ? errorToExitCode(error.cause)
+            : errorToExitCode(error);
+    const details = error instanceof PartialApplyError
+        ? { failedIndex: error.failedIndex, completed: redactValue(error.completed) }
+        : error instanceof PrShepherdValidationError
+            ? { validation: true }
+            : {};
+    const message = redactErrorMessage(error instanceof Error ? error.message : String(error));
+    return {
+        isError: true,
+        content: [{ type: "text", text: `pr-shepherd error (${code}): ${message}` }],
+        structuredContent: { code, message, details },
+    };
+}
+function redactErrorMessage(message) {
+    return message
+        .replace(/(?:ghp|github_pat)_[A-Za-z0-9_]+/g, "[redacted]")
+        .replace(/(authorization:\s*bearer\s+)[^\s]+/gi, "$1[redacted]");
+}
+function redactValue(value) {
+    if (typeof value === "string")
+        return redactErrorMessage(value);
+    if (Array.isArray(value))
+        return value.map(redactValue);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item)]));
+    }
+    return value;
+}

package/bin/mcp-stdio.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/mcp-stdio.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runPrShepherdMcpStdio } from "./mcp/index.mjs";
+runPrShepherdMcpStdio().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`pr-shepherd-mcp error: ${message}\n`);
+    process.exitCode = 1;
+});

package/bin/merge-status/derive.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Derives a shepherd `MergeStatusResult` from raw PR data.
+ *
+ * `pr.state` is passed through unchanged; `iterate` handles the cancel action
+ * for non-OPEN (merged/closed) PRs — this function does not branch on it.
+ *
+ * Interpretation order for `status` — first match wins:
+ *   1. mergeable == CONFLICTING       → CONFLICTS (hard conflict even for drafts)
+ *   2. blockingBotReviewInProgress        → BLOCKED
+ *   3. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts, even for drafts)
+ *   4. isDraft                        → DRAFT
+ *   5. mergeStateStatus BEHIND        → BEHIND
+ *   6. mergeStateStatus BLOCKED / HAS_HOOKS → BLOCKED
+ *   7. mergeStateStatus UNSTABLE      → UNSTABLE
+ *   8. mergeStateStatus UNKNOWN       → UNKNOWN
+ *   9. mergeStateStatus CLEAN         → CLEAN
+ */
+import type { BatchPrData, MergeStatusResult } from "../types.mts";
+export declare function deriveMergeStatus(pr: BatchPrData): MergeStatusResult;

package/bin/reporters/agent.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Projections for the agent-facing iterate output.
+ *
+ * These strip fields that are always-false by the time items reach iterate
+ * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
+ * agent/iterate prompt never reads (event, status, category).
+ * conclusion is preserved on AgentCheck so the formatter can branch on run-level conclusions.
+ * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
+ * The original domain types are preserved as internal snapshot types.
+ */
+import type { ReviewThread, PrComment, TriagedCheck, ClassifiedCheck, AgentThread, AgentComment, AgentCheck, AgentStalledCheck } from "../types.mts";
+export declare function toAgentThread(t: ReviewThread): AgentThread;
+export declare function toAgentComment(c: PrComment & {
+    edited?: boolean;
+}): AgentComment;
+export declare function toAgentCheck(c: TriagedCheck): AgentCheck;
+export declare function toAgentStalledCheck(c: ClassifiedCheck, nowSeconds: number): AgentStalledCheck;
+/**
+ * Project failing checks for the agent. Deduplicates only null-runId external
+ * checks by name — when runId is present each check may have a distinct job and
+ * log tail, so they are all kept.
+ */
+export declare function toAgentChecks(checks: TriagedCheck[]): AgentCheck[];

package/bin/reporters/agent.mjs

@@ -21,6 +21,7 @@ export function toAgentThread(t) {
             t.startLine !== t.line && { startLine: t.startLine }),
         author: t.author,
         ...(t.authorType !== undefined && { authorType: t.authorType }),
+        ...(t.authorAssociation !== undefined && { authorAssociation: t.authorAssociation }),
         body: t.body,
         url: t.url,
         ...(t.edited === true && { edited: true }),
@@ -29,6 +30,7 @@ export function toAgentThread(t) {
                 id: c.id,
                 author: c.author,
                 ...(c.authorType !== undefined && { authorType: c.authorType }),
+                ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
                 body: c.body,
                 url: c.url,
             })),
@@ -41,6 +43,7 @@ export function toAgentComment(c) {
         id: c.id,
         author: c.author,
         ...(c.authorType !== undefined && { authorType: c.authorType }),
+        ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
         body: c.body,
         url: c.url,
         ...(c.edited === true && { edited: true }),

package/bin/state/base.d.mts

@@ -0,0 +1 @@
+export declare function resolveStateBase(): string;

package/bin/state/bot-cr-seen.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Persistent first-seen state for bot CHANGES_REQUESTED reviews.
+ *
+ * Bot CRs are auto-dismissed via `--dismiss-review-ids` in the post-push
+ * `apply review:` command. If the agent drops that flag, the bot CR keeps the PR in
+ * `CHANGES_REQUESTED` state. This file tracks when each bot CR was first
+ * observed so the iterate loop can escalate after `iterate.stallTimeoutMinutes`
+ * — independent of the broader fingerprint-based `stall-timeout` mechanism in
+ * `iterate-stall.mts` (which only fires when no field of the iterate result
+ * changed).
+ *
+ * State lives in
+ * `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/bot-cr-seen.json`.
+ *
+ * `bodyHash` lets us reset `firstSeenAt` when the bot re-issues the review
+ * with a different body, so a fresh review gets the full timeout window.
+ */
+interface BotCrSeenEntry {
+    /** Unix timestamp (seconds) when this review was first observed undismissed. */
+    firstSeenAt: number;
+    /** SHA-256 body-hash prefix; reset firstSeenAt when this changes. */
+    bodyHash: string;
+}
+export interface BotCrSeenState {
+    reviews: Record<string, BotCrSeenEntry>;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function readBotCrSeenState(key: StateKey): Promise<BotCrSeenState | null>;
+export declare function writeBotCrSeenState(key: StateKey, state: BotCrSeenState): Promise<void>;
+/**
+ * Update tracked entries against the current set of bot CR reviews:
+ * - Insert any new IDs with `firstSeenAt = now` and the current body hash.
+ * - Reset `firstSeenAt` for entries whose body hash changed (review re-issued).
+ * - Drop entries whose IDs are no longer in the input (review was dismissed
+ *   or superseded by an approval).
+ *
+ * Pure function: returns the next state and the IDs whose age has reached the
+ * `stallTimeoutSeconds` threshold (escalate candidates).
+ */
+export declare function updateBotCrSeenState(previous: BotCrSeenState | null, currentBotCrReviews: ReadonlyArray<{
+    id: string;
+    body: string;
+}>, nowSeconds: number, stallTimeoutSeconds: number): {
+    next: BotCrSeenState;
+    staleIds: string[];
+};
+export {};

package/bin/state/bot-cr-seen.mjs

@@ -2,7 +2,7 @@
  * Persistent first-seen state for bot CHANGES_REQUESTED reviews.
  *
  * Bot CRs are auto-dismissed via `--dismiss-review-ids` in the post-push
- * `resolve:` command. If the agent drops that flag, the bot CR keeps the PR in
+ * `apply review:` command. If the agent drops that flag, the bot CR keeps the PR in
  * `CHANGES_REQUESTED` state. This file tracks when each bot CR was first
  * observed so the iterate loop can escalate after `iterate.stallTimeoutMinutes`
  * — independent of the broader fingerprint-based `stall-timeout` mechanism in

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

@@ -0,0 +1,27 @@
+/**
+ * Persistent attempt counter for the iterate escalation guard.
+ *
+ * Tracks how many times each review thread has been dispatched to the fix_code
+ * handler without being resolved. Counts are reset automatically when the HEAD
+ * commit SHA changes (i.e. a new push landed).
+ *
+ * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
+ */
+export interface FixAttemptsState {
+    /** HEAD SHA at the time the counts were last written. Reset key. */
+    headSha: string;
+    /** Map from thread ID → number of fix_code 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>;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+/** Read the current attempt state. Returns null on miss. */
+export declare function readFixAttempts(key: StateKey): Promise<FixAttemptsState | null>;
+/** Write attempt state (fire-and-forget — never throws). */
+export declare function writeFixAttempts(key: StateKey, state: FixAttemptsState): Promise<void>;
+export {};