gentle-pi 4.3.0 → 4.5.0

package/runtime/gentle-shell-startup-update.mjs

@@ -21,6 +21,30 @@
 
 
 
+
+
+
+
+
+
+
+
+/** The launcher config records the last live lookup so the everyday launch stays off the network. */
+
+
+
+
+
+/** Reads the config's `startupReleaseCheck` key; anything malformed is no cache. */
+export function parseStartupReleaseCache(value         )                                  {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const { checkedAt, latest } = value                                             ;
+	const ms = typeof checkedAt === "number" ? checkedAt : typeof checkedAt === "string" ? Date.parse(checkedAt) : Number.NaN;
+	if (!Number.isFinite(ms) || typeof latest !== "string" || latest === "") return undefined;
+	return { checkedAt: ms, latest };
+}
+
+export const STARTUP_RELEASE_TTL_MS = 24 * 60 * 60 * 1000;
 
 export function shouldCheckStartupUpdate({ args, env, bundled, inputTTY, outputTTY }                           )          {
 	if (!bundled || !inputTTY || !outputTTY || args.command || args.piSubcommand || args.error || args.help || args.version || args.packageRoot !== undefined) {
@@ -62,9 +86,30 @@ function isNewer(latest          , current          )          {
 	return false;
 }
 
-export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500 }                            )                                          {
+function offerFor(current        , latest                    , skipped                    )                                 {
 	const currentParts = stableParts(current);
 	if (!currentParts) return undefined;
+	if (latest === undefined || latest === skipped) return undefined;
+	const latestParts = stableParts(latest);
+	if (!latestParts || !isNewer(latestParts, currentParts)) return undefined;
+	return {
+		current,
+		latest,
+		notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
+	};
+}
+
+// A malformed cached latest is never trusted — it must not suppress the
+// network check for a whole TTL window — so it counts as no cache at all.
+function usableCache(cache                                 , ttlMs        , nowMs        )                                  {
+	if (cache === undefined) return undefined;
+	if (!Number.isFinite(cache.checkedAt) || typeof cache.latest !== "string" || cache.latest === "" || stableParts(cache.latest) === undefined) return undefined;
+	return nowMs - cache.checkedAt < ttlMs ? cache : undefined;
+}
+
+export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500, cache, nowMs = Date.now(), ttlMs = STARTUP_RELEASE_TTL_MS, cacheWrite }                            )                                          {
+	const cached = usableCache(cache, ttlMs, nowMs);
+	if (cached !== undefined) return offerFor(current, cached.latest, skipped);
 	const controller = new AbortController();
 	const deadline = Number.isFinite(timeoutMs) && timeoutMs >= 0 && timeoutMs <= 2_147_483_647 ? timeoutMs : 1500;
 	let timer                                           ;
@@ -77,17 +122,24 @@ export async function findStartupUpdate({ current, skipped, lookup, timeoutMs =
 		});
 		// The race bounds startup even if the injected lookup ignores cancellation.
 		const latest = await Promise.race([lookup(controller.signal), timeout]);
-		if (latest === undefined || latest === skipped) return undefined;
-		const latestParts = stableParts(latest);
-		if (!latestParts || !isNewer(latestParts, currentParts)) return undefined;
-		return {
-			current,
-			latest,
-			notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
-		};
+		// Only a real answer is worth a day's trust: a timeout or rejection must
+		// not suppress tomorrow's check.
+		if (typeof latest === "string") cacheWrite?.(latest);
+		return offerFor(current, latest, skipped);
 	} catch {
 		return undefined;
 	} finally {
 		clearTimeout(timer);
 	}
 }
+
+// Mirrors omitStartupVersion: preserves every other config key, fails loudly on
+// an invalid config, and records the lookup's answer with an injected clock.
+export function writeStartupReleaseCache(read                          , write                        , version        , nowMs = Date.now())       {
+	const text = read();
+	const config = text === undefined ? {} : JSON.parse(text);
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw new Error("Invalid launcher config");
+	const cache                      = { checkedAt: nowMs, latest: version };
+	const serialized = JSON.stringify({ ...config, startupReleaseCheck: { checkedAt: new Date(cache.checkedAt).toISOString(), latest: cache.latest } }, null, 2);
+	write(`${serialized}\n`);
+}

package/runtime/gentle-shell-uninstall.mjs

@@ -1,7 +1,9 @@
 // Generated by scripts/build-runtime-modules.mjs. Do not edit.
-import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmdirSync, rmSync } from "node:fs";
+import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { withoutBundledNpmCommand } from "./gentle-shell-bundled.mjs";
 import { isolatedDir, launcherConfigPath, parseRawLauncherConfig, provisionedEntry, userPiHome } from "./gentle-shell-launcher.mjs";
 
 // `gentle-shell self-uninstall`: removes what Gentle Shell itself created, then
@@ -779,6 +781,18 @@ function printBundledPlan(plan             , input                           , o
 	}
 }
 
