pr-shepherd 0.60.1 → 1.1.0

package/bin/cli/poll-targets.mjs

@@ -2,18 +2,20 @@ import { parseArgs } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getRepoInfo } from "../github/client.mjs";
 import { parseCliPrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "../pr-reference.mjs";
+import { rejectRemovedFlags } from "./removed-flags.mjs";
 const VALUE_FLAGS = new Set([
     "--format",
     "--ready-delay",
     "--stall-timeout",
     "--instructions",
-    "--poll-mode",
     "--interval",
     "--timeout",
     "--debounce",
-    "--stack",
 ]);
+/** Splits PR references from flags. Returns null after printing a usage error. */
 export function parsePollTargets(args) {
+    if (rejectRemovedFlags(args))
+        return null;
     const { values } = parseArgs({
         args,
         strict: false,
@@ -22,39 +24,22 @@ export function parsePollTargets(args) {
     });
     const consumed = new Set();
     const refs = [];
-    let stack;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (VALUE_FLAGS.has(arg)) {
-            if (arg === "--format" || arg === "--stack") {
+            if (arg === "--format") {
                 consumed.add(index);
                 if (index + 1 < args.length)
                     consumed.add(index + 1);
             }
-            if (arg === "--stack") {
-                const parsed = parseCliPrReference(args[index + 1] ?? "");
-                if (!parsed)
-                    return usage(`invalid --stack PR reference: ${args[index + 1] ?? "(missing)"}`);
-                if (stack)
-                    return usage("--stack may only be specified once");
-                stack = parsed;
-            }
             index += 1;
             continue;
         }
         const equals = arg.indexOf("=");
         const name = equals < 0 ? arg : arg.slice(0, equals);
         if (VALUE_FLAGS.has(name)) {
-            if (name === "--format" || name === "--stack")
+            if (name === "--format")
                 consumed.add(index);
-            if (name === "--stack") {
-                const parsed = parseCliPrReference(arg.slice(equals + 1));
-                if (!parsed)
-                    return usage(`invalid --stack PR reference: ${arg.slice(equals + 1)}`);
-                if (stack)
-                    return usage("--stack may only be specified once");
-                stack = parsed;
-            }
             continue;
         }
         if (arg === "--verbose") {
@@ -64,23 +49,25 @@ export function parsePollTargets(args) {
         if (arg.startsWith("--"))
             continue;
         const parsed = parseCliPrReference(arg);
-        if (!parsed)
-            continue;
+        if (!parsed) {
+            // A typo must not silently drop a PR from an exact multi-PR selection.
+            process.stderr.write(`pr-shepherd: invalid PR reference "${arg}".\n`);
+            process.exitCode = EXIT.USAGE;
+            return null;
+        }
         refs.push(parsed);
         consumed.add(index);
     }
-    if (stack && refs.length > 0)
-        return usage("--stack cannot be combined with explicit PRs");
     const format = (values.format ?? "text");
     return {
         refs,
-        stack,
         global: { format, verbose: values.verbose === true },
         extra: args.filter((_, index) => !consumed.has(index)),
     };
 }
+/** Resolves PR references that must all name one repository. */
 export async function resolvePollTargets(parsed) {
-    const all = parsed.stack ? [parsed.stack] : parsed.refs;
+    const all = parsed.refs;
     if (all.length === 0)
         return { prNumbers: [] };
     const checkoutRepo = all.some((ref) => ref.repository === undefined)
@@ -102,14 +89,7 @@ export async function resolvePollTargets(parsed) {
         if (!prNumbers.includes(target.prNumber))
             prNumbers.push(target.prNumber);
     }
-    return parsed.stack
-        ? { prNumbers: [], stackPrNumber: prNumbers[0], targetRepository: selectedRepo }
-        : { prNumbers, targetRepository: selectedRepo };
-}
-function usage(message) {
-    process.stderr.write(`pr-shepherd: ${message}\n`);
-    process.exitCode = EXIT.USAGE;
-    return null;
+    return { prNumbers, targetRepository: selectedRepo };
 }
 function usageThrow(message) {
     throw new ShepherdError(message, EXIT.USAGE);

package/bin/cli/removed-flags.d.mts

@@ -0,0 +1,3 @@
+export declare function isRemovedFlag(arg: string): boolean;
+/** Prints a usage error and returns true when `args` contains a removed flag. */
+export declare function rejectRemovedFlags(args: string[]): boolean;

package/bin/cli/removed-flags.mjs

@@ -0,0 +1,24 @@
+import { EXIT } from "../exit-codes.mjs";
+/** Flags removed in v1, with the replacement each usage error names. */
+const REMOVED_FLAGS = new Map([
+    ["--stack", "`--stack` was removed; use `pr-shepherd stack <PR>`."],
+    [
+        "--poll-mode",
+        "`--poll-mode` was removed; `pr-shepherd iterate` runs one tick, and looping commands run one tick when CLAUDE_CODE_REMOTE=true.",
+    ],
+]);
+export function isRemovedFlag(arg) {
+    return REMOVED_FLAGS.has(arg.split("=", 1)[0]);
+}
+/** Prints a usage error and returns true when `args` contains a removed flag. */
+export function rejectRemovedFlags(args) {
+    for (const arg of args) {
+        const message = REMOVED_FLAGS.get(arg.split("=", 1)[0]);
+        if (message === undefined)
+            continue;
+        process.stderr.write(`pr-shepherd: ${message}\n`);
+        process.exitCode = EXIT.USAGE;
+        return true;
+    }
+    return false;
+}

package/bin/cli/rule-auto-resolve-lines.d.mts

@@ -0,0 +1,3 @@
+import type { PollSummaryRuleAutoResolve } from "../types.mts";
+/** Row lines for an aggregate row or stack layer: the one-PR `## Classification auto-resolve` content. */
+export declare function formatRuleAutoResolveLines(event: PollSummaryRuleAutoResolve | undefined): string[];

package/bin/cli/rule-auto-resolve-lines.mjs

@@ -0,0 +1,12 @@
+/** Row lines for an aggregate row or stack layer: the one-PR `## Classification auto-resolve` content. */
+export function formatRuleAutoResolveLines(event) {
+    if (!event)
+        return [];
+    const link = (kind, id, url) => `    - ${kind} \`${id}\`${url ? ` ${url}` : ""}`;
+    return [
+        `  - classification auto-resolve: ${event.summary}`,
+        ...(event.threads ?? []).map((thread) => link("thread", thread.id, thread.url)),
+        ...(event.minimized ?? []).map((item) => link(item.kind, item.id, item.url)),
+        ...(event.errors ?? []).map((error) => `    - ${error}`),
+    ];
+}

package/bin/cli/runner.d.mts

@@ -2,7 +2,7 @@ interface PrShepherdCommand {
     argv: string[];
     text: string;
 }
-/** Every emitted pr-shepherd command starts with the configured `cliCommand` launcher. */
+/** Every emitted pr-shepherd command starts with the configured `cli-command` launcher. */
 export declare function buildPrShepherdCommand(args: string[]): PrShepherdCommand;
 export declare function renderShellCommand(argv: string[]): string;
 export {};

package/bin/cli/runner.mjs

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

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

@@ -1,4 +1,4 @@
-import type { PollSummaryItem } from "../types.mts";
+import type { PollSummaryItem, PollSummaryRuleAutoResolve } from "../types.mts";
 /** One lean stack row shared by Markdown, JSON, and MCP. */
 export interface StackLayerView {
     transport?: "rest";
@@ -26,6 +26,7 @@ export interface StackLayerView {
     actionable?: number;
     checksIncomplete?: true;
     reviewIncomplete?: true;
+    ruleAutoResolve?: PollSummaryRuleAutoResolve;
     queueRemoval?: {
         reason: string | null;
         actor?: string;

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

@@ -21,7 +21,6 @@ export interface StackOverview {
     instructions?: string[];
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;
-    pollMode?: "event";
     nextCheck?: NextCheck;
 }
 /** Lean stack payload shared by Markdown, JSON, and MCP. */

package/bin/cli/stack-overview.mjs

@@ -3,6 +3,7 @@ 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";
+import { formatRuleAutoResolveLines } from "./rule-auto-resolve-lines.mjs";
 /** Lean stack payload shared by Markdown, JSON, and MCP. */
 export function projectStackOverview(result) {
     const selection = result.selection;
@@ -26,7 +27,6 @@ export function projectStackOverview(result) {
         ...(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 }),
     };
 }
@@ -60,6 +60,7 @@ function projectLayer(item, stale) {
             (item.review?.actionable ?? 0) > 0 && { actionable: item.review?.actionable }),
         ...(item.checks?.incomplete && { checksIncomplete: true }),
         ...(item.review?.incomplete && { reviewIncomplete: true }),
+        ...(item.ruleAutoResolve && { ruleAutoResolve: item.ruleAutoResolve }),
         ...(removal && {
             queueRemoval: {
                 reason: removal.reason,
@@ -94,7 +95,7 @@ export function formatStackOverview(overview) {
     const lines = [
         `# ${overview.repo} stack #${stack.stackNumber}${stackTerminalTag(overview.nextAction)} — ${overview.reason}`,
         "",
-        `anchor PR #${stack.anchor} · ${stack.stackSize} layers · mode \`${overview.mode}\`${overview.pollMode ? ` · pollMode \`${overview.pollMode}\`` : ""}`,
+        `anchor PR #${stack.anchor} · ${stack.stackSize} layers · mode \`${overview.mode}\``,
         ...(overview.stackMergeable ? ["stackMergeable: true"] : []),
         ...(overview.nextAction ? [`nextAction: ${overview.nextAction}`] : []),
         ...formatNextCheckLines(overview.nextCheck),
@@ -157,6 +158,7 @@ function formatLayerLines(layer, index, overview) {
     return [
         `- ${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(" · ")}`,
+        ...formatRuleAutoResolveLines(layer.ruleAutoResolve),
         ...(layer.transport ? [`  - transport \`${layer.transport}\``] : []),
         ...(layer.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
     ];

package/bin/cli/{fix-formatter-extra.d.mts → triage-formatter-extra.d.mts}

@@ -1,4 +1,3 @@
-import type { CheckAnnotation, IterateResultFixCode } from "../types.mts";
+import type { CheckAnnotation } from "../types.mts";
 /** Returns null when the annotation adds nothing beyond the check's own conclusion tag. */
 export declare function renderCheckAnnotation(a: CheckAnnotation, logExcerpt?: string): string | null;
-export declare function renderProtectedRun(run: IterateResultFixCode["fix"]["protectedRuns"][number]): string;

package/bin/cli/{fix-formatter-extra.mjs → triage-formatter-extra.mjs}

@@ -25,12 +25,6 @@ export function renderCheckAnnotation(a, logExcerpt) {
 function duplicatesLog(text, logExcerpt) {
     return logExcerpt !== undefined && logExcerpt.includes(text.trim());
 }
-export function renderProtectedRun(run) {
-    const label = run.workflowName
-        ? `${run.workflowName} (${run.checkNames.join(", ")})`
-        : run.checkNames.join(", ");
-    return `- \`${run.runId}\` — \`${label}\` [matched: \`${run.matchedPattern}\`]`;
-}
 function renderAnnotationRange(a) {
     if (a.startLine === null && a.endLine === null)
         return "?";

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

@@ -0,0 +1,4 @@
+import type { IterateResultTriage } from "../types.mts";
+export declare function formatTriageResult(header: string, result: IterateResultTriage, opts?: {
+    verbose?: boolean;
+}): string;

package/bin/cli/{fix-formatter.mjs → triage-formatter.mjs}

@@ -4,17 +4,17 @@ import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mj
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
 import { BODY_TRUNCATE_MAX_CHARS } from "./body-truncate.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
-import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
+import { renderCheckAnnotation } from "./triage-formatter-extra.mjs";
 import { renderRelatedJobLines } from "./related-jobs-format.mjs";
 import { isFailingAgentCheck } from "../checks/conclusions.mjs";
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { partitionFixThreads } from "../commands/iterate/fix-instruction-threads.mjs";
-export function formatFixCodeResult(header, result, opts = {}) {
+export function formatTriageResult(header, result, opts = {}) {
     const verbose = opts.verbose ?? false;
     const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
     const sections = [header];
-    if (result.fix.reviewItems) {
-        const { shown, total } = result.fix.reviewItems;
+    if (result.triage.reviewItems) {
+        const { shown, total } = result.triage.reviewItems;
         sections.push(`**showing** ${shown} of ${total} review items`);
     }
     if (result.mergedBasePullRequests?.length) {
@@ -41,25 +41,25 @@ export function formatFixCodeResult(header, result, opts = {}) {
             }
         }
     };
-    const { locatedThreads, unlocatedMutatedThreads, unlocatedThreads } = partitionFixThreads(result.fix.threads, result.fix.resolveCommand, result.fix.resolveOnlyCommand);
+    const { locatedThreads, unlocatedMutatedThreads, unlocatedThreads } = partitionFixThreads(result.triage.threads, result.triage.resolveCommand, result.triage.resolveOnlyCommand);
     renderThreads("## Review threads", [...locatedThreads, ...unlocatedMutatedThreads]);
     renderThreads("## Unlocated review threads (logged once — no mutation)", unlocatedThreads);
-    if (result.fix.resolutionOnlyThreads.length > 0) {
+    if (result.triage.resolutionOnlyThreads.length > 0) {
         sections.push("## Review threads to resolve");
-        sections.push(result.fix.resolutionOnlyThreads
+        sections.push(result.triage.resolutionOnlyThreads
             .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t), verbose }))
             .join("\n"));
     }
-    if (result.fix.actionableComments.length > 0) {
+    if (result.triage.actionableComments.length > 0) {
         sections.push("## Actionable comments");
-        for (const c of result.fix.actionableComments) {
+        for (const c of result.triage.actionableComments) {
             const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
             const authorizationMarker = c.viewerCanMinimize === false ? " [viewer cannot minimize]" : "";
             sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${authorizationMarker}`);
             sections.push(blockquote(c.body, topCap, c.url));
         }
     }
-    const failingChecks = result.fix.checks.filter((ch) => isFailingAgentCheck(ch));
+    const failingChecks = result.triage.checks.filter((ch) => isFailingAgentCheck(ch));
     if (failingChecks.length > 0) {
         sections.push("## Failing checks");
         // Multiple failing CheckRuns (matrix jobs, etc.) can share one runId; the rerun command is
@@ -99,7 +99,7 @@ export function formatFixCodeResult(header, result, opts = {}) {
         });
         sections.push(bullets.join("\n\n"));
     }
-    const annotatedChecks = result.fix.checks
+    const annotatedChecks = result.triage.checks
         .map((ch) => ({
         ch,
         rendered: (ch.annotations ?? [])
@@ -121,9 +121,9 @@ export function formatFixCodeResult(header, result, opts = {}) {
             sections.push(rendered.join("\n\n"));
         }
     }
-    if (result.fix.changesRequestedReviews.length > 0) {
+    if (result.triage.changesRequestedReviews.length > 0) {
         sections.push("## Changes-requested reviews");
-        for (const r of result.fix.changesRequestedReviews) {
+        for (const r of result.triage.changesRequestedReviews) {
             // A stale bot CR that already had its full body surfaced on a prior tick stays a terse
             // one-line reminder (renderReviewBullet's staleBotCr branch) — repeating the full body
             // every tick would be noise, not new content. Every other review (a bot CR's first
@@ -141,65 +141,54 @@ export function formatFixCodeResult(header, result, opts = {}) {
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
-    if (result.fix.firstLookSummaries.length > 0) {
+    if (result.triage.firstLookSummaries.length > 0) {
         sections.push("## Review summaries (first look)");
-        for (const r of result.fix.firstLookSummaries) {
+        for (const r of result.triage.firstLookSummaries) {
             sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${r.viewerCanMinimize === false ? " [viewer cannot minimize]" : ""}`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
-    if (result.fix.editedSummaries.length > 0) {
+    if (result.triage.editedSummaries.length > 0) {
         sections.push("## Review summaries (edited since first look — already minimized; do not re-minimize)");
-        for (const r of result.fix.editedSummaries) {
+        for (const r of result.triage.editedSummaries) {
             sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${r.viewerCanMinimize === false ? " [viewer cannot minimize]" : ""}`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
-    const firstLookSummaryIds = new Set(result.fix.firstLookSummaries.map((r) => r.id));
-    const seenSummaryIds = result.fix.reviewSummaryIds.filter((id) => !firstLookSummaryIds.has(id));
+    const firstLookSummaryIds = new Set(result.triage.firstLookSummaries.map((r) => r.id));
+    const seenSummaryIds = result.triage.reviewSummaryIds.filter((id) => !firstLookSummaryIds.has(id));
     if (seenSummaryIds.length > 0) {
         sections.push("## Review IDs to minimize queue");
         sections.push(seenSummaryIds.map((id) => `- \`${id}\``).join("\n"));
     }
-    if (result.fix.surfacedApprovals.length > 0) {
+    if (result.triage.surfacedApprovals.length > 0) {
         sections.push("## Approvals (surfaced — not minimized)");
-        for (const r of result.fix.surfacedApprovals) {
+        for (const r of result.triage.surfacedApprovals) {
             sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})${r.viewerCanMinimize === false ? " [viewer cannot minimize]" : ""}`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body, topCap));
         }
     }
-    const firstLookTotal = result.fix.firstLookThreads.length + result.fix.firstLookComments.length;
+    const firstLookTotal = result.triage.firstLookThreads.length + result.triage.firstLookComments.length;
     if (firstLookTotal > 0) {
         sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
-        const resolutionOnlyIds = new Set(result.fix.resolutionOnlyThreads.map((t) => t.id));
-        sections.push(buildFirstLookBullets(result.fix.firstLookThreads, resolutionOnlyIds, result.fix.firstLookComments, verbose).join("\n"));
-    }
-    if (result.fix.inProgressRunIds.length > 0) {
-        sections.push("## In-progress runs");
-        sections.push(result.fix.inProgressRunIds.map((id) => `- \`${id}\``).join("\n"));
-    }
-    if (result.fix.protectedRuns.length > 0) {
-        sections.push("## Protected runs", result.fix.protectedRuns.map(renderProtectedRun).join("\n"));
-    }
-    if (result.cancelled.length > 0) {
-        sections.push("## Cancelled runs");
-        sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));
+        const resolutionOnlyIds = new Set(result.triage.resolutionOnlyThreads.map((t) => t.id));
+        sections.push(buildFirstLookBullets(result.triage.firstLookThreads, resolutionOnlyIds, result.triage.firstLookComments, verbose).join("\n"));
     }
     // The review mutation commands render inline in their `## Instructions` steps.
     const postFixLines = verbose ? [`- base: \`${result.baseBranch}\``] : [];
-    if (result.fix.requeue) {
-        postFixLines.push(`- requeue: ${inlineCode(renderMergeCommand(result.fix.requeue.command))}`);
-        if (result.fix.requeue.queueApiFallbackCommand) {
-            postFixLines.push(`- requeue API fallback: ${inlineCode(renderMergeCommand(result.fix.requeue.queueApiFallbackCommand))}`);
+    if (result.triage.requeue) {
+        postFixLines.push(`- requeue: ${inlineCode(renderMergeCommand(result.triage.requeue.command))}`);
+        if (result.triage.requeue.queueApiFallbackCommand) {
+            postFixLines.push(`- requeue API fallback: ${inlineCode(renderMergeCommand(result.triage.requeue.queueApiFallbackCommand))}`);
         }
     }
-    if (result.fix.queueRemovalAcknowledgment) {
-        postFixLines.push(`- acknowledge queue removal: ${inlineCode(renderMergeCommand(result.fix.queueRemovalAcknowledgment))}`);
+    if (result.triage.queueRemovalAcknowledgment) {
+        postFixLines.push(`- acknowledge queue removal: ${inlineCode(renderMergeCommand(result.triage.queueRemovalAcknowledgment))}`);
     }
     if (postFixLines.length > 0)
         sections.push("## Post-fix actions", postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(numberInstructions(result.fix.instructions));
+    sections.push(numberInstructions(result.triage.instructions));
     return joinSections(sections);
 }
 function indentBlockquote(body, indent) {

package/bin/cli/unknown-flags.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Reject flags a subcommand does not accept before its PR target is resolved. Without this, an
+ * unknown or removed flag is treated as value-taking and swallows the PR number that follows it,
+ * so the command silently targets the branch-inferred PR instead.
+ */
+export declare function rejectUnknownFlags(args: string[], command: string, knownFlags: readonly string[]): boolean;

package/bin/cli/unknown-flags.mjs

@@ -0,0 +1,29 @@
+import { EXIT } from "../exit-codes.mjs";
+import { FLAGS_WITH_VALUES } from "./arg-flags.mjs";
+const GLOBAL_FLAGS = ["--format", "--transport", "--verbose", "--help", "-h"];
+/**
+ * Reject flags a subcommand does not accept before its PR target is resolved. Without this, an
+ * unknown or removed flag is treated as value-taking and swallows the PR number that follows it,
+ * so the command silently targets the branch-inferred PR instead.
+ */
+export function rejectUnknownFlags(args, command, knownFlags) {
+    const known = new Set([...GLOBAL_FLAGS, ...knownFlags]);
+    let unknown;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith("-"))
+            continue;
+        if (!known.has(arg.split("=", 1)[0])) {
+            unknown = arg;
+            break;
+        }
+        // A separate value (`--message -1`) is the flag's argument, not another flag.
+        if (FLAGS_WITH_VALUES.has(arg))
+            i += 1;
+    }
+    if (unknown === undefined)
+        return false;
+    process.stderr.write(`pr-shepherd: ${command}: unknown flag "${unknown}".\n`);
+    process.exitCode = EXIT.USAGE;
+    return true;
+}