pr-shepherd 0.43.0 → 0.44.0

package/bin/github/batch-parsers.d.mts

@@ -1,3 +1,3 @@
 import type { BatchPrData } from "../types.mts";
-import type { RawPr, RawThread, RawComment, RawReview, RawReviewSummary, RawContextNode } from "./batch-raw-types.mts";
-export declare function parseRawPr(raw: RawPr, rawThreadPages: RawThread[], rawCommentNodes: RawComment[], rawReviewNodes: RawReview[], rawReviewSummaryNodes: RawReviewSummary[], rawApprovedReviewNodes: RawReviewSummary[], rawCheckNodes: RawContextNode[]): BatchPrData;
+import type { RawBatchResponse, RawPr, RawThread, RawComment, RawReview, RawReviewSummary, RawContextNode } from "./batch-raw-types.mts";
+export declare function parseRawPr(raw: RawPr, rawThreadPages: RawThread[], rawCommentNodes: RawComment[], rawReviewNodes: RawReview[], rawReviewSummaryNodes: RawReviewSummary[], rawApprovedReviewNodes: RawReviewSummary[], rawCheckNodes: RawContextNode[], repository?: Pick<NonNullable<RawBatchResponse["repository"]>, "viewerPermission" | "viewerCanAdminister">): BatchPrData;

package/bin/github/batch-parsers.mjs

@@ -10,6 +10,7 @@ function parseReviewNode(r) {
         author: r.author?.login ?? "unknown",
         authorType: mapAuthorType(r.author?.__typename, r.author?.login),
         ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
+        viewerCanMinimize: "viewerCanMinimize" in r && r.viewerCanMinimize === true,
         body: r.body,
         createdAtUnix: r.createdAt ? parseCreatedAt(r.createdAt) : 0,
     };
@@ -18,7 +19,7 @@ function parseReviewNode(r) {
     }
     return base;
 }
