pr-shepherd 0.52.0 → 0.52.1

package/bin/github/poll-summary-raw.d.mts

@@ -43,8 +43,23 @@ type RawCheckContext = {
     context: string;
     state: string;
 };
-interface RawCheckRollup {
-    contexts: SummaryConnection<RawCheckContext>;
+interface RawCheckContexts {
+    totalCount: number;
+    /** `startCursor` pages older contexts; hydration drops it so fingerprints never hash a cursor. */
+    pageInfo: {
+        hasPreviousPage: boolean;
+        startCursor?: string | null;
+    };
+    nodes: RawCheckContext[];
+}
+export interface RawCheckRollup {
+    contexts: RawCheckContexts;
+}
+/** A commit whose status contexts the compact summary reads. */
+export interface RawSummaryCommit {
+    oid: string;
+    committedDate?: string;
+    statusCheckRollup: RawCheckRollup | null;
 }
 export interface RawSummaryPr {
     number: number;
@@ -103,9 +118,7 @@ export interface RawSummaryPr {
         }>;
     } | null;
     mergeQueueEntry: {
-        headCommit: {
-            statusCheckRollup: RawCheckRollup | null;
-        } | null;
+        headCommit: RawSummaryCommit | null;
     } | null;
     stack: {
         number: number;
@@ -131,9 +144,7 @@ export interface RawSummaryPr {
     }>;
     commits: {
         nodes: Array<{
-            commit: {
-                statusCheckRollup: RawCheckRollup | null;
-            };
+            commit: RawSummaryCommit;
         }>;
     };
 }
@@ -142,27 +153,4 @@ export interface RawExplicitResponse {
         viewerCanAdminister: boolean;
     } & Record<string, RawSummaryPr | boolean | null>) | null;
 }
-export interface RawStackResponse {
-    repository: {
-        viewerCanAdminister: boolean;
-        pullRequest: {
-            stack: {
-                id: string;
-                number: number;
-                size: number;
-                baseRefName: string;
-                entries: {
-                    pageInfo: {
-                        hasNextPage: boolean;
-                        endCursor: string | null;
-                    };
-                    nodes: Array<{
-                        position: number;
-                        pullRequest: RawSummaryPr | null;
-                    }>;
-                };
-            } | null;
-        } | null;
-    } | null;
-}
 export {};

package/bin/github/poll-summary-route.mjs

@@ -25,12 +25,15 @@ export function routePollSummary(raw, checks, review, opts) {
         return { action: "wait", reasons: ["pending-or-unknown"] };
     }
     if (raw.isDraft) {
-        if (opts.noAutoMarkReady || actions.autoMarkReady === false) {
-            return { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] };
+        const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
+        // The stack selector asks the agent to mark a disabled draft ready, so
+        // that transition needs the same capability as the automatic one.
+        if (!raw.viewerCanUpdate && (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+            return { action: "escalate", reasons: ["mark-ready-authorization-required"] };
         }
-        return raw.viewerCanUpdate
-            ? { action: "mark_ready", reasons: ["draft-appears-ready"] }
-            : { action: "escalate", reasons: ["mark-ready-authorization-required"] };
+        return autoMarkReadyDisabled
+            ? { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] }
+            : { action: "mark_ready", reasons: ["draft-appears-ready"] };
     }
     if (opts.merge && raw.isInMergeQueue) {
         return { action: "wait", reasons: ["already-in-merge-queue"] };

package/bin/github/poll-summary.mjs

@@ -1,8 +1,10 @@
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
-import { GitHubRequestError } from "./errors.mjs";
+import { missingRepositoryError } from "./errors.mjs";
+import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
 import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
+import { MAX_STACK_ENTRIES_PER_PAGE, readStack, readStackTopology, stackAncestryGaps, } from "./stack-read.mjs";
 const MAX_EXPLICIT_PRS_PER_QUERY = 50;
 export async function fetchPollSummary(opts, repo) {
     if (opts.stackPrNumber !== undefined)
@@ -42,93 +44,34 @@ async function fetchExplicitChunk(prs, repo) {
         ...variables,
     });
     if (!result.data.repository)
-        throw missingRepository(repo);
+        throw missingRepositoryError(repo);
     const rawPrs = prs.map((pr, index) => {
         const raw = result.data.repository[`pr${index}`];
         if (!raw)
             throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
         return raw;
     });
+    for (const raw of rawPrs)
+        await hydratePollSummaryChecks(raw, repo);
     return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
 }
