@patronage/factory-ci 1.0.0-alpha.18 → 1.0.0-alpha.20

package/dist/index.d.ts

@@ -307,9 +307,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;
 }
@@ -904,6 +906,45 @@ interface FactoryLifecycleContractLane {
  */
 declare const factoryLifecycleContractLane: (declaration?: FactoryLifecycleContractLaneOptions) => FactoryLifecycleContractLane | undefined;
 //#endregion
+//#region src/pr-status-hud-workflow.d.ts
+declare const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
+declare const FACTORY_PR_STATUS_HUD_JOB_NAME = "Present PR status HUD";
+declare const FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID = "factory-app-token";
+declare const FACTORY_PR_STATUS_HUD_PLAN_PATH = ".factory-memory/preview-plan.json";
+/**
+ * Presentation is independent of deploy demand. Callers who `needs` the jobs
+ * that settle HUD sources (verify, deploy) must keep this `always()` so a
+ * skipped or withdrawn deploy still publishes Skipped rows.
+ */
+declare const FACTORY_PR_STATUS_HUD_IF = "always() && github.event_name == 'pull_request' && github.event.pull_request.draft != true";
+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 }}";
+}>;
+interface FactoryPrStatusHudWorkflow {
+  readonly concurrency: typeof FACTORY_PR_STATUS_HUD_CONCURRENCY;
+  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;
+//#endregion
 //#region src/preview-cleanup-topology.d.ts
 declare const FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID = "stage-residue-audit";
 declare const FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME = "Stage residue audit";
@@ -1301,4 +1342,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_PUSH_IDENTITY_SCHEMA_VERSION, type FactoryCandidateImpactWorkflow, type FactoryCandidateImpactWorkflowOptions, type FactoryLifecycleContractLane, type FactoryLifecycleContractLaneOptions, 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, 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, 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

@@ -1333,7 +1333,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 +1450,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);
@@ -2006,6 +2019,66 @@ const factoryLifecycleContractLane = (declaration) => {
 	});
 };
 //#endregion
+//#region src/pr-status-hud-workflow.ts
+const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
+const FACTORY_PR_STATUS_HUD_JOB_NAME = "Present PR status HUD";
+const FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID = "factory-app-token";
+const FACTORY_PR_STATUS_HUD_PLAN_PATH = ".factory-memory/preview-plan.json";
+/**
+* Presentation is independent of deploy demand. Callers who `needs` the jobs
+* that settle HUD sources (verify, deploy) must keep this `always()` so a
+* 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 }}`
+});
+const defaultCli = "psf";
+const factoryPrStatusHudWorkflow = (options) => {
+	assertPinnedAction("createGithubAppToken", options.createGithubAppToken, "actions/create-github-app-token");
+	const cli = options.cli || defaultCli;
+	const mintStep = Object.freeze({
+		id: FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID,
+		name: "Mint the factory App token",
+		uses: options.createGithubAppToken.uses,
+		with: Object.freeze({
+			"client-id": FACTORY_PROOF_GATE_APP_ID,
+			"private-key": `\${{ secrets.FACTORY_GITHUB_APP_PRIVATE_KEY }}`
+		})
+	});
+	const presentStep = Object.freeze({
+		env: Object.freeze({
+			FACTORY_GITHUB_APP_TOKEN: `\${{ steps.${FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID}.outputs.token }}`,
+			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 }}`,
+			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"`
+	});
+	return Object.freeze({
+		concurrency: FACTORY_PR_STATUS_HUD_CONCURRENCY,
+		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])
+	});
+};
+//#endregion
 //#region src/preview-cleanup-topology.ts
 const FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID = "stage-residue-audit";
 const FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME = "Stage residue audit";
@@ -3126,4 +3199,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_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, 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, 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.18",
+  "version": "1.0.0-alpha.20",
   "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",

package/src/index.ts

@@ -124,6 +124,18 @@ export {
   type FactoryLifecycleContractLaneOptions,
   factoryLifecycleContractLane,
 } from "./lifecycle-contract-lane.ts";
+export {
+  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,
+  type FactoryPrStatusHudWorkflow,
+  type FactoryPrStatusHudWorkflowOptions,
+  factoryPrStatusHudWorkflow,
+} from "./pr-status-hud-workflow.ts";
 export {
   FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_ID,
   FACTORY_PREVIEW_CLEANUP_AUDIT_JOB_NAME,

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

@@ -0,0 +1,96 @@
+import type { PinnedAction } from "./actions.ts";
+import type { WorkflowStep } from "./factory-workflow.ts";
+import { assertPinnedAction } from "./pinned-action.ts";
+import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
+
+export const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
+export const FACTORY_PR_STATUS_HUD_JOB_NAME = "Present PR status HUD";
+export const FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID = "factory-app-token";
+export const FACTORY_PR_STATUS_HUD_PLAN_PATH =
+  ".factory-memory/preview-plan.json";
+
+/**
+ * Presentation is independent of deploy demand. Callers who `needs` the jobs
+ * that settle HUD sources (verify, deploy) must keep this `always()` so a
+ * skipped or withdrawn deploy still publishes Skipped rows.
+ */
+export const FACTORY_PR_STATUS_HUD_IF =
+  "always() && github.event_name == 'pull_request' && github.event.pull_request.draft != true";
+
+export 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).
+ */
+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 }}`,
+});
+
+export interface FactoryPrStatusHudWorkflow {
+  readonly concurrency: typeof FACTORY_PR_STATUS_HUD_CONCURRENCY;
+  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[];
+}
+
+const defaultCli = "psf";
+
+export const factoryPrStatusHudWorkflow = (
+  options: FactoryPrStatusHudWorkflowOptions
+): FactoryPrStatusHudWorkflow => {
+  assertPinnedAction(
+    "createGithubAppToken",
+    options.createGithubAppToken,
+    "actions/create-github-app-token"
+  );
+  const cli = options.cli || defaultCli;
+  // Same unscoped mint as the freeze job. A subset (checks/issues/PRs)
+  // 422s: those permissions are not granted to this installation.
+  const mintStep: WorkflowStep = Object.freeze({
+    id: FACTORY_PR_STATUS_HUD_APP_TOKEN_STEP_ID,
+    name: "Mint the factory App token",
+    uses: options.createGithubAppToken.uses,
+    with: Object.freeze({
+      "client-id": FACTORY_PROOF_GATE_APP_ID,
+      "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 }}`,
+      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 }}`,
+      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"`,
+  });
+
+  return Object.freeze({
+    concurrency: FACTORY_PR_STATUS_HUD_CONCURRENCY,
+    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

@@ -74,9 +74,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;
 }
@@ -361,7 +363,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 +656,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 +704,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 +724,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);