pr-shepherd 0.34.0 → 0.35.0

package/bin/cli/poll-handler.mjs

@@ -14,12 +14,12 @@ export async function handlePoll(args) {
     if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const intervalStr = getFlag(extra, "--interval");
-    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));
+    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd", "--interval", intervalStr, hasFlag(extra, "--interval"));
     if (intervalSuffix === null)
         return;
     const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", DEFAULT_POLL_INTERVAL_SECONDS);
     const timeoutStr = getFlag(extra, "--timeout");
-    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
+    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
     if (timeoutSuffix === null)
         return;
     const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", DEFAULT_POLL_TIMEOUT_SECONDS);

package/bin/cli/resolve-validators.d.mts

@@ -0,0 +1,3 @@
+export declare function rejectPrrcMinimizeIds(ids: string[]): string[];
+export declare function warnPrrcThreadIds(ids: string[]): string[];
+export declare function validateRequireSha(sha: string | undefined): boolean;

package/bin/cli/resolve-validators.mjs

@@ -2,7 +2,7 @@ import { EXIT } from "../exit-codes.mjs";
 export function rejectPrrcMinimizeIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
+        process.stderr.write(`pr-shepherd: apply review: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
         process.exitCode = EXIT.DATAERR;
     }
     return prrcIds;
@@ -10,7 +10,7 @@ export function rejectPrrcMinimizeIds(ids) {
 export function warnPrrcThreadIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
+        process.stderr.write(`pr-shepherd: apply review: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
     }
     return prrcIds;
 }
