gentle-pi 4.2.0 → 4.4.0

package/tests/gentle-shell-import-pi.test.ts

@@ -0,0 +1,262 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { formatImportPiReport, importPi, nodeImportPiFs } from "../lib/gentle-shell-import-pi.ts";
+
+// `gentle-shell home import-pi` core: real temp directories, never the real
+// ~/.pi or ~/.gentle-shell. Credential contents never appear in assertions.
+
+const AUTH = JSON.stringify({ anthropic: { type: "oauth", refresh: "dummy-refresh", access: "dummy-access" } });
+const MCP = JSON.stringify({ mcpServers: { demo: { command: "demo" } } }, null, 2);
+
+function fixture(t: test.TestContext) {
+	const root = mkdtempSync(join(tmpdir(), "gentle-shell-import-pi-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const source = join(root, "pi-agent");
+	const target = join(root, "gentle-agent");
+	mkdirSync(source, { recursive: true });
+	mkdirSync(target, { recursive: true });
+	return { root, source, target };
+}
+
+function seedSource(source: string) {
+	writeFileSync(join(source, "auth.json"), AUTH, { mode: 0o644 });
+	chmodSync(join(source, "auth.json"), 0o644);
+	writeFileSync(join(source, "mcp.json"), MCP);
+	chmodSync(join(source, "mcp.json"), 0o640);
+	writeFileSync(join(source, "settings.json"), `${JSON.stringify({
+		defaultProvider: "anthropic",
+		defaultModel: "claude-opus-5-5",
+		defaultThinkingLevel: "high",
+		packages: ["npm:foreign"],
+		extensions: ["./x.ts"],
+		theme: "dark",
+		npmCommand: ["npm"],
+	}, null, 2)}\n`);
+	writeFileSync(join(source, "mcp-cache.json"), "{}");
+	writeFileSync(join(source, "mcp-npx-cache.json"), "{}");
+	writeFileSync(join(source, "AGENTS.md"), "# agents\n");
+	mkdirSync(join(source, "sessions"));
+}
+
+function snapshot(dir: string) {
+	return Object.fromEntries(readdirSync(dir).sort().map((name) => {
+		const stat = statSync(join(dir, name));
+		const hash = stat.isFile() ? createHash("sha256").update(readFileSync(join(dir, name))).digest("hex") : "dir";
+		return [name, { hash, mode: stat.mode, mtimeMs: stat.mtimeMs }];
+	}));
+}
+
+function statusOf(result: ReturnType<typeof importPi>, item: string) {
+	return result.items.find((entry) => entry.item === item)?.status;
+}
+
+const modeOf = (path: string) => statSync(path).mode & 0o777;
+
+test("copies auth.json (0600) and mcp.json (source mode) only when absent in the target", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "auth.json"), "copied");
+	assert.equal(statusOf(result, "mcp.json"), "copied");
+	assert.ok(readFileSync(join(f.target, "auth.json"), "utf8") === AUTH, "auth.json bytes copied verbatim");
+	assert.ok(readFileSync(join(f.target, "mcp.json"), "utf8") === MCP);
+	if (process.platform !== "win32") {
+		assert.equal(modeOf(join(f.target, "auth.json")), 0o600);
+		assert.equal(modeOf(join(f.target, "mcp.json")), 0o640);
+	}
+});
+
+test("never overwrites a target file that already exists and is idempotent", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	writeFileSync(join(f.target, "auth.json"), "{\"mine\":true}");
+	const first = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(first, "auth.json"), "present");
+	assert.ok(readFileSync(join(f.target, "auth.json"), "utf8") === "{\"mine\":true}", "existing target auth.json kept");
+	const before = snapshot(f.target);
+	const second = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(second.failed, false);
+	assert.ok(second.items.every((entry) => entry.status !== "copied"), "a second run copies nothing");
+	assert.deepEqual(snapshot(f.target), before);
+});
+
+test("never modifies the source: content, mode and mtime stay the same", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const before = snapshot(f.source);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(snapshot(f.source), before);
+});
+
+test("never copies caches, AGENTS.md, sessions or any other file", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(readdirSync(f.target).sort(), ["auth.json", "mcp.json", "settings.json"]);
+});
+
+test("missing source files are reported as not found, not errors", (t) => {
+	const f = fixture(t);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "auth.json"), "not found");
+	assert.equal(statusOf(result, "mcp.json"), "not found");
+	assert.equal(statusOf(result, "settings.json"), "not found");
+	assert.deepEqual(readdirSync(f.target), []);
+});
+
+test("skips a symlinked or non-regular source file", { skip: process.platform === "win32" }, (t) => {
+	const f = fixture(t);
+	writeFileSync(join(f.root, "elsewhere.json"), AUTH);
+	symlinkSync(join(f.root, "elsewhere.json"), join(f.source, "auth.json"));
+	mkdirSync(join(f.source, "mcp.json"));
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(result, "auth.json"), "skipped");
+	assert.equal(statusOf(result, "mcp.json"), "skipped");
+	assert.equal(existsSync(join(f.target, "auth.json")), false);
+	assert.equal(existsSync(join(f.target, "mcp.json")), false);
+});
+
+test("settings: copies only the default provider/model/thinking keys absent in the target, preserving every target key and order", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	writeFileSync(join(f.target, "settings.json"), `${JSON.stringify({ tuiMode: "fullscreen", theme: "Gentleman-Cute", defaultModel: "kept-model", packages: ["npm:own"] }, null, 2)}\n`);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "settings.json defaultProvider"), "copied");
+	assert.equal(statusOf(result, "settings.json defaultModel"), "present");
+	assert.equal(statusOf(result, "settings.json defaultThinkingLevel"), "copied");
+	const text = readFileSync(join(f.target, "settings.json"), "utf8");
+	assert.equal(text, `${JSON.stringify({
+		tuiMode: "fullscreen", theme: "Gentleman-Cute", defaultModel: "kept-model", packages: ["npm:own"],
+		defaultProvider: "anthropic", defaultThinkingLevel: "high",
+	}, null, 2)}\n`);
+});
+
+test("settings: the target keeps its own indentation and trailing-newline style", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	writeFileSync(join(f.target, "settings.json"), `{\n\t"tuiMode": "fullscreen",\n\t"zeta": 1\n}`);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(readFileSync(join(f.target, "settings.json"), "utf8"), JSON.stringify({
+		tuiMode: "fullscreen", zeta: 1, defaultProvider: "anthropic", defaultModel: "claude-opus-5-5", defaultThinkingLevel: "high",
+	}, null, "\t"));
+});
+
+test("settings: an unreadable settings.json is reported per item while the other items still run", (t) => {
+	if (process.platform === "win32" || process.getuid?.() === 0) return t.skip("needs POSIX permissions as a non-root user");
+	const f = fixture(t);
+	seedSource(f.source);
+	const settings = join(f.target, "settings.json");
+	writeFileSync(settings, "{}\n");
+	chmodSync(settings, 0o000);
+	try {
+		const result = importPi({ source: f.source, target: f.target, dryRun: false });
+		assert.equal(statusOf(result, "auth.json"), "copied");
+		assert.equal(statusOf(result, "settings.json"), "failed");
+		assert.equal(result.failed, true);
+		assert.match(formatImportPiReport(result, { source: f.source, target: f.target, dryRun: false }).join("\n"), /settings\.json: failed/);
+	} finally {
+		chmodSync(settings, 0o600);
+	}
+});
+
+test("a destination that cannot be classified is one failed item while the other items still run", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const blocked = join(f.target, "auth.json");
+	const fs = { ...nodeImportPiFs, kind: (path: string) => {
+		if (path === blocked) throw Object.assign(new Error(`ENOTDIR: not a directory, lstat '${path}'`), { code: "ENOTDIR" });
+		return nodeImportPiFs.kind(path);
+	} };
+	for (const dryRun of [true, false]) {
+		const result = importPi({ source: f.source, target: f.target, dryRun, fs });
+		assert.equal(statusOf(result, "auth.json"), "failed", `dryRun=${dryRun}`);
+		assert.equal(statusOf(result, "mcp.json"), dryRun ? "would copy" : "copied");
+		assert.equal(result.failed, true);
+	}
+});
+
+test("settings: a missing target settings.json gets only the allowlisted keys", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(JSON.parse(readFileSync(join(f.target, "settings.json"), "utf8")), {
+		defaultProvider: "anthropic", defaultModel: "claude-opus-5-5", defaultThinkingLevel: "high",
+	});
+});
+
+test("settings: nothing to add leaves the target settings.json untouched", (t) => {
+	const f = fixture(t);
+	writeFileSync(join(f.source, "settings.json"), JSON.stringify({ packages: ["npm:x"] }));
+	writeFileSync(join(f.target, "settings.json"), "{\"tuiMode\":\"fullscreen\"}");
+	const before = snapshot(f.target);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(snapshot(f.target), before);
+});
+
+test("settings: malformed source or target JSON is reported and nothing is written", (t) => {
+	const f = fixture(t);
+	writeFileSync(join(f.source, "settings.json"), "{ not json");
+	const badSource = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(badSource, "settings.json"), "skipped");
+	assert.equal(badSource.failed, false);
+	assert.equal(existsSync(join(f.target, "settings.json")), false);
+
+	writeFileSync(join(f.source, "settings.json"), JSON.stringify({ defaultProvider: "anthropic" }));
+	writeFileSync(join(f.target, "settings.json"), "[1, 2]");
+	const badTarget = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(badTarget, "settings.json"), "skipped");
+	assert.equal(readFileSync(join(f.target, "settings.json"), "utf8"), "[1, 2]");
+});
+
+test("dry run reports the same plan and writes nothing, not even the target directory", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const target = join(f.root, "not-created", "agent");
+	const result = importPi({ source: f.source, target, dryRun: true });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "auth.json"), "would copy");
+	assert.equal(statusOf(result, "settings.json defaultProvider"), "would copy");
+	assert.equal(existsSync(join(f.root, "not-created")), false);
+});
+
+test("a write failure is reported per item and keeps what was already copied", { skip: process.platform === "win32" }, (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	// A read-only target makes every write fail; nothing is half-written.
+	writeFileSync(join(f.target, "settings.json"), "{}");
+	chmodSync(f.target, 0o500);
+	let result;
+	try {
+		result = importPi({ source: f.source, target: f.target, dryRun: false });
+	} finally {
+		chmodSync(f.target, 0o700); // before the fixture's own cleanup
+	}
+	assert.equal(result.failed, true);
+	assert.equal(statusOf(result, "auth.json"), "failed");
+	assert.equal(statusOf(result, "settings.json defaultProvider"), "failed");
+});
+
+test("the report has one line per item and a summary, and never prints credential contents", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	const lines = formatImportPiReport(result, { source: f.source, target: f.target, dryRun: false });
+	const text = lines.join("\n");
+	assert.match(text, /auth\.json: copied \(0600\)/);
+	assert.match(text, /mcp\.json: copied/);
+	assert.match(text, /settings\.json defaultModel: copied/);
+	assert.match(text, /Imported 5 item\(s\)/);
+	assert.doesNotMatch(text, /dummy-refresh|dummy-access/);
+
+	const again = formatImportPiReport(importPi({ source: f.source, target: f.target, dryRun: true }), { source: f.source, target: f.target, dryRun: true });
+	assert.match(again.join("\n"), /auth\.json: already present, kept/);
+	assert.match(again.join("\n"), /Dry run/);
+	assert.match(again.join("\n"), /Nothing to import/);
+});

