pr-shepherd 0.17.0 → 0.18.0

package/bin/commands/check.mjs

@@ -151,5 +151,6 @@ export async function runCheck(opts) {
         firstLookSummaries,
         editedSummaries,
         approvedReviews: batchData.approvedReviews,
+        branchProtection: batchData.branchProtection,
     };
 }

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

@@ -94,6 +94,7 @@ function makeBatchData(overrides = {}) {
         changesRequestedReviews: [],
         reviewSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
         checks: [makeCheck()],
         ...overrides,
     };

package/bin/commands/commit-suggestion.apply.test-support.mjs

@@ -68,6 +68,7 @@ function makeBatch(threads) {
         changesRequestedReviews: [],
         reviewSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
     };
 }
 const FILE_CONTENT = "line1\n" +

package/bin/commands/commit-suggestion.test-support.mjs

@@ -76,6 +76,7 @@ function makeBatch(threads, headRepoWithOwner = "owner/repo") {
         changesRequestedReviews: [],
         reviewSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
     };
 }
 const FILE_CONTENT = "line1\n" +

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

@@ -1,24 +1,26 @@
 export function buildFailingCheckInstructions(checks) {
-    const instructions = [];
-    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
-    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
-    const startupFailureRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
-    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
-    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (failedRunIdChecks.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` or \`[conclusion: STARTUP_FAILURE]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log. If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\`. If the log shows a real test/build failure, apply a code fix.`);
+    if (checks.length === 0)
+        return [];
+    const hasRunId = checks.some((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
+    const hasCancelled = checks.some((c) => c.runId && c.conclusion === "CANCELLED");
+    const hasStartupFailure = checks.some((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
+    const hasExternal = checks.some((c) => !c.runId && c.detailsUrl);
+    const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
+    const parts = [];
+    if (hasRunId) {
+        parts.push("fetch the log with `gh run view <runId> --log-failed` and decide: rerun with `gh run rerun <runId> --failed` for transient infrastructure failures (network timeout, OOM kill, runner crash), or apply a code fix for real test/build failures");
     }
-    if (cancelledRunIdChecks.length > 0) {
-        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
+    if (hasCancelled) {
+        parts.push("for `[conclusion: CANCELLED]` entries: rerun with `gh run rerun <runId>` if the cancellation looks unintended (not superseded by a newer push or concurrency-group eviction); otherwise treat as resolved — do NOT confuse with IDs under `## Cancelled runs`");
     }
-    if (startupFailureRunIdChecks.length > 0) {
-        instructions.push(`For each \`[conclusion: STARTUP_FAILURE]\` bullet under \`## Failing checks\`: the workflow failed before jobs/logs were created. Run \`gh run view <runId>\` to inspect the run metadata, then run \`gh run rerun <runId>\` if the workflow should be attempted again.`);
+    if (hasStartupFailure) {
+        parts.push("for `[conclusion: STARTUP_FAILURE]` entries: inspect with `gh run view <runId>` and rerun with `gh run rerun <runId>` if the workflow should be retried");
     }
-    if (externalChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
+    if (hasExternal) {
+        parts.push("for `external` entries (no run ID, has URL): open the URL to inspect the failure");
     }
-    if (bareChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
+    if (hasBare) {
+        parts.push("for `(no runId)` entries: no log or URL is available — escalate to a human for manual investigation");
     }
-    return instructions;
+    return [`For each failing check under \`## Failing checks\`: ${parts.join("; ")}.`];
 }

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");
@@ -69,16 +59,25 @@ export function buildEscalateHumanMessage(escalate, pr) {
         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) {
@@ -107,9 +106,6 @@ export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("fix-thrash")) {
         return "Same thread(s) reached the automated attempt limit — treat this as a manual handoff. Apply the fix by hand.";
     }
-    if (triggers.includes("pr-level-changes-requested")) {
-        return "Reviewer requested changes but left no inline comments — read the review and act manually.";
-    }
     if (triggers.includes("thread-missing-location")) {
         return "Review thread has no file/line reference — automated location routing failed and manual handling is required.";
     }

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

@@ -17,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,
@@ -53,14 +53,15 @@ export async function handleFixCode(ctx) {
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
-    const hasReviewRequestedCodeLikeChanges = changesRequestedReviews.length > 0 &&
-        (actionableComments.length > 0 || resolutionOnlyThreads.length > 0);
-    const hasGuaranteedPush = threads.length > 0 || checks.length > 0 || hasConflicts || hasReviewRequestedCodeLikeChanges;
-    const shouldPush = hasGuaranteedPush;
-    // Only cancel in-progress runs for paths that produce a new code commit. A
-    // conflict-only rebase push will supersede any in-progress run on its own.
-    const hasCodeLikePush = threads.length > 0 || checks.length > 0 || hasReviewRequestedCodeLikeChanges;
-    const inProgressRunIds = hasCodeLikePush ? 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);
@@ -70,7 +71,17 @@ export async function handleFixCode(ctx) {
             `review IDs were also in minimize/comment IDs and were dropped from --dismiss-review-ids: ` +
             `${overlappingReviewIds.join(", ")}\n`);
     }
-    if (baseLookup.isFallback && shouldPush) {
+    // 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)],
@@ -89,7 +100,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, cliRunner, shouldPush);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, cliRunner);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,

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,12 +15,41 @@ export function renderResolveCommand(rc) {
     }
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner, needsPushInput) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
     const instructions = [];
-    const hasCodeWork = threads.length > 0 || checks.length > 0;
-    const needsPush = needsPushInput ?? (hasCodeWork || hasConflicts);
+    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) {
@@ -40,25 +68,22 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     if (changesRequestedReviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }
-    if (needsPush && (hasCodeWork || changesRequestedReviews.length > 0)) {
-        instructions.push(`Commit changed files: \`git add <files> && git commit -m "<descriptive message>"\``);
-    }
-    if (changesRequestedReviews.length > 0) {
-        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 (!needsPush && resolveCommand.requiresHeadSha) {
-        instructions.push("Capture the current HEAD SHA before resolving with: `HEAD_SHA=$(git rev-parse HEAD)`.");
+    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) {
@@ -73,29 +98,9 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     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) {
-            const shaSource = needsPush ? "pushed commit SHA" : "current HEAD SHA";
-            substituteParts.push(`"$HEAD_SHA" with the ${shaSource}`);
-        }
-        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\`.`

package/bin/github/batch-parser-helpers.mjs

@@ -0,0 +1,38 @@
+export function mapAuthorType(typeName) {
+    if (typeName === "User" || typeName === "Bot")
+        return typeName;
+    return "Unknown";
+}
+export function parseCreatedAt(iso) {
+    const ms = new Date(iso).getTime();
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+export function extractRunId(url) {
+    if (!url)
+        return null;
+    const m = /\/runs\/(\d+)/.exec(url);
+    return m ? (m[1] ?? null) : null;
+}
+export function extractCheckRunSummary(title, summary) {
+    const t = title?.trim();
+    if (t)
+        return t;
+    const firstLine = summary
+        ?.split("\n")
+        ?.find((l) => l.trim() !== "")
+        ?.trim();
+    return firstLine || undefined;
+}
+export function mapStatusContextState(state) {
+    switch (state) {
+        case "SUCCESS":
+            return { status: "COMPLETED", conclusion: "SUCCESS" };
+        case "FAILURE":
+        case "ERROR":
+            return { status: "COMPLETED", conclusion: "FAILURE" };
+        case "PENDING":
+        case "EXPECTED":
+        default:
+            return { status: "IN_PROGRESS", conclusion: null };
+    }
+}

package/bin/github/batch-parsers.mjs

@@ -1,3 +1,4 @@
+import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, } from "./batch-parser-helpers.mjs";
 export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes) {
     const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
         const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
@@ -92,6 +93,16 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         }
         return [];
     });
+    const rawProtection = raw.baseRef?.branchProtectionRule ?? null;
+    const branchProtection = rawProtection
+        ? {
+            requiresApprovingReviews: rawProtection.requiresApprovingReviews,
+            requiredApprovingReviewCount: rawProtection.requiredApprovingReviewCount,
+            requiresConversationResolution: rawProtection.requiresConversationResolution,
+            requiresStatusChecks: rawProtection.requiresStatusChecks,
+            requiredStatusCheckContexts: rawProtection.requiredStatusCheckContexts ?? [],
+        }
+        : null;
     return {
         nodeId: raw.id,
         number: raw.number,
@@ -112,43 +123,6 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         reviewSummaries,
         approvedReviews,
         checks,
+        branchProtection,
     };
 }
-function mapAuthorType(typeName) {
-    if (typeName === "User" || typeName === "Bot")
-        return typeName;
-    return "Unknown";
-}
-function parseCreatedAt(iso) {
-    const ms = new Date(iso).getTime();
-    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
-}
-function extractRunId(url) {
-    if (!url)
-        return null;
-    const m = /\/runs\/(\d+)/.exec(url);
-    return m ? (m[1] ?? null) : null;
-}
-function extractCheckRunSummary(title, summary) {
-    const t = title?.trim();
-    if (t)
-        return t;
-    const firstLine = summary
-        ?.split("\n")
-        ?.find((l) => l.trim() !== "")
-        ?.trim();
-    return firstLine || undefined;
-}
-function mapStatusContextState(state) {
-    switch (state) {
-        case "SUCCESS":
-            return { status: "COMPLETED", conclusion: "SUCCESS" };
-        case "FAILURE":
-        case "ERROR":
-            return { status: "COMPLETED", conclusion: "FAILURE" };
-        case "PENDING":
-        case "EXPECTED":
-        default:
-            return { status: "IN_PROGRESS", conclusion: null };
-    }
-}

package/bin/github/gql/batch-pr.gql

@@ -24,6 +24,15 @@ query BatchPr(
         nameWithOwner
       }
       baseRefName
+      baseRef {
+        branchProtectionRule {
+          requiresApprovingReviews
+          requiredApprovingReviewCount
+          requiresConversationResolution
+          requiresStatusChecks
+          requiredStatusCheckContexts
+        }
+      }
       # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
       reviewRequests(last: 50) {
         nodes {