fix(installer): recover Windows installs with a private pnpm home

README.md

@@ -456,6 +456,33 @@ It installs what is missing (Node.js, pnpm, Pi, Gentle Shell) and updates an exi
 - **Latest release** (recommended): the published Gentle Shell with its pinned Gentle AI binary.
 - **Latest main**: development builds of Gentle Shell and Gentle AI from the latest commit of `main`, built on your computer with Go. If your Go is missing, older or its version cannot be checked, the installer downloads its own pinned, verified Go only for that build.
 
+**Windows 11: `untrusted-pnpm-home` / “pnpm home folder”.** This means another
+account (possibly an unresolved SID from an old account or a sandbox) can modify
+`PNPM_HOME` or one of its parent folders. Do not disable the permission check or
+remove your own account's access. To install separately without changing the old
+folder's permissions or deleting its packages, close the wizard and run from
+PowerShell in this checkout:
+
+```powershell
+.\scripts\bootstrap.cmd --private-pnpm-home
+```
+
+If the current pnpm folder fails the check, this option selects
+`%USERPROFILE%\.pnpm` instead. If that folder is already occupied without the
+installer's marker (including `bin` or `tmp` left by earlier checks), it leaves
+it untouched and tries `%USERPROFILE%\.gentle-shell-pnpm` once. The selected
+folder must also pass the permission check and be absent, empty, or previously
+created by this installer. Version checks and their caches use the bootstrap's
+disposable folder until you confirm, not the selected installation folder. Review the new
+plan before confirming: it uses `pnpm setup --force` to save the new `PNPM_HOME`
+in your Windows user environment and add its `bin` to your user PATH. Existing
+global packages stay in the old folder and are **not migrated**; reinstall any
+you still need in the new home. The rejected pnpm folder and its subfolders are
+excluded from the installer's own PATH, so an old `gentle-shell` or `pi` there
+is not reused, updated, or mistaken for an unmanaged installation in the new
+home. Other PATH entries (including unrelated manual installations) are kept.
+Open a new terminal after installation.
+
 <details>
 <summary><kbd>More</kbd> <strong>How the installer treats the tools you already have</strong> — what it reuses, updates, or leaves alone</summary>
 

docs/install-wizard.md

@@ -1466,12 +1466,61 @@ yet (held to the strict depth-0 mask).
 | Not set: `%LOCALAPPDATA%\pnpm` | Passes | Used as before; the plan is unchanged. |
 | Not set: `%LOCALAPPDATA%\pnpm` | Fails, and nothing is installed there | `%USERPROFILE%\.pnpm` is used, if it passes the walk too. |
 | Not set: `%LOCALAPPDATA%\pnpm` | Fails, and something is installed there | Blocked: `untrusted-pnpm-home`. |
+| Explicit `--private-pnpm-home` option; configured/default folder holds files or is set by the user | Fails | Leave that folder unchanged and use the checked `%USERPROFILE%\.pnpm` instead. |
 | Any | The walk cannot finish (policy, PowerShell) | Blocked: `unknown-tool` for `pnpmHome`. |
 
+To recover from `untrusted-pnpm-home` on Windows 11 without changing the old
+folder's ACLs or removing existing packages, close the wizard and run from the
+checkout in PowerShell:
+
+```powershell
+.\scripts\bootstrap.cmd --private-pnpm-home
+```
+
+The bootstrap accepts only that optional switch and sets
+`GENTLE_INSTALL_PRIVATE_PNPM_HOME=1` for its children. The decision still checks
+the configured/default folder first and keeps it when safe. Only when it fails
+does this explicit option allow selecting the same checked private folder even
+if the old home was configured by the user or already holds files. When `.pnpm`
+is occupied and unmarked, the option leaves it intact and tries exactly one
+alternative, `%USERPROFILE%\.gentle-shell-pnpm`, under the same permission and
+marker checks. This also recovers a folder containing only `bin`, `tmp` or
+Node compile caches from earlier checks without pretending those files prove
+installer ownership. If both candidates are occupied and unmarked, or the
+selected candidate fails its walk, installation still blocks. No package is
+copied or migrated, and an unavailable ACL check still blocks. No installation
+folder is created before consent. A case-insensitive `Pnpm_Home` environment key is removed before the
+selected `PNPM_HOME` is passed to children, so only one spelling remains.
+The same decision excludes PATH entries at or beneath the rejected pnpm home
+from both the probe and standard runner environments. Windows case, trailing
+separators, quoted entries and normalized `..` segments are handled without
+matching sibling names such as `pnpm-other`. This prevents an old pnpm-owned
+`gentle-shell` or `pi` from being seen on PATH while absent from the new home's
+global listing, then being misclassified as unmanaged. The old programs are
+not executed, updated, removed, or adopted. The caller's PATH and unrelated
+manual/npm installations remain unchanged; genuinely unmanaged commands
+elsewhere still block. The review discloses this isolation before consent.
+
+The private decision and plan record `replaceEnvironment: true` only for this
+explicit option. The review explains that `pnpm setup --force` will replace an
+existing Windows **user** `PNPM_HOME` and update the user PATH after consent.
+Without this option, normal `pnpm setup` still refuses conflicting settings.
+
 A blocked decision (`untrusted-pnpm-home`, or `unknown-tool` for `pnpmHome`)
 runs no probe at all: the node probe would otherwise run the user's npm with
 that PNPM_HOME's `bin` first on PATH. The plan then holds only that blocker.
 
+For a selected private folder without the exact ownership marker, **all**
+probe subprocesses (including the internal npm/shim checks) get scratch
+`PNPM_HOME`, XDG folders, npm cache, TEMP and TMP under the already-private
+bootstrap tools directory; Node's compile cache is disabled. Even `--version`
+can otherwise create `bin` or temporary caches. Global package listing is
+skipped for both absent and empty unclaimed homes, not just absent ones. A
+refresh or the pre-consent re-inventory therefore leaves the selected home
+unchanged. Missing bootstrap scratch storage fails closed rather than running
+against the unclaimed home. Once the runner has claimed and marked the folder
+after consent, fresh probes list its real packages normally.
+
 "Nothing is installed" has one exact meaning: `%LOCALAPPDATA%\pnpm` does not
 exist, or it is a real directory (not a link) with no entries at all. Any
 entry, even an empty `store` folder or a pnpm config file, counts as an
@@ -1488,8 +1537,9 @@ The plan says all of this before consent: the default folder, the account
 folder, and that `pnpm setup` will save `PNPM_HOME=%USERPROFILE%\.pnpm` and
 add `%USERPROFILE%\.pnpm\bin` to the user PATH for new terminals. A blocker
 names the same folder, account and rights, plus the remedy: remove that
-account's write access, or set PNPM_HOME to a private folder such as
-`%USERPROFILE%\.pnpm` and reinstall the global pnpm packages there.
+account's write access and check again, or restart the checkout bootstrap with
+`--private-pnpm-home` to install separately in `%USERPROFILE%\.pnpm`.
+Reinstall any other global packages you need there; the old packages are not migrated.
 
 After consent the runner's first step, `prepare-pnpm-home`, claims the private
 folder before any pnpm command could create it with inherited permissions. It
@@ -1515,8 +1565,10 @@ to `HKCU\Environment` as `PNPM_HOME`, then puts `%PNPM_HOME%\bin` first in the
 user Path (`addDirToWindowsEnvPath`). The runner gives `pnpm setup` the
 private PNPM_HOME, and runs it even for an update, which otherwise keeps the
 PATH its installation already uses. A registry `PNPM_HOME` that already holds
-another value makes `pnpm setup` fail with `ERR_PNPM_BAD_ENV_FOUND` instead of
-overwriting it. The native Windows tests check the decision, the claim and the
+another value makes normal `pnpm setup` fail with `ERR_PNPM_BAD_ENV_FOUND`
+instead of overwriting it. The explicitly opted-in private-home plan uses
+`pnpm setup --force` to authorize that replacement after consent. The native
+Windows tests check the decision, the claim and the
 probe. No test runs `pnpm setup` against a real user registry: the registry
 write is pnpm's own behavior, read from the pnpm 11.1.1 package source.
 

scripts/bootstrap.cmd

