pr-shepherd 0.34.0 → 0.35.0

package/bin/state/iterate-stall.d.mts

@@ -0,0 +1,27 @@
+/**
+ * Persistent stall-detection state for the iterate loop.
+ *
+ * Tracks the fingerprint of the last iterate result and when that fingerprint
+ * was first seen. If the fingerprint does not change for stallTimeoutSeconds
+ * the iterate command escalates instead of repeating the same action.
+ *
+ * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/iterate-stall.json`.
+ */
+interface StallState {
+    /** Canonicalized JSON fingerprint of the material iterate inputs. */
+    fingerprint: string;
+    /** Unix timestamp (seconds) when this fingerprint was first seen. */
+    firstSeenAt: number;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+/** Read the current stall state. Returns null on miss, corrupt data, or invalid shape. */
+export declare function readStallState(key: StateKey): Promise<StallState | null>;
+/** Clear stall state so the next invocation starts a fresh timer (fire-and-forget — never throws). */
+export declare function clearStallState(key: StateKey): Promise<void>;
+/** Write stall state (fire-and-forget — never throws). */
+export declare function writeStallState(key: StateKey, state: StallState): Promise<void>;
+export {};

package/bin/state/seen-comments.d.mts

@@ -0,0 +1,62 @@
+export interface SeenMarker {
+    seenAt: number;
+    id?: string;
+    [key: string]: unknown;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+/** Compute a 16-hex-char SHA-256 prefix of a comment body. */
+export declare function hashBody(body: string): string;
+/**
+ * Classify a candidate item against the seen map.
+ *
+ * - "new"       — no marker exists; surface the body and write the marker.
+ * - "edited"    — marker exists but stored hash differs from the current body;
+ *                 surface the updated body and update the marker hash.
+ * - "unchanged" — marker exists and hash matches (or marker has no hash, which
+ *                 is treated conservatively as unchanged).
+ */
+export declare function classifyItem(id: string, body: string, map: Map<string, SeenMarker>): "new" | "edited" | "unchanged";
+/**
+ * Read the seen/ directory once and return a Set of already-seen IDs.
+ * Prefer this over repeated hasSeen() calls to avoid EMFILE on large PRs.
+ * Returns an empty Set if the directory does not yet exist.
+ */
+export declare function loadSeenSet(key: StateKey): Promise<Set<string>>;
+/**
+ * Read the seen/ directory and return a Map from ID to SeenMarker.
+ * Used when the caller needs the stored bodyHash to detect in-place edits.
+ * Returns an empty Map if the directory does not yet exist.
+ *
+ * Map keys are the stored `id` field when present (guarding against
+ * case-insensitive filesystem collisions), falling back to the filename for
+ * legacy markers that predate this field.
+ */
+export declare function loadSeenMap(key: StateKey): Promise<Map<string, SeenMarker>>;
+/** Return true if a "seen" marker exists for this id. */
+export declare function hasSeen(key: StateKey, id: string): Promise<boolean>;
+/**
+ * Write (or update) a "seen" marker for this id, storing the body hash so
+ * in-place edits can be detected on future fetches.
+ *
+ * - First call (no existing marker): creates `{ seenAt: now, bodyHash, id }`.
+ * - Subsequent call, hash unchanged: no-op (skips the write).
+ * - Subsequent call, hash changed: updates `bodyHash`, preserves original `seenAt`.
+ *
+ * All errors are silently swallowed — the marker is best-effort.
+ */
+export declare function markSeen(key: StateKey, id: string, body: string): Promise<void>;
+export declare function markReviewInlineThreads(key: StateKey, reviewId: string, inlineThreadIds: readonly string[]): Promise<void>;
+/**
+ * Write a marker after Shepherd successfully replies to a review thread.
+ *
+ * `previousBody` suppresses stale GitHub fetches that have not yet included the new reply.
+ * `body` suppresses the expected final transcript once GitHub includes Shepherd's reply.
+ */
+export declare function markReplySeen(key: StateKey, id: string, previousBody: string, body: string, replyBody: string): Promise<void>;
+/** Read the full marker for inspection (returns null on miss or error). */
+export declare function readSeenMarker(key: StateKey, id: string): Promise<SeenMarker | null>;
+export {};

package/bin/suggestions/extract.d.mts

@@ -0,0 +1,8 @@
+import type { SuggestionBlock } from "../types.mts";
+export declare function extractSuggestion(thread: {
+    path: string | null;
+    line: number | null;
+    startLine: number | null;
+    body: string;
+    author: string;
+}): SuggestionBlock | null;

package/bin/suggestions/parse.d.mts

@@ -0,0 +1,48 @@
+/**
+ * Parse GitHub review-comment "suggestion" blocks.
+ *
+ * GitHub's "Commit suggestion" UI button treats the first ```suggestion fenced
+ * block in a review comment as a replacement for the commented line range.
+ * This module extracts that block from the comment body.
+ *
+ * There is no GitHub API for applying suggestions — tools that reproduce the
+ * button (this one included) must parse + commit themselves.
+ */
+interface ParsedSuggestion {
+    /**
+     * Replacement lines to splice in. Empty array means "delete these lines".
+     * `[""]` means "replace with a single blank line". Array length equals the
+     * number of replacement lines in the suggestion snippet (not the number of
+     * lines in the resulting file).
+     */
+    lines: readonly string[];
+}
+/**
+ * Return the first ```suggestion block from a review-comment body, or null if none.
+ *
+ * Handles three distinct cases:
+ *   - Empty block (` ```suggestion\n``` `) → `lines: []` (deletion).
+ *   - Blank-line-only body (` ```suggestion\n\n``` `) → `lines: [""]`.
+ *   - Non-empty body → split into lines.
+ *
+ * The opening fence may be 3+ backticks; the closing fence must be at least
+ * as many backticks, at the start of a line (after the captured prefix). This
+ * means content lines that contain ` ``` ` in the middle (not at line-start)
+ * are treated as content rather than a closing fence — fixing the silent
+ * truncation in the original regex approach (issue #68).
+ *
+ * When the block is embedded in a quoted reply (e.g. `> ```suggestion …`),
+ * the leading prefix captured from the opening fence is stripped from each
+ * body line — but only when that exact prefix is present, so legitimate `>`
+ * characters inside the suggested code survive.
+ */
+export declare function parseSuggestion(body: string): ParsedSuggestion | null;
+/**
+ * True when a parsed suggestion's replacement is safe to commit: the joined
+ * replacement contains no nested ` ```suggestion ` marker and no unmatched
+ * ` ``` ` run (odd count). Both shapes previously masked silent truncation
+ * (issue #68). Conservative by design: reviewers whose suggestion content
+ * legitimately includes these markers must apply the change manually.
+ */
+export declare function isCommittableSuggestion(parsed: ParsedSuggestion): boolean;
+export {};

package/bin/suggestions/patch.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Build a git-apply-compatible unified diff for a single suggestion hunk.
+ *
+ * The diff uses `--- a/<path>` / `+++ b/<path>` headers so `git apply` and
+ * `git apply --check` accept it without a `diff --git` preamble.
+ */
+export declare function buildUnifiedDiff({ path, originalContent, startLine, endLine, replacementLines, context, }: {
+    path: string;
+    originalContent: string;
+    startLine: number;
+    endLine: number;
+    replacementLines: readonly string[];
+    context?: number;
+}): string;

package/bin/threads/transcript.d.mts

@@ -0,0 +1,14 @@
+import type { ReviewThread, ReviewThreadComment } from "../types.mts";
+export declare function threadComments(thread: {
+    body: string;
+    author: string;
+    authorType?: ReviewThreadComment["authorType"];
+    authorAssociation?: ReviewThreadComment["authorAssociation"];
+    url?: string;
+    createdAtUnix?: number;
+    comments?: Array<Pick<ReviewThreadComment, "id" | "author" | "body" | "url"> & {
+        authorType?: ReviewThreadComment["authorType"];
+        authorAssociation?: ReviewThreadComment["authorAssociation"];
+    } & Partial<Pick<ReviewThreadComment, "isMinimized" | "createdAtUnix">>>;
+}): ReviewThreadComment[];
+export declare function threadTranscriptBody(thread: ReviewThread, appendedBodies?: string[]): string;

package/bin/threads/transcript.mjs

@@ -5,6 +5,7 @@ export function threadComments(thread) {
             isMinimized: c.isMinimized ?? false,
             author: c.author,
             authorType: c.authorType ?? "Unknown",
+            ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAtUnix ?? 0,
@@ -16,6 +17,9 @@ export function threadComments(thread) {
             isMinimized: false,
             author: thread.author,
             authorType: thread.authorType ?? "Unknown",
+            ...(thread.authorAssociation !== undefined && {
+                authorAssociation: thread.authorAssociation,
+            }),
             body: thread.body,
             url: thread.url ?? "",
             createdAtUnix: thread.createdAtUnix ?? 0,

package/bin/types/activity.d.mts

@@ -0,0 +1,30 @@
+import type { AuthorType, CheckStatus, CommentAuthorAssociation } from "./github.mts";
+type ReviewActivityKind = "pr-comment" | "review-thread-comment" | "review-summary" | "approved-review" | "changes-requested-review";
+export interface ReviewActivityItem {
+    kind: ReviewActivityKind;
+    id: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url?: string;
+    createdAtUnix: number;
+    threadId?: string;
+    path?: string | null;
+    line?: number | null;
+}
+export interface PrActivitySummary {
+    commitCount: number;
+    reviewRoundCount: number;
+    latestCommitCommittedAtUnix: number | null;
+    reviewItemsSinceLatestCommit: ReviewActivityItem[];
+}
+export interface ActiveCheck {
+    name: string;
+    status: CheckStatus;
+    runId: string | null;
+    detailsUrl: string | null;
+    workflowName?: string;
+    summary?: string;
+}
+export {};

package/bin/types/agent-thread.d.mts

@@ -0,0 +1,9 @@
+import type { AuthorType, CommentAuthorAssociation } from "./github.mts";
+export interface AgentThreadComment {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+}

package/bin/types/check-annotations.d.mts

@@ -0,0 +1,14 @@
+export interface CheckAnnotation {
+    /** Stable marker id used by Shepherd; prefixed to avoid collisions with comment/review IDs. */
+    id: string;
+    path: string;
+    startLine: number | null;
+    endLine: number | null;
+    startColumn?: number | null;
+    endColumn?: number | null;
+    level: string;
+    title?: string;
+    message: string;
+    rawDetails?: string;
+    blobUrl?: string;
+}

package/bin/types/check-classification.d.mts

@@ -0,0 +1,19 @@
+import type { CheckAnnotation } from "./check-annotations.mts";
+import type { CheckRun } from "./github.mts";
+type CheckCategory = "passed" | "failing" | "in_progress" | "skipped" | "filtered" | "ignored" | "superseded";
+export interface ClassifiedCheck extends CheckRun {
+    category: CheckCategory;
+}
+export interface TriagedCheck extends ClassifiedCheck {
+    /** Workflow display name (e.g. `"CI"`). Populated when available from the jobs API; may be `undefined` on fetch failure or when no matching job is found. */
+    workflowName?: string;
+    /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from the check name for matrix builds. */
+    jobName?: string;
+    /** Name of the first failed step in the matched job (e.g. `"Run tests"`). */
+    failedStep?: string;
+    /** Bounded raw excerpt from the matched failed job log, when GitHub exposes one. */
+    logExcerpt?: string;
+    /** Inline annotations attached to this failing check run, surfaced once per PR. */
+    annotations?: CheckAnnotation[];
+}
+export {};

package/bin/types/github.d.mts

@@ -0,0 +1,139 @@
+import type { ReviewThreadComment } from "./review-thread.mts";
+import type { PrActivitySummary } from "./activity.mts";
+export type CheckConclusion = "ACTION_REQUIRED" | "CANCELLED" | "FAILURE" | "NEUTRAL" | "SKIPPED" | "STALE" | "STARTUP_FAILURE" | "SUCCESS" | "TIMED_OUT" | null;
+export type CheckStatus = "COMPLETED" | "IN_PROGRESS" | "PENDING" | "QUEUED" | "REQUESTED" | "WAITING";
+export type MergeableState = "CONFLICTING" | "MERGEABLE" | "UNKNOWN";
+export type MergeStateStatus = "BEHIND" | "BLOCKED" | "CLEAN" | "DIRTY" | "DRAFT" | "HAS_HOOKS" | "UNKNOWN" | "UNSTABLE";
+export type ReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
+export type AuthorType = "User" | "Bot" | "Unknown";
+/** Raw relationship between a comment author and the repository, as reported by GitHub. */
+export type CommentAuthorAssociation = "COLLABORATOR" | "CONTRIBUTOR" | "FIRST_TIMER" | "FIRST_TIME_CONTRIBUTOR" | "MANNEQUIN" | "MEMBER" | "NONE" | "OWNER";
+export interface CheckRun {
+    /** GitHub node ID for CheckRun contexts. Missing for StatusContext and synthetic checks. */
+    id?: string | null;
+    name: string;
+    status: CheckStatus;
+    conclusion: CheckConclusion;
+    source?: "check_run" | "status_context" | "startup_failure";
+    detailsUrl: string;
+    event: string | null;
+    runId: string | null;
+    createdAtUnix?: number;
+    startedAtUnix?: number;
+    completedAtUnix?: number;
+    updatedAtUnix?: number;
+    /** One-line status text shown in the GitHub UI (CheckRun.title or first line of summary; StatusContext.description). */
+    summary?: string;
+    /** Workflow display name for GitHub Actions check runs, when GraphQL exposes it. */
+    workflowName?: string;
+    workflowId?: string;
+}
+export interface ReviewThread {
+    id: string;
+    isResolved: boolean;
+    isOutdated: boolean;
+    isMinimized: boolean;
+    path: string | null;
+    line: number | null;
+    /** Start of the comment's line range. Null for single-line comments (use `line` for both). */
+    startLine: number | null;
+    /** PullRequestReview ID that created the top comment, when GitHub exposes it. */
+    reviewId?: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+    createdAtUnix?: number;
+    comments?: ReviewThreadComment[];
+    /** True when Shepherd re-surfaced this thread because its body changed after first look. */
+    edited?: boolean;
+}
+/**
+ * Parsed GitHub ```suggestion block, attached to a review thread when the
+ * reviewer left a machine-applicable replacement. The `lines` are the
+ * exact text the agent (or the CLI's commit-suggestions path) would write
+ * into the file in place of lines [startLine..endLine].
+ */
+export interface SuggestionBlock {
+    /** 1-indexed inclusive start line. Equal to `endLine` for single-line suggestions. */
+    startLine: number;
+    /** 1-indexed inclusive end line. */
+    endLine: number;
+    /** Replacement lines verbatim. Empty array = delete; `[""]` = single blank line. Join with `"\n"` to display as a string. */
+    lines: readonly string[];
+    /** Reviewer login, surfaced so callers can co-credit them in commits. */
+    author: string;
+}
+export interface PrComment {
+    id: string;
+    isMinimized: boolean;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+    createdAtUnix: number;
+}
+export interface Review {
+    id: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    createdAtUnix?: number;
+    edited?: boolean;
+    /** True for bot CR re-surfaced after first look (body unchanged). Terse render. */
+    staleBotCr?: boolean;
+    /** Commit OID the review was made against, when available from GraphQL. */
+    commitOid?: string;
+    /** True when commitOid !== headRefOid AND all associated threads are resolved/outdated. Distinct from `staleBotCr` (time-based). Reviews with no threads are not marked stale. */
+    staleReview?: boolean;
+}
+export interface BranchProtection {
+    requiresApprovingReviews: boolean;
+    requiredApprovingReviewCount: number;
+    requiresConversationResolution: boolean;
+    requiresStatusChecks: boolean;
+    /** Required status check context names (e.g. "ci/build", "ci/test"). Empty when requiresStatusChecks is false, or when requiresStatusChecks is true but GitHub returns no explicit contexts. */
+    requiredStatusCheckContexts: string[];
+}
+export type ShepherdMergeStatus = "CLEAN" | "BEHIND" | "CONFLICTS" | "BLOCKED" | "UNSTABLE" | "DRAFT" | "UNKNOWN";
+export interface MergeStatusResult {
+    status: ShepherdMergeStatus;
+    state: "OPEN" | "CLOSED" | "MERGED";
+    isDraft: boolean;
+    mergeable: MergeableState;
+    reviewDecision: ReviewDecision;
+    blockingBotReviewInProgress: boolean;
+    mergeStateStatus: MergeStateStatus;
+}
+export interface BatchPrData {
+    nodeId: string;
+    number: number;
+    state: "OPEN" | "CLOSED" | "MERGED";
+    isDraft: boolean;
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+    reviewDecision: ReviewDecision;
+    headRefOid: string;
+    headRefName: string;
+    /** `"owner/name"` of the head repository; null when the fork has been deleted. */
+    headRepoWithOwner: string | null;
+    baseRefName: string;
+    reviewRequests: Array<{
+        login: string;
+    }>;
+    latestReviews: Array<{
+        login: string;
+        state: string;
+    }>;
+    reviewThreads: ReviewThread[];
+    comments: PrComment[];
+    changesRequestedReviews: Review[];
+    reviewSummaries: Review[];
+    approvedReviews: Review[];
+    checks: CheckRun[];
+    branchProtection: BranchProtection | null;
+    activity?: PrActivitySummary;
+}

package/bin/types/iterate.d.mts

@@ -0,0 +1,157 @@
+import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
+import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
+import type { BranchProtection, CheckStatus, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
+import type { ProtectedRun } from "./protected-run.mts";
+export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "cancel" | "escalate";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "bot-cr-not-dismissed";
+export interface AgentStalledCheck {
+    name: string;
+    status: CheckStatus;
+    source: "check_run" | "status_context" | "startup_failure";
+    runId: string | null;
+    detailsUrl: string | null;
+    createdAtUnix?: number;
+    startedAtUnix?: number;
+    updatedAtUnix?: number;
+    ageSeconds: number;
+    summary?: string;
+}
+export interface EscalateDetails {
+    triggers: EscalateTrigger[];
+    unresolvedThreads: AgentThread[];
+    ambiguousComments: AgentComment[];
+    changesRequestedReviews: Review[];
+    /** Pending/unstarted CI checks that exceeded the stall timeout. */
+    stalledChecks?: AgentStalledCheck[];
+    /** Populated when fix-thrash triggered — threads that have been attempted too many times. */
+    thrashHistory?: Array<{
+        threadId: string;
+        attempts: number;
+    }>;
+    suggestion: string;
+    humanMessage: string;
+}
+export interface IterateResultSummary {
+    passing: number;
+    skipped: number;
+    filtered: number;
+    inProgress: number;
+    superseded: number;
+}
+export interface IterateResultBase {
+    pr: number;
+    repo: string;
+    status: ShepherdStatus;
+    state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
+    mergeStateStatus: MergeStateStatus;
+    mergeStatus: ShepherdMergeStatus;
+    reviewDecision: ReviewDecision;
+    blockingBotReviewInProgress: boolean;
+    isDraft: boolean;
+    shouldCancel: boolean;
+    remainingSeconds: number;
+    summary: IterateResultSummary;
+    /** Validated base branch (e.g. "main") for this PR. */
+    baseBranch: string;
+    /** Branch protection rule for the PR's base branch. Null when no rule exists or the base ref is unavailable. */
+    branchProtection: BranchProtection | null;
+    /**
+     * All CI checks that are relevant to PR readiness: triggered by a PR event
+     * (pull_request / pull_request_target, or StatusContext with null event),
+     * completed (status === COMPLETED), and not skipped/neutral.
+     *
+     * Includes both passing and failing checks. Failing entries carry
+     * `workflowName`, `jobName`, `failedStep`, and `summary`.
+     */
+    checks: RelevantCheck[];
+    inProgressChecks?: ActiveCheck[];
+    ignoredNames?: string[];
+    supersededNames?: string[];
+    activity?: PrActivitySummary;
+}
+interface IterateResultWait extends IterateResultBase {
+    action: "wait";
+    log: string;
+}
+export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
+interface IterateResultCancel extends IterateResultBase {
+    action: "cancel";
+    reason: CancelReason;
+    log: string;
+}
+export interface ResolveCommand {
+    /** Argv for spawn-style execution. May contain a `$DISMISS_MESSAGE` placeholder. `$HEAD_SHA` is never in `argv` — `renderResolveCommand` (from `commands/iterate/render.mts`) appends `--require-sha "$HEAD_SHA"` when rendering if `requiresHeadSha` is true. Use `renderResolveCommand` to render as a command string; don't naive-join. */
+    argv: string[];
+    /** When true, `renderResolveCommand` appends `--require-sha "$HEAD_SHA"` to the rendered command. */
+    requiresHeadSha: boolean;
+    /** Whether the model must substitute $DISMISS_MESSAGE with a specific description of the fix. */
+    requiresDismissMessage: boolean;
+    /** Thread IDs that should receive a reply instead of a resolve mutation. */
+    replyThreadIds?: string[];
+    /** Thread IDs that should be resolved on GitHub. Human-authored IDs must not appear here. */
+    resolveThreadIds?: string[];
+    /** Bot/non-human CHANGES_REQUESTED review IDs to dismiss. Human-authored IDs must not appear here. */
+    dismissReviewIds?: string[];
+    /** True when any mutation flag was appended (threads/comments/reviews). False for a bare runner-specific `pr-shepherd apply review <PR>` with nothing to do. Callers use this to gate emitting an apply instruction — coupling to argv length would break silently if the base argv ever grew a global flag. */
+    hasMutations: boolean;
+}
+/**
+ * Default fix_code variant: agent applies edits locally, commits, pushes,
+ * then runs the pre-built apply command. Emitted under `## Post-fix push`.
+ */
+interface FixRebaseAndPush {
+    threads: AgentThread[];
+    /** Unresolved threads that should be resolved on GitHub without requiring code edits. */
+    resolutionOnlyThreads: ReviewThread[];
+    /** PR comment bodies surfaced to the agent for evaluation, including previously filtered bot/noise comments; do not treat `actionableComments.length` as a proxy for "must push code". */
+    actionableComments: AgentComment[];
+    /** Review IDs (COMMENTED summaries and, if opted in, APPROVED reviews) to minimize — no code change needed. */
+    reviewSummaryIds: string[];
+    /** COMMENTED review summaries surfaced to the agent for the first time this iteration — body shown inline. */
+    firstLookSummaries: Review[];
+    /** COMMENTED review summaries whose body changed since the agent first saw them. Body shown inline; IDs not in `reviewSummaryIds`. */
+    editedSummaries: Review[];
+    /** APPROVED-state reviews surfaced for visibility (when `iterate.minimizeApprovals` is false). */
+    surfacedApprovals: Review[];
+    checks: AgentCheck[];
+    changesRequestedReviews: Review[];
+    /** Pre-built apply command. Run after committing and pushing. */
+    resolveCommand: ResolveCommand;
+    /** When present, run this command first (no SHA substitution needed) to resolve bot threads and minimize comments, independent of any push. */
+    resolveOnlyCommand?: ResolveCommand;
+    /** Ordered steps for the model to follow. */
+    instructions: string[];
+    /** Run IDs of in-progress GitHub Actions checks. The agent should cancel these before pushing new commits; if it decides not to push (e.g. resolve-only), it may skip cancellation. Empty when all in-progress runs are external status checks or already cancelled. */
+    inProgressRunIds: string[];
+    /** Workflow runs deliberately excluded from cancellation by actions.neverCancelRuns. */
+    protectedRuns: ProtectedRun[];
+    /** First-look threads — previously hidden, surfaced for acknowledgment only. */
+    firstLookThreads: FirstLookThread[];
+    /** First-look comments — previously hidden, surfaced for acknowledgment only. */
+    firstLookComments: FirstLookComment[];
+}
+export interface IterateResultFixCode extends IterateResultBase {
+    action: "fix_code";
+    fix: FixRebaseAndPush;
+    cancelled: string[];
+}
+interface IterateResultMarkReady extends IterateResultBase {
+    action: "mark_ready";
+    markedReady: boolean;
+    log: string;
+}
+interface IterateResultEscalate extends IterateResultBase {
+    action: "escalate";
+    escalate: EscalateDetails;
+}
+export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultEscalate;
+export interface IterateCommandOptions extends GlobalOptions {
+    readyDelaySeconds?: number;
+    noAutoMarkReady?: boolean;
+    noAutoCancelActionable?: boolean;
+    /** Override stall timeout seconds. Defaults to config.iterate.stallTimeoutMinutes * 60. */
+    stallTimeoutSeconds?: number;
+    /** Case-insensitive workflow/check glob patterns Shepherd must not cancel. */
+    neverCancelRuns?: string[];
+}
+export {};

package/bin/types/protected-run.d.mts

@@ -0,0 +1,6 @@
+export interface ProtectedRun {
+    runId: string;
+    matchedPattern: string;
+    checkNames: string[];
+    workflowName?: string;
+}