pr-shepherd 0.52.0 → 0.53.0

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

package/bin/state/graphql-quota-policy.d.mts

@@ -7,11 +7,17 @@ export interface GraphqlQuotaWarningState {
     lastRemaining: number;
     resetAt: number;
     warnedThresholds: number[];
+    /** Truncated SHA-256 of the credential. Absent in state written before fingerprints. */
+    credentialFingerprint?: string;
     rearmEpoch?: number;
 }
-export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt">, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
+type GraphqlQuotaSample = Pick<GraphqlApiUsage, "resource" | "limit" | "used" | "remaining" | "resetAt"> & {
+    credentialFingerprint?: string;
+};
+export declare function evaluateGraphqlQuotaWarning(bands: GraphqlQuotaWarningBand[], sample: GraphqlQuotaSample, previous: GraphqlQuotaWarningState | null, observedAt?: number): {
     warning?: GraphqlQuotaWarning;
     state: GraphqlQuotaWarningState & {
         rearmEpoch: number;
     };
 };
+export {};

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

@@ -4,25 +4,28 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
         previous.resource !== sample.resource ||
         previous.limit !== sample.limit ||
         windowRolled ||
-        (sample.used !== undefined && previous.lastUsed !== undefined
-            ? sample.used < previous.lastUsed
-            : sample.remaining > previous.lastRemaining);
-    const warned = new Set(rearm ? [] : previous.warnedThresholds);
+        fingerprintChanged(previous, sample);
+    const effective = !rearm && previous !== null && usageRegressed(previous, sample)
+        ? newerSavedSample(previous)
+        : sample;
+    const warned = new Set(rearm || previous === null ? [] : previous.warnedThresholds);
     const rearmEpoch = rearm ? (previous?.rearmEpoch ?? 0) + 1 : (previous?.rearmEpoch ?? 0);
-    const crossed = bands.filter((band) => sample.remaining * 100 <= sample.limit * band.remainingPercent);
+    const crossed = bands.filter((band) => effective.remaining * 100 <= effective.limit * band.remainingPercent);
     const newCrossed = crossed.filter((band) => !warned.has(band.remainingPercent));
     for (const band of crossed)
         warned.add(band.remainingPercent);
     const active = newCrossed.at(-1);
+    const credentialFingerprint = effective.credentialFingerprint ?? previous?.credentialFingerprint;
     const state = {
-        resource: sample.resource,
-        limit: sample.limit,
-        ...(sample.used !== undefined && { lastUsed: sample.used }),
-        lastRemaining: sample.remaining,
-        resetAt: sample.resetAt,
+        resource: effective.resource,
+        limit: effective.limit,
+        ...(effective.used !== undefined && { lastUsed: effective.used }),
+        lastRemaining: effective.remaining,
+        resetAt: effective.resetAt,
         warnedThresholds: bands
             .map((band) => band.remainingPercent)
             .filter((threshold) => warned.has(threshold)),
+        ...(credentialFingerprint !== undefined && { credentialFingerprint }),
         rearmEpoch,
     };
     if (active === undefined)
@@ -31,13 +34,37 @@ export function evaluateGraphqlQuotaWarning(bands, sample, previous, observedAt
         warning: {
             resource: "graphql",
             thresholdPercent: active.remainingPercent,
-            remaining: sample.remaining,
-            limit: sample.limit,
-            ...(sample.used !== undefined && { used: sample.used }),
-            resetAt: sample.resetAt,
+            remaining: effective.remaining,
+            limit: effective.limit,
+            ...(effective.used !== undefined && { used: effective.used }),
+            resetAt: effective.resetAt,
             pollIntervalMinutes: active.pollIntervalMinutes,
             pollTimeoutMinutes: active.pollIntervalMinutes * 2,
         },
         state,
     };
 }
+function fingerprintChanged(previous, sample) {
+    return (previous.credentialFingerprint !== undefined &&
+        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) {
+    return {
+        resource: previous.resource,
+        limit: previous.limit,
+        ...(previous.lastUsed !== undefined && { used: previous.lastUsed }),
+        remaining: previous.lastRemaining,
+        resetAt: previous.resetAt,
+        ...(previous.credentialFingerprint !== undefined && {
+            credentialFingerprint: previous.credentialFingerprint,
+        }),
+    };
+}

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 {
@@ -74,6 +70,8 @@ async function readState(path) {
             !Array.isArray(parsed.warnedThresholds)) {
             return null;
         }
+        if (typeof parsed.credentialFingerprint !== "string")
+            delete parsed.credentialFingerprint;
         return parsed;
     }
     catch {

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/api-usage.d.mts

@@ -13,6 +13,8 @@ export interface GraphqlApiUsage extends ApiResourceUsage {
     unmeasuredRequestCount: number;
     /** Exact sum reported by rateLimit.nodeCount for measured GraphQL queries. */
     nodeCount: number;
+    /** Truncated SHA-256 of the credential. Quota state only; summarized usage omits it. */
+    credentialFingerprint?: string;
 }
 export interface ApiUsage {
     credentialSources: string[];

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;