pr-shepherd 0.33.0 → 0.35.0

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

@@ -19,11 +19,13 @@ import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers
 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());
     if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const config = loadConfig();
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
@@ -49,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,78 +1,79 @@
 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";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 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 Error("--thread-id is required");
+        throw new ShepherdError("--thread-id is required", EXIT.USAGE);
     }
     if (!opts.message || opts.message.trim() === "") {
-        throw new Error("--message is required and must be non-empty");
+        throw new ShepherdError("--message is required and must be non-empty", EXIT.USAGE);
     }
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+        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) {
-        throw new Error(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`);
+        throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
     }
     if (currentBranch !== data.headRefName) {
-        throw new Error(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
-            `Check out "${data.headRefName}" before applying suggestions.`);
+        throw new ShepherdError(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
+            `Check out "${data.headRefName}" before applying suggestions.`, EXIT.UNAVAILABLE);
     }
     if (localHeadSha !== data.headRefOid) {
-        throw new Error(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
-            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`);
+        throw new ShepherdError(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
+            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`, EXIT.UNAVAILABLE);
     }
     const thread = data.reviewThreads.find((t) => t.id === opts.threadId);
     if (!thread) {
-        throw new Error(`Thread ${opts.threadId} not found on PR #${prNumber}.`);
+        throw new ShepherdError(`Thread ${opts.threadId} not found on PR #${prNumber}.`, EXIT.UNAVAILABLE);
     }
     if (thread.isResolved) {
-        throw new Error(`Thread ${opts.threadId} is already resolved.`);
+        throw new ShepherdError(`Thread ${opts.threadId} is already resolved.`, EXIT.UNAVAILABLE);
     }
     if (thread.isOutdated) {
-        throw new Error(`Thread ${opts.threadId} is outdated.`);
+        throw new ShepherdError(`Thread ${opts.threadId} is outdated.`, EXIT.UNAVAILABLE);
     }
     if (thread.isMinimized) {
-        throw new Error(`Thread ${opts.threadId} is minimized.`);
+        throw new ShepherdError(`Thread ${opts.threadId} is minimized.`, EXIT.UNAVAILABLE);
     }
     if (!thread.path || thread.line === null) {
-        throw new Error(`Thread ${opts.threadId} has no file/line anchor.`);
+        throw new ShepherdError(`Thread ${opts.threadId} has no file/line anchor.`, EXIT.UNAVAILABLE);
     }
     // 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 Error(`${thread.path} has uncommitted changes. Commit or stash them before running commit-suggestion.`);
+        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) {
-        throw new Error(`Thread ${opts.threadId} has no suggestion block in the comment body.`);
+        throw new ShepherdError(`Thread ${opts.threadId} has no suggestion block in the comment body.`, EXIT.UNAVAILABLE);
     }
     if (!isCommittableSuggestion(parsed)) {
-        throw new Error(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
-            `3+ backtick fences — refusing to apply (could silently truncate).`);
+        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
+            `3+ backtick fences — refusing to apply (could silently truncate).`, EXIT.UNAVAILABLE);
     }
     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,
@@ -93,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;

package/bin/commands/iterate/helpers.mjs

