pr-shepherd 0.10.3 → 0.12.0

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

@@ -4,24 +4,23 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { tryCancelRun } from "./helpers.mjs";
+import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
-    // Accumulate across shas — only increment when a push is detected (sha changed)
     const currentAttempts = stored ? { ...stored.threadAttempts } : {};
     if (isNewSha) {
         for (const t of report.threads.actionable) {
             currentAttempts[t.id] = (currentAttempts[t.id] ?? 0) + 1;
         }
     }
-    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.comments.actionable, report.changesRequestedReviews, failingChecks, currentAttempts, report.mergeStatus.status === "CONFLICTS");
+    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.threads.resolutionOnly, report.comments.actionable, report.changesRequestedReviews, failingChecks, currentAttempts, report.mergeStatus.status === "CONFLICTS");
     if (escalateTriggers.triggers.length > 0) {
         const escalateBase = {
             triggers: escalateTriggers.triggers,
-            unresolvedThreads: report.threads.actionable.map(toAgentThread),
+            unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
             ambiguousComments: report.comments.actionable.map(toAgentComment),
             changesRequestedReviews: report.changesRequestedReviews,
             attemptHistory: escalateTriggers.thrashHistory,
@@ -36,7 +35,6 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    // Save updated state (only incremented on sha change)
     await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts: currentAttempts });
     let cancelled = [];
     if (!opts.noAutoCancelActionable) {
@@ -46,18 +44,26 @@ export async function handleFixCode(ctx) {
         const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
         cancelled = results.filter((id) => id !== null);
     }
+    const cancelledSet = new Set(cancelled);
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
+    const resolutionOnlyThreads = report.threads.resolutionOnly;
     const actionableComments = report.comments.actionable.map(toAgentComment);
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
+    const needsPush = threads.length > 0 ||
+        actionableComments.length > 0 ||
+        checks.length > 0 ||
+        changesRequestedReviews.length > 0 ||
+        hasConflicts;
+    const inProgressRunIds = needsPush ? buildInProgressRunIds(report, cancelledSet) : [];
     const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
-    const resolveCommand = buildResolveCommand(threads, allCommentIds, changesRequestedReviews, checks, prNumber);
+    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
-            unresolvedThreads: threads,
+            unresolvedThreads: [...threads, ...resolutionOnlyThreads.map(toAgentThread)],
             ambiguousComments: actionableComments,
             changesRequestedReviews,
             suggestion: buildEscalateSuggestion(["base-branch-unknown"], baseLookup.failureReason),
@@ -73,7 +79,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);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -81,6 +87,7 @@ export async function handleFixCode(ctx) {
         fix: {
             mode: "rebase-and-push",
             threads,
+            resolutionOnlyThreads,
             actionableComments,
             reviewSummaryIds,
             firstLookSummaries,
@@ -92,6 +99,7 @@ export async function handleFixCode(ctx) {
             instructions,
             firstLookThreads,
             firstLookComments,
+            inProgressRunIds,
         },
         cancelled,
     }, report, reviewSummaryIds);

package/bin/commands/iterate/helpers.mjs

@@ -2,6 +2,13 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { rest } from "../../github/http.mjs";
 const execFile = promisify(execFileCb);
+export function buildInProgressRunIds(report, cancelledSet) {
+    return [
+        ...new Set(report.checks.inProgress
+            .map((c) => c.runId)
+            .filter((id) => id !== null && !cancelledSet.has(id))),
+    ];
+}
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -84,6 +91,33 @@ export async function getCurrentHeadSha() {
         return null;
     }
 }
+export function buildWaitLog(base) {
+    const { summary, remainingSeconds } = base;
+    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
+    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
+                parts.push("awaiting human review or branch protection");
+            break;
+        case "BEHIND":
+            parts.push("branch is behind base");
+            break;
+        case "DRAFT":
+            parts.push("PR is a draft");
+            break;
+        case "UNSTABLE":
+            parts.push("some checks are unstable");
+            break;
+    }
+    if (remainingSeconds > 0) {
+        parts.push(`${remainingSeconds}s until auto-cancel`);
+    }
+    return parts.join(" — ");
+}
 export function buildCooldownResult(prNumber, readyDelaySeconds) {
     return {
         action: "cooldown",

package/bin/commands/iterate/index.mjs

@@ -4,10 +4,9 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, } from "./helpers.mjs";
+import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, buildWaitLog, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { buildWaitLog } from "./render.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
@@ -97,6 +96,7 @@ export async function runIterate(opts) {
         edited: report.editedSummaries,
     }, report.approvedReviews, config.iterate.minimizeApprovals);
     const hasActionableWork = report.threads.actionable.length > 0 ||
