@patronage/factory-ci 1.0.0-alpha.19 → 1.0.0-alpha.21

package/README.md

@@ -397,6 +397,8 @@ Persistence is an injectable GitHub transport in the same style as `mintInstalla
 
 Pass `{ store }` to substitute the GitHub adapter. `previewProofInventory.memoryStore()` is an in-memory `list`/`put` port for tests. `githubStore({ token, fetch, timeoutMs? })` is the GitHub-backed implementation. Stack names stay caller strings.
 
+Transient transport failures — a network-level rejection such as EPIPE, a timeout, a 408/429/5xx, or a response body that dies mid-read — are retried with doubling backoff up to three transport attempts in total (the first attempt plus two retries), and then throw `PreviewProofTransportError` (attempt count, last transient status, credential-free reason); a permanent HTTP refusal throws `GitHubApiError` without retrying (#830). Either failure from `persist` or `recordCleanup` is an evidence-registration failure, not a failed deployment: retain the healthy disposable stage, record the proof BLOCKED (never PASS), and re-run registration at the same head — writes are keyed by stack and stage, so resuming needs no redeploy. Admission stays fail-closed on its own: an unregistered proof never satisfies the preview demand.
+
 ### GitHub App installation tokens
 
 ```ts

package/dist/index.d.ts

