gentle-pi 4.2.0 → 4.3.0

package/tests/session-subject-routing-contract.test.ts

@@ -8,7 +8,8 @@ const source = readFileSync(join(root, "extensions/gentle-agents.ts"), "utf8");
 const match = source.match(/name: "orchestrator_session_id",\s*label: "[^"]+",\s*description: ("(?:[^"\\]|\\.)*")/);
 assert.ok(match, "Registered session tool must expose a public description");
 const description: string = JSON.parse(match[1]);
-const detail = readFileSync(join(root, "assets/orchestrator-delegation.md"), "utf8")
+// S11 T2: the session subject rules moved from the delegation card to its reference.
+const detail = readFileSync(join(root, "assets/orchestrator-delegation-reference.md"), "utf8")
 	.split("## Session subject and display identity\n")[1].split("### Publish and find classified work")[0];
 const docs = readFileSync(join(root, "docs/gentle-agents-activity.md"), "utf8")
 	.split("### Declare a recognizable subject\n")[1].split("### Publish curated state")[0];

package/tests/shell-bar.test.ts

@@ -219,6 +219,13 @@ test("renderShellBar renders one line with the segments in order", () => {
 	);
 });
 
+test("renderShellBar paints the context gauge with the given gauge roles", () => {
+	const [line] = renderShellBar(model(), taggedTheme, 400, undefined, { ok: "gaugeOk", empty: "gaugeEmpty" });
+	assert.match(line, /<gaugeOk>▰▰▰▰<\/gaugeOk><gaugeEmpty>▱▱▱▱<\/gaugeEmpty>/);
+	const [fallback] = renderShellBar(model(), taggedTheme, 400);
+	assert.match(fallback, /<accent>▰▰▰▰<\/accent><border>▱▱▱▱<\/border>/);
+});
+
 test("renderShellBar colors the brand, model, effort, and gauge by role", () => {
 	const [line] = renderShellBar(model(), taggedTheme, 400);
 	assert.match(line, /<accent>✿ gentle shell<\/accent>/);

package/tests/shell-changes-view.test.ts

@@ -4,6 +4,7 @@ import { TuiAltScreen, visibleWidth, type Terminal, type TuiMouseEvent } from "@
 import { CHANGE_STATUS, DIFF_TOO_LARGE, changesModel, type ChangedFile } from "../lib/shell-changes.ts";
 import { WorktreeChangesView, ChangesView, colorDiff, type ChangesViewDeps } from "../lib/shell-changes-view.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 
 // The changes overlay: files on the left, the selected file's diff on the
 // right, keys at the bottom. Rendering is pure; git access is injected.
@@ -458,7 +459,7 @@ const statusCases = [
 	[CHANGE_STATUS.ADDED, "A", 3, 0],
 	[CHANGE_STATUS.DELETED, "D", 0, 4],
 	[CHANGE_STATUS.RENAMED, "R", 0, 0],
-	[CHANGE_STATUS.UNTRACKED, "??", 5, 0],
+	[CHANGE_STATUS.UNTRACKED, "U", 5, 0],
 ] as const;
 
 for (const [status, code, added, deleted] of statusCases) {
@@ -757,3 +758,138 @@ test("ChangesView.update keeps the selected file, reloads moved diffs, and survi
 	component.handleInput("j");
 	component.handleInput("o");
 });
+
+// Diff-only mode (F): the file column and its separator leave so the diff
+// spans the whole inner width; j/k still walk files, esc returns first.
+function diffOnlyView(overrides: { rows?: number; loadDiff?: (root: string, target: ChangedFile) => Promise<string> } = {}) {
+	const trees = [
+		{ root: "/main", branch: "main", model: changesModel([file("a.ts", 1, 0), file("b.ts", 1, 0)]) },
+		{ root: "/linked", branch: "agent", model: changesModel([file("c.ts", 1, 0)]) },
+	];
+	const events: string[] = [];
+	const component = new WorktreeChangesView(trees, {
+		theme: plainTheme, rows: overrides.rows ?? 10,
+		loadDiff: overrides.loadDiff ?? (async (root, target) => `+${root}:${target.path} ${"x".repeat(80)}`),
+		onOpen: (root, target) => { events.push(`open:${root}:${target.path}`); },
+		onClose: () => { events.push("close"); },
+		onRefresh: () => { events.push("refresh"); },
+		requestRender() {},
+	});
+	return { component, events };
+}
+
+test("F hides the file list and its separator so the diff spans the full inner width", async () => {
+	const { component } = diffOnlyView();
+	component.handleInput("\r");
+	component.handleInput("j");
+	await settle();
+	const normal = component.render(100);
+	assert.match(normal[1]!, /^│ +▾ main · main +│ M a\.ts +│$/, "the normal view keeps the two-pane layout");
+	assert.match(stripAnsi(normal[2]!), /^│ ▸   M a\.ts .*│ \+\/main:a\.ts x+…│$/, "the narrow diff pane clips a long line");
+	assert.match(normal[8]!, /F diff only/);
+	component.handleInput("F");
+	await settle();
+	const wide = component.render(100);
+	assert.equal(wide.length, 10);
+	for (const line of wide) assert.equal(visibleWidth(line), 100);
+	assert.match(wide[1]!, /^│ M a\.ts +│$/, "the path header starts at the frame edge");
+	assert.equal(wide[2]!, `│ ${`+/main:a.ts ${"x".repeat(80)}`.padEnd(96)} │`, "the diff uses the full inner width");
+	assert.doesNotMatch(wide.slice(1, 8).join("\n"), /main · main|│.*│.*│/, "no list column and no separator remain");
+	assert.match(wide[8]!, /F files/);
+	component.handleInput("F");
+	assert.match(component.render(100)[1]!, /▾ main · main/, "F toggles back to the file list");
+});
+
+test("j/k in diff-only mode walk files across worktrees and the path header follows", async () => {
+	const { component } = diffOnlyView();
+	component.handleInput("F");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M a\.ts +│$/, "entering on a group header jumps to its first file");
+	component.handleInput("j");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M b\.ts +│$/);
+	component.handleInput("j");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M c\.ts +│$/, "j crosses into the next worktree's files");
+	assert.match(component.render(100)[2]!, /\+\/linked:c\.ts/);
+	component.handleInput("j");
+	assert.match(component.render(100)[1]!, /^│ M c\.ts +│$/, "the last file stays selected");
+	component.handleInput("k");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M b\.ts +│$/);
+	component.handleInput("j");
+	component.handleInput("\x1b");
+	assert.match(component.render(100).join("\n"), /▸   M c\.ts/, "the files view shows the file chosen in diff-only mode");
+});
+
+test("esc leaves diff-only mode before closing; q, o and r keep working there", async () => {
+	const { component, events } = diffOnlyView();
+	component.handleInput("F");
+	component.handleInput("\x1b");
+	assert.deepEqual(events, [], "the first esc only returns to the file list");
+	assert.match(component.render(100)[1]!, /main · main/);
+	component.handleInput("\x1b");
+	assert.deepEqual(events, ["close"]);
+	component.handleInput("F");
+	component.handleInput("o");
+	component.handleInput("r");
+	component.handleInput("q");
+	assert.deepEqual(events, ["close", "open:/main:a.ts", "refresh", "close"]);
+});
+
+test("diff-only mode has no list mouse zone; the wheel scrolls the widened diff", async () => {
+	const long = Array.from({ length: 30 }, (_, index) => `+line ${index}`).join("\n");
+	const { component } = diffOnlyView({ rows: 8, loadDiff: async () => `@@ -0,0 +1,30 @@\n${long}` });
+	component.handleInput("F");
+	await settle();
+	component.render(80);
+	assert.equal(component.handleMouse(mouseButton("move", "none", 3, 2, 8)), undefined, "no hover target");
+	assert.equal(component.handleMouse(mouseButton("click", "left", 3, 2, 8)), undefined, "no click target");
+	assert.match(component.render(80)[1]!, /^│ M a\.ts +│$/, "a click where the list was does not select");
+	assert.deepEqual(component.handleMouse(mouse("wheel", 3, 2, 3, 8)), { handled: true, render: true });
+	assert.doesNotMatch(component.render(80)[2]!, /@@/, "the left edge now scrolls the diff");
+	component.handleInput("\x1b");
+	component.render(80);
+	assert.deepEqual(component.handleMouse(mouse("click", 3, 3, undefined, 8)), { handled: true, render: true }, "leaving diff-only restores the list zone");
+	assert.match(component.render(80)[3]!, /▸   M b\.ts/);
+});
+
+test("the native fullscreen wrapper keeps keyboard, hover, click and wheel on the changes view", async () => {
+	let onInput: ((data: string) => void) | undefined;
+	const terminal: Terminal = {
+		start(input: Parameters<Terminal["start"]>[0]) { onInput = input; }, stop() {}, async drainInput() {}, write() {}, get columns() { return 80; }, get rows() { return 8; }, get kittyProtocolActive() { return false; }, moveBy() {}, hideCursor() {}, showCursor() {}, clearLine() {}, clearFromCursor() {}, clearScreen() {}, setTitle() {}, setProgress() {}, setProgramStatus() {},
+	};
+	const long = Array.from({ length: 30 }, (_, index) => `+line ${index}`).join("\n");
+	let renders = 0;
+	const trees = [{ root: "/main", branch: "main", model: changesModel([file("a.ts", 1, 0), file("b.ts", 1, 0)]) }];
+	const component = new WorktreeChangesView(trees, {
+		theme: { fg: (color: string, text: string) => color === "warning" ? `\x1b[33m${text}\x1b[39m` : text }, rows: 8, loadDiff: async () => `@@ -0,0 +1,30 @@\n${long}`,
+		onOpen() {}, onClose() {}, onRefresh() {}, requestRender() {},
+	});
+	const interaction = createNativeFullscreenInteraction({ keyboardTarget: component, requestRender: () => { renders++; } });
+	interaction.addChild(component);
+	const tui = new TuiAltScreen(terminal, false, undefined, { mouse: true });
+	tui.setLayoutRoot(interaction);
+	tui.start();
+	interaction.handleInput("\r");
+	assert.ok(renders > 0, "keys reach the view and request a render");
+	tui.renderNow(true);
+	try {
+		onInput?.("\x1b[<35;4;4M");
+		assert.match(interaction.render(80)[3]!, /\x1b\[33mM b\.ts/, "hover paints the row under the pointer");
+		onInput?.("\x1b[<0;4;4M");
+		onInput?.("\x1b[<0;4;4m");
+		assert.match(stripAnsi(interaction.render(80)[3]!), /▸   M b\.ts/, "a click selects the file");
+		await settle();
+		tui.renderNow(true);
+		onInput?.("\x1b[<65;60;3M");
+		assert.doesNotMatch(stripAnsi(interaction.render(80)[2]!), /@@/, "the wheel scrolls the diff");
+		interaction.handleInput("F");
+		tui.renderNow(true);
+		onInput?.("\x1b[<0;4;3M");
+		onInput?.("\x1b[<0;4;3m");
+		assert.match(stripAnsi(interaction.render(80)[1]!), /^│ M b\.ts +│$/, "diff-only mode ignores clicks where the list was");
+	} finally {
+		tui.stop();
+	}
+});

package/tests/shell-gauge.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { paintGauge, renderGauge, type GaugePaint } from "../lib/shell-gauge.ts";
+
+// Issue #2222: gauge-specific theme roles fall back to today's roles when a
+// theme does not define them, so existing themes render byte-identically.
+// (Fixtures here are unit-scoped stubs; Pi's theme schema is validated
+// separately by the loader and was checked directly against ThemeJsonSchema.)
+
+const taggedTheme = {
+	fg(color: string, text: string) {
+		return `<${color}>${text}</${color}>`;
+	},
+};
+
+test("paintGauge falls back to today's roles when no gauge roles are given", () => {
+	assert.equal(paintGauge(45, taggedTheme), `<accent>▰▰▰▰</accent><border>▱▱▱▱</border>`);
+	assert.equal(paintGauge(85, taggedTheme), `<warning>▰▰▰▰▰▰▰</warning><border>▱</border>`);
+	assert.equal(paintGauge(96, taggedTheme), `<error>▰▰▰▰▰▰▰▰</error><border></border>`);
+	assert.equal(paintGauge(null, taggedTheme), `<dim></dim><border>▱▱▱▱▱▱▱▱</border>`);
+});
+
+test("paintGauge uses the gauge-specific roles when the theme defines them", () => {
+	const roles: GaugePaint = { ok: "gaugeOk", warning: "gaugeWarning", error: "gaugeError", empty: "gaugeEmpty" };
+	assert.equal(paintGauge(45, taggedTheme, 8, roles), `<gaugeOk>▰▰▰▰</gaugeOk><gaugeEmpty>▱▱▱▱</gaugeEmpty>`);
+	assert.equal(paintGauge(85, taggedTheme, 8, roles), `<gaugeWarning>▰▰▰▰▰▰▰</gaugeWarning><gaugeEmpty>▱</gaugeEmpty>`);
+	assert.equal(paintGauge(96, taggedTheme, 8, roles), `<gaugeError>▰▰▰▰▰▰▰▰</gaugeError><gaugeEmpty></gaugeEmpty>`);
+	// A null percentage stays dim: there is nothing to gauge yet.
+	assert.equal(paintGauge(null, taggedTheme, 8, roles), `<dim></dim><gaugeEmpty>▱▱▱▱▱▱▱▱</gaugeEmpty>`);
+});
+
+test("paintGauge falls back per role, not per block", () => {
+	// A theme that defines only gaugeWarning keeps accent for the ok range.
+	assert.equal(paintGauge(45, taggedTheme, 8, { warning: "gaugeWarning" }), `<accent>▰▰▰▰</accent><border>▱▱▱▱</border>`);
+	assert.equal(paintGauge(85, taggedTheme, 8, { warning: "gaugeWarning" }), `<gaugeWarning>▰▰▰▰▰▰▰</gaugeWarning><border>▱</border>`);
+});
+
+test("renderGauge uses theme-defined glyphs when given, defaults otherwise", () => {
+	assert.equal(renderGauge(50, 4, { filled: "█", empty: "░" }), "██░░");
+	assert.equal(renderGauge(50, 4), "▰▰▱▱");
+	assert.equal(renderGauge(50, 4, { filled: "█" }), "██▱▱");
+});

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