pr-shepherd 0.56.6 → 0.57.0

package/bin/github/transport-evidence.d.mts

@@ -0,0 +1,20 @@
+interface TransportEvidence {
+    transport?: "rest";
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
+}
+/** A future GitHub state cannot prove readiness through a negative blocker list. */
+export declare function isKnownMergeStateStatus(status: string): boolean;
+/**
+ * Missing feedback cannot certify readiness, even when GitHub reports CLEAN. Missing branch policy
+ * blocks only a non-CLEAN state, whose unmet requirements Shepherd derives from that policy. The
+ * aggregate `reviewDecision` is never a readiness input on either transport (approvals come from
+ * branch policy plus latest reviews), so its absence alone is not a gap.
+ */
+export declare function transportReadinessGaps(value: TransportEvidence, mergeStateStatus: string): Array<{
+    field: string;
+    reason: string;
+}>;
+export {};

package/bin/github/transport-evidence.mjs

@@ -0,0 +1,26 @@
+/** A future GitHub state cannot prove readiness through a negative blocker list. */
+export function isKnownMergeStateStatus(status) {
+    return [
+        "BEHIND",
+        "BLOCKED",
+        "CLEAN",
+        "DIRTY",
+        "DRAFT",
+        "HAS_HOOKS",
+        "UNKNOWN",
+        "UNSTABLE",
+    ].includes(status);
+}
+/**
+ * Missing feedback cannot certify readiness, even when GitHub reports CLEAN. Missing branch policy
+ * blocks only a non-CLEAN state, whose unmet requirements Shepherd derives from that policy. The
+ * aggregate `reviewDecision` is never a readiness input on either transport (approvals come from
+ * branch policy plus latest reviews), so its absence alone is not a gap.
+ */
+export function transportReadinessGaps(value, mergeStateStatus) {
+    if (value.transport !== "rest")
+        return [];
+    return (value.transportUnavailable ?? []).filter(({ field }) => /^(reviewThreads|reviewTranscripts|changesRequestedReviews|reviewSummaries|checks|checkRuns|checkSuites|checkAnnotations|annotations|nativeStack)(?:\.|$)/.test(field) ||
+        (mergeStateStatus !== "CLEAN" &&
+            ["branchProtection", "branchRules", "mergeRequirements"].some((policy) => field === policy || field.startsWith(`${policy}.`))));
+}

package/bin/github/transport-mode.d.mts

@@ -0,0 +1,2 @@
+export type GithubTransport = "auto" | "graphql" | "rest";
+export declare function parseGithubTransport(value: unknown): GithubTransport;

package/bin/github/transport-mode.mjs

@@ -0,0 +1,5 @@
+export function parseGithubTransport(value) {
+    if (value === "auto" || value === "graphql" || value === "rest")
+        return value;
+    throw new Error('transport must be one of "auto", "graphql", or "rest"');
+}

package/bin/github/transport.d.mts

@@ -0,0 +1,19 @@
+import { type GithubTransport } from "./transport-mode.mts";
+export type { GithubTransport } from "./transport-mode.mts";
+export declare function getGithubTransport(): "graphql" | "rest";
+/** Cloud-session marker or the specific GraphQL refusal observed by this client. */
+export declare function isCcrTransport(): boolean;
+/** Each client retains its auto fallback without sharing state with other clients. */
+export declare function createGithubTransportRunner(mode?: GithubTransport, options?: {
+    verbose?: boolean;
+}): <T>(work: () => Promise<T>, override?: GithubTransport) => Promise<T>;
+/** Wrap the complete command (including every poll tick) in one transport scope. */
+export declare function runWithGithubTransport<T>(mode: GithubTransport | undefined, work: () => Promise<T>, options?: {
+    verbose?: boolean;
+}): Promise<T>;
+/** Allow best-effort GraphQL reads to propagate failures eligible for transport fallback. */
+export declare function isGithubReadFallbackError(error: unknown): boolean;
+/** Choose named implementations; HTTP documents are never interpreted as REST routes. */
+export declare function githubOperation<T>(name: string, graphql: () => Promise<T>, rest: () => Promise<T>, options?: {
+    mutation?: boolean;
+}): Promise<T>;

package/bin/github/transport.mjs

