pr-shepherd 0.60.0 → 1.0.0

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

@@ -1,14 +1,37 @@
 import { isBotItem } from "./author.mjs";
 const QUOTA_NOTICES = [
     /^You have reached your Codex usage limits for security reviews\. Please try again later\.$/,
-    /^You have reached your Codex usage limits for code reviews\. You can see your limits in the \[Codex usage dashboard\]\(https:\/\/chatgpt.com\/codex\/cloud\/settings\/usage\)\.(?:\nTo continue using code reviews, add credits to your account and enable them for code reviews in your \[settings\]\(https:\/\/chatgpt.com\/codex\/cloud\/settings\/code-review\)\.)?$/,
-    /^Codex usage limits have been reached for code reviews\. Please check with the admins of this repo to increase the limits by adding credits\.\nRepo admins can enable using credits for code reviews in their \[settings\]\(https:\/\/chatgpt.com\/codex\/cloud\/settings\/code-review\)\.$/,
+    /^You have reached your Codex usage limits for code reviews\. You can see your limits in the \[Codex usage dashboard\]\(https:\/\/chatgpt\.com\/[^\s)]*\)\.(?:\nTo continue using code reviews, add credits to your account and enable them for code reviews in your \[settings\]\(https:\/\/chatgpt\.com\/[^\s)]*\)\.)?$/,
+    /^Codex usage limits have been reached for code reviews\. Please check with the admins of this repo to increase the limits by adding credits\.\nRepo admins can enable using credits for code reviews in their \[settings\]\(https:\/\/chatgpt\.com\/[^\s)]*\)\.$/,
     /^Codex usage limits have been reached\. Please try again later\.$/,
 ];
 const ABOUT_BLOCK = /\n\n<details> <summary>ℹ️ About Codex (?:in GitHub|security reviews in GitHub)<\/summary>[\s\S]*?<\/details>$/;
