pr-shepherd 0.60.1 → 1.0.0

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

@@ -1,16 +1,14 @@
-import { type loadConfig, type InstructionStyle, type PollMode } from "../config/load.mts";
+import type { loadConfig } from "../config/load.mts";
+import { type InstructionStyle } from "../config/resolve.mts";
 interface IterateFlags {
     readyDelaySuffix: string | undefined | null;
     readyDelaySeconds: number;
     stallTimeoutSuffix: string | undefined | null;
     stallTimeoutSeconds: number;
     noAutoMarkReady: boolean;
-    noAutoCancelActionable: boolean;
     merge: boolean;
     /** `null` when `--instructions` was invalid (an error was already printed). */
     instructions: InstructionStyle | null | undefined;
-    /** `null` when `--poll-mode` was invalid (an error was already printed). */
-    pollMode: PollMode | null | undefined;
 }
 /** True when any flag failed validation; the usage error is already printed. */
 export declare function hasInvalidIterateFlags(flags: IterateFlags): boolean;

package/bin/cli/iterate-flags.mjs

@@ -1,4 +1,4 @@
-import { INSTRUCTION_STYLES, POLL_MODES, isInstructionStyle, isPollMode, } from "../config/load.mjs";
+import { INSTRUCTION_STYLES, isInstructionStyle, } from "../config/resolve.mjs";
 import { EXIT } from "../exit-codes.mjs";
 import { getFlag, hasFlag } from "./args.mjs";
 import { parseDurationToSeconds } from "./duration.mjs";
@@ -10,29 +10,25 @@ const MINUTE_FLAG_OPTS = { defaultUnit: "m", allowZero: true };
 export function hasInvalidIterateFlags(flags) {
     return (flags.readyDelaySuffix === null ||
         flags.stallTimeoutSuffix === null ||
-        flags.instructions === null ||
-        flags.pollMode === null);
+        flags.instructions === null);
 }
 export function parseIterateFlags(extra, cfg) {
     const readyDelayStr = getFlag(extra, "--ready-delay");
     const readyDelaySuffix = validateSecondsDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"), MINUTE_FLAG_OPTS);
-    const readyDelaySeconds = parseDurationToSeconds(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes * 60, MINUTE_FLAG_OPTS);
+    const readyDelaySeconds = parseDurationToSeconds(readyDelaySuffix ?? "", cfg.iterate["ready-delay-minutes"] * 60, MINUTE_FLAG_OPTS);
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
-    const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
     const merge = hasFlag(extra, "--merge");
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
     const stallTimeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--stall-timeout", stallTimeoutStr, hasFlag(extra, "--stall-timeout"), MINUTE_FLAG_OPTS);
-    const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate.stallTimeoutMinutes * 60, MINUTE_FLAG_OPTS);
+    const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate["stall-timeout-minutes"] * 60, MINUTE_FLAG_OPTS);
     const instructions = parseInstructionsFlag(extra);
     return {
         instructions,
-        pollMode: parsePollModeFlag(extra),
         readyDelaySuffix,
         readyDelaySeconds,
         stallTimeoutSuffix,
         stallTimeoutSeconds,
         noAutoMarkReady,
-        noAutoCancelActionable,
         merge,
     };
 }
