gentle-pi 4.0.0 → 4.1.0

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

@@ -1,8 +1,9 @@
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import test from "node:test";
+import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection, parseChildPackageInjection } from "../lib/child-package-injection.ts";
 import {
 	MIN_PI_VERSION,
 	MIN_SETUP_GENTLE_AI_VERSION,
@@ -154,6 +155,50 @@ test("parseLauncherArgs recognises the home subcommand as argv[0] and captures t
 	assert.deepEqual(parsed.passthrough, []);
 });
 
+test("parseLauncherArgs recognises the upgrade subcommand as argv[0] and captures its arguments", () => {
+	const parsed = parseLauncherArgs(["upgrade", "--channel", "main"]);
+	assert.equal(parsed.command, "upgrade");
+	assert.deepEqual(parsed.commandArgs, ["--channel", "main"]);
+	assert.deepEqual(parsed.passthrough, []);
+	assert.equal(parsed.piSubcommand, undefined);
+});
+
+test("parseLauncherArgs recognises the self-uninstall subcommand as argv[0] and captures its arguments", () => {
+	const parsed = parseLauncherArgs(["self-uninstall", "--dry-run", "--include-shared"]);
+	assert.equal(parsed.command, "self-uninstall");
+	assert.deepEqual(parsed.commandArgs, ["--dry-run", "--include-shared"]);
+	assert.deepEqual(parsed.passthrough, []);
+	assert.equal(parsed.piSubcommand, undefined);
+	assert.equal(parsed.error, undefined);
+});
+
+test("parseLauncherArgs keeps uninstall as pi's own alias for remove", () => {
+	const parsed = parseLauncherArgs(["uninstall", "npm:x"]);
+	assert.equal(parsed.command, undefined);
+	assert.equal(parsed.piSubcommand, "uninstall");
+	assert.deepEqual(parsed.passthrough, ["uninstall", "npm:x"]);
+});
+
+test("help text documents gentle-shell self-uninstall and its flags", () => {
+	const text = helpText();
+	assert.ok(text.includes("       gentle-shell self-uninstall [--dry-run] [--yes] [--include-shared]"));
+	assert.ok(text.includes("  self-uninstall   Remove Gentle Shell: its own data, the isolated home and the gentle-pi"));
+	assert.match(text, /'gentle-shell uninstall <source>' is pi's own alias for 'remove'/);
+});
+
+test("help text documents gentle-shell upgrade and its channels", () => {
+	const text = helpText();
+	assert.ok(text.includes("       gentle-shell upgrade [--channel release|main]"));
+	assert.ok(text.includes("  upgrade          Update Gentle Shell along its channel: the latest release, or the latest"));
+});
+
+test("help text documents the bundled upgrade, its rollback and the pinned Pi update", () => {
+	const text = helpText();
+	assert.ok(text.includes("       gentle-shell upgrade --rollback"));
+	assert.match(text, /bundled install.*release channel only.*--rollback switches back to the previous kept version/s);
+	assert.match(text, /In a bundled install Pi ships pinned: 'update' without a package\n\s+runs 'gentle-shell upgrade'/);
+});
+
 test("parseLauncherArgs treats home as a plain passthrough token when it is not argv[0]", () => {
 	const parsed = parseLauncherArgs(["--isolated", "home"]);
 	assert.equal(parsed.command, undefined);
@@ -310,6 +355,22 @@ test("resolveHome falls back to <homedir>/.pi/agent for --link with no override"
 	assert.deepEqual(resolved, { mode: "link", dir: join("/home/alan", ".pi", "agent"), source: "flag" });
 });
 
+test("--link inside an isolated session resolves the preserved original Pi home (#2015)", () => {
+	const nestedEnv = { PI_CODING_AGENT_DIR: "/home/alan/.gentle-shell/agent", GENTLE_SHELL_USER_PI_HOME: "/custom/pi" };
+	// Nested: the inherited isolated home must not be re-selected.
+	assert.deepEqual(
+		resolveHome({ args: args({ link: true }), env: nestedEnv, homedir: "/home/alan", config: undefined }),
+		{ mode: "link", dir: "/custom/pi", source: "flag" },
+	);
+	assert.deepEqual(
+		resolveHome({ args: args(), env: nestedEnv, homedir: "/home/alan", config: { mode: "link" } }),
+		{ mode: "link", dir: "/custom/pi", source: "config" },
+	);
+	// Clean terminal: a custom override and the conventional home are unchanged.
+	assert.equal(resolveHome({ args: args({ link: true }), env: { PI_CODING_AGENT_DIR: "/custom/pi" }, homedir: "/home/alan", config: undefined }).dir, "/custom/pi");
+	assert.equal(resolveHome({ args: args({ link: true }), env: {}, homedir: "/home/alan", config: undefined }).dir, join("/home/alan", ".pi", "agent"));
+});
+
 test("resolveHome honours --isolated and reads GENTLE_SHELL_HOME", () => {
 	const resolved = resolveHome({
 		args: args({ isolated: true }),
@@ -852,7 +913,7 @@ test("findGentlePiDeclaration detects a bare npm:gentle-pi object source entry",
 });
 
 test("findGentlePiDeclaration recognises a relative path entry whose package.json name is gentle-pi", () => {
-	const resolvedDir = join("/agent", "..", "..", "work", "gentle-pi");
+	const resolvedDir = resolve("/agent", "..", "..", "work", "gentle-pi");
 	const result = findGentlePiDeclaration('{"packages":["../../work/gentle-pi"]}', {
 		agentDir: "/agent",
 		readPackageName: readPackageNameStub({ [resolvedDir]: "gentle-pi" }),
@@ -863,17 +924,17 @@ test("findGentlePiDeclaration recognises a relative path entry whose package.jso
 test("findGentlePiDeclaration recognises an absolute path entry whose package.json name is gentle-pi", () => {
 	const result = findGentlePiDeclaration('{"packages":["/checkouts/gentle-pi"]}', {
 		agentDir: "/agent",
-		readPackageName: readPackageNameStub({ "/checkouts/gentle-pi": "gentle-pi" }),
+		readPackageName: readPackageNameStub({ [resolve("/checkouts/gentle-pi")]: "gentle-pi" }),
 	});
-	assert.deepEqual(result, { kind: "path", dir: "/checkouts/gentle-pi" });
+	assert.deepEqual(result, { kind: "path", dir: resolve("/checkouts/gentle-pi") });
 });
 
 test("findGentlePiDeclaration recognises a path object source entry whose package.json name is gentle-pi", () => {
 	const result = findGentlePiDeclaration('{"packages":[{"source":"../gentle-pi","extensions":[]}]}', {
 		agentDir: "/agent",
-		readPackageName: readPackageNameStub({ [join("/agent", "..", "gentle-pi")]: "gentle-pi" }),
+		readPackageName: readPackageNameStub({ [resolve("/agent", "..", "gentle-pi")]: "gentle-pi" }),
 	});
-	assert.deepEqual(result, { kind: "path", dir: join("/agent", "..", "gentle-pi") });
+	assert.deepEqual(result, { kind: "path", dir: resolve("/agent", "..", "gentle-pi") });
 });
 
 test("findGentlePiDeclaration is undefined for a path entry whose package.json name is not gentle-pi", () => {
@@ -906,9 +967,9 @@ test("findGentlePiDeclaration is undefined when packages lists unrelated entries
 test("findGentlePiDeclaration returns the first matching declaration, path or npm, in list order", () => {
 	const result = findGentlePiDeclaration('{"packages":["../gentle-pi","npm:gentle-pi"]}', {
 		agentDir: "/agent",
-		readPackageName: readPackageNameStub({ [join("/agent", "..", "gentle-pi")]: "gentle-pi" }),
+		readPackageName: readPackageNameStub({ [resolve("/agent", "..", "gentle-pi")]: "gentle-pi" }),
 	});
-	assert.deepEqual(result, { kind: "path", dir: join("/agent", "..", "gentle-pi") });
+	assert.deepEqual(result, { kind: "path", dir: resolve("/agent", "..", "gentle-pi") });
 });
 
 // --- decideTakeOver -----------------------------------------------------------
@@ -992,7 +1053,7 @@ test("otherPackageInjections resolves a path entry relative to agentDir", () =>
 		agentDir: "/agent",
 		skip: { kind: "npm" },
 	});
-	assert.deepEqual(result.paths, [join("/agent", "..", "..", "work", "pi-qwen-ambassador")]);
+	assert.deepEqual(result.paths, [resolve("/agent", "..", "..", "work", "pi-qwen-ambassador")]);
 });
 
 test("otherPackageInjections skips a git entry and warns", () => {
@@ -1018,7 +1079,7 @@ test("otherPackageInjections warns for an object entry with extensions or autolo
 });
 
 test("otherPackageInjections skips the entry matching a path declaration being taken over", () => {
-	const declaredDir = join("/agent", "..", "..", "work", "gentle-pi");
+	const declaredDir = resolve("/agent", "..", "..", "work", "gentle-pi");
 	const result = otherPackageInjections({
 		settingsText: '{"packages":["npm:some-other","../../work/gentle-pi"]}',
 		agentDir: "/agent",
@@ -1033,7 +1094,7 @@ test("otherPackageInjections tolerates undefined or malformed settings text", ()
 });
 
 test("otherPackageInjections skips every gentle-pi entry, not only the one matching the declaration kind", () => {
-	const declaredDir = join("/agent", "..", "..", "work", "gentle-pi");
+	const declaredDir = resolve("/agent", "..", "..", "work", "gentle-pi");
 	const result = otherPackageInjections({
 		// The declaration being taken over is the path entry, but settings
 		// also carries a second, unrelated npm:gentle-pi entry: both must be
@@ -1088,7 +1149,7 @@ test("otherPackageInjections keeps a declared package directory that isDirectory
 });
 
 test("otherPackageInjections excludes a settings path entry that resolves via realpath to the same physical directory as a realpath'd skip (R4-forced-root-symlink-double-injection)", () => {
-	const linkOtherDir = join("/agent", "link-other");
+	const linkOtherDir = resolve("/agent", "link-other");
 	const result = otherPackageInjections({
 		settingsText: '{"packages":["link-other","npm:some-other"]}',
 		agentDir: "/agent",
@@ -1107,7 +1168,7 @@ test("otherPackageInjections keeps comparing raw strings when no realpath resolv
 		agentDir: "/agent",
 		skip: { kind: "path", dir: "/real/other" },
 	});
-	assert.deepEqual(result.paths, [join("/agent", "link-other"), join("/agent", "npm", "node_modules", "some-other")]);
+	assert.deepEqual(result.paths, [resolve("/agent", "link-other"), join("/agent", "npm", "node_modules", "some-other")]);
 });
 
 test("otherPackageInjections defaults to including every declared package when isDirectory is not provided (existing callers keep pure string resolution)", () => {
@@ -1134,6 +1195,7 @@ test("package injection relies on Pi's -e resource discovery in isolated and tak
 			passthrough: [],
 			baseEnv: {},
 			homedir: "/home/u",
+			cwd: "/work",
 		});
 		assert.deepEqual(built.args, takeOver ? ["--no-extensions", "-e", "/pkg"] : ["-e", "/pkg"]);
 	}
@@ -1153,6 +1215,7 @@ test("buildPiInvocation injects the launcher env into baseEnv", () => {
 		passthrough: [],
 		baseEnv: { PATH: "/usr/bin" },
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.env, { PATH: "/usr/bin", PI_CODING_AGENT_DIR: "/pi/agent", GENTLE_PI_AGENT_HOME: "/pi/agent", GENTLE_SHELL_USER_PI_HOME: join("/home/u", ".pi", "agent") });
 });
@@ -1168,6 +1231,7 @@ test("buildPiInvocation skips injection when there is a declaration and no takeo
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.command, "/usr/bin/pi");
 	assert.deepEqual(built.args, ["--mode", "rpc"]);
@@ -1184,6 +1248,7 @@ test("buildPiInvocation adds the gentle-pi injection flags when there is no decl
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, [
 		"-e",
@@ -1205,6 +1270,7 @@ test("buildPiInvocation emits only runtime args and passthrough when a pi subcom
 		piSubcommand: "install",
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, ["install", "npm:x"]);
 	assert.equal(built.command, "/usr/bin/pi");
@@ -1222,6 +1288,7 @@ test("buildPiInvocation still injects the launcher env for a pi subcommand", ()
 		piSubcommand: "list",
 		baseEnv: { PATH: "/usr/bin" },
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.env, {
 		PATH: "/usr/bin",
@@ -1243,6 +1310,7 @@ test("buildPiInvocation in link mode with a pi subcommand is exactly pi <subcomm
 		piSubcommand: "auth",
 		baseEnv: { PI_CODING_AGENT_DIR: "/pi/agent" },
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.equal(built.command, "/usr/bin/pi");
 	assert.deepEqual(built.args, ["auth", "status"]);
@@ -1263,6 +1331,7 @@ test("buildPiInvocation carries the user's original Pi home without weakening is
 		passthrough: [],
 		baseEnv,
 		homedir: "/home/u",
+		cwd: "/work",
 	}).env;
 	const conventional = build({});
 	assert.equal(conventional.PI_CODING_AGENT_DIR, "/gentle-shell/agent");
@@ -1297,6 +1366,7 @@ test("buildPiInvocation keeps the runtime's own args ahead of the injection and
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.equal(built.args[0], "/bundled/cli.js");
 	assert.equal(built.command, "/usr/bin/node");
@@ -1313,6 +1383,7 @@ test("buildPiInvocation takes over a conflicting path declaration: --no-extensio
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1336,6 +1407,7 @@ test("buildPiInvocation takes over with --package-root even for a matching npm d
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1355,6 +1427,7 @@ test("buildPiInvocation takes over with --package-root even when there is no dec
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1377,6 +1450,7 @@ test("buildPiInvocation injects loose extension entries during a takeover, after
 		passthrough: ["--mode", "rpc"],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1404,6 +1478,7 @@ test("buildPiInvocation omits loose extension entry flags when the list is empty
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(withoutField.args, ["--no-extensions", "-e", "/pkg"]);
 
@@ -1418,6 +1493,7 @@ test("buildPiInvocation omits loose extension entry flags when the list is empty
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(withEmptyField.args, withoutField.args);
 });
@@ -1439,6 +1515,7 @@ test("buildPiInvocation dedupes loose extension entries against other-package pa
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	assert.deepEqual(built.args, [
 		"--no-extensions",
@@ -1468,6 +1545,7 @@ test("buildPiInvocation dedupes the launcher's own package root against an other
 		passthrough: [],
 		baseEnv: {},
 		homedir: "/home/u",
+		cwd: "/work",
 	});
 	const eFlags = built.args.filter((arg, index) => built.args[index - 1] === "-e");
 	assert.deepEqual(eFlags, [join("/agent", "npm", "node_modules", "some-other"), "/pkg"]);
@@ -1480,6 +1558,127 @@ test("buildPiInvocation dedupes the launcher's own package root against an other
 	]);
 });
 
+// --- child package injection signal (#1690) ----------------------------------
+//
+// The launcher exports exactly the -e set it computed itself, so the subagent
+// runner can forward it to delegated children. Passthrough -e flags are not
+// part of the signal.
+
+const injectionInput = {
+	runtime: { kind: "path" as const, command: "/usr/bin/pi", args: [] },
+	home: isolatedHomeResolved,
+	packageRoot: "/pkg",
+	otherPackagePaths: [],
+	passthrough: ["-e", "/user/ext.ts", "--mode", "rpc"],
+	homedir: "/home/u",
+	cwd: "/work",
+};
+
+test("buildPiInvocation signals the packageRoot injection when there is no declaration", () => {
+	const built = buildPiInvocation({ ...injectionInput, declaration: undefined, takeOver: false, baseEnv: {} });
+	assert.deepEqual(parseChildPackageInjection(built.env), { noExtensions: false, extensionPaths: ["/pkg"] });
+});
+
+test("buildPiInvocation signals the exact deduped takeover -e set in order, without passthrough -e flags", () => {
+	const built = buildPiInvocation({
+		...injectionInput,
+		home: linkHome,
+		declaration: { kind: "path", dir: "/other/checkout" },
+		takeOver: true,
+		otherPackagePaths: ["/agent/npm/node_modules/some-other", "/shared/dup.ts", "/pkg"],
+		looseExtensionEntries: ["/shared/dup.ts", "/agent/extensions/a.ts", "/agent/extensions/a.ts"],
+		baseEnv: {},
+	});
+	const launcherPaths = built.args.slice(0, built.args.indexOf("--mode") - 2).filter((_, index, all) => all[index - 1] === "-e");
+	const signal = parseChildPackageInjection(built.env);
+	assert.deepEqual(signal, {
+		noExtensions: true,
+		// /pkg keeps its first (other-package) position, exactly as in argv.
+		extensionPaths: ["/agent/npm/node_modules/some-other", "/shared/dup.ts", "/pkg", "/agent/extensions/a.ts"],
+	});
+	assert.deepEqual(signal?.extensionPaths, launcherPaths);
+});
+
+test("buildPiInvocation signals absolute paths resolved against the given cwd when a takeover receives a relative loose entry", () => {
+	const cwd = resolve("/elsewhere", "launch-dir");
+	assert.notEqual(cwd, process.cwd());
+	const built = buildPiInvocation({
+		...injectionInput,
+		cwd,
+		home: linkHome,
+		declaration: { kind: "npm" },
+		takeOver: true,
+		looseExtensionEntries: [join("relative-home", "extensions", "a.ts")],
+		baseEnv: {},
+	});
+	assert.ok(built.args.includes(join("relative-home", "extensions", "a.ts")), "the -e argv itself is unchanged");
+	assert.deepEqual(parseChildPackageInjection(built.env)?.extensionPaths, [resolve(cwd, "relative-home", "extensions", "a.ts"), "/pkg"]);
+});
+
+test("buildPiInvocation signals one entry for a file spelled both relative and absolute, while argv keeps both spellings", () => {
+	const cwd = resolve("/elsewhere", "launch-dir");
+	const relative = join("relative-home", "extensions", "a.ts");
+	const absolute = resolve(cwd, relative);
+	const built = buildPiInvocation({
+		...injectionInput,
+		cwd,
+		home: linkHome,
+		declaration: { kind: "npm" },
+		takeOver: true,
+		otherPackagePaths: ["/agent/npm/node_modules/some-other", absolute],
+		looseExtensionEntries: [relative, "/agent/extensions/b.ts"],
+		baseEnv: {},
+	});
+	assert.deepEqual(built.args.slice(0, built.args.indexOf("--mode") - 2), [
+		"--no-extensions",
+		"-e",
+		"/agent/npm/node_modules/some-other",
+		"-e",
+		absolute,
+		"-e",
+		relative,
+		"-e",
+		"/agent/extensions/b.ts",
+		"-e",
+		"/pkg",
+	]);
+	assert.deepEqual(parseChildPackageInjection(built.env)?.extensionPaths, [
+		"/agent/npm/node_modules/some-other",
+		absolute,
+		"/agent/extensions/b.ts",
+		"/pkg",
+	]);
+});
+
+test("buildPiInvocation does not signal when settings already declare gentle-pi, and drops an inherited signal", () => {
+	const stale = encodeChildPackageInjection({ noExtensions: false, extensionPaths: ["/outer/pkg"] });
+	for (const baseEnv of [{}, { [CHILD_PACKAGE_INJECTION_ENV]: stale }]) {
+		const built = buildPiInvocation({ ...injectionInput, home: linkHome, declaration: { kind: "npm" }, takeOver: false, baseEnv });
+		assert.equal(Object.hasOwn(built.env, CHILD_PACKAGE_INJECTION_ENV), false);
+	}
+});
+
+test("buildPiInvocation does not signal for a pi subcommand, and drops an inherited signal", () => {
+	const stale = encodeChildPackageInjection({ noExtensions: false, extensionPaths: ["/outer/pkg"] });
+	for (const takeOver of [false, true]) {
+		const built = buildPiInvocation({
+			...injectionInput,
+			declaration: undefined,
+			takeOver,
+			passthrough: ["list"],
+			piSubcommand: "list",
+			baseEnv: { [CHILD_PACKAGE_INJECTION_ENV]: stale },
+		});
+		assert.equal(Object.hasOwn(built.env, CHILD_PACKAGE_INJECTION_ENV), false);
+	}
+});
+
+test("buildPiInvocation replaces an inherited signal with its own injection", () => {
+	const stale = encodeChildPackageInjection({ noExtensions: true, extensionPaths: ["/outer/pkg"] });
+	const built = buildPiInvocation({ ...injectionInput, declaration: undefined, takeOver: false, baseEnv: { [CHILD_PACKAGE_INJECTION_ENV]: stale } });
+	assert.deepEqual(parseChildPackageInjection(built.env), { noExtensions: false, extensionPaths: ["/pkg"] });
+});
+
 // --- discoverLooseExtensionEntries -------------------------------------------
 //
 // Pure mirror of pi's own discoverExtensionsInDir (packages/coding-agent/src/
@@ -1806,3 +2005,25 @@ test("helpText documents pi's own package-management subcommands", () => {
 	assert.match(text, /\bconfig\b/);
 	assert.match(text, /\bauth\b/);
 });
+
+// T3 B3: the isolated-home bootstrap creates ~/.gentle-shell private (0700) even under
+// umask 002, so the bundled prefix claim (which refuses group/other-writable folders) accepts it.
+test("the isolated-home bootstrap creates ~/.gentle-shell as 0700 under umask 002", { skip: process.platform === "win32" ? "POSIX modes" : false }, async () => {
+	const { chmodSync, mkdtempSync, rmSync, statSync, writeFileSync } = await import("node:fs");
+	const { spawnSync } = await import("node:child_process");
+	const { tmpdir } = await import("node:os");
+	const root = mkdtempSync(join(tmpdir(), "gentle-shell-umask-"));
+	try {
+		const piScript = join(root, "fake-pi.mjs");
+		writeFileSync(piScript, "#!/usr/bin/env node\nif (process.argv.includes('--version')) console.log('0.99.1');\n");
+		chmodSync(piScript, 0o755);
+		const binPath = fileURLToPath(new URL("../bin/gentle-shell.mjs", import.meta.url));
+		const env = { HOME: root, USERPROFILE: root, PATH: process.env.PATH ?? "/usr/bin:/bin", GENTLE_SHELL_PI: piScript, GENTLE_SHELL_NO_AUTO_SETUP: "1" };
+		const result = spawnSync("/bin/sh", ["-c", 'umask 002; exec "$0" "$@"', process.execPath, binPath, "hello"], { env, encoding: "utf8", input: "" });
+		assert.equal(result.status, 0, result.stderr);
+		assert.equal(statSync(join(root, ".gentle-shell")).mode & 0o777, 0o700);
+		assert.equal(statSync(join(root, ".gentle-shell", "agent")).mode & 0o777, 0o700);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});

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

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyStartupChoice, omitStartupVersion, resolveStartupRelaunch } from "../lib/gentle-shell-startup-flow.ts";
+
+test("relaunch resolves the activated version's own Node and preserves arguments without shell quoting", async (t) => {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "startup-relaunch-")));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const version = join(root, "versions", "4.2.0-1.2.0");
+	const pkg = join(version, "node_modules", "gentle-pi");
+	mkdirSync(join(pkg, "scripts"), { recursive: true });
+	mkdirSync(join(pkg, "bin"));
+	writeFileSync(join(version, ".gentle-shell-version"), "4.2.0-1.2.0\n");
+	writeFileSync(join(pkg, "bin", "gentle-shell.mjs"), "// verified launcher\n");
+	writeFileSync(join(pkg, "scripts", "bundled-install.mjs"), `export function prefixLayout({root}) { return {node: root + '/runtime/new node/bin/node'}; }`);
+	if (process.platform === "win32") writeFileSync(join(root, "current"), "4.2.0-1.2.0\n");
+	else symlinkSync("versions/4.2.0-1.2.0", join(root, "current"));
+	const argv = ["--home", "path with spaces", "--continue", "a;literal"];
+	const result = await resolveStartupRelaunch({ root, home: tmpdir(), platform: process.platform, env: {}, argv });
+	assert.equal(result.command, root + "/runtime/new node/bin/node");
+	assert.deepEqual(result.args, [join(pkg, "bin", "gentle-shell.mjs"), ...argv]);
+	assert.equal(result.env.GENTLE_SHELL_SKIP_STARTUP_UPDATE, "1");
+});
+
+function effects(code = 0) {
+	const events: string[] = [];
+	return { events, omit: () => { events.push("omit"); }, upgrade: async () => { events.push("upgrade"); return code; },
+		relaunch: async () => { events.push("relaunch"); return 17; } };
+}
+
+test("not now and cancellation never update or persist; cancellation exits 130", async () => {
+	const deps = effects();
+	assert.equal(await applyStartupChoice("skip", deps), undefined);
+	assert.equal(await applyStartupChoice("cancel", deps), 130);
+	assert.deepEqual(deps.events, []);
+});
+
+test("omit persists only the selected version and launches normally", async () => {
+	const deps = effects();
+	assert.equal(await applyStartupChoice("omit", deps), undefined);
+	assert.deepEqual(deps.events, ["omit"]);
+	let stored = '{"home":"link","provisioned":{"a":1},"other":true}';
+	omitStartupVersion(() => stored, (text) => { stored = text; }, "4.2.0");
+	assert.deepEqual(JSON.parse(stored), { home: "link", provisioned: { a: 1 }, other: true, skippedStartupRelease: "4.2.0" });
+});
+
+test("malformed settings are not overwritten by omit; normal launch remains possible", async () => {
+	for (const text of ["{broken", "[]", "null", '"text"']) {
+		let writes = 0;
+		assert.throws(() => omitStartupVersion(() => text, () => { writes++; }, "4.2.0"));
+		assert.equal(writes, 0);
+	}
+	const deps = effects();
+	deps.omit = () => { throw new Error("read-only config"); };
+	assert.equal(await applyStartupChoice("omit", deps), undefined);
+	assert.deepEqual(deps.events, []);
+});
+
+test("accepted update reopens active Shell only after upgrade success and preserves exit status", async () => {
+	const deps = effects();
+	assert.equal(await applyStartupChoice("update", deps), 17);
+	assert.deepEqual(deps.events, ["upgrade", "relaunch"]);
+});
+
+test("failed upgrade keeps ordinary launch; failed relaunch never falls through to old Shell", async () => {
+	const deps = effects(1);
+	assert.equal(await applyStartupChoice("update", deps), undefined);
+	assert.deepEqual(deps.events, ["upgrade"]);
+	const successful = effects();
+	successful.relaunch = async () => { throw new Error("new runtime failed"); };
+	await assert.rejects(applyStartupChoice("update", successful), /new runtime failed/);
+	assert.deepEqual(successful.events, ["upgrade"]);
+});

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

@@ -0,0 +1,85 @@
+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";
+
+const eligible = {
+	args: parseLauncherArgs([]), env: {}, bundled: true, inputTTY: true, outputTTY: true,
+};
+
+test("ordinary bundled interactive launch and resume are eligible", () => {
+	for (const argv of [[], ["--resume"], ["-r"], ["--continue"], ["-c"]]) {
+		assert.equal(shouldCheckStartupUpdate({ ...eligible, args: parseLauncherArgs(argv) }), true);
+	}
+});
+
+test("commands, overrides, non-TTY runs and child/offline opt-outs are excluded", () => {
+	for (const argv of [["upgrade"], ["home"], ["setup"], ["install", "npm:x"], ["--help"], ["--version"], ["--package-root", "/custom"]]) {
+		assert.equal(shouldCheckStartupUpdate({ ...eligible, args: parseLauncherArgs(argv) }), false, argv.join(" "));
+	}
+	for (const overrides of [{ bundled: false }, { inputTTY: false }, { outputTTY: false }, { args: { ...eligible.args, error: "invalid arguments" } }]) {
+		assert.equal(shouldCheckStartupUpdate({ ...eligible, ...overrides }), false);
+	}
+	for (const name of ["GENTLE_PI_AGENTS_CHILD", "PI_OFFLINE", "GENTLE_SHELL_SKIP_STARTUP_UPDATE"]) {
+		assert.equal(shouldCheckStartupUpdate({ ...eligible, env: { [name]: "1" } }), false);
+	}
+});
+
+test("forwarded command modes and unknown flags never trigger a startup offer", () => {
+	for (const argv of [["--print", "hello"], ["-p", "hello"], ["--mode", "rpc"], ["--mode=json"], ["--export", "session.json"], ["--list-models"], ["auth"], ["mcp"], ["--unknown"], ["--resume", "--print"], ["--resume", "session", "--mode", "json"]]) {
+		assert.equal(shouldCheckStartupUpdate({ ...eligible, args: parseLauncherArgs(argv) }), false, argv.join(" "));
+	}
+});
+
+test("only a newer strict stable version produces official release notes, without numeric precision loss", async () => {
+	for (const [current, latest] of [["1.2.3", "1.2.4"], ["1.99.99", "2.0.0"], ["1.9007199254740992.0", "1.9007199254740993.0"]]) {
+		assert.deepEqual(await findStartupUpdate({ current, lookup: async () => latest }), {
+			current, latest, notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
+		});
+	}
+});
+
+test("same, older, prerelease and malformed versions produce no offer", async () => {
+	for (const latest of ["1.2.3", "1.2.2", "0.99.99", "2.0.0-beta.1", "2.0.0+build", "v2.0.0", "02.0.0", "2.0", "2.0.0\n", "garbage", undefined]) {
+		assert.equal(await findStartupUpdate({ current: "1.2.3", lookup: async () => latest }), undefined);
+	}
+	for (const current of ["v1.2.3", "1.2.3-beta", "01.2.3", "1.2", ""]) {
+		assert.equal(await findStartupUpdate({ current, lookup: async () => "2.0.0" }), undefined);
+	}
+});
+
+test("skipping suppresses exactly the skipped release, not later releases", async () => {
+	assert.equal(await findStartupUpdate({ current: "1.0.0", skipped: "2.0.0", lookup: async () => "2.0.0" }), undefined);
+	assert.equal((await findStartupUpdate({ current: "1.0.0", skipped: "2.0.0", lookup: async () => "2.0.1" }))?.latest, "2.0.1");
+});
+
+test("lookup rejection and synchronous failure silently return no offer", async () => {
+	assert.equal(await findStartupUpdate({ current: "1.0.0", lookup: async () => { throw new Error("offline"); } }), undefined);
+	assert.equal(await findStartupUpdate({ current: "1.0.0", lookup: () => { throw new Error("offline"); } }), undefined);
+});
+
+test("timeout aborts and returns even when lookup ignores its signal", async (t) => {
+	t.mock.timers.enable({ apis: ["setTimeout"] });
+	let signal: AbortSignal | undefined;
+	const pending = findStartupUpdate({ current: "1.0.0", lookup: (value) => { signal = value; return new Promise(() => {}); } });
+	await Promise.resolve();
+	t.mock.timers.tick(1499);
+	assert.equal(signal?.aborted, false);
+	t.mock.timers.tick(1);
+	assert.equal(await pending, undefined);
+	assert.equal(signal?.aborted, true);
+});
+
+test("custom deadline is bounded and settled lookups clear the timeout", async (t) => {
+	t.mock.timers.enable({ apis: ["setTimeout"] });
+	let timedSignal: AbortSignal | undefined;
+	const pending = findStartupUpdate({ current: "1.0.0", timeoutMs: 20, lookup: (signal) => { timedSignal = signal; return new Promise(() => {}); } });
+	await Promise.resolve();
+	t.mock.timers.tick(20);
+	assert.equal(await pending, undefined);
+	assert.equal(timedSignal?.aborted, true);
+	let settledSignal: AbortSignal | undefined;
+	assert.ok(await findStartupUpdate({ current: "1.0.0", timeoutMs: 20, lookup: async (signal) => { settledSignal = signal; return "2.0.0"; } }));
+	t.mock.timers.tick(20);
+	assert.equal(settledSignal?.aborted, false);
+});