-export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes) {
+export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes, repository) {
     const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
         const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
         return login ? [{ login }] : [];
@@ -37,6 +38,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             author: c.author?.login ?? "unknown",
             authorType: mapAuthorType(c.author?.__typename, c.author?.login),
             ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
+            ...(c.viewerDidAuthor === true && { viewerDidAuthor: true }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,
@@ -46,6 +48,8 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             isResolved: t.isResolved,
             isOutdated: t.isOutdated,
             isMinimized: comment?.isMinimized ?? false,
+            viewerCanReply: t.viewerCanReply === true,
+            viewerCanResolve: t.viewerCanResolve === true,
             path: t.path ?? comment?.path ?? null,
             line: t.line ?? comment?.line ?? null,
             startLine: t.startLine ?? comment?.startLine ?? null,
@@ -55,6 +59,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             ...(comment?.authorAssociation !== undefined && {
                 authorAssociation: comment.authorAssociation,
             }),
+            ...(comment?.viewerDidAuthor === true && { viewerDidAuthor: true }),
             body: comment?.body ?? "",
             url: comment?.url ?? "",
             createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,
@@ -64,6 +69,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
     const comments = rawCommentNodes.map((c) => ({
         id: c.id,
         isMinimized: c.isMinimized,
+        viewerCanMinimize: c.viewerCanMinimize === true,
         author: c.author?.login ?? "unknown",
         authorType: mapAuthorType(c.author?.__typename, c.author?.login),
         ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
@@ -108,6 +114,16 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         headRefOid: raw.headRefOid,
         headRefName: raw.headRefName,
         headRepoWithOwner: raw.headRepository?.nameWithOwner ?? null,
+        viewerAuthorization: {
+            repositoryPermission: repository?.viewerPermission ?? null,
+            viewerCanAdminister: repository?.viewerCanAdminister === true,
+            viewerDidAuthor: raw.viewerDidAuthor === true,
+            viewerCanUpdate: raw.viewerCanUpdate === true,
+            viewerCanEnableAutoMerge: raw.viewerCanEnableAutoMerge === true,
+            viewerCanEditFiles: raw.viewerCanEditFiles === true,
+            headRepositoryPermission: raw.headRepository?.viewerPermission ??
+                null,
+        },
         baseRefName: raw.baseRefName,
         reviewRequests,
         latestReviews,

package/bin/github/batch-raw-types.d.mts

@@ -2,6 +2,8 @@ import type { CommentAuthorAssociation } from "../types/github.mts";
 import type { RawPrMergeFields } from "./batch-raw-rules.mts";
 export interface RawBatchResponse {
     repository: {
+        viewerPermission: string | null;
+        viewerCanAdminister: boolean;
         pullRequest: RawPr | null;
     } | null;
 }
@@ -10,6 +12,10 @@ export interface RawPr extends RawPrMergeFields {
     number: number;
     state: string;
     isDraft: boolean;
+    viewerDidAuthor: boolean;
+    viewerCanUpdate: boolean;
+    viewerCanEnableAutoMerge: boolean;
+    viewerCanEditFiles: boolean;
     mergeable: string;
     mergeStateStatus: string;
     reviewDecision: string | null;
@@ -17,6 +23,7 @@ export interface RawPr extends RawPrMergeFields {
     headRefName: string;
     headRepository: {
         nameWithOwner: string;
+        viewerPermission: string | null;
     } | null;
     baseRefName: string;
     baseRef: import("./batch-raw-rules.mts").RawBaseRef | null;
@@ -117,6 +124,7 @@ export interface RawThreadComment {
     isMinimized: boolean;
     url: string;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: boolean;
     author: RawAuthor | null;
     pullRequestReview?: {
         id: string;
@@ -131,6 +139,8 @@ export interface RawThread {
     id: string;
     isResolved: boolean;
     isOutdated: boolean;
+    viewerCanReply: boolean;
+    viewerCanResolve: boolean;
     path?: string | null;
     line?: number | null;
     startLine?: number | null;
@@ -157,6 +167,7 @@ export interface RawReviewThreadCommentsResponse {
 export interface RawComment {
     id: string;
     isMinimized: boolean;
+    viewerCanMinimize: boolean;
     url: string;
     authorAssociation?: CommentAuthorAssociation;
     author: RawAuthor | null;
@@ -176,6 +187,7 @@ export interface RawReview {
 export interface RawReviewSummary {
     id: string;
     isMinimized: boolean;
+    viewerCanMinimize: boolean;
     authorAssociation?: CommentAuthorAssociation;
     author: RawAuthor | null;
     body: string;

package/bin/github/batch.mjs

@@ -20,7 +20,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
     await hydrateMergeQueueChecks(raw, repo);
     const paged = await paginateBatchConnections(pr, repo, raw, opts, result.rateLimit);
     const rawThreadPages = await hydrateThreadCommentPages(paged.threads);
-    const data = parseRawPr(raw, rawThreadPages, paged.comments, paged.changesRequested, paged.reviewSummaries, paged.approvedReviews, paged.checks);
+    const data = parseRawPr(raw, rawThreadPages, paged.comments, paged.changesRequested, paged.reviewSummaries, paged.approvedReviews, paged.checks, result.data.repository);
     data.checks = mergeStartupFailureChecks(data.checks, parseSuiteStartupFailures(raw));
     return {
         data,

package/bin/github/client.d.mts

@@ -30,6 +30,7 @@ export declare function getPrHeadSha(pr: number, owner: string, name: string): P
 export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
     nodeId: string;
     body: string;
+    viewerCanUpdate?: boolean;
 }>;
 /** Overwrites the PR body. */
 export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;

package/bin/github/client.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 /**
  * High-level GitHub client — wraps http.mts for application-level concerns.
  *
@@ -76,7 +77,13 @@ export async function getPullRequestBody(pr, owner, name) {
             : "PR not found or access denied";
         throw new Error(`Could not fetch body for ${owner}/${name} PR #${pr}: ${detail}`);
     }
-    return { nodeId: pullRequest.id, body: pullRequest.body ?? "" };
+    return {
+        nodeId: pullRequest.id,
+        body: pullRequest.body ?? "",
+        ...(pullRequest.viewerCanUpdate !== undefined && {
+            viewerCanUpdate: pullRequest.viewerCanUpdate,
+        }),
+    };
 }
 /** Overwrites the PR body. */
 export async function updatePullRequestBody(pullRequestId, body) {

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

@@ -29,6 +29,8 @@ query BatchPrPage(
           id
           isResolved
           isOutdated
+          viewerCanReply
+          viewerCanResolve
           path
           line
           startLine
@@ -42,6 +44,7 @@ query BatchPrPage(
               isMinimized
               url
               authorAssociation
+              viewerDidAuthor
               author {
                 __typename
                 login
@@ -66,6 +69,7 @@ query BatchPrPage(
         nodes {
           id
           isMinimized
+          viewerCanMinimize
           url
           authorAssociation
           author {
@@ -108,6 +112,7 @@ query BatchPrPage(
         nodes {
           id
           isMinimized
+          viewerCanMinimize
           authorAssociation
           author {
             __typename
@@ -126,6 +131,7 @@ query BatchPrPage(
         nodes {
           id
           isMinimized
+          viewerCanMinimize
           authorAssociation
           author {
             __typename

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

@@ -2,11 +2,17 @@
 # re-select every connection (GraphQL points scale with possible nodes).
 query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
   repository(owner: $owner, name: $repo) {
+    viewerPermission
+    viewerCanAdminister
     pullRequest(number: $pr) {
       id
       number
       state
       isDraft
+      viewerDidAuthor
+      viewerCanUpdate
+      viewerCanEnableAutoMerge
+      viewerCanEditFiles
       mergeable
       mergeStateStatus
       reviewDecision
@@ -14,6 +20,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       headRefName
       headRepository {
         nameWithOwner
+        viewerPermission
       }
       baseRefName
       isInMergeQueue
@@ -146,6 +153,8 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           id
           isResolved
           isOutdated
+          viewerCanReply
+          viewerCanResolve
           path
           line
           startLine
@@ -159,6 +168,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
               isMinimized
               url
               authorAssociation
+              viewerDidAuthor
               author {
                 __typename
                 login
@@ -183,6 +193,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
         nodes {
           id
           isMinimized
+          viewerCanMinimize
           url
           authorAssociation
           author {
@@ -220,6 +231,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
         nodes {
           id
           isMinimized
+          viewerCanMinimize
           authorAssociation
           author {
             __typename
@@ -240,6 +252,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
         nodes {
           id
           isMinimized
+          viewerCanMinimize
           authorAssociation
           author {
             __typename

package/bin/github/gql/get-pr-body.gql

@@ -3,6 +3,7 @@ query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
     pullRequest(number: $pr) {
       id
       body
+      viewerCanUpdate
     }
   }
 }

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

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

package/bin/github/gql/suggestion-threads.gql

@@ -24,6 +24,7 @@ query SuggestionThreads($owner: String!, $repo: String!, $pr: Int!, $threadIds:
           isMinimized
           url
           authorAssociation
+          viewerDidAuthor
           author {
             __typename
             login

package/bin/github/suggestion-thread.mjs

@@ -41,6 +41,7 @@ function parseThread(raw, pr, threadId) {
         ...(comment?.authorAssociation !== undefined && {
             authorAssociation: comment.authorAssociation,
         }),
+        ...(comment?.viewerDidAuthor === true && { viewerDidAuthor: true }),
         body: comment?.body ?? "",
         url: comment?.url ?? "",
         createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,

package/bin/mcp/server.mjs

@@ -11,7 +11,7 @@ const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/rep
 const pr = z
     .string()
     .refine(isRepositoryQualifiedPrReference, { message: QUALIFIED_PR_ERROR })
-    .describe("GitHub pull-request URL or owner/repo#number");
+    .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 iterateInputSchema = z.object({
     pr,
@@ -19,8 +19,14 @@ const iterateInputSchema = z.object({
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
     merge: z.boolean().optional(),
-    noAutoCancelActionable: z.boolean().optional(),
-    neverCancelRuns: z.array(z.string()).optional(),
+    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."),
 });
 const reviewMutationsOperationSchema = z.object({
     type: z.literal("review_mutations"),
@@ -34,7 +40,7 @@ const reviewMutationsOperationSchema = z.object({
 const markFilesViewedOperationSchema = z.object({
     type: z.literal("mark_files_viewed"),
     files: z.array(z.string().min(1)).optional(),
-    tests: z.boolean().optional(),
+    tests: z.boolean().optional().describe("Select changed test files; no mutation occurs."),
     matchPatterns: z.array(z.string().min(1)).optional(),
 });
 const appendJournalOperationSchema = z.object({
@@ -73,7 +79,7 @@ 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.",
+        description: "Inspect the specified pull request and return the next Shepherd state.",
         inputSchema: iterateInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -83,7 +89,7 @@ export function createPrShepherdMcpServer(options = {}) {
         },
     }, async (input) => runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), formatIterateResult));
     server.registerTool("apply", {
-        description: "Apply ordered review, file-view, and journal operations after prevalidation.",
+        description: "Apply ordered authorized review and journal operations, or run selection-only file-view diagnostics, after prevalidation.",
         inputSchema: applyInputSchema,
         annotations: {
             readOnlyHint: false,

package/bin/pr-reference.d.mts

@@ -2,6 +2,19 @@ export interface ParsedPrReference {
     number?: number;
     repository?: string;
 }
+export interface ResolvedPrTarget {
+    prNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
+}
 /** Parses API PR references without performing repository or GitHub I/O. */
 export declare function parsePrReference(pr: number | string | undefined): ParsedPrReference | null;
+/** Parses a positional CLI PR reference, including a bare numeric string. */
+export declare function parseCliPrReference(value: string): ParsedPrReference | null;
+/** Converts a validated parsed reference into the command-layer target shape. */
+export declare function resolveParsedPrTarget(parsed: ParsedPrReference): ResolvedPrTarget;
+/** Canonical collision-safe PR reference for generated commands and handoffs. */
+export declare function formatPrUrl(repository: string, prNumber: number): string;
 export declare function isRepositoryQualifiedPrReference(pr: unknown): pr is string;

package/bin/pr-reference.mjs

@@ -18,7 +18,7 @@ export function parsePrReference(pr) {
         const parts = url.pathname.split("/").filter(Boolean);
         if ((url.protocol === "https:" || url.protocol === "http:") &&
             (url.hostname === "github.com" || url.hostname === "www.github.com") &&
-            parts.length === 4 &&
+            parts.length >= 4 &&
             parts[2] === "pull" &&
             /^[1-9][0-9]*$/.test(parts[3])) {
             return { number: Number(parts[3]), repository: `${parts[0]}/${parts[1]}` };
@@ -29,6 +29,28 @@ export function parsePrReference(pr) {
     }
     return null;
 }
+/** Parses a positional CLI PR reference, including a bare numeric string. */
+export function parseCliPrReference(value) {
+    if (/^[0-9]+$/.test(value))
+        return { number: Number(value) };
+    return parsePrReference(value);
+}
+/** Converts a validated parsed reference into the command-layer target shape. */
+export function resolveParsedPrTarget(parsed) {
+    if (parsed.repository === undefined)
+        return { prNumber: parsed.number };
+    const [owner, name] = parsed.repository.split("/");
+    if (!owner || !name)
+        throw new Error(`Invalid repository reference: ${parsed.repository}`);
+    return {
+        prNumber: parsed.number,
+        targetRepository: { owner, name },
+    };
+}
+/** Canonical collision-safe PR reference for generated commands and handoffs. */
+export function formatPrUrl(repository, prNumber) {
+    return `https://github.com/${repository}/pull/${prNumber}`;
+}
 export function isRepositoryQualifiedPrReference(pr) {
     if (typeof pr !== "string")
         return false;

package/bin/reporters/agent.mjs

@@ -13,6 +13,8 @@ export function toAgentThread(t) {
     const suggestion = extractSuggestion(t) ?? undefined;
     return {
         id: t.id,
+        ...(t.viewerCanReply === false && { viewerCanReply: false }),
+        ...(t.viewerCanResolve === false && { viewerCanResolve: false }),
         ...(t.reviewId !== undefined && { reviewId: t.reviewId }),
         path: t.path,
         line: t.line,
@@ -22,6 +24,7 @@ export function toAgentThread(t) {
         author: t.author,
         ...(t.authorType !== undefined && { authorType: t.authorType }),
         ...(t.authorAssociation !== undefined && { authorAssociation: t.authorAssociation }),
+        ...(t.viewerDidAuthor === true && { viewerDidAuthor: true }),
         body: t.body,
         url: t.url,
         ...(t.edited === true && { edited: true }),
@@ -31,6 +34,7 @@ export function toAgentThread(t) {
                 author: c.author,
                 ...(c.authorType !== undefined && { authorType: c.authorType }),
                 ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
+                ...(c.viewerDidAuthor === true && { viewerDidAuthor: true }),
                 body: c.body,
                 url: c.url,
             })),
@@ -41,6 +45,7 @@ export function toAgentThread(t) {
 export function toAgentComment(c) {
     return {
         id: c.id,
+        ...(c.viewerCanMinimize === false && { viewerCanMinimize: false }),
         author: c.author,
         ...(c.authorType !== undefined && { authorType: c.authorType }),
         ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),

package/bin/threads/transcript.d.mts

@@ -4,11 +4,13 @@ export declare function threadComments(thread: {
     author: string;
     authorType?: ReviewThreadComment["authorType"];
     authorAssociation?: ReviewThreadComment["authorAssociation"];
+    viewerDidAuthor?: true;
     url?: string;
     createdAtUnix?: number;
     comments?: Array<Pick<ReviewThreadComment, "id" | "author" | "body" | "url"> & {
         authorType?: ReviewThreadComment["authorType"];
         authorAssociation?: ReviewThreadComment["authorAssociation"];
+        viewerDidAuthor?: true;
     } & Partial<Pick<ReviewThreadComment, "isMinimized" | "createdAtUnix">>>;
 }): ReviewThreadComment[];
 export declare function threadTranscriptBody(thread: ReviewThread, appendedBodies?: string[]): string;

package/bin/threads/transcript.mjs

@@ -6,6 +6,7 @@ export function threadComments(thread) {
             author: c.author,
             authorType: c.authorType ?? "Unknown",
             ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
+            ...(c.viewerDidAuthor === true && { viewerDidAuthor: true }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAtUnix ?? 0,
@@ -20,6 +21,7 @@ export function threadComments(thread) {
             ...(thread.authorAssociation !== undefined && {
                 authorAssociation: thread.authorAssociation,
             }),
+            ...(thread.viewerDidAuthor === true && { viewerDidAuthor: true }),
             body: thread.body,
             url: thread.url ?? "",
             createdAtUnix: thread.createdAtUnix ?? 0,

package/bin/types/agent-thread.d.mts

@@ -4,6 +4,7 @@ export interface AgentThreadComment {
     author: string;
     authorType?: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
 }

package/bin/types/escalate.d.mts

@@ -1,7 +1,7 @@
 import type { AgentComment, AgentThread } from "./report.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "bot-cr-not-dismissed" | "merge-queue-removed";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -27,4 +27,9 @@ export interface EscalateDetails {
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;
+    authorization?: Array<{
+        action: "reply-thread" | "resolve-thread" | "dismiss-review" | "mark-ready" | "merge-or-enqueue";
+        targetIds: string[];
+        reason: "denied-or-unverifiable";
+    }>;
 }

package/bin/types/github.d.mts

@@ -7,6 +7,17 @@ export type MergeableState = "CONFLICTING" | "MERGEABLE" | "UNKNOWN";
 export type MergeStateStatus = "BEHIND" | "BLOCKED" | "CLEAN" | "DIRTY" | "DRAFT" | "HAS_HOOKS" | "UNKNOWN" | "UNSTABLE";
 export type ReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
 export type AuthorType = "User" | "Bot" | "Unknown";
+type RepositoryPermission = "NONE" | "READ" | "TRIAGE" | "WRITE" | "MAINTAIN" | "ADMIN";
+/** Raw GitHub viewer fields used to gate remote actions. */
+export interface ViewerAuthorization {
+    repositoryPermission: RepositoryPermission | null;
+    viewerCanAdminister: boolean;
+    viewerDidAuthor: boolean;
+    viewerCanUpdate: boolean;
+    viewerCanEnableAutoMerge: boolean;
+    viewerCanEditFiles: boolean;
+    headRepositoryPermission: RepositoryPermission | null;
+}
 /** Raw relationship between a comment author and the repository, as reported by GitHub. */
 export type CommentAuthorAssociation = "COLLABORATOR" | "CONTRIBUTOR" | "FIRST_TIMER" | "FIRST_TIME_CONTRIBUTOR" | "MANNEQUIN" | "MEMBER" | "NONE" | "OWNER";
 export interface CheckRun {
@@ -40,6 +51,8 @@ export interface ReviewThread {
     isResolved: boolean;
     isOutdated: boolean;
     isMinimized: boolean;
+    viewerCanReply?: boolean;
+    viewerCanResolve?: boolean;
     path: string | null;
     line: number | null;
     /** Start of the comment's line range. Null for single-line comments (use `line` for both). */
@@ -49,6 +62,7 @@ export interface ReviewThread {
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
     createdAtUnix?: number;
@@ -70,6 +84,7 @@ export interface SuggestionBlock {
 export interface PrComment {
     id: string;
     isMinimized: boolean;
+    viewerCanMinimize?: boolean;
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
@@ -82,6 +97,8 @@ export interface Review {
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    /** Present for minimizable COMMENTED/APPROVED reviews; false for non-minimizable review rows. */
+    viewerCanMinimize?: boolean;
     body: string;
     createdAtUnix?: number;
     edited?: boolean;
@@ -123,6 +140,7 @@ export interface BatchPrData extends BatchPrMergeFields {
     headRefName: string;
     /** `"owner/name"` of the head repository; null when the fork has been deleted. */
     headRepoWithOwner: string | null;
+    viewerAuthorization?: ViewerAuthorization;
     baseRefName: string;
     reviewRequests: Array<{
         login: string;
@@ -144,3 +162,4 @@ export interface BatchPrData extends BatchPrMergeFields {
     branchProtection: BranchProtection | null;
     activity?: PrActivitySummary;
 }
+export {};

package/bin/types/iterate.d.mts

@@ -59,9 +59,9 @@ export interface ResolveCommand {
     requiresHeadSha: boolean;
     /** Whether the model must substitute $DISMISS_MESSAGE with a specific description of the fix. */
     requiresDismissMessage: boolean;
-    /** Thread IDs that should receive a reply instead of a resolve mutation. */
+    /** Thread IDs that should receive a reply. Viewer-authored human IDs may also appear in resolveThreadIds. */
     replyThreadIds?: string[];
-    /** Thread IDs that should be resolved on GitHub. Human-authored IDs must not appear here. */
+    /** Thread IDs that should be resolved on GitHub. Human IDs are allowed only for authenticated-viewer reply+resolve pairs or marker-ended retries. */
     resolveThreadIds?: string[];
     /** Bot/non-human CHANGES_REQUESTED review IDs to dismiss. Human-authored IDs must not appear here. */
     dismissReviewIds?: string[];
@@ -69,8 +69,8 @@ export interface ResolveCommand {
     hasMutations: boolean;
 }
 /**
- * Default fix_code variant: agent applies edits locally, commits, pushes,
- * then runs the pre-built apply command. Emitted under `## Post-fix push`.
+ * Default fix_code variant: agent applies edits locally, commits when needed,
+ * then runs the pre-built apply command. Emitted under `## Post-fix actions`.
  */
 interface FixRebaseAndPush {
     threads: AgentThread[];
@@ -90,13 +90,13 @@ interface FixRebaseAndPush {
     changesRequestedReviews: Review[];
     /** Pre-built apply command. Run after committing and pushing. */
     resolveCommand: ResolveCommand;
-    /** When present, run this command first (no SHA substitution needed) to resolve bot threads and minimize comments, independent of any push. */
+    /** When present, run this command first (no SHA substitution needed) for standalone thread resolves and comment minimization, independent of any push. */
     resolveOnlyCommand?: ResolveCommand;
     /** Ordered steps for the model to follow. */
     instructions: string[];
-    /** Run IDs of in-progress GitHub Actions checks. The agent should cancel these before pushing new commits; if it decides not to push (e.g. resolve-only), it may skip cancellation. Empty when all in-progress runs are external status checks or already cancelled. */
+    /** Reserved compatibility field. Always empty because Shepherd cannot verify workflow-cancellation authorization. */
     inProgressRunIds: string[];
-    /** Workflow runs deliberately excluded from cancellation by actions.neverCancelRuns. */
+    /** Reserved compatibility field. Always empty because Shepherd never recommends workflow cancellation. */
     protectedRuns: ProtectedRun[];
     /** Requeue command emitted after merge-group remediation. */
     requeue?: MergeCommandPlan;
@@ -127,10 +127,11 @@ export type IterateResult = IterateResultWait | IterateResultCancel | IterateRes
 export interface IterateCommandOptions extends GlobalOptions {
     readyDelaySeconds?: number;
     noAutoMarkReady?: boolean;
+    /** Legacy no-op retained for API compatibility; workflow runs are never cancelled. */
     noAutoCancelActionable?: boolean;
     /** Override stall timeout seconds. Defaults to config.iterate.stallTimeoutMinutes * 60. */
     stallTimeoutSeconds?: number;
-    /** Case-insensitive workflow/check glob patterns Shepherd must not cancel. */
+    /** Legacy per-invocation no-op retained for API compatibility. */
     neverCancelRuns?: string[];
     persistSeen?: boolean;
     /** Shepherd through readiness and emit the exact merge/queue command when ready. */