gentle-pi 4.2.0 → 4.4.0

package/tests/shell-sidebar-layout.test.ts

@@ -589,6 +589,56 @@ test("a rail digest refreshes live state that no invalidation announces", (t) =>
 	assert.equal(todoRenders, 2, "explicit invalidation still reaches a rail without a digest");
 });
 
+test("a theme switch repaints rail sections whose digest did not change", (t) => {
+	const f = fixture();
+	// Pi hands extensions a live theme proxy and announces a switch only through
+	// ui.invalidate(), which never reaches the rail inside the layout tree.
+	let code = 31;
+	const live = { fg: (_color: string, text: string) => `\x1b[${code}m${text}\x1b[39m`, bold: (text: string) => text };
+	for (const key of ["footer", "agents", "todo"]) {
+		sidebarPart(f.tui, key, { render: () => [key], invalidate() {} }, {
+			digest: () => "stable",
+			render: () => [live.fg("accent", `${key} card`)],
+			invalidate() {},
+		});
+	}
+	t.after(installSidebar(f.tui, live));
+
+	const before = renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n");
+	for (const key of ["footer", "agents", "todo"]) assert.ok(before.includes(`\x1b[31m${key} card`), `${key} paints with the first theme`);
+
+	code = 32;
+	const after = renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n");
+	for (const key of ["footer", "agents", "todo"]) {
+		assert.ok(after.includes(`\x1b[32m${key} card`), `${key} repaints with the new theme`);
+		assert.ok(!after.includes(`\x1b[31m${key} card`), `${key} drops the old theme`);
+	}
+});
+
+test("structural cache misses skip the whole-rail digest pass", (t) => {
+	const f = fixture();
+	let digests = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		digest: () => { digests++; return "stable"; },
+		render: () => [`Todo ${digests}`],
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	// Every frame evaluates the digest exactly once: the whole-rail comparison
+	// reuses it for the section cache instead of calling each digest twice per
+	// prepare (issue #1681).
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	const prepared = digests;
+	assert.equal(prepared, 1, "preparing the rail evaluates the digest once");
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(digests, prepared + 1, "a cache hit compares the digest once");
+	renderLayoutFrame(f.root, 141, 20, () => {});
+	assert.equal(digests, prepared + 2, "a structural miss re-prepares with a single digest pass");
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(digests, prepared + 3, "returning to the cached structure stays on a single digest pass");
+});
+
 test("reuses final sidebar presentation until a relevant invalidation", (t) => {
 	const f = fixture();
 	sidebarPart(f.tui, "todo", { render: () => Array.from({ length: 10 }, (_, index) => `Todo ${index}`), invalidate() {} });

package/tests/short-check-routing-contract.test.ts

@@ -36,7 +36,7 @@ for (const [name, text] of Object.entries({ registeredDescription: background.de
 test("inline still means the same parent, and the public background API stays asynchronous", () => {
 	assert.ok(core.includes("Small path: inline (parent; `bash_background` policy);"));
 	assert.ok(guide.includes("Inline means the same parent, not necessarily synchronous bash"));
-	assert.ok(core.includes("run the focused test and the suite inline, once each"));
+	assert.ok(core.includes("run the focused test and the suite inline in one command"));
 	assert.match(background.description, /return a job id at once/);
 	assert.match(background.description, /notified once, automatically/);
 	assert.match(background.description, /do not poll, sleep, or delegate a subagent to wait/);

package/tests/skill-collision-prefixes.test.ts

@@ -25,7 +25,9 @@ const PREFIXED_NAMES: Record<string, string> = {
 	"work-unit-commits": "gentle-ai-work-unit-commits",
 };
 
-const UNPREFIXED_DIRS = ["gentle-ai"];
+// gentle-pi-owned skills that gentle-ai does not install keep their own
+// gentle- namespace, so they need no gentle-ai- prefix to avoid a collision.
+const UNPREFIXED_DIRS = ["gentle-ai", "design"];
 
 for (const [dir, expectedName] of Object.entries(PREFIXED_NAMES)) {
 	test(`skills/${dir}/SKILL.md frontmatter name is prefixed`, () => {

package/tests/skill-registry-watcher.test.ts

@@ -16,7 +16,7 @@ for (const code of ["ENOENT", "EMFILE"]) {
 			import assert from "node:assert/strict";
 			import fs from "node:fs";
 			import { syncBuiltinESMExports } from "node:module";
-			import { join } from "node:path";
+			import { join, sep } from "node:path";
 			const root = ${JSON.stringify(root)};
 			const cwd = join(root, "workspace");
 			const home = join(root, "home");
@@ -52,6 +52,8 @@ for (const code of ["ENOENT", "EMFILE"]) {
 			});
 			const ctx = { cwd, hasUI: true, ui: { notify: (message, level) => notices.push({ message, level }) } };
 			const waitFor = async (predicate) => {
+				// Must stay well below the parent's spawnSync timeout so a missed
+				// outcome fails with this assertion instead of an opaque ETIMEDOUT.
 				const deadline = Date.now() + 5000;
 				while (!predicate() && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 25));
 				assert.ok(predicate(), "timed out waiting for watcher outcome");
@@ -66,18 +68,28 @@ for (const code of ["ENOENT", "EMFILE"]) {
 				if (code === "ENOENT" && process.platform !== "darwin" && process.platform !== "win32") {
 					// Force the transient missing-directory race at Node's real recursive
 					// readdir boundary, after watcher creation, not in our refresh callback.
+					// Older Node rescans the parent folder; Node 24.22+ resolves new files
+					// via lstat and only readdirs a newly added directory, so trigger with
+					// a directory and fail whichever readdir lands under assets.
 					const nativeReaddir = fs.readdirSync;
 					let reachedRescan = false;
 					fs.readdirSync = function (path, options) {
-						if (path === assets) {
+						if (typeof path === "string" && (path === assets || path.startsWith(assets + sep))) {
 							fs.readdirSync = nativeReaddir;
 							reachedRescan = true;
 							throw Object.assign(new Error("ENOENT: transient skill assets disappeared"), { code, syscall: "scandir", path });
 						}
 						return nativeReaddir(path, options);
 					};
-					fs.writeFileSync(join(assets, "trigger.txt"), "trigger directory rescan");
-					await waitFor(() => reachedRescan);
+					fs.mkdirSync(join(assets, "trigger"));
+					// The rescan race needs live recursive-watch events. Where the OS
+					// cannot deliver them (an exhausted inotify budget, some WSL2
+					// setups), waiting the full waitFor budget is pointless: settle
+					// briefly for the natural race, then exercise the public error
+					// listener directly, as the manual fallback below always did.
+					const raceDeadline = Date.now() + 2000;
+					while (!reachedRescan && Date.now() < raceDeadline) await new Promise((resolve) => setTimeout(resolve, 25));
+					fs.readdirSync = nativeReaddir;
 					// Newer Node versions swallow rescan ENOENT themselves. Still
 					// exercise our public error listener without requiring Node's bug.
 					if (!notices.some(({ message, level }) => level === "warning" && message.includes(code))) {
@@ -112,7 +124,7 @@ for (const code of ["ENOENT", "EMFILE"]) {
 			timeout: 15_000,
 			env: { ...process.env, GIT_CEILING_DIRECTORIES: root },
 		});
-		assert.equal(child.error, undefined, child.error?.message);
+		assert.equal(child.error, undefined, `${child.error?.message}\n${child.stderr}`);
 		assert.equal(child.status, 0, child.stderr);
 		assert.match(child.stdout, new RegExp(`SURVIVED ${code}`));
 	});

package/tests/skill-registry.test.ts

@@ -120,28 +120,61 @@ test("uniqueExistingDirs normalizes duplicates and ignores missing roots", async
 	);
 });
 
-test("findSkillFiles scans one skill directory level only", async () => {
+test("findSkillFiles scans flat skills and category-nested skills without descending further", async () => {
 	const root = join(tmpdir(), `gentle-pi-shallow-${Date.now()}`);
 	const skillPath = join(root, "docs", "SKILL.md");
 	const nestedSkillPath = join(root, "fixtures", "nested", "SKILL.md");
+	const deeperSkillPath = join(root, "fixtures", "nested", "deeper", "SKILL.md");
 	mkdirSync(dirname(skillPath), { recursive: true });
 	mkdirSync(dirname(nestedSkillPath), { recursive: true });
+	mkdirSync(dirname(deeperSkillPath), { recursive: true });
 	writeFileSync(skillPath, "---\nname: docs\ndescription: Docs.\n---\n");
 	writeFileSync(nestedSkillPath, "---\nname: nested\ndescription: Nested fixture.\n---\n");
+	writeFileSync(deeperSkillPath, "---\nname: deeper\ndescription: Deeper fixture.\n---\n");
 
-	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath]);
+	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath, nestedSkillPath]);
 });
 
-test("findSkillFiles follows symlinked skill directories", async (t) => {
+test("findSkillFiles keeps direct skills ahead of alphabetically earlier nested collisions", async () => {
+	const cwd = join(tmpdir(), `gentle-pi-precedence-${Date.now()}`);
+	const directSkillPath = join(cwd, "skills", "zeta", "SKILL.md");
+	const nestedSkillPath = join(cwd, "skills", "alpha", "duplicate", "SKILL.md");
+	mkdirSync(dirname(directSkillPath), { recursive: true });
+	mkdirSync(dirname(nestedSkillPath), { recursive: true });
+	writeFileSync(directSkillPath, "---\nname: duplicate\ndescription: Direct skill.\n---\n");
+	writeFileSync(nestedSkillPath, "---\nname: duplicate\ndescription: Nested skill.\n---\n");
+
+	await __testing.regenerateRegistry(cwd, true);
+	const registry = readFileSync(join(cwd, ".atl", "skill-registry.md"), "utf8");
+	assert.match(registry, new RegExp(directSkillPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+	assert.doesNotMatch(registry, new RegExp(nestedSkillPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+});
+
+test("findSkillFiles does not descend into excluded categories", async () => {
+	const root = join(tmpdir(), `gentle-pi-excluded-category-${Date.now()}`);
+	for (const category of ["_shared", "skill-registry", "sdd-fixtures"]) {
+		const nestedSkillPath = join(root, category, "hidden", "SKILL.md");
+		mkdirSync(dirname(nestedSkillPath), { recursive: true });
+		writeFileSync(nestedSkillPath, "---\nname: hidden\ndescription: Hidden skill.\n---\n");
+	}
+
+	assert.deepEqual(await __testing.findSkillFiles(root), []);
+});
+
+test("findSkillFiles follows direct symlinked skills but not symlinked categories", async (t) => {
 	const root = join(tmpdir(), `gentle-pi-symlink-root-${Date.now()}`);
 	const realSkillDir = join(tmpdir(), `gentle-pi-symlink-target-${Date.now()}`);
+	const categoryTarget = join(tmpdir(), `gentle-pi-symlink-category-${Date.now()}`);
 	const linkedSkillDir = join(root, "linked");
 	const skillPath = join(linkedSkillDir, "SKILL.md");
 	mkdirSync(root, { recursive: true });
 	mkdirSync(realSkillDir, { recursive: true });
+	mkdirSync(join(categoryTarget, "nested"), { recursive: true });
 	writeFileSync(join(realSkillDir, "SKILL.md"), "---\nname: linked\ndescription: Linked skill.\n---\n");
+	writeFileSync(join(categoryTarget, "nested", "SKILL.md"), "---\nname: nested\ndescription: Nested skill.\n---\n");
 	try {
 		symlinkSync(realSkillDir, linkedSkillDir, "dir");
+		symlinkSync(categoryTarget, join(root, "category"), "dir");
 	} catch (error) {
 		t.skip(`symlink creation unavailable: ${error instanceof Error ? error.message : String(error)}`);
 		return;
@@ -150,6 +183,12 @@ test("findSkillFiles follows symlinked skill directories", async (t) => {
 	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath]);
 });
 
+test("only missing skill-file errors allow category scanning", () => {
+	assert.equal(__testing.isMissingSkillFileError({ code: "ENOENT" }), true);
+	assert.equal(__testing.isMissingSkillFileError({ code: "ENOTDIR" }), true);
+	assert.equal(__testing.isMissingSkillFileError({ code: "EACCES" }), false);
+});
+
 test("skill registry watchers close on shutdown", async () => {
 	const root = join(tmpdir(), `gentle-pi-watchers-${Date.now()}`);
 	const skillPath = join(root, "skills", "docs", "SKILL.md");
@@ -453,6 +492,11 @@ test("registered watcher protects registry tracked after a cache hit", async (t)
 	while (runtime.notices.length === 0 && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 50));
 	assert.equal(readFileSync(fixture.registry, "utf8"), before);
 	assert.ok(runtime.notices.some(({ message, level }) => level === "warning" && message.includes("/skill-registry:refresh")));
+	// The poll re-asks the same tracked-target state every interval: the
+	// warning stays a one-shot per unchanged state instead of repeating.
+	runtime.notices.length = 0;
+	await new Promise((resolve) => setTimeout(resolve, 3000));
+	assert.deepEqual(runtime.notices, []);
 	assert.ok(!runtime.notices.some(({ message }) => message.includes("refreshed")));
 });
 

package/tests/small-task-inline-contract.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+
+// Pain-point iteration S15. Bench evidence (pps14 x5): one run read "Two unrelated wishes" as separate
+// deliverables, classified a two-feature request as large (branch, feature document, session state), and
+// started two writers for ~100-line units: USD 0.55 against 0.20 for the run that stayed inline. Blind round 4
+// also found delivered tests that pin `git show <baseline commit>`, so the differential check had leaked into
+// committed tests that fail in another clone. These are instruction-delivery contracts, not proof of adherence.
+
+const read = (path: string): string => readFileSync(join(import.meta.dirname, "..", path), "utf8");
+
+test("S15 (a): separate deliverables are ones the user wants apart, not several features asked at once", () => {
+	const core = read("assets/orchestrator.md");
+	assert.ok(
+		core.includes("deliverables the user wants apart (never several features asked at once)"),
+		"Task Size must define separate deliverables",
+	);
+});
+
+test("S15 (b): parallel writers never fire for units of about 100 changed lines or less", () => {
+	const card = read("assets/orchestrator-delegation.md");
+	assert.ok(
+		card.includes("Units of about 100 changed lines or less always run inline: writing them costs less than starting workers."),
+		"the Writer trigger must keep small units inline",
+	);
+});
+
+test("S15 (c): the differential check runs in scratch and is never committed as a test", () => {
+	const clause = "a copy of the base commit in a `mktemp -d` scratch directory, never committed as a test; committed tests never read git history or a fixed commit";
+	const harness = __testing.buildGentlePrompt("neutral");
+	assert.ok(harness.includes(clause), "the always-on test-first policy must keep the differential check in scratch");
+	assert.ok(!harness.includes("(`git stash` or a copy of HEAD)"), "the harness must not suggest git stash or HEAD copies");
+	assert.ok(read("assets/agents/gentle-ai-worker.md").includes(clause), "the worker must keep the differential check in scratch");
+});

package/tests/standalone-config-home.test.ts

@@ -0,0 +1,324 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { gentlePiConfigHome } from "../lib/agent-home.ts";
+import { gentleAiDevBinaryRegistrationPath, gentleAiIsolationEnv } from "../lib/gentle-ai-binary.ts";
+import { GENTLE_SHELL_CONFIG_HOME_ENV, setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
+import { buildPiInvocation, migrateStandaloneConfig, standaloneConfigHome, type ResolvedHome } from "../lib/gentle-shell-launcher.ts";
+import { createActiveProfileReader } from "../extensions/gentle-shell.ts";
+import { readBannerConfig } from "../extensions/startup-banner.ts";
+
+// #2201 (S1, S1a): the standalone launcher's isolated home keeps Gentle Shell's
+// config next to its agent dir (~/.gentle-shell/gentle-ai), not in the shared
+// ~/.pi/gentle-ai that a Pi install with gentle-pi also uses.
+
+const posixOnly = { skip: process.platform === "win32" };
+const binPath = fileURLToPath(new URL("../bin/gentle-shell.mjs", import.meta.url));
+const MARKER = "GENTLE_SHELL_CONFIG_HOME";
+
+function scratch(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "standalone-config-home-")));
+}
+
+function launch(home: ResolvedHome, baseEnv: Record<string, string | undefined> = {}, bundled = false) {
+	return buildPiInvocation({
+		runtime: { kind: "path", command: "fake-pi", args: [] },
+		home,
+		packageRoot: "/pkg",
+		declaration: undefined,
+		takeOver: false,
+		otherPackagePaths: [],
+		passthrough: [],
+		baseEnv,
+		homedir: "/os-home",
+		cwd: "/cwd",
+		bundled,
+	});
+}
+
+function isolated(dir = "/os-home/.gentle-shell/agent"): { home: ResolvedHome } {
+	return { home: { mode: "isolated", dir, source: "default" } };
+}
+
+test("the marker is exported under its launcher-owned name, never GENTLE_PI_CONFIG_HOME", () => {
+	assert.equal(GENTLE_SHELL_CONFIG_HOME_ENV, MARKER);
+});
+
+test("config home precedence: explicit GENTLE_PI_CONFIG_HOME > launcher marker > ~/.pi/gentle-ai; empty counts as unset", () => {
+	const home = scratch();
+	const env = (extra: Record<string, string>) => ({ HOME: home, USERPROFILE: home, ...extra });
+	const previous = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE };
+	process.env.HOME = home;
+	process.env.USERPROFILE = home;
+	try {
+		assert.equal(gentlePiConfigHome(env({})), join(home, ".pi", "gentle-ai"));
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "/shell/gentle-ai" })), "/shell/gentle-ai");
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "/shell/gentle-ai", GENTLE_PI_CONFIG_HOME: "/explicit" })), "/explicit");
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "/shell/gentle-ai", GENTLE_PI_CONFIG_HOME: "" })), "/shell/gentle-ai");
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "" })), join(home, ".pi", "gentle-ai"));
+		assert.equal(gentlePiConfigHome(env({ [MARKER]: "relative/gentle-ai" })), join(home, ".pi", "gentle-ai"), "a relative marker is ignored");
+	} finally {
+		for (const [key, value] of Object.entries(previous)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	}
+});
+
+test("a bundled prefix still outranks the explicit override and the marker", (t) => {
+	const prefix = scratch();
+	setBundledInstallForTesting({ root: prefix });
+	t.after(() => setBundledInstallForTesting(undefined));
+	assert.equal(
+		gentlePiConfigHome({ GENTLE_SHELL_PREFIX: prefix, GENTLE_PI_CONFIG_HOME: "/explicit", [MARKER]: "/shell/gentle-ai" }),
+		join(prefix, "config", "gentle-ai"),
+	);
+});
+
+test("the banner and profile readers follow the same resolver, including an empty GENTLE_PI_CONFIG_HOME", async (t) => {
+	const root = scratch();
+	const config = join(root, "shell", "gentle-ai");
+	mkdirSync(config, { recursive: true });
+	writeFileSync(join(config, "banner.json"), JSON.stringify({ showTextLogo: false }));
+	writeFileSync(join(config, "profiles.json"), JSON.stringify({ kind: "gentle-pi.agent_model_profiles", version: 1, active: "fast", profiles: { fast: {} } }));
+	const previous = { marker: process.env[MARKER], explicit: process.env.GENTLE_PI_CONFIG_HOME };
+	process.env[MARKER] = config;
+	process.env.GENTLE_PI_CONFIG_HOME = "";
+	t.after(() => {
+		if (previous.marker === undefined) delete process.env[MARKER];
+		else process.env[MARKER] = previous.marker;
+		if (previous.explicit === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
+		else process.env.GENTLE_PI_CONFIG_HOME = previous.explicit;
+	});
+	assert.equal((await readBannerConfig()).showTextLogo, false);
+	assert.equal(createActiveProfileReader({ [MARKER]: config, GENTLE_PI_CONFIG_HOME: "" })(), "fast");
+});
+
+test("the launcher gives Pi the marker only in its isolated home", () => {
+	const isolatedLaunch = launch(isolated().home);
+	assert.equal(isolatedLaunch.env[MARKER], "/os-home/.gentle-shell/gentle-ai");
+	assert.equal(isolatedLaunch.env.GENTLE_PI_CONFIG_HOME, undefined, "GENTLE_PI_CONFIG_HOME is never exported to Pi");
+	assert.equal(standaloneConfigHome(isolated().home), "/os-home/.gentle-shell/gentle-ai");
+	// A custom GENTLE_SHELL_HOME's parent may be anyone's folder (~/myagent ->
+	// ~/gentle-ai), so only a .gentle-shell/agent home gets its own config folder.
+	assert.equal(launch(isolated("/custom/shell/agent").home).env[MARKER], undefined, "no marker beside a custom GENTLE_SHELL_HOME");
+	assert.equal(standaloneConfigHome(isolated("/os-home/myagent").home), undefined, "never the generic ~/gentle-ai");
+	assert.equal(standaloneConfigHome(isolated("/data/.gentle-shell/agent").home), "/data/.gentle-shell/gentle-ai");
+});
+
+test("--link, a custom --home and a bundled launch keep today's config home and drop an inherited marker", () => {
+	const inherited = { [MARKER]: "/outer/gentle-ai" };
+	const link = launch({ mode: "link", dir: "/os-home/.pi/agent", source: "flag" }, inherited);
+	const path = launch({ mode: "path", dir: "/custom/home", source: "flag" }, inherited);
+	const bundled = launch(isolated().home, inherited, true);
+	for (const invocation of [link, path, bundled]) assert.equal(MARKER in invocation.env, false);
+	assert.equal(standaloneConfigHome({ mode: "link", dir: "/os-home/.pi/agent", source: "flag" }), undefined);
+	assert.equal(standaloneConfigHome({ mode: "path", dir: "/custom/home", source: "flag" }), undefined);
+});
+
+test("Gentle AI processes started from a standalone isolated session get the bundled-style config pair", () => {
+	const env = gentleAiIsolationEnv({ PATH: "/bin", [MARKER]: "/os-home/.gentle-shell/gentle-ai" });
+	assert.equal(env.GENTLE_AI_PI_CONFIG_DIR, "/os-home/.gentle-shell/gentle-ai");
+	assert.equal(env.GENTLE_PI_CONFIG_HOME, "/os-home/.gentle-shell", "Gentle AI 4.0.0 reads it as the parent of its gentle-ai folder");
+	assert.equal(env.PATH, "/bin");
+	assert.equal(env.GENTLE_AI_HOME, undefined, "standalone keeps Gentle AI's own state where it was");
+});
+
+test("without the marker, or with an explicit GENTLE_PI_CONFIG_HOME, Gentle AI's environment is unchanged", () => {
+	const plain = { PATH: "/bin" };
+	assert.equal(gentleAiIsolationEnv(plain), plain);
+	const explicit = { PATH: "/bin", GENTLE_PI_CONFIG_HOME: "/explicit", [MARKER]: "/os-home/.gentle-shell/gentle-ai" };
+	assert.equal(gentleAiIsolationEnv(explicit), explicit);
+});
+
+test("the main-channel dev-binary registration ignores the marker and an empty GENTLE_PI_CONFIG_HOME", () => {
+	assert.equal(
+		gentleAiDevBinaryRegistrationPath({ env: { [MARKER]: "/os-home/.gentle-shell/gentle-ai", GENTLE_PI_CONFIG_HOME: "" }, home: "/os-home" }),
+		join("/os-home", ".pi", "gentle-ai", "dev-binary.json"),
+	);
+	assert.equal(gentleAiDevBinaryRegistrationPath({ env: { GENTLE_PI_CONFIG_HOME: "/explicit" }, home: "/os-home" }), join("/explicit", "dev-binary.json"));
+});
+
+// --- migration -----------------------------------------------------------------
+
+// The same real filesystem bin/gentle-shell.mjs gives migrateStandaloneConfig.
+const fs = {
+	kind: (path: string) => {
+		try {
+			const stat = lstatSync(path);
+			return stat.isDirectory() ? "dir" as const : stat.isFile() ? "file" as const : "other" as const;
+		} catch {
+			return "missing" as const;
+		}
+	},
+	list: (path: string) => readdirSync(path),
+	mkdirPrivate: (path: string) => { mkdirSync(path, { recursive: true, mode: 0o700 }); },
+	copyNew: (from: string, to: string) => copyFileSync(from, to, constants.COPYFILE_EXCL),
+};
+
+function migrationWorld() {
+	const root = scratch();
+	const source = join(root, "home", ".pi", "gentle-ai");
+	const target = join(root, "home", ".gentle-shell", "gentle-ai");
+	mkdirSync(source, { recursive: true });
+	mkdirSync(dirname(target), { recursive: true });
+	writeFileSync(join(source, "banner.json"), "{\"showTextLogo\":false}\n");
+	writeFileSync(join(source, "profiles.json"), "{\"active\":\"fast\"}\n");
+	writeFileSync(join(source, "dev-binary.json"), "{}\n");
+	writeFileSync(join(source, "channel.json"), "{}\n");
+	mkdirSync(join(source, "main", "gentle-ai"), { recursive: true });
+	writeFileSync(join(source, "main", "gentle-ai", "marker"), "x");
+	return { root, source, target };
+}
+
+function snapshotTree(dir: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		const stat = lstatSync(path);
+		if (stat.isDirectory()) for (const [key, value] of Object.entries(snapshotTree(path))) out[join(name, key)] = value;
+		else out[name] = stat.isSymbolicLink() ? "symlink" : `${stat.mode}:${stat.mtimeMs}:${readFileSync(path, "utf8")}`;
+	}
+	return out;
+}
+
+test("migration copies the regular files once into a new 0700 folder and never changes the source", posixOnly, () => {
+	const w = migrationWorld();
+	symlinkSync(join(w.source, "banner.json"), join(w.source, "linked.json"));
+	const before = snapshotTree(w.source);
+	const result = migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	assert.deepEqual(readdirSync(w.target).sort(), ["banner.json", "profiles.json"]);
+	assert.equal(readFileSync(join(w.target, "banner.json"), "utf8"), "{\"showTextLogo\":false}\n");
+	assert.equal(statSync(w.target).mode & 0o777, 0o700);
+	assert.deepEqual(snapshotTree(w.source), before);
+	assert.equal(result.lines.length, 1);
+	assert.match(result.lines[0], new RegExp(`${w.source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}.*${w.target.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`));
+});
+
+test("migration skips the main-channel files and does nothing once the folder exists", posixOnly, () => {
+	const w = migrationWorld();
+	migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	assert.equal(existsSync(join(w.target, "dev-binary.json")), false);
+	assert.equal(existsSync(join(w.target, "channel.json")), false);
+	assert.equal(existsSync(join(w.target, "main")), false);
+	writeFileSync(join(w.target, "banner.json"), "{\"color\":\"cyan\"}\n");
+	writeFileSync(join(w.source, "vim.json"), "{}\n");
+	const again = migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	assert.deepEqual(again.lines, []);
+	assert.equal(readFileSync(join(w.target, "banner.json"), "utf8"), "{\"color\":\"cyan\"}\n", "never overwrites");
+	assert.equal(existsSync(join(w.target, "vim.json")), false, "runs once");
+});
+
+test("without ~/.pi/gentle-ai the migration only creates the empty 0700 folder, silently", posixOnly, () => {
+	const root = scratch();
+	const target = join(root, ".gentle-shell", "gentle-ai");
+	const result = migrateStandaloneConfig({ source: join(root, ".pi", "gentle-ai"), target, fs });
+	assert.deepEqual(result.lines, []);
+	assert.deepEqual(readdirSync(target), []);
+	assert.equal(statSync(target).mode & 0o777, 0o700);
+});
+
+test("a failed copy warns and keeps whatever was copied; it never throws", posixOnly, () => {
+	const w = migrationWorld();
+	chmodSync(join(w.source, "profiles.json"), 0o000);
+	if (spawnSync("cat", [join(w.source, "profiles.json")]).status === 0) return; // running as root: nothing is unreadable
+	const result = migrateStandaloneConfig({ source: w.source, target: w.target, fs });
+	chmodSync(join(w.source, "profiles.json"), 0o644);
+	assert.deepEqual(readdirSync(w.target), ["banner.json"]);
+	assert.equal(result.lines.length, 1);
+	assert.match(result.lines[0], /could not copy/);
+	assert.match(result.lines[0], /profiles\.json/);
+	const blocked = scratch();
+	writeFileSync(join(blocked, "not-a-dir"), "");
+	const failed = migrateStandaloneConfig({ source: w.source, target: join(blocked, "not-a-dir", "gentle-ai"), fs });
+	assert.equal(failed.lines.length, 1);
+	assert.match(failed.lines[0], /could not/);
+});
+
+// --- the real launcher -----------------------------------------------------------
+
+function writeFakePi(path: string) {
+	writeFileSync(path, [
+		"#!/usr/bin/env node",
+		"const args = process.argv.slice(2);",
+		"if (args.includes('--version')) { console.log('1.2.0'); process.exit(0); }",
+		`console.log(JSON.stringify({ marker: process.env.${MARKER} ?? null, explicit: process.env.GENTLE_PI_CONFIG_HOME ?? null }));`,
+		"",
+	].join("\n"));
+	chmodSync(path, 0o755);
+}
+
+function writeFakeGentleAi(path: string) {
+	writeFileSync(path, [
+		"#!/usr/bin/env node",
+		"import { mkdirSync, writeFileSync } from 'node:fs';",
+		"import { homedir } from 'node:os';",
+		"import { join } from 'node:path';",
+		"for (const dir of [process.env.GENTLE_AI_PI_CONFIG_DIR, join(homedir(), '.pi', 'gentle-ai')]) {",
+		"  if (!dir) continue;",
+		"  mkdirSync(dir, { recursive: true });",
+		"  writeFileSync(join(dir, 'persona.json'), JSON.stringify({ mode: 'gentleman' }));",
+		"}",
+		"process.stdout.write(JSON.stringify({ dir: process.env.GENTLE_AI_PI_CONFIG_DIR ?? null, parent: process.env.GENTLE_PI_CONFIG_HOME ?? null }) + '\\n');",
+		"",
+	].join("\n"));
+	chmodSync(path, 0o755);
+}
+
+function launcherWorld() {
+	const root = scratch();
+	const home = join(root, "home");
+	mkdirSync(join(home, ".pi", "gentle-ai"), { recursive: true });
+	writeFileSync(join(home, ".pi", "gentle-ai", "banner.json"), "{\"showTextLogo\":false}\n");
+	const pi = join(root, "fake-pi.mjs");
+	writeFakePi(pi);
+	const env: NodeJS.ProcessEnv = { PATH: process.env.PATH, HOME: home, USERPROFILE: home, GENTLE_SHELL_PI: pi, GENTLE_SHELL_NO_AUTO_SETUP: "1" };
+	const run = (args: string[], extra: NodeJS.ProcessEnv = {}) => spawnSync(process.execPath, [binPath, ...args], { encoding: "utf8", env: { ...env, ...extra } });
+	return { root, home, env, run, shellConfig: join(home, ".gentle-shell", "gentle-ai") };
+}
+
+test("a standalone isolated launch migrates ~/.pi/gentle-ai and points Pi at ~/.gentle-shell/gentle-ai", posixOnly, () => {
+	const w = launcherWorld();
+	const result = w.run(["list"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(JSON.parse(result.stdout.trim().split("\n").at(-1)!), { marker: w.shellConfig, explicit: null });
+	assert.equal(readFileSync(join(w.shellConfig, "banner.json"), "utf8"), "{\"showTextLogo\":false}\n");
+	assert.equal(readFileSync(join(w.home, ".pi", "gentle-ai", "banner.json"), "utf8"), "{\"showTextLogo\":false}\n");
+	assert.equal(result.stderr.split("\n").filter((line) => line.includes(w.shellConfig) && line.includes("copied")).length, 1);
+	const second = w.run(["list"]);
+	assert.doesNotMatch(second.stderr, /copied/);
+});
+
+test("--link launches keep ~/.pi/gentle-ai: no marker and no migration", posixOnly, () => {
+	const w = launcherWorld();
+	mkdirSync(join(w.home, ".pi", "agent"), { recursive: true });
+	const result = w.run(["--link", "list"], { [MARKER]: "/outer/gentle-ai" });
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(JSON.parse(result.stdout.trim().split("\n").at(-1)!), { marker: null, explicit: null });
+	assert.equal(existsSync(w.shellConfig), false);
+});
+
+test("an explicit GENTLE_PI_CONFIG_HOME still wins: it reaches Pi and no migration runs", posixOnly, () => {
+	const w = launcherWorld();
+	const result = w.run(["list"], { GENTLE_PI_CONFIG_HOME: join(w.root, "explicit") });
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(JSON.parse(result.stdout.trim().split("\n").at(-1)!).explicit, join(w.root, "explicit"));
+	assert.equal(existsSync(w.shellConfig), false);
+});
+
+test("standalone setup gives Gentle AI the config pair and keeps both persona files unchanged", posixOnly, () => {
+	const w = launcherWorld();
+	const gentleAi = join(w.root, "fake-gentle-ai.mjs");
+	writeFakeGentleAi(gentleAi);
+	writeFileSync(join(w.home, ".pi", "gentle-ai", "persona.json"), "{\"mode\":\"neutral\"}");
+	const result = w.run(["setup"], { GENTLE_SHELL_GENTLE_AI_BIN: gentleAi });
+	assert.equal(result.status, 0, result.stderr);
+	const seen = JSON.parse(result.stdout.split("\n").find((line) => line.includes("\"dir\""))!);
+	assert.deepEqual(seen, { dir: w.shellConfig, parent: join(w.home, ".gentle-shell") });
+	assert.equal(readFileSync(join(w.home, ".pi", "gentle-ai", "persona.json"), "utf8"), "{\"mode\":\"neutral\"}");
+	assert.equal(readFileSync(join(w.shellConfig, "persona.json"), "utf8"), "{\"mode\":\"neutral\"}", "the migrated copy is restored too");
+});

package/tests/startup-banner.test.ts

@@ -462,19 +462,20 @@ test("delegated children never paint the startup banner", async (t) => {
 
 // S9: the config home each of these reads resolves, per case. The OS home is
 // a temporary folder in every case, so no case can reach the real one.
-// "unset" and "empty" are exactly as before: an empty GENTLE_PI_CONFIG_HOME
-// names the current folder. "bundled" stands in for this package running from
+// "unset" and "empty" both name ~/.pi/gentle-ai: an empty GENTLE_PI_CONFIG_HOME
+// counts as unset (#2201; it used to name the current folder). "bundled" stands in for this package running from
 // a bundled install (testing overlay) whose prefix the launcher passed; the
 // user's own GENTLE_PI_CONFIG_HOME is then not this install's.
 type ConfigHomeCase = "unset" | "empty" | "bundled";
 function configHomeCase(t: { after: (fn: () => void) => void }, kind: ConfigHomeCase): { env: NodeJS.ProcessEnv; dir: string; userConfig: string } {
 	const base = realpathSync(mkdtempSync(join(tmpdir(), `config-home-${kind}-`)));
-	const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_SHELL_PREFIX: process.env.GENTLE_SHELL_PREFIX };
+	const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, GENTLE_PI_CONFIG_HOME: process.env.GENTLE_PI_CONFIG_HOME, GENTLE_SHELL_PREFIX: process.env.GENTLE_SHELL_PREFIX, GENTLE_SHELL_CONFIG_HOME: process.env.GENTLE_SHELL_CONFIG_HOME };
 	const cwd = process.cwd();
 	process.env.HOME = join(base, "home");
 	process.env.USERPROFILE = join(base, "home");
 	delete process.env.GENTLE_PI_CONFIG_HOME;
 	delete process.env.GENTLE_SHELL_PREFIX;
+	delete process.env.GENTLE_SHELL_CONFIG_HOME;
 	t.after(() => {
 		process.chdir(cwd);
 		setBundledInstallForTesting(undefined);
@@ -489,7 +490,7 @@ function configHomeCase(t: { after: (fn: () => void) => void }, kind: ConfigHome
 	if (kind === "empty") {
 		mkdirSync(join(base, "cwd"));
 		process.chdir(join(base, "cwd"));
-		return { env: { GENTLE_PI_CONFIG_HOME: "" }, dir: join(base, "cwd"), userConfig };
+		return { env: { GENTLE_PI_CONFIG_HOME: "" }, dir: join(base, "home", ".pi", "gentle-ai"), userConfig };
 	}
 	const prefix = join(base, "prefix");
 	mkdirSync(prefix);