pr-shepherd 0.52.0 → 0.52.1

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/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

@@ -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" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed";
+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;

package/bin/types/github.d.mts

@@ -144,7 +144,7 @@ export interface BatchPrData extends BatchPrMergeFields {
     headRepoWithOwner: string | null;
     viewerAuthorization?: ViewerAuthorization;
     baseRefName: string;
-    /** Git OID of the base branch tip observed with this PR, when available. */
+    /** 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;

package/bin/types/poll-summary.d.mts

@@ -58,6 +58,11 @@ export interface PollSummaryItem {
     review?: PollSummaryReview;
     stack?: PollSummaryStack;
     pollCommand?: string;
+    /**
+     * `pollCommand` is one bounded tick without automatic mark-ready: it surfaces and routes review
+     * or CI work but cannot advance this draft, so repeating it for a waiting layer changes nothing.
+     */
+    pollProbe?: true;
     /** A current one-PR READY-after-delay completion was verified. */
     readyReceipt?: true;
     /** Lowest unready ancestor that prevents this layer from being stack-mergeable. */

package/bin/types/report.d.mts

@@ -31,7 +31,7 @@ export interface ShepherdReport {
     status: ShepherdStatus;
     /** PR base branch from the GraphQL batch. */
     baseBranch: string;
-    /** Git OID of the base branch tip observed with this report, when available. */
+    /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
     baseRefOid?: string;
     mergeStatus: MergeStatusResult;
     checks: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.52.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.52.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.52.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.52.1", "pr-shepherd-mcp"]
   }
 }