pr-shepherd 0.51.1 → 0.52.1

package/bin/state/base.mjs

@@ -1,29 +1,81 @@
-import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { isAbsolute, join } from "node:path";
 import { tmpdir } from "node:os";
 import { SAFE_PR_NUMBER, SAFE_SEGMENT } from "../util/path-segment.mjs";
+/** Read once per process; null when the platform or `getconf` offers no per-user temp dir. */
+let darwinUserTempDir;
+/**
+ * macOS's per-user temp dir, read from `confstr(_CS_DARWIN_USER_TEMP_DIR)` rather than
+ * `TMPDIR`. Sandboxed agent shells point `TMPDIR` at their own directory, so the same user's
+ * sandboxed CLI, unsandboxed CLI, and MCP server would otherwise keep separate state.
+ */
+function readDarwinUserTempDir() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const dir = execFileSync("/usr/bin/getconf", ["DARWIN_USER_TEMP_DIR"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return isAbsolute(dir) ? dir : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function resolveStateBase() {
     const envDir = process.env["PR_SHEPHERD_STATE_DIR"];
-    return envDir ? envDir : join(tmpdir(), "pr-shepherd-state");
+    if (envDir)
+        return envDir;
+    if (darwinUserTempDir === undefined)
+        darwinUserTempDir = readDarwinUserTempDir();
+    return join(darwinUserTempDir ?? tmpdir(), "pr-shepherd-state");
 }
 /**
- * `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/...parts`.
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/...parts`.
  * Owner, repo, PR number, and each extra part must be a safe path segment.
  */
 export function resolvePrStatePath(key, ...parts) {
-    if (!SAFE_SEGMENT.test(key.owner)) {
-        throw new Error(`Invalid state key segment "owner": ${key.owner}`);
-    }
-    if (!SAFE_SEGMENT.test(key.repo)) {
-        throw new Error(`Invalid state key segment "repo": ${key.repo}`);
+    return resolveRepoStatePath(key, numberSegment("pr", key.pr), parts);
+}
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/...parts`, beside the per-PR directories.
+ * Owner, repo, stack number, and each extra part must be a safe path segment.
+ */
+export function resolveStackStatePath(key, ...parts) {
+    return resolveRepoStatePath(key, `stack-${numberSegment("stack", key.stack)}`, parts);
+}
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>`.
+ * Owner and repo are separate segments so names that contain hyphens cannot collide.
+ */
+export function resolveRepoStateDir(key) {
+    assertOwnerRepo(key);
+    return join(resolveStateBase(), key.owner, key.repo);
+}
+function numberSegment(name, value) {
+    const segment = String(value);
+    if (!SAFE_PR_NUMBER.test(segment)) {
+        throw new Error(`Invalid state key segment "${name}": ${value}`);
     }
-    const pr = String(key.pr);
-    if (!SAFE_PR_NUMBER.test(pr)) {
-        throw new Error(`Invalid state key segment "pr": ${key.pr}`);
+    return segment;
+}
+function assertRepoSegment(name, value) {
+    // `.` and `..` match SAFE_SEGMENT, but they are real path segments here and would escape the base.
+    if (!SAFE_SEGMENT.test(value) || value === "." || value === "..") {
+        throw new Error(`Invalid state key segment "${name}": ${value}`);
     }
+}
+function assertOwnerRepo(key) {
+    assertRepoSegment("owner", key.owner);
+    assertRepoSegment("repo", key.repo);
+}
+function resolveRepoStatePath(key, entry, parts) {
+    assertOwnerRepo(key);
     for (const part of parts) {
-        if (!SAFE_SEGMENT.test(part)) {
+        if (!SAFE_SEGMENT.test(part) || part === "." || part === "..") {
             throw new Error(`Invalid state key segment: ${part}`);
         }
     }
-    return join(resolveStateBase(), `${key.owner}-${key.repo}`, pr, ...parts);
+    return join(resolveRepoStateDir(key), entry, ...parts);
 }

package/bin/state/fix-attempts.d.mts

@@ -4,7 +4,7 @@
  * Tracks how many caller-visible times each review thread has been dispatched to
  * the fix_code handler without being resolved. Body edits reset the count.
  *
- * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
+ * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/fix-attempts.json`.
  */
 export interface FixAttemptsState {
     /** HEAD SHA at the time the counts were last written, retained for observability/compatibility. */

package/bin/state/fix-attempts.mjs

@@ -4,7 +4,7 @@
  * Tracks how many caller-visible times each review thread has been dispatched to
  * the fix_code handler without being resolved. Body edits reset the count.
  *
- * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
+ * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/fix-attempts.json`.
  */
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";

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

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { resolveStateBase } from "./base.mjs";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveRepoStateDir } from "./base.mjs";
 import { getWorktreeKey } from "../util/worktree.mjs";
 import { claimWarning } from "./graphql-quota-claims.mjs";
 import { evaluateGraphqlQuotaWarning, } from "./graphql-quota-policy.mjs";
@@ -52,9 +51,6 @@ async function serializeStateUpdate(key, update) {
     return result;
 }
 async function warningStatePath(key) {
-    if (!SAFE_SEGMENT.test(key.owner) || !SAFE_SEGMENT.test(key.repo)) {
-        throw new Error(`Invalid repo key segments: ${key.owner}/${key.repo}`);
-    }
     let worktreeKey;
     try {
         worktreeKey = await getWorktreeKey();
@@ -62,7 +58,7 @@ async function warningStatePath(key) {
     catch {
         return undefined;
     }
-    return join(resolveStateBase(), `${key.owner}-${key.repo}`, "worktrees", `${worktreeKey}-graphql-quota-warnings.json`);
+    return join(resolveRepoStateDir(key), "worktrees", `${worktreeKey}-graphql-quota-warnings.json`);
 }
 async function readState(path) {
     try {

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

@@ -5,23 +5,15 @@
  * 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`.
+ * State lives in `$PR_SHEPHERD_STATE_DIR/<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 {
+import { type StallStateStore } from "./stall-state-store.mts";
+type Store = StallStateStore<{
     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 declare const readStallState: Store["read"];
+export declare const writeStallState: Store["write"];
+export declare const clearStallState: Store["clear"];
 export {};

package/bin/state/iterate-stall.mjs

@@ -5,69 +5,11 @@
  * 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`.
+ * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/iterate-stall.json`.
  */
-import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { dirname } from "node:path";
 import { resolvePrStatePath } from "./base.mjs";
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/** Read the current stall state. Returns null on miss, corrupt data, or invalid shape. */
-export async function readStallState(key) {
-    try {
-        const raw = await readFile(resolvePath(key), "utf8");
-        const parsed = JSON.parse(raw);
-        if (parsed === null ||
-            typeof parsed !== "object" ||
-            typeof parsed["fingerprint"] !== "string" ||
-            !Number.isFinite(parsed["firstSeenAt"])) {
-            return null;
-        }
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-/** Clear stall state so the next invocation starts a fresh timer (fire-and-forget — never throws). */
-export async function clearStallState(key) {
-    try {
-        await unlink(resolvePath(key));
-    }
-    catch {
-        // Best-effort — file may not exist.
-    }
-}
-/** Write stall state (fire-and-forget — never throws). */
-export async function writeStallState(key, state) {
-    let tmp;
-    try {
-        const path = resolvePath(key);
-        tmp = `${path}.${randomUUID()}.tmp`;
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(tmp, JSON.stringify(state), "utf8");
-        await rename(tmp, path);
-        tmp = undefined;
-    }
-    catch {
-        // Best-effort.
-    }
-    finally {
-        if (tmp !== undefined) {
-            try {
-                await unlink(tmp);
-            }
-            catch {
-                // Best-effort cleanup.
-            }
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function resolvePath(key) {
-    return resolvePrStatePath(key, "iterate-stall.json");
-}
+import { stallStateStore } from "./stall-state-store.mjs";
+const store = stallStateStore((key) => resolvePrStatePath(key, "iterate-stall.json"));
+export const readStallState = store.read;
+export const writeStallState = store.write;
+export const clearStallState = store.clear;

package/bin/state/ready-receipts.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Durable evidence that a single-PR Shepherd poll observed a ready PR after
+ * its ready-delay elapsed.  The ref OIDs and readiness fingerprint are part of
+ * the evidence: a receipt is never a general-purpose "this PR is ready"
+ * cache.
+ */
+export interface ReadyReceipt {
+    version: 1;
+    owner: string;
+    repo: string;
+    pr: number;
+    headRefOid: string;
+    baseRefOid: string;
+    status: "READY";
+    isDraft: false;
+    /** Canonical representation of the readiness inputs observed by Shepherd. */
+    readinessFingerprint: string;
+    /** Exact merge-queue removal observed by the one-PR session, if any. */
+    acknowledgedQueueRemovalId?: string;
+    recordedAtUnix: number;
+}
+export interface ReadyReceiptKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export interface ReadyReceiptCurrentState {
+    headRefOid: string;
+    baseRefOid: string;
+    readinessFingerprint: string;
+    status: string;
+    isDraft: boolean;
+}
+/** Read a persisted one-PR readiness receipt. Invalid/stale-shaped files are ignored. */
+export declare function readReadyReceipt(key: ReadyReceiptKey): Promise<ReadyReceipt | null>;
+/** Persist evidence for a completed one-PR ready-delay observation. */
+export declare function writeReadyReceipt(receipt: ReadyReceipt): Promise<void>;
+/** Remove a receipt after the observed PR state no longer matches it. */
+export declare function clearReadyReceipt(key: ReadyReceiptKey): Promise<void>;
+/**
+ * Check the complete binding before using a receipt for aggregate routing.
+ * Callers must provide a fresh fingerprint from the same readiness inputs used
+ * to create the receipt; ref OIDs alone are not sufficient.
+ */
+export declare function isReadyReceiptCurrent(receipt: ReadyReceipt | null, current: ReadyReceiptCurrentState): receipt is ReadyReceipt;

package/bin/state/ready-receipts.mjs

@@ -0,0 +1,86 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+/** Read a persisted one-PR readiness receipt. Invalid/stale-shaped files are ignored. */
+export async function readReadyReceipt(key) {
+    const path = receiptPath(key);
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return isReadyReceipt(parsed) && sameKey(parsed, key) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist evidence for a completed one-PR ready-delay observation. */
+export async function writeReadyReceipt(receipt) {
+    if (!isReadyReceipt(receipt))
+        throw new Error("Invalid ready receipt");
+    const path = receiptPath(receipt);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(receipt)}\n`, "utf8");
+}
+/** Remove a receipt after the observed PR state no longer matches it. */
+export async function clearReadyReceipt(key) {
+    try {
+        await unlink(receiptPath(key));
+    }
+    catch (error) {
+        // Missing receipts are already clear. Any other failure must reach the
+        // caller so stale evidence cannot be silently retained as if it cleared.
+        if (isNodeErrorCode(error, "ENOENT"))
+            return;
+        throw error;
+    }
+}
+function isNodeErrorCode(error, code) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+/**
+ * Check the complete binding before using a receipt for aggregate routing.
+ * Callers must provide a fresh fingerprint from the same readiness inputs used
+ * to create the receipt; ref OIDs alone are not sufficient.
+ */
+export function isReadyReceiptCurrent(receipt, current) {
+    return (receipt !== null &&
+        receipt.status === "READY" &&
+        receipt.isDraft === false &&
+        current.status === "READY" &&
+        current.isDraft === false &&
+        receipt.headRefOid === current.headRefOid &&
+        receipt.baseRefOid === current.baseRefOid &&
+        receipt.readinessFingerprint === current.readinessFingerprint);
+}
+function receiptPath(key) {
+    return resolvePrStatePath(key, "ready-receipt.json");
+}
+function sameKey(receipt, key) {
+    return receipt.owner === key.owner && receipt.repo === key.repo && receipt.pr === key.pr;
+}
+function isReadyReceipt(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (candidate.version === 1 &&
+        typeof candidate.owner === "string" &&
+        typeof candidate.repo === "string" &&
+        typeof candidate.pr === "number" &&
+        Number.isInteger(candidate.pr) &&
+        candidate.pr > 0 &&
+        typeof candidate.headRefOid === "string" &&
+        candidate.headRefOid.length > 0 &&
+        typeof candidate.baseRefOid === "string" &&
+        candidate.baseRefOid.length > 0 &&
+        candidate.status === "READY" &&
+        candidate.isDraft === false &&
+        typeof candidate.readinessFingerprint === "string" &&
+        candidate.readinessFingerprint.length > 0 &&
+        (candidate.acknowledgedQueueRemovalId === undefined ||
+            (typeof candidate.acknowledgedQueueRemovalId === "string" &&
+                candidate.acknowledgedQueueRemovalId.length > 0)) &&
+        typeof candidate.recordedAtUnix === "number" &&
+        Number.isFinite(candidate.recordedAtUnix));
+}

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

@@ -14,7 +14,7 @@
  *   terminal, check-run annotations once the check is COMPLETED. No ETag
  *   applies; the cache is keyed on an immutable identity instead.
  *
- * Entries live under `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/rest-cache/`
+ * Entries live under `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/rest-cache/`
  * and are removed for free when `pr-shepherd clean` deletes the PR's state
  * directory — there is no separate pruning routine.
  */

package/bin/state/rest-cache.mjs

@@ -14,7 +14,7 @@
  *   terminal, check-run annotations once the check is COMPLETED. No ETag
  *   applies; the cache is keyed on an immutable identity instead.
  *
- * Entries live under `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/rest-cache/`
+ * Entries live under `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/rest-cache/`
  * and are removed for free when `pr-shepherd clean` deletes the PR's state
  * directory — there is no separate pruning routine.
  */

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

@@ -0,0 +1,16 @@
+/**
+ * Persistent stall-detection state for an aggregate `--stack` selection whose open layers can
+ * only wait. Keyed by native stack number because the anchor PR can merge or change.
+ *
+ * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/stack-stall.json`.
+ */
+import { type StallStateStore } from "./stall-state-store.mts";
+type Store = StallStateStore<{
+    owner: string;
+    repo: string;
+    stack: number;
+}>;
+export declare const readStackStallState: Store["read"];
+export declare const writeStackStallState: Store["write"];
+export declare const clearStackStallState: Store["clear"];
+export {};

package/bin/state/stack-stall.mjs

@@ -0,0 +1,12 @@
+/**
+ * Persistent stall-detection state for an aggregate `--stack` selection whose open layers can
+ * only wait. Keyed by native stack number because the anchor PR can merge or change.
+ *
+ * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/stack-stall.json`.
+ */
+import { resolveStackStatePath } from "./base.mjs";
+import { stallStateStore } from "./stall-state-store.mjs";
+const store = stallStateStore((key) => resolveStackStatePath(key, "stack-stall.json"));
+export const readStackStallState = store.read;
+export const writeStackStallState = store.write;
+export const clearStackStallState = store.clear;

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

@@ -0,0 +1,37 @@
+interface StallState {
+    /** Canonicalized JSON fingerprint of the material inputs. */
+    fingerprint: string;
+    /** Unix timestamp (seconds) when this fingerprint was first seen. */
+    firstSeenAt: number;
+}
+/** A missing or unreadable-as-JSON file is `state: null`. Any other I/O or key error is `ok: false`. */
+type StallReadResult = {
+    ok: true;
+    state: StallState | null;
+} | {
+    ok: false;
+    reason: string;
+};
+type StallWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface StallStateStore<Key> {
+    /** Read the current stall state. Does not throw. */
+    read(key: Key): Promise<StallReadResult>;
+    /** Write stall state. Does not throw; `ok: false` means the timer was not saved. */
+    write(key: Key, state: StallState): Promise<StallWriteResult>;
+    /** Clear stall state so the next invocation starts a fresh timer (fire-and-forget — never throws). */
+    clear(key: Key): Promise<void>;
+}
+/**
+ * `{fingerprint, firstSeenAt}` files behind the one-PR and `--stack` stall guards.
+ * A missing file is a miss. An unwritable directory or an unsafe key is a persistence failure
+ * so the caller can hand off instead of treating every tick as the first sighting.
+ * `ENOENT` is the only read error treated as a miss. Corrupt JSON is also a miss, so one
+ * successful rewrite can start the timer again.
+ */
+export declare function stallStateStore<Key>(resolvePath: (key: Key) => string): StallStateStore<Key>;
+export {};

package/bin/state/stall-state-store.mjs

@@ -0,0 +1,74 @@
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+/**
+ * `{fingerprint, firstSeenAt}` files behind the one-PR and `--stack` stall guards.
+ * A missing file is a miss. An unwritable directory or an unsafe key is a persistence failure
+ * so the caller can hand off instead of treating every tick as the first sighting.
+ * `ENOENT` is the only read error treated as a miss. Corrupt JSON is also a miss, so one
+ * successful rewrite can start the timer again.
+ */
+export function stallStateStore(resolvePath) {
+    return {
+        async read(key) {
+            try {
+                const parsed = JSON.parse(await readFile(resolvePath(key), "utf8"));
+                if (parsed === null ||
+                    typeof parsed !== "object" ||
+                    typeof parsed["fingerprint"] !== "string" ||
+                    !Number.isFinite(parsed["firstSeenAt"])) {
+                    return { ok: true, state: null };
+                }
+                return { ok: true, state: parsed };
+            }
+            catch (error) {
+                // A missing file and corrupt JSON are both misses. One successful rewrite can start the timer.
+                if (isEnoent(error) || error instanceof SyntaxError)
+                    return { ok: true, state: null };
+                return { ok: false, reason: errorReason(error) };
+            }
+        },
+        async write(key, state) {
+            let tmp;
+            try {
+                const path = resolvePath(key);
+                tmp = `${path}.${randomUUID()}.tmp`;
+                await mkdir(dirname(path), { recursive: true });
+                await writeFile(tmp, JSON.stringify(state), "utf8");
+                await rename(tmp, path);
+                tmp = undefined;
+                return { ok: true };
+            }
+            catch (error) {
+                return { ok: false, reason: errorReason(error) };
+            }
+            finally {
+                if (tmp !== undefined) {
+                    try {
+                        await unlink(tmp);
+                    }
+                    catch {
+                        // Best-effort cleanup.
+                    }
+                }
+            }
+        },
+        async clear(key) {
+            try {
+                await unlink(resolvePath(key));
+            }
+            catch {
+                // Best-effort — file may not exist. A leftover file can only make a later timer escalate sooner.
+            }
+        },
+    };
+}
+function isEnoent(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function errorReason(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/bin/types/escalate.d.mts

@@ -1,8 +1,8 @@
 import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
-import type { MergeQueueRemovalStatus, StackStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed" | "stacked-pr";
+import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -39,7 +39,6 @@ export interface EscalateDetails {
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;
-    stack?: StackStatus;
     authorization?: Array<{
         action: "mark-ready" | "merge-or-enqueue";
         targetIds: string[];

package/bin/types/github.d.mts

@@ -144,6 +144,8 @@ export interface BatchPrData extends BatchPrMergeFields {
     headRepoWithOwner: string | null;
     viewerAuthorization?: ViewerAuthorization;
     baseRefName: string;
+    /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
+    baseRefOid?: string;
     reviewRequests: Array<{
         login: string;
     }>;

package/bin/types/iterate.d.mts

@@ -1,7 +1,7 @@
 import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
 import type { BranchProtection, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
-import type { MergeRequirements } from "./merge-requirements.mts";
+import type { MergeRequirements, StackDraftHold } from "./merge-requirements.mts";
 import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
@@ -50,6 +50,7 @@ interface IterateResultWait extends IterateResultBase {
     action: "wait";
     log: string;
     deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
+    stackDraftHold?: StackDraftHold;
 }
 export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
 interface IterateResultCancel extends IterateResultBase {

package/bin/types/merge-requirements.d.mts

@@ -39,6 +39,25 @@ export interface StackStatus {
     position: number;
     baseRefName: string;
 }
+/** Why an open native stack layer does not yet let the layers above it advance. */
+export type StackLayerBlockReason = "closed" | "draft" | "conflicting" | "queue-removal" | "failing-checks" | "review-work" | "checks-in-progress" | "merge-state" | "no-ready-receipt" | "stale-ancestry";
+/** The lowest native stack layer that keeps an upper draft from being marked ready. */
+export interface StackLowerLayerBlock {
+    pr: number;
+    reason: StackLayerBlockReason;
+}
+/**
+ * Why a native stack layer stays in draft on a WAIT tick. Repeating the same one-PR
+ * session cannot advance it, so the caller returns to the stack selector. A named
+ * `lowerLayer` is the layer to advance first; without one, the lower layers could not
+ * be verified.
+ */
+export type StackDraftHold = {
+    kind: "lower-layer-not-ready";
+    lowerLayer?: StackLowerLayerBlock;
+} | {
+    kind: "auto-mark-ready-disabled";
+};
 /** Extra batch-PR fields for merge-queue, stacks, and folded branch rules. */
 export interface BatchPrMergeFields {
     branchRules?: BranchRules;