pr-shepherd 0.56.5 → 0.57.0

package/bin/classify/standard/codecov-report.mjs

@@ -0,0 +1,10 @@
+import { isBotItem } from "./author.mjs";
+/** Codecov's coverage report comment. Coverage gates still report through their status checks. */
+const rule = (item) => {
+    if (!isBotItem(item, ["codecov"], ["pr-comment"]))
+        return null;
+    if (!/^#{1,6}\s*\[?Codecov\b/i.test(item.body.trimStart()))
+        return null;
+    return { autoResolve: true, suppress: true, reason: "Codecov coverage report" };
+};
+export default rule;

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

@@ -0,0 +1,8 @@
+import type { ClassifyRule } from "../types.mts";
+/**
+ * CodeRabbit progress, rate-limit, review-skipped and draft notices, plus its "Action not
+ * completed" command replies. The summarize comment is later edited in place into the PR
+ * walkthrough, so the rule only hides it from agent output and never minimizes it.
+ */
+declare const rule: ClassifyRule;
+export default rule;

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

@@ -0,0 +1,38 @@
+import { isBotItem } from "./author.mjs";
+const NOTICE_ENVELOPE = /^<!-- This is an auto-generated comment: (rate limited|skip review|review in progress) by coderabbit.ai -->\n([\s\S]*?)\n<!-- end of auto-generated comment: \1 by coderabbit.ai -->$/;
+const COMMAND_REPLY = /^<!-- This is an auto-generated reply by CodeRabbit -->\n<!-- CodeRabbit review command invocation: v2:[a-f0-9]+ -->\n<details>\n<summary>⚠️ Action not completed<\/summary>\n\n(?:Review rate limited\.|Review skipped: \d+ files exceed the limit of \d+\.)\n\n(?:> Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits\. This command is applicable only when automatic reviews are paused\.|---\n\nYour included review limit is currently reached under our \[Fair Usage Limits Policy\]\(https:\/\/docs.coderabbit.ai\/management\/plans#fair-usage-limits-policy\)\. This review may still proceed through usage-based billing if eligible\. Your next included review will be available in \d+ minutes?\.)\n\n<\/details>$/;
+/** Strips CodeRabbit's footer and header blocks so only the notice envelope remains. */
+function stripChrome(body) {
+    return body
+        .trim()
+        .replace(/\n<!-- tips_start -->[\s\S]*?<!-- tips_end -->$/, "")
+        .trim()
+        .replace(/\n<!-- autopilot:start -->[\s\S]*?<!-- autopilot:end -->$/, "")
+        .trim()
+        .replace(/^<!-- This is an auto-generated comment: summarize by coderabbit.ai -->\s*/, "")
+        .replace(/^<!-- review_stack_entry_start -->[\s\S]*?<!-- review_stack_entry_end -->\s*/, "");
+}
+function isQuotedNotice(quoted) {
+    const onlyQuotedLines = quoted.split("\n").every((line) => !line.trim() || line.startsWith(">"));
+    if (!onlyQuotedLines)
+        return false;
+    return (quoted.includes("> ## Review limit reached\n") ||
+        quoted.includes("> ## Draft PR not reviewed\n") ||
+        quoted.includes("> ## Review skipped\n") ||
+        quoted.includes("> Currently processing new changes in this PR. This may take a few minutes, please wait..."));
+}
+/**
+ * CodeRabbit progress, rate-limit, review-skipped and draft notices, plus its "Action not
+ * completed" command replies. The summarize comment is later edited in place into the PR
+ * walkthrough, so the rule only hides it from agent output and never minimizes it.
+ */
+const rule = (item) => {
+    if (!isBotItem(item, ["coderabbitai"], ["pr-comment"]))
+        return null;
+    const body = stripChrome(item.body);
+    const quoted = body.match(NOTICE_ENVELOPE)?.[2]?.trim();
+    if (!(quoted && isQuotedNotice(quoted)) && !COMMAND_REPLY.test(body))
+        return null;
+    return { suppress: true, reason: "CodeRabbit progress, review-limit, or skipped-review notice" };
+};
+export default rule;

package/bin/classify/standard/coderabbit-review-summary.d.mts

@@ -0,0 +1,8 @@
+import type { ClassifyRule } from "../types.mts";
+/**
+ * CodeRabbit review summaries that only count and re-prompt their inline threads. The threads
+ * carry the findings, so the summary adds nothing. Any outside-diff, nitpick, duplicate or
+ * other body-only section keeps the summary visible.
+ */
+declare const rule: ClassifyRule;
+export default rule;

package/bin/classify/standard/coderabbit-review-summary.mjs

@@ -0,0 +1,37 @@
+import { isBotItem } from "./author.mjs";
+const HEADING = /^\*\*Actionable comments posted: \d+\*\*\n/;
+const PROMPT_BLOCK = /\n<details>\n<summary>🤖 Prompt to fix review comments<\/summary>\n\n```\n([\s\S]*?)\n```\n\n<\/details>\n/;
+const REVIEW_INFO_BLOCK = /\n<details>\n<summary>ℹ️ Review info<\/summary>\n[\s\S]*<\/details>\n/;
+const AUTOFIX_BLOCK = /\n<!-- autofix_checkbox_start -->[\s\S]*?<!-- autofix_checkbox_end -->\n/;
+/** Sections that carry findings only in the summary body, never in an inline thread. */
+const BODY_ONLY_FINDINGS = /\[!CAUTION\]|Outside diff range comments|Nitpick comments|Duplicate comments|Additional comments|Outside diff comments:/;
+/**
+ * CodeRabbit review summaries that only count and re-prompt their inline threads. The threads
+ * carry the findings, so the summary adds nothing. Any outside-diff, nitpick, duplicate or
+ * other body-only section keeps the summary visible.
+ */
+const rule = (item) => {
+    if (!isBotItem(item, ["coderabbitai"], ["review-summary"]))
+        return null;
+    const body = `${item.body.trim()}\n`;
+    if (!HEADING.test(body) || BODY_ONLY_FINDINGS.test(body))
+        return null;
+    const prompt = body.match(PROMPT_BLOCK)?.[1];
+    if (prompt !== undefined && !prompt.includes("\nInline comments:\n"))
+        return null;
+    const rest = body
+        .replace(HEADING, "\n")
+        .replace(AUTOFIX_BLOCK, "\n")
+        .replace(PROMPT_BLOCK, "\n")
+        .replace(REVIEW_INFO_BLOCK, "\n")
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/^---$/gm, "");
+    if (rest.trim() !== "")
+        return null;
+    return {
+        autoResolve: true,
+        suppress: true,
+        reason: "CodeRabbit review summary that only repeats its inline threads",
+    };
+};
+export default rule;

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

@@ -0,0 +1,7 @@
+import type { ClassifyRule } from "../types.mts";
+/**
+ * Codex quota notices, the review-activity status table, and no-findings notices. Each pattern
+ * matches the whole comment, so a notice with any appended finding stays visible.
+ */
+declare const rule: ClassifyRule;
+export default rule;

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

@@ -0,0 +1,36 @@
+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\)\.$/,
+    /^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-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\._$/;
+/**
+ * Codex quota notices, the review-activity status table, and no-findings notices. Each pattern
+ * matches the whole comment, so a notice with any appended finding stays visible.
+ */
+const rule = (item) => {
+    if (!isBotItem(item, ["chatgpt-codex-connector"], ["pr-comment", "review-summary"])) {
+        return null;
+    }
+    const body = item.body.trim();
+    if (QUOTA_NOTICES.some((notice) => notice.test(body))) {
+        return { autoResolve: true, suppress: true, reason: "Codex usage-limit notice" };
+    }
+    if (item.kind !== "pr-comment")
+        return null;
+    // Strip only the trailing About block; extra findings after it stay visible.
+    const content = body.replace(ABOUT_BLOCK, "").trim();
+    if (ACTIVITY_SUMMARY.test(content)) {
+        return { autoResolve: true, suppress: true, reason: "Codex review-activity table" };
+    }
+    if (CLEAN_REVIEW.test(content) || CLEAN_SECURITY.test(content)) {
+        return { autoResolve: true, suppress: true, reason: "Codex no-findings notice" };
+    }
+    return null;
+};
+export default rule;

package/bin/classify/standard/codex-review-summary.d.mts

@@ -0,0 +1,7 @@
+import type { ClassifyRule } from "../types.mts";
+/**
+ * The Codex review summary that only introduces its inline threads. A summary that carries a
+ * finding in its own body (for example, a permalink to a line outside the diff) stays visible.
+ */
+declare const rule: ClassifyRule;
+export default rule;

package/bin/classify/standard/codex-review-summary.mjs

@@ -0,0 +1,20 @@
+import { isBotItem } from "./author.mjs";
+const ABOUT_BLOCK = /\n\n<details> <summary>ℹ️ About Codex in GitHub<\/summary>[\s\S]*?<\/details>$/;
+const ENVELOPE = /^### 💡 Codex Review\n\nHere are some automated review suggestions for this pull request\.\n\n\*\*Reviewed commit:\*\* `[a-f0-9]+`$/;
+/**
+ * The Codex review summary that only introduces its inline threads. A summary that carries a
+ * finding in its own body (for example, a permalink to a line outside the diff) stays visible.
+ */
+const rule = (item) => {
+    if (!isBotItem(item, ["chatgpt-codex-connector"], ["review-summary"]))
+        return null;
+    const content = item.body.trim().replace(ABOUT_BLOCK, "").trim();
+    if (!ENVELOPE.test(content))
+        return null;
+    return {
+        autoResolve: true,
+        suppress: true,
+        reason: "Codex review summary that only introduces its inline threads",
+    };
+};
+export default rule;

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

@@ -0,0 +1,4 @@
+import type { ClassifyRule } from "../types.mts";
+/** Dependabot's replies that report no change to make. */
+declare const rule: ClassifyRule;
+export default rule;

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

@@ -0,0 +1,15 @@
+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\.$/,
+];
+/** Dependabot's replies that report no change to make. */
+const rule = (item) => {
+    if (!isBotItem(item, ["dependabot"], ["pr-comment"]))
+        return null;
+    const body = item.body.trim();
+    if (!NOTICES.some((notice) => notice.test(body)))
+        return null;
+    return { autoResolve: true, suppress: true, reason: "Dependabot no-op reply" };
+};
+export default rule;

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

