pr-shepherd 0.56.6 → 0.57.1

package/bin/classify/standard/kilo-no-issues.mjs

@@ -0,0 +1,17 @@
+import { isBotItem } from "./author.mjs";
+const STATUS_LINE = /^[^\S\n]*(?:\*\*)?Status:?(?:\*\*)?:?[^\S\n]*(?:\p{Extended_Pictographic}️?[^\S\n]*)?No Issues Found\b/imu;
+/** Headings a no-issues report carries; any other heading means real feedback. */
+const REPORT_HEADING = /^(?:Code Review Summary|Files Reviewed\b.*)$/i;
+/** Kilo Code conversation comment whose status line reads "No Issues Found" and that carries no findings. */
+const rule = (item) => {
+    if (!isBotItem(item, ["kilo-code-bot"], ["pr-comment"]))
+        return null;
+    if (!STATUS_LINE.test(item.body))
+        return null;
+    for (const [, heading] of item.body.matchAll(/^#{1,6}\s+(.*)$/gm)) {
+        if (!REPORT_HEADING.test(heading.trim()))
+            return null;
+    }
+    return { autoResolve: true, suppress: true, reason: "Kilo Code no-issues report" };
+};
+export default rule;

package/bin/classify/standard/sourcery-notices.d.mts

@@ -0,0 +1,8 @@
+import type { ClassifyRule } from "../types.mts";
+/**
+ * Sourcery's private-repo upsell and weekly rate-limit notices on conversation comments. A real review opens
+ * with a Markdown heading ("Reviewer's Guide", "Summary by Sourcery"); the notices carry none,
+ * so a heading means genuine feedback that merely quotes the phrase.
+ */
+declare const rule: ClassifyRule;
+export default rule;

package/bin/classify/standard/sourcery-notices.mjs

@@ -0,0 +1,20 @@
+import { isBotItem } from "./author.mjs";
+/**
+ * Sourcery's private-repo upsell and weekly rate-limit notices on conversation comments. A real review opens
+ * with a Markdown heading ("Reviewer's Guide", "Summary by Sourcery"); the notices carry none,
+ * so a heading means genuine feedback that merely quotes the phrase.
+ */
+const rule = (item) => {
+    if (!isBotItem(item, ["sourcery-ai"], ["pr-comment"]))
+        return null;
+    if (/^#{1,6}\s/m.test(item.body))
+        return null;
+    if (/does not have access to Sourcery/i.test(item.body)) {
+        return { autoResolve: true, suppress: true, reason: "Sourcery no-access upsell" };
+    }
+    if (/reached your weekly rate limit/i.test(item.body)) {
+        return { autoResolve: true, suppress: true, reason: "Sourcery rate-limit notice" };
+    }
+    return null;
+};
+export default rule;

package/bin/cli/api-usage-formatter.mjs

@@ -3,7 +3,9 @@ function resetTime(resetAt) {
 }
 function formatResource(resource) {
     const used = resource.used === undefined ? "" : ` · used ${resource.used}`;
-    return `- \`${resource.resource}\`: ${resource.remaining}/${resource.limit} remaining${used} · ${resource.requestCount} requests · resets ${resetTime(resource.resetAt)}`;
+    const notModified = resource.notModified === undefined ? "" : ` · ${resource.notModified} not modified (304)`;
+    const requests = resource.requestCount === undefined ? "" : ` · ${resource.requestCount} requests`;
+    return `- \`${resource.resource}\`: ${resource.remaining}/${resource.limit} remaining${used}${requests}${notModified} · resets ${resetTime(resource.resetAt)}`;
 }
 export function formatQuotaWarning(warning) {
     if (warning === undefined)
@@ -46,5 +48,8 @@ export function formatApiUsage(usage) {
     }
     for (const resource of usage.rest ?? [])
         lines.push(formatResource(resource));
+    if (usage.unmeteredRestRequestCount !== undefined) {
+        lines.push(`- REST requests without rate-limit headers (unmetered): ${usage.unmeteredRestRequestCount}`);
+    }
     return lines.join("\n");
 }

package/bin/cli/apply-merge-handler.d.mts

@@ -0,0 +1,3 @@
+import { type ApplyMergeResult } from "../commands/apply-merge.mts";
+export declare function handleApplyMerge(args: string[]): Promise<void>;
+export declare function formatApplyMergeResult(result: ApplyMergeResult): string;

package/bin/cli/apply-merge-handler.mjs

@@ -0,0 +1,73 @@
+import { EXIT, ShepherdError, errorToExitCode } from "../exit-codes.mjs";
+import { runApplyMerge } from "../commands/apply-merge.mjs";
+import { getFlag, parseCommonArgs } from "./args.mjs";
+import { maybePrintHelp, USAGE } from "./help.mjs";
+const flags = new Set(["--require-sha", "--merge-action", "--method", "--expected-stack"]);
+export async function handleApplyMerge(args) {
+    if (maybePrintHelp(args, "apply merge"))
+        return;
+    try {
+        const { prNumber, global, extra } = parseCommonArgs(args);
+        for (let index = 0; index < extra.length; index += 1) {
+            const arg = extra[index];
+            const name = arg.split("=", 1)[0];
+            if (!flags.has(name))
+                throw new ShepherdError(`Unknown apply merge argument: ${arg}`, EXIT.USAGE);
+            if (!arg.includes("=")) {
+                if (!extra[index + 1] || extra[index + 1].startsWith("--"))
+                    throw new ShepherdError(`${name} requires a value`, EXIT.USAGE);
+                index += 1;
+            }
+        }
+        const requireSha = getFlag(extra, "--require-sha");
+        const mergeAction = getFlag(extra, "--merge-action");
+        if (requireSha === null || mergeAction === null) {
+            process.stderr.write(`${USAGE["apply merge"]}\n`);
+            process.exitCode = EXIT.USAGE;
+            return;
+        }
+        const result = await runApplyMerge({
+            prNumber,
+            targetRepository: global.targetRepository,
+            requireSha,
+            mergeAction: mergeAction,
+            mergeMethod: (getFlag(extra, "--method") ?? undefined),
+            expectedStack: parseExpectedStack(getFlag(extra, "--expected-stack")),
+        });
+        process.stdout.write(`${global.format === "json" ? JSON.stringify(result, null, 2) : formatApplyMergeResult(result)}\n`);
+        process.exitCode =
+            result.status === "pending"
+                ? EXIT.WAIT
+                : result.status === "failed"
+                    ? result.uncertain
+                        ? EXIT.TEMPFAIL
+                        : EXIT.UNAVAILABLE
+                    : EXIT.OK;
+    }
+    catch (error) {
+        process.stderr.write(`pr-shepherd: apply merge: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = errorToExitCode(error);
+    }
+}
+function parseExpectedStack(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new ShepherdError("--expected-stack must be valid JSON", EXIT.DATAERR);
+    }
+}
+export function formatApplyMergeResult(result) {
+    const lines = [`PR: ${result.repo}#${result.pr}`, `status: ${result.status}`];
+    if (result.uncertain)
+        lines.push("uncertain: true");
+    if (result.note)
+        lines.push(`note: ${result.note}`);
+    for (const [name, value] of Object.entries(result.details)) {
+        if (value !== undefined)
+            lines.push(`- ${name}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,2 @@
+export declare const FLAGS_WITH_VALUES: Set<string>;
+export declare const BOOLEAN_FLAGS: Set<string>;

package/bin/cli/arg-flags.mjs

@@ -0,0 +1,47 @@
+// Flags that consume the next argument as their value (used for PR-number
+// detection only — prevents a flag's value from being mistaken for a PR number).
+export const FLAGS_WITH_VALUES = new Set([
+    "--transport",
+    "--merge-action",
+    "--method",
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--instructions",
+    "--poll-mode",
+    "--require-sha",
+    "--message",
+    "--description",
+    "--body-file",
+    "--file",
+    "--stack",
+    "--thread-id",
+    "--resolve-thread-ids",
+    "--reply-thread-ids",
+    "--minimize-comment-ids",
+    "--dismiss-review-ids",
+    "--interval",
+    "--timeout",
+    "--debounce",
+    "--match",
+    "--check",
+    "--blocked-by",
+    "--queue-commit",
+    "--removed-at",
+]);
+// Boolean flags that do NOT consume the next argument. Any --flag not in this
+// set and not in FLAGS_WITH_VALUES is treated conservatively as value-taking
+// for PR-number detection — so removed flags don't silently cause their
+// numeric value to be misidentified as the PR number.
+export const BOOLEAN_FLAGS = new Set([
+    "--no-auto-mark-ready",
+    "--no-auto-cancel-actionable",
+    "--quiet-status",
+    "--no-quiet-status",
+    "--until-terminal",
+    "--merge",
+    "--dry-run",
+    "--verbose",
+    "--clear",
+    "--adopt-existing-replies",
+]);

package/bin/cli/args.mjs

@@ -3,45 +3,8 @@
  */
 import { parseArgs } from "node:util";
 import { parseCliPrReference, resolveParsedPrTarget } from "../pr-reference.mjs";
-// Flags that consume the next argument as their value (used for PR-number
-// detection only — prevents a flag's value from being mistaken for a PR number).
-const FLAGS_WITH_VALUES = new Set([
-    "--format",
-    "--ready-delay",
-    "--stall-timeout",
-    "--require-sha",
-    "--message",
-    "--description",
-    "--thread-id",
-    "--resolve-thread-ids",
-    "--reply-thread-ids",
-    "--minimize-comment-ids",
-    "--dismiss-review-ids",
-    "--interval",
-    "--timeout",
-    "--debounce",
-    "--match",
-    "--check",
-    "--blocked-by",
-    "--require-sha",
-    "--queue-commit",
-    "--removed-at",
-]);
-// Boolean flags that do NOT consume the next argument. Any --flag not in this
-// set and not in FLAGS_WITH_VALUES is treated conservatively as value-taking
-// for PR-number detection — so removed flags don't silently cause their
-// numeric value to be misidentified as the PR number.
-const BOOLEAN_FLAGS = new Set([
-    "--no-auto-mark-ready",
-    "--no-auto-cancel-actionable",
-    "--quiet-status",
-    "--no-quiet-status",
-    "--until-terminal",
-    "--merge",
-    "--dry-run",
-    "--verbose",
-    "--clear",
-]);
+import { parseGithubTransport } from "../github/transport-mode.mjs";
+import { FLAGS_WITH_VALUES, BOOLEAN_FLAGS } from "./arg-flags.mjs";
 // ---------------------------------------------------------------------------
 // Strict integer parsing
 // ---------------------------------------------------------------------------
@@ -58,7 +21,9 @@ export function parseCommonArgs(args) {
         allowPositionals: true,
         tokens: true,
         options: {
+            ...Object.fromEntries([...FLAGS_WITH_VALUES].map((flag) => [flag.slice(2), { type: "string" }])),
             format: { type: "string" },
+            transport: { type: "string" },
             verbose: { type: "boolean" },
         },
     });
@@ -68,11 +33,12 @@ export function parseCommonArgs(args) {
     // them from `extra`.  Subcommand-specific flags are left untouched.
     const consumedIndices = new Set();
     for (const tok of tokens ?? []) {
-        if (tok.kind === "option" && (tok.name === "format" || tok.name === "verbose")) {
+        if (tok.kind === "option" &&
+            (tok.name === "format" || tok.name === "verbose" || tok.name === "transport")) {
             consumedIndices.add(tok.index);
             // When the value is a separate arg (--flag value, not --flag=value),
             // inlineValue is false and the value occupies tok.index + 1.
-            if (tok.name === "format" &&
+            if ((tok.name === "format" || tok.name === "transport") &&
                 "inlineValue" in tok &&
                 tok.inlineValue === false &&
                 tok.value != null) {
@@ -122,6 +88,9 @@ export function parseCommonArgs(args) {
         global: {
             format,
             verbose,
+            ...(values.transport !== undefined
+                ? { transport: parseGithubTransport(values.transport) }
+                : {}),
             ...(target.targetRepository !== undefined
                 ? { targetRepository: target.targetRepository }
                 : undefined),

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

@@ -0,0 +1 @@
+export declare function handleClean(args: string[], command?: "admin clean" | "clean"): Promise<void>;

package/bin/cli/clean-handler.mjs

@@ -0,0 +1,71 @@
+import { runClean } from "../commands/clean.mjs";
+import { EXIT } from "../exit-codes.mjs";
+import { USAGE } from "./help.mjs";
+import { formatCleanResult } from "./formatters.mjs";
+import { rejectInvalidPollModeFlag, runInPollModeScope } from "./event-state-scope.mjs";
+const CLEAN_VARIANTS = new Set(["pr", "branch", "current", "repo", "all"]);
+export async function handleClean(args, command = "admin clean") {
+    const usage = command === "admin clean" ? USAGE["admin clean"] : USAGE.clean;
+    const variant = args[0];
+    if (!variant || !CLEAN_VARIANTS.has(variant)) {
+        process.stderr.write(`${usage}\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const rest = args.slice(1);
+    for (const a of rest) {
+        if (!a.startsWith("--"))
+            continue;
+        if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
+            continue;
+        if (a === "--poll-mode" || a.startsWith("--poll-mode="))
+            continue;
+        process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const fmtIdx = rest.indexOf("--format");
+    const fmtEqEntry = rest.find((a) => a.startsWith("--format="));
+    let formatValue;
+    if (fmtEqEntry !== undefined) {
+        formatValue = fmtEqEntry.slice("--format=".length);
+    }
+    else if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
+        formatValue = rest[fmtIdx + 1];
+    }
+    if (formatValue !== undefined && formatValue !== "text" && formatValue !== "json") {
+        process.stderr.write(`pr-shepherd: ${command}: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    if (rejectInvalidPollModeFlag(rest, command))
+        return;
+    const jsonOut = formatValue === "json";
+    const dryRun = rest.includes("--dry-run");
+    // Skip values consumed by --format <value> / --poll-mode <value> so they aren't positionals.
+    const flagConsumedIndices = new Set();
+    if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
+        flagConsumedIndices.add(fmtIdx);
+        flagConsumedIndices.add(fmtIdx + 1);
+    }
+    const pollModeIdx = rest.indexOf("--poll-mode");
+    if (pollModeIdx !== -1) {
+        flagConsumedIndices.add(pollModeIdx);
+        flagConsumedIndices.add(pollModeIdx + 1);
+    }
+    const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
+    if (positionals.length > 1) {
+        process.stderr.write(`pr-shepherd: ${command}: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const value = positionals[0];
+    // Event mode keeps its state under the durable state base; clean must target that same scope.
+    const result = await runInPollModeScope(rest, () => runClean({ variant: variant, value, dryRun }));
+    if (!result.ok) {
+        process.stderr.write(`pr-shepherd: ${command}: ${result.error}\n`);
+        process.exitCode = EXIT.SOFTWARE;
+        return;
+    }
+    process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${formatCleanResult(result)}\n`);
+}

package/bin/cli/default-poll.mjs

@@ -3,9 +3,12 @@ import { parsePrNumber } from "./args.mjs";
 import { validateDefaultArgs } from "./validate-default-args.mjs";
 import { USAGE } from "./help.mjs";
 const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
+    "--transport",
     "--format",
     "--ready-delay",
     "--stall-timeout",
+    "--instructions",
+    "--poll-mode",
     "--interval",
     "--timeout",
     "--debounce",

package/bin/cli/event-state-scope.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Run a dispatched command, entering the durable state scope first when it resolves to event
+ * mode. Entering before log setup keeps the per-worktree log a peer of the seen markers and
+ * stall state an event session writes. Invalid flags or config fall through unscoped so the
+ * command handler reports them.
+ */
+export declare function runInEventStateScope<T>(args: string[], work: () => Promise<T>): Promise<T>;
+/**
+ * Report an invalid `--poll-mode` value as a usage error. Commands that only use the flag to
+ * pick a state scope (`log-file`, `clean`) call this before `runInPollModeScope`, because no
+ * later handler would reject a typo there. Returns true after printing the error.
+ */
+export declare function rejectInvalidPollModeFlag(args: string[], command: string): boolean;
+/**
+ * Run `work` in the durable state scope when `--poll-mode` in `args`, or else `poll.mode`,
+ * resolves to event mode. `log-file` and `clean` use this to reach the state an event tick
+ * writes.
+ */
+export declare function runInPollModeScope<T>(args: string[], work: () => Promise<T>): Promise<T>;

package/bin/cli/event-state-scope.mjs

@@ -0,0 +1,60 @@
+import { loadConfig } from "../config/load.mjs";
+import { EXIT } from "../exit-codes.mjs";
+import { resolvePollMode } from "../commands/poll-mode.mjs";
+import { runWithDurableState } from "../state/durable-state.mjs";
+import { getFlag } from "./args.mjs";
+import { isDefaultPollInvocation } from "./default-poll.mjs";
+/** Subcommands that honor `--poll-mode`; the default poll invocation honors it too. */
+const POLL_MODE_SUBCOMMANDS = new Set(["iterate", "poll"]);
+const REQUESTABLE = ["auto", "poll", "event"];
+function requestedPollMode(value) {
+    return REQUESTABLE.find((mode) => mode === value);
+}
+/**
+ * Run a dispatched command, entering the durable state scope first when it resolves to event
+ * mode. Entering before log setup keeps the per-worktree log a peer of the seen markers and
+ * stall state an event session writes. Invalid flags or config fall through unscoped so the
+ * command handler reports them.
+ */
+export function runInEventStateScope(args, work) {
+    const subcommand = args[0];
+    const honorsPollMode = isDefaultPollInvocation(subcommand) || POLL_MODE_SUBCOMMANDS.has(subcommand ?? "");
+    return honorsPollMode ? runInPollModeScope(args, work) : work();
+}
+/**
+ * Report an invalid `--poll-mode` value as a usage error. Commands that only use the flag to
+ * pick a state scope (`log-file`, `clean`) call this before `runInPollModeScope`, because no
+ * later handler would reject a typo there. Returns true after printing the error.
+ */
+export function rejectInvalidPollModeFlag(args, command) {
+    if (!args.some((arg) => arg === "--poll-mode" || arg.startsWith("--poll-mode=")))
+        return false;
+    const value = getFlag(args, "--poll-mode");
+    if (requestedPollMode(value))
+        return false;
+    process.stderr.write(`pr-shepherd: ${command}: --poll-mode must be one of ${REQUESTABLE.join(", ")}, got ${JSON.stringify(value ?? "")}\n`);
+    process.exitCode = EXIT.USAGE;
+    return true;
+}
+/**
+ * Run `work` in the durable state scope when `--poll-mode` in `args`, or else `poll.mode`,
+ * resolves to event mode. `log-file` and `clean` use this to reach the state an event tick
+ * writes.
+ */
+export function runInPollModeScope(args, work) {
+    return resolvesToEvent(args) ? runWithDurableState(work) : work();
+}
+function resolvesToEvent(args) {
+    const flag = getFlag(args, "--poll-mode");
+    const requested = requestedPollMode(flag);
+    // An explicit poll or event request wins without reading config, so a malformed config
+    // cannot drop an explicit `--poll-mode event` out of the durable scope.
+    if (requested === "event" || requested === "poll")
+        return requested === "event";
+    try {
+        return resolvePollMode(requested, loadConfig().poll.mode) === "event";
+    }
+    catch {
+        return false;
+    }
+}

package/bin/cli/fix-formatter.mjs

@@ -1,5 +1,4 @@
 /* eslint-disable max-lines */
-import { renderResolveCommand } from "../commands/iterate/render.mjs";
 import { inlineCode, joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
@@ -77,9 +76,8 @@ export function formatFixCodeResult(header, result, opts = {}) {
             const scopeTag = ch.scope
                 ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`
                 : "";
-            const rerunTag = ch.rerunCommand ? " [rerun authorized]" : "";
             const lines = [
-                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${attemptTag}${scopeTag}${rerunTag}`,
+                `- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${attemptTag}${scopeTag}`,
             ];
             if (ch.conclusion !== "CANCELLED") {
                 if (ch.failedStep)
@@ -184,13 +182,8 @@ export function formatFixCodeResult(header, result, opts = {}) {
         sections.push("## Cancelled runs");
         sections.push(result.cancelled.map((id) => `- \`${id}\``).join("\n"));
     }
-    sections.push("## Post-fix actions");
-    const postFixLines = [`- base: \`${result.baseBranch}\``];
-    if (result.fix.resolveOnlyCommand?.hasMutations)
-        postFixLines.push(`- resolve-only: \`${renderResolveCommand(result.fix.resolveOnlyCommand)}\``);
-    if (result.fix.resolveCommand.hasMutations) {
-        postFixLines.push(`- apply review: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
-    }
+    // 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) {
@@ -200,7 +193,8 @@ export function formatFixCodeResult(header, result, opts = {}) {
     if (result.fix.queueRemovalAcknowledgment) {
         postFixLines.push(`- acknowledge queue removal: ${inlineCode(renderMergeCommand(result.fix.queueRemovalAcknowledgment))}`);
     }
-    sections.push(postFixLines.join("\n"));
+    if (postFixLines.length > 0)
+        sections.push("## Post-fix actions", postFixLines.join("\n"));
     sections.push("## Instructions");
     sections.push(numberInstructions(result.fix.instructions));
     return joinSections(sections);

package/bin/cli/handlers.d.mts

@@ -1,4 +1,3 @@
-export declare function handleClean(args: string[], command?: "admin clean" | "clean"): Promise<void>;
 export declare function handleCommitSuggestion(args: string[], command?: "build-suggestion-patch" | "commit-suggestion"): Promise<void>;
 export declare function handleSuggestionPatches(args: string[]): Promise<void>;
 export declare function handleIterate(args: string[]): Promise<void>;

package/bin/cli/handlers.mjs

@@ -1,73 +1,16 @@
 import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
 import { runSuggestionPatches } from "../commands/suggestion-patches.mjs";
 import { runMarkFilesAsViewed } from "../commands/mark-files-as-viewed.mjs";
-import { runIterate } from "../commands/iterate/index.mjs";
-import { runClean } from "../commands/clean.mjs";
+import { runIterateForMode } from "../commands/event-mode.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { EXIT } from "../exit-codes.mjs";
 import { parseCommonArgs, getFlag } from "./args.mjs";
 import { USAGE } from "./help.mjs";
-import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatCleanResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
+import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
 import { parseSuggestionPatchGroups } from "./suggestion-patch-flags.mjs";
-import { parseIterateFlags } from "./iterate-flags.mjs";
+import { hasInvalidIterateFlags, parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
 import { parseMarkFilesAsViewedArgs } from "./mark-files-as-viewed-flags.mjs";
-const CLEAN_VARIANTS = new Set(["pr", "branch", "current", "repo", "all"]);
-export async function handleClean(args, command = "admin clean") {
-    const usage = command === "admin clean" ? USAGE["admin clean"] : USAGE.clean;
-    const variant = args[0];
-    if (!variant || !CLEAN_VARIANTS.has(variant)) {
-        process.stderr.write(`${usage}\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
-    const rest = args.slice(1);
-    for (const a of rest) {
-        if (!a.startsWith("--"))
-            continue;
-        if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
-            continue;
-        process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
-    const fmtIdx = rest.indexOf("--format");
-    const fmtEqEntry = rest.find((a) => a.startsWith("--format="));
-    let formatValue;
-    if (fmtEqEntry !== undefined) {
-        formatValue = fmtEqEntry.slice("--format=".length);
-    }
-    else if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
-        formatValue = rest[fmtIdx + 1];
-    }
-    if (formatValue !== undefined && formatValue !== "text" && formatValue !== "json") {
-        process.stderr.write(`pr-shepherd: ${command}: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
-    const jsonOut = formatValue === "json";
-    const dryRun = rest.includes("--dry-run");
-    // Skip the value consumed by --format <value> so it isn't mistaken for the positional.
-    const flagConsumedIndices = new Set();
-    if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
-        flagConsumedIndices.add(fmtIdx);
-        flagConsumedIndices.add(fmtIdx + 1);
-    }
-    const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
-    if (positionals.length > 1) {
-        process.stderr.write(`pr-shepherd: ${command}: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
-    const value = positionals[0];
-    const result = await runClean({ variant: variant, value, dryRun });
-    if (!result.ok) {
-        process.stderr.write(`pr-shepherd: ${command}: ${result.error}\n`);
-        process.exitCode = EXIT.SOFTWARE;
-        return;
-    }
-    process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${formatCleanResult(result)}\n`);
-}
 export async function handleCommitSuggestion(args, command = "build-suggestion-patch") {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
@@ -113,11 +56,10 @@ export async function handleSuggestionPatches(args) {
 }
 export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
-    const cfg = loadConfig();
-    const flags = parseIterateFlags(extra, cfg);
-    if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
+    const flags = parseIterateFlags(extra, loadConfig());
+    if (hasInvalidIterateFlags(flags))
         return;
-    const result = await runIterate({
+    const result = await runIterateForMode({
         ...globalOpts,
         prNumber,
         readyDelaySeconds: flags.readyDelaySeconds,
@@ -125,6 +67,8 @@ export async function handleIterate(args) {
         noAutoMarkReady: flags.noAutoMarkReady,
         noAutoCancelActionable: flags.noAutoCancelActionable,
         merge: flags.merge,
+        instructions: flags.instructions ?? undefined,
+        pollMode: flags.pollMode ?? undefined,
     });
     emitIterateResult(result, {
         format: globalOpts.format,