+/**
+ * Read the stack's topology first so the hydrated page requests only as many
+ * entries as the stack holds: GitHub prices `first`, not the nodes returned.
+ */
 async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
-    let after = null;
-    let stackId = null;
-    let stackNumber = 0;
-    let stackSize = 0;
-    let viewerCanAdminister = false;
-    const entries = [];
-    do {
-        const response = (await graphqlWithRateLimit(POLL_STACK_SUMMARY_QUERY, {
-            owner: repo.owner,
-            repo: repo.name,
-            anchor,
-            after,
-        }));
-        const repository = response.data.repository;
-        if (!repository)
-            throw missingRepository(repo);
-        viewerCanAdminister = repository.viewerCanAdminister;
-        if (!repository.pullRequest) {
-            throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
-        }
-        const stack = repository.pullRequest.stack;
-        if (!stack) {
-            throw new ShepherdError(`PR #${anchor} is not part of a native GitHub stack`, EXIT.UNAVAILABLE);
-        }
-        if (stackId !== null && stack.id !== stackId) {
-            throw new ShepherdError("GitHub stack membership changed while it was being fetched; retry", EXIT.TEMPFAIL);
-        }
-        stackId = stack.id;
-        stackNumber = stack.number;
-        stackSize = stack.size;
-        for (const entry of stack.entries.nodes) {
-            if (!entry.pullRequest) {
-                throw new ShepherdError("GitHub returned an incomplete pull-request stack entry", EXIT.TEMPFAIL);
-            }
-            entries.push({ position: entry.position, pullRequest: entry.pullRequest });
-        }
-        const pageInfo = stack.entries.pageInfo;
-        if (pageInfo.hasNextPage && !pageInfo.endCursor) {
-            throw new ShepherdError("GitHub stack pagination did not include an end cursor", EXIT.TEMPFAIL);
-        }
-        after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
-    } while (after !== null);
-    const unique = new Map();
-    for (const entry of entries)
-        unique.set(entry.pullRequest.number, entry);
-    if (!unique.has(anchor) || unique.size !== stackSize) {
-        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
-    }
-    const ordered = [...unique.values()].sort((left, right) => left.position - right.position);
-    const stackAncestry = [];
-    for (let index = 1; index < ordered.length; index++) {
-        const parent = ordered[index - 1].pullRequest;
-        const child = ordered[index].pullRequest;
-        if (parent.state !== "OPEN" || child.state !== "OPEN")
-            continue;
-        if (child.baseRefName === parent.headRefName && child.baseRefOid === parent.headRefOid) {
-            continue;
-        }
-        stackAncestry.push({
-            parentPr: parent.number,
-            parentHeadRefName: parent.headRefName,
-            parentHeadRefOid: parent.headRefOid,
-            childPr: child.number,
-            childBaseRefName: child.baseRefName,
-            childBaseRefOid: child.baseRefOid,
-        });
-    }
+    const topology = await readStackTopology(anchor, repo);
+    const { stackNumber, stackSize, viewerCanAdminister, ordered } = await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first: Math.min(topology.stackSize, MAX_STACK_ENTRIES_PER_PAGE) });
+    for (const pr of ordered)
+        await hydratePollSummaryChecks(pr, repo);
+    const stackAncestry = stackAncestryGaps(ordered);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
-        prs: await Promise.all(ordered.map((entry) => summarizePollSummaryPr(entry.pullRequest, repo, opts, viewerCanAdminister))),
+        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
         ...(stackAncestry.length > 0 && { stackAncestry }),
     };
 }
 function deduplicate(values) {
     return [...new Set(values)];
 }
-function missingRepository(repo) {
-    return new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
-}

package/bin/github/queries.d.mts

@@ -14,8 +14,15 @@ export declare const BATCH_PR_PAGE_QUERY: string;
 export declare const PR_FINGERPRINT_QUERY: string;
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
 export declare const POLL_SUMMARY_FRAGMENT: string;
+/**
+ * Pages older status contexts for one commit with the same node selection as
+ * the compact summary, so hydrated and first-page nodes fingerprint alike.
+ */
+export declare const POLL_SUMMARY_CHECK_PAGE_QUERY: string;
 /** Discovers and summarizes every entry in one native GitHub pull-request stack. */
 export declare const POLL_STACK_SUMMARY_QUERY: string;
