pr-shepherd 0.43.0 → 0.44.1

package/bin/exit-codes.d.mts

@@ -35,7 +35,7 @@ export declare const EXIT: Readonly<{
     readonly UNAVAILABLE: 69;
     /** Unexpected/unclassified internal error — the fallback. */
     readonly SOFTWARE: 70;
-    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, Retry-After, GraphQL INTERNAL. */
     readonly TEMPFAIL: 75;
     /** GitHub 401/403 — missing token or insufficient PAT scopes. */
     readonly NOPERM: 77;

package/bin/exit-codes.mjs

@@ -34,7 +34,7 @@ export const EXIT = Object.freeze({
     UNAVAILABLE: 69,
     /** Unexpected/unclassified internal error — the fallback. */
     SOFTWARE: 70,
-    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, Retry-After, GraphQL INTERNAL. */
     TEMPFAIL: 75,
     /** GitHub 401/403 — missing token or insufficient PAT scopes. */
     NOPERM: 77,

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/errors.d.mts

@@ -3,7 +3,13 @@ import type { RateLimitInfo } from "./http.mts";
 export interface GitHubGraphQlError {
     message: string;
     path?: unknown;
+    /** GitHub's GraphQL `type` field — `INTERNAL` on engine crashes. */
+    type?: string;
+    /** GraphQL `extensions`; GitHub often sets `{ code: "INTERNAL" }`. */
+    extensions?: unknown;
 }
+/** GitHub GraphQL engine crash: HTTP 200, `data: null`, INTERNAL type/code or message. */
+export declare function isRetryableGraphQlInternal(graphqlErrors?: GitHubGraphQlError[]): boolean;
 export declare class GitHubRequestError extends ShepherdError {
     readonly status: number;
     readonly rateLimit?: RateLimitInfo;

package/bin/github/errors.mjs

@@ -5,16 +5,42 @@ import { EXIT, ShepherdError } from "../exit-codes.mjs";
 // be resolved. Status alone can't see this, so classification must also inspect the
 // GraphQL error messages themselves.
 const GRAPHQL_PERMISSION_ERROR = /resource not accessible/i;
+const GRAPHQL_INTERNAL_MESSAGE = /something went wrong while executing your query/i;
+function isInternalToken(value) {
+    return typeof value === "string" && value.toUpperCase() === "INTERNAL";
+}
+function extensionsCode(extensions) {
+    if (typeof extensions !== "object" || extensions === null || Array.isArray(extensions)) {
+        return undefined;
+    }
+    return extensions["code"];
+}
 function hasPermissionError(graphqlErrors) {
     return graphqlErrors?.some((e) => GRAPHQL_PERMISSION_ERROR.test(e.message)) ?? false;
 }
+/** GitHub GraphQL engine crash: HTTP 200, `data: null`, INTERNAL type/code or message. */
+export function isRetryableGraphQlInternal(graphqlErrors) {
+    if (!graphqlErrors?.length)
+        return false;
+    return graphqlErrors.some((error) => {
+        if (isInternalToken(error.type))
+            return true;
+        if (isInternalToken(extensionsCode(error.extensions)))
+            return true;
+        return GRAPHQL_INTERNAL_MESSAGE.test(error.message);
+    });
+}
 function classifyStatus(status, rateLimit, retryAfterSeconds, graphqlErrors) {
     // Retry signals take priority over everything else: GitHub's secondary rate limit
     // returns 403 with a Retry-After header, which is a transient throttle — not the
     // permission-denied 403 a bad/missing token produces. Treat any retry signal as
     // TEMPFAIL first so it isn't shadowed by the checks below.
     const rateLimitExhausted = rateLimit !== undefined && rateLimit.remaining <= 0;
-    if (status === 429 || status >= 500 || retryAfterSeconds !== undefined || rateLimitExhausted) {
+    if (status === 429 ||
+        status >= 500 ||
+        retryAfterSeconds !== undefined ||
+        rateLimitExhausted ||
+        isRetryableGraphQlInternal(graphqlErrors)) {
         return EXIT.TEMPFAIL;
     }
     if (status === 401 || status === 403 || hasPermissionError(graphqlErrors))

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

@@ -1,6 +1,7 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
+import { withGraphQlInternalRetry } from "./graphql-internal-retry.mjs";
 import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
@@ -96,10 +97,10 @@ async function graphqlInner(query, vars, opts) {
     return { data: payload.data, rateLimit, retryAfterSeconds, errors: payload.errors };
 }
 export async function graphql(query, vars = {}, opts = {}) {
-    const { data, errors } = await graphqlInner(query, vars, opts);
+    const { data, errors } = await withGraphQlInternalRetry(query, () => graphqlInner(query, vars, opts));
     return { data, errors };
 }
 export async function graphqlWithRateLimit(query, vars = {}, opts = {}) {
-    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars, opts);
+    const { data, rateLimit, retryAfterSeconds, errors } = await withGraphQlInternalRetry(query, () => graphqlInner(query, vars, opts));
     return { data, rateLimit: rateLimit ?? undefined, retryAfterSeconds, errors };
 }

package/bin/github/graphql-internal-retry.d.mts

@@ -0,0 +1,2 @@
+/** Retry GitHub GraphQL engine crashes (HTTP 200, data: null, INTERNAL) on reads. */
+export declare function withGraphQlInternalRetry<T>(document: string, run: () => Promise<T>): Promise<T>;

package/bin/github/graphql-internal-retry.mjs

@@ -0,0 +1,50 @@
+import { sleep } from "../util/sleep.mjs";
+import { GitHubRequestError, isRetryableGraphQlInternal } from "./errors.mjs";
+const GRAPHQL_INTERNAL_RETRY_DELAYS = [500, 1500];
+/** True when the root operation is a mutation. Anonymous `{...}` is a query. */
+function isGraphQlMutationDocument(document) {
+    let rest = document;
+    for (;;) {
+        rest = rest.replace(/^\s+/, "");
+        if (rest.startsWith("#")) {
+            const nl = rest.indexOf("\n");
+            rest = nl === -1 ? "" : rest.slice(nl + 1);
+            continue;
+        }
+        if (rest.startsWith('"""')) {
+            const end = rest.indexOf('"""', 3);
+            rest = end === -1 ? "" : rest.slice(end + 3);
+            continue;
+        }
+        break;
+    }
+    return /^mutation\b/i.test(rest);
+}
+function hasServerBackoff(err) {
+    if (err.retryAfterSeconds !== undefined)
+        return true;
+    return err.rateLimit !== undefined && err.rateLimit.remaining <= 0;
+}
+/** Retry GitHub GraphQL engine crashes (HTTP 200, data: null, INTERNAL) on reads. */
+export async function withGraphQlInternalRetry(document, run) {
+    let lastErr;
+    for (let attempt = 1; attempt <= GRAPHQL_INTERNAL_RETRY_DELAYS.length + 1; attempt++) {
+        try {
+            return await run();
+        }
+        catch (err) {
+            if (!(err instanceof GitHubRequestError) ||
+                !isRetryableGraphQlInternal(err.graphqlErrors) ||
+                isGraphQlMutationDocument(document) ||
+                hasServerBackoff(err)) {
+                throw err;
+            }
+            lastErr = err;
+            const delay = GRAPHQL_INTERNAL_RETRY_DELAYS[attempt - 1];
+            if (delay === undefined)
+                break;
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}

package/bin/github/graphql-response.mjs

@@ -13,7 +13,7 @@ export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds
                 typeof error["message"] === "string")) {
             throw malformedGraphQlResponse("errors field is not an array of GraphQL errors", status, rateLimit, retryAfterSeconds);
         }
-        errors = record["errors"];
+        errors = record["errors"].map((error) => parseGraphQlError(error));
     }
     if (!("data" in record)) {
         if (errors?.length)
@@ -26,6 +26,16 @@ export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds
     }
     return { data: record["data"] ?? null, errors };
 }
+function parseGraphQlError(error) {
+    const parsed = { message: error["message"] };
+    if ("path" in error)
+        parsed.path = error["path"];
+    if (typeof error["type"] === "string")
+        parsed.type = error["type"];
+    if (error["extensions"] !== undefined)
+        parsed.extensions = error["extensions"];
+    return parsed;
+}
 export function formatGraphQlErrors(errors) {
     return (errors ?? [])
         .map((error) => {

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;