gentle-pi 4.4.0 → 4.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "4.4.0",
+	"version": "4.5.1",
 	"description": "Turn Pi into el Gentleman: an ODD development harness with focused subagents, configured TDD evidence, native review, and skill discovery.",
 	"license": "MIT",
 	"type": "module",

package/runtime/gentle-shell-bundled.mjs

@@ -574,12 +574,17 @@ export function withoutMissingBundledNpmCommand(settingsText
 
 
 
+
+
+
 // `gentle-shell update [target]` in a bundled install, read the way Pi's
 // package-manager-cli.js reads it: the target is Pi itself for a bare
 // `update`, `--self`, or a `self`/`pi` positional, and "all" for `--all`,
 // `--self --extensions` or `self`/`pi` with `--extensions`. Only Pi's own part
 // is redirected; "all" still sends `update --extensions` (with the other
-// flags) to Pi. Packages, models, help, and forms Pi refuses (conflicting or
+// flags) to Pi. `--latest` marks Pi's own part as the newest published Pi;
+// with any form that is not Pi's own update it is unknown to Pi, so it passes
+// through. Packages, models, help, and forms Pi refuses (conflicting or
 // unknown options) reach Pi unchanged.
 export function bundledUpdatePlan(passthrough          )                    {
 	const passThrough = { self: false, piArgs: passthrough };
@@ -588,8 +593,10 @@ export function bundledUpdatePlan(passthrough          )                    {
 	let self = false;
 	let extensions = false;
 	let all = false;
+	let latest = false;
 	for (const token of passthrough.slice(1)) {
 		if (token === "--self") self = true;
+		else if (token === "--latest") latest = true;
 		else if (token === "--extensions") extensions = true;
 		else if (token === "--all") all = true;
 		else if (["--approve", "-a", "--no-approve", "-na", "--force"].includes(token)) flags.push(token);
@@ -601,19 +608,21 @@ export function bundledUpdatePlan(passthrough          )                    {
 		if ((positional[0] !== "self" && positional[0] !== "pi") || self) return passThrough;
 		self = true;
 	}
-	if (all || (self && extensions)) return { self: true, piArgs: ["update", "--extensions", ...flags] };
+	const marked = latest ? { latest: true } : {};
+	if (all || (self && extensions)) return { self: true, ...marked, piArgs: ["update", "--extensions", ...flags] };
 	if (extensions) return passThrough;
-	return { self: true };
+	return { self: true, ...marked };
 }
 
-// What `gentle-shell update` does after the redirected upgrade (`upgradeCode`
-// is undefined when it did not run): with nothing left for Pi it exits with the
-// upgrade's code; otherwise Pi still runs, so `update --all` updates the
-// extensions even when the upgrade could not complete.
+// What `gentle-shell update` does after the redirected upgrade or the
+// `--latest` Pi update (`upgradeCode` is undefined when it did not run): with
+// nothing left for Pi it exits with that code; otherwise Pi still runs, so
+// `update --all` updates the extensions even when that step could not complete.
 export function bundledUpdateNext(plan                   , upgradeCode                    )                                                             {
 	if (plan.piArgs === undefined) return { exitCode: upgradeCode ?? 0 };
 	if (plan.self && upgradeCode !== undefined && upgradeCode !== 0) {
-		return { piArgs: plan.piArgs, note: "gentle-shell: the Gentle Shell upgrade did not complete; updating the extensions anyway." };
+		const step = plan.latest ? "latest Pi update" : "Gentle Shell upgrade";
+		return { piArgs: plan.piArgs, note: `gentle-shell: the ${step} did not complete; updating the extensions anyway.` };
 	}
 	return { piArgs: plan.piArgs };
 }
@@ -624,6 +633,7 @@ export function bundledUpdateNotice(input
 		input.interactive
 			? "Running 'gentle-shell upgrade'..."
 			: "Run 'gentle-shell upgrade' to install the latest Gentle Shell release and its Pi.",
+		"Run 'gentle-shell update --latest' to install the newest published Pi now, without the release's verified lockfile.",
 	];
 }
 

package/runtime/gentle-shell-launcher.mjs

@@ -1352,6 +1352,8 @@ export function helpText()         {
 		"  gentle-shell update [target]     Run pi's own 'update' against the resolved home.",
 		"                                   In a bundled install Pi ships pinned: 'update' without a package",
 		"                                   runs 'gentle-shell upgrade' instead of updating Pi.",
+		"                                   'update --latest' installs the newest published Pi instead,",
+		"                                   without the release's verified lockfile.",
 		"  gentle-shell config              Run pi's own 'config' against the resolved home.",
 		"  gentle-shell auth <command>      Run pi's own 'auth' against the resolved home.",
 		"  gentle-shell mcp <command>       Run pi's own 'mcp' (add, list, login, logout) against the",

package/scripts/bundled-install.mjs

@@ -11,7 +11,7 @@ import { posix, win32 } from "node:path";
 import { spawn } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { crc32, gunzipSync, inflateRawSync } from "node:zlib";
-import { acquireGo, artifactFor, engramPinVersion, verifiedDownload } from "./installer-downloads.mjs";
+import { acquireGo, artifactFor, engramPinVersion, uvPinVersion, verifiedDownload } from "./installer-downloads.mjs";
 import { ensureWindowsPrivateFolder, readWindowsPnpmArchive, verifyWindowsStorage } from "./installer-windows.mjs";
 
 // The acquisition pins already verified for the installer; never a second copy.
@@ -23,9 +23,30 @@ const LAUNCHER_MARK = "gentle-shell bundled launcher (generated; do not edit)";
 const LAUNCHER_MISSING = "gentle-shell: no active Gentle Shell version; run the Gentle Shell installer again.";
 const PROFILE_MARK = "# gentle-shell bundled install";
 const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const PI_PACKAGE = "@earendil-works/pi-coding-agent";
 const VERSION_ID = /^[0-9A-Za-z][0-9A-Za-z.-]*$/;
 const MAX_EXPANDED = 512 * 1024 * 1024;
 const INSTALL_TIMEOUT = 15 * 60 * 1000;
+// The gentle-stream commit the /gentle:music offer installs, as a GitHub
+// archive (no git needed); `samples` adds pyfluidsynth for the sample voices.
+export const MUSIC_PLAYER_ARCHIVE = "https://github.com/Gentleman-Programming/gentle-stream/archive/381290451544ad2ca3348a68a81b3056bdac73b7.tar.gz";
+const MUSIC_PYTHON = "3.13";
+const MUSIC_MARKER = ".gentle-shell-music";
+// uv links its tool executables on POSIX (bin/gentle-stream -> tools/…): the
+// player counts when it resolves to a regular file inside <prefix>/music.
+// The /gentle:music extension asks the same question before running it.
+export function installedMusicPlayer(layout) {
+	try {
+		const real = realpathSync(layout.gentleStream);
+		const path = pathFor(process.platform);
+		const inside = path.relative(realpathSync(layout.music), real);
+		return !inside.startsWith("..") && !path.isAbsolute(inside) && lstatSync(real).isFile();
+	} catch {
+		return false;
+	}
+}
+const musicSpec = (samples) => `gentle-stream${samples ? "[samples]" : ""} @ ${MUSIC_PLAYER_ARCHIVE}`;
 
 const pathFor = (platform) => (platform === "win32" ? win32 : posix);
 function stat(path) {
@@ -77,6 +98,12 @@ export function prefixLayout({ platform, env = {}, home, root }) {
 		// The pinned Engram (ensureEngram), given to Gentle AI and gentle-engram (S9).
 		engramDir: path.join(runtime, `engram-${engramPinVersion}`),
 		engram: path.join(runtime, `engram-${engramPinVersion}`, windows ? "engram.exe" : "engram"),
+		// Only when /gentle:music's offer is accepted (installMusicPlayer): the
+		// pinned uv, and the Python and gentle-stream it installs under music/.
+		uvDir: path.join(runtime, `uv-${uvPinVersion}`),
+		uv: path.join(runtime, `uv-${uvPinVersion}`, windows ? "uv.exe" : "uv"),
+		music: path.join(base, "music"),
+		gentleStream: path.join(base, "music", "bin", windows ? "gentle-stream.exe" : "gentle-stream"),
 		pnpmHome, store: path.join(pnpmHome, "store"), cache: path.join(pnpmHome, "cache"), state: path.join(pnpmHome, "state"),
 		config: path.join(pnpmHome, "config"), npmrc: path.join(pnpmHome, "config", "npmrc"), tmp: path.join(base, "tmp"),
 		versions: path.join(base, "versions"), history: path.join(base, "versions.history"),
@@ -412,6 +439,94 @@ export async function ensureEngram({ layout, platform, arch, env = {}, adapters
 	});
 }
 
+/** The one executable a verified uv release archive must contain: `uv` in the
+ * archive's own top folder (`uv-<target>/uv`) of the POSIX `.tar.gz`, or the
+ * top-level `uv.exe` of the Windows `.zip`. uvx, uvw and anything else are
+ * never written.
+ */
+export function uvExecutable(bytes, descriptor) {
+	const message = "uv archive rejected";
+	const url = String(descriptor?.url ?? "");
+	if (url.endsWith(".zip")) return zipMember(bytes, "uv.exe", message);
+	const stem = /\/(uv-[A-Za-z0-9_.-]+)\.tar\.gz$/.exec(url)?.[1];
+	if (!stem) throw new Error(message);
+	return tarMember(bytes, `${stem}/uv`, message);
+}
+
+/** The pinned uv in runtime/uv-<v>/, published like Engram: downloaded through
+ * verifiedDownload, only its executable written, `uv --version` run from the
+ * staging folder, marked, then published. Never part of the default install:
+ * only installMusicPlayer asks for it. Returns whether it was acquired.
+ */
+export async function ensureUv({ layout, platform, arch, env = {}, adapters = {} }) {
+	const run = adapters.run ?? runCommand;
+	const path = pathFor(process.platform);
+	const childEnv = pnpmEnvironment(layout, { platform: layout.platform, env });
+	return publishRuntime(layout, "uv", layout.uvDir, layout.uv, { platform, arch, adapters }, async (stage, bytes, descriptor) => {
+		const binary = path.join(stage, path.relative(layout.uvDir, layout.uv));
+		writeFileSync(binary, uvExecutable(bytes, descriptor), { flag: "wx", mode: 0o700 });
+		const result = await run(binary, ["--version"], { cwd: layout.runtime, env: childEnv });
+		if (result.status !== 0 || !String(result.stdout).trim().startsWith(`uv ${descriptor.version} `)) throw new Error("Bundled uv verification failed");
+	});
+}
+
+/** The environment the music player's uv runs in: its tools, their executables,
+ * the uv-managed Python 3.13 and uv's cache all under <prefix>/music; no system
+ * Python and no uv.toml are consulted. Inherited UV_*, PYTHON*, PIP_*,
+ * VIRTUAL_ENV and CONDA_PREFIX are dropped; the rest (HOME, PATH, proxies, CA
+ * settings) is kept.
+ */
+export function musicEnvironment(layout, { env = {} } = {}) {
+	const path = pathFor(layout.platform);
+	const kept = Object.fromEntries(Object.entries(env).filter(([key]) => !/^(?:uv_.*|python.*|pip_.*|virtual_env|conda_prefix)$/i.test(key)));
+	return {
+		...kept,
+		UV_TOOL_DIR: path.join(layout.music, "tools"), UV_TOOL_BIN_DIR: path.dirname(layout.gentleStream),
+		UV_PYTHON_INSTALL_DIR: path.join(layout.music, "python"), UV_PYTHON_BIN_DIR: path.join(layout.music, "python", "bin"),
+		UV_CACHE_DIR: path.join(layout.music, "cache"),
+		UV_PYTHON: MUSIC_PYTHON, UV_PYTHON_PREFERENCE: "only-managed", UV_PYTHON_DOWNLOADS: "automatic", UV_NO_CONFIG: "1",
+	};
+}
+
+/** S5: the /gentle:music offer, after the user accepted it. Publishes the
+ * pinned uv (ensureUv), then `uv tool install`s the pinned gentle-stream
+ * archive with its `samples` extra into <prefix>/music (musicEnvironment);
+ * when that fails (pyfluidsynth, which needs the system FluidSynth library),
+ * once more without the extra. A marker naming the installed spec makes a
+ * second call a no-op. `out` gets one line per step. Returns the executable,
+ * whether the extra is in, and whether anything was installed.
+ */
+export async function installMusicPlayer({ layout, platform = layout.platform, arch = process.arch, env = {}, adapters = {}, out = () => {} }) {
+	const run = adapters.run ?? runCommand;
+	const path = pathFor(process.platform);
+	const marker = path.join(layout.music, MUSIC_MARKER);
+	const done = read(marker);
+	if (installedMusicPlayer(layout) && (done === `${musicSpec(true)}\n` || done === `${musicSpec(false)}\n`)) {
+		return { gentleStream: layout.gentleStream, samples: done === `${musicSpec(true)}\n`, installed: false };
+	}
+	out(`Downloading uv ${uvPinVersion} into Gentle Shell…`);
+	await ensureUv({ layout, platform, arch, env, adapters });
+	ensureDirectory(layout.music, layout.platform);
+	const childEnv = musicEnvironment(layout, { env });
+	const install = (samples) => run(layout.uv, ["tool", "install", "--python", MUSIC_PYTHON, musicSpec(samples)], { cwd: layout.music, env: childEnv, timeout: INSTALL_TIMEOUT });
+	out(`Installing Python ${MUSIC_PYTHON} and gentle-stream; this can take a few minutes…`);
+	let samples = true;
+	let result = await install(true);
+	if (result.status !== 0) {
+		out("The samples extra could not be installed (it needs the system FluidSynth library); retrying without the samples extra…");
+		samples = false;
+		result = await install(false);
+	}
+	if (result.status !== 0 || !installedMusicPlayer(layout)) {
+		const reason = String(result.stderr ?? "").trim().split("\n").filter(Boolean).at(-1);
+		throw new Error(`uv could not install gentle-stream${reason ? `: ${reason}` : ""}`);
+	}
+	replaceAtomically(marker, (temporary) => writeFileSync(temporary, `${musicSpec(samples)}\n`, { flag: "wx", mode: 0o600 }));
+	// The downloaded wheels and archives are not needed once installed.
+	await run(layout.uv, ["cache", "clean"], { cwd: layout.music, env: childEnv, timeout: INSTALL_TIMEOUT });
+	return { gentleStream: layout.gentleStream, samples, installed: true };
+}
+
 /** Our pinned Node with its bundled npm, and pnpm, in runtime/ (and the pinned
  * Go only when `go`, the pinned Engram only when `engram`), each downloaded
  * through verifiedDownload, checked by running it from its staging folder,
@@ -670,11 +785,16 @@ function pinnedGo(layout, go) {
  * not allowed. An installed version is reused; a folder left by an interrupted
  * install of this id (its process gone) is removed and installed again; any
  * other folder is never replaced. On Windows the pinned Go is required, so
- * gentle-pi's postinstall never builds with the user's go.exe. Adapters (run,
- * and distribution for local fixture packages in place of the registry) are
+ * gentle-pi's postinstall never builds with the user's go.exe. `unverified`
+ * (`gentle-shell update --latest` only) installs without a release lockfile:
+ * none is written beforehand and pnpm resolves the exact versions itself
+ * (`--no-frozen-lockfile`, so a CI environment cannot turn it frozen; the
+ * pnpm-lock.yaml pnpm leaves behind is never read again); the installed
+ * versions are still checked exactly. Adapters (run, and
+ * distribution for local fixture packages in place of the registry) are
  * trusted local test code only.
  */
-export async function installVersion({ layout, manifest, lockfile, platform = layout.platform, env = {}, go = null, adapters = {} }) {
+export async function installVersion({ layout, manifest, lockfile, unverified = false, platform = layout.platform, env = {}, go = null, adapters = {} }) {
 	const files = (adapters.distribution ?? distributionFiles)(manifest);
 	const { shell, pi, id } = versionsOf(manifest);
 	const destination = versionDirectory(layout, id);
@@ -682,7 +802,7 @@ export async function installVersion({ layout, manifest, lockfile, platform = la
 	const marker = path.join(destination, VERSION_MARKER);
 	if (installedVersion(layout, id)) return { id, path: destination, installed: false };
 	if (platform === "win32" && !pinnedGo(layout, go)) throw new Error("A Windows version install needs the pinned Go from ensureRuntime({ go: true })");
-	if (typeof lockfile !== "string" || lockfile.length === 0) throw new Error("Release lockfile missing");
+	if (!unverified && (typeof lockfile !== "string" || lockfile.length === 0)) throw new Error("Release lockfile missing");
 	const existing = stat(destination);
 	if (existing) {
 		const pending = existing.isDirectory() ? /^installing (\S+) ([1-9]\d*)\n$/.exec(read(marker) ?? "") : null;
@@ -695,8 +815,8 @@ export async function installVersion({ layout, manifest, lockfile, platform = la
 	mkdirSync(destination, { mode: 0o700 });
 	try {
 		writeFileSync(marker, `installing ${id} ${process.pid}\n`, { flag: "wx", mode: 0o600 });
-		for (const [name, text] of Object.entries({ ...files, "pnpm-lock.yaml": lockfile })) writeFileSync(path.join(destination, name), text, { flag: "wx", mode: 0o600 });
-		const result = await (adapters.run ?? runCommand)(layout.node, [layout.pnpm, "install", "--frozen-lockfile"],
+		for (const [name, text] of Object.entries(unverified ? files : { ...files, "pnpm-lock.yaml": lockfile })) writeFileSync(path.join(destination, name), text, { flag: "wx", mode: 0o600 });
+		const result = await (adapters.run ?? runCommand)(layout.node, [layout.pnpm, "install", unverified ? "--no-frozen-lockfile" : "--frozen-lockfile"],
 			{ cwd: destination, env: pnpmEnvironment(layout, { platform, env, go }), timeout: INSTALL_TIMEOUT });
 		// pnpm prints install and postinstall failures on stdout: keep both tails.
 		if (result.status !== 0) {
@@ -704,7 +824,7 @@ export async function installVersion({ layout, manifest, lockfile, platform = la
 				{ stderr: [String(result.stdout ?? "").slice(-6000), String(result.stderr ?? "").slice(-4000)].filter(Boolean).join("\n") });
 		}
 		const shellDirectory = installedPackage(destination, "gentle-pi", shell, "gentle-pi");
-		installedPackage(destination, "@earendil-works/pi-coding-agent", pi, "Pi");
+		installedPackage(destination, PI_PACKAGE, pi, "Pi");
 		if (!regular(path.join(shellDirectory, "bin", "gentle-shell.mjs"))) throw new Error("Installed gentle-pi has no launcher entry");
 		replaceAtomically(marker, (temp) => writeFileSync(temp, `${id}\n`, { flag: "wx", mode: 0o600 }));
 		return { id, path: destination, installed: true };
@@ -882,11 +1002,12 @@ function activateWithLauncher(layout, id, active, { module, next }) {
  * print exactly the release's gentle-pi and Pi before `current` switches; the
  * release's launcher is then written (a failure puts `current` back) and two
  * versions are kept (a pruning failure is only a warning). An already current
- * release changes nothing; any failure leaves `current` as it was and removes a
- * version this call installed. Returns { id, changed, previous?, removed?, warning? }.
+ * release changes nothing, and so does a release of the active Gentle Shell
+ * whose Pi is older than the one `gentle-shell update --latest` installed (no
+ * downgrade); any failure leaves `current` as it was and removes a version this
+ * call installed. Returns { id, changed, previous?, removed?, warning? }.
  */
 export async function upgradeBundled({ layout, home, platform = layout.platform, arch = process.arch, env = {}, adapters, out = () => {} }) {
-	const path = pathFor(process.platform);
 	const latest = await adapters.latest();
 	const release = await adapters.distribution(latest);
 	if (release?.status !== "published") throw new Error((UNPUBLISHED[release?.status] ?? UNPUBLISHED.unavailable)(latest));
@@ -897,9 +1018,40 @@ export async function upgradeBundled({ layout, home, platform = layout.platform,
 		out(`Gentle Shell ${shell} with Pi ${pi} is already current.`);
 		return { id, changed: false };
 	}
+	const activePi = piOfVersion(active, shell);
+	if (activePi && newerVersion(activePi, pi)) {
+		out(`Gentle Shell ${shell} is current; Pi ${activePi} (installed with 'gentle-shell update --latest') is newer than this release's verified Pi ${pi}.`);
+		return { id: active, changed: false };
+	}
+	return installAndActivate({ layout, home, platform, arch, env, adapters, out, manifest, lockfile, active,
+		success: `Upgraded to Gentle Shell ${shell} with Pi ${pi} (from ${active ?? "no active version"}). Run 'gentle-shell upgrade --rollback' to switch back.` });
+}
+
+/** The Pi of version id `<shell>-<pi>` for exactly this `shell`, or null. */
+function piOfVersion(id, shell) {
+	const pi = typeof id === "string" && id.startsWith(`${shell}-`) ? id.slice(shell.length + 1) : "";
+	return SEMVER.test(pi) ? pi : null;
+}
+/** Whether version `a` is newer than `b` by major, minor and patch. */
+function newerVersion(a, b) {
+	const [left, right] = [a, b].map((version) => SEMVER.exec(version).slice(1, 4).map(Number));
+	const index = left.findIndex((part, at) => part !== right[at]);
+	return index !== -1 && left[index] > right[index];
+}
+
+/** Installs `manifest` beside the active version (with the release lockfile,
+ * or `unverified` without one) and switches to it the way upgradeBundled
+ * always has: our runtime first, then the new version's own module and pinned
+ * runtime, its launcher checked for exactly `shell` and `pi`, `current`
+ * switched with that launcher, `success` printed and two versions kept (a
+ * pruning failure is only a warning). Any failure leaves `current` as it was
+ * and removes a version this call installed.
+ */
+async function installAndActivate({ layout, home, platform, arch, env, adapters, out, manifest, lockfile, unverified = false, active, success }) {
+	const { shell, pi, id } = versionsOf(manifest);
 	const go = platform === "win32";
 	const runtime = await (adapters.ensureRuntime ?? ensureRuntime)({ layout, platform, arch, go, env });
-	const version = await installVersion({ layout, manifest, lockfile, platform, env, go: runtime.go, adapters: adapters.install ?? {} });
+	const version = await installVersion({ layout, manifest, lockfile, unverified, platform, env, go: runtime.go, adapters: adapters.install ?? {} });
 	try {
 		const loaded = await loadRelease({ layout, id, home, platform, env, adapters, active });
 		// The release's own pins, its Engram included (an older module ignores `engram`).
@@ -914,7 +1066,7 @@ export async function upgradeBundled({ layout, home, platform = layout.platform,
 		if (version.installed && activeVersion(layout) !== id) rmSync(version.path, { recursive: true, force: true });
 		throw error;
 	}
-	out(`Upgraded to Gentle Shell ${shell} with Pi ${pi} (from ${active ?? "no active version"}). Run 'gentle-shell upgrade --rollback' to switch back.`);
+	out(success);
 	try {
 		return { id, changed: true, previous: active, removed: (adapters.prune ?? pruneVersions)(layout, 2) };
 	} catch (error) {
@@ -924,6 +1076,50 @@ export async function upgradeBundled({ layout, home, platform = layout.platform,
 	}
 }
 
+/** The newest published stable Pi: our pnpm's `view` of Pi's `latest`
+ * dist-tag, with the prefix npmrc (its registry and credentials). Only an
+ * exact major.minor.patch is accepted.
+ */
+export async function publishedPi(layout, { platform = layout.platform, env = {}, run = runCommand } = {}) {
+	const result = await (run ?? runCommand)(layout.node, [layout.pnpm, "view", `${PI_PACKAGE}@latest`, "version"],
+		{ cwd: layout.root, env: pnpmEnvironment(layout, { platform, env }), timeout: 60000 });
+	if (result.status !== 0) {
+		throw Object.assign(new Error(`the latest published Pi could not be resolved (pnpm view exit ${result.status})`), { stderr: String(result.stderr ?? "").slice(-4000) });
+	}
+	const version = String(result.stdout ?? "").trim();
+	if (!STABLE.test(version)) throw new Error(`the latest published Pi version ${JSON.stringify(version)} was rejected`);
+	return version;
+}
+
+/** `gentle-shell update --latest` in a bundled install (S3): the newest
+ * published stable Pi (adapters.latestPi) installed with this Gentle Shell
+ * `shell` as version `<shell>-<pi>`, without the release's verified lockfile
+ * (installVersion `unverified`), after a warning; then verified and activated
+ * exactly like upgradeBundled (installAndActivate). An active version that
+ * already has that Pi, or a newer one, changes nothing. Returns what upgradeBundled returns.
+ */
+export async function upgradePiLatest({ layout, home, shell, platform = layout.platform, arch = process.arch, env = {}, adapters, out = () => {} }) {
+	const latest = await adapters.latestPi();
+	if (!STABLE.test(String(latest))) throw new Error(`the latest published Pi version ${JSON.stringify(latest)} was rejected`);
+	const manifest = { shell, pi: latest };
+	const { pi, id } = versionsOf(manifest);
+	const active = activeVersion(layout);
+	if (active === id) {
+		out(`Pi ${pi} is already the latest published Pi.`);
+		return { id, changed: false };
+	}
+	const activePi = piOfVersion(active, shell);
+	if (!activePi) throw new Error(`the active version ${active ?? "(none)"} is not Gentle Shell ${shell}; current stays as it is`);
+	// A `latest` dist-tag moved back (or a release pinning a Pi newer than it) never downgrades Pi.
+	if (!newerVersion(pi, activePi)) {
+		out(`Pi ${activePi} is newer than the latest published Pi (${pi}); nothing changed.`);
+		return { id: active, changed: false };
+	}
+	out(`warning: Pi ${pi} is newer than the Pi verified for this Gentle Shell release (${activePi}); it installs without the release's verified lockfile, and Gentle Shell features that rely on audited Pi internals (such as the Vim editor) may turn off until a Gentle Shell release verifies it.`);
+	return installAndActivate({ layout, home, platform, arch, env, adapters, out, manifest, unverified: true, active,
+		success: `Installed Pi ${pi} with Gentle Shell ${shell} (from ${active}). Run 'gentle-shell upgrade --rollback' to switch back.` });
+}
+
 /** Whether version `id` reports exactly `gentle-shell <shell>` and `pi <pi>` to
  * `--version`: its entry run by our Node, or with `launcher` on POSIX the
  * bin/gentle-shell launcher itself (it runs the version `current` names).

package/scripts/installer-downloads.mjs

@@ -57,6 +57,23 @@ const engram = Object.freeze({
 });
 /** The Engram version the bundled install publishes under runtime/. */
 export const engramPinVersion = engram.version;
+// uv for the /gentle:music offer (installMusicPlayer), never part of the default
+// install: the astral-sh/uv release. Each sha256 and size comes from GitHub's
+// asset digests; every archive was downloaded and re-hashed before pinning.
+const uv = Object.freeze({
+	version: "0.13.6",
+	redirectHosts: engram.redirectHosts,
+	archives: Object.freeze({
+		"darwin-arm64": ["uv-aarch64-apple-darwin.tar.gz", "60fbd5c8a1ed681845eea28d9d622fcde03c51e91a43465b64a1e17db1ed3472", 14235670],
+		"darwin-x64": ["uv-x86_64-apple-darwin.tar.gz", "63ba17fdda55ad1a230d4b37fc6017ffa10c23688c83818bd3bfdf914c652a02", 17004934],
+		"linux-x64": ["uv-x86_64-unknown-linux-gnu.tar.gz", "f29c3e94ffabd7e6f3ba521dba169a9b7ec12100bf3257087f0f24f6123f3645", 16799024],
+		"linux-arm64": ["uv-aarch64-unknown-linux-gnu.tar.gz", "229e194255c7958d86d56e8790d969a6f74736592133f0dfd0076f754c642c1d", 15794886],
+		"win32-x64": ["uv-x86_64-pc-windows-msvc.zip", "a2a8820d5eea32f08ef467ef3b7f66883a9b076d5737a2fc2fbb5f458d1bb50f", 15239500],
+		"win32-arm64": ["uv-aarch64-pc-windows-msvc.zip", "c2426c0c8e28b53d8c440e47a18d96ad4db51e159866c0e81435b196d7f0081c", 15439263],
+	}),
+});
+/** The uv version the music offer publishes under runtime/. */
+export const uvPinVersion = uv.version;
 
 /** Fixed allowlist; callers cannot supply download URLs, checksums or commands. */
 export function artifactFor(name, platform, arch) {
@@ -77,6 +94,13 @@ export function artifactFor(name, platform, arch) {
 			url: `https://github.com/Gentleman-Programming/engram/releases/download/v${engram.version}/engram_${engram.version}_${suffix}`,
 			integrity: `sha256-${sha256}`, size, maxBytes: size, redirectHosts: engram.redirectHosts });
 	}
+	if (name === "uv") {
+		const pin = Object.hasOwn(uv.archives, `${platform}-${arch}`) ? uv.archives[`${platform}-${arch}`] : null;
+		if (!pin) throw new Error("Unsupported acquisition target");
+		const [asset, sha256, size] = pin;
+		return Object.freeze({ name, version: uv.version, platform, arch, url: `https://github.com/astral-sh/uv/releases/download/${uv.version}/${asset}`,
+			integrity: `sha256-${sha256}`, size, maxBytes: size, redirectHosts: uv.redirectHosts });
+	}
 	if (name === "go") {
 		const pin = Object.hasOwn(go.archives, `${platform}-${arch}`) ? go.archives[`${platform}-${arch}`] : null;
 		if (!pin) throw new Error("Unsupported acquisition target");

package/scripts/installer-preflight.mjs

@@ -25,7 +25,7 @@ export const requirements = Object.freeze({
 /** Pi version the installer installs next to gentle-pi, and the version an older
  * Pi is updated to (never below requirements.pi; the runner asserts it).
  */
-export const PI_INSTALL_VERSION = "1.2.0";
+export const PI_INSTALL_VERSION = "1.4.0";
 
 /** Runtime persisted under PNPM_HOME. Bootstrap-only Node: `pnpm runtime set
  * node <node> -g`, then `pnpm add -g npm@<npm> pnpm@<pnpm>`, or only npm when

package/scripts/pi-update.mjs

@@ -21,7 +21,9 @@ const SHIM_TARGET = /"((?:\$basedir[\\/]|%~?dp0%?[\\/])?[^"]*?[\\/]dist[\\/]bund
 export function managedUpdatePlan(args) {
  // The legacy extension-only alias must never trigger self-update.
  if (args.includes('--extensions-only')) return {self:false, piArgs:args};
- return bundledUpdatePlan(args);
+ // Its self update already installs the latest Pi, so --latest changes nothing here.
+ const {latest: _latest, ...plan} = bundledUpdatePlan(args);
+ return plan;
 }
 
 function pathsFor(platform) {