+        report.threads.resolutionOnly.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
         report.checks.failing.length > 0 ||

package/bin/commands/iterate/render.mjs

@@ -1,3 +1,6 @@
+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_END_ITERATION = "End this iteration.";
 /**
  * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE` and whitespace-bearing
  * argv entries in double quotes for placeholder substitution. Throws if argv contains `"`, `$`,
@@ -18,11 +21,14 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = []) {
     const instructions = [];
+    if (inProgressRunIds.length > 0) {
+        instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\`. Do this before applying any code fixes — the push at the end of this iteration will supersede those runs anyway, so letting them continue burns CI minutes for results no one will read. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
+    }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
-        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` the CLI already resolved the thread — remove its ID from \`--resolve-thread-ids\` in the \`resolve:\` command below. On \`applied: false\` read \`reason\` and \`patch\`, fall through to the manual-edit step, and do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) to preview the patch without mutating the working tree.`);
+        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` 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. Include the thread ID in \`--resolve-thread-ids\` in the \`resolve:\` command below (the thread is not auto-resolved). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions
@@ -30,11 +36,20 @@ export function buildFixInstructions(threads, actionableComments, checks, review
             : "";
         instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.${suggestionFallback}`);
     }
-    const checksWithRunId = checks.filter((c) => c.runId);
+    if (resolutionOnlyThreads.length > 0) {
+        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.`);
+    }
+    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
+    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED");
     const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
     const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (checksWithRunId.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID, examine the log tail in the fenced block to decide what to do:\n   - If the log tail shows a transient runner or infrastructure failure (network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\` and stop this iteration — CI will re-run automatically.\n   - If the log tail shows a real test or build failure, apply a code fix.\n   - If the fenced log block is absent, run \`gh run view <runId> --log-failed\` first to fetch it, then choose between rerun and fix above.`);
+    if (failedRunIdChecks.length > 0) {
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`);
+        instructions.push(`If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`);
+        instructions.push(`If the log shows a real test/build failure: apply a code fix.`);
+    }
+    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 (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.`);
@@ -64,7 +79,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
+        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.`);
     }
     if (firstLookSummaries.length > 0) {
         instructions.push(`Review the bodies shown under \`## Review summaries (first look — to be minimized)\` — you are seeing these for the first time. Their IDs are already included in the \`resolve:\` command's \`--minimize-comment-ids\`; if any warrants a \`## Shepherd Journal\` entry, record it before running resolve.`);
@@ -73,7 +88,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
         firstLookThreads.filter((t) => t.edited).length +
         firstLookComments.filter((c) => c.edited).length;
     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. Do **not** include their IDs in \`--minimize-comment-ids\`, \`--resolve-thread-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
+        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 = [];
@@ -93,40 +108,13 @@ export function buildFixInstructions(threads, actionableComments, checks, review
         instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.`);
     }
     if (needsPush) {
-        instructions.push(`Stop this iteration — CI needs time to run on the new push before the next tick.`);
+        instructions.push(FIX_INSTRUCTION_STOP_AFTER_PUSH);
     }
     else if (resolveCommand.hasMutations) {
-        instructions.push(`Stop this iteration before the next tick.`);
+        instructions.push(FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK);
     }
     else {
-        instructions.push(`End this iteration.`);
+        instructions.push(FIX_INSTRUCTION_END_ITERATION);
     }
     return instructions;
 }
-export function buildWaitLog(base) {
-    const { summary, remainingSeconds } = base;
-    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
-    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
-                parts.push("awaiting human review or branch protection");
-            break;
-        case "BEHIND":
-            parts.push("branch is behind base");
-            break;
-        case "DRAFT":
-            parts.push("PR is a draft");
-            break;
-        case "UNSTABLE":
-            parts.push("some checks are unstable");
-            break;
-    }
-    if (remainingSeconds > 0) {
-        parts.push(`${remainingSeconds}s until auto-cancel`);
-    }
-    return parts.join(" — ");
-}

package/bin/commands/iterate/stall.mjs

@@ -7,6 +7,7 @@ export function computeStallFingerprint(action, headSha, base, report, reviewSum
         ...report.checks.inProgress.map((p) => `inProgress:${p.name}`),
     ].sort();
     const threads = report.threads.actionable.map((t) => t.id).sort();
+    const resolutionOnlyThreads = report.threads.resolutionOnly.map((t) => t.id).sort();
     const comments = report.comments.actionable.map((c) => c.id).sort();
     const reviews = report.changesRequestedReviews.map((r) => r.id).sort();
     const summaries = [...reviewSummaryIds].sort();
@@ -19,6 +20,7 @@ export function computeStallFingerprint(action, headSha, base, report, reviewSum
         isDraft: base.isDraft,
         checks,
         threads,
+        resolutionOnlyThreads,
         comments,
         reviews,
         summaries,
@@ -42,7 +44,7 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
             const stalledMinutes = Math.floor(ageSeconds / 60);
             const escalateBase = {
                 triggers: ["stall-timeout"],
-                unresolvedThreads: report.threads.actionable.map(toAgentThread),
+                unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
                 ambiguousComments: report.comments.actionable.map(toAgentComment),
                 changesRequestedReviews: report.changesRequestedReviews,
                 suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),

package/bin/commands/iterate.mjs

@@ -1,2 +1,2 @@
 export { runIterate } from "./iterate/index.mjs";
-export { renderResolveCommand } from "./iterate/render.mjs";
+export { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, renderResolveCommand, } from "./iterate/render.mjs";

package/bin/commands/monitor.mjs

@@ -1,5 +1,6 @@
 import { getCurrentPrNumber } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
+import { joinSections } from "../util/markdown.mjs";
 export async function runMonitor(opts) {
     const config = loadConfig();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -16,30 +17,48 @@ export async function runMonitor(opts) {
     // step 1 of formatMonitorResult's ## Instructions and the in-prompt Self-dedup
     // block depend on this exact string — don't change the format.
     const loopTag = `#pr-shepherd-loop:pr=${prNumber}:`;
-    const loopPrompt = buildLoopPrompt(prNumber, loopTag, opts.readyDelaySuffix);
     const loopArgs = interval;
-    return { prNumber, loopTag, loopArgs, loopPrompt };
+    const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix);
+    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude");
+    return {
+        prNumber,
+        loopTag,
+        loopArgs,
+        loopPrompt,
+        reusableCommand,
+    };
 }
 // ---------------------------------------------------------------------------
 // Formatters
 // ---------------------------------------------------------------------------
-export function formatMonitorResult(result) {
+export function formatMonitorResult(result, opts) {
     const { prNumber, loopTag, loopArgs, loopPrompt } = result;
-    return [
-        `# PR #${prNumber} [MONITOR]`,
-        "",
-        `Loop tag: \`${loopTag}\``,
-        `Loop args: \`${loopArgs}\``,
-        "",
+    const runtime = opts?.runtime ?? "claude";
+    const sections = [
+        [
+            `# PR #${prNumber} [MONITOR]`,
+            "",
+            `Loop tag: \`${loopTag}\``,
+            `Loop args: \`${loopArgs}\``,
+        ].join("\n"),
+        runtime === "codex" ? `Reusable command: \`${result.reusableCommand}\`` : null,
         "## Loop prompt",
-        "",
         loopPrompt,
-        "",
         "## Instructions",
-        "",
-        `1. Run \`CronList\`. If any job's prompt contains \`${loopTag}\`, run the \`## Loop prompt\` body once inline (as if it were a cron tick) then stop — do not create a duplicate loop.`,
-        `2. Otherwise, invoke the \`/loop\` skill via the Skill tool. Build the \`args\` parameter as: only the value inside the backticks on the \`Loop args\` line above (the interval — not the \`Loop args:\` label), then a blank line, then the full \`## Loop prompt\` body.`,
-    ].join("\n");
+        buildMonitorInstructions(result, runtime)
+            .map((inst, i) => `${i + 1}. ${inst}`)
+            .join("\n"),
+    ];
+    return joinSections(sections);
+}
+export function formatMonitorJson(result, opts) {
+    const runtime = opts?.runtime ?? "claude";
+    const { reusableCommand, ...base } = result;
+    return {
+        ...base,
+        ...(runtime === "codex" && { reusableCommand }),
+        instructions: buildMonitorInstructions(result, runtime),
+    };
 }
 // ---------------------------------------------------------------------------
 // Internal
@@ -53,9 +72,29 @@ function validateReadyDelaySuffix(readyDelaySuffix) {
     }
     return trimmed;
 }
-function buildLoopPrompt(prNumber, loopTag, readyDelaySuffix) {
+function buildIterateCommand(prNumber, readyDelaySuffix) {
     const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
-    const iterateCmd = `npx pr-shepherd iterate ${prNumber}${validatedDelay ? ` --ready-delay ${validatedDelay}` : ""}`;
+    return `npx pr-shepherd ${prNumber}${validatedDelay ? ` --ready-delay ${validatedDelay}` : ""}`;
+}
+function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude") {
+    if (runtime === "codex") {
+        return [
+            loopTag,
+            "",
+            "**IMPORTANT — Codex recurrence rules:**",
+            "- Run the command below once and follow its `## Instructions` exactly.",
+            `- If the output tells you to continue the active Codex goal, wait about the configured interval (${loopArgs}) and rerun the reusable command from the monitor output.`,
+            "- Stop only when Shepherd emits `[CANCEL]` because the ready-delay completed or the PR was merged/closed, or when Shepherd emits `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).",
+            "- Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `npx pr-shepherd monitor`; Codex recurrence is explicit `iterate` command cycles.",
+            "",
+            "Run in a single Bash call:",
+            `  ${iterateCmd}`,
+            "",
+            `Exit codes 0–3 are all valid. If the command crashes (non-zero exit, no markdown output starting with \`# PR #${prNumber} [\`), report the first line of stderr and stop so the user can retry.`,
+            "",
+            "The output is Markdown. The first line is an H1 heading of the form `# PR #<N> [<ACTION>]`. Every output ends with a `## Instructions` section — follow those numbered steps exactly.",
+        ].join("\n");
+    }
     return [
         loopTag,
         "",
@@ -73,3 +112,15 @@ function buildLoopPrompt(prNumber, loopTag, readyDelaySuffix) {
         "The output is Markdown. The first line is an H1 heading of the form `# PR #<N> [<ACTION>]`. Every output ends with a `## Instructions` section — follow those numbered steps exactly.",
     ].join("\n");
 }
+function buildMonitorInstructions(result, runtime) {
+    if (runtime === "codex") {
+        return [
+            "Run the `## Loop prompt` body once inline now.",
+            `For an active Codex goal, keep cycling with \`${result.reusableCommand}\` about every configured interval (${result.loopArgs}) until a terminal condition is reached. Codex does not create a \`/loop\` monitor.`,
+        ];
+    }
+    return [
+        `Run \`CronList\`. If any job's prompt contains \`${result.loopTag}\`, run the \`## Loop prompt\` body once inline (as if it were a cron tick) then stop — do not create a duplicate loop.`,
+        "Otherwise, invoke the `/loop` skill via the Skill tool. Build the `args` parameter as: only the value inside the backticks on the `Loop args` line above (the interval — not the `Loop args:` label), then a blank line, then the full `## Loop prompt` body.",
+    ];
+}

package/bin/commands/ready-delay.mjs

@@ -16,7 +16,8 @@ import { resolveStateBase } from "../state/base.mjs";
  *   - If `isReady == true`: start or continue the ready timer.
  *   - If `isReady == false`: reset the timer.
  *
- * When `shouldCancel == true`, the slash command should invoke `/loop cancel`.
+ * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
+ * the loop and tells one-shot agents to stop.
  */
 export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo) {
     const markerPath = readySincePath(prNumber, owner, repo);

package/bin/commands/resolve-instructions.mjs

@@ -4,9 +4,10 @@
  * `buildFixInstructions` in `commands/iterate/render.mts`).
  */
 export function buildFetchInstructions(prNumber, result) {
-    const { actionableThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
+    const { actionableThreads, resolutionOnlyThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     const total = actionableThreads.length +
+        resolutionOnlyThreads.length +
         actionableComments.length +
         changesRequestedReviews.length +
         reviewSummaries.length +
@@ -21,15 +22,15 @@ export function buildFetchInstructions(prNumber, result) {
     const instructions = [];
     instructions.push(`Classify every item listed above into exactly one of: Fixed / Actionable / Not relevant / Outdated / Acknowledge. Do not silently skip any item. Bot-authored review summaries (authors whose name contains \`[bot]\` or matches \`copilot-pull-request-reviewer\`, \`gemini-code-assist\`) default to Acknowledge with reason "bot summary — no actionable content" unless the body calls out an unaddressed issue.`);
     if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
+        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\`, include its ID in \`--resolve-thread-ids\`; otherwise do not pass first-look-only IDs to mutation flags.`);
     }
     const editedTotal = firstLookThreads.filter((t) => t.edited).length +
         firstLookComments.filter((c) => c.edited).length;
     if (editedTotal > 0) {
-        instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body. Do **not** include their IDs in \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
+        instructions.push(`First-look bullets 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 (hasSuggestions) {
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` mark it Fixed — the CLI already resolved the thread, so exclude the ID from \`--resolve-thread-ids\`. On \`applied: false\` read \`reason\` and \`patch\`, then fall through to the manual fix step — do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) if you want to inspect the unified diff before it mutates the working tree — the CLI validates with \`git apply --check\`, returns the patch and \`valid: true/false\`, and exits \`1\` on drift without committing or resolving the thread.`);
+        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` 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. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
     }
     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.`);
@@ -38,6 +39,9 @@ export function buildFetchInstructions(prNumber, result) {
         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 {}\`.`);
     }
+    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.`
         : "";

package/bin/commands/resolve.mjs

@@ -6,7 +6,6 @@ import { loadConfig } from "../config/load.mjs";
 import { extractSuggestion } from "../suggestions/extract.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
-/** Fetch mode: auto-resolve outdated threads and return all active items for LLM triage. */
 export async function runResolveFetch(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -15,7 +14,7 @@ export async function runResolveFetch(opts) {
     }
     const { data } = await fetchPrBatch(prNumber, repo);
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
-    const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
+    const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved);
     const visibleComments = data.comments.filter((c) => !c.isMinimized);
     const outdatedCandidates = data.reviewThreads.filter((t) => t.isOutdated);
     const resolvedCandidates = data.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
@@ -68,7 +67,8 @@ export async function runResolveFetch(opts) {
             process.stderr.write(`pr-shepherd: auto-resolve outdated threads failed (continuing): ${errors.join(", ")}\n`);
         }
     }
-    const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
+    const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated && !t.isMinimized);
+    const resolutionOnlyThreads = unresolvedThreads.filter((t) => !autoResolvedIds.has(t.id) && (t.isOutdated || t.isMinimized));
     const cfg = loadConfig();
     const actionableThreads = activeThreads.map(({ isResolved: _r, isOutdated: _o, ...rest }) => {
         const thread = rest;
@@ -118,6 +118,7 @@ export async function runResolveFetch(opts) {
     const result = {
         prNumber,
         actionableThreads,
+        resolutionOnlyThreads,
         firstLookThreads,
         actionableComments: visibleComments,
         firstLookComments,
@@ -127,7 +128,6 @@ export async function runResolveFetch(opts) {
     };
     return { ...result, instructions: buildFetchInstructions(prNumber, result) };
 }
-/** Mutation mode: resolve/minimize/dismiss by ID. */
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());

package/bin/config.json

@@ -17,9 +17,7 @@
     "fetchReviewSummaries": true
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"],
-    "logTailLines": 5,
-    "logTailChars": 200
+    "ciTriggerEvents": ["pull_request", "pull_request_target"]
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]

package/bin/index.mjs

@@ -3,6 +3,7 @@
  * pr-shepherd — unified GitHub PR status + auto-resolve CLI
  *
  * Usage:
+ *   pr-shepherd [PR]
  *   pr-shepherd check [PR]
  *   pr-shepherd resolve [PR]
  *   pr-shepherd iterate [PR]

package/bin/reporters/agent.mjs

@@ -3,7 +3,8 @@
  *
  * These strip fields that are always-false by the time items reach iterate
  * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
- * monitor prompt never reads (event, status, conclusion, category).
+ * monitor prompt never reads (event, status, category).
+ * conclusion is preserved on AgentCheck so the formatter can branch on CANCELLED.
  * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
  * The original domain types are preserved for check command output.
  */
@@ -27,15 +28,18 @@ export function toAgentComment(c) {
     return { id: c.id, author: c.author, body: c.body, url: c.url };
 }
 export function toAgentCheck(c) {
+    if (c.conclusion === "SKIPPED" || c.conclusion === "NEUTRAL") {
+        throw new Error(`Unexpected conclusion ${c.conclusion} in toAgentCheck`);
+    }
     return {
         name: c.name,
         runId: c.runId,
         detailsUrl: c.detailsUrl,
+        conclusion: c.conclusion,
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
-        ...(c.logTail !== undefined && { logTail: c.logTail }),
     };
 }
 /**

package/bin/reporters/check-instructions.mjs

@@ -3,11 +3,15 @@
  * All rebase policy, CI budget policy, and ready-to-merge gating live here so the
  * skill stays a thin dispatcher and these rules co-evolve with the CLI data model.
  */
-export function buildCheckInstructions(report) {
+export function buildCheckInstructions(report, opts) {
+    const runtime = opts?.runtime ?? "claude";
     const { mergeStatus, checks, threads, comments, changesRequestedReviews, status } = report;
     const instructions = [];
     // 1. Summary
-    const totalActionable = threads.actionable.length + comments.actionable.length + changesRequestedReviews.length;
+    const totalActionable = threads.actionable.length +
+        threads.resolutionOnly.length +
+        comments.actionable.length +
+        changesRequestedReviews.length;
     const total = checks.passing.length +
         checks.failing.length +
         checks.inProgress.length +
@@ -28,8 +32,8 @@ export function buildCheckInstructions(report) {
     for (const c of checks.failing) {
         const stepHint = c.failedStep ? ` (failed step: \`${c.failedStep}\`)` : "";
         const diagnosisHint = c.runId
-            ? c.logTail !== undefined
-                ? `examine the log tail${stepHint} — if transient, run \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
+            ? c.conclusion === "CANCELLED"
+                ? `cancelled — if unintended, rerun with \`gh run rerun ${c.runId}\``
                 : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
             : c.detailsUrl
                 ? `open the check details (${c.detailsUrl}) to diagnose the failure`
@@ -54,7 +58,9 @@ export function buildCheckInstructions(report) {
     }
     // 5. Continuous monitoring pointer (suppressed only when truly ready to merge)
     if (!isReady) {
-        instructions.push("This is a one-shot check. For continuous monitoring that acts on these signals automatically, use `/pr-shepherd:monitor`.");
+        instructions.push(runtime === "codex"
+            ? `This is a one-shot check. For follow-up monitoring, run \`npx pr-shepherd ${report.pr}\`.`
+            : "This is a one-shot check. For continuous monitoring that acts on these signals automatically, use `/pr-shepherd:monitor`.");
     }
     return instructions;
 }

package/bin/reporters/json.mjs

@@ -5,6 +5,6 @@
  * without string-scraping the human-readable text reporter.
  */
 import { buildCheckInstructions } from "./check-instructions.mjs";
-export function formatJson(report) {
-    return JSON.stringify({ ...report, instructions: buildCheckInstructions(report) }, null, 2);
+export function formatJson(report, opts) {
+    return JSON.stringify({ ...report, instructions: buildCheckInstructions(report, opts) }, null, 2);
 }