@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/version/latest-corepack.ts

@@ -5,33 +5,37 @@
  * The target version is resolved from the registry's publish timestamps
  * (`pnpm view pnpm time --json`) instead of a dist-tag, because pnpm publishes its
  * per-major tag `latest-<major>` only for SUPERSEDED majors — while <major> is the newest
- * major, the only tag covering it is `latest` (kit#750). The former `latest-<major>` pin
- * (kit#444) therefore failed on every run in the common case, and `latest` itself can
- * momentarily point below the devEngines floor. Picking the newest registry version whose
- * major equals the `packageManager` pin keeps both invariants: never below the adopted
- * major, and advancing while that major is the current one.
+ * major, the only tag covering it is `latest`, so a `latest-<major>` pin would fail on every
+ * run in the common case, and `latest` itself can momentarily point below the devEngines
+ * floor. Picking the newest registry version whose major equals the `packageManager` pin keeps
+ * both invariants: never below the adopted major, and advancing while that major is the
+ * current one.
  *
- * The `minimumReleaseAge` quarantine is applied natively from `pnpm-workspace.yaml` (kit#768,
- * #3267). safe-chain filters the registry only when the process tree was launched through one
- * of its wrapped shell commands, so `josh latest` and `pnpm josh latest` used to resolve
- * different answers and the pin oscillated. Reading the window from the repo-managed
+ * The `minimumReleaseAge` quarantine is applied natively from `pnpm-workspace.yaml`.
+ * safe-chain filters the registry only when the process tree was launched through one of its
+ * wrapped shell commands, so `josh latest` and `pnpm josh latest` would resolve different
+ * answers and the pin would oscillate. Reading the window from the repo-managed
  * `pnpm-workspace.yaml` and filtering by publish timestamp makes the resolution identical in
  * every invocation context; right after a pnpm release the answer is simply the previous
- * release, exactly as the filtered view behaved.
+ * release, exactly as the filtered view behaves.
  *
  * The resolved version is floored at the current `packageManager` pin: a filtered registry
  * view legitimately answers below a freshly adopted pin for the first 24 hours after every
- * pnpm release, and writing that answer would downgrade the protected toolchain pin
- * (kit#766). Not-newer answers skip the bump non-fatally instead.
+ * pnpm release, and writing that answer would downgrade the protected toolchain pin.
+ * Not-newer answers skip the bump non-fatally instead.
  *
  * `devEngines.packageManager.version` is realigned with the `packageManager` pin on every
- * path — bumped, skipped, or unresolvable (kit#773). Alignment used to run only after a
- * successful bump, which never fires in the steady state of an up-to-date repository, so a
- * manifest that arrived with the two fields out of step kept the pnpm dual-declaration
- * warning forever. The alignment is idempotent, so running it unconditionally is free.
+ * path — bumped, skipped, or unresolvable. A bump never fires in the steady state of an
+ * up-to-date repository, so alignment gated on one would leave a manifest that arrived with
+ * the two fields out of step warning forever. The alignment is idempotent, so running it
+ * unconditionally is free.
  *
- * Registry and pnpm failures stay non-fatal: they are logged and swallowed (exit 0)
- * so the rest of the `josh latest` chain (`latest:update`, `audit`) keeps running.
+ * A failed bump exits non-zero with its cause, the manifest restored — a skip would let
+ * `latest:scope --record` mark the run fresh while a pnpm that could not self-update (the
+ * Corepack shim refuses it) stayed pinned silently. `josh latest` runs this step
+ * last, right before the record, so the dependency update and the audit still finish and only the
+ * record is withheld. A registry answer not newer than the pin, or nothing aged past the
+ * quarantine window yet, remains a non-fatal skip.
  *
  * Usage: tsx scripts/version/latest-corepack.ts
  */
@@ -54,9 +58,19 @@ const WORKSPACE_PATH = 'pnpm-workspace.yaml'
 const SHA512_BYTES = 64
 const INTEGRITY_RE = /^sha512-([A-Za-z0-9+/]+={0,2})$/u
 const PACKAGE_MANAGER_VALUE_RE = /("packageManager"\s*:\s*")pnpm@[^"]+(")/u
+
+// `target` is undefined both when the registry did not answer and when it answered but nothing has
+// aged past the quarantine window yet; only the first is a failure.
+interface TargetResolution {
+	target: string | undefined
+	is_registry_reachable: boolean
+}
+
 const PNPM_DEVELOPMENT_MANAGER_SCHEMA = z.object({ name: z.literal('pnpm'), version: z.string() })
 const DEV_ENGINES_SCHEMA = z.object({ packageManager: PNPM_DEVELOPMENT_MANAGER_SCHEMA })
 const DEV_ENGINES_PNPM_SCHEMA = z.object({ devEngines: DEV_ENGINES_SCHEMA.optional() })
+const COREPACK_REMEDY =
+	'pnpm runs through the Corepack shim, where pnpm 11+ refuses self-update (ERR_PNPM_CANT_SELF_UPDATE_IN_COREPACK). Run `corepack disable pnpm`, install a standalone pnpm (https://pnpm.io/installation), run josh sync so a devEngines.packageManager.onFail of "error" becomes "download" (the standalone pnpm then fetches the pinned version), then rerun josh latest.'
 
 function extract_development_engines_version(package_json_content: string): string | undefined {
 	const parsed = DEV_ENGINES_PNPM_SCHEMA.safeParse(
@@ -94,7 +108,7 @@ function extract_pinned_version(package_json_content: string): string | undefine
 
 // Never move the pin backwards. A filtered registry view (safe-chain's minimum-release-age
 // proxy) answers below a freshly adopted pin for 24 hours after every pnpm release, and an
-// equal answer would only rewrite the same value — both skip instead (kit#766).
+// equal answer would only rewrite the same value — both skip instead.
 function is_target_not_newer_than_pin(target: string, pinned_version: string | undefined): boolean {
 	if (pinned_version === undefined) return false
 	const target_version = target.slice(TARGET_PREFIX.length)
@@ -128,22 +142,33 @@ function query_release_times(): Record<string, string> | undefined {
 	return extract_times_json(result.stdout)
 }
 
+function to_resolution(
+	version: string | undefined,
+	is_registry_reachable: boolean,
+): TargetResolution {
+	const target = version === undefined ? undefined : `${TARGET_PREFIX}${version}`
+
+	return { target, is_registry_reachable }
+}
+
 // Ask the registry for the newest pnpm release on the pinned major that has aged past the
-// quarantine window. Returns undefined when the query fails or nothing qualifies yet.
-function query_major_latest_version(major: string): string | undefined {
+// quarantine window.
+function resolve_major_target(major: string): TargetResolution {
 	const times = query_release_times()
-	if (times === undefined) return undefined
+	if (times === undefined) return to_resolution(undefined, false)
 
 	// The project's own `pnpm-workspace.yaml`, deliberately not the upward walk the version check
 	// uses: `josh latest` reads `package.json` and writes the pnpm pin relative to the working
 	// directory, so it has no subdirectory case — and honouring an ancestor's policy here could freeze
-	// pnpm bumps in a project that declares none (joshuafolkken/kit#808).
-	return release_age.select_aged_version(
+	// pnpm bumps in a project that declares none.
+	const version = release_age.select_aged_version(
 		times,
 		major,
 		release_age.read_minimum_release_age(WORKSPACE_PATH),
 		Date.now(),
 	)
+
+	return to_resolution(version, true)
 }
 
 function parse_latest_version(stdout: string): string | undefined {
@@ -163,24 +188,40 @@ function query_latest_version(): string | undefined {
 	return parse_latest_version(result.stdout)
 }
 
-// The value handed to pnpm self-update: an exact registry-resolved version on the pinned
-// major, the latest exact version when no major can be read from package.json, or undefined when
-// the registry could not answer (the caller skips non-fatally).
-function resolve_corepack_target(major: string | undefined): string | undefined {
-	const version = major === undefined ? query_latest_version() : query_major_latest_version(major)
-	if (version === undefined) return undefined
+// The target handed to pnpm self-update: an exact registry-resolved version on the pinned major, or
+// the latest exact version when no major can be read from package.json. The latest-version query
+// has no quarantine selection, so resolving nothing there always means the registry did not answer.
+function resolve_target(major: string | undefined): TargetResolution {
+	if (major !== undefined) return resolve_major_target(major)
+	const version = query_latest_version()
+
+	return to_resolution(version, version !== undefined)
+}
 
-	return `pnpm@${version}`
+function resolve_corepack_target(major: string | undefined): string | undefined {
+	return resolve_target(major).target
 }
 
-// Non-fatal skip message shared by both skip paths: keep the josh latest chain
-// (latest:update, audit) running instead of aborting on a bump failure.
+// Non-fatal skip message for a registry answer with nothing to adopt — nothing to bump, nothing failed.
 function warn_skip(reason: string): void {
-	console.warn(`⚠ Skipped pnpm bump (${reason}); the chain continues.`)
+	console.warn(`⚠ Skipped pnpm bump (${reason}).`)
+}
+
+// Every failure path ends here, so the exit status the `josh latest` chain stops on is one value.
+function fail_bump(reason: string): number {
+	console.error(
+		`✖ pnpm bump failed (${reason}); the run is not recorded, so the next josh latest retries it.`,
+	)
+
+	return FAILURE_EXIT_CODE
 }
 
-function warn_unresolved(major: string | undefined = ''): void {
-	warn_skip(`no pnpm ${major} release resolvable from the registry`)
+// Corepack exports COREPACK_ROOT to the package manager it launches, and pnpm 11+ refuses
+// `self-update` under it (ERR_PNPM_CANT_SELF_UPDATE_IN_COREPACK), so the remedy is named there.
+function fail_self_update(status: number, environment: NodeJS.ProcessEnv = process.env): number {
+	if (environment['COREPACK_ROOT'] !== undefined) console.error(COREPACK_REMEDY)
+
+	return fail_bump(`pnpm self-update exited ${String(status)}`)
 }
 
 function run_pnpm_update(target: string): number {
@@ -193,22 +234,11 @@ function run_pnpm_update(target: string): number {
 	return result.exitCode ?? FAILURE_EXIT_CODE
 }
 
-// The target is an already-resolved exact version, so a non-zero status here is a
-// genuine pnpm or network failure; a later run retries. Returns whether a skip
-// happened.
-function did_warn_skip(status: number): boolean {
-	if (status === 0) return false
-
-	warn_skip(`pnpm self-update exited ${String(status)}`)
-
-	return true
-}
-
 // Realign `devEngines.packageManager.version` with the `packageManager` pin so the two
 // fields keep matching (pnpm suppresses the dual-declaration warning only on an exact
 // match). Runs on every path, not just after a successful bump: a repository that arrives
 // with the two fields already out of step sits in the no-bump steady state forever, so an
-// alignment gated on a bump would never repair it (kit#773).
+// alignment gated on a bump would never repair it.
 function sync_development_engines(package_json_path: string = PACKAGE_JSON_PATH): void {
 	const content = readFileSync(package_json_path, 'utf8')
 	const aligned = package_manager_version.align_development_engines_version(content)
@@ -224,7 +254,7 @@ function restore_package_json(
 	package_json_path: string = PACKAGE_JSON_PATH,
 ): void {
 	writeFileSync(package_json_path, content)
-	console.info('✔ Restored package.json pin (pnpm bump skipped)')
+	console.info('✔ Restored package.json pin (pnpm bump failed)')
 }
 
 function decode_integrity(encoded: string): string | undefined {
@@ -281,7 +311,7 @@ function restore_integrity(target: string, integrity: string): void {
 }
 
 // The equal case is the steady state of every up-to-date run, so it logs as success; only
-// an answer strictly below the pin is the anomaly worth a warning (kit#766).
+// an answer strictly below the pin is the anomaly worth a warning.
 function notify_skipped_bump(target: string, pinned_version: string): void {
 	if (target === `${TARGET_PREFIX}${pinned_version}`) {
 		console.info(`✔ pnpm pin ${pinned_version} already matches the newest registry release.`)
@@ -292,35 +322,19 @@ function notify_skipped_bump(target: string, pinned_version: string): void {
 	warn_skip(`registry answered ${target}, below the pinned ${pinned_version}`)
 }
 
-// Resolve the pnpm target with the pin floor applied. Undefined means the bump was
-// skipped and the reason has already been logged.
-function resolve_floored_target(original: string, major: string | undefined): string | undefined {
-	const target = resolve_corepack_target(major)
-
-	if (target === undefined) {
-		warn_unresolved(major)
-
-		return undefined
-	}
-
-	const pinned_version = extract_pinned_version(original)
-	if (!is_target_not_newer_than_pin(target, pinned_version)) return target
-
-	notify_skipped_bump(target, pinned_version ?? '')
-
-	return undefined
-}
-
-function restore_after_update(original: string, target: string, integrity: string): void {
+function restore_after_update(original: string, target: string, integrity: string): number {
 	try {
 		restore_integrity(target, integrity)
+
+		return 0
 	} catch {
 		restore_package_json(original)
-		warn_skip('pnpm self-update wrote an unexpected pin')
+
+		return fail_bump('pnpm self-update wrote an unexpected pin')
 	}
 }
 
-function pin_unpinned_manifest(original: string, target: string, integrity: string): void {
+function pin_unpinned_manifest(original: string, target: string, integrity: string): number {
 	const manifest = z.record(z.string(), z.unknown()).parse(json_value.parse_or_undefined(original))
 	const pinned = JSON.stringify(
 		{ ...manifest, packageManager: `${target}+${integrity}` },
@@ -334,53 +348,71 @@ function pin_unpinned_manifest(original: string, target: string, integrity: stri
 	)
 
 	const result = execaSync('pnpm', ['--version'], { reject: false })
-	if (result.exitCode === 0 && result.stdout.trim() === target.slice(TARGET_PREFIX.length)) return
+	if (result.exitCode === 0 && result.stdout.trim() === target.slice(TARGET_PREFIX.length)) return 0
 
 	restore_package_json(original)
-	warn_skip('the newly pinned pnpm version could not start')
-}
 
-function update_pinned_manifest(original: string, target: string, integrity: string): void {
-	const is_skipped = did_warn_skip(run_pnpm_update(target))
+	return fail_bump('the newly pinned pnpm version could not start')
+}
 
-	if (is_skipped) {
-		restore_package_json(original)
+// The target is an already-resolved exact version, so a non-zero status here is a genuine
+// pnpm, Corepack or network failure.
+function update_pinned_manifest(original: string, target: string, integrity: string): number {
+	const status = run_pnpm_update(target)
+	if (status === 0) return restore_after_update(original, target, integrity)
 
-		return
-	}
+	restore_package_json(original)
 
-	restore_after_update(original, target, integrity)
+	return fail_self_update(status)
 }
 
 // Query integrity before mutating the manifest; self-update writes both pins without it.
-function bump_package_manager(original: string, target: string): void {
+function bump_package_manager(original: string, target: string): number {
 	const integrity = query_integrity(target)
+	if (integrity === undefined) return fail_bump(`no integrity for ${target}`)
+	if (!PACKAGE_MANAGER_RE.test(original)) return pin_unpinned_manifest(original, target, integrity)
 
-	if (integrity === undefined) {
-		warn_skip(`no integrity for ${target}`)
+	return update_pinned_manifest(original, target, integrity)
+}
 
-		return
-	}
+// An unreachable registry fails, so the unrecorded run is retried. A reachable one with nothing
+// aged past the quarantine window is the quarantine skip — like a not-newer answer, there is nothing
+// to adopt yet, and failing would stall every run for up to the whole window.
+function report_unresolved(major: string | undefined, is_registry_reachable: boolean): number {
+	const label = `pnpm ${major ?? ''}`.trimEnd()
+	if (!is_registry_reachable) return fail_bump(`the registry did not answer for ${label}`)
 
-	if (!PACKAGE_MANAGER_RE.test(original)) {
-		pin_unpinned_manifest(original, target, integrity)
+	warn_skip(`no ${label} release has aged past the quarantine window yet`)
 
-		return
+	return 0
+}
+
+// Resolve the pnpm target with the pin floor applied, then bump.
+function bump_to_registry_target(original: string, major: string | undefined): number {
+	const { target, is_registry_reachable } = resolve_target(major)
+	if (target === undefined) return report_unresolved(major, is_registry_reachable)
+
+	const pinned_version = extract_pinned_version(original)
+
+	if (!is_target_not_newer_than_pin(target, pinned_version)) {
+		return bump_package_manager(original, target)
 	}
 
-	update_pinned_manifest(original, target, integrity)
+	notify_skipped_bump(target, pinned_version ?? '')
+
+	return 0
 }
 
-function main(): void {
+function main(): number {
 	const original = readFileSync(PACKAGE_JSON_PATH, 'utf8')
-	const major = extract_pnpm_major(original)
-	const target = resolve_floored_target(original, major)
-	if (target !== undefined) bump_package_manager(original, target)
+	const status = bump_to_registry_target(original, extract_pnpm_major(original))
 
 	sync_development_engines()
+
+	return status
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = main()
 
 const latest_corepack = {
 	extract_pnpm_major,
@@ -388,12 +420,11 @@ const latest_corepack = {
 	is_target_not_newer_than_pin,
 	notify_skipped_bump,
 	extract_times_json,
-	query_major_latest_version,
 	resolve_corepack_target,
 	run_pnpm_update,
 	query_integrity,
 	restore_integrity,
-	did_warn_skip,
+	fail_self_update,
 	sync_development_engines,
 	restore_package_json,
 	main,

package/scripts/version/latest-lane-guard.ts

@@ -2,7 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { lane_paths, type LaneEnvironment } from '#scripts/lane/lane-paths'
 
-// Refuse a dependency update inside a lane (joshuafolkken/kit#2135).
+// Refuse a dependency update inside a lane.
 //
 // `latest:scope` reads how long ago `josh latest` last finished, and that stamp is keyed to the
 // project root. A lane is a linked work tree whose project root is its own directory, so a fresh

package/scripts/version/latest-scope-cli.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { latest_lane_guard } from './latest-lane-guard'
 import { latest_stamp, type LatestStamp } from './latest-stamp'
 
-// `josh latest:scope` — say whether this run has to update dependencies (joshuafolkken/kit#1215).
+// `josh latest:scope` — say whether this run has to update dependencies.
 //
 // A command rather than a paragraph in a procedure, for the reason `josh review:level` is a command:
 // a rule an agent applies from memory is a rule an agent can talk itself out of, and this one is
@@ -65,7 +65,7 @@ function decide(): Decision {
 	}
 }
 
-// A lane is answered `skip` before the stamp is even read (joshuafolkken/kit#2135): the stamp is
+// A lane is answered `skip` before the stamp is even read: the stamp is
 // keyed to the project root, so a lane always reads as stale, and every lane would otherwise run its
 // own dependency update. `latest_lane_guard` is the single source of the reason and of the refusal
 // `josh latest` prints.

package/scripts/version/latest-stamp.ts

@@ -1,8 +1,7 @@
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
 
-// When `josh latest` last finished in this checkout, and whether that is recent enough to skip
-// (joshuafolkken/kit#1215).
+// When `josh latest` last finished in this checkout, and whether that is recent enough to skip.
 //
 // `josh latest` is a network-bound chain — pnpm update, every dependency, `ranges`, `pnpm audit` — that
 // took 60–120 seconds at the head of every `fullrun` / `halfrun` and of every child a batch ran, and

package/scripts/version/latest-update.ts

@@ -63,8 +63,8 @@ function report_kept_back(regressions: ReadonlyArray<VersionRegression>): void {
 
 // The direct-dependency `--latest` bump lifts the package.json ranges; this second, argument-less
 // pass then re-resolves every tier the lockfile carries within those ranges, which is the only stage
-// that reaches the indirect packages a direct-only update leaves pinned at a stale resolution
-// (joshuafolkken/kit#2200). `pnpm update` defaults to depth Infinity, so no flag is needed to reach
+// that reaches the indirect packages a direct-only update leaves pinned at a stale resolution.
+// `pnpm update` defaults to depth Infinity, so no flag is needed to reach
 // the whole tree. The re-resolution stage always runs — even when every direct dependency is
 // overridden and the `--latest` stage is absent, the indirect tiers still need re-resolving.
 const PNPM_UPDATE_ALL_TIERS = ['pnpm', 'update']

package/scripts/version/npm-registry.ts

@@ -7,7 +7,7 @@ import { z } from 'zod'
 import { release_age } from './release-age'
 
 // The public npm registry, read without credentials so a consumer who installed from public npm
-// can see the latest release without a `read:packages` GitHub token (joshuafolkken/kit#2882). The
+// can see the latest release without a `read:packages` GitHub token. The
 // GitHub Packages versions API stays the source for a scope routed there, and the fallback for a
 // package public npm does not carry.
 const PUBLIC_REGISTRY = 'https://registry.npmjs.org'
@@ -99,7 +99,7 @@ function read_release_times(package_name: string): Record<string, string> | unde
 // Whether public npm already carries `<name>@<version>`. **Asked of public npm regardless of how this
 // checkout routes the scope**, unlike the two readers above: `josh release` waits for `publish.yml`'s
 // `publish-npm` job and links the npmjs.com page, so GitHub Packages answering would not be the
-// question it asks (joshuafolkken/kit#3193).
+// question it asks.
 function has_public_version(package_name: string, version: string): boolean {
 	const parsed = times_schema.safeParse(read_packument(package_name, FULL_ACCEPT))
 

package/scripts/version/package-manager-version.ts

@@ -14,6 +14,12 @@ const PNPM_PIN_REGEX = /^pnpm@(.+)$/u
 const DEV_ENGINES_NAME_FIRST_REGEX = /("name":\s*"pnpm"\s*,\s*"version":\s*")[^"]+(")/u
 const DEV_ENGINES_VERSION_FIRST_REGEX = /("version":\s*")[^"]+("\s*,\s*"name":\s*"pnpm")/u
 
+// An `onFail: "error"` inside a `"packageManager": { … }` object — in a manifest that is only
+// `devEngines.packageManager`, since the top-level `packageManager` is a string — and never
+// `devEngines.runtime`, because `[^{}]` cannot cross into another block.
+const DEV_ENGINES_ON_FAIL_ERROR_REGEX = /("packageManager":\s*\{[^{}]*"onFail":\s*")error(")/u
+const ON_FAIL_DOWNLOAD = 'download'
+
 const optional_version_schema = z.object({ version: z.string().optional() }).optional()
 
 const alignment_read_schema = z.object({
@@ -86,10 +92,22 @@ function align_development_engines_version(content: string): string {
 	return set_development_engines_version(content, target)
 }
 
+// `onFail: "error"` rejects any pnpm that is not byte-for-byte the pin, so a machine that left
+// Corepack for a standalone pnpm cannot run pnpm at all; `"download"` fetches the pinned version
+// instead. Only `"error"` is rewritten — a `"warn"` / `"ignore"` the
+// project chose itself is kept, and the rest of the file is preserved byte-for-byte.
+function upgrade_development_engines_on_fail(content: string): string {
+	return content.replace(
+		DEV_ENGINES_ON_FAIL_ERROR_REGEX,
+		(_match: string, prefix: string, suffix: string) => `${prefix}${ON_FAIL_DOWNLOAD}${suffix}`,
+	)
+}
+
 const package_manager_version = {
 	extract_pnpm_pin,
 	align_development_engines_version,
 	set_development_engines_version,
+	upgrade_development_engines_on_fail,
 }
 
 export { package_manager_version }

package/scripts/version/publishable-range-check.ts

@@ -24,7 +24,8 @@ const FAILURE_EXIT_CODE = 1
 // consumer can resolve — the exact blind spot this guard exists to close.
 //
 // `pnpm view` rather than `npm view` because npm refuses to run at all inside a project whose
-// `devEngines.packageManager` names pnpm with `onFail: "error"`, failing every probe with
+// `devEngines.packageManager` names pnpm with an `onFail` other than `"warn"` / `"ignore"` (kit
+// ships `"download"`, which npm refuses on just the same), failing every probe with
 // EBADDEVENGINES instead of answering. Both are shimmed, so the filtered view is preserved.
 function probe_range(name: string, range: string): ProbeResult {
 	const result = execaSync('pnpm', ['view', `${name}@${range}`, 'version'], {

package/scripts/version/publishable-range.ts

@@ -4,7 +4,7 @@ import semver from 'semver'
 // kit ships a `preinstall` hook that installs @aikidosec/safe-chain, whose minimum-age policy hides
 // releases younger than its window from every install running behind it. A range whose floor sits
 // inside that window has no satisfying version for a consumer, so `pnpm install` fails with
-// ERR_PNPM_NO_MATCHING_VERSION naming a version that demonstrably exists and is tagged latest (#742).
+// ERR_PNPM_NO_MATCHING_VERSION naming a version that demonstrably exists and is tagged latest.
 //
 // The check asks the registry through that same filtered view instead of modelling the policy:
 // `pnpm view <name>@<range> version` prints no version and exits non-zero

package/scripts/version/release-age.ts

@@ -4,14 +4,14 @@ import { yaml_document } from '#scripts/lib/yaml-document'
 import semver from 'semver'
 import { z } from 'zod'
 
-// The minimum-release-age quarantine (kit#768), applied natively instead of inherited from
-// safe-chain's interception. safe-chain filters the registry only when the process tree was
-// started through one of its six wrapped shell commands, so `josh latest` and
-// `pnpm josh latest` used to resolve different "newest release" answers. These functions
-// make the resolution deterministic: the policy comes from the repo-managed `pnpm-workspace.yaml`,
-// the publish timestamps from the registry, and the selection is a pure computation over both.
-// pnpm 12 reads its settings from `pnpm-workspace.yaml` — a `minimum-release-age` line in `.npmrc`
-// is ignored there, so reading it would report a window pnpm does not apply (kit#3267).
+// The minimum-release-age quarantine, applied natively instead of inherited from safe-chain's
+// interception. safe-chain filters the registry only when the process tree was started through one
+// of its wrapped shell commands, so `josh latest` and `pnpm josh latest` would resolve different
+// "newest release" answers. These functions make the resolution deterministic: the policy comes
+// from the repo-managed `pnpm-workspace.yaml`, the publish timestamps from the registry, and the
+// selection is a pure computation over both. pnpm 12 reads its settings from `pnpm-workspace.yaml`
+// — a `minimum-release-age` line in `.npmrc` is ignored there, so reading it would report a window
+// pnpm does not apply.
 
 const NO_QUARANTINE_MINUTES = 0
 const WORKSPACE_PATH = 'pnpm-workspace.yaml'
@@ -78,7 +78,7 @@ function is_eligible(
 // `major` pins the search to one major line — what `josh latest` needs, since corepack validates the
 // resolved pnpm version against `devEngines`. Pass `undefined` to search every major, which is what
 // an "is this installable at all" question wants: `pnpm add pkg@latest` resolves to the newest
-// permitted release regardless of major (joshuafolkken/kit#808).
+// permitted release regardless of major.
 function select_aged_version(
 	times: Record<string, string>,
 	major: string | undefined,
@@ -112,7 +112,7 @@ function read_declared_minimum_release_age(workspace_path: string): number | und
 //
 // Deliberately not the upward walk below: `josh latest` resolves this against the working directory
 // it also writes `corepack use` into, and honouring an ancestor's policy there could freeze pnpm
-// bumps in a project that declares none (joshuafolkken/kit#808).
+// bumps in a project that declares none.
 function read_minimum_release_age(workspace_path: string = WORKSPACE_PATH): number {
 	return read_declared_minimum_release_age(workspace_path) ?? NO_QUARANTINE_MINUTES
 }
@@ -121,7 +121,7 @@ function read_minimum_release_age(workspace_path: string = WORKSPACE_PATH): numb
 //
 // This walks rather than reading one path because `josh version` and `josh latest` both run from
 // anywhere inside a project — and from outside one — so resolving against the working directory
-// alone would silently read "no quarantine" in every subdirectory (joshuafolkken/kit#808). pnpm
+// alone would silently read "no quarantine" in every subdirectory. pnpm
 // finds its workspace root the same way, by walking up to the nearest `pnpm-workspace.yaml`.
 //
 // `boundary` stops the walk at a known root. Production passes none, while tests bound the search

package/scripts/version/release-hold.ts

@@ -5,7 +5,7 @@ import { release_age } from './release-age'
 // *unpinned* resolution, so anything resolved without an explicit version stops one or more releases
 // short of `latest`. Reporting that as a bare `⚠ → <latest>` is indistinguishable from an install the
 // user forgot to upgrade — and it recurs after every successful upgrade, because the newest release
-// is by definition the youngest (joshuafolkken/kit#808).
+// is by definition the youngest.
 //
 // **The window binds unpinned resolution only.** Measured on pnpm 11.22.0 with
 // `minimumReleaseAge: 1440` and a release published 3.5 h earlier:
@@ -14,7 +14,7 @@ import { release_age } from './release-age'
 //   pnpm add pkg          ->  1.78.0   (the newest release past the window)
 //
 // So a pinned `Run:` hint always works and is never suppressed. What the window actually holds back
-// is peer resolution — the mechanism behind an upstream's effective install (joshuafolkken/kit#698),
+// is peer resolution — the mechanism behind an upstream's effective install,
 // which is why this explanation is attached there and nowhere else.
 
 const MINUTES_PER_HOUR = 60

package/scripts/version/safe-chain-version-update.ts

@@ -6,7 +6,7 @@ import { execaSync } from 'execa'
 const SAFE_CHAIN_PKG = '@aikidosec/safe-chain'
 
 // The registry's answer is trusted only as an exact semver version: it ends up in workflow files and
-// in the installer URL (joshuafolkken/kit#3266).
+// in the installer URL.
 function fetch_latest_version(): string | undefined {
 	const result = execaSync('npm', ['view', SAFE_CHAIN_PKG, 'version'], {
 		reject: false,
@@ -18,8 +18,8 @@ function fetch_latest_version(): string | undefined {
 }
 
 // The hash-verified installer pinned in the workflows is the one place a safe-chain release is
-// recorded; `preinstall` no longer names one (joshuafolkken/kit#3269). Every repository moves the
-// files that carry the pin — app-kit's own `dast.yml` / `load.yml` included (joshuafolkken/kit#2830).
+// recorded; `preinstall` no longer names one. Every repository moves the
+// files that carry the pin — app-kit's own `dast.yml` / `load.yml` included.
 function sync(): void {
 	const latest = fetch_latest_version()
 

package/scripts/version/version-check-logic.ts

@@ -29,8 +29,7 @@ interface VersionSnapshot {
 // What the local minimum-release-age policy permits an unpinned resolve to reach. Carried only on an
 // upstream report, because only the effective install is peer-resolved — every other target is
 // upgraded by an explicitly pinned command the window does not block. Optional throughout: a package
-// whose publish timestamps could not be read keeps exactly the report it had before
-// (joshuafolkken/kit#808).
+// whose publish timestamps could not be read keeps exactly the report it had before.
 interface ReleaseHold {
 	installable: string
 	minimum_age_minutes: number
@@ -75,7 +74,7 @@ interface EffectiveUpgradeHint {
 // `installed_versions` is populated only when the consumer declared its global upgrade command
 // pin-only (`is_global_upgrade_command_pinned`). It lists the globally-resolved versions kit already
 // knows, so a command whose every pin is already installed can be proven dead and replaced with an
-// explanation instead of a `Run:` hint (#697). Absent, no command is ever suppressed.
+// explanation instead of a `Run:` hint. Absent, no command is ever suppressed.
 interface UpstreamReport {
 	config: PackageVersionConfig
 	project_version: string | undefined

package/scripts/version/version-check.ts

@@ -4,8 +4,7 @@ import { version_check_arguments } from './version-check-arguments'
 import { version_commands } from './version-commands'
 
 // `version` shows the installed versions; `version --upgrade` updates both the global and the project
-// @joshuafolkken/kit install. The upgrade was a separate `version:upgrade` command until
-// joshuafolkken/kit#1928 folded it into this flag, so the version surface is one command again.
+// @joshuafolkken/kit install, so the version surface is one command.
 const UPGRADE_FLAG = '--upgrade'
 const ARGUMENT_OFFSET = 2
 const version_arguments = process.argv.slice(ARGUMENT_OFFSET)