gentle-pi 4.0.0 → 4.2.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 }),
@@ -622,9 +683,10 @@ test("checkPeerVersionPin passes for a matching pin", () => {
 	assert.deepEqual(result, { ok: true, pinned: ">=0.85.1" });
 });
 
-test("Pi 0.99.1 baseline and host peers follow the open development range policy", () => {
+test("Pi 1.2.0 baseline and host peers follow the open development range policy", () => {
 	const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-	assert.equal(MIN_PI_VERSION, "0.99.1");
+	assert.equal(MIN_PI_VERSION, "1.2.0");
+	assert.equal(pkg.peerDependencies["@earendil-works/pi-coding-agent"], ">=1.2.0");
 	assert.equal(pkg.engines.node, ">=22.19.0");
 	for (const name of ["@earendil-works/pi-ai", "@earendil-works/pi-tui"]) {
 		assert.equal(pkg.peerDependencies[name], "*");
@@ -634,34 +696,38 @@ test("Pi 0.99.1 baseline and host peers follow the open development range policy
 	// Development ranges are policy specifiers; their floor never drops below
 	// the runtime minimum the launcher enforces.
 	for (const name of ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai", "@earendil-works/pi-tui"]) {
-		assert.equal(pkg.devDependencies[name], ">=1.0.0", name);
+		assert.equal(pkg.devDependencies[name], ">=1.2.0", name);
 		assert.equal(checkPiVersion(pkg.devDependencies[name].slice(2)).ok, true, name);
 	}
 });
 
 test("checkPiVersion accepts a version equal to the minimum", () => {
-	assert.deepEqual(checkPiVersion("0.99.1"), { ok: true, version: "0.99.1" });
+	assert.deepEqual(checkPiVersion("1.2.0"), { ok: true, version: "1.2.0" });
 });
 
 test("checkPiVersion accepts a version above the minimum", () => {
-	assert.deepEqual(checkPiVersion("0.100.0"), { ok: true, version: "0.100.0" });
+	for (const version of ["1.2.1", "1.3.0", "2.0.0"]) {
+		assert.deepEqual(checkPiVersion(version), { ok: true, version });
+	}
 });
 
 test("checkPiVersion accepts a v-prefixed version", () => {
-	assert.deepEqual(checkPiVersion("v0.99.1"), { ok: true, version: "0.99.1" });
+	assert.deepEqual(checkPiVersion("v1.2.0"), { ok: true, version: "1.2.0" });
 });
 
 test("checkPiVersion accepts a prerelease suffix at the minimum", () => {
-	assert.deepEqual(checkPiVersion("pi version 0.99.1-rc.2"), { ok: true, version: "0.99.1" });
+	assert.deepEqual(checkPiVersion("pi version 1.2.0-rc.2"), { ok: true, version: "1.2.0" });
 });
 
 test("checkPiVersion rejects a version below the minimum and names both versions", () => {
-	const result = checkPiVersion("0.85.0");
+	const result = checkPiVersion("1.1.0");
 	assert.equal(result.ok, false);
 	if (result.ok) throw new Error("expected a failing result");
-	assert.equal(result.version, "0.85.0");
-	assert.match(result.message, /0\.85\.0/);
-	assert.match(result.message, /0\.99\.1/);
+	assert.equal(result.version, "1.1.0");
+	assert.match(result.message, /1\.1\.0/);
+	assert.match(result.message, /1\.2\.0/);
+	assert.equal(checkPiVersion("1.0.0").ok, false);
+	assert.equal(checkPiVersion("0.99.1").ok, false);
 });
 
 test("checkPiVersion rejects a prerelease below the minimum", () => {
@@ -675,7 +741,7 @@ test("checkPiVersion reports unparsable output with the raw text and the minimum
 	if (result.ok) throw new Error("expected a failing result");
 	assert.equal(result.version, undefined);
 	assert.match(result.message, /not a version/);
-	assert.match(result.message, /0\.99\.1/);
+	assert.match(result.message, /1\.2\.0/);
 });
 
 test("checkPiVersion accepts a custom minimum", () => {
@@ -852,7 +918,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 +929,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 +972,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 +1058,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 +1084,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 +1099,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 +1154,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 +1173,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 +1200,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 +1220,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 +1236,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 +1253,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 +1275,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 +1293,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 +1315,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 +1336,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 +1371,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 +1388,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 +1412,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 +1432,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 +1455,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 +1483,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 +1498,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 +1520,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 +1550,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 +1563,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 +2010,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('1.2.0');\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"]);
+});