-const ACTIVITY_SUMMARY = /^<!-- codex-pull-request-review-summary -->\n(?:<!-- codex-review-state:v1 \{[^\n]*\} -->\n)?(?:<!-- codex-security-review:v1 \{[^\n]*\} -->\n)?\n?## Codex Review Summary\n\nThis comment shows the latest Codex review activity on this pull request\.\n\n\| Review \| Status \| Commit \| Review trigger \|\n\| --- \| --- \| --- \| --- \|\n(?:\|[^\n]+\|\n?)+$/;
-const CLEAN_REVIEW = /^Codex Review: Didn't find any major issues\. (?:Bravo\.|Breezy!|Hooray!|:\+1:)\n\n\*\*Reviewed commit:\*\* `[a-f0-9]+`$/;
-const CLEAN_SECURITY = /^### 🛡️ Codex Security Review(?: · _Automatically triggered_)?\n\nSecurity review completed\. No security issues were found in this pull request\.\n\n\*\*Reviewed commit:\*\* `[a-f0-9]+`\n\n\[View security finding report\]\(https:\/\/chatgpt.com\/codex\/cloud\/tasks\/[a-zA-Z0-9_]+\)\n\n_Only the user who started this review can view the report in Codex\._$/;
+const ACTIVITY_SUMMARY = /^<!-- codex-pull-request-review-summary -->\n(?:<!-- codex-[a-z0-9-]+:[^\n]* -->\n)*\n?## Codex Review Summary\n\nThis comment shows the latest Codex review activity on this pull request\.\n\n\| Review \| Status \| Commit \| Review trigger \|\n\| --- \| --- \| --- \| --- \|\n(?:\|[^\n]+\|\n?)+$/;
+/**
+ * Codex's rotating clean-review sign-offs, as observed. Prose is matched only from this list so a
+ * short piece of advice in that position stays visible; a new sign-off is shown until added here.
+ */
+const SIGN_OFFS = [
+    "Already looking forward to the next diff.",
+    "Another round soon, please!",
+    "Bravo.",
+    "Breezy!",
+    "Can't wait for the next one!",
+    "Chef's kiss.",
+    "Delightful!",
+    "Hooray!",
+    "Keep it up!",
+    "Keep them coming!",
+    "More of your lovely PRs please.",
+    "Nice work!",
+    "Swish!",
+    "What shall we delve into next?",
+    "You're on a roll.",
+];
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** A clean review closes with a known sign-off, a `:shortcode:`, or a single emoji. */
+const CLEAN_REVIEW = new RegExp(`^Codex Review: Didn't find any major issues\\. (?:${SIGN_OFFS.map(escapeRegExp).join("|")}|:[a-z0-9_+-]+:|\\p{Extended_Pictographic}\\uFE0F?)\\n\\n\\*\\*Reviewed commit:\\*\\* \`[a-f0-9]+\`$`, "u");
+const CLEAN_SECURITY = /^### 🛡️ Codex Security Review(?: · _Automatically triggered_)?\n\nSecurity review completed\. No security issues were found in this pull request\.\n\n\*\*Reviewed commit:\*\* `[a-f0-9]+`\n\n\[View security finding report\]\(https:\/\/chatgpt\.com\/[^\s)]*\)\n\n_Only the user who started this review can view the report in Codex\._$/;
 /**
  * Codex quota notices, the review-activity status table, and no-findings notices on conversation
  * comments. Each pattern matches the whole comment, so a notice with any appended finding stays
@@ -21,8 +44,12 @@ const rule = (item) => {
     if (QUOTA_NOTICES.some((notice) => notice.test(body))) {
         return { autoResolve: true, suppress: true, reason: "Codex usage-limit notice" };
     }
-    // Strip only the trailing About block; extra findings after it stay visible.
-    const content = body.replace(ABOUT_BLOCK, "").trim();
+    // Strip only leading codex-* metadata markers and the trailing About block; extra findings stay
+    // visible. The activity table's own marker has no colon, so it is kept for ACTIVITY_SUMMARY.
+    const content = body
+        .replace(ABOUT_BLOCK, "")
+        .trim()
+        .replace(/^(?:<!-- codex-[a-z0-9-]+:[^\n]* -->\s*)+/, "");
     if (ACTIVITY_SUMMARY.test(content)) {
         return { autoResolve: true, suppress: true, reason: "Codex review-activity table" };
     }

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

@@ -1,7 +1,11 @@
 import { isBotItem } from "./author.mjs";
 const NOTICES = [
     /^Looks like this PR is already up-to-date with [^\s!]+! If you'd still like to recreate it from scratch, overwriting any edits, you can request `@dependabot recreate`\.$/,
-    /^Looks like these dependencies are updatable in another way, so this is no longer needed\.$/,
+    /^Looks like (?:these dependencies are|\S+ is) updatable in another way, so this is no longer needed\.$/,
+    /^Superseded by #\d+\.$/,
+    /^OK, I won't notify you again about this release, but will get in touch when a new version is available\. If you'd rather skip all updates until the next major or minor version, let me know by commenting `@dependabot ignore this major version` or `@dependabot ignore this minor version`\. You can also ignore all major, minor, or patch releases for a dependency by adding an \[`ignore` condition\]\(https:\/\/docs\.github\.com\/[^\s)]*\) with the desired `update_types` to your config file\.\n\nIf you change your mind, just re-open this PR and I'll resolve any conflicts on it\.$/,
+    /^This pull request was built based on a group rule\. Closing it will not ignore any of these versions in future pull requests\.\n\nTo ignore these dependencies, configure \[ignore rules\]\(https:\/\/docs\.github\.com\/[^\s)]*\) in dependabot\.yml$/,
+    /^Looks like this PR has been edited by someone other than Dependabot\. That means Dependabot can't rebase it - sorry!\n\nIf you're happy for Dependabot to recreate it from scratch, overwriting any edits, you can request `@dependabot recreate`\.$/,
 ];
 /** Dependabot's replies that report no change to make. */
 const rule = (item) => {

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

@@ -1,4 +1,4 @@
 import type { ClassifyRule } from "../types.mts";
-/** Complete Gemini Code Assist quota and review-limit notices. */
+/** Complete Gemini Code Assist quota, review-limit, and unsupported-file notices. */
 declare const rule: ClassifyRule;
 export default rule;

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

@@ -1,14 +1,25 @@
 import { isBotItem } from "./author.mjs";
-const NOTICES = [
+const QUOTA_NOTICES = [
     "You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!",
     "Review limit reached. I'll be able to review this pull request again tomorrow.",
 ];
-/** Complete Gemini Code Assist quota and review-limit notices. */
+const UNSUPPORTED_NOTICES = [
+    "Gemini is unable to generate a review for this pull request due to the file types involved not being currently supported.",
+    "Gemini is unable to generate a summary for this pull request due to the file types involved not being currently supported.",
+];
+/** A GitHub alert prefix such as `> [!WARNING]`, with the notice on the following quoted line. */
+const ALERT_PREFIX = /^> \[!(?:NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\n> /;
+/** Complete Gemini Code Assist quota, review-limit, and unsupported-file notices. */
 const rule = (item) => {
     if (!isBotItem(item, ["gemini-code-assist"], ["pr-comment"]))
         return null;
-    if (!NOTICES.includes(item.body.trim()))
-        return null;
-    return { autoResolve: true, suppress: true, reason: "Gemini quota or review-limit notice" };
+    const notice = item.body.trim().replace(ALERT_PREFIX, "");
+    if (QUOTA_NOTICES.includes(notice)) {
+        return { autoResolve: true, suppress: true, reason: "Gemini quota or review-limit notice" };
+    }
+    if (UNSUPPORTED_NOTICES.includes(notice)) {
+        return { autoResolve: true, suppress: true, reason: "Gemini unsupported-file-type notice" };
+    }
+    return null;
 };
 export default rule;

package/bin/classify/standard/kilo-no-issues.d.mts

@@ -1,4 +1,4 @@
 import type { ClassifyRule } from "../types.mts";
-/** Complete Kilo Code no-issues status or report with a file list and no extra prose. */
+/** Complete Kilo Code no-issues reports and its out-of-credits notice, with no extra findings. */
 declare const rule: ClassifyRule;
 export default rule;

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

@@ -1,20 +1,47 @@
 import { isBotItem } from "./author.mjs";
 const PLAIN_STATUS = /^Status: ✅ No Issues Found \| Recommendation: Merge$/;
 const REVIEW_REPORT = /^## Code Review Summary\n\n\*\*Status:\*\* No Issues Found \| \*\*Recommendation:\*\* Merge(?:\n\n### Files Reviewed \((\d+) files\)\n((?:- `[^`\n]+`(?:\n|$))+))?$/;
-/** Complete Kilo Code no-issues status or report with a file list and no extra prose. */
+/**
+ * The marked report: a no-issues status, an optional plain overview (see `isPlainOverview`), the
+ * collapsed file list, and `kilo-*` usage footers. Any other status, such as "N Issues Found",
+ * does not match, and Kilo rewrites this same comment when a later push finds issues. A stray
+ * `EOF` line, left by some models before the footer, is tolerated.
+ */
+const MARKED_REPORT = /^<!-- kilo-review -->\n\n?## Code Review Summary\n\n\*\*Status:\*\* No (?:New )?Issues Found \| \*\*Recommendation:\*\* Merge(?: \([^)\n]*\))?\n\n([\s\S]*?\n)?<details>\n<summary><b>Files Reviewed \([^)\n]*\)<\/b><\/summary>\n(?:(?!<details>)[\s\S])*?<\/details>\n+(?:EOF\n+)?---\n(?:<!-- kilo-[a-z-]+ -->\n<sub>[^\n]*<\/sub>(?:\n|$))+$/;
+const BILLING = /^<!-- kilo-billing-notice -->\n\*\*Kilo Code Review could not run — your account is out of credits\.\*\*\n\n\[Add credits\]\(https:\/\/app\.kilo\.ai\/[^\s)]*\) or \[switch to a free model\]\(https:\/\/app\.kilo\.ai\/[^\s)]*\) to enable reviews on this change\.$/;
+/**
+ * True when the overview is only prose and lists, optionally under `### Overview`. Any other
+ * heading, HTML block, or table could carry a finding, so it keeps the report visible.
+ */
+function isPlainOverview(overview) {
+    return (overview ?? "")
+        .split("\n")
+        .every((line) => line === "### Overview" || !/^\s*(?:#|<|\|)/.test(line));
+}
+/** True for the marked report when its overview is plain. */
+function isMarkedReport(body) {
+    const report = body.match(MARKED_REPORT);
+    return report != null && isPlainOverview(report[1]);
+}
+/** True for the unmarked report when its file count agrees with the listed files. */
+function isConsistentReport(body) {
+    const report = body.match(REVIEW_REPORT);
+    if (!report)
+        return false;
+    if (report[1] === undefined)
+        return true;
+    return report[2].trimEnd().split("\n").length === Number(report[1]);
+}
+/** Complete Kilo Code no-issues reports and its out-of-credits notice, with no extra findings. */
 const rule = (item) => {
     if (!isBotItem(item, ["kilo-code-bot"], ["pr-comment"]))
         return null;
     const body = item.body.trim();
-    if (!PLAIN_STATUS.test(body)) {
-        const report = body.match(REVIEW_REPORT);
-        if (!report)
-            return null;
-        if (report[1] !== undefined) {
-            const listed = report[2].trimEnd().split("\n").length;
-            if (listed !== Number(report[1]))
-                return null;
-        }
+    if (BILLING.test(body)) {
+        return { autoResolve: true, suppress: true, reason: "Kilo Code out-of-credits notice" };
+    }
+    if (!PLAIN_STATUS.test(body) && !isMarkedReport(body) && !isConsistentReport(body)) {
+        return null;
     }
     return { autoResolve: true, suppress: true, reason: "Kilo Code no-issues report" };
 };

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

@@ -1,5 +1,5 @@
 import { isBotItem } from "./author.mjs";
-const NO_ACCESS = /^Hi @[A-Za-z0-9-]+! 👋\n\nYour private repo does not have access to Sourcery\.\n\nPlease \[upgrade\]\(https:\/\/app\.sourcery\.ai\/login\?connection=github(?:&git_namespace_id=\d+)?&from_surface=github_bot&intent=private_repo_upsell\) to continue using Sourcery ✨$/;
+const NO_ACCESS = /^Hi @[A-Za-z0-9-]+! 👋\n\nYour private repo does not have access to Sourcery\.\n\nPlease \[upgrade\]\(https:\/\/app\.sourcery\.ai\/[^\s)]*\) to continue using Sourcery ✨$/;
 const RATE_LIMIT = /^Sorry @[A-Za-z0-9-]+, you have reached your weekly rate limit for Sourcery\. Please try again later\.$/;
 /** Complete Sourcery private-repo upsell and weekly rate-limit notices. */
 const rule = (item) => {

package/bin/cli/arg-flags.mjs

@@ -8,13 +8,11 @@ export const FLAGS_WITH_VALUES = new Set([
     "--ready-delay",
     "--stall-timeout",
     "--instructions",
-    "--poll-mode",
     "--require-sha",
     "--message",
     "--description",
     "--body-file",
     "--file",
-    "--stack",
     "--thread-id",
     "--resolve-thread-ids",
     "--reply-thread-ids",
@@ -35,7 +33,6 @@ export const FLAGS_WITH_VALUES = new Set([
 // 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",

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

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

package/bin/cli/clean-handler.mjs

@@ -2,10 +2,10 @@ 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;
+export async function handleClean(args) {
+    const command = "admin clean";
+    const usage = USAGE["admin clean"];
     const variant = args[0];
     if (!variant || !CLEAN_VARIANTS.has(variant)) {
         process.stderr.write(`${usage}\n`);
@@ -18,8 +18,6 @@ export async function handleClean(args, command = "admin clean") {
             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;
@@ -38,21 +36,14 @@ export async function handleClean(args, command = "admin clean") {
         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.
+    // Skip values consumed by --format <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`);
@@ -60,8 +51,7 @@ export async function handleClean(args, command = "admin clean") {
         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 }));
+    const result = await runClean({ variant: variant, value, dryRun });
     if (!result.ok) {
         process.stderr.write(`pr-shepherd: ${command}: ${result.error}\n`);
         process.exitCode = EXIT.SOFTWARE;

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

@@ -1,2 +1,4 @@
+export declare const DEFAULT_POLL_FLAGS_WITH_VALUES: Set<string>;
+export declare const DEFAULT_POLL_BOOLEAN_FLAGS: Set<string>;
 export declare function isDefaultPollInvocation(subcommand: string | undefined): boolean;
 export declare function validateDefaultPollArgs(args: string[]): boolean;

package/bin/cli/default-poll.mjs

@@ -2,22 +2,20 @@ import { EXIT } from "../exit-codes.mjs";
 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([
+import { isRemovedFlag, rejectRemovedFlags } from "./removed-flags.mjs";
+export const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
     "--transport",
     "--format",
     "--ready-delay",
     "--stall-timeout",
     "--instructions",
-    "--poll-mode",
     "--interval",
     "--timeout",
     "--debounce",
-    "--stack",
 ]);
-const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
+export const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--verbose",
     "--no-auto-mark-ready",
-    "--no-auto-cancel-actionable",
     "--quiet-status",
     "--no-quiet-status",
     "--until-terminal",
@@ -29,11 +27,16 @@ export function isDefaultPollInvocation(subcommand) {
     return (subcommand === undefined || parsePrNumber(subcommand) !== null || isDefaultPollFlag(subcommand));
 }
 export function validateDefaultPollArgs(args) {
+    if (rejectRemovedFlags(args))
+        return false;
     return validateDefaultArgs(args, DEFAULT_POLL_FLAGS_WITH_VALUES, DEFAULT_POLL_BOOLEAN_FLAGS, writeDefaultUsageError);
 }
 function isDefaultPollFlag(arg) {
     const name = arg.split("=", 1)[0];
-    return DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) || DEFAULT_POLL_BOOLEAN_FLAGS.has(arg);
+    // A removed flag routes here so its usage error names the replacement.
+    return (DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) ||
+        DEFAULT_POLL_BOOLEAN_FLAGS.has(arg) ||
+        isRemovedFlag(arg));
 }
 function writeDefaultUsageError(arg) {
     process.stderr.write(`Unknown subcommand: ${arg}\n`);

package/bin/cli/formatters.d.mts

@@ -3,6 +3,5 @@ export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mts";
 export { formatCleanResult } from "./clean-formatter.mts";
 export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mts";
 export { formatMutateResult } from "./mutate-formatter.mts";
-import type { BuildSuggestionPatchesResult, CommitSuggestionResult } from "../types.mts";
-export declare function formatSuggestionPatchesResult(result: BuildSuggestionPatchesResult): string;
-export declare function formatCommitSuggestionResult(result: CommitSuggestionResult): string;
+import type { SuggestResult } from "../types.mts";
+export declare function formatSuggestionPatchesResult(result: SuggestResult): string;

package/bin/cli/formatters.mjs

@@ -12,32 +12,6 @@ export function formatSuggestionPatchesResult(result) {
     appendInstructions(lines, result.postActionInstructions);
     return lines.join("\n");
 }
-export function formatCommitSuggestionResult(result) {
-    const lines = [];
-    const range = result.startLine === result.endLine
-        ? `line ${result.startLine}`
-        : `lines ${result.startLine}–${result.endLine}`;
-    lines.push(`Suggestion from @${result.author} for PR #${result.pr} — thread ${result.threadId}:`);
-    lines.push(`  repo: ${result.repo}`);
-    lines.push(`  ${result.path} (${range})`);
-    if (result.patch) {
-        const fence = safeFence(result.patch);
-        lines.push("");
-        lines.push(`${fence}diff`);
-        lines.push(result.patch.trimEnd());
-        lines.push(fence);
-    }
-    lines.push("", "## Suggested commit message", "", result.commitMessage, "", result.commitBody);
-    if (result.postActionInstructions.length > 0) {
-        lines.push("");
-        lines.push("## Instructions");
-        lines.push("");
-        result.postActionInstructions.forEach((inst, i) => {
-            lines.push(`${i + 1}. ${inst}`);
-        });
-    }
-    return lines.join("\n");
-}
 function formatPatch(patch, heading) {
     const range = patch.startLine === patch.endLine
         ? `line ${patch.startLine}`

package/bin/cli/handlers.d.mts

@@ -1,4 +1,4 @@
-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 handleSuggest(args: string[]): Promise<void>;
+/** `iterate [PR...]`: one tick for one PR, or one aggregate tick for several. */
 export declare function handleIterate(args: string[]): Promise<void>;
-export declare function handleMarkFilesAsViewed(args: string[], command?: "apply files" | "mark-files-as-viewed"): Promise<void>;
+export declare function handleMarkFilesAsViewed(args: string[]): Promise<void>;

package/bin/cli/handlers.mjs

@@ -1,47 +1,27 @@
-import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
 import { runSuggestionPatches } from "../commands/suggestion-patches.mjs";
 import { runMarkFilesAsViewed } from "../commands/mark-files-as-viewed.mjs";
-import { runIterateForMode } from "../commands/event-mode.mjs";
+import { runIterateTick, runPollSummaryTick } from "../commands/tick.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { EXIT } from "../exit-codes.mjs";
-import { parseCommonArgs, getFlag } from "./args.mjs";
+import { parseCommonArgs } from "./args.mjs";
+import { rejectUnknownFlags } from "./unknown-flags.mjs";
+import { rejectRemovedFlags } from "./removed-flags.mjs";
 import { USAGE } from "./help.mjs";
-import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
+import { formatSuggestionPatchesResult, formatMarkFilesAsViewedResult } from "./formatters.mjs";
 import { parseSuggestionPatchGroups } from "./suggestion-patch-flags.mjs";
 import { hasInvalidIterateFlags, parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
+import { emitPollSummaryResult } from "./poll-summary-emitter.mjs";
+import { parsePollTargets, resolvePollTargets } from "./poll-targets.mjs";
 import { parseMarkFilesAsViewedArgs } from "./mark-files-as-viewed-flags.mjs";
-export async function handleCommitSuggestion(args, command = "build-suggestion-patch") {
-    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
-    const threadId = getFlag(extra, "--thread-id");
-    if (!threadId) {
-        process.stderr.write(`${USAGE[command]}\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
-    const message = getFlag(extra, "--message") ?? undefined;
-    if (!message || message.trim() === "") {
-        process.stderr.write("--message is required and must be non-empty\n");
-        process.exitCode = EXIT.USAGE;
+const SUGGEST_FLAGS = ["--thread-id", "--message", "--description"];
+export async function handleSuggest(args) {
+    if (rejectUnknownFlags(args, "suggest", SUGGEST_FLAGS))
         return;
-    }
-    const description = getFlag(extra, "--description") ?? undefined;
-    const result = await runCommitSuggestion({
-        ...globalOpts,
-        prNumber,
-        threadId,
-        message,
-        description,
-    });
-    process.stdout.write(globalOpts.format === "json"
-        ? `${JSON.stringify(result, null, 2)}\n`
-        : `${formatCommitSuggestionResult(result)}\n`);
-}
-export async function handleSuggestionPatches(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const parsed = parseSuggestionPatchGroups(extra);
     if (!parsed.ok) {
-        process.stderr.write(`${parsed.error}\n${USAGE["build-suggestion-patches"]}\n`);
+        process.stderr.write(`${parsed.error}\n${USAGE.suggest}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -54,21 +34,50 @@ export async function handleSuggestionPatches(args) {
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatSuggestionPatchesResult(result)}\n`);
 }
+const ITERATE_FLAGS = [
+    "--ready-delay",
+    "--stall-timeout",
+    "--no-auto-mark-ready",
+    "--merge",
+    "--instructions",
+];
+/** `iterate [PR...]`: one tick for one PR, or one aggregate tick for several. */
 export async function handleIterate(args) {
+    if (rejectRemovedFlags(args) || rejectUnknownFlags(args, "iterate", ITERATE_FLAGS))
+        return;
+    const targets = parsePollTargets(args);
+    if (!targets)
+        return;
+    const resolved = targets.refs.length > 1 ? await resolvePollTargets(targets) : { prNumbers: [] };
+    // Duplicate references collapse to one PR, which takes the single-PR tick.
+    if (resolved.prNumbers.length > 1) {
+        const flags = parseIterateFlags(targets.extra, loadConfig());
+        if (hasInvalidIterateFlags(flags))
+            return;
+        const result = await runPollSummaryTick({
+            ...targets.global,
+            ...resolved,
+            readyDelaySeconds: flags.readyDelaySeconds,
+            stallTimeoutSeconds: flags.stallTimeoutSeconds,
+            noAutoMarkReady: flags.noAutoMarkReady,
+            merge: flags.merge,
+            instructions: flags.instructions ?? undefined,
+        });
+        emitPollSummaryResult(result, { format: targets.global.format });
+        return;
+    }
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const flags = parseIterateFlags(extra, loadConfig());
     if (hasInvalidIterateFlags(flags))
         return;
-    const result = await runIterateForMode({
+    const result = await runIterateTick({
         ...globalOpts,
         prNumber,
         readyDelaySeconds: flags.readyDelaySeconds,
         stallTimeoutSeconds: flags.stallTimeoutSeconds,
         noAutoMarkReady: flags.noAutoMarkReady,
-        noAutoCancelActionable: flags.noAutoCancelActionable,
         merge: flags.merge,
         instructions: flags.instructions ?? undefined,
-        pollMode: flags.pollMode ?? undefined,
     });
     emitIterateResult(result, {
         format: globalOpts.format,
@@ -76,7 +85,8 @@ export async function handleIterate(args) {
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
     });
 }
-export async function handleMarkFilesAsViewed(args, command = "apply files") {
+export async function handleMarkFilesAsViewed(args) {
+    const command = "apply files";
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const parsed = parseMarkFilesAsViewedArgs(extra);
     if (!parsed.ok) {