pr-shepherd 0.56.6 → 0.57.1

package/bin/state/durable-state.mjs

@@ -0,0 +1,41 @@
+import { execFileSync } from "node:child_process";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { join, resolve } from "node:path";
+import { getEffectiveCwd } from "../execution-context.mjs";
+/**
+ * A cloud session can be recycled between ticks, and its temp dir with it. The git common
+ * directory lives with the repository checkout, so state stored there survives whatever the
+ * session does with `TMPDIR`. Only a read-only `git rev-parse` is ever invoked.
+ */
+const durableScope = new AsyncLocalStorage();
+const commonDirByCwd = new Map();
+/** Run work whose state (seen markers, stall timers, reply records) must outlive a temp dir. */
+export function runWithDurableState(work) {
+    return durableScope.run(true, work);
+}
+/** Cloud sessions are always durable; other callers opt in through `runWithDurableState`. */
+export function durableStateRequested() {
+    return durableScope.getStore() === true || process.env["CLAUDE_CODE_REMOTE"] === "true";
+}
+/** `<git-common-dir>/pr-shepherd-state`, or null when not requested or outside a repository. */
+export function resolveDurableStateBase() {
+    if (!durableStateRequested())
+        return null;
+    const cwd = getEffectiveCwd();
+    if (!commonDirByCwd.has(cwd))
+        commonDirByCwd.set(cwd, readCommonDir(cwd));
+    return commonDirByCwd.get(cwd) ?? null;
+}
+function readCommonDir(cwd) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out ? join(resolve(cwd, out), "pr-shepherd-state") : null;
+    }
+    catch {
+        return null;
+    }
+}

package/bin/state/graphql-quota-policy.mjs