@@ -0,0 +1,126 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { loadConfig } from "../config/load.mjs";
+import { GitHubRequestError, isRetryableGraphQlInternal } from "./errors.mjs";
+import { isTransportError } from "./http-utils.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
+import { isCcrGraphqlRefusal } from "./graphql-session-refusal.mjs";
+import { parseGithubTransport } from "./transport-mode.mjs";
+import { appendEntry } from "../log/log-file.mjs";
+import { hasMixedGraphQlQuotaErrors, isPrimaryGraphQlQuotaExhausted, needsGraphQlQuotaProbe, } from "./graphql-quota-probe.mjs";
+const context = new AsyncLocalStorage();
+function configuredMode() {
+    return loadConfig().github?.transport ?? "auto";
+}
+export function getGithubTransport() {
+    const current = context.getStore();
+    const mode = current?.mode ?? configuredMode();
+    if (mode !== "auto")
+        return mode;
+    return current?.state.fallback || process.env["CLAUDE_CODE_REMOTE"] === "true"
+        ? "rest"
+        : "graphql";
+}
+/** Cloud-session marker or the specific GraphQL refusal observed by this client. */
+export function isCcrTransport() {
+    return process.env["CLAUDE_CODE_REMOTE"] === "true" || context.getStore()?.state.ccr === true;
+}
+/** Each client retains its auto fallback without sharing state with other clients. */
+export function createGithubTransportRunner(mode, options) {
+    if (mode !== undefined)
+        parseGithubTransport(mode);
+    const state = { fallback: false, ccr: false };
+    return function run(work, override) {
+        const selected = parseGithubTransport(override ?? mode ?? configuredMode());
+        return context.run({ mode: selected, state, verbose: options?.verbose }, work);
+    };
+}
+/** Wrap the complete command (including every poll tick) in one transport scope. */
+export function runWithGithubTransport(mode, work, options) {
+    const current = context.getStore();
+    if (current && (mode === undefined || mode === current.mode))
+        return work();
+    return createGithubTransportRunner(mode, options)(work);
+}
+function responseMessage(error) {
+    const raw = error.responseMessage ?? "";
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.message === "string")
+            return parsed.message;
+    }
+    catch { }
+    return raw.trim();
+}
+function fallbackReason(error) {
+    if (isTransportError(error))
+        return "ambiguous";
+    if (!(error instanceof GitHubRequestError))
+        return undefined;
+    if (/bad credentials|requires authentication|resource not accessible|insufficient permission|access denied/i.test(error.responseMessage ?? ""))
+        return undefined;
+    // Mixed GraphQL errors must retain credential, permission and validation failures.
+    if (error.status === 401 ||
+        error.graphqlErrors?.some((entry) => /resource not accessible|permission|forbidden|unauthorized|unknown (?:field|argument)|cannot query|variable .* (?:invalid|required)/i.test(entry.message) ||
+            ["FORBIDDEN", "UNAUTHORIZED", "GRAPHQL_VALIDATION_FAILED", "NOT_FOUND"].includes(entry.type?.toUpperCase() ?? "")))
+        return undefined;
+    const throttle = rateLimitKind(error);
+    if (isRetryableGraphQlInternal(error.graphqlErrors) &&
+        error.graphqlErrors?.some((entry) => !isRetryableGraphQlInternal([entry])))
+        return undefined;
+    if (hasMixedGraphQlQuotaErrors(error.graphqlErrors))
+        return undefined;
+    if (needsGraphQlQuotaProbe(error))
+        return "probe";
+    if (throttle === "secondary")
+        return undefined;
+    if (isCcrGraphqlRefusal(error.status, responseMessage(error)))
+        return "ccr";
+    // Exhausting the quota does not prove an INTERNAL/5xx mutation was refused.
+    if (error.status >= 500 || isRetryableGraphQlInternal(error.graphqlErrors))
+        return "ambiguous";
+    if (throttle === "primary" &&
+        (error.status === 403 ||
+            error.status === 429 ||
+            error.graphqlErrors?.some((entry) => /rate limit/i.test(entry.message) || entry.type === "RATE_LIMITED")) &&
+        (!error.rateLimit?.resource || error.rateLimit.resource === "graphql"))
+        return "refused";
+    return undefined;
+}
+/** Allow best-effort GraphQL reads to propagate failures eligible for transport fallback. */
+export function isGithubReadFallbackError(error) {
+    return fallbackReason(error) !== undefined;
+}
+/** Choose named implementations; HTTP documents are never interpreted as REST routes. */
+export async function githubOperation(name, graphql, rest, options) {
+    const current = context.getStore();
+    if (!current)
+        return runWithGithubTransport(undefined, () => githubOperation(name, graphql, rest, options));
+    if (getGithubTransport() === "rest")
+        return rest();
+    try {
+        return await graphql();
+    }
+    catch (error) {
+        let reason = fallbackReason(error);
+        if (current.mode !== "auto" || reason === undefined)
+            throw error;
+        if (reason === "probe") {
+            if (!(await isPrimaryGraphQlQuotaExhausted()))
+                throw error;
+            reason = "refused";
+        }
+        if (!current.state.fallback) {
+            const message = `pr-shepherd: GitHub transport switched to REST after ${name} (${reason}).\n`;
+            appendEntry(message);
+            if (current.verbose)
+                process.stderr.write(message);
+        }
+        current.state.fallback = true;
+        if (reason === "ccr")
+            current.state.ccr = true;
+        // An ambiguous mutation may already have succeeded; never replay it.
+        if (options?.mutation && reason === "ambiguous")
+            throw error;
+        return rest();
+    }
+}

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