@@ -0,0 +1,4 @@
+import type { ClassifyRule } from "../types.mts";
+/** Gemini Code Assist daily-quota and review-limit notices. A heading means a real review. */
+declare const rule: ClassifyRule;
+export default rule;

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

@@ -0,0 +1,13 @@
+import { isBotItem } from "./author.mjs";
+/** Gemini Code Assist daily-quota and review-limit notices. A heading means a real review. */
+const rule = (item) => {
+    if (!isBotItem(item, ["gemini-code-assist"], ["pr-comment", "review-summary"]))
+        return null;
+    if (/^#{1,6}\s/m.test(item.body))
+        return null;
+    if (!/You have reached your daily quota limit|Review limit reached/i.test(item.body)) {
+        return null;
+    }
+    return { autoResolve: true, suppress: true, reason: "Gemini quota or review-limit notice" };
+};
+export default rule;

package/bin/classify/standard/index.d.mts

@@ -0,0 +1,4 @@
+import type { ClassifyRule } from "../types.mts";
+/** Bundled classification rules that `classify.standard` can enable by name. */
+export declare const STANDARD_RULES: Readonly<Record<string, ClassifyRule>>;
+export declare const STANDARD_RULE_NAMES: readonly string[];

package/bin/classify/standard/index.mjs

@@ -0,0 +1,22 @@
+import coderabbitNotices from "./coderabbit-notices.mjs";
+import coderabbitReviewSummary from "./coderabbit-review-summary.mjs";
+import codecovReport from "./codecov-report.mjs";
+import codexNotices from "./codex-notices.mjs";
+import codexReviewSummary from "./codex-review-summary.mjs";
+import dependabotNotices from "./dependabot-notices.mjs";
+import geminiNotices from "./gemini-notices.mjs";
+import kiloNoIssues from "./kilo-no-issues.mjs";
+import sourceryNotices from "./sourcery-notices.mjs";
+/** Bundled classification rules that `classify.standard` can enable by name. */
+export const STANDARD_RULES = {
+    "coderabbit-notices": coderabbitNotices,
+    "coderabbit-review-summary": coderabbitReviewSummary,
+    "codecov-report": codecovReport,
+    "codex-notices": codexNotices,
+    "codex-review-summary": codexReviewSummary,
+    "dependabot-notices": dependabotNotices,
+    "gemini-notices": geminiNotices,
+    "kilo-no-issues": kiloNoIssues,
+    "sourcery-notices": sourceryNotices,
+};
+export const STANDARD_RULE_NAMES = Object.keys(STANDARD_RULES);

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

@@ -0,0 +1,4 @@
+import type { ClassifyRule } from "../types.mts";
+/** Kilo Code's report whose status line reads "No Issues Found" and that carries no findings. */
+declare const rule: ClassifyRule;
+export default rule;

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's report whose status line reads "No Issues Found" and that carries no findings. */
+const rule = (item) => {
+    if (!isBotItem(item, ["kilo-code-bot"], ["pr-comment", "review-summary"]))
+        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. A real Sourcery 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. A real Sourcery 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", "review-summary"]))
+        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",