+/** Replaces `path`'s text through a same-directory temporary file, so a crash never leaves it half-written. */
+function writeTextAtomically(path        , text        )       {
+	const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+	try {
+		writeFileSync(temporary, text);
+		renameSync(temporary, path);
+	} catch (error) {
+		try { unlinkSync(temporary); } catch { /* The temporary file is best effort. */ }
+		throw error;
+	}
+}
+
 /**
  * Runs `gentle-shell self-uninstall` for the bundled install at `root`. Exit
  * codes as runSelfUninstall: 0 done or dry run, 1 refused, cancelled or failed,
@@ -838,6 +852,24 @@ export async function runBundledSelfUninstall(input                           )
 	} catch {
 		// A leftover empty folder is harmless.
 	}
+	// A home that stays must not keep Pi pointed at the npm this uninstall removed
+	// (#2469): an `npmCommand` naming the prefix fails every later `pi install`
+	// with ENOENT naming the deleted node.exe.
+	if (!confirmation.includeShared) {
+		const settingsPath = join(plan.shellHome, "agent", "settings.json");
+		let settingsText                    ;
+		try { settingsText = readFileSync(settingsPath, "utf8"); } catch { settingsText = undefined; }
+		const removal = withoutBundledNpmCommand(settingsText, (path) => within(root, path, platform));
+		if (removal.status === "removed") {
+			try {
+				writeTextAtomically(settingsPath, removal.text);
+				out(`Removed npmCommand from ${settingsPath}: it named the removed install.`);
+			} catch (error) {
+				err(`gentle-shell self-uninstall: could not remove npmCommand from ${settingsPath}: ${error instanceof Error ? error.message : String(error)}`);
+				err(`Pi package installs keep failing until the npmCommand naming ${root} is deleted from it.`);
+			}
+		}
+	}
 	if (plan.held.length > 0) {
 		try {
 			if (!input.deferRemoval) throw new Error("no deferred removal on this system");

package/runtime/native-review-cli.mjs

@@ -203,10 +203,10 @@ export const NATIVE_REVIEW_MODE_SCOPE = {
 // stream while still succeeding. That last qualifier is what keeps this list
 // honest: v2.4.0 deleted reviewConsentSkippedDefaultProvenance ("Reviews are
 // on by default; this was never explicitly chosen. ..."), which used to ride
-// with the skip notice whenever the resolved mode source was `default`. Under
-// opt-in receipt-driven development a default-source clone is refused long
-// before the consent ceremony runs, so the pinned binary can no longer emit
-// that line and it is removed here rather than left as dead tolerance. Multi-
+// with the skip notice whenever the resolved mode source was `default`. Reviews
+// are on by default again since gentle-ai v4.0.0, but the pinned binary no
+// longer has that function and cannot emit the line, so it is removed here
+// rather than left as dead tolerance. Multi-
 // line stderr is still expected in principle — these are separate Fprintln
 // calls, never one joined string — which is why membership is per line.
 export const REVIEW_CONSENT_NOTICES = Object.freeze([
@@ -1091,6 +1091,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b.
 	// No new negotiated capability identity is asserted.
 	"4.2.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.3.1 repeats 4.2.0: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2, and the provider contract
+	// stays at 1.4.0, with published tarball SHA-256
+	// 58450471280aeb357443d6a28c819132d8c8eb78dd25b12bac64296b2f8c27c2.
+	// The v4.3.0 tag has no release and is never pinned.
+	// No new negotiated capability identity is asserted.
+	"4.3.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 

package/scripts/bundled-engram-migration.mjs

@@ -43,12 +43,6 @@ function coreHelp(core, env) {
 function supportsMigration(core, env) {
 	return coreHelp(core, env).includes("migrate-copy --data-dir <absolute-source> --output-dir <new-absolute-destination> --confirm-quiescent --json");
 }
-export function supportsBundledSessionOwned(core, env) {
-	if (!core) return false;
-	const clean = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("ENGRAM_") && key !== "GH_TOKEN" && key !== "GITHUB_TOKEN"));
-	try { return coreHelp(core, { ...clean, ENGRAM_NO_UPDATE_CHECK: "1" }).some((line) => /^serve --session-owned(?:\s|$)/.test(line)); }
-	catch { return false; }
-}
 
 export function migrateBundledEngram({ prefix, core, home, env }) {
 	let markerOwned = false;

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/gentle-ai-installer.mjs

@@ -37,7 +37,7 @@ 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 = "4.2.0";
+export const INSTALLER_VERSION = "4.3.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",
@@ -46,11 +46,11 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 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/v4@v4.2.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.3.1`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 4acaf4241beae1e0c977c92dfe406a270f8d40de, the published v4.2.0 release head.
+// tag resolves to commit 2dba7784114fff57864519c4c0d067e952a8c98b, the published v4.3.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:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=";
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:00p8dnjJrhYFq1Qikk2oY6K/UXIty9A/IBUUOUiX9XA=";
 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";
@@ -69,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 v4.2.0 digests are pinned from the published release:
+// still holds it. The v4.3.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.
@@ -111,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 v4.2.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v4.3.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_4.2.0_darwin_amd64.tar.gz", "8f6a91e0f99cac3aea138705d7d222ea342f53a47602d48cb01488952a1c12f8", "784855e99f1bc45579f01420c923b7dc1dc6d63492cdc0174a9a32e611849e57", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_4.2.0_darwin_arm64.tar.gz", "d5e9a6521de5f08a393635f083f64dc7afc1b8e97884f7aab5ae5eb1f17c7f37", "8ea490287ef796848b0d305cf2b26265e360d3f400efc016972844498fb87097", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_4.2.0_linux_amd64.tar.gz", "552c1642fd10f5d96cfe9bb1cc3b66b30eb47d3074cc7ca0559b598eb086defc", "9212c7b16ea9abfe93e3a16b29d8390e7762b5c07730cf05df1f3e7892ff96a4", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_4.2.0_linux_arm64.tar.gz", "2bebe91b8808ce48d86c4d3700d098e37cb6b0658f196c666d9deeeb7c7c1a7a", "e1b88bd3dcdc8a15ddbcaf8731fd44561f05b06fbcb59d9385bbe82c4b96b5c4", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_4.3.1_darwin_amd64.tar.gz", "6cf57fee0574daef2abed07f54a355fec3b93ac8f01733dc6c4d3674f1746112", "ca44c3fce186b63a7e7ad455c338133ba1982f4a13485301ce4d66edb73d2928", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.3.1_darwin_arm64.tar.gz", "13e8828447f9081465ee0c35a61b24fb49296d51a310c6999227e2aed178956b", "749d08062b0dec13681678a1a1c018613d223ddcca47b5f27681b1d8ab5d14c2", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.3.1_linux_amd64.tar.gz", "04ec685c56b42c29dff6db10fc7dc2c730217dc9c96736e53ad2acf3226dafb7", "86248792bde3fe5e9ca93b128c07e7caa6a5b31fac0f9fc84b5b3011b123cb90", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.3.1_linux_arm64.tar.gz", "99e7d313a2ff85eaf23a6415e9b3aae67bf74c2fa169b21b93070ada7613f6a0", "df3580506bb5ea63cc4ef5ccebe8b68cfedf66b72f3b51f84ff393183d8cea2b", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

package/scripts/installer-downloads.mjs

@@ -44,19 +44,36 @@ export const goPinVersion = go.version;
 // checksums.txt and GitHub's asset digests; every archive was downloaded and
 // re-hashed before pinning. GitHub serves the assets from its asset hosts.
 const engram = Object.freeze({
-	version: "3.4.0",
+	version: "3.5.2",
 	redirectHosts: Object.freeze(["objects.githubusercontent.com", "release-assets.githubusercontent.com"]),
 	archives: Object.freeze({
-		"darwin-arm64": ["darwin_arm64.tar.gz", "d0aa59c9a83d17ae3fc7f5dd31fdab6a26fd8c00fc5e692195753cd0719294f7", 7470202],
-		"darwin-x64": ["darwin_amd64.tar.gz", "3c5bdc73d226af5629cf4f4a781e223142e37c1ebb443c4b596f2e284352e381", 7961674],
-		"linux-x64": ["linux_amd64.tar.gz", "715fda625556e46d65ddb4526bb7f88a3fee5339ca3c44ce44cc652f17fa57f1", 7821191],
-		"linux-arm64": ["linux_arm64.tar.gz", "3309e9c0bbb539d183fd5aa9f9a13cd7aa0e81ec2512b5bedefb8b2bdd35b3e5", 7176726],
-		"win32-x64": ["windows_amd64.zip", "3065736ec7ff8137eb3fc607275f542ea13bb743a5157318c8a8770f11ce3289", 8021225],
-		"win32-arm64": ["windows_arm64.zip", "7463872a85a5e5434cf958bdffc71dda1926bced30d3b6b38c80fec9bb98fbba", 7231641],
+		"darwin-arm64": ["darwin_arm64.tar.gz", "43d398b2fe3327a4a6436c26b2a17d3285ba80bf2f11a22d0796ea2a7fd2b78c", 7749520],
+		"darwin-x64": ["darwin_amd64.tar.gz", "aea28ebf461a4ea86c52b793c29311539d7123875354ed7411eae982fc82ec87", 8181300],
+		"linux-x64": ["linux_amd64.tar.gz", "106a43ca8f43a27c2c260a6787151c3be6d91c5ed3d5e454e6140527adf92e01", 8064598],
+		"linux-arm64": ["linux_arm64.tar.gz", "b0ba49cf5a7d5af436c9744a9a0d638b3f9ebb2a7321c8736d30e96305c2993c", 7472279],
+		"win32-x64": ["windows_amd64.zip", "ba56a36d37b2da85fcb1581bbdbed9ae1ee690e642aab8dbe1e18209bf264afe", 8272809],
+		"win32-arm64": ["windows_arm64.zip", "df5acc5dd6ee407d484074e570c77a79567c0b8dccf55e25ae25a644c1e7db5f", 7530282],
 	}),
 });
 /** 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");