@@ -0,0 +1,4 @@
+import { ShepherdError } from "../exit-codes.mts";
+export declare class UnsupportedRestOperationError extends ShepherdError {
+    constructor(operation: string, reason?: string);
+}

package/bin/github/unsupported-rest.mjs

@@ -0,0 +1,7 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+export class UnsupportedRestOperationError extends ShepherdError {
+    constructor(operation, reason = "no supported REST endpoint is available") {
+        super(`${operation} is unsupported in REST transport: ${reason}`, EXIT.UNAVAILABLE);
+        this.name = "UnsupportedRestOperationError";
+    }
+}

package/bin/mcp/server.mjs

@@ -10,15 +10,19 @@ import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
 import { projectStackOverview } from "../cli/stack-overview.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
+import { formatApplyMergeResult } from "../cli/apply-merge-handler.mjs";
 import { extractShepherdJournal } from "../journal/index.mjs";
+import { formatPlaybookResult, runPlaybook } from "../commands/playbook.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
     .string()
     .refine(isRepositoryQualifiedPrReference, { message: QUALIFIED_PR_ERROR })
     .describe("GitHub pull-request URL or owner/repo#number; the explicit repository may differ from the server working directory");
 const ids = z.array(z.string().min(1)).optional();
+const transport = z.enum(["auto", "graphql", "rest"]).optional();
 const iterateInputSchema = z
     .object({
+    transport,
     pr: pr.optional(),
     prs: z.array(pr).min(1).optional(),
     stack: pr.optional(),
@@ -26,6 +30,14 @@ const iterateInputSchema = z
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
     merge: z.boolean().optional(),
+    instructions: z
+        .enum(["playbook", "inline"])
+        .optional()
+        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit, push and journal into the Fix-code loop playbook."),
+    pollMode: z
+        .enum(["auto", "poll", "event"])
+        .optional()
+        .describe("Overrides poll.mode. event returns one tick with pollMode and nextCheck so the caller owns the wake-up; auto (default) selects event when CLAUDE_CODE_REMOTE=true."),
     noAutoCancelActionable: z
         .boolean()
         .optional()
@@ -66,10 +78,33 @@ const acknowledgeQueueRemovalOperationSchema = z.object({
     queueCommitOid: z.string().regex(/^[0-9a-f]{40}$/),
     removedAtUnix: z.number().int().positive().safe(),
 });
+const mergeOperationSchema = z.object({
+    type: z.literal("merge"),
+    requireSha: z.string().regex(/^[0-9a-f]{40}$/),
+    mergeAction: z.enum(["direct_merge", "merge_queue", "default"]),
+    mergeMethod: z.enum(["merge", "squash", "rebase"]).optional(),
+    expectedStack: z
+        .object({
+        number: z.number().int().positive().safe(),
+        baseRefName: z.string().min(1),
+        prefix: z
+            .array(z.object({
+            pr: z.number().int().positive().safe(),
+            headRefName: z.string().min(1),
+            headRefOid: z.string().regex(/^[0-9a-f]{40}$/),
+            baseRefName: z.string().min(1),
+        }))
+            .min(1)
+            .max(100_000),
+    })
+        .optional(),
+});
 const applyInputSchema = z.object({
+    transport,
     pr,
     operations: z
         .array(z.discriminatedUnion("type", [
+        mergeOperationSchema,
         reviewMutationsOperationSchema,
         markFilesViewedOperationSchema,
         appendJournalOperationSchema,
@@ -78,12 +113,14 @@ const applyInputSchema = z.object({
         .min(1),
 });
 const suggestionPatchInputSchema = z.object({
+    transport,
     pr,
     threadId: z.string().min(1),
     message: z.string().min(1),
     description: z.string().optional(),
 });
 const suggestionPatchesInputSchema = z.object({
+    transport,
     pr,
     suggestions: z
         .array(z.object({
@@ -96,7 +133,7 @@ const suggestionPatchesInputSchema = z.object({
 /** Creates a local-only MCP server with Shepherd's public operations. */
 export function createPrShepherdMcpServer(options = {}) {
     let shepherd = options.shepherd;
-    const getShepherd = () => (shepherd ??= createPrShepherd({ cwd: options.cwd }));
+    const getShepherd = () => (shepherd ??= createPrShepherd({ cwd: options.cwd, transport: options.transport }));
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
         description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
@@ -146,8 +183,8 @@ export function createPrShepherdMcpServer(options = {}) {
         return extractShepherdJournal(input.body);
     }, JSON.stringify));
     server.registerTool("get_journal", {
-        description: "Fetch one pull request body with GraphQL and extract its Shepherd Journal.",
-        inputSchema: z.object({ pr }),
+        description: "Fetch one pull request body through the selected transport and extract its Shepherd Journal.",
+        inputSchema: z.object({ pr, transport }),
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
@@ -155,6 +192,16 @@ export function createPrShepherdMcpServer(options = {}) {
             openWorldHint: true,
         },
     }, async (input) => runTool(() => getShepherd().getJournal(requireRepositoryQualifiedPr(input)), JSON.stringify));
+    server.registerTool("playbook", {
+        description: "Return a playbook named by an instruction-step playbook pointer, from the package. Omit name to list playbooks. Read-only; no GitHub I/O.",
+        inputSchema: z.object({ name: z.string().optional() }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => runTool(async () => runPlaybook(input.name), formatPlaybookResult));
     server.registerTool("build_suggestion_patches", {
         description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
         inputSchema: suggestionPatchesInputSchema,
@@ -235,6 +282,8 @@ function formatApplyResult(result) {
         .map((operation, index) => {
         const heading = `## Operation ${index + 1}: ${operation.type}`;
         switch (operation.type) {
+            case "merge":
+                return `${heading}\n\n${formatApplyMergeResult(operation.result)}`;
             case "review_mutations":
                 return `${heading}\n\n${formatMutateResult(operation.result)}`;
             case "mark_files_viewed":

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

@@ -17,3 +17,5 @@
  */
 import type { BatchPrData, MergeStatusResult } from "../types.mts";
 export declare function deriveMergeStatus(pr: BatchPrData): MergeStatusResult;
+/** Steps 5–9 of the ladder: the status of a non-draft PR without conflicts. */
+export declare function nonDraftMergeStatus(mergeStateStatus: BatchPrData["mergeStateStatus"]): MergeStatusResult["status"];

package/bin/merge-status/derive.mjs

@@ -33,20 +33,8 @@ export function deriveMergeStatus(pr) {
     else if (pr.isDraft || pr.mergeStateStatus === "DRAFT") {
         status = "DRAFT";
     }
-    else if (pr.mergeStateStatus === "BEHIND") {
-        status = "BEHIND";
-    }
-    else if (pr.mergeStateStatus === "BLOCKED" || pr.mergeStateStatus === "HAS_HOOKS") {
-        status = "BLOCKED";
-    }
-    else if (pr.mergeStateStatus === "UNSTABLE") {
-        status = "UNSTABLE";
-    }
-    else if (pr.mergeStateStatus === "UNKNOWN") {
-        status = "UNKNOWN";
-    }
     else {
-        status = "CLEAN";
+        status = nonDraftMergeStatus(pr.mergeStateStatus);
     }
     return {
         status,
@@ -59,6 +47,22 @@ export function deriveMergeStatus(pr) {
         mergeRequirements: deriveMergeRequirements(pr),
     };
 }
+/** Steps 5–9 of the ladder: the status of a non-draft PR without conflicts. */
+export function nonDraftMergeStatus(mergeStateStatus) {
+    switch (mergeStateStatus) {
+        case "BEHIND":
+            return "BEHIND";
+        case "BLOCKED":
+        case "HAS_HOOKS":
+            return "BLOCKED";
+        case "UNSTABLE":
+            return "UNSTABLE";
+        case "CLEAN":
+            return "CLEAN";
+        default:
+            return "UNKNOWN";
+    }
+}
 // ---------------------------------------------------------------------------
 // Blocking bot review detection
 // ---------------------------------------------------------------------------

package/bin/merge-status/required-check-requirements.d.mts

@@ -0,0 +1,7 @@
+import type { MergeStatusResult } from "../types.mts";
+/**
+ * A native-stack layer merges under the stack trunk's rules, not its parent branch's, so
+ * replace the parent's required contexts with the trunk's. A trunk with none clears them.
+ * Any other PR keeps the contexts derived from its own base.
+ */
+export declare function withTrunkRequiredContexts(mergeStatus: MergeStatusResult, contexts: readonly string[]): MergeStatusResult;

package/bin/merge-status/required-check-requirements.mjs

@@ -0,0 +1,15 @@
+/**
+ * A native-stack layer merges under the stack trunk's rules, not its parent branch's, so
+ * replace the parent's required contexts with the trunk's. A trunk with none clears them.
+ * Any other PR keeps the contexts derived from its own base.
+ */
+export function withTrunkRequiredContexts(mergeStatus, contexts) {
+    const requirements = mergeStatus.mergeRequirements;
+    if (!requirements?.stack)
+        return mergeStatus;
+    const { requiredStatusChecks: _parent, ...rest } = requirements;
+    return {
+        ...mergeStatus,
+        mergeRequirements: contexts.length > 0 ? { ...rest, requiredStatusChecks: { contexts: [...contexts] } } : rest,
+    };
+}

package/bin/merge-status/requirements-format.d.mts

@@ -1,3 +1,8 @@
 import type { MergeRequirements } from "../types.mts";
+/**
+ * Lean JSON projection of the merge requirements. Drops exactly the entries that
+ * `formatMergeRequirementLines` omits, so text and JSON stay equivalent.
+ */
+export declare function projectMergeRequirements(req: MergeRequirements): Record<string, unknown> | null;
 export declare function formatMergeRequirementLines(req: MergeRequirements): string[];
 export declare function blockedReasonFromRequirements(req: MergeRequirements | undefined): string | null;

package/bin/merge-status/requirements-format.mjs

@@ -1,10 +1,32 @@
 const REQUIRED = "[Required]";
 const NOT_REQUIRED = "[Not Required]";
+/** No approvals and none required: the trivial default, omitted from lean output. */
+function isTrivialApprovals(req) {
+    return req.approvals.current === 0 && req.approvals.requiredCount === 0;
+}
+/** Resolution is known not to be required: unresolved threads are listed as items anyway. */
+function isTrivialConversations(req) {
+    return req.conversationsResolved.required === false;
+}
+/**
+ * Lean JSON projection of the merge requirements. Drops exactly the entries that
+ * `formatMergeRequirementLines` omits, so text and JSON stay equivalent.
+ */
+export function projectMergeRequirements(req) {
+    const { approvals, conversationsResolved, ...rest } = req;
+    const projected = {
+        ...(!isTrivialApprovals(req) && { approvals }),
+        ...(!isTrivialConversations(req) && { conversationsResolved }),
+        ...rest,
+    };
+    return Object.keys(projected).length > 0 ? projected : null;
+}
 export function formatMergeRequirementLines(req) {
-    const lines = [
-        formatApprovals(req.approvals.current, req.approvals.requiredCount),
-        formatConversations(req.conversationsResolved),
-    ];
+    const lines = [];
+    if (!isTrivialApprovals(req))
+        lines.push(formatApprovals(req.approvals.current, req.approvals.requiredCount));
+    if (!isTrivialConversations(req))
+        lines.push(formatConversations(req.conversationsResolved));
     if (req.codeOwnerReview)
         lines.push(`Code owner review: ${REQUIRED}`);
     if (req.lastPushApproval)
@@ -18,8 +40,8 @@ export function formatMergeRequirementLines(req) {
         lines.push(`Branch up to date: ${value} ${REQUIRED}`);
     }
     if (req.requiredStatusChecks) {
-        const n = req.requiredStatusChecks.contexts.length;
-        lines.push(`Required status checks: ${n} ${REQUIRED}`);
+        const names = req.requiredStatusChecks.contexts.join(", ");
+        lines.push(`Required status checks: ${names} ${REQUIRED}`);
     }
     if (req.requiredDeployments) {
         const envs = req.requiredDeployments.environments.join(", ");
@@ -41,11 +63,13 @@ export function blockedReasonFromRequirements(req) {
     if (!req)
         return null;
     const unmet = [];
-    if (req.approvals.requiredCount > 0 && req.approvals.current < req.approvals.requiredCount) {
+    if (req.approvals.requiredCount !== undefined &&
+        req.approvals.requiredCount > 0 &&
+        req.approvals.current < req.approvals.requiredCount) {
         const need = req.approvals.requiredCount - req.approvals.current;
         unmet.push(`awaiting ${need} approval${need === 1 ? "" : "s"}`);
     }
-    if (req.conversationsResolved.required && !req.conversationsResolved.resolved) {
+    if (req.conversationsResolved.required === true && req.conversationsResolved.resolved === false) {
         unmet.push("unresolved conversations are required");
     }
     if (req.branchUpToDate && !req.branchUpToDate.current) {
@@ -61,9 +85,11 @@ export function blockedReasonFromRequirements(req) {
     return unmet.length > 0 ? unmet.join("; ") : null;
 }
 function formatApprovals(current, requiredCount) {
+    if (requiredCount === undefined) {
+        const currentValue = current === 0 ? "None" : String(current);
+        return `Approvals: ${currentValue} [Requirement Unknown]`;
+    }
     const tag = requiredCount > 0 ? REQUIRED : NOT_REQUIRED;
-    if (current === 0 && requiredCount === 0)
-        return `Approvals: None ${NOT_REQUIRED}`;
     if (current === 0)
         return `Approvals: None ${REQUIRED}`;
     if (requiredCount > 0)
@@ -71,12 +97,15 @@ function formatApprovals(current, requiredCount) {
     return `Approvals: ${current} ${NOT_REQUIRED}`;
 }
 function formatConversations(c) {
-    const value = c.resolved ? "Yes" : "No";
-    const tag = c.required ? REQUIRED : NOT_REQUIRED;
+    const value = c.resolved === undefined ? "Unknown" : c.resolved ? "Yes" : "No";
+    // `required: false` never reaches here (see isTrivialConversations).
+    const tag = c.required === undefined ? "[Requirement Unknown]" : REQUIRED;
     return `Conversations Resolved: ${value} ${tag}`;
 }
 function formatMergeQueue(q) {
     const tag = q.required ? REQUIRED : NOT_REQUIRED;
+    if (q.inQueue === undefined)
+        return `Merge queue: Unknown ${tag}`;
     if (q.inQueue) {
         const pos = q.position != null ? `position ${q.position}` : "Yes";
         const state = q.state ? ` ${q.state}` : "";

package/bin/merge-status/requirements.mjs

@@ -2,16 +2,23 @@ import { EMPTY_BRANCH_RULES } from "../github/batch-parsers-rules.mjs";
 export function deriveMergeRequirements(pr) {
     const rules = pr.branchRules ?? EMPTY_BRANCH_RULES;
     const currentApprovals = pr.latestReviews.filter((r) => r.state === "APPROVED").length;
-    const unresolvedCount = pr.reviewThreads.filter((t) => !t.isResolved).length;
+    const policyUnavailable = pr.transport === "rest" &&
+        (pr.transportUnavailable ?? []).some(({ field }) => /^(?:branchRules|branchProtection)(?:\.|$)/.test(field));
+    const threadStatusUnavailable = pr.reviewThreads.some((thread) => thread.isResolved === undefined);
+    const unresolvedCount = threadStatusUnavailable
+        ? undefined
+        : pr.reviewThreads.filter((thread) => thread.isResolved === false).length;
     const req = {
         approvals: {
             current: currentApprovals,
-            requiredCount: rules.requiredApprovingReviewCount,
+            ...(!policyUnavailable && { requiredCount: rules.requiredApprovingReviewCount }),
         },
         conversationsResolved: {
-            resolved: unresolvedCount === 0,
-            unresolvedCount,
-            required: rules.requiresConversationResolution,
+            ...(unresolvedCount !== undefined && {
+                resolved: unresolvedCount === 0,
+                unresolvedCount,
+            }),
+            ...(!policyUnavailable && { required: rules.requiresConversationResolution }),
         },
     };
     if (rules.requiresCodeOwnerReviews)
@@ -39,8 +46,12 @@ export function deriveMergeRequirements(pr) {
     if (queueRequired || pr.isInMergeQueue) {
         req.mergeQueue = {
             required: queueRequired,
-            enabled: Boolean(pr.isMergeQueueEnabled),
-            inQueue: Boolean(pr.isInMergeQueue),
+            ...(pr.transport !== "rest" || pr.isMergeQueueEnabled !== undefined
+                ? { enabled: Boolean(pr.isMergeQueueEnabled) }
+                : {}),
+            ...(pr.transport !== "rest" || pr.isInMergeQueue !== undefined
+                ? { inQueue: Boolean(pr.isInMergeQueue) }
+                : {}),
             ...(pr.mergeQueueEntry?.position !== undefined && { position: pr.mergeQueueEntry.position }),
             ...(pr.mergeQueueEntry?.state !== undefined && { state: pr.mergeQueueEntry.state }),
         };

package/bin/state/base.mjs

@@ -1,7 +1,9 @@
 import { execFileSync } from "node:child_process";
+import { accessSync, constants, lstatSync, mkdirSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { tmpdir } from "node:os";
 import { SAFE_PR_NUMBER, SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveDurableStateBase } from "./durable-state.mjs";
 /** Read once per process; null when the platform or `getconf` offers no per-user temp dir. */
 let darwinUserTempDir;
 /**
@@ -23,10 +25,49 @@ function readDarwinUserTempDir() {
         return null;
     }
 }
+/** Read once per process; null when the platform is not Linux or the shared base is unusable. */
+let linuxUserStateBase;
+/**
+ * Linux has no per-user temp dir independent of `TMPDIR`, and sandboxed agent shells point
+ * `TMPDIR` at their own directory (e.g. `/tmp/claude-<uid>`). Use `/tmp/pr-shepherd-state-<uid>`
+ * instead so sandboxed and unsandboxed runs share state. `/tmp` is shared by every user, so the
+ * directory must be a real directory (not a symlink) owned by this user and not writable by
+ * anyone else; it must also be readable, writable, and searchable from this process. Otherwise fall back to `TMPDIR`.
+ */
+function readLinuxUserStateBase() {
+    if (process.platform !== "linux" || typeof process.getuid !== "function")
+        return null;
+    const uid = process.getuid();
+    const dir = join("/tmp", `pr-shepherd-state-${uid}`);
+    try {
+        mkdirSync(dir, { mode: 0o700 });
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            return null;
+    }
+    try {
+        const stat = lstatSync(dir);
+        if (!stat.isDirectory() || stat.uid !== uid || (stat.mode & 0o022) !== 0)
+            return null;
+        accessSync(dir, constants.R_OK | constants.W_OK | constants.X_OK);
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
 export function resolveStateBase() {
     const envDir = process.env["PR_SHEPHERD_STATE_DIR"];
     if (envDir)
         return envDir;
+    const durable = resolveDurableStateBase();
+    if (durable)
+        return durable;
+    if (linuxUserStateBase === undefined)
+        linuxUserStateBase = readLinuxUserStateBase();
+    if (linuxUserStateBase)
+        return linuxUserStateBase;
     if (darwinUserTempDir === undefined)
         darwinUserTempDir = readDarwinUserTempDir();
     return join(darwinUserTempDir ?? tmpdir(), "pr-shepherd-state");

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

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