@mawesome/npm-vm 0.0.0-alpha.0 → 0.1.0

package/dist/cli.js

@@ -0,0 +1,4157 @@
+#!/usr/bin/env node
+import { C as redactUrls, D as EXIT, E as unsignedMessage, O as NpmVmError, S as noMatchMessage, T as transportMessage, _ as dirPermsMessage, b as keyMessage, g as changedMessage, h as abiMessage, k as isNpmVmError, m as verifyProvenance, v as engineMessage, w as restartMessage, x as lockedMessage, y as integrityMessage } from "./provenance--sOYCeF2.js";
+import { accessSync, chmodSync, closeSync, constants, copyFileSync, createReadStream, createWriteStream, existsSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { basename, dirname, isAbsolute, join, matchesGlob, posix, relative, resolve, sep, win32 } from "node:path";
+import { createHash, createPublicKey, randomBytes, verify } from "node:crypto";
+import semver from "semver";
+import { homedir, hostname } from "node:os";
+import { execFile, execFileSync } from "node:child_process";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { Parser } from "tar";
+import Config from "@npmcli/config";
+import npmDefinitions from "@npmcli/config/lib/definitions/index.js";
+import { createInterface } from "node:readline/promises";
+//#region src/own-npm.ts
+/**
+* Locates Node's own npm from the running binary (spec section 1).
+* The lib dir, not the `bin/npm` link: under `--link` that link is the shim.
+*/
+function ownNpmRoot(execPath, platform = process.platform) {
+	if (platform === "win32") return win32.join(win32.dirname(execPath), "node_modules", "npm");
+	let real = execPath;
+	try {
+		real = realpathSync(execPath);
+	} catch {}
+	return posix.join(posix.dirname(real), "..", "lib", "node_modules", "npm");
+}
+function findOwnNpm(execPath = process.execPath, platform = process.platform) {
+	const root = ownNpmRoot(execPath, platform);
+	const { join } = platform === "win32" ? win32 : posix;
+	const manifest = join(root, "package.json");
+	if (!existsSync(manifest)) return null;
+	let version;
+	try {
+		version = JSON.parse(readFileSync(manifest, "utf8")).version;
+	} catch {
+		return null;
+	}
+	if (typeof version !== "string") return null;
+	return {
+		root,
+		version,
+		cliPath: join(root, "bin", "npm-cli.js"),
+		npxCliPath: join(root, "bin", "npx-cli.js")
+	};
+}
+//#endregion
+//#region src/state/proc.ts
+function powershellPath(env = process.env) {
+	return join(env["SystemRoot"] ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+const SHELL_DIRS = [
+	"/bin",
+	"/usr/bin",
+	"/usr/local/bin",
+	"/opt/homebrew/bin",
+	"/snap/bin"
+];
+/**
+* An absolute path for a shell to probe (spec SEC-8): the login shell when `$SHELL` is absolute, else system dirs.
+* Never PATH, which inside an npm script starts with `node_modules/.bin`.
+*/
+function shellBinary(shell, env = process.env, platform = process.platform) {
+	const name = shell === "powershell" ? "pwsh" : shell;
+	if (platform === "win32") {
+		const pwsh = join(env["ProgramFiles"] ?? "C:\\Program Files", "PowerShell", "7", "pwsh.exe");
+		return shell === "powershell" && existsSync(pwsh) ? pwsh : null;
+	}
+	const login = env["SHELL"];
+	return [...login !== void 0 && isAbsolute(login) && basename(login) === name ? [login] : [], ...SHELL_DIRS.map((dir) => join(dir, name))].find((candidate) => existsSync(candidate)) ?? null;
+}
+/** The start identity of `pid`, or null when the lookup fails or is ambiguous. */
+function startIdentity(pid, platform = process.platform, env = process.env) {
+	try {
+		if (platform === "linux") {
+			const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+			const start = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[19];
+			return start !== void 0 && /^\d+$/.test(start) ? start : null;
+		}
+		if (platform === "darwin") {
+			const out = execFileSync("/bin/ps", [
+				"-o",
+				"lstart=",
+				"-p",
+				String(pid)
+			], {
+				encoding: "utf8",
+				env: {
+					LC_ALL: "C",
+					PATH: "/usr/bin:/bin"
+				}
+			}).trim();
+			return out === "" || out.includes("\n") ? null : out;
+		}
+		if (platform === "win32") {
+			const out = execFileSync(powershellPath(env), [
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				`(Get-Process -Id ${pid}).StartTime.ToFileTimeUtc()`
+			], {
+				encoding: "utf8",
+				windowsHide: true
+			}).trim();
+			return /^\d+$/.test(out) ? out : null;
+		}
+	} catch {
+		return null;
+	}
+	return null;
+}
+function ownIdentity(platform, env) {
+	return {
+		pid: process.pid,
+		start: startIdentity(process.pid, platform, env)
+	};
+}
+/**
+* Whether the recorded process still runs: dead only when the PID is gone or its start identity differs.
+* Any failure to look up means live, so nothing ever expires a process that merely cannot be inspected.
+*/
+function isLive(identity, platform = process.platform) {
+	try {
+		process.kill(identity.pid, 0);
+	} catch (error) {
+		if (error.code === "ESRCH") return false;
+		return true;
+	}
+	if (identity.start === null) return true;
+	const current = startIdentity(identity.pid, platform);
+	return current === null || current === identity.start;
+}
+//#endregion
+//#region src/state/lease.ts
+function leasesDir(entry) {
+	return `${entry}.leases`;
+}
+function gatePath(entry) {
+	return `${entry}.prune`;
+}
+function newToken() {
+	return randomBytes(8).toString("hex");
+}
+function ownerRecord(machineId, identity = ownIdentity()) {
+	return {
+		...identity,
+		host: hostname(),
+		machineId,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function readOwner(file) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (typeof parsed.pid !== "number") return null;
+		return {
+			pid: parsed.pid,
+			start: typeof parsed.start === "string" ? parsed.start : null,
+			host: typeof parsed.host === "string" ? parsed.host : "?",
+			machineId: typeof parsed.machineId === "string" ? parsed.machineId : "?",
+			createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : ""
+		};
+	} catch {
+		return null;
+	}
+}
+/** A file in the per-machine cache belongs to a dead owner only when PROC-1 says so; unreadable means live. */
+function ownerLive(file) {
+	const owner = readOwner(file);
+	return owner === null ? true : isLive(owner);
+}
+/** Creates a shared lease on `entry`; the file name is unique, so a prune can never delete a live one by mistake. */
+function createLease(entry, owner) {
+	const dir = leasesDir(entry);
+	for (let attempt = 0;; attempt += 1) {
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const path = join(dir, newToken());
+		try {
+			writeFileSync(path, JSON.stringify(owner), {
+				mode: 384,
+				flag: "wx"
+			});
+		} catch (error) {
+			rmSync(path, { force: true });
+			if (error.code === "ENOENT" && attempt < 3) continue;
+			throw error;
+		}
+		return {
+			path,
+			release() {
+				rmSync(path, { force: true });
+			}
+		};
+	}
+}
+/**
+* Whether a lease created before a gate check is still in place (spec LEASE-1).
+* A prune that passed its own lease check first moves the whole leases dir away, taking the file with it.
+*/
+function leaseSurvived(lease) {
+	return existsSync(lease.path);
+}
+function listLeases(entry) {
+	try {
+		return readdirSync(leasesDir(entry)).map((name) => join(leasesDir(entry), name));
+	} catch {
+		return [];
+	}
+}
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const GATE_WAIT_MS = 5e3;
+/**
+* The runtime's shared lease (spec LEASE-1): lease first, then look for a live prune gate.
+* A live gate means the entry is going away: wait briefly, retry once, else return null so the caller fetches a private entry.
+*/
+async function acquireShared(entry, owner, options = {}) {
+	for (let attempt = 0; attempt < 3; attempt += 1) {
+		const lease = createLease(entry, owner);
+		const gate = gatePath(entry);
+		let gated = false;
+		try {
+			gated = ownerLive(gate);
+		} catch {
+			gated = false;
+		}
+		if (!gated || !gateExists(gate)) {
+			if (leaseSurvived(lease)) return lease;
+			continue;
+		}
+		lease.release();
+		const deadline = Date.now() + (options.waitMs ?? GATE_WAIT_MS);
+		while (Date.now() < deadline && gateExists(gate)) await sleep$1(50);
+	}
+	return null;
+}
+function gateExists(gate) {
+	try {
+		return readOwner(gate) !== null;
+	} catch {
+		return false;
+	}
+}
+/** Creates the prune gate with O_EXCL; false when another gate exists (there is only ever one prune, so a leftover). */
+function createGate(entry, owner) {
+	try {
+		writeFileSync(gatePath(entry), JSON.stringify(owner), {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		rmSync(gatePath(entry), { force: true });
+		throw error;
+	}
+	return true;
+}
+function removeGate(entry) {
+	rmSync(gatePath(entry), { force: true });
+}
+//#endregion
+//#region src/spec.ts
+var SpecError = class extends Error {
+	name = "SpecError";
+	field;
+	/** The project's policy for this failure, when the entry declaring it could still be read. */
+	onFail = "error";
+	constructor(field, message) {
+		super(message);
+		this.field = field;
+	}
+};
+const MAX_RANGE_LENGTH = 256;
+const HASH_HEX_LENGTH = {
+	sha512: 128,
+	sha256: 64,
+	sha224: 56
+};
+const ON_FAIL = /* @__PURE__ */ new Set([
+	"ignore",
+	"warn",
+	"error",
+	"download"
+]);
+/**
+* Validates one version string before it reaches a transport argv or a message (spec RES-4).
+* Build metadata other than a well-formed hash suffix is rejected: semver would silently drop it.
+*/
+function parseVersionSpec(raw, field) {
+	if (raw.length > MAX_RANGE_LENGTH) throw new SpecError(field, `${field}: version is longer than ${MAX_RANGE_LENGTH} characters`);
+	const plus = raw.indexOf("+");
+	const range = (plus === -1 ? raw : raw.slice(0, plus)).trim();
+	let hash = null;
+	if (plus !== -1) hash = parseHash(raw.slice(plus + 1), field);
+	if (semver.validRange(range) === null) throw new SpecError(field, `${field}: ${JSON.stringify(raw)} is not a semver range`);
+	const exact = semver.valid(range);
+	if (hash !== null && exact === null) throw new SpecError(field, `${field}: a hash needs an exact version, got ${JSON.stringify(raw)}`);
+	return {
+		range,
+		exact,
+		hash
+	};
+}
+function parseHash(suffix, field) {
+	const match = /^(sha512|sha256|sha224)\.([0-9a-fA-F]+)$/.exec(suffix);
+	if (match === null) throw new SpecError(field, `${field}: unsupported hash suffix ${JSON.stringify(`+${suffix}`)}`);
+	const algorithm = match[1];
+	const hex = match[2].toLowerCase();
+	if (hex.length !== HASH_HEX_LENGTH[algorithm]) throw new SpecError(field, `${field}: ${algorithm} hash must be ${HASH_HEX_LENGTH[algorithm]} hex characters`);
+	return {
+		algorithm,
+		hex
+	};
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reads the npm requirements of a parsed `package.json` (spec RES-4).
+* Returns null when the project declares nothing for npm, including when it declares only pnpm or yarn.
+*/
+function parseSpecs(pkg) {
+	if (!isObject(pkg)) return null;
+	const devEngines = pkg["devEngines"];
+	if (isObject(devEngines) && devEngines["packageManager"] !== void 0) {
+		const fromDevEngines = parseDevEngines(devEngines["packageManager"]);
+		if (fromDevEngines !== null) return fromDevEngines;
+	}
+	const packageManager = pkg["packageManager"];
+	if (typeof packageManager === "string" && packageManager.startsWith("npm@")) {
+		const field = "packageManager";
+		return {
+			specs: [parseVersionSpec(packageManager.slice(4), field)],
+			onFail: "error",
+			field
+		};
+	}
+	return null;
+}
+function parseDevEngines(value) {
+	const field = "devEngines.packageManager";
+	const entries = Array.isArray(value) ? value : [value];
+	if (entries.length === 0) return null;
+	const specs = [];
+	const last = entries[entries.length - 1];
+	const onFail = isObject(last) ? parseOnFail(last, field) : "error";
+	try {
+		for (const entry of entries) {
+			if (!isObject(entry)) throw new SpecError(field, `${field}: every entry must be an object`);
+			if (entry["name"] !== "npm") continue;
+			const version = entry["version"];
+			if (version === void 0) specs.push({
+				range: "*",
+				exact: null,
+				hash: null
+			});
+			else if (typeof version === "string") specs.push(parseVersionSpec(version, field));
+			else throw new SpecError(field, `${field}: version must be a string`);
+		}
+	} catch (error) {
+		if (error instanceof SpecError) error.onFail = onFail;
+		throw error;
+	}
+	if (specs.length === 0) return null;
+	return {
+		specs,
+		onFail,
+		field: "devEngines"
+	};
+}
+function parseOnFail(entry, field) {
+	const onFail = entry.onFail;
+	if (onFail === void 0) return "error";
+	if (typeof onFail !== "string" || !ON_FAIL.has(onFail)) throw new SpecError(field, `${field}: onFail must be ignore, warn, error or download`);
+	return onFail;
+}
+/** Whether a concrete version satisfies the spec's range, hash aside (spec RES-5 and RES-6). */
+function matchesRange(version, spec) {
+	return semver.satisfies(version, spec.range);
+}
+//#endregion
+//#region src/select.ts
+function engineAccepts(candidate, nodeVersion) {
+	return candidate.enginesNode === null || semver.satisfies(nodeVersion, candidate.enginesNode, { includePrerelease: true });
+}
+function hashAccepts(candidate, spec) {
+	if (spec.hash === null) return candidate.keyid !== null;
+	if (spec.hash.algorithm === "sha512") return sriHex(candidate.integrity) === spec.hash.hex;
+	if (candidate.digests === void 0 || candidate.digests === null) return true;
+	return candidate.digests[spec.hash.algorithm] === spec.hash.hex;
+}
+/** The hex digest of a `sha512-<base64>` SRI string, or null for any other form. */
+function sriHex(integrity) {
+	const match = /^sha512-([A-Za-z0-9+/=]+)$/.exec(integrity.trim());
+	return match === null ? null : Buffer.from(match[1], "base64").toString("hex");
+}
+/** Whether Node's own npm satisfies a spec without a hash (spec RES-5). */
+function ownNpmSatisfies(ownVersion, specs) {
+	return specs.some((spec) => spec.hash === null && matchesRange(ownVersion, spec));
+}
+/**
+* Picks the highest candidate matching any spec and the active Node (spec RES-6), cached first.
+* Returns the reason when nothing fits, distinguishing an `engines.node` exclusion from no match at all.
+*/
+function selectCandidate(specs, candidates, nodeVersion) {
+	let best = null;
+	let excluded = null;
+	for (const candidate of candidates) {
+		const matching = specs.filter((entry) => matchesRange(candidate.version, entry) && hashAccepts(candidate, entry));
+		if (matching.length === 0) continue;
+		if (!engineAccepts(candidate, nodeVersion)) {
+			if (excluded === null || semver.gt(candidate.version, excluded.version)) excluded = candidate;
+			continue;
+		}
+		if (best === null || semver.gt(candidate.version, best.candidate.version)) best = {
+			candidate,
+			hashes: matching.some((entry) => entry.hash === null) ? [] : matching.flatMap((entry) => entry.hash === null ? [] : [entry.hash])
+		};
+	}
+	if (best !== null) return {
+		kind: "selected",
+		selection: best
+	};
+	if (excluded !== null) return {
+		kind: "failed",
+		failure: {
+			kind: "engine",
+			version: excluded.version,
+			enginesNode: excluded.enginesNode ?? "*"
+		}
+	};
+	return {
+		kind: "failed",
+		failure: {
+			kind: "nomatch",
+			reason: "no published version matches"
+		}
+	};
+}
+//#endregion
+//#region src/install/verify.ts
+/** Every digest a spec or the registry may ask for, in one pass over the file. */
+async function fileDigests(file) {
+	const sha512 = createHash("sha512");
+	const sha256 = createHash("sha256");
+	const sha224 = createHash("sha224");
+	await pipeline(createReadStream(file), new Transform({ transform(chunk, _encoding, callback) {
+		sha512.update(chunk);
+		sha256.update(chunk);
+		sha224.update(chunk);
+		callback();
+	} }));
+	const sha512Digest = sha512.digest();
+	return {
+		sha512: `sha512-${sha512Digest.toString("base64")}`,
+		sha512hex: sha512Digest.toString("hex"),
+		sha256hex: sha256.digest("hex"),
+		sha224hex: sha224.digest("hex")
+	};
+}
+function integrityFailure(expected, actual, detail) {
+	return new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(expected, actual, detail));
+}
+/** The tarball must match the registry's integrity and, when the project pins hashes, one of them (spec SEC-2). */
+function checkIntegrity(digests, integrity, hashes) {
+	if (digests.sha512 !== integrity.trim()) throw integrityFailure(integrity, digests.sha512, "the tarball does not match the registry integrity");
+	if (hashes.length === 0) return;
+	const actual = {
+		sha512: digests.sha512hex,
+		sha256: digests.sha256hex,
+		sha224: digests.sha224hex
+	};
+	if (!hashes.some((hash) => actual[hash.algorithm] === hash.hex)) {
+		const [first] = hashes;
+		throw integrityFailure(`${first.algorithm}.${first.hex}`, `${first.algorithm}.${actual[first.algorithm]}`, "the tarball does not match the pinned hash");
+	}
+}
+/**
+* Checks the registry signatures over `name@version:integrity` against the pinned keyring (spec SEC-1).
+* Returns the key id that verified; throws M-KEY for an unknown key and M-UNSIGNED when no signature is usable.
+*/
+async function verifySignatures(input) {
+	if (input.signatures.length === 0) {
+		if (input.pinned) return null;
+		throw new NpmVmError("M-UNSIGNED", EXIT.verification, unsignedMessage(input.registry, input.version));
+	}
+	const payload = Buffer.from(`${input.name}@${input.version}:${input.integrity}`, "utf8");
+	let unknown = null;
+	for (const signature of input.signatures) {
+		const key = input.keys.find((entry) => entry.keyid === signature.keyid);
+		if (key === void 0) {
+			unknown ??= signature.keyid;
+			continue;
+		}
+		if (key.revoked === true || !await keyCurrent(key, input.publishedAt)) continue;
+		const publicKey = createPublicKey({
+			key: Buffer.from(key.key, "base64"),
+			format: "der",
+			type: "spki"
+		});
+		if (verify("sha256", payload, publicKey, Buffer.from(signature.sig, "base64"))) return key.keyid;
+	}
+	if (unknown !== null) throw new NpmVmError("M-KEY", EXIT.verification, keyMessage(unknown));
+	throw new NpmVmError("M-UNSIGNED", EXIT.verification, unsignedMessage(input.registry, input.version));
+}
+/** An expired key still vouches for versions published before it expired; an unknown time fails closed. */
+async function keyCurrent(key, publishedAt) {
+	if (key.expires === null) return true;
+	const published = await publishedAt();
+	return published !== null && Date.parse(published) < Date.parse(key.expires);
+}
+const DEFAULT_LIMITS = {
+	maxEntries: 1e4,
+	maxBytes: 268435456
+};
+function unsafe(detail) {
+	return integrityFailure("a safe npm tarball", "an unsafe entry", detail);
+}
+/** The destination-relative path of a tarball entry, or a thrown M-INTEGRITY for anything outside `package/` (spec SEC-3). */
+function entryRelativePath(path) {
+	if (path.includes("\\") || [...path].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) throw unsafe(`entry name contains a control character or backslash: ${JSON.stringify(path)}`);
+	if (path.startsWith("/") || /^[A-Za-z]:/.test(path)) throw unsafe(`absolute entry name: ${path}`);
+	const segments = path.split("/").filter((segment) => segment !== "" && segment !== ".");
+	if (segments.includes("..")) throw unsafe(`entry name climbs out of the archive: ${path}`);
+	if (segments[0] !== "package") throw unsafe(`entry outside package/: ${path}`);
+	return segments.length === 1 ? "" : posix.join(...segments.slice(1));
+}
+/**
+* Extracts regular files and directories under `package/` into `dest`, rejecting everything else (spec SEC-3).
+* Modes are `0644` or `0755` by the owner exec bit; ownership and extended attributes are ignored.
+*/
+async function safeExtract(tarball, dest, limits = DEFAULT_LIMITS) {
+	let entries = 0;
+	let bytes = 0;
+	let decompressed = 0;
+	const writes = [];
+	const parser = new Parser({ strict: true });
+	let aborted = null;
+	const abort = (error) => {
+		aborted ??= error;
+		parser.abort(error);
+	};
+	parser.on("entry", (entry) => {
+		try {
+			entries += 1;
+			bytes += entry.size;
+			if (entries > limits.maxEntries) throw unsafe(`more than ${limits.maxEntries} entries`);
+			if (bytes > limits.maxBytes) throw unsafe(`more than ${limits.maxBytes} bytes`);
+			const relative = entryRelativePath(entry.path);
+			const target = relative === "" ? dest : join(dest, relative);
+			if (entry.type === "Directory") {
+				mkdirSync(target, {
+					recursive: true,
+					mode: 493
+				});
+				entry.resume();
+				return;
+			}
+			if (entry.type !== "File" || relative === "") throw unsafe(`${entry.type} entry: ${entry.path}`);
+			mkdirSync(dirname(target), {
+				recursive: true,
+				mode: 493
+			});
+			const mode = ((entry.mode ?? 420) & 64) === 0 ? 420 : 493;
+			writes.push(pipeline(entry, createWriteStream(target, { mode })));
+		} catch (error) {
+			abort(error);
+		}
+	});
+	const counter = new Transform({ transform(chunk, _encoding, callback) {
+		decompressed += chunk.length;
+		if (decompressed > limits.maxBytes) {
+			callback(unsafe(`more than ${limits.maxBytes} bytes after decompression`));
+			return;
+		}
+		callback(null, chunk);
+	} });
+	const done = new Promise((resolve, reject) => {
+		parser.on("end", () => resolve());
+		parser.on("error", (error) => reject(error));
+	});
+	done.catch(() => void 0);
+	try {
+		await pipeline(createReadStream(tarball), createGunzip(), counter, parser);
+		await done;
+		await Promise.all(writes);
+	} catch (error) {
+		await Promise.allSettled(writes);
+		throw aborted ?? (error instanceof NpmVmError ? error : unsafe(`cannot read the tarball: ${error.message}`));
+	}
+	if (aborted !== null) throw aborted;
+}
+const VERIFIED_FILE = ".verified";
+function writeVerified(dir, verified) {
+	writeFileSync(join(dir, VERIFIED_FILE), JSON.stringify(verified), { mode: 384 });
+}
+function readVerified(dir) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dir, VERIFIED_FILE), "utf8"));
+		if (typeof parsed.version !== "string" || typeof parsed.integrity !== "string") return null;
+		if (typeof parsed.sha256 !== "string" || typeof parsed.sha224 !== "string") return null;
+		return {
+			version: parsed.version,
+			integrity: parsed.integrity,
+			keyid: typeof parsed.keyid === "string" ? parsed.keyid : null,
+			sha256: parsed.sha256,
+			sha224: parsed.sha224,
+			verifiedAt: typeof parsed.verifiedAt === "string" ? parsed.verifiedAt : ""
+		};
+	} catch {
+		return null;
+	}
+}
+/** `<version>-<16 hex of the integrity>`: two registries serving different bytes get two entries (spec SEC-4). */
+function entryName(version, integrity) {
+	const hex = sriHex(integrity);
+	if (hex === null) throw new Error(`not a sha512 integrity: ${integrity}`);
+	return `${version}-${hex.slice(0, 16)}`;
+}
+/** Where verified entries are staged before the rename into `npm/`: same filesystem, so the rename stays atomic. */
+function stagingDir(cacheRoot) {
+	return join(cacheRoot, "staging");
+}
+function canonicalEntry(cacheRoot, version, integrity) {
+	return join(cacheRoot, "npm", entryName(version, integrity));
+}
+function privateEntry(canonical, token) {
+	return `${canonical}.${token}`;
+}
+/** Whether a directory name under `npm/` is an entry rather than a lease dir, a gate or a deletion in progress. */
+function isEntryName(name) {
+	return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?-[0-9a-f]{16}(?:\.[0-9a-f]{16})?$/.test(name);
+}
+function readManifest$2(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		const engines = pkg["engines"];
+		const node = typeof engines === "object" && engines !== null ? engines["node"] : void 0;
+		return {
+			name: pkg["name"],
+			version: pkg["version"],
+			enginesNode: typeof node === "string" ? node : null
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether an entry may run (spec SEC-5): verified for this integrity, owned by the current user,
+* and holding the npm it claims. Never deletes anything.
+*/
+function validateEntry(entryPath, integrity) {
+	try {
+		const stat = statSync(entryPath);
+		if (!stat.isDirectory() || process.getuid !== void 0 && stat.uid !== process.getuid()) return false;
+	} catch {
+		return false;
+	}
+	const verified = readVerified(entryPath);
+	if (verified === null || verified.integrity !== integrity) return false;
+	const manifest = readManifest$2(entryPath);
+	return manifest !== null && manifest.name === "npm" && manifest.version === verified.version;
+}
+/** Every verified entry in the cache as a candidate, whatever its validity; use-time validation decides. */
+function listEntries(cacheRoot, keys = []) {
+	let names;
+	try {
+		names = readdirSync(join(cacheRoot, "npm"));
+	} catch {
+		return [];
+	}
+	const candidates = [];
+	for (const name of names) {
+		if (!isEntryName(name)) continue;
+		const entryPath = join(cacheRoot, "npm", name);
+		const verified = readVerified(entryPath);
+		const manifest = readManifest$2(entryPath);
+		if (verified === null || manifest === null || manifest.version !== verified.version) continue;
+		if (verified.keyid !== null && keys.some((key) => key.keyid === verified.keyid && key.revoked === true)) continue;
+		candidates.push({
+			version: verified.version,
+			enginesNode: manifest.enginesNode,
+			integrity: verified.integrity,
+			entryPath,
+			signatures: null,
+			keyid: verified.keyid,
+			digests: {
+				sha256: verified.sha256,
+				sha224: verified.sha224
+			}
+		});
+	}
+	return candidates;
+}
+function isCollision(error) {
+	const code = error.code;
+	return code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM" || code === "EISDIR";
+}
+/**
+* Moves a verified temp dir into the cache under a lease (spec SEC-4). The lease exists before the
+* rename, so a prune never sees the entry without it; a lost race reuses or sidesteps the winner's entry.
+*/
+function publishEntry(tempDir, canonical, integrity, owner) {
+	const lease = createLease(canonical, owner);
+	if (existsSync(gatePath(canonical)) && ownerLive(gatePath(canonical))) {
+		lease.release();
+		return publishPrivately(tempDir, canonical, owner);
+	}
+	if (!leaseSurvived(lease)) return publishEntry(tempDir, canonical, integrity, owner);
+	try {
+		renameSync(tempDir, canonical);
+		return {
+			entryPath: canonical,
+			lease
+		};
+	} catch (error) {
+		if (!isCollision(error)) {
+			lease.release();
+			throw error;
+		}
+	}
+	if (validateEntry(canonical, integrity)) {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+		return {
+			entryPath: canonical,
+			lease
+		};
+	}
+	lease.release();
+	return publishPrivately(tempDir, canonical, owner);
+}
+function publishPrivately(tempDir, canonical, owner) {
+	for (;;) {
+		const entryPath = privateEntry(canonical, newToken());
+		const privateLease = createLease(entryPath, owner);
+		if (existsSync(gatePath(entryPath)) && ownerLive(gatePath(entryPath))) {
+			privateLease.release();
+			continue;
+		}
+		if (!leaseSurvived(privateLease)) continue;
+		try {
+			renameSync(tempDir, entryPath);
+		} catch (error) {
+			privateLease.release();
+			throw error;
+		}
+		return {
+			entryPath,
+			lease: privateLease
+		};
+	}
+}
+//#endregion
+//#region src/state/atomic.ts
+const RETRY_CODES = /* @__PURE__ */ new Set([
+	"EBUSY",
+	"EPERM",
+	"EACCES"
+]);
+const RETRY_LIMIT_MS = 5e3;
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+* Runs a file operation, retrying Windows sharing violations with backoff for up to 5 s (spec MUT-3).
+* Elsewhere the same codes are real permission errors and surface at once.
+*/
+function withSharingRetry(operation, platform = process.platform, limitMs = RETRY_LIMIT_MS) {
+	const started = Date.now();
+	let delay = 20;
+	for (;;) try {
+		return operation();
+	} catch (error) {
+		const code = error.code ?? "";
+		if (platform !== "win32" || !RETRY_CODES.has(code) || Date.now() - started + delay > limitMs) throw error;
+		sleepSync(delay);
+		delay = Math.min(delay * 2, 500);
+	}
+}
+/** Writes `content` to `path` through a temp file in the same dir, fsynced and renamed into place. */
+function atomicWrite(path, content, mode = 420) {
+	const dir = dirname(path);
+	mkdirSync(dir, { recursive: true });
+	const temp = join(dir, `.${newToken()}.tmp`);
+	try {
+		const fd = openSync(temp, "wx", mode);
+		try {
+			const buffer = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+			for (let offset = 0; offset < buffer.length;) {
+				const written = writeSync(fd, buffer, offset, buffer.length - offset);
+				if (written <= 0) throw new Error(`short write to ${temp}: ${offset} of ${buffer.length} bytes`);
+				offset += written;
+			}
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		withSharingRetry(() => renameSync(temp, path));
+	} catch (error) {
+		rmSync(temp, { force: true });
+		throw error;
+	}
+}
+/** Renames with the Windows retry; a cross-device rename is not retried, it is a layout error. */
+function atomicRename(from, to) {
+	withSharingRetry(() => renameSync(from, to));
+}
+function removeWithRetry(path) {
+	withSharingRetry(() => rmSync(path, {
+		recursive: true,
+		force: true
+	}));
+}
+//#endregion
+//#region src/state/prune.ts
+const USED_SUFFIX = ".used";
+/** Records a resolution of `entry` for the prune age, in a sidecar so the entry itself stays untouched. */
+function touchUsed(entry) {
+	const marker = `${entry}${USED_SUFFIX}`;
+	try {
+		const now = /* @__PURE__ */ new Date();
+		utimesSync(marker, now, now);
+	} catch {
+		writeFileSync(marker, "", { flag: "a" });
+	}
+}
+function lastUsed(entry) {
+	try {
+		return statSync(`${entry}${USED_SUFFIX}`).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+/** Why one entry would go, or null to keep it. */
+function pruneReason(cacheRoot, name, options) {
+	const entry = join(cacheRoot, "npm", name);
+	if (name.includes(".deleting.")) return "leftover";
+	if (!isEntryName(name)) return null;
+	const verified = readVerified(entry);
+	if (verified === null || !validateEntry(entry, verified.integrity)) return "invalid";
+	if (/\.[0-9a-f]{16}$/.test(name) && !listLeases(entry).some((lease) => ownerLive(lease))) return "orphan-private";
+	const used = lastUsed(entry);
+	return (options.now ?? Date.now()) - (used ?? statSync(entry).mtimeMs) > options.maxAgeMs ? "stale" : null;
+}
+/**
+* Removes one entry the exclusive way (spec LEASE-1): gate, drop dead leases, bail on a live one, rename aside, drop the gate, delete.
+* After the gate is gone nothing here touches the entry's paths again.
+*/
+function pruneEntry(entry, owner) {
+	if (existsSync(gatePath(entry)) && !ownerLive(gatePath(entry))) removeGate(entry);
+	if (!createGate(entry, owner)) return false;
+	for (const lease of listLeases(entry)) if (!ownerLive(lease)) rmSync(lease, { force: true });
+	if (listLeases(entry).length > 0) {
+		removeGate(entry);
+		return false;
+	}
+	const token = newToken();
+	const deletingEntry = `${entry}.deleting.${token}`;
+	const deletingLeases = `${entry}.leases.deleting.${token}`;
+	if (existsSync(entry)) atomicRename(entry, deletingEntry);
+	if (existsSync(leasesDir(entry))) atomicRename(leasesDir(entry), deletingLeases);
+	removeGate(entry);
+	removeWithRetry(deletingEntry);
+	removeWithRetry(deletingLeases);
+	rmSync(`${entry}${USED_SUFFIX}`, { force: true });
+	return true;
+}
+const STAGING_MAX_AGE_MS = 864e5;
+/** Work dirs a crashed extraction left under `staging/`; a live one is never a day old. */
+function pruneStaging(cacheRoot, now) {
+	let names;
+	try {
+		names = readdirSync(stagingDir(cacheRoot));
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		const dir = join(stagingDir(cacheRoot), name);
+		try {
+			if (now - statSync(dir).mtimeMs > STAGING_MAX_AGE_MS) removeWithRetry(dir);
+		} catch {}
+	}
+}
+/** Prunes the whole cache; the caller holds the exclusive lock (MUT-1) so only one prune ever runs. */
+function pruneCache(cacheRoot, owner, options) {
+	const report = {
+		removed: [],
+		kept: [],
+		skipped: []
+	};
+	pruneStaging(cacheRoot, options.now ?? Date.now());
+	let names;
+	try {
+		names = readdirSync(join(cacheRoot, "npm"));
+	} catch {
+		return report;
+	}
+	for (const name of names) {
+		const entry = join(cacheRoot, "npm", name);
+		if (name.endsWith(".leases") && existsSync(entry) && !existsSync(entry.slice(0, -7))) {
+			(pruneEntry(entry.slice(0, -7), owner) ? report.removed : report.skipped).push(name);
+			continue;
+		}
+		if (name.endsWith(".prune") && !existsSync(entry.slice(0, -6)) && !ownerLive(entry)) {
+			rmSync(entry, { force: true });
+			report.removed.push(name);
+			continue;
+		}
+		const reason = pruneReason(cacheRoot, name, options);
+		if (reason === null) {
+			if (isEntryName(name)) report.kept.push(name);
+			continue;
+		}
+		if (reason === "leftover") {
+			removeWithRetry(entry);
+			report.removed.push(name);
+			continue;
+		}
+		if (pruneEntry(entry, owner)) report.removed.push(name);
+		else report.skipped.push(name);
+	}
+	return report;
+}
+//#endregion
+//#region src/setup/home.ts
+function localAppData(env) {
+	return env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local");
+}
+function defaultHome(env, platform = process.platform) {
+	if (platform === "win32") return join(localAppData(env), "npm-vm");
+	return join(env["XDG_DATA_HOME"] || join(homedir(), ".local", "share"), "npm-vm");
+}
+function cacheBase(env, platform = process.platform) {
+	if (platform === "win32") return join(localAppData(env), "npm-vm-cache");
+	return join(env["XDG_CACHE_HOME"] || join(homedir(), ".cache"), "npm-vm");
+}
+function platformId(platform, env) {
+	try {
+		if (platform === "linux") {
+			for (const file of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) try {
+				const id = readFileSync(file, "utf8").trim();
+				if (id !== "") return id;
+			} catch {}
+			return null;
+		}
+		if (platform === "darwin") {
+			const out = execFileSync("/usr/sbin/ioreg", [
+				"-rd1",
+				"-c",
+				"IOPlatformExpertDevice"
+			], {
+				encoding: "utf8",
+				env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin" }
+			});
+			return /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out)?.[1] ?? null;
+		}
+		if (platform === "win32") {
+			const reg = join(env["SystemRoot"] ?? "C:\\Windows", "System32", "reg.exe");
+			const out = execFileSync(reg, [
+				"query",
+				"HKLM\\SOFTWARE\\Microsoft\\Cryptography",
+				"/v",
+				"MachineGuid"
+			], { encoding: "utf8" });
+			return /MachineGuid\s+REG_SZ\s+(\S+)/.exec(out)?.[1] ?? null;
+		}
+	} catch {}
+	return null;
+}
+/** The hashed machine id, or a hashed hostname when the platform id is unreadable. */
+function readMachineId(env = process.env, platform = process.platform) {
+	const raw = platformId(platform, env);
+	const source = raw ?? hostname();
+	return {
+		id: createHash("sha256").update(source).digest("hex").slice(0, 16),
+		fallback: raw === null
+	};
+}
+function resolveDirs(env = process.env, home = env["NPM_VM_HOME"] || defaultHome(env), platform = process.platform, machine = readMachineId(env, platform)) {
+	const absoluteHome = resolve(home);
+	const state = join(absoluteHome, "state");
+	return {
+		home: absoluteHome,
+		cache: join(cacheBase(env, platform), machine.id),
+		state,
+		tmp: join(state, "tmp"),
+		journal: join(state, "journal"),
+		machine
+	};
+}
+//#endregion
+//#region src/install/config.ts
+const DROPPED = /* @__PURE__ */ new Set(["NODE_OPTIONS", "NODE_EXTRA_CA_CERTS"]);
+/** Proxy settings reach the transport only from the user and global npm config (spec DL-2), never the env. */
+const PROXY_VARS = /^(https?_proxy|all_proxy|no_proxy|proxy)$/i;
+/** The env without anything that would steer npm or Node: `npm_config_*`, proxies, `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`. */
+function sanitizeEnv(env) {
+	const clean = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (/^npm_config_/i.test(key) || DROPPED.has(key.toUpperCase()) || PROXY_VARS.test(key)) continue;
+		clean[key] = value;
+	}
+	return clean;
+}
+function optionalString(value) {
+	const text = Array.isArray(value) ? value.map(String).filter((item) => item !== "").join(",") : value;
+	return typeof text === "string" && text !== "" ? text : null;
+}
+/**
+* Loads npm's config the way npm does, minus the project: `cwd` is an empty dir under the home,
+* the env is sanitized and nothing is printed. Credentials come only from `getCredentialsByURI`.
+*/
+async function loadNpmConfig(own, env, cwd, nodePath = process.execPath) {
+	const { definitions, shorthands, flatten, nerfDarts } = npmDefinitions;
+	const config = new Config({
+		definitions,
+		shorthands,
+		flatten,
+		nerfDarts,
+		npmPath: own.root,
+		argv: [
+			nodePath,
+			own.cliPath,
+			"--location=global"
+		],
+		execPath: nodePath,
+		env: { ...sanitizeEnv(env) },
+		cwd,
+		excludeNpmCwd: true
+	});
+	await config.load();
+	const registry = String(config.get("registry"));
+	const ca = config.get("ca");
+	return {
+		registry,
+		userconfig: String(config.get("userconfig")),
+		globalconfig: String(config.get("globalconfig")),
+		cache: String(config.get("cache")),
+		credentials: config.getCredentialsByURI(registry),
+		httpsProxy: optionalString(config.get("https-proxy")),
+		proxy: optionalString(config.get("proxy")),
+		noproxy: optionalString(config.get("noproxy")),
+		ca: Array.isArray(ca) ? ca.map(String) : typeof ca === "string" ? [ca] : null,
+		cafile: optionalString(config.get("cafile")),
+		strictSsl: config.get("strict-ssl") !== false
+	};
+}
+//#endregion
+//#region src/install/fetch.ts
+const MIN_TRANSPORT = "8.0.0";
+const MAX_OUTPUT = 268435456;
+/** Whether Node's own npm can serve as the transport (spec DL-1). */
+function transportUsable(own) {
+	return own !== null && semver.gte(own.version, MIN_TRANSPORT);
+}
+/** A fresh private working dir under `state/tmp/`, never the shared system temp dir (spec DL-2). */
+function newWorkDir(tmpRoot) {
+	mkdirSync(tmpRoot, {
+		recursive: true,
+		mode: 448
+	});
+	return mkdtempSync(join(tmpRoot, "work-"));
+}
+/**
+* Runs Node's own npm as the download transport, isolated from the project (spec DL-1, DL-2).
+* Every call runs in its own empty working dir, with that dir as the prefix and the user and global config named explicitly.
+*/
+var Transport = class {
+	#own;
+	#config;
+	#env;
+	#tmpRoot;
+	#nodePath;
+	constructor(own, config, env, tmpRoot, nodePath = process.execPath) {
+		this.#own = own;
+		this.#config = config;
+		this.#env = sanitizeEnv(env);
+		this.#tmpRoot = tmpRoot;
+		this.#nodePath = nodePath;
+	}
+	/** Versions of npm matching `range`, newest last as npm lists them; an unmatched range is an empty list. */
+	view(range) {
+		return this.viewPackage("npm", range);
+	}
+	/** The same for any package, used by self-update for its own package. */
+	async viewPackage(name, range) {
+		const output = await this.#run([
+			"view",
+			`${name}@${range}`,
+			"version",
+			"engines",
+			"dist"
+		], true);
+		if (output === null) return [];
+		return asList(output).flatMap((item) => {
+			const version = readString(item, "version");
+			const dist = readObject(item, "dist");
+			const integrity = dist === null ? null : readString(dist, "integrity");
+			const tarball = dist === null ? null : readString(dist, "tarball");
+			if (version === null || integrity === null || tarball === null) return [];
+			const engines = readObject(item, "engines");
+			const signatures = (dist === null ? null : dist["signatures"]) ?? [];
+			const attestations = dist === null ? null : readObject(dist, "attestations");
+			return [{
+				version,
+				enginesNode: engines === null ? null : readString(engines, "node"),
+				integrity,
+				tarball,
+				signatures: Array.isArray(signatures) ? signatures.filter(isSignature) : [],
+				attestationsUrl: attestations === null ? null : readString(attestations, "url")
+			}];
+		});
+	}
+	/** Publication time per version, used only to judge signatures by expired keys. */
+	async times() {
+		const output = await this.#run([
+			"view",
+			"npm",
+			"time"
+		], true);
+		const map = output === null ? null : asList(output)[0] ?? null;
+		const times = {};
+		if (map !== null && typeof map === "object") {
+			for (const [version, time] of Object.entries(map)) if (typeof time === "string") times[version] = time;
+		}
+		return times;
+	}
+	/** Downloads one npm version's tarball into `dest` through `npm pack`. */
+	pack(version, dest) {
+		return this.packPackage("npm", version, dest);
+	}
+	async packPackage(name, version, dest) {
+		const item = asList(await this.#run([
+			"pack",
+			`${name}@${version}`,
+			`--pack-destination=${dest}`
+		], false)).flatMap((item) => readString(item, "filename") === null ? asList(Object.values(item)) : [item]).find((candidate) => readString(candidate, "filename") !== null) ?? null;
+		const filename = item === null ? null : readString(item, "filename");
+		const integrity = item === null ? null : readString(item, "integrity");
+		if (filename === null || integrity === null) throw this.#failure(`npm pack returned no tarball for ${name}@${version}`);
+		return {
+			file: join(dest, filename),
+			integrity
+		};
+	}
+	#failure(detail) {
+		return new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(this.#own.version, detail));
+	}
+	/** Runs npm with the isolation flags; returns parsed JSON, or null for a 404 when `missingIsEmpty`. */
+	async #run(args, missingIsEmpty) {
+		const cwd = newWorkDir(this.#tmpRoot);
+		const argv = [
+			this.#own.cliPath,
+			...args,
+			"--json",
+			"--ignore-scripts",
+			"--loglevel=error",
+			"--replace-registry-host=always",
+			...proxyFlags(this.#config),
+			"--fetch-retry-mintimeout=1000",
+			"--fetch-retry-maxtimeout=10000",
+			`--prefix=${cwd}`,
+			`--cache=${this.#config.cache}`,
+			`--userconfig=${this.#config.userconfig}`,
+			`--globalconfig=${this.#config.globalconfig}`
+		];
+		try {
+			const { stdout: output } = await new Promise((resolve, reject) => {
+				execFile(this.#nodePath, argv, {
+					cwd,
+					env: this.#env,
+					maxBuffer: MAX_OUTPUT,
+					timeout: 3e5,
+					windowsHide: true
+				}, (error, stdout, stderr) => {
+					if (error === null) {
+						resolve({ stdout });
+						return;
+					}
+					reject(Object.assign(error, {
+						stdout,
+						stderr
+					}));
+				});
+			});
+			return parseJson(output);
+		} catch (error) {
+			const stderr = String(error.stderr ?? "");
+			if (missingIsEmpty && /\bE404\b/.test(stderr)) return null;
+			const line = (stderr.split("\n").find((text) => /^npm (ERR!|error)/.test(text)) ?? error.message).replace(/^npm (ERR!|error) /, "").trim();
+			const redacted = redactUrls(line);
+			if (/\bEINTEGRITY\b/.test(stderr)) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage("the registry integrity", "other bytes", redacted));
+			throw this.#failure(redacted);
+		} finally {
+			rmSync(cwd, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+/** Proxy settings as flags, since the env the transport sees carries none (spec DL-2). */
+function proxyFlags(config) {
+	const flags = [];
+	if (config.httpsProxy !== null) flags.push(`--https-proxy=${config.httpsProxy}`);
+	if (config.proxy !== null) flags.push(`--proxy=${config.proxy}`);
+	if (config.noproxy !== null) flags.push(`--noproxy=${config.noproxy}`);
+	return flags;
+}
+function parseJson(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") return null;
+	return JSON.parse(trimmed);
+}
+function asList(value) {
+	return (Array.isArray(value) ? value : [value]).filter((item) => typeof item === "object" && item !== null);
+}
+function readString(record, key) {
+	const value = record[key];
+	return typeof value === "string" ? value : null;
+}
+function readObject(record, key) {
+	const value = record[key];
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function isSignature(value) {
+	return typeof value === "object" && value !== null && typeof value.keyid === "string" && typeof value.sig === "string";
+}
+//#endregion
+//#region src/install/keys.ts
+const REGISTRY_KEYS = [{
+	keyid: "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA",
+	key: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg==",
+	expires: "2025-01-29T00:00:00.000Z"
+}, {
+	keyid: "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U",
+	key: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==",
+	expires: null
+}];
+const EXTRA_KEYS_FILE = "keys.json";
+/**
+* Keys added beside the built-in ones from `<home>/state/keys.json`, for registries that sign with their own keys.
+* Anything able to write there could replace the runtime itself, so this adds no trust the home does not already hold.
+*/
+function loadKeyring(stateDir) {
+	let extra;
+	try {
+		extra = JSON.parse(readFileSync(join(stateDir, EXTRA_KEYS_FILE), "utf8"));
+	} catch {
+		return [...REGISTRY_KEYS];
+	}
+	const keys = Array.isArray(extra) ? extra : [];
+	return [...REGISTRY_KEYS, ...keys.filter((key) => typeof key === "object" && key !== null && typeof key.keyid === "string" && typeof key.key === "string" && (key.expires === null || typeof key.expires === "string"))];
+}
+//#endregion
+//#region src/install/index.ts
+function createContext(env = process.env, home, node = {
+	execPath: process.execPath,
+	version: process.version
+}) {
+	const dirs = resolveDirs(env, home);
+	return {
+		dirs,
+		own: findOwnNpm(node.execPath),
+		env,
+		nodeVersion: node.version,
+		nodePath: node.execPath,
+		keys: loadKeyring(dirs.state)
+	};
+}
+function toCandidate(version) {
+	return {
+		version: version.version,
+		enginesNode: version.enginesNode,
+		integrity: version.integrity,
+		entryPath: null,
+		signatures: version.signatures
+	};
+}
+/** Lazily loads the npm config and builds the transport once per process. */
+var TransportFactory = class {
+	#context;
+	#ready = null;
+	constructor(context) {
+		this.#context = context;
+	}
+	get() {
+		this.#ready ??= this.#create();
+		return this.#ready;
+	}
+	async #create() {
+		const { own, env, dirs } = this.#context;
+		const found = own?.version ?? null;
+		if (!transportUsable(own)) throw new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(found, "too old or missing"));
+		const cwd = newWorkDir(dirs.tmp);
+		try {
+			const config = await loadNpmConfig(own, env, cwd, this.#context.nodePath);
+			return {
+				transport: new Transport(own, config, env, dirs.tmp, this.#context.nodePath),
+				config
+			};
+		} finally {
+			rmSync(cwd, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+function createInstaller(context) {
+	const factory = new TransportFactory(context);
+	async function registryVersions(specs) {
+		const { transport } = await factory.get();
+		const byVersion = /* @__PURE__ */ new Map();
+		for (const spec of specs) for (const version of await transport.view(spec.exact ?? spec.range)) byVersion.set(version.version, version);
+		return [...byVersion.values()];
+	}
+	async function installTarball(selection, source, onPacked) {
+		const { candidate } = selection;
+		const owner = ownerRecord(context.dirs.machine.id);
+		if (source.published.version !== candidate.version || source.published.integrity !== candidate.integrity) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(candidate.integrity, source.published.integrity, `the registry no longer serves npm ${candidate.version} with this integrity`));
+		const digests = await fileDigests(source.file);
+		checkIntegrity(digests, candidate.integrity, selection.hashes);
+		const keyid = await verifySignatures({
+			name: "npm",
+			version: candidate.version,
+			integrity: candidate.integrity,
+			signatures: source.published.signatures,
+			publishedAt: source.publishedAt,
+			keys: context.keys,
+			registry: source.registry,
+			pinned: selection.hashes.length > 0
+		});
+		if (onPacked !== void 0) await onPacked(source, digests);
+		const work = newWorkDir(stagingDir(context.dirs.cache));
+		try {
+			const extracted = join(work, "package");
+			mkdirSync(extracted, { mode: 448 });
+			await safeExtract(source.file, extracted);
+			checkExtracted(extracted, candidate, context.nodeVersion);
+			writeVerified(extracted, {
+				version: candidate.version,
+				integrity: candidate.integrity,
+				keyid,
+				sha256: digests.sha256hex,
+				sha224: digests.sha224hex,
+				verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const canonical = canonicalEntry(context.dirs.cache, candidate.version, candidate.integrity);
+			mkdirSync(join(canonical, ".."), {
+				recursive: true,
+				mode: 448
+			});
+			const published = publishEntry(extracted, canonical, candidate.integrity, owner);
+			touchUsed(published.entryPath);
+			return published;
+		} finally {
+			rmSync(work, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	return {
+		nodeVersion: context.nodeVersion,
+		ownNpm: () => context.own,
+		cached: async () => listEntries(context.dirs.cache, context.keys),
+		registry: async (specs) => (await registryVersions(specs)).map(toCandidate),
+		entryPathFor: (candidate) => canonicalEntry(context.dirs.cache, candidate.version, candidate.integrity),
+		async registryIdentity() {
+			const { config } = await factory.get();
+			return createHash("sha256").update(config.registry).digest("hex").slice(0, 12);
+		},
+		installTarball: (selection, source) => installTarball(selection, source),
+		async ensure(selection, options = {}) {
+			const { candidate } = selection;
+			const owner = ownerRecord(context.dirs.machine.id);
+			if (candidate.entryPath !== null && validateEntry(candidate.entryPath, candidate.integrity)) {
+				const lease = await acquireShared(candidate.entryPath, owner);
+				if (lease !== null && validateEntry(candidate.entryPath, candidate.integrity)) {
+					touchUsed(candidate.entryPath);
+					return {
+						entryPath: candidate.entryPath,
+						lease
+					};
+				}
+				lease?.release();
+			}
+			if (options.offline ?? (context.env["NPM_VM_OFFLINE"] ?? "") !== "") throw new NpmVmError("M-NOMATCH", EXIT.resolution, `npm ${candidate.version} is not usable from the cache and NPM_VM_OFFLINE forbids the registry.`);
+			const { transport, config } = await factory.get();
+			const published = (await transport.view(candidate.version)).find((item) => item.version === candidate.version);
+			if (published === void 0) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(candidate.integrity, "nothing", `the registry no longer serves npm ${candidate.version}`));
+			const work = newWorkDir(context.dirs.tmp);
+			try {
+				return await installTarball(selection, {
+					file: (await transport.pack(candidate.version, work)).file,
+					published,
+					publishedAt: async () => (await transport.times())[candidate.version] ?? null,
+					registry: config.registry
+				}, options.onPacked);
+			} finally {
+				rmSync(work, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+	};
+}
+/** The extracted manifest is authoritative for name, version and engines (spec SEC-5). */
+function checkExtracted(dir, candidate, nodeVersion) {
+	let pkg;
+	try {
+		pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch (error) {
+		throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage("npm package.json", "unreadable", error.message));
+	}
+	if (pkg["name"] !== "npm" || pkg["version"] !== candidate.version) throw new NpmVmError("M-INTEGRITY", EXIT.verification, integrityMessage(`npm@${candidate.version}`, `${String(pkg["name"])}@${String(pkg["version"])}`, "the tarball holds a different package"));
+	const engines = pkg["engines"];
+	const node = typeof engines === "object" && engines !== null ? engines["node"] : void 0;
+	if (typeof node === "string" && !semver.satisfies(nodeVersion, node, { includePrerelease: true })) throw new NpmVmError("M-ENGINE", EXIT.resolution, engineMessage(candidate.version, node, nodeVersion));
+}
+//#endregion
+//#region src/project.ts
+const BOOLEANS = /* @__PURE__ */ new Set(["global", "workspaces"]);
+const SHORTHANDS = {
+	C: "prefix",
+	g: "global",
+	L: "location",
+	ws: "workspaces"
+};
+/**
+* The subset of nopt that decides the prefix: `--flag value`, `--flag=value`, `--no-flag`, `--flag true|false` for booleans, npm's shorthands and `--`.
+* Later flags win, as in nopt.
+*/
+function parsePrefixFlags(argv, cwd) {
+	const flags = {
+		prefix: null,
+		global: null,
+		location: null,
+		workspaces: null
+	};
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg === "--") break;
+		let name;
+		let value = null;
+		if (arg.startsWith("--")) {
+			const eq = arg.indexOf("=");
+			name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+			value = eq === -1 ? null : arg.slice(eq + 1);
+			name = SHORTHANDS[name] ?? name;
+		} else if (arg.startsWith("-") && arg.length > 1 && SHORTHANDS[arg.slice(1)] !== void 0) name = SHORTHANDS[arg.slice(1)];
+		else continue;
+		let negated = false;
+		if (name.startsWith("no-") && BOOLEANS.has(name.slice(3))) {
+			negated = true;
+			name = name.slice(3);
+		}
+		if (BOOLEANS.has(name)) {
+			let bool = !negated;
+			if (value !== null) bool = value !== "false";
+			else if (!negated && (argv[i + 1] === "true" || argv[i + 1] === "false")) {
+				bool = argv[i + 1] === "true";
+				i += 1;
+			}
+			if (name === "global") flags.global = bool;
+			else flags.workspaces = bool;
+			continue;
+		}
+		if (name !== "prefix" && name !== "location") continue;
+		if (value === null) {
+			if (i + 1 >= argv.length) continue;
+			value = argv[i + 1];
+			i += 1;
+		}
+		if (name === "prefix") flags.prefix = resolve(cwd, value);
+		else flags.location = value;
+	}
+	return flags;
+}
+/** Global mode from the command line and the npm env, CLI winning (spec RES-3). */
+function isGlobalMode(flags, env) {
+	const fromEnv = env["npm_config_global"];
+	const global = flags.global ?? (fromEnv === void 0 || fromEnv === "" ? null : ![
+		"false",
+		"0",
+		"null"
+	].includes(fromEnv));
+	const location = flags.location ?? env["npm_config_location"] ?? null;
+	return global === true || location === "global";
+}
+function hasPackageJson(dir) {
+	try {
+		return statSync(join(dir, "package.json")).isFile();
+	} catch {
+		return false;
+	}
+}
+function hasNodeModules(dir) {
+	try {
+		return statSync(join(dir, "node_modules")).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function* walkUp(start) {
+	let dir = resolve(start);
+	for (;;) {
+		yield dir;
+		const parent = dirname(dir);
+		if (parent === dir) return;
+		dir = parent;
+	}
+}
+/** The `workspaces` patterns of a manifest: the array form or `{ packages: [] }`, else none. */
+function workspacePatterns(pkg) {
+	if (typeof pkg !== "object" || pkg === null) return [];
+	let raw = pkg.workspaces;
+	if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) raw = raw.packages;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((entry) => typeof entry === "string");
+}
+/**
+* Whether `candidate` is one of the workspaces `root` declares, matched like `@npmcli/map-workspaces`.
+* A pattern selects directories holding a `package.json`, `!pattern` removes matches, and `node_modules` never matches.
+*/
+function isWorkspaceOf(root, candidate, patterns) {
+	const rel = relative(root, candidate);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel) || !hasPackageJson(candidate)) return false;
+	if (rel.split(sep).includes("node_modules")) return false;
+	const posix = rel.split(sep).join("/");
+	const { positive, negative } = splitPatterns(patterns);
+	return positive.some((pattern) => matchesGlob(posix, pattern)) && !negative.some((pattern) => matchesGlob(posix, pattern));
+}
+function splitPatterns(patterns) {
+	const positive = [];
+	const negative = [];
+	for (const raw of patterns) {
+		const bangs = /^!+/.exec(raw)?.[0].length ?? 0;
+		const pattern = normalizePattern(raw.slice(bangs));
+		if (bangs % 2 === 1) {
+			negative.push(pattern);
+			continue;
+		}
+		for (let i = negative.length - 1; i >= 0; i -= 1) if (matchesGlob(pattern, negative[i])) negative.splice(i, 1);
+		positive.push(pattern);
+	}
+	return {
+		positive,
+		negative
+	};
+}
+function normalizePattern(pattern) {
+	return pattern.replace(/\\/g, "/").replace(/^\.?\/+/, "").replace(/\/+$/, "");
+}
+function readManifest$1(dir) {
+	try {
+		return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch {
+		return null;
+	}
+}
+/**
+* Mirrors `@npmcli/config` `loadLocalPrefix` (spec RES-2): a CLI prefix is final.
+* Otherwise the nearest ancestor with `package.json` or `node_modules` wins, promoted to a parent whose `workspaces` include it unless `--no-workspaces` or global mode.
+*/
+function findProject(argv, cwd, env = process.env) {
+	const flags = parsePrefixFlags(argv, cwd);
+	const global = isGlobalMode(flags, env);
+	if (flags.prefix !== null) return {
+		root: flags.prefix,
+		global,
+		cliPrefix: flags.prefix
+	};
+	let localPrefix = null;
+	for (const dir of walkUp(cwd)) {
+		const manifest = hasPackageJson(dir);
+		if (localPrefix === null) {
+			if (manifest || hasNodeModules(dir)) {
+				localPrefix = dir;
+				if (flags.workspaces === false || global) break;
+			}
+			continue;
+		}
+		if (!manifest) continue;
+		const pkg = readManifest$1(dir);
+		if (pkg !== null && isWorkspaceOf(dir, localPrefix, workspacePatterns(pkg))) {
+			localPrefix = dir;
+			break;
+		}
+	}
+	return {
+		root: localPrefix ?? resolve(cwd),
+		global,
+		cliPrefix: null
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Resolves the npm to run for `argv` in `cwd` (spec section 5); writes only under the cache, spawns npm only as the transport. */
+function resolveNpm(argv, cwd, options = {}) {
+	return resolveNpmWith(argv, cwd, options, createInstaller(createContext(options.env ?? process.env, options.home)));
+}
+async function resolveNpmWith(argv, cwd, options, providers) {
+	const env = options.env ?? process.env;
+	const own = providers.ownNpm();
+	const ownResult = (projectRoot, source, warning) => {
+		if (own === null) throw new NpmVmError("M-TRANSPORT", EXIT.transport, "No npm found beside the active Node; reinstall Node.");
+		return {
+			kind: "own",
+			version: own.version,
+			cliPath: own.cliPath,
+			source,
+			projectRoot,
+			selection: null,
+			specs: null,
+			warning
+		};
+	};
+	if (nonEmpty(env["NPM_VM_DISABLE"])) return ownResult(null, null, null);
+	const project = findProject(argv, cwd, env);
+	if (project.global) return ownResult(project.root, null, null);
+	let parsed;
+	let source;
+	if (nonEmpty(env["NPM_VM_VERSION"])) {
+		parsed = {
+			specs: [parseVersionSpec(env["NPM_VM_VERSION"], "NPM_VM_VERSION")],
+			onFail: "error",
+			field: "devEngines"
+		};
+		source = {
+			file: "NPM_VM_VERSION",
+			field: "env"
+		};
+	} else {
+		const file = join(project.root, "package.json");
+		let read;
+		try {
+			read = readSpecs(file);
+		} catch (error) {
+			if (!(error instanceof SpecError)) throw error;
+			const message = `${file}: ${error.message}`;
+			const failure = new NpmVmError("M-NOMATCH", EXIT.resolution, message);
+			return applyPolicy(error.onFail, failure, () => ownResult(project.root, null, message));
+		}
+		if (read === null) return ownResult(project.root, null, null);
+		parsed = read;
+		source = {
+			file,
+			field: read.field
+		};
+	}
+	if (own !== null && ownNpmSatisfies(own.version, parsed.specs)) return ownResult(project.root, source, null);
+	const cached = await providers.cached(parsed.specs);
+	let result = selectCandidate(parsed.specs, cached, providers.nodeVersion);
+	if (result.kind === "failed" && !options.offline && !nonEmpty(env["NPM_VM_OFFLINE"])) {
+		let fromRegistry;
+		try {
+			fromRegistry = await providers.registry(parsed.specs);
+		} catch (error) {
+			if (!(error instanceof NpmVmError) || error.id !== "M-TRANSPORT") throw error;
+			return applyPolicy(parsed.onFail, error, () => ownResult(project.root, source, error.message));
+		}
+		result = selectCandidate(parsed.specs, fromRegistry, providers.nodeVersion);
+	}
+	if (result.kind === "selected") {
+		const { candidate } = result.selection;
+		const entry = candidate.entryPath ?? providers.entryPathFor(candidate);
+		return {
+			kind: candidate.entryPath === null ? "download" : "cached",
+			version: candidate.version,
+			cliPath: join(entry, "bin", "npm-cli.js"),
+			source,
+			projectRoot: project.root,
+			selection: result.selection,
+			specs: parsed.specs,
+			warning: null
+		};
+	}
+	const message = result.failure.kind === "engine" ? engineMessage(result.failure.version, result.failure.enginesNode, providers.nodeVersion) : noMatchMessage(parsed.specs, source.file, result.failure.reason);
+	const id = result.failure.kind === "engine" ? "M-ENGINE" : "M-NOMATCH";
+	const failure = new NpmVmError(id, EXIT.resolution, message);
+	return applyPolicy(parsed.onFail, failure, () => ownResult(project.root, source, message));
+}
+/** `onFail` makes a failed resolution fatal, a warning before Node's own npm, or silent (spec RES-7). */
+function applyPolicy(onFail, failure, fallback) {
+	if (onFail === "ignore") return {
+		...fallback(),
+		warning: null
+	};
+	if (onFail === "warn") return fallback();
+	throw failure;
+}
+/** Reads and validates the project's specs; a broken file or range follows its own `onFail` when readable, else errors. */
+function readSpecs(file) {
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+	let pkg;
+	try {
+		pkg = JSON.parse(text);
+	} catch (error) {
+		throw new NpmVmError("M-NOMATCH", EXIT.resolution, `${file} is not valid JSON: ${error.message}`);
+	}
+	return parseSpecs(pkg);
+}
+function nonEmpty(value) {
+	return value !== void 0 && value !== "";
+}
+const SHIM_DIR = "shims";
+const LAUNCHERS_DIR = "launchers";
+const SELECTORS = [
+	"npm",
+	"npx",
+	"npm-vm"
+];
+const UNSAFE = /[\n\r"'`$%!]/;
+/** Refuses a home no quoting makes safe in all four shells and cmd (spec SET-2, M-HOMEPATH). */
+function assertSafeHome(home) {
+	const match = UNSAFE.exec(home);
+	if (match !== null) {
+		const shown = match[0] === "\n" || match[0] === "\r" ? "a line break" : `"${match[0]}"`;
+		throw new NpmVmError("M-HOMEPATH", EXIT.usage, `The npm-vm home ${home} contains ${shown}, which cannot be quoted safely in every shell. Set NPM_VM_HOME to a plain path and run setup again.`);
+	}
+}
+function selectorOf(name) {
+	return name === "npm-vm" ? "cli" : name;
+}
+/**
+* The launcher templates shipped beside this code: `src/launchers/` from source, `dist/runtime/launchers/`
+* from the bin, and `launchers/` beside an installed `runtime.cjs`.
+*/
+function templatesDir() {
+	const here = import.meta.dirname;
+	for (const candidate of [
+		join(here, LAUNCHERS_DIR),
+		join(here, "..", LAUNCHERS_DIR),
+		join(here, "runtime", LAUNCHERS_DIR)
+	]) if (existsSync(join(candidate, "sh.tmpl"))) return candidate;
+	throw new Error(`npm-vm launcher templates not found near ${here}`);
+}
+function readTemplate(dir, kind) {
+	const text = readFileSync(join(dir, `${kind}.tmpl`), "utf8");
+	return kind === "sh" ? text.replace(/\r\n/g, "\n") : text;
+}
+/** Fills one launcher template; the ABI comes from the launcher generation the templates belong to. */
+function renderTemplate(template, values) {
+	return template.replace(/\{\{ABI\}\}/g, String(values.abi)).replace(/\{\{BOOTSTRAP\}\}/g, values.bootstrap).replace(/\{\{SELECTOR\}\}/g, values.selector);
+}
+/** The POSIX shim: `sh` on every OS, so Git Bash and MSYS on Windows get one too. */
+function posixShim(home, name, templates = templatesDir(), abi = 1, platform = process.platform) {
+	const { join: joinPath } = platform === "win32" ? win32 : posix;
+	return renderTemplate(readTemplate(templates, "sh"), {
+		bootstrap: joinPath(home, "bootstrap.cjs"),
+		selector: selectorOf(name),
+		abi
+	});
+}
+/**
+* The cmd shim resolves node.exe through PATH only (`%~$PATH:i`): cmd would otherwise run a `node.exe`
+* committed to the current directory. One command line, so `%*` keeps its quoting.
+*/
+function cmdShim(home, name, templates = templatesDir(), abi = 1) {
+	return renderTemplate(readTemplate(templates, "cmd"), {
+		bootstrap: win32.join(home, "bootstrap.cjs"),
+		selector: selectorOf(name),
+		abi
+	});
+}
+/** PowerShell never searches the current directory for a command, so `Get-Command` is enough. */
+function powershellShim(home, name, templates = templatesDir(), abi = 1) {
+	return renderTemplate(readTemplate(templates, "ps1"), {
+		bootstrap: win32.join(home, "bootstrap.cjs"),
+		selector: selectorOf(name),
+		abi
+	});
+}
+/** Every shim file for the platform (spec SET-2); `.ps1` files are included only when the policy allows them (WIN-2). */
+function renderShims(home, platform, options = {}) {
+	assertSafeHome(home);
+	const templates = options.templates ?? templatesDir();
+	const abi = options.abi ?? 1;
+	const files = [];
+	for (const name of SELECTORS) {
+		files.push({
+			name,
+			content: posixShim(home, name, templates, abi, platform),
+			mode: 493
+		});
+		if (platform === "win32") {
+			files.push({
+				name: `${name}.cmd`,
+				content: cmdShim(home, name, templates, abi),
+				mode: 420
+			});
+			if (options.powershell !== false) files.push({
+				name: `${name}.ps1`,
+				content: powershellShim(home, name, templates, abi),
+				mode: 420
+			});
+		}
+	}
+	return files;
+}
+/** The ABI a shim or bootstrap file declares, or null when the file is not ours. */
+function shimAbi(content) {
+	const match = /npm-vm launcher abi=(\d+)|LAUNCHER_ABI = (\d+)/.exec(content);
+	return match === null ? null : Number(match[1] ?? match[2]);
+}
+function shimDir(home) {
+	return join(home, SHIM_DIR);
+}
+/** Our `.ps1` shims left from a permissive policy; PowerShell would still prefer them over `.cmd` (WIN-2). */
+function stalePowershellShims(home) {
+	return SELECTORS.map((name) => join(shimDir(home), `${name}.ps1`)).filter((file) => {
+		try {
+			return shimAbi(readFileSync(file, "utf8")) !== null;
+		} catch {
+			return false;
+		}
+	});
+}
+//#endregion
+//#region src/setup/shell.ts
+const SHELLS = [
+	"zsh",
+	"bash",
+	"fish",
+	"powershell"
+];
+function isShell(value) {
+	return SHELLS.includes(value);
+}
+const BLOCK_START = "# >>> npm-vm >>>";
+const BLOCK_END = "# <<< npm-vm <<<";
+/** Escapes a path for use inside a bash or zsh `${var//pattern/}` pattern, where `/` and glob characters are special. */
+function patternOf(path) {
+	return path.replace(/[\\/*?[\]]/g, (char) => `\\${char}`);
+}
+/** Adds `shims/` to the front of PATH when absent; sourcing it twice changes nothing (spec SH-1). */
+function shimsFor(shell, home) {
+	if (shell === "powershell") return win32.join(home, SHIM_DIR);
+	return process.platform === "win32" ? shimDir(home).replace(/\\/g, "/") : shimDir(home);
+}
+function pathSnippet(shell, home) {
+	assertSafeHome(home);
+	const shims = shimsFor(shell, home);
+	switch (shell) {
+		case "zsh":
+		case "bash": return [
+			`case ":$PATH:" in`,
+			`  *":${shims}:"*) ;;`,
+			`  *) export PATH="${shims}:$PATH" ;;`,
+			"esac",
+			""
+		].join("\n");
+		case "fish": return [
+			`if not contains -- "${shims}" $PATH`,
+			`    set -gx PATH "${shims}" $PATH`,
+			"end",
+			""
+		].join("\n");
+		case "powershell": return [
+			`if (($env:Path -split [IO.Path]::PathSeparator) -notcontains '${shims}') {`,
+			`    $env:Path = '${shims}' + [IO.Path]::PathSeparator + $env:Path`,
+			"}",
+			""
+		].join("\n");
+	}
+}
+/**
+* The prompt hook (spec SH-2): moves `shims/` back to the front when something prepended over it,
+* with parameter expansion only, keeping `$?` and chaining whatever hook was there.
+*/
+function hookSnippet(shell, home) {
+	assertSafeHome(home);
+	const shims = shimsFor(shell, home);
+	switch (shell) {
+		case "zsh": return [
+			"_npm_vm_guard() {",
+			"  local ret=$?",
+			`  if [[ "$path[1]" != "${shims}" ]]; then`,
+			`    path=("${shims}" \${path:#${shims}})`,
+			"  fi",
+			"  return $ret",
+			"}",
+			"if [[ -z \"${precmd_functions[(r)_npm_vm_guard]}\" ]]; then",
+			"  precmd_functions+=(_npm_vm_guard)",
+			"fi",
+			""
+		].join("\n");
+		case "bash": return [
+			"_npm_vm_guard() {",
+			"  local ret=$?",
+			`  case ":$PATH:" in`,
+			`    ":${shims}:"*) ;;`,
+			"    *)",
+			"      local rest=\":$PATH:\"",
+			`      rest="\${rest//:${patternOf(shims)}:/:}"`,
+			"      rest=\"${rest#:}\"",
+			"      rest=\"${rest%:}\"",
+			`      PATH="${shims}\${rest:+:$rest}"`,
+			"      ;;",
+			"  esac",
+			"  return $ret",
+			"}",
+			"case \";${PROMPT_COMMAND};\" in",
+			"  *\";_npm_vm_guard;\"*) ;;",
+			"  *) PROMPT_COMMAND=\"_npm_vm_guard${PROMPT_COMMAND:+;$PROMPT_COMMAND}\" ;;",
+			"esac",
+			""
+		].join("\n");
+		case "fish": return [
+			"if status is-interactive",
+			"    function _npm_vm_guard --on-event fish_prompt",
+			`        if test "$PATH[1]" != "${shims}"`,
+			`            set -l found (contains -i -- "${shims}" $PATH)`,
+			"            if test -n \"$found\"",
+			"                set -e PATH[$found]",
+			"            end",
+			`            set -gx PATH "${shims}" $PATH`,
+			"        end",
+			"    end",
+			"end",
+			""
+		].join("\n");
+		case "powershell": return [
+			"if (-not (Test-Path Function:\\global:_npm_vm_original_prompt)) {",
+			"    $prev = Get-Item Function:\\prompt -ErrorAction SilentlyContinue",
+			"    if ($prev) { Set-Item Function:\\global:_npm_vm_original_prompt $prev.ScriptBlock }",
+			"    else { function global:_npm_vm_original_prompt { \"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) \" } }",
+			"    function global:prompt {",
+			"        $ok = $?",
+			"        $exit = $global:LASTEXITCODE",
+			`        $shims = '${shims}'`,
+			"        $parts = @($env:Path -split [IO.Path]::PathSeparator)",
+			"        if ($parts.Length -eq 0 -or $parts[0] -ne $shims) {",
+			"            $env:Path = (@($shims) + @($parts | Where-Object { $_ -ne $shims })) -join [IO.Path]::PathSeparator",
+			"        }",
+			"        $out = & $function:global:_npm_vm_original_prompt",
+			"        $global:LASTEXITCODE = $exit",
+			"        $out",
+			"        if (-not $ok) { Write-Error 'npm-vm: preserving $?' -ErrorAction SilentlyContinue }",
+			"    }",
+			"}",
+			""
+		].join("\n");
+	}
+}
+/** Both snippets inside the marked block `setup` writes and `uninstall` removes (spec SH-4). */
+function profileBlock(shell, home, parts) {
+	const body = [parts.path ? pathSnippet(shell, home) : "", parts.hook ? hookSnippet(shell, home) : ""].filter((text) => text !== "").join("");
+	return `${BLOCK_START}\n${body}${BLOCK_END}\n`;
+}
+//#endregion
+//#region src/state/meta.ts
+function sha256(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+function isUtf8(content) {
+	return !content.includes(0) && Buffer.from(content.toString("utf8"), "utf8").equals(content);
+}
+function lineEndingsOf(text) {
+	const crlf = (text.match(/\r\n/g) ?? []).length;
+	const lf = (text.match(/\n/g) ?? []).length - crlf;
+	if (crlf === 0 && lf === 0) return "none";
+	if (crlf > 0 && lf > 0) return "mixed";
+	return crlf > 0 ? "crlf" : "lf";
+}
+const MISSING = {
+	type: "missing",
+	mode: 0,
+	sha256: null,
+	encoding: null,
+	lineEndings: null,
+	symlinkTarget: null
+};
+/** Captures `path` without following symlinks; a missing path is a valid state, not an error. */
+function captureMeta(path) {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch {
+		return MISSING;
+	}
+	const mode = process.platform === "win32" ? 0 : stat.mode & 4095;
+	if (stat.isSymbolicLink()) return {
+		type: "symlink",
+		mode,
+		sha256: null,
+		encoding: null,
+		lineEndings: null,
+		symlinkTarget: readlinkSync(path)
+	};
+	if (stat.isDirectory()) return {
+		type: "directory",
+		mode,
+		sha256: null,
+		encoding: null,
+		lineEndings: null,
+		symlinkTarget: null
+	};
+	if (!stat.isFile()) return {
+		type: "other",
+		mode,
+		sha256: null,
+		encoding: null,
+		lineEndings: null,
+		symlinkTarget: null
+	};
+	const content = readFileSync(path);
+	const utf8 = isUtf8(content);
+	return {
+		type: "file",
+		mode,
+		sha256: sha256(content),
+		encoding: utf8 ? "utf8" : "binary",
+		lineEndings: utf8 ? lineEndingsOf(content.toString("utf8")) : null,
+		symlinkTarget: null
+	};
+}
+/** Whether the path still holds exactly what `meta` recorded (spec MUT-5): same type, same bytes or link target. */
+function metaMatches(path, meta) {
+	const now = captureMeta(path);
+	return now.type === meta.type && now.sha256 === meta.sha256 && now.symlinkTarget === meta.symlinkTarget;
+}
+//#endregion
+//#region src/state/journal.ts
+function journalPath(journalDir, id) {
+	return join(journalDir, `${id}.json`);
+}
+function readJournal(file) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		return typeof parsed.id === "string" && typeof parsed.target === "string" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function listJournals(journalDir) {
+	let names;
+	try {
+		names = readdirSync(journalDir);
+	} catch {
+		return [];
+	}
+	return names.filter((name) => name.endsWith(".json")).map((name) => readJournal(join(journalDir, name))).filter((journal) => journal !== null);
+}
+/**
+* Applies one file change under a journal: backup and staged copy first, the journal, then the write.
+* The journal and its sidecars disappear only after the target holds the intended bytes.
+*/
+function mutateFile(journalDir, kind, owner, target, content, mode = 420) {
+	mkdirSync(journalDir, {
+		recursive: true,
+		mode: 448
+	});
+	const id = `${kind}-${newToken()}`;
+	const original = captureMeta(target);
+	let backup = null;
+	if (original.type === "file") {
+		backup = join(journalDir, `${id}.bak`);
+		copyFileSync(target, backup);
+	}
+	let staged = null;
+	if (content !== null) {
+		staged = join(journalDir, `${id}.new`);
+		atomicWrite(staged, content, 384);
+	}
+	const journal = {
+		id,
+		kind,
+		owner,
+		target,
+		original,
+		intended: content === null ? null : sha256(content),
+		staged,
+		backup,
+		mode,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	atomicWrite(journalPath(journalDir, id), JSON.stringify(journal), 384);
+	apply(journal, content);
+	discard(journalDir, journal);
+}
+function apply(journal, content) {
+	if (content === null) {
+		withSharingRetry(() => {
+			if (existsSync(journal.target)) unlinkSync(journal.target);
+		});
+		return;
+	}
+	atomicWrite(journal.target, content, journal.mode);
+}
+function discard(journalDir, journal) {
+	for (const sidecar of [journal.backup, journal.staged]) if (sidecar !== null) rmSync(sidecar, { force: true });
+	rmSync(journalPath(journalDir, journal.id), { force: true });
+}
+function targetSha(target) {
+	const meta = captureMeta(target);
+	return meta.type === "file" ? meta.sha256 : null;
+}
+/**
+* Finishes one journal (spec MUT-2): a target already at the intended bytes is done; one still at the
+* original is replayed from the staged copy; anything else is left alone and reported as changed (MUT-5).
+*/
+function recoverJournal(journalDir, journal, report) {
+	const current = targetSha(journal.target);
+	const exists = captureMeta(journal.target).type !== "missing";
+	if (journal.intended === null ? !exists : current === journal.intended) {
+		discard(journalDir, journal);
+		report.finished.push(journal.id);
+		return;
+	}
+	if (metaMatches(journal.target, journal.original)) {
+		if (journal.intended === null) {
+			apply(journal, null);
+			report.replayed.push(journal.id);
+		} else if (journal.staged !== null && existsSync(journal.staged) && sha256(readFileSync(journal.staged)) === journal.intended) {
+			apply(journal, readFileSync(journal.staged));
+			report.replayed.push(journal.id);
+		} else report.rolledBack.push(journal.id);
+		discard(journalDir, journal);
+		return;
+	}
+	report.changed.push(journal.target);
+	discard(journalDir, journal);
+}
+/** Recovers every journal whose owner is dead on this machine; foreign and live ones are skipped. */
+function recoverDeadJournals(journalDir, machineId, kinds) {
+	const report = {
+		finished: [],
+		replayed: [],
+		rolledBack: [],
+		changed: [],
+		skipped: []
+	};
+	for (const journal of listJournals(journalDir)) {
+		if (kinds !== void 0 && !kinds.includes(journal.kind)) continue;
+		if (journal.owner.machineId !== machineId || isLive(journal.owner)) {
+			report.skipped.push(journal.id);
+			continue;
+		}
+		recoverJournal(journalDir, journal, report);
+	}
+	return report;
+}
+/** Recovers one journal the operator vouched for, whatever machine owns it (the `recover` command). */
+function recoverForeignJournal(journalDir, id, confirmedMachineId) {
+	const report = {
+		finished: [],
+		replayed: [],
+		rolledBack: [],
+		changed: [],
+		skipped: []
+	};
+	const journal = readJournal(journalPath(journalDir, id));
+	if (journal === null) throw new Error(`no journal ${id} in ${journalDir}`);
+	if (journal.owner.machineId !== confirmedMachineId) throw new Error(`journal ${id} belongs to machine ${journal.owner.machineId}, not ${confirmedMachineId}`);
+	recoverJournal(journalDir, journal, report);
+	return report;
+}
+//#endregion
+//#region src/state/lock.ts
+const LOCK_FILE = "lock";
+const WAIT_LIMIT_MS = 1e4;
+function lockPath(stateDir) {
+	return join(stateDir, LOCK_FILE);
+}
+function readLock(stateDir) {
+	try {
+		const parsed = JSON.parse(readFileSync(lockPath(stateDir), "utf8"));
+		if (typeof parsed.pid !== "number" || typeof parsed.token !== "string") return null;
+		return {
+			pid: parsed.pid,
+			start: typeof parsed.start === "string" ? parsed.start : null,
+			host: typeof parsed.host === "string" ? parsed.host : "?",
+			machineId: typeof parsed.machineId === "string" ? parsed.machineId : "?",
+			createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
+			token: parsed.token
+		};
+	} catch {
+		return null;
+	}
+}
+/** Whether the lock owner can be shown to be dead: only on this machine, and only by PROC-1. */
+function lockOwnerLive(record, machineId) {
+	if (record === null) return true;
+	if (record.machineId !== machineId) return true;
+	return isLive(record);
+}
+function tryCreate(path, record) {
+	try {
+		writeFileSync(path, JSON.stringify(record), {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		rmSync(path, { force: true });
+		throw error;
+	}
+	return true;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Takes the exclusive lock (spec MUT-1): created with O_EXCL, released only by its owner, never reclaimed.
+* Waits with backoff for up to 10 s, then fails with M-LOCKED naming the file and whether the owner is live.
+*/
+async function acquireLock(stateDir, owner, options = {}) {
+	mkdirSync(stateDir, {
+		recursive: true,
+		mode: 448
+	});
+	const path = lockPath(stateDir);
+	const record = {
+		...owner,
+		token: newToken()
+	};
+	const deadline = Date.now() + (options.waitMs ?? WAIT_LIMIT_MS);
+	let delay = 50;
+	for (;;) {
+		if (tryCreate(path, record)) return {
+			path,
+			release() {
+				if (readLock(stateDir)?.token === record.token) rmSync(path, { force: true });
+			}
+		};
+		if (Date.now() + delay > deadline) {
+			const holder = readLock(stateDir);
+			const foreign = holder !== null && holder.machineId !== owner.machineId;
+			const live = lockOwnerLive(holder, owner.machineId);
+			throw new NpmVmError("M-LOCKED", EXIT.problems, lockedMessage(path, holder, live, foreign));
+		}
+		await sleep(delay);
+		delay = Math.min(delay * 2, 1e3);
+	}
+}
+//#endregion
+//#region src/commands/cache.ts
+const DAY_MS = 864e5;
+/** `install [<spec>]`: fetches and verifies the project's npm, or the given spec, into the cache. */
+async function install(context, spec, cwd = process.cwd()) {
+	const env = spec === void 0 ? context.env : {
+		...context.env,
+		NPM_VM_VERSION: spec
+	};
+	const installer = createInstaller(createContext(env, context.dirs.home));
+	const result = await resolveNpmWith([], cwd, { env }, installer);
+	if (result.selection === null) {
+		context.io.out(context.json ? JSON.stringify(result) : `Node's own npm ${result.version} satisfies the requirement; nothing to download.`);
+		return EXIT.ok;
+	}
+	const ensured = await installer.ensure(result.selection);
+	ensured.lease.release();
+	context.io.out(context.json ? JSON.stringify({
+		...result,
+		entryPath: ensured.entryPath
+	}) : `npm ${result.version} is ready in ${ensured.entryPath}`);
+	return EXIT.ok;
+}
+function cacheList(context) {
+	const entries = listEntries(context.dirs.cache).map((entry) => {
+		const used = lastUsed(entry.entryPath);
+		return {
+			version: entry.version,
+			integrity: entry.integrity,
+			path: entry.entryPath,
+			lastUsed: used === null ? null : new Date(used).toISOString(),
+			liveLeases: listLeases(entry.entryPath).filter((lease) => ownerLive(lease)).length,
+			verifiedAt: readVerified(entry.entryPath)?.verifiedAt ?? ""
+		};
+	});
+	if (context.json) context.io.out(JSON.stringify({
+		cache: context.dirs.cache,
+		entries
+	}, null, 2));
+	else {
+		const lines = [`${context.dirs.cache}`];
+		for (const entry of entries) lines.push(`  npm ${entry.version}  ${entry.path}  last used ${entry.lastUsed ?? "never"}${entry.liveLeases > 0 ? `  in use by ${entry.liveLeases}` : ""}`);
+		if (entries.length === 0) lines.push("  (empty)");
+		context.io.out(lines.join("\n"));
+	}
+	return EXIT.ok;
+}
+async function cachePrune(context, olderThanDays = 90) {
+	if (!Number.isFinite(olderThanDays) || olderThanDays < 0) throw new NpmVmError("M-NOMATCH", EXIT.usage, "--older-than needs a non-negative number of days.");
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		recoverDeadJournals(context.dirs.journal, context.dirs.machine.id);
+		const cacheLock = await acquireLock(context.dirs.cache, context.owner);
+		let report;
+		try {
+			report = pruneCache(context.dirs.cache, context.owner, { maxAgeMs: olderThanDays * DAY_MS });
+		} finally {
+			cacheLock.release();
+		}
+		context.io.out(context.json ? JSON.stringify(report, null, 2) : `Removed ${report.removed.length}, kept ${report.kept.length}, skipped ${report.skipped.length} (in use).`);
+	} finally {
+		lock.release();
+	}
+	return EXIT.ok;
+}
+/** `recover --journal <id> --confirm-dead-machine <machine-id>` (spec PROC-1, CLI). */
+async function recover(context, journalId, confirmedMachine) {
+	const journal = listJournals(context.dirs.journal).find((entry) => entry.id === journalId);
+	if (journal === void 0) throw new NpmVmError("M-NOMATCH", EXIT.usage, `No journal ${journalId} under ${context.dirs.journal}.`);
+	if (journal.owner.machineId !== confirmedMachine) throw new NpmVmError("M-NOMATCH", EXIT.usage, `Journal ${journalId} belongs to machine ${journal.owner.machineId}, not ${confirmedMachine}.`);
+	if (journal.owner.machineId === context.dirs.machine.id && isLive(journal.owner)) throw new NpmVmError("M-LOCKED", EXIT.problems, `Journal ${journalId} belongs to PID ${journal.owner.pid} on this machine, which is still running.`);
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		const report = recoverForeignJournal(context.dirs.journal, journalId, confirmedMachine);
+		context.io.out(context.json ? JSON.stringify(report) : `Recovered ${journalId}: ${describeReport(report)}`);
+	} finally {
+		lock.release();
+	}
+	return EXIT.ok;
+}
+function describeReport(report) {
+	if (report.replayed.length > 0) return "replayed";
+	if (report.rolledBack.length > 0) return "rolled back";
+	if (report.changed.length > 0) return "target changed since, left untouched";
+	return "already finished";
+}
+//#endregion
+//#region src/commands/context.ts
+function terminalIo() {
+	const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	return {
+		out: (text) => process.stdout.write(`${text}\n`),
+		err: (text) => process.stderr.write(`${text}\n`),
+		interactive,
+		async confirm(question) {
+			if (!interactive) return false;
+			const rl = createInterface({
+				input: process.stdin,
+				output: process.stdout
+			});
+			try {
+				const answer = await rl.question(`${question} [y/N] `);
+				return /^y(es)?$/i.test(answer.trim());
+			} finally {
+				rl.close();
+			}
+		}
+	};
+}
+function createCommandContext(options) {
+	const env = options.env ?? process.env;
+	const dirs = resolveDirs(env, options.home);
+	return {
+		dirs,
+		env,
+		platform: process.platform,
+		owner: ownerRecord(dirs.machine.id),
+		io: options.io ?? terminalIo(),
+		json: options.json ?? false,
+		version: options.version
+	};
+}
+//#endregion
+//#region src/setup/link.ts
+const ORIGINAL_SUFFIX = ".npm-vm-original";
+const LINKS_FILE = "links.json";
+function versionsUnder(dir) {
+	try {
+		return readdirSync(dir).filter((name) => /^v?\d+\.\d+\.\d+$/.test(name));
+	} catch {
+		return [];
+	}
+}
+function fnmDir(env, platform, home) {
+	if (env["FNM_DIR"]) return env["FNM_DIR"];
+	if (platform === "win32") return join(env["APPDATA"] ?? join(home, "AppData", "Roaming"), "fnm");
+	if (platform === "darwin") return join(home, "Library", "Application Support", "fnm");
+	return join(env["XDG_DATA_HOME"] || join(home, ".local", "share"), "fnm");
+}
+/** The root nvm-windows keeps its versions in, from its settings.txt (spec LNK-1). */
+function nvmWindowsRoot(env) {
+	const nvmHome = env["NVM_HOME"];
+	if (!nvmHome) return null;
+	try {
+		const settings = readFileSync(join(nvmHome, "settings.txt"), "utf8");
+		return /^root:\s*(.+)$/m.exec(settings)?.[1]?.trim() ?? nvmHome;
+	} catch {
+		return nvmHome;
+	}
+}
+/** Windows paths resolved through junctions and compared without case, so one install is never linked twice (LNK-4). */
+function installKey(binDir, platform) {
+	let real = binDir;
+	try {
+		real = realpathSync(binDir);
+	} catch {}
+	return platform === "win32" ? real.toLowerCase() : real;
+}
+function findNodeInstalls(env = process.env, platform = process.platform, home = env["HOME"] || homedir()) {
+	const installs = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (install) => {
+		const key = installKey(install.binDir, platform);
+		if (!seen.has(key) && existsSync(install.binDir)) {
+			seen.add(key);
+			installs.push(install);
+		}
+	};
+	const nvmDir = env["NVM_DIR"] || join(home, ".nvm");
+	for (const version of versionsUnder(join(nvmDir, "versions", "node"))) add({
+		manager: "nvm",
+		version: version.replace(/^v/, ""),
+		binDir: join(nvmDir, "versions", "node", version, "bin")
+	});
+	const fnm = join(fnmDir(env, platform, home), "node-versions");
+	for (const version of versionsUnder(fnm)) {
+		const installation = join(fnm, version, "installation");
+		add({
+			manager: "fnm",
+			version: version.replace(/^v/, ""),
+			binDir: platform === "win32" ? installation : join(installation, "bin")
+		});
+	}
+	if (platform === "win32") {
+		const root = nvmWindowsRoot(env);
+		if (root !== null) for (const version of versionsUnder(root)) add({
+			manager: "nvm-windows",
+			version: version.replace(/^v/, ""),
+			binDir: join(root, version)
+		});
+	}
+	return installs;
+}
+/** The files `--link` replaces in one install; blocked `.ps1` files are moved aside so `.cmd` wins. */
+function linkTargets(home, platform, powershell) {
+	const targets = [];
+	for (const name of ["npm", "npx"]) {
+		targets.push({
+			name,
+			content: posixShim(home, name),
+			mode: 493
+		});
+		if (platform === "win32") {
+			targets.push({
+				name: `${name}.cmd`,
+				content: cmdShim(home, name),
+				mode: 420
+			});
+			targets.push({
+				name: `${name}.ps1`,
+				content: powershell ? powershellShim(home, name) : null,
+				mode: 420
+			});
+		}
+	}
+	return targets;
+}
+/** Keeps a copy of the original beside the target; a symlink is copied as a symlink. */
+function preserveOriginal(path, originalPath, meta) {
+	if (meta.type === "symlink") symlinkSync(readlinkSync(path), originalPath);
+	else copyFileSync(path, originalPath);
+}
+/** Puts the preserved original back in place of whatever is (or is not) at the target. */
+function restoreOriginal(dirs, owner, entry) {
+	const originalPath = entry.originalPath;
+	if (entry.original.type === "symlink") {
+		mutateFile(dirs.journal, "link", owner, entry.target, null);
+		withSharingRetry(() => renameSync(originalPath, entry.target));
+		return;
+	}
+	mutateFile(dirs.journal, "link", owner, entry.target, readFileSync(originalPath), entry.original.mode || 493);
+	rmSync(originalPath, { force: true });
+}
+/**
+* Replaces one entry point with a shim (spec LNK-2, LNK-3). The original is copied beside the target and
+* recorded before the journaled write, so a crash at any step leaves either a restorable original or the shim.
+* A file matching neither our shim nor the recorded original is reported and left alone.
+*/
+function linkOne(dirs, owner, binDir, target) {
+	const path = join(binDir, target.name);
+	const originalPath = `${path}${ORIGINAL_SUFFIX}`;
+	const known = readLinks(dirs).entries.find((entry) => entry.target === path);
+	let current = captureMeta(path);
+	if (current.type === "missing" && known !== void 0 && known.shim.type !== "missing" && known.originalPath !== null && existsSync(known.originalPath)) {
+		restoreOriginal(dirs, owner, known);
+		forget$1(dirs, known);
+		current = captureMeta(path);
+	}
+	if (target.content === null) return moveAside(dirs, owner, binDir, target.name, known);
+	if (current.type === "missing" && known !== void 0 && known.shim.type === "missing" && known.originalPath !== null && metaMatches(known.originalPath, known.original)) {
+		mutateFile(dirs.journal, "link", owner, path, Buffer.from(target.content, "utf8"), target.mode);
+		record(dirs, {
+			...known,
+			shim: captureMeta(path),
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "linked"
+		};
+	}
+	if (current.type === "missing") return {
+		target: path,
+		outcome: "missing"
+	};
+	if (current.type === "file" && readFileSync(path, "utf8") === target.content) {
+		if (known === void 0) record(dirs, {
+			binDir,
+			name: target.name,
+			target: path,
+			originalPath: existsSync(originalPath) ? originalPath : null,
+			original: captureMeta(originalPath),
+			shim: current,
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		else if (known.shim.type === "missing") record(dirs, {
+			...known,
+			shim: current,
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "already"
+		};
+	}
+	if (known !== void 0 && metaMatches(path, known.shim)) {
+		mutateFile(dirs.journal, "link", owner, path, Buffer.from(target.content, "utf8"), target.mode);
+		record(dirs, {
+			...known,
+			shim: captureMeta(path),
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "linked"
+		};
+	}
+	if (known !== void 0 && !metaMatches(path, known.original)) return {
+		target: path,
+		outcome: "foreign",
+		detail: "changed since npm-vm linked it"
+	};
+	if (existsSync(originalPath) && !metaMatches(originalPath, current)) return {
+		target: path,
+		outcome: "foreign",
+		detail: `${originalPath} already exists`
+	};
+	try {
+		if (!existsSync(originalPath)) preserveOriginal(path, originalPath, current);
+	} catch (error) {
+		return {
+			target: path,
+			outcome: "unwritable",
+			detail: error.message
+		};
+	}
+	const entry = {
+		binDir,
+		name: target.name,
+		target: path,
+		originalPath,
+		original: current,
+		shim: MISSING,
+		linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	record(dirs, entry);
+	try {
+		mutateFile(dirs.journal, "link", owner, path, Buffer.from(target.content, "utf8"), target.mode);
+	} catch (error) {
+		return {
+			target: path,
+			outcome: "unwritable",
+			detail: error.message
+		};
+	}
+	record(dirs, {
+		...entry,
+		shim: captureMeta(path)
+	});
+	return {
+		target: path,
+		outcome: "linked"
+	};
+}
+/** Moves a file aside without a replacement, for Node's `.ps1` entry points when scripts are blocked. */
+function moveAside(dirs, owner, binDir, name, known) {
+	const path = join(binDir, name);
+	const originalPath = `${path}${ORIGINAL_SUFFIX}`;
+	const current = captureMeta(path);
+	if (known !== void 0 && known.shim.type !== "missing" && metaMatches(path, known.shim)) {
+		mutateFile(dirs.journal, "link", owner, path, null);
+		record(dirs, {
+			...known,
+			shim: MISSING,
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "linked"
+		};
+	}
+	if (current.type === "missing") {
+		if (known === void 0 && existsSync(originalPath)) {
+			record(dirs, {
+				binDir,
+				name,
+				target: path,
+				originalPath,
+				original: captureMeta(originalPath),
+				shim: MISSING,
+				linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return {
+				target: path,
+				outcome: "already"
+			};
+		}
+		return {
+			target: path,
+			outcome: known !== void 0 && existsSync(originalPath) ? "already" : "missing"
+		};
+	}
+	if (known !== void 0 && !metaMatches(path, known.original)) return {
+		target: path,
+		outcome: "foreign",
+		detail: "changed since npm-vm linked it"
+	};
+	if (existsSync(originalPath) && !metaMatches(originalPath, current)) return {
+		target: path,
+		outcome: "foreign",
+		detail: `${originalPath} already exists`
+	};
+	try {
+		withSharingRetry(() => renameSync(path, originalPath));
+	} catch (error) {
+		return {
+			target: path,
+			outcome: "unwritable",
+			detail: error.message
+		};
+	}
+	record(dirs, {
+		binDir,
+		name,
+		target: path,
+		originalPath,
+		original: current,
+		shim: MISSING,
+		linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	return {
+		target: path,
+		outcome: "linked"
+	};
+}
+/** Puts the original back only when the shim is still ours (spec MUT-5); a replaced file is left as is. */
+function unlinkOne(dirs, owner, entry) {
+	const current = captureMeta(entry.target);
+	const hasOriginal = entry.originalPath !== null && existsSync(entry.originalPath);
+	if (current.type === "missing") {
+		if (hasOriginal && metaMatches(entry.originalPath, entry.original)) {
+			restoreOriginal(dirs, owner, entry);
+			forget$1(dirs, entry);
+			return "restored";
+		}
+		if (hasOriginal) return "changed";
+		forget$1(dirs, entry);
+		return "missing";
+	}
+	if (entry.shim.type === "missing") return "changed";
+	if (!metaMatches(entry.target, entry.shim)) return "changed";
+	if (hasOriginal) restoreOriginal(dirs, owner, entry);
+	else mutateFile(dirs.journal, "link", owner, entry.target, null);
+	forget$1(dirs, entry);
+	return "restored";
+}
+function record(dirs, entry) {
+	const links = readLinks(dirs);
+	links.entries = [...links.entries.filter((item) => item.target !== entry.target), entry];
+	writeLinks(dirs, links);
+}
+function forget$1(dirs, entry) {
+	const links = readLinks(dirs);
+	links.entries = links.entries.filter((item) => item.target !== entry.target);
+	writeLinks(dirs, links);
+}
+function readLinks(dirs) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dirs.state, LINKS_FILE), "utf8"));
+		return Array.isArray(parsed.entries) ? parsed : {
+			version: 1,
+			entries: []
+		};
+	} catch {
+		return {
+			version: 1,
+			entries: []
+		};
+	}
+}
+function writeLinks(dirs, links) {
+	atomicWrite(join(dirs.state, LINKS_FILE), JSON.stringify(links, null, "	"), 384);
+}
+/** Whether a recorded link still holds our shim, for `doctor` (spec CLI). */
+function linkState(entry) {
+	const type = captureMeta(entry.target).type;
+	if (entry.shim.type === "missing") {
+		const preserved = entry.originalPath !== null && metaMatches(entry.originalPath, entry.original);
+		return type === "missing" ? preserved ? "intact" : "missing" : "changed";
+	}
+	if (type === "missing") return "missing";
+	return metaMatches(entry.target, entry.shim) ? "intact" : "changed";
+}
+//#endregion
+//#region src/setup/layout.ts
+const BOOTSTRAP_FILE = "bootstrap.cjs";
+const CURRENT_FILE = "current";
+const PREVIOUS_FILE = "previous";
+const MANIFEST_FILE = "manifest.json";
+const VERSIONS_DIR = "versions";
+/**
+* Where this code's runtime build lives: beside an installed `runtime.cjs`, under `dist/runtime/` for the
+* bin, or `../../dist/runtime/` when running from source. Null when nothing has been built.
+*/
+function runtimeDistDir() {
+	const here = import.meta.dirname;
+	const candidates = [
+		here,
+		join(here, "runtime"),
+		join(here, "..", "dist", "runtime"),
+		join(here, "..", "..", "dist", "runtime")
+	];
+	for (const candidate of candidates) if (existsSync(join(candidate, "runtime.cjs")) && existsSync(join(candidate, "bootstrap.cjs"))) return candidate;
+	return null;
+}
+function versionDir(home, version) {
+	return join(home, VERSIONS_DIR, version);
+}
+function copyTree(from, to, files, prefix = "") {
+	mkdirSync(to, {
+		recursive: true,
+		mode: 493
+	});
+	for (const name of readdirSync(from)) {
+		const source = join(from, name);
+		const target = join(to, name);
+		if (statSync(source).isDirectory()) copyTree(source, target, files, `${prefix}${name}/`);
+		else {
+			copyFileSync(source, target);
+			files.push(`${prefix}${name}`);
+		}
+	}
+}
+/**
+* Installs one runtime version under `versions/<version>/` atomically (spec SET-1): copied into a
+* temp dir beside it and renamed into place, so a crash never leaves a half-written version.
+*/
+function installVersion(home, version, distDir, abi) {
+	const versions = join(home, VERSIONS_DIR);
+	mkdirSync(versions, {
+		recursive: true,
+		mode: 493
+	});
+	const target = versionDir(home, version);
+	const staging = join(versions, `.${version}.${process.pid}.${Date.now()}`);
+	rmSync(staging, {
+		recursive: true,
+		force: true
+	});
+	const files = [];
+	copyTree(distDir, staging, files);
+	const manifest = {
+		version,
+		abi,
+		files: files.toSorted()
+	};
+	writeFileSync(join(staging, MANIFEST_FILE), JSON.stringify(manifest, null, "	"));
+	const replaced = join(versions, `.${version}.replaced.${process.pid}.${Date.now()}`);
+	if (existsSync(target)) atomicRename(target, replaced);
+	try {
+		atomicRename(staging, target);
+	} catch (error) {
+		if (existsSync(replaced)) atomicRename(replaced, target);
+		throw error;
+	}
+	removeWithRetry(replaced);
+	return target;
+}
+function readCurrent(home) {
+	try {
+		return readFileSync(join(home, CURRENT_FILE), "utf8").trim();
+	} catch {
+		return null;
+	}
+}
+function readPrevious(home) {
+	try {
+		return readFileSync(join(home, PREVIOUS_FILE), "utf8").trim();
+	} catch {
+		return null;
+	}
+}
+function readManifest(home, version) {
+	try {
+		return JSON.parse(readFileSync(join(versionDir(home, version), MANIFEST_FILE), "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** Removes copies a crashed reinstall moved aside; the launcher only reads them while `versions/<v>` is missing. */
+function sweepReplaced(home) {
+	let names;
+	try {
+		names = readdirSync(join(home, VERSIONS_DIR));
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		const match = /^\.(.+)\.replaced\./.exec(name);
+		if (match !== null && existsSync(join(home, "versions", match[1], "runtime.cjs"))) removeWithRetry(join(home, VERSIONS_DIR, name));
+	}
+}
+/** The ABI an installed runtime declares, read from its manifest. */
+function runtimeAbi(home, version) {
+	return readManifest(home, version)?.abi ?? null;
+}
+//#endregion
+//#region src/setup/profile.ts
+const PROFILES_FILE = "profiles.json";
+const BLOCK_RE = /^# >>> npm-vm >>>\n[\s\S]*?^# <<< npm-vm <<<\n?/m;
+function bashLoginFile(home) {
+	for (const name of [
+		".bash_profile",
+		".bash_login",
+		".profile"
+	]) if (existsSync(join(home, name))) return join(home, name);
+	return join(home, ".bash_profile");
+}
+/** The user profile of one PowerShell host, asked with `-NoProfile` so nothing of the user's runs (spec SEC-8). */
+function powershellProfile(host, env, platform = process.platform) {
+	const bin = host === "powershell" ? powershellPath(env) : shellBinary("powershell", env, platform);
+	if (bin === null) return null;
+	try {
+		const out = execFileSync(bin, [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"$PROFILE.CurrentUserAllHosts"
+		], {
+			encoding: "utf8",
+			env,
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		return out === "" ? null : out;
+	} catch {
+		return null;
+	}
+}
+/** The files to edit for `shells` (spec SH-3); PowerShell hosts that are not installed yield nothing. */
+function profileTargets(shells, env = process.env, platform = process.platform, home = env["HOME"] || homedir()) {
+	const targets = [];
+	for (const shell of shells) switch (shell) {
+		case "zsh": {
+			const zdot = env["ZDOTDIR"] || home;
+			targets.push({
+				shell,
+				file: join(zdot, ".zshenv"),
+				parts: {
+					path: true,
+					hook: false
+				}
+			});
+			targets.push({
+				shell,
+				file: join(zdot, ".zshrc"),
+				parts: {
+					path: false,
+					hook: true
+				}
+			});
+			break;
+		}
+		case "bash": {
+			targets.push({
+				shell,
+				file: join(home, ".bashrc"),
+				parts: {
+					path: true,
+					hook: true
+				}
+			});
+			const login = bashLoginFile(home);
+			if (login !== join(home, ".bashrc")) targets.push({
+				shell,
+				file: login,
+				parts: {
+					path: true,
+					hook: false
+				}
+			});
+			break;
+		}
+		case "fish": {
+			const config = env["XDG_CONFIG_HOME"] || join(home, ".config");
+			targets.push({
+				shell,
+				file: join(config, "fish", "conf.d", "npm-vm.fish"),
+				parts: {
+					path: true,
+					hook: true
+				}
+			});
+			break;
+		}
+		case "powershell": {
+			const hosts = platform === "win32" ? ["powershell", "pwsh"] : ["pwsh"];
+			for (const host of hosts) {
+				const file = powershellProfile(host, env, platform);
+				if (file !== null && !targets.some((target) => target.file === file)) targets.push({
+					shell,
+					file,
+					parts: {
+						path: true,
+						hook: true
+					}
+				});
+			}
+			break;
+		}
+	}
+	return targets;
+}
+/** Why a profile is printed instead of edited (spec SH-5), or null when editing it is fine. */
+function profileGuard(file, env = process.env, platform = process.platform) {
+	let stat;
+	try {
+		stat = lstatSync(file);
+	} catch {
+		stat = null;
+	}
+	if (stat !== null && stat.isSymbolicLink()) return "it is a symlink, so a dotfile manager probably owns it";
+	let probe = stat === null ? dirname(file) : file;
+	while (!existsSync(probe) && dirname(probe) !== probe) probe = dirname(probe);
+	try {
+		accessSync(probe, constants.W_OK);
+	} catch {
+		return "it is not writable";
+	}
+	try {
+		if (realpathSync(probe).startsWith("/nix/store")) return "it lives in the Nix store (home-manager)";
+	} catch {}
+	const chezmoi = join(env["HOME"] || homedir(), ".local", "share", "chezmoi");
+	if (existsSync(join(chezmoi, `dot_${basename(file).replace(/^\./, "")}`))) return "chezmoi manages it";
+	if (platform === "win32" && stat !== null && file.endsWith(".ps1")) {
+		if (readFileSync(file, "utf8").includes("# SIG # Begin signature block") && executionPolicy(env) === "AllSigned") return "it is signed and the execution policy is AllSigned";
+	}
+	return null;
+}
+/** The effective PowerShell execution policy, asked without a profile (spec WIN-2). */
+function executionPolicy(env = process.env) {
+	try {
+		return execFileSync(powershellPath(env), [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"Get-ExecutionPolicy"
+		], {
+			encoding: "utf8",
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+/** The content with our block replaced or appended; a trailing newline is guaranteed before the block. */
+function withBlock(content, block) {
+	const text = content ?? "";
+	if (BLOCK_RE.test(text)) return text.replace(BLOCK_RE, block);
+	return `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${text === "" ? "" : "\n"}${block}`;
+}
+/** The content without our block and the blank line that separated it; nothing else moves. */
+function withoutBlock(content) {
+	const match = BLOCK_RE.exec(content);
+	if (match === null) return content;
+	let before = content.slice(0, match.index).replace(/\n+$/, "\n");
+	if (before === "\n") before = "";
+	const after = content.slice(match.index + match[0].length);
+	return before !== "" && after !== "" ? `${before}\n${after}` : `${before}${after}`;
+}
+function currentBlock(content) {
+	const match = BLOCK_RE.exec(content);
+	return match === null ? null : match[0];
+}
+function renderDiff(file, before, after) {
+	const oldBlock = before === null ? null : currentBlock(before);
+	const newBlock = currentBlock(after) ?? "";
+	const lines = [`--- ${file}`, `+++ ${file}`];
+	if (oldBlock !== null) lines.push(...oldBlock.trimEnd().split("\n").map((line) => `-${line}`));
+	lines.push(...newBlock.trimEnd().split("\n").map((line) => `+${line}`));
+	return `${lines.join("\n")}\n`;
+}
+/** What `setup` would write for `target`, or null when the file already holds exactly this block. */
+function planProfileEdit(target, home) {
+	const before = existsSync(target.file) ? readFileSync(target.file, "utf8") : null;
+	const after = withBlock(before, profileBlock(target.shell, home, target.parts));
+	if (before === after) return null;
+	return {
+		target,
+		before,
+		after,
+		diff: renderDiff(target.file, before, after)
+	};
+}
+function uniqueBackup(file) {
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+	let candidate = `${file}.npm-vm-backup-${stamp}`;
+	let counter = 1;
+	while (existsSync(candidate)) {
+		candidate = `${file}.npm-vm-backup-${stamp}-${counter}`;
+		counter += 1;
+	}
+	return candidate;
+}
+/** Applies one consented edit under a journal and a unique backup, and records it (spec SH-4). */
+function applyProfileEdit(dirs, owner, edit) {
+	let backup = null;
+	if (edit.before !== null) {
+		backup = uniqueBackup(edit.target.file);
+		atomicWrite(backup, edit.before, 384);
+	}
+	const mode = edit.before === null ? 420 : captureMeta(edit.target.file).mode || 420;
+	mutateFile(dirs.journal, "profile", owner, edit.target.file, Buffer.from(edit.after, "utf8"), mode);
+	const record = {
+		file: edit.target.file,
+		shell: edit.target.shell,
+		parts: edit.target.parts,
+		writtenSha256: sha256(edit.after),
+		backup,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	const profiles = readProfiles(dirs);
+	profiles.entries = [...profiles.entries.filter((entry) => entry.file !== record.file), record];
+	writeProfiles(dirs, profiles);
+	return record;
+}
+/** Removes our block only when the file is still what we wrote (spec MUT-5); otherwise it is left alone. */
+function removeProfileBlock(dirs, owner, record) {
+	if (!existsSync(record.file)) {
+		forget(dirs, record);
+		return "missing";
+	}
+	const content = readFileSync(record.file, "utf8");
+	if (sha256(content) !== record.writtenSha256) return "changed";
+	const after = withoutBlock(content);
+	mutateFile(dirs.journal, "profile", owner, record.file, after.trim() === "" ? null : Buffer.from(after, "utf8"), captureMeta(record.file).mode || 420);
+	forget(dirs, record);
+	return "removed";
+}
+function forget(dirs, record) {
+	const profiles = readProfiles(dirs);
+	profiles.entries = profiles.entries.filter((entry) => entry.file !== record.file);
+	writeProfiles(dirs, profiles);
+}
+function readProfiles(dirs) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dirs.state, PROFILES_FILE), "utf8"));
+		return Array.isArray(parsed.entries) ? parsed : {
+			version: 1,
+			entries: []
+		};
+	} catch {
+		return {
+			version: 1,
+			entries: []
+		};
+	}
+}
+function writeProfiles(dirs, profiles) {
+	atomicWrite(join(dirs.state, PROFILES_FILE), JSON.stringify(profiles, null, "	"), 384);
+}
+//#endregion
+//#region src/setup/windows.ts
+function powershell(env, command) {
+	return execFileSync(powershellPath(env), [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		command
+	], {
+		encoding: "utf8",
+		env,
+		windowsHide: true,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+}
+function regExe(env) {
+	return join(env["SystemRoot"] ?? "C:\\Windows", "System32", "reg.exe");
+}
+function quote(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function readUserPath(env) {
+	return powershell(env, "[Environment]::GetEnvironmentVariable('Path', 'User')");
+}
+function writeUserPath(env, value) {
+	powershell(env, `[Environment]::SetEnvironmentVariable('Path', ${quote(value)}, 'User')`);
+}
+function sameDir(a, b) {
+	return a.replace(/[\\/]+$/, "").toLowerCase() === b.replace(/[\\/]+$/, "").toLowerCase();
+}
+/** Prepends `dir` to the user PATH unless present; returns whether anything changed. */
+function addToUserPath(env, dir) {
+	const parts = readUserPath(env).split(";").filter((part) => part !== "");
+	if (parts.some((part) => sameDir(part, dir))) return false;
+	writeUserPath(env, [dir, ...parts].join(";"));
+	return true;
+}
+function removeFromUserPath(env, dir) {
+	const parts = readUserPath(env).split(";").filter((part) => part !== "");
+	const kept = parts.filter((part) => !sameDir(part, dir));
+	if (kept.length === parts.length) return false;
+	writeUserPath(env, kept.join(";"));
+	return true;
+}
+const AUTORUN_KEY = "HKCU\\Software\\Microsoft\\Command Processor";
+const AUTORUN_MARK = "npm-vm";
+function readCmdAutoRun(env) {
+	try {
+		const out = execFileSync(regExe(env), [
+			"query",
+			AUTORUN_KEY,
+			"/v",
+			"AutoRun"
+		], {
+			encoding: "utf8",
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		return /AutoRun\s+REG_(?:EXPAND_)?SZ\s+(.*)$/m.exec(out)?.[1]?.trim() ?? null;
+	} catch {
+		return null;
+	}
+}
+/** The cmd AutoRun entry that puts shims first in every cmd session; only with `--cmd-autorun` (WIN-3). */
+function autoRunCommand(shimsDir) {
+	return `set "PATH=${shimsDir};%PATH%" & rem ${AUTORUN_MARK}`;
+}
+/** `value` without the fragment `autoRunCommand` generated, whatever home it named; the user's own commands stay. */
+function withoutAutoRunCommand(value) {
+	if (value === null) return "";
+	return value.replace(/^set "PATH=[^"]*;%PATH%" & rem npm-vm(?: & )?/, "").trim();
+}
+function setCmdAutoRun(env, shimsDir) {
+	const ours = autoRunCommand(shimsDir);
+	const kept = withoutAutoRunCommand(readCmdAutoRun(env));
+	const value = kept === "" ? ours : `${ours} & ${kept}`;
+	execFileSync(regExe(env), [
+		"add",
+		AUTORUN_KEY,
+		"/v",
+		"AutoRun",
+		"/t",
+		"REG_SZ",
+		"/d",
+		value,
+		"/f"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	});
+}
+function clearCmdAutoRun(env) {
+	const existing = readCmdAutoRun(env);
+	if (existing === null || !existing.includes(`rem ${AUTORUN_MARK}`)) return false;
+	const rest = withoutAutoRunCommand(existing);
+	if (rest === "") execFileSync(regExe(env), [
+		"delete",
+		AUTORUN_KEY,
+		"/v",
+		"AutoRun",
+		"/f"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	});
+	else execFileSync(regExe(env), [
+		"add",
+		AUTORUN_KEY,
+		"/v",
+		"AutoRun",
+		"/t",
+		"REG_SZ",
+		"/d",
+		rest,
+		"/f"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	});
+	return true;
+}
+/** Whether the effective execution policy lets our unsigned `.ps1` shims run (spec WIN-2). */
+function powershellAllowsScripts(policy) {
+	return policy !== null && ![
+		"Restricted",
+		"AllSigned",
+		"Undefined"
+	].includes(policy);
+}
+/** Which `npm` each Windows context resolves first, for `doctor`. */
+function windowsWinners(env) {
+	const results = [];
+	try {
+		const out = execFileSync(join(env["SystemRoot"] ?? "C:\\Windows", "System32", "where.exe"), ["npm"], {
+			encoding: "utf8",
+			env,
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		results.push({
+			context: "cmd",
+			path: out.split(/\r?\n/)[0] ?? null
+		});
+	} catch {
+		results.push({
+			context: "cmd",
+			path: null
+		});
+	}
+	try {
+		results.push({
+			context: "PowerShell",
+			path: powershell(env, "(Get-Command npm -All | Select-Object -First 1).Source") || null
+		});
+	} catch {
+		results.push({
+			context: "PowerShell",
+			path: null
+		});
+	}
+	return results;
+}
+//#endregion
+//#region src/commands/doctor.ts
+const PROBE_TIMEOUT_MS = 5e3;
+/** The `npm` an interactive login shell resolves, by asking that shell (its profiles decide the PATH). */
+function shellWinner(shell, env) {
+	const bin = shellBinary(shell, env);
+	if (bin === null) return null;
+	const args = shell === "fish" ? [
+		"-l",
+		"-i",
+		"-c",
+		"emit fish_prompt; command -v npm"
+	] : shell === "powershell" ? [
+		"-NoProfile",
+		"-Command",
+		"(Get-Command npm).Source"
+	] : shell === "zsh" ? [
+		"-l",
+		"-i",
+		"-c",
+		"for f in $precmd_functions; do \"$f\"; done; command -v npm"
+	] : [
+		"-l",
+		"-i",
+		"-c",
+		"eval \"$PROMPT_COMMAND\"; command -v npm"
+	];
+	try {
+		const out = execFileSync(bin, args, {
+			encoding: "utf8",
+			env,
+			timeout: PROBE_TIMEOUT_MS,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim().split("\n").pop();
+		return out === void 0 || out === "" ? null : out;
+	} catch {
+		return null;
+	}
+}
+/** A Windows path for comparison: `where` answers with the long name, the home may carry an 8.3 short name. */
+function canonical(path) {
+	try {
+		return realpathSync.native(path).toLowerCase();
+	} catch {
+		return path.toLowerCase();
+	}
+}
+/** What `command -v npm` printed: an alias or a function wins over PATH, so no PATH fix can help. */
+function winnerKind(winner) {
+	if (winner.startsWith("alias ")) return "alias";
+	return winner === "npm" ? "function" : "path";
+}
+function samePath(a, b, platform) {
+	return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+async function collect(context) {
+	const { dirs, env, platform } = context;
+	const report = {
+		home: dirs.home,
+		version: readCurrent(dirs.home),
+		problems: [],
+		notes: []
+	};
+	const setupHint = "Run `npx --prefix ~ -y @mawesome/npm-vm setup`.";
+	const problem = (check, detail, fix) => {
+		report.problems.push({
+			check,
+			detail,
+			fix
+		});
+	};
+	if (report.version === null || readManifest(dirs.home, report.version) === null) problem("runtime", `no runtime is installed under ${dirs.home}`, setupHint);
+	else {
+		const root = join(dirs.home, BOOTSTRAP_FILE);
+		const shipped = join(versionDir(dirs.home, report.version), BOOTSTRAP_FILE);
+		if (!existsSync(root) || !readFileSync(root).equals(readFileSync(shipped))) problem("launcher", `${root} differs from the installed version's launcher`, setupHint);
+	}
+	for (const name of SELECTORS) {
+		const file = join(shimDir(dirs.home), name);
+		const abi = existsSync(file) ? shimAbi(readFileSync(file, "utf8")) : null;
+		if (abi === null) problem("shims", `${file} is missing or not an npm-vm shim`, setupHint);
+		else if (abi !== 1) problem("shims", `${file} declares launcher ABI ${abi}, this version needs 1`, setupHint);
+	}
+	if (dirs.machine.fallback) report.notes.push("The machine id falls back to the hostname; cloned machines or containers sharing this home could collide in the cache.");
+	const lock = readLock(dirs.state);
+	if (lock !== null && !lockOwnerLive(lock, dirs.machine.id)) problem("lock", `${lockPath(dirs.state)} is held by PID ${lock.pid}, which no longer runs`, `Delete ${lockPath(dirs.state)}.`);
+	for (const journal of listJournals(dirs.journal)) {
+		const foreign = journal.owner.machineId !== dirs.machine.id;
+		problem("journal", `${journal.id} (${journal.kind}) for ${journal.target} was left by ${foreign ? `another machine (${journal.owner.host})` : `PID ${journal.owner.pid}`}`, foreign ? `Confirm no npm-vm runs on ${journal.owner.host}, then run \`npm-vm recover --journal ${journal.id} --confirm-dead-machine ${journal.owner.machineId}\`.` : "Run any npm-vm command; dead owners are recovered automatically.");
+	}
+	const profiles = readProfiles(dirs);
+	for (const entry of profiles.entries) if (!existsSync(entry.file) || !readFileSync(entry.file, "utf8").includes("# >>> npm-vm >>>")) problem("profile", `${entry.file} no longer holds the npm-vm block`, `Run \`npm-vm init ${entry.shell}\` and add the block, or run setup again.`);
+	const shimsDir = shimDir(dirs.home);
+	if (platform === "win32") {
+		const shimsCanonical = canonical(shimsDir);
+		for (const winner of windowsWinners(env)) if (winner.path === null || !canonical(winner.path).startsWith(shimsCanonical)) problem("path", `${winner.context} resolves npm to ${winner.path ?? "nothing"}`, "Run setup again, then restart the terminal (M-RESTART).");
+	} else {
+		const login = basename(env["SHELL"] ?? "");
+		const shells = /* @__PURE__ */ new Set([...profiles.entries.map((entry) => entry.shell), ...isShell(login) ? [login] : []]);
+		for (const shell of shells) {
+			if (shell === "powershell") continue;
+			const winner = shellWinner(shell, env);
+			if (winner === null) continue;
+			const kind = winnerKind(winner);
+			if (kind !== "path") problem("path", `${shell} resolves npm to a shell ${kind}: ${winner}`, `A shell ${kind} wins over PATH. Remove it from your ${shell} profile, or make it run ${join(shimsDir, "npm")}.`);
+			else if (!samePath(winner, join(shimsDir, "npm"), platform)) problem("path", `${shell} resolves npm to ${winner}${winner.includes("corepack") ? " (a Corepack shim)" : ""}`, `Add the snippet from \`npm-vm init ${shell}\` after your Node manager's init line, or run setup with --link.`);
+		}
+	}
+	const links = readLinks(dirs);
+	if (links.entries.length > 0) {
+		for (const entry of links.entries) {
+			const state = linkState(entry);
+			if (state !== "intact") problem("link", `${entry.target} is ${state === "missing" ? "missing" : "no longer the npm-vm shim"}`, "Run `npm-vm setup --link` to relink, or `npm-vm uninstall` to stop linking.");
+		}
+		const linked = new Set(links.entries.map((entry) => entry.binDir));
+		for (const install of findNodeInstalls(env, platform)) if (!linked.has(install.binDir)) problem("link", `${install.manager} ${install.version} at ${install.binDir} is not linked`, "Run `npm-vm setup --link`.");
+	}
+	report.notes.push(...findNodeInstalls(env, platform).map((install) => `Found ${install.manager} ${install.version} at ${install.binDir}`));
+	const project = findProject([], process.cwd(), env);
+	if (existsSync(join(project.root, "node_modules", ".bin", "npm"))) report.notes.push(`${project.root}/node_modules/.bin/npm exists; npm scripts in this project run it instead of the shim.`);
+	return report;
+}
+async function doctor(context, options = {}) {
+	const report = await collect(context);
+	if (options.quiet) return report.problems.length === 0 ? EXIT.ok : EXIT.problems;
+	if (context.json) context.io.out(JSON.stringify(report, null, 2));
+	else {
+		const lines = [`npm-vm ${report.version ?? "(not installed)"} in ${report.home}`];
+		for (const problem of report.problems) lines.push(`  problem [${problem.check}]: ${problem.detail}`, `    fix: ${problem.fix}`);
+		for (const note of report.notes) lines.push(`  note: ${note}`);
+		lines.push(report.problems.length === 0 ? "  healthy" : `  ${report.problems.length} problem(s)`);
+		context.io.out(lines.join("\n"));
+	}
+	return report.problems.length === 0 ? EXIT.ok : EXIT.problems;
+}
+//#endregion
+//#region src/commands/pin.ts
+/** The indentation and newline a JSON file uses, so the rewrite keeps its shape. */
+function detectFormat(text) {
+	return {
+		indent: /^[ \t]+(?=")/m.exec(text)?.[0] ?? "  ",
+		newline: text.includes("\r\n") ? "\r\n" : "\n",
+		trailingNewline: text.endsWith("\n")
+	};
+}
+/** `devEngines.packageManager` with one npm entry, keeping other managers and the field's shape. */
+function pinnedManifest(pkg, version) {
+	const entry = {
+		name: "npm",
+		version,
+		onFail: "error"
+	};
+	const devEngines = typeof pkg["devEngines"] === "object" && pkg["devEngines"] !== null ? { ...pkg["devEngines"] } : {};
+	const existing = devEngines["packageManager"];
+	if (Array.isArray(existing)) devEngines["packageManager"] = [...existing.filter((item) => !(typeof item === "object" && item !== null && item.name === "npm")), entry];
+	else if (typeof existing === "object" && existing !== null && existing.name !== "npm") devEngines["packageManager"] = [existing, entry];
+	else devEngines["packageManager"] = entry;
+	return {
+		...pkg,
+		devEngines
+	};
+}
+function nearestManifestDir(cwd) {
+	let dir = cwd;
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/** `^<latest npm whose engines accept the active Node>`, asked from the registry. */
+async function defaultRange(context) {
+	const latest = (await createInstaller(createContext(context.env, context.dirs.home)).registry([parseVersionSpec(">=8", "pin")])).filter((candidate) => candidate.enginesNode === null || semver.satisfies(process.version, candidate.enginesNode, { includePrerelease: true })).map((candidate) => candidate.version).toSorted(semver.rcompare)[0];
+	if (latest === void 0) throw new NpmVmError("M-NOMATCH", EXIT.resolution, `No npm release supports Node ${process.version}.`);
+	return `^${latest}`;
+}
+async function pin(context, range, cwd = process.cwd()) {
+	const project = findProject([], cwd, context.env);
+	const nearest = nearestManifestDir(cwd);
+	if (nearest !== null && nearest !== project.root) throw new NpmVmError("M-NOMATCH", EXIT.usage, `${nearest} is a workspace of ${project.root}; npm reads devEngines from the root. Run pin from ${project.root} to pin it there.`);
+	const file = join(project.root, "package.json");
+	if (!existsSync(file)) throw new NpmVmError("M-NOMATCH", EXIT.usage, `No package.json in ${project.root}.`);
+	const version = range ?? await defaultRange(context);
+	try {
+		parseVersionSpec(version, "pin");
+	} catch (error) {
+		throw new NpmVmError("M-NOMATCH", EXIT.usage, error.message);
+	}
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		recoverDeadJournals(context.dirs.journal, context.dirs.machine.id);
+		const text = readFileSync(file, "utf8");
+		let pkg;
+		try {
+			pkg = JSON.parse(text);
+		} catch (error) {
+			throw new NpmVmError("M-NOMATCH", EXIT.usage, `${file} is not valid JSON: ${error.message}`);
+		}
+		const format = detectFormat(text);
+		const output = `${JSON.stringify(pinnedManifest(pkg, version), null, format.indent).replace(/\n/g, format.newline)}${format.trailingNewline ? format.newline : ""}`;
+		if (output !== text) {
+			const mode = process.platform === "win32" ? 420 : statSync(file).mode & 4095;
+			mutateFile(context.dirs.journal, "project", context.owner, file, Buffer.from(output, "utf8"), mode);
+		}
+	} finally {
+		lock.release();
+	}
+	context.io.out(context.json ? JSON.stringify({
+		file,
+		version
+	}) : `Pinned npm ${version} in ${file}`);
+	return EXIT.ok;
+}
+//#endregion
+//#region src/commands/self-update.ts
+const PACKAGE_NAME = "@mawesome/npm-vm";
+function run$1(file, args) {
+	return new Promise((resolve) => {
+		execFile(process.execPath, [file, ...args], {
+			encoding: "utf8",
+			timeout: 6e4,
+			windowsHide: true
+		}, (error, stdout, stderr) => {
+			resolve({
+				code: error === null ? 0 : error.code ?? 1,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+/** The launcher generation a bootstrap file belongs to, read from its `LAUNCHER_ABI` constant. */
+function launcherAbiOf(bootstrapFile) {
+	const abi = shimAbi(readFileSync(bootstrapFile, "utf8"));
+	if (abi === null) throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`${bootstrapFile} declares no launcher ABI`));
+	return abi;
+}
+/**
+* Replaces the home's launcher files with those of `version` (spec SUP-3): the bootstrap at the root and
+* every shim, rendered from that version's templates, each under a journal.
+*/
+function installLaunchers(context, version) {
+	const { dirs, platform, env } = context;
+	const dir = versionDir(dirs.home, version);
+	const bootstrap = join(dir, BOOTSTRAP_FILE);
+	const abi = launcherAbiOf(bootstrap);
+	mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, BOOTSTRAP_FILE), readFileSync(bootstrap), 420);
+	const powershell = platform !== "win32" || powershellAllowsScripts(executionPolicy(env));
+	mkdirSync(shimDir(dirs.home), {
+		recursive: true,
+		mode: 493
+	});
+	for (const file of renderShims(dirs.home, platform, {
+		powershell,
+		templates: join(dir, LAUNCHERS_DIR),
+		abi
+	})) mutateFile(dirs.journal, "launcher", context.owner, join(shimDir(dirs.home), file.name), Buffer.from(file.content), file.mode);
+	if (platform === "win32" && !powershell) for (const stale of stalePowershellShims(dirs.home)) mutateFile(dirs.journal, "launcher", context.owner, stale, null);
+}
+function currentLauncherAbi(context) {
+	const file = join(context.dirs.home, BOOTSTRAP_FILE);
+	return existsSync(file) ? shimAbi(readFileSync(file, "utf8")) : null;
+}
+async function selfUpdate(context, options, deps = {}) {
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		recoverDeadJournals(context.dirs.journal, context.dirs.machine.id);
+		return options.rollback ? rollback(context) : await update(context, deps);
+	} finally {
+		lock.release();
+	}
+}
+/** `self-update --rollback` (spec SUP-4): offline, swaps `current` back and restores the previous launchers if the ABI differs. */
+function rollback(context) {
+	const { dirs, io } = context;
+	const current = readCurrent(dirs.home);
+	const previous = readPrevious(dirs.home);
+	if (previous === null || !existsSync(versionDir(dirs.home, previous)) || current === null) throw new NpmVmError("M-ABI", EXIT.usage, "No previous version to roll back to.");
+	mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, "current"), Buffer.from(`${previous}\n`));
+	if (launcherAbiOf(join(versionDir(dirs.home, previous), "bootstrap.cjs")) !== currentLauncherAbi(context)) installLaunchers(context, previous);
+	atomicWrite(join(dirs.home, PREVIOUS_FILE), `${current}\n`);
+	io.out(context.json ? JSON.stringify({
+		current: previous,
+		previous: current
+	}) : `Rolled back to npm-vm ${previous} (from ${current}).`);
+	return EXIT.ok;
+}
+async function update(context, deps) {
+	const { dirs, env, io } = context;
+	const installed = readCurrent(dirs.home) ?? context.version;
+	const own = findOwnNpm();
+	const found = own?.version ?? null;
+	if (!transportUsable(own)) throw new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(found, "too old or missing"));
+	const work = newWorkDir(dirs.tmp);
+	try {
+		const config = await loadNpmConfig(own, env, work);
+		const transport = new Transport(own, config, env, dirs.tmp);
+		const latest = (await transport.viewPackage(PACKAGE_NAME, "latest"))[0];
+		if (latest === void 0) throw new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(own.version, `${PACKAGE_NAME}@latest is not published`));
+		if (!semver.gt(latest.version, installed)) {
+			io.out(context.json ? JSON.stringify({
+				current: installed,
+				latest: latest.version,
+				updated: false
+			}) : `npm-vm ${installed} is up to date (latest is ${latest.version}).`);
+			return EXIT.ok;
+		}
+		const packed = await transport.packPackage(PACKAGE_NAME, latest.version, work);
+		const digests = await fileDigests(packed.file);
+		if (digests.sha512 !== latest.integrity) throw new NpmVmError("M-INTEGRITY", EXIT.verification, `${PACKAGE_NAME}@${latest.version}: tarball does not match the registry integrity.`);
+		await verifySignatures({
+			name: PACKAGE_NAME,
+			version: latest.version,
+			integrity: latest.integrity,
+			signatures: latest.signatures,
+			publishedAt: async () => null,
+			keys: loadKeyring(dirs.state),
+			registry: config.registry,
+			pinned: false
+		});
+		await verifyProvenance({
+			name: PACKAGE_NAME,
+			version: latest.version,
+			sha512hex: digests.sha512hex,
+			attestationsUrl: latest.attestationsUrl,
+			config,
+			stateDir: dirs.state
+		}, {
+			...deps.fetchAttestations === void 0 ? {} : { fetch: deps.fetchAttestations },
+			...deps.verifyBundle === void 0 ? {} : { verify: deps.verifyBundle },
+			env
+		});
+		const extracted = join(work, "package");
+		mkdirSync(extracted, { mode: 448 });
+		await safeExtract(packed.file, extracted);
+		const runtimeSource = join(extracted, "dist", "runtime");
+		if (!existsSync(join(runtimeSource, "runtime.cjs")) || !existsSync(join(runtimeSource, "bootstrap.cjs"))) throw new NpmVmError("M-INTEGRITY", EXIT.verification, `${PACKAGE_NAME}@${latest.version} ships no runtime build.`);
+		const candidateAbi = launcherAbiOf(join(runtimeSource, BOOTSTRAP_FILE));
+		const installedRuntimeAbi = runtimeAbi(dirs.home, installed) ?? currentLauncherAbi(context) ?? candidateAbi;
+		if (installedRuntimeAbi < candidateAbi - 1) throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`npm-vm ${latest.version} skips launcher generations (${installedRuntimeAbi} to ${candidateAbi})`));
+		if (candidateAbi < installedRuntimeAbi) throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`npm-vm ${latest.version} ships launcher ABI ${candidateAbi}, older than the installed runtime's ${installedRuntimeAbi}`));
+		const target = installVersion(dirs.home, latest.version, runtimeSource, candidateAbi);
+		const health = await run$1(join(target, BOOTSTRAP_FILE), [
+			"--candidate",
+			"cli",
+			"--version"
+		]);
+		if (health.code !== 0 || health.stdout.trim() !== latest.version) {
+			rmSync(target, {
+				recursive: true,
+				force: true
+			});
+			throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`the downloaded runtime failed its health check: ${health.stderr.trim() || health.stdout.trim() || `exit ${health.code}`}`));
+		}
+		if (candidateAbi !== currentLauncherAbi(context)) installLaunchers(context, latest.version);
+		atomicWrite(join(dirs.home, PREVIOUS_FILE), `${installed}\n`);
+		mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, "current"), Buffer.from(`${latest.version}\n`));
+		io.out(context.json ? JSON.stringify({
+			current: latest.version,
+			previous: installed,
+			updated: true
+		}) : `Updated npm-vm ${installed} to ${latest.version}.`);
+		return EXIT.ok;
+	} finally {
+		rmSync(work, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/commands/setup.ts
+/** Refuses a home or cache another user could write to (spec SEC-9). */
+function assertPrivateDir(dir, platform) {
+	if (platform === "win32") return;
+	const stat = statSync(dir);
+	if (process.getuid !== void 0 && stat.uid !== process.getuid()) throw new NpmVmError("M-DIRPERMS", EXIT.problems, dirPermsMessage(dir, "is not owned by you", `chown $(id -u) ${dir}`));
+	if ((stat.mode & 18) !== 0) throw new NpmVmError("M-DIRPERMS", EXIT.problems, dirPermsMessage(dir, "is writable by other users", `chmod go-w ${dir}`));
+}
+function ensurePrivateDir(dir, platform) {
+	if (!existsSync(dir)) {
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		if (platform !== "win32") chmodSync(dir, 448);
+	}
+	assertPrivateDir(dir, platform);
+}
+/** The shells to configure: `--shell` values, else the login shell, plus PowerShell on Windows. */
+function defaultShells(env, platform) {
+	if (platform === "win32") return ["powershell"];
+	const login = basename(env["SHELL"] ?? "");
+	return isShell(login) ? [login] : ["bash"];
+}
+function sameFiles(home, version, distDir) {
+	const manifest = readManifest(home, version);
+	if (manifest === null) return false;
+	return manifest.files.every((file) => {
+		try {
+			return readFileSync(join(distDir, file)).equals(readFileSync(join(versionDir(home, version), file)));
+		} catch {
+			return false;
+		}
+	});
+}
+async function setup(context, options) {
+	const { dirs, env, platform, io } = context;
+	assertSafeHome(dirs.home);
+	const distDir = runtimeDistDir();
+	if (distDir === null) throw new NpmVmError("M-ABI", EXIT.problems, "This npm-vm installation ships no runtime build; reinstall the package.");
+	for (const dir of [
+		dirs.home,
+		dirs.state,
+		dirs.cache
+	]) if (options.dryRun) {
+		if (existsSync(dir)) assertPrivateDir(dir, platform);
+	} else ensurePrivateDir(dir, platform);
+	const report = {
+		home: dirs.home,
+		version: context.version,
+		profiles: [],
+		links: [],
+		skipped: 0
+	};
+	const shells = options.shells ?? defaultShells(env, platform);
+	const targets = options.modifyProfile ? profileTargets(shells, env, platform) : [];
+	const policy = platform === "win32" ? executionPolicy(env) : null;
+	const powershell = platform !== "win32" || powershellAllowsScripts(policy);
+	const plans = targets.map((target) => ({
+		target,
+		guard: profileGuard(target.file, env, platform),
+		edit: planProfileEdit(target, dirs.home)
+	}));
+	const lock = options.dryRun ? null : await acquireLock(dirs.state, context.owner);
+	try {
+		if (lock !== null) recoverDeadJournals(dirs.journal, dirs.machine.id);
+		if (!options.dryRun) {
+			installRuntime(context, distDir);
+			mkdirSync(shimDir(dirs.home), {
+				recursive: true,
+				mode: 493
+			});
+			for (const file of renderShims(dirs.home, platform, { powershell })) mutateFile(dirs.journal, "launcher", context.owner, join(shimDir(dirs.home), file.name), Buffer.from(file.content), file.mode);
+			if (platform === "win32" && !powershell) for (const stale of stalePowershellShims(dirs.home)) mutateFile(dirs.journal, "launcher", context.owner, stale, null);
+		}
+		for (const plan of plans) report.profiles.push(await applyPlan(context, options, plan));
+		if (options.link) for (const install of findNodeInstalls(env, platform)) for (const target of linkTargets(dirs.home, platform, powershell)) if (options.dryRun) report.links.push({
+			target: join(install.binDir, target.name),
+			outcome: "linked",
+			detail: "dry run"
+		});
+		else report.links.push(linkOne(dirs, context.owner, install.binDir, target));
+		if (platform === "win32" && !options.dryRun && options.userPath) {
+			if (addToUserPath(env, shimDir(dirs.home))) {
+				env["Path"] = `${shimDir(dirs.home)};${env["Path"] ?? ""}`;
+				io.err(restartMessage());
+			}
+			if (options.cmdAutorun) setCmdAutoRun(env, shimDir(dirs.home));
+			if (!powershell) io.err(`PowerShell's execution policy (${policy ?? "unknown"}) blocks unsigned scripts, so no .ps1 shims were installed; cmd shims take over.`);
+		}
+	} finally {
+		lock?.release();
+	}
+	report.skipped = report.profiles.filter((entry) => entry.outcome === "printed" || entry.outcome === "declined" || entry.outcome === "changed").length + report.links.filter((link) => [
+		"foreign",
+		"unwritable",
+		"missing"
+	].includes(link.outcome)).length;
+	if (context.json) io.out(JSON.stringify(report, null, 2));
+	else io.out(describe$1(report));
+	if (!options.dryRun) {
+		if (await doctor(context, { quiet: context.json }) !== EXIT.ok && options.strict) return EXIT.partial;
+	}
+	return options.strict && report.skipped > 0 ? EXIT.partial : EXIT.ok;
+}
+/** Installs this version's runtime and launcher unless the identical files are already in place. */
+function installRuntime(context, distDir) {
+	const { dirs, version } = context;
+	if (!sameFiles(dirs.home, version, distDir)) installVersion(dirs.home, version, distDir, 1);
+	sweepReplaced(dirs.home);
+	if (readCurrent(dirs.home) !== version) mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, "current"), Buffer.from(`${version}\n`));
+	const bootstrap = readFileSync(join(versionDir(dirs.home, version), BOOTSTRAP_FILE));
+	const installed = existsSync(join(dirs.home, "bootstrap.cjs")) ? readFileSync(join(dirs.home, BOOTSTRAP_FILE)) : null;
+	if (installed === null || !installed.equals(bootstrap)) mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, BOOTSTRAP_FILE), bootstrap, 420);
+}
+async function applyPlan(context, options, plan) {
+	const { io, dirs } = context;
+	const { target } = plan;
+	if (plan.guard !== null) {
+		io.out(`Not editing ${target.file}: ${plan.guard}. Add this yourself:\n${profileBlock(target.shell, dirs.home, target.parts)}`);
+		return {
+			file: target.file,
+			outcome: "printed",
+			reason: plan.guard
+		};
+	}
+	if (plan.edit === null) return {
+		file: target.file,
+		outcome: "unchanged"
+	};
+	if (options.dryRun) {
+		io.out(`Would edit ${target.file}:\n${plan.edit.diff}`);
+		return {
+			file: target.file,
+			outcome: "dry-run"
+		};
+	}
+	if (!options.yes) {
+		io.out(plan.edit.diff);
+		if (!await io.confirm(`Apply this change to ${target.file}?`)) {
+			io.out(`Skipped ${target.file}. Add this yourself:\n${profileBlock(target.shell, dirs.home, target.parts)}`);
+			return {
+				file: target.file,
+				outcome: "declined"
+			};
+		}
+	}
+	const guard = profileGuard(target.file, context.env, context.platform);
+	const fresh = planProfileEdit(target, dirs.home);
+	if (fresh === null) return {
+		file: target.file,
+		outcome: "unchanged"
+	};
+	if (guard !== null || fresh.before !== plan.edit.before && !options.yes) {
+		io.out(`${target.file} changed while the prompt was open; run setup again to review the new change.`);
+		return {
+			file: target.file,
+			outcome: "changed"
+		};
+	}
+	applyProfileEdit(dirs, context.owner, fresh);
+	return {
+		file: target.file,
+		outcome: "written"
+	};
+}
+function describe$1(report) {
+	const lines = [`npm-vm ${report.version} installed in ${report.home}`];
+	for (const profile of report.profiles) lines.push(`  ${profile.file}: ${profile.outcome}${profile.reason ? ` (${profile.reason})` : ""}`);
+	for (const link of report.links) lines.push(`  ${link.target}: ${link.outcome}${link.detail ? ` (${link.detail})` : ""}`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/uninstall.ts
+/** Removes the cache's directories only while empty: an npm publishing right now keeps its entry. */
+function removeEmptyTree(cache) {
+	for (const dir of [
+		join(cache, "npm"),
+		stagingDir(cache),
+		cache
+	]) try {
+		rmdirSync(dir);
+	} catch {}
+}
+async function uninstall(context, options) {
+	const { dirs, env, platform, io } = context;
+	if (!options.yes) {
+		if (!await io.confirm(`Remove npm-vm from ${dirs.home}, its profile blocks and links${options.purgeCache ? ", and the cache" : ""}?`)) {
+			io.out("Nothing removed.");
+			return EXIT.ok;
+		}
+	}
+	const report = {
+		profiles: [],
+		links: [],
+		homeRemoved: false,
+		cacheRemoved: false,
+		cacheKept: []
+	};
+	const lock = await acquireLock(dirs.state, context.owner);
+	let clean = true;
+	try {
+		recoverDeadJournals(dirs.journal, dirs.machine.id);
+		for (const entry of readProfiles(dirs).entries) {
+			const outcome = removeProfileBlock(dirs, context.owner, entry);
+			report.profiles.push({
+				file: entry.file,
+				outcome
+			});
+			if (outcome === "changed") {
+				clean = false;
+				io.err(changedMessage(entry.file, "npm-vm block"));
+			}
+		}
+		for (const entry of readLinks(dirs).entries) {
+			const outcome = unlinkOne(dirs, context.owner, entry);
+			report.links.push({
+				target: entry.target,
+				outcome
+			});
+			if (outcome === "changed") {
+				clean = false;
+				io.err(changedMessage(entry.target, "shim"));
+			}
+		}
+		if (platform === "win32") {
+			removeFromUserPath(env, shimDir(dirs.home));
+			clearCmdAutoRun(env);
+		}
+		if (options.purgeCache) {
+			const cacheLock = await acquireLock(dirs.cache, context.owner);
+			try {
+				const pruned = pruneCache(dirs.cache, context.owner, { maxAgeMs: 0 });
+				report.cacheKept = pruned.kept.concat(pruned.skipped);
+				if (report.cacheKept.length === 0) {
+					removeEmptyTree(dirs.cache);
+					report.cacheRemoved = true;
+				}
+			} finally {
+				cacheLock.release();
+			}
+			if (report.cacheRemoved) removeEmptyTree(dirs.cache);
+			if (report.cacheKept.length > 0) {
+				clean = false;
+				io.err(`Cache kept: ${report.cacheKept.join(", ")} ${report.cacheKept.length === 1 ? "is" : "are"} in use by a running npm.`);
+			}
+		}
+		const tombstone = `${dirs.home}.removing.${process.pid}.${Date.now()}`;
+		atomicRename(dirs.home, tombstone);
+		removeWithRetry(tombstone);
+		report.homeRemoved = true;
+	} finally {
+		lock.release();
+	}
+	io.out(context.json ? JSON.stringify(report, null, 2) : describe(report, dirs.cache));
+	return clean ? EXIT.ok : EXIT.problems;
+}
+function describe(report, cache) {
+	const lines = ["npm-vm removed."];
+	for (const profile of report.profiles) lines.push(`  ${profile.file}: ${profile.outcome}`);
+	for (const link of report.links) lines.push(`  ${link.target}: ${link.outcome}`);
+	if (report.cacheRemoved) lines.push(`  cache removed (${cache})`);
+	else if (report.cacheKept.length > 0) lines.push(`  cache kept at ${cache}: ${report.cacheKept.join(", ")} in use by a running npm`);
+	else lines.push(`  cache kept at ${cache}; add --purge-cache to remove it`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/dispatch.ts
+const VERSION = readSelfVersion();
+const USAGE = `npm-vm v${VERSION}: run the npm version a project declares in devEngines
+
+Usage:
+  npm-vm <command> [options]
+
+Commands:
+  setup                  Install the launcher, shims and shell snippets; --link also replaces npm
+                         inside every nvm/fnm Node. --shell <s> (repeatable), --yes, --dry-run,
+                         --no-modify-profile, --cmd-autorun and --no-user-path (Windows), --strict (exit 2 on skips).
+  init <shell>           Print the snippet for zsh, bash, fish or powershell (--path, --hook; default both).
+  doctor                 Check the installation; exit 1 when something needs fixing.
+  which                  Print the npm that would run for the current directory.
+  pin [<range>]          Write devEngines.packageManager for npm into the project's package.json.
+  install [<spec>]       Download and verify the project's npm, or <spec>, into the cache.
+  cache list             List cached npm versions.
+  cache prune            Remove unused entries; --older-than <days> (default 90).
+  self-update            Update npm-vm with provenance verification; --rollback restores the previous version.
+  recover                Finish a journal left by another machine: --journal <id> --confirm-dead-machine <id>.
+  uninstall              Remove npm-vm (--yes to skip the prompt, --purge-cache to drop the cache too).
+
+Global options:
+  --json                 Machine-readable output where a command offers it.
+  --version, -v          Print the version.
+  --help, -h             Print this help.
+
+Environment:
+  NPM_VM_VERSION        Use this range or version instead of the project's.
+  NPM_VM_DISABLE        Any value: always run Node's own npm.
+  NPM_VM_OFFLINE        Any value: never contact the registry.
+  NPM_VM_HOME           The home directory (setup only).
+
+Exit codes: 0 ok, 1 problems found, 2 partial setup under --strict, 3 resolution failed, 4 transport
+unavailable, 5 verification failed, 6 launcher mismatch, 64 usage error.`;
+function parse(argv) {
+	return parseArgs({
+		args: argv,
+		allowPositionals: true,
+		allowNegative: true,
+		options: {
+			json: { type: "boolean" },
+			path: { type: "boolean" },
+			hook: { type: "boolean" },
+			link: { type: "boolean" },
+			shell: {
+				type: "string",
+				multiple: true
+			},
+			yes: { type: "boolean" },
+			"dry-run": { type: "boolean" },
+			"modify-profile": { type: "boolean" },
+			"cmd-autorun": { type: "boolean" },
+			"user-path": { type: "boolean" },
+			strict: { type: "boolean" },
+			"older-than": { type: "string" },
+			rollback: { type: "boolean" },
+			journal: { type: "string" },
+			"confirm-dead-machine": { type: "string" },
+			"purge-cache": { type: "boolean" },
+			bundle: { type: "string" },
+			"tuf-cache": { type: "string" },
+			version: {
+				type: "boolean",
+				short: "v"
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+}
+/** Command-specific options, so a flag meant for another command is an error rather than silently ignored. */
+const COMMAND_OPTIONS = {
+	setup: [
+		"link",
+		"shell",
+		"yes",
+		"dry-run",
+		"modify-profile",
+		"cmd-autorun",
+		"user-path",
+		"strict"
+	],
+	init: ["path", "hook"],
+	doctor: [],
+	which: [],
+	pin: [],
+	install: [],
+	cache: ["older-than"],
+	"self-update": ["rollback"],
+	recover: ["journal", "confirm-dead-machine"],
+	uninstall: ["yes", "purge-cache"],
+	"verify-attestation": ["bundle", "tuf-cache"]
+};
+function misplacedOptions(command, values) {
+	const allowed = new Set(COMMAND_OPTIONS[command] ?? []);
+	return Object.values(COMMAND_OPTIONS).flat().filter((option) => !allowed.has(option) && values[option] !== void 0).map((option) => `--${option}`);
+}
+async function run(argv, options) {
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		console.error(error.message);
+		console.error(USAGE);
+		return EXIT.usage;
+	}
+	const { values, positionals } = parsed;
+	if (values.version) {
+		console.log(VERSION);
+		return EXIT.ok;
+	}
+	const command = positionals[0];
+	if (values.help || command === void 0) {
+		console.log(USAGE);
+		return command === void 0 && !values.help ? EXIT.usage : EXIT.ok;
+	}
+	if (COMMAND_OPTIONS[command] === void 0) {
+		console.error(`Unknown command: ${command}`);
+		console.error(USAGE);
+		return EXIT.usage;
+	}
+	const misplaced = misplacedOptions(command, values);
+	if (misplaced.length > 0) {
+		console.error(`${misplaced.join(", ")} cannot be used with ${command}`);
+		return EXIT.usage;
+	}
+	const context = createCommandContext({
+		...options.home === void 0 ? {} : { home: options.home },
+		...options.env === void 0 ? {} : { env: options.env },
+		...options.io === void 0 ? {} : { io: options.io },
+		json: values.json ?? false,
+		version: VERSION
+	});
+	try {
+		return await dispatch(command, positionals.slice(1), values, context, options);
+	} catch (error) {
+		return reportError(error, context);
+	}
+}
+async function dispatch(command, rest, values, context, options) {
+	switch (command) {
+		case "setup": {
+			const shells = values.shell ?? null;
+			const bad = shells?.filter((shell) => !isShell(shell)) ?? [];
+			if (bad.length > 0) {
+				context.io.err(`--shell needs one of: ${SHELLS.join(", ")} (got ${bad.join(", ")})`);
+				return EXIT.usage;
+			}
+			return setup(context, {
+				link: values.link ?? false,
+				shells,
+				yes: values.yes ?? false,
+				dryRun: values["dry-run"] ?? false,
+				modifyProfile: values["modify-profile"] ?? true,
+				cmdAutorun: values["cmd-autorun"] ?? false,
+				strict: values.strict ?? false,
+				userPath: values["user-path"] ?? true
+			});
+		}
+		case "init": {
+			const shell = rest[0];
+			if (shell === void 0 || !isShell(shell)) {
+				context.io.err(`init needs one of: ${SHELLS.join(", ")}`);
+				return EXIT.usage;
+			}
+			const both = values.path !== true && values.hook !== true;
+			process.stdout.write(profileBlock(shell, context.dirs.home, {
+				path: both || values.path === true,
+				hook: both || values.hook === true
+			}));
+			return EXIT.ok;
+		}
+		case "doctor": return doctor(context);
+		case "which": {
+			const result = await resolveNpm([], process.cwd(), {
+				home: context.dirs.home,
+				...options.env === void 0 ? {} : { env: options.env }
+			});
+			context.io.out(context.json ? JSON.stringify(result, null, 2) : describeWhich(result));
+			return EXIT.ok;
+		}
+		case "pin": return pin(context, rest[0]);
+		case "install": return install(context, rest[0]);
+		case "cache":
+			if (rest[0] === "list") return cacheList(context);
+			if (rest[0] === "prune") return cachePrune(context, values["older-than"] === void 0 ? 90 : Number(values["older-than"]));
+			context.io.err("cache needs list or prune");
+			return EXIT.usage;
+		case "self-update": return selfUpdate(context, { rollback: values.rollback ?? false });
+		case "recover":
+			if (values.journal === void 0 || values["confirm-dead-machine"] === void 0) {
+				context.io.err("recover needs --journal <id> and --confirm-dead-machine <machine-id>");
+				return EXIT.usage;
+			}
+			return recover(context, values.journal, values["confirm-dead-machine"]);
+		case "verify-attestation": {
+			if (values.bundle === void 0 || values["tuf-cache"] === void 0) return EXIT.usage;
+			const { verifyBundleHere } = await import("./provenance-DDegWCyS.js");
+			await verifyBundleHere(JSON.parse(readFileSync(values.bundle, "utf8")), values["tuf-cache"]);
+			return EXIT.ok;
+		}
+		case "uninstall": return uninstall(context, {
+			yes: values.yes ?? false,
+			purgeCache: values["purge-cache"] ?? false
+		});
+		default: return EXIT.usage;
+	}
+}
+function describeWhich(result) {
+	const where = result.kind === "own" ? "Node's own npm" : result.kind === "cached" ? "cached" : "to download";
+	const from = result.source === null ? "no project requirement" : `${result.source.field} in ${result.source.file}`;
+	const lines = [`npm ${result.version} (${where}): ${result.cliPath}`, `Source: ${from}`];
+	if (result.warning !== null) lines.push(`Warning: ${result.warning}`);
+	return lines.join("\n");
+}
+function reportError(error, context) {
+	if (isNpmVmError(error)) {
+		context.io.err(`npm-vm: ${error.message}`);
+		return error.exitCode;
+	}
+	context.io.err(`npm-vm: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+	return EXIT.problems;
+}
+/** The build injects the package version; running from source reads the manifest instead. */
+function readSelfVersion() {
+	return "0.1.0";
+}
+//#endregion
+//#region src/cli.ts
+process.exitCode = await run(process.argv.slice(2), {});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map