@@ -1,5 +1,12 @@
 @echo off
 setlocal DisableDelayedExpansion
+rem Explicit opt-in only; never silently replace the user's configured pnpm home.
+set "GENTLE_INSTALL_PRIVATE_PNPM_HOME="
+if "%~1"=="" goto bootstrap
+if /i not "%~1"=="--private-pnpm-home" goto usage
+if not "%~2"=="" goto usage
+set "GENTLE_INSTALL_PRIVATE_PNPM_HOME=1"
+:bootstrap
 rem Trusted extracted/checkout bundle only. Never pipe a remote script here.
 rem Fixed stock PowerShell commands; paths are environment DATA, not PS source.
 rem Each invocation is below CMD's logical command length limit.
@@ -237,6 +244,10 @@ rem through reparse points. A removal problem never fails the installation.
   "if ([Console]::IsErrorRedirected) { $bytes = [Text.Encoding]::UTF8.GetBytes($message + [Environment]::NewLine); $stderr = [Console]::OpenStandardError(); $stderr.Write($bytes, 0, $bytes.Length); $stderr.Flush() } else { [Console]::Error.WriteLine($message) }; exit 1 } }"
 endlocal & exit /b 0
 
+:usage
+>&2 echo Usage: scripts\bootstrap.cmd [--private-pnpm-home]
+endlocal & exit /b 1
+
 :unavailable
 >&2 echo Bootstrap: stock Windows PowerShell is unavailable. No acquisition attempted.
 :failed

scripts/installer-preflight.mjs