package/tests/gentle-shell-launcher.test.ts

@@ -5,7 +5,9 @@ import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection, parseChildPackageInjection } from "../lib/child-package-injection.ts";
 import {
+	GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV,
 	MIN_PI_VERSION,
+	withLauncherPackagesExcluded,
 	MIN_SETUP_GENTLE_AI_VERSION,
 	PI_SUBCOMMANDS,
 	buildPiInvocation,
@@ -37,6 +39,7 @@ import {
 	userPiHome,
 	resolvePiRuntime,
 	restoreJsonField,
+	separateHomeHint,
 	settingsDeclareGentlePi,
 	shellQuote,
 	type PackageJsonPeerShape,
@@ -66,6 +69,20 @@ test("parseLauncherArgs returns all-false defaults for an empty argv", () => {
 	});
 });
 
+test("parseLauncherArgs reserves explicit memory recovery without consuming prior commands or escaped prompts", () => {
+	const memory = parseLauncherArgs(["memory", "migrate", "--confirm-quiescent"]);
+	assert.equal(memory.command, "memory");
+	assert.deepEqual(memory.commandArgs, ["migrate", "--confirm-quiescent"]);
+	assert.deepEqual(memory.passthrough, []);
+	for (const command of ["home", "upgrade", "self-uninstall"] as const) {
+		const parsed = parseLauncherArgs([command, "--help"]);
+		assert.equal(parsed.command, command);
+		assert.deepEqual(parsed.commandArgs, ["--help"]);
+	}
+	assert.deepEqual(parseLauncherArgs(["--", "memory"]).passthrough, ["memory"]);
+	assert.match(helpText(), /gentle-shell memory migrate --confirm-quiescent/);
+});
+
 test("parseLauncherArgs captures a --package-root value from the next argument", () => {
 	assert.equal(parseLauncherArgs(["--package-root", "/custom/root"]).packageRoot, "/custom/root");
 });
