@bensandee/forgejo-cli 0.1.0

package/dist/bin.mjs

@@ -0,0 +1,4232 @@
+#!/usr/bin/env node
+import { readFileSync, statSync, writeSync } from "node:fs";
+import * as path$1 from "node:path";
+import path from "node:path";
+import { parseArgs, parseEnv } from "node:util";
+import { FatalError, TransientError, UnexpectedError, describeError, redact, redact as redact$1 } from "@bensandee/common";
+import { z } from "zod";
+import { defineCommand, runCommand, runMain } from "citty";
+import { execFileSync } from "node:child_process";
+//#region ../cli-kit/src/json.ts
+/**
+* Pure logic for the `--json` entry path of a bin (`run.ts`). Kept apart from
+* that I/O-heavy entry point so it stays pure and unit-testable.
+*/
+/** True when `rawArgs` ask for JSON mode: a `--json` token (bare or `--json=<truthy>`), no
+* `--help`/`-h`, and not the bare `--version` query. The `=<value>` form is matched because citty
+* coerces a boolean flag that way (`value !== "false"`), so `--json=true` DOES put the command in
+* json mode; matching only the bare token left that invocation with `createCliOutput` suppressing
+* prose into a buffer tooling's `runBstCli` never flushed -- zero bytes of output for exit code 0.
+* `--json=false` and `--no-json` stay excluded, the way citty parses them. A `--json` that arrives
+* as the *value* of a preceding string flag (e.g. `--body --json`) is scanned the same way and is a
+* known, accepted ambiguity: this is a raw-argument scan, not an arg-aware parse. */
+function resolveJsonMode(rawArgs) {
+	if (!rawArgs.some(requestsJson)) return false;
+	if (rawArgs.includes("--help") || rawArgs.includes("-h")) return false;
+	if (rawArgs.length === 1 && (rawArgs[0] === "--version" || rawArgs[0] === "-v")) return false;
+	return true;
+}
+/** One raw token: whether it asks for json mode, mirroring citty's boolean coercion of a value
+* (anything but the literal `false` is truthy). */
+function requestsJson(token) {
+	if (token === "--json") return true;
+	if (!token.startsWith("--json=")) return false;
+	return token !== "--json=false";
+}
+/** The first token that is not a flag and not a flag's value, mirroring citty's own
+* `findSubCommandIndex` for a command whose own `args` is empty (true of `bst`'s top-level
+* command) -- a `--` sentinel ends the scan with no command found, same as citty. */
+function resolveCommandName(rawArgs) {
+	for (const arg of rawArgs) {
+		if (arg === "--") return void 0;
+		if (!arg.startsWith("-")) return arg;
+	}
+}
+/** Whether `--verbose`/`-v`/`--trace` (flag or the matching env var) was requested -- the gate on
+* whether an error document's `detail` may carry a stack trace. Mirrors `resolveLogLevel`'s
+* flag/env sources at the raw-argument level, since JSON-mode resolution runs before citty has
+* parsed anything, and must keep naming the same tokens tooling's `runBstCli` raises the log level
+* from: a run whose diagnostics are on and whose error document withholds its detail is the same
+* invocation answering the same question two ways. */
+function verboseRequested(rawArgs) {
+	if (process.env["TOOLING_TRACE"] === "true" || process.env["TOOLING_DEBUG"] === "true") return true;
+	return rawArgs.includes("--verbose") || rawArgs.includes("-v") || rawArgs.includes("--trace");
+}
+/** Narrow a subcommand map entry to a plain `CommandDef`, rejecting the function/Promise
+* variants `Resolvable` allows. None of this repo's commands are ever wrapped that way (every
+* one is a direct `defineCommand()` result), so this is a conservative "not resolvable
+* synchronously" rather than a real gap: the JSON path never invokes citty's own async
+* resolution machinery (see `run.ts`, `resolveSubCommand` note). */
+function asCommandDef(value) {
+	if (value === void 0) return void 0;
+	if (typeof value === "function") return void 0;
+	if (value instanceof Promise) return void 0;
+	return value;
+}
+/** Whether a resolved command declares a `json` argument -- what the coverage test reads to
+* decide between "granted --json" and its `EXEMPT` list. */
+function commandDeclaresJson(cmd) {
+	if (cmd === void 0) return false;
+	const argsDef = cmd.args;
+	if (argsDef === void 0) return false;
+	if (typeof argsDef === "function") return false;
+	if (argsDef instanceof Promise) return false;
+	return "json" in argsDef;
+}
+/** Build the structured error document a `--json` failure flushes instead of prose --
+* `{ ok: false, command, version, error: { kind, message, detail? } }`. `notices` is not this
+* function's concern: `flushJsonOutput` folds the buffered notices into whatever document it
+* writes, error or payload alike. */
+function buildErrorDocument(input) {
+	const error = input.detail === void 0 ? {
+		kind: input.kind,
+		message: input.message
+	} : {
+		kind: input.kind,
+		message: input.message,
+		detail: input.detail
+	};
+	return {
+		ok: false,
+		command: input.command,
+		version: input.version,
+		error
+	};
+}
+/**
+* The last-resort net for `--json`: if the process exits without `run.ts`'s flush ever
+* having written a document -- an await that never settles, for instance -- this writes one
+* parseable `{ok: false}` document and marks the exit nonzero, instead of nothing and Node's own
+* unsettled-top-level-await exit code. Distinct from the "completed without recording a JSON
+* payload" net in `run.ts`: that one runs after a command *returns*, so it cannot
+* see a process that never returns at all.
+*
+* On Node's unsettled-top-level-await path specifically, the loader prints its own warning to
+* stderr before any userland `exit` hook runs, so a merged `2>&1` capture still does not parse as
+* JSON alone -- this restores the stdout document and the exit code; it does not restore stderr's
+* cleanliness.
+*/
+function runJsonExitNet(params) {
+	if (params.wroteDocument()) return;
+	const label = params.command ?? params.binName;
+	const document = buildErrorDocument({
+		command: params.command,
+		version: params.version,
+		kind: "runtime",
+		message: `${label} --json exited before the command produced a result: the process ended with the command still outstanding, so no document was recorded.`
+	});
+	try {
+		params.write(JSON.stringify(document) + "\n");
+	} catch (_writeError) {}
+	process.exitCode = 1;
+}
+/** Install {@link runJsonExitNet} as a `process` `"exit"` listener, writing synchronously to fd 1
+* via `node:fs`. */
+function installJsonExitNet(binName, command, version, wroteDocument) {
+	process.on("exit", () => {
+		runJsonExitNet({
+			write: (text) => writeSync(1, text),
+			wroteDocument,
+			command,
+			version,
+			binName
+		});
+	});
+}
+/** Classify a caught `unknown` into the error document's `kind`/`message`/`detail`. citty's
+* `CLIError` (arg-parse failures, an unknown subcommand, no command specified) is not exported
+* by the package, so it is recognised by `name` rather than `instanceof` -- still no typecast,
+* since `error instanceof Error` narrows `unknown` to `Error` first. Everything else, including
+* `FatalError`/`UnexpectedError`, is `"runtime"`. */
+function classifyThrown(error, verbose) {
+	const kind = error instanceof Error && error.name === "CLIError" ? "usage" : "runtime";
+	const message = redact(describeError(error));
+	if (!verbose) return {
+		kind,
+		message
+	};
+	const detail = error instanceof Error && typeof error.stack === "string" ? redact(error.stack) : void 0;
+	return detail === void 0 ? {
+		kind,
+		message
+	} : {
+		kind,
+		message,
+		detail
+	};
+}
+//#endregion
+//#region ../cli-kit/src/env-file.ts
+/**
+* The one way a file feeds this process's environment: `BST_ENV_FILE=<path>` names an env file
+* (`KEY=value` lines, `#` comments, an optional `export` prefix) that a bin loads
+* before anything else runs (each bin passes its own name and version). Unset means no file is touched.
+*
+* Explicit and opt-in rather than "load `.env` if one exists", so a production container, which
+* receives every variable through `docker run -e`, can never pick up a stray file -- nothing sets
+* this variable there. A value that names an unreadable file is fatal instead of a warning, since
+* configuration that fails to resolve should fail where it was written, not later as a missing
+* credential. The environment always wins over the file, the same precedence as Node's own
+* `--env-file`, so a shell export or a `-e` on a container is never overridden.
+*/
+const ENV_FILE_VAR = "BST_ENV_FILE";
+/**
+* Load `$BST_ENV_FILE` into `process.env`, returning what happened, or `undefined` when the
+* variable is unset or blank. Throws {@link FatalError} on a file that cannot be read.
+*/
+function loadEnvFileFromEnv() {
+	const raw = process.env[ENV_FILE_VAR]?.trim();
+	if (raw === void 0 || raw === "") return void 0;
+	const file = path$1.resolve(raw);
+	let content;
+	try {
+		content = readFileSync(file, "utf8");
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new FatalError(`${ENV_FILE_VAR} names ${file}, which could not be read (${reason}). Unset ${ENV_FILE_VAR} or point it at a readable env file.`);
+	}
+	const added = [];
+	const kept = [];
+	for (const [name, value] of Object.entries(parseEnv(content))) if (process.env[name] === void 0) {
+		process.env[name] = value;
+		added.push(name);
+	} else kept.push(name);
+	return {
+		path: file,
+		added,
+		kept
+	};
+}
+/**
+* One diagnostic line about a load -- the path and the variable names, never a value -- or, for
+* `undefined`, the fact that no file was configured. The absent case is reported rather than
+* passed over because "my credential did not load" and "no file was ever named" look identical
+* from outside the process, and that is exactly the question this line is read to answer.
+*/
+function describeEnvFileLoad(load) {
+	if (load === void 0) return `No env file loaded -- ${ENV_FILE_VAR} is unset or empty.`;
+	const parts = [`Loaded ${String(load.added.length)} variable(s) from ${load.path} (${ENV_FILE_VAR}): ` + (load.added.length === 0 ? "none" : load.added.join(", "))];
+	if (load.kept.length > 0) parts.push(`${String(load.kept.length)} already set in the environment kept their value: ` + load.kept.join(", "));
+	return parts.join("; ");
+}
+const processIo = {
+	out: (text) => {
+		process.stdout.write(`${text}\n`);
+	},
+	err: (text) => {
+		process.stderr.write(`${text}\n`);
+	},
+	exit: (code) => process.exit(code)
+};
+/**
+* {@link loadEnvFileFromEnv} for a bin entry point: a failure ends the process with exit code 1
+* instead of propagating as an unhandled rejection with a stack trace. This runs before the CLI
+* exists, so it renders the failure itself -- as the one `{ok: false}` document `--json` promises
+* when `rawArgs` ask for it, else as a single stderr line.
+*/
+function loadEnvFileForBin(rawArgs, bin, io = processIo) {
+	try {
+		return loadEnvFileFromEnv();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (resolveJsonMode(rawArgs)) {
+			const document = buildErrorDocument({
+				command: resolveCommandName(rawArgs),
+				version: bin.version,
+				kind: "usage",
+				message
+			});
+			io.out(JSON.stringify(document));
+		} else io.err(`${bin.name}: ${message}`);
+		return io.exit(1);
+	}
+}
+//#endregion
+//#region src/version.ts
+const parsed = z.object({ version: z.string() }).safeParse({
+	name: "@bensandee/forgejo-cli",
+	version: "0.1.0",
+	description: "bst-fj: Forgejo API commands without the rest of bst",
+	license: "MIT",
+	repository: {
+		"type": "git",
+		"url": "https://codeberg.org/bensandee/tooling.git",
+		"directory": "packages/forgejo-cli"
+	},
+	bin: { "bst-fj": "./bin/bst-fj.mjs" },
+	files: ["bin", "dist"],
+	type: "module",
+	imports: { "#src/*.ts": "./src/*.ts" },
+	exports: {
+		"./package.json": "./package.json",
+		"./*": "./src/*.ts",
+		"./test/*": "./test/*.ts"
+	},
+	publishConfig: {
+		"exports": { "./package.json": "./package.json" },
+		"access": "public",
+		"registry": "https://registry.npmjs.org"
+	},
+	scripts: {
+		"build": "tsdown",
+		"dev": "tsdown --watch",
+		"test": "vitest run"
+	},
+	dependencies: {
+		"@bensandee/common": "0.2.0",
+		"citty": "^0.2.2",
+		"zod": "^4.6.5"
+	},
+	devDependencies: {
+		"@bensandee/cli-kit": "workspace:*",
+		"@bensandee/forgejo": "workspace:*",
+		"@types/node": "24.13.5",
+		"tsdown": "0.23.0"
+	}
+});
+if (!parsed.success) throw new UnexpectedError(`@bensandee/forgejo-cli's package.json has no string version.`);
+/** The package version, stamped on `--version` and on every `--json` error document. */
+const BST_FJ_VERSION = parsed.data.version;
+//#endregion
+//#region src/env-file-preload.ts
+/**
+* The `$BST_ENV_FILE` load as a module side effect, so a bin entry point can run it **before any
+* other module evaluates** simply by importing this module first. That ordering is the whole
+* point: a module that reads the environment at import time would otherwise read an environment
+* the file had not joined yet. A dynamic `import()` cannot guarantee it either: the bundler inlines
+* the target and evaluates it with the rest of the bundle, ahead of the call.
+*
+* Only the bin entry point imports this module. Nothing under test does, so a developer's exported
+* `BST_ENV_FILE` never reaches a vitest worker.
+*/
+const envFileLoad = loadEnvFileForBin(process.argv.slice(2), {
+	name: "bst-fj",
+	version: BST_FJ_VERSION
+});
+//#endregion
+//#region ../cli-kit/src/logger.ts
+const RANK = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	debug: 3,
+	trace: 4
+};
+let moduleLevel = "info";
+/** Set the process-global minimum level (default `info`). Read live by every non-pinned logger. */
+function setLogLevel(level) {
+	moduleLevel = level;
+}
+let moduleTimestamps = false;
+/**
+* Resolve the minimum level from flags + env, cheapest-wins: `--trace`/`TOOLING_TRACE` -> `trace`
+* (the exec/fetch firehose), else `--verbose`/`TOOLING_DEBUG` -> `debug`, else `info`. Trace
+* outranks verbose. Pure; a command passes its parsed flags and feeds the result to
+* {@link setLogLevel}.
+*/
+function resolveLogLevel(flags) {
+	if (flags.trace === true || process.env["TOOLING_TRACE"] === "true") return "trace";
+	if (flags.verbose === true || process.env["TOOLING_DEBUG"] === "true") return "debug";
+	return "info";
+}
+const isCI = Boolean(process.env["CI"]);
+const out = (msg) => console.log(msg);
+const err = (line) => console.error(line);
+/** The plain user-facing adapter -- stdout with level tags, mirroring the pre-unification `log`.
+* The tag is what carries the level once clack's coloured symbol is gone. */
+const plainUserSink = {
+	info: out,
+	warn: (msg) => out(`[warn] ${msg}`),
+	error: (msg) => out(`[error] ${msg}`),
+	success: (msg) => out(`[ok] ${msg}`)
+};
+let plainOutput = isCI;
+let jsonMode = false;
+/** Silence the four user-facing levels process-wide (default off). Diagnostic levels are
+* unaffected -- see the `jsonMode` comment above. */
+function setJsonMode(enabled) {
+	jsonMode = enabled;
+}
+/** Read the json-mode global for the one user-facing sink outside the logger (`note()` in
+* tooling's `utils/log.ts`), which the sink-selection gate below cannot reach. */
+function isJsonMode() {
+	return jsonMode;
+}
+let jsonNoticeSink;
+/** Give a suppressed `warn`/`error` line somewhere to go while `jsonMode` is on. Pass `undefined`
+* to go back to dropping them. */
+function setJsonNoticeSink(sink) {
+	jsonNoticeSink = sink;
+}
+/**
+* Render the tag a text reader sees. Widen the payload freely; widen this only for something a
+* reader needs on the line it is reading -- a multi-repo agent's reader needs the repository,
+* because a bare `#42` names an object in whichever of several repos the cycle happens to be in,
+* and recovering which one meant scrolling back to the claim line.
+*
+* `repo` renders as its trailing segment alone. What discriminates two units is the repo name; the
+* owner costs width on every line and usually repeats, and the claim line still names `owner/repo`
+* in full once per cycle, so a short name that is genuinely ambiguous is one scroll from the whole
+* one.
+*/
+function formatContext(context) {
+	const parts = [];
+	if (context.repo !== void 0) {
+		const segment = context.repo.split("/").findLast((part) => part.length > 0);
+		if (segment !== void 0) parts.push(segment);
+	}
+	if (context.issue !== void 0) parts.push(`#${String(context.issue)}`);
+	if (context.pr !== void 0) parts.push(`PR#${String(context.pr)}`);
+	if (context.phase !== void 0) parts.push(context.phase);
+	return parts.length > 0 ? `[${parts.join(" ")}]` : "";
+}
+function build(config) {
+	const contextTag = formatContext(config.context);
+	const enabled = (level) => RANK[level] <= RANK[config.level ?? moduleLevel];
+	const stamp = () => `[${config.now().toISOString()}]`;
+	const userFacing = (level, threshold) => (msg) => {
+		if (!enabled(threshold)) return;
+		if (jsonMode) {
+			if ((level === "warn" || level === "error") && jsonNoticeSink) jsonNoticeSink(redact$1(msg));
+			return;
+		}
+		const segments = [];
+		if (config.timestamps ?? moduleTimestamps) segments.push(stamp());
+		if (contextTag) segments.push(contextTag);
+		segments.push(redact$1(msg));
+		(config.userSink ?? (plainOutput ? plainUserSink : plainUserSink))[level](segments.join(" "));
+	};
+	const diagnostic = (level) => (msg) => {
+		if (!enabled(level)) return;
+		const segments = [stamp()];
+		if (contextTag) segments.push(contextTag);
+		segments.push(`[${level}]`, redact$1(msg));
+		config.diagnosticSink(segments.join(" "));
+	};
+	return {
+		info: userFacing("info", "info"),
+		warn: userFacing("warn", "warn"),
+		error: userFacing("error", "error"),
+		success: userFacing("success", "info"),
+		debug: diagnostic("debug"),
+		trace: diagnostic("trace"),
+		child: (context) => build({
+			...config,
+			context: {
+				...config.context,
+				...context
+			}
+		})
+	};
+}
+/** Create a {@link Logger}. All seams default to real sinks and the live global level. */
+function createLogger(options = {}) {
+	return build({
+		level: options.level,
+		timestamps: options.timestamps,
+		context: options.context ?? {},
+		userSink: options.userSink,
+		diagnosticSink: options.diagnosticSink ?? err,
+		now: options.now ?? (() => /* @__PURE__ */ new Date())
+	});
+}
+/** The process-wide root logger the shims delegate to. Pins nothing, so it follows both process
+* globals -- which is what makes `setLogTimestamps` reach every module that logs through `log`. */
+const rootLogger = createLogger();
+//#endregion
+//#region ../cli-kit/src/flags.ts
+/**
+* Pure logic over an invocation's flags: whether it carries one its resolved command never
+* declared, whether a `[dir]` positional names a directory (through an injected probe), and how a
+* flag's own value reads.
+* Kept apart from the bins' I/O-heavy entry points so it stays pure and unit-testable.
+* No `process`, `node:fs` or logger import -- see `flags.test.ts`'s "no I/O" assertion.
+*
+* The detection mirrors citty@0.2.2's own parser (`_parser.ts`/`args.ts` in
+* `node_modules/citty/dist/index.mjs`) closely enough that it agrees with what citty would
+* silently accept: the same option table (declared name, declared alias, camelCase/kebab-case
+* pair), the same `--no-<flag>` pre-pass, and the same `node:util` `parseArgs({ strict: false,
+* allowPositionals: true })` call. Anything that call surfaces as a key we did not expect is a
+* flag citty would otherwise absorb without a word -- see `flags-differential.test.ts`, which
+* pins this mirror against the real citty rather than trusting the copy. The mirror is literal,
+* with no exception: a `--no-<x>` token is known exactly when `x` is declared, because that is the
+* key citty's pre-pass writes.
+*/
+/** The carve-out set: citty's own builtins (`--help`/`-h`, `--version`/`-v`) plus the flags every
+* command honours regardless of whether it declares them. Accepted on every command, declared or
+* not -- and each one is honoured somewhere: `--help`/`-h` short-circuit this check wherever they
+* appear (`hasHelpFlag`) and citty renders usage; `--version` and a lone `-v` are citty's version
+* query (`runMain` intercepts it only when it is the whole argv, so `isLoneVersionQuery` mirrors
+* that); `-v` beside anything else is read as `--verbose`, and `--verbose`/`--trace` set the
+* process log level in tooling's `runBstCli`. The one member with no meaning of its own past that
+* is `--version` written beside other arguments, which citty ignores. */
+const UNIVERSAL_FLAGS = [
+	"--help",
+	"-h",
+	"--version",
+	"-v",
+	"--verbose",
+	"--trace"
+];
+/** Derived from {@link UNIVERSAL_FLAGS} rather than restated beside it: two hand-written copies of
+* one set are one edit away from disagreeing, and nothing would catch the half that was missed. */
+const UNIVERSAL_NAMES = new Set(UNIVERSAL_FLAGS.map(flagName));
+function hasHelpFlag(rawArgs) {
+	return rawArgs.includes("--help") || rawArgs.includes("-h");
+}
+function isLoneVersionQuery(rawArgs) {
+	return rawArgs.length === 1 && (rawArgs[0] === "--version" || rawArgs[0] === "-v");
+}
+/** The token citty would read as a command name, mirroring its own `findSubCommandIndex`: every
+* "-"-prefixed token is skipped, and so is the token after one naming a `string`/`enum` arg the
+* command declares, since citty consumes that as the flag's value (`--repo x/y`) before it looks
+* for a name. `argsDef` is omitted for `bst`'s own top-level command, which declares no args of
+* its own, so nothing is consumed there. A `--` sentinel ends the scan with no command found,
+* same as `resolveCommandName` in @bensandee/cli-kit/json. */
+function splitAtCommand(rawArgs, argsDef) {
+	for (let i = 0; i < rawArgs.length; i++) {
+		const token = rawArgs[i];
+		if (token === "--") return void 0;
+		if (token.startsWith("-")) {
+			if (argsDef !== void 0 && !token.includes("=") && declaresValueFlag(token, argsDef)) i++;
+			continue;
+		}
+		return {
+			index: i,
+			before: rawArgs.slice(0, i)
+		};
+	}
+}
+/** citty's `_isValueFlag`: whether `token` names a declared arg whose value is a separate token. */
+function declaresValueFlag(token, argsDef) {
+	const name = flagName(token);
+	const normalized = toCamelCase(name);
+	for (const [key, def] of Object.entries(argsDef)) {
+		if (def.type !== "string" && def.type !== "enum") continue;
+		if (normalized === toCamelCase(key)) return true;
+		const alias = "alias" in def ? def.alias : void 0;
+		if (alias === void 0) continue;
+		if (Array.isArray(alias) ? alias.includes(name) : alias === name) return true;
+	}
+	return false;
+}
+function flagBase(token) {
+	const eq = token.indexOf("=");
+	return eq === -1 ? token : token.slice(0, eq);
+}
+function flagName(token) {
+	return flagBase(token).replace(/^-{1,2}/, "");
+}
+/** Narrow a resolved command's `args` to a plain `ArgsDef`, rejecting the function/Promise
+* variants `Resolvable` allows -- the same conservative narrowing `commandDeclaresJson` applies
+* to a command's `json` argument. No command in this repo defines `args` dynamically. */
+function resolveStaticArgsDef(cmd) {
+	const argsDef = cmd.args;
+	if (argsDef === void 0) return void 0;
+	if (typeof argsDef === "function") return void 0;
+	if (argsDef instanceof Promise) return void 0;
+	return argsDef;
+}
+/** citty's own `camelCase`/`kebabCase` (from the bundled `scule`) are not part of its public
+* exports, so this is a minimal reimplementation over the hyphenated, all-lowercase names this
+* repo's `args` definitions actually use (`body-file`, `dry-run`, ...) -- not a general-purpose
+* case converter. The differential test pins that this is faithful enough for every declared arg
+* in the tree. */
+function toCamelCase(name) {
+	return name.replace(/-([a-z0-9])/g, (_match, ch) => ch.toUpperCase());
+}
+function toKebabCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Build the option table citty's `parseArgs` (`args.ts`) builds from a command's declared
+* `args`: every declared name plus its declared alias(es) and its camelCase/kebab-case pair
+* becomes its own entry in the table `node:util`'s `parseArgs` consults, typed by walking the
+* alias relationship back to whichever side declared `boolean`.
+*
+* One structural difference from citty, which additionally hands a one-character alias to
+* `parseArgs` as the partner entry's `short`: an entry registered under its own single-letter name
+* is matched by `-x` and consumes the next token exactly as a `short` mapping does, so the two
+* tables agree on every name a parse reports as unknown -- they differ only in which of the pair
+* holds the value, which nothing here reads. Pinned by the one-character-alias cases in
+* `flags-differential.test.ts`. */
+function buildParseTable(argsDef) {
+	const booleanNames = /* @__PURE__ */ new Set();
+	const aliasesByMain = /* @__PURE__ */ new Map();
+	const knownNames = new Set(UNIVERSAL_NAMES);
+	const acceptedFlags = [];
+	for (const [name, def] of Object.entries(argsDef)) {
+		if (def.type === "positional") continue;
+		if (def.type === "boolean") booleanNames.add(name);
+		const declaredAlias = "alias" in def ? def.alias : void 0;
+		let declaredAliases;
+		if (declaredAlias === void 0) declaredAliases = [];
+		else if (Array.isArray(declaredAlias)) declaredAliases = declaredAlias;
+		else declaredAliases = [declaredAlias];
+		const aliases = [...declaredAliases];
+		const camel = toCamelCase(name);
+		const kebab = toKebabCase(name);
+		if (camel !== name && !aliases.includes(camel)) aliases.push(camel);
+		if (kebab !== name && !aliases.includes(kebab)) aliases.push(kebab);
+		aliasesByMain.set(name, aliases);
+		knownNames.add(name);
+		for (const alias of aliases) knownNames.add(alias);
+		acceptedFlags.push(`--${name}`);
+	}
+	function typeFor(name) {
+		if (booleanNames.has(name)) return "boolean";
+		for (const [main, aliases] of aliasesByMain) if ((main === name || aliases.includes(name)) && booleanNames.has(main)) return "boolean";
+		return "string";
+	}
+	const nodeOptions = {};
+	for (const [main, aliases] of aliasesByMain) {
+		nodeOptions[main] = { type: typeFor(main) };
+		for (const alias of aliases) nodeOptions[alias] = { type: typeFor(alias) };
+	}
+	return {
+		nodeOptions,
+		knownNames,
+		acceptedFlags
+	};
+}
+/** Mirror citty's `parseRawArgs`: strip `--no-<flag>` tokens before they ever reach
+* `node:util`'s parser (citty accepts the negated form for *any* name, declared or not -- so an
+* undeclared `--no-bogus` must still surface as `bogus` for the known-name check below, the same
+* way an undeclared `--bogus` would), then run the same `strict: false` /
+* `allowPositionals: true` parse citty runs, falling back to an empty parse on any throw exactly
+* as citty's own `try/catch` does. */
+function parsePostCommandArgs(postCommandArgs, nodeOptions) {
+	const negatedNames = [];
+	const processedArgs = [];
+	for (let i = 0; i < postCommandArgs.length; i++) {
+		const token = postCommandArgs[i];
+		if (token === "--") {
+			processedArgs.push(...postCommandArgs.slice(i));
+			break;
+		}
+		if (token.startsWith("--no-")) {
+			negatedNames.push(token.slice(5));
+			continue;
+		}
+		processedArgs.push(token);
+	}
+	let values = {};
+	let positionals = [];
+	try {
+		const parsed = parseArgs({
+			args: processedArgs,
+			options: Object.keys(nodeOptions).length > 0 ? nodeOptions : void 0,
+			allowPositionals: true,
+			strict: false
+		});
+		values = parsed.values;
+		positionals = parsed.positionals;
+	} catch {
+		values = {};
+	}
+	return {
+		values,
+		positionals,
+		negatedNames
+	};
+}
+/** The first positional declaring `valueHint: "dir"` whose value `probe` says is not a directory.
+* citty fills positionals in declaration order, so the Nth declared positional takes the Nth
+* positional token. An omitted positional is left to the command's own default. */
+function findBadDirArg(postCommandArgs, argsDef, nodeOptions, probe) {
+	const { positionals } = parsePostCommandArgs(postCommandArgs, nodeOptions);
+	const declared = Object.entries(argsDef).filter(([, def]) => def.type === "positional");
+	for (const [index, [argName, def]] of declared.entries()) {
+		const value = positionals.at(index);
+		if (value === void 0 || def.valueHint !== "dir") continue;
+		const kind = probe(value);
+		if (kind !== "directory") return {
+			argName,
+			value,
+			missing: kind === "missing"
+		};
+	}
+}
+/** The bare key names citty's own parse would carry that `argsDef` never declared -- directly
+* comparable to what a stub command's `run` would see via `Object.keys(args)` for a key citty
+* never intended, which is exactly what the differential test compares against. Note that a
+* negated `--no-<x>` produces the key `x`, not `no-<x>`: citty's pre-pass strips the token down
+* to `x` and assigns `out[x] = false` *unconditionally*, whether or not `x` itself is a declared
+* name. So a negated name is known exactly when the BARE name is declared, with no second lookup
+* under `no-<x>`: no command declares a `no-`-prefixed name and both packages'
+* `flag-strictness.test.ts` forbid one, so if that guard is ever bypassed, being rejected as an
+* unknown flag is the better outcome -- the flag would otherwise parse, be accepted here, and
+* silently do nothing. */
+function computeUnknownArgNames(postCommandArgs, argsDef) {
+	const table = buildParseTable(argsDef);
+	const { values, negatedNames } = parsePostCommandArgs(postCommandArgs, table.nodeOptions);
+	const unknown = /* @__PURE__ */ new Set();
+	for (const name of Object.keys(values)) if (!table.knownNames.has(name)) unknown.add(name);
+	for (const name of negatedNames) if (!table.knownNames.has(name)) unknown.add(name);
+	return [...unknown];
+}
+/** Map each bare key `computeUnknownArgNames` can produce back to the literal token that
+* produced it, so the rendered message shows what the caller actually typed (`--no-coverage`,
+* not `--coverage`) rather than reconstructing a plausible-looking guess. */
+function buildDisplayTokenMap(postCommandArgs) {
+	const map = /* @__PURE__ */ new Map();
+	for (const token of postCommandArgs) {
+		if (token === "--") break;
+		if (token.startsWith("--no-")) {
+			const key = token.slice(5);
+			if (!map.has(key)) map.set(key, flagBase(token));
+			continue;
+		}
+		if (!token.startsWith("-")) continue;
+		const key = flagName(token);
+		if (!map.has(key)) map.set(key, flagBase(token));
+	}
+	return map;
+}
+/** Fallback for a bare name with no matching raw token (e.g. one letter of a bundled short-flag
+* group such as `-yes`) -- vanishingly rare for this repo's single-letter aliases, but a
+* conservative guess beats dropping the flag from the message entirely. */
+function formatFlagToken(bareName) {
+	return bareName.length === 1 ? `-${bareName}` : `--${bareName}`;
+}
+/** Narrow a command's `subCommands` to a plain map, rejecting the function/Promise variants
+* `Resolvable` allows -- the same conservative narrowing `resolveStaticArgsDef` applies to
+* `args`. No command in this repo defines `subCommands` dynamically. */
+function resolveStaticSubCommands(cmd) {
+	const subCommands = cmd.subCommands;
+	if (subCommands === void 0) return void 0;
+	if (typeof subCommands === "function") return void 0;
+	if (subCommands instanceof Promise) return void 0;
+	return subCommands;
+}
+/** Walk down a command that routes to `subCommands` -- mirrors citty's own `runCommand`, which
+* recurses into `rawArgs.slice(subCommandArgIndex + 1)` against the named subcommand and measures
+* the flags there. **A router's own `args` does not stop the descent**: citty looks for the
+* subcommand token whether or not the router declares flags of its own, so a command with both
+* (`bst-fj labels`, whose `--json` exists for the `--json`-coverage test to see) must be
+* descended past rather than treated as the leaf -- otherwise every flag its subcommands declare
+* is measured against the router's table and rejected. The router's own table is the answer only
+* when no subcommand token follows. Returns `undefined` on anything the top-level check already
+* treats conservatively: an unregistered name (citty reports that itself), an entry that cannot
+* be narrowed, or a router with neither a subcommand token nor args of its own. */
+function resolveLeafCommand(cmd, chain, postCommandArgs) {
+	const argsDef = resolveStaticArgsDef(cmd);
+	const subCommands = resolveStaticSubCommands(cmd);
+	if (subCommands !== void 0) {
+		const split = splitAtCommand(postCommandArgs, argsDef);
+		if (split !== void 0) {
+			const subName = postCommandArgs[split.index];
+			if (!(subName in subCommands)) return void 0;
+			const subCmd = asCommandDef(subCommands[subName]);
+			if (subCmd === void 0) return void 0;
+			return resolveLeafCommand(subCmd, [...chain, subName], postCommandArgs.slice(split.index + 1));
+		}
+	}
+	return argsDef === void 0 ? void 0 : {
+		chain,
+		argsDef,
+		postCommandArgs
+	};
+}
+/** Returns the offending flags plus the resolved command name and its accepted flag list, or a
+* "nothing to report" result. Short-circuits, in order: `--help`/`-h` anywhere or a lone
+* `--version`/`-v` (citty's `runMain` intercepts both); no command name, or a name not in
+* `subCommands` (citty already reports those); an entry `asCommandDef` cannot narrow
+* (conservatively -- no command in this repo is a function or Promise). Flags before the command
+* name are checked against the universal set only, since the top-level `bst` command declares no
+* args of its own and citty slices them away before the subcommand ever sees them. A command
+* routing to nested `subCommands` descends via `resolveLeafCommand` -- citty parses the *nested*
+* command's args against the remaining argv, so that is where an unknown flag actually surfaces.
+* A flag written between a router and its subcommand name (`bst-fj labels --zzz sync`) goes
+* unreported: citty's own `strict: false` parse at the router absorbs it, and the subcommand
+* never sees it -- which is also why `--json` written there is silently dropped rather than
+* honoured, so a machine reader must write it after the subcommand name.
+*
+* With a `probe`, a positional declaring `valueHint: "dir"` whose value is not a directory is
+* reported too, after the flag checks. Commands hand that value to git, pnpm, or a file read as a
+* working directory, where a file produced a stack trace and `docs:check` passed without checking
+* anything. */
+function findUnknownFlags(rawArgs, subCommands, probe) {
+	if (hasHelpFlag(rawArgs) || isLoneVersionQuery(rawArgs)) return { kind: "none" };
+	const split = splitAtCommand(rawArgs);
+	if (split === void 0) return { kind: "none" };
+	const commandName = rawArgs[split.index];
+	if (!(commandName in subCommands)) return { kind: "none" };
+	const cmd = asCommandDef(subCommands[commandName]);
+	if (cmd === void 0) return { kind: "none" };
+	for (const token of split.before) if (!UNIVERSAL_NAMES.has(flagName(token))) return {
+		kind: "before-command",
+		command: commandName,
+		flag: flagBase(token)
+	};
+	const leaf = resolveLeafCommand(cmd, [commandName], rawArgs.slice(split.index + 1));
+	if (leaf === void 0) return { kind: "none" };
+	const table = buildParseTable(leaf.argsDef);
+	const unknownNames = computeUnknownArgNames(leaf.postCommandArgs, leaf.argsDef);
+	if (unknownNames.length === 0) {
+		const badDir = probe === void 0 ? void 0 : findBadDirArg(leaf.postCommandArgs, leaf.argsDef, table.nodeOptions, probe);
+		if (badDir === void 0) return { kind: "none" };
+		return {
+			kind: "not-a-directory",
+			command: commandName,
+			commandPath: leaf.chain.join(" "),
+			...badDir
+		};
+	}
+	const displayTokens = buildDisplayTokenMap(leaf.postCommandArgs);
+	return {
+		kind: "unknown",
+		command: commandName,
+		commandPath: leaf.chain.join(" "),
+		unknownFlags: unknownNames.map((name) => displayTokens.get(name) ?? formatFlagToken(name)),
+		accepted: table.acceptedFlags
+	};
+}
+/** `Unknown flag --repo for issue:comment. Nothing ran.` followed by
+* `Accepted: --body, --body-file, --json, --dry-run, --verbose (plus --help, --trace).` -- the
+* "(plus ...)" tail is {@link UNIVERSAL_FLAGS} minus what the command already declares, minus the
+* short aliases (`-h`/`-v` say nothing their long spelling does not) and minus `--version`, which
+* is a lone-invocation query citty never treats as a per-command flag (see `isLoneVersionQuery`),
+* so listing it as "accepted" here would overstate what actually happens on `<command>
+* --version`. */
+function formatUnknownFlagsMessage(result) {
+	const first = `Unknown ${result.unknownFlags.length === 1 ? "flag" : "flags"} ${result.unknownFlags.join(", ")} for ${result.commandPath}. Nothing ran.`;
+	const extras = UNIVERSAL_FLAGS.filter((flag) => flag.startsWith("--") && flag !== "--version" && !result.accepted.includes(flag));
+	return `${first}\nAccepted: ${extras.length === 0 ? result.accepted.join(", ") : `${result.accepted.join(", ")} (plus ${extras.join(", ")})`}.`;
+}
+/** `--json must come after the command name.` */
+function formatFlagBeforeCommandMessage(result) {
+	return `${result.flag} must come after the command name.`;
+}
+/** `No such directory: nope. ascii:check takes a directory as [dir]. Nothing ran.` */
+function formatNotADirectoryMessage(result) {
+	return `${result.missing ? `No such directory: ${result.value}.` : `${result.value} is not a directory.`} ${result.commandPath} takes a directory as [${result.argName}]. Nothing ran.`;
+}
+/** The single message any non-`"none"` variant renders, so `run.ts` needs one call
+* regardless of which shape the check found. */
+function formatFlagCheckMessage(result) {
+	if (result.kind === "before-command") return formatFlagBeforeCommandMessage(result);
+	if (result.kind === "not-a-directory") return formatNotADirectoryMessage(result);
+	return formatUnknownFlagsMessage(result);
+}
+/** `<n>[s|m|h]`, a bare integer meaning seconds. */
+const DURATION_PATTERN = /^(\d+)(s|m|h)?$/;
+const UNIT_MS = {
+	s: 1e3,
+	m: 6e4,
+	h: 36e5
+};
+/**
+* Parse a `--timeout`/`--interval`-shaped duration (`<n>[s|m|h]`, a bare integer meaning seconds)
+* into milliseconds. Anything else is a `FatalError` naming `flag`, so an unreadable value throws
+* into the standard error document rather than silently falling back to a default.
+*/
+function parseDuration(value, flag) {
+	const match = DURATION_PATTERN.exec(value.trim());
+	if (!match) throw new FatalError(`${flag} expects a duration like "30s", "15m", or "1h" (a bare integer means seconds) -- got ${JSON.stringify(value)}.`);
+	const [, amount, unit] = match;
+	const multiplier = UNIT_MS[unit ?? "s"];
+	return Number.parseInt(amount ?? "0", 10) * multiplier;
+}
+/**
+* Read a repeatable comma-separated list flag (`--skip`, `--add`) out of the RAW argv, unioning
+* every occurrence.
+*
+* **The union is the point, and the raw argv is the only place it survives.** pnpm appends
+* CI-forwarded flags to the END of the resolved script, so a repo whose `check` script already
+* carries `--skip build` sees TWO occurrences the moment CI or an agent adds `--skip 'docker:*'`.
+* citty declares this arg as `type: "string"` and collapses a repeated one to the LAST value
+* before the handler ever runs -- probed against citty 0.2.2, `--skip build --skip 'docker:*'`
+* arrives as the bare string `"docker:*"`, with no array and no trace of the first occurrence.
+* So reading `args.skip` cannot be made additive; the fix has to go to `rawArgs`. That collapse
+* is how this repo's `ci:check` came to run a second full build on every CI run, and it
+* contradicts the semantics the `.tooling.json#checks.skip` path already documents: a skip is
+* additive everywhere else, so it must be additive here too.
+*
+* Handles both spellings (`--skip a` and `--skip=a`), stops at a bare `--`, and ignores an
+* occurrence whose value is missing. A malformed flag contributes nothing rather than throwing
+* -- it must not take down a check run.
+*
+* "Missing" is specifically a following token starting with `--`, not one starting with `-`.
+* The looser test reads `--skip -x` as a forgotten value and silently drops a skip the caller
+* did ask for, and it makes the two spellings disagree: `--skip=-x` has no such ambiguity and
+* would keep the value. Only a long flag can be mistaken for the next argument, so only a long
+* flag terminates.
+*/
+function parseListFlag(rawArgs, flag) {
+	const long = `--${flag}`;
+	const values = [];
+	for (const [index, token] of rawArgs.entries()) {
+		if (token === "--") break;
+		if (token.startsWith(`${long}=`)) {
+			values.push(token.slice(long.length + 1));
+			continue;
+		}
+		if (token !== long) continue;
+		const next = rawArgs[index + 1];
+		if (next !== void 0 && !next.startsWith("--")) values.push(next);
+	}
+	return values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter((value) => value.length > 0);
+}
+/** True when `--<flag>` (or `--<flag>=...`) appears anywhere in `rawArgs`, independent of what it
+* resolved to. `parseListFlag` silently drops a value that resolves to empty -- an unset `$VAR` in
+* `--repo "$REPO"`, or a trailing `--repo` whose value fell off the line -- so a caller that only
+* checks the parsed list cannot tell "no --repo given" apart from "a --repo given that resolved to
+* nothing" and falls back to the current repo with no word said (the same failure shape
+* `parseRepoTarget`, in `@bensandee/forgejo/connection`, refuses for the issue commands). */
+function listFlagPresent(rawArgs, flag) {
+	const long = `--${flag}`;
+	return rawArgs.some((token) => token === long || token.startsWith(`${long}=`));
+}
+//#endregion
+//#region ../cli-kit/src/output.ts
+const stdout = (msg) => console.log(msg);
+function initialState() {
+	return {
+		payload: void 0,
+		hasPayload: false,
+		error: void 0,
+		hasError: false,
+		notices: [],
+		wrote: false
+	};
+}
+let state = initialState();
+function isJsonRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createCliOutput(jsonMode) {
+	const effective = jsonMode || isJsonMode();
+	return {
+		json: (payload) => {
+			if (!effective) return;
+			if (state.hasPayload) rootLogger.debug("output: a second json() call overwrote the first -- last call wins.");
+			state.payload = payload;
+			state.hasPayload = true;
+		},
+		text: (message) => {
+			if (!effective) stdout(message);
+		},
+		notice: (message) => {
+			if (effective) state.notices.push(redact$1(message));
+			else stdout(message);
+		}
+	};
+}
+/** Replace what {@link flushJsonOutput} writes with an error document, discarding any payload
+* already recorded by `json()` -- buffered notices are not discarded, they fold into the error
+* document the same way they fold into a payload. */
+function recordJsonError(document) {
+	state.error = document;
+	state.hasError = true;
+}
+function buildFlushDocument() {
+	let base;
+	if (state.hasError) base = state.error;
+	else if (state.hasPayload) base = state.payload;
+	if (base === void 0) return void 0;
+	if (state.notices.length === 0) return base;
+	if (isJsonRecord(base)) return {
+		...base,
+		notices: state.notices
+	};
+	return {
+		payload: base,
+		notices: state.notices
+	};
+}
+/** Write the single recorded document -- the error document if `recordJsonError` was called,
+* otherwise the recorded payload, each with buffered notices folded in under `notices` when
+* the buffer is non-empty -- and report whether anything was written. */
+function flushJsonOutput() {
+	const document = buildFlushDocument();
+	if (document === void 0) return false;
+	stdout(JSON.stringify(document));
+	state.wrote = true;
+	return true;
+}
+/** Whether {@link flushJsonOutput} has already written a document this process -- the guard the
+* premature-exit net (`@bensandee/cli-kit/json`) reads to tell a normal flush from a process that
+* died with the command still outstanding. */
+function jsonDocumentWritten() {
+	return state.wrote;
+}
+//#endregion
+//#region ../cli-kit/src/path-probe.ts
+/** The real {@link PathKind} probe the pre-run argument check uses. A path that exists but is not
+* a directory (a file, a socket) reads as `"file"`. */
+function probeCliPath(value) {
+	const stat = statSync(value, { throwIfNoEntry: false });
+	if (stat === void 0) return "missing";
+	return stat.isDirectory() ? "directory" : "file";
+}
+//#endregion
+//#region ../cli-kit/src/run.ts
+/**
+* Wait until a stream's internally-buffered data has been flushed to the OS.
+*
+* On Linux, `process.stdout`/`process.stderr` are ASYNCHRONOUS when the fd is
+* a pipe (only files and TTYs get synchronous writes). A `write("", cb)` call
+* queues behind any pending writes and invokes `cb` once the underlying fd has
+* actually accepted everything buffered so far -- including when nothing was
+* pending, so this is safe to call unconditionally. Errors (e.g. EPIPE from a
+* reader that closed early, such as `| head`) are swallowed: there is nothing
+* further to flush in that case, and `runCli()` below must not throw here.
+*/
+function drain(stream) {
+	return new Promise((resolve) => {
+		stream.write("", () => resolve());
+	});
+}
+/**
+* Raise the process log level to what `--verbose`/`-v`/`--trace` in `rawArgs` ask for.
+*
+* `--verbose`/`-v`/`--trace` are universal (see flags.ts): honoured on every command whether
+* or not it declares any of them, not just the ones that parse them from their own args. Resolving
+* the level from raw argv, in addition to the environment-only default at module load, is what
+* makes that carve-out honest rather than a flag the CLI accepts but never acts on. `-v` reads as
+* verbose here and as citty's version query only when it is the whole argv, which is the sole
+* shape citty's `runMain` intercepts -- so the two never contend.
+*
+* Exported because each bin must call it **before** {@link runCli}: a bin reports its
+* `$BST_ENV_FILE` load at module top level, which is ahead of anything that parses a flag, so
+* without this call that one line is the only diagnostic in the CLI the flags cannot reach.
+* Idempotent, and deliberately called twice -- `runCli` resolves the same level again off the
+* same argv, so a caller that is not a bin is unaffected.
+*/
+function applyVerbosityFromArgs(rawArgs) {
+	setLogLevel(resolveLogLevel({
+		verbose: rawArgs.includes("--verbose") || rawArgs.includes("-v"),
+		trace: rawArgs.includes("--trace")
+	}));
+}
+/**
+* Build and run a bin's CLI from its {@link RunCliConfig}.
+*
+* citty only calls process.exit() for --help and errors. On normal completion
+* a command may leave the event loop alive (bst's @clack/prompts leaves readline
+* interfaces, signal listeners and spinner intervals), so we still call
+* process.exit() explicitly -- but only after draining stdout/stderr. Exiting
+* immediately after `runMain` resolves used to truncate piped `--json` output
+* at the ~64KB pipe buffer:
+* `process.stdout.write(bigJson)` returns before the OS has accepted all of it,
+* and `process.exit()` discards whatever is still queued. See tooling-cli's
+* test/bin-json-piping.test.ts.
+*/
+async function runCli(config) {
+	const allSubCommands = config.subCommands;
+	const main = defineCommand({
+		meta: {
+			name: config.name,
+			version: config.version,
+			description: config.description
+		},
+		subCommands: allSubCommands
+	});
+	/**
+	* Render a `--json` error document and exit -- the shared tail every JSON-mode rejection here
+	* needs, whether from the strict-flag check, the `--json`-support check, a thrown error
+	* mid-command, or a command that recorded no payload. `never` return type: every call site
+	* ends the process, so nothing after a call to this needs its own unreachable-code guard.
+	*/
+	const exitWithJsonError = async (command, kind, message, detail) => {
+		recordJsonError(buildErrorDocument({
+			command,
+			version: config.version,
+			kind,
+			message,
+			detail
+		}));
+		if ((process.exitCode ?? 0) === 0) process.exitCode = 1;
+		flushJsonOutput();
+		await Promise.all([drain(process.stdout), drain(process.stderr)]);
+		process.exit(process.exitCode ?? 0);
+	};
+	const rawArgs = process.argv.slice(2);
+	applyVerbosityFromArgs(rawArgs);
+	const commandName = resolveCommandName(rawArgs);
+	if (!resolveJsonMode(rawArgs)) {
+		const flagCheck = findUnknownFlags(rawArgs, allSubCommands, probeCliPath);
+		if (flagCheck.kind !== "none") {
+			console.error(formatFlagCheckMessage(flagCheck));
+			process.exitCode = 1;
+			await Promise.all([drain(process.stdout), drain(process.stderr)]);
+			process.exit(process.exitCode ?? 0);
+		}
+		if (config.banner !== void 0) console.error(config.banner);
+		await runMain(main);
+		await Promise.all([drain(process.stdout), drain(process.stderr)]);
+		process.exit(process.exitCode ?? 0);
+	}
+	setJsonMode(true);
+	setJsonNoticeSink((msg) => createCliOutput(true).notice(msg));
+	installJsonExitNet(config.name, commandName, config.version, jsonDocumentWritten);
+	const jsonFlagCheck = findUnknownFlags(rawArgs, allSubCommands, probeCliPath);
+	if (jsonFlagCheck.kind !== "none") await exitWithJsonError(jsonFlagCheck.command, "usage", formatFlagCheckMessage(jsonFlagCheck));
+	const resolvedCommand = asCommandDef(commandName !== void 0 && commandName in allSubCommands ? allSubCommands[commandName] : void 0);
+	if (commandName === void 0 || resolvedCommand === void 0 || !commandDeclaresJson(resolvedCommand)) {
+		let message;
+		if (commandName === void 0) message = "No command specified.";
+		else if (resolvedCommand === void 0) message = `Unknown command ${commandName}.`;
+		else message = `Command ${commandName} does not support --json.`;
+		await exitWithJsonError(commandName, "usage", message);
+	}
+	try {
+		await runCommand(main, { rawArgs });
+	} catch (error) {
+		const classified = classifyThrown(error, verboseRequested(rawArgs));
+		await exitWithJsonError(commandName, classified.kind, classified.message, classified.detail);
+	}
+	if (!flushJsonOutput()) await exitWithJsonError(commandName, "runtime", `${commandName} --json completed without recording a JSON payload. This is a bug in the command's --json support -- it does not necessarily mean the command's underlying action failed.`);
+	await Promise.all([drain(process.stdout), drain(process.stderr)]);
+	process.exit(process.exitCode ?? 0);
+}
+let current = {
+	warn(message) {
+		process.stderr.write(`${message}\n`);
+	},
+	debug() {}
+};
+function setForgejoLogger(logger) {
+	current = logger;
+}
+/** Stable call-site surface: modules bind `log` once; injection swaps the target underneath. */
+const log = {
+	warn(message) {
+		current.warn(message);
+	},
+	debug(message) {
+		current.debug(message);
+	}
+};
+//#endregion
+//#region ../forgejo/src/fetch-retry.ts
+/** Production policy: 5 attempts, 250ms->2s exponential backoff (four gaps, ~3.75s total). */
+const DEFAULT_RETRY_POLICY = {
+	attempts: 5,
+	baseDelayMs: 250,
+	maxDelayMs: 2e3
+};
+/**
+* Per-request wall-clock timeout for every forge fetch -- a backstop against an *infinite* hang,
+* not a tight SLA. `globalThis.fetch` has no timeout, so a stalled keep-alive socket (the peer
+* sent FIN but never answers) makes a request neither resolve nor reject: the agent then hangs
+* forever on it, and `retryOnTransient` cannot help because it only catches *thrown* errors, not
+* an indefinite stall. This was the root cause of "the loop stalls when a task fails" -- the
+* stall lands on `unclaimOnError`'s non-retried failure-comment POST. Generous (healthy forge
+* calls finish in well under a second) so it never trips a slow-but-live request; the one call
+* that can legitimately exceed it -- a large release-asset upload -- opts out with `timeoutMs: 0`.
+*/
+const DEFAULT_FETCH_TIMEOUT_MS = 12e4;
+/**
+* A transport-level error a retry can recover from by opening a fresh socket: undici's thrown
+* `TypeError` ("fetch failed": DNS blip, dead keep-alive, socket hang-up), plus the
+* `AbortSignal.timeout` abort we attach ourselves (a `DOMException` named `TimeoutError`, or
+* `AbortError` on some undici paths) -- a stalled read is exactly what a retry is for. A
+* caller's own cancel also surfaces as an abort here; {@link retryOnTransient} checks the
+* caller's signal before this classifier, so a real cancel is rethrown and never retried.
+*/
+function isTransientTransportError(error) {
+	if (error instanceof TypeError) return true;
+	return error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+/**
+* Bound every request by the wall-clock cap, composing with -- never replaced by -- a signal the
+* caller brought: with both present the request aborts on whichever fires first, so threading a
+* cancel signal in can never silently disable the stall backstop. A disabled cap (`timeoutMs <=
+* 0`) returns `init` untouched, caller signal included. Called once per attempt -- an
+* already-fired timeout signal stays aborted, so a retried request must mint a new one rather
+* than reuse the timed-out attempt's.
+*/
+function withTimeoutSignal(init, timeoutMs) {
+	if (timeoutMs <= 0) return init;
+	const timeout = AbortSignal.timeout(timeoutMs);
+	if (init?.signal != null) return {
+		...init,
+		signal: AbortSignal.any([init.signal, timeout])
+	};
+	return {
+		...init,
+		signal: timeout
+	};
+}
+/** Exponential backoff (capped) between attempts; a non-positive base is a no-op (the test seam). */
+async function retryBackoff(attempt, baseDelayMs, maxDelayMs) {
+	if (baseDelayMs <= 0) return;
+	const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), maxDelayMs);
+	await new Promise((resolve) => setTimeout(resolve, delay));
+}
+/**
+* Retry `fn` on a transient transport error (see {@link isTransientTransportError}: undici's
+* "fetch failed" TypeError, or our own `AbortSignal.timeout` abort) up to `policy.attempts`
+* times, with exponential backoff between tries. Any other thrown error propagates on the first
+* attempt -- only a transport-level error is transient. A resolved value (including a 4xx/5xx
+* `Response`) is never a throw, so it is never retried. After the last attempt fails, the final
+* error is re-thrown.
+*
+* Idempotency is the caller's contract: only wrap a `fn` whose re-execution converges to the same
+* state. `retryOnTransient` cannot and does not verify that.
+*
+* `callerSignal` is the caller's own cancel: once it has fired, every error -- transient-shaped
+* or not -- is rethrown at once, because a cancelled call must never be retried.
+*/
+async function retryOnTransient(fn, policy = DEFAULT_RETRY_POLICY, callerSignal = null) {
+	let lastError;
+	for (let attempt = 1; attempt <= policy.attempts; attempt++) try {
+		return await fn();
+	} catch (error) {
+		if (callerSignal?.aborted) throw error;
+		if (!isTransientTransportError(error)) throw error;
+		lastError = error;
+		if (attempt < policy.attempts) await retryBackoff(attempt, policy.baseDelayMs, policy.maxDelayMs);
+	}
+	throw lastError;
+}
+/**
+* Wrap a fetch so idempotent requests retry on a transient `TypeError` (see {@link
+* retryOnTransient}). A request is idempotent when its method is GET/HEAD (a read) OR the caller
+* passed `{ idempotent: true }` as the third arg -- the escape hatch for a mutating call that
+* converges (e.g. `updatePr`'s PATCH). A non-idempotent mutation (POST create/comment) is never
+* retried: "fetch failed" does not prove the request never landed server-side, so a re-send could
+* duplicate it. `policy` is injectable so tests run with `baseDelayMs: 0` and never wait.
+*/
+function fetchWithRetry(fetchImpl, policy = DEFAULT_RETRY_POLICY, defaultTimeoutMs = DEFAULT_FETCH_TIMEOUT_MS) {
+	return (input, init, retry) => {
+		const method = (init?.method ?? "GET").toUpperCase();
+		const idempotent = method === "GET" || method === "HEAD" || retry?.idempotent === true;
+		const timeoutMs = retry?.timeoutMs ?? defaultTimeoutMs;
+		const callerSignal = init?.signal ?? null;
+		const attempt = () => fetchImpl(input, withTimeoutSignal(init, timeoutMs));
+		if (!idempotent) return attempt();
+		return retryOnTransient(attempt, retry?.attempts === void 0 ? policy : {
+			...policy,
+			attempts: retry.attempts
+		}, callerSignal);
+	};
+}
+/**
+* A real-network {@link ForgeFetcher} with the default retry policy, for a caller that has no
+* `ReleaseExecutor` (the standalone Forgejo CLI). `globalThis.fetch` is read at call time, so a
+* stub installed after this call is still seen.
+*/
+function createForgeFetcher(policy = DEFAULT_RETRY_POLICY) {
+	return { fetch: fetchWithRetry((input, init) => globalThis.fetch(input, init), policy) };
+}
+//#endregion
+//#region src/fetcher.ts
+/**
+* The one place a command gets its real fetcher. Every command reaches the network only through
+* this function, so a test mocks this module and no other.
+*/
+function cliFetcher() {
+	return createForgeFetcher();
+}
+//#endregion
+//#region ../forgejo/src/errors.ts
+/**
+* A refusal about the caller's reach rather than about the request: 401/403 (the token lacks the
+* scope) and 404 (the resource is absent, or present and invisible to this token -- the two are
+* indistinguishable by design on both forges).
+*
+* It extends `FatalError` and carries the identical message, so every existing caller sees exactly
+* what it saw before. The subclass exists for a caller reading an *optional* enrichment **behind a
+* proof the resource exists**, which can therefore degrade instead of failing: `runIssueView`'s
+* pulls read is that caller, and the only one. Catching plain `FatalError` there would also
+* swallow a 422 or a schema mismatch as "no access", which is why the narrower type exists.
+*
+* Whether to degrade stays with the caller; this layer only reports what the forge said.
+*
+* `name` stays `"FatalError"`: the base class types it as that literal, and the discriminator here
+* is `instanceof`, not the string.
+*/
+var ForgeAccessError = class extends FatalError {};
+/**
+* Request headers shared by every Forgejo API caller in this package. Sitting on the leaf module
+* that already owns {@link ForgejoConnection} is what lets `issues.ts`, `issue-labels.ts`,
+* `issue-comments.ts`, and `label-provisioning.ts` all use them with no edge back to `issues.ts`.
+*/
+function authHeaders$1(conn) {
+	return { Authorization: `token ${conn.token}` };
+}
+function jsonHeaders(conn) {
+	return {
+		...authHeaders$1(conn),
+		"Content-Type": "application/json"
+	};
+}
+/** Shared "not found" wording so it isn't duplicated across every function that reads a repo. */
+function repoNotFoundMessage(conn) {
+	return `Repository ${conn.repository} not found (or the token cannot see it)`;
+}
+/**
+* Field names come from a real Forgejo response. Note `browser_download_url` --
+* NOT `download_url`. The URL is a web route (`/attachments/<uuid>`), not an
+* `/api/v1` route, and an API token does authenticate against it.
+*
+* Lives on this leaf module -- rather than on `issues.ts`, which normalizes the attachments
+* inline on an issue, or `issue-comments.ts`, which reads a comment's own attachments -- because
+* both need it and neither may import from the other.
+*/
+const AttachmentSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	size: z.number(),
+	created_at: z.string(),
+	browser_download_url: z.string()
+});
+z.array(AttachmentSchema);
+/** Safely read response body text for inclusion in error messages. */
+async function responseBodyText(res) {
+	try {
+		const text = await res.text();
+		const truncated = text.length > 500 ? text.slice(0, 500) + "..." : text;
+		return redact(truncated);
+	} catch {
+		return "(could not read response body)";
+	}
+}
+const SwaggerEnvelopeSchema = z.union([z.object({ message: z.literal("") }), z.object({
+	message: z.string(),
+	url: z.string().regex(/\/api\/swagger$/)
+})]);
+/**
+* Detect Forgejo's signature "route not handled" response shape -- empty body
+* or a JSON envelope with either an empty `message` or a `url` pointing at
+* `/api/swagger`. Forgejo returns this from a 500 (and sometimes 404) when no
+* route handles the request, even though the status code suggests a
+* server-side fault.
+*/
+function isForgejoGenericServerErrorBody(body) {
+	if (body === "") return true;
+	try {
+		const parsed = JSON.parse(body);
+		return SwaggerEnvelopeSchema.safeParse(parsed).success;
+	} catch (_error) {
+		return false;
+	}
+}
+const DISPATCH_VERB_PATTERN = /\bdispatch\b/i;
+/**
+* Map a non-2xx Forgejo response to a human-readable hint.
+*
+* Returns the most-likely cause first; callers still surface the raw body so an
+* uncommon failure mode isn't masked. Returns "" for unmapped codes (2xx/3xx,
+* teapots) so the caller can decide whether to include a Hint line at all.
+*/
+function forgejoErrorHint(status, body, operation) {
+	const isDispatch = DISPATCH_VERB_PATTERN.test(operation.verb);
+	const resource = operation.resource ?? "the resource";
+	if (status === 401 || status === 403) return `Forgejo rejected the token. It needs the scope required for "${operation.verb}" on ${resource}.`;
+	if (status === 404) {
+		const base = `"${resource}" was not found on the server. Verify the name${operation.ref ? `, that it exists on ${operation.ref}` : ""}, and that the token can see it.`;
+		return isDispatch ? `${base} For dispatch, also confirm the workflow has an "on: workflow_dispatch:" trigger.` : base;
+	}
+	if (status === 400 || status === 422) {
+		const base = `Forgejo rejected the request payload for "${operation.verb}". Check for missing or invalid fields.`;
+		return isDispatch ? `${base} For dispatch, common causes are a missing "on: workflow_dispatch:" trigger or a required input not being provided.` : base;
+	}
+	if (status >= 500 && status < 600) {
+		if (isForgejoGenericServerErrorBody(body)) {
+			const ref = operation.ref ? ` on ${operation.ref}` : "";
+			return `Forgejo returned a generic server error. Most often this means the requested route is unavailable${isDispatch ? ` (e.g. "${resource}" doesn't exist${ref}, or the workflow lacks an "on: workflow_dispatch:" trigger)` : ""}. Less commonly: the token lacks scope, or it is a server-side bug.`;
+		}
+		return `Forgejo server error -- usually transient. Retry; if it persists, check the server logs.`;
+	}
+	return "";
+}
+/**
+* Build a richer error message for a non-2xx Forgejo API response.
+*
+* Reads, truncates, and redacts the body via {@link responseBodyText}; appends
+* a `Hint:` line when {@link forgejoErrorHint} has one; appends the raw body as
+* a `Response:` block. Callers still pick the error class (Transient vs Fatal).
+*/
+async function forgejoErrorMessage(res, operation) {
+	const body = await responseBodyText(res);
+	const hint = forgejoErrorHint(res.status, body, operation);
+	return `Failed to ${operation.verb} on Forgejo: ${String(res.status)} ${res.statusText}` + (hint ? `\nHint: ${hint}` : "") + (body ? `\nResponse: ${body}` : "");
+}
+/**
+* Classify a non-2xx Forgejo response. 404 is bad input (the named resource
+* doesn't exist -- not retryable). 401/403 is a credentials/scope problem --
+* also not retryable, and the single most common failure mode here (a token
+* missing the required scope returns 403). 422 is a validation failure (e.g.
+* a nonexistent label on create) -- retrying with the same input can never
+* succeed. 410 means issues are disabled on the repository -- also permanent
+* until repo config changes, not something a retry fixes. Anything else is
+* presumed transient (server hiccups, rate limiting, etc.).
+*
+* `notFoundMessage` lets a caller supply a resource-specific 404 message
+* (e.g. "Issue #<n> not found in owner/repo"); when omitted, the 404 case
+* falls back to {@link forgejoErrorMessage}'s generic (but still hinted)
+* message, which is what every `pr.ts` call site gets.
+*
+* The 404 and 401/403 cases throw {@link ForgeAccessError} -- a `FatalError` subclass with the
+* same message, so nothing here changes for a caller that only distinguishes fatal from transient.
+*/
+async function throwForgejoFailure(res, operation, notFoundMessage) {
+	if (res.status === 404) throw new ForgeAccessError(notFoundMessage ?? await forgejoErrorMessage(res, operation));
+	const message = await forgejoErrorMessage(res, operation);
+	if (res.status === 401 || res.status === 403) throw new ForgeAccessError(message);
+	if (res.status === 422) throw new FatalError(`${message}\nForgejo rejected this as invalid (422) -- retrying with the same input cannot succeed (e.g. a nonexistent label or an assignee the repository will not accept).`);
+	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
+/**
+* The combined commit status, read as the per-job report the response already carries rather than
+* reduced to a single boolean. `CommitChecks.green` alone is a real consumer's whole need -- the
+* automerge gate only ever asks "is it green" -- but a read-only caller that reports on a PR's CI
+* wants the per-job list too, and the endpoint already returns it.
+*
+* The parse is deliberately two layers, and the layering is the whole point. The top-level schema
+* is byte-for-byte what `pr-merge.ts` has always required (`{ state, statuses }`), and `green` is
+* computed from it *before any entry is inspected*. Entries are then projected through a second,
+* all-nullish schema, so an entry shape this build cannot read degrades that one row of the report
+* and can never move the verdict. `pr-merge.ts`'s doc comment records the lesson this shape
+* encodes in prose: a schema that required a field the forge never sent (`state` on an entry, where
+* Forgejo sends `status`) once withheld every automerge, silently, because the whole response
+* failed to parse over one field the verdict never reads.
+*/
+const CombinedStatusSchema = z.object({
+	state: z.string(),
+	statuses: z.array(z.unknown())
+});
+const CheckEntrySchema = z.object({
+	context: z.string().nullish(),
+	status: z.string().nullish(),
+	description: z.string().nullish(),
+	target_url: z.string().nullish(),
+	updated_at: z.string().nullish(),
+	id: z.number().nullish()
+});
+/** A single trailing ` (<word>)` parenthetical, stripped from a context to get its `name`. */
+const TRAILING_EVENT = / \([^()]+\)$/;
+function classifyVerdict(state) {
+	if (state === "success") return "good";
+	if (state === "pending") return "pending";
+	if (state === "skipped" || state === "neutral") return "skipped";
+	return "red";
+}
+function entryKey(entry, index) {
+	if (typeof entry.context === "string" && entry.context.length > 0) return entry.context;
+	return `#${String(index)}`;
+}
+function updatedAtMillis(value) {
+	if (!value) return 0;
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
+/**
+* Deduplicate entries by `context`, newest `updated_at` winning, falling back to `id`, then to
+* array order. An entry with no (or empty) `context` is keyed by its own index instead, so two
+* context-less entries never collapse into one row.
+*/
+function dedupeEntries(entries) {
+	const byKey = /* @__PURE__ */ new Map();
+	entries.forEach((entry, index) => {
+		const key = entryKey(entry, index);
+		const existing = byKey.get(key);
+		if (!existing) {
+			byKey.set(key, {
+				entry,
+				index
+			});
+			return;
+		}
+		const existingUpdated = updatedAtMillis(existing.entry.updated_at);
+		const candidateUpdated = updatedAtMillis(entry.updated_at);
+		if (candidateUpdated > existingUpdated) {
+			byKey.set(key, {
+				entry,
+				index
+			});
+			return;
+		}
+		if (candidateUpdated === existingUpdated) {
+			const existingId = existing.entry.id ?? -Infinity;
+			if ((entry.id ?? -Infinity) > existingId) byKey.set(key, {
+				entry,
+				index
+			});
+		}
+	});
+	const sorted = [...byKey.values()];
+	sorted.sort((a, b) => a.index - b.index);
+	return sorted;
+}
+/**
+* Read a commit's combined status as a per-job report, scoped to `sha`. An unparseable response
+* returns `parsed: false` rather than throwing: a broken read must never look like a decision a
+* caller is entitled to make.
+*/
+async function readCommitChecks(executor, conn, sha) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/commits/${sha}/status`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "read commit status",
+		resource: sha
+	});
+	const body = await res.json();
+	const parsed = CombinedStatusSchema.safeParse(body);
+	if (!parsed.success) return {
+		parsed: false,
+		state: "",
+		green: false,
+		contexts: []
+	};
+	const green = parsed.data.state === "success" && parsed.data.statuses.length > 0;
+	const EMPTY_ENTRY = {
+		context: null,
+		status: null,
+		description: null,
+		target_url: null,
+		updated_at: null,
+		id: null
+	};
+	const contexts = dedupeEntries(parsed.data.statuses.map((raw) => {
+		const entryParsed = CheckEntrySchema.safeParse(raw);
+		return entryParsed.success ? entryParsed.data : EMPTY_ENTRY;
+	})).map(({ entry }) => {
+		const context = entry.context ?? "";
+		return {
+			context,
+			name: context.replace(TRAILING_EVENT, ""),
+			state: entry.status ?? "",
+			verdict: classifyVerdict(entry.status),
+			description: entry.description ?? null,
+			targetUrl: entry.target_url ?? null,
+			updatedAt: entry.updated_at ?? null
+		};
+	});
+	return {
+		parsed: true,
+		state: parsed.data.state,
+		green,
+		contexts
+	};
+}
+z.object({ default_branch: z.string() });
+const BranchHeadSchema = z.object({ commit: z.object({ id: z.string() }) });
+z.object({
+	total_commits: z.number(),
+	commits: z.array(z.unknown())
+});
+z.object({ sha: z.string() });
+z.object({
+	sha: z.string(),
+	created: z.string()
+});
+z.array(z.unknown());
+function repoBase(conn) {
+	return `${conn.serverUrl}/api/v1/repos/${conn.repository}`;
+}
+function authHeaders(conn) {
+	return { Authorization: `token ${conn.token}` };
+}
+/** A branch's own "not found" wording -- distinct from {@link repoNotFoundMessage} so a stale
+* cached branch name (e.g. after a default-branch rename) reports the resource that is actually
+* missing, not the repo it lives in. */
+function branchNotFoundMessage(conn, branch) {
+	return `Branch ${branch} not found in ${conn.repository}`;
+}
+/** A branch's head commit SHA -- the cheap "has anything landed?" probe a caller uses to decide
+* whether a clone is worth doing at all. */
+async function getBranchHeadSha(executor, conn, branch) {
+	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
+	}, branchNotFoundMessage(conn, branch));
+	const parsed = BranchHeadSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected branch response: ${parsed.error.message}`);
+	return parsed.data.commit.id;
+}
+//#endregion
+//#region ../forgejo/src/connection.ts
+function parseGitUrl(urlStr) {
+	try {
+		const url = new URL(urlStr);
+		const pathname = url.pathname.replace(/\.git$/, "").replace(/^\//, "");
+		if (!pathname.includes("/")) return null;
+		return {
+			protocol: url.protocol,
+			hostname: url.hostname,
+			repository: pathname
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* The one place RELEASE_TOKEN / FORGEJO_TOKEN precedence lives. `||` (not `??`) on
+* purpose: CI injects RELEASE_TOKEN="" for an unset secret, which must fall through to
+* FORGEJO_TOKEN instead of masking it.
+*/
+function forgeTokenFromEnv(env) {
+	return env["RELEASE_TOKEN"] || env["FORGEJO_TOKEN"];
+}
+/**
+* Resolve the Forgejo connection from the environment and one repository URL the caller finds
+* (git remote origin, else package.json; this module does no I/O). `repoUrl` is a thunk, called
+* only once the environment has not settled the connection, so a complete environment never
+* costs a git subprocess or a package.json read (and never fails on a malformed one).
+*
+* Priority:
+* 1. Environment variables (FORGEJO_SERVER_URL, FORGEJO_REPOSITORY, RELEASE_TOKEN)
+* 2. `repoUrl` (server URL and owner/repo parsed from it)
+*
+* For Forgejo, a token is always required ({@link forgeTokenFromEnv}). Returns `null` where the
+* repository is on github.com or there is no repository URL at all: the caller treats that as
+* GitHub (the gh CLI handles auth).
+*/
+function resolveForgejoConnection(env, repoUrl) {
+	const serverUrl = env["FORGEJO_SERVER_URL"];
+	const repository = env["FORGEJO_REPOSITORY"];
+	const token = forgeTokenFromEnv(env);
+	if (serverUrl && repository && token) return {
+		serverUrl,
+		repository,
+		token
+	};
+	const url = repoUrl();
+	const parsed = url === null ? null : parseGitUrl(url);
+	if (parsed === null) {
+		if (serverUrl) {
+			if (!repository) throw new FatalError("FORGEJO_REPOSITORY environment variable is required");
+			if (!token) throw new FatalError("RELEASE_TOKEN environment variable is required");
+		}
+		return null;
+	}
+	if (parsed.hostname === "github.com") return null;
+	if (!token) throw new FatalError("RELEASE_TOKEN environment variable is required (server URL and repository were resolved from package.json)");
+	return {
+		serverUrl: serverUrl ?? `${parsed.protocol}//${parsed.hostname}`,
+		repository: repository ?? parsed.repository,
+		token
+	};
+}
+const ISSUE_PATH = /^\/([^/]+\/[^/]+)\/(?:issues|pulls?)\/(\d+)\/?$/;
+/** Parse a bare issue number or a full issue URL. A URL also carries repo coordinates. */
+function parseIssueRef(input) {
+	if (input === void 0 || input.trim() === "") return {};
+	const value = input.trim();
+	if (/^\d+$/.test(value)) return { number: Number.parseInt(value, 10) };
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		url = void 0;
+	}
+	if (url !== void 0 && url.protocol !== "http:" && url.protocol !== "https:") throw new FatalError(`Not an issue number or issue URL: "${value}" (expected e.g. 273 or https://host/owner/repo/issues/273)`);
+	if (url !== void 0) {
+		const match = ISSUE_PATH.exec(url.pathname);
+		if (match) {
+			const [, repository, num] = match;
+			if (repository !== void 0 && num !== void 0) return {
+				number: Number.parseInt(num, 10),
+				target: {
+					serverUrl: url.origin,
+					repository,
+					hostname: url.hostname
+				}
+			};
+		}
+	}
+	throw new FatalError(`Not an issue number or issue URL: "${value}" (expected e.g. 273 or https://host/owner/repo/issues/273)`);
+}
+/**
+* Parse a `--repo <url>` value into a target. `undefined` -- the flag absent -- is the only input
+* meaning "not given": a present but blank value refuses instead of resolving from the working
+* directory, because both shapes that produce one come from a caller who believes they targeted
+* another repository. `--repo "$REPO"` with the variable unset arrives as `""`, and so does a
+* trailing `--repo` whose value fell off the end of the line, which citty coerces from `true` to
+* `""` for a string-typed arg. Answering either from the current repo is the same number, a
+* different object, and not a word said -- the silence the `--repo` handling exists to close.
+*/
+function parseRepoTarget(input) {
+	if (input === void 0) return void 0;
+	if (input.trim() === "") throw new FatalError("--repo was given with no repository URL (expected e.g. https://host/owner/repo).");
+	const match = /^(https?:\/\/[^/]+)\/([^/]+\/[^/]+?)(?:\.git)?\/?$/.exec(input.trim());
+	if (!match) throw new FatalError(`Not a repository URL: "${input}"`);
+	const [, serverUrl, repository] = match;
+	if (serverUrl === void 0 || repository === void 0) throw new FatalError(`Not a repository URL: "${input}"`);
+	return {
+		serverUrl,
+		repository,
+		hostname: new URL(serverUrl).hostname
+	};
+}
+/**
+* Reconcile an issue ref's own target (from an issue URL) with an explicit `--repo`. Before this,
+* every call site let `ref.target ?? parseRepoTarget(repo)` discard a `--repo` the moment the ref
+* carried a target of its own -- silently, the same failure class the strict-flag check exists to
+* close, one layer in: a caller who passes both a URL and a disagreeing `--repo` gets an answer
+* from the URL's repository with no sign the flag was ignored.
+*
+* Absent one side, the other wins outright. Present on both sides, agreement (compared on the
+* parsed `serverUrl`/`repository`, not the raw strings, so a trailing slash or `.git` -- both of
+* which `parseRepoTarget` already normalizes away -- is never mistaken for a disagreement) resolves
+* quietly; disagreement throws, naming both repositories rather than picking one without a word.
+*/
+function resolveIssueTarget(refTarget, repo) {
+	const repoTarget = parseRepoTarget(repo);
+	if (refTarget === void 0) return repoTarget;
+	if (repoTarget === void 0) return refTarget;
+	if (refTarget.serverUrl === repoTarget.serverUrl && refTarget.repository === repoTarget.repository) return refTarget;
+	throw new FatalError(`--repo disagrees with the issue URL: --repo names ${repoTarget.serverUrl}/${repoTarget.repository}, the issue URL names ${refTarget.serverUrl}/${refTarget.repository}.`);
+}
+/**
+* Normalize a git remote URL to a clean HTTPS URL.
+* Handles SSH (git@host:owner/repo.git) and HTTPS variants.
+*/
+function normalizeGitUrl(raw) {
+	const sshMatch = raw.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+	if (sshMatch) return `https://${sshMatch[1]}/${sshMatch[2]}`;
+	try {
+		const url = new URL(raw);
+		url.pathname = url.pathname.replace(/\.git$/, "");
+		url.username = "";
+		url.password = "";
+		return url.toString().replace(/\/$/, "");
+	} catch (_error) {
+		return null;
+	}
+}
+//#endregion
+//#region ../cli-kit/src/git.ts
+const BRANCH_REF_PREFIX = "refs/heads/";
+/** The origin read gives up after this long, so a wedged remote lookup cannot hang a command. */
+const ORIGIN_READ_TIMEOUT_MS = 5e3;
+function defaultGitRunner(args, cwd, options) {
+	try {
+		const trimmed = execFileSync("git", args, {
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: options?.timeoutMs
+		}).toString("utf-8").trim();
+		return trimmed === "" ? void 0 : trimmed;
+	} catch {
+		return;
+	}
+}
+/**
+* Resolve the branch the current run is on.
+*
+* CI env wins: `GITHUB_REF` (also set by Forgejo Actions) is the source of truth
+* for whether this is a branch event -- tag and pull-request refs are deliberately
+* reported as `undefined` since they have no meaningful branch. On a branch event
+* the short name comes from `GITHUB_REF_NAME` (falling back to stripping the
+* prefix off `GITHUB_REF`). Without `GITHUB_REF`, falls back to local git.
+*
+* Returns `undefined` when the branch cannot be determined or the ref is not a
+* branch (tag, PR merge ref, detached HEAD).
+*/
+function resolveCurrentBranch(options) {
+	const env = options.env ?? process.env;
+	const ref = env["GITHUB_REF"];
+	if (ref !== void 0 && ref !== "") {
+		if (!ref.startsWith(BRANCH_REF_PREFIX)) return void 0;
+		const name = env["GITHUB_REF_NAME"];
+		return name !== void 0 && name !== "" ? name : ref.slice(11);
+	}
+	const branch = (options.git ?? defaultGitRunner)([
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	], options.cwd);
+	if (branch === void 0 || branch === "HEAD") return void 0;
+	return branch;
+}
+/**
+* The raw output of `git remote get-url origin`, or `null` when there is no origin or `cwd` is not
+* a repository. Not normalized: an SSH remote comes back as written.
+*/
+function readOriginUrl(cwd, git = defaultGitRunner) {
+	return git([
+		"remote",
+		"get-url",
+		"origin"
+	], cwd, { timeoutMs: ORIGIN_READ_TIMEOUT_MS }) ?? null;
+}
+const RepositorySchema = z.union([z.string(), z.object({ url: z.string() })]);
+/** The `repository` field of `cwd`'s `package.json` as a URL string, or `null` when absent. */
+function readPackageRepositoryUrl(cwd) {
+	const pkgPath = path.join(cwd, "package.json");
+	let raw;
+	try {
+		raw = readFileSync(pkgPath, "utf-8");
+	} catch {
+		return null;
+	}
+	const pkg = z.object({ repository: RepositorySchema.optional() }).safeParse(JSON.parse(raw));
+	if (!pkg.success) return null;
+	const repo = pkg.data.repository;
+	if (!repo) return null;
+	return typeof repo === "string" ? repo : repo.url;
+}
+//#endregion
+//#region src/connection.ts
+/**
+* The repository URL for `cwd`: the `origin` remote first, since `package.json` may advertise a
+* public mirror rather than the host the commands act on; `package.json#repository` only as a
+* last resort. `null` when neither parses.
+*/
+function resolveRepoUrl(cwd) {
+	const originUrl = normalizeGitUrl(readOriginUrl(cwd) ?? "");
+	if (originUrl !== null && parseGitUrl(originUrl) !== null) return originUrl;
+	const pkgUrl = readPackageRepositoryUrl(cwd);
+	return pkgUrl !== null && parseGitUrl(pkgUrl) !== null ? pkgUrl : null;
+}
+/**
+* The Forgejo connection a command acts on. An explicit target (from an issue URL or `--repo`)
+* wins over the working directory. `githubRefusal` is the command's own sentence for a github.com
+* repository, which owes the reader the `gh` alternative. The environment settles the connection
+* before any git or `package.json` read, so CI with only the environment needs neither.
+*/
+function requireForgejoTarget(cwd, target, githubRefusal, env = process.env) {
+	if (target !== void 0) {
+		if (target.hostname === "github.com") throw new FatalError(githubRefusal);
+		const token = forgeTokenFromEnv(env);
+		if (!token) throw new FatalError("bst-fj needs a forge token -- set RELEASE_TOKEN (preferred) or FORGEJO_TOKEN.");
+		return {
+			serverUrl: target.serverUrl,
+			repository: target.repository,
+			token
+		};
+	}
+	const conn = resolveForgejoConnection(env, () => resolveRepoUrl(cwd));
+	if (conn === null) throw new FatalError(githubRefusal);
+	return conn;
+}
+//#endregion
+//#region ../forgejo/src/check-poll.ts
+/**
+* Commit-check classification and poll-read helpers shared by the forge-side check readers -- both
+* `pr:checks` and `commit:status` read the same `commit-status` primitive and poll it the same way;
+* only what each does with a settled result (a PR baseline vs an arbitrary ref's URL) differs. The
+* `--timeout`/`--interval` flag parsing that sets the poll cadence stays with the CLI.
+*/
+function classifyBaseStatus(checks) {
+	if (!checks.parsed) return "unparseable";
+	if (checks.contexts.length === 0) return "no-status";
+	if (checks.green) return "green";
+	if (checks.contexts.some((check) => check.verdict === "pending")) return "pending";
+	return "red";
+}
+/** At least one status, and no entry still pending -- the same definition `--wait` polls toward. */
+function isSettled(checks) {
+	if (!checks.parsed || checks.contexts.length === 0) return false;
+	return !checks.contexts.some((check) => check.verdict === "pending");
+}
+/**
+* Whether the per-entry classification disagrees with the forge's own combined reduction --
+* either direction: every entry reads `good` or `skipped` but the combined state is not
+* `success`, or the combined state is `success` while some entry reads neither. A skipped entry
+* is not a divergence -- it is a job that did not run, which carries no information about the
+* code -- so it is folded into "settled good" here the same way it is everywhere else. The
+* combined state always wins the verdict (`classifyBaseStatus` never looks at this); a caller
+* only needs to know whether to surface a notice about a genuine one.
+*/
+function disagreesWithCombinedState(checks) {
+	if (!checks.parsed || checks.contexts.length === 0) return false;
+	const allSettledGood = checks.contexts.every((check) => check.verdict === "good" || check.verdict === "skipped");
+	return checks.green !== allSettledGood;
+}
+function pushDisagreementNotice(notices, sha, checks) {
+	if (!disagreesWithCombinedState(checks)) return;
+	const notice = `The combined status ("${checks.state}") for ${sha} disagrees with this build's per-check classification -- the combined status wins the verdict.`;
+	if (!notices.includes(notice)) notices.push(notice);
+}
+/** No commit status was read -- the sentinel a `head-moved` report (which never reads the new
+* head's checks) or an exhausted retry budget (which has no trustworthy checks left) carries. */
+const EMPTY_CHECKS = {
+	parsed: false,
+	state: "",
+	green: false,
+	contexts: []
+};
+/** One poll's commit-status read, reduced to a {@link PollRead} a retry budget can count. */
+async function readPollChecks(fetcher, conn, sha) {
+	try {
+		const result = await readCommitChecks(fetcher, conn, sha);
+		if (result.parsed) return { checks: result };
+		return { failureDetail: "The commit status response did not match the shape this build expects." };
+	} catch (error) {
+		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;
+/** The test-only override, ignored unless it is a positive integer, and never above production. */
+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);
+}
+/** `--timeout`/`--interval` in milliseconds, defaulted and floored. Separated from the wait loop
+* so a command can refuse an unparseable duration before it makes a single request. */
+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;
+	return {
+		timeoutMs,
+		intervalMs: envMsOverride(process.env["BST_TEST_CHECK_POLL_INTERVAL_MS"], Math.max(requestedIntervalMs, MIN_INTERVAL_MS))
+	};
+}
+//#endregion
+//#region src/sleep.ts
+/** The production delay between `--wait` polls. Tests inject their own through the runners' `sleep` option. */
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+//#region src/commit-status.ts
+/**
+* `bst-fj commit:status` -- query and report Forgejo commit status checks for an arbitrary commit
+* SHA, branch name, tag, or local git ref over `@bensandee/forgejo`'s `readCommitChecks`.
+*
+* Unlike `pr:checks` which requires an open pull request, this command queries commit check
+* contexts and the combined status reduction directly for any ref.
+*/
+/**
+* Resolve `--repo`, cwd connection, and the commit ref into a `CommitStatusTarget`.
+*/
+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.");
+	const rawRef = options.ref !== void 0 && options.ref.trim() !== "" ? options.ref.trim() : "HEAD";
+	let resolvedSha = rawRef;
+	if (!FULL_SHA.test(rawRef)) {
+		if (targetRepo === void 0) {
+			const git = options.git ?? defaultGitRunner;
+			const symbolic = rawRef === "HEAD" ? void 0 : git([
+				"rev-parse",
+				"--symbolic-full-name",
+				rawRef
+			], options.cwd);
+			if (symbolic !== void 0 && symbolic.startsWith("refs/heads/")) resolvedSha = await forgeBranchHeadSha(fetcher, conn, rawRef) ?? rawRef;
+			else {
+				const rev = git(["rev-parse", `${rawRef}^{commit}`], options.cwd);
+				resolvedSha = rev !== void 0 && rev.length === 40 ? rev : await forgeBranchHeadSha(fetcher, conn, rawRef) ?? rawRef;
+			}
+		} else resolvedSha = await forgeBranchHeadSha(fetcher, conn, rawRef) ?? rawRef;
+	}
+	const path = FULL_SHA.test(resolvedSha) ? "commit" : "commits";
+	const url = `${conn.serverUrl}/${conn.repository}/${path}/${resolvedSha}`;
+	return {
+		conn,
+		ref: rawRef,
+		sha: resolvedSha,
+		url
+	};
+}
+/** A ref that is already a full commit SHA needs no resolution at all. */
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/**
+* The forge's head SHA for `ref` as a branch, or `undefined` when the forge has no such branch --
+* a tag, or any other ref the commit-status API can read directly, which then passes through
+* verbatim. A server error still throws: passing through on a 5xx would silently answer about the
+* wrong commit. `ForgeAccessError` also covers 401/403, where pass-through costs nothing extra --
+* the status read that follows fails on the same credential.
+*/
+async function forgeBranchHeadSha(fetcher, conn, ref) {
+	try {
+		return await getBranchHeadSha(fetcher, conn, ref);
+	} catch (error) {
+		if (error instanceof ForgeAccessError) return void 0;
+		throw error;
+	}
+}
+function buildReport$1(target, checks, ctx, extras = {}) {
+	const { notices, waited, elapsedMs } = ctx;
+	const status = extras.statusOverride ?? classifyBaseStatus(checks);
+	const report = {
+		sha: target.sha,
+		ref: target.ref,
+		repository: target.conn.repository,
+		url: target.url,
+		status,
+		settled: isSettled(checks),
+		combinedState: checks.state,
+		waited,
+		elapsedMs,
+		checks: checks.contexts.map((check) => ({ ...check })),
+		notices
+	};
+	if (extras.detailOverride !== void 0) report.detail = extras.detailOverride;
+	else if (status === "unparseable") report.detail = "The commit status response did not match the shape this build expects.";
+	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, {
+				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;
+		}
+		if (now() - startedAt >= timeoutMs) return buildReport$1(target, lastGoodChecks ?? EMPTY_CHECKS, {
+			notices,
+			waited: true,
+			elapsedMs: now() - startedAt
+		}, { statusOverride: "timeout" });
+		await sleep(intervalMs);
+	}
+}
+/**
+* Query commit checks for the resolved target ref/SHA and produce a `CommitStatusReport`.
+*/
+async function runCommitStatus(fetcher, options) {
+	const timings = options.wait === true ? resolvePollTimings(options) : void 0;
+	const target = await resolveCommitStatusTarget(fetcher, options);
+	const notices = [];
+	if (timings !== void 0) return waitForSettledChecks$1(fetcher, target, notices, {
+		...timings,
+		sleep: options.sleep ?? sleep,
+		now: options.now ?? Date.now
+	});
+	const checks = await readCommitChecks(fetcher, target.conn, target.sha);
+	pushDisagreementNotice(notices, target.sha, checks);
+	return buildReport$1(target, checks, {
+		notices,
+		waited: false,
+		elapsedMs: 0
+	});
+}
+/**
+* Render a `commit:status` report as human-readable text.
+*/
+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 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;
+	const goodCount = report.checks.filter((c) => c.verdict === "good").length;
+	const skippedCount = report.checks.filter((c) => c.verdict === "skipped").length;
+	const summaryParts = [
+		`commit ${shortSha}: ${report.status}`,
+		`${String(redCount)} red, ${String(pendingCount)} pending, ${String(goodCount)} good, ${String(skippedCount)} skipped`,
+		report.url
+	];
+	lines.push(summaryParts.join(" -- "));
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/commit-status.ts
+const commitStatusCommand = defineCommand({
+	meta: {
+		name: "commit:status",
+		description: "Query Forgejo commit status checks for an arbitrary commit SHA, branch, tag, or local git ref. Unlike pr:checks, which requires an open PR, commit:status inspects commit checks directly."
+	},
+	args: {
+		ref: {
+			type: "positional",
+			description: "Commit SHA, branch, tag, or git ref (default: HEAD)",
+			required: false
+		},
+		repo: {
+			type: "string",
+			description: "Repository URL (default: this repo)"
+		},
+		wait: {
+			type: "boolean",
+			description: "Poll until every check for the commit has settled"
+		},
+		timeout: {
+			type: "string",
+			description: "--wait's give-up duration, e.g. 20m (default: 20m). Checked once per poll, so a wait can run up to one --interval past it."
+		},
+		interval: {
+			type: "string",
+			description: "--wait's poll interval, e.g. 15s (default: 15s, floored at 5s)"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit the machine-readable report on stdout"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug output"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const report = await runCommitStatus(cliFetcher(), {
+			cwd: process.cwd(),
+			ref: args.ref,
+			repo: args.repo,
+			wait: args.wait === true,
+			timeout: args.timeout,
+			interval: args.interval
+		});
+		const { notices, ...payload } = report;
+		for (const notice of notices) out.notice(notice);
+		out.json(payload);
+		out.text(renderCommitStatus(report));
+		process.exitCode = report.status === "green" ? 0 : 1;
+	}
+});
+//#endregion
+//#region ../forgejo/src/label-provisioning.ts
+const LabelSchema = z.object({
+	id: z.number(),
+	name: z.string(),
+	color: z.string().optional(),
+	description: z.string().optional(),
+	exclusive: z.boolean().optional()
+});
+const LabelListSchema = z.array(LabelSchema);
+/** Page size for `GET .../labels`. Also the signal that another page may exist. */
+const LABELS_PAGE_SIZE = 100;
+/** Hard cap on pages fetched, so a misbehaving server can't spin this forever. */
+const LABELS_MAX_PAGES = 20;
+/**
+* Fetch every repository label, paginating until a short page (or the page
+* cap) is hit. Without pagination, a repo with more labels than one page
+* holds would silently see only the first page -- turning a real label into a
+* false "no label named X" failure (see {@link resolveLabelIds}).
+*/
+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$1(conn) });
+		if (!res.ok) await throwForgejoFailure(res, {
+			verb: "list labels",
+			resource: conn.repository
+		}, repoNotFoundMessage(conn));
+		const parsed = LabelListSchema.safeParse(await res.json());
+		if (!parsed.success) throw new UnexpectedError(`Unexpected label-list response: ${parsed.error.message}`);
+		labels.push(...parsed.data);
+		if (parsed.data.length < LABELS_PAGE_SIZE) break;
+	}
+	return labels;
+}
+/** {@link AgentLabelSpec} as a zod schema, so a hand-written spec fails at load rather than at the
+* first API call. Strict: an unknown field is a typo, not an extension point. */
+const LabelSpecSchema = z.strictObject({
+	name: z.string().min(1),
+	color: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+	description: z.string(),
+	exclusive: z.boolean().optional()
+});
+/** Named label sets: each set name maps to the specs it provisions. */
+const LabelSetsSchema = z.record(z.string(), z.array(LabelSpecSchema));
+/** Forgejo echoes label color without a leading '#'; the spec writes one. Normalize before comparing. */
+function normalizeColor(color) {
+	return color.replace(/^#/, "").toLowerCase();
+}
+/** True when an existing label's color or description differs from what the spec asks for. Exclusivity is judged separately (see {@link auditForgejoLabels}) because it is a gate condition, not cosmetic. */
+function hasCosmeticDrift(existing, spec) {
+	return normalizeColor(existing.color ?? "") !== normalizeColor(spec.color) || (existing.description ?? "") !== spec.description;
+}
+/** True when a spec asks for `exclusive: true` and the live label does not carry it -- the one direction
+* that produces the silent wrong answer `labelDrifted` used to repair as a side effect (two `agent/`
+* labels can coexist, and `stageOf` returns whichever the forge lists first). */
+function isNonExclusive(existing, spec) {
+	return (spec.exclusive ?? false) && !(existing.exclusive ?? false);
+}
+/** True when the live label's exclusivity differs from the spec's in either direction -- what
+* `ensureForgejoLabels` reconciles. `isNonExclusive` stays one-directional: it is the gate
+* condition `auditRepoLabels` reads, and a spec asking for `exclusive: false` was never a gate
+* failure. */
+function isExclusivityDrifted(existing, spec) {
+	return (existing.exclusive ?? false) !== (spec.exclusive ?? false);
+}
+/**
+* Audit a repo's labels against `specs` with a single list fetch and no write -- the read half of
+* what `ensureForgejoLabels` used to do in one pass. Returns the name->id map for every existing
+* label (so a caller keeps the fetch-avoidance `ensureForgejoLabels` callers relied on) plus four
+* name lists: labels missing entirely, labels present but not exclusive when the spec asks for it,
+* labels whose exclusivity drifted in either direction, and labels with cosmetic (color/description)
+* drift alone. A missing label and a non-exclusive one are both gate conditions; exclusivity drift
+* and cosmetic drift are reported but never block.
+*/
+async function auditForgejoLabels(executor, conn, specs) {
+	const existing = await fetchAllForgejoLabels(executor, conn);
+	const byName = new Map(existing.map((label) => [label.name, label]));
+	const labelIds = new Map(existing.map((label) => [label.name, label.id]));
+	const missing = [];
+	const nonExclusive = [];
+	const exclusivityDrift = [];
+	const cosmeticDrift = [];
+	for (const spec of specs) {
+		const current = byName.get(spec.name);
+		if (current === void 0) {
+			missing.push(spec.name);
+			continue;
+		}
+		if (isNonExclusive(current, spec)) nonExclusive.push(spec.name);
+		if (isExclusivityDrifted(current, spec)) exclusivityDrift.push(spec.name);
+		if (hasCosmeticDrift(current, spec)) cosmeticDrift.push(spec.name);
+	}
+	return {
+		labelIds,
+		missing,
+		nonExclusive,
+		exclusivityDrift,
+		cosmeticDrift
+	};
+}
+/** The `<scope>/` portion of a label name, or `null` for a leaf-only name like `bug`. */
+function labelScope(name) {
+	const slash = name.indexOf("/");
+	return slash === -1 ? null : name.slice(0, slash + 1);
+}
+/**
+* The live labels a set has left behind: present on the repo, carrying a scope the set owns, and
+* not a member of the set. This is the drift {@link auditForgejoLabels} structurally cannot report
+* -- the audit is a fact about exactly the specs it is given, so a name deleted from a set is
+* absent from both the specs and the audit, and nothing notices it is still on the repo.
+*
+* Ownership is derived from the specs rather than declared, so a label set needs no new key: a set
+* owns a scope when one of its own members carries it. A leaf-only name (`bug`) owns nothing and
+* falls under nothing, which is what keeps a repo's ordinary labels out of the report in both
+* directions.
+*
+* Deliberately not a field on {@link LabelAudit}: the agent audits against its *required* subset,
+* so a staleness computed from the audit's own specs would report every ensured-but-not-required
+* label as a stray. A caller passes the full set it provisions from.
+*/
+function staleLabelNames(specs, live) {
+	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));
+	const stale = [];
+	for (const name of live) {
+		if (wanted.has(name)) continue;
+		const scope = labelScope(name);
+		if (scope !== null && owned.has(scope)) stale.push(name);
+	}
+	stale.sort((a, b) => a.localeCompare(b));
+	return stale;
+}
+/**
+* Ensure every label in `specs` exists on the repo with the spec's color and description,
+* creating any that are missing and PATCHing any that {@link auditForgejoLabels} reports as
+* non-exclusive or cosmetically drifted. An ensure-loop like `ensureRelease`: instance label
+* templates only apply at repo creation, so a repo the agent has never touched has none of these.
+* Implemented over the audit so the two can never disagree about what "drifted" means.
+*
+* Reconciling existing labels (not just creating missing ones) is what backfills descriptions
+* onto labels created before they carried one -- the create-only version left every already-present
+* label with whatever description it happened to have, so a repo the agent had touched never
+* gained the self-documenting text.
+*
+* Returns the name->id map the audit already computed (existing labels plus any just created), so a
+* caller that goes on to mutate labels for the same repo (the agent's claim) can thread it
+* through `addForgejoIssueLabel` / `removeForgejoIssueLabel` and skip their own redundant list
+* fetch.
+*/
+async function ensureForgejoLabels(executor, conn, specs) {
+	const audit = await auditForgejoLabels(executor, conn, specs);
+	const labelIds = new Map(audit.labelIds);
+	const missing = new Set(audit.missing);
+	const drifted = /* @__PURE__ */ new Set([...audit.exclusivityDrift, ...audit.cosmeticDrift]);
+	const labelsBase = `${conn.serverUrl}/api/v1/repos/${conn.repository}/labels`;
+	for (const spec of specs) {
+		if (missing.has(spec.name)) {
+			const res = await executor.fetch(labelsBase, {
+				method: "POST",
+				headers: jsonHeaders(conn),
+				body: JSON.stringify({
+					name: spec.name,
+					color: spec.color,
+					description: spec.description,
+					exclusive: spec.exclusive ?? false
+				})
+			});
+			if (!res.ok) await throwForgejoFailure(res, {
+				verb: "create label",
+				resource: spec.name
+			}, repoNotFoundMessage(conn));
+			const parsed = LabelSchema.safeParse(await res.json());
+			if (!parsed.success) throw new UnexpectedError(`Unexpected label-create response: ${parsed.error.message}`);
+			labelIds.set(spec.name, parsed.data.id);
+			continue;
+		}
+		if (drifted.has(spec.name)) {
+			const id = labelIds.get(spec.name);
+			if (id === void 0) throw new UnexpectedError(`Audit reported drift for "${spec.name}" with no known id`);
+			const res = await executor.fetch(`${labelsBase}/${String(id)}`, {
+				method: "PATCH",
+				headers: jsonHeaders(conn),
+				body: JSON.stringify({
+					name: spec.name,
+					color: spec.color,
+					description: spec.description,
+					exclusive: spec.exclusive ?? false
+				})
+			});
+			if (!res.ok) await throwForgejoFailure(res, {
+				verb: "update label",
+				resource: spec.name
+			}, repoNotFoundMessage(conn));
+		}
+	}
+	return labelIds;
+}
+/**
+* Delete a repository label definition by id -- the write half of `--prune`: a label the
+* caller has already determined no longer belongs to a set's declared universe. Idempotent, like
+* `removeForgejoIssueLabel`: Forgejo returns 204 whether or not the label still exists, so a
+* retry after a transient blip is safe.
+*/
+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$1(conn)
+	}, { idempotent: true });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: "delete label",
+		resource: String(id)
+	}, repoNotFoundMessage(conn));
+}
+//#endregion
+//#region ../forgejo/src/issues.ts
+/**
+* Timestamps are plain strings on purpose: Forgejo returns offset-form
+* (`2026-07-13T09:23:13-05:00`), which `z.string().datetime()` rejects.
+* Unknown keys are stripped rather than rejected, so upstream additions
+* cannot break parsing.
+*/
+const IssueResponseSchema = z.object({
+	number: z.number(),
+	title: z.string(),
+	state: z.string(),
+	html_url: z.string(),
+	body: z.string().nullish(),
+	user: z.object({ login: z.string() }).nullish(),
+	labels: z.array(z.object({ name: z.string() })).nullish(),
+	assignees: z.array(z.object({ login: z.string() })).nullish(),
+	created_at: z.string(),
+	updated_at: z.string(),
+	closed_at: z.string().nullish(),
+	pull_request: z.unknown().nullish(),
+	/**
+	* Already inline on the issue response -- no separate fetch is needed to
+	* surface attachments. `nullish()` because the field may be absent or
+	* explicitly `null` depending on the endpoint.
+	*/
+	assets: z.array(AttachmentSchema).nullish()
+});
+z.array(IssueResponseSchema);
+const DependencyResponseSchema = z.object({
+	number: z.number(),
+	state: z.string(),
+	repository: z.object({ full_name: z.string() }).nullish()
+});
+z.array(DependencyResponseSchema);
+/** Page size for `GET /user/repos`. Also the "another page may exist" signal. */
+const USER_REPOS_PAGE_SIZE = 50;
+/** Hard cap on pages, so a misbehaving server cannot spin startup forever. */
+const USER_REPOS_MAX_PAGES = 20;
+const UserRepoSchema = z.object({
+	full_name: z.string(),
+	default_branch: z.string().nullish(),
+	archived: z.boolean().nullish(),
+	permissions: z.object({
+		push: z.boolean().optional(),
+		admin: z.boolean().optional()
+	}).nullish()
+});
+const UserRepoListSchema = z.array(UserRepoSchema);
+/**
+* Every repo the bot (token) can access, via Forgejo's `/user/repos`, each tagged with whether the
+* bot has write (push or admin) access. This is the agent's opt-in signal for creating the agent
+* label vocabulary: inviting the bot as a collaborator is the grant, and membership exists the
+* moment it is invited -- before any label does. `canWrite` is false for a read-only repo; the
+* caller enumerates it but writes no labels there. Paginates until an empty page: Forgejo clamps
+* `limit` (ToCorrectPageSize), so a short page is not a reliable end signal -- same reason as
+* {@link searchForgejoIssues}.
+*/
+async function fetchAccessibleRepos(executor, serverUrl, token) {
+	const headers = { Authorization: `token ${token}` };
+	const repos = [];
+	for (let page = 1; page <= USER_REPOS_MAX_PAGES; page++) {
+		const params = new URLSearchParams({
+			limit: String(USER_REPOS_PAGE_SIZE),
+			page: String(page)
+		});
+		const res = await executor.fetch(`${serverUrl}/api/v1/user/repos?${params.toString()}`, { headers });
+		if (!res.ok) await throwForgejoFailure(res, {
+			verb: "list repositories",
+			resource: serverUrl
+		}, `Repository listing failed on ${serverUrl} (or the token cannot see any repositories)`);
+		const parsed = UserRepoListSchema.safeParse(await res.json());
+		if (!parsed.success) throw new UnexpectedError(`Unexpected user-repos response: ${parsed.error.message}`);
+		for (const repo of parsed.data) repos.push({
+			fullName: repo.full_name,
+			canWrite: repo.permissions?.push === true || repo.permissions?.admin === true,
+			defaultBranch: repo.default_branch ?? null,
+			archived: repo.archived === true
+		});
+		if (parsed.data.length === 0) break;
+		if (page === USER_REPOS_MAX_PAGES) log.warn(`Repository listing on ${serverUrl} hit the ${String(USER_REPOS_MAX_PAGES)}-page cap without an empty page; results may be truncated`);
+	}
+	return repos;
+}
+//#endregion
+//#region ../forgejo/src/label-sync.ts
+/** `--check` wins over `--dry-run`; neither means apply. */
+function resolveSyncMode(check, dryRun) {
+	if (check) return "check";
+	if (dryRun) return "dry-run";
+	return "apply";
+}
+/** A `--repo owner/repo` target shares the current repo's server and token -- only the
+* repository portion changes, the same convention `--fleet` uses. */
+function targetConnection(base, repo) {
+	if (repo === void 0) return base;
+	return {
+		...base,
+		repository: repo
+	};
+}
+/** Every repo the invoking token can write to, discovered live -- no configured repo list.
+* The server URL and token come from the current repo's connection; only the repository portion
+* varies per target, the same convention `--repo` uses. */
+async function resolveFleetTargets(fetcher, base) {
+	return (await fetchAccessibleRepos(fetcher, base.serverUrl, base.token)).filter((repo) => repo.canWrite).map((repo) => targetConnection(base, repo.fullName));
+}
+function outcomeFromAudit(conn, specs, audit, lists) {
+	const missing = new Set(audit.missing);
+	const drifted = /* @__PURE__ */ new Set([...audit.exclusivityDrift, ...audit.cosmeticDrift]);
+	const unchanged = specs.map((spec) => spec.name).filter((name) => !missing.has(name) && !drifted.has(name));
+	return {
+		repository: conn.repository,
+		created: audit.missing,
+		updated: [...drifted],
+		unchanged,
+		...lists
+	};
+}
+async function syncOneRepo(params) {
+	const { fetcher, conn, specs, mode, prune, allowedPruneNames, resolveTargetSpecs } = 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 outcome = outcomeFromAudit(conn, target.specs, audit, {
+		omitted: target.omitted,
+		pruned: pruneCandidates,
+		stale: prune ? stale.filter((name) => !pruneCandidates.includes(name)) : stale
+	});
+	if (mode === "apply") {
+		if (outcome.created.length > 0 || outcome.updated.length > 0) await ensureForgejoLabels(fetcher, conn, target.specs);
+		for (const name of pruneCandidates) {
+			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);
+		}
+	}
+	return outcome;
+}
+/**
+* Ensure (or, under `check`/`dry-run`, only report) that every target repo carries `specs`.
+* Never touches a label outside `specs` -- both `auditForgejoLabels` and `ensureForgejoLabels`
+* only ever look at the names they are given. `apply` re-audits inside `ensureForgejoLabels`
+* rather than threading the first audit's label-id map through: one extra idempotent GET per
+* repo, traded for not reaching into `ensureForgejoLabels`'s internals from the caller.
+*
+* `contained` governs failure handling only: by default a throw from one repo's sync propagates
+* and stops the run. With `contained: true` one repo's failure is recorded in `failures` and the
+* sweep continues over the rest.
+*/
+async function syncLabelSet(params) {
+	const { fetcher, targets, specs, setName, mode, contained, prune, pruneAllowlist } = params;
+	const specList = [...specs];
+	const repos = [];
+	const failures = [];
+	for (const conn of targets) {
+		const allowedPruneNames = pruneAllowlist?.get(conn.repository);
+		const syncOneRepoParams = {
+			fetcher,
+			conn,
+			specs: specList,
+			mode,
+			prune: prune === true,
+			allowedPruneNames,
+			resolveTargetSpecs: params.resolveTargetSpecs
+		};
+		if (contained !== true) {
+			repos.push(await syncOneRepo(syncOneRepoParams));
+			continue;
+		}
+		try {
+			repos.push(await syncOneRepo(syncOneRepoParams));
+		} catch (error) {
+			failures.push({
+				repository: conn.repository,
+				error: describeError(error)
+			});
+		}
+	}
+	return {
+		set: setName,
+		mode,
+		repos,
+		failures,
+		drifted: repos.some((repo) => repo.created.length > 0 || repo.updated.length > 0 || repo.pruned.length > 0)
+	};
+}
+function syncSummaryLines(result) {
+	const verb = result.mode === "apply" ? "" : "would ";
+	const repoLines = [];
+	for (const repo of result.repos) {
+		const actions = [];
+		if (repo.created.length > 0) actions.push(`${verb}create: ${repo.created.join(", ")}`);
+		if (repo.updated.length > 0) actions.push(`${verb}update: ${repo.updated.join(", ")}`);
+		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(", ")}`);
+		if (actions.length === 0) {
+			repoLines.push(`${repo.repository}: up to date (${String(repo.unchanged.length)} unchanged)`);
+			continue;
+		}
+		repoLines.push(`${repo.repository}: ${actions.join("; ")}`);
+	}
+	return {
+		repoLines,
+		failureLines: result.failures.map((failure) => `${failure.repository}: failed: ${failure.error}`)
+	};
+}
+//#endregion
+//#region src/label-sets-file.ts
+/**
+* The specs of one named set in a label-sets file: a JSON object whose keys are set names and
+* whose values are arrays of label specs. Every failure names the file, and all of them happen
+* before any request, so a bad file never leaves a repo half-synced.
+*/
+function readLabelSet(path, setName) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch (error) {
+		throw new FatalError(`Cannot read label-sets file ${path}: ${describeError(error)}`);
+	}
+	let data;
+	try {
+		data = JSON.parse(raw);
+	} catch (error) {
+		throw new FatalError(`Label-sets file ${path} is not valid JSON: ${describeError(error)}`);
+	}
+	const parsed = LabelSetsSchema.safeParse(data);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		const where = issue === void 0 || issue.path.length === 0 ? "(root)" : issue.path.join(".");
+		throw new FatalError(`Label-sets file ${path} is invalid at ${where}: ${issue?.message ?? "unknown error"}`);
+	}
+	const specs = parsed.data[setName];
+	if (specs === void 0) {
+		const known = Object.keys(parsed.data).toSorted().join(", ") || "(none)";
+		throw new FatalError(`Unknown label set "${setName}" in ${path}. Known sets: ${known}`);
+	}
+	return specs;
+}
+//#endregion
+//#region src/labels.ts
+async function runLabelsList(fetcher, conn) {
+	const labels = await fetchAllForgejoLabels(fetcher, conn);
+	return {
+		repository: conn.repository,
+		labels
+	};
+}
+function renderList(result) {
+	if (result.labels.length === 0) {
+		rootLogger.info(`No labels found in ${result.repository}`);
+		return;
+	}
+	for (const label of result.labels.toSorted((a, b) => a.name.localeCompare(b.name))) {
+		const exclusive = label.exclusive === true ? " [exclusive]" : "";
+		rootLogger.info(`${label.name}${exclusive}  #${label.color ?? ""}  ${label.description ?? ""}`);
+	}
+}
+async function runLabelsSync(params) {
+	const { fetcher, targets, specs, setName, mode, contained } = params;
+	return syncLabelSet({
+		fetcher,
+		targets,
+		specs,
+		setName,
+		mode,
+		contained
+	});
+}
+function renderSync(result) {
+	const { repoLines, failureLines } = syncSummaryLines(result);
+	for (const line of repoLines) rootLogger.info(line);
+	for (const line of failureLines) rootLogger.warn(line);
+}
+//#endregion
+//#region src/commands/labels.ts
+const GITHUB_REFUSAL = "bst-fj labels requires a Forgejo repository";
+const listCommand$1 = defineCommand({
+	meta: {
+		name: "list",
+		description: "List a repository's existing labels"
+	},
+	args: {
+		repo: {
+			type: "string",
+			description: "Target owner/repo (default: this repo)"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit results as JSON instead of a human-readable list"
+		}
+	},
+	async run({ args, rawArgs }) {
+		const base = requireForgejoTarget(process.cwd(), void 0, GITHUB_REFUSAL);
+		const repoNames = parseListFlag(rawArgs, "repo");
+		if (repoNames.length === 0 && listFlagPresent(rawArgs, "repo")) throw new FatalError("--repo was given with no repository name (expected e.g. owner/repo). Refusing rather than falling back to the current repo.");
+		const conn = targetConnection(base, repoNames.at(-1));
+		const result = await runLabelsList(cliFetcher(), conn);
+		if (args.json === true) {
+			createCliOutput(true).json(result);
+			return;
+		}
+		renderList(result);
+	}
+});
+const syncCommand = defineCommand({
+	meta: {
+		name: "sync",
+		description: "Create/update a repo's labels from a named set in a label-sets file (never deletes a label)"
+	},
+	args: {
+		file: {
+			type: "string",
+			required: true,
+			description: "JSON file mapping each set name to an array of label specs"
+		},
+		set: {
+			type: "string",
+			required: true,
+			description: "Label set name, a key of --file"
+		},
+		repo: {
+			type: "string",
+			description: "Target owner/repo. Repeatable (unions); default: this repo"
+		},
+		fleet: {
+			type: "boolean",
+			description: "Target every repo the token can write to, discovered live. Mutually exclusive with --repo"
+		},
+		check: {
+			type: "boolean",
+			description: "Report drift without writing; exits 1 if any label is missing or drifted"
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Report what would change without writing"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit results as JSON instead of a human-readable summary"
+		}
+	},
+	async run({ args, rawArgs }) {
+		const base = requireForgejoTarget(process.cwd(), void 0, GITHUB_REFUSAL);
+		const repoNames = parseListFlag(rawArgs, "repo");
+		if (repoNames.length === 0 && listFlagPresent(rawArgs, "repo")) throw new FatalError("--repo was given with no repository name (expected e.g. owner/repo). Refusing rather than falling back to the current repo.");
+		const fleet = args.fleet === true;
+		if (fleet && repoNames.length > 0) throw new FatalError("--repo and --fleet are mutually exclusive");
+		const specs = readLabelSet(args.file, args.set);
+		const fetcher = cliFetcher();
+		let targets;
+		if (fleet) targets = await resolveFleetTargets(fetcher, base);
+		else if (repoNames.length > 0) targets = repoNames.map((repo) => targetConnection(base, repo));
+		else targets = [base];
+		const mode = resolveSyncMode(args.check === true, args["dry-run"] === true);
+		const result = await runLabelsSync({
+			fetcher,
+			targets,
+			specs,
+			setName: args.set,
+			mode,
+			contained: fleet
+		});
+		if (args.json === true) createCliOutput(true).json(result);
+		else renderSync(result);
+		if (mode === "check" && result.drifted || result.failures.length > 0) process.exitCode = 1;
+	}
+});
+const labelsCommand = defineCommand({
+	meta: {
+		name: "labels",
+		description: "Provision and audit a repository's label definitions from a named label set (sync, list)"
+	},
+	args: { json: {
+		type: "boolean",
+		description: "Emit results as JSON instead of a human-readable summary"
+	} },
+	subCommands: {
+		list: listCommand$1,
+		sync: syncCommand
+	}
+});
+z.object({
+	number: z.number(),
+	html_url: z.string().optional()
+});
+/** Compose a PR's web URL from the connection coordinates. */
+function prWebUrl(conn, prNumber) {
+	return `${conn.serverUrl}/${conn.repository}/pulls/${String(prNumber)}`;
+}
+/** Requested page size. Forgejo clamps it, so a short page is NOT an end signal -- only an empty
+* one is (same reasoning as `searchForgejoIssues`). */
+const PULLS_PAGE_SIZE = 50;
+/** Hard cap on pages, so a misbehaving server cannot spin a caller forever. */
+const PULLS_MAX_PAGES = 20;
+/**
+* Find the open PR with the given head branch -- its number and its base ref -- or null.
+*
+* Filters client-side by head.ref rather than relying on Forgejo's query parameter filtering,
+* which behaves inconsistently. `base` is required on the wire: the endpoint serves full
+* pull-request objects (the same shape {@link getPrRefs} reads off `/pulls/<n>`), and a caller
+* reporting a PR's base must fail loudly rather than fall back to a locally guessed one.
+*
+* Paged to an empty page or to {@link PULLS_MAX_PAGES}, sharing both constants with
+* {@link listPulls} rather than trusting the server's default page size. The walk ends on an
+* empty page rather than a short one because Forgejo clamps `limit`, so a short page may be the
+* clamp rather than the end (same reasoning `listPulls` and `searchForgejoIssues` already
+* record). Exhausting the cap throws rather than returning `null`: this function's answer is a
+* yes/no, so a truncated read does not degrade it, it inverts it into precisely the value that
+* makes `pr:create` and `openWipPr` write a duplicate to the forge -- unlike `listPulls`, whose
+* caller reads a whole set and can tolerate a truncated tail.
+*/
+async function findOpenPrEntry(executor, conn, head, signal = null) {
+	let capped = false;
+	const match = (await listPulls(executor, conn, {
+		state: "open",
+		stopWhen: (pr) => pr.headRef === head,
+		onPageCap: () => {
+			capped = true;
+		},
+		signal
+	})).find((pr) => pr.headRef === head);
+	if (match !== void 0) {
+		if (match.baseRef === null) throw new UnexpectedError(`Open PR #${String(match.number)} on ${conn.repository} carries no base branch`);
+		return {
+			number: match.number,
+			base: match.baseRef
+		};
+	}
+	if (capped) throw new FatalError(`Open PR lookup on ${conn.repository} for head "${head}" hit the ${String(PULLS_MAX_PAGES)}-page cap without finding it or reaching an empty page; a truncated read here reads as "no open PR" and makes a caller create a duplicate`);
+	return null;
+}
+/**
+* The open PR number for a head branch, or null. A wrapper over {@link findOpenPrEntry}: most
+* callers only ask whether a PR exists, and one fetch with one schema serves both questions.
+*/
+async function findOpenPr(executor, conn, head, signal = null) {
+	return (await findOpenPrEntry(executor, conn, head, signal))?.number ?? null;
+}
+const PullListItemSchema = z.object({
+	number: z.number(),
+	title: z.string().nullish(),
+	head: z.object({ ref: z.string() }),
+	base: z.object({ ref: z.string() }).nullish(),
+	state: z.enum(["open", "closed"]),
+	merged: z.boolean().nullish(),
+	merged_at: z.string().nullish(),
+	html_url: z.string().nullish(),
+	draft: z.boolean().nullish(),
+	user: z.object({ login: z.string().nullish() }).nullish(),
+	updated_at: z.string().nullish(),
+	labels: z.array(z.object({ name: z.string() })).nullish()
+});
+/**
+* Every pull request -- open, merged, and closed-unmerged -- by default, via `state=all`; a caller
+* may narrow the read with {@link ListPullsOptions.state}. Paged to an empty page or to
+* {@link PULLS_MAX_PAGES}, whichever comes first.
+*
+* The one paged PR listing: `branch:prune` reads it to completion because it decides over the whole
+* set, and the agent agent passes `stopWhen` to answer "does a pull request already exist on this
+* head, in any state" at the cost of one page in the common case (Forgejo lists recently touched
+* pull requests first). That existence question is the reason this exists alongside
+* {@link findOpenPr}: a caller deciding whether to CREATE must not ask an open-only question, since
+* a closed pull request is still one that exists and creating over it mints a fresh one on every
+* re-entry.
+*
+* Hitting the page cap **warns** rather than returning quietly. A silently truncated read is
+* indistinguishable from "no such pull request", which is precisely the answer that makes a caller
+* create a duplicate.
+*/
+async function listPulls(executor, conn, options = {}) {
+	const headers = { Authorization: `token ${conn.token}` };
+	const pulls = [];
+	for (let page = 1; page <= PULLS_MAX_PAGES; page++) {
+		options.signal?.throwIfAborted();
+		const params = new URLSearchParams({
+			state: options.state ?? "all",
+			limit: String(PULLS_PAGE_SIZE),
+			page: String(page)
+		});
+		if (options.sort !== void 0) params.set("sort", options.sort);
+		const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/pulls?${params.toString()}`;
+		const res = await executor.fetch(url, {
+			headers,
+			signal: options.signal ?? null
+		});
+		if (!res.ok) await throwForgejoFailure(res, {
+			verb: "list PRs",
+			resource: conn.repository
+		});
+		const parsed = PullListItemSchema.array().safeParse(await res.json());
+		if (!parsed.success) throw new UnexpectedError(`Unexpected PR list response: ${parsed.error.message}`);
+		const items = parsed.data.map((pr) => ({
+			number: pr.number,
+			title: pr.title ?? null,
+			headRef: pr.head.ref,
+			baseRef: pr.base?.ref ?? null,
+			state: pr.state,
+			merged: pr.merged ?? pr.merged_at != null,
+			mergedAt: pr.merged_at ?? null,
+			url: pr.html_url ?? null,
+			draft: pr.draft ?? null,
+			author: pr.user?.login ?? null,
+			updatedAt: pr.updated_at ?? null,
+			labels: (pr.labels ?? []).map((label) => label.name)
+		}));
+		pulls.push(...items);
+		if (items.length === 0) break;
+		if (options.stopWhen !== void 0 && items.some(options.stopWhen)) break;
+		if (options.limit !== void 0 && pulls.length >= options.limit) break;
+		if (page === PULLS_MAX_PAGES) {
+			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?.();
+		}
+	}
+	return pulls;
+}
+z.object({ body: z.string().nullish() });
+/**
+* Read one projection of `.../pulls/<n>` -- the shared body of every single-PR GET below.
+*
+* They all issue the identical request and differ only in which slice of the payload they need,
+* so the schema and a `what` noun are the parameters; `what` spells both the failure verb
+* ("read PR head") and the schema-mismatch message ("Unexpected PR head response"), which keeps
+* an error naming the field the caller actually asked for. Reading the whole payload and picking
+* fields off it in the caller is the tempting alternative and is worse: a narrow schema is what
+* makes a forge that stops serving a field fail loudly here, rather than surfacing `undefined`
+* somewhere further out.
+*
+* Note this is the *pulls* endpoint, which is not interchangeable with the issues endpoint
+* `getPrBody` uses -- only this one carries `head`, `base`, and `draft`.
+*/
+async function readPrField(executor, conn, prNumber, schema, what) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/pulls/${String(prNumber)}`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (!res.ok) await throwForgejoFailure(res, {
+		verb: `read PR ${what}`,
+		resource: `#${String(prNumber)}`
+	});
+	const parsed = schema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected PR ${what} response: ${parsed.error.message}`);
+	return parsed.data;
+}
+z.object({ head: z.object({ ref: z.string() }) });
+z.object({
+	head: z.object({ ref: z.string() }),
+	base: z.object({ ref: z.string() })
+});
+const PrBranchRefRawSchema = z.object({
+	ref: z.string(),
+	sha: z.string(),
+	repo: z.object({ full_name: z.string() }).nullish()
+});
+const PrDetailSchema = z.object({
+	head: PrBranchRefRawSchema,
+	base: PrBranchRefRawSchema,
+	draft: z.boolean(),
+	merged: z.boolean(),
+	mergeable: z.boolean().nullish(),
+	state: z.string()
+});
+/**
+* Map a validated pulls-endpoint payload to {@link PrDetail}: an absent `repo` becomes `null`
+* rather than an invented repository name, and an absent `mergeable` becomes `null` rather than
+* `false` -- both forges can omit or null this field while still computing it.
+*/
+function normalizePrDetail(data) {
+	return {
+		head: {
+			ref: data.head.ref,
+			sha: data.head.sha,
+			repo: data.head.repo?.full_name ?? null
+		},
+		base: {
+			ref: data.base.ref,
+			sha: data.base.sha,
+			repo: data.base.repo?.full_name ?? null
+		},
+		draft: data.draft,
+		merged: data.merged,
+		mergeable: data.mergeable ?? null,
+		state: data.state
+	};
+}
+/**
+* Fetch a PR's head and base branch details, draft/merged state, and tri-state mergeability in one
+* `/pulls/<n>` read -- the projection `bst issue:view` reports as its `pr` block, so a review
+* workflow that starts from a PR number reaches its branch without a `git ls-remote` reverse
+* lookup. `ref`/`sha`/`draft`/`merged` are required on the wire: a forge that stops serving one of
+* them should fail loudly here rather than surface `undefined` further out (see `readPrField`'s
+* doc comment). `mergeable` and `repo` are nullish because absent and explicitly-null are both
+* real answers.
+*/
+async function getForgejoPrDetail(executor, conn, prNumber) {
+	return normalizePrDetail(await readPrField(executor, conn, prNumber, PrDetailSchema, "detail"));
+}
+z.object({
+	title: z.string(),
+	body: z.string().nullish()
+});
+z.object({
+	title: z.string(),
+	draft: z.boolean()
+});
+const PullReviewSchema = z.object({
+	id: z.number(),
+	body: z.string(),
+	commit_id: z.string().nullish(),
+	user: z.object({ login: z.string() }).nullish(),
+	html_url: z.string().nullish(),
+	submitted_at: z.string().nullish()
+});
+z.array(PullReviewSchema);
+z.object({ head: z.object({ sha: z.string() }) });
+const PullReviewCommentSchema = z.object({
+	body: z.string(),
+	path: z.string().optional(),
+	diff_hunk: z.string().optional(),
+	user: z.object({ login: z.string() }).nullish()
+});
+z.array(PullReviewCommentSchema);
+//#endregion
+//#region src/pr-checks.ts
+/**
+* `bst-fj pr:checks` -- the PR CI verdict, read live off the PR's current head SHA over the same
+* `@bensandee/forgejo` primitive the automerge gate uses (`readCommitChecks`), so the agent and
+* the CLI cannot drift about what green means.
+*
+* This module owns the whole runner (`runPrChecks`); `commands/pr-checks.ts` is the thin citty
+* definition over it. Resolution -- turning `--pr`/`--branch`/`--repo`/the current checkout into a
+* PR number, a live `ForgejoConnection`, and that PR's detail -- is `resolvePrChecksTarget` below,
+* kept as its own function because it is where every refusal lives: no PR for a branch, a
+* `--repo` with neither `--pr` nor `--branch`, or a github.com target. Reads GET-only, at every
+* step, under every flag.
+*/
+/**
+* Resolve `--pr`/`--branch`/`--repo`/the current checkout into a PR number, a live
+* `ForgejoConnection`, and that PR's detail -- the whole set of ways this command can be told "no"
+* before it ever reads a check.
+*
+* Order: `--pr` (a number or URL, the URL carrying its own repository) wins; otherwise `--branch`
+* resolves through {@link findOpenPr}; otherwise the current checkout's branch does, through the
+* same lookup. `--repo` requires an explicit `--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. A github.com target refuses before any request -- GitHub Actions publishes
+* check runs, not commit statuses, so a combined-status read against it would confidently report
+* `no-status` for a green PR.
+*/
+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.");
+	const conn = requireForgejoTarget(options.cwd, resolveIssueTarget(ref.target, options.repo), "pr:checks is Forgejo-only: GitHub Actions publishes check runs, not commit statuses, so a combined-status read against a github.com PR would confidently report `no-status` for a green PR. Use `gh pr checks --watch` instead.");
+	let prNumber;
+	if (ref.number !== void 0) prNumber = ref.number;
+	else {
+		const branch = options.branch ?? resolveCurrentBranch({
+			cwd: options.cwd,
+			git: options.git,
+			env: options.env
+		});
+		if (branch === void 0) throw new FatalError("Could not determine the current branch (detached HEAD, or not a git repository) -- pass --branch or --pr explicitly.");
+		const found = await findOpenPr(fetcher, conn, branch);
+		if (found === null) throw new FatalError(`No open pull request found for branch "${branch}".`);
+		prNumber = found;
+	}
+	const detail = await getForgejoPrDetail(fetcher, conn, prNumber);
+	return {
+		prNumber,
+		conn,
+		url: prWebUrl(conn, prNumber),
+		detail
+	};
+}
+/**
+* Read the base branch's current head checks and report which normalized names read red there --
+* the baseline a PR head's own red checks are compared against. Matched by normalized `name`, not
+* raw `context`: Forgejo folds the triggering event into the context, so the same job reads
+* `CI / check (pull_request)` on the PR and `CI / check (push)` on `main`, and exact-string
+* matching would fail in precisely the case this annotation exists for.
+*
+* `baseline: false` (`--no-baseline`) skips both reads entirely and reports `"skipped"`. Any other
+* failure to establish a clean baseline -- the branch-head read failing, the status read failing,
+* an unparseable status body, or zero statuses on the base head -- reports `"unavailable"` with a
+* `reason`, never `"read"` with an empty `redNames`: an empty list must mean "read, and none were
+* red", not "could not tell".
+*
+* Exported for the agent's automerge sweep, which annotates its CI-red hold with the same
+* baseline.
+*/
+async function readBaseline(fetcher, conn, baseRef, enabled) {
+	if (!enabled) return {
+		ref: baseRef,
+		status: "skipped",
+		redNames: []
+	};
+	const unavailable = (reason, sha) => sha === void 0 ? {
+		ref: baseRef,
+		status: "unavailable",
+		reason,
+		redNames: []
+	} : {
+		ref: baseRef,
+		sha,
+		status: "unavailable",
+		reason,
+		redNames: []
+	};
+	let baseSha;
+	try {
+		baseSha = await getBranchHeadSha(fetcher, conn, baseRef);
+	} catch (error) {
+		return unavailable(describeError(error));
+	}
+	let baseChecks;
+	try {
+		baseChecks = await readCommitChecks(fetcher, conn, baseSha);
+	} catch (error) {
+		return unavailable(describeError(error), baseSha);
+	}
+	if (!baseChecks.parsed) return unavailable("The base branch's commit status response did not match the shape this build expects.", baseSha);
+	if (baseChecks.contexts.length === 0) return unavailable(`No checks have been posted for ${baseRef}'s current head (${baseSha}).`, baseSha);
+	const redNames = baseChecks.contexts.filter((check) => check.verdict === "red").map((check) => check.name);
+	return {
+		ref: baseRef,
+		sha: baseSha,
+		status: "read",
+		redNames
+	};
+}
+/**
+* Assemble a {@link PrChecksReport} from a PR detail read, a commit-status read, and the
+* once-per-invocation baseline -- the one place that shape is built, so the read-once path and
+* every `--wait` exit (settled, `head-moved`, `timeout`, retry-budget exhaustion) produce
+* identically-shaped reports.
+*/
+function buildReport(detail, checks, ctx, extras = {}) {
+	const { target, baseline, notices, waited, elapsedMs } = ctx;
+	const preexistingNames = new Set(baseline.status === "read" ? baseline.redNames : []);
+	const status = extras.statusOverride ?? classifyBaseStatus(checks);
+	const report = {
+		pr: target.prNumber,
+		repository: target.conn.repository,
+		url: target.url,
+		state: detail.state,
+		headSha: detail.head.sha,
+		baseRef: detail.base.ref,
+		status,
+		settled: isSettled(checks),
+		combinedState: checks.state,
+		waited,
+		elapsedMs,
+		checks: checks.contexts.map((check) => ({
+			...check,
+			preexisting: check.verdict === "red" && preexistingNames.has(check.name)
+		})),
+		baseline,
+		notices
+	};
+	if (extras.detailOverride !== void 0) report.detail = extras.detailOverride;
+	else if (status === "unparseable") report.detail = "The commit status response did not match the shape this build expects.";
+	if (extras.previousHeadSha !== void 0) report.previousHeadSha = extras.previousHeadSha;
+	return report;
+}
+/**
+* Poll the PR's live head until its checks settle, following the spec's poll contract: each poll
+* re-reads the PR detail (never pinning the head SHA from an earlier poll) and then that head's
+* commit status -- exactly two reads. A changed head SHA ends the wait immediately as
+* `head-moved`, carrying both SHAs, rather than re-pinning and continuing: a verdict for a commit
+* that is no longer head is meaningless, and following a rebasing head would let the wait outlive
+* its own timeout. Settlement additionally requires a **quiet interval**: two consecutive polls,
+* one interval apart, both settled with the same set of contexts -- a job that has posted no status
+* yet is invisible to this endpoint, so a workflow registering moments after another finished would
+* otherwise be reported settled before it ever ran. A red check never short-circuits the wait; the
+* point of `--wait` is a complete report. Up to {@link RETRY_BUDGET} consecutive failed or
+* unparseable status reads are absorbed (the counter resets on any good read) before the wait gives
+* up as `unparseable`; a timeout still reports whatever was last observed. The per-poll PR-detail
+* read carries its own budget of the same size, exhausting into a rethrow.
+*/
+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;
+		}
+		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;
+	}
+}
+/**
+* Read the PR's current head SHA's checks and produce a report -- classified into
+* {@link PrChecksStatus}, over one combined-status read by default or, with `options.wait`, over
+* {@link waitForSettledChecks}'s poll loop. Never touches `process.exitCode` and never prints: that
+* is `commands/pr-checks.ts`'s job, which also relays `report.notices` through `CliOutput.notice`
+* and strips it before emitting the JSON payload.
+*/
+async function runPrChecks(fetcher, options) {
+	const timings = options.wait === true ? resolvePollTimings(options) : void 0;
+	const target = await resolvePrChecksTarget(fetcher, options);
+	const notices = [];
+	const closed = target.detail.merged || target.detail.state !== "open";
+	if (target.detail.merged) notices.push(`PR #${String(target.prNumber)} is merged -- reporting its last checks rather than a live wait.`);
+	else if (target.detail.state !== "open") notices.push(`PR #${String(target.prNumber)} is closed (not merged) -- reporting its last checks rather than a live wait.`);
+	const baseline = await readBaseline(fetcher, target.conn, target.detail.base.ref, options.baseline ?? true);
+	if (timings !== void 0 && !closed) return waitForSettledChecks(fetcher, target, baseline, notices, {
+		...timings,
+		sleep: options.sleep ?? sleep,
+		now: options.now ?? Date.now
+	});
+	const checks = await readCommitChecks(fetcher, target.conn, target.detail.head.sha);
+	pushDisagreementNotice(notices, target.detail.head.sha, checks);
+	return buildReport(target.detail, checks, {
+		target,
+		baseline,
+		notices,
+		waited: false,
+		elapsedMs: 0
+	});
+}
+/**
+* The baseline summary clause, e.g. `3 red, 1 of them already red on main` -- present only when
+* the baseline was actually read and at least one check is red. An unavailable or skipped
+* baseline never earns a clause: saying nothing is the honest answer when "how many were
+* pre-existing" cannot be established, never an implied zero.
+*/
+function baselineClause(report) {
+	if (report.baseline.status !== "read") return null;
+	const redChecks = report.checks.filter((check) => check.verdict === "red");
+	if (redChecks.length === 0) return null;
+	const preexistingCount = redChecks.filter((check) => check.preexisting).length;
+	return `${String(redChecks.length)} red, ${String(preexistingCount)} of them already red on ` + report.baseline.ref;
+}
+/**
+* Render a `pr:checks` report as text: one line per check (its state, context and description,
+* with the target URL appended only for a red check -- the line a human is about to go read), then
+* a summary line carrying the head SHA, the verdict, the baseline clause when there is one, and
+* the PR URL.
+*/
+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 summaryParts = [`head ${report.headSha.slice(0, 12)}: ${report.status}`];
+	const clause = baselineClause(report);
+	if (clause !== null) summaryParts.push(clause);
+	summaryParts.push(report.url);
+	lines.push(summaryParts.join(" -- "));
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/pr-checks.ts
+const prChecksCommand = defineCommand({
+	meta: {
+		name: "pr:checks",
+		description: "Read a PR's CI verdict off its current head SHA, over the same combined-status read the automerge gate uses -- optionally --wait for it to settle. It runs nothing locally: it reads what the forge's CI already said about a PR."
+	},
+	args: {
+		pr: {
+			type: "string",
+			description: "PR number or URL (default: the current branch's open PR)"
+		},
+		branch: {
+			type: "string",
+			description: "Resolve the open PR whose head is this branch"
+		},
+		repo: {
+			type: "string",
+			description: "Target repository (requires --pr or --branch)"
+		},
+		wait: {
+			type: "boolean",
+			description: "Poll until every check for the head SHA has settled"
+		},
+		timeout: {
+			type: "string",
+			description: "--wait's give-up duration, e.g. 20m (default: 20m). Checked once per poll, so a wait can run up to one --interval past it."
+		},
+		interval: {
+			type: "string",
+			description: "--wait's poll interval, e.g. 15s (default: 15s, floored at 5s)"
+		},
+		baseline: {
+			type: "boolean",
+			default: true,
+			description: "Also read the base branch's checks, to mark which red checks are pre-existing. --no-baseline skips both reads."
+		},
+		json: {
+			type: "boolean",
+			description: "Emit the machine-readable report on stdout"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug output"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const report = await runPrChecks(cliFetcher(), {
+			cwd: process.cwd(),
+			pr: args.pr,
+			branch: args.branch,
+			repo: args.repo,
+			wait: args.wait === true,
+			timeout: args.timeout,
+			interval: args.interval,
+			baseline: args.baseline
+		});
+		const { notices, ...payload } = report;
+		for (const notice of notices) out.notice(notice);
+		out.json(payload);
+		out.text(renderPrChecks(report));
+		process.exitCode = report.status === "green" ? 0 : 1;
+	}
+});
+//#endregion
+//#region src/pr-list.ts
+/**
+* `bst-fj pr:list` -- a read-only, Forgejo-only pull request listing over the shared `listPulls`
+* pager (`@bensandee/forgejo/pr`), so a duplicate-work check needs no raw API call. GitHub-only
+* PR listing already has a first-class tool (`gh pr list`), the same precedent `pr:checks`
+* follows for the same structural reason.
+*/
+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;
+}
+/**
+* List a repository's pull requests, most recently updated first, sliced to `--limit`. Refuses a
+* github.com target before any fetch -- `gh pr list` already serves GitHub, first-class.
+*/
+async function runPrList(fetcher, options) {
+	const state = parseState(options.state);
+	const limit = parseLimit(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 = [];
+	return {
+		pulls: (await listPulls(fetcher, conn, {
+			state,
+			sort: "recentupdate",
+			limit,
+			onPageCap: () => {
+				notices.push("PR listing hit the page cap before an empty page; results may be truncated.");
+			}
+		})).slice(0, limit),
+		notices
+	};
+}
+function statusLabel(pr) {
+	if (pr.merged) return "merged";
+	if (pr.draft === true) return `${pr.state}/draft`;
+	return pr.state;
+}
+/** Human-readable rendering: one line per PR, most recently updated first. */
+function renderPrList(result) {
+	if (result.pulls.length === 0) return "No pull requests.";
+	return result.pulls.map((pr) => {
+		const branches = `${pr.headRef} -> ${pr.baseRef ?? "?"}`;
+		const labels = pr.labels.length === 0 ? "" : ` [${pr.labels.join(", ")}]`;
+		const url = pr.url === null ? "" : ` ${pr.url}`;
+		return `#${String(pr.number)} ${statusLabel(pr)} ${branches}: ${pr.title ?? "(no title)"}${labels}${url}`;
+	}).join("\n");
+}
+//#endregion
+//#region src/commands/pr-list.ts
+const prListCommand = defineCommand({
+	meta: {
+		name: "pr:list",
+		description: "List a repository's pull requests (Forgejo-only; use gh pr list on GitHub)"
+	},
+	args: {
+		state: {
+			type: "string",
+			default: "open",
+			description: "open | closed | all"
+		},
+		limit: {
+			type: "string",
+			default: "30",
+			description: "Maximum pull requests to return"
+		},
+		repo: {
+			type: "string",
+			description: "Repository URL (default: this repo)"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit JSON on stdout"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug output"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const result = await runPrList(cliFetcher(), {
+			cwd: process.cwd(),
+			state: args.state,
+			limit: args.limit,
+			repo: args.repo ?? void 0
+		});
+		for (const notice of result.notices) out.notice(notice);
+		out.json({ pulls: result.pulls });
+		out.text(renderPrList(result));
+	}
+});
+//#endregion
+//#region ../forgejo/src/releases.ts
+/** Patient-repair attempts (delete frozen release, wait, retry) before escalating. */
+const SETTLE_ATTEMPTS = 4;
+/** Base backoff between patient-repair attempts; doubles each attempt. */
+const SETTLE_BASE_DELAY_MS = 2e3;
+/** Cap on a single patient-repair backoff. */
+const SETTLE_MAX_DELAY_MS = 16e3;
+const ReleaseSchema = z.object({
+	id: z.number(),
+	tag_name: z.string().optional(),
+	created_at: z.string().optional(),
+	published_at: z.string().optional(),
+	html_url: z.string().nullish(),
+	prerelease: z.boolean().optional()
+});
+/**
+* Detect the signature of a broken Forgejo release: a `created_at` that maps to
+* the Unix epoch (`created_unix = 0`).
+*
+* Forgejo auto-creates a "tag placeholder" release row when a tag is pushed.
+* If our `POST /releases` races that placeholder, Forgejo promotes the
+* placeholder in place (flipping `is_tag` to false) **without** resetting
+* `created_unix`, leaving a published release stuck at the epoch. Such a
+* release sorts as the oldest, so `/releases/latest` never returns it.
+*
+* The epoch renders as `1969-12-31T18:00:00-06:00` or `1970-01-01T00:00:00Z`
+* depending on the server timezone; both parse to `<= 0` ms. A missing or
+* unparseable date is treated as broken too, so the caller repairs rather than
+* ships it.
+*/
+function isEpochReleaseDate(date) {
+	if (!date) return true;
+	const ms = new Date(date).getTime();
+	return Number.isNaN(ms) || ms <= 0;
+}
+/**
+* Fetch the Forgejo release for a tag, returning the parsed object or `null`
+* when no release exists (404). Unlike {@link findRelease}, this exposes the
+* release `id` and dates so callers can inspect/repair an epoch-dated release.
+*/
+async function getReleaseByTag(executor, conn, tag) {
+	const encodedTag = encodeURIComponent(tag);
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases/tags/${encodedTag}`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (res.status === 404) return null;
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "check release",
+		resource: tag
+	}));
+	const parsed = ReleaseSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected release response: ${parsed.error.message}`);
+	return parsed.data;
+}
+/**
+* Create a Forgejo release for a given tag.
+*
+* When `options.target` (a commit SHA or branch) is provided and the tag does
+* not yet exist, Forgejo **creates the tag itself** from that commitish and
+* stamps `created_unix = now` synchronously -- sidestepping the buggy async
+* stamping of a pushed tag. The created tag is lightweight.
+*/
+async function createRelease(executor, conn, tag, options = {}) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases`;
+	const payload = {
+		tag_name: tag,
+		name: tag,
+		body: `Published ${tag}`,
+		prerelease: options.prerelease ?? false
+	};
+	if (options.target) payload["target_commitish"] = options.target;
+	const res = await executor.fetch(url, {
+		method: "POST",
+		headers: {
+			Authorization: `token ${conn.token}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(payload)
+	});
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "create release",
+		resource: tag
+	}));
+}
+/**
+* Delete a git tag from the repository (`DELETE /repos/{repo}/tags/{tag}`).
+*
+* Used by {@link ensureRelease} to take tag ownership away from the buggy
+* push-ingestion path: once the tag is gone, recreating the release with a
+* `target_commitish` makes Forgejo create the tag fresh with a real date. A 404
+* (already gone) is treated as success.
+*/
+async function deleteTag(executor, conn, tag) {
+	const encodedTag = encodeURIComponent(tag);
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/tags/${encodedTag}`;
+	const res = await executor.fetch(url, {
+		method: "DELETE",
+		headers: { Authorization: `token ${conn.token}` }
+	});
+	if (!res.ok && res.status !== 404) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "delete tag",
+		resource: tag
+	}));
+}
+const TagSchema = z.looseObject({
+	name: z.string(),
+	id: z.string(),
+	commit: z.object({ sha: z.string().regex(/^[0-9a-f]{40}$/) })
+});
+/**
+* The commit a tag points at (`GET /repos/{repo}/tags/{tag}`), or `null` when the forge has no
+* such tag. For an annotated tag, `id` and `commit.url` hold the tag object's SHA; only
+* `commit.sha` is the commit, so that is the field read.
+*/
+async function getTagCommit(executor, conn, tag) {
+	const encodedTag = encodeURIComponent(tag);
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/tags/${encodedTag}`;
+	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+	if (res.status === 404) return null;
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "read tag",
+		resource: tag
+	}));
+	const parsed = TagSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected tag response: ${parsed.error.message}`);
+	return parsed.data.commit.sha;
+}
+/**
+* Delete a Forgejo release by id. Does **not** delete the underlying git tag
+* (no `delete_tag` query param) -- the tag is the source of truth, and a
+* subsequent `POST /releases` relies on it still existing to insert a fresh
+* row with `created_unix = now`. A 404 (already gone) is treated as success.
+*/
+async function deleteRelease(executor, conn, releaseId) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases/${String(releaseId)}`;
+	const res = await executor.fetch(url, {
+		method: "DELETE",
+		headers: { Authorization: `token ${conn.token}` }
+	});
+	if (!res.ok && res.status !== 404) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "delete release",
+		resource: String(releaseId)
+	}));
+}
+/**
+* Flag an existing Forgejo release as a prerelease (`PATCH /repos/{repo}/releases/{id}`).
+*
+* {@link ensureRelease} uses this on the path where the release was already there, and so does the
+* `release:changesets` rerun, so a rerun over a release an earlier unflagged run created can still
+* keep the forge's Latest pointer off a prerelease. It sets the flag and never clears it, which is
+* why the body is fixed at
+* `{ prerelease: true }` and why the write is a fixed-field PATCH: `{ idempotent: true }`, the
+* convention every other fixed-field PATCH in this package passes (see `updateForgejoComment` in
+* `issue-comments.ts`), because a re-sent convergent PATCH is a no-op.
+*
+* The JSON body is {@link createRelease}'s shape (one `Authorization` header plus a content type),
+* but unlike {@link deleteRelease} against the same URL a 404 is **not** tolerated here: a row that
+* vanished mid-run means the flag was not applied, and the caller must know.
+*/
+async function markReleasePrerelease(executor, conn, releaseId, tag) {
+	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/releases/${String(releaseId)}`;
+	const res = await executor.fetch(url, {
+		method: "PATCH",
+		headers: {
+			Authorization: `token ${conn.token}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ prerelease: true })
+	}, { idempotent: true });
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "edit release",
+		resource: tag
+	}));
+}
+/**
+* Ensure a Forgejo release exists for a tag **with a real created date**.
+*
+* Forgejo stamps a pushed annotated tag's date *asynchronously*; a release
+* creation that races that stamp freezes the row at the Unix epoch (see
+* {@link isEpochReleaseDate}) -- a published-but-invisible release, because
+* `/releases/latest` sorts by date. The failure is intermittent. The repair:
+*
+* 1. A real-dated release already exists -> `"exists"`.
+* 2. Otherwise create the release and read it back. On epoch, delete the frozen
+*    release and wait (increasing backoff) for Forgejo to settle the tag's date,
+*    then retry -- **preserving the pushed (annotated) tag**. The frozen release
+*    is never deleted-and-left-empty.
+* 3. If the date still never settles and a `target` commit is known, delete the
+*    tag and recreate the release with `target_commitish` so **Forgejo creates
+*    the tag itself**, stamped `now`. The tag becomes lightweight. -> `"repaired"`.
+* 4. If nothing yields a real date, leave a visible release row (rather than only
+*    an invisible tag) and throw loudly.
+*
+* Returns `{ status, release }` -- see {@link EnsureReleaseOutcome}.
+*/
+async function ensureRelease(executor, conn, tag, options = {}) {
+	const attempts = options.attempts ?? SETTLE_ATTEMPTS;
+	const baseDelayMs = options.baseDelayMs ?? SETTLE_BASE_DELAY_MS;
+	const existing = await getReleaseByTag(executor, conn, tag);
+	if (existing && !isEpochReleaseDate(existing.created_at)) {
+		if (options.prerelease === true && existing.prerelease === false) await markReleasePrerelease(executor, conn, existing.id, tag);
+		return {
+			status: "exists",
+			release: releaseRef(existing)
+		};
+	}
+	let current = existing;
+	let repairing = false;
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		if (current && isEpochReleaseDate(current.created_at)) {
+			await deleteRelease(executor, conn, current.id);
+			current = null;
+			repairing = true;
+			await settleBackoff(attempt, baseDelayMs);
+		}
+		try {
+			await createRelease(executor, conn, tag, {
+				target: options.target,
+				prerelease: options.prerelease
+			});
+		} catch (error) {
+			const raced = await getReleaseByTag(executor, conn, tag);
+			if (raced && !isEpochReleaseDate(raced.created_at)) return {
+				status: "race",
+				release: releaseRef(raced)
+			};
+			current = raced;
+			if (attempt >= attempts) break;
+			log.warn(`Release creation attempt ${String(attempt)}/${String(attempts)} failed: ${describeError(error)}`);
+			await settleBackoff(attempt, baseDelayMs);
+			continue;
+		}
+		current = await getReleaseByTag(executor, conn, tag);
+		if (current && !isEpochReleaseDate(current.created_at)) return {
+			status: repairing ? "repaired" : "created",
+			release: releaseRef(current)
+		};
+		if (attempt < attempts) log.warn(`Release for ${tag} came back epoch-dated (attempt ${String(attempt)}/${String(attempts)}) -- waiting for Forgejo to settle the tag's date before retrying`);
+	}
+	const recreated = options.target ? await recreateTagViaApi(executor, conn, tag, {
+		target: options.target,
+		prerelease: options.prerelease,
+		current,
+		attempts,
+		baseDelayMs
+	}) : null;
+	if (recreated) return {
+		status: "repaired",
+		release: releaseRef(recreated)
+	};
+	throw new TransientError(`Release for ${tag} never got a real (non-epoch) created date after ${String(attempts)} attempts. This is an intermittent Forgejo bug: a pushed tag's date settles asynchronously and a racing release creation freezes it at the Unix epoch (1969/1970). ` + (options.target ? `Recreating the tag via the API did not help -- investigate the server or upgrade Forgejo.` : `Pass the release tag's target commit so the tag can be recreated, or retry the release.`));
+}
+async function recreateTagViaApi(executor, conn, tag, opts) {
+	const { target, prerelease, current, attempts, baseDelayMs } = opts;
+	log.warn(`Release for ${tag} stayed epoch-dated -- recreating the tag via the API so Forgejo stamps a real date (the tag becomes lightweight)`);
+	if (current) await deleteRelease(executor, conn, current.id);
+	await deleteTag(executor, conn, tag);
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		try {
+			await createRelease(executor, conn, tag, {
+				target,
+				prerelease
+			});
+		} catch (error) {
+			if (attempt >= attempts) throw new TransientError(`Release for ${tag} was deleted to repair its epoch date, but recreating it from ${target} failed: ${describeError(error)}. The tag no longer exists on the server -- re-push it (or re-run the release) to restore it.`);
+			await settleBackoff(attempt, baseDelayMs);
+			continue;
+		}
+		const recreated = await getReleaseByTag(executor, conn, tag);
+		if (recreated && !isEpochReleaseDate(recreated.created_at)) return recreated;
+		return null;
+	}
+	return null;
+}
+/**
+* The `{ id, url }` projection of a release row carried back to a caller. A server that omits
+* `html_url` yields `url: null` -- the id is still the row's identity.
+*/
+function releaseRef(release) {
+	return {
+		id: release.id,
+		url: release.html_url ?? null
+	};
+}
+/** Exponential backoff (capped) between patient-repair attempts; a non-positive base is a no-op. */
+async function settleBackoff(attempt, baseDelayMs) {
+	if (baseDelayMs <= 0) return;
+	const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), SETTLE_MAX_DELAY_MS);
+	await new Promise((resolve) => setTimeout(resolve, delay));
+}
+//#endregion
+//#region src/commands/release-create.ts
+const releaseCreateCommand = defineCommand({
+	meta: {
+		name: "release:create",
+		description: "Create a Forgejo release for a tag the forge already has, or with --target, for a new tag created at that commit"
+	},
+	args: {
+		tag: {
+			type: "string",
+			description: "Git tag to create a release for",
+			required: true
+		},
+		prerelease: {
+			type: "boolean",
+			description: "Flag the release as a prerelease, so the forge's Latest pointer skips it",
+			default: false
+		},
+		target: {
+			type: "string",
+			description: "Commit SHA the tag points at (default: read from the forge's tags API). A tag the forge lacks is created at this commit; the epoch-date repair recreates the tag from it."
+		},
+		json: {
+			type: "boolean",
+			description: "Emit the release result as JSON"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const conn = requireForgejoTarget(process.cwd(), void 0, "bst-fj release:create requires a Forgejo repository");
+		if (args.target !== void 0 && args.target.trim() === "") throw new FatalError("--target needs a commit SHA; it was given an empty value.");
+		const fetcher = cliFetcher();
+		const prerelease = args.prerelease === true;
+		const target = args.target ?? await getTagCommit(fetcher, conn, args.tag);
+		if (target === null) throw new FatalError(`Tag ${args.tag} does not exist on ${conn.repository}. Push the tag first, or pass --target <sha> naming the commit it points at.`);
+		const outcome = await ensureRelease(fetcher, conn, args.tag, {
+			target,
+			prerelease
+		});
+		out.json({
+			status: outcome.status,
+			tag: args.tag,
+			target,
+			prerelease,
+			release: outcome.release
+		});
+		if (outcome.status === "exists") rootLogger.info(`Release for ${args.tag} already exists -- skipping`);
+		else rootLogger.info(`Created Forgejo release for ${args.tag}`);
+	}
+});
+//#endregion
+//#region ../forgejo/src/secrets.ts
+const ActionSecretListSchema = z.object({
+	secrets: z.array(z.object({ name: z.string() })),
+	total_count: z.number()
+});
+z.object({ sha1: z.string() });
+/**
+* The forge's own rules for an Actions secret name, mirrored from Forgejo's
+* `models/secret/secret.go` (`ValidateName`). GitHub reserves `GITHUB_` and a
+* leading digit as well, so a name this accepts is usable on both forges.
+*
+* A rejected name is not a soft failure: the API answers `invalid secret name`,
+* so the secret can never be created, and every workflow referencing it
+* resolves `${{ secrets.X }}` to the empty string instead.
+*/
+const NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const FORBIDDEN_PREFIX_PATTERN = /^(FORGEJO_|GITEA_|GITHUB_|[0-9])/i;
+function isValidSecretName(name) {
+	return NAME_PATTERN.test(name) && !FORBIDDEN_PREFIX_PATTERN.test(name);
+}
+/**
+* Set (or overwrite) a Forgejo Actions secret on a repository.
+*
+* Uses PUT which is idempotent -- creates or overwrites.
+*/
+async function setActionSecret(executor, conn, secretName, secretValue) {
+	const [owner, repo] = conn.repository.split("/");
+	const url = `${conn.serverUrl}/api/v1/repos/${owner}/${repo}/actions/secrets/${encodeURIComponent(secretName)}`;
+	const res = await executor.fetch(url, {
+		method: "PUT",
+		headers: {
+			Authorization: `token ${conn.token}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ data: secretValue })
+	});
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "set secret",
+		resource: secretName
+	}));
+}
+/**
+* List Forgejo Actions secret names for a repository.
+*
+* Returns only names -- Forgejo never exposes secret values.
+* Paginates automatically to collect all secrets.
+*/
+async function listActionSecrets(executor, conn) {
+	const [owner, repo] = conn.repository.split("/");
+	const names = [];
+	let page = 1;
+	const limit = 50;
+	for (;;) {
+		const url = `${conn.serverUrl}/api/v1/repos/${owner}/${repo}/actions/secrets?page=${String(page)}&limit=${String(limit)}`;
+		const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+		if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+			verb: "list secrets",
+			resource: `${owner}/${repo}`
+		}));
+		const parsed = ActionSecretListSchema.safeParse(await res.json());
+		if (!parsed.success) throw new UnexpectedError(`Unexpected secrets list response: ${parsed.error.message}`);
+		for (const secret of parsed.data.secrets) names.push(secret.name);
+		if (names.length >= parsed.data.total_count) break;
+		page++;
+	}
+	return names;
+}
+/**
+* Delete a Forgejo Actions secret from a repository.
+*
+* Returns silently on success. Throws on failure (including 404 if the secret doesn't exist).
+*/
+async function deleteActionSecret(executor, conn, secretName) {
+	const [owner, repo] = conn.repository.split("/");
+	const url = `${conn.serverUrl}/api/v1/repos/${owner}/${repo}/actions/secrets/${encodeURIComponent(secretName)}`;
+	const res = await executor.fetch(url, {
+		method: "DELETE",
+		headers: { Authorization: `token ${conn.token}` }
+	});
+	if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+		verb: "delete secret",
+		resource: secretName
+	}));
+}
+//#endregion
+//#region 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) {
+		rootLogger.info(`[dry-run] Would set secret ${config.secretName} on ${config.conn.repository}`);
+		return {
+			status: "would-set",
+			name: config.secretName,
+			repository: config.conn.repository
+		};
+	}
+	await setActionSecret(fetcher, config.conn, config.secretName, config.secretValue);
+	rootLogger.success(`Set secret ${config.secretName}`);
+	return {
+		status: "set",
+		name: config.secretName,
+		repository: config.conn.repository
+	};
+}
+async function runSecretsList(fetcher, config) {
+	const names = await listActionSecrets(fetcher, config.conn);
+	if (names.length === 0) rootLogger.info("No secrets found");
+	else for (const name of names) rootLogger.info(name);
+	return names;
+}
+async function runSecretsDelete(fetcher, config) {
+	if (config.dryRun) {
+		rootLogger.info(`[dry-run] Would delete secret ${config.secretName} from ${config.conn.repository}`);
+		return {
+			status: "would-delete",
+			name: config.secretName,
+			repository: config.conn.repository
+		};
+	}
+	await deleteActionSecret(fetcher, config.conn, config.secretName);
+	rootLogger.success(`Deleted secret ${config.secretName}`);
+	return {
+		status: "deleted",
+		name: config.secretName,
+		repository: config.conn.repository
+	};
+}
+//#endregion
+//#region src/commands/secrets.ts
+/** Read secret value from --body flag or stdin. */
+function readSecretValue(body) {
+	if (body) return body;
+	try {
+		const value = readFileSync("/dev/stdin", "utf-8").trim();
+		if (value.length === 0) throw new FatalError("No secret value provided. Use --body or pipe a value via stdin.");
+		return value;
+	} catch (error) {
+		if (error instanceof FatalError) throw error;
+		throw new FatalError("No secret value provided. Use --body or pipe a value via stdin.");
+	}
+}
+const setCommand = defineCommand({
+	meta: {
+		name: "set",
+		description: "Set a repository secret (reads value from --body or stdin)"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Secret name",
+			required: true
+		},
+		body: {
+			type: "string",
+			description: "Secret value (reads from stdin if omitted)"
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Show what would be done without making API calls"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Enable verbose output"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit results as JSON instead of a human-readable summary"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const conn = requireForgejoTarget(process.cwd(), void 0, "bst-fj secrets requires a Forgejo repository");
+		const fetcher = cliFetcher();
+		const secretValue = readSecretValue(args.body);
+		const result = await runSecretsSet(fetcher, {
+			conn,
+			secretName: args.name,
+			secretValue,
+			dryRun: args["dry-run"] === true
+		});
+		out.json(result);
+	}
+});
+const listCommand = defineCommand({
+	meta: {
+		name: "list",
+		description: "List repository secret names"
+	},
+	args: {
+		verbose: {
+			type: "boolean",
+			description: "Enable verbose output"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit results as JSON instead of a human-readable summary"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const conn = requireForgejoTarget(process.cwd(), void 0, "bst-fj secrets requires a Forgejo repository");
+		const secrets = await runSecretsList(cliFetcher(), { conn });
+		out.json({
+			repository: conn.repository,
+			secrets
+		});
+	}
+});
+const deleteCommand = defineCommand({
+	meta: {
+		name: "delete",
+		description: "Delete a repository secret"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Secret name to delete",
+			required: true
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Show what would be done without making API calls"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Enable verbose output"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit results as JSON instead of a human-readable summary"
+		}
+	},
+	async run({ args }) {
+		const out = createCliOutput(args.json === true);
+		const conn = requireForgejoTarget(process.cwd(), void 0, "bst-fj secrets requires a Forgejo repository");
+		const result = await runSecretsDelete(cliFetcher(), {
+			conn,
+			secretName: args.name,
+			dryRun: args["dry-run"] === true
+		});
+		out.json(result);
+	}
+});
+const secretsCommand = defineCommand({
+	meta: {
+		name: "secrets",
+		description: "Low-level CRUD for individual Forgejo Actions secrets (set, list, delete). Use bst setup:secrets (in @bensandee/tooling) for initial repo onboarding"
+	},
+	args: { json: {
+		type: "boolean",
+		description: "Emit results as JSON instead of a human-readable summary"
+	} },
+	subCommands: {
+		set: setCommand,
+		list: listCommand,
+		delete: deleteCommand
+	}
+});
+//#endregion
+//#region ../forgejo/src/webhooks.ts
+const WebhookSchema = z.object({
+	id: z.number(),
+	type: z.string(),
+	active: z.boolean(),
+	config: z.record(z.string(), z.string()).optional()
+});
+const WebhookListSchema = z.array(WebhookSchema);
+/**
+* Returns a status struct instead of throwing, so it deliberately does not use
+* {@link forgejoErrorMessage} -- the caller branches on `status` rather than
+* catching an error.
+*/
+async function fetchHooks(executor, conn, endpoint) {
+	const res = await executor.fetch(`${conn.serverUrl}/api/v1${endpoint}`, { headers: { Authorization: `token ${conn.token}` } });
+	if (res.status === 401 || res.status === 403) return {
+		status: "unauthorized",
+		httpStatus: res.status
+	};
+	if (!res.ok) {
+		const body = await responseBodyText(res);
+		return {
+			status: "error",
+			httpStatus: res.status,
+			message: `${res.statusText}\n${body}`
+		};
+	}
+	const parsed = WebhookListSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected webhook list response for ${endpoint}: ${parsed.error.message}`);
+	return {
+		status: "ok",
+		hooks: parsed.data
+	};
+}
+/** List system-level webhooks. Requires admin token (read:admin scope). */
+async function listSystemHooks(executor, conn) {
+	return fetchHooks(executor, conn, "/admin/hooks");
+}
+/** List webhooks owned by the authenticated user. Requires read:user scope. */
+async function listUserHooks(executor, conn) {
+	return fetchHooks(executor, conn, "/user/hooks");
+}
+/** List webhooks for an organization. Requires read:organization scope. */
+async function listOrgHooks(executor, conn, org) {
+	return fetchHooks(executor, conn, `/orgs/${encodeURIComponent(org)}/hooks`);
+}
+/** List webhooks for a repository. Requires read:repository + repo admin. */
+async function listRepoHooks(executor, conn, repository) {
+	return fetchHooks(executor, conn, `/repos/${repository}/hooks`);
+}
+const AuthenticatedUserSchema = z.object({ login: z.string() });
+/** Return the login of the authenticated user, or null if the token is invalid. */
+async function getAuthenticatedUser(executor, conn) {
+	const res = await executor.fetch(`${conn.serverUrl}/api/v1/user`, { headers: { Authorization: `token ${conn.token}` } });
+	if (!res.ok) return {
+		ok: false,
+		httpStatus: res.status
+	};
+	const parsed = AuthenticatedUserSchema.safeParse(await res.json());
+	if (!parsed.success) throw new UnexpectedError(`Unexpected /user response: ${parsed.error.message}`);
+	return {
+		ok: true,
+		login: parsed.data.login
+	};
+}
+/**
+* Probe whether the token has admin access by requesting `/admin/users?limit=1`.
+*
+* Returns true on 2xx, false on 401/403. Any other status is treated as not-admin
+* to keep enumeration conservative.
+*/
+async function hasAdminAccess(executor, conn) {
+	return (await executor.fetch(`${conn.serverUrl}/api/v1/admin/users?limit=1`, { headers: { Authorization: `token ${conn.token}` } })).ok;
+}
+const OrgSchema = z.object({ username: z.string() });
+const OrgListSchema = z.array(OrgSchema);
+const PAGE_LIMIT = 50;
+async function paginate(executor, conn, endpoint, verb, extract) {
+	const all = [];
+	let page = 1;
+	const separator = endpoint.includes("?") ? "&" : "?";
+	for (;;) {
+		const url = `${conn.serverUrl}/api/v1${endpoint}${separator}page=${String(page)}&limit=${String(PAGE_LIMIT)}`;
+		const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
+		if (!res.ok) throw new TransientError(await forgejoErrorMessage(res, {
+			verb,
+			resource: `${endpoint} (page ${String(page)})`
+		}));
+		const items = extract(await res.json());
+		all.push(...items);
+		if (items.length < PAGE_LIMIT) break;
+		page++;
+	}
+	return all;
+}
+/**
+* List organizations. When `mode` is "admin", uses `/admin/orgs` (all orgs on
+* the instance). When "user", uses `/user/orgs` (only the token user's orgs).
+*/
+async function listOrgs(executor, conn, mode) {
+	const endpoint = mode === "admin" ? "/admin/orgs" : "/user/orgs";
+	return (await paginate(executor, conn, endpoint, "list orgs", (raw) => {
+		const parsed = OrgListSchema.safeParse(raw);
+		if (!parsed.success) throw new UnexpectedError(`Unexpected ${endpoint} response: ${parsed.error.message}`);
+		return parsed.data;
+	})).map((o) => o.username);
+}
+const RepoSearchSchema = z.object({ data: z.array(z.object({ full_name: z.string() })) });
+/** List repositories visible to the token via `/repos/search`. */
+async function searchRepos(executor, conn) {
+	return (await paginate(executor, conn, "/repos/search", "list repos", (raw) => {
+		const parsed = RepoSearchSchema.safeParse(raw);
+		if (!parsed.success) throw new UnexpectedError(`Unexpected /repos/search response: ${parsed.error.message}`);
+		return parsed.data.data;
+	})).map((r) => r.full_name);
+}
+//#endregion
+//#region src/commands/webhooks.ts
+/** Render a WebhookFetchStatus, logging warnings for unauthorized/error cases. */
+function collectGroup(label, scopeHint, status) {
+	if (status.status === "ok") return status.hooks.length > 0 ? {
+		label,
+		hooks: status.hooks
+	} : null;
+	if (status.status === "unauthorized") {
+		rootLogger.warn(`${label}: HTTP ${String(status.httpStatus)} -- token likely missing scope: ${scopeHint}`);
+		return null;
+	}
+	rootLogger.warn(`${label}: HTTP ${String(status.httpStatus)} ${status.message}`);
+	return null;
+}
+async function runListWebhooks(fetcher, conn) {
+	const userResult = await getAuthenticatedUser(fetcher, conn);
+	if (!userResult.ok) throw new FatalError(`Token is invalid or lacks read:user scope (HTTP ${String(userResult.httpStatus)})`);
+	const user = userResult.login;
+	const isAdmin = await hasAdminAccess(fetcher, conn);
+	const groups = [];
+	const systemGroup = collectGroup("System", "read:admin", await listSystemHooks(fetcher, conn));
+	if (systemGroup) groups.push(systemGroup);
+	const userGroup = collectGroup(`User: ${user}`, "read:user", await listUserHooks(fetcher, conn));
+	if (userGroup) groups.push(userGroup);
+	const orgs = await listOrgs(fetcher, conn, isAdmin ? "admin" : "user");
+	for (const org of orgs) {
+		const orgGroup = collectGroup(`Org: ${org}`, "read:organization", await listOrgHooks(fetcher, conn, org));
+		if (orgGroup) groups.push(orgGroup);
+	}
+	const repos = await searchRepos(fetcher, conn);
+	for (const repo of repos) {
+		const repoGroup = collectGroup(`Repo: ${repo}`, "read:repository + repo admin", await listRepoHooks(fetcher, conn, repo));
+		if (repoGroup) groups.push(repoGroup);
+	}
+	return {
+		user,
+		isAdmin,
+		groups,
+		totalCount: groups.reduce((sum, g) => sum + g.hooks.length, 0)
+	};
+}
+function renderText(inventory, serverUrl) {
+	rootLogger.info(`Forgejo Webhook Inventory -- ${serverUrl}`);
+	rootLogger.info(`Token user: ${inventory.user}${inventory.isAdmin ? " (admin)" : ""}`);
+	if (inventory.groups.length === 0) {
+		rootLogger.info("No webhooks found.");
+		return;
+	}
+	for (const group of inventory.groups) {
+		rootLogger.info(`${group.label} (${String(group.hooks.length)} webhook(s))`);
+		for (const hook of group.hooks) {
+			const url = hook.config?.["url"] ?? "n/a";
+			rootLogger.info(`  id=${String(hook.id)}  type=${hook.type}  active=${String(hook.active)}  url=${url}`);
+		}
+	}
+	rootLogger.info(`Total: ${String(inventory.totalCount)} webhook(s)`);
+	if (inventory.isAdmin) rootLogger.info("Note: User-level webhooks for other accounts cannot be enumerated via the API. Check the admin UI or run this command with tokens from individual user accounts.");
+}
+//#endregion
+//#region src/registry.ts
+const bstFjSubCommands = {
+	"commit:status": commitStatusCommand,
+	labels: labelsCommand,
+	"pr:checks": prChecksCommand,
+	"pr:list": prListCommand,
+	"release:create": releaseCreateCommand,
+	secrets: secretsCommand,
+	webhooks: defineCommand({
+		meta: {
+			name: "webhooks",
+			description: "Enumerate webhooks across a Forgejo instance (system, user, org, and repo levels)"
+		},
+		args: { json: {
+			type: "boolean",
+			description: "Emit results as JSON instead of a human-readable summary"
+		} },
+		async run({ args }) {
+			const conn = requireForgejoTarget(process.cwd(), void 0, "bst-fj webhooks requires a Forgejo repository");
+			const inventory = await runListWebhooks(cliFetcher(), conn);
+			if (args.json) {
+				createCliOutput(true).json(inventory);
+				return;
+			}
+			renderText(inventory, conn.serverUrl);
+		}
+	})
+};
+//#endregion
+//#region src/bin.ts
+applyVerbosityFromArgs(process.argv.slice(2));
+rootLogger.debug(describeEnvFileLoad(envFileLoad));
+setForgejoLogger(rootLogger);
+await runCli({
+	name: "bst-fj",
+	version: BST_FJ_VERSION,
+	description: "Forgejo API commands: labels, secrets, webhooks, releases, PR and commit checks",
+	banner: void 0,
+	subCommands: bstFjSubCommands
+});
+//#endregion
+export {};