pr-shepherd 0.33.0 → 0.35.0

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/graphql-response.mjs

@@ -1,3 +1,4 @@
+import { EXIT } from "../exit-codes.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds) {
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -34,9 +35,13 @@ export function formatGraphQlErrors(errors) {
         .join("; ");
 }
 function malformedGraphQlResponse(detail, status, rateLimit, retryAfterSeconds) {
+    // A response that fails to parse as valid GraphQL shape is an internal/unexpected
+    // failure, not a precondition or permission problem — force EX_SOFTWARE rather
+    // than letting the (likely 200) status fall through to EX_UNAVAILABLE.
     return new GitHubRequestError(`Malformed GitHub GraphQL response: ${detail}`, {
         status,
         rateLimit: rateLimit ?? undefined,
         retryAfterSeconds,
+        exitCodeOverride: EXIT.SOFTWARE,
     });
 }

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-auth.mjs

@@ -1,5 +1,6 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const execFile = promisify(execFileCb);
 let _token;
 export function _resetTokenCache() {
@@ -35,7 +36,7 @@ async function resolveToken() {
         _token = codexToken;
         return _token;
     }
-    throw new Error("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.");
+    throw new ShepherdError("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.", EXIT.NOPERM);
 }
 export async function makeHeaders() {
     return {

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/rest-http.mjs

@@ -1,8 +1,9 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { redactToken, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactToken, redactUrl, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
 export async function rest(method, path, body) {
     const url = `${BASE_URL}${path}`;
@@ -28,7 +29,11 @@ export async function rest(method, path, body) {
             textBody: redactToken(text),
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`);
+        throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
     }
     if (ct.includes("application/json")) {
         const json = (await res.json());
@@ -80,7 +85,11 @@ export async function restText(path) {
             durationMs,
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`);
+        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
     }
     appendEntry(formatResponseEntry({
         n,
@@ -121,8 +130,13 @@ async function followRestTextRedirect(res, entry) {
         durationMs: Math.round(performance.now() - t1),
         contentLength: parseContentLength(redirectRes.headers),
     }));
-    if (!redirectRes.ok)
-        throw new Error(`redirect target ${location} failed: ${redirectRes.status}`);
+    if (!redirectRes.ok) {
+        throw new GitHubRequestError(`redirect target ${location} failed: ${redirectRes.status}`, {
+            status: redirectRes.status,
+            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+        });
+    }
     return redirectRes.text();
 }
 function parseContentLength(headers) {

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,10 +4,11 @@
  *
  * Usage:
  *   pr-shepherd [PR]
- *   pr-shepherd resolve [PR]
+ *   pr-shepherd apply review [PR]
  *   pr-shepherd iterate [PR]
  */
 import { main } from "./cli-parser.mjs";
+import { errorToExitCode } from "./exit-codes.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {
     if (depth > 5 || seen.has(cause))
         return "[circular or deep cause chain]";
@@ -23,5 +24,5 @@ main(process.argv).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
     const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
     process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
-    process.exit(1);
+    process.exit(errorToExitCode(err));
 });

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;