@joshuafolkken/kit 1.1229.0 → 1.1240.0

package/scripts/gate/machine-capacity.ts

@@ -0,0 +1,175 @@
+import { readFile } from 'node:fs/promises'
+import { availableParallelism, cpus, totalmem } from 'node:os'
+import { execa } from 'execa'
+
+// What the machine has free right now, read for the core budget's admission (joshuafolkken/kit#3371).
+//
+// **The budget used to be the core count, and that count is not what is free.** The ledger in
+// `core-budget.ts` admits against `availableParallelism()`, so the load it never sees — Claude sessions,
+// node processes that do not pass through `josh`, the window server — ran on top of a budget already
+// spent. On 2026-10-07, three lanes on the 11-core / 18 GB machine reached a load average of 16.8 with
+// 31% of the CPU in the kernel, compressing and swapping 4.4 GB of memory the ledger never counted.
+//
+// **This is a closed loop, not the open-loop formula joshuafolkken/kit#1637 rejected.** That proposal
+// derived a share from the core count up front; this reads what is busy and free at the moment of
+// admission and subtracts only the part the ledger does not already account for.
+//
+// **The busy cores are the CPU-time difference over a short window, not the load average.** The load
+// average trails by a minute, so a gate started just after another one finished would see the finished
+// one's load as external and wait out the decay. `os.cpus()` is one read with no process spawned.
+//
+// **A reading that fails answers undefined, and undefined is the old behavior.** A CI runner or a
+// container — where the host's CPU times are not this process's quota — budgets by the core count and
+// admits without looking at memory, exactly as before.
+
+// The window the busy cores are measured over: long enough that one scheduler tick does not dominate it,
+// short enough that a solo admission is not visibly delayed.
+const SAMPLE_WINDOW_MS = 250
+// **The background a developer machine always carries, which the gate's weights were measured beside.**
+// On 2026-10-07 the 11-core machine idled at about 1.5 cores outside `josh` — Claude sessions 0.55, the
+// window server 0.47, a browser 0.5. The solo gate's weights sum to exactly the core count and were
+// measured with that load present, so only what exceeds it is load the budget must give way to;
+// counting the baseline would defer a solo gate's unit suite on every run.
+const BASELINE_CORES = 2
+const BYTES_PER_MB = 1_048_576
+const KB_PER_MB = 1024
+const PERCENT = 100
+const MEMINFO_PATH = '/proc/meminfo'
+const LINUX_AVAILABLE = /^MemAvailable:\s+(?<kb>\d+) kB/mu
+// The kernel's own memory-pressure figure: the percentage of memory still available, compressible and
+// purgeable pages included — what `os.freemem()` leaves out on macOS, where it reads near zero on a
+// machine with gigabytes to spare.
+const PRESSURE_ARGUMENTS = ['-n', 'kern.memorystatus_level']
+const PRESSURE_LEVEL = /^\s*(?<level>\d+)\s*$/u
+
+interface MachineReading {
+	busy_cores: number | undefined
+	available_mb: number | undefined
+}
+
+// What the ledger's admitted reservations declare — the part of the machine's load already accounted for.
+interface LedgerLoad {
+	cores: number
+	memory_mb: number
+}
+
+interface MachineBudget {
+	cores: number
+	memory_mb: number
+}
+
+interface CpuTimes {
+	busy: number
+	total: number
+}
+
+function cpu_times(): CpuTimes {
+	let busy = 0
+	let idle = 0
+
+	for (const { times } of cpus()) {
+		busy += times.user + times.nice + times.sys + times.irq
+		idle += times.idle
+	}
+
+	return { busy, total: busy + idle }
+}
+
+function busy_cores_between(before: CpuTimes, after: CpuTimes, cores: number): number | undefined {
+	const total = after.total - before.total
+
+	if (total <= 0) return undefined
+
+	return ((after.busy - before.busy) / total) * cores
+}
+
+// `kern.memorystatus_level` → `58`: the share of physical memory still available, as a percentage.
+function parse_darwin_pressure(output: string, total_bytes: number): number | undefined {
+	const level = PRESSURE_LEVEL.exec(output)?.groups?.['level']
+
+	if (level === undefined) return undefined
+
+	return (Number(level) / PERCENT) * (total_bytes / BYTES_PER_MB)
+}
+
+function parse_linux_available(meminfo: string): number | undefined {
+	const kb = LINUX_AVAILABLE.exec(meminfo)?.groups?.['kb']
+
+	return kb === undefined ? undefined : Number(kb) / KB_PER_MB
+}
+
+async function read_available_mb(
+	platform: NodeJS.Platform = process.platform,
+): Promise<number | undefined> {
+	try {
+		if (platform === 'darwin') {
+			const { stdout } = await execa('sysctl', PRESSURE_ARGUMENTS)
+
+			return parse_darwin_pressure(stdout, totalmem())
+		}
+
+		return platform === 'linux'
+			? parse_linux_available(await readFile(MEMINFO_PATH, 'utf8'))
+			: undefined
+	} catch {
+		return undefined
+	}
+}
+
+// A CPU quota narrower than the host makes the host-wide CPU times the wrong machine, so the busy cores
+// are read only where the quota and the host agree.
+function is_unquoted(): boolean {
+	return cpus().length > 0 && cpus().length === availableParallelism()
+}
+
+async function default_sleep(ms: number): Promise<void> {
+	await new Promise<void>((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}
+
+async function read_machine(
+	sleep: (ms: number) => Promise<void> = default_sleep,
+): Promise<MachineReading> {
+	const before = cpu_times()
+	const [available_mb] = await Promise.all([read_available_mb(), sleep(SAMPLE_WINDOW_MS)])
+	const busy_cores = is_unquoted()
+		? busy_cores_between(before, cpu_times(), cpus().length)
+		: undefined
+
+	return { busy_cores, available_mb }
+}
+
+// The busy cores the ledger does not account for, beyond the baseline the weights were measured beside,
+// in whole cores — the budget is in whole cores, and a fraction of a core is not a core to give up.
+function external_cores(busy_cores: number | undefined, ledger_cores: number): number {
+	if (busy_cores === undefined) return 0
+
+	return Math.floor(Math.max(0, busy_cores - ledger_cores - BASELINE_CORES))
+}
+
+// **The budget the ledger admits against: what is free plus what the ledger itself already holds.**
+// The admitted reservations' load is inside the reading, and the admission walk counts their declared
+// weight again, so it is added back — what is subtracted is only the load from outside the ledger. The
+// caller passes every admitted claim's cores but only the memory of claims past
+// `core_admission.RAMP_UP_MS`, whose tools have had time to allocate.
+// Memory that could not be read is no limit at all, the behavior before memory was read.
+function machine_budget(cores: number, reading: MachineReading, ledger: LedgerLoad): MachineBudget {
+	return {
+		cores: cores - external_cores(reading.busy_cores, ledger.cores),
+		memory_mb:
+			reading.available_mb === undefined ? Infinity : reading.available_mb + ledger.memory_mb,
+	}
+}
+
+const machine_capacity = {
+	BASELINE_CORES,
+	busy_cores_between,
+	machine_budget,
+	parse_darwin_pressure,
+	parse_linux_available,
+	read_machine,
+}
+
+export type { LedgerLoad, MachineBudget, MachineReading }
+export { machine_capacity }

package/scripts/gate/verification-gate.ts

@@ -177,6 +177,7 @@ function default_budget(): BudgetContext {
 interface ReservedStep {
 	step: GateStep
 	weight: number
+	memory_mb: number
 }
 
 async function build_reserved_steps(
@@ -188,6 +189,7 @@ async function build_reserved_steps(
 		plan.checks.map(async (check) => ({
 			step: await build_gate_step(check, start_directory, plan),
 			weight: gate_plan.check_weight(check, plan, available_cores),
+			memory_mb: gate_plan.check_memory(check, plan, available_cores),
 		})),
 	)
 }
@@ -205,8 +207,11 @@ async function run_reserved_step(
 
 	return await core_budget.with_core_reservation(
 		reserved.weight,
-		async () => await run_gate_step(reserved.step),
-		{ budget: budget.available_cores },
+		async (admission) => ({
+			...(await run_gate_step(reserved.step)),
+			budget_note: core_budget.describe_overflow(admission),
+		}),
+		{ budget: budget.available_cores, memory_mb: reserved.memory_mb },
 	)
 }
 

package/scripts/init/init.ts

@@ -25,6 +25,7 @@ import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
 import { kit_development_versions } from './kit-development-versions'
 import { kit_setup_state } from './kit-setup-state'
+import { package_manager_pin } from './package-manager-pin'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
 const PACKAGE_JSON = 'package.json'
@@ -52,7 +53,10 @@ function resolve_kit_package_manager(manifest: unknown): string | undefined {
 }
 
 function get_kit_package_manager(): string | undefined {
-	return resolve_kit_package_manager(init_actions.read_package_json(PACKAGE_JSON))
+	return package_manager_pin.choose(
+		resolve_kit_package_manager(init_actions.read_package_json(PACKAGE_JSON)),
+		process.env['npm_config_user_agent'],
+	)
 }
 
 function get_kit_development_engines(): Record<string, unknown> {

package/scripts/init/package-manager-pin.ts

@@ -0,0 +1,35 @@
+import { package_manager_version } from '#scripts/version/package-manager-version'
+import semver from 'semver'
+
+// pnpm sets `npm_config_user_agent` to `pnpm/<version> npm/? node/<version> <platform> <arch>` for
+// every script and `pnpm exec` it runs, so the pnpm that invoked `josh init` is readable from it.
+const PNPM_USER_AGENT_REGEX = /^pnpm\/(\S+)/u
+
+function running_pnpm_version(user_agent = ''): string | undefined {
+	const version = PNPM_USER_AGENT_REGEX.exec(user_agent)?.[1]
+
+	return version === undefined ? undefined : (semver.valid(version) ?? undefined)
+}
+
+function is_older_than(kit_pin: string, version: string): boolean {
+	const kit_version = semver.valid(package_manager_version.extract_pnpm_pin(kit_pin) ?? '')
+
+	return kit_version !== null && semver.lt(kit_version, version)
+}
+
+// Never pin a project below the pnpm installing it: the lockfile that pnpm just wrote can name a
+// version an older pnpm fails to resolve, so `pnpm install` under kit's older pin breaks the
+// first `josh init` (joshuafolkken/kit#3367). The kit pin keeps its integrity suffix when it wins.
+function choose(kit_pin: string | undefined, user_agent: string | undefined): string | undefined {
+	const running = running_pnpm_version(user_agent)
+	if (kit_pin === undefined || running === undefined) return kit_pin
+
+	return is_older_than(kit_pin, running) ? `pnpm@${running}` : kit_pin
+}
+
+const package_manager_pin = {
+	running_pnpm_version,
+	choose,
+}
+
+export { package_manager_pin }

package/scripts/issue/issue-auto-ok.ts

@@ -2,7 +2,7 @@ import { git_branch } from '#scripts/git/git-branch'
 import { git_command } from '#scripts/git/git-command'
 import { run_carry } from '#scripts/run/carry/run-carry'
 import { issue_file } from './issue-file'
-import { AUTO_OK_LABEL, has_label_name } from './issue-labels'
+import { AUTO_OK_LABEL, has_label_name, RELEASE_LABEL } from './issue-labels'
 import { issue_state_cli } from './issue-state-cli'
 
 // Whether `josh issue:file` applies `auto-ok` to the Issue it files (joshuafolkken/kit#3213). Work
@@ -12,9 +12,13 @@ import { issue_state_cli } from './issue-state-cli'
 // default. `--no-auto-ok` is the one exception, declared for an Issue that needs a person's judgement
 // (a Tier B toss-up or a Tier C action). A filing to another repository is never opted in: that
 // repository's own `backlogrun` would implement and merge it though nobody opted that repository in.
+// A `release` Issue is never opted in either (joshuafolkken/kit#3360): a release is Tier C, so only a
+// person applies `auto-ok` to it, whatever the carry record or the branch's Issue says.
 
 interface AutoOkSignals {
 	is_opted_out: boolean
+	// The filing carries the `release` label.
+	is_release: boolean
 	is_carried: boolean
 	// The labels of the Issue the current branch names; `undefined` when the branch names none or the
 	// Issue could not be read.
@@ -31,6 +35,10 @@ const CROSS_REPOSITORY: AutoOkDecision = {
 	is_applied: false,
 	reason: 'the Issue is filed to another repository',
 }
+const RELEASE: AutoOkDecision = {
+	is_applied: false,
+	reason: `a ${RELEASE_LABEL} Issue is opted in by a person only`,
+}
 const CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
 const BRANCH_OPTED_IN: AutoOkDecision = {
 	is_applied: true,
@@ -41,9 +49,22 @@ const NOT_OPTED_IN: AutoOkDecision = {
 	reason: 'no backlogrun carry record is live and the branch names no auto-ok Issue',
 }
 
-// The opt-out wins over every signal, then the carry record, then the branch's Issue.
-function decide(signals: AutoOkSignals): AutoOkDecision {
+type Withholding = Pick<AutoOkSignals, 'is_opted_out' | 'is_release'>
+
+// The two signals that withhold `auto-ok` before any other is read, or `undefined` when neither holds.
+function withheld(signals: Withholding): AutoOkDecision | undefined {
 	if (signals.is_opted_out) return OPTED_OUT
+	if (signals.is_release) return RELEASE
+
+	return undefined
+}
+
+// The opt-out and the `release` label win over every signal, then the carry record, then the branch's
+// Issue.
+function decide(signals: AutoOkSignals): AutoOkDecision {
+	const decision = withheld(signals)
+
+	if (decision !== undefined) return decision
 	if (signals.is_carried) return CARRIED
 	if (has_label_name(signals.branch_labels ?? [], AUTO_OK_LABEL)) return BRANCH_OPTED_IN
 
@@ -76,17 +97,21 @@ async function branch_labels(current: string): Promise<ReadonlyArray<string> | u
 }
 
 // Each read is skipped once an earlier signal has already decided the answer; a cross-repository
-// filing is refused before any signal is read.
+// filing is refused before any signal is read. `labels` are the ones the filing declares.
 async function resolve(
 	is_opted_out: boolean,
 	target: string,
 	current: string,
+	labels: ReadonlyArray<string> = [],
 ): Promise<AutoOkDecision> {
-	if (is_opted_out) return OPTED_OUT
+	const withholding = { is_opted_out, is_release: has_label_name(labels, RELEASE_LABEL) }
+	const decision = withheld(withholding)
+
+	if (decision !== undefined) return decision
 	if (!issue_file.is_same_repository(target, current)) return CROSS_REPOSITORY
 	if (await is_carried()) return CARRIED
 
-	return decide({ is_opted_out, is_carried: false, branch_labels: await branch_labels(current) })
+	return decide({ ...withholding, is_carried: false, branch_labels: await branch_labels(current) })
 }
 
 const issue_auto_ok = { decide, line_of, resolve }

package/scripts/issue/issue-file-cli.ts

@@ -14,23 +14,24 @@ import { repository_labels } from '#scripts/repo/repository-labels'
 import { issue_auto_ok } from './issue-auto-ok'
 import { issue_file, type FileArguments } from './issue-file'
 import { issue_lint_cli } from './issue-lint-cli'
+import { issue_release_cli } from './issue-release-cli'
 import { issue_scout_cli } from './issue-scout-cli'
 import { issue_wip } from './issue-wip'
 
 // `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
-// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]` — file an Issue with every
-// filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body lint, the
-// `## Origin` check for another repository, the `auto-ok` decision (joshuafolkken/kit#3213) with the
-// run label it owes (joshuafolkken/kit#3313), the WIP cap count (joshuafolkken/kit#3181), the duplicate
-// scout, the missing workflow labels created (joshuafolkken/kit#3176), the create call carrying every
-// label, and `epic:bundle` after it.
+// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]` — file an Issue
+// with every filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body
+// lint, the `## Origin` check for another repository, the `auto-ok` decision (joshuafolkken/kit#3213)
+// with the run label it owes (joshuafolkken/kit#3313), the WIP cap count (joshuafolkken/kit#3181), the
+// duplicate scout, the missing workflow labels created (joshuafolkken/kit#3176), the create call
+// carrying every label, the release link on `--release` (joshuafolkken/kit#3360), and `epic:bundle`.
 // A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
-	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]'
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
 const THIRD_PARTY_MESSAGE =
@@ -142,6 +143,7 @@ async function labels_of(filing: Filing): Promise<ReadonlyArray<string> | undefi
 		filing.args.is_auto_ok_opted_out,
 		filing.target,
 		filing.current,
+		filing.args.labels,
 	)
 
 	console.info(issue_auto_ok.line_of(auto_ok))
@@ -177,10 +179,30 @@ async function create(filing: Filing, labels: ReadonlyArray<string>): Promise<st
 	}
 }
 
+function issue_number_of(url: string): number {
+	return Number(github_issue_url.parse(url)?.issue_number)
+}
+
+// `--release`: the filed Issue blocks the target's release Issue (joshuafolkken/kit#3360). Reported,
+// never failed, for the reason `place` gives. The re-run hint names the target through `GH_REPO`:
+// `issue:release` links in the repository `gh` resolves, which is not the target on a `--repo` filing.
+async function link_release(url: string, filing: Filing): Promise<void> {
+	if (!filing.args.is_release) return
+	const issue_number = issue_number_of(url)
+	const is_linked =
+		Number.isSafeInteger(issue_number) &&
+		(await issue_release_cli.link(issue_number, filing.target))
+
+	if (is_linked) return
+	console.error(
+		`⚠ the release link did not complete for ${url} — run \`${GH_REPO_VARIABLE}=${filing.target} pnpm josh issue:release <N>\`.`,
+	)
+}
+
 // The Issue exists once `create` returns, so a failed placement is reported rather than failed: a
 // non-zero exit would read as "not filed" and invite the second filing the scout exists to stop.
 async function place(url: string, target: string): Promise<void> {
-	const issue_number = Number(github_issue_url.parse(url)?.issue_number)
+	const issue_number = issue_number_of(url)
 	const exit_code = Number.isSafeInteger(issue_number)
 		? await epic_bundle_cli.report_for(issue_number, target, FRESH_ISSUE_POLL)
 		: FAILURE_EXIT_CODE
@@ -204,6 +226,7 @@ async function send(filing: Filing, labels: ReadonlyArray<string>): Promise<numb
 
 	if (url === undefined) return FAILURE_EXIT_CODE
 	console.info(url)
+	await link_release(url, filing)
 	await place(url, filing.target)
 
 	return SUCCESS_EXIT_CODE

package/scripts/issue/issue-file.ts

@@ -43,6 +43,9 @@ interface FileArguments {
 	is_over_cap: boolean
 	// `--no-auto-ok`: the Issue needs a person's judgement, so `auto-ok` is not applied (`issue-auto-ok.ts`).
 	is_auto_ok_opted_out: boolean
+	// `--release`: the change reaches a consumer only once published, so the Issue is linked to the
+	// repository's release Issue as a blocker (`issue-release-cli.ts`).
+	is_release: boolean
 }
 
 const OPTIONS = {
@@ -54,6 +57,7 @@ const OPTIONS = {
 	distinct: { type: 'string', multiple: true },
 	'over-cap': { type: 'boolean' },
 	'no-auto-ok': { type: 'boolean' },
+	release: { type: 'boolean' },
 } as const
 
 // The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
@@ -123,6 +127,7 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		repo: values.repo,
 		is_over_cap: values['over-cap'] === true,
 		is_auto_ok_opted_out: values['no-auto-ok'] === true,
+		is_release: values.release === true,
 	}
 }
 

package/scripts/issue/issue-labels.ts

@@ -65,6 +65,12 @@ const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
 // takes it off, because taking it off asserts the work is *not* done, which is the same claim in
 // reverse and is no more a run's to make.
 const ALREADY_DONE_LABEL = 'already-done'
+// Marks the Issue that tracks a repository's next release (joshuafolkken/kit#3360). An Issue whose
+// change reaches a consumer only once published is linked to it as a `blocked_by` blocker
+// (`josh issue:release`), so "merged but not yet released" is visible in the backlog. A run applies
+// it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` refuses the default for it on every path,
+// since a release is Tier C — and only a person opts it into unattended execution.
+const RELEASE_LABEL = 'release'
 
 // The four labels that mean an open issue must not be handed to a run as it stands: an `epic`
 // tracks a batch and is never run directly (its children are), `in-progress` is already claimed by
@@ -228,6 +234,11 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: 'e99695',
 		description: 'Offered first in a backlogrun; only a person removes it',
 	},
+	{
+		name: RELEASE_LABEL,
+		color: 'fef2c0',
+		description: 'Tracks the next release; its blockers are the merged work it publishes',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -340,6 +351,7 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	NEEDS_HUMAN_REVIEW_LABEL,
 	ALREADY_DONE_LABEL,
 	PRIORITY_HIGH_LABEL,
+	RELEASE_LABEL,
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
@@ -386,6 +398,7 @@ export {
 	PRIORITY_HIGH_LABEL,
 	RELEASE_CLASSIFICATION_LABELS,
 	RELEASE_CLASSIFICATION_NAMES,
+	RELEASE_LABEL,
 	REPOSITORY_LABELS,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,

package/scripts/issue/issue-release-cli.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { github_issue_url } from '#scripts/gh/github-issue-url'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { repository_labels } from '#scripts/repo/repository-labels'
+import { RELEASE_LABEL } from './issue-labels'
+import { issue_release } from './issue-release'
+
+// `josh issue:release <N>` — link Issue `<N>` to its repository's release Issue as a `blocked_by`
+// blocker, filing the release Issue when none is open (joshuafolkken/kit#3360). `josh issue:file
+// --release` calls the same `link` once its Issue exists, so a new and an existing Issue are linked
+// by one body of code.
+//
+// The relation is written through `issue_add_blocked_by`, which addresses the repository `gh`
+// resolves — the current one, or the target a cross-repository `issue:file` has pointed `GH_REPO` at.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const USAGE = 'Usage: josh issue:release <issue-number>'
+const NONE = 'none'
+const UNKNOWN_REPO_MESSAGE =
+	'Could not read this repository from `git remote` — check `gh auth status`.'
+
+interface ReleaseIssue {
+	issue_number: number
+	// Filed by this call, rather than found open.
+	is_filed: boolean
+}
+
+// `undefined` when the listing is unreadable, `NONE` when it reads and names no open release Issue.
+async function find_open(target: string): Promise<number | typeof NONE | undefined> {
+	const outcome = await git_gh_issue_list.issue_list({
+		json_fields: 'number',
+		limit: MAX_SCANNED,
+		label: RELEASE_LABEL,
+		repo: target,
+	})
+
+	if (outcome.json === undefined) return undefined
+
+	return issue_release.open_release_of(outcome.json) ?? NONE
+}
+
+// The new release Issue's number, or `undefined` when the create call failed. Never `auto-ok`: the
+// labels are `RELEASE_LABELS`, decided here rather than by `issue_auto_ok`, which refuses the label too.
+async function file_release(target: string): Promise<number | undefined> {
+	repository_labels.ensure_labels(target)
+	const request = git_gh_issue_write.issue_create_request({
+		title: issue_release.title_of(target),
+		body: issue_release.body_of(target),
+		labels: issue_release.RELEASE_LABELS,
+		repo: target,
+	})
+
+	try {
+		const url = await git_gh_exec.exec_gh_api(request)
+		const issue_number = Number(github_issue_url.parse(url)?.issue_number) || undefined
+
+		if (issue_number === undefined) console.error(`✖ the release number is unreadable: ${url}`)
+
+		return issue_number
+	} catch (error) {
+		console.error(`✖ the release Issue could not be filed: ${error_text.message_of(error)}`)
+
+		return undefined
+	}
+}
+
+// An unreadable listing files nothing: a second release Issue beside one the listing failed to show
+// would split the blockers between two releases.
+async function release_of(target: string): Promise<ReleaseIssue | undefined> {
+	const open = await find_open(target)
+
+	if (open === undefined) {
+		console.error(`✖ the open ${RELEASE_LABEL} Issues of ${target} could not be listed`)
+
+		return undefined
+	}
+
+	if (open !== NONE) return { issue_number: open, is_filed: false }
+	const filed = await file_release(target)
+
+	return filed === undefined ? undefined : { issue_number: filed, is_filed: true }
+}
+
+function linked_line(release: ReleaseIssue, issue_number: number): string {
+	const how = release.is_filed ? 'filed' : 'open'
+
+	return `release: #${String(release.issue_number)} (${how}) is blocked by #${String(issue_number)}`
+}
+
+// Whether Issue `issue_number` of `target` now blocks the release Issue. Every outcome is printed.
+async function link(issue_number: number, target: string): Promise<boolean> {
+	const release = await release_of(target)
+
+	if (release === undefined) return false
+	const blocked = String(release.issue_number)
+	const is_linked = await git_gh_issue_write.issue_add_blocked_by(blocked, String(issue_number))
+
+	if (is_linked) console.info(linked_line(release, issue_number))
+	else console.error(`✖ #${String(issue_number)} could not be recorded as a blocker of #${blocked}`)
+
+	return is_linked
+}
+
+// An unknown flag parses to no positionals, so it refuses the call like a missing number.
+function positionals_of(argv: ReadonlyArray<string>): ReadonlyArray<string> {
+	return cli_flags.arguments_of(argv, {})?.positionals ?? []
+}
+
+// The number is the one positional: a missing, malformed or second one refuses the whole call.
+function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
+	const [issue_number, ...rest] = positionals_of(argv)
+	const is_single = rest.length === 0 && issue_number !== undefined
+
+	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? Number(issue_number) : undefined
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = issue_number_of(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const current = await git_gh_command.repo_get_name_with_owner()
+
+	if (current === undefined) {
+		console.error(UNKNOWN_REPO_MESSAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return (await link(issue_number, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_release_cli = { link, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_release_cli }