@patronage/software-factory 1.0.0-alpha.17 → 1.0.0-alpha.19

package/dist/index.js

@@ -14,10 +14,10 @@ import { setImmediate as setImmediate$1, setTimeout as setTimeout$1 } from "node
 import { Worker } from "node:worker_threads";
 import picomatch from "picomatch";
 import { parse } from "yaml";
-import { FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
+import { FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, previewProofInventory, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
 import { promisify } from "node:util";
 //#region package.json
-var version = "1.0.0-alpha.17";
+var version = "1.0.0-alpha.19";
 //#endregion
 //#region src/review-rungs.ts
 const EVIDENCE_REVIEW_RUNGS$1 = [
@@ -291,11 +291,11 @@ var boundary_review_proof_exports = /* @__PURE__ */ __exportAll({
 	undispositionedBlockingFindings: () => undispositionedBlockingFindings
 });
 const BOUNDARY_REVIEW_PROOF_KIND$1 = "boundary-review-proof";
-const shaSchema$5 = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
+const shaSchema$6 = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
 const coveredSetEntrySchema$1 = z.object({
-	headSha: shaSchema$5.optional(),
+	headSha: shaSchema$6.optional(),
 	issue: z.number().int().positive().optional(),
-	mergedSha: shaSchema$5.optional(),
+	mergedSha: shaSchema$6.optional(),
 	pr: z.number().int().positive(),
 	state: z.enum(["merged", "open"]),
 	wave: z.string().min(1).optional()
@@ -1198,11 +1198,16 @@ const impactConfigSchema = z.object({
 		});
 	})
 }).strict();
+const lifecycleContractSchema = z.object({
+	command: z.string().min(1).describe("Package-script invocation hosted CI runs for the non-credentialed lifecycle-contract lane (for example `pnpm test:factory`). Never a direct Vitest invocation."),
+	jobName: z.string().min(1).optional().describe("Display name for the generated GitHub Actions job. Defaults to Factory / Alchemy Contracts when omitted.")
+}).strict().describe("Opt-in hosted lifecycle-contract lane. Presence includes the non-credentialed job in generated Verify; absence omits it. factory-ci does not load this object; generators pass it as typed options (ADR 0021).");
 const factoryProjectProfileSchema = z.object({
 	$schema: z.string().min(1).optional(),
 	extensions: z.record(z.string(), z.unknown()).optional(),
 	hq: hqIngestConfigSchema.optional(),
 	impact: impactConfigSchema.optional(),
+	lifecycleContract: lifecycleContractSchema.optional(),
 	repository: z.object({
 		name: z.string().min(1),
 		owner: z.string().min(1)
@@ -3699,10 +3704,10 @@ const resolveAuthoringSessionIds = ({ override, recorded }) => {
 //#region src/demand-waiver.ts
 const DEMAND_WAIVER_SCHEMA_VERSION$1 = 1;
 const DEFAULT_DEMAND_WAIVER_PATH = ".factory-memory/demand-waivers.json";
-const shaSchema$4 = z.string().regex(/^[0-9a-f]{40}$/u);
+const shaSchema$5 = z.string().regex(/^[0-9a-f]{40}$/u);
 const demandWaiverSchema = z.object({
 	candidate: z.object({
-		headSha: shaSchema$4,
+		headSha: shaSchema$5,
 		pr: z.number().int().positive()
 	}),
 	demand: waiverDemandKeySchema,
@@ -5984,7 +5989,7 @@ function withGateTiming(spec, action) {
 	};
 }
 //#endregion
-//#region src/commands/options.ts
+//#region src/command-options.ts
 function positiveInteger$1(name) {
 	return (value) => {
 		const parsed = Number(value);
@@ -8533,7 +8538,7 @@ var CandidateIdentityError = class extends Error {
 		this.name = "CandidateIdentityError";
 	}
 };
-const OBJECT_ID = /^[0-9a-f]{40}$/u;
+const OBJECT_ID$1 = /^[0-9a-f]{40}$/u;
 /**
 * Private patch-id primitive for this proof-identity owner. It stays local so
 * the ownership boundary is structural rather than an approximation of which
@@ -8565,7 +8570,7 @@ function runStablePatchId(cwd, base) {
 	return id;
 }
 function assertObjectId(field, value) {
-	if (!OBJECT_ID.test(value)) throw new CandidateIdentityError(`Candidate identity ${field} must be a 40-character object id, got ${JSON.stringify(value)}. Evidence bound to a malformed identity cannot be matched against a candidate, so this fails closed.`);
+	if (!OBJECT_ID$1.test(value)) throw new CandidateIdentityError(`Candidate identity ${field} must be a 40-character object id, got ${JSON.stringify(value)}. Evidence bound to a malformed identity cannot be matched against a candidate, so this fails closed.`);
 	return value;
 }
 /**
@@ -8665,16 +8670,16 @@ var external_evidence_exports = /* @__PURE__ */ __exportAll({
 	requiredCheckScopeSchema: () => requiredCheckScopeSchema$1,
 	resolveAuthoringSessionIds: () => resolveAuthoringSessionIds
 });
-const shaSchema$3 = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
+const shaSchema$4 = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
 const evidenceEnvelopeSchema = z.object({
 	check: z.string().min(1),
 	checkType: z.enum(EVIDENCE_CHECK_TYPES$1),
 	findingsPointer: z.string().min(1).optional(),
-	headSha: shaSchema$3,
-	mergeBaseSha: shaSchema$3,
+	headSha: shaSchema$4,
+	mergeBaseSha: shaSchema$4,
 	model: z.string().min(1).optional(),
 	outcome: z.enum(["pass", "fail"]),
-	patchId: shaSchema$3,
+	patchId: shaSchema$4,
 	policyVersion: z.string().min(1).optional(),
 	producer: z.string().min(1),
 	requestId: z.string().min(1).optional(),
@@ -9081,6 +9086,124 @@ function generationOrderMs(value) {
 	return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
 }
 //#endregion
+//#region src/pr-verify-status.ts
+const PR_VERIFY_STATUS_CONTEXT = "patronage-factory/pr-verify";
+const GITHUB_PUBLISH_TIMEOUT_MS = 5e3;
+/**
+* Fire a best-effort async operation without blocking the caller and without
+* ever surfacing an unhandled rejection. Every check-run/commit-status
+* publisher in this module and github-check-runs.ts is a fire-and-forget
+* sink whose own failure (including its diagnostic write) must never affect
+* the gate result; this is the single detach wrapper they share instead of
+* each redeclaring the same try/catch-and-void shape.
+*/
+function runDetachedBestEffort(work) {
+	const safe = async () => {
+		try {
+			await work();
+		} catch {}
+	};
+	safe();
+}
+async function runGhStatus(args, cwd) {
+	const { execFile } = await import("node:child_process");
+	await promisify(execFile)("gh", args, {
+		cwd,
+		timeout: GITHUB_PUBLISH_TIMEOUT_MS
+	});
+}
+function createGhCommitStatusPoster(output, run = runGhStatus) {
+	return (input) => {
+		const { context = PR_VERIFY_STATUS_CONTEXT, cwd, description, owner, repo, sha, state, suppressFailureDiagnostic = false, targetUrl } = input;
+		const args = [
+			"api",
+			"--method",
+			"POST",
+			`/repos/${owner}/${repo}/statuses/${sha}`,
+			"-f",
+			`state=${state}`,
+			"-f",
+			`context=${context}`,
+			"-f",
+			`description=${description}`,
+			"-f",
+			`target_url=${targetUrl}`
+		];
+		const publish = async () => {
+			await Promise.resolve();
+			try {
+				await run(args, cwd);
+				if (state === "success") output.stdout.write(context === "patronage-factory/pr-verify" ? `pr:verify posted ${PR_VERIFY_STATUS_CONTEXT}=success\n` : `${context} posted success\n`);
+			} catch (error) {
+				if (suppressFailureDiagnostic) return;
+				const message = error instanceof Error ? error.message : String(error);
+				output.stderr.write(context === "patronage-factory/pr-verify" ? `pr:verify: unable to post ${PR_VERIFY_STATUS_CONTEXT} status: ${message}\n` : `${context}: unable to post commit status: ${message}\n`);
+			}
+		};
+		runDetachedBestEffort(publish);
+	};
+}
+//#endregion
+//#region src/github-app-client.ts
+const readExchange = async (request, url, init, timeoutMs) => {
+	const response = await request(url, {
+		...init,
+		headers: {
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28",
+			...init.headers
+		},
+		signal: init.signal ?? AbortSignal.timeout(timeoutMs)
+	});
+	const etag = response.headers.get("etag") ?? void 0;
+	if (response.status === 204) return {
+		etag,
+		json: void 0,
+		status: 204
+	};
+	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
+	return {
+		etag,
+		json: await response.json(),
+		status: response.status
+	};
+};
+async function requestGitHubJson(request, url, init, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) {
+	return (await readExchange(request, url, init, timeoutMs)).json;
+}
+/** Mint one repository-scoped installation token for the Patronage Factory App. */
+const mintFactoryInstallationToken = (repository, config, request, now, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) => mintInstallationToken({
+	credentials: config,
+	owner: repository.owner,
+	repo: repository.repo
+}, {
+	fetch: request,
+	now: () => now,
+	timeoutMs
+});
+const resolveFactoryAppToken = async (input, dependencies, request, timeoutMs) => {
+	if (dependencies.token) return dependencies.token;
+	const config = dependencies.githubApp ?? tryUserConfig()?.config.githubApp;
+	if (!config) throw new Error("The Patronage Factory GitHub App is required for App-owned GitHub requests.");
+	return mintFactoryInstallationToken(input, config, request, (dependencies.now ?? Date.now)(), timeoutMs);
+};
+const factoryAppInit = (input, token) => ({
+	...input.body === void 0 ? {} : { body: JSON.stringify(input.body) },
+	headers: {
+		Authorization: `Bearer ${token}`,
+		"Content-Type": "application/json",
+		...input.headers
+	},
+	method: input.method
+});
+/** Perform one repository request as the Patronage Factory GitHub App. */
+async function requestFactoryApp(input, dependencies = {}) {
+	const request = dependencies.fetch ?? fetch;
+	const timeoutMs = dependencies.timeoutMs ?? 5e3;
+	const token = await resolveFactoryAppToken(input, dependencies, request, timeoutMs);
+	return readExchange(request, `https://api.github.com/repos/${input.owner}/${input.repo}/${input.path}`, factoryAppInit(input, token), timeoutMs);
+}
+//#endregion
 //#region src/pr-verify-mode.ts
 const RESOLVED_PR_VERIFY_MODES = new Set([
 	"docs-only",
@@ -9142,64 +9265,6 @@ const prVerifyCheckPayloadFor = (proof) => {
 };
 const renderPrVerifyCheckPayloadText = (payload) => `\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
 //#endregion
-//#region src/pr-verify-status.ts
-const PR_VERIFY_STATUS_CONTEXT = "patronage-factory/pr-verify";
-const GITHUB_PUBLISH_TIMEOUT_MS = 5e3;
-/**
-* Fire a best-effort async operation without blocking the caller and without
-* ever surfacing an unhandled rejection. Every check-run/commit-status
-* publisher in this module and github-check-runs.ts is a fire-and-forget
-* sink whose own failure (including its diagnostic write) must never affect
-* the gate result; this is the single detach wrapper they share instead of
-* each redeclaring the same try/catch-and-void shape.
-*/
-function runDetachedBestEffort(work) {
-	const safe = async () => {
-		try {
-			await work();
-		} catch {}
-	};
-	safe();
-}
-async function runGhStatus(args, cwd) {
-	const { execFile } = await import("node:child_process");
-	await promisify(execFile)("gh", args, {
-		cwd,
-		timeout: GITHUB_PUBLISH_TIMEOUT_MS
-	});
-}
-function createGhCommitStatusPoster(output, run = runGhStatus) {
-	return (input) => {
-		const { context = PR_VERIFY_STATUS_CONTEXT, cwd, description, owner, repo, sha, state, suppressFailureDiagnostic = false, targetUrl } = input;
-		const args = [
-			"api",
-			"--method",
-			"POST",
-			`/repos/${owner}/${repo}/statuses/${sha}`,
-			"-f",
-			`state=${state}`,
-			"-f",
-			`context=${context}`,
-			"-f",
-			`description=${description}`,
-			"-f",
-			`target_url=${targetUrl}`
-		];
-		const publish = async () => {
-			await Promise.resolve();
-			try {
-				await run(args, cwd);
-				if (state === "success") output.stdout.write(context === "patronage-factory/pr-verify" ? `pr:verify posted ${PR_VERIFY_STATUS_CONTEXT}=success\n` : `${context} posted success\n`);
-			} catch (error) {
-				if (suppressFailureDiagnostic) return;
-				const message = error instanceof Error ? error.message : String(error);
-				output.stderr.write(context === "patronage-factory/pr-verify" ? `pr:verify: unable to post ${PR_VERIFY_STATUS_CONTEXT} status: ${message}\n` : `${context}: unable to post commit status: ${message}\n`);
-			}
-		};
-		runDetachedBestEffort(publish);
-	};
-}
-//#endregion
 //#region src/github-check-runs.ts
 const FACTORY_CHECK_NAMES = {
 	"pr-ready": "patronage-factory/pr-ready",
@@ -9293,19 +9358,6 @@ const prePushVerifyBindingNotice = (sha) => `${FACTORY_CHECK_NAMES["pr-verify"]}
 The proof is complete and stored. After you push, pr:publish binds this check to the same commit and reuses that proof — no verification command runs again.
 Re-verify only if the tree changes: a new commit, an amend, or a rebase.
 `;
-async function githubJson(request, url, init, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) {
-	const response = await request(url, {
-		...init,
-		headers: {
-			Accept: "application/vnd.github+json",
-			"X-GitHub-Api-Version": "2022-11-28",
-			...init.headers
-		},
-		signal: init.signal ?? AbortSignal.timeout(timeoutMs)
-	});
-	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
-	return await response.json();
-}
 /**
 * Mint an installation token for the Patronage Factory App.
 *
@@ -9315,15 +9367,7 @@ async function githubJson(request, url, init, timeoutMs = GITHUB_PUBLISH_TIMEOUT
 * where the credentials come from (`user-config`), and the publish timeout the
 * rest of these calls are bound by. Nothing is cached, as before.
 */
-const installationToken = (repository, config, request, now, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) => mintInstallationToken({
-	credentials: config,
-	owner: repository.owner,
-	repo: repository.repo
-}, {
-	fetch: request,
-	now: () => now,
-	timeoutMs
-});
+const installationToken = (repository, config, request, now, timeoutMs = GITHUB_PUBLISH_TIMEOUT_MS) => mintFactoryInstallationToken(repository, config, request, now, timeoutMs);
 function verifyOutput(proof) {
 	const value = proof;
 	const commands = value.executedCommands?.length ?? 0;
@@ -9412,7 +9456,7 @@ async function postFactoryCheckRun({ config, deadlineMs, dependencies, detailsUr
 	const timeoutMs = dependencies.timeoutMs ?? 5e3;
 	try {
 		const token = await installationToken(input, config, request, (dependencies.now ?? Date.now)(), timeoutMs);
-		return await githubJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/check-runs`, {
+		return await requestGitHubJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/check-runs`, {
 			body: JSON.stringify(checkRunRequestBody(input, detailsUrl)),
 			headers: {
 				Authorization: `Bearer ${token}`,
@@ -9509,7 +9553,7 @@ async function servedFactoryCheckRun(input, config, dependencies) {
 		filter: "all",
 		per_page: "100"
 	});
-	const served = await githubJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/commits/${input.sha}/check-runs?${query.toString()}`, {
+	const served = await requestGitHubJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/commits/${input.sha}/check-runs?${query.toString()}`, {
 		headers: { Authorization: `Bearer ${token}` },
 		method: "GET"
 	}, timeoutMs);
@@ -10183,7 +10227,7 @@ const assertCleanInstallResolution = (repoRoot, dependencies = {}) => {
 //#region src/pr-verify.ts
 const PR_VERIFY_SCHEMA_VERSION = 4;
 const DEFAULT_PR_VERIFY_PROOF_PATH = ".factory-memory/pr-verify.json";
-const PR_VERIFY_PROOF_DESCRIPTOR = {
+const PR_VERIFY_PROOF_DESCRIPTOR$1 = {
 	defaultPath: DEFAULT_PR_VERIFY_PROOF_PATH,
 	label: "pr:verify proof",
 	parse: validatePrVerifyProof,
@@ -10225,7 +10269,7 @@ function defaultPrVerifyGit() {
 	};
 }
 function readPreviousPrVerifyProof(cwd, filePath) {
-	return readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR, cwd, filePath);
+	return readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR$1, cwd, filePath);
 }
 function collectBaselineFullProofs({ appendPrevious, previousProof, seedFilter }) {
 	if (!previousProof) return;
@@ -10569,7 +10613,7 @@ function runPrVerify(args, dependencies = {}) {
 //#endregion
 //#region src/demand-waive.ts
 const DEMAND_WAIVER_SCHEMA_VERSION = 1;
-const shaSchema$2 = z.string().regex(/^[0-9a-f]{40}$/u);
+const shaSchema$3 = z.string().regex(/^[0-9a-f]{40}$/u);
 const demandWaiverStorePath = (cwd, filePath) => path.resolve(cwd, filePath ?? ".factory-memory/demand-waivers.json");
 /** Every waiver recorded in this checkout; an absent or unreadable store is
 * no waivers, so a damaged file can only ever block, never permit. */
@@ -10619,7 +10663,7 @@ const requestRefusals = ({ demand, parsedDemand, rationale }) => [...parsedDeman
 * the authoring session read below describes a different candidate.
 */
 const candidateBindingRefusals = ({ headSha, pr, verifyProof }) => {
-	if (!headSha || !shaSchema$2.safeParse(headSha).success) return [`demand:waive could not resolve a pushed head SHA for PR #${pr}; a waiver binds to one candidate.`];
+	if (!headSha || !shaSchema$3.safeParse(headSha).success) return [`demand:waive could not resolve a pushed head SHA for PR #${pr}; a waiver binds to one candidate.`];
 	return verifyProof && verifyProof.headSha !== headSha ? [`The pr:verify proof in this checkout records head ${verifyProof.headSha}, not the pushed head ${headSha}; re-run pr:verify on the candidate before waiving one of its demands.`] : [];
 };
 /**
@@ -10645,7 +10689,7 @@ const runDemandWaive = (args, dependencies = {}) => {
 		pr: args.pr,
 		repo: repository.name
 	});
-	const verifyProof = readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR, cwd);
+	const verifyProof = readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR$1, cwd);
 	refusals.push(...candidateBindingRefusals({
 		headSha,
 		pr: args.pr,
@@ -13184,13 +13228,13 @@ const HOSTED_VERIFY_CHECK_NAME$1 = "verify";
 const GITHUB_ACTIONS_APP_ID = 15368;
 const GITHUB_ACTIONS_APP_SLUG = "github-actions";
 const MERGE_FREEZE_SCHEMA_VERSION = 1;
-const CHECK_RUNS_PER_PAGE = 100;
-const CHECK_RUN_PAGE_LIMIT = 10;
-const shaSchema$1 = z.string().regex(/^[0-9a-f]{40}$/u);
+const CHECK_RUNS_PER_PAGE$1 = 100;
+const CHECK_RUN_PAGE_LIMIT$1 = 10;
+const shaSchema$2 = z.string().regex(/^[0-9a-f]{40}$/u);
 const activeMergeFreezeStateSchema = z.object({
 	active: z.literal(true),
 	generationId: z.number().int().positive(),
-	headSha: shaSchema$1,
+	headSha: shaSchema$2,
 	outcome: z.enum(["active", "stale"]),
 	reason: z.string().min(1),
 	recordedAt: z.iso.datetime(),
@@ -13200,7 +13244,7 @@ const inactiveMergeFreezeStateSchema = z.object({
 	active: z.literal(false),
 	clearRationale: z.string().min(1).optional(),
 	generationId: z.number().int().positive(),
-	headSha: shaSchema$1,
+	headSha: shaSchema$2,
 	outcome: z.literal("inactive"),
 	reason: z.string().min(1),
 	recordedAt: z.iso.datetime(),
@@ -13224,7 +13268,7 @@ const mergeFreezeCheckRunListItemSchema = z.object({
 		"neutral",
 		"success"
 	]).nullable().optional(),
-	head_sha: shaSchema$1,
+	head_sha: shaSchema$2,
 	id: z.number().int().positive(),
 	name: z.literal(MERGE_FREEZE_CHECK_NAME),
 	output: z.object({ text: z.string().nullable().optional() }).optional(),
@@ -13249,7 +13293,7 @@ const hostedVerifyCheckRunSchema = z.object({
 		id: z.literal(GITHUB_ACTIONS_APP_ID),
 		slug: z.literal(GITHUB_ACTIONS_APP_SLUG)
 	}),
-	head_sha: shaSchema$1,
+	head_sha: shaSchema$2,
 	id: z.number().int().positive(),
 	name: z.literal(HOSTED_VERIFY_CHECK_NAME$1),
 	started_at: z.iso.datetime().nullable(),
@@ -13260,8 +13304,8 @@ const hostedVerifyCheckRunSchema = z.object({
 	])
 });
 const commitParentsSchema = z.object({
-	parents: z.array(z.object({ sha: shaSchema$1 })),
-	sha: shaSchema$1
+	parents: z.array(z.object({ sha: shaSchema$2 })),
+	sha: shaSchema$2
 });
 function selectListedMergeFreezeGeneration(listed, expectedHeadSha) {
 	const runs = z.object({ check_runs: z.array(z.unknown()) }).parse(listed).check_runs.map((run) => mergeFreezeCheckRunListItemSchema.parse(run));
@@ -13395,11 +13439,11 @@ function createGitHubCheckRunMergeFreezeApi(dependencies = {}) {
 	return {
 		list({ cwd, headSha, name, repository }) {
 			const checkRuns = [];
-			for (let page = 1; page <= CHECK_RUN_PAGE_LIMIT; page += 1) {
-				const response = z.object({ check_runs: z.array(z.unknown()) }).parse((dependencies.readJson ?? runGhJsonAt)(["api", `/repos/${repository.owner}/${repository.name}/commits/${headSha}/check-runs?check_name=${encodeURIComponent(name)}&filter=all&per_page=${CHECK_RUNS_PER_PAGE}&page=${page}`], cwd));
+			for (let page = 1; page <= CHECK_RUN_PAGE_LIMIT$1; page += 1) {
+				const response = z.object({ check_runs: z.array(z.unknown()) }).parse((dependencies.readJson ?? runGhJsonAt)(["api", `/repos/${repository.owner}/${repository.name}/commits/${headSha}/check-runs?check_name=${encodeURIComponent(name)}&filter=all&per_page=${CHECK_RUNS_PER_PAGE$1}&page=${page}`], cwd));
 				checkRuns.push(...response.check_runs);
-				if (response.check_runs.length < CHECK_RUNS_PER_PAGE) break;
-				if (page === CHECK_RUN_PAGE_LIMIT) throw new Error(`${MERGE_FREEZE_CHECK_NAME} check-run pagination limit was exhausted before GitHub returned a final page.`);
+				if (response.check_runs.length < CHECK_RUNS_PER_PAGE$1) break;
+				if (page === CHECK_RUN_PAGE_LIMIT$1) throw new Error(`${MERGE_FREEZE_CHECK_NAME} check-run pagination limit was exhausted before GitHub returned a final page.`);
 			}
 			return { check_runs: checkRuns };
 		},
@@ -13495,7 +13539,7 @@ const selectReviewProof = ({ reviewProof }) => {
 	if (isExplicitReviewFailure(reviewProof) || isUntypedReviewProof(reviewProof)) return {};
 	return hasReviewProof(reviewProof) ? reviewProof : {};
 };
-const shaSchema = z.string().regex(/^[0-9a-f]{40}$/u);
+const shaSchema$1 = z.string().regex(/^[0-9a-f]{40}$/u);
 const patchIdSchema = z.string().regex(/^[0-9a-f]{40,64}$/u);
 const reviewCycleStateSchema = z.object({
 	autoBlockingFindings: z.number().int().nonnegative(),
@@ -13550,7 +13594,7 @@ const readinessRepairSchema = z.object({
 	command: z.string().min(1)
 });
 const managedReadinessLedgerSchema = z.object({
-	baseSha: shaSchema,
+	baseSha: shaSchema$1,
 	blockingReasons: z.array(z.string()),
 	classification: z.enum([
 		"docs/process-only",
@@ -13590,13 +13634,13 @@ const managedReadinessLedgerSchema = z.object({
 	* branded `patronage-factory/pr-ready` check binds to — GitHub's required
 	* checks compare a new head's checks against exactly this SHA (#477).
 	*/
-	headSha: shaSchema,
+	headSha: shaSchema$1,
 	/**
 	* The merge base used to evaluate tree-scoped external evidence. Optional
 	* only for backwards-compatible parsing of readiness ledgers written before
 	* #732; a committed verify-type demand cannot pass the merge gate without it.
 	*/
-	mergeBaseSha: shaSchema.optional(),
+	mergeBaseSha: shaSchema$1.optional(),
 	patchId: patchIdSchema,
 	pr: z.number().int().positive(),
 	repairs: z.array(readinessRepairSchema).default([]),
@@ -14312,6 +14356,605 @@ const evaluateReadiness = (input) => {
 	};
 };
 //#endregion
+//#region src/github-pr-status-comment.ts
+const FACTORY_PR_STATUS_COMMENT_MARKER = "<!-- patronage-factory-pr-status-hud -->";
+const OBSERVED_MARKER_PREFIX = "<!-- patronage-factory-pr-status-observed:";
+const OBSERVED_MARKER_SUFFIX = " -->";
+const UPSERT_ATTEMPT_LIMIT = 5;
+const writtenCommentSchema = z.object({
+	html_url: z.string().url(),
+	id: z.number().int().positive(),
+	performed_via_github_app: z.object({ id: z.number().int().positive() }).refine((app) => String(app.id) === FACTORY_PROOF_GATE_APP_ID, "PR status HUD mutation was not performed by the Patronage Factory App.")
+});
+const issueCommentSchema = writtenCommentSchema.extend({
+	body: z.string().nullable(),
+	performed_via_github_app: z.object({ id: z.number().int().positive() }).nullable().optional()
+});
+const managedBody = (body, observedAt) => {
+	const observed = observedAt === void 0 ? "" : `${OBSERVED_MARKER_PREFIX}${observedAt}${OBSERVED_MARKER_SUFFIX}\n`;
+	const trimmed = body.trim();
+	if (trimmed === "" && observed === "") return FACTORY_PR_STATUS_COMMENT_MARKER;
+	return `${FACTORY_PR_STATUS_COMMENT_MARKER}\n${observed}${trimmed}`;
+};
+const readObservedAt = (body) => {
+	if (!body) return;
+	const start = body.indexOf(OBSERVED_MARKER_PREFIX);
+	if (start === -1) return;
+	const from = start + 42;
+	const end = body.indexOf(OBSERVED_MARKER_SUFFIX, from);
+	if (end === -1) return;
+	const value = body.slice(from, end);
+	if (Number.isNaN(new Date(value).valueOf())) return;
+	return value;
+};
+const existingIsCurrentOrNewer = (existingBody, incomingObservedAt) => {
+	if (incomingObservedAt === void 0) return false;
+	const existingObservedAt = readObservedAt(existingBody);
+	return existingObservedAt !== void 0 && existingObservedAt >= incomingObservedAt;
+};
+const isManagedComment = (comment) => String(comment.performed_via_github_app?.id) === FACTORY_PROOF_GATE_APP_ID && Boolean(comment.body?.includes("<!-- patronage-factory-pr-status-hud -->"));
+const exchangeFor = (dependencies) => {
+	if (dependencies.request) return dependencies.request;
+	if (dependencies.requestJson) {
+		const { requestJson } = dependencies;
+		return async (input) => {
+			return {
+				json: await requestJson(input),
+				status: 200
+			};
+		};
+	}
+	return requestFactoryApp;
+};
+const listManagedComments = async (exchange, input, pageNumber = 1, collected = []) => {
+	const response = await exchange({
+		method: "GET",
+		owner: input.owner,
+		path: `issues/${input.pr}/comments?per_page=100&page=${pageNumber}`,
+		repo: input.repo
+	});
+	const page = z.array(issueCommentSchema).parse(response.json);
+	const managed = [...collected, ...page.filter(isManagedComment)];
+	if (page.length < 100) return managed;
+	return listManagedComments(exchange, input, pageNumber + 1, managed);
+};
+const resultFrom = (action, comment) => ({
+	action,
+	commentId: comment.id,
+	url: comment.html_url
+});
+const isRetryableMutation = (error) => error instanceof GitHubApiError && error.status === 404;
+const deleteManagedComment = async (exchange, input, commentId) => {
+	try {
+		await exchange({
+			method: "DELETE",
+			owner: input.owner,
+			path: `issues/comments/${commentId}`,
+			repo: input.repo
+		});
+	} catch (error) {
+		if (!(error instanceof GitHubApiError) || error.status !== 404) throw error;
+	}
+};
+const newestBody = (comments, incomingBody, incomingObservedAt) => {
+	let body = incomingBody;
+	let observedAt = incomingObservedAt;
+	for (const comment of comments) {
+		const { body: commentBody } = comment;
+		const observed = readObservedAt(commentBody);
+		if (observed !== void 0 && (observedAt === void 0 || observed > observedAt) && commentBody) {
+			body = commentBody;
+			observedAt = observed;
+		}
+	}
+	return body;
+};
+const readComment = async (exchange, input, commentId) => {
+	const response = await exchange({
+		method: "GET",
+		owner: input.owner,
+		path: `issues/comments/${commentId}`,
+		repo: input.repo
+	});
+	return issueCommentSchema.parse(response.json);
+};
+const patchManaged = async (exchange, input, commentId, body) => {
+	const response = await exchange({
+		body: { body },
+		method: "PATCH",
+		owner: input.owner,
+		path: `issues/comments/${commentId}`,
+		repo: input.repo
+	});
+	return writtenCommentSchema.parse(response.json);
+};
+const reconcileManagedComments = async (exchange, input, comments, incomingBody) => {
+	const [first, ...rest] = comments;
+	if (!first) throw new Error("PR status HUD reconcile requires at least one managed comment.");
+	let keeper = first;
+	for (const comment of rest) if (comment.id < keeper.id) keeper = comment;
+	await Promise.all(comments.filter((comment) => comment.id !== keeper.id).map((comment) => deleteManagedComment(exchange, input, comment.id)));
+	const body = newestBody(comments, incomingBody, input.observedAt);
+	if (keeper.body === body) return keeper;
+	const updated = await patchManaged(exchange, input, keeper.id, body);
+	return {
+		...keeper,
+		...updated,
+		body
+	};
+};
+const attemptUpsert = async (exchange, input, writtenBody, attempt) => {
+	if (attempt >= UPSERT_ATTEMPT_LIMIT) throw new Error("PR status HUD upsert exhausted attempts without a single current comment.");
+	const managed = await listManagedComments(exchange, input);
+	if (managed.length > 1) return resultFrom("updated", await reconcileManagedComments(exchange, input, managed, writtenBody));
+	const [existing] = managed;
+	if (existing) try {
+		const fresh = await readComment(exchange, input, existing.id);
+		if (existingIsCurrentOrNewer(fresh.body, input.observedAt)) return resultFrom("updated", fresh);
+		return resultFrom("updated", await patchManaged(exchange, input, existing.id, writtenBody));
+	} catch (error) {
+		if (isRetryableMutation(error)) return attemptUpsert(exchange, input, writtenBody, attempt + 1);
+		throw error;
+	}
+	try {
+		const createdResponse = await exchange({
+			body: { body: writtenBody },
+			method: "POST",
+			owner: input.owner,
+			path: `issues/${input.pr}/comments`,
+			repo: input.repo
+		});
+		const created = writtenCommentSchema.parse(createdResponse.json);
+		const after = await listManagedComments(exchange, input);
+		if (after.length > 1) {
+			const keeper = await reconcileManagedComments(exchange, input, after, writtenBody);
+			return resultFrom(keeper.id === created.id ? "created" : "updated", keeper);
+		}
+		return resultFrom("created", created);
+	} catch (error) {
+		if (isRetryableMutation(error)) return attemptUpsert(exchange, input, writtenBody, attempt + 1);
+		throw error;
+	}
+};
+async function upsertFactoryPrStatusComment(input, dependencies = {}) {
+	return attemptUpsert(exchangeFor(dependencies), input, managedBody(input.body, input.observedAt), 0);
+}
+//#endregion
+//#region src/preview-lifecycle.ts
+const previewTargetPlanSchema = z.object({
+	basis: z.string(),
+	disposition: z.enum(["deploy", "not-required"]),
+	name: z.string().min(1)
+});
+const previewLifecyclePlanSchema = z.object({
+	deploy: z.array(z.string()),
+	notRequired: z.array(previewTargetPlanSchema),
+	stampTrusted: z.boolean(),
+	targets: z.array(previewTargetPlanSchema)
+}).superRefine((plan, context) => {
+	const deploy = plan.targets.filter((target) => target.disposition === "deploy").map((target) => target.name);
+	const notRequired = plan.targets.filter((target) => target.disposition === "not-required");
+	if (JSON.stringify(plan.deploy) !== JSON.stringify(deploy)) context.addIssue({
+		code: "custom",
+		message: "deploy must match the plan's deploy target dispositions",
+		path: ["deploy"]
+	});
+	if (JSON.stringify(plan.notRequired) !== JSON.stringify(notRequired)) context.addIssue({
+		code: "custom",
+		message: "notRequired must match the plan's not-required target dispositions",
+		path: ["notRequired"]
+	});
+});
+/** Validate a serialized plan without deriving or changing its dispositions. */
+const validatePreviewLifecyclePlan = (value) => previewLifecyclePlanSchema.parse(value);
+/**
+* The declared preview stacks: impact targets that are ALSO declared required
+* checks — i.e. targets whose proof is produced externally, which is exactly
+* what a preview producer is.
+*
+* Deriving the list from the two existing declarations rather than adding a
+* third is what makes lifecycle and demand unable to disagree: the stacks this
+* plan can withhold are precisely the demands wave 2 can release, so a stack
+* can never be skipped while its proof stays demanded.
+*/
+const previewLifecycleTargets = (profile) => {
+	const demanded = new Set((profile.requiredChecks ?? []).map(({ name }) => name));
+	return (profile.impact?.targets ?? []).map(({ name }) => name).filter((name) => demanded.has(name));
+};
+/**
+* Plan the preview lifecycle for one candidate.
+*
+* Trust is resolved here through the SAME identity gate demand release uses
+* (`trustedImpactStamp`): the proof must have passed and must bind both the
+* candidate's headSha and its patchId. A stale, aborted, absent, or
+* differently-bound proof yields no stamp, and every declared stack is planned
+* for deploy. Total over its INPUTS — no proof, stamp, or profile can make it
+* throw. A malformed CALL is the deliberate exception: omitting
+* `vetoedTargets` is API misuse, not data doubt, and throws.
+*/
+const planPreviewLifecycle = ({ candidate, profile, proof, vetoedTargets }) => {
+	assertVetoedTargets(vetoedTargets, "planPreviewLifecycle");
+	const stamp = trustedImpactStamp({
+		candidate,
+		proof
+	});
+	const vetoed = new Set(vetoedTargets);
+	const targets = previewLifecycleTargets(profile).map((name) => {
+		const decision = impactStampScopeDecision({
+			stamp,
+			surface: "preview-lifecycle",
+			targetName: name
+		});
+		const vetoedHere = decision.scoped && vetoed.has(name);
+		return {
+			basis: vetoedHere ? `veto: a current envelope bound to this candidate records stack "${name}" as FAILING, so the stamp's release is withheld (${decision.reason})` : decision.reason,
+			disposition: decision.scoped && !vetoedHere ? "not-required" : "deploy",
+			name
+		};
+	});
+	return {
+		deploy: targets.filter((target) => target.disposition === "deploy").map((target) => target.name),
+		notRequired: targets.filter((target) => target.disposition === "not-required"),
+		stampTrusted: stamp !== void 0,
+		targets
+	};
+};
+//#endregion
+//#region src/pr-status-hud.ts
+const statusLabel = (status) => {
+	return `${{
+		Failed: "❌",
+		"In progress": "⏳",
+		Ready: "✅",
+		Skipped: "➖"
+	}[status]} ${status}`;
+};
+const utcTimestamp = (value) => {
+	const instant = new Date(value);
+	if (Number.isNaN(instant.valueOf())) throw new TypeError(`PR status HUD requires an ISO timestamp; received ${value}.`);
+	return `${instant.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+};
+const markdownText = (value) => value.split(/\r\n?|\n/u).join(" ").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("@", "&#64;").replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("*", "\\*").replaceAll("_", "\\_").replaceAll("[", "\\[").replaceAll("]", "\\]");
+const markdownCell = (value) => markdownText(value).replaceAll("|", "\\|");
+const safeMarkdownLink = (label, value) => {
+	if (!value) return "—";
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "https:" && url.protocol !== "http:") return "—";
+		return `[${label}](<${url.href}>)`;
+	} catch {
+		return "—";
+	}
+};
+const renderTable = (rows) => [
+	"| Target | Status | Link | Timestamp |",
+	"| --- | --- | --- | --- |",
+	...rows.map((row) => `| ${markdownCell(row.target)} | ${statusLabel(row.status)} | ${row.link} | ${row.timestamp} |`)
+].join("\n");
+const checkRow = (target, snapshot, renderedAt) => {
+	if (!snapshot) return {
+		detail: "No completed Factory App snapshot is available at this head.",
+		link: "—",
+		status: "In progress",
+		target,
+		timestamp: utcTimestamp(renderedAt)
+	};
+	return {
+		detail: `Completed snapshot: ${snapshot.conclusion}.`,
+		link: safeMarkdownLink("Details", snapshot.detailsUrl),
+		status: snapshot.conclusion === "success" ? "Ready" : "Failed",
+		target,
+		timestamp: utcTimestamp(snapshot.completedAt)
+	};
+};
+const previewRow = (target, registration, failure, renderedAt) => {
+	if (target.disposition === "not-required") return {
+		detail: target.basis,
+		link: "—",
+		status: "Skipped",
+		target: target.name,
+		timestamp: utcTimestamp(renderedAt)
+	};
+	if (registration) return {
+		detail: "Factory-owned preview registration is live at this head.",
+		link: safeMarkdownLink("Preview", registration.url),
+		status: "Ready",
+		target: target.name,
+		timestamp: utcTimestamp(renderedAt)
+	};
+	if (failure) return {
+		detail: `Preview deploy concluded ${failure.conclusion}.`,
+		link: safeMarkdownLink("Details", failure.detailsUrl),
+		status: "Failed",
+		target: target.name,
+		timestamp: utcTimestamp(failure.completedAt)
+	};
+	return {
+		detail: target.basis,
+		link: "—",
+		status: "In progress",
+		target: target.name,
+		timestamp: utcTimestamp(renderedAt)
+	};
+};
+function renderFactoryPrStatusHud(input) {
+	if (input.planHeadSha !== input.headSha) throw new Error(`PR status HUD plan targets ${input.planHeadSha}, expected current head ${input.headSha}.`);
+	const checks = new Map(Object.entries(input.checks).flatMap(([name, check]) => {
+		if (!check) return [];
+		const expectedSha = name === "patronage-factory/merge-freeze" ? input.baseSha : input.headSha;
+		return check.headSha === expectedSha ? [[name, check]] : [];
+	}));
+	const registrations = new Map(input.previewRegistrations.filter((row) => row.pr === input.pr && row.headSha === input.headSha && row.cleanupStatus === "pending").map((row) => [row.stack, row]));
+	const rows = [
+		checkRow("Verify", checks.get("patronage-factory/pr-verify"), input.renderedAt),
+		checkRow("Ready", checks.get("patronage-factory/pr-ready"), input.renderedAt),
+		...input.plan.targets.map((target) => previewRow(target, registrations.get(target.name), input.previewFailures?.[target.name], input.renderedAt))
+	];
+	const mergeFreeze = checks.get("patronage-factory/merge-freeze");
+	if (mergeFreeze) rows.push(checkRow("Merge freeze", mergeFreeze, input.renderedAt));
+	rows.push({
+		detail: "Production deployment is not demanded for a pull request.",
+		link: "—",
+		status: "Skipped",
+		target: "Production deploy",
+		timestamp: utcTimestamp(input.renderedAt)
+	});
+	const active = rows.filter((row) => row.status !== "Skipped");
+	const skipped = rows.filter((row) => row.status === "Skipped");
+	const skippedDetails = skipped.map((row) => `- **${markdownText(row.target)}:** ${markdownText(row.detail)}`).join("\n");
+	return [
+		"## Patronage Factory status",
+		"",
+		renderTable(active),
+		"",
+		"<details>",
+		`<summary>Skipped (${skipped.length})</summary>`,
+		"",
+		renderTable(skipped),
+		"",
+		skippedDetails,
+		"",
+		"</details>",
+		"",
+		`_Observed ${utcTimestamp(input.renderedAt)} at \`${input.headSha.slice(0, 7)}\`. Human-readable presentation only; checks and factory evidence remain authoritative._`
+	].join("\n");
+}
+async function presentFactoryPrStatusHud(input, dependencies) {
+	const identity = {
+		headSha: input.headSha,
+		owner: input.owner,
+		pr: input.pr,
+		repo: input.repo
+	};
+	const sources = await dependencies.readSources(identity);
+	const renderedAt = input.renderedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+	const body = renderFactoryPrStatusHud({
+		...sources,
+		headSha: input.headSha,
+		plan: input.plan,
+		planHeadSha: input.planHeadSha,
+		pr: input.pr,
+		renderedAt
+	});
+	await dependencies.assertCurrentIdentity({
+		baseSha: sources.baseSha,
+		...identity
+	});
+	return (dependencies.upsert ?? upsertFactoryPrStatusComment)({
+		body,
+		observedAt: renderedAt,
+		owner: input.owner,
+		pr: input.pr,
+		repo: input.repo
+	});
+}
+const checkRunSchema = z.object({
+	app: z.object({ id: z.number().int().positive() }).nullable().optional(),
+	completed_at: z.iso.datetime().nullable(),
+	conclusion: z.string().nullable().optional(),
+	details_url: z.string().nullable().optional(),
+	head_sha: z.string().regex(/^[0-9a-f]{40}$/u),
+	name: z.string(),
+	started_at: z.iso.datetime().nullable(),
+	status: z.enum([
+		"completed",
+		"in_progress",
+		"queued"
+	])
+});
+const CHECK_RUNS_PER_PAGE = 100;
+const CHECK_RUN_PAGE_LIMIT = 10;
+const pullIdentitySchema = z.object({
+	base: z.object({ sha: z.string().regex(/^[0-9a-f]{40}$/u) }),
+	head: z.object({ sha: z.string().regex(/^[0-9a-f]{40}$/u) })
+});
+const readFactoryPrIdentity = async (input, dependencies) => pullIdentitySchema.parse(await requestGitHubJson(dependencies.fetch ?? fetch, `https://api.github.com/repos/${input.owner}/${input.repo}/pulls/${input.pr}`, {
+	headers: { Authorization: `Bearer ${input.token}` },
+	method: "GET"
+}, dependencies.timeoutMs));
+async function assertFactoryPrStatusIdentity(input, dependencies = {}) {
+	const current = await readFactoryPrIdentity(input, dependencies);
+	if (current.head.sha !== input.headSha || current.base.sha !== input.baseSha) throw new Error(`PR status HUD candidate identity moved to base ${current.base.sha} / head ${current.head.sha}; refusing stale presentation for base ${input.baseSha} / head ${input.headSha}.`);
+}
+const listFactoryCheckRuns = async (input, name, sha, dependencies) => {
+	const request = dependencies.fetch ?? fetch;
+	const runs = [];
+	for (let page = 1; page <= CHECK_RUN_PAGE_LIMIT; page += 1) {
+		const response = z.object({ check_runs: z.array(checkRunSchema) }).parse(await requestGitHubJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/commits/${sha}/check-runs?check_name=${encodeURIComponent(name)}&filter=all&per_page=${CHECK_RUNS_PER_PAGE}&page=${page}`, {
+			headers: { Authorization: `Bearer ${input.token}` },
+			method: "GET"
+		}, dependencies.timeoutMs));
+		runs.push(...response.check_runs);
+		if (response.check_runs.length < CHECK_RUNS_PER_PAGE) return runs;
+	}
+	throw new Error(`${name} pagination limit was exhausted before GitHub returned a final page.`);
+};
+const completedSnapshot = (name, sha, runs) => {
+	const candidates = runs.filter((run) => String(run.app?.id ?? "") === FACTORY_PROOF_GATE_APP_ID && run.head_sha === sha && run.name === name);
+	if (candidates.some((run) => !Number.isFinite(generationOrderMs(run.started_at)))) throw new Error(`${name} presentation snapshot has a generation with no usable started_at.`);
+	const selected = selectNewestGeneration(candidates.map((run) => ({
+		orderMs: generationOrderMs(run.started_at),
+		run
+	})));
+	if (selected.kind === "ambiguous") throw new Error(`Newest ${name} presentation snapshot is ambiguous: ${selected.tied.length} check runs share the newest timestamp.`);
+	if (selected.kind === "none") return;
+	const { run } = selected.generation;
+	if (run.status !== "completed" || !run.completed_at || !run.conclusion) return;
+	return {
+		completedAt: run.completed_at,
+		conclusion: run.conclusion,
+		...run.details_url ? { detailsUrl: run.details_url } : {},
+		headSha: run.head_sha,
+		name
+	};
+};
+const FAILED_PREVIEW_CONCLUSIONS = new Set([
+	"action_required",
+	"cancelled",
+	"failure",
+	"stale",
+	"startup_failure",
+	"timed_out"
+]);
+const completedFailedPreview = (name, sha, runs) => {
+	const candidates = runs.filter((run) => run.head_sha === sha && run.name === name);
+	if (candidates.some((run) => !Number.isFinite(generationOrderMs(run.started_at)))) throw new Error(`${name} preview failure snapshot has a generation with no usable started_at.`);
+	const selected = selectNewestGeneration(candidates.map((run) => ({
+		orderMs: generationOrderMs(run.started_at),
+		run
+	})));
+	if (selected.kind === "ambiguous") throw new Error(`Newest ${name} preview failure snapshot is ambiguous: ${selected.tied.length} check runs share the newest timestamp.`);
+	if (selected.kind === "none") return;
+	const { run } = selected.generation;
+	if (run.status !== "completed" || !run.completed_at || !run.conclusion || !FAILED_PREVIEW_CONCLUSIONS.has(run.conclusion)) return;
+	return {
+		completedAt: run.completed_at,
+		conclusion: run.conclusion,
+		...run.details_url ? { detailsUrl: run.details_url } : {},
+		headSha: run.head_sha,
+		name
+	};
+};
+async function readFactoryPrStatusSources(input, dependencies = {}) {
+	const listPreviews = dependencies.listPreviewRegistrations ?? ((identity) => previewProofInventory.list(identity, {
+		fetch: dependencies.fetch,
+		timeoutMs: dependencies.timeoutMs,
+		token: identity.token
+	}));
+	const [previewRegistrations, pullIdentity] = await Promise.all([listPreviews(input), readFactoryPrIdentity(input, dependencies)]);
+	if (pullIdentity.head.sha !== input.headSha) throw new Error(`PR status HUD candidate head moved to ${pullIdentity.head.sha}; refusing stale presentation for ${input.headSha}.`);
+	const baseSha = pullIdentity.base.sha;
+	const checkTargets = [
+		["patronage-factory/pr-verify", input.headSha],
+		["patronage-factory/pr-ready", input.headSha],
+		["patronage-factory/merge-freeze", baseSha]
+	];
+	const listedChecks = await Promise.all(checkTargets.map(([name, sha]) => listFactoryCheckRuns(input, name, sha, dependencies)));
+	const checks = Object.fromEntries(checkTargets.flatMap(([name, sha], index) => {
+		const snapshot = completedSnapshot(name, sha, listedChecks[index] ?? []);
+		return snapshot ? [[name, snapshot]] : [];
+	}));
+	const previewTargets = input.previewTargets ?? [];
+	const listedPreviewChecks = await Promise.all(previewTargets.map((name) => listFactoryCheckRuns(input, name, input.headSha, dependencies)));
+	return {
+		baseSha,
+		checks,
+		previewFailures: Object.fromEntries(previewTargets.flatMap((name, index) => {
+			const snapshot = completedFailedPreview(name, input.headSha, listedPreviewChecks[index] ?? []);
+			return snapshot ? [[name, snapshot]] : [];
+		})),
+		previewRegistrations
+	};
+}
+const OBJECT_ID = /^[0-9a-f]{40}$/u;
+const PR_VERIFY_PROOF_DESCRIPTOR = {
+	defaultPath: ".factory-memory/pr-verify.json",
+	label: "pr:verify proof",
+	parse: validatePrVerifyProof,
+	schemaVersion: 4
+};
+const objectIdOrHead = (value, headSha) => value !== void 0 && OBJECT_ID.test(value) ? value : headSha;
+/**
+* Consume `planPreviewLifecycle` for the current checkout. No second plan is
+* invented: dispositions are Ready/Skipped from `deploy` vs `not-required`.
+* Candidate identity is never copied from the proof. Absent independent
+* identity or an unbound verify proof is the planner's conservative path.
+*/
+function planFactoryPrStatusHud(input) {
+	const { profile } = loadProjectProfile({
+		cwd: input.cwd,
+		profilePath: input.profilePath
+	});
+	const proof = readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR, input.cwd);
+	const independentPatchId = input.patchId !== void 0 && OBJECT_ID.test(input.patchId) ? input.patchId : void 0;
+	const boundProof = independentPatchId !== void 0 && proof !== void 0 && proof.headSha === input.headSha ? proof : void 0;
+	const patchId = independentPatchId ?? input.headSha;
+	const mergeBaseSha = objectIdOrHead(input.mergeBaseSha, input.headSha);
+	return planPreviewLifecycle({
+		candidate: {
+			headSha: input.headSha,
+			patchId
+		},
+		profile,
+		proof: boundProof,
+		vetoedTargets: boundFailingCheckNames({
+			candidate: {
+				headSha: input.headSha,
+				mergeBaseSha,
+				patchId
+			},
+			checkType: "verify",
+			envelopes: loadEvidenceEnvelopes(input.cwd)
+		})
+	});
+}
+const resolveHudToken = async (input) => {
+	if (input.token) return input.token;
+	const config = tryUserConfig()?.config.githubApp;
+	if (!config) throw new Error("PR status HUD refresh requires the Patronage Factory GitHub App.");
+	return mintFactoryInstallationToken({
+		owner: input.owner,
+		repo: input.repo
+	}, config, fetch, Date.now());
+};
+/** Plan from the checkout and present the App-owned HUD. */
+async function refreshFactoryPrStatusHud(input) {
+	const plan = planFactoryPrStatusHud(input);
+	const token = await resolveHudToken(input);
+	return presentFactoryPrStatusHud({
+		headSha: input.headSha,
+		owner: input.owner,
+		plan,
+		planHeadSha: input.headSha,
+		pr: input.pr,
+		repo: input.repo
+	}, {
+		assertCurrentIdentity: (identity) => assertFactoryPrStatusIdentity({
+			...identity,
+			token
+		}),
+		readSources: (identity) => readFactoryPrStatusSources({
+			...identity,
+			previewTargets: plan.deploy,
+			token
+		}),
+		upsert: (upsertInput) => upsertFactoryPrStatusComment(upsertInput, { request: (request) => requestFactoryApp(request, { token }) })
+	});
+}
+/**
+* Presentation must not fail an admission gate. Used after pr:ready publishes
+* its check so the table is not stuck at first-write.
+*/
+async function refreshFactoryPrStatusHudSafely(input, onNotice = (message) => {
+	console.warn(message);
+}) {
+	try {
+		await refreshFactoryPrStatusHud(input);
+	} catch (error) {
+		onNotice(`PR status HUD refresh failed without affecting the gate: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+//#endregion
 //#region src/pr-ready.ts
 const CHECK_CONCLUSION_BY_READINESS_STATUS = {
 	blocked: "failure",
@@ -14583,6 +15226,20 @@ async function runPrReady(args, dependencies = {}) {
 		sleep: dependencies.sleep
 	});
 	let finalCheckPublished = false;
+	let hudMergeBaseSha;
+	let hudPatchId;
+	const presentHud = async () => {
+		await (dependencies.presentStatusHud ?? refreshFactoryPrStatusHudSafely)({
+			cwd,
+			headSha: pr.headRefOid,
+			owner: repository.owner,
+			pr: args.pr,
+			repo: repository.name,
+			...args.profilePath === void 0 ? {} : { profilePath: args.profilePath },
+			...hudMergeBaseSha === void 0 ? {} : { mergeBaseSha: hudMergeBaseSha },
+			...hudPatchId === void 0 ? {} : { patchId: hudPatchId }
+		});
+	};
 	try {
 		const authoritativeBaseSha = authoritativePrBase({
 			args,
@@ -14594,7 +15251,9 @@ async function runPrReady(args, dependencies = {}) {
 			cwd,
 			git
 		});
-		const { headSha: localHeadSha, patchId } = candidateIdentityForBase(authoritativeBaseSha);
+		const { headSha: localHeadSha, mergeBaseSha: resolvedMergeBaseSha, patchId } = candidateIdentityForBase(authoritativeBaseSha);
+		hudMergeBaseSha = resolvedMergeBaseSha;
+		hudPatchId = patchId;
 		const files = git.changedFiles(cwd, authoritativeBaseSha, pr.headRefOid);
 		const committedPolicy = policyProfileAtCommittedHead({
 			cwd,
@@ -14778,6 +15437,7 @@ async function runPrReady(args, dependencies = {}) {
 			subject: { prNumber: args.pr }
 		}, dependencies.hq);
 		reportProof(proof, output, Boolean(args.json), args.report ?? true);
+		await presentHud();
 		if (proof.status !== "ready" && (args.throwWhenBlocked ?? true)) throw new Error(`pr:ready blocked: ${proof.blockingReasons.join(" ")}`);
 		return proof;
 	} catch (error) {
@@ -14798,6 +15458,7 @@ async function runPrReady(args, dependencies = {}) {
 				sha: pr.headRefOid
 			};
 			if (!await (dependencies.publishFinalCheckRun ? dependencies.publishFinalCheckRun(failureCheckInput) : ensureFactoryCheckRunPublished(failureCheckInput, { onDiagnostic: (diagnostic) => process.stderr.write(diagnostic) }))) console.warn(`pr:ready could not publish the failing ${FACTORY_CHECK_NAMES["pr-ready"]} check run for ${pr.headRefOid}; the required check is absent rather than red.`);
+			await presentHud();
 		}
 		throw error;
 	}
@@ -15207,7 +15868,7 @@ async function runPrReview(args, dependencies = {}) {
 		git
 	})(args.base);
 	const { additional: additionalOutput, canonical: output } = resolveProofOutputPaths(cwd, DEFAULT_PR_REVIEW_PROOF_PATH, args.output);
-	const verifyProof = readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR, cwd, args.verifyProof ?? ".factory-memory/pr-verify.json");
+	const verifyProof = readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR$1, cwd, args.verifyProof ?? ".factory-memory/pr-verify.json");
 	const writeProofCopies = (proof) => {
 		writeReviewProofCopies(cwd, proof, output, additionalOutput);
 		enqueueHqIngest({
@@ -15418,7 +16079,7 @@ function discoverOrCreatePullRequestNumber({ args, branch, cwd, gh }) {
 	if (!created[0]) throw new Error(`gh pr create completed but no PR was found for branch ${branch}.`);
 	return created[0].number;
 }
-const readOptionalVerifyProof = (cwd, proofPath) => readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR, cwd, proofPath);
+const readOptionalVerifyProof = (cwd, proofPath) => readOptionalProofFor(PR_VERIFY_PROOF_DESCRIPTOR$1, cwd, proofPath);
 const followUpSummaryLine = (outcome) => {
 	if (outcome.status === "succeeded") return `Follow-up succeeded: ${outcome.action.command} — ${outcome.reason}.`;
 	if (outcome.status === "skipped") return `Follow-up skipped (${outcome.action.command}): ${outcome.reason}.`;
@@ -16211,6 +16872,67 @@ function createProductionImpactCommand(output) {
 	}));
 }
 //#endregion
+//#region src/pr-status-hud-command.ts
+const shaSchema = z.string().regex(/^[0-9a-f]{40}$/u);
+const boundPlanSchema = z.object({
+	headSha: shaSchema,
+	plan: z.unknown()
+});
+function resolvePrStatusHudPlan(args) {
+	if (args.planPath !== void 0) {
+		const boundPlan = boundPlanSchema.parse(JSON.parse(readFileSync(path.resolve(args.cwd, args.planPath), "utf-8")));
+		if (boundPlan.headSha !== args.headSha) throw new Error(`PR status HUD plan targets ${boundPlan.headSha}, expected current head ${args.headSha}.`);
+		return {
+			plan: validatePreviewLifecyclePlan(boundPlan.plan),
+			planHeadSha: boundPlan.headSha
+		};
+	}
+	return {
+		plan: planFactoryPrStatusHud({
+			cwd: args.cwd,
+			headSha: args.headSha
+		}),
+		planHeadSha: args.headSha
+	};
+}
+async function runPrStatusHud(args) {
+	const { plan, planHeadSha } = resolvePrStatusHudPlan(args);
+	return presentFactoryPrStatusHud({
+		headSha: args.headSha,
+		owner: args.owner,
+		plan,
+		planHeadSha,
+		pr: args.pr,
+		repo: args.repo
+	}, {
+		assertCurrentIdentity: (identity) => assertFactoryPrStatusIdentity({
+			...identity,
+			token: args.token
+		}),
+		readSources: (identity) => readFactoryPrStatusSources({
+			...identity,
+			token: args.token
+		}),
+		upsert: (input) => upsertFactoryPrStatusComment(input, { request: (request) => requestFactoryApp(request, { token: args.token }) })
+	});
+}
+function createPrStatusHudCommand(output, action = runPrStatusHud, env = process.env) {
+	return markCwdOptionDefault(new Command("pr:status-hud").description("Present the App-owned PR status HUD from planPreviewLifecycle").requiredOption("--head <sha>", "candidate head commit SHA").requiredOption("--owner <owner>", "GitHub repository owner").requiredOption("--repo <repo>", "GitHub repository name").requiredOption("--pr <number>", "pull request number", positiveInteger$1("--pr")).option("--plan <path>", "optional candidate-bound JSON envelope; when omitted, planPreviewLifecycle is consumed from the checkout").option("--cwd <path>", "repository working directory", collectCwdOption).action(async (options) => {
+		const token = env.FACTORY_GITHUB_APP_TOKEN;
+		if (!token) throw new Error("pr:status-hud requires FACTORY_GITHUB_APP_TOKEN from actions/create-github-app-token; a workflow GITHUB_TOKEN cannot own the Factory App comment.");
+		const result = await action({
+			cwd: resolveCwdOption(options.cwd),
+			headSha: shaSchema.parse(options.head),
+			owner: options.owner,
+			...options.plan === void 0 ? {} : { planPath: options.plan },
+			pr: options.pr,
+			repo: options.repo,
+			token
+		});
+		output.stdout.write(`PR status HUD ${result.action}: ${result.url} (comment ${result.commentId})\n`);
+	}));
+}
+//#endregion
 //#region src/worktree-scratch-files.ts
 var worktree_scratch_files_exports = /* @__PURE__ */ __exportAll({
 	checkWorktreeScratchFiles: () => checkWorktreeScratchFiles,
@@ -16427,60 +17149,6 @@ const assembleReviewPrompt = ({ base, changedFiles, headSha, issueFocus, kind, p
 	};
 };
 //#endregion
-//#region src/preview-lifecycle.ts
-/**
-* The declared preview stacks: impact targets that are ALSO declared required
-* checks — i.e. targets whose proof is produced externally, which is exactly
-* what a preview producer is.
-*
-* Deriving the list from the two existing declarations rather than adding a
-* third is what makes lifecycle and demand unable to disagree: the stacks this
-* plan can withhold are precisely the demands wave 2 can release, so a stack
-* can never be skipped while its proof stays demanded.
-*/
-const previewLifecycleTargets = (profile) => {
-	const demanded = new Set((profile.requiredChecks ?? []).map(({ name }) => name));
-	return (profile.impact?.targets ?? []).map(({ name }) => name).filter((name) => demanded.has(name));
-};
-/**
-* Plan the preview lifecycle for one candidate.
-*
-* Trust is resolved here through the SAME identity gate demand release uses
-* (`trustedImpactStamp`): the proof must have passed and must bind both the
-* candidate's headSha and its patchId. A stale, aborted, absent, or
-* differently-bound proof yields no stamp, and every declared stack is planned
-* for deploy. Total over its INPUTS — no proof, stamp, or profile can make it
-* throw. A malformed CALL is the deliberate exception: omitting
-* `vetoedTargets` is API misuse, not data doubt, and throws.
-*/
-const planPreviewLifecycle = ({ candidate, profile, proof, vetoedTargets }) => {
-	assertVetoedTargets(vetoedTargets, "planPreviewLifecycle");
-	const stamp = trustedImpactStamp({
-		candidate,
-		proof
-	});
-	const vetoed = new Set(vetoedTargets);
-	const targets = previewLifecycleTargets(profile).map((name) => {
-		const decision = impactStampScopeDecision({
-			stamp,
-			surface: "preview-lifecycle",
-			targetName: name
-		});
-		const vetoedHere = decision.scoped && vetoed.has(name);
-		return {
-			basis: vetoedHere ? `veto: a current envelope bound to this candidate records stack "${name}" as FAILING, so the stamp's release is withheld (${decision.reason})` : decision.reason,
-			disposition: decision.scoped && !vetoedHere ? "not-required" : "deploy",
-			name
-		};
-	});
-	return {
-		deploy: targets.filter((target) => target.disposition === "deploy").map((target) => target.name),
-		notRequired: targets.filter((target) => target.disposition === "not-required"),
-		stampTrusted: stamp !== void 0,
-		targets
-	};
-};
-//#endregion
 //#region src/index.ts
 function createProgram(options = {}) {
 	const factoryCliInvocation = options.factoryCliInvocation ? FactoryCliInvocationSchema.parse(options.factoryCliInvocation) : defaultFactoryCliInvocation(import.meta.filename);
@@ -16507,6 +17175,7 @@ function createProgram(options = {}) {
 	program.addCommand(createEpicPublishStructureCommand(output));
 	program.addCommand(createPrReviewCommand(output, options.actions?.prReview));
 	program.addCommand(createPrReadyCommand(output, options.actions?.prReady));
+	program.addCommand(createPrStatusHudCommand(output, options.actions?.prStatusHud));
 	program.addCommand(createPrPublishCommand(output, prPublishAction));
 	program.addCommand(createDemandWaiveCommand(output, options.actions?.demandWaive));
 	return program;
@@ -16531,4 +17200,4 @@ if (isDirectCliExecution()) try {
 	process.exit(1);
 }
 //#endregion
-export { DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, DemandWaiveRefusalError, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, EpicStructureValidationError, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, FactoryCliInvocationSchema, FollowUpActionSchema, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, PrPublishFollowUpError, REVIEW_FOCUS_SECTION, WorkerCheckoutGuardError, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, blockingLadderFindings, boundary_manifest_exports as boundaryManifest, boundary_review_proof_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_exports as commentProvenance, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, impactStampScopeDecision, inferFixedInThreadDispositions, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, openLadderFindings, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_exports as prReadinessEvaluation, external_evidence_exports as prReadinessExternalEvidence, pr_body_renderer_exports as prReadinessPrBodyRenderer, proof_identity_exports as prReadinessProofIdentity, review_proof_exports as prReadinessReviewProof, status_check_rollup_exports as prReadinessStatusChecks, verification_proof_exports as prReadinessVerificationProof, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readPrReadyProof, readPrReviewProof, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_exports as worktreeScratchFiles };
+export { DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, DemandWaiveRefusalError, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, EpicStructureValidationError, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, FactoryCliInvocationSchema, FollowUpActionSchema, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, PrPublishFollowUpError, REVIEW_FOCUS_SECTION, WorkerCheckoutGuardError, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertFactoryPrStatusIdentity, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, blockingLadderFindings, boundary_manifest_exports as boundaryManifest, boundary_review_proof_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_exports as commentProvenance, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, impactStampScopeDecision, inferFixedInThreadDispositions, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, openLadderFindings, planFactoryPrStatusHud, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_exports as prReadinessEvaluation, external_evidence_exports as prReadinessExternalEvidence, pr_body_renderer_exports as prReadinessPrBodyRenderer, proof_identity_exports as prReadinessProofIdentity, review_proof_exports as prReadinessReviewProof, status_check_rollup_exports as prReadinessStatusChecks, verification_proof_exports as prReadinessVerificationProof, presentFactoryPrStatusHud, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readFactoryPrStatusSources, readPrReadyProof, readPrReviewProof, refreshFactoryPrStatusHud, refreshFactoryPrStatusHudSafely, renderFactoryPrStatusHud, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, validatePreviewLifecyclePlan, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_exports as worktreeScratchFiles };