pr-shepherd 0.56.5 → 0.57.0

package/bin/cli/iterate-instructions.mjs

@@ -1,12 +1,19 @@
-import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { inlineCode } from "../util/markdown.mjs";
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
 import { AUTO_MARK_READY_DISABLED_HOLD } from "../commands/stack-work.mjs";
-import { buildPrShepherdCommand } from "./runner.mjs";
+import { buildPrShepherdCommand, renderShellCommand } from "./runner.mjs";
+import { eventWaitSteps } from "../commands/event-instructions.mjs";
+import { playbookPointer } from "../commands/playbook-pointer.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "ready": {
+            if (result.nextCheck) {
+                return [
+                    `PR #${result.pr} is ready. Ready-delay has ${result.remainingSeconds}s left. Do not invent unrelated work.`,
+                    ...eventWaitSteps(result.nextCheck),
+                ];
+            }
             const sentence = `PR #${result.pr} is ready. Ready-delay has ${result.remainingSeconds}s left. Rerun this command when the timer elapses. Do not invent unrelated work.`;
             return [
                 result.quotaWarning ? buildQuotaAwareContinuation(result.quotaWarning, sentence) : sentence,
@@ -14,7 +21,10 @@ export function buildSimpleIterateInstructions(result) {
         }
         case "wait":
             if (result.stackDraftHold)
-                return [buildStackDraftHoldInstruction(result, result.stackDraftHold)];
+                return buildStackDraftHoldInstructions(result, result.stackDraftHold);
+            if (result.nextCheck) {
+                return ["Non-terminal — no action needed this tick.", ...eventWaitSteps(result.nextCheck)];
+            }
             if (result.quotaWarning) {
                 return [
                     buildQuotaAwareContinuation(result.quotaWarning, "Non-terminal — no action needed this tick."),
@@ -24,7 +34,8 @@ export function buildSimpleIterateInstructions(result) {
                 "Non-terminal — no action needed this tick. Iterate immediately with the same options to continue.",
             ];
         case "mark_ready":
-            if (result.quotaWarning) {
+            // Event mode reruns at once too: Shepherd is not polling, so no cadence applies.
+            if (result.quotaWarning && result.pollMode !== "event") {
                 return [
                     buildQuotaAwareContinuation(result.quotaWarning, "The CLI marked the PR ready for review."),
                 ];
@@ -33,32 +44,43 @@ export function buildSimpleIterateInstructions(result) {
                 "The CLI marked the PR ready for review. Iterate immediately with the same options to continue.",
             ];
         case "merge": {
+            // The commands are inline, so no separate `## Merge command` section repeats them.
+            const command = inlineCode(renderShellCommand(result.merge.command.argv));
+            if (result.merge.mode === "rest" && result.nextCheck)
+                return [
+                    `Run the REST merge command exactly as printed: ${command}. \`enqueued\` is not merged.`,
+                    ...eventWaitSteps(result.nextCheck),
+                ];
+            if (result.merge.mode === "rest")
+                return [
+                    `Run the REST merge command exactly as printed: ${command}. If its status is \`pending\`, rerun that same command at the configured polling cadence to resume the recorded request; \`enqueued\` is not merged.`,
+                    "Then iterate with the same options until GitHub confirms the PR merged or needs work.",
+                ];
             const instructions = [
-                `Run the \`${result.merge.mode === "queue" ? "merge queue" : "auto-merge"}\` command shown above exactly as printed.`,
+                `Run the ${result.merge.mode === "queue" ? "merge queue" : "auto-merge"} command exactly as printed: ${command}.`,
             ];
             if (result.merge.mode === "queue" && result.merge.queueApiFallbackCommand) {
-                instructions.push(`If the gh CLI says auto-merge is disabled instead of adding the PR to the queue, run the \`queue API fallback\` command: ${inlineCode(renderMergeCommand(result.merge.queueApiFallbackCommand))}.`);
+                instructions.push(`If gh says auto-merge is disabled instead of adding the PR to the queue, run the queue API fallback: ${inlineCode(renderShellCommand(result.merge.queueApiFallbackCommand.argv))}.`);
             }
             else if (result.merge.fallbackCommand) {
-                instructions.push(`Only if GitHub reports that auto-merge is unavailable, run the \`plain merge fallback\` command: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}.`);
+                instructions.push(`Only if GitHub reports that auto-merge is unavailable, run the plain merge fallback: ${inlineCode(renderShellCommand(result.merge.fallbackCommand.argv))}.`);
             }
             instructions.push(result.quotaWarning
                 ? buildQuotaAwareContinuation(result.quotaWarning, "After running the merge command.")
-                : "Then iterate immediately with the same options to monitor until the PR merges or needs work.");
+                : "Then iterate immediately with the same options until the PR merges or needs work.");
             return instructions;
         }
         case "cancel":
-            return [
-                "Stop polling this pull request — its poll is complete.",
-                "Continue any remaining pull requests or issues from the original request.",
-            ];
+            // `[CANCEL]` needs no steps: stopping, then continuing the original request, is the skill's
+            // invariant recurrence rule, and nothing remains to run for this PR.
+            return [];
         case "escalate": {
             const pending = result.escalate.pendingReviewCommands;
             if (!pending)
                 return ["Stop — human direction is required before automated polling can resume."];
             return [
                 "Stop polling. Ask the user whether to run the pending review commands shown above.",
-                "If yes, replace any `$HEAD_SHA` with the full 40-character pushed PR-head SHA and any `$DISMISS_MESSAGE` with a one-sentence disposition, run every pending command, then rerun Shepherd with the same options.",
+                "If yes, set any `$DISMISS_MESSAGE` to a one-sentence disposition, run every pending command from the pushed PR head, then rerun Shepherd with the same options.",
             ];
         }
     }
@@ -67,18 +89,26 @@ export function buildSimpleIterateInstructions(result) {
  * A held stack draft cannot advance by repeating its one-PR session, so hand control back
  * to the stack selector instead of asking for another immediate iteration.
  */
-function buildStackDraftHoldInstruction(result, hold) {
+function buildStackDraftHoldInstructions(result, hold) {
+    const event = result.pollMode === "event";
     const stackCommand = buildPrShepherdCommand([
         "--stack",
         formatPrUrl(result.repo, result.pr),
         "--until-terminal",
+        ...(event ? ["--poll-mode", "event"] : []),
     ]).text;
     const handoff = `a \`--stack\` selector listed this session, finish that selector's remaining steps and rerun it with its original flags; otherwise run ${inlineCode(stackCommand)}, adding \`--merge\` when merging was requested.`;
     const reason = hold.kind === "auto-mark-ready-disabled" ? AUTO_MARK_READY_DISABLED_HOLD : hold.kind;
     const instruction = `PR #${result.pr} stays in draft because ${reason}, so repeating this one-PR session cannot advance it. If ${handoff}`;
-    return result.quotaWarning
+    const step = result.quotaWarning
         ? buildQuotaAwareContinuation(result.quotaWarning, instruction)
         : instruction;
+    if (!event)
+        return [step];
+    return [
+        step,
+        `Event mode: do not rerun this one-PR session and keep no wake-up for it. After the handoff, follow only the stack selector's output; it ends the turn and schedules the next tick through its own \`nextCheck\`. ${playbookPointer("Cloud event loop")}`,
+    ];
 }
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");

package/bin/cli/iterate-lean.mjs

@@ -1,5 +1,8 @@
 import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
 import { projectRuleAutoResolve } from "../commands/rule-auto-resolve-format.mjs";
+import { projectMergeRequirements } from "../merge-status/requirements-format.mjs";
+import { branchSegmentShowsBase } from "./iterate-branch-segment.mjs";
+import { isRedundantMergeQueue } from "./iterate-merge-formatter.mjs";
 /**
  * Project an IterateResult to a lean JSON shape for the default (non-verbose) output.
  * Omits fields that are the trivial default (false, 0, empty) or state-gated fields
@@ -17,38 +20,56 @@ export function projectIterateLean(result, opts) {
     const hasActivity = activity.commitCount > 0 ||
         activity.reviewRoundCount > 0 ||
         activity.reviewItemsSinceLatestCommit.length > 0;
+    if (result.action === "cancel" && (result.reason === "merged" || result.reason === "closed")) {
+        // Terminal: the PR's checks, reviews, and merge state no longer drive any action.
+        return {
+            action: result.action,
+            pr: result.pr,
+            reason: result.reason,
+            ...(result.ruleAutoResolve && {
+                ruleAutoResolve: projectRuleAutoResolve(result.ruleAutoResolve),
+            }),
+        };
+    }
+    const counts = Object.fromEntries(["passing", "skipped", "filtered", "inProgress", "superseded"]
+        .filter((k) => result.summary[k] > 0)
+        .map((k) => [k, result.summary[k]]));
+    const summary = Object.keys(counts).length > 0 ? counts : null;
+    const mergeRequirements = result.mergeRequirements
+        ? projectMergeRequirements(result.mergeRequirements)
+        : null;
     const base = {
         action: result.action,
         pr: result.pr,
         repo: result.repo || undefined,
+        ...(result.transport && { transport: result.transport }),
+        ...(result.transportUnavailable?.length && {
+            transportUnavailable: result.transportUnavailable,
+        }),
         status: result.status,
-        state: result.state,
-        mergeStateStatus: result.mergeStateStatus,
+        // OPEN and CLEAN are the trivial defaults; the text header omits them the same way.
+        ...(result.state !== "OPEN" && { state: result.state }),
+        ...(result.mergeStateStatus !== "CLEAN" && { mergeStateStatus: result.mergeStateStatus }),
         ...(result.mergeStatus !== "CLEAN" && { mergeStatus: result.mergeStatus }), // mergeStateStatus alone can't always reconstruct this
         ...(readyDelaySuffix && { readyDelayOverride: readyDelaySuffix }),
         ...(result.mergeStatus === "BLOCKED" &&
             result.reviewDecision !== null && { reviewDecision: result.reviewDecision }),
         ...(result.blockingBotReviewInProgress && { blockingBotReviewInProgress: true }),
         ...(result.isDraft && { isDraft: true }),
-        summary: {
-            passing: result.summary.passing,
-            ...(result.summary.skipped > 0 && { skipped: result.summary.skipped }),
-            ...(result.summary.filtered > 0 && { filtered: result.summary.filtered }),
-            ...(result.summary.inProgress > 0 && { inProgress: result.summary.inProgress }),
-            ...(result.summary.superseded > 0 && { superseded: result.summary.superseded }),
-        },
+        ...(summary && { summary }),
         ...(result.status === "READY" &&
             result.remainingSeconds > 0 && {
             remainingSeconds: result.remainingSeconds,
         }),
-        ...(result.baseBranch && { baseBranch: result.baseBranch }),
+        // Lean text shows the base branch only in the behind/conflicts branch segment.
+        ...(branchSegmentShowsBase(result) && { baseBranch: result.baseBranch }),
         ...(result.stackTrunkConflict && { stackTrunkConflict: result.stackTrunkConflict }),
         ...((result.mergedBasePullRequests?.length ?? 0) > 0 && {
             mergedBasePullRequests: result.mergedBasePullRequests,
         }),
         ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
-        ...(result.mergeRequirements && { mergeRequirements: result.mergeRequirements }),
-        ...(result.mergeQueue && { mergeQueue: result.mergeQueue }),
+        ...(mergeRequirements && { mergeRequirements }),
+        ...(result.mergeQueue && !isRedundantMergeQueue(result) && { mergeQueue: result.mergeQueue }),
         ...(hasActivity && {
             activity: {
                 commitCount: activity.commitCount,
@@ -78,6 +99,8 @@ export function projectIterateLean(result, opts) {
         ...(result.baseBehindBy !== undefined &&
             result.baseBehindBy > 0 && { baseBehindBy: result.baseBehindBy }),
         ...(result.quotaWarning && { quotaWarning: result.quotaWarning }),
+        ...(result.pollMode && { pollMode: result.pollMode }),
+        ...(result.nextCheck && { nextCheck: result.nextCheck }),
         ...(result.ruleAutoResolve && {
             ruleAutoResolve: projectRuleAutoResolve(result.ruleAutoResolve),
         }),
@@ -92,7 +115,10 @@ export function projectIterateLean(result, opts) {
         case "wait":
             return {
                 ...base,
-                ...(result.deferredWork && { deferredWork: result.deferredWork }),
+                // Zero counts are omitted, matching the text `**deferred (in merge queue)**` rollup.
+                ...(result.deferredWork && {
+                    deferredWork: Object.fromEntries(Object.entries(result.deferredWork).filter(([, n]) => n > 0)),
+                }),
                 ...(result.stackDraftHold && { stackDraftHold: result.stackDraftHold }),
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
@@ -102,7 +128,6 @@ export function projectIterateLean(result, opts) {
                 ...base,
                 reason: result.reason,
                 log: adaptIterateLog(result.log),
-                instructions: simpleInstructions(result),
             };
         case "mark_ready":
             // drop markedReady — always true, redundant with action discriminator

package/bin/cli/iterate-merge-formatter.d.mts

@@ -1,5 +1,11 @@
 import type { IterateDeferredWork, IterateResult, IterateResultMerge } from "../types.mts";
 /** One inline rollup line of the non-CI work held back while the PR sits in the merge queue. */
 export declare function formatDeferredWorkLine(dw: IterateDeferredWork): string;
+/**
+ * True when `mergeQueue` adds nothing to the `Merge queue:` requirement line: it carries only
+ * `enabled`/`inQueue`, the queue is required (so enabled), and membership matches. Text and JSON
+ * both omit it then.
+ */
+export declare function isRedundantMergeQueue(result: IterateResult): boolean;
 export declare function appendMergeQueueHeader(lines: string[], result: IterateResult): void;
 export declare function formatMergeAction(header: string, result: IterateResultMerge): string;

package/bin/cli/iterate-merge-formatter.mjs

@@ -1,5 +1,4 @@
-import { renderMergeCommand } from "../commands/iterate/merge.mjs";
-import { inlineCode, joinSections } from "../util/markdown.mjs";
+import { joinSections } from "../util/markdown.mjs";
 import { buildSimpleIterateInstructions, numberInstructions } from "./iterate-instructions.mjs";
 /** One inline rollup line of the non-CI work held back while the PR sits in the merge queue. */
 export function formatDeferredWorkLine(dw) {
@@ -16,9 +15,25 @@ export function formatDeferredWorkLine(dw) {
     }
     return `**deferred (in merge queue)** ${parts.join(", ")}`;
 }
+/**
+ * True when `mergeQueue` adds nothing to the `Merge queue:` requirement line: it carries only
+ * `enabled`/`inQueue`, the queue is required (so enabled), and membership matches. Text and JSON
+ * both omit it then.
+ */
+export function isRedundantMergeQueue(result) {
+    const queue = result.mergeQueue;
+    const req = result.mergeRequirements?.mergeQueue;
+    if (!queue || !req)
+        return false;
+    return (Object.keys(queue).every((k) => k === "enabled" || k === "inQueue") &&
+        queue.enabled &&
+        req.required &&
+        req.enabled === true &&
+        req.inQueue === queue.inQueue);
+}
 export function appendMergeQueueHeader(lines, result) {
     const queue = result.mergeQueue;
-    if (!queue)
+    if (!queue || isRedundantMergeQueue(result))
         return;
     const parts = [`enabled \`${queue.enabled}\``, `inQueue \`${queue.inQueue}\``];
     if (queue.entry) {
@@ -46,7 +61,12 @@ export function appendMergeQueueHeader(lines, result) {
         parts.push("removal acknowledged");
     lines.push(`**merge queue** ${parts.join(" · ")}`);
     if (queue.autoMergeRequest) {
-        lines.push(`**auto-merge** method \`${queue.autoMergeRequest.mergeMethod}\` · enabledAtUnix \`${queue.autoMergeRequest.enabledAtUnix}\`${queue.autoMergeRequest.enabledBy ? ` · by \`@${queue.autoMergeRequest.enabledBy}\`` : ""}`);
+        const autoMergeParts = [`method \`${queue.autoMergeRequest.mergeMethod}\``];
+        if (queue.autoMergeRequest.enabledAtUnix !== undefined)
+            autoMergeParts.push(`enabledAtUnix \`${queue.autoMergeRequest.enabledAtUnix}\``);
+        if (queue.autoMergeRequest.enabledBy)
+            autoMergeParts.push(`by \`@${queue.autoMergeRequest.enabledBy}\``);
+        lines.push(`**auto-merge** ${autoMergeParts.join(" · ")}`);
     }
     if (queue.latestRemoval) {
         const removal = queue.latestRemoval;
@@ -54,18 +74,8 @@ export function appendMergeQueueHeader(lines, result) {
     }
 }
 export function formatMergeAction(header, result) {
-    const commandLines = [
-        `- ${result.merge.mode === "queue" ? "merge queue" : "auto-merge"}: ${inlineCode(renderMergeCommand(result.merge.command))}`,
-    ];
-    if (result.merge.fallbackCommand) {
-        commandLines.push(`- plain merge fallback: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}`);
-    }
-    if (result.merge.queueApiFallbackCommand) {
-        commandLines.push(`- queue API fallback: ${inlineCode(renderMergeCommand(result.merge.queueApiFallbackCommand))}`);
-    }
     return joinSections([
         header,
-        `## Merge command\n\n${commandLines.join("\n")}`,
         `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
     ]);
 }

package/bin/cli/iterate-verbose.mjs

@@ -5,10 +5,7 @@ export function projectIterateVerbose(result, opts) {
     if (result.action === "fix_code")
         return { ...result, ...readyDelayOverride };
     const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
-    return {
-        ...result,
-        ...log,
-        ...readyDelayOverride,
-        instructions: buildSimpleIterateInstructions(result),
-    };
+    // `cancel` has no instructions, so verbose JSON omits the field as verbose Markdown omits the section.
+    const instructions = result.action === "cancel" ? {} : { instructions: buildSimpleIterateInstructions(result) };
+    return { ...result, ...log, ...readyDelayOverride, ...instructions };
 }

package/bin/cli/list-formatters.mjs

@@ -3,7 +3,9 @@ import { threadComments } from "../threads/transcript.mjs";
 import { truncateBody, BODY_TRUNCATE_MAX_CHARS, NESTED_BODY_TRUNCATE_MAX_CHARS, } from "./body-truncate.mjs";
 const BODY_PREVIEW_MAX = 100;
 export function renderAuthor(author, authorType, authorAssociation, viewerDidAuthor) {
-    return [`@${author}`, authorType, authorAssociation, viewerDidAuthor ? "viewer-authored" : null]
+    // `User` is the default author type; only `Bot` and `Unknown` are worth a label.
+    const type = authorType === "User" ? null : authorType;
+    return [`@${author}`, type, authorAssociation, viewerDidAuthor ? "viewer-authored" : null]
         .filter(Boolean)
         .join(" · ");
 }

package/bin/cli/mutate-formatter.mjs

@@ -1,6 +1,6 @@
 function pushIds(lines, label, ids) {
     if (ids?.length)
-        lines.push(`${label} (${ids.length}): ${ids.join(", ")}`);
+        lines.push(`${label}: ${ids.join(", ")}`);
 }
 function formatRateLimit(result) {
     const rateLimit = result.rateLimit;
@@ -27,6 +27,8 @@ function formatRateLimit(result) {
 }
 export function formatMutateResult(result) {
     const lines = [];
+    if (result.sessionRefusal)
+        lines.push(`Stopped: GitHub session access refused — ${result.sessionRefusal}`);
     pushIds(lines, "Replied to threads", result.repliedThreads);
     pushIds(lines, "Resolved threads", result.resolvedThreads);
     pushIds(lines, "Minimized comments", result.minimizedComments);
@@ -43,14 +45,17 @@ export function formatMutateResult(result) {
     const rateLimit = formatRateLimit(result);
     if (rateLimit)
         lines.push(rateLimit);
-    pushIds(lines, "Not replied due to rate limit", result.unrepliedThreads);
-    pushIds(lines, "Not resolved due to rate limit", result.unresolvedThreads);
-    pushIds(lines, "Not minimized due to rate limit", result.unminimizedComments);
-    pushIds(lines, "Not dismissed due to rate limit", result.undismissedReviews);
+    const pendingReason = result.sessionRefusal ? "session access" : "rate limit";
+    pushIds(lines, `Not replied due to ${pendingReason}`, result.unrepliedThreads);
+    pushIds(lines, `Not resolved due to ${pendingReason}`, result.unresolvedThreads);
+    pushIds(lines, `Not minimized due to ${pendingReason}`, result.unminimizedComments);
+    pushIds(lines, `Not dismissed due to ${pendingReason}`, result.undismissedReviews);
     const errors = result.rateLimit
         ? result.errors.filter((e) => !e.startsWith("rate limit:"))
         : result.errors;
     if (errors.length)
         lines.push(`Errors:\n  ${errors.join("\n  ")}`);
+    if (result.instructions?.length)
+        lines.push(`## Instructions\n\n${result.instructions.map((instruction, index) => `${index + 1}. ${instruction}`).join("\n")}`);
     return lines.join("\n");
 }

package/bin/cli/next-check-format.d.mts

@@ -0,0 +1,7 @@
+import type { NextCheck } from "../types/next-check.mts";
+/** ` · **pollMode** \`event\``, or nothing in poll mode. */
+export declare function formatPollModeSegment(result: {
+    pollMode?: "event";
+}): string;
+/** The header line naming the next wake-up, or nothing when none applies. */
+export declare function formatNextCheckLines(next: NextCheck | undefined): string[];

package/bin/cli/next-check-format.mjs

@@ -0,0 +1,10 @@
+/** ` · **pollMode** \`event\``, or nothing in poll mode. */
+export function formatPollModeSegment(result) {
+    return result.pollMode ? ` · **pollMode** \`${result.pollMode}\`` : "";
+}
+/** The header line naming the next wake-up, or nothing when none applies. */
+export function formatNextCheckLines(next) {
+    if (!next)
+        return [];
+    return [`**nextCheck** \`${next.at}\` · in ${next.inSeconds}s · reason \`${next.reason}\``];
+}

package/bin/cli/playbook-handler.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Print a playbook shipped in the package, or list the names. Local read only: no GitHub,
+ * git, or log I/O, so playbook pointers resolve without the skill installed.
+ */
+export declare function handlePlaybook(args: string[]): void;

package/bin/cli/playbook-handler.mjs

@@ -0,0 +1,40 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { formatPlaybookResult, runPlaybook } from "../commands/playbook.mjs";
+import { maybePrintHelp } from "./help.mjs";
+/**
+ * Print a playbook shipped in the package, or list the names. Local read only: no GitHub,
+ * git, or log I/O, so playbook pointers resolve without the skill installed.
+ */
+export function handlePlaybook(args) {
+    if (maybePrintHelp(args, "playbook"))
+        return;
+    let format = "text";
+    const words = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--format" || arg.startsWith("--format=")) {
+            const value = arg === "--format" ? args[++index] : arg.slice("--format=".length);
+            if (value !== "text" && value !== "json")
+                return usageError(`invalid --format ${value}`);
+            format = value;
+        }
+        else if (arg.startsWith("-")) {
+            return usageError(`unknown flag ${arg}`);
+        }
+        else {
+            words.push(arg);
+        }
+    }
+    try {
+        const result = runPlaybook(words.join(" "));
+        process.stdout.write(format === "json" ? `${JSON.stringify(result)}\n` : `${formatPlaybookResult(result)}\n`);
+    }
+    catch (error) {
+        process.stderr.write(`pr-shepherd: playbook: ${String(error)}\n`);
+        process.exitCode = error instanceof ShepherdError ? error.exitCode : EXIT.USAGE;
+    }
+}
+function usageError(message) {
+    process.stderr.write(`pr-shepherd: playbook: ${message}\n`);
+    process.exitCode = EXIT.USAGE;
+}

package/bin/cli/poll-handler.mjs

@@ -1,12 +1,11 @@
-import { runPoll } from "../commands/poll.mjs";
+import { runAggregatePollForMode, runPollForMode } from "../commands/event-mode.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
 import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
-import { parseIterateFlags } from "./iterate-flags.mjs";
+import { hasInvalidIterateFlags, parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
 import { EXIT } from "../exit-codes.mjs";
-import { runAggregatePoll } from "../commands/poll-summary.mjs";
 import { emitPollSummaryResult } from "./poll-summary-emitter.mjs";
 import { parsePollTargets, resolvePollTargets } from "./poll-targets.mjs";
 export async function handlePoll(args) {
@@ -23,7 +22,7 @@ export async function handlePoll(args) {
     const extra = isAggregate ? parsedTargets.extra : commonExtra;
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
-    if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
+    if (hasInvalidIterateFlags(flags))
         return;
     const intervalStr = getFlag(extra, "--interval");
     const intervalSuffix = validateSecondsDurationFlag("pr-shepherd", "--interval", intervalStr, hasFlag(extra, "--interval"));
@@ -61,6 +60,8 @@ export async function handlePoll(args) {
         noAutoMarkReady: flags.noAutoMarkReady,
         noAutoCancelActionable: flags.noAutoCancelActionable,
         merge: flags.merge,
+        instructions: flags.instructions ?? undefined,
+        pollMode: flags.pollMode ?? undefined,
         intervalSeconds,
         timeoutSeconds,
         debounceSeconds,
@@ -68,14 +69,14 @@ export async function handlePoll(args) {
         untilTerminal: hasFlag(extra, "--until-terminal"),
     };
     if (isAggregate) {
-        const result = await runAggregatePoll({
+        const result = await runAggregatePollForMode({
             ...shared,
             ...resolvedTargets,
         });
         emitPollSummaryResult(result, { format: globalOpts.format });
         return;
     }
-    const result = await runPoll({ ...shared, prNumber });
+    const result = await runPollForMode({ ...shared, prNumber });
     emitIterateResult(result, {
         format: globalOpts.format,
         verbose: globalOpts.verbose ?? false,

package/bin/cli/poll-summary-formatter.mjs

@@ -1,6 +1,8 @@
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { withPollSummaryInstructions } from "../commands/poll-summary-instructions.mjs";
 import { formatStackOverview, projectStackOverview } from "./stack-overview.mjs";
+import { formatTransportEvidence } from "./transport-formatter.mjs";
+import { formatNextCheckLines, formatPollModeSegment } from "./next-check-format.mjs";
 export function formatPollSummaryResult(result) {
     if (result.selection.kind === "stack")
         return formatStackOverview(projectStackOverview(result));
@@ -8,11 +10,13 @@ export function formatPollSummaryResult(result) {
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
-        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.stackMergeable !== undefined ? ` · **stack mergeable** \`${result.stackMergeable}\`` : ""}${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${formatPollModeSegment(result)}${result.stackMergeable !== undefined ? ` · **stack mergeable** \`${result.stackMergeable}\`` : ""}${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
+        ...formatNextCheckLines(result.nextCheck),
         "",
         "## Pull requests",
         "",
         ...result.prs.map(formatItem),
+        ...formatTransportEvidence(result),
     ];
     if (result.stackAncestry?.length) {
         lines.push("", "## Stack ancestry", "");
@@ -44,11 +48,14 @@ function formatItem(item) {
         : "";
     const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
     const readyReceipt = item.readyReceipt ? " · Shepherd READY completion `verified`" : "";
+    const queuePolicy = item.requiresMergeQueue !== undefined
+        ? ` · merge queue ${item.requiresMergeQueue ? "required" : "not required"}`
+        : "";
     const checks = item.checks;
     const review = item.review;
     return [
         `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
-        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${stack}`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${queuePolicy}${stack}`,
         `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
@@ -68,6 +75,8 @@ function formatItem(item) {
             ]
             : []),
         `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
+        ...(item.transport ? [`  - transport \`${item.transport}\``] : []),
+        ...(item.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
         ...(item.pollCommand
             ? [`  - pollCommand: \`${item.pollCommand}\`${item.pollProbe ? " · bounded probe" : ""}`]
             : []),

package/bin/cli/poll-targets.mjs

@@ -6,6 +6,8 @@ const VALUE_FLAGS = new Set([
     "--format",
     "--ready-delay",
     "--stall-timeout",
+    "--instructions",
+    "--poll-mode",
     "--interval",
     "--timeout",
     "--debounce",

package/bin/cli/resolve-validators.mjs

@@ -15,11 +15,11 @@ export function warnPrrcThreadIds(ids) {
     return prrcIds;
 }
 export function validateRequireSha(sha) {
-    if (sha === undefined)
+    if (sha === undefined || sha === "HEAD")
         return true;
     if (/^[0-9a-f]{40}$/.test(sha))
         return true;
-    process.stderr.write(`pr-shepherd: apply review: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
+    process.stderr.write(`pr-shepherd: apply review: --require-sha must be HEAD or a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid.\n`);
     process.exitCode = EXIT.DATAERR;
     return false;
 }

package/bin/cli/runner.mjs

@@ -1,7 +1,12 @@
 import { loadConfig } from "../config/load.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
 /** Every emitted pr-shepherd command starts with the configured `cliCommand` launcher. */
 export function buildPrShepherdCommand(args) {
-    const argv = [...loadConfig().cliCommand, ...args];
+    const transport = getGithubTransport() === "rest" &&
+        !args.some((arg) => arg === "--transport" || arg.startsWith("--transport="))
+        ? ["--transport", "rest"]
+        : [];
+    const argv = [...loadConfig().cliCommand, ...args, ...transport];
     return { argv, text: renderShellCommand(argv) };
 }
 export function renderShellCommand(argv) {

package/bin/cli/stack-layer-view.d.mts

@@ -0,0 +1,33 @@
+import type { PollSummaryItem } from "../types.mts";
+/** One lean stack row shared by Markdown, JSON, and MCP. */
+export interface StackLayerView {
+    transport?: "rest";
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
+    pr: number;
+    title: string;
+    url: string;
+    state: PollSummaryItem["state"];
+    shepherded?: true;
+    mergeable?: boolean;
+    blocker?: string;
+    author?: string;
+    owned?: true;
+    isDraft?: true;
+    isInMergeQueue?: true;
+    requiresMergeQueue?: boolean;
+    position?: number;
+    stackSize?: number;
+    baseRefName: string;
+    failing?: number;
+    inProgress?: number;
+    actionable?: number;
+    checksIncomplete?: true;
+    reviewIncomplete?: true;
+    queueRemoval?: {
+        reason: string | null;
+        actor?: string;
+    };
+}

package/bin/cli/stack-layer-view.mjs

@@ -0,0 +1 @@
+export {};