pr-shepherd 0.60.1 → 1.1.0

package/bin/commands/iterate/index.mjs

@@ -8,7 +8,7 @@ import { buildWaitLog, buildTerminalCancelResult, blockedCancelNote } from "./he
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
-import { handleFixCode } from "./fix-code.mjs";
+import { handleTriage } from "./triage.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
 import { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
@@ -60,24 +60,21 @@ async function attachEditedComments(result, tick, opts) {
 }
 async function runIterateCore(opts, tick) {
     const config = loadConfig();
-    const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
-    const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
+    const botUsernames = normalizeBotUsernames(config["bot-usernames"]);
+    const readyDelaySeconds = opts.readyDelaySeconds ?? config.iterate["ready-delay-minutes"] * 60;
+    const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate["stall-timeout-minutes"] * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
-    const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
     const checkContext = createCheckExecutionContext(readyDelaySeconds);
     const report = await runCheck({
         ...opts,
         prNumber,
-        // Outdated Shepherd-visible threads are always resolved by iterate. The
-        // old actions.autoResolveOutdated switch is retained only as an ignored
-        // compatibility key in the config loader.
+        // Outdated Shepherd-visible threads are always resolved by iterate.
         autoResolve: true,
-        autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
-        reviewOutputMaxChars: config.iterate.reviewOutputMaxChars,
+        autoMinimizeSuppressed: config.actions["auto-minimize-suppressed"],
+        reviewOutputMaxChars: config.iterate["review-output-max-chars"],
     }, checkContext);
     tick.report = report;
     const [repoOwner, repoName] = report.repo.split("/");
@@ -107,7 +104,7 @@ async function runIterateCore(opts, tick) {
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
-    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [
+    }, report.approvedReviews, config.iterate["minimize-approvals"], config.iterate["minimize-comments"], botUsernames, [
         ...report.threads.actionable,
         ...report.threads.resolutionOnly,
         ...(report.heldThreadReviewIds ?? []).map((reviewId) => ({ reviewId })),
@@ -128,7 +125,7 @@ async function runIterateCore(opts, tick) {
     }
     // A first look at an already-minimized comment is only an acknowledgment. Edited PR comments
     // (report.comments.edited) are neither: they never block readiness or restart the ready delay.
-    // Review items held back by iterate.reviewOutputMaxChars keep the PR out of ready/merge: a
+    // Review items held back by iterate.review-output-max-chars keep the PR out of ready/merge: a
     // capped tick that shows only first-look comments still counts, since held work follows.
     const hasReadinessWork = (report.reviewItems !== undefined && report.comments.firstLook.length > 0) ||
         report.threads.actionable.length > 0 ||
@@ -142,7 +139,7 @@ async function runIterateCore(opts, tick) {
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
-        (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
+        (config.iterate["minimize-approvals"] && surfacedApprovals.length > 0);
     const hasActionableWork = hasReadinessWork || report.comments.firstLook.length > 0;
     const activeMerge = Boolean(opts.merge &&
         (report.mergeQueue?.inQueue ||
@@ -183,12 +180,12 @@ async function runIterateCore(opts, tick) {
     const checkDrivenActionableWork = hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status);
     const deferWhileQueued = opts.merge === true &&
         report.mergeQueue?.inQueue === true &&
-        config.actions.workWhileQueued !== true;
+        config.actions["work-while-queued"] !== true;
     if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
-        return handleFixCode({
+        return handleTriage({
             base,
             report: reportForWork,
-            opts: { ...opts, prNumber, neverCancelRuns },
+            opts: { ...opts, prNumber },
             headSha,
             stallKey,
             prNumber,
@@ -208,10 +205,10 @@ async function runIterateCore(opts, tick) {
         });
     }
     if (unreportedRepair.length > 0 && staleAncestry) {
-        return handleFixCode({
+        return handleTriage({
             base,
             report: reportForWork,
-            opts: { ...opts, prNumber, neverCancelRuns },
+            opts: { ...opts, prNumber },
             headSha,
             stallKey,
             prNumber,
@@ -241,15 +238,15 @@ async function runIterateCore(opts, tick) {
         firstLookSummaries,
         editedSummaries,
         surfacedApprovals,
-        minimizeApprovals: config.iterate.minimizeApprovals,
+        minimizeApprovals: config.iterate["minimize-approvals"],
     });
     if (mergeStateResult)
         return annotateBlockedWait(mergeStateResult, blockerGate);
     if (staleAncestry) {
-        return handleFixCode({
+        return handleTriage({
             base,
             report: reportForWork,
-            opts: { ...opts, prNumber, neverCancelRuns },
+            opts: { ...opts, prNumber },
             headSha,
             stallKey,
             prNumber,
@@ -287,7 +284,7 @@ async function runIterateCore(opts, tick) {
             escalate: { ...escalation, humanMessage: buildEscalateHumanMessage(escalation, report.pr) },
         };
     }
-    const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
+    const autoMarkReady = !opts.noAutoMarkReady && config["mark-ready"].auto;
     if (canMarkReady && !autoMarkReady) {
         await clearReadyDelay(report.pr, repoOwner, repoName);
         await clearStallState(stallKey);
@@ -307,7 +304,7 @@ async function runIterateCore(opts, tick) {
         const receipt = receiptCurrent
             ? "written"
             : await recordReadyReceipt(receiptKey, report, checkContext);
-        // Aggregate --stack routing trusts only a layer's receipt, so an unwritten
+        // Aggregate `stack` routing trusts only a layer's receipt, so an unwritten
         // one keeps the elapsed marker and retries next tick. A one-PR receipt
         // only lets a rerun skip the wait, so its failure never changes the action.
         // A layer GitHub reports BLOCKED gets no receipt, so aggregate routing

package/bin/commands/iterate/merge-plan.mjs

@@ -7,7 +7,7 @@ import { getGithubTransport } from "../../github/transport.mjs";
 const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
 export function buildMergeCommandPlan(input) {
     if (input.transport === "rest" || getGithubTransport() === "rest") {
-        const configured = configuredMergeMethod(loadConfig().merge ?? {});
+        const configured = configuredMergeMethod(loadConfig().merge);
         if (!input.queue && input.queueKnown !== true && configured)
             return {
                 unavailable: "REST cannot verify merge-queue policy and cannot apply a configured direct merge method to an automatic merge request. Refresh branch policy before merging.",
@@ -70,10 +70,10 @@ export function buildMergeCommandPlan(input) {
         };
     }
     const mergeConfig = loadConfig().merge;
-    const configuredArgs = mergeConfig?.commandArgs ?? [];
+    const configuredArgs = mergeConfig["command-args"];
     const decision = chooseMergeMethod({
         allowed: input.allowedMergeMethods,
-        configured: configuredMergeMethod(mergeConfig ?? {}),
+        configured: configuredMergeMethod(mergeConfig),
         fallback: "merge",
     });
     if ("unavailable" in decision)

package/bin/commands/iterate/merge-state.mjs

@@ -6,14 +6,14 @@ import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { inlineCode } from "../../util/markdown.mjs";
 /**
  * A one-PR poll cannot prove the layers below it merged or that its PR number is a safe merge
- * selector. Route it through the aggregate stack selector, which merges one bottom layer at a time.
+ * selector. Route it through the aggregate stack command, which merges one bottom layer at a time.
  */
 function buildStackedRouteResult(base, report, stack) {
     const prUrl = formatPrUrl(report.repo, report.pr);
     return {
         ...base,
-        action: "fix_code",
-        fix: {
+        action: "triage",
+        triage: {
             threads: [],
             resolutionOnlyThreads: [],
             actionableComments: [],
@@ -31,14 +31,11 @@ function buildStackedRouteResult(base, report, stack) {
             },
             instructions: [
                 `PR #${report.pr} is layer ${stack.position} of ${stack.size} in native stack #${stack.number}; do not run \`gh pr merge\` for this layer.`,
-                `Run ${inlineCode(buildPrShepherdCommand(["--stack", prUrl, "--until-terminal", "--merge"]).text)} to reconcile the stack and run each bottom-layer merge command it emits.`,
+                `Run ${inlineCode(buildPrShepherdCommand(["stack", prUrl, "--until-terminal", "--merge"]).text)} to reconcile the stack and run each bottom-layer merge command it emits.`,
             ],
-            inProgressRunIds: [],
-            protectedRuns: [],
             firstLookThreads: [],
             firstLookComments: [],
         },
-        cancelled: [],
     };
 }
 export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -15,7 +15,7 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
             : "trunk" in start
                 ? `trunk \`${start.trunk}\``
                 : `bottom open layer PR #${start.bottomPr}`;
-        return `Use the repository's stack-update procedure for native stack #${stackNumber} in \`${repo}\`, starting at ${boundary} and preserving the ordered parent boundaries of every affected upper layer. Read membership with REST-backed Shepherd \`--stack\` output and update and push affected branches using the caller's git workflow. ${playbookPointer("Branch update")}`;
+        return `Use the repository's stack-update procedure for native stack #${stackNumber} in \`${repo}\`, starting at ${boundary} and preserving the ordered parent boundaries of every affected upper layer. Read membership with REST-backed Shepherd \`stack\` output and update and push affected branches using the caller's git workflow. ${playbookPointer("Branch update")}`;
     }
     const [checkout, command] = "parentBranch" in start
         ? [

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

@@ -7,7 +7,7 @@ import type { InstructionStyle } from "../../config/load.mts";
  * if it is not. `apply review` reads that HEAD itself with a read-only `git rev-parse HEAD`.
  */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
-export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, _cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], _inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behind-base-hint — see buildBehindBaseHintInstruction
 isBehind?: boolean, _viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection?: QueueEjectionRecovery, // current merge-queue removal with failing queue checks
 instructionStyle?: InstructionStyle): string[];

package/bin/commands/iterate/render.mjs

@@ -5,7 +5,7 @@ import { buildCommitSuggestionInstruction } from "../commit-suggestion-instructi
 import { partitionFixThreads } from "./fix-instruction-threads.mjs";
 import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
 import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
-import { buildPushSteps } from "./fix-loop-instruction.mjs";
+import { buildPushSteps } from "./triage-loop-instruction.mjs";
 /**
  * Render a resolve command as a shell snippet. Appends `--require-sha HEAD` when set: run after
  * the push step, the local HEAD is the pushed PR head, and `apply review` rejects the mutations
@@ -16,7 +16,7 @@ export function renderResolveCommand(rc) {
     return rc.requiresHeadSha ? `${command} ${REQUIRE_HEAD_SHA}` : command;
 }
 const REQUIRE_HEAD_SHA = "--require-sha HEAD";
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, _cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], _inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behind-base-hint — see buildBehindBaseHintInstruction
 isBehind = false, _viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection, // current merge-queue removal with failing queue checks
 instructionStyle = "inline") {

package/bin/commands/iterate/stall.mjs

@@ -5,25 +5,27 @@ import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationAppro
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 function pendingReviewCommandsFromResult(result) {
-    if (result.action !== "fix_code")
+    if (result.action !== "triage")
         return undefined;
     const pending = {
-        ...(result.fix.resolveOnlyCommand?.hasMutations && {
-            resolveOnlyCommand: result.fix.resolveOnlyCommand,
+        ...(result.triage.resolveOnlyCommand?.hasMutations && {
+            resolveOnlyCommand: result.triage.resolveOnlyCommand,
+        }),
+        ...(result.triage.resolveCommand.hasMutations && {
+            resolveCommand: result.triage.resolveCommand,
         }),
-        ...(result.fix.resolveCommand.hasMutations && { resolveCommand: result.fix.resolveCommand }),
     };
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 function surfacedSummariesFromResult(result) {
-    if (result.action !== "fix_code")
+    if (result.action !== "triage")
         return {};
     return {
-        ...(result.fix.firstLookSummaries.length > 0 && {
-            firstLookSummaries: result.fix.firstLookSummaries,
+        ...(result.triage.firstLookSummaries.length > 0 && {
+            firstLookSummaries: result.triage.firstLookSummaries,
         }),
-        ...(result.fix.editedSummaries.length > 0 && {
-            editedSummaries: result.fix.editedSummaries,
+        ...(result.triage.editedSummaries.length > 0 && {
+            editedSummaries: result.triage.editedSummaries,
         }),
     };
 }

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

@@ -1,7 +1,7 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { playbookPointer } from "../playbook-pointer.mjs";
-const FIX_CODE_LOOP_PLAYBOOK = "Fix-code loop";
+const TRIAGE_LOOP_PLAYBOOK = "Triage loop";
 /** The generic push stays separate from conflict and queue-recovery push instructions. */
 export function buildPushSteps(style, genericPush) {
     if (!genericPush)
@@ -9,6 +9,10 @@ export function buildPushSteps(style, genericPush) {
     const push = "Commit and push any changes.";
     if (style === "inline")
         return [push];
-    const cli = renderShellCommand([...loadConfig().cliCommand, "playbook", FIX_CODE_LOOP_PLAYBOOK]);
-    return [`${push} ${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`];
+    const cli = renderShellCommand([
+        ...loadConfig()["cli-command"],
+        "playbook",
+        TRIAGE_LOOP_PLAYBOOK,
+    ]);
+    return [`${push} ${playbookPointer(TRIAGE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`];
 }

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

@@ -1,6 +1,6 @@
 import type { IterateCommandOptions, IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
 import type { NormalizedBotUsernames } from "../../comments/authors.mts";
-interface HandleFixCodeContext {
+interface HandleTriageContext {
     base: IterateResultBase;
     report: ShepherdReport;
     opts: IterateCommandOptions;
@@ -25,5 +25,5 @@ interface HandleFixCodeContext {
     /** Verified stack-repair guidance, when ancestry is stale. */
     repairInstructions?: string[];
 }
-export declare function handleFixCode(ctx: HandleFixCodeContext): Promise<IterateResult>;
+export declare function handleTriage(ctx: HandleTriageContext): Promise<IterateResult>;
 export {};

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-signature.d.mts

@@ -1,2 +1,8 @@
 import type { PollSummaryResult } from "../types.mts";
+/**
+ * Decision-relevant state only. Raw review totals and the ignored, skipped, filtered, and
+ * superseded check counts move when rules suppress a bot notice or a bot reposts a status
+ * check, which would reprint quiet polls and keep an idle stack from reaching `stall-timeout`.
+ * Post-rule `actionable` and the check transitions that drive routing stay in.
+ */
 export declare function summaryStatusSignature(result: PollSummaryResult): string;