pr-shepherd 0.56.6 → 0.57.1

package/bin/cli/stack-overview.d.mts

@@ -1,32 +1,13 @@
-import type { PollSummaryItem, PollSummaryResult, PollSummaryStackAncestry, StackNextAction } from "../types.mts";
+import type { PollSummaryResult, PollSummaryStackAncestry, StackNextAction } from "../types.mts";
 import type { ApiUsage, GraphqlQuotaWarning } from "../types/api-usage.mts";
-/** Agent-facing stack row. Planning keeps the richer PollSummaryItem. */
-interface StackLayerView {
-    pr: number;
-    title: string;
-    url: string;
-    state: PollSummaryItem["state"];
-    shepherded: boolean;
-    mergeable: boolean;
-    blocker?: string;
-    author?: string;
-    owned?: true;
-    isDraft?: true;
-    isInMergeQueue?: true;
-    position?: number;
-    stackSize?: number;
-    baseRefName: string;
-    failing?: number;
-    inProgress?: number;
-    actionable?: number;
-    checksIncomplete?: true;
-    reviewIncomplete?: true;
-    queueRemoval?: {
-        reason: string | null;
-        actor?: string;
-    };
-}
+import type { StackLayerView } from "./stack-layer-view.mts";
+import type { NextCheck } from "../types/next-check.mts";
 export interface StackOverview {
+    transport?: "rest";
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
     mode: "summary";
     repo: string;
     selection: Extract<PollSummaryResult["selection"], {
@@ -40,9 +21,10 @@ export interface StackOverview {
     instructions?: string[];
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;
+    pollMode?: "event";
+    nextCheck?: NextCheck;
 }
 /** Lean stack payload shared by Markdown, JSON, and MCP. */
 export declare function projectStackOverview(result: PollSummaryResult): StackOverview;
 /** Markdown for a stack overview. */
 export declare function formatStackOverview(overview: StackOverview): string;
-export {};

package/bin/cli/stack-overview.mjs

@@ -1,5 +1,8 @@
 import { stackLayerBlockReason } from "../commands/stack-layer-readiness.mjs";
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
+import { formatTransportEvidence } from "./transport-formatter.mjs";
+import { formatNextCheckLines } from "./next-check-format.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
 /** Lean stack payload shared by Markdown, JSON, and MCP. */
 export function projectStackOverview(result) {
     const selection = result.selection;
@@ -10,32 +13,43 @@ export function projectStackOverview(result) {
     return {
         mode: "summary",
         repo: result.repo,
+        ...(result.transport && { transport: result.transport }),
+        ...(result.transportUnavailable?.length && {
+            transportUnavailable: result.transportUnavailable,
+        }),
         selection,
         reason: result.reason,
-        ...(result.stackMergeable !== undefined && { stackMergeable: result.stackMergeable }),
+        ...(result.stackMergeable && { stackMergeable: true }),
         ...(result.nextAction && { nextAction: result.nextAction }),
         prs: result.prs.map((item) => projectLayer(item, stale.has(item.pr))),
         ...(result.stackAncestry?.length && { stackAncestry: result.stackAncestry }),
         ...(result.instructions?.length && { instructions: result.instructions }),
         ...(result.apiUsage && { apiUsage: result.apiUsage }),
         ...(result.quotaWarning && { quotaWarning: result.quotaWarning }),
+        ...(result.pollMode && { pollMode: result.pollMode }),
+        ...(result.nextCheck && { nextCheck: result.nextCheck }),
     };
 }
 function projectLayer(item, stale) {
-    const blocker = layerBlocker(item, stale);
+    // A merged or closed layer's state already says it will not merge; skip the `closed` blocker.
+    const open = item.state === "OPEN";
+    const blocker = open ? layerBlocker(item, stale) : undefined;
     const removal = item.queueRemoval;
     return {
         pr: item.pr,
+        ...(item.transport && { transport: item.transport }),
+        ...(item.transportUnavailable?.length && { transportUnavailable: item.transportUnavailable }),
         title: item.title,
         url: item.url,
         state: item.state,
-        shepherded: item.readyReceipt === true,
-        mergeable: blocker === undefined,
+        ...(item.readyReceipt === true && { shepherded: true }),
+        ...(open && { mergeable: blocker === undefined }),
         ...(blocker && { blocker }),
         ...(item.authorLogin && { author: item.authorLogin }),
         ...(item.owned && { owned: true }),
         ...(item.isDraft && { isDraft: true }),
         ...(item.isInMergeQueue && { isInMergeQueue: true }),
+        ...(item.requiresMergeQueue !== undefined && { requiresMergeQueue: item.requiresMergeQueue }),
         ...(item.stack && { position: item.stack.position, stackSize: item.stack.size }),
         baseRefName: item.baseRefName,
         ...(blocker === "failing-checks" &&
@@ -80,15 +94,15 @@ export function formatStackOverview(overview) {
     const lines = [
         `# ${overview.repo} stack #${stack.stackNumber}${stackTerminalTag(overview.nextAction)} — ${overview.reason}`,
         "",
-        `Stack: #${stack.stackNumber} · anchor PR #${stack.anchor} · ${stack.stackSize} layers · mode \`${overview.mode}\``,
-        ...(overview.stackMergeable !== undefined
-            ? [`stackMergeable: ${overview.stackMergeable}`]
-            : []),
+        `anchor PR #${stack.anchor} · ${stack.stackSize} layers · mode \`${overview.mode}\`${overview.pollMode ? ` · pollMode \`${overview.pollMode}\`` : ""}`,
+        ...(overview.stackMergeable ? ["stackMergeable: true"] : []),
         ...(overview.nextAction ? [`nextAction: ${overview.nextAction}`] : []),
+        ...formatNextCheckLines(overview.nextCheck),
         "",
         "## Layers",
         "",
-        ...overview.prs.flatMap(formatLayerLines),
+        ...overview.prs.flatMap((layer, i) => formatLayerLines(layer, i, overview)),
+        ...formatTransportEvidence(overview),
     ];
     if (overview.stackAncestry?.length) {
         lines.push("", "## Stack ancestry", "");
@@ -107,10 +121,16 @@ export function formatStackOverview(overview) {
         lines.push("", usage);
     return lines.join("\n");
 }
-function formatLayerLines(layer) {
+// `inOrder`: the list index shows the position; a row links only a URL the repo/number don't imply.
+function formatLayerLines(layer, index, overview) {
+    const inOrder = layer.position === index + 1 && layer.stackSize === overview.selection.stackSize;
     const facts = [
-        layer.shepherded ? "shepherded" : "not shepherded",
-        layer.mergeable ? "mergeable" : `not mergeable (\`${layer.blocker ?? "unknown"}\`)`,
+        layer.shepherded ? "shepherded" : undefined,
+        layer.mergeable === undefined
+            ? undefined
+            : layer.mergeable
+                ? "mergeable"
+                : `not mergeable (\`${layer.blocker ?? "unknown"}\`)`,
         layer.author ? `owner \`@${layer.author}\`` : undefined,
         layer.owned ? "owned" : undefined,
     ].filter((fact) => fact !== undefined);
@@ -118,7 +138,10 @@ function formatLayerLines(layer) {
         layer.state,
         layer.isDraft ? "draft" : undefined,
         layer.isInMergeQueue ? "in merge queue" : undefined,
-        layer.position !== undefined && layer.stackSize !== undefined
+        layer.requiresMergeQueue !== undefined
+            ? `merge queue ${layer.requiresMergeQueue ? "required" : "not required"}`
+            : undefined,
+        !inOrder && layer.position !== undefined && layer.stackSize !== undefined
             ? `position ${layer.position}/${layer.stackSize}`
             : undefined,
         `base \`${layer.baseRefName}\``,
@@ -132,7 +155,9 @@ function formatLayerLines(layer) {
             : undefined,
     ].filter((detail) => detail !== undefined);
     return [
-        `- [PR #${layer.pr}: ${layer.title}](${layer.url}) — ${facts.join(" · ")}`,
+        `- ${layer.url === formatPrUrl(overview.repo, layer.pr) ? `PR #${layer.pr}: ${layer.title}` : `[PR #${layer.pr}: ${layer.title}](${layer.url})`}${facts.length > 0 ? ` — ${facts.join(" · ")}` : ""}`,
         `  - ${details.join(" · ")}`,
+        ...(layer.transport ? [`  - transport \`${layer.transport}\``] : []),
+        ...(layer.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
     ];
 }

package/bin/cli/transport-args.d.mts

@@ -0,0 +1,5 @@
+/** Strip the global flag before subcommand detection; validation follows help. */
+export declare function extractTransportArgs(raw: string[]): {
+    args: string[];
+    transport?: string;
+};

package/bin/cli/transport-args.mjs

@@ -0,0 +1,23 @@
+/** Strip the global flag before subcommand detection; validation follows help. */
+export function extractTransportArgs(raw) {
+    const args = [];
+    let transport;
+    for (let index = 0; index < raw.length; index += 1) {
+        const arg = raw[index];
+        if (arg.startsWith("--transport=")) {
+            transport = arg.slice("--transport=".length);
+        }
+        else if (arg === "--transport") {
+            const next = raw[index + 1];
+            transport = next && !next.startsWith("-") ? raw[++index] : "";
+        }
+        else {
+            args.push(arg);
+            // A flag-looking string can be another option's literal value.
+            if (FLAGS_WITH_VALUES.has(arg) && index + 1 < raw.length)
+                args.push(raw[++index]);
+        }
+    }
+    return { args, transport };
+}
+import { FLAGS_WITH_VALUES } from "./arg-flags.mjs";

package/bin/cli/transport-formatter.d.mts

@@ -0,0 +1,9 @@
+interface TransportEvidence {
+    transport?: "rest";
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
+}
+export declare function formatTransportEvidence(value: TransportEvidence): string[];
+export {};

package/bin/cli/transport-formatter.mjs

@@ -0,0 +1,13 @@
+export function formatTransportEvidence(value) {
+    return [
+        ...(value.transport ? [`**transport** \`${value.transport}\``] : []),
+        ...(value.transportUnavailable?.length
+            ? [
+                "",
+                "## Unavailable transport fields",
+                "",
+                ...value.transportUnavailable.map(({ field, reason }) => `- \`${field}\`: ${reason}`),
+            ]
+            : []),
+    ];
+}

package/bin/cli-parser.mjs

@@ -1,25 +1,60 @@
 /* eslint-disable max-lines */
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
-import { EXIT, errorToExitCode } from "./exit-codes.mjs";
+import { EXIT, applyReviewResultToExitCode, errorToExitCode } from "./exit-codes.mjs";
 import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
+import { handleClean } from "./cli/clean-handler.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
-import { handleClean, handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
+import { handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
 import { handleJournalExtract } from "./cli/journal-extract-handler.mjs";
+import { handlePlaybook } from "./cli/playbook-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { handleCheckBlocker } from "./cli/check-blocker-handler.mjs";
 import { handleQueueRemoval } from "./cli/queue-removal-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
+import { rejectInvalidPollModeFlag, runInEventStateScope, runInPollModeScope, } from "./cli/event-state-scope.mjs";
+import { handleApplyMerge } from "./cli/apply-merge-handler.mjs";
+import { getLocalHeadSha } from "./commands/suggestion-patch-git.mjs";
+import { extractTransportArgs } from "./cli/transport-args.mjs";
+import { parseGithubTransport } from "./github/transport-mode.mjs";
+import { runWithGithubTransport } from "./github/transport.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
 export async function main(argv) {
+    const extracted = extractTransportArgs(argv.slice(2));
+    const dispatched = [...argv.slice(0, 2), ...extracted.args];
+    // Help and version retain their I/O-free short circuit, even with invalid flags.
+    if (extracted.args.some((arg) => arg === "--help" || arg === "-h") ||
+        extracted.args[0] === "--version" ||
+        extracted.args[0] === "-v" ||
+        extracted.args[0] === "log-file" ||
+        extracted.args[0] === "playbook" ||
+        (extracted.args[0] === "admin" && extracted.args[1] === "log-file") ||
+        (extracted.args[0] === "journal" && extracted.args[1] === "extract")) {
+        return dispatch(dispatched);
+    }
+    let mode;
+    try {
+        mode =
+            extracted.transport === undefined ? undefined : parseGithubTransport(extracted.transport);
+    }
+    catch (error) {
+        process.stderr.write(`pr-shepherd: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    return runWithGithubTransport(mode, () => dispatch(dispatched), {
+        verbose: extracted.args.includes("--verbose"),
+    });
+}
+async function dispatch(argv) {
     const args = argv.slice(2); // strip node + script path
     const subcommand = args[0];
     if (subcommand === "--version" || subcommand === "-v") {
@@ -69,6 +104,17 @@ export async function main(argv) {
     if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
         warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
     }
+    // A local read of shipped files: no GitHub, git, or log I/O.
+    if (subcommand === "playbook") {
+        handlePlaybook(args.slice(1));
+        return;
+    }
+    // Event mode enters the durable state scope before the log resolves its path.
+    return runInEventStateScope(args, () => dispatchLogged(argv));
+}
+async function dispatchLogged(argv) {
+    const args = argv.slice(2);
+    const subcommand = args[0];
     // Initialize the per-worktree log and install a stdout tee.
     await setupLog(argv);
     if (isDefaultPollInvocation(subcommand)) {
@@ -124,6 +170,9 @@ function warnLegacyAlias(alias, replacement) {
 async function handleApply(args) {
     const action = args[0];
     switch (action) {
+        case "merge":
+            await handleApplyMerge(args.slice(1));
+            return;
         case "review":
             await handleResolve(args.slice(1));
             return;
@@ -167,13 +216,16 @@ function readVersion() {
 async function handleLogFile(args, usageKey = "log-file") {
     if (maybePrintHelp(args, usageKey))
         return;
+    if (rejectInvalidPollModeFlag(args, usageKey))
+        return;
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {
             const idx = args.indexOf("--format");
             return idx !== -1 && args[idx + 1] === "json";
         })();
     try {
-        const result = await runLogFile();
+        // Report the log the matching tick writes: event mode keeps it in durable state.
+        const result = await runInPollModeScope(args, () => runLogFile());
         process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${result.path}\n`);
     }
     catch (e) {
@@ -189,6 +241,7 @@ async function handleResolve(args, command = "apply review") {
     const dismissReviewIds = parseList(getFlag(extra, "--dismiss-review-ids"));
     const dismissMessage = getFlag(extra, "--message") ?? undefined;
     const requireSha = getFlag(extra, "--require-sha") ?? undefined;
+    const adoptExistingReplies = hasFlag(extra, "--adopt-existing-replies");
     warnPrrcThreadIds(resolveThreadIds);
     if (!validateRequireSha(requireSha))
         return;
@@ -216,12 +269,14 @@ async function handleResolve(args, command = "apply review") {
         minimizeCommentIds,
         dismissReviewIds,
         dismissMessage,
-        requireSha,
+        // `HEAD` reads this checkout's commit (read-only `git rev-parse HEAD`), as the shell would.
+        requireSha: requireSha === "HEAD" ? await getLocalHeadSha() : requireSha,
+        ...(adoptExistingReplies && { adoptExistingReplies }),
     });
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatMutateResult(result)}\n`);
-    if (result.errors.length > 0) {
-        process.exitCode = result.rateLimit ? EXIT.TEMPFAIL : EXIT.UNAVAILABLE;
-    }
+    const exitCode = applyReviewResultToExitCode(result);
+    if (exitCode !== EXIT.OK)
+        process.exitCode = exitCode;
 }

package/bin/commands/apply-merge-options.d.mts

@@ -0,0 +1,4 @@
+import type { RestMergeOptions } from "../github/rest-merge.mts";
+export declare function validateApplyMergeOptions(input: RestMergeOptions): void;
+export declare function sameMergeOptions(left: RestMergeOptions, right: RestMergeOptions): boolean;
+export declare function validateApplyMergeTarget(input: RestMergeOptions, pr: number | undefined): void;

package/bin/commands/apply-merge-options.mjs

@@ -0,0 +1,34 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { restMergeStackGuardKey, validateRestMergeStackGuard, } from "../github/rest-merge-stack-guard.mjs";
+export function validateApplyMergeOptions(input) {
+    if (input.expectedStack !== undefined) {
+        try {
+            validateRestMergeStackGuard(input.expectedStack);
+        }
+        catch (error) {
+            throw new ShepherdError(error instanceof Error ? error.message : String(error), EXIT.DATAERR);
+        }
+        if (input.expectedStack.prefix.at(-1)?.headRefOid !== input.requireSha)
+            throw new ShepherdError("expectedStack prefix head must match --require-sha", EXIT.DATAERR);
+    }
+    if (typeof input.requireSha !== "string" || !/^[0-9a-f]{40}$/.test(input.requireSha))
+        throw new ShepherdError("--require-sha must be a full 40-character lowercase hex SHA", EXIT.DATAERR);
+    if (!["direct_merge", "merge_queue", "default"].includes(input.mergeAction))
+        throw new ShepherdError("--merge-action must be direct_merge, merge_queue, or default", EXIT.USAGE);
+    if (input.mergeMethod !== undefined && !["merge", "squash", "rebase"].includes(input.mergeMethod))
+        throw new ShepherdError("--method must be merge, squash, or rebase", EXIT.USAGE);
+    if (input.mergeMethod !== undefined && input.mergeAction !== "direct_merge")
+        throw new ShepherdError("--method is supported only with --merge-action direct_merge", EXIT.USAGE);
+}
+export function sameMergeOptions(left, right) {
+    return (left.requireSha === right.requireSha &&
+        left.mergeAction === right.mergeAction &&
+        left.mergeMethod === right.mergeMethod &&
+        restMergeStackGuardKey(left.expectedStack) === restMergeStackGuardKey(right.expectedStack));
+}
+export function validateApplyMergeTarget(input, pr) {
+    if (pr !== undefined &&
+        input.expectedStack !== undefined &&
+        input.expectedStack.prefix.at(-1)?.pr !== pr)
+        throw new ShepherdError("expectedStack prefix must end at the requested PR", EXIT.DATAERR);
+}

package/bin/commands/apply-merge-output.d.mts

@@ -0,0 +1,7 @@
+import type { RepoInfo } from "../github/client.mts";
+import type { RestMergeOptions, RestMergeResponse } from "../github/rest-merge.mts";
+import type { ApplyMergeResult } from "./apply-merge.mts";
+export declare function mergeResultFactory(pr: number, repo: RepoInfo, options: RestMergeOptions): {
+    failed: (message: string, uncertain?: true) => ApplyMergeResult;
+    project: (response: RestMergeResponse) => ApplyMergeResult;
+};

package/bin/commands/apply-merge-output.mjs

@@ -0,0 +1,20 @@
+export function mergeResultFactory(pr, repo, options) {
+    const failed = (message, uncertain) => ({
+        pr,
+        repo: `${repo.owner}/${repo.name}`,
+        status: "failed",
+        details: {
+            message,
+            expected_head_sha: options.requireSha,
+            merge_action: options.mergeAction,
+            ...(options.mergeMethod && { merge_method: options.mergeMethod }),
+        },
+        ...(uncertain && { uncertain }),
+    });
+    const project = (response) => ({
+        pr,
+        repo: `${repo.owner}/${repo.name}`,
+        ...response,
+    });
+    return { failed, project };
+}

package/bin/commands/apply-merge-pull.d.mts

@@ -0,0 +1,20 @@
+import type { RestMergeResponse } from "../github/rest-merge.mts";
+export interface PullState {
+    state: string;
+    merged: boolean;
+    draft: boolean;
+    head: {
+        sha: string;
+    };
+    merge_commit_sha?: string;
+}
+/**
+ * Read the pull conditionally: inside the PR's conditional scope an unchanged pull answers a free
+ * 304 whose stored body equals GitHub's current one.
+ */
+export declare function readPull(repo: {
+    owner: string;
+    name: string;
+}, pr: number): Promise<PullState>;
+/** The merged outcome of a pull already merged, carrying its merge commit when GitHub reports one. */
+export declare function mergedResponse(pull: PullState, message: string): RestMergeResponse;

package/bin/commands/apply-merge-pull.mjs

@@ -0,0 +1,15 @@
+import { readRest, restRepoPath } from "../github/rest-reader-core.mjs";
+/**
+ * Read the pull conditionally: inside the PR's conditional scope an unchanged pull answers a free
+ * 304 whose stored body equals GitHub's current one.
+ */
+export function readPull(repo, pr) {
+    return readRest("GET", `${restRepoPath(repo)}/pulls/${pr}`);
+}
+/** The merged outcome of a pull already merged, carrying its merge commit when GitHub reports one. */
+export function mergedResponse(pull, message) {
+    return {
+        status: "merged",
+        details: { message, ...(pull.merge_commit_sha && { sha: pull.merge_commit_sha }) },
+    };
+}

package/bin/commands/apply-merge.d.mts

@@ -0,0 +1,18 @@
+export { validateApplyMergeOptions } from "./apply-merge-options.mts";
+import { type RestMergeOptions, type RestMergeResponse } from "../github/rest-merge.mts";
+export interface ApplyMergeInput extends RestMergeOptions {
+    prNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
+}
+export interface ApplyMergeResult extends RestMergeResponse {
+    pr: number;
+    repo: string;
+    /** A mutation may already have reached GitHub. No new request will be issued. */
+    uncertain?: true;
+    note?: string;
+}
+/** Submit one guarded asynchronous request, or resume its existing UUID without resubmitting. */
+export declare function runApplyMerge(input: ApplyMergeInput): Promise<ApplyMergeResult>;

package/bin/commands/apply-merge.mjs

@@ -0,0 +1,126 @@
+import { mergeResultFactory } from "./apply-merge-output.mjs";
+import { validateApplyMergeOptions, validateApplyMergeTarget, sameMergeOptions, } from "./apply-merge-options.mjs";
+import { validateRestStackMergeReadiness } from "./rest-stack-merge-readiness.mjs";
+export { validateApplyMergeOptions } from "./apply-merge-options.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
+import { GitHubRequestError } from "../github/errors.mjs";
+import { mergedResponse, readPull } from "./apply-merge-pull.mjs";
+import { withRestConditionalScope } from "../github/rest-conditional-scope.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
+import { getRestMerge, matchesRestMergeRequest, requestRestMerge, } from "../github/rest-merge.mjs";
+import { claimMergeRequest, replaceFailedMergeRequest, readMergeRequest, writeMergeRequest, writeMergeRequestStatus, } from "../state/merge-request.mjs";
+/** Submit one guarded asynchronous request, or resume its existing UUID without resubmitting. */
+export async function runApplyMerge(input) {
+    validateApplyMergeOptions(input);
+    validateApplyMergeTarget(input, input.prNumber);
+    if (getGithubTransport() !== "rest")
+        throw new ShepherdError("apply merge requires REST transport; pass --transport rest", EXIT.USAGE);
+    const repo = input.targetRepository ?? (await getRepoInfo());
+    const pr = input.prNumber ?? (await getCurrentPrNumber());
+    if (!pr)
+        throw new ShepherdError("No open PR found for current branch. Pass a PR explicitly.", EXIT.UNAVAILABLE);
+    validateApplyMergeTarget(input, pr);
+    const key = { owner: repo.owner, repo: repo.name, pr };
+    // The PR's own conditional scope: the pull and stack reads share the ETag cache the iterate tick
+    // that printed this command just filled, so an unchanged resource answers a free 304 whose
+    // stored body equals GitHub's current one. The merge-async GET and PUT stay unconditional.
+    return withRestConditionalScope(key, () => submitApplyMerge(input, repo, pr, key));
+}
+async function submitApplyMerge(input, repo, pr, key) {
+    const options = {
+        requireSha: input.requireSha,
+        mergeAction: input.mergeAction,
+        ...(input.mergeMethod && { mergeMethod: input.mergeMethod }),
+        ...(input.expectedStack && { expectedStack: input.expectedStack }),
+    };
+    const { failed, project } = mergeResultFactory(pr, repo, options);
+    const existing = await readMergeRequest(key);
+    const pull = await readPull(repo, pr);
+    if (pull.merged === true)
+        return project(mergedResponse(pull, "Pull request is merged."));
+    if (pull.head?.sha !== input.requireSha)
+        return failed("Current PR head does not match --require-sha; no merge request was submitted.");
+    if (pull.state !== "open" || pull.draft !== false)
+        return failed("Pull request must be open and ready for review.");
+    const replaceFailed = existing &&
+        !existing.uncertain &&
+        ((existing.response?.status === "failed" && !sameMergeOptions(existing.options, options)) ||
+            (existing.response?.status === "enqueued" &&
+                existing.options.requireSha !== options.requireSha));
+    if (existing && !replaceFailed) {
+        if (!sameMergeOptions(existing.options, options))
+            return failed("A persisted asynchronous merge request has different options; reconcile its outcome before requesting another merge.", true);
+        if (existing.response?.status !== undefined && existing.response.status !== "pending")
+            return {
+                ...project(existing.response),
+                ...(existing.uncertain && { uncertain: true }),
+                ...(existing.response.status === "enqueued" && {
+                    note: "This is the recorded request outcome; current merge-queue membership is not confirmed.",
+                }),
+            };
+        if (!existing.uuid)
+            return failed("The previous merge submission has an unknown outcome and no UUID. The PR is not merged; no duplicate request was submitted.", true);
+        try {
+            const response = await getRestMerge(repo, pr, existing.uuid);
+            if (response.status === "pending" &&
+                (!matchesRestMergeRequest(response, options) || response.details.uuid !== existing.uuid))
+                return failed("Asynchronous merge status does not match the persisted guarded request.", true);
+            await writeMergeRequestStatus(key, { ...existing, response });
+            return project(response);
+        }
+        catch (error) {
+            if (error instanceof GitHubRequestError && error.status === 404) {
+                const latest = await readPull(repo, pr);
+                if (latest.merged === true)
+                    return project(mergedResponse(latest, "Pull request is merged; its asynchronous request has expired."));
+                return failed("The asynchronous merge UUID expired or is unavailable. The PR is not merged; its request outcome is unknown and no duplicate was submitted.", true);
+            }
+            throw error;
+        }
+    }
+    let record = {
+        version: 1,
+        options,
+        startedAtUnix: Math.floor(Date.now() / 1000),
+    };
+    await validateRestStackMergeReadiness(pr, repo, input.requireSha, input.expectedStack);
+    if (!(existing
+        ? await replaceFailedMergeRequest(key, existing, record)
+        : await claimMergeRequest(key, record)))
+        return failed("Another merge request is already being submitted; resume this command after its outcome is recorded.", true);
+    // Recovery may have selected an older durable intent; retain its unique generation token.
+    record = (await readMergeRequest(key));
+    let response;
+    try {
+        response = await requestRestMerge(repo, pr, options);
+    }
+    catch (error) {
+        if (error instanceof GitHubRequestError && error.status >= 400 && error.status < 500) {
+            await writeMergeRequest(key, {
+                ...record,
+                response: {
+                    status: "failed",
+                    details: { message: error.responseMessage ?? error.message },
+                },
+            });
+            throw error;
+        }
+        return failed(`Merge submission outcome is unknown: ${error instanceof Error ? error.message : String(error)}. No duplicate request will be submitted.`, true);
+    }
+    if (response.status === "pending" && !matchesRestMergeRequest(response, options)) {
+        const mismatch = failed("GitHub returned a pending merge with different or unverifiable options; its UUID was not adopted.", true);
+        await writeMergeRequest(key, {
+            ...record,
+            response: { status: mismatch.status, details: mismatch.details },
+            uncertain: true,
+        });
+        return mismatch;
+    }
+    await writeMergeRequest(key, {
+        ...record,
+        ...(response.details.uuid && response.status === "pending" && { uuid: response.details.uuid }),
+        response,
+    });
+    return project(response);
+}

package/bin/commands/apply-queue-removal.mjs

@@ -2,15 +2,18 @@ import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
 import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
 import { getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
+import { getGithubTransport } from "../github/transport.mjs";
 import { isCiQueueRemovalReason, writeQueueRemovalAcknowledgment, } from "../state/queue-removal-ack.mjs";
 /** Validate an observed native-stack CI queue removal before recording the caller's acknowledgment. */
 export async function applyQueueRemovalAck(input) {
+    requireQueueRemovalTransport();
     const repo = input.targetRepository ?? (await getRepoInfo());
     const pr = input.prNumber ?? (await getCurrentPrNumber());
     if (pr === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const { data } = await fetchPrBatch(pr, repo);
+    requireQueueRemovalTransport(data.transport);
     const removal = data.latestMergeQueueRemoval;
     if (data.state !== "OPEN" ||
         !data.stack ||
@@ -41,3 +44,7 @@ export async function applyQueueRemovalAck(input) {
     }
     return { pr, repo: `${repo.owner}/${repo.name}`, acknowledgment };
 }
+function requireQueueRemovalTransport(snapshotTransport) {
+    if (snapshotTransport === "rest" || getGithubTransport() === "rest")
+        throw new ShepherdError("Queue-removal acknowledgment is transport-unsupported: REST cannot verify current merge-queue removal evidence.", EXIT.UNAVAILABLE);
+}