@@ -19,7 +19,7 @@ export function validateRequireSha(sha) {
         return true;
     if (/^[0-9a-f]{40}$/.test(sha))
         return true;
-    process.stderr.write(`pr-shepherd: resolve: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
+    process.stderr.write(`pr-shepherd: apply review: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
     process.exitCode = EXIT.DATAERR;
     return false;
 }

package/bin/cli/runner.d.mts

@@ -0,0 +1,7 @@
+interface PrShepherdCommand {
+    argv: string[];
+    text: string;
+}
+export declare function buildPrShepherdCommand(args: string[]): PrShepherdCommand;
+export declare function renderShellCommand(argv: string[]): string;
+export {};

package/bin/cli/suggestion-renderer.d.mts

@@ -0,0 +1,3 @@
+import type { SuggestionBlock } from "../types.mts";
+export declare function renderLineRange(startLine: number | undefined, endLine: number | null): string;
+export declare function renderSuggestionBlock(s: SuggestionBlock, indent?: string): string;

package/bin/cli/validate-default-args.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Validate args for default-dispatch paths (e.g. `pr-shepherd [PR] [flags]`).
+ * Returns false when an unexpected token is found; calls onError with the
+ * offending arg so callers can print their own usage message.
+ */
+export declare function validateDefaultArgs(args: string[], flagsWithValues: ReadonlySet<string>, booleanFlags: ReadonlySet<string>, onError: (arg: string) => void): boolean;

package/bin/cli-parser.d.mts

@@ -0,0 +1,2 @@
+/** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
+export declare function main(argv: string[]): Promise<void>;

package/bin/cli-parser.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
 import { EXIT, errorToExitCode } from "./exit-codes.mjs";
@@ -5,7 +6,7 @@ import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
-import { USAGE, maybePrintHelp } from "./cli/help.mjs";
+import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
@@ -31,19 +32,33 @@ export async function main(argv) {
         await handleLogFile(args.slice(1));
         return;
     }
+    // The public command groups keep admin diagnostics out of the normal
+    // 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");
+        return;
+    }
     // Short-circuit all --help/-h before any I/O or logging.
     if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
         if (isDefaultPollInvocation(subcommand)) {
-            process.stdout.write(`${USAGE.poll}\n`);
+            process.stdout.write(`${USAGE.default}\n`);
         }
         else {
-            const key = subcommand != null && subcommand in USAGE
-                ? subcommand
-                : "top";
-            process.stdout.write(`${USAGE[key]}\n`);
+            process.stdout.write(`${USAGE[helpKeyForArgs(args)]}\n`);
         }
         return;
     }
+    const legacyReplacement = {
+        poll: "pr-shepherd [PR] (the default PR polling command)",
+        resolve: "apply review",
+        "mark-files-as-viewed": "apply files",
+        journal: "apply journal",
+        "commit-suggestion": "build-suggestion-patch",
+    };
+    if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
+        warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
+    }
     // Initialize the per-worktree log and install a stdout tee.
     await setupLog(argv);
     if (isDefaultPollInvocation(subcommand)) {
@@ -53,14 +68,23 @@ export async function main(argv) {
         return;
     }
     switch (subcommand) {
+        case "apply":
+            await handleApply(args.slice(1));
+            break;
+        case "build-suggestion-patch":
+            await handleCommitSuggestion(args.slice(1));
+            break;
+        case "admin":
+            await handleAdmin(args.slice(1));
+            break;
         case "resolve":
-            await handleResolve(args.slice(1));
+            await handleResolve(args.slice(1), "resolve");
             break;
         case "commit-suggestion":
-            await handleCommitSuggestion(args.slice(1));
+            await handleCommitSuggestion(args.slice(1), "commit-suggestion");
             break;
         case "mark-files-as-viewed":
-            await handleMarkFilesAsViewed(args.slice(1));
+            await handleMarkFilesAsViewed(args.slice(1), "mark-files-as-viewed");
             break;
         case "iterate":
             await handleIterate(args.slice(1));
@@ -69,10 +93,10 @@ export async function main(argv) {
             await handlePoll(args.slice(1));
             break;
         case "clean":
-            await handleClean(args.slice(1));
+            await handleClean(args.slice(1), "clean");
             break;
         case "journal":
-            await handleJournal(args.slice(1));
+            await handleJournal(args.slice(1), "journal");
             break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
@@ -81,6 +105,38 @@ export async function main(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) {
+        case "review":
+            await handleResolve(args.slice(1));
+            return;
+        case "files":
+            await handleMarkFilesAsViewed(args.slice(1));
+            return;
+        case "journal":
+            await handleJournal(args.slice(1));
+            return;
+        default:
+            process.stderr.write(`Unknown apply action: ${action ?? "(none)"}\n`);
+            process.stderr.write(`${USAGE.apply}\n`);
+            process.exitCode = EXIT.USAGE;
+    }
+}
+async function handleAdmin(args) {
+    switch (args[0]) {
+        case "clean":
+            await handleClean(args.slice(1));
+            return;
+        default:
+            process.stderr.write(`Unknown admin command: ${args[0] ?? "(none)"}\n`);
+            process.stderr.write(`${USAGE.admin}\n`);
+            process.exitCode = EXIT.USAGE;
+    }
+}
 function readVersion() {
     const pkgUrl = new URL("../package.json", import.meta.url);
     const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
@@ -89,8 +145,8 @@ function readVersion() {
 // ---------------------------------------------------------------------------
 // Subcommand handlers
 // ---------------------------------------------------------------------------
-async function handleLogFile(args) {
-    if (maybePrintHelp(args, "log-file"))
+async function handleLogFile(args, usageKey = "log-file") {
+    if (maybePrintHelp(args, usageKey))
         return;
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {
@@ -106,7 +162,7 @@ async function handleLogFile(args) {
         process.exitCode = errorToExitCode(e);
     }
 }
-async function handleResolve(args) {
+async function handleResolve(args, command = "apply review") {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
     const replyThreadIds = parseList(getFlag(extra, "--reply-thread-ids"));
@@ -120,7 +176,7 @@ async function handleResolve(args) {
     if (rejectPrrcMinimizeIds(minimizeCommentIds).length > 0)
         return;
     if (hasFlag(extra, "--fetch")) {
-        process.stderr.write("pr-shepherd: resolve: --fetch has been removed; run pr-shepherd iterate or poll to fetch the next action.\n");
+        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;
     }
@@ -129,7 +185,7 @@ async function handleResolve(args) {
         minimizeCommentIds.length > 0 ||
         dismissReviewIds.length > 0;
     if (!hasAction) {
-        process.stderr.write("pr-shepherd: resolve: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n");
+        process.stderr.write(`pr-shepherd: ${command}: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }

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

@@ -0,0 +1,5 @@
+import type { CheckAnnotation, TriagedCheck } from "../types.mts";
+export declare function attachUnseenCheckAnnotations(checks: TriagedCheck[], seenMap: Map<string, {
+    seenAt: number;
+}>, prNumber: number): Promise<TriagedCheck[]>;
+export declare function annotationMarkerBody(a: CheckAnnotation): string;

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

@@ -0,0 +1,3 @@
+import type { MergeStatusResult, ShepherdStatus } from "../types.mts";
+import type { CiVerdict } from "../checks/classify.mts";
+export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number): ShepherdStatus;

package/bin/commands/check-terminal-report.d.mts

@@ -0,0 +1,5 @@
+import type { BatchPrData, MergeStatusResult, ShepherdReport } from "../types.mts";
+export declare function buildTerminalReport(prNumber: number, repo: {
+    owner: string;
+    name: string;
+}, batchData: BatchPrData, mergeStatus: MergeStatusResult, status: "MERGED" | "CLOSED"): ShepherdReport;

package/bin/commands/check.d.mts

@@ -0,0 +1,6 @@
+import type { GlobalOptions, ShepherdReport } from "../types.mts";
+export declare function runCheck(opts: GlobalOptions & {
+    autoResolve?: boolean;
+    autoMinimizeSuppressed?: boolean;
+    skipTriage?: boolean;
+}): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -20,6 +20,7 @@ import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { getEffectiveCwd } from "../execution-context.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -50,7 +51,7 @@ export async function runCheck(opts) {
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const seenMap = await loadSeenMap(stateKey);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const ruleSet = await loadRules(discoverRuleFiles(process.cwd()));
+    const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
     const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);

package/bin/commands/clean.d.mts

@@ -0,0 +1,21 @@
+export type CleanVariant = "pr" | "branch" | "current" | "repo" | "all";
+interface CleanOptions {
+    variant: CleanVariant;
+    /** PR number string (for "pr") or branch name (for "branch"). Defaults to current. */
+    value?: string;
+    dryRun?: boolean;
+}
+export interface CleanResult {
+    ok: boolean;
+    variant: CleanVariant;
+    dryRun: boolean;
+    base: string;
+    target: string;
+    /** Paths removed (actual delete) or that would be removed (dry-run). */
+    deleted: string[];
+    /** Target path when it did not exist. */
+    skipped: string[];
+    error?: string;
+}
+export declare function runClean(opts: CleanOptions): Promise<CleanResult>;
+export {};