@@ -205,6 +222,40 @@ test("parseLauncherArgs treats home as a plain passthrough token when it is not
 	assert.deepEqual(parsed.passthrough, ["home"]);
 });
 
+test("parseLauncherArgs accepts home selectors ahead of home import-pi only", () => {
+	const link = parseLauncherArgs(["--link", "home", "import-pi"]);
+	assert.equal(link.link, true);
+	assert.equal(link.command, "home");
+	assert.deepEqual(link.commandArgs, ["import-pi"]);
+	assert.deepEqual(link.passthrough, []);
+	const path = parseLauncherArgs(["--home", "/x", "home", "import-pi", "--dry-run"]);
+	assert.equal(path.home, "/x");
+	assert.equal(path.command, "home");
+	assert.deepEqual(path.commandArgs, ["import-pi", "--dry-run"]);
+	const first = parseLauncherArgs(["home", "import-pi", "--dry-run"]);
+	assert.equal(first.command, "home");
+	assert.deepEqual(first.commandArgs, ["import-pi", "--dry-run"]);
+	// Anything else after a selector stays pi's, as before.
+	assert.deepEqual(parseLauncherArgs(["--link", "home", "link"]).passthrough, ["home", "link"]);
+	assert.deepEqual(parseLauncherArgs(["-p", "home", "import-pi"]).passthrough, ["-p", "home", "import-pi"]);
+});
+
+test("help text documents gentle-shell home import-pi", () => {
+	const text = helpText();
+	assert.ok(text.includes("       gentle-shell [home selectors] home import-pi [--dry-run]"));
+	assert.match(text, /import-pi\s+Copy your pi sign-ins \(auth\.json\) and MCP servers \(mcp\.json\)/);
+});
+
+test("separateHomeHint mentions home import-pi only when the user's pi home has sign-ins", () => {
+	const isolated: ResolvedHome = { mode: "isolated", dir: "/h/.gentle-shell/agent", source: "default" };
+	const without = separateHomeHint(isolated, { piSignIns: false });
+	assert.equal(without, "gentle-shell: using a separate home at /h/.gentle-shell/agent. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.");
+	const withSignIns = separateHomeHint(isolated, { piSignIns: true });
+	assert.match(withSignIns, /Run 'gentle-shell --link' to reuse your pi sign-ins and chats, or 'gentle-shell home import-pi' to copy your sign-ins and MCP servers into this home\.$/);
+	const path = separateHomeHint({ mode: "path", dir: "/custom", source: "flag" }, { piSignIns: true });
+	assert.match(path, /'gentle-shell --home \/custom home import-pi'/);
+});
+
 // --- setup subcommand ----------------------------------------------------
 //
 // Unlike `home`, `setup` is not restricted to argv[0]: it accepts the home
@@ -293,6 +344,19 @@ test("parseLauncherArgs recognises a pi subcommand as the first token after --",
 	assert.deepEqual(parsed.passthrough, ["install", "npm:x"]);
 });
 
+test("parseLauncherArgs keeps a separator that follows a pi subcommand (#2140)", () => {
+	const parsed = parseLauncherArgs(["mcp", "add", "demo", "--", "npx", "demo-server"]);
+	assert.equal(parsed.piSubcommand, "mcp");
+	assert.deepEqual(parsed.passthrough, ["mcp", "add", "demo", "--", "npx", "demo-server"]);
+});
+
+test("parseLauncherArgs still consumes a later separator when no pi subcommand started", () => {
+	const parsed = parseLauncherArgs(["hello", "--", "--link"]);
+	assert.equal(parsed.piSubcommand, undefined);
+	assert.equal(parsed.link, false);
+	assert.deepEqual(parsed.passthrough, ["hello", "--link"]);
+});
+
 test("parseLauncherArgs errors when --link is combined with --isolated", () => {
 	const parsed = parseLauncherArgs(["--link", "--isolated"]);
 	assert.match(parsed.error ?? "", /--link/);
@@ -1826,8 +1890,34 @@ test("quoteForCmdExe leaves a plain token untouched", () => {
 	assert.equal(quoteForCmdExe("pi"), "pi");
 });
 
-test("quoteForCmdExe quotes a token with a space and escapes an inner double quote", () => {
-	assert.equal(quoteForCmdExe('say "hi" now'), '"say \\"hi\\" now"');
+test("quoteForCmdExe quotes a token with a space and the other cmd.exe specials", () => {
+	assert.equal(quoteForCmdExe("say hi now"), '"say hi now"');
+	assert.equal(quoteForCmdExe("a&b"), '"a&b"');
+});
+
+// cmd.exe has no backslash escape: a `"` inside a quoted token ends the
+// quoted section, so everything after it is parsed as command syntax. The
+// simple quoting cannot represent such a token, so it refuses it instead of
+// emitting a command line that lets the argument inject commands.
+test("quoteForCmdExe rejects a token with a double quote", () => {
+	for (const token of ['say "hi" now', 'x" & whoami & rem "', '"', 'a"b']) {
+		assert.throws(() => quoteForCmdExe(token), /double quote/);
+	}
+});
+
+test("planSpawn refuses a win32 .cmd launch whose argument carries a double quote", () => {
+	const hostile = 'x" & whoami & rem "';
+	for (const command of ["C:\\Program Files\\nodejs\\pi.cmd", "C:\\pi\\pi.BAT"]) {
+		assert.throws(() => planSpawn({ command, args: ["--version", hostile], platform: "win32" }), /double quote/);
+	}
+	assert.throws(() => planSpawn({ command: 'C:\\pi\\a"b.cmd', args: [], platform: "win32" }), /double quote/);
+});
+
+test("planSpawn passes a double quote through when no cmd.exe command line is built", () => {
+	const args = ["--prompt", 'say "hi"'];
+	assert.deepEqual(planSpawn({ command: "C:\\pi\\pi.exe", args, platform: "win32" }), { command: "C:\\pi\\pi.exe", args, shell: false });
+	assert.deepEqual(planSpawn({ command: "/usr/bin/pi", args, platform: "linux" }), { command: "/usr/bin/pi", args, shell: false });
+	assert.deepEqual(planSpawn({ command: "/usr/local/bin/pi.cmd", args, platform: "darwin" }), { command: "/usr/local/bin/pi.cmd", args, shell: false });
 });
 
 test("quoteForCmdExe quotes an empty token", () => {
@@ -2032,3 +2122,18 @@ test("the isolated-home bootstrap creates ~/.gentle-shell as 0700 under umask 00
 		rmSync(root, { recursive: true, force: true });
 	}
 });
+
+// #2143: Gentle AI installs npm:gentle-pi into the home only for the launcher
+// to remove it again; a Gentle AI with package exclusion (gentle-ai#5503)
+// skips it, and an older one ignores the variable.
+test("withLauncherPackagesExcluded asks Gentle AI to skip npm:gentle-pi, keeping a caller's own exclusions", () => {
+	assert.equal(GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV, "GENTLE_AI_PI_EXCLUDE_PACKAGES");
+	assert.equal(withLauncherPackagesExcluded({ PATH: "/bin" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:gentle-pi");
+	assert.equal(withLauncherPackagesExcluded({ GENTLE_AI_PI_EXCLUDE_PACKAGES: "" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:gentle-pi");
+	assert.equal(withLauncherPackagesExcluded({ GENTLE_AI_PI_EXCLUDE_PACKAGES: "npm:pi-btw" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:pi-btw,npm:gentle-pi");
+	assert.equal(withLauncherPackagesExcluded({ GENTLE_AI_PI_EXCLUDE_PACKAGES: "npm:gentle-pi, npm:pi-btw" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:gentle-pi,npm:pi-btw");
+	const input = { PATH: "/bin" };
+	assert.equal(withLauncherPackagesExcluded(input).PATH, "/bin");
+	assert.deepEqual(input, { PATH: "/bin" }, "the caller's env is not mutated");
+});
+

package/tests/gentle-shell-startup-update.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { parseLauncherArgs } from "../lib/gentle-shell-launcher.ts";
-import { findStartupUpdate, shouldCheckStartupUpdate } from "../lib/gentle-shell-startup-update.ts";
+import { findStartupUpdate, parseStartupReleaseCache, shouldCheckStartupUpdate, writeStartupReleaseCache } from "../lib/gentle-shell-startup-update.ts";
 
 const eligible = {
 	args: parseLauncherArgs([]), env: {}, bundled: true, inputTTY: true, outputTTY: true,
@@ -83,3 +83,79 @@ test("custom deadline is bounded and settled lookups clear the timeout", async (
 	t.mock.timers.tick(20);
 	assert.equal(settledSignal?.aborted, false);
 });
+
+// A fresh cache keeps the everyday launch off the network entirely: the offer
+// (or its absence) is decided from the recorded lookup, and the live lookup —
+// whose result is the only thing worth caching — runs only when the cache is
+// stale, missing, or malformed.
+test("a fresh cache decides the offer without touching the network", async () => {
+	const offline = async (): Promise<string> => { throw new Error("lookup must not run on a fresh cache"); };
+	const fresh = { checkedAt: Date.now() - 60 * 60 * 1000, latest: "2.0.0" };
+	assert.deepEqual(await findStartupUpdate({ current: "1.0.0", lookup: offline, cache: fresh, ttlMs: 24 * 60 * 60 * 1000 }), {
+		current: "1.0.0", latest: "2.0.0", notesUrl: "https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v2.0.0",
+	});
+	assert.equal(await findStartupUpdate({ current: "2.0.0", lookup: offline, cache: fresh, ttlMs: 24 * 60 * 60 * 1000 }), undefined);
+});
+
+test("a fresh cache respects the skipped release exactly like a live lookup", async () => {
+	const offline = async (): Promise<string> => { throw new Error("lookup must not run on a fresh cache"); };
+	assert.equal(await findStartupUpdate({ current: "1.0.0", skipped: "2.0.0", lookup: offline, cache: { checkedAt: Date.now() - 1000, latest: "2.0.0" } }), undefined);
+	assert.equal((await findStartupUpdate({ current: "1.0.0", skipped: "2.0.0", lookup: offline, cache: { checkedAt: Date.now() - 1000, latest: "2.0.1" } }))?.latest, "2.0.1");
+});
+
+test("a stale, missing or malformed cache runs the live lookup and records its answer", async () => {
+	const written: string[] = [];
+	const opts = {
+		current: "1.0.0",
+		lookup: async () => "2.0.1",
+		ttlMs: 1000,
+		cacheWrite: (latest: string) => { written.push(latest); },
+	};
+	// Stale beyond the TTL.
+	assert.equal((await findStartupUpdate({ ...opts, cache: { checkedAt: Date.now() - 1001, latest: "2.0.0" } }))?.latest, "2.0.1");
+	// No cache at all.
+	assert.equal((await findStartupUpdate({ ...opts }))?.latest, "2.0.1");
+	// A cache whose latest never parsed: never trusted, refreshed instead.
+	assert.equal((await findStartupUpdate({ ...opts, cache: { checkedAt: Date.now() - 1, latest: "garbage" } }))?.latest, "2.0.1");
+	assert.deepEqual(written, ["2.0.1", "2.0.1", "2.0.1"]);
+});
+
+test("an unanswered lookup is never cached", async () => {
+	const written: string[] = [];
+	assert.equal(await findStartupUpdate({ current: "1.0.0", lookup: async () => undefined, cacheWrite: (latest) => { written.push(latest); } }), undefined);
+	assert.equal(await findStartupUpdate({ current: "1.0.0", lookup: async () => { throw new Error("offline"); }, cacheWrite: (latest) => { written.push(latest); } }), undefined);
+	assert.deepEqual(written, []);
+});
+
+test("the cache ages against the injected clock, not the wall", async () => {
+	const now = 1_700_000_000_000;
+	const offline = async (): Promise<string> => { throw new Error("lookup must not run on a fresh cache"); };
+	// Exactly at the TTL boundary the cache is already stale: the check errs
+	// toward the live lookup, never toward skipping it.
+	assert.equal((await findStartupUpdate({ current: "1.0.0", lookup: async () => "2.0.0", ttlMs: 1000, nowMs: now, cache: { checkedAt: now - 1000, latest: "2.0.0" } }))?.latest, "2.0.0");
+	assert.deepEqual(await findStartupUpdate({ current: "1.0.0", lookup: offline, ttlMs: 1000, nowMs: now - 1, cache: { checkedAt: now - 1000, latest: "2.0.0" } }).then((offer) => offer?.latest), "2.0.0");
+});
+
+test("parseStartupReleaseCache accepts the recorded shape and rejects everything else", () => {
+	assert.deepEqual(parseStartupReleaseCache({ checkedAt: "2026-01-01T00:00:00.000Z", latest: "2.0.1" }), { checkedAt: Date.parse("2026-01-01T00:00:00.000Z"), latest: "2.0.1" });
+	assert.deepEqual(parseStartupReleaseCache({ checkedAt: 1_700_000_000_000, latest: "2.0.1" }), { checkedAt: 1_700_000_000_000, latest: "2.0.1" });
+	for (const bad of [undefined, null, "x", [], {}, { checkedAt: "nope", latest: "2.0.1" }, { checkedAt: 1_700_000_000_000 }, { checkedAt: 1_700_000_000_000, latest: "" }]) {
+		assert.equal(parseStartupReleaseCache(bad), undefined);
+	}
+});
+
+test("writeStartupReleaseCache records one lookup alongside the existing config keys", () => {
+	const stored: string[] = [];
+	const config = JSON.stringify({ skippedStartupRelease: "9.9.9", other: { nested: true } });
+	writeStartupReleaseCache(() => config, (text) => stored.push(text), "2.0.1", 1_700_000_000_000);
+	const saved = JSON.parse(stored[0]);
+	assert.equal(saved.skippedStartupRelease, "9.9.9");
+	assert.deepEqual(saved.other, { nested: true });
+	assert.equal(saved.startupReleaseCheck.latest, "2.0.1");
+	assert.equal(saved.startupReleaseCheck.checkedAt, new Date(1_700_000_000_000).toISOString());
+	// An absent config file starts a minimal one.
+	writeStartupReleaseCache(() => undefined, (text) => stored.push(text), "2.0.1");
+	assert.deepEqual(JSON.parse(stored[1]).startupReleaseCheck.latest, "2.0.1");
+	// An invalid config must fail loudly, never overwrite it silently.
+	assert.throws(() => writeStartupReleaseCache(() => "{ broken", () => {}, "2.0.1"));
+});

package/tests/gentle-shell-uninstall.test.ts

@@ -976,3 +976,92 @@ test("bundled on Windows: the user Path entry goes first, the running node.exe,
 		assert.equal(existsSync(join(w.shared.agent, "auth.json")), true);
 	} finally { w.cleanup(); }
 });
+
+// #2469: a home that self-uninstall keeps must not keep Pi pointed at the npm
+// the uninstall removed: a stale `npmCommand` makes every later `pi install`
+// fail with ENOENT naming the deleted node.exe.
+const bundledNpmCommand = (w: BundledWorld) => [w.node, join(dirname(w.node), "gentle-shell", "npm"), "--update-notifier=false"];
+
+const bundledNpmSettings = (w: BundledWorld, npmCommand: unknown) => `${JSON.stringify({ theme: "dark", npmCommand }, null, "  ")}\n`;
+
+test("bundled: keeping the home removes the npmCommand that names the removed prefix and keeps the rest of settings.json", posixOnly, async () => {
+	const w = bundledWorld();
+	try {
+		const settings = join(w.shared.agent, "settings.json");
+		write(settings, bundledNpmSettings(w, bundledNpmCommand(w)));
+		assert.equal(await w.uninstall(["--yes"]), 0, w.err.join("\n"));
+		assert.deepEqual(JSON.parse(readFileSync(settings, "utf8")), { theme: "dark" });
+		assert.ok(w.out.join("\n").includes(`npmCommand from ${settings}`), w.out.join("\n"));
+	} finally { w.cleanup(); }
+});
+
+test("bundled: keeping the home leaves settings.json alone when npmCommand does not name the prefix", posixOnly, async () => {
+	const w = bundledWorld();
+	try {
+		const settings = join(w.shared.agent, "settings.json");
+		const text = bundledNpmSettings(w, ["/usr/local/bin/node", "--update-notifier=false"]);
+		write(settings, text);
+		assert.equal(await w.uninstall(["--yes"]), 0, w.err.join("\n"));
+		assert.equal(readFileSync(settings, "utf8"), text);
+	} finally { w.cleanup(); }
+});
+
+test("bundled: keeping the home never rewrites a settings.json that is not a JSON object", posixOnly, async () => {
+	const w = bundledWorld();
+	try {
+		const settings = join(w.shared.agent, "settings.json");
+		write(settings, "not json at all\n");
+		assert.equal(await w.uninstall(["--yes"]), 0, w.err.join("\n"));
+		assert.equal(readFileSync(settings, "utf8"), "not json at all\n");
+	} finally { w.cleanup(); }
+});
+
+test("bundled on Windows: keeping the home also removes the npmCommand naming the removed prefix", async () => {
+	const w = bundledWorld({ platform: "win32" });
+	try {
+		const settings = join(w.shared.agent, "settings.json");
+		write(settings, `${JSON.stringify({ npmCommand: bundledNpmCommand(w) }, null, "  ")}\n`);
+		assert.equal(await w.uninstall(["--yes"]), 0, w.err.join("\n"));
+		assert.equal(readFileSync(settings, "utf8"), "{}\n");
+		assert.ok(w.out.join("\n").includes(`npmCommand from ${settings}`), w.out.join("\n"));
+	} finally { w.cleanup(); }
+});
+
+test("bundled: --include-shared removes the home with its settings, so no npmCommand cleanup is needed", posixOnly, async () => {
+	const w = bundledWorld();
+	try {
+		write(join(w.shared.agent, "settings.json"), bundledNpmSettings(w, bundledNpmCommand(w)));
+		assert.equal(await w.uninstall(["--yes", "--include-shared"]), 0, w.err.join("\n"));
+		assert.equal(existsSync(join(w.shared.agent, "settings.json")), false);
+	} finally { w.cleanup(); }
+});
+
+// #2201: the standalone isolated home keeps its config in ~/.gentle-shell/gentle-ai.
+test("Gentle Shell's own config folder next to the isolated home is removed; the shared config home keeps its rule", async () => {
+	const w = world();
+	try {
+		const own = join(w.shell, "gentle-ai");
+		write(join(own, "profiles.json"));
+		write(join(own, "persona.json"));
+		assert.equal(await w.uninstall(["--dry-run"]), 0);
+		assert.ok(section(w.out, "Remove Gentle Shell data:").some((line) => line.includes(own)), w.out.join("\n"));
+		assert.equal(await w.uninstall(["--yes"]), 0);
+		assert.equal(existsSync(own), false);
+		assert.equal(existsSync(w.shell), false);
+		for (const name of ["profiles.json", "persona.json"]) assert.equal(existsSync(join(w.config, name)), true, name);
+	} finally { w.cleanup(); }
+});
+
+test("the gentle-ai folder next to a custom GENTLE_SHELL_HOME is kept: it may not be Gentle Shell's", async () => {
+	const w = world();
+	try {
+		const custom = join(w.root, "elsewhere", "agent");
+		const sibling = join(w.root, "elsewhere", "gentle-ai");
+		write(join(custom, ".gentle-shell-home"));
+		write(join(sibling, "notes.json"));
+		assert.equal(await w.uninstall(["--yes"], { env: { GENTLE_SHELL_HOME: custom } }), 0);
+		assert.equal(existsSync(custom), false);
+		assert.equal(existsSync(join(sibling, "notes.json")), true);
+		assert.ok(section(w.out, "Kept:").some((line) => line.includes(sibling)), w.out.join("\n"));
+	} finally { w.cleanup(); }
+});