dsh-plugin-shop 0.8.1 → 0.8.2

package/lib/index.js

@@ -5,7 +5,7 @@ import { lt, minVersion, satisfies, valid, validRange } from "semver";
 import { createHash, randomUUID } from "node:crypto";
 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 { basename, delimiter, dirname, isAbsolute, join, posix, relative, resolve, win32 } from "node:path";
 import { homedir } from "node:os";
 import { z } from "zod";
 import { gunzipSync } from "node:zlib";
@@ -688,7 +688,7 @@ const pointerSchema = z.object({
 		sha256: z.string()
 	}).optional()
 });
-const nodeFs$2 = {
+const nodeFs$1 = {
 	exists: (path) => existsSync(path),
 	read: (path) => readFileSync(path, "utf8"),
 	write: (path, data) => {
@@ -720,7 +720,7 @@ function parseStarsText(text) {
 * included, degrades to no stars (spec §5).
 */
 async function loadCatalog(options) {
-	const { cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs$2 } = options;
+	const { cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs$1 } = options;
 	if (options.baseUrl === void 0 === (options.origins === void 0)) throw new Error("loadCatalog: exactly one of baseUrl or origins is required");
 	const originList = options.origins ?? [httpOrigin(options.baseUrl, fetchImpl)];
 	if (originList.length === 0) throw new Error("loadCatalog: no origins");
@@ -1079,6 +1079,23 @@ const DSH_BIN_NAME = "dsh";
 */
 const JS_ENTRY = /\.[cm]?js$/;
 /**
+* The command that starts `bin` through `execPath` when `bin` names a
+* JavaScript entry, or `null` when `bin` is a program to spawn as given.
+*
+* Extracted from {@link dshCommand} so `prefetch.ts` can reach the same
+* decision for pnpm without a second copy of {@link JS_ENTRY}: both need it
+* for the same two reasons — a packaged JS entry is what a caller pinning an
+* installation can name, and a `.mjs` test fixture is the only fake CLI that
+* can be spawned on Windows at all.
+*/
+function jsEntryCommand(bin, args, execPath) {
+	if (!JS_ENTRY.test(bin)) return null;
+	return {
+		command: execPath,
+		args: [bin, ...args]
+	};
+}
+/**
 * The command that starts the dsh CLI with `args`.
 *
 * For the bare name the node route replaces exactly one thing: looking `dsh`
@@ -1101,11 +1118,7 @@ function dshCommand(options) {
 			args: [...args]
 		};
 	}
-	if (JS_ENTRY.test(dshBin)) return {
-		command: execPath,
-		args: [dshBin, ...args]
-	};
-	return {
+	return jsEntryCommand(dshBin, args, execPath) ?? {
 		command: dshBin,
 		args: [...args]
 	};
@@ -1169,6 +1182,13 @@ function resolveDshScript(fs, options) {
 	return null;
 }
 //#endregion
+//#region src/shared/install-state.ts
+/** Whether the host is done with this record: it will not change again, and a
+* poller may stop. */
+function isTerminalInstallState(state) {
+	return state === "done" || state === "failed";
+}
+//#endregion
 //#region src/host/executor.ts
 /** Plugin-command executor: spawn the dsh CLI, stream its output, serialize
 * per profile. One implementation drives both `dsh plugin add` (install) and
@@ -1182,6 +1202,23 @@ const INSTALL_TIMEOUT_MS = Number(process.env.DSH_SHOP_INSTALL_TIMEOUT_MS) || 9e
 /** Grace period for output already buffered after the child exits. */
 const PIPE_DRAIN_MS = 500;
 const profileQueues = /* @__PURE__ */ new Map();
+/** How many commands are queued or running per profile.
+*
+* `profileQueues` cannot answer this: its entries are only ever set, never
+* deleted, so `has(profile)` is true forever after a profile's first install
+* and would call every later lone install queued — earning it a pointless
+* prefetch and a `Downloading…` label that is simply false. Promise state is
+* not observable, so a counter is the only honest signal available.
+*/
+const profileDepth = /* @__PURE__ */ new Map();
+function enterQueue(profile) {
+	const ahead = profileDepth.get(profile) ?? 0;
+	profileDepth.set(profile, ahead + 1);
+	return ahead;
+}
+function leaveQueue(profile) {
+	profileDepth.set(profile, Math.max(0, (profileDepth.get(profile) ?? 1) - 1));
+}
 function chain(profile, task) {
 	const next = (profileQueues.get(profile) ?? Promise.resolve()).then(task, task);
 	profileQueues.set(profile, next.catch(() => {}));
@@ -1338,6 +1375,10 @@ function spawnFailureDetail(code, message, dshBin, platform) {
 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`;
 }
+/** The real kill. Exported for the tests that inject a RECORDING `KillFns`:
+* a recorder that only records asserts that a kill was requested and leaves
+* the child running, which for a `detached` fixture is an immortal node
+* process per run — see `prefetch.test.ts`'s delegating recorder. */
 const nodeKills = {
 	killGroup: (pid) => process.kill(-pid, "SIGKILL"),
 	killPid: (pid) => process.kill(pid, "SIGKILL"),
@@ -1383,7 +1424,7 @@ function lineSink(emit) {
 	};
 }
 /** Read-only filesystem seam for the CLI lookup; the same shape as `pinFs`. */
-const nodeFs$1 = {
+const nodeFs = {
 	exists: (path) => existsSync(path),
 	read: (path) => readFileSync(path, "utf8")
 };
@@ -1393,7 +1434,7 @@ let cachedScript;
 * so no platform but Windows pays for it. */
 function dshScript() {
 	if (process.platform !== "win32") return null;
-	if (cachedScript === void 0) cachedScript = resolveDshScript(nodeFs$1, {
+	if (cachedScript === void 0) cachedScript = resolveDshScript(nodeFs, {
 		argv1: process.argv[1],
 		path: process.env.PATH
 	});
@@ -1455,12 +1496,12 @@ function shellSafeTarget(target, platform) {
 * manifest before the command reports `done` (§7.2 step 6 and its uninstall
 * mirror). When `afterDone` is given, a zero exit that passes `confirm`
 * withholds the terminal `done` until the callback — typically the hot-mount
-* attempt — settles; its result sets `needsRestart` (default `true`) and
+* attempt — settles; its result sets `activation` (default `restart`) and
 * `restartReason`. The client stops polling at `done`, so the hot outcome
 * 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, platform = process.platform, beforeSpawn, confirm, afterDone, onStatus, timeoutMs = INSTALL_TIMEOUT_MS } = options;
+	const { profile, argv, dshBin, env, platform = process.platform, beforeSpawn, prefetcher, 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)}`);
@@ -1469,21 +1510,22 @@ function spawnPluginCli(options) {
 	const installId = randomUUID();
 	const log = [];
 	let logBytes = 0;
+	const ahead = enterQueue(profile);
 	let state = "running";
-	let needsRestartOnDone = true;
+	let activationOnDone = "restart";
 	let restartReason;
 	let detail;
 	const status = () => ({
 		state,
 		log: [...log],
 		...state === "done" ? {
-			needsRestart: needsRestartOnDone,
+			activation: activationOnDone,
 			...restartReason !== void 0 ? { restartReason } : {}
 		} : {},
 		...detail !== void 0 ? { detail } : {}
 	});
 	const append = (line) => {
-		if (state !== "running") return;
+		if (isTerminalInstallState(state)) return;
 		log.push(line);
 		logBytes += Buffer.byteLength(line);
 		while ((log.length > MAX_LOG_LINES || logBytes > MAX_LOG_BYTES) && log.length > 1) {
@@ -1498,115 +1540,136 @@ function spawnPluginCli(options) {
 		onStatus?.(status());
 		return status();
 	};
-	return {
-		installId,
-		status,
-		finished: chain(profile, () => new Promise((resolve) => {
-			beforeSpawn?.(env?.DSH_HOME);
-			const { command, args } = dshCommand({
-				dshBin,
-				args: [
-					"plugin",
-					"--profile",
-					profile,
-					...spawnArgv
+	let prefetch = null;
+	if (ahead > 0 && prefetcher !== void 0) try {
+		prefetch = prefetcher.request({
+			profile,
+			spec: target,
+			cwd: resolveProfileDir(profile, env?.DSH_HOME),
+			env,
+			log: append
+		});
+	} catch (error) {
+		append(`dsh-plugin-shop: the download phase could not start — ${error.message}`);
+	}
+	if (prefetch?.started === true) state = "downloading";
+	else if (prefetch !== null) append(prefetch.reason === "no-pnpm" ? "dsh-plugin-shop: no download phase — pnpm not found on PATH" : "dsh-plugin-shop: no download phase for this spec form; the install fetches it directly");
+	const finished = chain(profile, () => new Promise((resolve) => {
+		state = "running";
+		onStatus?.(status());
+		beforeSpawn?.(env?.DSH_HOME);
+		const { command, args } = dshCommand({
+			dshBin,
+			args: [
+				"plugin",
+				"--profile",
+				profile,
+				...spawnArgv
+			],
+			platform,
+			execPath: process.execPath,
+			script: dshScript()
+		});
+		let child;
+		try {
+			child = spawn(command, args, {
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
 				],
-				platform,
-				execPath: process.execPath,
-				script: dshScript()
+				env: env ?? process.env,
+				detached: platform !== "win32"
 			});
-			let child;
-			try {
-				child = spawn(command, args, {
-					stdio: [
-						"ignore",
-						"pipe",
-						"pipe"
-					],
-					env: env ?? process.env,
-					detached: platform !== "win32"
-				});
-			} catch (error) {
-				resolve(failToStart(error));
-				return;
-			}
-			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;
-				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";
-						detail = confirmDetail;
-					} else if (afterDone !== void 0) {
-						try {
-							const outcome = await afterDone(env?.DSH_HOME);
-							needsRestartOnDone = outcome?.needsRestart ?? true;
-							restartReason = outcome?.restartReason;
-						} catch {
-							needsRestartOnDone = true;
-							restartReason = "mount-failed";
-						}
-						state = "done";
-					} else state = "done";
-				} else {
+		} catch (error) {
+			resolve(failToStart(error));
+			return;
+		}
+		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;
+			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";
-					detail = installFailureDetail(profile, log);
-				}
-				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, platform);
-				drainThenSettle();
-			}, timeoutMs);
-		}))
+					detail = confirmDetail;
+				} else if (afterDone !== void 0) {
+					try {
+						const outcome = await afterDone(env?.DSH_HOME);
+						activationOnDone = outcome?.activation ?? "restart";
+						restartReason = outcome?.restartReason;
+					} catch {
+						activationOnDone = "restart";
+						restartReason = "mount-failed";
+					}
+					state = "done";
+				} else state = "done";
+			} else {
+				state = "failed";
+				detail = installFailureDetail(profile, log);
+			}
+			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, platform);
+			drainThenSettle();
+		}, timeoutMs);
+	})).finally(() => {
+		leaveQueue(profile);
+		prefetcher?.release(profile, target);
+	});
+	finished.catch(() => {});
+	return {
+		installId,
+		status,
+		finished
 	};
 }
 /**
@@ -1621,7 +1684,7 @@ function spawnPluginCli(options) {
 * (§D hot mount).
 */
 function startInstall(options) {
-	const { profile, spec, dshBin = "dsh", env, platform, expectedName, alsoConfirm, afterDone, onStatus, timeoutMs } = options;
+	const { profile, spec, dshBin = "dsh", env, platform, expectedName, prefetcher, alsoConfirm, afterDone, onStatus, timeoutMs } = options;
 	let before = null;
 	return spawnPluginCli({
 		profile,
@@ -1632,6 +1695,7 @@ function startInstall(options) {
 		beforeSpawn: expectedName !== void 0 ? (home) => {
 			before = readProfileDependencies(profile, home);
 		} : void 0,
+		prefetcher,
 		confirm: expectedName !== void 0 ? (home) => confirmBundleActivation(profile, home, expectedName, before) ?? alsoConfirm?.(home) ?? null : alsoConfirm,
 		afterDone,
 		onStatus,
@@ -1723,7 +1787,7 @@ const PATCH_SCHEMA = JSON_SCHEMA.extend(new Type("tag:yaml.org,2002:js", {
 	resolve: () => true,
 	construct: (data) => ({ __jsExpr: data })
 }));
-const nodeFs = {
+const nodeHotFs = {
 	read: (path) => readFileSync(path, "utf8"),
 	write: (path, data) => {
 		mkdirSync(dirname(path), { recursive: true });
@@ -1853,7 +1917,7 @@ function suppressWrite(treeClass) {
 * the bundle layer either way, so a restart always activates it.
 */
 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 { fs = nodeHotFs, 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");
@@ -1973,6 +2037,88 @@ function cleanHotDir(profileDir) {
 	for (const name of names) if (HOT_FILE_RE.test(name)) rmSync(join(dir, name), { force: true });
 }
 //#endregion
+//#region src/host/activation.ts
+/**
+* Decide what the reader must do.
+*
+* @param input.hostLive - whether the plugin's host half is in its intended
+* post-change state in this process right now: the hot-mount outcome for an
+* install or update, whether the fiber actually went away for an uninstall,
+* and true for a toggle (the user layer is hot-reloaded).
+* @param input.hasClientHalf - whether the package declares `dsh.client`. An
+* unreadable manifest reports `true`; see `client-half.ts` for why.
+* @param input.clientLive - whether THIS change's browser half is in the
+* graph the webserver hands a reloading tab.
+*
+* `clientLive` is the difference between the two routes a change can take,
+* and it is measured rather than assumed:
+*
+* - A change to the BOOT COMPOSITION — a toggle, an uninstall — moves an
+*   entry the registry already enumerates, and the served graph follows it
+*   within seconds (§2, measured 2026-09-11). `true`.
+* - A HOT MOUNT — an install or an update — adds to the live loader entries
+*   without entering that composition, so the graph a tab reloads into does
+*   not contain the package. Measured 2026-09-14 against dsh 0.1.5-rc.1 in
+*   `web-full-flow.e2e.ts`: across a reload following a hot mount the graph
+*   is byte-identical, same `rev`, while the package's host half is live the
+*   whole time. `false` — and a `restart` is then the only honest answer,
+*   because there is nothing a reload could fetch.
+*
+* The asymmetry that decides every unknown still runs the same way: offering
+* a step that was not needed costs the reader one action, withholding one
+* that was needed is the defect this module exists to fix. What changed on
+* 2026-09-14 is which step is the needed one after a hot mount.
+*/
+function activationOf(input) {
+	if (!input.hostLive) return "restart";
+	if (!input.hasClientHalf) return "live";
+	return input.clientLive ? "reload" : "restart";
+}
+//#endregion
+//#region src/host/client-half.ts
+/**
+* Does an installed package have a browser half? (design
+* 2026-09-11-activation-model §3.)
+*
+* The harness's `ClientModuleRegistry` scans the loader's entries for
+* packages declaring `dsh.client` and composes `window.__DSH_BOOT__` from
+* them. That declaration is therefore the whole question: a package that
+* declares it puts something in a browser tab, and a tab opened before the
+* change is showing the state from before it.
+*
+* The read goes through `HotFs`, the same injected seam `hot.ts` uses to
+* read the same file for `dsh.bundle.patch`, so tests never touch disk and
+* exactly one production call site does.
+*/
+/**
+* Whether `packageName`, as installed in `profileDir`, declares `dsh.client`.
+*
+* **An unreadable manifest answers `true`.** Offering a reload that was not
+* needed costs the reader one keystroke; withholding one that was needed is
+* the defect this module exists to fix, so the fallback is the safe side of
+* a lopsided asymmetry rather than a guess.
+*
+* The VALUE of `dsh.client` is not inspected — an empty object is a
+* declaration. Only a non-object (the manifest saying something else
+* entirely) reads as no declaration.
+*/
+function hasClientHalf(fs, profileDir, packageName) {
+	let text;
+	try {
+		text = fs.read(join(profileDir, "node_modules", packageName, "package.json"));
+	} catch {
+		return true;
+	}
+	let manifest;
+	try {
+		manifest = JSON.parse(text);
+	} catch {
+		return true;
+	}
+	const client = manifest?.dsh?.client;
+	return typeof client === "object" && client !== null && !Array.isArray(client);
+}
+//#endregion
 //#region src/host/restart.ts
 /** Restart executor: hand the port to a new dsh instance, two-phase.
 *
@@ -2358,6 +2504,312 @@ function collidingEntryId(options) {
 	return null;
 }
 //#endregion
+//#region src/host/prefetch.ts
+/**
+* The download phase that runs in front of the per-profile install mutex.
+*
+* `dsh plugin add` is one opaque call: it resolves, fetches, links and writes
+* in a single pnpm invocation, so the shop cannot split it. What it can do is
+* warm pnpm's content store first, from outside the mutex, so the serialized
+* install is a store hit. Measured 2026-09-10: an npm or github spec warmed
+* this way installs with `downloaded 0`. Design doc §3.
+*
+* Best-effort by construction. Every failure here — pnpm absent, a non-zero
+* batch, a timeout, a store guessed wrong — leaves `dsh plugin add` to fetch
+* what the store lacks, exactly as it does today. Nothing about whether an
+* install SUCCEEDS may depend on this module.
+*/
+/** How long one batch may run before it is killed. Far below
+* `INSTALL_TIMEOUT_MS`: a batch still running after this is no longer hiding
+* any latency, and the install behind it simply proceeds cold. */
+const BATCH_TIMEOUT_MS = Number(process.env.DSH_SHOP_PREFETCH_TIMEOUT_MS) || 9e4;
+/**
+* Whether warming the store for `spec` can save the install any work.
+*
+* A raw https tarball URL cannot, measured twice on 2026-09-10: pnpm
+* re-fetches such a URL on EVERY install even when the store already holds
+* that exact tarball — it must read the `package.json` inside it and that
+* read does not go through the store — and `pnpm store add` on a URL resolves
+* no dependency closure. So a prefetch of that form is one extra full
+* download for no measured saving. The three spec forms are indistinguishable
+* at the `store add` boundary (all exit 0, all print `+ <spec>`), which is why
+* this exclusion is recorded rather than left to look like an oversight.
+* Design doc §3.
+*/
+function isPrefetchableSpec(spec) {
+	return !/^https?:\/\//i.test(spec);
+}
+/**
+* `cmd.exe`'s exit code for a command line it could not resolve — the Windows
+* answer to the ENOENT node never sends there.
+*
+* On the one platform where this module passes `shell: true`, the child node
+* starts is `cmd.exe`, which EXISTS: the spawn succeeds, its "not recognized
+* as an internal or external command" complaint goes to a stderr this module
+* discards, and no `error` event ever arrives. The ENOENT latch below is
+* therefore dead on Windows by construction. Measured 2026-09-14 on this
+* Linux box, whose shell answers 127 instead of 9009 but is otherwise the same
+* shape: `spawn('definitely-not-here', argv, { shell: true })` emits only
+* `exit`, while the identical spawn without the shell emits `error: ENOENT`.
+* PR #45's `windows` job is the half that cannot run here — it is where the
+* missing latch showed up, as the case "reports pnpm absent to the install it
+* was serving, and refuses the next by name" sitting red for the full 10s of
+* its `vi.waitFor` because the line it filters for was never announced.
+*
+* **That arm did not turn the leg green, and this is why.** A temporary
+* diagnostic, gated on `shell` so only the Windows runner printed it, came
+* back with four exits, in test-file order:
+*
+*   exit code=1     bin="…\dsh-prefetch-*\definitely-not-here"
+*   exit code=9009  bin="pnpm"
+*   exit code=1     bin="pnpm"
+*   exit code=0     bin="pnpm"
+*
+* The first line is the failing case's own bin, and it is the whole finding:
+* that case passes a PATH, `cmd.exe` answers **1** for a path it cannot find,
+* and 1 is also what a command that RAN and failed answers. The two things
+* this latch must tell apart are the same number, so no value of this
+* constant could have made the arm fire — it was gated on a signal that case
+* does not produce. (The 9009 line is not evidence for the constant either.
+* It is the second shell-gated exit the suite emits, and the only real
+* `cmd.exe` child started before it is the one above: the cases that pass a
+* bare `pnpm` inject a scripted child that emits its own code — this file's
+* `scriptedSpawn` — so 9009 there is a fixture value echoed back, not a
+* measurement of the shell.)
+*
+* Absence is therefore asked BEFORE the spawn now, by {@link resolvesBin},
+* which is the primary mechanism. This arm stays as the one thing resolving
+* cannot cover: a name that IS found and still cannot be run. Its number is
+* `cmd.exe`'s long-standing answer for an unresolvable name and is unverified
+* by this repo's own runs — nothing reaches it without `platform === 'win32'`,
+* and nothing on the Windows runner has produced one. Should it be wrong the
+* behaviour is what Windows had before the arm existed: the latch does not set
+* and the generic exit line stands. A false positive is bounded by this
+* module's own contract — the worst a stray 9009 can do is refuse the rest of
+* the process's prefetches, a lost optimization and never a failed, slower or
+* altered install.
+*/
+const SHELL_COMMAND_NOT_FOUND = 9009;
+/** What a bare name may be resolved AS on Windows, on top of the name itself.
+*
+* `cmd.exe` resolves a bare command through `PATHEXT`, and these are the two
+* shapes an executor actually arrives in: `.cmd` is what npm's pnpm shim is,
+* which is the reason this module passes `shell: true` there at all, and
+* `.exe` is what a native install (a packed binary, a Node SEA) puts on PATH.
+* The bare name is tried as well, which makes this a superset of what the
+* shell resolves. That asymmetry is deliberate, because the two mistakes do
+* not cost the same: a false PRESENT spends one doomed child, which
+* {@link SHELL_COMMAND_NOT_FOUND} or `error` then latches a moment later,
+* while a false ABSENT both disables the optimization for the rest of the
+* process and tells the user pnpm is missing from a machine that has it. */
+const WIN32_SUFFIXES = [
+	"",
+	".cmd",
+	".exe"
+];
+/**
+* Every plausible reading of a PATH string, as the directories it could hold.
+*
+* Three readings, because the two ends of that string disagree about who
+* decides the separator. `platform` says what the SHELL is — this module takes
+* it as an argument, and the tests drive the win32 branch from a Linux runner
+* with it — while the string itself was produced by the HOST that built the
+* batch's environment. So whichever separator `platform` names, the string may
+* have been joined with the other one, and BOTH mismatches are reachable; only
+* one of them was guarded.
+*
+* The one that bit: a single-entry PATH whose entry is a Windows absolute path
+* — `C:\Users\…\dsh-prefetch-X`, which is exactly what a test's temp directory
+* is on the Windows runner — read with `platform: 'linux'` splits on ':' into
+* `C` and `\Users\…`. Neither is the directory, so the pnpm that was right
+* there was reported absent, and the latch that follows means it stays absent
+* for the rest of the process. The string's own reading comes first for that
+* shape: it IS one directory, and that is the most direct true answer there
+* is. (A real PATH yields its real entries under one of the two splits; this
+* reading costs a stat on a string that is not a directory, which is what a
+* multi-entry PATH always is.)
+*
+* Trying all three costs an `existsSync` or two on a string none of them
+* resolves, and it is the safe direction to err in — see `WIN32_SUFFIXES`: a
+* false PRESENT spends one doomed child, while a false ABSENT both disables
+* the optimization for the rest of the process and tells the user pnpm is
+* missing from a machine that has it. The price is that a directory named
+* exactly like a PATH string — legal, if perverse — is read as the entry it
+* spells, and that lands on the cheap side of the same asymmetry.
+*
+* Order decides only how much work a MISS costs: a hit in any reading is
+* present, so the list is a set and not a preference.
+*/
+const pathReadings = (path) => {
+	const raw = path ?? "";
+	return [
+		raw,
+		...raw.split(posix.delimiter),
+		...raw.split(win32.delimiter)
+	];
+};
+/**
+* Whether `bin` names something a batch could actually start — asked of the
+* filesystem before the spawn, because on Windows the failure cannot answer it
+* (see {@link SHELL_COMMAND_NOT_FOUND}: a path that is not there and a command
+* that ran and failed both exit 1).
+*
+* Pure path arithmetic over `existsSync`, which is what makes it testable on
+* the Linux runners — the exit-code route was not, and that is why the Windows
+* leg was the only place the defect could appear. No process is started to ask
+* the question, so a bin that is not there is never spawned.
+*
+* `path` is the batch's OWN PATH, not the shop's: an install may carry a
+* narrowed environment, the batch inherits exactly that, and the name has to
+* resolve where the child will look for it. An absent `PATH` falls back to the
+* process's, the same way the child's environment would. The string is read
+* into entries by {@link pathReadings}, which tries every separator rather
+* than betting on the one `platform` names.
+*
+* An empty PATH entry is skipped, as `dsh-cli.ts` skips it: it means "the
+* current directory", which is not where a bare `pnpm` lives, and a relative
+* `existsSync` here would be answering about the shop's cwd instead.
+*
+* A RELATIVE bin is looked up against the process's own cwd rather than the
+* batch's, which is the one thing this questions less precisely than the OS
+* will. No caller produces one today — production passes the bare name, and
+* the fixtures pass absolute paths — and the backstop covers it if one ever
+* does, since the child then simply fails where this said it would start.
+*/
+const resolvesBin = (bin, platform, path) => {
+	if (bin.includes("/") || bin.includes("\\")) return existsSync(bin);
+	const suffixes = platform === "win32" ? WIN32_SUFFIXES : [""];
+	for (const dir of pathReadings(path)) {
+		if (dir === "") continue;
+		for (const suffix of suffixes) if (existsSync(join(dir, bin + suffix))) return true;
+	}
+	return false;
+};
+function createPrefetcher(options = {}) {
+	const { pnpmBin = "pnpm", spawn: spawn$1 = spawn, platform = process.platform, execPath = process.execPath, timeoutMs = BATCH_TIMEOUT_MS, kills } = options;
+	const lanes = /* @__PURE__ */ new Map();
+	let pnpmAbsent = false;
+	const lane = (profile, cwd, env) => {
+		const existing = lanes.get(profile);
+		if (existing !== void 0) {
+			existing.cwd = cwd;
+			existing.env = env;
+			return existing;
+		}
+		const created = {
+			pending: /* @__PURE__ */ new Map(),
+			inFlight: /* @__PURE__ */ new Map(),
+			child: null,
+			timer: null,
+			cwd,
+			env
+		};
+		lanes.set(profile, created);
+		return created;
+	};
+	/** Tell every install the running batch served. */
+	const announce = (current, line) => {
+		for (const log of current.inFlight.values()) log(line);
+	};
+	/** pnpm is not on PATH: stop prefetching for the rest of this process, and
+	* tell the installs the running batch served why.
+	*
+	* Three ways absence arrives land here — {@link resolvesBin}, which is the
+	* primary one and the only one that asks before spawning; node's ENOENT for
+	* a binary it could not start; and cmd.exe's {@link SHELL_COMMAND_NOT_FOUND}
+	* for a name it could not resolve — so the latch and the line a user reads
+	* cannot drift apart between them. */
+	const latchAbsent = (current) => {
+		pnpmAbsent = true;
+		announce(current, "dsh-plugin-shop: no download phase — pnpm not found on PATH");
+	};
+	const finish = (profile, current) => {
+		if (current.timer !== null) clearTimeout(current.timer);
+		current.timer = null;
+		current.child = null;
+		current.inFlight.clear();
+		if (current.pending.size > 0 && !pnpmAbsent) start(profile, current);
+	};
+	const start = (profile, current) => {
+		const specs = [...current.pending.keys()];
+		for (const [spec, log] of current.pending) current.inFlight.set(spec, log);
+		current.pending.clear();
+		if (!resolvesBin(pnpmBin, platform, current.env?.PATH ?? process.env.PATH)) {
+			latchAbsent(current);
+			finish(profile, current);
+			return;
+		}
+		const argv = [
+			"store",
+			"add",
+			...specs
+		];
+		const routed = jsEntryCommand(pnpmBin, argv, execPath);
+		const shell = routed === null && platform === "win32";
+		const args = shell ? argv.map((arg) => shellSafeTarget(arg, platform)) : routed?.args ?? argv;
+		let child;
+		try {
+			child = spawn$1(routed?.command ?? pnpmBin, args, {
+				cwd: current.cwd,
+				env: current.env,
+				stdio: "ignore",
+				detached: platform !== "win32",
+				shell
+			});
+		} catch (error) {
+			announce(current, `dsh-plugin-shop: the download phase could not start — ${error.message}`);
+			finish(profile, current);
+			return;
+		}
+		current.child = child;
+		const isCurrent = () => current.child === child;
+		child.on("error", (error) => {
+			if (!isCurrent()) return;
+			if (error.code === "ENOENT") latchAbsent(current);
+			else announce(current, `dsh-plugin-shop: the download phase could not start — ${error.message}`);
+			finish(profile, current);
+		});
+		child.on("exit", (code) => {
+			if (!isCurrent()) return;
+			if (shell && code === SHELL_COMMAND_NOT_FOUND) latchAbsent(current);
+			else if (code === 0) announce(current, "dsh-plugin-shop: packages fetched ahead of the install");
+			else if (code !== null) announce(current, `dsh-plugin-shop: the download phase exit ${code}; the install will fetch what is missing`);
+			finish(profile, current);
+		});
+		current.timer = setTimeout(() => {
+			if (!isCurrent()) return;
+			announce(current, "dsh-plugin-shop: the download phase exceeded its bound; the install will fetch what is missing");
+			killTree(child.pid, platform, kills);
+			finish(profile, current);
+		}, timeoutMs);
+	};
+	return {
+		request: ({ profile, spec, cwd, env, log = () => {} }) => {
+			if (!isPrefetchableSpec(spec)) return {
+				started: false,
+				reason: "unsupported-spec"
+			};
+			if (pnpmAbsent) return {
+				started: false,
+				reason: "no-pnpm"
+			};
+			const current = lane(profile, cwd, env);
+			current.pending.set(spec, log);
+			if (current.child === null) queueMicrotask(() => {
+				if (current.child === null && current.pending.size > 0 && !pnpmAbsent) start(profile, current);
+			});
+			return { started: true };
+		},
+		release: (profile, spec) => {
+			const current = lanes.get(profile);
+			if (current === void 0) return;
+			current.pending.delete(spec);
+			current.inFlight.delete(spec);
+			if (current.child !== null && current.inFlight.size === 0 && current.pending.size === 0) killTree(current.child.pid, platform, kills);
+		}
+	};
+}
+//#endregion
 //#region src/host/peers.ts
 /** Harness compatibility: which declared peers the running installation does
 * not provide (design 2026-09-01-harness-compatibility), and — for the
@@ -2450,9 +2902,11 @@ function nodeVersionResolver(baseUrl) {
 *
 * `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
+* every later rc on the same 0.1 line — including whichever one is installed
+* and working, named as a property because that version moves and a comment
+* naming it goes stale in place — 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.
@@ -2557,6 +3011,20 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 	if (target) Object.defineProperty(target, contextIn.name, descriptor);
 	done = true;
 };
+/** Each blocked reason's author-readable refusal, written once.
+*
+* `restart()` returns these as its `detail` and `version()` returns the bare
+* reason for the client to localize, so the two can no longer disagree about
+* WHY a restart is impossible. They did: `version()` reported a boolean that
+* covered two of the refusals, the client had one string for that boolean, and
+* that string named systemd — so a Windows user was told to restart a systemd
+* service and to set an override that the platform check, being the first gate
+* of the three, could never reach. */
+const RESTART_BLOCKED_DETAIL = {
+	windows: "dsh-plugin-shop: restart is not supported on Windows yet; restart dsh manually to apply the change",
+	systemd: "dsh-plugin-shop: restart is disabled because this process is a systemd service — a restart would kill the takeover helper along with the unit, and the service would not come back. Set allowRestart: true in the shop row config to override.",
+	"port-zero": "dsh-plugin-shop: restart is not supported when dsh was launched with --port 0; restart dsh manually"
+};
 /** How many bytes a release tarball may be at the integrity check. The
 * registry already refuses to publish a tarball over 32 MiB, so 64 MiB is
 * headroom, not a gate of its own. */
@@ -2767,6 +3235,7 @@ let ShopGateway = (() => {
 		profileDir;
 		inventory;
 		hot;
+		hotFs;
 		loaderEntriesInjected;
 		dshBin;
 		/** The argv `shop/restart` re-spawns: the real process argv minus node and
@@ -2792,10 +3261,13 @@ let ShopGateway = (() => {
 		/** The release-tarball fetch for the install-time integrity check; global
 		* fetch in production, a fixture response in tests. */
 		fetchTarball;
+		/** One pump for the whole gateway: batching is per profile and lives inside
+		* it, so a second instance would race the first for the same store. */
+		prefetcher;
 		/** 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). */
 		/** Finished install records retained, so a poll sees the true terminal
-		* state (§8: done / needsRestart / failure detail). Oldest evicted on add. */
+		* state (§8: done / activation / failure detail). Oldest evicted on add. */
 		static MAX_FINISHED_INSTALLS = 32;
 		/** How long the gateway waits after a successful restart response before
 		* exiting the old process — the browser must receive the URL first. */
@@ -2832,6 +3304,7 @@ let ShopGateway = (() => {
 			this.profileDir = options.profileDir;
 			this.inventory = options.inventory;
 			this.hot = options.hot;
+			this.hotFs = options.hotFs;
 			this.loaderEntriesInjected = options.loaderEntries;
 			this.dshBin = options.dshBin ?? "dsh";
 			this.restartArgv = options.restartArgv ?? process.argv.slice(2);
@@ -2853,6 +3326,7 @@ let ShopGateway = (() => {
 			this.platform = options.platform ?? process.platform;
 			this.ppid = options.ppid ?? process.ppid;
 			this.fetchTarball = options.fetchTarball ?? ((url) => fetch(url));
+			this.prefetcher = options.prefetcher ?? createPrefetcher();
 			try {
 				cleanHotDir(this.profileDirResolved());
 			} catch {}
@@ -2976,24 +3450,53 @@ let ShopGateway = (() => {
 				return [];
 			}
 		}
-		async liveDisableIds(ids) {
-			if (ids.length === 0) return false;
+		/** Whether an installed package declares `dsh.client`. Reads through the
+		* `hotFs` option — `HotFs` is `hot.ts`'s type, but this gateway forwards
+		* the option only HERE, never into `hotMount`, which takes its own `fs`
+		* from `HotDeps`. A fixture therefore drives this read alone, which is the
+		* point: it is the only way to state what a package declared BEFORE an
+		* update overwrote its manifest. */
+		packageHasClientHalf(packageName) {
+			return hasClientHalf(this.hotFs ?? nodeHotFs, this.profileDirResolved(), packageName);
+		}
+		/**
+		* Bring every live entry the package owns down, best effort, and report
+		* whether its host half is DOWN when this returns.
+		*
+		* "Nothing matched" is down: a package with no live entry is not running,
+		* which is the ordinary case for removing a plugin that never loaded this
+		* session. Only a matched entry whose fiber outlives the retries — or
+		* whose `update` throws — leaves the plugin UP, and that is the one case
+		* an uninstall must not describe as stopped.
+		*
+		* The old spelling answered "did any update succeed", which is a different
+		* question: `update` resolving says the row was accepted, not that the
+		* instance went away. The retry loop below exists precisely because those
+		* two come apart, so reading the first as the second threw away the answer
+		* the loop was computing.
+		*/
+		async liveEntriesDown(ids) {
+			if (ids.length === 0) return true;
 			const owned = new Set(ids);
-			let found = false;
+			let allDown = true;
 			for (const entry of this.loaderEntries()) {
 				if (entry.id === void 0 || !ownsEntryId(owned, entry.id)) continue;
+				let down = false;
 				for (let attempt = 0; attempt < 3; attempt++) {
 					try {
 						await entry.update({ disabled: true }, false, true);
-						found = true;
 					} catch {
 						break;
 					}
-					if (entry.fiber === void 0) break;
+					if (entry.fiber === void 0) {
+						down = true;
+						break;
+					}
 					await new Promise((resolve) => setTimeout(resolve, 200));
 				}
+				if (!down) allDown = false;
 			}
-			return found;
+			return allDown;
 		}
 		/** Enable or disable one installed plugin, hot (§8): a disable writes the
 		* row to the user layer, an enable drops it again so the bundle default
@@ -3039,7 +3542,14 @@ let ShopGateway = (() => {
 					disabled: !args.enabled
 				}))
 			});
-			return { ok: true };
+			return {
+				ok: true,
+				activation: activationOf({
+					hostLive: true,
+					clientLive: true,
+					hasClientHalf: this.packageHasClientHalf(args.name)
+				})
+			};
 		}
 		rowConfig() {
 			if (this.options.catalogUrl !== void 0 && this.options.cacheDir !== void 0) return {
@@ -3116,6 +3626,32 @@ let ShopGateway = (() => {
 		restartPlatformSupported() {
 			return this.platform !== "win32";
 		}
+		/** Why a restart would be refused for this process, or null when nothing
+		* static does. One ordered list, read by `restart()` before it commits and
+		* by `version()` so the client can say the same thing up front.
+		*
+		* The order is the order the refusals were written in and is load-bearing
+		* for the copy a reader sees: Windows first, because the platform check has
+		* no override and reporting the systemd one there sends a Windows user to
+		* set `allowRestart: true`, which this gate would still refuse.
+		*
+		* - `windows`: the handoff helper is a POSIX shell one-liner (restart.ts)
+		*   and there is no `sh` on Windows. That spawn fails ASYNCHRONOUSLY, so
+		*   committing would answer `ok: true`, exit this process, and leave nothing
+		*   to take the port — dsh would simply be gone.
+		* - `systemd`: under a unit the two-phase handoff kills itself, because the
+		*   main process exiting also kills the unit's cgroup and takes the detached
+		*   helper with it; the service never comes back. Overridable, and the only
+		*   one of the three that is.
+		* - `port-zero`: the OS hands the NEW process a fresh port the browser
+		*   cannot know, so a restart would strand the client on a dead origin. */
+		staticRestartBlock() {
+			if (!this.restartPlatformSupported()) return "windows";
+			if (detectSupervisor(this.env, { ppid: this.ppid }) === "systemd" && !this.allowRestartConfigured()) return "systemd";
+			const portIndex = this.restartArgv.indexOf("--port");
+			if (portIndex !== -1 && this.restartArgv[portIndex + 1] === "0") return "port-zero";
+			return null;
+		}
 		allowRestartConfigured() {
 			if (this.allowRestart !== void 0) return this.allowRestart;
 			return ((this.ctx.loader?.entries().find((entry) => entry.options.name === "dsh-plugin-shop"))?.options.config)?.allowRestart === true;
@@ -3182,11 +3718,13 @@ let ShopGateway = (() => {
 			} else spec = `${args.name}@${args.version}`;
 			const isUpdate = installedSpec !== void 0;
 			const priorEntryIds = isUpdate ? this.ownedEntryIdsOrNone(args.name) : [];
+			const priorClientHalf = isUpdate && this.packageHasClientHalf(args.name);
 			const running = startInstall({
 				profile: this.profile,
 				spec,
 				dshBin: this.dshBin,
 				expectedName: args.name,
+				prefetcher: this.prefetcher,
 				alsoConfirm: () => {
 					const clash = collidingEntryId({
 						profileDir: this.profileDirResolved(),
@@ -3201,12 +3739,21 @@ let ShopGateway = (() => {
 						mount: hotMount,
 						unmount: hotUnmount
 					};
-					if (isUpdate) await this.liveDisableIds(priorEntryIds);
+					if (isUpdate) await this.liveEntriesDown(priorEntryIds);
 					const result = await hot.mount({ plugin: (plugin, config) => this.ctx.plugin(plugin, config) }, this.profileDirResolved(), args.name);
-					return result.ok ? { needsRestart: false } : {
-						needsRestart: true,
-						restartReason: result.reason ?? void 0
+					if (!result.ok) return {
+						activation: "restart",
+						...result.reason !== null ? { restartReason: result.reason } : {}
 					};
+					const activation = activationOf({
+						hostLive: true,
+						clientLive: false,
+						hasClientHalf: priorClientHalf || this.packageHasClientHalf(args.name)
+					});
+					return activation === "restart" ? {
+						activation,
+						restartReason: "client-half"
+					} : { activation };
 				}
 			});
 			if (entry.source === "github") {
@@ -3221,24 +3768,27 @@ let ShopGateway = (() => {
 			this.evictFinishedInstalls();
 			return {
 				ok: true,
-				installId: running.installId
+				installId: running.installId,
+				state: running.status().state
 			};
 		}
 		/** Bound retained finished records at MAX_FINISHED_INSTALLS, evicting the
-		* oldest finished ones (insertion order, oldest first). Running records
-		* are never evicted; an id absent from the map reports `found: false`. */
+		* oldest finished ones (insertion order, oldest first). Live records —
+		* running AND queued — are never evicted; an id absent from the map reports
+		* `found: false`. */
 		evictFinishedInstalls() {
 			const finishedIds = [];
 			for (const id of this.installOrder) {
 				const record = this.installs.get(id);
-				if (record !== void 0 && record.status().state !== "running") finishedIds.push(id);
+				if (record !== void 0 && isTerminalInstallState(record.status().state)) finishedIds.push(id);
 			}
 			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. */
+		/** Whether any command this gateway started is still running — or still
+		* waiting its turn. */
 		hasRunningCommand() {
-			for (const record of this.installs.values()) if (record.status().state === "running") return true;
+			for (const record of this.installs.values()) if (!isTerminalInstallState(record.status().state)) return true;
 			return false;
 		}
 		/** Poll one install's progress (§7.2); unknown ids report `found: false`. */
@@ -3371,17 +3921,21 @@ let ShopGateway = (() => {
 			};
 			const installedEntry = named.find((entry) => installedSpecMatches(entry, spec));
 			const priorEntryIds = this.ownedEntryIdsOrNone(args.name);
+			const hadClientHalf = this.packageHasClientHalf(args.name);
 			const running = startUninstall({
 				profile: this.profile,
 				name: args.name,
 				dshBin: this.dshBin,
 				expectedName: args.name,
 				afterDone: async () => {
-					await (this.hot ?? {
-						mount: hotMount,
-						unmount: hotUnmount
-					}).unmount(args.name) || await this.liveDisableIds(priorEntryIds);
-					return { needsRestart: false };
+					return { activation: activationOf({
+						hostLive: await (this.hot ?? {
+							mount: hotMount,
+							unmount: hotUnmount
+						}).unmount(args.name) || await this.liveEntriesDown(priorEntryIds),
+						clientLive: true,
+						hasClientHalf: hadClientHalf
+					}) };
 				}
 			});
 			const pins = readRepoPins(this.pinFs, this.pinsPath());
@@ -3411,18 +3965,10 @@ let ShopGateway = (() => {
 				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"
-			};
-			if (detectSupervisor(this.env, { ppid: this.ppid }) === "systemd" && !this.allowRestartConfigured()) return {
+			const blocked = this.staticRestartBlock();
+			if (blocked !== null) return {
 				ok: false,
-				detail: "dsh-plugin-shop: restart is disabled because this process is a systemd service — a restart would kill the takeover helper along with the unit, and the service would not come back. Set allowRestart: true in the shop row config to override."
-			};
-			const portIndex = this.restartArgv.indexOf("--port");
-			if (portIndex !== -1 && this.restartArgv[portIndex + 1] === "0") return {
-				ok: false,
-				detail: "dsh-plugin-shop: restart is not supported when dsh was launched with --port 0; restart dsh manually"
+				detail: RESTART_BLOCKED_DETAIL[blocked]
 			};
 			try {
 				const { cacheDir } = this.rowConfig();
@@ -3460,7 +4006,7 @@ let ShopGateway = (() => {
 				installed,
 				latest,
 				outdated: latest !== null && lt(installed, latest),
-				restartSupported: this.restartPlatformSupported() && (detectSupervisor(this.env, { ppid: this.ppid }) === null || this.allowRestartConfigured())
+				restartBlocked: this.staticRestartBlock()
 			};
 		}
 		/** Update the shop itself to a published version (§7.3): the explicit pin
@@ -3476,14 +4022,16 @@ let ShopGateway = (() => {
 				profile: this.profile,
 				spec: `dsh-plugin-shop@${args.version}`,
 				dshBin: this.dshBin,
-				expectedName: "dsh-plugin-shop"
+				expectedName: "dsh-plugin-shop",
+				prefetcher: this.prefetcher
 			});
 			this.installs.set(running.installId, running);
 			this.installOrder.push(running.installId);
 			this.evictFinishedInstalls();
 			return {
 				ok: true,
-				installId: running.installId
+				installId: running.installId,
+				state: running.status().state
 			};
 		}
 	};