dsh-plugin-shop 0.7.4 → 0.8.0-beta.0

package/lib/index.js

@@ -1,16 +1,17 @@
 import { createRequire } from "node:module";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { loadOptionalPatches, readProfileManifest, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
-import { lt, minVersion, valid } from "semver";
+import { lt, minVersion, satisfies, valid, validRange } from "semver";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { gunzipSync } from "node:zlib";
-import { spawn } from "node:child_process";
-import { JSON_SCHEMA, Type, dump, load } from "js-yaml";
+import { spawn, spawnSync } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { DEFAULT_SCHEMA, JSON_SCHEMA, Type, dump, load } from "js-yaml";
 //#region src/own-version.ts
 /** The shop's own published version, read from the package.json that ships
 * next to this package — the RUNNING version, not the manifest's range
@@ -18,8 +19,27 @@ import { JSON_SCHEMA, Type, dump, load } from "js-yaml";
 * both the source tree (tests) and the bundled `lib/index.js` sit exactly
 * one level below the package root, so the same relative URL resolves in
 * both. */
+function ownManifest() {
+	return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+}
 function ownVersion() {
-	return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
+	return ownManifest().version;
+}
+/**
+* The peer ranges this build declares — the input to the load-time harness
+* self-check. Read from the same shipped manifest as `ownVersion`, so the
+* ranges checked are the ones this build was actually published with, never
+* a second copy that can drift from them.
+*
+* A non-string range is dropped rather than repaired: only what we can
+* compare against is worth a verdict.
+*/
+function ownPeerRanges() {
+	const declared = ownManifest().peerDependencies;
+	if (declared === null || typeof declared !== "object") return {};
+	const ranges = {};
+	for (const [spec, range] of Object.entries(declared)) if (typeof range === "string") ranges[spec] = range;
+	return ranges;
 }
 //#endregion
 //#region src/host/origin.ts
@@ -51,6 +71,39 @@ function resolveDataUrl(baseUrl, url) {
 	if (resolved.origin !== new URL(baseUrl).origin) throw new Error("catalog data url must be relative to the catalog base");
 	return resolved.href;
 }
+/** The largest catalog body this host reads into memory. */
+const MAX_BODY_BYTES = 67108864;
+/** Read a response body through a byte cap, converting transport failures. */
+async function readCappedBytes(response, label, maxBytes = MAX_BODY_BYTES) {
+	if (response.body === null) throw new TransportError(`${label} returned no body`);
+	const reader = response.body.getReader();
+	const chunks = [];
+	let bytes = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			bytes += value.byteLength;
+			if (bytes > maxBytes) {
+				try {
+					await reader.cancel();
+				} catch {}
+				throw new TransportError(`${label} exceeded the ${maxBytes}-byte cap`);
+			}
+			chunks.push(Buffer.from(value));
+		}
+	} catch (error) {
+		if (error instanceof TransportError) throw error;
+		throw new TransportError(`${label} body read failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks);
+}
+/** Read a capped response body as UTF-8 text. */
+async function readCappedText(response, label, maxBytes = MAX_BODY_BYTES) {
+	return (await readCappedBytes(response, label, maxBytes)).toString("utf8");
+}
 /** The transport this project has always used: a static `v1/` tree. */
 function httpOrigin(baseUrl, fetchImpl) {
 	const id = `http:${baseUrl}`;
@@ -65,21 +118,21 @@ function httpOrigin(baseUrl, fetchImpl) {
 				throw new TransportError(`catalog pointer fetch failed for ${id}: ${detail}`, { cause: error });
 			}
 			if (!response.ok) throw new TransportError(`catalog pointer returned ${response.status} for ${id}`);
-			const pointerText = await response.text();
+			const pointerText = await readCappedText(response, `catalog pointer fetch for ${id}`);
 			return {
 				id,
 				pointer: async () => pointerText,
-				file: async (url) => {
+				file: async (url, signal) => {
 					const resolved = resolveDataUrl(baseUrl, url);
 					let dataResponse;
 					try {
-						dataResponse = await fetchImpl(resolved);
+						dataResponse = await fetchImpl(resolved, signal === void 0 ? void 0 : { signal });
 					} catch (error) {
 						const detail = error instanceof Error ? error.message : String(error);
 						throw new TransportError(`catalog data fetch failed for ${id}: ${detail}`, { cause: error });
 					}
 					if (!dataResponse.ok) throw new TransportError(`catalog data returned ${dataResponse.status} for ${id}`);
-					return dataResponse.text();
+					return readCappedText(dataResponse, `catalog data fetch for ${id}`);
 				}
 			};
 		}
@@ -158,6 +211,10 @@ const latestSchema = z.object({
 });
 /** Where the published package keeps the catalog tree (design §2). */
 const PACKAGE_ROOT = "package/v1/";
+/** Maximum compressed package bytes read from a registry. */
+const MAX_PACKAGE_BYTES = 33554432;
+/** Maximum bytes allowed after gzip inflation. */
+const MAX_INFLATED_BYTES = MAX_BODY_BYTES;
 /** Verify tarball bytes against npm's own Subresource-Integrity string.
 * `dist.integrity` may carry several space-separated digests; npm publishes
 * one, and the first is the one we check. */
@@ -216,7 +273,7 @@ function npmOrigin(rawRegistryUrl, packageName, fetchImpl) {
 				throw new TransportError(`npm origin ${registryUrl} returned an unparsable manifest: ${detail}`, { cause: error });
 			}
 			let files = null;
-			const load = async () => {
+			const load = async (loadSignal) => {
 				if (files !== null) return files;
 				let tarballUrl;
 				try {
@@ -228,41 +285,38 @@ function npmOrigin(rawRegistryUrl, packageName, fetchImpl) {
 				if (tarballUrl.origin !== new URL(registryUrl).origin) throw new TransportError(`npm origin ${registryUrl}: dist.tarball host ${tarballUrl.origin} is not the registry's`);
 				let tarballResponse;
 				try {
-					tarballResponse = await fetchImpl(tarballUrl.href);
+					tarballResponse = await fetchImpl(tarballUrl.href, loadSignal === void 0 ? void 0 : { signal: loadSignal });
 				} catch (error) {
 					const detail = error instanceof Error ? error.message : String(error);
 					throw new TransportError(`npm origin ${registryUrl} tarball fetch failed: ${detail}`, { cause: error });
 				}
 				if (!tarballResponse.ok) throw new TransportError(`npm origin ${registryUrl} tarball returned ${tarballResponse.status}`);
-				let bytes;
-				try {
-					bytes = Buffer.from(await tarballResponse.arrayBuffer());
-				} catch (error) {
-					const detail = error instanceof Error ? error.message : String(error);
-					throw new TransportError(`npm origin ${registryUrl} tarball body read failed: ${detail}`, { cause: error });
-				}
+				const declaredLength = Number(tarballResponse.headers.get("content-length"));
+				if (Number.isFinite(declaredLength) && declaredLength > 33554432) throw new TransportError(`npm origin ${registryUrl} tarball exceeded the ${MAX_PACKAGE_BYTES}-byte cap`);
+				const bytes = await readCappedBytes(tarballResponse, `npm origin ${registryUrl} tarball`, MAX_PACKAGE_BYTES);
 				verifyIntegrity(bytes, manifest.dist.integrity, registryUrl);
 				let parsed;
 				try {
-					parsed = readTar(gunzipSync(bytes));
+					parsed = readTar(gunzipSync(bytes, { maxOutputLength: MAX_INFLATED_BYTES }));
 				} catch (error) {
 					const detail = error instanceof Error ? error.message : String(error);
+					if (error.code === "ERR_BUFFER_TOO_LARGE" || /larger than|too large/i.test(detail)) throw new TransportError(`npm origin ${registryUrl}: the tarball inflates past the ${MAX_INFLATED_BYTES}-byte cap; refusing to read it`, { cause: error });
 					throw new TransportError(`npm origin ${registryUrl} served an unparsable tarball: ${detail}`, { cause: error });
 				}
 				files = parsed;
 				return files;
 			};
-			const read = async (name) => {
-				const entry = (await load()).get(`${PACKAGE_ROOT}${name}`);
+			const read = async (name, readSignal) => {
+				const entry = (await load(readSignal)).get(`${PACKAGE_ROOT}${name}`);
 				if (entry === void 0) throw new TransportError(`npm origin ${registryUrl}: ${name} is not in the catalog package`);
 				return entry.toString("utf8");
 			};
 			return {
 				id,
 				pointer: async () => read("index.json"),
-				file: async (url) => {
+				file: async (url, fileSignal) => {
 					if (url.includes("/") || url.startsWith(".")) throw new Error(`npm origin ${registryUrl}: ${JSON.stringify(url)} must be a plain file name`);
-					return read(url);
+					return read(url, fileSignal);
 				}
 			};
 		}
@@ -318,6 +372,38 @@ function inCompletionOrder(promises) {
 		}
 	})();
 }