@@ -286,6 +286,15 @@ declare const previewProofLifecycle: {
  * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
  * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
  * still exists.
+ *
+ * Transient transport failures are retried with bounded backoff and then
+ * surface as `PreviewProofTransportError` (#830). A failure from `persist` or
+ * `recordCleanup` is an evidence-registration failure, never a failed
+ * deployment: the caller retains the healthy disposable stage, records its own
+ * proof BLOCKED (never PASS), and re-runs registration at the same head —
+ * writes are keyed by stack and stage, so resuming needs no redeploy.
+ * Admission stays fail-closed on its own: an unregistered proof never
+ * satisfies the preview demand.
  */
 /** Check-run name that carries one registration JSON payload. Not a gate. */
 declare const PREVIEW_PROOF_INVENTORY_CHECK_NAME = "patronage-factory/preview-proof";
@@ -307,9 +316,11 @@ interface PreviewProofInventoryTransport {
   /** Per-request timeout; defaults to five seconds. */
   timeoutMs?: number;
   /**
-   * Bearer token. `list` accepts a workflow `GITHUB_TOKEN` (read). `persist`
-   * and `recordCleanup` must use a Factory App installation token: GitHub
-   * refuses GITHUB_TOKEN writes to App-owned check-runs.
+   * Bearer token. `list` accepts a workflow `GITHUB_TOKEN` (read) and needs
+   * commit (contents) read for the force-push timeline; the contents-less
+   * Factory App token cannot serve it (#825). `persist` and `recordCleanup`
+   * must use a Factory App installation token: GitHub refuses GITHUB_TOKEN
+   * writes to App-owned check-runs.
    */
   token: string;
 }
@@ -342,6 +353,21 @@ interface PreviewProofInventoryCleanupInput {
   stack: string;
   stage: string;
 }
+/**
+ * The transport gave out — a network-level rejection (EPIPE, DNS, an aborted
+ * or timed-out request) or a transient HTTP status — and bounded retries did
+ * not recover it. GitHub never judged the content, so this is never a
+ * validation verdict and never a deployment failure. Only a bounded reason
+ * string is retained: the raw transport error can hold the request and its
+ * `Authorization` header, so it is deliberately discarded.
+ */
+declare class PreviewProofTransportError extends Error {
+  /** How many transport attempts were made before giving up. */
+  readonly attempts: number;
+  /** The last transient HTTP status, when the server answered at all. */
+  readonly status?: number;
+  constructor(reason: string, attempts: number, status?: number);
+}
 declare const previewProofInventory: {
   readonly githubStore: (transport: PreviewProofInventoryTransport) => PreviewProofInventoryStore;
   readonly list: (input: PreviewProofInventoryListInput, access: PreviewProofInventoryAccess) => Promise<readonly PreviewProofRegistration[]>;
@@ -919,6 +945,16 @@ interface FactoryPrStatusHudWorkflowOptions {
   readonly cli?: string;
   readonly createGithubAppToken: PinnedAction;
 }
+/**
+ * Least privilege for the job that runs the present step. A `permissions`
+ * block zeroes every unlisted GITHUB_TOKEN scope, and the inventory list
+ * reads pull requests, commits, and check-runs with that token (#825).
+ */
+declare const FACTORY_PR_STATUS_HUD_PERMISSIONS: Readonly<{
+  readonly checks: "read";
+  readonly contents: "read";
+  readonly "pull-requests": "read";
+}>;
 declare const FACTORY_PR_STATUS_HUD_CONCURRENCY: Readonly<{
   cancelInProgress: false;
   group: "status-hud-${{ github.repository }}-${{ github.event.pull_request.number }}";
@@ -928,6 +964,7 @@ interface FactoryPrStatusHudWorkflow {
   readonly if: typeof FACTORY_PR_STATUS_HUD_IF;
   readonly jobId: typeof FACTORY_PR_STATUS_HUD_JOB_ID;
   readonly jobName: typeof FACTORY_PR_STATUS_HUD_JOB_NAME;
+  readonly permissions: typeof FACTORY_PR_STATUS_HUD_PERMISSIONS;
   readonly presentSteps: readonly WorkflowStep[];
 }
 declare const factoryPrStatusHudWorkflow: (options: FactoryPrStatusHudWorkflowOptions) => FactoryPrStatusHudWorkflow;
@@ -1329,4 +1366,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, type FactoryPrStatusHudWorkflow, type FactoryPrStatusHudWorkflowOptions, type FactoryPreviewCleanupAuditJob, type FactoryPreviewCleanupDestroyJob, type FactoryPreviewCleanupTopology, type FactoryPreviewCleanupTopologyOptions, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, PREVIEW_PROOF_INVENTORY_CHECK_NAME, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type PreviewProofCandidate, type PreviewProofCleanupOutcome, type PreviewProofCleanupStatus, type PreviewProofEnvelopeEvidence, type PreviewProofInventoryAccess, type PreviewProofInventoryCleanupInput, type PreviewProofInventoryListInput, type PreviewProofInventoryPersistInput, type PreviewProofInventoryStore, type PreviewProofInventoryTransport, type PreviewProofLifecycleEvent, type PreviewProofLifecycleState, type PreviewProofRegistration, type PreviewProofResolveQuery, PreviewProofTransportError, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, type VitestJsonReport, type VitestProfile, type VitestProfileDependencies, type VitestProfileDurationSummary, type VitestProfileEnvironment, VitestProfileError, type VitestProfileOptions, type VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/dist/index.js

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build } from "esbuild";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { createSign, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
@@ -1172,12 +1173,25 @@ const assertProofReuseCoverage = (input) => {
 * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
 * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
 * still exists.
+*
+* Transient transport failures are retried with bounded backoff and then
+* surface as `PreviewProofTransportError` (#830). A failure from `persist` or
+* `recordCleanup` is an evidence-registration failure, never a failed
+* deployment: the caller retains the healthy disposable stage, records its own
+* proof BLOCKED (never PASS), and re-runs registration at the same head —
+* writes are keyed by stack and stage, so resuming needs no redeploy.
+* Admission stays fail-closed on its own: an unregistered proof never
+* satisfies the preview demand.
 */
 /** Check-run name that carries one registration JSON payload. Not a gate. */
 const PREVIEW_PROOF_INVENTORY_CHECK_NAME = "patronage-factory/preview-proof";
 const INVENTORY_KIND = "patronage-factory-preview-proof";
 const INVENTORY_SCHEMA_VERSION = 1;
 const DEFAULT_TIMEOUT_MS = 5e3;
+/** Total transport attempts per request, the first one included. */
+const TRANSPORT_RETRY_ATTEMPTS = 3;
+/** Delay before the first retry; each further retry doubles it. */
+const TRANSPORT_RETRY_BACKOFF_MS = 500;
 const CHECK_RUNS_PER_PAGE = 100;
 const COMMITS_PER_PAGE = 100;
 const MAX_CHECK_RUN_PAGES = 10;
@@ -1309,20 +1323,93 @@ const memoryStore = () => {
 		}
 	};
 };
+/**
+* The transport gave out — a network-level rejection (EPIPE, DNS, an aborted
+* or timed-out request) or a transient HTTP status — and bounded retries did
+* not recover it. GitHub never judged the content, so this is never a
+* validation verdict and never a deployment failure. Only a bounded reason
+* string is retained: the raw transport error can hold the request and its
+* `Authorization` header, so it is deliberately discarded.
+*/
+var PreviewProofTransportError = class extends Error {
+	/** How many transport attempts were made before giving up. */
+	attempts;
+	/** The last transient HTTP status, when the server answered at all. */
+	status;
+	constructor(reason, attempts, status) {
+		super(`Preview proof inventory transport failed after ${attempts} attempt(s): ${reason}`);
+		this.name = "PreviewProofTransportError";
+		this.attempts = attempts;
+		if (status !== void 0) this.status = status;
+	}
+};
+/**
+* Transient statuses are the ones where GitHub never judged the content — a
+* request timeout (408), a rate limit (429), or the server failing (5xx) — so
+* the same bytes can still succeed. Every other non-2xx is GitHub refusing
+* this request and repeats on retry.
+*/
+const isTransientStatus = (status) => status === 408 || status === 429 || status >= 500;
+/**
+* A bounded, credential-free description of a transport failure. The raw
+* error may retain the request and its `Authorization` header; only the name
+* and a truncated message survive.
+*/
+const boundedTransportReason = (error) => error instanceof Error ? `${error.name}: ${error.message}`.slice(0, 200) : "unknown transport error";
+const defaultTransportWait = (ms) => setTimeout$1(ms);
+let transportWait = defaultTransportWait;
+/**
+* One transport attempt. A transient failure is reported as an outcome so the
+* caller can retry; a permanent HTTP refusal throws `GitHubApiError` here.
+*/
+const githubJsonAttempt = async (request, url, token, init, timeoutMs) => {
+	let response;
+	try {
+		response = await request(url, {
+			body: init.body,
+			headers: {
+				Accept: "application/vnd.github+json",
+				Authorization: `Bearer ${token}`,
+				"X-GitHub-Api-Version": GITHUB_API_VERSION,
+				...init.body === void 0 ? {} : { "Content-Type": "application/json" }
+			},
+			method: init.method,
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (error) {
+		return {
+			ok: false,
+			reason: boundedTransportReason(error)
+		};
+	}
+	if (!response.ok) {
+		if (!isTransientStatus(response.status)) throw new GitHubApiError(response.status, response.statusText);
+		return {
+			ok: false,
+			reason: `GitHub API ${response.status} ${response.statusText}`,
+			status: response.status
+		};
+	}
+	try {
+		return {
+			ok: true,
+			value: await response.json()
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: boundedTransportReason(error)
+		};
+	}
+};
 const githubJson = async (request, url, token, init, timeoutMs) => {
-	const response = await request(url, {
-		body: init.body,
-		headers: {
-			Accept: "application/vnd.github+json",
-			Authorization: `Bearer ${token}`,
-			"X-GitHub-Api-Version": GITHUB_API_VERSION,
-			...init.body === void 0 ? {} : { "Content-Type": "application/json" }
-		},
-		method: init.method,
-		signal: AbortSignal.timeout(timeoutMs)
-	});
-	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
-	return await response.json();
+	let outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
+	for (let attempt = 2; attempt <= TRANSPORT_RETRY_ATTEMPTS && !outcome.ok; attempt += 1) {
+		await transportWait(TRANSPORT_RETRY_BACKOFF_MS * 2 ** (attempt - 2));
+		outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
+	}
+	if (outcome.ok) return outcome.value;
+	throw new PreviewProofTransportError(outcome.reason, TRANSPORT_RETRY_ATTEMPTS, outcome.status);
 };
 const githubGraphql = async (request, token, timeoutMs, query, variables) => {
 	const served = await githubJson(request, "https://api.github.com/graphql", token, {
@@ -1333,7 +1420,10 @@ const githubGraphql = async (request, token, timeoutMs, query, variables) => {
 		method: "POST"
 	}, timeoutMs);
 	if (!isRecord$1(served)) throw new TypeError("GitHub GraphQL response was not an object");
-	if (served.errors !== void 0) throw new Error("Preview proof inventory GraphQL query failed.");
+	if (served.errors !== void 0) {
+		const details = Array.isArray(served.errors) ? served.errors.flatMap((entry) => isRecord$1(entry) ? [[entry.type, entry.message].filter((part) => typeof part === "string").join(": ")] : []).filter((detail) => detail.length > 0).join("; ") : "";
+		throw new Error(details.length > 0 ? `Preview proof inventory GraphQL query failed: ${details}` : "Preview proof inventory GraphQL query failed.");
+	}
 	return served.data;
 };
 const repoApi = (owner, repo) => `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
@@ -1447,27 +1537,37 @@ const listPullRequestCommitShas = (request, token, timeoutMs, owner, repo, pr) =
 	if (!Array.isArray(commits)) throw new TypeError("GitHub pull request commits response was not an array");
 	return commits.flatMap((commit) => isRecord$1(commit) && typeof commit.sha === "string" ? [commit.sha] : []);
 }, COMMITS_PER_PAGE, MAX_COMMIT_PAGES, "Preview proof inventory commit listing exhausted pagination before GitHub returned a final page.");
+const readPullBaseSha = (pull) => {
+	if (!isRecord$1(pull.base) || typeof pull.base.sha !== "string") throw new TypeError("GitHub pull request response omitted base.sha");
+	return pull.base.sha;
+};
 /**
-* Current head, replaced heads from force-push, and PR commits. The
-* pull-commits endpoint silently stops at 250 and never lists a rebased-away
-* head, so those two cases use compare pagination and the force-push timeline.
+* Current head, replaced heads from force-push, the commits each replaced head
+* carried, and PR commits. The pull-commits endpoint silently stops at 250 and
+* never lists a rebased-away head, so those two cases use compare pagination
+* and the force-push timeline. A persist, then a fast-forward, then a rebase
+* leaves the persist SHA behind the replaced head, so each replaced head is
+* also walked back to the base (#796).
 */
 const listCommitShasForPull = async (request, token, timeoutMs, owner, repo, pr) => {
 	const pull = await githubJson(request, `${repoApi(owner, repo)}/pulls/${pr}`, token, { method: "GET" }, timeoutMs);
 	if (!isRecord$1(pull) || !isRecord$1(pull.head) || typeof pull.head.sha !== "string") throw new TypeError("GitHub pull request response omitted head.sha");
 	const pullCommits = await listPullRequestCommitShas(request, token, timeoutMs, owner, repo, pr);
 	let older = pullCommits;
-	if (pullCommits.length >= GITHUB_PULL_COMMITS_CAP) {
-		if (!isRecord$1(pull.base) || typeof pull.base.sha !== "string") throw new TypeError("GitHub pull request response omitted base.sha");
-		older = await listCompareCommitShas(request, token, timeoutMs, owner, repo, pull.base.sha, pull.head.sha);
-	}
+	if (pullCommits.length >= GITHUB_PULL_COMMITS_CAP) older = await listCompareCommitShas(request, token, timeoutMs, owner, repo, readPullBaseSha(pull), pull.head.sha);
 	const previousHeads = await listForcePushBeforeShas(request, token, timeoutMs, owner, repo, pr);
+	let replaced = [];
+	if (previousHeads.length > 0) {
+		const baseSha = readPullBaseSha(pull);
+		replaced = (await mapPool(previousHeads, 8, (previousHead) => listCompareCommitShas(request, token, timeoutMs, owner, repo, baseSha, previousHead))).flatMap((history) => [...history].toReversed());
+	}
 	const shas = [];
 	const seen = /* @__PURE__ */ new Set();
 	for (const sha of [
 		pull.head.sha,
 		...previousHeads,
-		...older.toReversed()
+		...older.toReversed(),
+		...replaced
 	]) if (!seen.has(sha)) {
 		seen.add(sha);
 		shas.push(sha);
@@ -2017,6 +2117,16 @@ const FACTORY_PR_STATUS_HUD_PLAN_PATH = ".factory-memory/preview-plan.json";
 * skipped or withdrawn deploy still publishes Skipped rows.
 */
 const FACTORY_PR_STATUS_HUD_IF = "always() && github.event_name == 'pull_request' && github.event.pull_request.draft != true";
+/**
+* Least privilege for the job that runs the present step. A `permissions`
+* block zeroes every unlisted GITHUB_TOKEN scope, and the inventory list
+* reads pull requests, commits, and check-runs with that token (#825).
+*/
+const FACTORY_PR_STATUS_HUD_PERMISSIONS = Object.freeze({
+	checks: "read",
+	contents: "read",
+	"pull-requests": "read"
+});
 const FACTORY_PR_STATUS_HUD_CONCURRENCY = Object.freeze({
 	cancelInProgress: false,
 	group: `status-hud-\${{ github.repository }}-\${{ github.event.pull_request.number }}`
@@ -2040,7 +2150,8 @@ const factoryPrStatusHudWorkflow = (options) => {
 			FACTORY_HEAD_SHA: `\${{ github.event.pull_request.head.sha }}`,
 			FACTORY_OWNER: `\${{ github.repository_owner }}`,
 			FACTORY_PR: `\${{ github.event.pull_request.number }}`,
-			FACTORY_REPO: `\${{ github.event.repository.name }}`
+			FACTORY_REPO: `\${{ github.event.repository.name }}`,
+			GITHUB_TOKEN: `\${{ github.token }}`
 		}),
 		name: "Present the PR status HUD",
 		run: `${cli} pr:status-hud --head "$FACTORY_HEAD_SHA" --owner "$FACTORY_OWNER" --repo "$FACTORY_REPO" --pr "$FACTORY_PR"`
@@ -2050,6 +2161,7 @@ const factoryPrStatusHudWorkflow = (options) => {
 		if: FACTORY_PR_STATUS_HUD_IF,
 		jobId: FACTORY_PR_STATUS_HUD_JOB_ID,
 		jobName: FACTORY_PR_STATUS_HUD_JOB_NAME,
+		permissions: FACTORY_PR_STATUS_HUD_PERMISSIONS,
 		presentSteps: Object.freeze([mintStep, presentStep])
 	});
 };
@@ -3174,4 +3286,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };
+export { EXECUTE_ALCHEMY_ENTRY_MAX_BUFFER, FACTORY_CANDIDATE_IMPACT_BASIS_OUTPUT, FACTORY_CANDIDATE_IMPACT_DECISION_OUTPUT, FACTORY_CANDIDATE_IMPACT_INERT_OUTPUT, FACTORY_CANDIDATE_IMPACT_STEP_ID, FACTORY_CANDIDATE_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_LIFECYCLE_CONTRACT_JOB_ID, FACTORY_LIFECYCLE_CONTRACT_JOB_NAME, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID, FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID, FACTORY_PR_STATUS_HUD_CONCURRENCY, FACTORY_PR_STATUS_HUD_IF, FACTORY_PR_STATUS_HUD_JOB_ID, FACTORY_PR_STATUS_HUD_JOB_NAME, FACTORY_PR_STATUS_HUD_PERMISSIONS, FACTORY_PR_STATUS_HUD_PLAN_PATH, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, PREVIEW_PROOF_INVENTORY_CHECK_NAME, PreviewProofTransportError, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateImpactWorkflow, factoryCandidateOrPushCondition, factoryLifecycleContractLane, factoryPrStatusHudWorkflow, factoryPreviewCleanupTopology, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, previewCleanupDestroyJobId, previewProofInventory, previewProofLifecycle, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.21",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",
@@ -36,17 +36,19 @@
   "devDependencies": {
     "@types/node": "24.13.3",
     "@vitest/coverage-v8": "4.1.10",
+    "knip": "6.27.0",
     "oxfmt": "0.59.0",
-    "oxlint": "1.74.0",
+    "oxlint": "1.76.0",
     "tsdown": "0.21.10",
     "typescript": "5.9.3",
-    "ultracite": "7.9.4",
+    "ultracite": "7.10.5",
     "vitest": "4.1.10"
   },
   "engines": {
     "node": "^24.0.0"
   },
   "scripts": {
+    "cleanup:check": "knip --files --dependencies",
     "prebuild": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "build": "tsdown",
     "precheck": "bash ../scripts/ensure-worktree-bootstrap.sh",

package/src/index.ts

@@ -50,6 +50,7 @@ export {
   type PreviewProofInventoryPersistInput,
   type PreviewProofInventoryStore,
   type PreviewProofInventoryTransport,
+  PreviewProofTransportError,
 } from "./preview-proof-inventory.ts";
 export {
   type CheckoutStepOptions,
@@ -130,6 +131,7 @@ export {
   FACTORY_PR_STATUS_HUD_IF,
   FACTORY_PR_STATUS_HUD_JOB_ID,
   FACTORY_PR_STATUS_HUD_JOB_NAME,
+  FACTORY_PR_STATUS_HUD_PERMISSIONS,
   FACTORY_PR_STATUS_HUD_PLAN_PATH,
   type FactoryPrStatusHudWorkflow,
   type FactoryPrStatusHudWorkflowOptions,

package/src/pr-status-hud-workflow.ts

@@ -22,6 +22,17 @@ export interface FactoryPrStatusHudWorkflowOptions {
   readonly createGithubAppToken: PinnedAction;
 }
 
+/**
+ * Least privilege for the job that runs the present step. A `permissions`
+ * block zeroes every unlisted GITHUB_TOKEN scope, and the inventory list
+ * reads pull requests, commits, and check-runs with that token (#825).
+ */
+export const FACTORY_PR_STATUS_HUD_PERMISSIONS = Object.freeze({
+  checks: "read",
+  contents: "read",
+  "pull-requests": "read",
+} as const);
+
 export const FACTORY_PR_STATUS_HUD_CONCURRENCY = Object.freeze({
   cancelInProgress: false,
   group: `status-hud-\${{ github.repository }}-\${{ github.event.pull_request.number }}`,
@@ -32,6 +43,7 @@ export interface FactoryPrStatusHudWorkflow {
   readonly if: typeof FACTORY_PR_STATUS_HUD_IF;
   readonly jobId: typeof FACTORY_PR_STATUS_HUD_JOB_ID;
   readonly jobName: typeof FACTORY_PR_STATUS_HUD_JOB_NAME;
+  readonly permissions: typeof FACTORY_PR_STATUS_HUD_PERMISSIONS;
   readonly presentSteps: readonly WorkflowStep[];
 }
 
@@ -57,6 +69,9 @@ export const factoryPrStatusHudWorkflow = (
       "private-key": `\${{ secrets.FACTORY_GITHUB_APP_PRIVATE_KEY }}`,
     }),
   });
+  // The App token owns the HUD comment but has no contents permission, so
+  // the force-push timeline read (#819) is FORBIDDEN for it. The workflow
+  // token carries the job's `contents: read` and serves that read (#825).
   const presentStep: WorkflowStep = Object.freeze({
     env: Object.freeze({
       FACTORY_GITHUB_APP_TOKEN: `\${{ steps.${FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID}.outputs.token }}`,
@@ -64,6 +79,7 @@ export const factoryPrStatusHudWorkflow = (
       FACTORY_OWNER: `\${{ github.repository_owner }}`,
       FACTORY_PR: `\${{ github.event.pull_request.number }}`,
       FACTORY_REPO: `\${{ github.event.repository.name }}`,
+      GITHUB_TOKEN: `\${{ github.token }}`,
     }),
     name: "Present the PR status HUD",
     run: `${cli} pr:status-hud --head "$FACTORY_HEAD_SHA" --owner "$FACTORY_OWNER" --repo "$FACTORY_REPO" --pr "$FACTORY_PR"`,
@@ -74,6 +90,7 @@ export const factoryPrStatusHudWorkflow = (
     if: FACTORY_PR_STATUS_HUD_IF,
     jobId: FACTORY_PR_STATUS_HUD_JOB_ID,
     jobName: FACTORY_PR_STATUS_HUD_JOB_NAME,
+    permissions: FACTORY_PR_STATUS_HUD_PERMISSIONS,
     presentSteps: Object.freeze([mintStep, presentStep]),
   });
 };

package/src/preview-proof-inventory.ts

@@ -1,3 +1,5 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
 import { parseLocalPreviewStage } from "./disposable-stage.ts";
 import { GitHubApiError } from "./github-app-token.ts";
 import type {
@@ -18,6 +20,15 @@ import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
  * secrets. Cleanup writes go through `previewProofLifecycle.transition` with
  * `{ type: "cleanup" }`. Outcomes are never inferred from whether a stage
  * still exists.
+ *
+ * Transient transport failures are retried with bounded backoff and then
+ * surface as `PreviewProofTransportError` (#830). A failure from `persist` or
+ * `recordCleanup` is an evidence-registration failure, never a failed
+ * deployment: the caller retains the healthy disposable stage, records its own
+ * proof BLOCKED (never PASS), and re-runs registration at the same head —
+ * writes are keyed by stack and stage, so resuming needs no redeploy.
+ * Admission stays fail-closed on its own: an unregistered proof never
+ * satisfies the preview demand.
  */
 
 /** Check-run name that carries one registration JSON payload. Not a gate. */
@@ -27,6 +38,10 @@ export const PREVIEW_PROOF_INVENTORY_CHECK_NAME =
 const INVENTORY_KIND = "patronage-factory-preview-proof";
 const INVENTORY_SCHEMA_VERSION = 1;
 const DEFAULT_TIMEOUT_MS = 5000;
+/** Total transport attempts per request, the first one included. */
+const TRANSPORT_RETRY_ATTEMPTS = 3;
+/** Delay before the first retry; each further retry doubles it. */
+const TRANSPORT_RETRY_BACKOFF_MS = 500;
 const CHECK_RUNS_PER_PAGE = 100;
 const COMMITS_PER_PAGE = 100;
 const MAX_CHECK_RUN_PAGES = 10;
@@ -74,9 +89,11 @@ export interface PreviewProofInventoryTransport {
   /** Per-request timeout; defaults to five seconds. */
   timeoutMs?: number;
   /**
-   * Bearer token. `list` accepts a workflow `GITHUB_TOKEN` (read). `persist`
-   * and `recordCleanup` must use a Factory App installation token: GitHub
-   * refuses GITHUB_TOKEN writes to App-owned check-runs.
+   * Bearer token. `list` accepts a workflow `GITHUB_TOKEN` (read) and needs
+   * commit (contents) read for the force-push timeline; the contents-less
+   * Factory App token cannot serve it (#825). `persist` and `recordCleanup`
+   * must use a Factory App installation token: GitHub refuses GITHUB_TOKEN
+   * writes to App-owned check-runs.
    */
   token: string;
 }
@@ -317,6 +334,126 @@ export const memoryStore = (): PreviewProofInventoryStore => {
   };
 };
 
+/**
+ * The transport gave out — a network-level rejection (EPIPE, DNS, an aborted
+ * or timed-out request) or a transient HTTP status — and bounded retries did
+ * not recover it. GitHub never judged the content, so this is never a
+ * validation verdict and never a deployment failure. Only a bounded reason
+ * string is retained: the raw transport error can hold the request and its
+ * `Authorization` header, so it is deliberately discarded.
+ */
+export class PreviewProofTransportError extends Error {
+  /** How many transport attempts were made before giving up. */
+  readonly attempts: number;
+  /** The last transient HTTP status, when the server answered at all. */
+  readonly status?: number;
+
+  constructor(reason: string, attempts: number, status?: number) {
+    super(
+      `Preview proof inventory transport failed after ${attempts} attempt(s): ${reason}`
+    );
+    this.name = "PreviewProofTransportError";
+    this.attempts = attempts;
+    if (status !== undefined) {
+      this.status = status;
+    }
+  }
+}
+
+/**
+ * Transient statuses are the ones where GitHub never judged the content — a
+ * request timeout (408), a rate limit (429), or the server failing (5xx) — so
+ * the same bytes can still succeed. Every other non-2xx is GitHub refusing
+ * this request and repeats on retry.
+ */
+const isTransientStatus = (status: number): boolean =>
+  status === 408 || status === 429 || status >= 500;
+
+/**
+ * A bounded, credential-free description of a transport failure. The raw
+ * error may retain the request and its `Authorization` header; only the name
+ * and a truncated message survive.
+ */
+const boundedTransportReason = (error: unknown): string =>
+  error instanceof Error
+    ? `${error.name}: ${error.message}`.slice(0, 200)
+    : "unknown transport error";
+
+type TransportWait = (ms: number) => Promise<void>;
+
+const defaultTransportWait: TransportWait = (ms) => sleep(ms);
+
+let transportWait: TransportWait = defaultTransportWait;
+
+/** Package-test seam. Not re-exported from `index.ts`. */
+export const setPreviewProofTransportWaitForTests = (
+  next?: TransportWait
+): void => {
+  transportWait = next ?? defaultTransportWait;
+};
+
+/**
+ * One GitHub JSON request with bounded retries (#830). Each attempt gets a
+ * fresh timeout signal. A transient failure — network rejection, timeout,
+ * transient HTTP status, or a body that dies mid-read — retries with doubling
+ * backoff and exhausts into `PreviewProofTransportError`; a permanent HTTP
+ * refusal throws `GitHubApiError` on its first response. Retrying a write is
+ * safe: check-run payloads are idempotent per stack and stage, and a
+ * duplicated create is resolved by the newest-run read
+ * (`compareCheckRunsNewestFirst`).
+ */
+type TransportOutcome =
+  | { ok: true; value: unknown }
+  | { ok: false; reason: string; status?: number };
+
+/**
+ * One transport attempt. A transient failure is reported as an outcome so the
+ * caller can retry; a permanent HTTP refusal throws `GitHubApiError` here.
+ */
+const githubJsonAttempt = async (
+  request: typeof fetch,
+  url: string,
+  token: string,
+  init: { body?: string; method: "GET" | "PATCH" | "POST" },
+  timeoutMs: number
+): Promise<TransportOutcome> => {
+  let response: Response;
+  try {
+    response = await request(url, {
+      body: init.body,
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "X-GitHub-Api-Version": GITHUB_API_VERSION,
+        ...(init.body === undefined
+          ? {}
+          : { "Content-Type": "application/json" }),
+      },
+      method: init.method,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return { ok: false, reason: boundedTransportReason(error) };
+  }
+  if (!response.ok) {
+    if (!isTransientStatus(response.status)) {
+      throw new GitHubApiError(response.status, response.statusText);
+    }
+    return {
+      ok: false,
+      reason: `GitHub API ${response.status} ${response.statusText}`,
+      status: response.status,
+    };
+  }
+  try {
+    return { ok: true, value: (await response.json()) as unknown };
+  } catch (error) {
+    // A 2xx whose body dies mid-read is the transport failing, not GitHub
+    // refusing: the EPIPE that motivated #830 lands exactly here.
+    return { ok: false, reason: boundedTransportReason(error) };
+  }
+};
+
 const githubJson = async (
   request: typeof fetch,
   url: string,
@@ -324,23 +461,27 @@ const githubJson = async (
   init: { body?: string; method: "GET" | "PATCH" | "POST" },
   timeoutMs: number
 ): Promise<unknown> => {
-  const response = await request(url, {
-    body: init.body,
-    headers: {
-      Accept: "application/vnd.github+json",
-      Authorization: `Bearer ${token}`,
-      "X-GitHub-Api-Version": GITHUB_API_VERSION,
-      ...(init.body === undefined
-        ? {}
-        : { "Content-Type": "application/json" }),
-    },
-    method: init.method,
-    signal: AbortSignal.timeout(timeoutMs),
-  });
-  if (!response.ok) {
-    throw new GitHubApiError(response.status, response.statusText);
+  let outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
+
+  for (
+    let attempt = 2;
+    attempt <= TRANSPORT_RETRY_ATTEMPTS && !outcome.ok;
+    attempt += 1
+  ) {
+    // oxlint-disable-next-line no-await-in-loop -- bounded backoff between sequential retries
+    await transportWait(TRANSPORT_RETRY_BACKOFF_MS * 2 ** (attempt - 2));
+    // oxlint-disable-next-line no-await-in-loop -- retries are sequential by design
+    outcome = await githubJsonAttempt(request, url, token, init, timeoutMs);
   }
-  return (await response.json()) as unknown;
+
+  if (outcome.ok) {
+    return outcome.value;
+  }
+  throw new PreviewProofTransportError(
+    outcome.reason,
+    TRANSPORT_RETRY_ATTEMPTS,
+    outcome.status
+  );
 };
 
 const githubGraphql = async (
@@ -361,7 +502,25 @@ const githubGraphql = async (
     throw new TypeError("GitHub GraphQL response was not an object");
   }
   if (served.errors !== undefined) {
-    throw new Error("Preview proof inventory GraphQL query failed.");
+    const details = Array.isArray(served.errors)
+      ? served.errors
+          .flatMap((entry) =>
+            isRecord(entry)
+              ? [
+                  [entry.type, entry.message]
+                    .filter((part) => typeof part === "string")
+                    .join(": "),
+                ]
+              : []
+          )
+          .filter((detail) => detail.length > 0)
+          .join("; ")
+      : "";
+    throw new Error(
+      details.length > 0
+        ? `Preview proof inventory GraphQL query failed: ${details}`
+        : "Preview proof inventory GraphQL query failed."
+    );
   }
   return served.data;
 };
@@ -636,10 +795,20 @@ const listPullRequestCommitShas = (
     "Preview proof inventory commit listing exhausted pagination before GitHub returned a final page."
   );
 
+const readPullBaseSha = (pull: Record<string, unknown>): string => {
+  if (!isRecord(pull.base) || typeof pull.base.sha !== "string") {
+    throw new TypeError("GitHub pull request response omitted base.sha");
+  }
+  return pull.base.sha;
+};
+
 /**
- * Current head, replaced heads from force-push, and PR commits. The
- * pull-commits endpoint silently stops at 250 and never lists a rebased-away
- * head, so those two cases use compare pagination and the force-push timeline.
+ * Current head, replaced heads from force-push, the commits each replaced head
+ * carried, and PR commits. The pull-commits endpoint silently stops at 250 and
+ * never lists a rebased-away head, so those two cases use compare pagination
+ * and the force-push timeline. A persist, then a fast-forward, then a rebase
+ * leaves the persist SHA behind the replaced head, so each replaced head is
+ * also walked back to the base (#796).
  */
 const listCommitShasForPull = async (
   request: typeof fetch,
@@ -674,16 +843,13 @@ const listCommitShasForPull = async (
   );
   let older = pullCommits;
   if (pullCommits.length >= GITHUB_PULL_COMMITS_CAP) {
-    if (!isRecord(pull.base) || typeof pull.base.sha !== "string") {
-      throw new TypeError("GitHub pull request response omitted base.sha");
-    }
     older = await listCompareCommitShas(
       request,
       token,
       timeoutMs,
       owner,
       repo,
-      pull.base.sha,
+      readPullBaseSha(pull),
       pull.head.sha
     );
   }
@@ -697,9 +863,34 @@ const listCommitShasForPull = async (
     pr
   );
 
+  let replaced: readonly string[] = [];
+  if (previousHeads.length > 0) {
+    const baseSha = readPullBaseSha(pull);
+    const histories = await mapPool(
+      previousHeads,
+      PREVIEW_PROOF_LIST_CONCURRENCY,
+      (previousHead) =>
+        listCompareCommitShas(
+          request,
+          token,
+          timeoutMs,
+          owner,
+          repo,
+          baseSha,
+          previousHead
+        )
+    );
+    replaced = histories.flatMap((history) => [...history].toReversed());
+  }
+
   const shas: string[] = [];
   const seen = new Set<string>();
-  for (const sha of [pull.head.sha, ...previousHeads, ...older.toReversed()]) {
+  for (const sha of [
+    pull.head.sha,
+    ...previousHeads,
+    ...older.toReversed(),
+    ...replaced,
+  ]) {
     if (!seen.has(sha)) {
       seen.add(sha);
       shas.push(sha);

package/src/vitest-profile-reader.ts

@@ -216,5 +216,10 @@ export const readVitestProfileDocument = (
     return { kind: "unrecognized", reason: summary };
   }
 
+  // Every field above is checked against the profile contract, but the checks
+  // return reasons rather than narrowing `value`. Rebuilding the document
+  // field-by-field here would copy the writer's shape into the reader and let
+  // the two drift. Keep the one double assertion; the checks are the proof.
+  // oxlint-disable-next-line anti-slop/no-chained-type-assertions
   return { kind: "profile", profile: value as unknown as VitestProfile };
 };