pr-shepherd 0.16.4 → 0.18.0

package/bin/commands/iterate/classify.mjs

@@ -1,5 +1,16 @@
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
+function dedupeIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all") {
     // First-look and seen summaries go into the minimize mutation; edited summaries do NOT —
     // they are already minimized server-side (body changed after minimize was applied).
@@ -28,26 +39,43 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
 }
 export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber, runner) {
     const argv = buildPrShepherdCommand(["resolve", String(prNumber)], { runner }).argv;
-    const threadIds = [...threads.map((t) => t.id), ...resolutionOnlyThreads.map((t) => t.id)];
+    const resolveThreadIds = dedupeIds(threads.map((t) => t.id));
+    const threadIds = dedupeIds([...resolveThreadIds, ...resolutionOnlyThreads.map((t) => t.id)]);
     if (threadIds.length > 0) {
         argv.push("--resolve-thread-ids", threadIds.join(","));
     }
     if (allCommentIds.length > 0) {
         argv.push("--minimize-comment-ids", allCommentIds.join(","));
     }
-    const hasDismiss = reviews.length > 0;
+    const commentIdSet = new Set(allCommentIds);
+    const filteredReviewIds = [];
+    const droppedDismissReviewIds = [];
+    for (const review of reviews) {
+        if (commentIdSet.has(review.id))
+            droppedDismissReviewIds.push(review.id);
+        else
+            filteredReviewIds.push(review.id);
+    }
+    const hasDismiss = filteredReviewIds.length > 0;
     if (hasDismiss) {
-        argv.push("--dismiss-review-ids", reviews.map((r) => r.id).join(","));
+        argv.push("--dismiss-review-ids", filteredReviewIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");
     }
-    // A push is required when threads, CI failures, or changes-requested reviews are present — the
-    // CLI knows those imply code edits. Comments are surfaced for the agent to evaluate; the CLI
-    // cannot know whether a given comment will require a push, so comments are excluded here.
-    const requiresHeadSha = threads.length > 0 || checks.length > 0 || reviews.length > 0;
     // hasMutations = we appended at least one of --resolve-thread-ids,
     // --minimize-comment-ids, or --dismiss-review-ids. Returned explicitly
     // (rather than derived from argv.length) so callers don't couple to the
     // base-argv shape.
-    const hasMutations = threadIds.length > 0 || allCommentIds.length > 0 || reviews.length > 0;
-    return { argv, requiresHeadSha, requiresDismissMessage: hasDismiss, hasMutations };
+    const hasMutations = threadIds.length > 0 || allCommentIds.length > 0 || filteredReviewIds.length > 0;
+    // `requiresHeadSha` is only added when this resolve command includes a
+    // mutation that can race with a moving HEAD: resolving actionable threads,
+    // dismissing CHANGES_REQUESTED reviews, or addressing failing checks.
+    const hasCodeMutations = hasMutations && (threads.length > 0 || checks.length > 0 || filteredReviewIds.length > 0);
+    const requiresHeadSha = hasCodeMutations;
+    return {
+        argv,
+        requiresHeadSha,
+        requiresDismissMessage: hasDismiss,
+        ...(droppedDismissReviewIds.length > 0 ? { droppedDismissReviewIds } : undefined),
+        hasMutations,
+    };
 }

package/bin/commands/iterate/escalate.mjs

@@ -1,5 +1,5 @@
 import { loadConfig } from "../../config/load.mjs";
-export function checkEscalateTriggers(actionableThreads, resolutionOnlyThreads, actionableComments, changesRequestedReviews, failingChecks, threadAttempts, hasConflicts) {
+export function checkEscalateTriggers(actionableThreads, threadAttempts) {
     const triggers = [];
     const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
     // Trigger 1: fix thrash — same thread dispatched too many times without resolving.
@@ -7,17 +7,7 @@ export function checkEscalateTriggers(actionableThreads, resolutionOnlyThreads,
     if (thrashThreads.length > 0) {
         triggers.push("fix-thrash");
     }
-    // Trigger 2: PR-level CHANGES_REQUESTED with no inline threads/comments/CI to act on.
-    // Skip when there are merge conflicts — fix_code handles conflict resolution, not escalation.
-    if (changesRequestedReviews.length > 0 &&
-        actionableThreads.length === 0 &&
-        resolutionOnlyThreads.length === 0 &&
-        actionableComments.length === 0 &&
-        failingChecks.length === 0 &&
-        !hasConflicts) {
-        triggers.push("pr-level-changes-requested");
-    }
-    // Trigger 3: actionable thread has no file/line — cannot locate code to edit.
+    // Trigger 2: actionable thread has no file/line — cannot locate code to edit.
     const unlocatable = actionableThreads.filter((t) => t.path === null || t.line === null);
     if (unlocatable.length > 0) {
         triggers.push("thread-missing-location");
@@ -55,7 +45,7 @@ export function validateBaseBranch(raw) {
 }
 export function buildEscalateHumanMessage(escalate, pr) {
     const lines = [];
-    lines.push("⚠️ /pr-shepherd:pr-shepherd paused — needs human direction");
+    lines.push("⚠️ /pr-shepherd:pr-shepherd paused — manual intervention required");
     lines.push("");
     lines.push(`**Triggers:** ${escalate.triggers.map((t) => `\`${t}\``).join(", ")}`);
     lines.push("");
@@ -66,23 +56,34 @@ export function buildEscalateHumanMessage(escalate, pr) {
     if (hasItems) {
         lines.push("");
         lines.push("## Items needing attention");
+        lines.push("");
         for (const t of escalate.unresolvedThreads) {
             const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
-            const firstLine = t.body.split("\n")[0] ?? "";
-            lines.push(`- thread \`${t.id}\` — ${loc} (@${t.author}): ${firstLine}`);
+            lines.push(`- thread \`${t.id}\` — ${loc} (@${t.author}):`);
+            lines.push("");
+            for (const bodyLine of t.body.split("\n"))
+                lines.push(`  > ${bodyLine}`);
+            lines.push("");
         }
         for (const r of escalate.changesRequestedReviews) {
-            const firstLine = r.body.split("\n")[0] ?? "";
-            lines.push(`- review \`${r.id}\` (@${r.author}): ${firstLine}`);
+            lines.push(`- review \`${r.id}\` (@${r.author}):`);
+            lines.push("");
+            for (const bodyLine of r.body.split("\n"))
+                lines.push(`  > ${bodyLine}`);
+            lines.push("");
         }
         for (const c of escalate.ambiguousComments) {
-            const firstLine = c.body.split("\n")[0] ?? "";
-            lines.push(`- comment \`${c.id}\` (@${c.author}): ${firstLine}`);
+            lines.push(`- comment \`${c.id}\` (@${c.author}):`);
+            lines.push("");
+            for (const bodyLine of c.body.split("\n"))
+                lines.push(`  > ${bodyLine}`);
+            lines.push("");
         }
     }
     if (escalate.thrashHistory && escalate.thrashHistory.length > 0) {
         lines.push("");
         lines.push("## Fix attempts");
+        lines.push("");
         for (const a of escalate.thrashHistory) {
             lines.push(`- thread \`${a.threadId}\` attempted ${a.attempts} times`);
         }
@@ -90,26 +91,23 @@ export function buildEscalateHumanMessage(escalate, pr) {
     lines.push("");
     lines.push("---");
     lines.push("");
-    lines.push(`After fixing manually, rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
+    lines.push(`After completing manual fixes (and pushing if required), rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("stall-timeout")) {
         const mins = detail ?? "30";
-        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. Inspect the PR and resume manually once the blocking issue is resolved.`;
+        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
     if (triggers.includes("base-branch-unknown")) {
         const reason = detail ? ` (${detail})` : "";
-        return `Could not determine the PR's base branch${reason} — refusing to emit a rebase that could force-push onto the wrong base. Run the rebase manually against the PR's real target branch.`;
+        return `Could not determine the PR's base branch${reason} — automated rebases are paused because branch safety is unclear. Run the rebase manually against the PR's real target branch.`;
     }
     if (triggers.includes("fix-thrash")) {
-        return "Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:pr-shepherd";
-    }
-    if (triggers.includes("pr-level-changes-requested")) {
-        return "Reviewer requested changes but left no inline comments — read the review and act manually";
+        return "Same thread(s) reached the automated attempt limit — treat this as a manual handoff. Apply the fix by hand.";
     }
     if (triggers.includes("thread-missing-location")) {
-        return "Review thread has no file/line reference — cannot locate code to edit automatically";
+        return "Review thread has no file/line reference — automated location routing failed and manual handling is required.";
     }
-    return "Ambiguous state — inspect the PR and act manually";
+    return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

package/bin/commands/iterate/fix-code.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts } from "../../state/fix-attempts.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
@@ -16,7 +17,7 @@ export async function handleFixCode(ctx) {
             currentAttempts[t.id] = (currentAttempts[t.id] ?? 0) + 1;
         }
     }
-    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.threads.resolutionOnly, report.comments.actionable, report.changesRequestedReviews, failingChecks, currentAttempts, report.mergeStatus.status === "CONFLICTS");
+    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, currentAttempts);
     if (escalateTriggers.triggers.length > 0) {
         const escalateBase = {
             triggers: escalateTriggers.triggers,
@@ -52,14 +53,35 @@ export async function handleFixCode(ctx) {
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
-    const hasGuaranteedSupersedingPush = threads.length > 0 || checks.length > 0 || changesRequestedReviews.length > 0 || hasConflicts;
-    const inProgressRunIds = hasGuaranteedSupersedingPush
-        ? buildInProgressRunIds(report, cancelledSet)
-        : [];
+    // Only surface in-progress runs when a push is plausible — resolution-only and
+    // summary-only iterations have no path to a push, so listing runs would prompt
+    // unnecessary cancellation.
+    const pushLikely = threads.length > 0 ||
+        checks.length > 0 ||
+        hasConflicts ||
+        changesRequestedReviews.length > 0 ||
+        actionableComments.length > 0;
+    const inProgressRunIds = pushLikely ? buildInProgressRunIds(report, cancelledSet) : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, cliRunner);
-    if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
+    const overlappingReviewIds = resolveCommand.droppedDismissReviewIds ?? [];
+    if (overlappingReviewIds.length > 0) {
+        process.stderr.write(`pr-shepherd: resolve command overlap: ${overlappingReviewIds.length} ` +
+            `review IDs were also in minimize/comment IDs and were dropped from --dismiss-review-ids: ` +
+            `${overlappingReviewIds.join(", ")}\n`);
+    }
+    // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
+    // would need the correct base to rebase safely. This is a conservative guard, not a
+    // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
+    // resolution-only threads also need a known base in case the agent does push.
+    const pushIsPlausible = threads.length > 0 ||
+        checks.length > 0 ||
+        hasConflicts ||
+        changesRequestedReviews.length > 0 ||
+        actionableComments.length > 0 ||
+        resolutionOnlyThreads.length > 0;
+    if (baseLookup.isFallback && pushIsPlausible) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
             unresolvedThreads: [...threads, ...resolutionOnlyThreads.map(toAgentThread)],

package/bin/commands/iterate/index.mjs

@@ -45,6 +45,7 @@ export async function runIterate(opts) {
             state: report.mergeStatus.state,
             summary: buildSummary(report),
             baseBranch: report.baseBranch,
+            branchProtection: report.branchProtection,
             checks: buildRelevantChecks(report),
             action: "cancel",
             reason: report.mergeStatus.state === "MERGED" ? "merged" : "closed",
@@ -84,6 +85,7 @@ export async function runIterate(opts) {
         remainingSeconds: readyState.remainingSeconds,
         summary: buildSummary(report),
         baseBranch: report.baseBranch,
+        branchProtection: report.branchProtection,
         checks: buildRelevantChecks(report),
     };
     if (readyState.shouldCancel) {

package/bin/commands/iterate/render.mjs

@@ -2,12 +2,11 @@ import { renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
-export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
-export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
+export const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
 /**
  * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE`, `$HEAD_SHA`, and
- * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is appended separately
- * when `requiresHeadSha` is set.
+ * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is never in `argv` —
+ * `renderResolveCommand` appends `--require-sha "$HEAD_SHA"` when `requiresHeadSha` is set.
  */
 export function renderResolveCommand(rc) {
     const parts = [...rc.argv];
@@ -16,10 +15,41 @@ export function renderResolveCommand(rc) {
     }
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
     const instructions = [];
+    const hasNonConflictHints = threads.length > 0 ||
+        checks.length > 0 ||
+        changesRequestedReviews.length > 0 ||
+        actionableComments.length > 0;
+    // Leading decision or mandatory instruction depending on what actionable items exist.
+    if (hasNonConflictHints) {
+        const actionableSections = [];
+        if (threads.length > 0)
+            actionableSections.push("`## Review threads`");
+        if (actionableComments.length > 0)
+            actionableSections.push("`## Actionable comments`");
+        if (checks.length > 0)
+            actionableSections.push("`## Failing checks`");
+        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" : "";
+        if (hasConflicts) {
+            // Conflicts make push mandatory regardless of whether code edits are needed.
+            instructions.push(`The branch has merge conflicts that require rebase before merging. Apply any code edits for items ${sectionRef}, commit if edits were made, rebase onto \`origin/${baseBranch}\` per your repository's conventions, push${resolveClause}.`);
+        }
+        else {
+            const skipClause = resolveCommand.hasMutations
+                ? "skip cancellation/commit/push and run the `resolve:` command"
+                : "no push is needed";
+            instructions.push(`Decide for each item ${sectionRef} whether a code change is warranted. **If any code changes are needed:** cancel in-progress runs first, apply edits, commit, rebase, push${resolveClause}. **If no code changes are needed:** ${skipClause}.`);
+        }
+    }
+    else if (hasConflicts) {
+        instructions.push(`The branch has merge conflicts — rebase onto \`origin/${baseBranch}\` per your repository's conventions to resolve them, then push.`);
+    }
     if (inProgressRunIds.length > 0) {
-        instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\` before applying code fixes. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
+        instructions.push(`If you decide to push new commits: cancel each in-progress run listed under \`## In-progress runs\` before applying code fixes (e.g. \`gh run cancel <id>\`). Runs may complete between the tick and your action; treat cancellation errors on already-finished runs as non-fatal. Skip this step if you are only resolving threads without pushing — the existing runs remain relevant.`);
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
@@ -35,25 +65,25 @@ export function buildFixInstructions(threads, actionableComments, checks, review
         instructions.push(`Resolve the threads under \`## Review threads to resolve\` with the \`resolve:\` command shown below. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
     }
     instructions.push(...buildFailingCheckInstructions(checks));
-    if (reviews.length > 0) {
+    if (changesRequestedReviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }
-    const hasCodeChanges = threads.length > 0 || checks.length > 0 || reviews.length > 0;
-    const needsPush = hasCodeChanges || hasConflicts;
-    if (hasCodeChanges) {
-        instructions.push(`Commit changed files: \`git add <files> && git commit -m "<descriptive message>"\``);
-        instructions.push(`Keep the PR title and description current: if the changes alter the PR's scope or intent, run \`gh pr edit ${prNumber} --title "<new title>" --body "<new body>"\` to reflect them. Skip if the existing title/body still accurately describe the PR.`);
+    if (hasNonConflictHints) {
+        instructions.push(`If you applied code edits: commit them with a descriptive message, then rebase onto \`origin/${baseBranch}\` per your repository's conventions before pushing.`);
     }
-    if (needsPush) {
-        const captureHint = resolveCommand.requiresHeadSha
-            ? ` — capture \`HEAD_SHA=$(git rev-parse HEAD)\``
-            : "";
-        if (hasConflicts) {
-            instructions.push(`Rebase with conflict resolution: run \`git fetch origin && git rebase origin/${baseBranch}\`. If the rebase halts with conflicts, edit the conflicted files to resolve them, \`git add <files>\`, then \`git rebase --continue\`. Repeat until the rebase completes, then \`git push --force-with-lease\`${captureHint}.`);
+    if (resolveCommand.hasMutations) {
+        const substituteParts = [];
+        if (resolveCommand.requiresHeadSha) {
+            substituteParts.push(`\`$HEAD_SHA\` with the pushed commit SHA (or \`$(git rev-parse HEAD)\` if you did not push)`);
         }
-        else {
-            instructions.push(`Rebase and push: \`git fetch origin && git rebase origin/${baseBranch} && git push --force-with-lease\`${captureHint}`);
+        if (resolveCommand.requiresDismissMessage) {
+            substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence description of what you changed`);
         }
+        const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
+        instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
+    }
+    if (cancelledCount > 0) {
+        instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — those runs were already cancelled by the CLI before this turn.`);
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
@@ -68,28 +98,9 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (editedTotal > 0) {
         instructions.push(`Items under \`## Review summaries (edited since first look)\` and any first-look bullet tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
     }
-    if (resolveCommand.hasMutations) {
-        const substituteParts = [];
-        if (resolveCommand.requiresHeadSha) {
-            substituteParts.push(`"$HEAD_SHA" with the pushed commit SHA`);
-        }
-        if (resolveCommand.requiresDismissMessage) {
-            substituteParts.push(`$DISMISS_MESSAGE with a one-sentence description of what you changed`);
-        }
-        const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
-        instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
-    }
-    if (needsPush && cancelledCount > 0) {
-        instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — the CLI cancelled those runs before your push, and your push has already triggered new runs with different IDs.`);
-    }
     if (resolveCommand.hasMutations) {
         instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
     }
-    if (needsPush) {
-        instructions.push(FIX_INSTRUCTION_STOP_AFTER_PUSH);
-    }
-    else {
-        instructions.push(FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK);
-    }
+    instructions.push(FIX_INSTRUCTION_STOP);
     return instructions;
 }

package/bin/commands/iterate-test-support.mjs

@@ -89,6 +89,7 @@ function makeReport(overrides = {}) {
         firstLookSummaries: [],
         editedSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
         ...overrides,
     };
 }

package/bin/commands/poll.mjs

@@ -0,0 +1,32 @@
+import { runIterate } from "./iterate/index.mjs";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
+    if (process.stderr.isTTY || verbose) {
+        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
+    }
+}
+const MAX_TIMER_MS = 2 ** 31 - 1;
+export async function runPoll(opts) {
+    const { intervalSeconds, timeoutSeconds, ...iterateOpts } = opts;
+    const intervalMs = Math.min(intervalSeconds * 1000, MAX_TIMER_MS);
+    const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
+    const start = Date.now();
+    let tick = 0;
+    let lastResult;
+    const verbose = opts.verbose === true;
+    while (true) {
+        tick += 1;
+        lastResult = await runIterate(iterateOpts);
+        if (lastResult.action !== "wait")
+            return lastResult;
+        const elapsedMs = Date.now() - start;
+        const remainingMs = timeoutMs - elapsedMs;
+        if (remainingMs <= 0)
+            return lastResult;
+        const nextSleepMs = Math.min(intervalMs, remainingMs);
+        writeTickProgress(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), verbose);
+        await sleep(nextSleepMs);
+    }
+}

package/bin/commands/poll.test-support.mjs

@@ -0,0 +1,77 @@
+import { vi, beforeEach, afterEach } from "vitest";
+vi.mock("./iterate/index.mts", () => ({ runIterate: vi.fn() }));
+import { runIterate } from "./iterate/index.mjs";
+const mockRunIterate = vi.mocked(runIterate);
+function makeWaitResult(overrides = {}) {
+    return {
+        action: "wait",
+        pr: 42,
+        repo: "owner/repo",
+        status: "IN_PROGRESS",
+        state: "OPEN",
+        mergeStateStatus: "BLOCKED",
+        mergeStatus: "BLOCKED",
+        reviewDecision: "REVIEW_REQUIRED",
+        blockingBotReviewInProgress: false,
+        isDraft: false,
+        shouldCancel: false,
+        remainingSeconds: 0,
+        summary: { passing: 2, failing: 0, inProgress: 1, skipped: 0, filtered: 0 },
+        baseBranch: "main",
+        checks: [],
+        log: "WAIT: 2 passing, 1 in-progress",
+        ...overrides,
+    };
+}
+function makeCancelResult() {
+    return {
+        action: "cancel",
+        pr: 42,
+        repo: "owner/repo",
+        status: "READY",
+        state: "MERGED",
+        mergeStateStatus: "CLEAN",
+        mergeStatus: "CLEAN",
+        reviewDecision: "APPROVED",
+        blockingBotReviewInProgress: false,
+        isDraft: false,
+        shouldCancel: true,
+        remainingSeconds: 0,
+        summary: { passing: 3, failing: 0, inProgress: 0, skipped: 0, filtered: 0 },
+        baseBranch: "main",
+        checks: [],
+        reason: "merged",
+        log: "CANCEL: PR #42 is merged — stopping",
+    };
+}
+function makeMarkReadyResult() {
+    return {
+        action: "mark_ready",
+        pr: 42,
+        repo: "owner/repo",
+        status: "READY",
+        state: "OPEN",
+        mergeStateStatus: "CLEAN",
+        mergeStatus: "CLEAN",
+        reviewDecision: "APPROVED",
+        blockingBotReviewInProgress: false,
+        isDraft: false,
+        shouldCancel: false,
+        remainingSeconds: 0,
+        summary: { passing: 3, failing: 0, inProgress: 0, skipped: 0, filtered: 0 },
+        baseBranch: "main",
+        checks: [],
+        markedReady: true,
+        log: "MARKED READY: PR #42 converted from draft to ready for review",
+    };
+}
+function registerPollHooks() {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+}
+export { mockRunIterate, makeWaitResult, makeCancelResult, makeMarkReadyResult, registerPollHooks };

package/bin/commands/resolve-instructions.mjs

@@ -37,16 +37,13 @@ export function buildFetchInstructions(prNumber, result, runner) {
     }
     if (hasCodeItems) {
         instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);
-        instructions.push(`Commit changed files: \`git add <files>\` (not \`git add -A\`) \`&& git commit -m "<descriptive message>"\`.`);
-        instructions.push(`Keep the PR title and description current: if the fixes alter the PR's scope or intent, run \`gh pr edit ${prNumber} --title "<new title>" --body "<new body>"\` to reflect them. Skip if the existing title/body still accurately describe the PR.`);
-        instructions.push(`Rebase and push: \`BASE_BRANCH=$(gh pr view ${prNumber} --json baseRefName --jq .baseRefName) && git fetch origin && git rebase "origin/$BASE_BRANCH" && git push --force-with-lease\`.`);
-        instructions.push(`Cancel stale in-progress runs: \`BRANCH=$(git rev-parse --abbrev-ref HEAD) && CURRENT_SHA=$(git rev-parse HEAD) && gh run list --branch "$BRANCH" --status in_progress --json databaseId,headSha --jq ".[] | select(.headSha != \\"$CURRENT_SHA\\") | .databaseId" | xargs -I{} gh run cancel {}\`.`);
+        instructions.push(`If you applied code edits: commit them with a descriptive message, cancel any stale in-progress runs, then rebase and push per your repository's conventions.`);
     }
     if (resolutionOnlyThreads.length > 0) {
         instructions.push(`Resolve each thread under \`## Review threads to resolve\` with \`--resolve-thread-ids\`. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
     }
     const requireShaHint = hasCodeItems
-        ? ` Include \`--require-sha $(git rev-parse HEAD)\` only when the rebase-and-push step above ran.`
+        ? ` Include \`--require-sha $(git rev-parse HEAD)\` only when you pushed new commits.`
         : "";
     const dismissNote = changesRequestedReviews.length > 0
         ? ` For \`--dismiss-review-ids\`: \`--message\` is required with one specific sentence describing the fix or the reason for not acting (no boilerplate like "address review comments"); omit \`--message\` when not dismissing. Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`, never \`--dismiss-review-ids\`.`