pr-shepherd 0.52.0 → 0.53.0

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

@@ -0,0 +1,14 @@
+import type { PollSummaryItem, PollSummaryResult } from "../types.mts";
+/**
+ * A `--stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
+ * stall guards cannot fire. Escalate `stall-timeout` once that idle plan's fingerprint stays
+ * unchanged for `stallTimeoutSeconds`; any other plan, or `0`, clears the timer. When the enabled
+ * timer cannot be read or written, escalate `stall-state-unavailable` instead of restarting it.
+ */
+export declare function applyStackStallGuard(planned: {
+    result: PollSummaryResult;
+    idle?: PollSummaryItem[];
+}, repo: {
+    owner: string;
+    name: string;
+}, stallTimeoutSeconds: number): Promise<PollSummaryResult>;

package/bin/commands/stack-stall.mjs

@@ -0,0 +1,68 @@
+import { clearStackStallState, readStackStallState, writeStackStallState, } from "../state/stack-stall.mjs";
+import { formatDurationApprox } from "./iterate/escalate.mjs";
+import { summaryStatusSignature } from "./poll-summary-signature.mjs";
+import { describeIdleLayers } from "./stack-drain.mjs";
+/**
+ * A `--stack` plan that can only wait never reruns its layers' one-PR sessions, so their own
+ * stall guards cannot fire. Escalate `stall-timeout` once that idle plan's fingerprint stays
+ * unchanged for `stallTimeoutSeconds`; any other plan, or `0`, clears the timer. When the enabled
+ * timer cannot be read or written, escalate `stall-state-unavailable` instead of restarting it.
+ */
+export async function applyStackStallGuard(planned, repo, stallTimeoutSeconds) {
+    const { result, idle } = planned;
+    if (result.selection.kind !== "stack")
+        return result;
+    const key = { owner: repo.owner, repo: repo.name, stack: result.selection.stackNumber };
+    if (!idle || stallTimeoutSeconds <= 0) {
+        await clearStackStallState(key);
+        return result;
+    }
+    const fingerprint = stackStallFingerprint(result);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const read = await readStackStallState(key);
+    if (!read.ok)
+        return stackStateUnavailable(result, read.reason);
+    const stored = read.state;
+    if (!stored || stored.fingerprint !== fingerprint || stored.firstSeenAt > nowSeconds) {
+        const wrote = await writeStackStallState(key, { fingerprint, firstSeenAt: nowSeconds });
+        if (!wrote.ok)
+            return stackStateUnavailable(result, wrote.reason);
+        return result;
+    }
+    const ageSeconds = nowSeconds - stored.firstSeenAt;
+    if (ageSeconds < stallTimeoutSeconds)
+        return result;
+    return {
+        ...result,
+        reason: "actionable",
+        nextAction: "escalate",
+        stackMergeable: false,
+        instructions: [
+            `1. \`stall-timeout\`: the stack has not changed for ${formatDurationApprox(ageSeconds)} while no one-PR session could advance it: ${describeIdleLayers(idle)}. Stop and ask a human to unblock the waiting layers.`,
+        ],
+    };
+}
+function stackStateUnavailable(result, reason) {
+    return {
+        ...result,
+        reason: "actionable",
+        nextAction: "escalate",
+        stackMergeable: false,
+        instructions: [
+            `1. \`stall-state-unavailable\`: the stack stall timer could not be saved (${reason}). Stop and ask a human to fix the state directory before resuming.`,
+        ],
+    };
+}
+/** The status signature plus the per-layer evidence it omits, so a push resets the timer. */
+function stackStallFingerprint(result) {
+    return JSON.stringify({
+        status: summaryStatusSignature(result),
+        layers: result.prs.map((item) => ({
+            pr: item.pr,
+            headRefOid: item.headRefOid,
+            isDraft: item.isDraft,
+            readyReceipt: item.readyReceipt,
+            reasons: item.reasons,
+        })),
+    });
+}

package/bin/commands/stack-work.d.mts

@@ -0,0 +1,32 @@
+import type { PollSummaryItem } from "../types.mts";
+type ProbedLayer = PollSummaryItem & {
+    pollCommand: string;
+    pollProbe: true;
+};
+/**
+ * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
+ * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
+ */
+export declare const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
+/** How the stack selector routes the autonomous layers that still need work. */
+export interface StackWork {
+    /** Layers that need a one-PR Shepherd session, with or without a known command. */
+    sessions: PollSummaryItem[];
+    /** Clean, unblocked drafts that the agent marks ready because the poll loop will not. */
+    markReady: ProbedLayer[];
+    /** Layers whose bounded probe could only report that they are still waiting. */
+    idle: ProbedLayer[];
+}
+/**
+ * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
+ * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * A stale-ancestry child keeps its session, which returns the ancestry repair.
+ */
+export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
+/**
+ * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
+ * first because only the one-PR session reads the full review context.
+ */
+export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
+export {};

