pr-shepherd 0.60.0 → 1.0.0

package/bin/commands/iterate/{fix-code.mjs → triage.mjs}

@@ -77,22 +77,22 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     };
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
-export async function handleFixCode(ctx) {
-    const result = await handleFixCodeTick(ctx);
+export async function handleTriage(ctx) {
+    const result = await handleTriageTick(ctx);
     // Every escalation from a capped tick carries the rollup: the reader sees a subset.
     const { reviewItems } = ctx.report;
     if (result.action !== "escalate" || reviewItems === undefined)
         return result;
     return { ...result, escalate: { ...result.escalate, reviewItems } };
 }
-async function handleFixCodeTick(ctx) {
+async function handleTriageTick(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, releasedCheckNames = EMPTY_RELEASED, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
     const allThreads = [...report.threads.actionable, ...report.threads.resolutionOnly];
     const ruleAutoResolveIds = new Set(ruleAutoResolveThreadIds ?? []);
-    const resolveOtherHumanThreads = loadConfig().iterate.resolveOtherHumanThreads ?? "none";
+    const resolveOtherHumanThreads = loadConfig().iterate["resolve-other-human-threads"] ?? "none";
     const routedThreadMutations = buildThreadMutationRouting(allThreads, botUsernames, [...ruleAutoResolveIds], resolveOtherHumanThreads);
     const replyIdSet = new Set(routedThreadMutations.replyThreadIds);
     const resolveIdSet = new Set(routedThreadMutations.resolveThreadIds);
@@ -107,12 +107,11 @@ async function handleFixCodeTick(ctx) {
         ((thread.path !== null && thread.line !== null) ||
             threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
     const retryableActionableThreads = mutationActionableThreads.filter((thread) => thread.path !== null && thread.line !== null);
-    const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     await aliasThreadFixAttempts({ owner: repoOwner, name: repoName }, prNumber, retryableActionableThreads.map(({ id }) => id), stored);
-    const countFixCodeAttempt = opts.persistSeen !== false;
+    const countTriageAttempt = opts.persistSeen !== false;
     const priorThreadAttempts = previousFixAttempts(stored, retryableActionableThreads);
-    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, retryableActionableThreads, countFixCodeAttempt);
+    const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, retryableActionableThreads, countTriageAttempt);
     const resolutionOnlyThreadsForWork = report.threads.resolutionOnly.filter((thread) => !skippedThreadIds.has(thread.id) &&
         ((thread.path !== null && thread.line !== null) ||
             threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
@@ -126,7 +125,7 @@ async function handleFixCodeTick(ctx) {
         ...(report.comments.minimizeIds ?? report.comments.actionable.map((comment) => comment.id)),
         ...reviewSummaryIds,
     ], changesRequestedReviewsForWork, checks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
-    const escalateTriggers = countFixCodeAttempt
+    const escalateTriggers = countTriageAttempt
         ? checkEscalateTriggers(retryableActionableThreads, priorThreadAttempts)
         : { triggers: [], thrashHistory: undefined };
     if (escalateTriggers.triggers.length > 0) {
@@ -161,7 +160,6 @@ async function handleFixCodeTick(ctx) {
     // it does not confirm the credential executing `gh` has that scope; an unauthorized rerun
     // simply fails when the agent runs it, the same residual risk as every other CLI-recommended
     // git/gh mutation in this codebase.
-    const cancelled = [];
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
@@ -204,11 +202,7 @@ async function handleFixCodeTick(ctx) {
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
-    const { behindBaseHint, instructions: configuredInstructions } = loadConfig().iterate;
-    // 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 inProgressRunIds = [];
+    const { "behind-base-hint": behindBaseHint, instructions: configuredInstructions } = loadConfig().iterate;
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !releasedCheckNames.has(check.name) &&
@@ -265,7 +259,7 @@ async function handleFixCodeTick(ctx) {
         };
     }
     // Push access to the PR head branch is a usage precondition. Build review mutations for
-    // conflict ticks normally so the caller can push and complete the same fix_code cycle.
+    // conflict ticks normally so the caller can push and complete the same triage cycle.
     const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
     // 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
@@ -346,7 +340,7 @@ async function handleFixCodeTick(ctx) {
     const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0) || queueEjection
         ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict, report.stackBottomPr)
         : undefined;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, canGenerateGithubMutation(report.viewerAuthorization?.viewerCanUpdate, "ready"), exhaustedAttempts.length > 0, stackRebase, queueEjection, opts.instructions ?? configuredInstructions);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, canGenerateGithubMutation(report.viewerAuthorization?.viewerCanUpdate, "ready"), exhaustedAttempts.length > 0, stackRebase, queueEjection, opts.instructions ?? configuredInstructions);
     if (recovery && "unavailable" in recovery)
         instructions.unshift(recovery.unavailable);
     if (acknowledgmentRecovery && "unavailable" in acknowledgmentRecovery)
@@ -391,8 +385,8 @@ async function handleFixCodeTick(ctx) {
         baseBranch: baseLookup.branch,
         ...(mergedBasePullRequests.length > 0 && { mergedBasePullRequests }),
         ...(trunkConflict && { stackTrunkConflict: trunkConflict.trunk }),
-        action: "fix_code",
-        fix: {
+        action: "triage",
+        triage: {
             threads,
             resolutionOnlyThreads,
             actionableComments,
@@ -409,16 +403,13 @@ async function handleFixCodeTick(ctx) {
             instructions,
             firstLookThreads,
             firstLookComments,
-            inProgressRunIds,
-            protectedRuns,
             ...(report.reviewItems && { reviewItems: report.reviewItems }),
         },
-        cancelled,
     };
     const result = await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds);
-    if (result.action === "fix_code" && opts.persistSeen !== false) {
+    if (result.action === "triage" && opts.persistSeen !== false) {
         await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
-        await Promise.allSettled(result.fix.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
+        await Promise.allSettled(result.triage.checks.flatMap((ch) => (ch.annotations ?? []).map((a) => markSeen(stallKey, a.id, annotationMarkerBody(a)))));
     }
     return result;
 }

package/bin/commands/iterate/unreported-required.mjs

@@ -84,8 +84,8 @@ export function buildUnreportedFixResult(base, report, instructions) {
     const prUrl = formatPrUrl(report.repo, report.pr);
     return {
         ...base,
-        action: "fix_code",
-        fix: {
+        action: "triage",
+        triage: {
             threads: [],
             resolutionOnlyThreads: [],
             actionableComments: [],
@@ -102,12 +102,9 @@ export function buildUnreportedFixResult(base, report, instructions) {
                 hasMutations: false,
             },
             instructions: [...instructions, buildFixCompletionInstruction()],
-            inProgressRunIds: [],
-            protectedRuns: [],
             firstLookThreads: [],
             firstLookComments: [],
         },
-        cancelled: [],
     };
 }
 function stackRebase(report) {

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

@@ -13,8 +13,6 @@ export interface JournalResult {
     sectionExisted: boolean;
     dryRun: boolean;
     previewBody?: string;
-    /** @deprecated Explicit journal requests now rely on GitHub's mutation response. */
-    authorizationSkipped?: "denied-or-unverifiable";
 }
-/** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */
+/** Implementation for `apply journal`. */
 export declare function runJournal(opts: RunJournalOptions): Promise<JournalResult>;

package/bin/commands/journal/index.mjs

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

package/bin/commands/mark-files-as-viewed.d.mts

@@ -21,8 +21,6 @@ export interface MarkFilesAsViewedResult {
     errors: string[];
     rateLimit?: ResolveRateLimitStop;
     unmarkedPaths?: string[];
-    /** @deprecated Explicit file-view requests are attempted; GitHub authorizes the mutation. */
-    authorizationSkipped?: "unverifiable";
 }
-/** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
+/** Implementation for `apply files`. */
 export declare function runMarkFilesAsViewed(opts: MarkFilesAsViewedOptions): Promise<MarkFilesAsViewedResult>;

package/bin/commands/mark-files-as-viewed.mjs

@@ -34,7 +34,7 @@ const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr
 const TEST_FILE_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[cm]?[jt]sx?$|_tests?\.rs$|(^|\/)tests?\.rs$/i;
 // Keep mutation batches small so rate-limit stops leave an ordered pending list.
 const MARK_FILES_CHUNK_SIZE = 10;
-/** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
+/** Implementation for `apply files`. */
 export async function runMarkFilesAsViewed(opts) {
     return githubOperation("markFileAsViewed", () => runGraphqlMarkFilesAsViewed(opts), async () => {
         throw new UnsupportedRestOperationError("markFileAsViewed");

package/bin/commands/next-check.d.mts

@@ -8,10 +8,10 @@ export interface NextCheckCandidate {
     seconds: number;
 }
 /** The earliest candidate as a `NextCheck`, with `at` rounded up to a whole minute. */
-export declare function earliestNextCheck(candidates: NextCheckCandidate[], nowMs?: number): NextCheck | undefined;
+export declare function earliestNextCheck(candidates: NextCheckCandidate[], nowMs?: number, minimumSeconds?: number): NextCheck | undefined;
 interface NextCheckFacts {
     /** The action Shepherd returned for this tick. */
-    action: "wait" | "ready" | "mark_ready" | "fix_code" | "merge" | "cancel" | "escalate";
+    action: "wait" | "ready" | "mark_ready" | "triage" | "merge" | "cancel" | "escalate";
     /** Ready-delay seconds left; only meaningful for `ready`. */
     remainingSeconds?: number;
     queued?: boolean;

package/bin/commands/next-check.mjs

@@ -3,11 +3,13 @@ export const MERGE_QUEUE_RECHECK_SECONDS = 300;
 /** Backstop for a missed GitHub event; events normally wake the session long before this. */
 export const SAFETY_NET_SECONDS = 3000;
 /** The earliest candidate as a `NextCheck`, with `at` rounded up to a whole minute. */
-export function earliestNextCheck(candidates, nowMs = Date.now()) {
+export function earliestNextCheck(candidates, nowMs = Date.now(), minimumSeconds = 0) {
     const first = [...candidates].sort((a, b) => a.seconds - b.seconds)[0];
     if (!first)
         return undefined;
-    const atMs = Math.ceil((nowMs + Math.max(0, first.seconds) * 1000) / 60_000) * 60_000;
+    // A quota warning's interval is a floor: no wake-up may come sooner than it permits.
+    const seconds = Math.max(0, first.seconds, minimumSeconds);
+    const atMs = Math.ceil((nowMs + seconds * 1000) / 60_000) * 60_000;
     return {
         at: new Date(atMs).toISOString().replace(/\.\d{3}Z$/, "Z"),
         inSeconds: Math.max(0, Math.round((atMs - nowMs) / 1000)),

package/bin/commands/poll-progress.mjs

@@ -53,7 +53,7 @@ export function writeWaitProgress(opts) {
 export function writeDebounceProgress(tick, elapsedMs, remainingMs) {
     const elapsedSeconds = Math.round(elapsedMs / 1000);
     const remainingSeconds = Math.round(remainingMs / 1000);
-    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] TRIAGE — debounce ${remainingSeconds}s remaining\n`);
 }
 export function writeRuleAutoResolveProgress(result) {
     if (result.ruleAutoResolve?.summary)

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -25,7 +25,7 @@ export function explicitInstructions(result) {
         ];
     }
     if (result.reason === "waiting" || result.reason === "timeout") {
-        return ["1. Run this aggregate selector again when the caller is ready to recheck."];
+        return ["1. Run this aggregate command again when the caller is ready to recheck."];
     }
     const instructions = [
         "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",

package/bin/commands/poll-summary-instructions.mjs

@@ -24,7 +24,7 @@ export function planPollSummary(result, mergeRequested) {
             const layer = needsOwnSession
                 ? {
                     ...item,
-                    action: "fix_code",
+                    action: "triage",
                     reasons: [
                         ...item.reasons,
                         staleChildren.has(item.pr) ? "stale-ancestry" : "ready-receipt-required",
@@ -108,8 +108,8 @@ function planStack(result, mergeRequested) {
         if (ownedWork) {
             const rerun = onlyDraftReadinessVerification(work.sessions, work.idle) &&
                 work.sessions.every((item) => item.owned)
-                ? "If every listed one-PR probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, report the human handoff above and stop this selector. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same `--stack` selector when that work completes."
-                : "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.";
+                ? "If every listed one-PR probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, report the human handoff above and stop this `stack` command. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same `stack` command when that work completes."
+                : "After the listed one-PR sessions, rerun this same `stack` command. Stop for the human handoff only when no autonomous shepherding remains.";
             appendStackRerunInstruction(instructions, runnableCandidates, rerun);
         }
         return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
@@ -129,7 +129,7 @@ function planStack(result, mergeRequested) {
                 instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${ownedWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
             }
             if (ownedWork) {
-                appendStackRerunInstruction(instructions, runnableCandidates, "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
+                appendStackRerunInstruction(instructions, runnableCandidates, "After the listed one-PR sessions, rerun this same `stack` command. Stop for the human handoff only when no autonomous shepherding remains.");
             }
             return { action: ownedWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
@@ -149,10 +149,10 @@ function planStack(result, mergeRequested) {
         appendAutonomousInstructions(instructions, work.sessions);
         if (onlyDraftReadinessVerification(work.sessions, work.idle) &&
             work.sessions.every((item) => item.owned)) {
-            instructions.push(`${instructions.length + 1}. If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop shepherding this stack and leave those drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same \`--stack\` selector when that work completes.`);
+            instructions.push(`${instructions.length + 1}. If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop shepherding this stack and leave those drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same \`stack\` command when that work completes.`);
             return { action: "shepherd", stackMergeable: false, instructions };
         }
-        const action = appendStackRerunInstruction(instructions, work.sessions, "After the selected one-PR sessions, rerun this same `--stack` selector.");
+        const action = appendStackRerunInstruction(instructions, work.sessions, "After the selected one-PR sessions, rerun this same `stack` command.");
         return { action, stackMergeable: false, instructions };
     }
     if (open.some((item) => item.isInMergeQueue)) {
@@ -176,7 +176,7 @@ function planStack(result, mergeRequested) {
         const instructions = [];
         const sessions = open.filter((item) => item.action !== "cancel");
         appendAutonomousInstructions(instructions, sessions);
-        const action = appendStackRerunInstruction(instructions, sessions, "After the selected one-PR sessions, rerun this same `--stack` selector.");
+        const action = appendStackRerunInstruction(instructions, sessions, "After the selected one-PR sessions, rerun this same `stack` command.");
         return { action, stackMergeable, instructions };
     }
     return retargetWaitPlan(open[0]);

package/bin/commands/poll-summary.mjs

@@ -61,14 +61,14 @@ async function readPollSummaryTick(opts) {
         ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
         ...(fetched.allowedMergeMethods && { allowedMergeMethods: fetched.allowedMergeMethods }),
     }, opts.merge === true);
-    const result = await applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
+    const result = await applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate["stall-timeout-minutes"] * 60);
     return { result, repo, ...(fetched.handoffSource && { handoffSource: fetched.handoffSource }) };
 }
 async function runAggregatePollCore(opts) {
     const intervalMs = Math.min(opts.intervalSeconds * 1000, MAX_TIMER_MS);
     const timeoutMs = Math.min(opts.timeoutSeconds * 1000, MAX_TIMER_MS);
     const debounceMs = Math.min((opts.debounceSeconds ?? 60) * 1000, MAX_TIMER_MS);
-    const quotaBands = loadConfig().watch.graphqlQuotaWarnings;
+    const quotaBands = loadConfig().quotaWarningBands;
     const start = Date.now();
     let tick = 0;
     let debounceUntil = null;
@@ -139,7 +139,7 @@ async function runAggregatePollCore(opts) {
             : last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
         const hasFix = last.selection.kind === "stack"
             ? last.nextAction === "shepherd" && last.reason !== "waiting"
-            : last.prs.some((item) => item.action === "fix_code");
+            : last.prs.some((item) => item.action === "triage");
         const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
         pendingQuotaWarning = carryQuotaWarning(pendingQuotaWarning, warning);
         if (allTerminal) {
@@ -205,7 +205,7 @@ function attachUsage(result, mergeRequested) {
     const enriched = apiUsage ? { ...result, apiUsage } : result;
     // A disappeared native stack is an aggregate-level terminal handoff. Keep
     // that explicit escalation intact even when the one-PR fallback contains
-    // open orphan rows that would otherwise be re-planned as fix_code.
+    // open orphan rows that would otherwise be re-planned as triage.
     if (enriched.selection.kind === "stack" && enriched.nextAction === "escalate") {
         return enriched;
     }

package/bin/commands/poll.d.mts

@@ -2,7 +2,7 @@ import type { IterateCommandOptions, IterateResult } from "../types.mts";
 export interface PollCommandOptions extends IterateCommandOptions {
     intervalSeconds: number;
     timeoutSeconds: number;
-    /** Settle window after first FIX_CODE before returning. Default 60. 0 disables. */
+    /** Settle window after first TRIAGE before returning. Default 60. 0 disables. */
     debounceSeconds?: number;
     quietStatus?: boolean;
     untilTerminal?: boolean;

package/bin/commands/poll.mjs

@@ -21,7 +21,7 @@ async function runPollCore(opts) {
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
     const debounceSeconds = debounceSecondsOpt ?? DEFAULT_POLL_DEBOUNCE_SECONDS;
     const debounceMs = Math.min(debounceSeconds * 1000, MAX_TIMER_MS);
-    const quotaBands = loadConfig().watch.graphqlQuotaWarnings;
+    const quotaBands = loadConfig().quotaWarningBands;
     const start = Date.now();
     let tick = 0;
     let lastResult;
@@ -82,10 +82,10 @@ async function runPollCore(opts) {
         };
         if (untilTerminal &&
             pendingQuotaWarning !== undefined &&
-            !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
+            !(lastResult.action === "triage" && debounceSeconds > 0 && !pastDebounce) &&
             !(debounceUntil !== null && !pastDebounce)) {
             await refreshIfReturning();
-            if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+            if (lastResult.action === "triage" && debounceSeconds > 0 && !pastDebounce) {
                 debounceUntil ??= Date.now() + debounceMs;
                 const remainingMs = Math.max(debounceUntil - Date.now(), 0);
                 writeRuleAutoResolveProgress(lastResult);
@@ -142,7 +142,7 @@ async function runPollCore(opts) {
             await sleep(sleepMs);
             continue;
         }
-        if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+        if (lastResult.action === "triage" && debounceSeconds > 0 && !pastDebounce) {
             writeRuleAutoResolveProgress(lastResult);
             debounceUntil ??= Date.now() + debounceMs;
             const remainingMs = debounceUntil - Date.now();

package/bin/commands/resolve-mutate.d.mts

@@ -1,4 +1,4 @@
 import type { ResolveOptions } from "../types.mts";
 import type { ResolveCommandOptions } from "./resolve.mts";
-/** @deprecated Hidden implementation for `resolve`; use `apply review`. */
+/** Implementation for `apply review`. */
 export declare function runResolveMutate(opts: ResolveCommandOptions & ResolveOptions): Promise<import("../comments/resolve.mts").ResolveResult>;

package/bin/commands/resolve-mutate.mjs

@@ -7,7 +7,7 @@ import { threadTranscriptBodies } from "../threads/transcript.mjs";
 import { addPrShepherdMarker } from "../comments/marker.mjs";
 import { adoptedReplyThreads } from "../comments/uncertain-replies.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
-/** @deprecated Hidden implementation for `resolve`; use `apply review`. */
+/** Implementation for `apply review`. */
 export async function runResolveMutate(opts) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());

package/bin/commands/rest-stack-merge-readiness.mjs

@@ -70,5 +70,5 @@ function guardMember(member) {
     };
 }
 function fail(message) {
-    throw new ShepherdError(`${message}; rerun the --stack --merge selector before applying this request`, EXIT.UNAVAILABLE);
+    throw new ShepherdError(`${message}; rerun \`pr-shepherd stack <PR> --merge\` before applying this request`, EXIT.UNAVAILABLE);
 }

package/bin/commands/single-tick.d.mts

@@ -0,0 +1,5 @@
+/**
+ * True when a looping command (the default command, `stack`) runs one tick instead of
+ * sleeping: inside a Claude Code cloud session, where the session owns the next wake-up.
+ */
+export declare function runsSingleTick(): boolean;

package/bin/commands/single-tick.mjs

@@ -0,0 +1,7 @@
+/**
+ * True when a looping command (the default command, `stack`) runs one tick instead of
+ * sleeping: inside a Claude Code cloud session, where the session owns the next wake-up.
+ */
+export function runsSingleTick() {
+    return process.env["CLAUDE_CODE_REMOTE"] === "true";
+}

package/bin/commands/stack-drain.mjs

@@ -92,7 +92,7 @@ export function planPrefixDrain(result, mergeRequested) {
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);
-    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`--stack --merge\` selector; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
+    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`stack --merge\` command; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
     return {
         action: "merge",
         stackMergeable: gaps.length === 0 && open.every(isStackLayerReady),

package/bin/commands/stack-merge-flag.mjs

@@ -2,5 +2,5 @@ import { loadConfig } from "../config/load.mjs";
 import { configuredMergeMethod, mergeMethodFlag, } from "../config/merge-method.mjs";
 /** Stack commands prefer squash unless config or the repository selects another method. */
 export function stackMergeFlag(allowed) {
-    return mergeMethodFlag(allowed, "squash", configuredMergeMethod(loadConfig().merge ?? {}));
+    return mergeMethodFlag(allowed, "squash", configuredMergeMethod(loadConfig().merge));
 }

package/bin/commands/stack-stall.d.mts

@@ -1,6 +1,6 @@
 import type { PollSummaryItem, PollSummaryResult } from "../types.mts";
 /**
- * A `--stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
+ * A `stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
  * stall guards cannot fire. Escalate `stall-timeout` once that idle plan's fingerprint stays
  * unchanged for `stallTimeoutSeconds`; any other plan, or `0`, clears the timer. When the enabled
  * timer cannot be read or written, escalate `stall-state-unavailable` instead of restarting it.
@@ -14,6 +14,6 @@ export declare function applyStackStallGuard(planned: {
 }, stallTimeoutSeconds: number): Promise<PollSummaryResult>;
 /**
  * Unix seconds when an unchanged idle stack plan trips `stall-timeout`, or undefined when no
- * stack timer is running. Event mode schedules its next tick no later than this.
+ * stack timer is running. A single tick schedules its next tick no later than this.
  */
 export declare function readStackStallDeadline(result: PollSummaryResult, stallTimeoutSeconds: number): Promise<number | undefined>;

package/bin/commands/stack-stall.mjs

@@ -3,7 +3,7 @@ import { formatDurationApprox } from "./iterate/escalate.mjs";
 import { summaryStatusSignature } from "./poll-summary-signature.mjs";
 import { describeIdleLayers } from "./stack-drain.mjs";
 /**
- * A `--stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
+ * A `stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
  * stall guards cannot fire. Escalate `stall-timeout` once that idle plan's fingerprint stays
  * unchanged for `stallTimeoutSeconds`; any other plan, or `0`, clears the timer. When the enabled
  * timer cannot be read or written, escalate `stall-state-unavailable` instead of restarting it.
@@ -44,7 +44,7 @@ export async function applyStackStallGuard(planned, repo, stallTimeoutSeconds) {
 }
 /**
  * Unix seconds when an unchanged idle stack plan trips `stall-timeout`, or undefined when no
- * stack timer is running. Event mode schedules its next tick no later than this.
+ * stack timer is running. A single tick schedules its next tick no later than this.
  */
 export async function readStackStallDeadline(result, stallTimeoutSeconds) {
     const [owner, repo] = result.repo.split("/");

package/bin/commands/stack-work.d.mts

@@ -1,5 +1,5 @@
 import type { PollSummaryItem } from "../types.mts";
-/** How the stack selector routes the autonomous layers that still need work. */
+/** How the stack command routes the autonomous layers that still need work. */
 export interface StackWork {
     /** Layers that need a one-PR Shepherd session, with or without a known command. */
     sessions: PollSummaryItem[];
@@ -18,7 +18,7 @@ export declare function onlyDraftReadinessVerification(sessions: PollSummaryItem
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
 /**
- * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
+ * The closing step after routed sessions: rerun the stack command, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
  */
 export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string): "shepherd" | "escalate";

package/bin/commands/stack-work.mjs

@@ -29,14 +29,14 @@ function isProbed(item) {
     return item.pollProbe === true && item.pollCommand !== undefined;
 }
 /**
- * Work exists, but every routed layer belongs to another author: rerunning the stack selector
+ * Work exists, but every routed layer belongs to another author: rerunning the stack command
  * cannot change anything, so the caller reports the overview and stops instead.
  */
 function onlyUnownedWork(layers) {
     return layers.length > 0 && layers.every((item) => !item.owned);
 }
 /**
- * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
+ * The closing step after routed sessions: rerun the stack command, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
  */
 export function appendStackRerunInstruction(instructions, layers, rerun) {

package/bin/commands/suggestion-patch-item.d.mts

@@ -10,6 +10,5 @@ export declare function buildSuggestionPatchItem({ thread, request, originalCont
     request: SuggestionPatchRequest;
     originalContent: string;
 }): SuggestionPatchResult;
-export declare function buildSingularInstructions(patch: SuggestionPatchResult, prReference: string | number): string[];
 export declare function buildCommitCommand(patch: SuggestionPatchResult): string;
 export declare function quotePath(path: string): string;

package/bin/commands/suggestion-patch-item.mjs

@@ -61,18 +61,6 @@ export function buildSuggestionPatchItem({ thread, request, originalContent, })
         filesToStage: [thread.path],
     };
 }
-export function buildSingularInstructions(patch, prReference) {
-    const range = patch.startLine === patch.endLine
-        ? `line ${patch.startLine}`
-        : `lines ${patch.startLine}–${patch.endLine}`;
-    return [
-        `Apply the patch to \`${patch.path}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
-        `Stage the file: \`git add -- ${quotePath(patch.path)}\``,
-        `Commit: \`${buildCommitCommand(patch)}\``,
-        `Use the originating iterate output for any authorization-checked GitHub review action for thread \`${patch.threadId}\` on ${String(prReference)}.`,
-        "Shepherd cannot verify authorization for the Git credential that would push this branch, so this output does not recommend a push.",
-    ];
-}
 export function buildCommitCommand(patch) {
     return [
         "git commit",

package/bin/commands/suggestion-patches.d.mts

@@ -1,6 +1,6 @@
-import type { BuildSuggestionPatchesResult, GlobalOptions } from "../types.mts";
+import type { SuggestResult, GlobalOptions } from "../types.mts";
 import { type SuggestionPatchRequest } from "./suggestion-patch-item.mts";
 export interface SuggestionPatchesOptions extends GlobalOptions {
     suggestions: readonly SuggestionPatchRequest[];
 }
-export declare function runSuggestionPatches(opts: SuggestionPatchesOptions): Promise<BuildSuggestionPatchesResult>;
+export declare function runSuggestionPatches(opts: SuggestionPatchesOptions): Promise<SuggestResult>;

package/bin/commands/suggestion-patches.mjs

@@ -21,7 +21,7 @@ export async function runSuggestionPatches(opts) {
     const status = await getPathsStatus(paths);
     if (status !== "") {
         throw new ShepherdError(`Suggestion target files have uncommitted changes:\n${status}\n` +
-            "Commit or stash them before running build-suggestion-patches.", EXIT.UNAVAILABLE);
+            "Commit or stash them before running suggest.", EXIT.UNAVAILABLE);
     }
     const originals = await readOriginals(data.headRefOid, paths);
     const patches = threads.map((thread, index) => buildSuggestionPatchItem({

package/bin/commands/tick-instructions.d.mts

@@ -0,0 +1,9 @@
+import type { NextCheck } from "../types/next-check.mts";
+/**
+ * Steps for a single tick whose PR is waiting: end the turn, keep one wake-up, and let the
+ * next tick come from a PR event or the wake-up. Always printed after any state-specific
+ * sentence.
+ */
+export declare function tickWaitSteps(next: NextCheck): string[];
+/** One aggregate step: sessions still run first, and only then does the turn end. */
+export declare function tickAggregateStep(next: NextCheck, waiting: boolean): string;

package/bin/commands/tick-instructions.mjs

@@ -0,0 +1,23 @@
+import { playbookPointer } from "./playbook-pointer.mjs";
+function wakeUpClause(next) {
+    const kind = next.reason === "safety-net" ? "safety-net wake-up" : "wake-up";
+    return `Keep exactly one ${kind} at \`${next.at}\` (\`${next.reason}\`).`;
+}
+/**
+ * Steps for a single tick whose PR is waiting: end the turn, keep one wake-up, and let the
+ * next tick come from a PR event or the wake-up. Always printed after any state-specific
+ * sentence.
+ */
+export function tickWaitSteps(next) {
+    return [
+        `End this turn now without sleeping or polling. ${playbookPointer("Event loop")}`,
+        `${wakeUpClause(next)} When a PR event or that wake-up arrives, rerun this command with the same options and act only on Shepherd's output, never on the event payload.`,
+    ];
+}
+/** One aggregate step: sessions still run first, and only then does the turn end. */
+export function tickAggregateStep(next, waiting) {
+    const lead = waiting
+        ? "End this turn now without sleeping or polling."
+        : "Once the steps above are done and the rerun still waits, end the turn without sleeping.";
+    return `${lead} ${wakeUpClause(next)} When a PR event or that wake-up arrives, rerun this command with the same options and act only on Shepherd's output, never on the event payload. ${playbookPointer("Event loop")}`;
+}

package/bin/commands/tick.d.mts

@@ -0,0 +1,15 @@
+import type { IterateCommandOptions, IterateResult, PollSummaryCommandOptions, PollSummaryResult } from "../types.mts";
+import { type PollCommandOptions } from "./poll.mts";
+import { type AggregatePollCommandOptions } from "./poll-summary.mts";
+/**
+ * One iterate tick: no settle window and no sleeping, seen markers persist immediately, and
+ * `nextCheck` reports when to come back if no GitHub event arrives first. The tick's result is
+ * never discarded, so edited-comment markers are written on the result it returns.
+ */
+export declare function runIterateTick(opts: IterateCommandOptions): Promise<IterateResult>;
+/** One aggregate tick, with `nextCheck` unless nothing remains to wait for. */
+export declare function runPollSummaryTick(opts: PollSummaryCommandOptions): Promise<PollSummaryResult>;
+/** The default command: the sleeping loop, or one tick in a cloud session. */
+export declare function runPollCommand(opts: PollCommandOptions): Promise<IterateResult>;
+/** The aggregate loop (`stack`, several PRs), or one tick in a cloud session. */
+export declare function runAggregatePollCommand(opts: AggregatePollCommandOptions): Promise<PollSummaryResult>;