@patronage/software-factory 1.0.0-alpha.42 → 1.0.0-alpha.44

package/dist/index.d.ts

@@ -239,8 +239,8 @@ declare const boundaryReviewProofBaseSchema: z.ZodObject<{
     mergedSha: z.ZodOptional<z.ZodString>;
     pr: z.ZodNumber;
     state: z.ZodEnum<{
-      open: "open";
       merged: "merged";
+      open: "open";
     }>;
     wave: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>;
@@ -283,8 +283,8 @@ declare const boundaryReviewProofSchema: z.ZodObject<{
     mergedSha: z.ZodOptional<z.ZodString>;
     pr: z.ZodNumber;
     state: z.ZodEnum<{
-      open: "open";
       merged: "merged";
+      open: "open";
     }>;
     wave: z.ZodOptional<z.ZodString>;
   }, z.core.$loose>>;
@@ -1752,8 +1752,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    active: "active";
     stale: "stale";
+    active: "active";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -2040,10 +2040,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        stale: "stale";
         blocked: "blocked";
         "not-required": "not-required";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -2052,10 +2052,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        stale: "stale";
         blocked: "blocked";
         "not-required": "not-required";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -2089,7 +2089,7 @@ type ReadinessStatus = "ready" | "blocked";
 type ManagedReadinessLedger = z.infer<typeof managedReadinessLedgerSchema>;
 declare function validateManagedReadinessLedger(value: unknown): ManagedReadinessLedger;
 declare namespace status_check_rollup_d_exports {
-  export { CheckState, HOSTED_VERIFY_CHECK_NAME, HOSTED_VERIFY_DRAFT_CHECK_NAME, StatusCheckRollup, hostedVerifyCheckState, isDraftHostedVerifyCheck, isExcludedFromAdmissionChecks, isFactoryReadyCheck, isHostedVerifyCheck, isSupersededHostedVerifyCheck, pendingCheckNames, statusCheckState };
+  export { CheckState, HOSTED_VERIFY_CHECK_NAME, HOSTED_VERIFY_DRAFT_CHECK_NAME, StatusCheckRollup, hostedVerifyCheckState, isCancelledPrStatusHudCheck, isDraftHostedVerifyCheck, isExcludedFromAdmissionChecks, isFactoryReadyCheck, isHostedVerifyCheck, isSupersededHostedVerifyCheck, pendingCheckNames, statusCheckState };
 }
 type CheckState = "passed" | "failed" | "pending" | "none" | "unknown";
 interface StatusCheckRollup {
@@ -2150,10 +2150,27 @@ declare const HOSTED_VERIFY_DRAFT_CHECK_NAME = "verify (draft)";
  * `verify` row already answers for, so admission does not judge it.
  */
 declare const isDraftHostedVerifyCheck: (check: StatusCheckRollup) => boolean;
+/**
+ * Is this a cancelled run of the PR status HUD job (#1056)?
+ *
+ * The HUD job keeps one stable name across Verify generations, so a superseded
+ * run and its replacement share a context and `effectiveChecks` keeps only the
+ * newer. But the Verify workflow cancels an in-flight pull-request run when the
+ * next one starts (`ready_for_review` is the next one), and until the
+ * replacement's HUD job appears, the rollup carries only the CANCELLED row. A
+ * readiness read in that window would report a failed required check that
+ * names a job nobody broke.
+ *
+ * The HUD only presents. It verifies nothing and never gates, so its
+ * cancellation says nothing about the candidate. Only a cancellation is
+ * excluded: a HUD run that failed still reads as failed, and every
+ * verification and deploy check keeps its own state.
+ */
+declare const isCancelledPrStatusHudCheck: (check: StatusCheckRollup) => boolean;
 /**
  * The rollup rows an admission read must not judge: the factory's own branded
- * checks (it would be judging itself) and the draft-head summary residue
- * above.
+ * checks (it would be judging itself), the draft-head summary residue above,
+ * and a cancelled PR status HUD run.
  */
 declare const isExcludedFromAdmissionChecks: (check: StatusCheckRollup) => boolean;
 /**
@@ -2512,6 +2529,12 @@ interface CompletedFactoryCheckSnapshot {
    * generation (#1158). Absent when the newest generation stands.
    */
   readonly readPastRunIds?: readonly number[];
+  /**
+   * Merge freeze only (#1503): why readiness refuses to read the freeze at
+   * this tip, when it does. The row then presents that refusal, never the
+   * run's own conclusion.
+   */
+  readonly refusal?: string;
 }
 interface FailedPreviewSnapshot {
   readonly completedAt: string;
@@ -3131,10 +3154,10 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 //#region src/review-proof-applicability.d.ts
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
-  stale: "stale";
   blocked: "blocked";
   "not-required": "not-required";
   current: "current";
+  stale: "stale";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -3242,8 +3265,8 @@ declare const boundaryCheckProofSchema: z.ZodObject<{
     pr: z.ZodNumber;
     sha: z.ZodString;
     state: z.ZodEnum<{
-      open: "open";
       merged: "merged";
+      open: "open";
     }>;
     wave: z.ZodString;
   }, z.core.$strip>>;
@@ -4680,13 +4703,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "stale" | "blocked" | "not-required" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "stale" | "blocked" | "not-required" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4799,13 +4822,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "stale" | "blocked" | "not-required" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "stale" | "blocked" | "not-required" | "current" | "missing";
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;

package/dist/index.js

@@ -5,7 +5,7 @@ import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { EventEmitter, once } from "node:events";
 import * as nodeFs from "node:fs";
 import { accessSync, appendFileSync, closeSync, constants, cpSync, existsSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { FACTORY_APP_BROKER_ORIGIN, FACTORY_APP_BROKER_PATH, FACTORY_CURSOR_OIDC_AUDIENCE, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, previewProofInventory, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
+import { FACTORY_APP_BROKER_ORIGIN, FACTORY_APP_BROKER_PATH, FACTORY_CURSOR_OIDC_AUDIENCE, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PR_STATUS_HUD_JOB_NAME, GitHubApiError, assertPreviewCleanupStackPolicy, assertPreviewCleanupTargetsAbsent, discoverOrphanedPreviewCleanupTargets, discoverPreviewCleanupTargets, mintInstallationToken, parsePreviewCleanupResidue, parsePreviewCleanupTargets, previewCleanupGithubOutput, previewCleanupResiduePullRequests, previewProofInventory, productionImpactTargetOutput, readPullRequestStates, readVitestProfileDocument, recordPreviewCleanupOutcome } from "@patronage/factory-ci";
 import http from "node:http";
 import { isDeepStrictEqual, promisify } from "node:util";
 import os, { homedir, tmpdir } from "node:os";
@@ -22,7 +22,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { pathToFileURL } from "node:url";
 //#region package.json
 var name = "@patronage/software-factory";
-var version = "1.0.0-alpha.42";
+var version = "1.0.0-alpha.44";
 //#endregion
 //#region src/git-globals-parse.ts
 const VALUE_TAKING_GIT_OPTIONS = new Set([
@@ -9784,6 +9784,15 @@ const verifyProofGenerations = (runs, bound) => {
 *   created no earlier than its verification began, so `started_at` is an
 *   upper bound on that start. Ranking there can only make such a run newer
 *   than it is, so it vetoes more, never less.
+* - A pass with no usable typed proof is trusted only when it is the only run
+*   at this head (`startUnknownBesideAnotherRun`, #1514). Its verification
+*   started at some unknown instant no later than its `started_at`, so
+*   another run posted before that `started_at` may still have been posted
+*   after the pass began: a pass verified before a failure but posted after
+*   it would otherwise outrank the failure. Ranked at its post, such a pass
+*   can only veto more as an older run; as the newest, nothing is trusted
+*   beside any other run. Proofs over the text cap are rare, so refusing
+*   costs one fresh verification.
 * - Neither `endedAt` nor a passing run's `started_at` is its start. Every
 *   writer posts its `pr-verify` run only once verification has finished
 *   (`pr:verify` on success or failure, `pr:publish` on re-post), so both say
@@ -9834,7 +9843,7 @@ const verifyProofGenerations = (runs, bound) => {
 *   reimplement this reader's payload parser. On payloads the factory's
 *   writer emits, both readers select the same pass or both refuse: the
 *   differential suite, `pr-verify-reuse-differential.test.ts`, asserts it
-*   over 9,653 generated run sets. On App-signed text the writer never emits,
+*   over 10,561 generated run sets. On App-signed text the writer never emits,
 *   the two can differ in either direction. The known instances where the
 *   hosted gate reuses and this reader refuses are: (a) a reused run whose
 *   typed proof fails `validatePrVerifyProof`; (b) a newest pass that repeats
@@ -9873,8 +9882,10 @@ const newestVerifyProofGeneration = (runs, bound) => {
 	if (selected.kind !== "newest") return;
 	const newest = selected.generation;
 	const repeatsAnotherRun = !newest.recorded && newest.payload !== void 0 && generations.some((generation) => generation !== newest && sameVerdict(generation, newest));
-	const postedSinceItStarted = isPassingRun(newest.run, newest.payload) && posts.some((post) => post.generation !== newest && post.postedMs >= newest.orderMs);
-	return repeatsAnotherRun || postedSinceItStarted ? void 0 : newest;
+	const passing = isPassingRun(newest.run, newest.payload);
+	const startUnknownBesideAnotherRun = passing && !newest.recorded && posts.some((post) => post.generation !== newest);
+	const postedSinceItStarted = passing && posts.some((post) => post.generation !== newest && post.postedMs >= newest.orderMs);
+	return repeatsAnotherRun || startUnknownBesideAnotherRun || postedSinceItStarted ? void 0 : newest;
 };
 /**
 * Read the machine-readable `pr:verify` binding for one commit (#247).
@@ -17738,6 +17749,7 @@ var status_check_rollup_exports = /* @__PURE__ */ __exportAll({
 	HOSTED_VERIFY_CHECK_NAME: () => HOSTED_VERIFY_CHECK_NAME,
 	HOSTED_VERIFY_DRAFT_CHECK_NAME: () => HOSTED_VERIFY_DRAFT_CHECK_NAME,
 	hostedVerifyCheckState: () => hostedVerifyCheckState,
+	isCancelledPrStatusHudCheck: () => isCancelledPrStatusHudCheck,
 	isDraftHostedVerifyCheck: () => isDraftHostedVerifyCheck,
 	isExcludedFromAdmissionChecks: () => isExcludedFromAdmissionChecks,
 	isFactoryReadyCheck: () => isFactoryReadyCheck,
@@ -17812,11 +17824,28 @@ const HOSTED_VERIFY_DRAFT_CHECK_NAME = `${HOSTED_VERIFY_CHECK_NAME} (draft)`;
 */
 const isDraftHostedVerifyCheck = (check) => check.name === HOSTED_VERIFY_DRAFT_CHECK_NAME && Boolean(check.workflowName);
 /**
+* Is this a cancelled run of the PR status HUD job (#1056)?
+*
+* The HUD job keeps one stable name across Verify generations, so a superseded
+* run and its replacement share a context and `effectiveChecks` keeps only the
+* newer. But the Verify workflow cancels an in-flight pull-request run when the
+* next one starts (`ready_for_review` is the next one), and until the
+* replacement's HUD job appears, the rollup carries only the CANCELLED row. A
+* readiness read in that window would report a failed required check that
+* names a job nobody broke.
+*
+* The HUD only presents. It verifies nothing and never gates, so its
+* cancellation says nothing about the candidate. Only a cancellation is
+* excluded: a HUD run that failed still reads as failed, and every
+* verification and deploy check keeps its own state.
+*/
+const isCancelledPrStatusHudCheck = (check) => check.name === FACTORY_PR_STATUS_HUD_JOB_NAME && Boolean(check.workflowName) && (check.conclusion ?? check.state) === "CANCELLED";
+/**
 * The rollup rows an admission read must not judge: the factory's own branded
-* checks (it would be judging itself) and the draft-head summary residue
-* above.
+* checks (it would be judging itself), the draft-head summary residue above,
+* and a cancelled PR status HUD run.
 */
-const isExcludedFromAdmissionChecks = (check) => isFactoryReadyCheck(check) || isDraftHostedVerifyCheck(check);
+const isExcludedFromAdmissionChecks = (check) => isFactoryReadyCheck(check) || isDraftHostedVerifyCheck(check) || isCancelledPrStatusHudCheck(check);
 /**
 * The hosted `verify` gate's state on this head, read by presence (#477).
 *
@@ -17882,6 +17911,15 @@ const effectiveChecks = (rollup) => {
 	}
 	return currentChecks;
 };
+/**
+* The current generation of each check, less the excluded rows.
+*
+* Generations collapse before the exclusion runs. An exclusion that depends on
+* a run's state, like the cancelled HUD run (#1056), must judge only the
+* newest generation: dropping it first would let an older, superseded run of
+* the same job stand in as current (#1550).
+*/
+const currentIncludedChecks = (rollup, exclude) => effectiveChecks(rollup ?? []).filter((check) => !exclude?.(check));
 const terminalState = (check) => check.conclusion ?? check.state ?? "";
 const progressState = (check) => check.status ?? check.state ?? "";
 /**
@@ -17894,11 +17932,10 @@ const progressState = (check) => check.status ?? check.state ?? "";
 * rather than dropped: a wait must not look settled because one row was
 * unprintable.
 */
-const pendingCheckNames = (rollup, exclude) => effectiveChecks((rollup ?? []).filter((check) => !exclude?.(check))).filter((check) => PENDING_STATES.has(progressState(check))).map((check) => checkContext(check) ?? check.name ?? "unnamed check");
+const pendingCheckNames = (rollup, exclude) => currentIncludedChecks(rollup, exclude).filter((check) => PENDING_STATES.has(progressState(check))).map((check) => checkContext(check) ?? check.name ?? "unnamed check");
 const statusCheckState = (rollup, exclude) => {
-	const included = rollup?.filter((check) => !exclude?.(check));
-	if (!included || included.length === 0) return "none";
-	const currentChecks = effectiveChecks(included);
+	const currentChecks = currentIncludedChecks(rollup, exclude);
+	if (currentChecks.length === 0) return "none";
 	if (currentChecks.every((check) => PASSED_STATES.has(terminalState(check)))) return "passed";
 	if (currentChecks.some((check) => FAILED_STATES.has(terminalState(check)))) return "failed";
 	if (currentChecks.some((check) => PENDING_STATES.has(progressState(check)))) return "pending";
@@ -18092,6 +18129,13 @@ const mergeFreezeCheckRunListItemSchema = z.object({
 		"queued"
 	])
 });
+/**
+* Whether the reader can parse one listed run (#1550). The reader parses every
+* listed run before it selects one, so a single run it cannot parse refuses
+* the whole read, even behind a newer green generation. The PR status HUD
+* applies the same rule through this export rather than a copy of the schema.
+*/
+const isReadableMergeFreezeListedRun = (run) => mergeFreezeCheckRunListItemSchema.safeParse(run).success;
 const completedMergeFreezeCheckRunSchema = mergeFreezeCheckRunListItemSchema.extend({
 	conclusion: z.enum([
 		"failure",
@@ -19601,6 +19645,13 @@ const checkRow = (target, snapshot, renderedAt) => {
 		target,
 		timestamp: utcTimestamp(renderedAt)
 	};
+	if (snapshot.refusal) return {
+		detail: snapshot.refusal,
+		link: safeMarkdownLink("Details", snapshot.detailsUrl),
+		status: "Failed",
+		target: `${target} (${snapshot.refusal})`,
+		timestamp: utcTimestamp(snapshot.completedAt)
+	};
 	return {
 		detail: `Completed snapshot: ${snapshot.conclusion}.`,
 		link: safeMarkdownLink("Details", snapshot.detailsUrl),
@@ -19790,9 +19841,10 @@ const listFactoryCheckRuns = async (input, name, sha, dependencies) => {
 	}
 	throw new Error(`${name} pagination limit was exhausted before GitHub returned a final page.`);
 };
+const writtenByFactoryApp = (run) => String(run.app?.id ?? "") === FACTORY_PROOF_GATE_APP_ID;
 /** The Factory App's generations of one check at one SHA, each orderable. */
 const factoryGenerations = (name, sha, runs) => {
-	const candidates = runs.filter((run) => String(run.app?.id ?? "") === FACTORY_PROOF_GATE_APP_ID && run.head_sha === sha && run.name === name);
+	const candidates = runs.filter((run) => writtenByFactoryApp(run) && 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.`);
 	return candidates;
 };
@@ -19824,25 +19876,52 @@ const MERGE_FREEZE_CHECK = "patronage-factory/merge-freeze";
 * tip (#1158). The newest completed run alone would show that cancellation as
 * a freeze readiness does not apply, so the row names the runs it read past.
 *
+* Where readiness refuses to read the freeze at all, the row says so rather
+* than showing a conclusion readiness never trusts (#1503). A listed run the
+* pinned Factory App did not write refuses the whole read, as it does in the
+* reader (#1393): filtering it out could let an older generation win. So does
+* any listed run the reader cannot parse, such as an older one concluded
+* `cancelled` (#1550). A newest payload the selection cannot parse, or one
+* that contradicts its own check run, is unreadable.
+*
 * Otherwise the row is the newest completed snapshot, as for every other check:
-* running, missing and ambiguous generations present as before, and so does a
-* newest generation the selection cannot settle. Every case where the freeze
-* stays fail-closed keeps the newest generation, so the row stays red. The HUD
-* is advisory and never gates.
+* running, missing and ambiguous generations present as before. Every case
+* where the freeze stays fail-closed keeps the row red. The HUD is advisory and
+* never gates.
 */
 const mergeFreezeSnapshot = (sha, runs) => {
+	const foreign = runs.find((run) => !writtenByFactoryApp(run));
+	const unparseable = runs.find((run) => !isReadableMergeFreezeListedRun(run));
+	const refusing = foreign ?? unparseable;
+	if (refusing) {
+		const at = refusing.completed_at ?? refusing.started_at;
+		if (!at) throw new Error(`${MERGE_FREEZE_CHECK} presentation snapshot has a refused run with no usable timestamp.`);
+		return {
+			completedAt: at,
+			conclusion: refusing.conclusion ?? refusing.status,
+			...refusing.details_url ? { detailsUrl: refusing.details_url } : {},
+			headSha: sha,
+			name: MERGE_FREEZE_CHECK,
+			refusal: foreign ? `refused: run ${String(foreign.id)} was not written by the Factory App` : `refused: run ${String(refusing.id)} cannot be read`
+		};
+	}
 	const generations = factoryGenerations(MERGE_FREEZE_CHECK, sha, runs);
 	const newest = newestSnapshot(MERGE_FREEZE_CHECK, generations);
 	if (!newest) return newest;
+	const unreadable = {
+		...newest,
+		refusal: "unreadable newest payload"
+	};
 	try {
-		const { readPast, run } = selectMergeFreezeRun(generations, sha);
+		const { generation, readPast, run } = selectMergeFreezeRun(generations, sha);
+		if (generation.kind === "unreadable") return unreadable;
 		const selected = run && readPast.length > 0 ? runSnapshot(MERGE_FREEZE_CHECK, run) : void 0;
 		return selected ? {
 			...selected,
 			readPastRunIds: readPast.map((past) => past.id)
 		} : newest;
 	} catch {
-		return newest;
+		return unreadable;
 	}
 };
 const FAILED_PREVIEW_CONCLUSIONS = new Set([
@@ -24807,6 +24886,155 @@ function createPrStatusHudCommand(output, action = runPrStatusHud, env = process
 	}));
 }
 //#endregion
+//#region src/preview-cleanup-command.ts
+const ACTIONS = new Set([
+	"audit",
+	"discover",
+	"record",
+	"sweep"
+]);
+const collect = (value, previous = []) => [...previous, value];
+const parseAction = (value) => {
+	if (!ACTIONS.has(value)) throw new InvalidArgumentError("must be discover, sweep, record, or audit");
+	return value;
+};
+const policyFrom = (options) => {
+	const stackAliases = {};
+	for (const entry of options.stackAlias) {
+		const separator = entry.indexOf("=");
+		if (separator <= 0 || separator === entry.length - 1) throw new Error(`--stack-alias must be <alias>=<stack>, got "${entry}".`);
+		stackAliases[entry.slice(0, separator)] = entry.slice(separator + 1);
+	}
+	return {
+		...options.hostedStagePrefix === void 0 ? {} : { hostedStagePrefix: options.hostedStagePrefix },
+		stackAliases,
+		stacks: options.stack
+	};
+};
+const repositoryFrom = (options, env) => {
+	const [owner, repo, extra] = (options.repository ?? env.GITHUB_REPOSITORY ?? "").split("/");
+	if (!(owner && repo) || extra !== void 0) throw new Error("preview:cleanup requires --repository <owner/repo> or GITHUB_REPOSITORY.");
+	return {
+		owner,
+		repo
+	};
+};
+const requireValue = (name, value) => {
+	if (value === void 0 || value === "") throw new Error(`preview:cleanup requires ${name} for this action.`);
+	return value;
+};
+const requireToken = (env, name) => {
+	const token = env[name]?.trim();
+	if (!token) throw new Error(`preview:cleanup requires ${name} for this action.`);
+	return token;
+};
+const describeTargets = (count, label, deferred = 0) => `${label}: ${count} cleanup target${count === 1 ? "" : "s"}${deferred > 0 ? `, ${deferred} deferred to the next sweep` : ""}\n`;
+const recordOutcome = async (options, policy, deps) => {
+	const { env, readFile } = deps;
+	const outcome = requireValue("--outcome", options.outcome);
+	if (outcome !== "passed" && outcome !== "failed") throw new Error("--outcome must be passed or failed.");
+	const targetStack = requireValue("--target-stack", options.targetStack);
+	assertPreviewCleanupStackPolicy(policy);
+	if (!policy.stacks.includes(targetStack)) throw new Error(`--target-stack "${targetStack}" is not a declared --stack.`);
+	const { owner, repo } = repositoryFrom(options, env);
+	const evidence = readFile(requireValue("--evidence-file", options.evidenceFile)).split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+	const server = env.GITHUB_SERVER_URL?.trim();
+	const runId = env.GITHUB_RUN_ID?.trim();
+	const transport = deps.fetch === void 0 ? {} : { fetch: deps.fetch };
+	const result = await recordPreviewCleanupOutcome({
+		evidence,
+		...options.headSha ? { headSha: options.headSha } : {},
+		outcome,
+		owner,
+		pr: requireValue("--pr", options.pr),
+		repo,
+		...server && runId ? { runUrl: `${server}/${owner}/${repo}/actions/runs/${runId}` } : {},
+		stack: targetStack,
+		stackAliases: policy.stackAliases ?? {},
+		stage: requireValue("--target-stage", options.targetStage)
+	}, {
+		read: {
+			...transport,
+			token: requireToken(env, "GITHUB_TOKEN")
+		},
+		write: {
+			...transport,
+			token: requireToken(env, "FACTORY_GITHUB_APP_TOKEN")
+		}
+	});
+	return `Cleanup ${outcome} for ${targetStack}/${options.targetStage}: ${result.kind}\n`;
+};
+async function runPreviewCleanup(options, deps = {}) {
+	const env = deps.env ?? process.env;
+	const readFile = deps.readFile ?? ((path) => readFileSync(path, "utf-8"));
+	const writeOutput = deps.writeOutput ?? appendFileSync;
+	const policy = policyFrom(options);
+	const readResidue = () => parsePreviewCleanupResidue(JSON.parse(readFile(requireValue("--residue", options.residue))));
+	const publish = (text) => {
+		if (options.githubOutput !== void 0) writeOutput(options.githubOutput, text);
+	};
+	if (options.action === "discover") {
+		const pr = requireValue("--pr", options.pr);
+		const { owner, repo } = repositoryFrom(options, env);
+		const registrations = await (deps.listRegistrations === void 0 ? previewProofInventory.list({
+			owner,
+			pr,
+			repo
+		}, {
+			...deps.fetch === void 0 ? {} : { fetch: deps.fetch },
+			token: requireToken(env, "GITHUB_TOKEN")
+		}) : deps.listRegistrations({
+			owner,
+			pr,
+			repo
+		}));
+		const targets = discoverPreviewCleanupTargets({
+			...policy,
+			pr,
+			registrations,
+			residue: readResidue()
+		});
+		const text = previewCleanupGithubOutput(policy, targets);
+		publish(text);
+		return `${describeTargets(targets.length, `PR #${pr}`)}${text}`;
+	}
+	if (options.action === "sweep") {
+		const { owner, repo } = repositoryFrom(options, env);
+		const residue = readResidue();
+		const pullRequestStates = await readPullRequestStates({
+			owner,
+			prs: previewCleanupResiduePullRequests(policy, residue),
+			repo
+		}, {
+			...deps.fetch === void 0 ? {} : { fetch: deps.fetch },
+			token: requireToken(env, "GITHUB_TOKEN")
+		});
+		const sweep = discoverOrphanedPreviewCleanupTargets({
+			...policy,
+			...options.maxTargets === void 0 ? {} : { maxTargets: options.maxTargets },
+			pullRequestStates,
+			residue
+		});
+		const text = previewCleanupGithubOutput(policy, sweep.targets);
+		publish(text);
+		return `${describeTargets(sweep.targets.length, "Sweep", sweep.deferred)}${text}`;
+	}
+	if (options.action === "record") return recordOutcome(options, policy, {
+		...deps,
+		env,
+		readFile
+	});
+	const targets = parsePreviewCleanupTargets(policy, JSON.parse(requireValue("--targets", options.targets)));
+	assertPreviewCleanupTargetsAbsent(targets, readResidue());
+	return `No residue remains for ${targets.length} cleanup target${targets.length === 1 ? "" : "s"}\n`;
+}
+function createPreviewCleanupCommand(output, deps = {}) {
+	return new Command("preview:cleanup").description("Discover, sweep, record, or audit disposable preview stage cleanup for factory-ci's generated cleanup workflow").requiredOption("--action <action>", "discover (one closed PR), sweep (closed PRs' residue), record, or audit", parseAction).option("--stack <name>", "declared cleanup stack; repeat for each stack", collect, []).option("--stack-alias <alias=stack>", "another name for a declared stack; repeat as needed", collect, []).option("--hosted-stage-prefix <prefix>", "the hosted per-PR stage prefix, such as pr-").option("--repository <owner/repo>", "repository; defaults to GITHUB_REPOSITORY").option("--residue <path>", "residue JSON: an array of stack and stage rows").option("--pr <number>", "pull request number", positiveInteger$1("--pr")).option("--max-targets <count>", "sweep targets per run", positiveInteger$1("--max-targets")).option("--target-stack <stack>", "the destroyed stack, for record").option("--target-stage <stage>", "the destroyed stage, for record").option("--outcome <outcome>", "passed or failed, for record").option("--evidence-file <path>", "evidence lines, for record").option("--head-sha <sha>", "registered head SHA, for record").option("--targets <json>", "the discover job's targets output, for audit").option("--github-output <path>", "append discover or sweep outputs to the Actions output file").action(async (options) => {
+		if (options.stack.length === 0) throw new Error("preview:cleanup requires at least one --stack.");
+		output.stdout.write(await runPreviewCleanup(options, deps));
+	});
+}
+//#endregion
 //#region src/preview-reaper.ts
 const previewBindingReferenceSchema = z.object({
 	binding: z.string().min(1),
@@ -25619,6 +25847,7 @@ function createProgram(options = {}) {
 	program.addCommand(createProductionImpactCommand(output));
 	program.addCommand(createPreviewReceiptCommand(output));
 	program.addCommand(createPreviewReapCommand(output));
+	program.addCommand(createPreviewCleanupCommand(output));
 	program.addCommand(createCandidateImpactCommand(output));
 	program.addCommand(createAffectedCommand(output));
 	program.addCommand(createAppTokenExecCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "1.0.0-alpha.42",
+  "version": "1.0.0-alpha.44",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "picomatch": "^4.0.5",
     "yaml": "^2.9.0",
     "zod": "4.4.3",
-    "@patronage/factory-ci": "1.0.0-alpha.42"
+    "@patronage/factory-ci": "1.0.0-alpha.44"
   },
   "devDependencies": {
     "@types/node": "24.13.3",