+//#endregion
+//#region src/shared/identity.ts
+/** The registry's uniqueness rule, shared with the presentation layer. */
+function identityKey(identity) {
+	return identity.source === "npm" ? `npm:${identity.name}` : `github:${identity.repo ?? identity.name}#${identity.subdir ?? ""}`;
+}
+/** A GitHub commit pin. */
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+/** A GitHub release tag accepted as the version/pin of a rescued entry. */
+const RELEASE_TAG = /^[A-Za-z0-9][A-Za-z0-9._+/-]{0,127}$/;
+/** `owner/slug`, lowercased, or null when this is not a repository reference. */
+const REPO = "([\\w.-]+)\\/([\\w.-]+?)";
+const GITHUB_SHORTHAND = new RegExp(`^github:${REPO}(?:[#&].*)?$`);
+const GITHUB_URL = new RegExp(`^(?:git\\+)?https?:\\/\\/(?:www\\.)?github\\.com\\/${REPO}(?:\\.git)?(?:[\\/?#].*)?$`);
+/**
+* Read the repository out of a profile dependency spec, or return null for
+* an npm range/spec that does not identify a GitHub repository.
+*/
+function parseRepoSpec(spec) {
+	const shorthand = GITHUB_SHORTHAND.exec(spec);
+	if (shorthand !== null && shorthand[1] !== void 0 && shorthand[2] !== void 0) return `${shorthand[1]}/${shorthand[2]}`.toLowerCase();
+	const url = GITHUB_URL.exec(spec);
+	if (url !== null && url[1] !== void 0 && url[2] !== void 0) return `${url[1]}/${url[2]}`.toLowerCase();
+	return null;
+}
+/** Whether an installed dependency spec names this catalog entry. */
+function installedSpecMatches(entry, spec) {
+	const repo = parseRepoSpec(spec);
+	if (entry.source === "npm") return repo === null;
+	if (entry.repo === void 0) return false;
+	return repo === entry.repo.toLowerCase();
+}
 /** A cached catalog younger than this is served without touching the network. */
 const FRESH_MS = 3e5;
 /** How long a probe may take before the race gives up on that origin. Long
@@ -332,27 +418,35 @@ const PROBE_TIMEOUT_MS = 1e4;
 * exists to prevent. Generous against every measured npm origin (12.53 MB/s
 * mirror -> 0.12 s for 1.5 MB; npmjs direct 1.99 MB/s -> 0.75 s). */
 const COMMIT_TIMEOUT_MS = 3e4;
