pr-shepherd 0.60.1 → 1.0.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/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-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

@@ -26,7 +26,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 }),
     };
 }
@@ -94,7 +93,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),

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;
+}

package/bin/cli-parser.mjs

@@ -1,24 +1,25 @@
 /* eslint-disable max-lines */
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
-import { EXIT, applyReviewResultToExitCode, errorToExitCode } from "./exit-codes.mjs";
+import { EXIT, ShepherdError, applyReviewResultToExitCode, errorToExitCode, } from "./exit-codes.mjs";
+import { loadConfig } from "./config/load.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 { rejectUnknownFlags } from "./cli/unknown-flags.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
-import { handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
+import { handleSuggest, 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 { handlePoll, handleStack } 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";
@@ -34,7 +35,6 @@ export async function main(argv) {
     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")) {
@@ -50,6 +50,17 @@ export async function main(argv) {
         process.exitCode = EXIT.USAGE;
         return;
     }
+    // Validate config before any GitHub work, so a bad or pre-v1 config file exits 78 up front.
+    try {
+        loadConfig();
+    }
+    catch (error) {
+        if (!(error instanceof ShepherdError))
+            throw error;
+        process.stderr.write(`pr-shepherd: ${error.message}\n`);
+        process.exitCode = error.exitCode;
+        return;
+    }
     return runWithGithubTransport(mode, () => dispatch(dispatched), {
         verbose: extracted.args.includes("--verbose"),
     });
@@ -65,12 +76,7 @@ async function dispatch(argv) {
         process.stdout.write(`${USAGE.top}\n`);
         return;
     }
-    // log-file must run before the stdout tee and log init to avoid recursion.
-    if (subcommand === "log-file") {
-        await handleLogFile(args.slice(1));
-        return;
-    }
-    // Extraction deliberately precedes legacy warnings and logging: it is a local,
+    // Extraction deliberately precedes logging: it is a local,
     // GitHub/config/log-free read path for automation that already has a PR body.
     if (subcommand === "journal" && args[1] === "extract") {
         await handleJournalExtract(args.slice(2));
@@ -80,7 +86,7 @@ async function dispatch(argv) {
     // command namespace. Keep this before setupLog because log-file reads the
     // log path and must not initialize/tee the log it is reporting.
     if (subcommand === "admin" && args[1] === "log-file") {
-        await handleLogFile(args.slice(2), "admin log-file");
+        await handleLogFile(args.slice(2));
         return;
     }
     // Short-circuit all --help/-h before any I/O or logging.
@@ -93,24 +99,12 @@ async function dispatch(argv) {
         }
         return;
     }
-    const legacyReplacement = {
-        poll: "pr-shepherd [PR] (the default PR polling command)",
-        resolve: "apply review",
-        "mark-files-as-viewed": "apply files",
-        journal: "apply journal",
-        "build-suggestion-patch": "build-suggestion-patches",
-        "commit-suggestion": "build-suggestion-patches",
-    };
-    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));
+    return dispatchLogged(argv);
 }
 async function dispatchLogged(argv) {
     const args = argv.slice(2);
@@ -127,36 +121,18 @@ async function dispatchLogged(argv) {
         case "apply":
             await handleApply(args.slice(1));
             break;
-        case "build-suggestion-patches":
-            await handleSuggestionPatches(args.slice(1));
+        case "suggest":
+            await handleSuggest(args.slice(1));
             break;
-        case "build-suggestion-patch":
-            await handleCommitSuggestion(args.slice(1));
+        case "stack":
+            await handleStack(args.slice(1));
             break;
         case "admin":
             await handleAdmin(args.slice(1));
             break;
-        case "resolve":
-            await handleResolve(args.slice(1), "resolve");
-            break;
-        case "commit-suggestion":
-            await handleCommitSuggestion(args.slice(1), "commit-suggestion");
-            break;
-        case "mark-files-as-viewed":
-            await handleMarkFilesAsViewed(args.slice(1), "mark-files-as-viewed");
-            break;
         case "iterate":
             await handleIterate(args.slice(1));
             break;
-        case "poll":
-            await handlePoll(args.slice(1));
-            break;
-        case "clean":
-            await handleClean(args.slice(1), "clean");
-            break;
-        case "journal":
-            await handleJournal(args.slice(1), "journal");
-            break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
             process.stderr.write(`${USAGE.top}\n`);
@@ -164,9 +140,6 @@ async function dispatchLogged(argv) {
             return;
     }
 }
-function warnLegacyAlias(alias, replacement) {
-    process.stderr.write(`pr-shepherd: ${alias} is deprecated; use ${replacement.startsWith("pr-shepherd") ? replacement : `pr-shepherd ${replacement}`} instead.\n`);
-}
 async function handleApply(args) {
     const action = args[0];
     switch (action) {
@@ -213,10 +186,10 @@ function readVersion() {
 // ---------------------------------------------------------------------------
 // Subcommand handlers
 // ---------------------------------------------------------------------------
-async function handleLogFile(args, usageKey = "log-file") {
-    if (maybePrintHelp(args, usageKey))
+async function handleLogFile(args) {
+    if (maybePrintHelp(args, "admin log-file"))
         return;
-    if (rejectInvalidPollModeFlag(args, usageKey))
+    if (rejectUnknownFlags(args, "admin log-file", []))
         return;
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {
@@ -224,16 +197,27 @@ async function handleLogFile(args, usageKey = "log-file") {
             return idx !== -1 && args[idx + 1] === "json";
         })();
     try {
-        // Report the log the matching tick writes: event mode keeps it in durable state.
-        const result = await runInPollModeScope(args, () => runLogFile());
+        const result = await runLogFile();
         process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${result.path}\n`);
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: log-file: ${String(e)}\n`);
+        process.stderr.write(`pr-shepherd: admin log-file: ${String(e)}\n`);
         process.exitCode = errorToExitCode(e);
     }
 }
-async function handleResolve(args, command = "apply review") {
+const APPLY_REVIEW_FLAGS = [
+    "--resolve-thread-ids",
+    "--reply-thread-ids",
+    "--minimize-comment-ids",
+    "--dismiss-review-ids",
+    "--message",
+    "--require-sha",
+    "--adopt-existing-replies",
+];
+async function handleResolve(args) {
+    const command = "apply review";
+    if (rejectUnknownFlags(args, command, APPLY_REVIEW_FLAGS))
+        return;
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
     const replyThreadIds = parseList(getFlag(extra, "--reply-thread-ids"));
@@ -247,11 +231,6 @@ async function handleResolve(args, command = "apply review") {
         return;
     if (rejectPrrcMinimizeIds(minimizeCommentIds).length > 0)
         return;
-    if (hasFlag(extra, "--fetch")) {
-        process.stderr.write(`pr-shepherd: ${command}: --fetch has been removed; run pr-shepherd iterate to fetch the next action.\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
     const hasAction = resolveThreadIds.length > 0 ||
         replyThreadIds.length > 0 ||
         minimizeCommentIds.length > 0 ||

package/bin/commands/check-annotations.d.mts

@@ -6,7 +6,7 @@ export declare function checksWithActionableAnnotations(report: ShepherdReport):
  * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
  * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
  * the seen-marker suppression gate there can't drift from the actual iterate dispatch
- * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * decision (a queued PR with a failing check still renders review items via `triage`; their
  * seen markers must not be suppressed just because the PR happens to be queued).
  */
 export declare function hasCheckDrivenActionableWork(checks: {

package/bin/commands/check-annotations.mjs

@@ -20,7 +20,7 @@ export function checksWithActionableAnnotations(report) {
  * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
  * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
  * the seen-marker suppression gate there can't drift from the actual iterate dispatch
- * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * decision (a queued PR with a failing check still renders review items via `triage`; their
  * seen markers must not be suppressed just because the PR happens to be queued).
  */
 export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {