gentle-pi 4.3.0 → 4.4.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,6 +513,58 @@ 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;

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"'`\\$&|;<>(){}*?[\]!#~]/;

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");

package/lib/image-attachments.ts

@@ -0,0 +1,150 @@
+import type { ImageContent } from "@earendil-works/pi-ai";
+import { getImageDimensions, type ImageDimensions } from "@earendil-works/pi-tui";
+import type { ClipboardImage } from "./clipboard-image.ts";
+
+// Pasted images live in the draft as atomic `[Image#N]` chips (gentle-shell#2464).
+// The bytes stay in memory: a chip deleted from the draft is never sent, and
+// the chips still in the text become real image attachments on submit.
+//
+// The token has no whitespace on purpose: Pi's word motions, word deletion and
+// word wrap treat any segment containing a space as whitespace unless it is
+// one of Pi's own paste markers, so `[Image #1]` would be skipped and eaten
+// together with the word before it.
+
+export const IMAGE_TOKEN_PATTERN = /\[Image#(\d+)\]/g;
+
+export interface ImageAttachment {
+	id: number;
+	token: string;
+	mimeType: string;
+	byteLength: number;
+	base64: string;
+	dimensions?: ImageDimensions;
+}
+
+export interface SubmittedImages {
+	text: string;
+	images: ImageContent[];
+	/** Chips the active model cannot receive; their tokens become a plain note. */
+	omitted: number;
+}
+
+export interface TextSpan { start: number; end: number }
+
+interface Segment { segment: string; index: number; input: string }
+
+export function imageToken(id: number): string {
+	return `[Image#${id}]`;
+}
+
+export class ImageAttachments {
+	private readonly entries = new Map<number, ImageAttachment>();
+	// Never reset: Pi's prompt history keeps the raw submitted text, so a
+	// reused id would let a recalled `[Image#1]` bind to a different image.
+	private counter = 0;
+
+	get size(): number { return this.entries.size; }
+
+	has(id: number): boolean { return this.entries.has(id); }
+
+	add(image: ClipboardImage): ImageAttachment {
+		const id = ++this.counter;
+		const base64 = Buffer.from(image.bytes).toString("base64");
+		const attachment: ImageAttachment = {
+			id,
+			token: imageToken(id),
+			mimeType: image.mimeType,
+			byteLength: image.bytes.length,
+			base64,
+			dimensions: getImageDimensions(base64, image.mimeType) ?? undefined,
+		};
+		this.entries.set(id, attachment);
+		return attachment;
+	}
+
+	/** Registered chips in the order they appear in `text`, each once. */
+	referenced(text: string): ImageAttachment[] {
+		const seen = new Set<number>();
+		const result: ImageAttachment[] = [];
+		for (const match of text.matchAll(IMAGE_TOKEN_PATTERN)) {
+			const id = Number(match[1]);
+			const attachment = this.entries.get(id);
+			if (!attachment || seen.has(id)) continue;
+			seen.add(id);
+			result.push(attachment);
+		}
+		return result;
+	}
+
+	/**
+	 * Resolve a submitted draft. Returns undefined when it holds no registered
+	 * chip, so ordinary prompts pass through untouched.
+	 *
+	 * Pi can run input handlers after the editor already holds a new draft
+	 * (a prompt queued during compaction), so only chips the current draft
+	 * still shows survive; everything else, sent or deleted, is released.
+	 */
+	submit(text: string, modelAcceptsImages: boolean, currentDraft = ""): SubmittedImages | undefined {
+		const attachments = this.referenced(text);
+		const keep = new Set(this.referenced(currentDraft).map((attachment) => attachment.id));
+		for (const id of [...this.entries.keys()]) if (!keep.has(id)) this.entries.delete(id);
+		if (attachments.length === 0) return undefined;
+		if (modelAcceptsImages) {
+			return { text, images: attachments.map((attachment) => ({ type: "image", data: attachment.base64, mimeType: attachment.mimeType })), omitted: 0 };
+		}
+		const ids = new Set(attachments.map((attachment) => attachment.id));
+		const noted = text.replace(IMAGE_TOKEN_PATTERN, (token, id: string) => ids.has(Number(id)) ? `${token.slice(0, -1)} omitted: the current model does not accept images]` : token);
+		return { text: noted, images: [], omitted: attachments.length };
+	}
+
+	/** Drop every pending image; numbering keeps counting up. */
+	clear(): void {
+		this.entries.clear();
+	}
+
+	/** Character spans of the registered chips in `text`. */
+	spans(text: string): TextSpan[] {
+		if (this.entries.size === 0 || !text.includes("[Image#")) return [];
+		const spans: TextSpan[] = [];
+		for (const match of text.matchAll(IMAGE_TOKEN_PATTERN)) {
+			if (this.entries.has(Number(match[1]))) spans.push({ start: match.index, end: match.index + match[0].length });
+		}
+		return spans;
+	}
+
+	/**
+	 * Merge every registered chip into one segment, so cursor movement, word
+	 * wrap and deletion treat it as a single unit (one Backspace removes it).
+	 * Segments that already span several graphemes, such as Pi's own paste
+	 * markers, pass through unchanged.
+	 */
+	segment(text: string, segments: Iterable<Segment>): Iterable<Segment> {
+		const spans = this.spans(text);
+		if (spans.length === 0) return segments;
+		const merged: Segment[] = [];
+		let span = 0;
+		for (const segment of segments) {
+			while (span < spans.length && spans[span]!.end <= segment.index) span++;
+			const current = spans[span];
+			if (current && segment.index >= current.start && segment.index < current.end) {
+				if (segment.index === current.start) merged.push({ segment: text.slice(current.start, current.end), index: current.start, input: text });
+				continue;
+			}
+			merged.push(segment);
+		}
+		return merged;
+	}
+}
+
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** `png · 1280×720 · 84 KB`: the chip's description when no preview is drawn. */
+export function describeAttachment(attachment: Pick<ImageAttachment, "mimeType" | "byteLength" | "dimensions">): string {
+	const format = attachment.mimeType.replace(/^image\//, "").replace("jpeg", "jpg");
+	const size = attachment.dimensions ? `${attachment.dimensions.widthPx}×${attachment.dimensions.heightPx}` : undefined;
+	return [format, size, formatBytes(attachment.byteLength)].filter(Boolean).join(" · ");
+}

package/lib/inprocess-reviewer.ts

@@ -153,6 +153,36 @@ function isTextContent(part: { type?: unknown }): part is TextContent {
 	return part.type === "text";
 }
 
+/** Completion diagnostics are facts only; never copy provider text, errors, or payloads. */
+function emptyOutputEvidence(model: Model<Api>, assistant: AssistantMessage): Record<string, unknown> {
+	const evidence: Record<string, unknown> = { reviewerModel: `${model.provider}/${model.id}`.slice(0, 512) };
+	if (["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"].includes(assistant.stopReason)) {
+		evidence.stopReason = assistant.stopReason;
+	}
+	const addCounter = (target: Record<string, number>, key: string, value: unknown) => {
+		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) target[key] = value;
+	};
+	const usage: Record<string, number> = {};
+	for (const key of ["input", "output", "reasoning", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+		addCounter(usage, key, assistant.usage?.[key]);
+	}
+	if (Object.keys(usage).length > 0) evidence.usage = usage;
+	const text = assistant.content.filter(isTextContent);
+	const thinking = assistant.content.filter((part) => part.type === "thinking");
+	const content: Record<string, number> = {};
+	addCounter(content, "blocks", assistant.content.length);
+	addCounter(content, "textBlocks", text.length);
+	addCounter(content, "thinkingBlocks", thinking.length);
+	if (text.every((part) => typeof part.text === "string")) {
+		addCounter(content, "textChars", text.reduce((sum, part) => sum + part.text.length, 0));
+	}
+	if (thinking.every((part) => typeof part.thinking === "string")) {
+		addCounter(content, "thinkingChars", thinking.reduce((sum, part) => sum + part.thinking.length, 0));
+	}
+	evidence.content = content;
+	return evidence;
+}
+
 /**
  * Mirrors pi's main-loop OpenCode attribution condition exactly
  * (core/provider-attribution.js#getSessionHeaders): the model's provider is
@@ -329,10 +359,11 @@ export async function runInProcessReviewer(request: InProcessReviewerRequest, de
 
 	const text = assistant.content.filter(isTextContent).map((part) => part.text).join("");
 	if (text.length === 0) {
+		const evidence = emptyOutputEvidence(model, assistant);
 		return refuse(
 			INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT,
-			`Reviewer produced no text for ${request.routingKey} (stopReason: ${assistant.stopReason}).`,
-			{ stopReason: assistant.stopReason, ...(assistant.errorMessage === undefined ? {} : { errorMessage: assistant.errorMessage }) },
+			`Reviewer produced no text for ${request.routingKey} (stopReason: ${evidence.stopReason ?? "unknown"}).`,
+			evidence,
 		);
 	}