-/** Reject with a TransportError if `work` outlives `COMMIT_TIMEOUT_MS`. The
-* underlying fetch is left to finish or fail on its own and its result is
-* discarded: aborting it would need a signal threaded through OriginHandle,
-* and a stalled origin we have already abandoned costs nothing but its own
-* socket. */
-async function withCommitTimeout(work, id) {
+/** Run one committed-origin read under a deadline and abort it on expiry. */
+async function withCommitBudget(id, what, start) {
+	const controller = new AbortController();
 	let timer;
 	try {
-		return await Promise.race([work, new Promise((_resolve, reject) => {
-			timer = setTimeout(() => reject(new TransportError(`${id} did not produce a pointer within ${COMMIT_TIMEOUT_MS} ms`)), COMMIT_TIMEOUT_MS);
+		return await Promise.race([start(controller.signal), new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				const expired = new TransportError(`${id} did not ${what} within ${COMMIT_TIMEOUT_MS} ms`);
+				controller.abort(expired);
+				reject(expired);
+			}, COMMIT_TIMEOUT_MS);
 		})]);
 	} finally {
 		clearTimeout(timer);
 	}
 }
+/** npm's package-name grammar. The value becomes half of an install spec, so
+* aliases and shell punctuation must not reach the CLI. */
+const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/** Canonical SemVer 2.0.0, including legal prerelease/build metadata. */
+const NPM_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
+/** The repository binding used to build a GitHub install spec. */
+const REPO_FULL_NAME = /^[\w.-]+\/[\w.-]+$/;
 /** Records when the loader itself wrote the cache; the pointer's `builtAt` is
 * the catalog's build time, not the cache's fetch time. */
 const META_FILE = "index.meta.json";
 const entrySchema = z.object({
-	name: z.string(),
-	version: z.string(),
+	name: z.string().min(1).max(214).regex(/^[^\u0000-\u001f\u007f]+$/, "entry name carries a control character"),
+	version: z.string().min(1).max(256),
 	integrity: z.string().nullable(),
 	publishedAt: z.string().nullable(),
 	repository: z.string().nullable(),
@@ -388,15 +482,39 @@ const entrySchema = z.object({
 		capabilities: z.array(z.string())
 	}).optional(),
 	source: z.enum(["npm", "github"]).default("npm"),
-	repo: z.string().optional(),
+	repo: z.string().regex(REPO_FULL_NAME, "repo must be owner/slug").optional(),
 	subdir: z.string().regex(/^(?!.*(^|\/)\.\.?(\/|$))[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/).optional(),
 	added: z.string().optional(),
 	tarball: z.object({
 		url: z.string(),
-		sha256: z.string()
+		sha256: z.string().regex(/^[0-9a-f]{64}$/)
 	}).optional(),
 	publisher: z.string().optional(),
 	peers: z.array(z.string()).optional()
+}).superRefine((entry, ctx) => {
+	if (entry.source === "npm") {
+		if (!NPM_NAME.test(entry.name)) ctx.addIssue({
+			code: "custom",
+			path: ["name"],
+			message: `npm entry name ${JSON.stringify(entry.name)} is outside npm package-name grammar`
+		});
+		if (!NPM_VERSION.test(entry.version)) ctx.addIssue({
+			code: "custom",
+			path: ["version"],
+			message: `npm entry version ${JSON.stringify(entry.version)} is not a plain semver version`
+		});
+		return;
+	}
+	if (entry.repo === void 0) ctx.addIssue({
+		code: "custom",
+		path: ["repo"],
+		message: "a github entry must carry its repo — it is the entry's identity and the spec is built from it"
+	});
+	if (!COMMIT_SHA.test(entry.version) && !RELEASE_TAG.test(entry.version)) ctx.addIssue({
+		code: "custom",
+		path: ["version"],
+		message: `github entry version ${JSON.stringify(entry.version)} is neither a 40-character commit sha nor a release tag`
+	});
 });
 const dataSchema = z.object({
 	schemaVersion: z.number(),
@@ -429,6 +547,7 @@ function validateEntryCoherence(entries) {
 			throw new Error(`catalog entry ${entry.name}: tarball url is unparseable`);
 		}
 		if (parsed.protocol !== "https:" || parsed.hostname !== "github.com") throw new Error(`catalog entry ${entry.name}: tarball url must be https on github.com`);
+		if (parsed.search !== "" || parsed.hash !== "") throw new Error(`catalog entry ${entry.name}: tarball url must carry no query or fragment`);
 		const segments = parsed.pathname.split("/").filter((s) => s !== "");
 		if (`${segments[0] ?? ""}/${segments[1] ?? ""}`.toLowerCase() !== entry.repo.toLowerCase() || segments[2] !== "releases") throw new Error(`catalog entry ${entry.name}: tarball url is not a release of ${entry.repo}`);
 	}
@@ -460,7 +579,7 @@ function parseStarsText(text) {
 	try {
 		const parsed = JSON.parse(text);
 		if (typeof parsed.stars !== "object" || parsed.stars === null) return {};
-		const out = {};
+		const out = Object.create(null);
 		for (const [key, value] of Object.entries(parsed.stars)) if (typeof value === "number") out[key] = value;
 		return out;
 	} catch {
@@ -553,7 +672,7 @@ async function loadCatalog(options) {
 			continue;
 		}
 		try {
-			pointerText = await withCommitTimeout(settled.value.pointer(), settled.value.id);
+			pointerText = await withCommitBudget(settled.value.id, "produce a pointer", () => settled.value.pointer());
 			handle = settled.value;
 			break;
 		} catch (error) {
@@ -566,7 +685,7 @@ async function loadCatalog(options) {
 	if (pointer.schemaVersion > 6) throw new Error(`catalog schemaVersion ${pointer.schemaVersion} is newer than this build supports (6)`);
 	let dataText;
 	try {
-		dataText = await handle.file(pointer.plugins.url);
+		dataText = await withCommitBudget(handle.id, `serve ${pointer.plugins.url}`, (signal) => handle.file(pointer.plugins.url, signal));
 	} catch (error) {
 		if (!(error instanceof TransportError)) throw error;
 		return cachedOrThrow(error);
@@ -577,13 +696,16 @@ async function loadCatalog(options) {
 	if (data.schemaVersion > 6) throw new Error(`catalog schemaVersion ${data.schemaVersion} is newer than this build supports (6)`);
 	validateEntryCoherence(data.plugins);
 	let stars = {};
-	if (pointer.stars !== void 0) try {
-		const starsText = await handle.file(pointer.stars.url);
-		if (createHash("sha256").update(starsText).digest("hex") === pointer.stars.sha256) {
-			stars = parseStarsText(starsText);
-			fsImpl.write(join(cacheDir, basename(pointer.stars.url)), starsText);
-		}
-	} catch {}
+	if (pointer.stars !== void 0) {
+		const sidecar = pointer.stars;
+		try {
+			const starsText = await withCommitBudget(handle.id, `serve ${sidecar.url}`, (signal) => handle.file(sidecar.url, signal));
+			if (createHash("sha256").update(starsText).digest("hex") === sidecar.sha256) {
+				stars = parseStarsText(starsText);
+				fsImpl.write(join(cacheDir, basename(sidecar.url)), starsText);
+			}
+		} catch {}
+	}
 	const snapshot = {
 		schemaVersion: pointer.schemaVersion,
 		builtAt: pointer.builtAt,
@@ -672,11 +794,7 @@ function npmrcRegistry(readFile, home) {
 }
 //#endregion
 //#region src/host/install.ts
-/**
-* Decide whether one install request may proceed, against the Host's own
-* snapshot (§5.3). The browser sends a name; nothing the browser says about
-* the package is trusted.
-*/
+/** Decide whether an install request may proceed and return the resolved row. */
 function validateInstall(snapshot, args) {
 	const denied = snapshot.denied.find((d) => d.name === args.name);
 	if (denied !== void 0) return {
@@ -684,7 +802,29 @@ function validateInstall(snapshot, args) {
 		code: "denied",
 		detail: `dsh-plugin-shop: ${args.name} is denied: ${denied.detail}`
 	};
-	const entry = snapshot.entries.find((e) => e.name === args.name);
+	let entry;
+	if (args.source === void 0) {
+		const named = snapshot.entries.filter((e) => e.name === args.name);
+		if (named.length > 1) return {
+			ok: false,
+			code: "ambiguous-identity",
+			detail: `dsh-plugin-shop: the catalog holds ${named.length} entries named ${args.name}, and this request does not say which one; refresh the shop and try again`
+		};
+		entry = named[0];
+	} else {
+		const wanted = identityKey({
+			source: args.source,
+			name: args.name,
+			repo: args.repo,
+			subdir: args.subdir
+		});
+		entry = snapshot.entries.find((candidate) => identityKey(candidate) === wanted);
+		if (entry === void 0) return {
+			ok: false,
+			code: "not-in-catalog",
+			detail: `dsh-plugin-shop: ${wanted} is not in the catalog`
+		};
+	}
 	if (entry === void 0) return {
 		ok: false,
 		code: "not-in-catalog",
@@ -700,7 +840,10 @@ function validateInstall(snapshot, args) {
 		code: "needs-acknowledgement",
 		detail: entry.tier === "verified-stale" ? `dsh-plugin-shop: ${args.name} is verified-stale: a newer version than the review is current and has not been reviewed; acknowledgement is required` : `dsh-plugin-shop: ${args.name} is ${entry.tier}-tier and has not been reviewed; acknowledgement is required`
 	};
-	return { ok: true };
+	return {
+		ok: true,
+		entry
+	};
 }
 //#endregion
 //#region src/host/dsh-cli.ts
@@ -817,6 +960,11 @@ function resolveDshScript(fs, options) {
 * post-exit manifest confirmation. */
 const MAX_LOG_LINES = 200;
 const MAX_LOG_BYTES = 65536;
+/** Bound one dsh command so a stalled install cannot hold the profile queue
+* forever. Tests can pass a shorter value; production stays generous. */
+const INSTALL_TIMEOUT_MS = Number(process.env.DSH_SHOP_INSTALL_TIMEOUT_MS) || 9e5;
+/** Grace period for output already buffered after the child exits. */
+const PIPE_DRAIN_MS = 500;
 const profileQueues = /* @__PURE__ */ new Map();
 function chain(profile, task) {
 	const next = (profileQueues.get(profile) ?? Promise.resolve()).then(task, task);
@@ -909,6 +1057,54 @@ function spawnFailureDetail(code, message, dshBin, platform) {
 	if (code === "ENOENT") return "dsh not found on PATH — install the dsh CLI to manage profile plugins";
 	return `dsh spawn failed: ${message}`;
 }
+/** The failure detail for a command stopped by the shop's deadline. */
+function installTimeoutDetail(profile, timeoutMs) {
+	return `dsh-plugin-shop: the command did not finish within ${Math.max(1, Math.round(timeoutMs / 1e3))}s and was stopped. Run it yourself to see what it is waiting on: dsh plugin --profile ${profile} install`;
+}
+const nodeKills = {
+	killGroup: (pid) => process.kill(-pid, "SIGKILL"),
+	killPid: (pid) => process.kill(pid, "SIGKILL"),
+	taskkill: (pid) => {
+		spawnSync("taskkill", [
+			"/PID",
+			String(pid),
+			"/T",
+			"/F"
+		], { stdio: "ignore" });
+	}
+};
+/** Kill a child and its descendants (process group on POSIX, taskkill tree on Windows). */
+function killTree(pid, platform, kills = nodeKills) {
+	if (pid === void 0) return;
+	if (platform === "win32") {
+		kills.taskkill(pid);
+		return;
+	}
+	try {
+		kills.killGroup(pid);
+	} catch {
+		try {
+			kills.killPid(pid);
+		} catch {}
+	}
+}
+function lineSink(emit) {
+	const decoder = new StringDecoder("utf8");
+	let pending = "";
+	return {
+		write(chunk) {
+			pending += decoder.write(chunk);
+			const parts = pending.split(/\r?\n/);
+			pending = parts.pop() ?? "";
+			for (const line of parts) if (line !== "") emit(line);
+		},
+		flush() {
+			pending += decoder.end();
+			if (pending !== "") emit(pending);
+			pending = "";
+		}
+	};
+}
 /** Read-only filesystem seam for the CLI lookup; the same shape as `pinFs`. */
 const nodeFs$1 = {
 	exists: (path) => existsSync(path),
@@ -926,6 +1122,12 @@ function dshScript() {
 	});
 	return cachedScript;
 }
+/** Shell punctuation that must never reach the downstream CLI as an operand.
+* The downstream dsh invokes pnpm with shell mode on Windows, where these
+* characters alter the command line. `&` is intentionally allowed here: the
+* legitimate monorepo spec uses it as `&path:<subdir>`, and catalog.ts
+* validates each component before it reaches this layer. */
+const UNSAFE_TARGET = /[\s"'`|<>^$();\\{}]|[\u0000-\u001f\u007f]/;
 /** Run one `dsh plugin --profile <profile> <verb> <target>` and track it.
 * Never rolls back; a failure surfaces stderr verbatim plus the recovery hint
 * (§10). The shop never passes build-script flags: `allowBuilds` stays the
@@ -941,9 +1143,10 @@ function dshScript() {
 * must settle before it. A throwing callback never fails the install — the
 * package IS installed; it reports `done` with the restart fallback. */
 function spawnPluginCli(options) {
-	const { profile, argv, dshBin, env, confirm, afterDone, onStatus } = options;
+	const { profile, argv, dshBin, env, confirm, afterDone, onStatus, timeoutMs = INSTALL_TIMEOUT_MS } = options;
 	const target = argv[1];
 	if (target === void 0 || target.startsWith("-")) throw new Error(`dsh-plugin-shop: refusing to spawn with a flag-like operand: ${target ?? "(none)"}`);
+	if (UNSAFE_TARGET.test(target)) throw new Error(`dsh-plugin-shop: refusing to spawn with an unsafe operand: ${JSON.stringify(target)}`);
 	const installId = randomUUID();
 	const log = [];
 	let logBytes = 0;
@@ -961,6 +1164,7 @@ function spawnPluginCli(options) {
 		...detail !== void 0 ? { detail } : {}
 	});
 	const append = (line) => {
+		if (state !== "running") return;
 		log.push(line);
 		logBytes += Buffer.byteLength(line);
 		while ((log.length > MAX_LOG_LINES || logBytes > MAX_LOG_BYTES) && log.length > 1) {
@@ -999,24 +1203,33 @@ function spawnPluginCli(options) {
 						"pipe",
 						"pipe"
 					],
-					env: env ?? process.env
+					env: env ?? process.env,
+					detached: process.platform !== "win32"
 				});
 			} catch (error) {
 				resolve(failToStart(error));
 				return;
 			}
-			child.stdout.on("data", (chunk) => {
-				for (const line of chunk.toString().split(/\r?\n/)) if (line !== "") append(line);
-			});
-			child.stderr.on("data", (chunk) => {
-				for (const line of chunk.toString().split(/\r?\n/)) if (line !== "") append(line);
-			});
-			child.on("error", (error) => {
-				resolve(failToStart(error));
-			});
-			child.on("close", async (exitCode) => {
+			let exited = false;
+			let closed = false;
+			let exitCode = null;
+			let timedOut = false;
+			let drainTimer;
+			let deadlineTimer;
+			const outLines = lineSink(append);
+			const errLines = lineSink(append);
+			const settle = async () => {
 				if (state !== "running") return;
-				if (exitCode === 0) {
+				clearTimeout(drainTimer);
+				clearTimeout(deadlineTimer);
+				outLines.flush();
+				errLines.flush();
+				child.stdout.destroy();
+				child.stderr.destroy();
+				if (timedOut) {
+					state = "failed";
+					detail = installTimeoutDetail(profile, timeoutMs);
+				} else if (exitCode === 0) {
 					const confirmDetail = confirm?.(env?.DSH_HOME);
 					if (confirmDetail != null) {
 						state = "failed";
@@ -1038,7 +1251,41 @@ function spawnPluginCli(options) {
 				}
 				onStatus?.(status());
 				resolve(status());
+			};
+			const drainThenSettle = () => {
+				clearTimeout(drainTimer);
+				drainTimer = setTimeout(() => {
+					settle();
+				}, PIPE_DRAIN_MS);
+			};
+			child.stdout.on("data", (chunk) => {
+				outLines.write(chunk);
+			});
+			child.stderr.on("data", (chunk) => {
+				errLines.write(chunk);
+			});
+			child.on("error", (error) => {
+				if (state !== "running") return;
+				clearTimeout(drainTimer);
+				clearTimeout(deadlineTimer);
+				resolve(failToStart(error));
+			});
+			child.on("exit", (code) => {
+				exited = true;
+				exitCode = code;
+				if (closed) settle();
+				else drainThenSettle();
 			});
+			child.on("close", () => {
+				closed = true;
+				if (exited) settle();
+			});
+			deadlineTimer = setTimeout(() => {
+				if (state !== "running") return;
+				timedOut = true;
+				killTree(child.pid, process.platform);
+				drainThenSettle();
+			}, timeoutMs);
 		}))
 	};
 }
@@ -1049,7 +1296,7 @@ function spawnPluginCli(options) {
 * is given, the terminal `done` waits for it to settle (§D hot mount).
 */
 function startInstall(options) {
-	const { profile, spec, dshBin = "dsh", env, expectedName, afterDone, onStatus } = options;
+	const { profile, spec, dshBin = "dsh", env, expectedName, afterDone, onStatus, timeoutMs } = options;
 	return spawnPluginCli({
 		profile,
 		argv: ["add", spec],
@@ -1057,7 +1304,8 @@ function startInstall(options) {
 		env,
 		confirm: expectedName !== void 0 ? (home) => confirmBundleActivation(profile, home, expectedName) : void 0,
 		afterDone,
-		onStatus
+		onStatus,
+		timeoutMs
 	});
 }
 /**
@@ -1068,7 +1316,7 @@ function startInstall(options) {
 * waits for it to settle (§D hot mount).
 */
 function startUninstall(options) {
-	const { profile, name, dshBin = "dsh", env, expectedName, afterDone, onStatus } = options;
+	const { profile, name, dshBin = "dsh", env, expectedName, afterDone, onStatus, timeoutMs } = options;
 	return spawnPluginCli({
 		profile,
 		argv: ["remove", name],
@@ -1076,7 +1324,8 @@ function startUninstall(options) {
 		env,
 		confirm: expectedName !== void 0 ? (home) => confirmBundleRemoval(profile, home, expectedName) : void 0,
 		afterDone,
-		onStatus
+		onStatus,
+		timeoutMs
 	});
 }
 //#endregion
@@ -1181,7 +1430,13 @@ function parseSimplePatch(patchText) {
 * the output is itself a simple patch (round-trips through
 * parseSimplePatch). */
 function renderRows(rows, prefix) {
-	return rows.map((row) => `- id: ${prefix}${row.id}\n  name: ${row.name}`).join("\n") + "\n";
+	return dump(rows.map((row) => ({
+		id: `${prefix}${row.id}`,
+		name: row.name
+	})), {
+		noRefs: true,
+		lineWidth: -1
+	});
 }
 /** The next free `hot-<n>` number: one past the highest existing file, or 1
 * when the directory does not exist yet (the write recreates it). */
@@ -1246,9 +1501,18 @@ async function hotMount(ctx, profileDir, packageName, deps = {}) {
 	const { fs = nodeFs, dir = join(profileDir, HOT_DIR), timeoutMs = Number(process.env.DSH_SHOP_HOT_MOUNT_TIMEOUT_MS) || 1e4, now = Date.now } = deps;
 	const packageDir = join(profileDir, "node_modules", packageName);
 	const dsh = readPkgDsh(fs, packageDir);
+	const patchFile = resolve(packageDir, dsh?.patch ?? "cordis.patch.yml");
+	const inside = relative(packageDir, patchFile);
+	if (inside === "" || inside.startsWith("..") || isAbsolute(inside)) {
+		ctx.logger?.warn(`hot-mount ${packageName}: the declared bundle patch is outside the package directory — restart will activate it`);
+		return {
+			ok: false,
+			reason: "no-patch"
+		};
+	}
 	let patchText;
 	try {
-		patchText = fs.read(join(packageDir, dsh?.patch ?? "cordis.patch.yml"));
+		patchText = fs.read(patchFile);
 	} catch {
 		ctx.logger?.warn(`hot-mount ${packageName}: no patch file to mount — restart will activate it`);
 		return {
@@ -1382,17 +1646,41 @@ function cleanHotDir(profileDir) {
 * function has already returned and the caller has committed — so the gateway
 * refuses on Windows before reaching here rather than exiting into nothing
 * (index.ts `restartPlatformSupported`). */
+/**
+* Resolve the command line that re-runs this process.
+*
+* A bare `dsh` from PATH is not necessarily the process serving the current
+* port: a dsh launched through `node`, `npx`, or `pnpm dlx` carries its own
+* script and `execArgv`. Reconstructing that exact node invocation preserves
+* the entry point and runtime flags. An explicitly named binary remains an
+* explicit choice and is passed through unchanged.
+*/
+function restartCommand(options) {
+	const { dshBin, argv, execPath, execArgv, script } = options;
+	if (dshBin === "dsh" && script !== void 0) return {
+		command: execPath,
+		args: [
+			...execArgv,
+			script,
+			...argv
+		]
+	};
+	return {
+		command: dshBin,
+		args: [...argv]
+	};
+}
 function startRestart(options) {
-	const { dshBin, argv, parentPid, logFile, env } = options;
+	const { command, args, parentPid, logFile, env } = options;
 	const logFd = openSync(logFile, "a");
 	try {
-		spawn("sh", [
+		const helper = spawn("sh", [
 			"-c",
 			"while kill -0 \"$1\" 2>/dev/null; do sleep 0.2; done; shift; exec \"$@\"",
 			"sh",
 			String(parentPid),
-			dshBin,
-			...argv
+			command,
+			...args
 		], {
 			stdio: [
 				"ignore",
@@ -1401,7 +1689,13 @@ function startRestart(options) {
 			],
 			env: env ?? process.env,
 			detached: true
-		}).unref();
+		});
+		helper.on("error", (error) => {
+			try {
+				appendFileSync(logFile, `dsh-plugin-shop: the restart helper could not start: ${error.message}\n`);
+			} catch {}
+		});
+		helper.unref();
 	} finally {
 		closeSync(logFd);
 	}
@@ -1415,12 +1709,22 @@ function startRestart(options) {
 * harvested into its own catalog. */
 /** The npm package the shop itself is published as. */
 const SHOP_PACKAGE = "dsh-plugin-shop";
-/** Fetch the shop's `latest` dist-tag, or `null` when the registry cannot
-* answer (network failure, unexpected payload — anything). The caller
-* renders `null` as "no update check", never as a failure. */
-async function fetchLatestVersion(fetchFn = fetch) {
+/** The registry that always gets asked, last. */
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+/** How long one registry gets to answer. `shop/version` is warmed at every
+* web boot, so a silent socket must not hold the boot indefinitely. */
+const VERSION_CHECK_TIMEOUT_MS = 5e3;
+/** Ask one registry. Any failure — network, non-2xx, unexpected payload,
+* deadline — is the same outcome: no answer from this registry. */
+async function askRegistry(fetchFn, registry, timeoutMs) {
+	const url = `${registry}${SHOP_PACKAGE}`;
+	const signal = AbortSignal.timeout(timeoutMs);
 	try {
-		const response = await fetchFn(`https://registry.npmjs.org/${SHOP_PACKAGE}`);
+		const response = await Promise.race([fetchFn(url, { signal }), new Promise((_resolve, reject) => {
+			signal.addEventListener("abort", () => {
+				reject(/* @__PURE__ */ new Error(`the version check did not answer within ${timeoutMs} ms`));
+			}, { once: true });
+		})]);
 		if (!response.ok) return null;
 		const latest = (await response.json())["dist-tags"]?.latest;
 		return typeof latest === "string" ? latest : null;
@@ -1428,6 +1732,24 @@ async function fetchLatestVersion(fetchFn = fetch) {
 		return null;
 	}
 }
+/**
+* Fetch the shop's `latest` dist-tag, or `null` when no registry can answer.
+* The user's own registry is tried first when known; npmjs is always the
+* fallback so a mirror that lags cannot hide a release.
+*/
+async function fetchLatestVersion(fetchFn = fetch, options = {}) {
+	const { registry = null, timeoutMs = VERSION_CHECK_TIMEOUT_MS } = options;
+	const asked = /* @__PURE__ */ new Set();
+	const registries = registry === null ? [DEFAULT_REGISTRY] : [registry, DEFAULT_REGISTRY];
+	for (const base of registries) {
+		const normalized = base.endsWith("/") ? base : `${base}/`;
+		if (asked.has(normalized)) continue;
+		asked.add(normalized);
+		const latest = await askRegistry(fetchFn, normalized, timeoutMs);
+		if (latest !== null) return latest;
+	}
+	return null;
+}
 //#endregion
 //#region src/host/supervisor.ts
 function detectSupervisor(env, proc) {
@@ -1435,14 +1757,25 @@ function detectSupervisor(env, proc) {
 }
 //#endregion
 //#region src/host/repo-pins.ts
+/**
+* The Host's memory of which commit it installed for each github entry.
+*
+* pnpm writes the manifest dependency as `github:owner/slug` — no commit —
+* and the resolved commit lives only in the lockfile. The shop records the
+* commit it pinned at install time in its own cache so `installed()` can
+* report `outdated` honestly without parsing pnpm's lockfile. The profile
+* manifest remains the source of truth for *presence*: a pin whose bundle
+* is not a manifest dependency is a leftover from a failed install and is
+* never reported.
+*/
 /** Read the pins file; any irregularity degrades to an empty record. */
 function readRepoPins(fs, path) {
 	if (!fs.exists(path)) return {};
 	try {
 		const parsed = JSON.parse(fs.read(path));
 		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
-		const out = {};
-		for (const [name, commit] of Object.entries(parsed)) if (typeof commit === "string" && /^[0-9a-f]{40}$/.test(commit)) out[name] = commit;
+		const out = Object.create(null);
+		for (const [name, pin] of Object.entries(parsed)) if (typeof pin === "string" && (COMMIT_SHA.test(pin) || RELEASE_TAG.test(pin))) out[name] = pin;
 		return out;
 	} catch {
 		return {};
@@ -1455,6 +1788,18 @@ function writeRepoPins(fs, path, pins) {
 //#endregion
 //#region src/host/profile.ts
 /** Profile directory discovery and user-layer writes (§8: hot enable/disable). */
+function isJsExpr(value) {
+	return typeof value === "object" && value !== null && typeof value.__jsExpr === "string";
+}
+const JS_EXPR_TYPE = new Type("tag:yaml.org,2002:js", {
+	kind: "scalar",
+	resolve: () => true,
+	construct: (data) => ({ __jsExpr: data }),
+	predicate: isJsExpr,
+	represent: (value) => value.__jsExpr
+});
+/** js-yaml's default schema plus the user-layer `!!js` round trip. */
+const USER_LAYER_SCHEMA = DEFAULT_SCHEMA.extend([JS_EXPR_TYPE]);
 /**
 * Find the profile directory that owns `startPath`.
 *
@@ -1523,7 +1868,10 @@ function setUserLayerRows(options) {
 		disabled: true
 	}))];
 	const tmp = `${file}.tmp`;
-	writeFileSync(tmp, dump(next, { noRefs: true }));
+	writeFileSync(tmp, dump(next, {
+		noRefs: true,
+		schema: USER_LAYER_SCHEMA
+	}));
 	renameSync(tmp, file);
 }
 /**
@@ -1618,7 +1966,9 @@ function ownsEntryId(owned, entryId) {
 //#endregion
 //#region src/host/peers.ts
 /** Harness compatibility: which declared peers the running installation does
-* not provide (design 2026-09-01-harness-compatibility). */
+* not provide (design 2026-09-01-harness-compatibility), and — for the
+* shop's OWN declared peers — which ones it provides at a version outside
+* the declared range. */
 /**
 * The production resolver: the same question the harness's own
 * ClientModuleRegistry asks, through a require anchored at the profile. Asking
@@ -1632,7 +1982,9 @@ function nodeResolver(baseUrl) {
 			require.resolve(`${spec}/package.json`);
 			return true;
 		} catch (error) {
-			if (error.code === "MODULE_NOT_FOUND") return false;
+			const code = error.code;
+			if (code === "MODULE_NOT_FOUND") return false;
+			if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED") return true;
 			throw error;
 		}
 	};
@@ -1669,10 +2021,105 @@ function incompatibilityMap(entries, resolve) {
 			}
 			if (!present) missing.push(spec);
 		}
-		if (usable && missing.length > 0) out[entry.name] = missing;
+		if (usable && missing.length > 0) out[identityKey(entry)] = missing;
 	}
 	return out;
 }
+/**
+* The production resolver: `nodeResolver`'s own resolution, kept this time
+* instead of collapsed to a boolean. Anything that leaves no version to read
+* answers null — a peer that is absent, one that restricts `./package.json`
+* in its exports, an unreadable or malformed manifest, a manifest with no
+* `version`. Absence is deliberately NOT reported as a version violation:
+* `incompatibilityMap` is what covers a missing peer.
+*/
+function nodeVersionResolver(baseUrl) {
+	const require = createRequire(baseUrl);
+	return (spec) => {
+		let manifestPath;
+		try {
+			manifestPath = require.resolve(`${spec}/package.json`);
+		} catch {
+			return null;
+		}
+		try {
+			const version = JSON.parse(readFileSync(manifestPath, "utf8")).version;
+			return typeof version === "string" ? version : null;
+		} catch {
+			return null;
+		}
+	};
+}
+/**
+* The declared peers whose provided version is outside the declared range,
+* ordered by peer name. Pure: the module graph arrives through `resolve`.
+*
+* `includePrerelease` is load-bearing, not a convenience. The harness ships
+* nothing but `-rc` versions, so under strict semver `^0.1.1-rc.2` excludes
+* `0.1.2-rc.1` — the version that is installed and works — and every future
+* rc bump would raise a false alarm. With it on, the range still excludes an
+* older prerelease (`0.1.1-rc.1`) and a minor- or major-line move
+* (`0.2.0-rc.1`, `1.0.0`), which are the moves that actually break a plugin
+* path. Discrimination on both sides is the whole point: one false warning
+* teaches a reader to ignore every warning.
+*
+* Anything unreadable yields NO verdict for that peer and never a violation:
+* a resolver that answers null or throws, a found version that is not
+* semver, a declared range semver cannot parse. The other peers are still
+* judged.
+*/
+function peerVersionMismatches(ranges, resolve) {
+	const mismatches = [];
+	for (const spec of Object.keys(ranges).sort()) {
+		const range = ranges[spec];
+		if (range === void 0 || validRange(range) === null) continue;
+		let found;
+		try {
+			found = resolve(spec);
+		} catch {
+			continue;
+		}
+		if (found === null || valid(found) === null) continue;
+		if (satisfies(found, range, { includePrerelease: true })) continue;
+		mismatches.push({
+			spec,
+			range,
+			found
+		});
+	}
+	return mismatches;
+}
+/**
+* The load-time message for a set of mismatches, or null when there is
+* nothing to say. Every mismatch is named with its declared range and the
+* version found, in ONE message: the reader needs the whole picture in the
+* line they will scroll past, and the message says the shop still loads
+* because refusing to load would cost them the shop over a diagnostic.
+*/
+function peerVersionWarning(mismatches) {
+	if (mismatches.length === 0) return null;
+	return `dsh-plugin-shop: the harness does not provide the peer versions this shop declares — ${mismatches.map(({ spec, range, found }) => `${spec} ${range}, found ${found}`).join("; ")}. The shop still loads; if a path misbehaves, check this first.`;
+}
+/**
+* A self-check that warns AT MOST ONCE, however many times it is called.
+* The guard is what keeps a diagnostic a diagnostic: a message repeated per
+* call is noise a reader learns to skip, and the shop's load path is not the
+* only place that could reasonably ask this question.
+*
+* It never throws. A check that could fail a load would be worse than the
+* mismatch it reports — the user would lose the whole shop over a warning.
+*/
+function createPeerVersionCheck(deps) {
+	let spoken = false;
+	return () => {
+		if (spoken) return;
+		spoken = true;
+		try {
+			const message = peerVersionWarning(peerVersionMismatches(deps.ranges, deps.resolve));
+			if (message !== null) deps.warn(message);
+		} catch {}
+	};
+}
 //#endregion
 //#region src/host/index.ts
 /** ShopGateway: the Host half of dsh-plugin-shop (§5.1). */
@@ -1905,6 +2352,8 @@ let ShopGateway = (() => {
 		/** The argv `shop/restart` re-spawns: the real process argv minus node and
 		* the CLI script path, or a test-provided substitute. */
 		restartArgv;
+		/** The script the restart re-runs — this process's own entry. */
+		restartScript;
 		/** The exit the restart calls once the response is out; `process.exit` in
 		* production, a spy in tests. */
 		exit;
@@ -1934,9 +2383,14 @@ let ShopGateway = (() => {
 		/** The install gate runs against the last loaded snapshot, never a fresh
 		* fetch per request (§7.2: the Host's cached snapshot is the truth). */
 		lastSnapshot = null;
+		/** A cold-cache catalog load shared by concurrent RPC calls. */
+		inFlightLoad = null;
 		/** The origin list built for the last-seen `catalogUrl`, memoised so the
 		* user's npmrc is read at most once per gateway (see `originsFor`). */
 		originCache = null;
+		/** The user's own `registry=` from `~/.npmrc`, read at most once per
+		* gateway. A wrapper distinguishes a genuine `null` from an unread value. */
+		npmRegistryCache = null;
 		/** The incompatibility map already computed for `lastSnapshot`, keyed by
 		* that snapshot's own object identity. Design §3 asks for the verdict
 		* once per loaded snapshot, not once per RPC call: `loadCatalog` serves
@@ -1961,10 +2415,11 @@ let ShopGateway = (() => {
 			this.loaderEntriesInjected = options.loaderEntries;
 			this.dshBin = options.dshBin ?? "dsh";
 			this.restartArgv = options.restartArgv ?? process.argv.slice(2);
+			this.restartScript = options.restartScript ?? process.argv[1];
 			this.exit = options.exit ?? ((code) => process.exit(code));
 			this.restartExitDelayMs = options.restartExitDelayMs ?? ShopGateway.RESTART_EXIT_DELAY_MS;
 			this.restartParentPid = options.restartParentPid ?? process.pid;
-			this.latestVersion = options.fetchLatestVersion ?? (() => fetchLatestVersion());
+			this.latestVersion = options.fetchLatestVersion ?? (() => fetchLatestVersion(fetch, { registry: this.npmRegistry() }));
 			this.pinFs = options.pinFs ?? {
 				exists: (path) => existsSync(path),
 				read: (path) => readFileSync(path, "utf8"),
@@ -1981,6 +2436,26 @@ let ShopGateway = (() => {
 			try {
 				cleanHotDir(this.profileDirResolved());
 			} catch {}
+			this.checkPeerVersions();
+		}
+		/**
+		* Warn once, at load, about any declared peer the harness provides outside
+		* its declared range. Advisory by construction: it cannot throw, and it
+		* never refuses the load — losing the whole shop is a worse outcome than
+		* running against a harness that moved.
+		*/
+		checkPeerVersions() {
+			try {
+				createPeerVersionCheck({
+					ranges: this.options.peerRanges ?? ownPeerRanges(),
+					resolve: this.options.resolvePeerVersion ?? nodeVersionResolver(pathToFileURL(join(this.profileDirResolved(), "cordis.yml")).href),
+					warn: (message) => {
+						const logger = this.ctx.logger;
+						if (logger === void 0) console.warn(message);
+						else logger.warn(message);
+					}
+				})();
+			} catch {}
 		}
 		/** The pins file lives in the shop's own cache, next to the catalog cache. */
 		pinsPath() {
@@ -2123,25 +2598,59 @@ let ShopGateway = (() => {
 				cacheDir
 			};
 		}
-		/** The origins to race for this row's catalog. Read once per gateway: the
-		* user's npmrc does not change under a running dsh, and re-reading it on
-		* every catalog call would put a filesystem read on the hot path. */
-		originsFor(catalogUrl) {
-			if (this.originCache?.catalogUrl === catalogUrl) return this.originCache.origins;
-			const registry = npmrcRegistry((path) => {
+		/** The user's own registry, read once. The self-update check and catalog
+		* race share this preference so neither path repeatedly touches ~/.npmrc. */
+		npmRegistry() {
+			const cached = this.npmRegistryCache;
+			if (cached !== null) return cached.value;
+			const value = npmrcRegistry((path) => {
 				try {
 					return readFileSync(path, "utf8");
 				} catch {
 					return null;
 				}
 			}, homedir());
-			const origins = catalogOrigins(catalogUrl, fetch, registry);
+			this.npmRegistryCache = { value };
+			return value;
+		}
+		/** The origins to race for this row's catalog. Read once per gateway: the
+		* user's npmrc does not change under a running dsh, and re-reading it on
+		* every catalog call would put a filesystem read on the hot path. */
+		originsFor(catalogUrl) {
+			if (this.originCache?.catalogUrl === catalogUrl) return this.originCache.origins;
+			const origins = catalogOrigins(catalogUrl, fetch, this.npmRegistry());
 			this.originCache = {
 				catalogUrl,
 				origins
 			};
 			return origins;
 		}
+		/** Join an in-flight load; refresh requests always start a new load. */
+		loadCatalogOnce(refresh) {
+			const existing = this.inFlightLoad;
+			if (!refresh && existing !== null) return existing;
+			const { catalogUrl, cacheDir } = this.rowConfig();
+			const started = (this.options.loadCatalog ?? loadCatalog)({
+				origins: this.originsFor(catalogUrl),
+				cacheDir,
+				refresh
+			}).then((result) => {
+				this.lastSnapshot = result.snapshot;
+				return result;
+			});
+			this.inFlightLoad = started;
+			const forget = () => {
+				if (this.inFlightLoad === started) this.inFlightLoad = null;
+			};
+			started.then(forget, forget);
+			return started;
+		}
+		/** Return the current snapshot, loading it once when needed. */
+		async snapshotNow() {
+			if (this.lastSnapshot !== null) return this.lastSnapshot;
+			const { snapshot } = await this.loadCatalogOnce(false);
+			return snapshot;
+		}
 		/** The explicit restart override. Only the row's `config:` sub-object is
 		* passed to a plugin — a top-level `allowRestart:` beside `name:` would be
 		* silently ignored by the loader (dsh-market README, #227). */
@@ -2156,13 +2665,7 @@ let ShopGateway = (() => {
 		}
 		/** Browse the catalog (§7.3): cached snapshot, refreshed on demand. */
 		async catalog(args) {
-			const { catalogUrl, cacheDir } = this.rowConfig();
-			const { snapshot, stale } = await (this.options.loadCatalog ?? loadCatalog)({
-				origins: this.originsFor(catalogUrl),
-				cacheDir,
-				refresh: args?.refresh ?? false
-			});
-			this.lastSnapshot = snapshot;
+			const { snapshot, stale } = await this.loadCatalogOnce(args?.refresh ?? false);
 			let incompatible;
 			if (this.incompatibleCache !== null && this.incompatibleCache.snapshot === snapshot) incompatible = this.incompatibleCache.map;
 			else {
@@ -2194,26 +2697,13 @@ let ShopGateway = (() => {
 		* passing request reaches the executor.
 		*/
 		async install(args) {
-			if (this.lastSnapshot === null) {
-				const { catalogUrl, cacheDir } = this.rowConfig();
-				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					origins: this.originsFor(catalogUrl),
-					cacheDir
-				});
-				this.lastSnapshot = snapshot;
-			}
-			const verdict = validateInstall(this.lastSnapshot, args);
+			const verdict = validateInstall(await this.snapshotNow(), args);
 			if (!verdict.ok) return {
 				ok: false,
 				code: verdict.code,
 				detail: verdict.detail
 			};
-			const entry = this.lastSnapshot.entries.find((e) => e.name === args.name);
-			if (entry === void 0) return {
-				ok: false,
-				code: "not-in-catalog",
-				detail: `dsh-plugin-shop: ${args.name} is not in the catalog`
-			};
+			const entry = verdict.entry;
 			let spec;
 			if (entry.source === "github" && entry.tarball !== void 0) {
 				const integrity = await verifyTarballSha256(this.fetchTarball, entry.tarball.url, entry.tarball.sha256);
@@ -2255,7 +2745,7 @@ let ShopGateway = (() => {
 				const pins = readRepoPins(this.pinFs, this.pinsPath());
 				writeRepoPins(this.pinFs, this.pinsPath(), {
 					...pins,
-					[args.name]: args.version
+					[identityKey(entry)]: entry.version
 				});
 			}
 			this.installs.set(running.installId, running);
@@ -2278,6 +2768,11 @@ let ShopGateway = (() => {
 			const excess = Math.max(0, finishedIds.length - ShopGateway.MAX_FINISHED_INSTALLS);
 			for (const id of finishedIds.slice(0, excess)) this.installs.delete(id);
 		}
+		/** Whether any command this gateway started is still running. */
+		hasRunningCommand() {
+			for (const record of this.installs.values()) if (record.status().state === "running") return true;
+			return false;
+		}
 		/** Poll one install's progress (§7.2); unknown ids report `found: false`. */
 		installStatus(args) {
 			const running = this.installs.get(args.installId);
@@ -2297,14 +2792,7 @@ let ShopGateway = (() => {
 		* attached. The tab's shelf cards and its installed section both derive
 		* from this one list. */
 		async installed() {
-			if (this.lastSnapshot === null) {
-				const { catalogUrl, cacheDir } = this.rowConfig();
-				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					origins: this.originsFor(catalogUrl),
-					cacheDir
-				});
-				this.lastSnapshot = snapshot;
-			}
+			const snapshot = await this.snapshotNow();
 			const dependencies = readProfileManifest("dsh-plugin-shop", this.profileDirResolved()).dependencies ?? {};
 			const pins = readRepoPins(this.pinFs, this.pinsPath());
 			const live = /* @__PURE__ */ new Map();
@@ -2332,13 +2820,20 @@ let ShopGateway = (() => {
 				return present.length === 0 || present.every(([, enabled]) => enabled);
 			};
 			const installed = [];
-			for (const entry of this.lastSnapshot.entries) {
+			for (const entry of snapshot.entries) {
 				const spec = dependencies[entry.name];
 				if (spec === void 0) continue;
+				if (!installedSpecMatches(entry, spec)) continue;
+				const identity = {
+					source: entry.source,
+					repo: entry.repo,
+					subdir: entry.subdir
+				};
 				if (entry.source === "github") {
-					const pin = pins[entry.name];
+					const pin = pins[identityKey(entry)] ?? pins[entry.name];
 					installed.push({
 						name: entry.name,
+						...identity,
 						installed: pin ?? spec,
 						latest: entry.version,
 						outdated: pin !== void 0 && pin !== entry.version,
@@ -2346,6 +2841,7 @@ let ShopGateway = (() => {
 					});
 				} else installed.push({
 					name: entry.name,
+					...identity,
 					installed: spec,
 					latest: entry.version,
 					outdated: this.isBehind(spec, entry.version),
@@ -2375,22 +2871,17 @@ let ShopGateway = (() => {
 		* dependencies the shop does not manage (the base bundle, the shop
 		* itself). The same install records/polling serve the client. */
 		async uninstall(args) {
-			if (this.lastSnapshot === null) {
-				const { catalogUrl, cacheDir } = this.rowConfig();
-				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					origins: this.originsFor(catalogUrl),
-					cacheDir
-				});
-				this.lastSnapshot = snapshot;
-			}
-			if (!this.lastSnapshot.entries.some((entry) => entry.name === args.name)) return {
+			const named = (await this.snapshotNow()).entries.filter((entry) => entry.name === args.name);
+			if (named.length === 0) return {
 				ok: false,
 				detail: `dsh-plugin-shop: ${args.name} is not in the catalog`
 			};
-			if ((readProfileManifest("dsh-plugin-shop", this.profileDirResolved()).dependencies ?? {})[args.name] === void 0) return {
+			const spec = (readProfileManifest("dsh-plugin-shop", this.profileDirResolved()).dependencies ?? {})[args.name];
+			if (spec === void 0) return {
 				ok: false,
 				detail: `dsh-plugin-shop: ${args.name} is not installed`
 			};
+			const installedEntry = named.find((entry) => installedSpecMatches(entry, spec));
 			const priorEntryIds = this.ownedEntryIdsOrNone(args.name);
 			const running = startUninstall({
 				profile: this.profile,
@@ -2406,10 +2897,14 @@ let ShopGateway = (() => {
 				}
 			});
 			const pins = readRepoPins(this.pinFs, this.pinsPath());
-			if (pins[args.name] !== void 0) {
-				delete pins[args.name];
-				writeRepoPins(this.pinFs, this.pinsPath(), pins);
+			const stalePins = [args.name, ...installedEntry === void 0 ? [] : [identityKey(installedEntry)]];
+			let forgot = false;
+			for (const key of stalePins) {
+				if (pins[key] === void 0) continue;
+				delete pins[key];
+				forgot = true;
 			}
+			if (forgot) writeRepoPins(this.pinFs, this.pinsPath(), pins);
 			this.installs.set(running.installId, running);
 			this.installOrder.push(running.installId);
 			this.evictFinishedInstalls();
@@ -2424,6 +2919,10 @@ let ShopGateway = (() => {
 		* response is out. The browser monitors the origin and refreshes when the
 		* new server answers. Refusals are issued before anything is torn down. */
 		async restart() {
+			if (this.hasRunningCommand()) return {
+				ok: false,
+				detail: "dsh-plugin-shop: an install is still running in this profile; a restart now would boot the new dsh against a half-written profile. Wait for it to finish and try again."
+			};
 			if (!this.restartPlatformSupported()) return {
 				ok: false,
 				detail: "dsh-plugin-shop: restart is not supported on Windows yet; restart dsh manually to apply the change"
@@ -2439,9 +2938,16 @@ let ShopGateway = (() => {
 			};
 			try {
 				const { cacheDir } = this.rowConfig();
-				startRestart({
+				const { command, args } = restartCommand({
 					dshBin: this.dshBin,
 					argv: this.restartArgv,
+					execPath: process.execPath,
+					execArgv: process.execArgv,
+					script: this.restartScript
+				});
+				startRestart({
+					command,
+					args,
 					parentPid: this.restartParentPid,
 					logFile: join(cacheDir, "restart.log"),
 					env: process.env