pr-shepherd 0.34.0 → 0.36.0

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,13 +1,16 @@
 import { execFile as execFileCb } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
-import { fetchPrBatch } from "../github/batch.mjs";
+import { fetchSuggestionThread } from "../github/suggestion-thread.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 ShepherdError("--thread-id is required", EXIT.USAGE);
@@ -21,9 +24,11 @@ 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);
+    const data = await fetchSuggestionThread(prNumber, repo, opts.threadId);
     if (!data.headRepoWithOwner) {
         throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
     }
@@ -35,7 +40,7 @@ export async function runCommitSuggestion(opts) {
         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);
+    const thread = data.thread;
     if (!thread) {
         throw new ShepherdError(`Thread ${opts.threadId} not found on PR #${prNumber}.`, EXIT.UNAVAILABLE);
     }
@@ -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,13 @@ 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 cwd = getEffectiveCwd();
+    const resolvedPath = resolve(cwd, filePath);
+    const rel = relative(cwd, resolvedPath);
+    if (rel.startsWith("..") || rel === "") {
+        throw new ShepherdError(`Thread ${opts.threadId} path escapes the working tree.`, EXIT.UNAVAILABLE);
+    }
+    const originalContent = await readFile(resolvedPath, "utf8");
     const patch = buildUnifiedDiff({
         path: filePath,
         originalContent,
@@ -94,7 +100,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/fix-code.mjs

@@ -166,7 +166,7 @@ export async function handleFixCode(ctx) {
         cancelled,
     };
     const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
-    if (result.action === "fix_code") {
+    if (result.action === "fix_code" && opts.persistSeen !== false) {
         await Promise.allSettled(result.fix.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
     }
     return result;

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

@@ -0,0 +1,14 @@
+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;
+export declare function blockedCancelNote(base: IterateResultBase): string;

package/bin/commands/iterate/helpers.mjs

@@ -1,6 +1,8 @@
 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";
+import { blockedReasonFromRequirements } from "../../merge-status/requirements-format.mjs";
 const execFile = promisify(execFileCb);
 export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mjs";
 export function buildSummary(report) {
@@ -39,6 +41,7 @@ export function buildTerminalCancelResult(report) {
         summary: buildSummary(report),
         baseBranch: report.baseBranch,
         branchProtection: report.branchProtection,
+        mergeRequirements: report.mergeStatus.mergeRequirements,
         checks: buildRelevantChecks(report),
         inProgressChecks: buildActiveChecks(report),
         ...buildSuppressedCheckFields(report),
@@ -114,7 +117,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 {
@@ -131,14 +136,15 @@ export function buildWaitLog(base) {
             .join(", ")}`);
     }
     switch (base.mergeStatus) {
-        case "BLOCKED":
-            if (base.reviewDecision === "REVIEW_REQUIRED")
-                parts.push("awaiting human review");
-            else if (base.reviewDecision === "APPROVED")
-                parts.push("awaiting additional approvals");
-            else
+        case "BLOCKED": {
+            const fromRules = blockedReasonFromRequirements(base.mergeRequirements);
+            if (fromRules)
+                parts.push(fromRules);
+            else if (!base.blockingBotReviewInProgress) {
                 parts.push("awaiting human review or branch protection");
+            }
             break;
+        }
         case "BEHIND":
             parts.push("branch is behind base");
             break;
@@ -154,3 +160,9 @@ export function buildWaitLog(base) {
     }
     return parts.join(" — ");
 }
+export function blockedCancelNote(base) {
+    if (base.mergeStatus !== "BLOCKED")
+        return "has been ready for review";
+    const fromRules = blockedReasonFromRequirements(base.mergeRequirements);
+    return fromRules ? `is ${fromRules}` : "is awaiting human review or branch protection resolution";
+}

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

@@ -5,7 +5,7 @@ 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 { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
@@ -25,7 +25,10 @@ export async function runIterate(opts) {
     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("/");
@@ -48,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);
@@ -87,6 +90,7 @@ export async function runIterate(opts) {
         summary: buildSummary(report),
         baseBranch: report.baseBranch,
         branchProtection: report.branchProtection,
+        mergeRequirements: report.mergeStatus.mergeRequirements,
         checks: buildRelevantChecks(report),
         inProgressChecks: buildActiveChecks(report),
         ...buildSuppressedCheckFields(report),
@@ -94,15 +98,7 @@ export async function runIterate(opts) {
     };
     if (readyState.shouldCancel) {
         await clearStallState(stallKey);
-        let cancelNote;
-        if (base.mergeStatus !== "BLOCKED")
-            cancelNote = "has been ready for review";
-        else if (base.reviewDecision === "REVIEW_REQUIRED")
-            cancelNote = "is awaiting human review";
-        else if (base.reviewDecision === "APPROVED")
-            cancelNote = "is awaiting additional approvals";
-        else
-            cancelNote = "is awaiting human review or branch protection resolution";
+        const cancelNote = blockedCancelNote(base);
         return {
             ...base,
             action: "cancel",

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) {

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

@@ -0,0 +1,22 @@
+export interface AppendResult {
+    body: string;
+    mutated: boolean;
+    sectionExisted: boolean;
+}
+type ValidationOk = {
+    ok: true;
+    item: string;
+};
+type ValidationError = {
+    ok: false;
+    error: string;
+};
+export type ValidationResult = ValidationOk | ValidationError;
+/** Validates that the input is a properly formed markdown list item. */
+export declare function validateJournalItem(input: string): ValidationResult;
+/**
+ * Appends a validated list item to the ## Shepherd Journal section of a PR body.
+ * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
+ */
+export declare function appendJournalItem(body: string, item: string): AppendResult;
+export {};

package/bin/commands/log-file.d.mts

@@ -0,0 +1,5 @@
+interface LogFileResult {
+    path: string;
+}
+export declare function runLogFile(): Promise<LogFileResult>;
+export {};