package/bin/commands/stack-work.mjs

@@ -0,0 +1,38 @@
+/**
+ * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
+ * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
+ */
+export const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
+/**
+ * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
+ * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
+ * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * A stale-ancestry child keeps its session, which returns the ancestry repair.
+ */
+export function splitStackWork(candidates, staleChildren) {
+    const work = { sessions: [], markReady: [], idle: [] };
+    for (const item of candidates) {
+        if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
+            work.sessions.push(item);
+        }
+        else if (item.reasons.includes("draft-auto-mark-ready-disabled")) {
+            work.markReady.push(item);
+        }
+        else {
+            work.idle.push(item);
+        }
+    }
+    return work;
+}
+/**
+ * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
+ * first because only the one-PR session reads the full review context.
+ */
+export function appendMarkReadyInstructions(instructions, layers) {
+    for (const item of layers) {
+        instructions.push(`${instructions.length + 1}. Automatic mark-ready is disabled, so marking PR #${item.pr} ready for review is your step. Run \`${item.pollCommand}\` first. If it returns \`[WAIT]\` saying PR #${item.pr} stays in draft because ${AUTO_MARK_READY_DISABLED_HOLD}, run \`gh pr ready ${item.pr} -R ${item.repo}\`; otherwise complete its instructions and leave PR #${item.pr} in draft this round.`);
+    }
+}
+function isProbed(item) {
+    return item.pollProbe === true && item.pollCommand !== undefined;
+}

package/bin/config/load.d.mts