+/** Reads only native-stack membership and the refs that link adjacent entries. */
+export declare const POLL_STACK_TOPOLOGY_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queries.mjs

@@ -16,10 +16,18 @@ export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
 /** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
 export const PR_FINGERPRINT_QUERY = withSharedFragments(gql("pr-fingerprint.gql"));
+const POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT = gql("poll-summary-check-contexts.gql");
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
-export const POLL_SUMMARY_FRAGMENT = gql("poll-summary-fragment.gql");
+export const POLL_SUMMARY_FRAGMENT = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+/**
+ * Pages older status contexts for one commit with the same node selection as
+ * the compact summary, so hydrated and first-page nodes fingerprint alike.
+ */
+export const POLL_SUMMARY_CHECK_PAGE_QUERY = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-check-page.gql")}`;
 /** Discovers and summarizes every entry in one native GitHub pull-request stack. */
 export const POLL_STACK_SUMMARY_QUERY = `${POLL_SUMMARY_FRAGMENT}\n${gql("poll-stack-summary.gql")}`;
+/** Reads only native-stack membership and the refs that link adjacent entries. */
+export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queue-removal-freshness.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Whether a removed merge-queue commit still belongs to the current PR head.
+ *
+ * A merge-commit queue lists that head as a parent. Squash and rebase queues
+ * build a one-parent commit on the base (or on the previous group commit), so
+ * the PR head is not an ancestor. Missing parents are unverifiable: GitHub
+ * keeps returning the latest removal after the synthetic commit is gone.
+ * A one-parent removal is stale when the current head's committer time is
+ * later than the removal, which is a push after the ejection.
+ */
+export declare function queueRemovalAppliesToHead(input: {
+    parentOids: readonly string[] | null | undefined;
+    headOid: string;
+    headCommittedAtUnix?: number;
+    removedAtUnix?: number;
+}): boolean;

package/bin/github/queue-removal-freshness.mjs

@@ -0,0 +1,26 @@
+/**
+ * Whether a removed merge-queue commit still belongs to the current PR head.
+ *
+ * A merge-commit queue lists that head as a parent. Squash and rebase queues
+ * build a one-parent commit on the base (or on the previous group commit), so
+ * the PR head is not an ancestor. Missing parents are unverifiable: GitHub
+ * keeps returning the latest removal after the synthetic commit is gone.
+ * A one-parent removal is stale when the current head's committer time is
+ * later than the removal, which is a push after the ejection.
+ */
+export function queueRemovalAppliesToHead(input) {
+    const parents = input.parentOids ?? [];
+    if (parents.length === 0)
+        return false;
+    if (parents.includes(input.headOid))
+        return true;
+    if (parents.length > 1)
+        return false;
+    if (input.headCommittedAtUnix !== undefined &&
+        input.removedAtUnix !== undefined &&
+        input.removedAtUnix > 0 &&
+        input.headCommittedAtUnix > input.removedAtUnix) {
+        return false;
+    }
+    return true;
+}

package/bin/github/stack-read.d.mts

@@ -0,0 +1,34 @@
+import type { PollSummaryStackAncestry } from "../types.mts";
+import { type RepoInfo } from "./client.mts";
+/** GitHub's `first` ceiling for one native-stack entries page. */
+export declare const MAX_STACK_ENTRIES_PER_PAGE = 50;
+/** Fields every native-stack read needs to validate membership and adjacent ancestry. */
+export interface StackMemberRefs {
+    number: number;
+    state: string;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    baseRefOid: string;
+}
+/** One complete, validated native-stack membership read. */
+export interface StackRead<Pr extends StackMemberRefs> {
+    stackNumber: number;
+    stackSize: number;
+    viewerCanAdminister: boolean;
+    /** Every member, bottom-to-top, each observed in the same paged read. */
+    ordered: Pr[];
+}
+/**
+ * Page through one native stack and fail closed on anything short of the full
+ * membership: a missing repository, PR, or stack; a changed stack identity; a
+ * null entry; a page without a cursor; or fewer unique members than `size`.
+ */
+export declare function readStack<Pr extends StackMemberRefs>(query: string, anchor: number, repo: RepoInfo, variables?: Record<string, unknown>): Promise<StackRead<Pr>>;
+/** Membership and linking refs only — no per-PR CI or review hydration. */
+export declare function readStackTopology(anchor: number, repo: RepoInfo): Promise<StackRead<StackMemberRefs>>;
+/**
+ * Adjacent entries, both open, whose child base no longer matches the parent
+ * head. Both sides come from the same read, so each gap was observed together.
+ */
+export declare function stackAncestryGaps(ordered: StackMemberRefs[]): PollSummaryStackAncestry[];

