gentle-pi 4.3.0 → 4.5.0

package/lib/gentle-shell-bundled.ts

@@ -1,7 +1,7 @@
 import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { request as httpRequest } from "node:http";
 import { createConnection } from "node:net";
-import { dirname, posix, win32 } from "node:path";
+import { dirname, isAbsolute, posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // The launcher in a bundled install (S5, S8): pure decisions over an injected
@@ -27,6 +27,46 @@ export interface BundledInstall {
 
 type Env = Record<string, string | undefined>;
 
+/**
+ * Builds the detached shared server's environment without retaining session scratch.
+ * Windows Node can reintroduce an omitted TEMP from its parent, so use the
+ * original stable ancestor there; POSIX omits scratch temp settings instead.
+ */
+export function sharedEngramEnv(base: Env, platform: string = process.platform): Env {
+	const path = pathFor(platform);
+	const env: Env = {};
+	const scratch = (value: string) => /^(gp|ga)[A-Za-z0-9]{6}$/.test(path.basename(path.normalize(value)));
+	let stableTemp: string | undefined;
+	let tempKey: string | undefined;
+	for (const [key, value] of Object.entries(base)) {
+		const name = platform === "win32" ? key.toUpperCase() : key;
+		if (name.startsWith("ENGRAM_") || name === "GH_TOKEN" || name === "GITHUB_TOKEN") continue;
+		if (["TMPDIR", "TMP", "TEMP"].includes(name) && value !== undefined && scratch(value)) {
+			if (platform !== "win32") continue;
+			// A drive-relative or root-relative path depends on ambient state.
+			const root = win32.parse(value).root;
+			if (!/^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+[\\/]?)$/.test(root) || value.split(/[\\/]/).includes("..")) {
+				throw new Error("An absolute Windows scratch temp path is required for shared Engram.");
+			}
+			let stable = win32.normalize(value);
+			while (scratch(stable)) {
+				const parent = win32.dirname(stable);
+				if (parent === stable) throw new Error("An absolute Windows scratch temp path is required for shared Engram.");
+				stable = parent;
+			}
+			env[key] = stable;
+			stableTemp ??= stable;
+		} else {
+			env[key] = value;
+		}
+		if (name === "TEMP") tempKey = key;
+	}
+	// Keep an existing custom TEMP, even if TMP/TMPDIR chose another root.
+	if (stableTemp !== undefined && (tempKey === undefined || env[tempKey] === undefined)) env[tempKey ?? "TEMP"] = stableTemp;
+	env.ENGRAM_NO_UPDATE_CHECK = "1";
+	return env;
+}
+
 // The same rules scripts/bundled-install.mjs writes versions and markers with.
 const VERSION_ID = /^[0-9A-Za-z][0-9A-Za-z.-]*$/;
 const VERSION_MARKER = ".gentle-shell-version";
@@ -232,15 +272,14 @@ export function bundledPi(install: BundledInstall, input: { platform: string; fs
 // Gentle AI's variables, never set here because the agent's shell would pass
 // them to a gentle-ai the user runs), and the published Engram as
 // gentle-engram's ENGRAM_BIN unless the user chose one. With a memory decision
-// (S2, S6): the startup policy, and ENGRAM_BIN is the verified core only when
-// memory is allowed locally; otherwise the Shell-owned guard, so no provider,
-// whatever loaded it, runs an Engram binary against an unverified store.
+// (S2, S6): the startup policy, and ENGRAM_BIN is the Shell-owned guard, so no
+// provider, whatever loaded it, runs an Engram binary against a store; allowed
+// memory reaches the shared server through ENGRAM_URL only.
 export const ENGRAM_COMPANION_SOURCE = "npm:gentle-engram@0.4.2";
-export const ENGRAM_PRIVATE_REQUIRED_NOTICE = "Engram memory disabled: session-owned servers require a supporting published bundled core and companion. This bundle does not establish both capabilities; it will not fall back to a detached shared server. Install a supporting published bundle and restart Shell. Existing shared services are not stopped or adopted as session-owned.";
-export const ENGRAM_CORE_CHANGED_NOTICE = "Engram memory disabled: the bundled core changed since Shell recorded this store. Install a published bundle supporting migrate-copy, stop every Engram client, retain a complete backup, then run gentle-shell memory migrate --confirm-quiescent. The command verifies and migrates a copy before updating provenance; older bundles refuse safely. Do not edit coreSha256 or delete the original store. Shell remains usable without memory.";
-export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe store or server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
+export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server on 127.0.0.1:7437 with verified /compatibility evidence; Shell never stops or replaces a server already listening there. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
+export const ENGRAM_START_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not start the shared Engram server, or it did not report ready in time. Restart Shell to retry; if another program holds 127.0.0.1:7437, stop it first. Shell remains usable without memory.";
+export const ENGRAM_NEWER_SCHEMA_NOTICE = "Engram memory disabled: ~/.engram was migrated by a newer Engram than Shell's bundled core, so Shell will not start a server on it. Start that newer Engram's server yourself (engram serve); Shell reuses a running server with verified /compatibility evidence. Back up the store; do not delete or downgrade it. Shell remains usable without memory.";
 // `gentle-shell setup` publishes the verified core (ensureEngram) on every run.
-export const ENGRAM_PROVISION_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not provision a new Engram store identity, so it cannot vouch for that store. Restart Shell to retry. If Shell keeps reporting unknown compatibility and ~/.engram holds only .instance-id files, back it up and remove it, then restart Shell. Shell remains usable without memory.";
 export const ENGRAM_CORE_MISSING_NOTICE = "Engram memory disabled: the bundled Engram core is not installed yet. Run 'gentle-shell setup' to install the verified core, then restart Shell. Shell remains usable without memory.";
 // The first Engram release whose server answers GET /compatibility (PR #1792).
 export const ENGRAM_COMPATIBILITY_MIN_VERSION = "3.4.0";
@@ -261,13 +300,14 @@ function outdatedServerVersion(version: string | undefined): string | undefined
 // The default endpoint gentle-engram uses without ENGRAM_URL or ENGRAM_PORT.
 export const ENGRAM_DEFAULT_PORT = 7437;
 export const ENGRAM_DEFAULT_URL = `http://127.0.0.1:${ENGRAM_DEFAULT_PORT}`;
-const ENGRAM_SELECTIONS = ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_SOCKET", "ENGRAM_DATABASE_URL"];
+const ENGRAM_SELECTIONS = ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_SOCKET", "ENGRAM_DATABASE_URL", "ENGRAM_SERVER_MODE"];
 const HEX32 = /^[a-f0-9]{32}$/;
 
 export type EngramProbe = { kind: "refused" } | { kind: "unknown" } | { kind: "listening"; compatible: boolean; healthInstanceId?: string; healthVersion?: string };
-// `fresh`: Shell provisions a new store this run and may record its provenance.
-// `url`: a running server verified through /compatibility, reached explicitly.
-export type EngramStartup = { policy: "allow" | "disabled"; notice?: string; url?: string; fresh?: true; owned?: true };
+// `url`: the shared server, reached explicitly once /compatibility verified it.
+// `spawn`: nothing listens yet; Shell starts the bundled core's server and must
+// see it verified before Pi starts, or memory is disabled for that launch.
+export type EngramStartup = { policy: "allow" | "disabled"; notice?: string; url?: string; spawn?: true };
 
 // Without an invalid policy or an explicit Engram selection, the default
 // endpoint may be probed; an explicit selection is never contacted.
@@ -277,26 +317,24 @@ export function engramProbeAllowed(env: Env): boolean {
 }
 
 // Evidence only: never run an executable, open SQLite or infer compatibility
-// from versions. `provenance` means Shell's own record matched the store
-// (directory, .instance-id, core digest) and its header showed no newer schema.
-// A server version only selects the wording of a disabled decision.
-export function classifyEngramStartup(input: { env: Env; store: "absent" | "present" | "unknown"; endpoint: EngramProbe; core: boolean;
-	coreVersion: string; provenance?: { instanceId: string } }): EngramStartup {
+// from versions. Like other agents' hooks, Shell shares the global server: a
+// verified listener is reused, and with nothing listening the verified bundled
+// core starts one on Engram's defaults, unless the default store's header
+// (`userVersion`) shows a newer schema than that core's. A listener that does
+// not verify is never replaced. A server version only selects the wording.
+export function classifyEngramStartup(input: { env: Env; endpoint: EngramProbe; core: boolean; coreVersion: string; userVersion?: number }): EngramStartup {
 	if (!engramProbeAllowed(input.env)) return { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
 	const endpoint = input.endpoint;
-	const outdated = endpoint.kind === "listening" && !endpoint.compatible ? outdatedServerVersion(endpoint.healthVersion) : undefined;
-	const unknown: EngramStartup = { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 	if (endpoint.kind === "listening" && endpoint.compatible) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
-	if (endpoint.kind === "refused" && input.store === "absent") {
-		return input.core ? { policy: "allow", fresh: true } : { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
+	if (endpoint.kind === "refused") {
+		if (!input.core) return { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
+		if (input.userVersion !== undefined && !engramHeaderAllows(input.userVersion, bundledEngramSchema(input.coreVersion))) {
+			return { policy: "disabled", notice: ENGRAM_NEWER_SCHEMA_NOTICE };
+		}
+		return { policy: "allow", url: ENGRAM_DEFAULT_URL, spawn: true };
 	}
-	const own = input.provenance;
-	if (own === undefined || !input.core || input.store !== "present") return unknown;
-	// Shell's own store, created by this exact core: offline, the provider starts
-	// that core; a running server must be that store and that exact core.
-	if (endpoint.kind === "refused") return { policy: "allow" };
-	if (endpoint.kind === "listening" && endpoint.healthInstanceId === own.instanceId && endpoint.healthVersion === input.coreVersion) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
-	return unknown;
+	const outdated = endpoint.kind === "listening" ? outdatedServerVersion(endpoint.healthVersion) : undefined;
+	return { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 }
 
 // The exact contract a startup-verified store reports (Engram GET /compatibility).
@@ -356,8 +394,8 @@ export async function probeEngramEndpoint(input: { port?: number; timeoutMs?: nu
 	return { kind: "listening", compatible: false, healthInstanceId: identified ? body.instance_id : undefined, healthVersion: identified ? body.version : undefined };
 }
 
-// Shell's own record of a store it provisioned fresh with the verified core.
-// Written only after Shell itself provisioned the store's identity, before Pi starts.
+// Shell's record of a store an earlier Shell provisioned with its bundled core,
+// read only by the explicit `gentle-shell memory migrate` recovery.
 export type EngramProvenance = { schema: 1; dataDir: string; instanceId: string; coreSha256: string };
 
 export function engramProvenancePath(prefix: string, platform: string = process.platform): string {
@@ -371,14 +409,10 @@ export function parseEngramProvenance(text: string | undefined): EngramProvenanc
 	return { schema: 1, dataDir: record.dataDir, instanceId: record.instanceId, coreSha256: record.coreSha256 };
 }
 
-export function engramProvenanceMatches(record: EngramProvenance | undefined, observed: { dataDir: string; instanceId?: string; coreSha256?: string }): boolean {
-	return record !== undefined && record.dataDir === observed.dataDir && record.instanceId === observed.instanceId && record.coreSha256 === observed.coreSha256;
-}
-
 // The bundled core's own schema (SQLite user_version), verified from the
-// tagged sources v3.3.2 and v3.4.0: internal/store/store.go `const schemaVersion = 1`.
+// tagged sources v3.3.2, v3.4.0 and v3.5.2: internal/store/store.go `const schemaVersion = 1`.
 // A pin without a verified entry leaves the header check unavailable.
-const BUNDLED_ENGRAM_SCHEMA: Record<string, number> = { "3.3.2": 1, "3.4.0": 1 };
+const BUNDLED_ENGRAM_SCHEMA: Record<string, number> = { "3.3.2": 1, "3.4.0": 1, "3.5.2": 1 };
 
 export function bundledEngramSchema(coreVersion: string): number | undefined {
 	return Object.hasOwn(BUNDLED_ENGRAM_SCHEMA, coreVersion) ? BUNDLED_ENGRAM_SCHEMA[coreVersion] : undefined;
@@ -426,11 +460,6 @@ export function supportsEngramStartupPolicy(metadata: string | undefined): boole
 	return pkg?.name === "gentle-engram" && pkg.engram?.startupPolicy === 1;
 }
 
-export function supportsEngramSessionOwned(metadata: string | undefined): boolean {
-	const pkg = parseJson(metadata);
-	return supportsEngramStartupPolicy(metadata) && pkg?.engram?.sessionOwned === 1;
-}
-
 export function bundledChildEnv(base: Env, input: { node: string; cli: string; prefix: string; engram?: string; guard?: string; memory?: EngramStartup }): Env {
 	const env: Env = { ...base, PI_SKIP_VERSION_CHECK: "1", [GENTLE_SHELL_PREFIX_ENV]: input.prefix };
 	delete env.GENTLE_SHELL_PI;
@@ -453,14 +482,7 @@ export function bundledChildEnv(base: Env, input: { node: string; cli: string; p
 		return env;
 	}
 	if (memory.url !== undefined) env.ENGRAM_URL = memory.url;
-	const local = memory.policy === "allow" && memory.url === undefined ? input.engram : undefined;
-	env.ENGRAM_BIN = local ?? input.guard;
-	if (local && memory.owned) {
-		env.ENGRAM_SERVER_MODE = "session-owned";
-		delete env.ENGRAM_URL;
-		delete env.ENGRAM_PORT;
-		delete env.ENGRAM_SOCKET;
-	}
+	env.ENGRAM_BIN = input.guard;
 	return env;
 }
 
@@ -491,9 +513,64 @@ export function withBundledNpmCommand(settingsText: string | undefined, command:
 	return { status: "write", text: settingsText === undefined || settingsText.endsWith("\n") ? `${serialized}\n` : serialized };
 }
 
+export type BundledNpmCommandRemoval = { status: "unchanged" } | { status: "malformed" } | { status: "removed"; text: string };
+
+// settings.json without `npmCommand`: every other key kept in order and the
+// file's indentation and final newline kept.
+function settingsWithoutNpmCommand(settingsText: string, settings: Record<string, unknown>): string {
+	const indent = settingsText.match(/\{\r?\n([ \t]+)/)?.[1] ?? "  ";
+	const { npmCommand: _removed, ...rest } = settings;
+	const serialized = JSON.stringify(rest, null, indent);
+	return settingsText.endsWith("\n") ? `${serialized}\n` : serialized;
+}
+
+// The agent home's settings.json without a `npmCommand` naming the prefix a
+// bundled self-uninstall removed (gentle-shell-uninstall.ts): one absolute
+// entry inside `withinRemoved` drops the whole key, every other key kept in
+// order and the file's indentation and final newline kept. A file that is not
+// a JSON object is never rewritten; a command naming nothing inside it stays.
+export function withoutBundledNpmCommand(settingsText: string | undefined, withinRemoved: (path: string) => boolean): BundledNpmCommandRemoval {
+	if (settingsText === undefined) return { status: "unchanged" };
+	const settings = parseJson(settingsText);
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { status: "malformed" };
+	const current = settings.npmCommand;
+	if (!Array.isArray(current) || !current.some((part) => typeof part === "string" && isAbsolute(part) && withinRemoved(part))) return { status: "unchanged" };
+	return { status: "removed", text: settingsWithoutNpmCommand(settingsText, settings) };
+}
+
+// An `npmCommand` a bundled install wrote (scripts/bundled-install.mjs
+// bundledNpmCommand, with npm-cli.js and --prefix in earlier releases): our
+// node in runtime/node-<v>, then npm's settings and cache flags, and
+// --update-notifier=false last. A command the user chose never matches, even
+// when its program is missing.
+export function isBundledNpmCommand(command: readonly unknown[]): boolean {
+	const [node] = command;
+	return typeof node === "string" && /[\\/]runtime[\\/]node-[^\\/]+[\\/](node\.exe|bin[\\/]node)$/.test(node)
+		&& ["--userconfig=", "--globalconfig=", "--cache="].every((flag) => command.some((part) => typeof part === "string" && part.startsWith(flag)))
+		&& command[command.length - 1] === "--update-notifier=false";
+}
+
+// The agent home's settings.json without an `npmCommand` a bundled install
+// wrote whose executable (its first entry) no longer exists, as after a
+// bundled self-uninstall that kept the home (#2469): Pi runs that command for
+// every package install, so a key naming a deleted node.exe fails them all
+// with ENOENT. A command whose executable exists, that names no absolute
+// path, or that the user set themselves is never touched.
+export function withoutMissingBundledNpmCommand(settingsText: string | undefined, exists: (path: string) => boolean): BundledNpmCommandRemoval {
+	if (settingsText === undefined) return { status: "unchanged" };
+	const settings = parseJson(settingsText);
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { status: "malformed" };
+	const executable = Array.isArray(settings.npmCommand) ? settings.npmCommand[0] : undefined;
+	if (typeof executable !== "string" || !isAbsolute(executable) || exists(executable) || !isBundledNpmCommand(settings.npmCommand as unknown[])) return { status: "unchanged" };
+	return { status: "removed", text: settingsWithoutNpmCommand(settingsText, settings) };
+}
+
 export interface BundledUpdatePlan {
 	// Pi's own update was asked for: redirect it to `gentle-shell upgrade`.
 	self: boolean;
+	// `--latest` asked for the newest published Pi in place of the release's
+	// verified one (scripts/bundled-install.mjs upgradePiLatest). Only set then.
+	latest?: boolean;
 	// What Pi still runs, if anything: the extension part of `--all`, or the
 	// whole command when it never updates Pi itself.
 	piArgs?: string[];
@@ -504,7 +581,9 @@ export interface BundledUpdatePlan {
 // `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: string[]): BundledUpdatePlan {
 	const passThrough = { self: false, piArgs: passthrough };
@@ -513,8 +592,10 @@ export function bundledUpdatePlan(passthrough: string[]): BundledUpdatePlan {
 	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);
@@ -526,19 +607,21 @@ export function bundledUpdatePlan(passthrough: string[]): BundledUpdatePlan {
 		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: BundledUpdatePlan, upgradeCode: number | undefined): { exitCode: number } | { piArgs: string[]; note?: string } {
 	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 };
 }
@@ -549,6 +632,7 @@ export function bundledUpdateNotice(input: { piVersion: string; interactive: boo
 		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/lib/gentle-shell-launcher.ts

@@ -1118,12 +1118,17 @@ const CMD_EXE_SPECIAL_CHARS = /[\s"&|<>^%()]/;
 
 // cmd.exe quoting is deliberately simple, not a full cmd.exe parser: wrap a
 // token in double quotes when it is empty or contains whitespace or any of
-// `"&|<>^%()`, and escape an inner `"` as `\"` — doubling inner quotes is not
-// reliable in cmd.exe, unlike the `\"` convention Node's own Windows spawn
-// helpers use.
+// `&|<>^%()`. A token with an inner `"` cannot be represented: cmd.exe has no
+// backslash escape, so `\"` still ends the quoted section and the rest of the
+// token is parsed as command syntax (`x" & whoami & rem "` would run
+// `whoami`). Doubling the quote is not reliable either, so such a token is
+// refused instead of producing a command line it cannot protect.
 export function quoteForCmdExe(token: string): string {
+	if (token.includes('"')) {
+		throw new Error("cannot pass an argument containing a double quote through cmd.exe: it would end the quoted argument and let the rest run as a command");
+	}
 	if (token.length > 0 && !CMD_EXE_SPECIAL_CHARS.test(token)) return token;
-	return `"${token.replace(/"/g, '\\"')}"`;
+	return `"${token}"`;
 }
 
 const POSIX_SHELL_SPECIAL_CHARS = /[\s"'`\\$&|;<>(){}*?[\]!#~]/;
@@ -1346,6 +1351,8 @@ export function helpText(): string {
 		"  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/lib/gentle-shell-startup-update.ts

@@ -19,8 +19,32 @@ export interface StartupUpdateLookupOptions {
 	skipped?: string;
 	lookup: (signal: AbortSignal) => Promise<string | undefined>;
 	timeoutMs?: number;
+	/** A recorded previous lookup. Fresh enough, it answers without the network. */
+	cache?: StartupReleaseCache;
+	/** Injected clock and budget for tests; defaults to now and one day. */
+	nowMs?: number;
+	ttlMs?: number;
+	/** Called once with a live lookup's version; never for a fresh-cache answer or an unanswered lookup. */
+	cacheWrite?: (latest: string) => void;
 }
 
+/** The launcher config records the last live lookup so the everyday launch stays off the network. */
+export interface StartupReleaseCache {
+	checkedAt: number;
+	latest: string;
+}
+
+/** Reads the config's `startupReleaseCheck` key; anything malformed is no cache. */
+export function parseStartupReleaseCache(value: unknown): StartupReleaseCache | undefined {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const { checkedAt, latest } = value as { checkedAt?: unknown; latest?: unknown };
+	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 }: StartupUpdateCheckOptions): boolean {
 	if (!bundled || !inputTTY || !outputTTY || args.command || args.piSubcommand || args.error || args.help || args.version || args.packageRoot !== undefined) {
 		return false;
@@ -61,9 +85,30 @@ function isNewer(latest: string[], current: string[]): boolean {
 	return false;
 }
 
-export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500 }: StartupUpdateLookupOptions): Promise<StartupUpdateOffer | undefined> {
+function offerFor(current: string, latest: string | undefined, skipped: string | undefined): StartupUpdateOffer | undefined {
 	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: StartupReleaseCache | undefined, ttlMs: number, nowMs: number): StartupReleaseCache | undefined {
+	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 }: StartupUpdateLookupOptions): Promise<StartupUpdateOffer | undefined> {
+	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: ReturnType<typeof setTimeout> | undefined;
@@ -76,17 +121,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: () => string | undefined, write: (text: string) => void, version: string, nowMs = Date.now()): void {
+	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: StartupReleaseCache = { 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/lib/gentle-shell-uninstall.ts

@@ -1,6 +1,8 @@
-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.ts";
 import { isolatedDir, launcherConfigPath, parseRawLauncherConfig, provisionedEntry, userPiHome } from "./gentle-shell-launcher.ts";
 
 // `gentle-shell self-uninstall`: removes what Gentle Shell itself created, then
@@ -778,6 +780,18 @@ function printBundledPlan(plan: BundledPlan, input: BundledSelfUninstallInput, o
 	}
 }
 
+/** Replaces `path`'s text through a same-directory temporary file, so a crash never leaves it half-written. */
+function writeTextAtomically(path: string, text: string): void {
+	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,
@@ -837,6 +851,24 @@ export async function runBundledSelfUninstall(input: BundledSelfUninstallInput):
 	} 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: string | undefined;
+		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");