@@ -50,15 +46,3 @@ function parseInstructionsFlag(extra) {
 function hasInstructionsFlag(extra) {
     return extra.some((arg) => arg === "--instructions" || arg.startsWith("--instructions="));
 }
-/** Validate `--poll-mode`. Returns `undefined` when absent, `null` after printing a usage error. */
-function parsePollModeFlag(extra) {
-    const value = getFlag(extra, "--poll-mode");
-    if (!extra.some((arg) => arg === "--poll-mode" || arg.startsWith("--poll-mode="))) {
-        return undefined;
-    }
-    if (isPollMode(value))
-        return value;
-    process.stderr.write(`pr-shepherd: --poll-mode must be one of ${POLL_MODES.join(", ")}, got ${JSON.stringify(value ?? "")}\n`);
-    process.exitCode = EXIT.USAGE;
-    return null;
-}

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

@@ -6,7 +6,7 @@ import type { IterateResult } from "../types.mts";
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` prints the `apply review` command inline, in backticks, in its
+ *   2. `[TRIAGE]` prints the `apply review` command inline, in backticks, in its
  *      `## Instructions` step; the agent runs that backticked command as printed.
  *   3. Every action except `cancel` ends with a `## Instructions` section — numbered
  *      `1.`, `2.`, … — that tells the agent exactly what to do with this output, with at

package/bin/cli/iterate-formatter.mjs

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 import { insertEditedCommentsSection } from "./edited-comments-format.mjs";
-import { formatFixCodeResult } from "./fix-formatter.mjs";
+import { formatTriageResult } from "./triage-formatter.mjs";
 import { formatRelevantChecks } from "./iterate-checks-formatter.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, } from "./iterate-instructions.mjs";
@@ -12,7 +12,7 @@ import { formatSuppressedNameLines } from "./iterate-check-names.mjs";
 import { branchStateSegment } from "./iterate-branch-segment.mjs";
 import { insertRuleAutoResolveSection } from "../commands/rule-auto-resolve-format.mjs";
 import { formatTransportEvidence } from "./transport-formatter.mjs";
-import { formatNextCheckLines, formatPollModeSegment } from "./next-check-format.mjs";
+import { formatNextCheckLines } from "./next-check-format.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
@@ -21,7 +21,7 @@ import { formatPrUrl } from "../pr-reference.mjs";
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` prints the `apply review` command inline, in backticks, in its
+ *   2. `[TRIAGE]` prints the `apply review` command inline, in backticks, in its
  *      `## Instructions` step; the agent runs that backticked command as printed.
  *   3. Every action except `cancel` ends with a `## Instructions` section — numbered
  *      `1.`, `2.`, … — that tells the agent exactly what to do with this output, with at
@@ -55,7 +55,7 @@ export function formatIterateResult(result, opts) {
         ? ` · **merge** \`${result.mergeStateStatus}\``
         : "";
     const stateSeg = verbose || result.state !== "OPEN" ? ` · **state** \`${result.state}\`` : "";
-    const baseLine = `**status** \`${result.status}\`${mergeSeg}${reviewDecisionSeg}${stateSeg}${repoSeg}${baseBranchSeg}${formatPollModeSegment(result)}`;
+    const baseLine = `**status** \`${result.status}\`${mergeSeg}${reviewDecisionSeg}${stateSeg}${repoSeg}${baseBranchSeg}`;
     const branchSeg = branchStateSegment(result);
     let summaryLine;
     if (verbose) {
@@ -199,8 +199,8 @@ export function formatIterateResult(result, opts) {
                 result.escalate.humanMessage,
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]));
-        case "fix_code":
-            return finish(formatFixCodeResult(joinSections([header, ...telemetrySections]), result, { verbose }));
+        case "triage":
+            return finish(formatTriageResult(joinSections([header, ...telemetrySections]), result, { verbose }));
     }
 }
 function appendUnreportedLines(lines, result) {

package/bin/cli/iterate-instructions.d.mts

@@ -1,6 +1,6 @@
 import type { IterateResult } from "../types.mts";
 export declare function buildSimpleIterateInstructions(result: Exclude<IterateResult, {
-    action: "fix_code";
+    action: "triage";
 }>): string[];
 export declare function adaptIterateLog(log: string): string;
 export declare function numberInstructions(instructions: string[]): string;

package/bin/cli/iterate-instructions.mjs

@@ -1,14 +1,14 @@
 import { inlineCode } from "../util/markdown.mjs";
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { renderShellCommand } from "./runner.mjs";
-import { eventWaitSteps } from "../commands/event-instructions.mjs";
+import { tickWaitSteps } from "../commands/tick-instructions.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),
+                    ...tickWaitSteps(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.`;
@@ -18,7 +18,7 @@ export function buildSimpleIterateInstructions(result) {
         }
         case "wait":
             if (result.nextCheck) {
-                return ["Non-terminal — no action needed this tick.", ...eventWaitSteps(result.nextCheck)];
+                return ["Non-terminal — no action needed this tick.", ...tickWaitSteps(result.nextCheck)];
             }
             if (result.quotaWarning) {
                 return [
@@ -29,8 +29,7 @@ export function buildSimpleIterateInstructions(result) {
                 "Non-terminal — no action needed this tick. Iterate immediately with the same options to continue.",
             ];
         case "mark_ready":
-            // Event mode reruns at once too: Shepherd is not polling, so no cadence applies.
-            if (result.quotaWarning && result.pollMode !== "event") {
+            if (result.quotaWarning) {
                 return [
                     buildQuotaAwareContinuation(result.quotaWarning, "The CLI marked the PR ready for review."),
                 ];
@@ -44,7 +43,7 @@ export function buildSimpleIterateInstructions(result) {
             if (result.merge.mode === "rest" && result.nextCheck)
                 return [
                     `Run the REST merge command exactly as printed: ${command}. \`enqueued\` is not merged.`,
-                    ...eventWaitSteps(result.nextCheck),
+                    ...tickWaitSteps(result.nextCheck),
                 ];
             if (result.merge.mode === "rest")
                 return [

package/bin/cli/iterate-lean.mjs

@@ -95,7 +95,6 @@ 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),
@@ -140,58 +139,51 @@ export function projectIterateLean(result, opts) {
                 merge: result.merge,
                 instructions: simpleInstructions(result),
             };
-        case "fix_code":
+        case "triage":
             return {
                 ...base,
-                // Passing checks stay summary counts and failures stay in `fix.checks`, as in lean text.
-                ...(result.cancelled.length > 0 && { cancelled: result.cancelled }),
-                fix: {
-                    ...(result.fix.threads.length > 0 && { threads: result.fix.threads }),
-                    ...(result.fix.resolutionOnlyThreads.length > 0 && {
-                        resolutionOnlyThreads: result.fix.resolutionOnlyThreads,
+                // Passing checks stay summary counts and failures stay in `triage.checks`, as in lean text.
+                triage: {
+                    ...(result.triage.threads.length > 0 && { threads: result.triage.threads }),
+                    ...(result.triage.resolutionOnlyThreads.length > 0 && {
+                        resolutionOnlyThreads: result.triage.resolutionOnlyThreads,
                     }),
-                    ...(result.fix.actionableComments.length > 0 && {
-                        actionableComments: result.fix.actionableComments,
+                    ...(result.triage.actionableComments.length > 0 && {
+                        actionableComments: result.triage.actionableComments,
                     }),
-                    ...(result.fix.reviewSummaryIds.length > 0 && {
-                        reviewSummaryIds: result.fix.reviewSummaryIds,
+                    ...(result.triage.reviewSummaryIds.length > 0 && {
+                        reviewSummaryIds: result.triage.reviewSummaryIds,
                     }),
-                    ...(result.fix.firstLookSummaries.length > 0 && {
-                        firstLookSummaries: result.fix.firstLookSummaries,
+                    ...(result.triage.firstLookSummaries.length > 0 && {
+                        firstLookSummaries: result.triage.firstLookSummaries,
                     }),
-                    ...(result.fix.editedSummaries.length > 0 && {
-                        editedSummaries: result.fix.editedSummaries,
+                    ...(result.triage.editedSummaries.length > 0 && {
+                        editedSummaries: result.triage.editedSummaries,
                     }),
-                    ...(result.fix.surfacedApprovals.length > 0 && {
-                        surfacedApprovals: result.fix.surfacedApprovals,
+                    ...(result.triage.surfacedApprovals.length > 0 && {
+                        surfacedApprovals: result.triage.surfacedApprovals,
                     }),
-                    ...(result.fix.firstLookThreads.length > 0 && {
-                        firstLookThreads: result.fix.firstLookThreads,
+                    ...(result.triage.firstLookThreads.length > 0 && {
+                        firstLookThreads: result.triage.firstLookThreads,
                     }),
-                    ...(result.fix.firstLookComments.length > 0 && {
-                        firstLookComments: result.fix.firstLookComments,
+                    ...(result.triage.firstLookComments.length > 0 && {
+                        firstLookComments: result.triage.firstLookComments,
                     }),
-                    ...(result.fix.inProgressRunIds.length > 0 && {
-                        inProgressRunIds: result.fix.inProgressRunIds,
+                    ...(result.triage.requeue && { requeue: result.triage.requeue }),
+                    ...(result.triage.queueRemovalAcknowledgment && {
+                        queueRemovalAcknowledgment: result.triage.queueRemovalAcknowledgment,
                     }),
-                    ...(result.fix.protectedRuns.length > 0 && {
-                        protectedRuns: result.fix.protectedRuns,
+                    ...(result.triage.checks.length > 0 && { checks: result.triage.checks }),
+                    ...(result.triage.changesRequestedReviews.length > 0 && {
+                        changesRequestedReviews: result.triage.changesRequestedReviews,
                     }),
-                    ...(result.fix.requeue && { requeue: result.fix.requeue }),
-                    ...(result.fix.queueRemovalAcknowledgment && {
-                        queueRemovalAcknowledgment: result.fix.queueRemovalAcknowledgment,
+                    resolveCommand: result.triage.resolveCommand,
+                    ...(result.triage.resolveOnlyCommand && {
+                        resolveOnlyCommand: result.triage.resolveOnlyCommand,
                     }),
-                    ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
-                    ...(result.fix.changesRequestedReviews.length > 0 && {
-                        changesRequestedReviews: result.fix.changesRequestedReviews,
-                    }),
-                    resolveCommand: result.fix.resolveCommand,
-                    ...(result.fix.resolveOnlyCommand && {
-                        resolveOnlyCommand: result.fix.resolveOnlyCommand,
-                    }),
-                    ...(result.fix.reviewItems && { reviewItems: result.fix.reviewItems }),
-                    ...(result.fix.instructions.length > 0 && {
-                        instructions: result.fix.instructions,
+                    ...(result.triage.reviewItems && { reviewItems: result.triage.reviewItems }),
+                    ...(result.triage.instructions.length > 0 && {
+                        instructions: result.triage.instructions,
                     }),
                 },
             };

package/bin/cli/iterate-verbose.mjs

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

package/bin/cli/journal-formatter.mjs

@@ -1,7 +1,4 @@
 export function formatJournalResult(result) {
-    if (result.authorizationSkipped) {
-        return `Authorization denied or unverifiable — Shepherd Journal in PR #${result.prNumber} was not updated.`;
-    }
     if (result.dryRun) {
         const lines = ["Dry run — no body change written."];
         if (result.previewBody !== undefined) {

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

@@ -1 +1 @@
-export declare function handleJournal(args: string[], command?: "apply journal" | "journal"): Promise<void>;
+export declare function handleJournal(args: string[]): Promise<void>;

package/bin/cli/journal-handler.mjs

@@ -5,7 +5,8 @@ import { getFlag } from "./args.mjs";
 import { parseCliPrReference, resolveParsedPrTarget } from "../pr-reference.mjs";
 import { USAGE } from "./help.mjs";
 import { formatJournalResult } from "./journal-formatter.mjs";
-export async function handleJournal(args, command = "apply journal") {
+export async function handleJournal(args) {
+    const command = "apply journal";
     for (const a of args) {
         if (!a.startsWith("--"))
             continue;

package/bin/cli/mutate-formatter.mjs

@@ -33,15 +33,6 @@ export function formatMutateResult(result) {
     pushIds(lines, "Resolved threads", result.resolvedThreads);
     pushIds(lines, "Minimized comments", result.minimizedComments);
     pushIds(lines, "Dismissed reviews", result.dismissedReviews);
-    pushIds(lines, "Skipped dismissals", result.skippedDismissals);
-    pushIds(lines, "Skipped human thread resolves", result.skippedHumanResolves);
-    pushIds(lines, "Skipped human minimizes", result.skippedHumanMinimizes);
-    pushIds(lines, "Skipped human review dismissals", result.skippedHumanDismissals);
-    pushIds(lines, "Skipped non-human/unknown thread replies", result.skippedNonHumanReplies);
-    pushIds(lines, "Authorization denied/unverifiable for thread replies", result.skippedUnauthorizedReplies);
-    pushIds(lines, "Authorization denied/unverifiable for thread resolves", result.skippedUnauthorizedResolves);
-    pushIds(lines, "Authorization denied/unverifiable for minimizes", result.skippedUnauthorizedMinimizes);
-    pushIds(lines, "Authorization denied/unverifiable for review dismissals", result.skippedUnauthorizedDismissals);
     const rateLimit = formatRateLimit(result);
     if (rateLimit)
         lines.push(rateLimit);

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

@@ -1,7 +1,3 @@
 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

@@ -1,7 +1,3 @@
-/** ` · **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)

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

@@ -1 +1,4 @@
+/** The default command: one PR, or several PRs from one repository. */
 export declare function handlePoll(args: string[]): Promise<void>;
+/** `pr-shepherd stack <PR>`: the native stack containing one PR. */
+export declare function handleStack(args: string[]): Promise<void>;

package/bin/cli/poll-handler.mjs

@@ -1,4 +1,4 @@
-import { runAggregatePollForMode, runPollForMode } from "../commands/event-mode.mjs";
+import { runAggregatePollCommand, runPollCommand, runPollSummaryTick } from "../commands/tick.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
 import { parseDurationToSeconds } from "./duration.mjs";
@@ -8,41 +8,88 @@ import { emitIterateResult } from "./iterate-emitter.mjs";
 import { EXIT } from "../exit-codes.mjs";
 import { emitPollSummaryResult } from "./poll-summary-emitter.mjs";
 import { parsePollTargets, resolvePollTargets } from "./poll-targets.mjs";
+import { DEFAULT_POLL_BOOLEAN_FLAGS, DEFAULT_POLL_FLAGS_WITH_VALUES } from "./default-poll.mjs";
+import { validateDefaultArgs } from "./validate-default-args.mjs";
+import { rejectRemovedFlags } from "./removed-flags.mjs";
+import { rejectUnknownFlags } from "./unknown-flags.mjs";
+import { maybePrintHelp, USAGE } from "./help.mjs";
+/** The default command: one PR, or several PRs from one repository. */
 export async function handlePoll(args) {
     const parsedTargets = parsePollTargets(args);
     if (!parsedTargets)
         return;
-    const needsResolution = parsedTargets.stack !== undefined || parsedTargets.refs.length > 1;
-    const resolvedTargets = needsResolution
-        ? await resolvePollTargets(parsedTargets)
-        : { prNumbers: [] };
-    const isAggregate = resolvedTargets.stackPrNumber !== undefined || resolvedTargets.prNumbers.length > 1;
-    const { prNumber, global: commonGlobalOpts, extra: commonExtra } = parseCommonArgs(args);
-    const globalOpts = isAggregate ? parsedTargets.global : commonGlobalOpts;
-    const extra = isAggregate ? parsedTargets.extra : commonExtra;
+    const resolvedTargets = parsedTargets.refs.length > 1 ? await resolvePollTargets(parsedTargets) : { prNumbers: [] };
+    // Duplicate references collapse to one PR, which takes the single-PR iterator.
+    if (resolvedTargets.prNumbers.length > 1) {
+        const shared = parseLoopOptions(parsedTargets.extra, parsedTargets.global, true);
+        if (!shared)
+            return;
+        const result = await runAggregatePollCommand({ ...shared.options, ...resolvedTargets });
+        emitPollSummaryResult(result, { format: parsedTargets.global.format });
+        return;
+    }
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const shared = parseLoopOptions(extra, globalOpts, false);
+    if (!shared)
+        return;
+    const result = await runPollCommand({ ...shared.options, prNumber });
+    emitIterateResult(result, {
+        format: globalOpts.format,
+        verbose: globalOpts.verbose ?? false,
+        readyDelaySuffix: shared.readyDelaySuffix,
+    });
+}
+/** `pr-shepherd stack <PR>`: the native stack containing one PR. */
+export async function handleStack(args) {
+    if (maybePrintHelp(args, "stack"))
+        return;
+    if (rejectRemovedFlags(args) || rejectUnknownFlags(args, "stack", STACK_FLAGS))
+        return;
+    if (!validateDefaultArgs(args, DEFAULT_POLL_FLAGS_WITH_VALUES, STACK_BOOLEAN_FLAGS, usageArg))
+        return;
+    const parsedTargets = parsePollTargets(args);
+    if (!parsedTargets)
+        return;
+    if (parsedTargets.refs.length !== 1) {
+        usage("stack requires exactly one PR reference.");
+        return;
+    }
+    const { prNumbers, targetRepository } = await resolvePollTargets(parsedTargets);
+    const shared = parseLoopOptions(parsedTargets.extra, parsedTargets.global, true);
+    if (!shared)
+        return;
+    const target = { stackPrNumber: prNumbers[0], targetRepository };
+    const result = hasFlag(parsedTargets.extra, "--once")
+        ? await runPollSummaryTick({ ...shared.options, ...target })
+        : await runAggregatePollCommand({ ...shared.options, ...target });
+    emitPollSummaryResult(result, { format: parsedTargets.global.format });
+}
+const STACK_BOOLEAN_FLAGS = new Set([...DEFAULT_POLL_BOOLEAN_FLAGS, "--once"]);
+const STACK_FLAGS = [...DEFAULT_POLL_FLAGS_WITH_VALUES, ...STACK_BOOLEAN_FLAGS];
+function parseLoopOptions(extra, globalOpts, isAggregate) {
     const cfg = loadConfig();
     const flags = parseIterateFlags(extra, cfg);
     if (hasInvalidIterateFlags(flags))
-        return;
+        return null;
     const intervalStr = getFlag(extra, "--interval");
     const intervalSuffix = validateSecondsDurationFlag("pr-shepherd", "--interval", intervalStr, hasFlag(extra, "--interval"));
     if (intervalSuffix === null)
-        return;
-    let intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", cfg.poll.intervalSeconds);
+        return null;
+    let intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", cfg.poll["interval-seconds"]);
     // `--interval` is the invocation interval. Only an omitted flag is scaled, and only for aggregates.
     if (isAggregate && intervalSuffix === undefined) {
-        intervalSeconds *= cfg.poll.stackIntervalFactor;
+        intervalSeconds *= cfg.poll["stack-interval-factor"];
     }
     const timeoutStr = getFlag(extra, "--timeout");
     const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
     if (timeoutSuffix === null)
-        return;
-    const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", cfg.poll.timeoutSeconds);
+        return null;
+    const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", cfg.poll["timeout-seconds"]);
     const debounceStr = getFlag(extra, "--debounce");
     const debounceSuffix = validateSecondsDurationFlag("pr-shepherd", "--debounce", debounceStr, hasFlag(extra, "--debounce"), { allowZero: true });
     if (debounceSuffix === null)
-        return;
-    const debounceSeconds = parseDurationToSeconds(debounceSuffix ?? "", cfg.poll.debounceSeconds, {
+        return null;
+    const debounceSeconds = parseDurationToSeconds(debounceSuffix ?? "", cfg.poll["debounce-seconds"], {
         allowZero: true,
     });
     const quietStatusFlag = hasFlag(extra, "--quiet-status");
@@ -50,36 +97,30 @@ export async function handlePoll(args) {
     if (quietStatusFlag && noQuietStatusFlag) {
         process.stderr.write("pr-shepherd: --quiet-status and --no-quiet-status cannot be used together\n");
         process.exitCode = EXIT.USAGE;
-        return;
-    }
-    const quietStatus = quietStatusFlag || (!noQuietStatusFlag && cfg.poll.quietStatus);
-    const shared = {
-        ...globalOpts,
-        readyDelaySeconds: flags.readyDelaySeconds,
-        stallTimeoutSeconds: flags.stallTimeoutSeconds,
-        noAutoMarkReady: flags.noAutoMarkReady,
-        noAutoCancelActionable: flags.noAutoCancelActionable,
-        merge: flags.merge,
-        instructions: flags.instructions ?? undefined,
-        pollMode: flags.pollMode ?? undefined,
-        intervalSeconds,
-        timeoutSeconds,
-        debounceSeconds,
-        quietStatus,
-        untilTerminal: hasFlag(extra, "--until-terminal"),
-    };
-    if (isAggregate) {
-        const result = await runAggregatePollForMode({
-            ...shared,
-            ...resolvedTargets,
-        });
-        emitPollSummaryResult(result, { format: globalOpts.format });
-        return;
+        return null;
     }
-    const result = await runPollForMode({ ...shared, prNumber });
-    emitIterateResult(result, {
-        format: globalOpts.format,
-        verbose: globalOpts.verbose ?? false,
+    const quietStatus = quietStatusFlag || (!noQuietStatusFlag && cfg.poll["quiet-status"]);
+    return {
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
-    });
+        options: {
+            ...globalOpts,
+            readyDelaySeconds: flags.readyDelaySeconds,
+            stallTimeoutSeconds: flags.stallTimeoutSeconds,
+            noAutoMarkReady: flags.noAutoMarkReady,
+            merge: flags.merge,
+            instructions: flags.instructions ?? undefined,
+            intervalSeconds,
+            timeoutSeconds,
+            debounceSeconds,
+            quietStatus,
+            untilTerminal: hasFlag(extra, "--until-terminal"),
+        },
+    };
+}
+function usageArg(arg) {
+    usage(`unexpected argument: "${arg}"`);
+}
+function usage(message) {
+    process.stderr.write(`pr-shepherd: stack: ${message}\n${USAGE.stack}\n`);
+    process.exitCode = EXIT.USAGE;
 }

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

@@ -25,8 +25,8 @@ function pollSummaryExitCode(result) {
     const actions = new Set(result.prs.map((item) => item.action));
     if (actions.has("escalate"))
         return EXIT.ESCALATE;
-    if (actions.has("fix_code"))
-        return EXIT.FIX_CODE;
+    if (actions.has("triage"))
+        return EXIT.TRIAGE;
     if (actions.has("merge"))
         return EXIT.MERGE;
     if (actions.has("mark_ready"))

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

@@ -2,7 +2,7 @@ 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";
+import { formatNextCheckLines } from "./next-check-format.mjs";
 export function formatPollSummaryResult(result) {
     if (result.selection.kind === "stack")
         return formatStackOverview(projectStackOverview(result));
@@ -10,7 +10,7 @@ export function formatPollSummaryResult(result) {
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
-        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${formatPollModeSegment(result)}${result.stackMergeable !== undefined ? ` · **stack mergeable** \`${result.stackMergeable}\`` : ""}${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.stackMergeable !== undefined ? ` · **stack mergeable** \`${result.stackMergeable}\`` : ""}${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
         ...formatNextCheckLines(result.nextCheck),
         "",
         "## Pull requests",

package/bin/cli/poll-targets.d.mts

@@ -3,13 +3,13 @@ import { type ParsedPrReference } from "../pr-reference.mts";
 import type { GlobalOptions } from "../types.mts";
 export interface ParsedPollTargets {
     refs: ParsedPrReference[];
-    stack: ParsedPrReference | undefined;
     global: GlobalOptions;
     extra: string[];
 }
+/** Splits PR references from flags. Returns null after printing a usage error. */
 export declare function parsePollTargets(args: string[]): ParsedPollTargets | null;
+/** Resolves PR references that must all name one repository. */
 export declare function resolvePollTargets(parsed: ParsedPollTargets): Promise<{
     prNumbers: number[];
-    stackPrNumber?: number;
     targetRepository?: RepoInfo;
 }>;