package/bin/github/stack-read.mjs

@@ -0,0 +1,92 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { missingRepositoryError } from "./errors.mjs";
+import { POLL_STACK_TOPOLOGY_QUERY } from "./queries.mjs";
+/** GitHub's `first` ceiling for one native-stack entries page. */
+export const MAX_STACK_ENTRIES_PER_PAGE = 50;
+/**
+ * Page through one native stack and fail closed on anything short of the full
+ * membership: a missing repository, PR, or stack; a changed stack identity; a
+ * null entry; a page without a cursor; or fewer unique members than `size`.
+ */
+export async function readStack(query, anchor, repo, variables = {}) {
+    let after = null;
+    let stackId = null;
+    let stackNumber = 0;
+    let stackSize = 0;
+    let viewerCanAdminister = false;
+    const entries = [];
+    do {
+        const response = await graphqlWithRateLimit(query, { owner: repo.owner, repo: repo.name, anchor, after, ...variables });
+        const repository = response.data.repository;
+        if (!repository)
+            throw missingRepositoryError(repo);
+        viewerCanAdminister = repository.viewerCanAdminister;
+        if (!repository.pullRequest) {
+            throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
+        }
+        const stack = repository.pullRequest.stack;
+        if (!stack) {
+            throw new ShepherdError(`PR #${anchor} is not part of a native GitHub stack`, EXIT.UNAVAILABLE);
+        }
+        if (stackId !== null && stack.id !== stackId) {
+            throw new ShepherdError("GitHub stack membership changed while it was being fetched; retry", EXIT.TEMPFAIL);
+        }
+        stackId = stack.id;
+        stackNumber = stack.number;
+        stackSize = stack.size;
+        for (const entry of stack.entries.nodes) {
+            if (!entry.pullRequest) {
+                throw new ShepherdError("GitHub returned an incomplete pull-request stack entry", EXIT.TEMPFAIL);
+            }
+            entries.push({ position: entry.position, pullRequest: entry.pullRequest });
+        }
+        const pageInfo = stack.entries.pageInfo;
+        if (pageInfo.hasNextPage && !pageInfo.endCursor) {
+            throw new ShepherdError("GitHub stack pagination did not include an end cursor", EXIT.TEMPFAIL);
+        }
+        if (pageInfo.hasNextPage && pageInfo.endCursor === after) {
+            throw new ShepherdError("GitHub stack pagination returned a repeated end cursor", EXIT.TEMPFAIL);
+        }
+        after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
+    } while (after !== null);
+    const unique = new Map();
+    for (const entry of entries)
+        unique.set(entry.pullRequest.number, entry);
+    if (!unique.has(anchor) || unique.size !== stackSize) {
+        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
+    }
+    const ordered = [...unique.values()]
+        .sort((left, right) => left.position - right.position)
+        .map((entry) => entry.pullRequest);
+    return { stackNumber, stackSize, viewerCanAdminister, ordered };
+}
+/** Membership and linking refs only — no per-PR CI or review hydration. */
+export function readStackTopology(anchor, repo) {
+    return readStack(POLL_STACK_TOPOLOGY_QUERY, anchor, repo);
+}
+/**
+ * Adjacent entries, both open, whose child base no longer matches the parent
+ * head. Both sides come from the same read, so each gap was observed together.
+ */
+export function stackAncestryGaps(ordered) {
+    const gaps = [];
+    for (let index = 1; index < ordered.length; index++) {
+        const parent = ordered[index - 1];
+        const child = ordered[index];
+        if (parent.state !== "OPEN" || child.state !== "OPEN")
+            continue;
+        if (child.baseRefName === parent.headRefName && child.baseRefOid === parent.headRefOid) {
+            continue;
+        }
+        gaps.push({
+            parentPr: parent.number,
+            parentHeadRefName: parent.headRefName,
+            parentHeadRefOid: parent.headRefOid,
+            childPr: child.number,
+            childBaseRefName: child.baseRefName,
+            childBaseRefOid: child.baseRefOid,
+        });
+    }
+    return gaps;
+}