package/bin/commands/commit-suggestion-instruction.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Build the `build-suggestion-patch` instruction step for agent consumers.
+ * Currently emitted by iterate `fix_code` for suggestion review threads.
+ * @param sectionName - The markdown section heading where suggestion threads appear,
+ *   e.g. `"## Review threads"`.
+ * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
+ */
+export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string, includeDriftHint: boolean): string;

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,6 +1,6 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
- * Build the `commit-suggestion` instruction step for agent consumers.
+ * Build the `build-suggestion-patch` instruction step for agent consumers.
  * Currently emitted by iterate `fix_code` for suggestion review threads.
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
@@ -8,7 +8,7 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  */
 export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint) {
     const command = buildPrShepherdCommand([
-        "commit-suggestion",
+        "build-suggestion-patch",
         String(prNumber),
         "--thread-id",
         "<id>",
@@ -19,5 +19,5 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
     const driftHint = includeDriftHint
         ? " If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step."
         : " If the patch fails to apply, fall through to the manual-edit step.";
-    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`: run \`${command}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Human-authored thread IDs are replied to by the resolve command below; Shepherd does not auto-resolve them.${driftHint} Do not retry the same command.`;
+    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`: run \`${command}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Human-authored thread IDs are replied to by the apply command below; Shepherd does not auto-resolve them.${driftHint} Do not retry the same command.`;
 }

package/bin/commands/commit-suggestion.d.mts

@@ -0,0 +1,8 @@
+import type { CommitSuggestionResult, GlobalOptions } from "../types.mts";
+export interface CommitSuggestionOptions extends GlobalOptions {
+    threadId: string;
+    message: string;
+    description?: string;
+}
+/** @deprecated Hidden implementation for `commit-suggestion`; use `build-suggestion-patch`. */
+export declare function runCommitSuggestion(opts: CommitSuggestionOptions): Promise<CommitSuggestionResult>;

package/bin/commands/commit-suggestion.mjs

@@ -1,5 +1,6 @@
 import { execFile as execFileCb } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import { promisify } from "node:util";
 import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
@@ -7,7 +8,9 @@ import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.m
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { getEffectiveCwd, getExecutionCwd } from "../execution-context.mjs";
 const execFile = promisify(execFileCb);
+/** @deprecated Hidden implementation for `commit-suggestion`; use `build-suggestion-patch`. */
 export async function runCommitSuggestion(opts) {
     if (!opts.threadId) {
         throw new ShepherdError("--thread-id is required", EXIT.USAGE);
@@ -21,7 +24,9 @@ export async function runCommitSuggestion(opts) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const currentBranch = await getCurrentBranch();
-    const { stdout: localHeadOut } = await execFile("git", ["rev-parse", "HEAD"]);
+    const { stdout: localHeadOut } = await execFile("git", ["rev-parse", "HEAD"], {
+        cwd: getExecutionCwd(),
+    });
     const localHeadSha = localHeadOut.trim();
     const { data } = await fetchPrBatch(prNumber, repo);
     if (!data.headRepoWithOwner) {
@@ -53,14 +58,9 @@ export async function runCommitSuggestion(opts) {
     }
     // Validate the target file is clean before generating the patch, so the emitted
     // `git add -- <file>` instruction cannot accidentally stage unrelated local edits.
-    const { stdout: fileStatus } = await execFile("git", [
-        "status",
-        "--porcelain",
-        "--",
-        thread.path,
-    ]);
+    const { stdout: fileStatus } = await execFile("git", ["status", "--porcelain", "--", thread.path], { cwd: getExecutionCwd() });
     if (fileStatus.trim() !== "") {
-        throw new ShepherdError(`${thread.path} has uncommitted changes. Commit or stash them before running commit-suggestion.`, EXIT.UNAVAILABLE);
+        throw new ShepherdError(`${thread.path} has uncommitted changes. Commit or stash them before running build-suggestion-patch.`, EXIT.UNAVAILABLE);
     }
     const parsed = parseSuggestion(thread.body);
     if (!parsed) {
@@ -73,7 +73,7 @@ export async function runCommitSuggestion(opts) {
     const startLine = thread.startLine ?? thread.line;
     const endLine = thread.line;
     const filePath = thread.path;
-    const originalContent = await readFile(filePath, "utf8");
+    const originalContent = await readFile(resolve(getEffectiveCwd(), filePath), "utf8");
     const patch = buildUnifiedDiff({
         path: filePath,
         originalContent,
@@ -94,7 +94,8 @@ export async function runCommitSuggestion(opts) {
         ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
     ].join(" ");
     const resolveCommand = buildPrShepherdCommand([
-        "resolve",
+        "apply",
+        "review",
         String(prNumber),
         "--resolve-thread-ids",
         opts.threadId,

package/bin/commands/iterate/check-instructions.d.mts

@@ -0,0 +1,16 @@
+import type { AgentCheck, ResolveCommand, Review } from "../../types.mts";
+/** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
+export declare function buildCrStaleClause(reviews: Review[]): string;
+/**
+ * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
+ * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in CLAUDE.md); this
+ * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
+ * point of use (rather than at config load) so a malformed rc file value (non-string, or
+ * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or
+ * discarding the rest of the user's config.
+ */
+export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, isBehind: boolean): string[];
+/** Build the `Run the apply review: command` instruction, including its optional substitution hint. */
+export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
+export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];

package/bin/commands/iterate/check-instructions.mjs

@@ -23,13 +23,13 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
         return [];
     return [`The branch is behind \`origin/${baseBranch}\` — ${trimmedHint} before pushing.`];
 }
-/** Build the `Run the resolve: command` instruction, including its optional substitution hint. */
+/** Build the `Run the apply review: command` instruction, including its optional substitution hint. */
 export function buildResolveCommandInstruction(resolveCommand) {
     if (!resolveCommand.hasMutations)
         return [];
     const instructions = [];
     if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-        instructions.push(`Before running the \`resolve:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
+        instructions.push(`Before running the \`apply review:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
     }
     const substituteParts = [];
     if (resolveCommand.requiresHeadSha) {
@@ -39,7 +39,7 @@ export function buildResolveCommandInstruction(resolveCommand) {
         substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence reply/description of what you changed`);
     }
     const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
-    instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
+    instructions.push(`Run the \`apply review:\` command shown above${substituteHint}.`);
     return instructions;
 }
 export function buildFailingCheckInstructions(checks) {

package/bin/commands/iterate/classify.d.mts

@@ -0,0 +1,18 @@
+import type { AgentThread, Review, ResolveCommand, AgentCheck, ReviewThread } from "../../types.mts";
+import { type NormalizedBotUsernames } from "../../comments/authors.mts";
+import type { MinimizeCommentsPolicy } from "../../config/load.mts";
+export declare function classifyReviewSummaries(summaries: {
+    firstLook: Review[];
+    seen: Review[];
+    edited: Review[];
+}, approvals: Review[], minimizeApprovals: boolean, minimizeComments?: MinimizeCommentsPolicy | undefined, botUsernames?: NormalizedBotUsernames, unresolvedThreads?: ReviewThread[], ruleAutoResolveIds?: string[]): {
+    minimizeIds: string[];
+    selfMinimizeIds: string[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    surfacedApprovals: Review[];
+};
+export declare function buildResolveCommand(threads: AgentThread[], resolutionOnlyThreads: ReviewThread[], allCommentIds: string[], reviews: Review[], checks: AgentCheck[], prNumber: number, botUsernames?: NormalizedBotUsernames, ruleAutoResolveThreadIds?: string[]): {
+    resolveCommand: ResolveCommand;
+    resolveOnlyCommand?: ResolveCommand;
+};

package/bin/commands/iterate/classify.mjs

@@ -17,7 +17,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     const eligible = (r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames) &&
         !blockedReviewIds.has(r.id);
     // First-look summaries still need one tick to surface their body to the agent,
-    // so their minimize IDs ride in the agent-facing resolve command. Seen summaries
+    // so their minimize IDs ride in the agent-facing apply command. Seen summaries
     // (already surfaced in a prior tick) have no new content to show — the CLI
     // self-minimizes them in-process (selfMinimizeIds) instead of routing a
     // cosmetic-only mutation through fix_code (issue #313). Edited summaries are
@@ -80,7 +80,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     if (hasMessageMutations && hasResolveOrMinimize) {
         // Split: message-bearing mutations (replies + dismissals) ride in resolveArgv;
         // resolve/minimize mutations go in resolveOnlyArgv so they can run without SHA or message.
-        const resolveArgv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
+        const resolveArgv = buildPrShepherdCommand(["apply", "review", String(prNumber)]).argv;
         if (replyThreadIds.length > 0) {
             resolveArgv.push("--reply-thread-ids", replyThreadIds.join(","));
         }
@@ -99,7 +99,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
             ...(hasDismiss ? { dismissReviewIds } : undefined),
             hasMutations: true,
         };
-        const resolveOnlyArgv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
+        const resolveOnlyArgv = buildPrShepherdCommand(["apply", "review", String(prNumber)]).argv;
         if (resolveThreadIds.length > 0) {
             resolveOnlyArgv.push("--resolve-thread-ids", resolveThreadIds.join(","));
         }
@@ -116,7 +116,7 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
         return { resolveCommand, resolveOnlyCommand };
     }
     // Single command: all mutations combined (or only one category present).
-    const argv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
+    const argv = buildPrShepherdCommand(["apply", "review", String(prNumber)]).argv;
     if (replyThreadIds.length > 0) {
         argv.push("--reply-thread-ids", replyThreadIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");

package/bin/commands/iterate/escalate.d.mts

@@ -0,0 +1,31 @@
+import type { EscalateDetails, EscalateTrigger, ReviewThread } from "../../types.mts";
+interface EscalateCheck {
+    triggers: EscalateTrigger[];
+    thrashHistory?: EscalateDetails["thrashHistory"];
+}
+export declare function checkEscalateTriggers(actionableThreads: ReviewThread[], threadAttempts: Record<string, number>): EscalateCheck;
+interface BaseBranchLookup {
+    branch: string;
+    /** True when we could not confirm the branch name from GitHub. Callers must
+     * escalate rather than emitting a rebase against a potentially-wrong base. */
+    isFallback: boolean;
+    /** Populated when `isFallback`; one-line reason shown in escalate output. */
+    failureReason?: string;
+}
+/**
+ * Validate the base branch name from the GraphQL batch (`report.baseBranch`)
+ * and fall back safely if it's missing/unsafe. The branch is interpolated into
+ * shell commands by `buildFixInstructions`, so we reject anything outside
+ * `[A-Za-z0-9._/-]` to prevent shell injection.
+ */
+/**
+ * Render a seconds count as an approximate human duration: "8 seconds" below one minute,
+ * otherwise whole minutes ("166 minutes", "60 minutes") — matching the precision the
+ * generic stall timer has always reported, just adding a seconds tier for sub-minute ages
+ * instead of always flooring to "0 minutes".
+ */
+export declare function formatDurationApprox(seconds: number): string;
+export declare function validateBaseBranch(raw: string): BaseBranchLookup;
+export declare function buildEscalateHumanMessage(escalate: Omit<EscalateDetails, "humanMessage">, pr: number): string;
+export declare function buildEscalateSuggestion(triggers: EscalateTrigger[], detail?: string): string;
+export {};

package/bin/commands/iterate/escalate.mjs

@@ -1,4 +1,7 @@
 import { loadConfig } from "../../config/load.mjs";
+function renderEscalateAuthor(item) {
+    return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
+}
 export function checkEscalateTriggers(actionableThreads, threadAttempts) {
     const triggers = [];
     const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
@@ -85,21 +88,21 @@ export function buildEscalateHumanMessage(escalate, pr) {
             lines.push("");
         for (const t of escalate.unresolvedThreads) {
             const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
-            lines.push(`- thread \`${t.id}\` — ${loc} (@${t.author}):`);
+            lines.push(`- thread \`${t.id}\` — ${loc} (${renderEscalateAuthor(t)}):`);
             lines.push("");
             for (const bodyLine of t.body.split("\n"))
                 lines.push(`  > ${bodyLine}`);
             lines.push("");
         }
         for (const r of escalate.changesRequestedReviews) {
-            lines.push(`- review \`${r.id}\` (@${r.author}):`);
+            lines.push(`- review \`${r.id}\` (${renderEscalateAuthor(r)}):`);
             lines.push("");
             for (const bodyLine of r.body.split("\n"))
                 lines.push(`  > ${bodyLine}`);
             lines.push("");
         }
         for (const c of escalate.ambiguousComments) {
-            lines.push(`- comment \`${c.id}\` (@${c.author}):`);
+            lines.push(`- comment \`${c.id}\` (${renderEscalateAuthor(c)}):`);
             lines.push("");
             for (const bodyLine of c.body.split("\n"))
                 lines.push(`  > ${bodyLine}`);
@@ -137,7 +140,7 @@ export function buildEscalateSuggestion(triggers, detail) {
     }
     if (triggers.includes("bot-cr-not-dismissed")) {
         const ids = detail ? ` (review IDs: ${detail})` : "";
-        return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior resolve command. Dismiss the review(s) manually (or re-run resolve with the IDs) to unblock the PR.`;
+        return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior apply command. Dismiss the review(s) manually (or re-run \`pr-shepherd apply review\` with the IDs) to unblock the PR.`;
     }
     return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

package/bin/commands/iterate/fix-code.d.mts

@@ -0,0 +1,25 @@
+import type { IterateCommandOptions, IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
+import type { NormalizedBotUsernames } from "../../comments/authors.mts";
+interface HandleFixCodeContext {
+    base: IterateResultBase;
+    report: ShepherdReport;
+    opts: IterateCommandOptions;
+    headSha: string;
+    stallKey: {
+        owner: string;
+        repo: string;
+        pr: number;
+    };
+    prNumber: number;
+    stallTimeoutSeconds: number;
+    repoOwner: string;
+    repoName: string;
+    reviewSummaryIds: string[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    surfacedApprovals: Review[];
+    botUsernames: NormalizedBotUsernames;
+    ruleAutoResolveThreadIds?: string[];
+}
+export declare function handleFixCode(ctx: HandleFixCodeContext): Promise<IterateResult>;
+export {};

package/bin/commands/iterate/helpers.d.mts

@@ -0,0 +1,13 @@
+import type { ActiveCheck, IterateResult, IterateResultBase, IterateResultSummary, RelevantCheck, ShepherdReport } from "../../types.mts";
+export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mts";
+export declare function buildSummary(report: ShepherdReport): IterateResultSummary;
+/** Non-blocking check-name lists (ignored/superseded), omitted from the result when empty. */
+export declare function buildSuppressedCheckFields(report: ShepherdReport): Pick<IterateResultBase, "ignoredNames" | "supersededNames">;
+/** Build the `cancel` result for a merged/closed PR — caller has already updated ready-delay/stall state. */
+export declare function buildTerminalCancelResult(report: ShepherdReport): IterateResult;
+/** Build completed, non-skipped checks relevant to PR readiness. */
+export declare function buildRelevantChecks(report: ShepherdReport): RelevantCheck[];
+export declare function buildActiveChecks(report: ShepherdReport): ActiveCheck[];
+export declare function tryCancelRun(runId: string, owner: string, repo: string): Promise<string | null>;
+export declare function getCurrentHeadSha(): Promise<string | null>;
+export declare function buildWaitLog(base: IterateResultBase): string;