@bensandee/forgejo-cli 0.5.6 → 0.6.1

package/dist/bin.mjs

@@ -6,7 +6,7 @@ import { FatalError, TransientError, UnexpectedError, describeError, redact, red
 import { z } from "zod";
 import { defineCommand, renderUsage, runCommand, runMain } from "citty";
 import { execFileSync, spawn } from "node:child_process";
-//#region ../cli-kit/src/json.ts
+// ../cli-kit/src/json.ts
 function resolveJsonMode(rawArgs) {
 	if (!rawArgs.some(requestsJson)) return false;
 	if (rawArgs.includes("--help") || rawArgs.includes("-h")) return false;
@@ -100,8 +100,7 @@ function classifyThrown(error, verbose) {
 		detail
 	};
 }
-//#endregion
-//#region ../cli-kit/src/env-file.ts
+// ../cli-kit/src/env-file.ts
 const ENV_FILE_VAR = "BST_ENV_FILE";
 function loadEnvFileFromEnv() {
 	const raw = process.env[ENV_FILE_VAR]?.trim();
@@ -158,11 +157,10 @@ function loadEnvFileForBin(rawArgs, bin, io = processIo) {
 		return io.exit(1);
 	}
 }
-//#endregion
-//#region src/version.ts
+// src/version.ts
 const parsed = z.object({ version: z.string() }).safeParse({
 	name: "@bensandee/forgejo-cli",
-	version: "0.5.6",
+	version: "0.6.1",
 	description: "bst-fj: Forgejo API commands without the rest of bst",
 	license: "MIT",
 	repository: {
@@ -203,14 +201,12 @@ const parsed = z.object({ version: z.string() }).safeParse({
 });
 if (!parsed.success) throw new UnexpectedError(`@bensandee/forgejo-cli's package.json has no string version.`);
 const BST_FJ_VERSION = parsed.data.version;
-//#endregion
-//#region src/env-file-preload.ts
+// src/env-file-preload.ts
 const envFileLoad = loadEnvFileForBin(process.argv.slice(2), {
 	name: "bst-fj",
 	version: BST_FJ_VERSION
 });
-//#endregion
-//#region ../cli-kit/src/logger.ts
+// ../cli-kit/src/logger.ts
 const RANK = {
 	error: 0,
 	warn: 1,
@@ -310,8 +306,7 @@ function createLogger(options = {}) {
 	});
 }
 const rootLogger = createLogger();
-//#endregion
-//#region ../cli-kit/src/flags.ts
+// ../cli-kit/src/flags.ts
 const UNIVERSAL_FLAGS = [
 	"--help",
 	"-h",
@@ -643,8 +638,12 @@ function listFlagPresent(rawArgs, flag) {
 	const long = `--${flag}`;
 	return rawArgs.some((token) => token === long || token.startsWith(`${long}=`));
 }
-//#endregion
-//#region ../cli-kit/src/output.ts
+function parseLimitFlag(raw) {
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value < 1) throw new FatalError(`--limit must be a positive integer, got "${raw}"`);
+	return value;
+}
+// ../cli-kit/src/output.ts
 const stdout = (msg) => console.log(msg);
 function initialState() {
 	return {
@@ -707,8 +706,7 @@ function flushJsonOutput() {
 function jsonDocumentWritten() {
 	return state.wrote;
 }
-//#endregion
-//#region ../cli-kit/src/path-probe.ts
+// ../cli-kit/src/path-probe.ts
 function probeCliPath(value) {
 	try {
 		const stat = statSync(value, { throwIfNoEntry: false });
@@ -718,8 +716,7 @@ function probeCliPath(value) {
 		return "missing";
 	}
 }
-//#endregion
-//#region ../cli-kit/src/run.ts
+// ../cli-kit/src/run.ts
 function classifyWithHook(error, verbose, hook) {
 	const classified = classifyThrown(error, verbose);
 	const worded = hook?.(error);
@@ -873,8 +870,7 @@ const log = {
 		current.debug(message);
 	}
 };
-//#endregion
-//#region ../forgejo/src/connection.ts
+// ../forgejo/src/connection.ts
 function parseGitUrl(urlStr) {
 	try {
 		const url = new URL(urlStr);
@@ -1001,14 +997,12 @@ function normalizeGitUrl(raw) {
 		return null;
 	}
 }
-//#endregion
-//#region src/describe-forge-error.ts
+// src/describe-forge-error.ts
 function describeForgeError(error) {
 	if (error instanceof RepoTargetEmptyError) return "--repo was given with no repository URL (expected e.g. https://host/owner/repo).";
 	if (error instanceof RepoTargetMismatchError) return `--repo disagrees with the issue URL: --repo names ${error.given}, the issue URL names ${error.fromReference}.`;
 }
-//#endregion
-//#region ../forgejo/src/fetch-retry.ts
+// ../forgejo/src/fetch-retry.ts
 const DEFAULT_RETRY_POLICY = {
 	attempts: 5,
 	baseDelayMs: 250,
@@ -1065,28 +1059,29 @@ function fetchWithRetry(fetchImpl, policy = DEFAULT_RETRY_POLICY, defaultTimeout
 function createForgeFetcher(policy = DEFAULT_RETRY_POLICY) {
 	return { fetch: fetchWithRetry((input, init) => globalThis.fetch(input, init), policy) };
 }
-//#endregion
-//#region src/fetcher.ts
+// src/fetcher.ts
 function cliFetcher() {
 	return createForgeFetcher();
 }
-//#endregion
-//#region ../forgejo/src/errors.ts
+// ../forgejo/src/errors.ts
 var ForgeAccessError = class extends FatalError {};
-function authHeaders$2(conn) {
+function authHeaders(conn) {
 	return { Authorization: `token ${conn.token}` };
 }
 function jsonHeaders(conn) {
 	return {
-		...authHeaders$2(conn),
+		...authHeaders(conn),
 		"Content-Type": "application/json"
 	};
 }
 function repoNotFoundMessage(conn) {
 	return `Repository ${conn.repository} not found (or the token cannot see it)`;
 }
+function repoBase(conn) {
+	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
+}
 function issuesBase(conn) {
-	return `${conn.serverUrl}/api/v1/repos/${conn.repository}/issues`;
+	return `${repoBase(conn)}/issues`;
 }
 function issueNotFoundMessage(conn, number) {
 	return `Issue #${String(number)} not found in ${conn.repository}`;
@@ -1165,8 +1160,7 @@ async function throwForgejoFailure(res, operation, notFoundMessage) {
 	if (res.status === 410) throw new FatalError(`${message}\nForgejo returned 410 Gone -- issues are likely disabled on this repository; retrying will not help.`);
 	throw new TransientError(message);
 }
-//#endregion
-//#region ../forgejo/src/commit-status.ts
+// ../forgejo/src/commit-status.ts
 const CombinedStatusSchema = z.object({
 	state: z.string(),
 	statuses: z.array(z.unknown())
@@ -1286,18 +1280,12 @@ z.object({
 	created: z.string()
 });
 z.array(z.unknown());
-function repoBase$1(conn) {
-	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
-}
-function authHeaders$1(conn) {
-	return { Authorization: `token ${conn.token}` };
-}
 function branchNotFoundMessage(conn, branch) {
 	return `Branch ${branch} not found in ${conn.repository}`;
 }
 async function getBranchHeadSha(executor, conn, branch) {
-	const url = `${repoBase$1(conn)}/branches/${encodeURIComponent(branch)}`;
-	const res = await executor.fetch(url, { headers: authHeaders$1(conn) });
+	const url = `${repoBase(conn)}/branches/${encodeURIComponent(branch)}`;
+	const res = await executor.fetch(url, { headers: authHeaders(conn) });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "read branch",
 		resource: branch
@@ -1307,8 +1295,8 @@ async function getBranchHeadSha(executor, conn, branch) {
 	return parsed.data.commit.id;
 }
 async function branchExists(executor, conn, branch) {
-	const url = `${repoBase$1(conn)}/branches/${encodeURIComponent(branch)}`;
-	const res = await executor.fetch(url, { headers: authHeaders$1(conn) });
+	const url = `${repoBase(conn)}/branches/${encodeURIComponent(branch)}`;
+	const res = await executor.fetch(url, { headers: authHeaders(conn) });
 	if (res.status === 404) return false;
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "check branch",
@@ -1316,8 +1304,7 @@ async function branchExists(executor, conn, branch) {
 	}, branchNotFoundMessage(conn, branch));
 	return true;
 }
-//#endregion
-//#region ../cli-kit/src/git.ts
+// ../cli-kit/src/git.ts
 const BRANCH_REF_PREFIX = "refs/heads/";
 const ORIGIN_READ_TIMEOUT_MS = 5e3;
 function defaultGitRunner(args, cwd, options) {
@@ -1380,8 +1367,7 @@ function readPackageRepositoryUrl(cwd) {
 	if (!repo) return null;
 	return typeof repo === "string" ? repo : repo.url;
 }
-//#endregion
-//#region src/connection.ts
+// src/connection.ts
 function resolveRepoUrl(cwd) {
 	return resolveRepoUrlFrom(() => readOriginUrl(cwd), () => readPackageRepositoryUrl(cwd));
 }
@@ -1403,8 +1389,7 @@ function requireForgejoTarget(cwd, target, githubRefusal, env = process.env) {
 	if (conn === null) throw new FatalError(githubRefusal);
 	return conn;
 }
-//#endregion
-//#region ../forgejo/src/check-poll.ts
+// ../forgejo/src/check-poll.ts
 function classifyBaseStatus(checks) {
 	if (!checks.parsed) return "unparseable";
 	if (checks.contexts.length === 0) return "no-status";
@@ -1441,17 +1426,67 @@ async function readPollChecks(fetcher, conn, sha) {
 		return { failureDetail: describeError(error) };
 	}
 }
-//#endregion
-//#region src/poll-timings.ts
-const DEFAULT_TIMEOUT_MS = 12e5;
-const DEFAULT_INTERVAL_MS = 15e3;
-const MIN_INTERVAL_MS = 5e3;
+async function settleChecks(fetcher, conn, poll, round) {
+	const { timeoutMs, intervalMs, sleep, now } = poll;
+	const startedAt = now();
+	const elapsed = () => now() - startedAt;
+	let consecutiveFailures = 0;
+	let lastFailureDetail;
+	let lastGoodChecks;
+	let previousSettledContexts = null;
+	for (;;) {
+		const sha = round.sha();
+		const { checks, failureDetail } = await readPollChecks(fetcher, conn, sha);
+		if (failureDetail !== void 0) lastFailureDetail = failureDetail;
+		if (checks === void 0) {
+			consecutiveFailures += 1;
+			if (consecutiveFailures >= 3) return round.report(EMPTY_CHECKS, {
+				exit: "retry-budget",
+				elapsed,
+				failureDetail: lastFailureDetail
+			});
+		} else {
+			consecutiveFailures = 0;
+			lastGoodChecks = checks;
+			pushDisagreementNotice(round.notices, sha, checks);
+			if (isSettled(checks)) {
+				const contexts = new Set(checks.contexts.map((check) => check.context));
+				if (previousSettledContexts !== null && previousSettledContexts.size === contexts.size && [...previousSettledContexts].every((context) => contexts.has(context))) return round.report(checks, {
+					exit: "settled",
+					elapsed
+				});
+				previousSettledContexts = contexts;
+			} else previousSettledContexts = null;
+		}
+		if (elapsed() >= timeoutMs) return round.report(lastGoodChecks ?? EMPTY_CHECKS, {
+			exit: "timeout",
+			elapsed
+		});
+		await sleep(intervalMs);
+		if (round.afterSleep !== void 0) {
+			const after = await round.afterSleep(sha, elapsed);
+			if (after !== "retry" && after !== "next") return after.done;
+		}
+	}
+}
+function renderCheckLine(check) {
+	const parts = [check.state, check.context];
+	if (check.description !== null) parts.push(check.description);
+	let line = parts.join(" -- ");
+	if (check.verdict === "red" && check.targetUrl !== null) line += ` (${check.targetUrl})`;
+	return line;
+}
+// ../cli-kit/src/env-override.ts
 function envMsOverride(raw, productionMs) {
 	if (raw === void 0) return productionMs;
 	const parsed = Number(raw.trim());
 	if (!Number.isSafeInteger(parsed) || parsed <= 0) return productionMs;
 	return Math.min(parsed, productionMs);
 }
+// src/poll-timings.ts
+const DEFAULT_TIMEOUT_MS = 12e5;
+const DEFAULT_INTERVAL_MS = 15e3;
+const MIN_INTERVAL_MS = 5e3;
 function resolvePollTimings(options) {
 	const timeoutMs = options.timeout !== void 0 ? parseDuration(options.timeout, "--timeout") : DEFAULT_TIMEOUT_MS;
 	const requestedIntervalMs = options.interval !== void 0 ? parseDuration(options.interval, "--interval") : DEFAULT_INTERVAL_MS;
@@ -1460,15 +1495,13 @@ function resolvePollTimings(options) {
 		intervalMs: envMsOverride(process.env["BST_TEST_CHECK_POLL_INTERVAL_MS"], Math.max(requestedIntervalMs, MIN_INTERVAL_MS))
 	};
 }
-//#endregion
-//#region src/sleep.ts
+// src/sleep.ts
 function sleep(ms) {
 	return new Promise((resolve) => {
 		setTimeout(resolve, ms);
 	});
 }
-//#endregion
-//#region src/commit-status.ts
+// src/commit-status.ts
 async function resolveCommitStatusTarget(fetcher, options) {
 	const targetRepo = parseRepoTarget(options.repo);
 	const conn = requireForgejoTarget(options.cwd, targetRepo, "commit:status is Forgejo-only: GitHub Actions publishes check runs, not commit statuses. Use `gh run list` / `gh run view` instead.");
@@ -1528,47 +1561,23 @@ function buildReport$1(target, checks, ctx, extras = {}) {
 	return report;
 }
 async function waitForSettledChecks$1(fetcher, target, notices, poll) {
-	const { timeoutMs, intervalMs, sleep, now } = poll;
-	const startedAt = now();
-	let consecutiveFailures = 0;
-	let lastFailureDetail;
-	let lastGoodChecks;
-	let previousSettledContexts = null;
-	for (;;) {
-		const sha = target.sha;
-		const { checks, failureDetail } = await readPollChecks(fetcher, target.conn, sha);
-		if (failureDetail !== void 0) lastFailureDetail = failureDetail;
-		if (checks === void 0) {
-			consecutiveFailures += 1;
-			if (consecutiveFailures >= 3) return buildReport$1(target, EMPTY_CHECKS, {
+	return settleChecks(fetcher, target.conn, poll, {
+		sha: () => target.sha,
+		notices,
+		report: (checks, extras) => {
+			const extrasForReport = {};
+			if (extras.exit === "timeout") extrasForReport.statusOverride = "timeout";
+			else if (extras.exit === "retry-budget") {
+				extrasForReport.statusOverride = "unparseable";
+				if (extras.failureDetail !== void 0) extrasForReport.detailOverride = extras.failureDetail;
+			}
+			return buildReport$1(target, checks, {
 				notices,
 				waited: true,
-				elapsedMs: now() - startedAt
-			}, {
-				statusOverride: "unparseable",
-				detailOverride: lastFailureDetail
-			});
-		} else {
-			consecutiveFailures = 0;
-			lastGoodChecks = checks;
-			pushDisagreementNotice(notices, sha, checks);
-			if (isSettled(checks)) {
-				const contexts = new Set(checks.contexts.map((check) => check.context));
-				if (previousSettledContexts !== null && previousSettledContexts.size === contexts.size && [...previousSettledContexts].every((context) => contexts.has(context))) return buildReport$1(target, checks, {
-					notices,
-					waited: true,
-					elapsedMs: now() - startedAt
-				});
-				previousSettledContexts = contexts;
-			} else previousSettledContexts = null;
+				elapsedMs: extras.elapsed()
+			}, extrasForReport);
 		}
-		if (now() - startedAt >= timeoutMs) return buildReport$1(target, lastGoodChecks ?? EMPTY_CHECKS, {
-			notices,
-			waited: true,
-			elapsedMs: now() - startedAt
-		}, { statusOverride: "timeout" });
-		await sleep(intervalMs);
-	}
+	});
 }
 async function runCommitStatus(fetcher, options) {
 	const timings = options.wait === true ? resolvePollTimings(options) : void 0;
@@ -1588,13 +1597,7 @@ async function runCommitStatus(fetcher, options) {
 	});
 }
 function renderCommitStatus(report) {
-	const lines = report.checks.map((check) => {
-		const parts = [check.state, check.context];
-		if (check.description !== null) parts.push(check.description);
-		let line = parts.join(" -- ");
-		if (check.verdict === "red" && check.targetUrl !== null) line += ` (${check.targetUrl})`;
-		return line;
-	});
+	const lines = report.checks.map(renderCheckLine);
 	const shortSha = FULL_SHA.test(report.sha) ? report.sha.slice(0, 12) : report.sha;
 	const redCount = report.checks.filter((c) => c.verdict === "red").length;
 	const pendingCount = report.checks.filter((c) => c.verdict === "pending").length;
@@ -1608,8 +1611,7 @@ function renderCommitStatus(report) {
 	lines.push(summaryParts.join(" -- "));
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/commit-status.ts
+// src/commands/commit-status.ts
 const commitStatusCommand = defineCommand({
 	meta: {
 		name: "commit:status",
@@ -1663,8 +1665,7 @@ const commitStatusCommand = defineCommand({
 		process.exitCode = report.status === "green" ? 0 : 1;
 	}
 });
-//#endregion
-//#region ../forgejo/src/fetcher.ts
+// ../forgejo/src/fetcher.ts
 const LONG_FETCH_TIMEOUT_MS = 6e5;
 function morePagesFollow(res, pageLength, received, pageSize) {
 	if (pageLength === 0) return false;
@@ -1673,8 +1674,7 @@ function morePagesFollow(res, pageLength, received, pageSize) {
 	if (!Number.isSafeInteger(total) || total < 0) return pageLength >= pageSize;
 	return received < total;
 }
-//#endregion
-//#region ../forgejo/src/label-provisioning.ts
+// ../forgejo/src/label-provisioning.ts
 const LabelSchema = z.object({
 	id: z.number(),
 	name: z.string(),
@@ -1688,7 +1688,7 @@ const LABELS_MAX_PAGES = 20;
 async function fetchAllForgejoLabels(executor, conn) {
 	const labels = [];
 	for (let page = 1; page <= LABELS_MAX_PAGES; page++) {
-		const res = await executor.fetch(`${conn.serverUrl}/api/v1/repos/${conn.repository}/labels?limit=${String(LABELS_PAGE_SIZE)}&page=${String(page)}`, { headers: authHeaders$2(conn) });
+		const res = await executor.fetch(`${conn.serverUrl}/api/v1/repos/${conn.repository}/labels?limit=${String(LABELS_PAGE_SIZE)}&page=${String(page)}`, { headers: authHeaders(conn) });
 		if (!res.ok) await throwForgejoFailure(res, {
 			verb: "list labels",
 			resource: conn.repository
@@ -1712,6 +1712,17 @@ async function resolveLabelIds(executor, conn, names) {
 		return match.id;
 	});
 }
+function isRetiringExpired(spec, today) {
+	return today > spec.until;
+}
+function retiringAsLabelSpec(spec) {
+	return {
+		name: spec.name,
+		color: spec.color,
+		description: spec.description,
+		exclusive: false
+	};
+}
 const LabelSpecSchema = z.strictObject({
 	name: z.string().min(1),
 	color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
@@ -1761,13 +1772,14 @@ function labelScope(name) {
 	const slash = name.indexOf("/");
 	return slash === -1 ? null : name.slice(0, slash + 1);
 }
-function staleLabelNames(specs, live) {
+function staleLabelNames(specs, live, retiring = []) {
 	const owned = /* @__PURE__ */ new Set();
 	for (const spec of specs) {
 		const scope = labelScope(spec.name);
 		if (scope !== null) owned.add(scope);
 	}
 	const wanted = new Set(specs.map((spec) => spec.name));
+	for (const spec of retiring) wanted.add(spec.name);
 	const stale = [];
 	for (const name of live) {
 		if (wanted.has(name)) continue;
@@ -1828,15 +1840,14 @@ async function ensureForgejoLabels(executor, conn, specs) {
 async function deleteForgejoLabel(executor, conn, id) {
 	const res = await executor.fetch(`${conn.serverUrl}/api/v1/repos/${conn.repository}/labels/${String(id)}`, {
 		method: "DELETE",
-		headers: authHeaders$2(conn)
+		headers: authHeaders(conn)
 	}, { idempotent: true });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "delete label",
 		resource: String(id)
 	}, repoNotFoundMessage(conn));
 }
-//#endregion
-//#region ../forgejo/src/issues.ts
+// ../forgejo/src/issues.ts
 const IssueResponseSchema = z.object({
 	number: z.number(),
 	title: z.string(),
@@ -1881,7 +1892,7 @@ function normalizeIssue(raw) {
 	};
 }
 async function getForgejoIssue(executor, conn, number) {
-	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}`, { headers: authHeaders$2(conn) });
+	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}`, { headers: authHeaders(conn) });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "get issue",
 		resource: `#${String(number)}`
@@ -1895,17 +1906,19 @@ const DependencyResponseSchema = z.object({
 });
 z.array(DependencyResponseSchema);
 function issueListParams(type, query) {
-	const params = new URLSearchParams(type === "all" ? {} : { type });
+	const kind = query.type ?? type;
+	const params = new URLSearchParams(kind === "all" ? {} : { type: kind });
 	params.set("state", query.state);
 	params.set("limit", String(query.limit));
 	if (query.label !== void 0) params.set("labels", query.label);
 	if (query.page !== void 0) params.set("page", String(query.page));
 	if (query.since !== void 0) params.set("since", query.since);
 	if (query.sort !== void 0) params.set("sort", query.sort);
+	if (query.q !== void 0) params.set("q", query.q);
 	return params;
 }
 async function fetchIssueListPage(executor, conn, params) {
-	const res = await executor.fetch(`${issuesBase(conn)}?${params.toString()}`, { headers: authHeaders$2(conn) });
+	const res = await executor.fetch(`${issuesBase(conn)}?${params.toString()}`, { headers: authHeaders(conn) });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "list issues",
 		resource: conn.repository
@@ -1939,6 +1952,29 @@ async function listForgejoIssuesDetailedPaged(executor, conn, query, options) {
 	}
 	return issues;
 }
+async function listOpenObjectsWithLabel(executor, conn, label) {
+	const objects = [];
+	for (let page = 1; page <= DETAILED_LIST_MAX_PAGES; page++) {
+		const { raw } = await fetchIssueListPage(executor, conn, issueListParams("all", {
+			state: "open",
+			label,
+			limit: DETAILED_LIST_PAGE_SIZE,
+			page
+		}));
+		for (const issue of raw.map(normalizeIssue)) {
+			if (!issue.labels.includes(label)) continue;
+			objects.push({
+				number: issue.number,
+				kind: issue.isPullRequest ? "pull" : "issue",
+				title: issue.title,
+				url: issue.url
+			});
+		}
+		if (raw.length === 0) break;
+		if (page === DETAILED_LIST_MAX_PAGES) log.warn(`Open-object listing on ${conn.repository} hit the ${String(DETAILED_LIST_MAX_PAGES)}-page cap without an empty page; results may be truncated`);
+	}
+	return objects;
+}
 const USER_REPOS_PAGE_SIZE = 50;
 const USER_REPOS_MAX_PAGES = 20;
 const UserRepoSchema = z.object({
@@ -2030,8 +2066,7 @@ async function setForgejoIssueState(executor, conn, number, state) {
 	}, issueNotFoundMessage(conn, number));
 	return normalizeIssue(parseIssueOrThrow(await res.json()));
 }
-//#endregion
-//#region ../forgejo/src/label-sync.ts
+// ../forgejo/src/label-sync.ts
 function resolveSyncMode(check, dryRun) {
 	if (check) return "check";
 	if (dryRun) return "dry-run";
@@ -2059,24 +2094,77 @@ function outcomeFromAudit(conn, specs, audit, lists) {
 		...lists
 	};
 }
+async function checkPruneCandidate(fetcher, conn, name) {
+	let objects;
+	try {
+		objects = await listOpenObjectsWithLabel(fetcher, conn, name);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `could not check open objects: ${describeError(error)}`,
+			objects: []
+		};
+	}
+	if (objects.length === 0) return { ok: true };
+	return {
+		ok: false,
+		reason: `on ${String(objects.length)} open object(s)`,
+		objects
+	};
+}
 async function syncOneRepo(params) {
-	const { fetcher, conn, specs, mode, prune, allowedPruneNames, resolveTargetSpecs } = params;
+	const { fetcher, conn, specs, mode, prune, allowedPruneNames, resolveTargetSpecs, retiring, today } = params;
 	const target = resolveTargetSpecs === void 0 ? {
 		specs,
 		omitted: [],
 		aliasNames: []
 	} : await resolveTargetSpecs(conn, specs);
-	const audit = await auditForgejoLabels(fetcher, conn, target.specs);
-	const stale = staleLabelNames(specs, audit.labelIds.keys()).filter((name) => !target.aliasNames.includes(name));
-	const pruneCandidates = prune ? [...target.omitted, ...stale].filter((name) => audit.labelIds.has(name) && (allowedPruneNames === void 0 || allowedPruneNames.includes(name))) : [];
+	const retiringNames = new Set(retiring.map((spec) => spec.name));
+	const fullAudit = await auditForgejoLabels(fetcher, conn, [...target.specs, ...retiring.map(retiringAsLabelSpec)]);
+	const presentRetiring = retiring.filter((spec) => fullAudit.labelIds.has(spec.name));
+	const audit = {
+		...fullAudit,
+		missing: fullAudit.missing.filter((name) => !retiringNames.has(name))
+	};
+	const stale = staleLabelNames(specs, audit.labelIds.keys(), retiring).filter((name) => !target.aliasNames.includes(name));
+	const expiredRetiring = presentRetiring.filter((spec) => isRetiringExpired(spec, today)).map((spec) => spec.name);
+	const pruneCandidates = prune ? [
+		...target.omitted,
+		...stale,
+		...expiredRetiring
+	].filter((name) => audit.labelIds.has(name) && (allowedPruneNames === void 0 || allowedPruneNames.includes(name))) : [];
+	const pruned = [];
+	const refused = [];
+	for (const name of pruneCandidates) {
+		const verdict = await checkPruneCandidate(fetcher, conn, name);
+		if (verdict.ok) {
+			pruned.push(name);
+			continue;
+		}
+		refused.push({
+			name,
+			reason: verdict.reason,
+			objects: verdict.objects
+		});
+	}
+	const retiringReports = [];
+	for (const spec of presentRetiring) retiringReports.push({
+		name: spec.name,
+		replacement: spec.replacement,
+		until: spec.until,
+		expired: isRetiringExpired(spec, today),
+		openObjects: await listOpenObjectsWithLabel(fetcher, conn, spec.name)
+	});
 	const outcome = outcomeFromAudit(conn, target.specs, audit, {
 		omitted: target.omitted,
-		pruned: pruneCandidates,
-		stale: prune ? stale.filter((name) => !pruneCandidates.includes(name)) : stale
+		pruned,
+		stale: prune ? stale.filter((name) => !pruneCandidates.includes(name)) : stale,
+		retiring: retiringReports,
+		refused
 	});
 	if (mode === "apply") {
-		if (outcome.created.length > 0 || outcome.updated.length > 0) await ensureForgejoLabels(fetcher, conn, target.specs);
-		for (const name of pruneCandidates) {
+		if (outcome.created.length > 0 || outcome.updated.length > 0) await ensureForgejoLabels(fetcher, conn, [...target.specs, ...presentRetiring.map(retiringAsLabelSpec)]);
+		for (const name of pruned) {
 			const id = audit.labelIds.get(name);
 			if (id === void 0) throw new UnexpectedError(`Prune candidate "${name}" had no known id after the audit`);
 			await deleteForgejoLabel(fetcher, conn, id);
@@ -2086,6 +2174,9 @@ async function syncOneRepo(params) {
 }
 async function syncLabelSet(params) {
 	const { fetcher, targets, specs, setName, mode, contained, prune, pruneAllowlist } = params;
+	const retiring = params.retiring ?? [];
+	const today = params.today ?? "";
+	if (retiring.length > 0 && params.today === void 0) throw new UnexpectedError("syncLabelSet was given retiring label specs but no `today` to compare their expiry against: an expired entry is a prune candidate, and a guessed date could delete a name whose retirement window is still open.");
 	const specList = [...specs];
 	const repos = [];
 	const failures = [];
@@ -2098,7 +2189,9 @@ async function syncLabelSet(params) {
 			mode,
 			prune: prune === true,
 			allowedPruneNames,
-			resolveTargetSpecs: params.resolveTargetSpecs
+			resolveTargetSpecs: params.resolveTargetSpecs,
+			retiring,
+			today
 		};
 		if (contained !== true) {
 			repos.push(await syncOneRepo(syncOneRepoParams));
@@ -2131,6 +2224,11 @@ function syncSummaryLines(result) {
 		if (repo.omitted.length > 0) actions.push(`omitted (repo declares its own priority vocabulary): ${repo.omitted.join(", ")}`);
 		if (repo.pruned.length > 0) actions.push(`${verb}prune: ${repo.pruned.join(", ")}`);
 		if (repo.stale.length > 0) actions.push(`stale (present, not in this set): ${repo.stale.join(", ")}`);
+		for (const refusal of repo.refused) {
+			const objects = refusal.objects.map((object) => `#${String(object.number)} (${object.kind}) ${object.title}`).join(", ");
+			actions.push(`refused to prune ${refusal.name}: ${refusal.reason}${objects === "" ? "" : ` (${objects})`}`);
+		}
+		for (const retiring of repo.retiring) actions.push(`retiring ${retiring.name}: replaced by ${retiring.replacement}, prunable after ${retiring.until}${retiring.expired ? " (expired)" : ""}; ${String(retiring.openObjects.length)} open object(s)`);
 		if (actions.length === 0) {
 			repoLines.push(`${repo.repository}: up to date (${String(repo.unchanged.length)} unchanged)`);
 			continue;
@@ -2142,8 +2240,7 @@ function syncSummaryLines(result) {
 		failureLines: result.failures.map((failure) => `${failure.repository}: failed: ${failure.error}`)
 	};
 }
-//#endregion
-//#region src/label-sets-file.ts
+// src/label-sets-file.ts
 function readLabelSet(path, setName) {
 	let raw;
 	try {
@@ -2170,8 +2267,7 @@ function readLabelSet(path, setName) {
 	}
 	return specs;
 }
-//#endregion
-//#region src/labels.ts
+// src/labels.ts
 async function runLabelsList(fetcher, conn) {
 	const labels = await fetchAllForgejoLabels(fetcher, conn);
 	return {
@@ -2205,8 +2301,7 @@ function renderSync(result) {
 	for (const line of repoLines) rootLogger.info(line);
 	for (const line of failureLines) rootLogger.warn(line);
 }
-//#endregion
-//#region src/commands/labels.ts
+// src/commands/labels.ts
 const GITHUB_REFUSAL = "bst-fj labels requires a Forgejo repository";
 const listCommand$1 = defineCommand({
 	meta: {
@@ -2270,7 +2365,7 @@ const syncCommand = defineCommand({
 		},
 		json: {
 			type: "boolean",
-			description: "Emit one JSON document: set, mode (apply | check | dry-run), repos ([{repository, created, updated, unchanged, omitted, stale}], every field but repository a list of label names), failures ([{repository, error}]; always present, filled only under --fleet), drifted. drifted is true when any label is missing or drifted, and sets the exit code only under --check."
+			description: "Emit one JSON document: set, mode (apply | check | dry-run), repos ([{repository, created, updated, unchanged, omitted, stale, retiring, refused}], every field but repository and those two a list of label names; retiring and refused are always empty here, since this command never prunes), failures ([{repository, error}]; always present, filled only under --fleet), drifted. drifted is true when any label is missing or drifted, and sets the exit code only under --check."
 		}
 	},
 	async run({ args, rawArgs }) {
@@ -2313,8 +2408,7 @@ const labelsCommand = defineCommand({
 		sync: syncCommand
 	}
 });
-//#endregion
-//#region ../forgejo/src/releases.ts
+// ../forgejo/src/releases.ts
 const SETTLE_ATTEMPTS = 4;
 const SETTLE_BASE_DELAY_MS = 2e3;
 const SETTLE_MAX_DELAY_MS = 16e3;
@@ -2536,8 +2630,7 @@ z.looseObject({
 		created: z.string().nullish()
 	})
 });
-//#endregion
-//#region src/commands/release-create.ts
+// src/commands/release-create.ts
 const releaseCreateCommand = defineCommand({
 	meta: {
 		name: "release:create",
@@ -2586,8 +2679,7 @@ const releaseCreateCommand = defineCommand({
 		else rootLogger.info(`Created Forgejo release for ${args.tag}`);
 	}
 });
-//#endregion
-//#region ../forgejo/src/secrets.ts
+// ../forgejo/src/secrets.ts
 const ActionSecretListSchema = z.array(z.object({ name: z.string() }));
 const SECRETS_PAGE_SIZE = 50;
 const SECRETS_MAX_PAGES = 20;
@@ -2643,8 +2735,7 @@ async function deleteActionSecret(executor, conn, secretName) {
 		resource: secretName
 	}));
 }
-//#endregion
-//#region src/secrets.ts
+// src/secrets.ts
 async function runSecretsSet(fetcher, config) {
 	if (!isValidSecretName(config.secretName)) throw new FatalError(`Invalid secret name "${config.secretName}". A name must match [A-Za-z_][A-Za-z0-9_]* and must not start with FORGEJO_, GITEA_, GITHUB_, or a digit.`);
 	if (config.dryRun) {
@@ -2686,8 +2777,7 @@ async function runSecretsDelete(fetcher, config) {
 		repository: config.conn.repository
 	};
 }
-//#endregion
-//#region src/commands/secrets.ts
+// src/commands/secrets.ts
 function readSecretValue(body) {
 	if (body) return body;
 	try {
@@ -2816,15 +2906,14 @@ const secretsCommand = defineCommand({
 		delete: deleteCommand
 	}
 });
-//#endregion
-//#region ../forgejo/src/user.ts
+// ../forgejo/src/user.ts
 const AuthenticatedUserSchema = z.object({
 	login: z.string(),
 	email: z.string().nullish()
 });
 async function getAuthenticatedUser(executor, conn, signal = null) {
 	const res = await executor.fetch(`${conn.serverUrl}/api/v1/user`, {
-		headers: authHeaders$2(conn),
+		headers: authHeaders(conn),
 		signal
 	});
 	if (!res.ok) return {
@@ -2840,8 +2929,7 @@ async function getAuthenticatedUser(executor, conn, signal = null) {
 		email: parsed.data.email || null
 	};
 }
-//#endregion
-//#region ../forgejo/src/webhooks.ts
+// ../forgejo/src/webhooks.ts
 const WebhookSchema = z.object({
 	id: z.number(),
 	type: z.string(),
@@ -2922,8 +3010,7 @@ async function searchRepos(executor, conn) {
 		return parsed.data.data;
 	})).map((r) => r.full_name);
 }
-//#endregion
-//#region src/commands/webhooks.ts
+// src/commands/webhooks.ts
 function collectGroup(label, scopeHint, status) {
 	if (status.status === "ok") return status.hooks.length > 0 ? {
 		label,
@@ -2999,8 +3086,7 @@ const webhooksCommand = defineCommand({
 		renderText(inventory, conn.serverUrl);
 	}
 });
-//#endregion
-//#region ../forgejo/src/actions.ts
+// ../forgejo/src/actions.ts
 function forgeTimestamp(value) {
 	if (value === null || value === void 0 || value === "") return null;
 	const ms = Date.parse(value);
@@ -3178,8 +3264,7 @@ async function dispatchWorkflow(executor, conn, options) {
 		inputs: options.inputs
 	};
 }
-//#endregion
-//#region ../forgejo/src/actions-log.ts
+// ../forgejo/src/actions-log.ts
 const CSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]/gu;
 const OSC_SEQUENCE = /\u001b\][^\u0007]*(?:\u0007|\u001b\\)/gu;
 const LONE_ESCAPE = /\u001b/gu;
@@ -3221,8 +3306,7 @@ function readActionsJobLog(text) {
 		lines
 	};
 }
-//#endregion
-//#region src/ci-log.ts
+// src/ci-log.ts
 const ACTIONS_RUN_URL = /\/actions\/runs\/(\d+)\/?(?:[?#]|$)/u;
 function parseCiLogTarget(target) {
 	if (/^\d+$/.test(target)) return {
@@ -3313,8 +3397,7 @@ function renderCiLog(result) {
 	for (const line of result.lines) lines.push(line.at === null ? line.text : `${line.at} ${line.text}`);
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/ci-log.ts
+// src/commands/ci-log.ts
 const ciLogCommand = defineCommand({
 	meta: {
 		name: "ci:log",
@@ -3368,13 +3451,7 @@ const ciLogCommand = defineCommand({
 		out.text(renderCiLog(result));
 	}
 });
-//#endregion
-//#region src/ci-runs.ts
-function parseLimit$2(raw) {
-	const limit = Number(raw);
-	if (!Number.isInteger(limit) || limit < 1) throw new FatalError(`Invalid --limit "${raw}" (expected a positive integer).`);
-	return limit;
-}
+// src/ci-runs.ts
 function resolveRunsRef(ref, pr) {
 	if (ref !== void 0 && pr !== void 0) throw new FatalError("--ref and --pr are the same filter -- give one of them (--pr 273 for a pull request's own runs, --ref main for a branch's).");
 	if (pr !== void 0) {
@@ -3399,7 +3476,7 @@ function resolveRunsRef(ref, pr) {
 	};
 }
 async function runCiRuns(fetcher, options) {
-	const limit = parseLimit$2(options.limit);
+	const limit = parseLimitFlag(options.limit);
 	const resolved = resolveRunsRef(options.ref, options.pr);
 	const conn = requireForgejoTarget(options.cwd, resolveIssueTarget(resolved.target, options.repo), "ci:runs is Forgejo-only -- gh run list already serves GitHub, first-class. Use that instead.");
 	rootLogger.debug(`ci:runs repository=${conn.repository} limit=${String(limit)}`);
@@ -3450,8 +3527,7 @@ function renderCiRuns(result) {
 	}
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/ci-runs.ts
+// src/commands/ci-runs.ts
 const ciRunsCommand = defineCommand({
 	meta: {
 		name: "ci:runs",
@@ -3516,8 +3592,7 @@ const ciRunsCommand = defineCommand({
 		out.text(renderCiRuns(result));
 	}
 });
-//#endregion
-//#region ../cli-kit/src/workflow-inputs.ts
+// ../cli-kit/src/workflow-inputs.ts
 const INPUT_FLAG = "--input";
 const INPUT_FLAG_EQ = "--input=";
 function collectInputArgs(rawArgs) {
@@ -3544,8 +3619,7 @@ function parseInputs(raw) {
 	}
 	return inputs;
 }
-//#endregion
-//#region src/workflow-dispatch.ts
+// src/workflow-dispatch.ts
 async function runWorkflowDispatch(fetcher, options) {
 	const dispatched = await dispatchWorkflow(fetcher, requireForgejoTarget(options.cwd, void 0, "workflow:dispatch is Forgejo-only -- use gh workflow run on GitHub."), {
 		...options.repo === void 0 ? {} : { repository: options.repo },
@@ -3562,8 +3636,7 @@ async function runWorkflowDispatch(fetcher, options) {
 		inputs: dispatched.inputs
 	};
 }
-//#endregion
-//#region src/registry-actions.ts
+// src/registry-actions.ts
 const actionsSubCommands = {
 	"ci:log": ciLogCommand,
 	"ci:runs": ciRunsCommand,
@@ -3632,8 +3705,7 @@ const DirEntrySchema = z.looseObject({
 	type: z.string()
 });
 z.array(DirEntrySchema);
-//#endregion
-//#region ../forgejo/src/branches.ts
+// ../forgejo/src/branches.ts
 const BranchEntrySchema = z.object({
 	name: z.string(),
 	protected: z.boolean().optional(),
@@ -3644,12 +3716,6 @@ const BranchEntrySchema = z.object({
 });
 const BRANCHES_PAGE_SIZE = 50;
 const DEFAULT_MAX_PAGES = 20;
-function repoBase(conn) {
-	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
-}
-function authHeaders(conn) {
-	return { Authorization: `token ${conn.token}` };
-}
 async function listBranches(executor, conn, options = {}) {
 	const signal = options.signal;
 	const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
@@ -3718,8 +3784,7 @@ async function deleteBranch(executor, conn, branch) {
 		resource: `${conn.repository}/${branch}`
 	});
 }
-//#endregion
-//#region src/branch.ts
+// src/branch.ts
 const REFUSAL_WORDS = {
 	forbidden: "forbidden",
 	locked: "locked",
@@ -3745,8 +3810,7 @@ function renderBranchList(listing) {
 	if (listing.truncated) lines.push("Listing truncated at the page cap; more branches exist.");
 	return lines.join("\n");
 }
-//#endregion
-//#region src/registry-branch.ts
+// src/registry-branch.ts
 const branchSubCommands = {
 	"branch:delete": defineCommand({
 		meta: {
@@ -3816,8 +3880,7 @@ const branchSubCommands = {
 		}
 	})
 };
-//#endregion
-//#region ../cli-kit/src/body-source.ts
+// ../cli-kit/src/body-source.ts
 function tryRead(read, label) {
 	try {
 		return read();
@@ -3837,8 +3900,7 @@ function readBodySource(body, bodyFile, options = {}) {
 	if (!existsSync(bodyFile)) throw new FatalError(`${flags.file} not found: ${bodyFile}`);
 	return tryRead(() => readFileSync(bodyFile, "utf-8"), `${flags.file} "${bodyFile}"`);
 }
-//#endregion
-//#region ../forgejo/src/issue-comments.ts
+// ../forgejo/src/issue-comments.ts
 const CommentResponseSchema = z.object({
 	id: z.number(),
 	body: z.string().nullish(),
@@ -3879,7 +3941,7 @@ async function listForgejoComments(executor, conn, number, options = {}) {
 			limit: String(COMMENTS_PAGE_SIZE),
 			page: String(page)
 		});
-		const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/comments?${params.toString()}`, { headers: authHeaders$2(conn) });
+		const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/comments?${params.toString()}`, { headers: authHeaders(conn) });
 		if (!res.ok) await throwForgejoFailure(res, {
 			verb: "list comments",
 			resource: `#${String(number)}`
@@ -3912,8 +3974,7 @@ async function addForgejoComment(executor, conn, number, body) {
 	}, issueNotFoundMessage(conn, number));
 	return normalizeComment(parseCommentOrThrow(await res.json()));
 }
-//#endregion
-//#region ../forgejo/src/pr-title.ts
+// ../forgejo/src/pr-title.ts
 const WIP_PREFIXES = ["WIP:", "[WIP]"];
 function hasWipPrefix(title) {
 	return matchedWipPrefix(title) !== void 0;
@@ -3927,8 +3988,7 @@ function stripWipPrefix(title) {
 	if (prefix === void 0) return title;
 	return title.slice(prefix.length).trimStart();
 }
-//#endregion
-//#region ../forgejo/src/pr.ts
+// ../forgejo/src/pr.ts
 const CreatedPrSchema = z.object({
 	number: z.number(),
 	html_url: z.string().optional()
@@ -3979,9 +4039,12 @@ function updatedBefore(since) {
 	return (pr) => pr.updatedAt !== null && Date.parse(pr.updatedAt) < since;
 }
 async function listPulls(executor, conn, options = {}) {
+	const startPage = options.startPage ?? 1;
+	if (!Number.isInteger(startPage) || startPage < 1) throw new FatalError(`Cannot list PRs on ${conn.repository}: startPage must be an integer of at least 1, got ${String(startPage)}`);
+	const lastPage = startPage + PULLS_MAX_PAGES - 1;
 	const headers = { Authorization: `token ${conn.token}` };
 	const pulls = [];
-	for (let page = 1; page <= PULLS_MAX_PAGES; page++) {
+	for (let page = startPage; page <= lastPage; page++) {
 		options.signal?.throwIfAborted();
 		const params = new URLSearchParams({
 			state: options.state ?? "all",
@@ -4021,9 +4084,9 @@ async function listPulls(executor, conn, options = {}) {
 		if (options.stopWhen !== void 0 && items.some(options.stopWhen)) break;
 		if (options.updatedSince !== void 0 && items.some(updatedBefore(options.updatedSince))) break;
 		if (options.limit !== void 0 && pulls.length >= options.limit) break;
-		if (page === PULLS_MAX_PAGES) {
+		if (page === lastPage) {
 			log.warn(`PR listing on ${conn.repository} hit the ${String(PULLS_MAX_PAGES)}-page cap without an empty page; results may be truncated`);
-			options.onPageCap?.();
+			options.onPageCap?.(lastPage);
 		}
 	}
 	return pulls;
@@ -4195,8 +4258,7 @@ const PullReviewCommentSchema = z.object({
 	user: z.object({ login: z.string() }).nullish()
 });
 z.array(PullReviewCommentSchema);
-//#endregion
-//#region ../forgejo/src/issue-api.ts
+// ../forgejo/src/issue-api.ts
 var IssueNumberRequiredError = class extends FatalError {
 	constructor() {
 		super("An issue number or issue URL is required.");
@@ -4223,8 +4285,7 @@ function forgejoIssueApi(fetcher, conn) {
 		pullRequest: (number) => getForgejoPrDetail(fetcher, conn, number)
 	};
 }
-//#endregion
-//#region ../forgejo/src/issue-messages.ts
+// ../forgejo/src/issue-messages.ts
 const ISSUE_LIST_JSON_HELP = "Emit one JSON document: issues ([{number, title, state, url, author, labels, createdAt, updatedAt, closedAt (null while open), isPullRequest, assignees, attachments ([{id, name, size, createdAt, downloadUrl}])}]), truncated.";
 const ISSUE_CREATE_JSON_HELP = "Emit one JSON document: number, url, assignees. A dry run reports number 0 and an empty url.";
 const ISSUE_STATE_JSON_HELP = "Emit one JSON document: number, url, action (close | reopen), state ({previous, current}), changed, comment? ({posted}; present only when a comment was given).";
@@ -4255,8 +4316,7 @@ function describeNoLabelsGiven(error, clearFlag) {
 function describeAttachmentExists(error, forceFlag) {
 	return `"${error.filePath}" already exists -- pass ${forceFlag} to overwrite it.`;
 }
-//#endregion
-//#region ../forgejo/src/issue-run.ts
+// ../forgejo/src/issue-run.ts
 var NothingToUpdateError = class extends FatalError {
 	constructor() {
 		super("Nothing to change: neither a title nor a body was given.");
@@ -4362,7 +4422,7 @@ function parseState$1(state) {
 	if (state === "open" || state === "closed" || state === "all") return state;
 	throw new InvalidListQueryError("state", state);
 }
-function parseLimit$1(raw) {
+function parseLimit(raw) {
 	const limit = Number(raw);
 	if (!Number.isInteger(limit) || limit <= 0) throw new InvalidListQueryError("limit", raw);
 	return limit;
@@ -4375,7 +4435,7 @@ async function listIssues(resolve, request) {
 	const label = normalizeLabel(request.label);
 	const query = {
 		state: parseState$1(request.state),
-		limit: parseLimit$1(request.limit),
+		limit: parseLimit(request.limit),
 		...label === void 0 ? {} : { label }
 	};
 	const { api } = resolve(parseRepoTarget(request.repo));
@@ -4512,8 +4572,7 @@ function formatIssueList(result) {
 	}
 	return lines.join("\n");
 }
-//#endregion
-//#region src/issue-transport.ts
+// src/issue-transport.ts
 function githubRefusal(command) {
 	return `bst-fj is Forgejo-only -- use \`gh\` or \`pnpm exec bst ${command}\` for a github.com repository.`;
 }
@@ -4536,8 +4595,7 @@ function forgejoIssueTransport(cwd, target, command) {
 		target: resolved.target
 	};
 }
-//#endregion
-//#region src/commands/issue-comment.ts
+// src/commands/issue-comment.ts
 const issueCommentCommand = defineCommand({
 	meta: {
 		name: "issue:comment",
@@ -4595,8 +4653,7 @@ const issueCommentCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region src/commands/issue-create.ts
+// src/commands/issue-create.ts
 const issueCreateCommand = defineCommand({
 	meta: {
 		name: "issue:create",
@@ -4669,8 +4726,7 @@ const issueCreateCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region ../forgejo/src/issue-run-download.ts
+// ../forgejo/src/issue-run-download.ts
 function isReadableFile(filePath) {
 	try {
 		readFileSync(filePath);
@@ -4763,8 +4819,7 @@ function formatDownload(result, dryRun) {
 	for (const file of result.files) lines.push(`  ${file.name}  (${String(file.size)} bytes)`);
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/issue-download.ts
+// src/commands/issue-download.ts
 const issueDownloadCommand = defineCommand({
 	meta: {
 		name: "issue:download",
@@ -4823,8 +4878,7 @@ const issueDownloadCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region ../forgejo/src/issue-labels.ts
+// ../forgejo/src/issue-labels.ts
 const TimelineEntrySchema = z.object({
 	id: z.number(),
 	type: z.string(),
@@ -4857,7 +4911,7 @@ async function removeForgejoIssueLabel(executor, conn, number, name, labelIds) {
 	const id = await resolveLabelId(executor, conn, name, labelIds);
 	const res = await executor.fetch(`${issuesBase(conn)}/${String(number)}/labels/${String(id)}`, {
 		method: "DELETE",
-		headers: authHeaders$2(conn)
+		headers: authHeaders(conn)
 	}, { idempotent: true });
 	if (!res.ok) await throwForgejoFailure(res, {
 		verb: "remove label",
@@ -4875,8 +4929,7 @@ async function replaceForgejoIssueLabels(executor, conn, number, labelIds) {
 		resource: `#${String(number)}`
 	}, issueNotFoundMessage(conn, number));
 }
-//#endregion
-//#region ../forgejo/src/issue-run-labels.ts
+// ../forgejo/src/issue-run-labels.ts
 async function labelIssue(resolve, request) {
 	const ref = parseIssueRef(request.ref);
 	const number = requireIssueNumber(ref);
@@ -4945,8 +4998,7 @@ function formatIssueSetLabels(result, dryRun) {
 	if (result.added.length > 0) lines.push(`  ${dryRun ? "would add" : "added"}: ${result.added.join(", ")}`);
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/issue-label.ts
+// src/commands/issue-label.ts
 function defineIssueLabelCommand(action) {
 	const name = action === "add" ? "issue:label" : "issue:unlabel";
 	return defineCommand({
@@ -5005,8 +5057,7 @@ function defineIssueLabelCommand(action) {
 }
 const issueLabelCommand = defineIssueLabelCommand("add");
 const issueUnlabelCommand = defineIssueLabelCommand("remove");
-//#endregion
-//#region src/commands/issue-set-labels.ts
+// src/commands/issue-set-labels.ts
 const issueSetLabelsCommand = defineCommand({
 	meta: {
 		name: "issue:set-labels",
@@ -5066,8 +5117,7 @@ const issueSetLabelsCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region ../forgejo/src/issue-run-state.ts
+// ../forgejo/src/issue-run-state.ts
 var EmptyCommentError = class extends FatalError {
 	constructor() {
 		super("The comment resolved to empty text.");
@@ -5163,8 +5213,7 @@ function formatIssueState(result, dryRun) {
 	}
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/issue-state.ts
+// src/commands/issue-state.ts
 function defineIssueStateCommand(action) {
 	const name = action === "close" ? "issue:close" : "issue:reopen";
 	return defineCommand({
@@ -5240,8 +5289,7 @@ function defineIssueStateCommand(action) {
 }
 const issueCloseCommand = defineIssueStateCommand("close");
 const issueReopenCommand = defineIssueStateCommand("reopen");
-//#endregion
-//#region src/commands/issue-list.ts
+// src/commands/issue-list.ts
 const issueListCommand = defineCommand({
 	meta: {
 		name: "issue:list",
@@ -5299,8 +5347,7 @@ const issueListCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region src/commands/issue-update.ts
+// src/commands/issue-update.ts
 const issueUpdateCommand = defineCommand({
 	meta: {
 		name: "issue:update",
@@ -5371,8 +5418,7 @@ const issueUpdateCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region src/registry-issue.ts
+// src/registry-issue.ts
 const issueSubCommands = {
 	"issue:view": defineCommand({
 		meta: {
@@ -5425,8 +5471,7 @@ const issueSubCommands = {
 	"issue:set-labels": issueSetLabelsCommand,
 	"issue:download": issueDownloadCommand
 };
-//#endregion
-//#region src/pr-checks.ts
+// src/pr-checks.ts
 async function resolvePrChecksTarget(fetcher, options) {
 	const ref = parseIssueRef(options.pr);
 	if (options.repo !== void 0 && ref.number === void 0 && options.branch === void 0) throw new FatalError("--repo requires --pr or --branch -- the current branch of this checkout means nothing in another repository, and inferring it there would silently answer about the wrong PR.");
@@ -5521,75 +5566,45 @@ function buildReport(detail, checks, ctx, extras = {}) {
 	return report;
 }
 async function waitForSettledChecks(fetcher, target, baseline, notices, poll) {
-	const { timeoutMs, intervalMs, sleep, now } = poll;
-	const startedAt = now();
 	let currentDetail = target.detail;
-	let consecutiveFailures = 0;
 	let consecutiveDetailFailures = 0;
-	let lastFailureDetail;
-	let lastGoodChecks;
-	let previousSettledContexts = null;
-	for (;;) {
-		const sha = currentDetail.head.sha;
-		const { checks, failureDetail } = await readPollChecks(fetcher, target.conn, sha);
-		if (failureDetail !== void 0) lastFailureDetail = failureDetail;
-		if (checks === void 0) {
-			consecutiveFailures += 1;
-			if (consecutiveFailures >= 3) return buildReport(currentDetail, EMPTY_CHECKS, {
-				target,
-				baseline,
-				notices,
-				waited: true,
-				elapsedMs: now() - startedAt
-			}, {
-				statusOverride: "unparseable",
-				detailOverride: lastFailureDetail
-			});
-		} else {
-			consecutiveFailures = 0;
-			lastGoodChecks = checks;
-			pushDisagreementNotice(notices, sha, checks);
-			if (isSettled(checks)) {
-				const contexts = new Set(checks.contexts.map((check) => check.context));
-				if (previousSettledContexts !== null && previousSettledContexts.size === contexts.size && [...previousSettledContexts].every((context) => contexts.has(context))) return buildReport(currentDetail, checks, {
-					target,
-					baseline,
-					notices,
-					waited: true,
-					elapsedMs: now() - startedAt
-				});
-				previousSettledContexts = contexts;
-			} else previousSettledContexts = null;
-		}
-		if (now() - startedAt >= timeoutMs) return buildReport(currentDetail, lastGoodChecks ?? EMPTY_CHECKS, {
-			target,
-			baseline,
-			notices,
-			waited: true,
-			elapsedMs: now() - startedAt
-		}, { statusOverride: "timeout" });
-		await sleep(intervalMs);
-		let nextDetail;
-		try {
-			nextDetail = await getForgejoPrDetail(fetcher, target.conn, target.prNumber);
-			consecutiveDetailFailures = 0;
-		} catch (error) {
-			consecutiveDetailFailures += 1;
-			if (consecutiveDetailFailures >= 3) throw error;
-			continue;
+	const reportFor = (detail, checks, elapsedMs, extras = {}) => buildReport(detail, checks, {
+		target,
+		baseline,
+		notices,
+		waited: true,
+		elapsedMs
+	}, extras);
+	return settleChecks(fetcher, target.conn, poll, {
+		sha: () => currentDetail.head.sha,
+		notices,
+		report: (checks, extras) => {
+			const reportExtras = {};
+			if (extras.exit === "timeout") reportExtras.statusOverride = "timeout";
+			else if (extras.exit === "retry-budget") {
+				reportExtras.statusOverride = "unparseable";
+				if (extras.failureDetail !== void 0) reportExtras.detailOverride = extras.failureDetail;
+			}
+			return reportFor(currentDetail, checks, extras.elapsed(), reportExtras);
+		},
+		afterSleep: async (sha, elapsed) => {
+			let nextDetail;
+			try {
+				nextDetail = await getForgejoPrDetail(fetcher, target.conn, target.prNumber);
+				consecutiveDetailFailures = 0;
+			} catch (error) {
+				consecutiveDetailFailures += 1;
+				if (consecutiveDetailFailures >= 3) throw error;
+				return "retry";
+			}
+			if (nextDetail.head.sha !== sha) return { done: reportFor(nextDetail, EMPTY_CHECKS, elapsed(), {
+				statusOverride: "head-moved",
+				previousHeadSha: sha
+			}) };
+			currentDetail = nextDetail;
+			return "next";
 		}
-		if (nextDetail.head.sha !== sha) return buildReport(nextDetail, EMPTY_CHECKS, {
-			target,
-			baseline,
-			notices,
-			waited: true,
-			elapsedMs: now() - startedAt
-		}, {
-			statusOverride: "head-moved",
-			previousHeadSha: sha
-		});
-		currentDetail = nextDetail;
-	}
+	});
 }
 async function runPrChecks(fetcher, options) {
 	const timings = options.wait === true ? resolvePollTimings(options) : void 0;
@@ -5622,13 +5637,7 @@ function baselineClause(report) {
 	return `${String(redChecks.length)} red, ${String(preexistingCount)} of them already red on ` + report.baseline.ref;
 }
 function renderPrChecks(report) {
-	const lines = report.checks.map((check) => {
-		const parts = [check.state, check.context];
-		if (check.description !== null) parts.push(check.description);
-		let line = parts.join(" -- ");
-		if (check.verdict === "red" && check.targetUrl !== null) line += ` (${check.targetUrl})`;
-		return line;
-	});
+	const lines = report.checks.map((check) => renderCheckLine(check));
 	const summaryParts = [`head ${report.headSha.slice(0, 12)}: ${report.status}`];
 	const clause = baselineClause(report);
 	if (clause !== null) summaryParts.push(clause);
@@ -5636,8 +5645,7 @@ function renderPrChecks(report) {
 	lines.push(summaryParts.join(" -- "));
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/pr-checks.ts
+// src/commands/pr-checks.ts
 const prChecksCommand = defineCommand({
 	meta: {
 		name: "pr:checks",
@@ -5701,8 +5709,7 @@ const prChecksCommand = defineCommand({
 		process.exitCode = report.status === "green" ? 0 : 1;
 	}
 });
-//#endregion
-//#region ../forgejo/src/pr-close.ts
+// ../forgejo/src/pr-close.ts
 async function closePullRequest(api, request) {
 	rejectEmptyComment(request.comment);
 	return changeState(api, request.number, {
@@ -5719,15 +5726,13 @@ function formatPrClose(result, dryRun) {
 	return lines.join("\n");
 }
 const PR_CLOSE_JSON_HELP = "Emit one JSON document: number, url, action (close), state ({previous, current}), changed, merged? (present only when the pull request was already closed), comment? ({posted}; present only when a comment was given).";
-//#endregion
-//#region ../forgejo/src/pr-number.ts
+// ../forgejo/src/pr-number.ts
 function parsePrNumber(raw) {
 	const value = Number(raw);
 	if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1) throw new FatalError(`Invalid pull request number "${raw}" (expected a positive integer).`);
 	return value;
 }
-//#endregion
-//#region src/commands/pr-close.ts
+// src/commands/pr-close.ts
 const prCloseCommand = defineCommand({
 	meta: {
 		name: "pr:close",
@@ -5791,8 +5796,7 @@ const prCloseCommand = defineCommand({
 		}
 	}
 });
-//#endregion
-//#region ../forgejo/src/closing-refs.ts
+// ../forgejo/src/closing-refs.ts
 const CLOSING_REF = /(?:^|[\s([])(clos(?:e|es|ed)|fix(?:es|ed)?|resolv(?:e|es|ed))(?::[ \t]*|[ \t]+)((?:[\w.-]+\/[\w.-]+)?#\d+)(?![\w-])/gim;
 function capitalize(word) {
 	return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
@@ -5822,8 +5826,7 @@ function carryForwardClosingRefs(source, target) {
 	const refLines = missing.map((ref) => ref.text).join("\n");
 	return target.trim() === "" ? refLines : `${target}\n\n${refLines}`;
 }
-//#endregion
-//#region ../forgejo/src/git.ts
+// ../forgejo/src/git.ts
 const GIT_LOCAL_TIMEOUT_MS = 6e4;
 const GIT_WRITE_TIMEOUT_MS = 3e5;
 function pickDefaultBranch(override, originHead) {
@@ -5934,8 +5937,7 @@ async function pushBranch(git, cwd, branch, env, forceWithLease = false) {
 	});
 	if (result.exitCode !== 0) throw new FatalError(`Failed to push ${branch}: ${result.stderr || result.stdout}`);
 }
-//#endregion
-//#region ../forgejo/src/pr-upsert.ts
+// ../forgejo/src/pr-upsert.ts
 const COMMIT_TYPES = /* @__PURE__ */ new Set([
 	"feat",
 	"fix",
@@ -6143,8 +6145,7 @@ async function runPrUpsert(git, host, options) {
 		...shape
 	};
 }
-//#endregion
-//#region ../forgejo/src/pr-upsert-messages.ts
+// ../forgejo/src/pr-upsert-messages.ts
 function describePrModeError(error, commands) {
 	if (error.reason === "already-open") {
 		const createVerb = commands.create.split(" ").at(-1) ?? commands.create;
@@ -6223,8 +6224,7 @@ function formatPrUpdate(result, rewrites, flags) {
 		body: null
 	};
 }
-//#endregion
-//#region ../forgejo/src/pr-host.ts
+// ../forgejo/src/pr-host.ts
 function forgejoPrHost(fetcher, conn) {
 	return {
 		wipTitles: true,
@@ -6257,8 +6257,7 @@ function forgejoPrEditHost(fetcher, conn) {
 		ready: (number, write) => updatePr(fetcher, conn, number, { title: write.title })
 	};
 }
-//#endregion
-//#region src/git.ts
+// src/git.ts
 const TIMED_OUT_EXIT_CODE = 124;
 const ABORTED_EXIT_CODE = 143;
 function cliGit() {
@@ -6334,8 +6333,7 @@ function cliGit() {
 		});
 	}) };
 }
-//#endregion
-//#region src/pr-run.ts
+// src/pr-run.ts
 const COMMANDS = {
 	create: "pnpm exec bst-fj pr:create",
 	update: "pnpm exec bst-fj pr:update"
@@ -6369,8 +6367,7 @@ async function runForgejoPr(githubRefusal, options) {
 		});
 	}
 }
-//#endregion
-//#region src/commands/pr-create.ts
+// src/commands/pr-create.ts
 const prCreateCommand = defineCommand({
 	meta: {
 		name: "pr:create",
@@ -6439,8 +6436,7 @@ const prCreateCommand = defineCommand({
 		if (summary.body !== null) out.text(`${summary.body.heading}\n${summary.body.text}`);
 	}
 });
-//#endregion
-//#region ../forgejo/src/pr-files.ts
+// ../forgejo/src/pr-files.ts
 const DEFAULT_LIMIT = 100;
 const PrFileEntrySchema = z.object({
 	filename: z.string(),
@@ -6485,8 +6481,7 @@ async function readPrFilesPage(executor, conn, prNumber, page, limit) {
 		truncated: res.headers.get("x-hasmore") === "true"
 	};
 }
-//#endregion
-//#region src/pr-files.ts
+// src/pr-files.ts
 function runPrFiles(fetcher, options) {
 	const number = parsePrNumber(options.number);
 	return listAllPrFiles(fetcher, requireForgejoTarget(options.cwd, parseRepoTarget(options.repo), "pr:files is Forgejo-only -- gh pr diff --name-only already serves GitHub."), number);
@@ -6497,8 +6492,7 @@ function renderPrFiles(listing) {
 	if (listing.truncated) lines.push("Listing truncated; the pull request changes more files.");
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/pr-files.ts
+// src/commands/pr-files.ts
 const prFilesCommand = defineCommand({
 	meta: {
 		name: "pr:files",
@@ -6537,20 +6531,14 @@ const prFilesCommand = defineCommand({
 		out.text(renderPrFiles(listing));
 	}
 });
-//#endregion
-//#region src/pr-list.ts
+// src/pr-list.ts
 function parseState(state) {
 	if (state === "open" || state === "closed" || state === "all") return state;
 	throw new FatalError(`Invalid --state "${state}" (expected open, closed, or all).`);
 }
-function parseLimit(raw) {
-	const limit = Number(raw);
-	if (!Number.isInteger(limit) || limit < 1) throw new FatalError(`Invalid --limit "${raw}" (expected a positive integer).`);
-	return limit;
-}
 async function runPrList(fetcher, options) {
 	const state = parseState(options.state);
-	const limit = parseLimit(options.limit);
+	const limit = parseLimitFlag(options.limit);
 	rootLogger.debug(`pr:list state=${state} limit=${String(limit)}`);
 	const conn = requireForgejoTarget(options.cwd, parseRepoTarget(options.repo), "pr:list is Forgejo-only -- gh pr list already serves GitHub, first-class. Use that instead.");
 	const notices = [];
@@ -6580,8 +6568,7 @@ function renderPrList(result) {
 		return `#${String(pr.number)} ${statusLabel(pr)} ${branches}: ${pr.title ?? "(no title)"}${labels}${url}`;
 	}).join("\n");
 }
-//#endregion
-//#region src/commands/pr-list.ts
+// src/commands/pr-list.ts
 const prListCommand = defineCommand({
 	meta: {
 		name: "pr:list",
@@ -6624,8 +6611,7 @@ const prListCommand = defineCommand({
 		out.text(renderPrList(result));
 	}
 });
-//#endregion
-//#region ../forgejo/src/pr-merge.ts
+// ../forgejo/src/pr-merge.ts
 async function mergePr(executor, conn, prNumber, options) {
 	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/pulls/${String(prNumber)}/merge`;
 	const body = {
@@ -6728,8 +6714,7 @@ z.object({
 		sha: z.string()
 	})
 });
-//#endregion
-//#region ../forgejo/src/pr-merge-run.ts
+// ../forgejo/src/pr-merge-run.ts
 const MERGE_METHODS = [
 	"merge",
 	"rebase",
@@ -6800,8 +6785,7 @@ async function runPrMergeCore(fetcher, conn, number, options = {}) {
 		}
 	};
 }
-//#endregion
-//#region src/pr-merge.ts
+// src/pr-merge.ts
 function parseMethod(raw) {
 	if (raw === void 0) return "merge";
 	const method = MERGE_METHODS.find((candidate) => candidate === raw);
@@ -6828,8 +6812,7 @@ function renderPrMerge(result) {
 	const what = `PR #${String(result.number)} (${result.method}) at ${result.headSha.slice(0, 12)}, checks ${result.checks}`;
 	return result.merged ? `Merged ${what}.` : `Dry run: would merge ${what}.`;
 }
-//#endregion
-//#region src/commands/pr-merge.ts
+// src/commands/pr-merge.ts
 const prMergeCommand = defineCommand({
 	meta: {
 		name: "pr:merge",
@@ -6885,8 +6868,7 @@ const prMergeCommand = defineCommand({
 		out.text(renderPrMerge(result));
 	}
 });
-//#endregion
-//#region ../forgejo/src/pr-edit.ts
+// ../forgejo/src/pr-edit.ts
 const MERGEABLE_RECHECK_DELAY_MS = 2e3;
 function isOpen(live) {
 	return live.state === "open" && live.merged === false;
@@ -7013,8 +6995,7 @@ function renderPrReady(result) {
 	if (result.action === "would-ready") return `Dry run: pull request ${number} would stop being a draft, reading "${result.title}".`;
 	return `Dry run: pull request ${number} would read "${result.title}".`;
 }
-//#endregion
-//#region src/registry-pr.ts
+// src/registry-pr.ts
 const prSubCommands = {
 	"pr:checks": prChecksCommand,
 	"pr:close": prCloseCommand,
@@ -7179,8 +7160,7 @@ const prSubCommands = {
 		}
 	})
 };
-//#endregion
-//#region src/registry.ts
+// src/registry.ts
 const bstFjSubCommands = {
 	"commit:status": commitStatusCommand,
 	labels: labelsCommand,
@@ -7192,8 +7172,7 @@ const bstFjSubCommands = {
 	webhooks: webhooksCommand,
 	...issueSubCommands
 };
-//#endregion
-//#region src/bin.ts
+// src/bin.ts
 applyVerbosityFromArgs(process.argv.slice(2));
 rootLogger.debug(describeEnvFileLoad(envFileLoad));
 setForgejoLogger(rootLogger);
@@ -7205,5 +7184,4 @@ await runCli({
 	subCommands: bstFjSubCommands,
 	describeError: describeForgeError
 });
-//#endregion
 export {};