gentle-pi 3.7.0 → 4.1.0

package/scripts/gentle-ai-installer.mjs

@@ -13,6 +13,7 @@ import {
 	writeFile,
 } from "node:fs/promises";
 import https from "node:https";
+import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
@@ -36,19 +37,20 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "3.7.0";
+export const INSTALLER_VERSION = "4.1.1";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
 	GO_SUMDB_SOURCE_BUILD: "go-sumdb-source-build",
 });
-export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai";
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v3";
+export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai";
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v4";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.7.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.1.1`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 6dee8f833aec9e46015759c5065a9035795d9af1, the published v3.7.0 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:MQbzHlLdPklUQn0rVE9Mz94UygHsN2OPe7xMfPn9aGw=";
+// tag resolves to commit 898d3976e8049a7238eaa7de60bff325c30d2b3d, the published v4.1.1 release head.
+// v4.0.0 moved the Go module path to the /v4 major-version suffix.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:+WmZ2IvIOiJ8qtHa7wsjnYKNasem+PByeOZ6HIjoAL8=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -67,7 +69,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v3.7.0 digests are pinned from the published release:
+// still holds it. The v4.1.1 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -109,15 +111,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v3.7.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v4.1.1 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_3.7.0_darwin_amd64.tar.gz", "e55ff3ee06258a90e9195c0e3a593b85f6d79cc439e9e6c04b2596725120a610", "aa30a940e3b75ac218249b3f92d17afd2b972f833258e8212175a73d8e76d5bf", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.7.0_darwin_arm64.tar.gz", "66eb5740c4506cb2cfd1cc5207439c61cfe07678854f4ac7c83027a95a0e666a", "ca726cf3f9a523dc0112aa113beb634cda389e8b47edc5851254c32979bee89e", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.7.0_linux_amd64.tar.gz", "a730a61a43758f04cc9a4ac644945cc0e8652a1e33d6997a0a3d3f0044d2fff5", "002d09fd2b9628a29986a660c1f51f8a5042ff7fd54c8ab15b7b27de96c6cccc", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.7.0_linux_arm64.tar.gz", "a3a3d3a974f3d9b67d935fe9e306ae83c305da4ec1baed4a5319c10b044cd0eb", "e29546c51d8d65528bf565239ed3fc174da73c5fa3e861e64f20f84b16f28f26", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_4.1.1_darwin_amd64.tar.gz", "f2e9aebfba3056e88a8d7c7193e4e8c04282dc126d5eaa2216bc807deadecffd", "82351dd86bf7323c6a5b9e9e68b3cc2893a65a4df04fbdf1ef1801cabf5d2338", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.1.1_darwin_arm64.tar.gz", "8093dced37130cb26534d81663013f81d9039342e33f00b8c85aa5319aa7eea9", "6362e3641b87ae2b41a8dd7695dad4cf47457ee86c9f63792e474476bfdb6b6a", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.1.1_linux_amd64.tar.gz", "57869ebcdba5ba9942493ab413bbc15d146e2451c4dca3eaafcf163fcbd646b4", "7c638c8467efc7036e0ec6b8a1d9080a5e9a64f7ae6cbc6074fce577f789b7fe", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.1.1_linux_arm64.tar.gz", "5f8fa38573eea0f2110902f0996aa0b008aac58dc0f9a6abbdf301dcbc93f4eb", "76a36a73d6905a16221496ffe9a193bd79e17951463d711cd03abf370349ef55", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,
@@ -193,16 +195,32 @@ export async function downloadGentleAiAsset(url, destination, maxBytes = MAX_DOW
 	const downloadOnce = async () => {
 		const response = await responseFor(url, redirects), contentLength = Number(response.headers["content-length"] ?? "0");
 		if (!Number.isSafeInteger(contentLength) || contentLength < 0 || contentLength > maxBytes) { response.resume(); throw new Error("Gentle AI download exceeds the maximum allowed size"); }
-		await new Promise((resolve, reject) => {
-			const output = createWriteStream(destination, { flags: "wx", mode: 0o600 }); let received = 0, settled = false;
-			let timer = setTimeout(() => response.destroy(downloadTimeoutError("body")), bodyTimeoutMs);
-			const finish = (callback, value) => { if (!settled) { settled = true; clearTimeout(timer); callback(value); } };
-			const fail = (error) => { response.destroy(); output.destroy(); finish(reject, error); };
-			const reset = () => { clearTimeout(timer); timer = setTimeout(() => response.destroy(downloadTimeoutError("body")), bodyTimeoutMs); };
-			response.on("data", (chunk) => { reset(); received += chunk.length; if (received > maxBytes) response.destroy(new Error("Gentle AI download exceeds the maximum allowed size")); });
-			response.on("error", fail); response.setTimeout?.(bodyTimeoutMs, () => response.destroy(downloadTimeoutError("body")));
-			output.on("error", fail); output.on("finish", () => finish(resolve)); response.pipe(output);
-		});
+		let created = false;
+		try {
+			await new Promise((resolve, reject) => {
+				const output = createWriteStream(destination, { flags: "wx", mode: 0o600 }); let received = 0, settled = false;
+				output.on("open", () => { created = true; });
+				let timer = setTimeout(() => response.destroy(downloadTimeoutError("body")), bodyTimeoutMs);
+				// The exclusive open is asynchronous, so a failed attempt may settle the
+				// download before its destination stream finished with the filesystem. Wait
+				// for that stream to close first: otherwise a late creation outlives the
+				// retry's removal of the destination and the next exclusive open fails with
+				// EEXIST instead of reporting the timeout that caused the retry.
+				const closed = () => new Promise((done) => { if (output.closed) done(); else output.on("close", done); });
+				const finish = (callback, value) => { if (settled) return; settled = true; clearTimeout(timer); void closed().then(() => callback(value)); };
+				const fail = (error) => { response.destroy(); output.destroy(); finish(reject, error); };
+				const reset = () => { clearTimeout(timer); timer = setTimeout(() => response.destroy(downloadTimeoutError("body")), bodyTimeoutMs); };
+				response.on("data", (chunk) => { reset(); received += chunk.length; if (received > maxBytes) response.destroy(new Error("Gentle AI download exceeds the maximum allowed size")); });
+				response.on("error", fail); response.setTimeout?.(bodyTimeoutMs, () => response.destroy(downloadTimeoutError("body")));
+				output.on("error", fail); output.on("finish", () => finish(resolve)); response.pipe(output);
+			});
+		} catch (error) {
+			// A failed attempt removes only the file it created, once its stream closed, so
+			// the retry starts from a free destination path. A path this download never
+			// owned is left alone instead of being deleted with it.
+			if (created) await rm(destination, { force: true });
+			throw error;
+		}
 	};
 	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) try { if (attempt > 1) await rm(destination, { force: true }); await downloadOnce(); return; } catch (error) {
 		if (attempt === maxAttempts || !isRetryableDownloadError(error)) throw error;
@@ -402,7 +420,7 @@ async function safeRemoveDirectory(path) {
 	try {
 		const details = await lstat(path);
 		if (!details.isDirectory() || details.isSymbolicLink()) throw new Error("not a real directory");
-		await rm(path, { recursive: true, force: true });
+		await rm(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
 	} catch (error) { if (!(error && typeof error === "object" && error.code === "ENOENT")) throw error; }
 }
 
@@ -567,7 +585,7 @@ async function recoverInterruptedPublication(runtimeRoot, bundleIsValid, options
 	const live = versionBundlePath(runtimeRoot);
 	const liveExists = await realBundleDirectory(live, runtimeRoot, "live bundle");
 	if (!liveExists) {
-		try { await (options.rename ?? rename)(backup, live); }
+		try { await renameWithWindowsPublicationRetry(backup, live, options); }
 		catch (error) { throw bundleRecoveryError(runtimeRoot, `could not restore valid backup ${backup}: ${error instanceof Error ? error.message : String(error)}`); }
 		return;
 	}
@@ -584,21 +602,43 @@ async function cleanupStaleStagingBundles(runtimeRoot) {
 	}
 }
 
+// Windows publication can lose a race with the just-executed gentle-ai.exe or a
+// real-time scanner still holding the staging directory. Retry only those lock
+// codes, and only on the effective win32 platform, so a permanent failure still
+// surfaces as the original error instead of a successful install.
+const WINDOWS_PUBLICATION_RETRY_DELAYS_MS = [200, 400, 800, 1600];
+
+function isRetryableWindowsPublicationLock(error) {
+	return Boolean(error && typeof error === "object" && ["EPERM", "EBUSY", "EACCES"].includes(error.code));
+}
+
+async function renameWithWindowsPublicationRetry(from, to, options) {
+	const renameFile = options.rename ?? rename;
+	if ((options.platform ?? process.platform) !== "win32") return renameFile(from, to);
+	for (let attempt = 0; attempt <= WINDOWS_PUBLICATION_RETRY_DELAYS_MS.length; attempt += 1) {
+		try { return await renameFile(from, to); }
+		catch (error) {
+			if (attempt === WINDOWS_PUBLICATION_RETRY_DELAYS_MS.length || !isRetryableWindowsPublicationLock(error)) throw error;
+			await new Promise((resolve) => setTimeout(resolve, WINDOWS_PUBLICATION_RETRY_DELAYS_MS[attempt]));
+		}
+	}
+}
+
 async function publishBundle(runtimeRoot, stagingDirectory, options) {
-	const versionDirectory = join(runtimeRoot, `v${INSTALLER_VERSION}`), renameFile = options.rename ?? rename;
+	const versionDirectory = join(runtimeRoot, `v${INSTALLER_VERSION}`);
 	const backupDirectory = join(runtimeRoot, `.v${INSTALLER_VERSION}.backup-${process.pid}-${Date.now()}`);
 	let movedPrior = false;
 	try {
 		try {
 			const current = await lstat(versionDirectory);
 			if (!current.isDirectory() || current.isSymbolicLink()) throw new Error("Gentle AI package-local version directory must be a real directory");
-			await renameFile(versionDirectory, backupDirectory);
+			await renameWithWindowsPublicationRetry(versionDirectory, backupDirectory, options);
 			movedPrior = true;
 		} catch (error) { if (!(error && typeof error === "object" && error.code === "ENOENT")) throw error; }
-		await renameFile(stagingDirectory, versionDirectory);
+		await renameWithWindowsPublicationRetry(stagingDirectory, versionDirectory, options);
 	} catch (error) {
 		if (movedPrior) {
-			try { await renameFile(backupDirectory, versionDirectory); }
+			try { await renameWithWindowsPublicationRetry(backupDirectory, versionDirectory, options); }
 			catch (rollbackError) { throw new Error("Gentle AI bundle publication failed and rollback could not restore the prior bundle", { cause: rollbackError }); }
 		}
 		throw error;
@@ -622,31 +662,39 @@ async function installWindowsGentleAiFromGoSumdb(options, packageRoot, architect
 	return withInstallLock(packageRoot, options, async (runtimeRoot) => {
 		await cleanupStaleStagingBundles(runtimeRoot);
 		const stagingDirectory = await mkdtemp(join(runtimeRoot, `.v${INSTALLER_VERSION}.staging-`));
+		// Go builds in a short private directory under the system temp directory, never inside
+		// the package: from a deep pnpm store path (179 characters, run 38063142924) the
+		// working directories Go gives asm.exe inside GOMODCACHE exceed MAX_PATH and
+		// CreateProcess fails with "The directory name is invalid."
+		let buildDirectory = null;
 		try {
 			await chmod(stagingDirectory, 0o700);
-			const buildDirectory = join(stagingDirectory, ".build");
-			await mkdir(buildDirectory, { recursive: true, mode: 0o700 });
+			buildDirectory = await mkdtemp(join(options.temporaryDirectory ?? tmpdir(), "gai-"));
+			await chmod(buildDirectory, 0o700);
 			const goPath = await resolveWindowsGoExecutable(options);
 			const environment = sealedGoEnvironment(goPath, buildDirectory, architecture);
 			for (const directory of [environment.GOBIN, environment.GOPATH, environment.GOMODCACHE, environment.GOCACHE, environment.TEMP]) await mkdir(directory, { recursive: true, mode: 0o700 });
 			await recoverInterruptedPublication(runtimeRoot, (directory) => existingWindowsSourceBundleMatches(directory, execute, goPath, environment, architecture), options);
 			const existing = versionBundlePath(runtimeRoot);
 			if (await existingWindowsSourceBundleMatches(existing, execute, goPath, environment, architecture)) return { installed: false, binaryPath: join(existing, "gentle-ai.exe"), method: GENTLE_AI_INSTALL_METHOD.GO_SUMDB_SOURCE_BUILD };
-			await assertGoToolchain(execute, goPath, environment, stagingDirectory);
-			try { await runCommand(execute, goPath, ["install", GENTLE_AI_WINDOWS_SOURCE_PACKAGE], commandOptions(environment, stagingDirectory, GO_INSTALL_TIMEOUT_MS)); }
+			await assertGoToolchain(execute, goPath, environment, buildDirectory);
+			try { await runCommand(execute, goPath, ["install", GENTLE_AI_WINDOWS_SOURCE_PACKAGE], commandOptions(environment, buildDirectory, GO_INSTALL_TIMEOUT_MS)); }
 			catch (error) { throw new GentleAiInstallerError(GENTLE_AI_GO_INSTALL_FAILED_CODE, `Gentle AI Go SumDB source installation failed for ${GENTLE_AI_WINDOWS_SOURCE_PACKAGE}.`, error); }
 			const builtBinary = join(environment.GOBIN, "gentle-ai.exe"), binaryPath = join(stagingDirectory, "gentle-ai.exe");
 			const details = await lstat(builtBinary);
 			if (!details.isFile() || details.isSymbolicLink()) throw new GentleAiInstallerError(GENTLE_AI_GO_INSTALL_FAILED_CODE, "Gentle AI Go installation produced a non-regular gentle-ai.exe.");
 			await copyFile(builtBinary, binaryPath);
-			const metadata = await verifyGoBuildMetadata(execute, goPath, binaryPath, environment, stagingDirectory, architecture);
-			await assertExactGentleAiVersion(execute, binaryPath, environment, stagingDirectory);
+			const metadata = await verifyGoBuildMetadata(execute, goPath, binaryPath, environment, buildDirectory, architecture);
+			await assertExactGentleAiVersion(execute, binaryPath, environment, buildDirectory);
 			const binarySha256 = await sha256File(binaryPath);
 			await writeFile(join(stagingDirectory, "integrity.json"), canonicalManifest(windowsSourceManifest(metadata, binarySha256, architecture)), { mode: 0o600 });
 			await safeRemoveDirectory(buildDirectory);
 			const published = await publishBundle(runtimeRoot, stagingDirectory, options);
 			return { installed: true, binaryPath: join(published, "gentle-ai.exe"), method: GENTLE_AI_INSTALL_METHOD.GO_SUMDB_SOURCE_BUILD };
-		} finally { await safeRemoveDirectory(stagingDirectory); }
+		} finally {
+			try { if (buildDirectory !== null) await safeRemoveDirectory(buildDirectory); }
+			finally { await safeRemoveDirectory(stagingDirectory); }
+		}
 	});
 }
 

package/scripts/install-gentle-ai.mjs

@@ -8,6 +8,52 @@ import { fileURLToPath } from "node:url";
 import { INSTALLER_VERSION, installGentleAi } from "./gentle-ai-installer.mjs";
 import { installTuiModeSetting, isPiManagedInstall } from "./install-tui-mode-setting.mjs";
 
+const FAILURE_CAUSE_DEPTH = 6;
+const FAILURE_OUTPUT_TAIL = 4000;
+
+function failureOutputs(error) {
+	return ["stderr", "stdout"].map((stream) => [stream, typeof error?.[stream] === "string" ? error[stream].trimEnd() : ""]).filter(([, text]) => text.trim().length > 0);
+}
+
+function failureHeadline(error, outputs) {
+	const message = error instanceof Error ? error.message : String(error);
+	// A child-process error repeats its stderr after the first message line; it is printed below, bounded.
+	const text = outputs.length > 0 ? message.split(/\r?\n/)[0] : message;
+	const status = [
+		...(typeof error?.code === "string" || typeof error?.code === "number" ? [`code ${error.code}`] : []),
+		...(typeof error?.signal === "string" ? [`signal ${error.signal}`] : []),
+	];
+	return `${text}${status.length > 0 ? ` (${status.join(", ")})` : ""}`;
+}
+
+/**
+ * A failed installation for the postinstall's stderr: the error's message, then its
+ * `cause` chain (at most 6 deep) with each code and the last 4000 characters of any
+ * stdout/stderr a failed command left on it. When a cause carried output, the last
+ * line repeats the deepest one's last output line in `Error:` form, the line the
+ * installer wizard's one-line failure detail selects after pnpm's own summary.
+ */
+function describeGentleAiInstallFailure(error) {
+	const lines = [];
+	let rootCause = null;
+	let cause = error;
+	for (let depth = 0; cause !== undefined && cause !== null && depth <= FAILURE_CAUSE_DEPTH; depth += 1) {
+		const outputs = failureOutputs(cause);
+		const name = cause instanceof Error && typeof cause.name === "string" && cause.name !== "" ? cause.name : "Error";
+		lines.push(depth === 0 ? failureHeadline(cause, outputs) : `  caused by ${name}: ${failureHeadline(cause, outputs)}`);
+		for (const [stream, text] of outputs) {
+			const tail = text.length > FAILURE_OUTPUT_TAIL ? text.slice(-FAILURE_OUTPUT_TAIL) : text;
+			lines.push(`    ${stream}${tail === text ? "" : ` (last ${FAILURE_OUTPUT_TAIL} characters)`}:`, ...tail.split(/\r?\n/).map((line) => `    | ${line}`));
+		}
+		// stderr first: a deeper cause's output replaces a shallower one's.
+		if (outputs.length > 0) rootCause = outputs[0][1].split(/\r?\n/).findLast((line) => line.trim().length > 0).trim();
+		cause = cause instanceof Error ? cause.cause : undefined;
+	}
+	if (cause !== undefined && cause !== null) lines.push("  ... further causes omitted");
+	if (rootCause !== null) lines.push(`  root cause Error: ${rootCause}`);
+	return lines.join("\n");
+}
+
 if (process.env.GENTLE_PI_SKIP_GENTLE_AI_INSTALL === "1") {
 	console.warn("GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1: skipped package-local Gentle AI installation; native review operations will fail with package-local-binary-missing until gentle-pi is reinstalled.");
 } else {
@@ -15,7 +61,8 @@ if (process.env.GENTLE_PI_SKIP_GENTLE_AI_INSTALL === "1") {
 		const result = await installGentleAi();
 		console.log(`Gentle AI v${INSTALLER_VERSION} ${result.installed ? "installed" : "integrity-verified"} at ${result.binaryPath}`);
 	} catch (error) {
-		console.error(`gentle-pi could not install its package-local Gentle AI v${INSTALLER_VERSION} binary: ${error instanceof Error ? error.message : String(error)}`);
+		// The whole cause chain: the failing command's own output is the diagnosis.
+		console.error(`gentle-pi could not install its package-local Gentle AI v${INSTALLER_VERSION} binary: ${describeGentleAiInstallFailure(error)}`);
 		process.exitCode = 1;
 	}
 }

package/scripts/install-tui-mode-setting.mjs

@@ -65,6 +65,15 @@ function sameFile(left, right) {
 	return left && right && left.dev === right.dev && left.ino === right.ino;
 }
 
+// A path's lstat against the fstat of the handle just opened on it. On recent
+// Windows, lstat by path reports dev 0 (no volume serial) while fstat reports
+// the volume's (#1258, #2109): there the file index alone identifies it, and a
+// known dev must still match. POSIX keeps the full device and inode check.
+export function sameOpenedFile(pathStat, handleStat, platform = process.platform) {
+	if (platform !== "win32" || !pathStat || !handleStat || (pathStat.dev !== 0 && handleStat.dev !== 0)) return Boolean(sameFile(pathStat, handleStat));
+	return pathStat.ino === handleStat.ino;
+}
+
 function assertDirectories(paths) {
 	for (const path of paths) {
 		const stat = inspect(path);
@@ -80,7 +89,7 @@ function readSettings(path) {
 	if (!before.isFile() || before.isSymbolicLink()) throw new Error("settings.json must be a regular, non-symlink file");
 	const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
 	try {
-		if (!sameFile(before, fstatSync(fd))) throw new Error("settings.json changed while opening");
+		if (!sameOpenedFile(before, fstatSync(fd))) throw new Error("settings.json changed while opening");
 		const text = readFileSync(fd, "utf8");
 		const value = JSON.parse(text.replace(/^\uFEFF/, ""));
 		if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("settings.json must contain a JSON object");

package/scripts/install-wizard-preview.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Development preview for the browser installation wizard.
+//
+// Starts the REAL local host (createInstallerServer) with the real assets, but
+// with fake inventories and a fake runner: it never runs host probes, package
+// managers, downloads or installs. Use it to develop and visually check the UI:
+//
+//   node scripts/install-wizard-preview.mjs --scenario=terminal --step-ms=600
+//
+// Then open the printed one-time session URL. Not part of the installer entry.
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { planPreflight, requirements } from "./installer-preflight.mjs";
+import { createInstallerServer } from "./installer-server.mjs";
+
+const BIN = "/home/you/.local/share/pnpm/bin";
+const baseInventory = Object.freeze({
+	platform: "linux",
+	arch: "x64",
+	node: { available: true, version: "24.21.0", usable: true, persistent: true, npm: true },
+	pnpm: { available: true, version: "11.1.1", usable: true, compatible: true, persistent: true },
+	pi: { available: false },
+	shell: { available: false },
+	gentleAi: { available: false },
+	go: { available: false },
+	globalBin: { available: true, path: BIN, writable: true, onPath: true },
+	setup: false,
+});
+// A machine that only has the bootstrap's temporary Node and pnpm, with no pnpm bin on PATH.
+const freshInventory = Object.freeze({
+	...baseInventory,
+	node: { available: true, version: "24.21.0", usable: true, persistent: false, npm: false },
+	pnpm: { available: true, version: "11.1.1", usable: true, compatible: true, persistent: false },
+	globalBin: { ...baseInventory.globalBin, onPath: false },
+});
+// An earlier run installed the pinned stack, but its setup and `pnpm setup` did not finish.
+const recoveryInventory = Object.freeze({
+	...baseInventory,
+	pi: { available: true, version: "1.0.0", usable: true },
+	shell: { available: true, version: requirements.shell, usable: true, global: true },
+	gentleAi: { available: true, version: requirements.gentleAi, usable: true, compatible: true },
+	globalBin: { ...baseInventory.globalBin, onPath: false },
+	setup: { available: true, recoverable: true },
+});
+const checks = ["check-npm", "check-global-bin", "check-existing-stack"];
+const install = ["install-global", "verify-global-list", "verify-shell-bin", "verify-gentle-ai", "shell-setup"];
+const persistence = ["persist-node", "persist-package-managers", "verify-persistent-runtime", "check-npm", "configure-npm-prefix"];
+
+// Each scenario mirrors the runner's fixed step order for its plan.
+const scenarios = Object.freeze({
+	ready: { inventories: [baseInventory], steps: [...checks, ...install], result: { outcome: "ready" } },
+	terminal: {
+		inventories: [freshInventory],
+		steps: ["check-global-bin", "check-existing-stack", ...persistence, ...install, "persist-path"],
+		result: { outcome: "terminal-action-required", action: "open-new-terminal", npmPrefix: "configured" },
+	},
+	blocked: {
+		inventories: [baseInventory],
+		steps: ["check-npm", "check-global-bin"],
+		result: { outcome: "blocked", reason: "existing-stack" },
+	},
+	failed: {
+		inventories: [freshInventory],
+		steps: ["check-global-bin", "check-existing-stack", ...persistence],
+		result: { outcome: "failed", failedStep: "install-global" },
+	},
+	// The first plan goes stale before install (the PATH was fixed meanwhile): the host
+	// answers 409 plan-changed and the wizard must show the new plan and ask again.
+	"plan-changed": { inventories: [freshInventory, baseInventory], steps: [...checks, ...install], result: { outcome: "ready" } },
+	recovery: {
+		inventories: [recoveryInventory],
+		steps: ["check-npm", "check-global-bin", "check-recoverable-stack", ...install.slice(1), "persist-path"],
+		result: { outcome: "terminal-action-required", action: "open-new-terminal" },
+	},
+	preflight: {
+		inventories: [{ ...baseInventory, node: { available: true, version: "18.20.0", usable: true, persistent: true, npm: true },
+			gentleAi: { available: true, version: "1.0.0", usable: true, compatible: false } }],
+		steps: [],
+		result: { outcome: "blocked", reason: "preflight-blocked" },
+	},
+});
+export const scenarioNames = Object.freeze(Object.keys(scenarios));
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Fake collectPlan/runInstall for a scenario; nothing touches the machine. */
+export function previewScenario(name, { stepMs = 600 } = {}) {
+	const scenario = scenarios[name];
+	if (!scenario) throw new Error(`Unknown scenario "${name}". Use one of: ${scenarioNames.join(", ")}`);
+	let collected = 0;
+	return {
+		collectPlan: async () => {
+			const inventory = structuredClone(scenario.inventories[Math.min(collected, scenario.inventories.length - 1)]);
+			collected += 1;
+			await sleep(Math.min(stepMs, 400));
+			return { inventory, plan: planPreflight(inventory) };
+		},
+		runInstall: async (_request, log) => {
+			const completed = [];
+			for (const step of scenario.steps) {
+				await sleep(stepMs);
+				completed.push(step);
+				log({ step, status: "done" });
+			}
+			await sleep(stepMs);
+			const { result } = scenario;
+			if (result.outcome === "blocked") log({ step: "gate", status: "blocked", reason: result.reason });
+			if (result.outcome === "failed") log({ step: result.failedStep, status: "failed" });
+			return { ...result, completed };
+		},
+	};
+}
+
+/** Starts the real host on 127.0.0.1 with a fake scenario. Returns { host, url }. */
+export async function startPreview({ scenario = "ready", stepMs = 600, log = console.log } = {}) {
+	const fake = previewScenario(scenario, { stepMs });
+	const host = createInstallerServer({
+		assetsDir: fileURLToPath(new URL("../assets/install-wizard/", import.meta.url)),
+		collectPlan: fake.collectPlan,
+		runInstall: fake.runInstall,
+	});
+	const { url } = await host.listen();
+	log(`Gentle Shell wizard preview (scenario: ${scenario}). Fake plan and fake installer: nothing is installed.`);
+	log(`Open this one-time link (expires in 2 minutes):\n  ${url}`);
+	return { host, url };
+}
+
+function option(args, name, fallback) {
+	const found = args.find((arg) => arg.startsWith(`--${name}=`));
+	return found === undefined ? fallback : found.slice(name.length + 3);
+}
+
+async function main(args) {
+	if (args.includes("--help")) {
+		console.log(`Usage: node scripts/install-wizard-preview.mjs [--scenario=${scenarioNames.join("|")}] [--step-ms=600]`);
+		return;
+	}
+	const scenario = option(args, "scenario", "ready");
+	const stepMs = Number(option(args, "step-ms", "600"));
+	if (!scenarioNames.includes(scenario) || !Number.isFinite(stepMs) || stepMs < 0) {
+		console.error(`Use --scenario=${scenarioNames.join("|")} and a non-negative --step-ms.`);
+		process.exitCode = 2;
+		return;
+	}
+	const { host } = await startPreview({ scenario, stepMs });
+	process.once("SIGINT", () => host.close("signal"));
+	process.once("SIGTERM", () => host.close("signal"));
+	const { reason, outcome } = await host.closed;
+	console.log(`Preview closed (${reason}); last outcome: ${outcome?.outcome ?? "none"}.`);
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	await main(process.argv.slice(2));
+}