@@ -1,13 +1,25 @@
+import { mostConservativeSample } from "../github/rate-limit-sample.mjs";
 export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt = Date.now() / 1000) {
     const windowRolled = previous !== null && sample.resetAt > previous.resetAt && observedAt >= previous.resetAt;
+    // A sample whose own window already ended before the saved one is stale, whatever its
+    // credential, resource, or limit: keep the saved sample and do not re-arm from it.
+    const stale = previous !== null && sample.resetAt < previous.resetAt && observedAt >= sample.resetAt;
     const rearm = previous === null ||
-        previous.resource !== sample.resource ||
-        previous.limit !== sample.limit ||
-        windowRolled ||
-        fingerprintChanged(previous, sample);
-    const effective = !rearm && previous !== null && usageRegressed(previous, sample)
-        ? newerSavedSample(previous)
-        : sample;
+        (!stale &&
+            (previous.resource !== sample.resource ||
+                previous.limit !== sample.limit ||
+                windowRolled ||
+                fingerprintChanged(previous, sample)));
+    // Same window: the lowest remaining and the highest used seen so far, so an older sample (or a
+    // proxy route whose X-RateLimit-Used disagrees) never lowers the warning level.
+    const effective = rearm || previous === null
+        ? sample
+        : stale
+            ? savedSample(previous)
+            : {
+                ...mostConservativeSample(savedSample(previous), sample),
+                resetAt: Math.max(previous.resetAt, sample.resetAt),
+            };
     const warned = new Set(rearm || previous === null ? [] : previous.warnedThresholds);
     const rearmEpoch = rearm ? (previous?.rearmEpoch ?? 0) + 1 : (previous?.rearmEpoch ?? 0);
     const crossed = bands.filter((band) => effective.remaining * 100 <= effective.limit * band.remainingPercent);
@@ -15,7 +27,9 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
     for (const band of crossed)
         warned.add(band.remainingPercent);
     const active = newCrossed.at(-1);
-    const credentialFingerprint = effective.credentialFingerprint ?? previous?.credentialFingerprint;
+    const credentialFingerprint = stale
+        ? previous?.credentialFingerprint
+        : (sample.credentialFingerprint ?? previous?.credentialFingerprint);
     const state = {
         resource: effective.resource,
         limit: effective.limit,
@@ -49,14 +63,7 @@ function fingerprintChanged(previous, sample) {
         sample.credentialFingerprint !== undefined &&
         previous.credentialFingerprint !== sample.credentialFingerprint);
 }
-/** An older observation of the same window: lower used, or higher remaining when used is absent. */
-function usageRegressed(previous, sample) {
-    if (sample.used !== undefined && previous.lastUsed !== undefined) {
-        return sample.used < previous.lastUsed;
-    }
-    return sample.remaining > previous.lastRemaining;
-}
-function newerSavedSample(previous) {
+function savedSample(previous) {
     return {
         resource: previous.resource,
         limit: previous.limit,

package/bin/state/merge-request.d.mts

@@ -0,0 +1,25 @@
+import type { RestMergeOptions, RestMergeResponse } from "../github/rest-merge.mts";
+export interface MergeRequestRecord {
+    version: 1;
+    options: RestMergeOptions;
+    startedAtUnix: number;
+    uuid?: string;
+    response?: RestMergeResponse;
+    uncertain?: true;
+    /** Identifies the one consumable source of a permanently recorded successor. */
+    replacementToken?: string;
+}
+type Key = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+export declare function readMergeRequest(key: Key): Promise<MergeRequestRecord | null>;
+/** Persist intent exclusively before contacting GitHub; another process cannot submit it twice. */
+export declare function claimMergeRequest(key: Key, record: MergeRequestRecord): Promise<boolean>;
+/** Consume one durable successor of a failed request or an enqueue guarded by an older head. */
+export declare function replaceFailedMergeRequest(key: Key, previous: MergeRequestRecord, next: MergeRequestRecord): Promise<boolean>;
+export declare function writeMergeRequest(key: Key, record: MergeRequestRecord): Promise<void>;
+/** A delayed status poll can update only its own intent, never a later main request. */
+export declare function writeMergeRequestStatus(key: Key, record: MergeRequestRecord): Promise<void>;
+export {};

package/bin/state/merge-request.mjs

@@ -0,0 +1,145 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+import { restMergeStackGuardKey, validateRestMergeStackGuard, } from "../github/rest-merge-stack-guard.mjs";
+const path = (key) => resolvePrStatePath(key, "merge-async.json");
+const generation = (record) => createHash("sha256")
+    .update(JSON.stringify([
+    record.options.requireSha,
+    record.options.mergeAction,
+    record.options.mergeMethod,
+    record.startedAtUnix,
+    record.replacementToken,
+    ...(record.options.expectedStack
+        ? [restMergeStackGuardKey(record.options.expectedStack)]
+        : []),
+]))
+    .digest("hex")
+    .slice(0, 24);
+const statusPath = (key, record) => resolvePrStatePath(key, `merge-async-status-${generation(record)}.json`);
+export async function readMergeRequest(key) {
+    let raw;
+    try {
+        raw = await readFile(path(key), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const record = parseRecord(raw);
+    try {
+        const status = parseRecord(await readFile(statusPath(key, record), "utf8"));
+        if (generation(status) !== generation(record))
+            throw new Error("Asynchronous merge status does not match its persisted intent");
+        return status;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return record;
+        throw error;
+    }
+}
+function parseRecord(raw) {
+    const record = JSON.parse(raw);
+    if (record?.version !== 1 ||
+        !/^[0-9a-f]{40}$/.test(record.options?.requireSha ?? "") ||
+        !["direct_merge", "merge_queue", "default"].includes(record.options.mergeAction) ||
+        !Number.isSafeInteger(record.startedAtUnix) ||
+        (record.uuid !== undefined && !/^[0-9a-f-]{36}$/i.test(record.uuid)) ||
+        (record.replacementToken !== undefined &&
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(record.replacementToken))) {
+        throw new Error("Invalid asynchronous merge state; outcome must be reconciled before another request");
+    }
+    if (record.options.expectedStack !== undefined) {
+        validateRestMergeStackGuard(record.options.expectedStack);
+        if (record.options.expectedStack.prefix.at(-1)?.headRefOid !== record.options.requireSha)
+            throw new Error("Invalid asynchronous merge state: expectedStack head differs from guarded SHA");
+    }
+    return record;
+}
+/** Persist intent exclusively before contacting GitHub; another process cannot submit it twice. */
+export async function claimMergeRequest(key, record) {
+    await mkdir(dirname(path(key)), { recursive: true });
+    try {
+        await writeFile(path(key), `${JSON.stringify(record)}\n`, { flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+/** Consume one durable successor of a failed request or an enqueue guarded by an older head. */
+export async function replaceFailedMergeRequest(key, previous, next) {
+    if (previous.uncertain ||
+        (previous.response?.status !== "failed" &&
+            !(previous.response?.status === "enqueued" &&
+                previous.options.requireSha !== next.options.requireSha)))
+        return false;
+    const stem = resolvePrStatePath(key, `merge-async-successor-${generation(previous)}`);
+    const candidate = { ...next, replacementToken: randomUUID() };
+    const source = `${stem}-${candidate.replacementToken}.json`;
+    let created = false;
+    let published = false;
+    try {
+        await writeFile(source, `${JSON.stringify(candidate)}\n`, { flag: "wx" });
+        created = true;
+        if (JSON.stringify(await readMergeRequest(key)) !== JSON.stringify(previous))
+            return false;
+        let persisted = candidate;
+        try {
+            // Publish only complete bytes. This permanent marker must never be consumed or rewritten.
+            await link(source, `${stem}.json`);
+            published = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            persisted = parseRecord(await readFile(`${stem}.json`, "utf8"));
+            if (!persisted.replacementToken)
+                throw new Error("Legacy merge successor has no recovery token; reconcile its outcome");
+            if (persisted.options.requireSha !== next.options.requireSha ||
+                persisted.options.mergeAction !== next.options.mergeAction ||
+                persisted.options.mergeMethod !== next.options.mergeMethod ||
+                restMergeStackGuardKey(persisted.options.expectedStack) !==
+                    restMergeStackGuardKey(next.options.expectedStack))
+                return false;
+        }
+        if (JSON.stringify(await readMergeRequest(key)) !== JSON.stringify(previous))
+            return false;
+        try {
+            // Never recreate this source: its absence means another caller already consumed the intent.
+            await rename(`${stem}-${persisted.replacementToken}.json`, path(key));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        return true;
+    }
+    finally {
+        if (created && !published)
+            await unlink(source).catch(() => { });
+    }
+}
+export async function writeMergeRequest(key, record) {
+    await writeRecord(path(key), record);
+}
+/** A delayed status poll can update only its own intent, never a later main request. */
+export async function writeMergeRequestStatus(key, record) {
+    await writeRecord(statusPath(key, record), record);
+}
+async function writeRecord(destination, record) {
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(record)}\n`);
+        await rename(temporary, destination);
+    }
+    finally {
+        await unlink(temporary).catch(() => { });
+    }
+}

package/bin/state/pr-fingerprint.d.mts

@@ -6,6 +6,15 @@ export interface StoredPrFingerprint {
     inputDigest: string;
     fingerprint: PrFingerprint;
     report: ShepherdReport;
+    /**
+     * Conditional REST change detectors read before the GraphQL snapshot that produced
+     * `report`, and when that snapshot ran (unix ms). Dropped whenever the report is rewritten.
+     */
+    detectors?: StoredWaitDetectors;
+}
+export interface StoredWaitDetectors {
+    digest: string;
+    fullAt: number;
 }
 export declare function fingerprintInputDigest(config: PrShepherdConfig): string;
 export declare function loadPrFingerprint(key: {
@@ -18,3 +27,9 @@ export declare function storePrFingerprint(key: {
     repo: string;
     pr: number;
 }, fingerprint: PrFingerprint, report: ShepherdReport, config: PrShepherdConfig): Promise<void>;
+/** Record the detector digest read before this tick's GraphQL snapshot beside its report. */
+export declare function attachWaitDetectors(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, stored: StoredPrFingerprint, detectors: StoredWaitDetectors): Promise<void>;

package/bin/state/pr-fingerprint.mjs

@@ -5,7 +5,13 @@ import { dirname } from "node:path";
 import { resolvePrStatePath } from "./base.mjs";
 import { discoverRuleFiles } from "../classify/loader.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
-const VERSION = 3;
+const VERSION = 4;
+let packageVersion;
+/** Bundled standard rules change with the package, so their digest input is its version. */
+function readPackageVersion() {
+    packageVersion ??= JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    return packageVersion;
+}
 export function fingerprintInputDigest(config) {
     const hash = createHash("sha256");
     hash.update(JSON.stringify({
@@ -21,6 +27,9 @@ export function fingerprintInputDigest(config) {
             neverCancelRuns: config.actions.neverCancelRuns,
             workWhileQueued: config.actions.workWhileQueued,
         },
+        standardRules: (config.standardRules?.length ?? 0) > 0
+            ? { names: config.standardRules, version: readPackageVersion() }
+            : undefined,
     }));
     for (const file of discoverRuleFiles(getEffectiveCwd())) {
         hash.update("\0");
@@ -48,17 +57,23 @@ export async function loadPrFingerprint(key) {
     }
 }
 export async function storePrFingerprint(key, fingerprint, report, config) {
+    await writeStored(key, {
+        version: VERSION,
+        inputDigest: fingerprintInputDigest(config),
+        fingerprint,
+        report,
+    });
+}
+/** Record the detector digest read before this tick's GraphQL snapshot beside its report. */
+export async function attachWaitDetectors(key, stored, detectors) {
+    await writeStored(key, { ...stored, detectors });
+}
+async function writeStored(key, payload) {
     const path = resolvePrStatePath(key, "fingerprint.json");
     let tmp;
     try {
         await mkdir(dirname(path), { recursive: true });
         tmp = `${path}.${randomUUID()}.tmp`;
-        const payload = {
-            version: VERSION,
-            inputDigest: fingerprintInputDigest(config),
-            fingerprint,
-            report,
-        };
         await writeFile(tmp, `${JSON.stringify(payload)}\n`, "utf8");
         await rename(tmp, path);
         tmp = undefined;

package/bin/state/rest-cache.d.mts

@@ -30,6 +30,8 @@ export interface EtagCacheEntry {
     body: unknown;
     storedAt: number;
     headSha?: string;
+    /** Pagination `Link` header; GitHub does not reliably repeat it on a 304. */
+    link?: string;
 }
 export interface DerivedCacheEntry<T = unknown> {
     kind: "derived";
@@ -43,6 +45,7 @@ export declare function storeEtagEntry(key: StateKey, name: string, fields: {
     etag: string;
     body: unknown;
     headSha?: string;
+    link?: string;
 }): Promise<void>;
 export declare function loadDerived<T = unknown>(key: StateKey, name: string): Promise<DerivedCacheEntry<T> | null>;
 export declare function storeDerived<T = unknown>(key: StateKey, name: string, value: T, headSha?: string): Promise<void>;

package/bin/state/rest-cache.mjs

@@ -34,6 +34,7 @@ export async function storeEtagEntry(key, name, fields) {
         body: fields.body,
         storedAt: Date.now(),
         ...(fields.headSha !== undefined && { headSha: fields.headSha }),
+        ...(fields.link !== undefined && { link: fields.link }),
     });
 }
 export async function loadDerived(key, name) {

package/bin/state/rest-snapshot-report.d.mts

@@ -0,0 +1,21 @@
+import type { PrShepherdConfig } from "../config/load.mts";
+import type { ShepherdReport } from "../types.mts";
+/**
+ * The last REST-transport report plus the digest of the conditional-read snapshot it was built
+ * from. The REST counterpart of `fingerprint.json`: when the next tick's reads are all 304 and
+ * hash to the same digest, the stored report is still current.
+ */
+export interface StoredRestSnapshotReport {
+    version: number;
+    inputDigest: string;
+    snapshotDigest: string;
+    report: ShepherdReport;
+}
+type Key = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+export declare function loadRestSnapshotReport(key: Key): Promise<StoredRestSnapshotReport | null>;
+export declare function storeRestSnapshotReport(key: Key, snapshotDigest: string, report: ShepherdReport, config: PrShepherdConfig): Promise<void>;
+export {};

package/bin/state/rest-snapshot-report.mjs

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+import { fingerprintInputDigest } from "./pr-fingerprint.mjs";
+const VERSION = 2;
+export async function loadRestSnapshotReport(key) {
+    try {
+        const parsed = JSON.parse(await readFile(resolvePrStatePath(key, "rest-report.json"), "utf8"));
+        const record = parsed;
+        return record["version"] === VERSION &&
+            typeof record["inputDigest"] === "string" &&
+            typeof record["snapshotDigest"] === "string" &&
+            record["report"] !== null &&
+            typeof record["report"] === "object"
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function storeRestSnapshotReport(key, snapshotDigest, report, config) {
+    const path = resolvePrStatePath(key, "rest-report.json");
+    let tmp;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        tmp = `${path}.${randomUUID()}.tmp`;
+        const payload = {
+            version: VERSION,
+            inputDigest: fingerprintInputDigest(config),
+            snapshotDigest,
+            report,
+        };
+        await writeFile(tmp, `${JSON.stringify(payload)}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // An optimization only; a failed write just means the next tick rebuilds the report.
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}

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

@@ -49,6 +49,9 @@ export declare function hasSeen(key: StateKey, id: string): Promise<boolean>;
  * All errors are silently swallowed — the marker is best-effort.
  */
 export declare function markSeen(key: StateKey, id: string, body: string): Promise<void>;
+/** A definite permission denial suppresses generated retries until the feedback changes. */
+export declare function markMutationDenied(key: StateKey, id: string, body?: string): Promise<void>;
+export declare function mutationWasDenied(id: string, body: string, map: Map<string, SeenMarker>): boolean;
 export declare function markReviewInlineThreads(key: StateKey, reviewId: string, inlineThreadIds: readonly string[]): Promise<void>;
 /**
  * Write a marker after Shepherd successfully replies to a review thread.

package/bin/state/seen-comments.mjs

@@ -105,6 +105,24 @@ export async function hasSeen(key, id) {
 export async function markSeen(key, id, body) {
     await writeSeenMarker(key, id, { bodyHash: hashBody(body) });
 }
+/** A definite permission denial suppresses generated retries until the feedback changes. */
+export async function markMutationDenied(key, id, body) {
+    let bodyHash = body === undefined ? undefined : hashBody(body);
+    if (bodyHash === undefined) {
+        try {
+            const marker = JSON.parse(await readFile(resolvePath(key, id), "utf8"));
+            bodyHash = marker.bodyHash;
+        }
+        catch {
+            return;
+        }
+    }
+    if (typeof bodyHash === "string")
+        await writeSeenMarker(key, id, { deniedMutationBodyHash: bodyHash });
+}
+export function mutationWasDenied(id, body, map) {
+    return map.get(id)?.deniedMutationBodyHash === hashBody(body);
+}
 export async function markReviewInlineThreads(key, reviewId, inlineThreadIds) {
     await writeSeenMarker(key, reviewId, {
         inlineThreadIds: [...new Set(inlineThreadIds)].sort((a, b) => a.localeCompare(b)),

package/bin/types/api-usage.d.mts

@@ -1,6 +1,9 @@
 export interface ApiResourceUsage {
     resource: string;
-    requestCount: number;
+    /** Quota-consuming requests; excludes `notModified` responses. Omitted when 0. */
+    requestCount?: number;
+    /** Conditional reads answered 304 Not Modified (no quota consumed). Omitted when 0. */
+    notModified?: number;
     limit: number;
     used?: number;
     remaining: number;
@@ -29,6 +32,11 @@ export interface ApiUsage {
     credentialSources: string[];
     graphql?: GraphqlApiUsage;
     rest?: ApiResourceUsage[];
+    /**
+     * REST responses that carried no rate-limit headers, so no pool reported a charge (the Claude
+     * Code proxy's `ccr` routes). Omitted when 0.
+     */
+    unmeteredRestRequestCount?: number;
 }
 export interface GraphqlQuotaWarning {
     resource: "graphql" | "core" | "combined";

package/bin/types/escalate.d.mts

@@ -2,7 +2,7 @@ import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
+export type EscalateTrigger = "transport-unsupported" | "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;

package/bin/types/github.d.mts

@@ -24,11 +24,11 @@ type RepositoryPermission = "NONE" | "READ" | "TRIAGE" | "WRITE" | "MAINTAIN" |
 /** Raw GitHub viewer fields used to gate remote actions. */
 export interface ViewerAuthorization {
     repositoryPermission: RepositoryPermission | null;
-    viewerCanAdminister: boolean;
-    viewerDidAuthor: boolean;
-    viewerCanUpdate: boolean;
-    viewerCanEnableAutoMerge: boolean;
-    viewerCanEditFiles: boolean;
+    viewerCanAdminister?: boolean;
+    viewerDidAuthor?: boolean;
+    viewerCanUpdate?: boolean;
+    viewerCanEnableAutoMerge?: boolean;
+    viewerCanEditFiles?: boolean;
     headRepositoryPermission: RepositoryPermission | null;
 }
 /** Raw relationship between a comment author and the repository, as reported by GitHub. */
@@ -60,12 +60,17 @@ export interface CheckRun {
     workflowId?: string;
     /** True when GraphQL reported at least one CheckRun annotation. Omitted when false. */
     hasAnnotations?: boolean;
+    /**
+     * Every annotation on this run, when BatchPr's `annotations(first: 1)` page already held all
+     * of them. Internal: lets the check path skip `CheckRunAnnotationsBatch`; never rendered.
+     */
+    inlineAnnotations?: import("./check-annotations.mts").CheckAnnotation[];
 }
 export interface ReviewThread {
     id: string;
-    isResolved: boolean;
-    isOutdated: boolean;
-    isMinimized: boolean;
+    isResolved?: boolean;
+    isOutdated?: boolean;
+    isMinimized?: boolean;
     viewerCanReply?: boolean;
     viewerCanResolve?: boolean;
     path: string | null;
@@ -98,7 +103,7 @@ export interface SuggestionBlock {
 }
 export interface PrComment {
     id: string;
-    isMinimized: boolean;
+    isMinimized?: boolean;
     viewerCanMinimize?: boolean;
     author: string;
     authorType: AuthorType;
@@ -146,6 +151,13 @@ export interface MergeStatusResult {
     mergeRequirements?: MergeRequirements;
 }
 export interface BatchPrData extends BatchPrMergeFields {
+    /** Present when this snapshot was fetched through REST. */
+    transport?: "rest";
+    /** Fields unavailable from the selected transport; absence is never fabricated as false. */
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
     nodeId: string;
     number: number;
     state: "OPEN" | "CLOSED" | "MERGED";
@@ -172,6 +184,8 @@ export interface BatchPrData extends BatchPrMergeFields {
     baseRefName: string;
     /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
     baseRefOid?: string;
+    /** The base branch's live tip (`baseRef.target.oid`). GraphQL only; keys the BaseBehind cache. */
+    baseTipOid?: string;
     reviewRequests: Array<{
         login: string;
     }>;

package/bin/types/iterate.d.mts

@@ -6,6 +6,7 @@ import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
 import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
+import type { NextCheck } from "./next-check.mts";
 export type ShepherdAction = "wait" | "ready" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
 export interface IterateResultSummary {
     passing: number;
@@ -15,6 +16,11 @@ export interface IterateResultSummary {
     superseded: number;
 }
 export interface IterateResultBase {
+    transport?: "rest";
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
     pr: number;
     repo: string;
     status: ShepherdStatus;
@@ -58,6 +64,10 @@ export interface IterateResultBase {
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;
     fingerprintReused?: true;
+    /** Set to `event` when this result came from event mode: one tick, no sleeping. Omitted in poll mode. */
+    pollMode?: "event";
+    /** Event mode only: when to come back if no GitHub event arrives first. Omitted for terminal actions. */
+    nextCheck?: NextCheck;
     /** Classification-rule resolve/minimize applied during this fetch. Omitted when nothing happened. */
     ruleAutoResolve?: RuleAutoResolveReport;
 }
@@ -79,9 +89,9 @@ interface IterateResultCancel extends IterateResultBase {
     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 for spawn-style execution. May contain a `$DISMISS_MESSAGE` placeholder. `--require-sha` is never in `argv` — `renderResolveCommand` (from `commands/iterate/render.mts`) appends `--require-sha HEAD` 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. */
+    /** When true, `renderResolveCommand` appends `--require-sha HEAD` to the rendered command. */
     requiresHeadSha: boolean;
     /** Whether the model must substitute $DISMISS_MESSAGE with a specific description of the fix. */
     requiresDismissMessage: boolean;
@@ -175,8 +185,20 @@ export interface IterateCommandOptions extends GlobalOptions {
      * the public `IterateInput` in api.mts.
      */
     fingerprintCache?: boolean;
+    /**
+     * Internal. Event mode passes a sink that receives the CI-start stall deadline (oldest
+     * unstarted check age + stall timeout) so `nextCheck` can wake before it. Excluded from
+     * the public `IterateInput` in api.mts.
+     */
+    stallDeadlineSink?: {
+        ciStartDeadlineSeconds?: number;
+    };
     /** Shepherd through readiness and emit the exact merge/queue command when ready. */
     merge?: boolean;
+    /** Override `poll.mode` for this call. `auto` resolves to `event` when `CLAUDE_CODE_REMOTE=true`. */
+    pollMode?: import("../config/load.mts").PollMode;
+    /** Override `iterate.instructions` for this call. */
+    instructions?: import("../config/load.mts").InstructionStyle;
     /**
      * Internal. Defers quota warnings until an until-terminal poll breaks. Set only by
      * `runPollCore`; excluded from the public `IterateInput` in api.mts.