@@ -274,7 +274,8 @@ export function planPreflight(inventory, { channel = "release" } = {}) {
 	if (home?.available === true && home.source === "private" && typeof home.path === "string" && typeof home.rejected?.path === "string") {
 		const finding = Object.fromEntries(["check", "at", "sid", "account", "rights"]
 			.filter((key) => typeof home.rejected[key] === "string").map((key) => [key, home.rejected[key]]));
-		tools.pnpmHome = { status: "private", path: home.path, default: home.rejected.path, finding };
+		tools.pnpmHome = { status: "private", path: home.path, default: home.rejected.path, finding,
+			...(home.replaceEnvironment === true ? { replaceEnvironment: true } : {}) };
 	}
 	// Windows only (S6 notice, never a blocker): reused tools whose folders another
 	// account can change, from the inventory's one `folders` walk. Only tools this

scripts/installer-probes.mjs

@@ -21,7 +21,7 @@ import {
 	succeeded,
 	windowsInvocation,
 } from "./installer-runner.mjs";
-import { verifyWindowsStorage, verifyWindowsStorageMany } from "./installer-windows.mjs";
+import { privatePnpmHome, verifyWindowsStorage, verifyWindowsStorageMany } from "./installer-windows.mjs";
 
 // Real host probes for collectInventory. Every effect goes through injected
 // adapters; probes only run fixed read-only argv (`--version`, `go version`,
@@ -205,9 +205,30 @@ export function createProbes({ platform, env, run, fs, home, verifyGentleAi = pa
 	storageMany = platform === "win32" ? (files) => verifyWindowsStorageMany(files, env) : null, pnpmHome = null }) {
 	const path = pathOf(platform);
 	const user = userEnvironment({ platform, env });
+	const roots = bootstrapRoots({ platform, env });
 	const globalBin = pnpmGlobalBin({ platform, env: user });
 	// pnpm 11 global commands need `$PNPM_HOME/bin` on PATH, as in the runner.
 	const privateHome = platform === "win32" && pnpmHome?.source === "private";
+	const unclaimedPrivateHome = async () => privateHome &&
+		(await fs.readText(path.join(globalBin.pnpmHome, privatePnpmHome.marker)).catch(() => null)) !== privatePnpmHome.text;
+	if (privateHome) {
+		// Even --version can create caches or PNPM_HOME/bin. Until consent and
+		// the private claim, redirect EVERY subprocess (including npmInvocation's
+		// internal probes) into the bootstrap's already-private disposable root.
+		const execute = run;
+		const tools = roots[0];
+		run = async (command, argv, options = {}) => {
+			if (!(await unclaimedPrivateHome())) return execute(command, argv, options);
+			if (!tools) throw new Error("Private Windows probe storage unavailable");
+			const kept = Object.fromEntries(Object.entries(options.env ?? env).filter(([key]) =>
+				!/^(?:PNPM_HOME|TEMP|TMP|XDG_CONFIG_HOME|XDG_CACHE_HOME|XDG_STATE_HOME|XDG_DATA_HOME|NPM_CONFIG_CACHE|NODE_COMPILE_CACHE|NODE_DISABLE_COMPILE_CACHE)$/i.test(key)));
+			return execute(command, argv, { ...options, env: { ...kept,
+				PNPM_HOME: path.join(tools, "probe-pnpm-home"), TEMP: tools, TMP: tools, NODE_DISABLE_COMPILE_CACHE: "1",
+				XDG_CONFIG_HOME: path.join(tools, "probe-config"), XDG_CACHE_HOME: path.join(tools, "probe-cache"),
+				XDG_STATE_HOME: path.join(tools, "probe-state"), XDG_DATA_HOME: path.join(tools, "probe-data"),
+				NPM_CONFIG_CACHE: path.join(tools, "probe-npm-cache") } });
+		};
+	}
 	const child = globalBin ? childEnvironment(env, platform, globalBin, { privateHome }) : env;
 	const userChild = globalBin ? childEnvironment(user, platform, globalBin, { privateHome }) : user;
 	/** Every file passes the storage walk; any failure means it is not usable. */
@@ -226,7 +247,6 @@ export function createProbes({ platform, env, run, fs, home, verifyGentleAi = pa
 		return succeeded(result) && result.truncated !== true ? String(result.stdout ?? "").trim() : null;
 	};
 	const persistentOn = async (name) => (await lookPath(name, user, platform, fs)) !== null;
-	const roots = bootstrapRoots({ platform, env });
 	const marker = platform === "win32" ? new RegExp(BOOTSTRAP_TOOLS.source, "i") : BOOTSTRAP_TOOLS;
 	/** A file inside the bootstrap's temporary tools directory. */
 	const fromBootstrap = (file) => path.isAbsolute(file) && (roots.some((root) => contains(root, file, platform)) ||
@@ -235,9 +255,9 @@ export function createProbes({ platform, env, run, fs, home, verifyGentleAi = pa
 	let listing;
 	/** Output of the single `list -g` call, or null when it is unavailable. */
 	const globalListing = () => (listing ??= (async () => {
-		// A private PNPM_HOME this run has not created yet holds nothing; listing it
-		// could make pnpm create it, unprotected, before consent.
-		if (privateHome && globalBin && !(await fs.exists(globalBin.pnpmHome))) return "[]";
+		// Absent AND empty unclaimed private homes hold no packages. Never run
+		// pnpm list there: it creates bin/config/cache before the ownership marker.
+		if (await unclaimedPrivateHome()) return "[]";
 		const pnpm = globalBin ? await pnpmInvocation(env, platform, fs) : null;
 		if (!pnpm) return null;
 		return output(pnpm.command, [...pnpm.prefix, "list", "-g", "--depth", "0", "--json"], child, deadlines.list);

scripts/installer-runner.mjs

@@ -1080,7 +1080,10 @@ export async function runStandardInstall(request, adapters) {
 	const persistPath = !globalBin.onPath && (privateHome || (!update && !piOnly));
 	if (persistPath) {
 		steps.push(["persist-path", async () => {
-			const result = await adapters.run(pnpm.command, [...pnpm.prefix, "setup"], { env: child, deadlineMs: deadlines.setup, stderrTail: 4096 });
+			// Only the explicit private-home plan authorizes replacing an existing
+			// HKCU PNPM_HOME; normal setup still refuses conflicting settings.
+			const force = privateHome && request.plan.tools.pnpmHome.replaceEnvironment === true;
+			const result = await adapters.run(pnpm.command, [...pnpm.prefix, "setup", ...(force ? ["--force"] : [])], { env: child, deadlineMs: deadlines.setup, stderrTail: 4096 });
 			if (succeeded(result)) return true;
 			setupDetail = outputDetail(result);
 			return false;