@@ -15,6 +15,8 @@ interface PollConfig {
 export interface PrShepherdConfig {
     /** Optional user classification configuration; preserved for rule consumers. */
     classify?: unknown;
+    /** Argv prefix for every pr-shepherd command Shepherd emits, e.g. `["pnpm", "exec", "pr-shepherd"]`. */
+    cliCommand: string[];
     /** GitHub logins that should be treated as bots even when GitHub reports User/Unknown. */
     botUsernames: string[];
     /** Case-insensitive glob patterns for check/status context names Shepherd should ignore. */

package/bin/config/load.mjs

@@ -76,6 +76,14 @@ function parseResolveOtherHumanThreads(value) {
     }
     throw new Error(`Invalid config: iterate.resolveOtherHumanThreads must be one of "none", "outdated", or "always", got ${JSON.stringify(value)}`);
 }
+function parseCliCommand(value) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((arg) => typeof arg === "string" && arg.trim() !== "")) {
+        throw new Error("Invalid config: cliCommand must be a non-empty array of non-empty strings");
+    }
+    return value;
+}
 function parseBotUsernames(value) {
     if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
         throw new Error(`Invalid config: botUsernames must be an array of strings`);
@@ -223,6 +231,7 @@ function parseGraphqlQuotaWarnings(value, pollIntervalSeconds) {
 }
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",
+    "cliCommand",
     "botUsernames",
     "ignoreChecks",
     "iterate",
@@ -284,6 +293,7 @@ function warnUnknownConfigKeys(config) {
 const rawDefaults = builtins;
 function parseConfig(value, normalizeMergeArgs = true) {
     const config = value;
+    config.cliCommand = parseCliCommand(config.cliCommand);
     config.botUsernames = parseBotUsernames(config.botUsernames);
     config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
     config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);

package/bin/config.json

@@ -1,4 +1,5 @@
 {
+  "cliCommand": ["pr-shepherd"],
   "botUsernames": [
     "chatgpt-connector",
     "openai-codex",

package/bin/github/api-telemetry-aggregate.d.mts

@@ -9,6 +9,7 @@ export interface TelemetryAggregate {
         unmeasuredRequestCount: number;
         nodeCount: number;
         rateLimit?: RateLimitInfo;
+        credentialFingerprint?: string;
     };
     rest: Map<string, {
         requestCount: number;

package/bin/github/api-telemetry-aggregate.mjs

@@ -21,7 +21,7 @@ export function aggregateEvents(events) {
                 aggregate.graphql.measuredQueryCost += event.rateLimit.cost;
             aggregate.graphql.nodeCount += event.rateLimit?.nodeCount ?? 0;
             if (event.rateLimit !== undefined) {
-                aggregate.graphql.rateLimit = selectAuthoritativeRateLimit(aggregate.graphql.rateLimit, event.rateLimit);
+                adoptGraphqlRateLimit(aggregate.graphql, event.rateLimit, event.credentialFingerprint);
             }
             continue;
         }
@@ -48,7 +48,7 @@ export function mergeAggregate(target, source) {
     target.graphql.unmeasuredRequestCount += source.graphql.unmeasuredRequestCount;
     target.graphql.nodeCount += source.graphql.nodeCount;
     if (source.graphql.rateLimit !== undefined) {
-        target.graphql.rateLimit = selectAuthoritativeRateLimit(target.graphql.rateLimit, source.graphql.rateLimit);
+        adoptGraphqlRateLimit(target.graphql, source.graphql.rateLimit, source.graphql.credentialFingerprint);
     }
     for (const [resource, sourceGroup] of source.rest) {
         const targetGroup = target.rest.get(resource) ?? { requestCount: 0 };
@@ -65,6 +65,12 @@ export function aggregateStore(active) {
     mergeAggregate(all, aggregateEvents(active.events));
     return all;
 }
+function adoptGraphqlRateLimit(graphql, candidate, fingerprint) {
+    const next = selectAuthoritativeRateLimit(graphql.rateLimit, candidate);
+    if (next !== graphql.rateLimit)
+        graphql.credentialFingerprint = fingerprint;
+    graphql.rateLimit = next;
+}
 function selectAuthoritativeRateLimit(current, candidate) {
     if (current === undefined)
         return { ...candidate };

package/bin/github/api-telemetry.d.mts

@@ -4,10 +4,14 @@ export interface ApiTelemetryEvent {
     kind: "GraphQL" | "REST";
     method: string;
     authSource: string;
+    /** Truncated SHA-256 of the credential that produced this request. */
+    credentialFingerprint?: string;
     rateLimit?: RateLimitInfo;
 }
 /** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
 export declare function withApiTelemetryScope<T>(fn: () => Promise<T>): Promise<T>;
 export declare function recordApiTelemetry(event: ApiTelemetryEvent): void;
 export declare function mergeGraphqlRateLimit(headerRateLimit: RateLimitInfo | null, data: unknown): RateLimitInfo | null;
+/** Attach the credential fingerprint without adding it when this command has none. */
+export declare function withGraphqlCredentialFingerprint<T extends object>(sample: T): T;
 export declare function summarizeApiTelemetry(): ApiUsage | undefined;

package/bin/github/api-telemetry.mjs

@@ -65,6 +65,18 @@ export function mergeGraphqlRateLimit(headerRateLimit, data) {
         ...(payload !== null && Number.isFinite(payload.nodeCount) && { nodeCount: payload.nodeCount }),
     };
 }
+/** Fingerprint of the credential that owns the authoritative GraphQL rate-limit sample. */
+function graphqlQuotaCredentialFingerprint() {
+    const active = store();
+    if (active === undefined)
+        return undefined;
+    return aggregateStore(active).graphql.credentialFingerprint;
+}
+/** Attach the credential fingerprint without adding it when this command has none. */
+export function withGraphqlCredentialFingerprint(sample) {
+    const credentialFingerprint = graphqlQuotaCredentialFingerprint();
+    return credentialFingerprint === undefined ? sample : { ...sample, credentialFingerprint };
+}
 export function summarizeApiTelemetry() {
     const active = store();
     if (active === undefined)

package/bin/github/batch-parsers.mjs

@@ -125,7 +125,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
                 null,
         },
         baseRefName: raw.baseRefName,
-        ...(raw.baseRef?.target?.oid && { baseRefOid: raw.baseRef.target.oid }),
+        ...(raw.baseRefOid && { baseRefOid: raw.baseRefOid }),
         reviewRequests,
         latestReviews,
         reviewThreads,

package/bin/github/batch-raw-rules.d.mts

@@ -80,9 +80,6 @@ interface RawRuleParameters {
     }>;
 }
 export interface RawBaseRef {
-    target?: {
-        oid: string;
-    } | null;
     branchProtectionRule: RawBranchProtectionRule | null;
     rules: {
         pageInfo?: {

package/bin/github/batch-raw-types.d.mts

@@ -30,6 +30,8 @@ export interface RawPr extends RawPrMergeFields {
         viewerPermission: string | null;
     } | null;
     baseRefName: string;
+    /** `PullRequest.baseRefOid`: the base commit GitHub recorded for this PR, not the branch's live tip. */
+    baseRefOid?: string;
     baseRef: import("./batch-raw-rules.mts").RawBaseRef | null;
     reviewRequests: {
         nodes: Array<{

package/bin/github/errors.d.mts

@@ -10,6 +10,11 @@ export interface GitHubGraphQlError {
 }
 /** GitHub GraphQL engine crash: HTTP 200, `data: null`, INTERNAL type/code or message. */
 export declare function isRetryableGraphQlInternal(graphqlErrors?: GitHubGraphQlError[]): boolean;
+/** HTTP 200 GraphQL response whose `repository` field resolved to null. */
+export declare function missingRepositoryError(repo: {
+    owner: string;
+    name: string;
+}): GitHubRequestError;
 export declare class GitHubRequestError extends ShepherdError {
     readonly status: number;
     readonly rateLimit?: RateLimitInfo;

package/bin/github/errors.mjs

@@ -47,6 +47,10 @@ function classifyStatus(status, rateLimit, retryAfterSeconds, graphqlErrors) {
         return EXIT.NOPERM;
     return EXIT.UNAVAILABLE;
 }
+/** HTTP 200 GraphQL response whose `repository` field resolved to null. */
+export function missingRepositoryError(repo) {
+    return new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
+}
 export class GitHubRequestError extends ShepherdError {
     status;
     rateLimit;

package/bin/github/gql/batch-pr.gql

@@ -35,6 +35,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
         viewerPermission
       }
       baseRefName
+      baseRefOid
       isInMergeQueue
       ...PrMergePolicy
       autoMergeRequest {

package/bin/github/gql/poll-stack-summary.gql

@@ -1,4 +1,10 @@
-query PollStackSummary($owner: String!, $repo: String!, $anchor: Int!, $after: String) {
+query PollStackSummary(
+  $owner: String!
+  $repo: String!
+  $anchor: Int!
+  $first: Int!
+  $after: String
+) {
   _shepherdRateLimit: rateLimit {
     cost
     limit
@@ -15,7 +21,7 @@ query PollStackSummary($owner: String!, $repo: String!, $anchor: Int!, $after: S
         number
         size
         baseRefName
-        entries(first: 50, after: $after) {
+        entries(first: $first, after: $after) {
           pageInfo {
             hasNextPage
             endCursor

package/bin/github/gql/poll-stack-topology.gql

@@ -0,0 +1,38 @@
+query PollStackTopology($owner: String!, $repo: String!, $anchor: Int!, $after: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $repo) {
+    viewerCanAdminister
+    pullRequest(number: $anchor) {
+      stack {
+        id
+        number
+        size
+        baseRefName
+        entries(first: 50, after: $after) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          nodes {
+            position
+            pullRequest {
+              number
+              state
+              headRefName
+              headRefOid
+              baseRefName
+              baseRefOid
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/poll-summary-check-contexts.gql

@@ -0,0 +1,34 @@
+fragment PollSummaryCheckContexts on StatusCheckRollupContextConnection {
+  totalCount
+  pageInfo {
+    hasPreviousPage
+    startCursor
+  }
+  nodes {
+    __typename
+    ... on CheckRun {
+      id
+      name
+      status
+      conclusion
+      detailsUrl
+      annotations(first: 1) {
+        totalCount
+      }
+      checkSuite {
+        workflowRun {
+          databaseId
+          event
+          workflow {
+            databaseId
+            name
+          }
+        }
+      }
+    }
+    ... on StatusContext {
+      context
+      state
+    }
+  }
+}

package/bin/github/gql/poll-summary-check-page.gql

@@ -0,0 +1,23 @@
+query PollSummaryCheckPage($owner: String!, $repo: String!, $oid: GitObjectID!, $before: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $repo) {
+    object(oid: $oid) {
+      __typename
+      ... on Commit {
+        oid
+        statusCheckRollup {
+          contexts(last: 100, before: $before) {
+            ...PollSummaryCheckContexts
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/poll-summary-fragment.gql

@@ -88,39 +88,10 @@ fragment PollSummaryPr on PullRequest {
   }
   mergeQueueEntry {
     headCommit {
+      oid
       statusCheckRollup {
         contexts(last: 100) {
-          totalCount
-          pageInfo {
-            hasPreviousPage
-          }
-          nodes {
-            __typename
-            ... on CheckRun {
-              id
-              name
-              status
-              conclusion
-              detailsUrl
-              annotations(first: 1) {
-                totalCount
-              }
-              checkSuite {
-                workflowRun {
-                  databaseId
-                  event
-                  workflow {
-                    databaseId
-                    name
-                  }
-                }
-              }
-            }
-            ... on StatusContext {
-              context
-              state
-            }
-          }
+          ...PollSummaryCheckContexts
         }
       }
     }
@@ -212,39 +183,11 @@ fragment PollSummaryPr on PullRequest {
   commits(last: 1) {
     nodes {
       commit {
+        oid
+        committedDate
         statusCheckRollup {
           contexts(last: 100) {
-            totalCount
-            pageInfo {
-              hasPreviousPage
-            }
-            nodes {
-              __typename
-              ... on CheckRun {
-                id
-                name
-                status
-                conclusion
-                detailsUrl
-                annotations(first: 1) {
-                  totalCount
-                }
-                checkSuite {
-                  workflowRun {
-                    databaseId
-                    event
-                    workflow {
-                      databaseId
-                      name
-                    }
-                  }
-                }
-              }
-              ... on StatusContext {
-                context
-                state
-              }
-            }
+            ...PollSummaryCheckContexts
           }
         }
       }

package/bin/github/gql/pr-merge-policy.gql

@@ -1,9 +1,6 @@
 fragment PrMergePolicy on PullRequest {
   isMergeQueueEnabled
   baseRef {
-    target {
-      oid
-    }
     branchProtectionRule {
       requiresApprovingReviews
       requiredApprovingReviewCount

package/bin/github/graphql-http.mjs

@@ -22,9 +22,11 @@ async function graphqlInner(query, vars, opts) {
     }));
     const t0 = performance.now();
     let authSource = "unknown";
+    let credentialFingerprint;
     const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
+        credentialFingerprint = auth.fingerprint;
         return fetch(url, {
             method: "POST",
             headers: auth.headers,
@@ -38,6 +40,7 @@ async function graphqlInner(query, vars, opts) {
         response,
         durationMs,
         authSource,
+        credentialFingerprint,
     }));
     const durationMs = Math.round(performance.now() - retryT0);
     const headerRateLimit = parseRateLimit(res.headers);
@@ -61,6 +64,7 @@ async function graphqlInner(query, vars, opts) {
             kind: "GraphQL",
             method: "POST",
             authSource,
+            credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
         throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
@@ -93,6 +97,7 @@ async function graphqlInner(query, vars, opts) {
             kind: "GraphQL",
             method: "POST",
             authSource,
+            credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
         throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
@@ -123,6 +128,7 @@ async function graphqlInner(query, vars, opts) {
         kind: "GraphQL",
         method: "POST",
         authSource,
+        credentialFingerprint,
         rateLimit: rateLimit ?? undefined,
     });
     const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);

package/bin/github/http-auth.d.mts

@@ -2,6 +2,8 @@ export type AuthSource = "GH_TOKEN" | "GITHUB_TOKEN" | "gh auth token" | "GITHUB
 export declare function _resetTokenCache(): void;
 export declare function hasCachedToken(): boolean;
 export declare function clearTokenCache(): void;
+/** Truncated SHA-256. Callers persist this instead of the token or its full hash. */
+export declare function credentialFingerprint(token: string): string;
 /**
  * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
  * conditional REST requests) on top of the standard auth/version headers.
@@ -9,4 +11,5 @@ export declare function clearTokenCache(): void;
 export declare function makeAuthHeaders(extra?: Record<string, string>): Promise<{
     headers: Record<string, string>;
     source: AuthSource;
+    fingerprint: string;
 }>;

package/bin/github/http-auth.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -15,6 +16,10 @@ export function clearTokenCache() {
     _token = undefined;
     _tokenSource = undefined;
 }
+/** Truncated SHA-256. Callers persist this instead of the token or its full hash. */
+export function credentialFingerprint(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
 async function resolveToken() {
     if (_token && _tokenSource)
         return { token: _token, source: _tokenSource };
@@ -58,6 +63,7 @@ export async function makeAuthHeaders(extra) {
     const { token, source } = await resolveToken();
     return {
         source,
+        fingerprint: credentialFingerprint(token),
         headers: {
             Authorization: `Bearer ${token}`,
             Accept: "application/vnd.github+json",

package/bin/github/http-intermediate.d.mts

@@ -6,4 +6,5 @@ export declare function recordIntermediateResponse(opts: {
     response: Response;
     durationMs: number;
     authSource: string;
+    credentialFingerprint?: string;
 }): void;

package/bin/github/http-intermediate.mjs

@@ -15,6 +15,9 @@ export function recordIntermediateResponse(opts) {
         kind: opts.kind === "GraphQL" ? "GraphQL" : "REST",
         method: opts.method,
         authSource: opts.authSource,
+        ...(opts.credentialFingerprint !== undefined && {
+            credentialFingerprint: opts.credentialFingerprint,
+        }),
         rateLimit,
     });
 }