package/bin/log/log-file.d.mts

@@ -1,7 +1,7 @@
 /**
  * Append-only per-worktree markdown log.
  *
- * Log path: $PR_SHEPHERD_STATE_DIR/<owner>-<repo>/worktrees/<basename>-<sha8>.md
+ * Log path: $PR_SHEPHERD_STATE_DIR/<owner>/<repo>/worktrees/<basename>-<sha8>.md
  *
  * Always-on by default. Set PR_SHEPHERD_LOG_DISABLED=1 or CI=true to disable.
  * Write failures flip an internal disabled flag so the CLI never crashes because

package/bin/log/log-file.mjs

@@ -1,7 +1,7 @@
 /**
  * Append-only per-worktree markdown log.
  *
- * Log path: $PR_SHEPHERD_STATE_DIR/<owner>-<repo>/worktrees/<basename>-<sha8>.md
+ * Log path: $PR_SHEPHERD_STATE_DIR/<owner>/<repo>/worktrees/<basename>-<sha8>.md
  *
  * Always-on by default. Set PR_SHEPHERD_LOG_DISABLED=1 or CI=true to disable.
  * Write failures flip an internal disabled flag so the CLI never crashes because
@@ -9,8 +9,7 @@
  */
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { resolveStateBase } from "../state/base.mjs";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveRepoStateDir } from "../state/base.mjs";
 import { getWorktreeKey } from "../util/worktree.mjs";
 function computeDisabled() {
     if (process.env["PR_SHEPHERD_LOG_DISABLED"] === "1")
@@ -26,14 +25,9 @@ export function nextEntry() {
     return ++_entryCounter;
 }
 export function getLogFilePath(key) {
-    const { owner, repo } = key;
-    if (!SAFE_SEGMENT.test(owner) || !SAFE_SEGMENT.test(repo)) {
-        throw new Error(`Invalid repo key segments: ${owner}/${repo}`);
-    }
-    const base = resolveStateBase();
     // Worktree key injected at init time; fall back to "unknown" if not yet set.
     const wkey = _worktreeKey ?? "unknown";
-    return join(base, `${owner}-${repo}`, "worktrees", `${wkey}.md`);
+    return join(resolveRepoStateDir(key), "worktrees", `${wkey}.md`);
 }
 let _worktreeKey = null;
 /**
@@ -44,9 +38,6 @@ export async function initLog(repoKey) {
     if (_disabled)
         return null;
     try {
-        const { owner, repo } = repoKey;
-        if (!SAFE_SEGMENT.test(owner) || !SAFE_SEGMENT.test(repo))
-            return null;
         _worktreeKey = await getWorktreeKey();
         const path = getLogFilePath(repoKey);
         mkdirSync(dirname(path), { recursive: true });
@@ -72,12 +63,8 @@ export function appendEntry(markdown) {
 }
 /** Resolve the log path without initializing (for the log-file subcommand). */
 export async function resolveLogPath(repoKey) {
-    if (!SAFE_SEGMENT.test(repoKey.owner) || !SAFE_SEGMENT.test(repoKey.repo)) {
-        throw new Error(`Invalid repo key segments: ${repoKey.owner}/${repoKey.repo}`);
-    }
     const wkey = await getWorktreeKey();
-    const base = resolveStateBase();
-    return join(base, `${repoKey.owner}-${repoKey.repo}`, "worktrees", `${wkey}.md`);
+    return join(resolveRepoStateDir(repoKey), "worktrees", `${wkey}.md`);
 }
 /** Exposed for tests to reset module state. */
 export function _resetLogState() {

package/bin/state/base.d.mts

@@ -1,6 +1,6 @@
 export declare function resolveStateBase(): string;
 /**
- * `$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 declare function resolvePrStatePath(key: {
@@ -8,3 +8,20 @@ export declare function resolvePrStatePath(key: {
     repo: string;
     pr: number;
 }, ...parts: string[]): string;
+/**
+ * `$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 declare function resolveStackStatePath(key: {
+    owner: string;
+    repo: string;
+    stack: number;
+}, ...parts: string[]): string;
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>`.
+ * Owner and repo are separate segments so names that contain hyphens cannot collide.
+ */
+export declare function resolveRepoStateDir(key: {
+    owner: string;
+    repo: string;
+}): string;

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";