@@ -1,6 +1,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
+import { getExecutionCwd } from "../../execution-context.mjs";
 const execFile = promisify(execFileCb);
 export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mjs";
 export function buildSummary(report) {
@@ -114,7 +115,9 @@ export async function tryCancelRun(runId, owner, repo) {
 }
 export async function getCurrentHeadSha() {
     try {
-        const { stdout } = await execFile("git", ["rev-parse", "HEAD"]);
+        const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {
+            cwd: getExecutionCwd(),
+        });
         return stdout.trim();
     }
     catch {

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

@@ -0,0 +1,2 @@
+import type { IterateCommandOptions, IterateResult } from "../../types.mts";
+export declare function runIterate(opts: IterateCommandOptions): Promise<IterateResult>;

package/bin/commands/iterate/index.mjs

@@ -4,6 +4,7 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
+import { EXIT, ShepherdError } from "../../exit-codes.mjs";
 import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
@@ -17,18 +18,22 @@ export async function runIterate(opts) {
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
     const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null)
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    if (prNumber === null) {
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
+    }
     const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
     const report = await runCheck({
         ...opts,
         prNumber,
-        autoResolve: config.actions.autoResolveOutdated,
+        // Outdated Shepherd-visible threads are always resolved by iterate. The
+        // old actions.autoResolveOutdated switch is retained only as an ignored
+        // compatibility key in the config loader.
+        autoResolve: true,
         autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
     });
     const [repoOwner, repoName] = report.repo.split("/");
     if (!repoOwner || !repoName) {
-        throw new Error(`Unexpected repo format: "${report.repo}" (expected "owner/name")`);
+        throw new ShepherdError(`Unexpected repo format: "${report.repo}" (expected "owner/name")`, EXIT.DATAERR);
     }
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
     if (report.mergeStatus.state !== "OPEN") {
@@ -46,7 +51,7 @@ export async function runIterate(opts) {
     // GitHub can still return a null/error/rate-limit result per ID without
     // throwing (autoMinimizeComments reports this via `errors`, not a rejection);
     // any ID it did not confirm minimized falls back into the agent-facing set so
-    // the resolve command remains a working fallback instead of silently dropping it.
+    // the apply command remains a working fallback instead of silently dropping it.
     let reviewSummaryIds = minimizeIds;
     if (selfMinimizeIds.length > 0) {
         const { minimized } = await autoMinimizeComments(selfMinimizeIds);

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

@@ -0,0 +1,5 @@
+import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, FirstLookThread, FirstLookComment, ReviewThread } from "../../types.mts";
+/** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
+export declare function renderResolveCommand(rc: ResolveCommand): string;
+export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prNumber: number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+isBehind?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -32,14 +32,16 @@ isBehind = false) {
         if (changesRequestedReviews.length > 0)
             actionableSections.push("`## Changes-requested reviews`");
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
-        const resolveClause = resolveCommand.hasMutations ? ", then run the `resolve:` command" : "";
+        const resolveClause = resolveCommand.hasMutations
+            ? ", then run the `apply review:` command"
+            : "";
         if (hasConflicts) {
             // Conflicts make push mandatory regardless of whether code edits are needed.
             instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Apply any code edits for items ${sectionRef}, then commit and push${resolveClause}.`);
         }
         else {
             const skipClause = resolveCommand.hasMutations
-                ? "skip the commit/push and run the `resolve:` command"
+                ? "skip the commit/push and run the `apply review:` command"
                 : "no push is needed";
             instructions.push(`Decide for each item ${sectionRef} whether a code change is warranted. **If any code changes are needed:** apply edits, commit, push${resolveClause}. **If no code changes are needed:** ${skipClause}.`);
         }
@@ -59,12 +61,12 @@ isBehind = false) {
         // is only accurate when threads are present.
         const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
         const suggestionFallback = hasSuggestions
-            ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`commit-suggestion\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
+            ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`build-suggestion-patch\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
             : "";
         instructions.push(`Apply code fixes: read and edit ${filesRef}.${suggestionFallback}`);
     }
     if (resolutionOnlyThreads.length > 0) {
-        instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`resolve:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
+        instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`apply review:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
     }
     instructions.push(...buildFailingCheckInstructions(checks));
     if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
@@ -74,7 +76,7 @@ isBehind = false) {
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.${staleClause}`);
         if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
-            instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`resolve:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);
+            instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`apply review:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);
@@ -84,7 +86,7 @@ isBehind = false) {
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, its ID is already included in the \`resolve:\` command; otherwise do not pass first-look-only IDs to mutation flags.`);
+        instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, its ID is already included in the \`apply review:\` command; otherwise do not pass first-look-only IDs to mutation flags.`);
     }
     if (firstLookSummaries.length > 0)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);

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

@@ -0,0 +1,20 @@
+import type { ShepherdReport } from "../../types.mts";
+import type { ProtectedRun } from "../../types/protected-run.mts";
+type FailingCheck = ShepherdReport["checks"]["failing"][number];
+type InProgressCheck = ShepherdReport["checks"]["inProgress"][number];
+type CancellableCheck = FailingCheck | InProgressCheck;
+interface RunProtection {
+    protectedRunIds: Set<string>;
+    protectedRuns: ProtectedRun[];
+}
+interface BuildRunIdOptions {
+    protectedRunIds?: Set<string>;
+}
+export declare function buildAutoCancelRunIdsWithOptions(report: ShepherdReport, opts?: BuildRunIdOptions): string[];
+interface BuildInProgressRunIdOptions {
+    suppressProtectedFreshReruns?: boolean;
+    protectedRunIds?: Set<string>;
+}
+export declare function buildInProgressRunIds(report: ShepherdReport, cancelledSet: Set<string>, opts?: BuildInProgressRunIdOptions): string[];
+export declare function buildRunProtection(checks: CancellableCheck[], patterns?: string[]): RunProtection;
+export {};

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

@@ -0,0 +1,6 @@
+import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+export declare function applyStallGuard(stallKey: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, stallTimeoutSeconds: number, headSha: string, base: IterateResultBase, prNumber: number, prospectiveResult: IterateResult, report: ShepherdReport, reviewSummaryIds: string[]): Promise<IterateResult>;

package/bin/commands/journal/index.d.mts

@@ -0,0 +1,14 @@
+export interface RunJournalOptions {
+    prNumber: number | undefined;
+    rawItem: string;
+    dryRun: boolean;
+}
+export interface JournalResult {
+    prNumber: number;
+    mutated: boolean;
+    sectionExisted: boolean;
+    dryRun: boolean;
+    previewBody?: string;
+}
+/** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */
+export declare function runJournal(opts: RunJournalOptions): Promise<JournalResult>;

package/bin/commands/journal/index.mjs

@@ -1,5 +1,6 @@
 import { getRepoInfo, getPullRequestBody, updatePullRequestBody, getCurrentPrNumber, } from "../../github/client.mjs";
 import { validateJournalItem, appendJournalItem } from "./transform.mjs";
+/** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */
 export async function runJournal(opts) {
     const validation = validateJournalItem(opts.rawItem);
     if (!validation.ok) {