@joshuafolkken/kit 1.3044.0 → 1.3092.0

package/scripts/run/wake/run-wake-handoff.ts

@@ -19,10 +19,7 @@ import { run_carry_reclaim } from '#scripts/run/carry/run-carry-reclaim'
 // The adoption also recovers a record whose owner died without a cut (`run-wake.ts` →
 // `decide_not_handed_off`): it rewrites the owner and clears any hand-off, whoever held it.
 //
-// **A Codex session cannot be given its session id** (`agent-argv.ts` → `build`), so neither its
-// transcript nor its pid is known here: it is adopted with the pid-less owner `run:carry --resume`
-// writes for it, and its pid is never moved onto the record — a pid it cannot match would make its
-// own counts a foreign live owner's.
+// Codex authenticates with a launch identity; the launched PID supplies liveness independently.
 //
 // `hand_off` is the older recovery the backlog preflight still runs: it marks the record handed off,
 // as a `--cut` does, so a later claim over it reads `resume` rather than `standing`.
@@ -34,7 +31,9 @@ interface WakeSession {
 }
 
 function session_owner(session: WakeSession): CarryOwner {
-	if (session.provider === agent_provider.OPENAI_PROVIDER) return { is_headless: true }
+	if (session.provider === agent_provider.OPENAI_PROVIDER) {
+		return { session: session.session_id, is_headless: true }
+	}
 
 	const directory = cost_transcript.transcript_directory(session.worktree)
 	const transcript = run_carry_conversation.transcript_of(session.session_id, directory)
@@ -60,11 +59,13 @@ function hand_to(target: string, owner: CarryOwner): void {
 	run_carry.adopt_carry(target, read.carry, { ...owner, provider: read.carry.scheduler_provider })
 }
 
-// Through `reclaim_at`, so the transcript the adoption named is what lets the pid move — one writer.
+// Through the shared reclaim writer, authenticated by transcript or launch identity.
 function hand_on(target: string, owner: CarryOwner, pid: number): void {
-	if (owner.transcript === undefined) return
+	if (owner.transcript === undefined && owner.session === undefined) return
 
-	run_carry_reclaim.reclaim_at(target, run_carry.owner_of(pid, undefined, owner.transcript))
+	const process_owner = run_carry.owner_of(pid, undefined, owner.transcript)
+
+	run_carry_reclaim.reclaim_at(target, { ...process_owner, session: owner.session })
 }
 
 // **The launched pid is the supervisor's own write, so it is no sign the session picked the run up**:

package/scripts/run/wake/run-wake-loop.ts

@@ -30,6 +30,8 @@ const STOPPED_BY_PERSON: LoopStop = { reason: STOPPED_REASON, note: undefined }
 const CODE_CHANGED: LoopStop = { reason: RELOAD_REASON, note: undefined }
 
 interface LoopPorts {
+	refresh?: () => void
+	session_failure?: () => string | undefined
 	// The carry record, re-read every pass rather than cached: it is written by the parent loop of a
 	// different session, which is the whole point of reading it here.
 	read_carry: () => CarryRead
@@ -200,14 +202,25 @@ async function retry_closes(ports: LoopPorts): Promise<void> {
 // stopping any lane. A record already removed ends the loop before this pass is reached, and a carry
 // record that ended or became unreadable stops the run before the code is checked, so a reload never
 // hands a finished run to a successor.
+async function preflight_stop(
+	decision: WakeDecision,
+	ports: LoopPorts,
+): Promise<LoopStop | undefined> {
+	if (decision.kind === 'stop') return undefined
+	const failure = ports.session_failure?.()
+	if (failure !== undefined) return { reason: FAILED_REASON, note: failure }
+
+	return (await ports.is_code_stale()) ? CODE_CHANGED : undefined
+}
+
 async function run_pass(
 	target: string,
 	wake: RunWake,
 	ports: LoopPorts,
 ): Promise<LoopStop | undefined> {
 	const decision = await decide_pass(wake, ports)
-
-	if (decision.kind !== 'stop' && (await ports.is_code_stale())) return CODE_CHANGED
+	const stop = await preflight_stop(decision, ports)
+	if (stop !== undefined) return stop
 
 	await retry_closes(ports)
 
@@ -254,12 +267,19 @@ function without_release_gap(ports: LoopPorts): LoopPorts {
 	}
 }
 
+function refreshed_wake(target: string, ports: LoopPorts): RunWake | undefined {
+	if (run_wake.read_own_wake(target) === undefined) return undefined
+	ports.refresh?.()
+
+	return run_wake.read_own_wake(target)
+}
+
 async function run_loop(target: string, ports: LoopPorts, interval_ms: number): Promise<LoopStop> {
 	const continuous = without_release_gap(ports)
 
 	return await poll.wait_for(
 		async () => {
-			const wake = run_wake.read_own_wake(target)
+			const wake = refreshed_wake(target, continuous)
 
 			return wake === undefined ? STOPPED_BY_PERSON : await run_pass(target, wake, continuous)
 		},

package/scripts/run/wake/run-wake-ports.ts

@@ -5,8 +5,10 @@ import { lane_close } from '#scripts/lane/lane-close'
 import { lane_withdraw_closed } from '#scripts/lane/lane-withdraw-closed'
 import { poll } from '#scripts/lib/poll'
 import { run_carry, type CarryOwner, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_session } from '#scripts/run/carry/run-carry-session'
 import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { run_headless } from '#scripts/run/run-headless'
+import { run_wake_codex } from './run-wake-codex'
 import type { WakeContext } from './run-wake-describe'
 import { run_wake_driver } from './run-wake-driver'
 import { run_wake_handoff } from './run-wake-handoff'
@@ -66,7 +68,12 @@ function launch_session(
 	if (built === undefined) return { kind: 'failed', note: UNSAFE_INVOCATION_NOTE }
 	if (built.kind === 'rejected') return { kind: 'failed', note: built.note }
 
-	const target = { cwd: context.worktree, env: session.environment, log_path: context.log_target }
+	const target = {
+		cwd: context.worktree,
+		env: session.environment,
+		log_path: run_wake_codex.log_path(context, session.id, profile),
+	}
+	if (profile.provider === 'openai') note_to_stderr(`session output: ${target.log_path}`)
 
 	return run_wake_session.launch({ argv: built.argv, ...target, profile }, note_to_stderr)
 }
@@ -136,7 +143,10 @@ function session_ports(context: WakeContext, profile: AgentProfile): SessionPort
 			wake_session(context, invocation, profile, {
 				id: session_id,
 				material,
-				environment: run_headless.environment(),
+				environment:
+					profile.provider === 'openai'
+						? { ...run_headless.environment(), [run_carry_session.KEY]: session_id }
+						: run_headless.environment(),
 			}),
 		wake_beside: (invocation, session_id, material) =>
 			wake_beside(context, invocation, profile, {
@@ -164,7 +174,11 @@ function ports_for(
 
 	return {
 		is_code_stale,
-		read_carry: () => run_carry.read_carry(context.carry_target),
+		refresh: () => {
+			run_wake_codex.refresh(context)
+		},
+		session_failure: () => run_wake_codex.failure(context),
+		read_carry: () => run_wake_codex.read_carry(context),
 		is_owner_live: (read) => read.kind === 'carried' && is_session_at_work(read.carry),
 		has_work: async () => true,
 		...session_ports(context, profile),

package/scripts/run/wake/run-wake-takeover.ts

@@ -1,3 +1,4 @@
+import { backlog_dispatch_bound } from '#scripts/backlog/backlog-dispatch-bound'
 import { process_identity } from '#scripts/josh/process-identity'
 import { poll } from '#scripts/lib/poll'
 import { MS_PER_SECOND } from '#scripts/lib/timeouts'
@@ -13,8 +14,10 @@ import { run_wake_stop } from './run-wake-stop'
 // bound, is a reload that failed.
 
 const TAKEOVER_INTERVAL_MS = MS_PER_SECOND
-// A cold `tsx` start claims within seconds; the bound is generous so a loaded machine is not a failure.
-const TAKEOVER_ATTEMPTS = 120
+// A cold `tsx` start claims within seconds. The successor still has a driver to start after its claim,
+// so the claim gets what the dispatch bound leaves after that start (joshuafolkken/kit#7507).
+const TAKEOVER_WAIT_MS = backlog_dispatch_bound.NOTICE_MS
+const TAKEOVER_ATTEMPTS = TAKEOVER_WAIT_MS / TAKEOVER_INTERVAL_MS
 
 type TakeoverResult = 'taken' | 'died' | 'unclaimed'
 
@@ -60,7 +63,7 @@ async function await_takeover(
 	return result
 }
 
-const run_wake_takeover = { await_takeover, ports_of }
+const run_wake_takeover = { TAKEOVER_WAIT_MS, await_takeover, ports_of }
 
 export type { TakeoverPorts, TakeoverResult }
 export { run_wake_takeover }

package/scripts/run/wake/run-wake-window.ts

@@ -1,3 +1,4 @@
+import { backlog_dispatch_bound } from '#scripts/backlog/backlog-dispatch-bound'
 import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 
 // **The driver is bounded so the supervisor reaches its pass boundary between dispatches**
@@ -10,6 +11,8 @@ const WINDOW_MS = WINDOW_MINUTES * MS_PER_MINUTE
 // **The supervisor's pause between passes is its own, not the driver's offer interval**
 // (joshuafolkken/kit#6718): a pass reads local records, and the backlog only through the driver, so
 // stretching the offer interval for the REST budget must not slow how soon a judgment hand-off is seen.
-const PASS_INTERVAL_MS = MS_PER_MINUTE
+// A pass may start a fresh driver, so the pause is what the dispatch bound leaves after that start
+// (joshuafolkken/kit#7507).
+const PASS_INTERVAL_MS = backlog_dispatch_bound.NOTICE_MS
 
 export const run_wake_window = { WINDOW_MINUTES, WINDOW_MS, PASS_INTERVAL_MS }

package/scripts/run/wake/run-wake.ts

@@ -45,6 +45,8 @@ interface RunWake {
 	woke: number
 	// The grace window is measured from this; cleared when the woken session claims the record.
 	woke_at?: string | undefined
+	// Kept after claim so legacy shared-log completion can authenticate the launch.
+	launch_at?: string | undefined
 	// Launches for the current cut: what was started, against `woke`'s what arrived.
 	attempts?: number | undefined
 	// Named in the failure warning, never killed — a slow session is still doing the run's work.
@@ -100,6 +102,7 @@ const run_wake_schema = process_owner_schema.extend({
 	started_at: z.string(),
 	woke: z.number(),
 	woke_at: z.string().optional(),
+	launch_at: z.string().optional(),
 	// Every optional `RunWake` field must be listed: `z.object` strips undeclared ones on the round trip.
 	attempts: z.number().optional(),
 	woke_pid: z.number().optional(),
@@ -199,6 +202,7 @@ function carried_state(existing: RunWake | undefined, invocation: string): Parti
 	return {
 		woke: existing.woke,
 		woke_at: existing.woke_at,
+		launch_at: existing.launch_at,
 		attempts: existing.attempts,
 		woke_pid: existing.woke_pid,
 		spawned: existing.spawned,
@@ -266,6 +270,7 @@ function count_claim(wake: RunWake): RunWake {
 	return {
 		...wake,
 		woke,
+		launch_at: wake.woke_at ?? wake.launch_at,
 		woke_at: undefined,
 		attempts: undefined,
 		idle_since: undefined,

package/scripts/sync/sync-ai-files.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { is_workflow_destination } from '#scripts/claude/workflow-destination'
 import { init_ai_copy } from '#scripts/init/init-ai-copy'
 import { transform_copied_content } from '#scripts/init/init-copy-content'
 import { init_logic } from '#scripts/init/init-logic'
@@ -7,7 +8,9 @@ import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import type { ProjectShape } from '#scripts/init/project-profile'
 import { security_policy } from '#scripts/init/security-policy'
 import { file_reader } from '#scripts/lib/read-file'
+import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
 import { pack_hook } from '#scripts/safe-chain/pack-hook'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { claude_settings_merge } from './claude-settings-merge'
 import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
 import { file_content } from './file-content'
@@ -20,7 +23,21 @@ const CLAUDE_MD_FILENAME = 'CLAUDE.md'
 const CLAUDE_SETTINGS_FILE = '.claude/settings.json'
 const CODEX_HOOKS_FILE = '.codex/hooks.json'
 
+function keep_custom_workflow(destination: string): boolean {
+	if (!is_workflow_destination(destination)) return false
+	const existing = file_reader.read_optional(destination)
+	if (existing === undefined) return false
+	const marker = `${managed_marker_logic.MARKER_PREFIX} ${KIT_PACKAGE_NAME}`
+	if (existing.split(/\r?\n/u, 1)[0] === marker) return false
+	console.warn(
+		`  ⚠ kept      ${destination} (custom workflow; migrate its acquisition settings manually)`,
+	)
+
+	return true
+}
+
 function sync_ai_file(source_path: string, destination_path: string): boolean {
+	if (keep_custom_workflow(destination_path)) return false
 	const content = readFileSync(source_path, 'utf8')
 
 	return file_content.write_text_if_changed(

package/scripts/sync/sync-configs.ts

@@ -35,7 +35,17 @@ function sync_with_merge(
 // lines, including env-var forms: npmrcAuthFile can opt the file into authentication from a deploy
 // dashboard that sync cannot inspect.
 function sync_npmrc(destination_path: string): void {
-	sync_with_merge(destination_path, '.npmrc', init_logic.merge_npmrc)
+	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : ''
+	const merged = init_logic.merge_npmrc(existing, path.dirname(destination_path))
+
+	if (merged === existing) {
+		console.info('  ✔ unchanged .npmrc')
+
+		return
+	}
+
+	file_content.write_contained(destination_path, merged)
+	console.info('  ✔ synced    .npmrc')
 }
 
 // Union-merge kit's .gitignore entries into the consumer file instead of overwriting it,

package/scripts/sync/sync.ts

@@ -194,7 +194,11 @@ function sync_consumer_resolved_development_deps(destination_path: string): void
 function sync_prepare_lefthook_warning(destination_path: string): void {
 	sync_package_json_with(
 		destination_path,
-		(existing) => init_logic.upgrade_prepare_lefthook_warning(existing),
+		(existing) =>
+			init_logic.upgrade_npm_lifecycle(
+				init_logic.upgrade_prepare_lefthook_warning(existing),
+				path.dirname(destination_path),
+			),
 		'  ✔ synced    prepare lefthook install warning (run `pnpm install`)',
 	)
 }

package/scripts/test/test-related-cap.ts

@@ -4,11 +4,12 @@ import { direct_importers } from './direct-importers'
 import { test_declared_logic } from './test-declared-logic'
 import { test_pinned_logic } from './test-pinned-logic'
 import { test_pinned_reach, type ReachedCount } from './test-pinned-reach'
+import { test_related_imports } from './test-related-imports'
 import { test_related_pins } from './test-related-pins'
 import { related_scope } from './test-related-scope'
 
 // **A change whose imports reach more than `test_pinned_logic.MAX_TEST_FILES` test files runs only the
-// tests importing its widest files directly** (joshuafolkken/kit#5532, #5702), as a file every test imports does
+// tests importing its widest files directly when their imports are unchanged** (#7453, #5532, #5702), as a file every test imports does
 // (`direct-importers.ts`): the tests past them stay unchecked here, for `josh gate`'s whole suite and
 // CI to run. `--keep-whole-suite` (the gate's unit leg) lifts the cap outside a lane
 // (`test-related-whole.ts`), and so does a missing graph.
@@ -85,7 +86,8 @@ async function direct_of(
 	root: string,
 	over_cap: ReadonlyArray<string>,
 ): Promise<Array<[string, Array<string>]>> {
-	const importers = await direct_importers.importers_of(root, over_cap)
+	const stable = await test_related_imports.stable_files(root, over_cap)
+	const importers = await direct_importers.importers_of(root, stable)
 	const narrowed = [...importers].filter(([, tests]) => tests.length > 0)
 
 	return narrowed.map(([file, tests]) => [file, test_related_pins.with_pins(file, tests)])
@@ -96,7 +98,9 @@ async function split_of(
 	root: string,
 	files: ReadonlyArray<string>,
 ): Promise<[Map<string, Array<string>>, Array<string>]> {
-	const every_test = await direct_importers.every_test_importers(root, files)
+	const shared = direct_importers.every_test_imports_of(files)
+	const stable = await test_related_imports.stable_files(root, shared)
+	const every_test = await direct_importers.every_test_importers(root, stable)
 
 	return [every_test, candidates_of(root, files, every_test)]
 }

package/scripts/test/test-related-imports.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { change_base } from '#scripts/git/change-base'
+import { git_spawn } from '#scripts/git/git-spawn'
+import type ts from 'typescript'
+
+type TypeScript = typeof ts
+
+interface Comparison {
+	base: string
+	typescript: TypeScript
+}
+
+// A new import can break an indirect test's mock while every direct importer passes (#7453).
+// Only unchanged import declarations and targets may use the direct-only cap. Unknown history keeps reach.
+function is_loading(typescript: TypeScript, node: ts.Node, source: ts.SourceFile): boolean {
+	if (!typescript.isCallExpression(node)) return false
+
+	return (
+		node.expression.kind === typescript.SyntaxKind.ImportKeyword ||
+		node.expression.getText(source) === 'require'
+	)
+}
+
+function signature(typescript: TypeScript, file: string, content: string): string {
+	const source = typescript.createSourceFile(file, content, typescript.ScriptTarget.Latest)
+	const declarations: Array<string> = []
+
+	function visit(node: ts.Node): void {
+		if (
+			typescript.isImportDeclaration(node) ||
+			typescript.isExportDeclaration(node) ||
+			is_loading(typescript, node, source)
+		) {
+			declarations.push(node.getText(source))
+		}
+
+		typescript.forEachChild(node, visit)
+	}
+
+	visit(source)
+
+	return JSON.stringify(declarations)
+}
+
+async function is_stable(root: string, file: string, comparison: Comparison): Promise<boolean> {
+	if (path.extname(file) === '.svelte') return false
+
+	try {
+		const before = await git_spawn.read(['-C', root, 'show', `${comparison.base}:${file}`])
+		const current = readFileSync(path.join(root, file), 'utf8')
+
+		return (
+			signature(comparison.typescript, file, before) ===
+			signature(comparison.typescript, file, current)
+		)
+	} catch {
+		return false
+	}
+}
+
+async function compare(root: string, files: ReadonlyArray<string>): Promise<Array<boolean>> {
+	try {
+		const base = await change_base.resolved_through_merge()
+		if (base === undefined) return files.map(() => false)
+		const { default: typescript } = await import('typescript')
+
+		return await Promise.all(
+			files.map(async (file) => await is_stable(root, file, { base, typescript })),
+		)
+	} catch {
+		return files.map(() => false)
+	}
+}
+
+async function stable_files(root: string, files: ReadonlyArray<string>): Promise<Array<string>> {
+	if (files.length === 0) return []
+	const stable = await compare(root, files)
+	const retained = files.filter((_file, index) => stable[index] !== true)
+
+	if (retained.length > 0) {
+		process.stdout.write(
+			`josh test:related: keeping full reach (imports changed or unknown): ${retained.join(', ')}\n`,
+		)
+	}
+
+	return files.filter((_file, index) => stable[index] === true)
+}
+
+const test_related_imports = { stable_files }
+
+export { test_related_imports }

package/scripts/test/vitest-failure-summary.ts

@@ -16,6 +16,8 @@ const UNIT_LOG_PREFIX = 'josh-unit-log-'
 const UNIT_LOG_HEADER = 'vitest'
 const FAILED_LINE = /^FAIL\s+(?<name>\S.*)$/u
 const FAILED_HEADING = 'failed tests:'
+const IMPORT_FAILURE =
+	/^(?:Error|SyntaxError): (?:\[vitest\] No "[^"\r\n]+" export is defined on the "[^"\r\n]+" mock\.|The requested module '[^'\r\n]+' does not provide an export named|Cannot find (?:module|package) |Failed to resolve import )[^\r\n]*$/mu
 const NONE_NAMED = '  (none named in the output — read the full output)'
 const NONE_NAMED_VERDICT = 'none named'
 // A name is `<file> > <suite> > <test>` or `<file> [ <file> ]`, prefixed `|<project>| ` in a workspace —
@@ -46,6 +48,10 @@ function failed_tests(output: string): ReadonlyArray<string> {
 	return [...new Set(names.filter((name) => name !== undefined))]
 }
 
+function import_failure(output: string): string | undefined {
+	return IMPORT_FAILURE.exec(stripVTControlCharacters(output))?.[0]
+}
+
 // The files the failed names belong to, each once — what to run after a fix, before the whole related
 // set again (joshuafolkken/kit#5023).
 function failed_files(names: ReadonlyArray<string>): ReadonlyArray<string> {
@@ -103,6 +109,7 @@ const vitest_failure_summary = {
 	RERUN_PREFIX,
 	failed_files,
 	failed_tests,
+	import_failure,
 	format_failure_summary,
 	report,
 	unit_log_path,

package/scripts/version/npm-registry.ts

@@ -4,12 +4,14 @@ import { COMMAND_TIMEOUT_MS, FETCH_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import semver from 'semver'
 import { z } from 'zod'
+import { KIT_PACKAGE_NAME } from './kit-descriptor'
 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. The
-// GitHub Packages versions API stays the source for a scope routed there, and the fallback for a
-// package public npm does not carry.
+// GitHub Packages versions API stays the source for other packages whose scope is routed there.
+// Kit always checks npm; version-remote retains GitHub as a diagnostic/legacy lookup fallback,
+// while kit upgrades still require npm publication and never switch acquisition back to GitHub.
 const PUBLIC_REGISTRY = 'https://registry.npmjs.org'
 // The abbreviated packument carries `dist-tags` without every version's full manifest.
 const ABBREVIATED_ACCEPT = 'application/vnd.npm.install-v1+json'
@@ -37,7 +39,7 @@ interface ViewAnswer {
 const FETCH_SCRIPT = [
 	'const [url, accept] = process.argv.slice(1)',
 	'const response = await fetch(url, { headers: { accept } })',
-	'if (!response.ok) process.exit(1)',
+	'if (!response.ok) { console.error(`HTTP ${response.status}`); process.exit(1) }',
 	'process.stdout.write(await response.text())',
 ].join('\n')
 
@@ -45,6 +47,11 @@ const FETCH_SCRIPT = [
 // install command, so `1.0.0;curl…|sh` or any other text is refused at the source, not downstream.
 const version_schema = z.string().refine((value) => semver.valid(value) === value)
 const latest_schema = z.looseObject({ 'dist-tags': z.looseObject({ latest: version_schema }) })
+const public_version_schema = z.looseObject({
+	name: z.string(),
+	version: version_schema,
+	dist: z.looseObject({ tarball: z.url(), integrity: z.string() }),
+})
 const times_schema = z.looseObject({ time: release_age.release_times_schema })
 const name_schema = z.looseObject({ name: z.string().optional() })
 const PUBLISHING_SCOPE = '@joshuafolkken/'
@@ -55,13 +62,27 @@ function packument_url(package_name: string): string {
 	return `${PUBLIC_REGISTRY}/${package_name.replace(SCOPE_SEPARATOR, () => ENCODED_SCOPE_SEPARATOR)}`
 }
 
-function read_packument(package_name: string, accept: string): unknown {
+function read_packument(
+	package_name: string,
+	accept: string,
+	should_require = false,
+	version?: string,
+): unknown {
+	const base = packument_url(package_name)
+	const url = version === undefined ? base : `${base}/${version}`
 	const result = execaSync(
 		process.execPath,
-		['--input-type=module', '-e', FETCH_SCRIPT, packument_url(package_name), accept],
+		['--input-type=module', '-e', FETCH_SCRIPT, url, accept],
 		{ reject: false, timeout: FETCH_TIMEOUT_MS },
 	)
-	if (result.exitCode !== 0) return undefined
+
+	if (result.exitCode !== 0) {
+		if (should_require) {
+			throw new Error(`Public npm request failed: ${package_name}: ${result.stderr}`)
+		}
+
+		return undefined
+	}
 
 	return json_value.parse_or_undefined(result.stdout)
 }
@@ -81,7 +102,7 @@ function is_github_registry(value: string): boolean {
 // `pnpm config get` (project `.npmrc` over user `~/.npmrc`). The two
 // registries are published by parallel jobs and can drift, so a consumer routed to GitHub Packages
 // keeps reading it: public npm could otherwise offer a release its registry does not carry yet.
-// Memoized per scope — kit and app-kit share one, and one report asks for both packages.
+// Memoized per scope for the generic consumers; kit bypasses this legacy registry routing.
 function is_github_scope(scope: string): boolean {
 	const is_cached_github = github_scopes.get(scope)
 	if (is_cached_github !== undefined) return is_cached_github
@@ -97,6 +118,7 @@ function is_github_scope(scope: string): boolean {
 }
 
 function is_public_source(package_name: string): boolean {
+	if (package_name === KIT_PACKAGE_NAME) return true
 	const scope = SCOPE_PATTERN.exec(package_name)?.[0]
 
 	return scope === undefined || !is_github_scope(scope)
@@ -130,6 +152,21 @@ function has_public_version(package_name: string, version: string): boolean {
 	return parsed.success && parsed.data.time[version] !== undefined
 }
 
+// The destination artifact, regardless of the checkout's old scope registry mapping.
+function read_public_version(
+	package_name: string,
+	version: string,
+): z.infer<typeof public_version_schema> | undefined {
+	if (!version_schema.safeParse(version).success) return undefined
+	const selected = public_version_schema.safeParse(
+		read_packument(package_name, FULL_ACCEPT, true, version),
+	)
+	if (!selected.success) return undefined
+	const entry = selected.data
+
+	return entry.name === package_name && entry.version === version ? entry : undefined
+}
+
 // **The one answer to "does this repository publish to npm"**: its package name when public npm
 // already carries it under kit's scope, otherwise nothing. Neither GitHub visibility nor `private`
 // decides it — a forgotten `private: true` must not turn publishing on — and the scope keeps a
@@ -170,6 +207,7 @@ const npm_registry = {
 	packument_url,
 	published_package_name,
 	read_latest,
+	read_public_version,
 	read_release_times,
 	valid_version,
 	view,

package/scripts/version/upgrade-shell-command.ts

@@ -1,3 +1,8 @@
+import path from 'node:path'
+import { PACKAGE_DIR } from '#scripts/init/init-paths'
+import { shell_quote } from '#scripts/lib/shell-quote'
+import { npm_acquisition } from '#scripts/registry-migration/npm-acquisition'
+import { KIT_PACKAGE_NAME } from './kit-descriptor'
 import type { PackageVersionConfig } from './version-command-config'
 
 // One upgrade the version commands offer and run: `text` is the line printed after `Run:`, and
@@ -20,7 +25,18 @@ function update_argv(
 	is_local: boolean,
 	config: PackageVersionConfig,
 ): Array<string> {
-	return ['pnpm', 'add', update_scope_flag(is_local), `${config.package_name}@${latest}`]
+	const registry =
+		!is_local && config.package_name === KIT_PACKAGE_NAME
+			? ['--config.@joshuafolkken:registry=https://registry.npmjs.org/']
+			: []
+
+	return [
+		'pnpm',
+		'add',
+		update_scope_flag(is_local),
+		...registry,
+		`${config.package_name}@${latest}`,
+	]
 }
 
 // The bare `pnpm add` invocation that installs one package at an exact version, in the global or the
@@ -33,6 +49,11 @@ function format_update_command(
 	return update_argv(latest, is_local, config).join(' ')
 }
 
+function needs_migration(is_local: boolean, package_name: string, root: string): boolean {
+	return is_local && package_name === KIT_PACKAGE_NAME && !npm_acquisition.is_project_npm(root)
+}
+
+// A kit project before migration first verifies the whole scope through the transactional entry.
 // The upgrade for one target. A project-scope install is followed by kit's lockfile repair
 // (`fix-gh-packages`), which a global install does not need. The printed text is derived from the
 // steps, so the hint and what actually runs cannot drift apart.
@@ -40,11 +61,22 @@ function build_upgrade_command(
 	latest: string,
 	is_local: boolean,
 	config: PackageVersionConfig,
+	root: string = process.cwd(),
 ): UpgradeCommand {
 	const steps = [update_argv(latest, is_local, config)]
+
+	if (needs_migration(is_local, config.package_name, root)) {
+		steps.unshift(['node', path.join(PACKAGE_DIR, 'dist/registry-migrate.mjs'), latest])
+	}
+
 	if (is_local) steps.push(['node_modules/.bin/tsx', config.fix_gh_packages_path])
 
-	return { text: steps.map((step) => step.join(' ')).join(STEP_SEPARATOR), steps }
+	return {
+		text: steps
+			.map((step) => step.map((argument) => shell_quote.word(argument)).join(' '))
+			.join(STEP_SEPARATOR),
+		steps,
+	}
 }
 
 // The consumer's own configured command — `pnpm add -g …`, or a chain with `&&` — is inside the trust