gentle-pi 4.2.0 → 4.4.0

package/tests/gentle-music.test.ts

@@ -0,0 +1,335 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import test, { type TestContext } from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import gentleMusic, {
+	findOnPath,
+	formatMusicStatus,
+	GENTLE_STREAM_SPEC,
+	MUSIC_COMMAND_NAME,
+	musicTuiArgs,
+	parseMusicArgs,
+	resolveGentleStream,
+	type MusicSpawn,
+} from "../extensions/gentle-music.ts";
+
+// /gentle:music hands the terminal to gentle-stream's own TUI, the way Pi's
+// external editor does, and controls the background player with
+// `gentle-stream ctl …` without taking the terminal.
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+type Command = { description: string; handler(args: string, ctx: ExtensionContext): Promise<void> };
+
+function fakePi() {
+	const commands = new Map<string, Command>();
+	const handlers = new Map<string, Handler[]>();
+	const pi = {
+		registerCommand: (name: string, registration: Command) => commands.set(name, registration),
+		registerShortcut: () => assert.fail("/gentle:music registers no shortcut"),
+		on: (event: string, handler: Handler) => handlers.set(event, [...(handlers.get(event) ?? []), handler]),
+	} as unknown as ExtensionAPI;
+	const fire = async (event: string, payload: unknown, ctx: ExtensionContext) => {
+		for (const handler of handlers.get(event) ?? []) await handler(payload, ctx);
+	};
+	return { pi, commands, fire };
+}
+
+function fakeContext(mode = "tui", model: { provider: string; id: string } | null = { provider: "anthropic", id: "claude-sonnet-5-5" }, failing?: "stop" | "start") {
+	const notices: Array<[string, string | undefined]> = [];
+	const calls: string[] = [];
+	let settled = false;
+	const tui = {
+		stop: () => { calls.push("stop"); if (failing === "stop") throw new Error("terminal busy"); },
+		start: () => { calls.push("start"); if (failing === "start") throw new Error("terminal gone"); },
+		requestRender: (force?: boolean) => calls.push(`render:${force === true}`),
+	};
+	const ctx = {
+		hasUI: true,
+		mode,
+		model: model ?? undefined,
+		ui: {
+			notify: (message: string, type?: string) => notices.push([message, type]),
+			custom: (factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: unknown) => void) => unknown) =>
+				new Promise((resolve) => {
+					factory(tui, {}, {}, (value) => { settled = true; resolve(value); });
+				}),
+		},
+	} as unknown as ExtensionContext;
+	return { ctx, notices, calls, settled: () => settled };
+}
+
+type Outcome = { code?: number | null; error?: Error; stdout?: string; stderr?: string; hang?: boolean };
+
+function fakeSpawn(outcomes: Outcome[], calls: string[] = []) {
+	const spawned: Array<{ command: string; args: readonly string[]; stdio: unknown }> = [];
+	const spawn: MusicSpawn = (command, args, options) => {
+		spawned.push({ command, args, stdio: options.stdio });
+		calls.push(`spawn:${args.join(" ")}`);
+		const outcome = outcomes.shift() ?? { code: 0 };
+		const child = Object.assign(new EventEmitter(), {
+			stdout: new EventEmitter(),
+			stderr: new EventEmitter(),
+			kill: () => { calls.push("kill"); child.emit("close", null); return true; },
+		});
+		if (!outcome.hang) {
+			setImmediate(() => {
+				if (outcome.error) { child.emit("error", outcome.error); return; }
+				if (outcome.stdout) child.stdout.emit("data", Buffer.from(outcome.stdout));
+				if (outcome.stderr) child.stderr.emit("data", Buffer.from(outcome.stderr));
+				child.emit("close", outcome.code ?? 0);
+			});
+		}
+		return child;
+	};
+	return { spawn, spawned };
+}
+
+const onPath = (names: Record<string, string>) => (name: string) => names[name];
+
+function fakeSignals() {
+	const listeners = new Set<() => void>();
+	return {
+		listeners,
+		signals: { on: (_signal: "SIGINT", listener: () => void) => listeners.add(listener), off: (_signal: "SIGINT", listener: () => void) => listeners.delete(listener) },
+	};
+}
+
+test("executable resolution prefers gentle-stream, then uvx, then uv, else nothing", () => {
+	assert.deepEqual(resolveGentleStream(onPath({ "gentle-stream": "/bin/gentle-stream", uvx: "/bin/uvx" })), { command: "/bin/gentle-stream", prefix: [] });
+	assert.deepEqual(resolveGentleStream(onPath({ uvx: "/bin/uvx", uv: "/bin/uv" })), { command: "/bin/uvx", prefix: ["--from", GENTLE_STREAM_SPEC, "gentle-stream"] });
+	assert.deepEqual(resolveGentleStream(onPath({ uv: "/bin/uv" })), { command: "/bin/uv", prefix: ["tool", "run", "--from", GENTLE_STREAM_SPEC, "gentle-stream"] });
+	assert.equal(resolveGentleStream(onPath({})), undefined);
+});
+
+test("findOnPath finds executable files only, honoring PATHEXT on Windows", (t: TestContext) => {
+	const root = mkdtempSync(join(tmpdir(), "gentle-music-path-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const a = join(root, "a");
+	const b = join(root, "b");
+	mkdirSync(a);
+	mkdirSync(b);
+	writeFileSync(join(a, "gentle-stream"), "not executable");
+	chmodSync(join(a, "gentle-stream"), 0o644);
+	writeFileSync(join(b, "gentle-stream"), "#!/bin/sh\n");
+	chmodSync(join(b, "gentle-stream"), 0o755);
+	mkdirSync(join(a, "uvx"));
+	const env = { PATH: [a, b].join(delimiter) };
+	if (process.platform !== "win32") assert.equal(findOnPath("gentle-stream", env, "darwin"), join(b, "gentle-stream"));
+	assert.equal(findOnPath("uvx", env, "darwin"), undefined, "a directory is not an executable");
+	assert.equal(findOnPath("missing", env, "darwin"), undefined);
+	assert.equal(findOnPath("gentle-stream", {}, "darwin"), undefined);
+	writeFileSync(join(a, "uv.EXE"), "");
+	assert.equal(findOnPath("uv", { Path: a, PATHEXT: ".COM;.EXE" }, "win32"), join(a, "uv.EXE"));
+});
+
+test("TUI arguments carry the session model and the mood as one argument", () => {
+	assert.deepEqual(musicTuiArgs({ model: { provider: "anthropic", id: "claude-sonnet-5-5" }, mood: "rainy \"lo-fi\" night; $HOME" }), ["--model", "anthropic/claude-sonnet-5-5", "--mood", "rainy \"lo-fi\" night; $HOME"]);
+	assert.deepEqual(musicTuiArgs({ model: { provider: "anthropic", id: "claude-sonnet-5-5" } }), ["--model", "anthropic/claude-sonnet-5-5"]);
+	assert.deepEqual(musicTuiArgs({ model: undefined, mood: "calm" }), ["--mood", "calm"]);
+	assert.deepEqual(musicTuiArgs({ model: { provider: "", id: "x" } }), []);
+});
+
+test("only an exact single control word is a subcommand; anything else is a mood", () => {
+	assert.deepEqual(parseMusicArgs(""), { kind: "tui" });
+	assert.deepEqual(parseMusicArgs("   "), { kind: "tui" });
+	for (const command of ["next", "pause", "play", "stop", "status"]) assert.deepEqual(parseMusicArgs(` ${command} `), { kind: "ctl", command });
+	assert.deepEqual(parseMusicArgs("next to the sea"), { kind: "tui", mood: "next to the sea" });
+	assert.deepEqual(parseMusicArgs("toggle"), { kind: "tui", mood: "toggle" });
+	assert.deepEqual(parseMusicArgs("  dark synthwave  "), { kind: "tui", mood: "dark synthwave" });
+});
+
+test("status output becomes a one-line summary", () => {
+	assert.equal(formatMusicStatus('{"running": false}\n'), "nothing is playing");
+	assert.equal(formatMusicStatus('{"running": true, "playing": true, "name": "Neon Rain", "genre": "synthwave", "mood": "night"}'), "♪ Neon Rain · synthwave · playing");
+	assert.equal(formatMusicStatus('{"running": true, "playing": false, "name": "Neon Rain", "genre": "synthwave", "mood": ""}'), "♪ Neon Rain · synthwave · paused");
+	assert.equal(formatMusicStatus('{"running": true, "playing": true, "name": "", "genre": ""}'), "♪ playing");
+	assert.equal(formatMusicStatus("garbage"), undefined);
+	assert.equal(formatMusicStatus("[]"), undefined);
+});
+
+test("registers /gentle:music without a shortcut", () => {
+	const { pi, commands } = fakePi();
+	gentleMusic(pi, { which: onPath({}) });
+	assert.equal(MUSIC_COMMAND_NAME, "gentle:music");
+	assert.match(commands.get(MUSIC_COMMAND_NAME)!.description, /gentle-stream/);
+});
+
+test("non-TUI modes get a notice and spawn nothing", async () => {
+	const { pi, commands } = fakePi();
+	const { spawn, spawned } = fakeSpawn([]);
+	gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn });
+	for (const mode of ["rpc", "json", "print"]) {
+		const context = fakeContext(mode);
+		await commands.get(MUSIC_COMMAND_NAME)!.handler("", context.ctx);
+		assert.deepEqual(context.notices, [["/gentle:music needs the interactive terminal.", "warning"]]);
+		assert.deepEqual(context.calls, []);
+	}
+	assert.equal(spawned.length, 0);
+});
+
+test("without gentle-stream or uv the command explains how to install and does nothing else", async () => {
+	const { pi, commands } = fakePi();
+	const { spawn, spawned } = fakeSpawn([]);
+	gentleMusic(pi, { which: onPath({}), spawn });
+	const context = fakeContext();
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("calm", context.ctx);
+	assert.equal(spawned.length, 0);
+	assert.deepEqual(context.calls, []);
+	assert.equal(context.notices.length, 1);
+	const [message, type] = context.notices[0]!;
+	assert.equal(type, "warning");
+	assert.match(message, /https:\/\/docs\.astral\.sh\/uv/);
+	assert.ok(message.includes(`uv tool install '${GENTLE_STREAM_SPEC}'`));
+});
+
+test("the TUI gets the terminal, then Pi is restarted with a forced repaint", async () => {
+	const { pi, commands } = fakePi();
+	const context = fakeContext();
+	const { spawn, spawned } = fakeSpawn([{ code: 0 }], context.calls);
+	const { listeners, signals } = fakeSignals();
+	let sigintWhileRunning = 0;
+	gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn: (command, args, options) => { sigintWhileRunning = listeners.size; return spawn(command, args, options); }, signals });
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("rainy night", context.ctx);
+	assert.deepEqual(context.calls, ["stop", "spawn:--model anthropic/claude-sonnet-5-5 --mood rainy night", "start", "render:true"]);
+	assert.deepEqual(spawned[0], { command: "/bin/gentle-stream", args: ["--model", "anthropic/claude-sonnet-5-5", "--mood", "rainy night"], stdio: "inherit" });
+	assert.equal(sigintWhileRunning, 1, "Pi ignores Ctrl+C while the TUI runs");
+	assert.equal(listeners.size, 0, "the SIGINT guard is removed afterwards");
+	assert.deepEqual(context.notices, []);
+	assert.equal(context.settled(), true);
+});
+
+test("the uvx fallback runs gentle-stream from the published spec", async () => {
+	const { pi, commands } = fakePi();
+	const context = fakeContext("tui", null);
+	const { spawn, spawned } = fakeSpawn([{ code: 0 }], context.calls);
+	gentleMusic(pi, { which: onPath({ uvx: "/bin/uvx" }), spawn, signals: fakeSignals().signals });
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("", context.ctx);
+	assert.deepEqual(spawned[0]!.args, ["--from", GENTLE_STREAM_SPEC, "gentle-stream"]);
+});
+
+test("Pi is restored and the failure reported when the TUI exits non-zero or cannot start", async () => {
+	for (const [outcome, pattern] of [[{ code: 2 }, /exited with code 2/], [{ error: new Error("spawn ENOENT") }, /could not start.*spawn ENOENT/]] as const) {
+		const { pi, commands } = fakePi();
+		const context = fakeContext();
+		const { spawn } = fakeSpawn([outcome], context.calls);
+		const { listeners, signals } = fakeSignals();
+		gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn, signals });
+		await commands.get(MUSIC_COMMAND_NAME)!.handler("", context.ctx);
+		assert.deepEqual(context.calls.filter((call) => !call.startsWith("spawn")), ["stop", "start", "render:true"]);
+		assert.equal(listeners.size, 0);
+		assert.equal(context.notices.length, 1);
+		assert.match(context.notices[0]![0], pattern);
+		assert.equal(context.notices[0]![1], "error");
+	}
+});
+
+test("Pi is restored even when spawn itself throws", async () => {
+	const { pi, commands } = fakePi();
+	const context = fakeContext();
+	const { listeners, signals } = fakeSignals();
+	gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn: () => { throw new Error("EPERM"); }, signals });
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("", context.ctx);
+	assert.deepEqual(context.calls, ["stop", "start", "render:true"]);
+	assert.equal(listeners.size, 0);
+	assert.match(context.notices[0]![0], /could not start.*EPERM/);
+});
+
+test("control words run ctl with captured output and never take the terminal", async () => {
+	const { pi, commands } = fakePi();
+	const context = fakeContext();
+	const { spawn, spawned } = fakeSpawn([
+		{ code: 0, stdout: '{"running": true, "playing": true, "name": "Neon Rain", "genre": "synthwave", "mood": "night"}\n' },
+		{ code: 0 },
+		{ code: 1, stderr: "gentle-stream: nothing is playing\n" },
+		{ code: 0, stdout: "not json" },
+	], context.calls);
+	gentleMusic(pi, { which: onPath({ uvx: "/bin/uvx" }), spawn });
+	const run = (args: string) => commands.get(MUSIC_COMMAND_NAME)!.handler(args, context.ctx);
+	await run("status");
+	await run("next");
+	await run("pause");
+	await run("status");
+	assert.deepEqual(spawned.map((entry) => entry.args.slice(3)), [["ctl", "status"], ["ctl", "next"], ["ctl", "pause"], ["ctl", "status"]]);
+	assert.ok(spawned.every((entry) => JSON.stringify(entry.stdio) === JSON.stringify(["ignore", "pipe", "pipe"])));
+	assert.ok(!context.calls.includes("stop"), "ctl never stops the TUI");
+	assert.deepEqual(context.notices, [
+		["♪ Neon Rain · synthwave · playing", "info"],
+		["♪ next track", "info"],
+		["gentle-stream: nothing is playing", "warning"],
+		["gentle-stream status was not readable: not json", "warning"],
+	]);
+});
+
+test("a control word without gentle-stream or uv explains how to install", async () => {
+	const { pi, commands } = fakePi();
+	const { spawn, spawned } = fakeSpawn([]);
+	gentleMusic(pi, { which: onPath({}), spawn });
+	const context = fakeContext();
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("next", context.ctx);
+	assert.equal(spawned.length, 0);
+	assert.match(context.notices[0]![0], /uv tool install/);
+});
+
+test("quitting Pi stops the music only after /gentle:music was used", async () => {
+	const unused = fakePi();
+	const quiet = fakeSpawn([]);
+	gentleMusic(unused.pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn: quiet.spawn, signals: fakeSignals().signals, usage: { used: false } });
+	await unused.fire("session_shutdown", { type: "session_shutdown", reason: "quit" }, fakeContext().ctx);
+	assert.equal(quiet.spawned.length, 0);
+
+	const usage = { used: false };
+	const { pi, commands, fire } = fakePi();
+	const context = fakeContext();
+	const { spawn, spawned } = fakeSpawn([{ code: 0 }, { code: 0 }], context.calls);
+	gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn, signals: fakeSignals().signals, usage });
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("", context.ctx);
+	await fire("session_shutdown", { type: "session_shutdown", reason: "new" }, context.ctx);
+	assert.equal(spawned.length, 1, "switching sessions keeps the music playing");
+	await fire("session_shutdown", { type: "session_shutdown", reason: "quit" }, context.ctx);
+	assert.deepEqual(spawned[1], { command: "/bin/gentle-stream", args: ["ctl", "stop"], stdio: ["ignore", "pipe", "pipe"] });
+});
+
+test("the shutdown stop never blocks longer than its budget", async () => {
+	const { pi, commands, fire } = fakePi();
+	const context = fakeContext();
+	const { spawn } = fakeSpawn([{ code: 0 }, { hang: true }], context.calls);
+	gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn, signals: fakeSignals().signals, usage: { used: false }, shutdownTimeoutMs: 20 });
+	await commands.get(MUSIC_COMMAND_NAME)!.handler("status", context.ctx);
+	const started = Date.now();
+	await fire("session_shutdown", { type: "session_shutdown", reason: "quit" }, context.ctx);
+	assert.ok(Date.now() - started < 1000);
+	assert.ok(context.calls.includes("kill"), "the hung ctl is killed");
+});
+
+test("a failing terminal handover still settles the command, reports it and removes the Ctrl+C guard", async () => {
+	for (const failing of ["stop", "start"] as const) {
+		const { pi, commands } = fakePi();
+		const context = fakeContext("tui", undefined, failing);
+		const { spawn, spawned } = fakeSpawn([{ code: 0 }], context.calls);
+		const { listeners, signals } = fakeSignals();
+		gentleMusic(pi, { which: onPath({ "gentle-stream": "/bin/gentle-stream" }), spawn, signals });
+		await commands.get(MUSIC_COMMAND_NAME)!.handler("", context.ctx);
+		assert.equal(context.settled(), true, `done is called when tui.${failing}() throws`);
+		assert.equal(listeners.size, 0, "the SIGINT guard is removed");
+		assert.equal(spawned.length, failing === "stop" ? 0 : 1);
+		assert.equal(context.notices.length, 1);
+		assert.match(context.notices[0]![0], failing === "stop" ? /terminal busy/ : /terminal gone/);
+	}
+});
+
+test("Windows .cmd and .bat shims are not picked, so resolution falls back to uvx", (t: TestContext) => {
+	const dir = mkdtempSync(join(tmpdir(), "gentle-music-win-"));
+	t.after(() => rmSync(dir, { recursive: true, force: true }));
+	writeFileSync(join(dir, "gentle-stream.CMD"), "@echo off\n");
+	writeFileSync(join(dir, "uvx.BAT"), "@echo off\n");
+	writeFileSync(join(dir, "uv.EXE"), "");
+	const env = { Path: dir, PATHEXT: ".COM;.EXE;.BAT;.CMD" };
+	assert.equal(findOnPath("gentle-stream", env, "win32"), undefined);
+	assert.equal(findOnPath("uvx", env, "win32"), undefined);
+	assert.equal(findOnPath("uv", env, "win32"), join(dir, "uv.EXE"));
+	const resolved = resolveGentleStream((name) => findOnPath(name, env, "win32"));
+	assert.equal(resolved?.command, join(dir, "uv.EXE"));
+});

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

@@ -661,6 +661,123 @@ test("first isolated run bootstraps the home, writes fullscreen, and prints the
 	assert.doesNotMatch(second.stderr, /using a separate home at/);
 });
 
+// --- home import-pi ----------------------------------------------------------
+
+function importPiFixture(t: test.TestContext) {
+	const f = fixture(t);
+	const env = { ...f.env, PI_CODING_AGENT_DIR: undefined };
+	const piHome = join(f.home, ".pi", "agent");
+	mkdirSync(piHome, { recursive: true });
+	writeFileSync(join(piHome, "auth.json"), JSON.stringify({ anthropic: { type: "oauth", refresh: "dummy-refresh" } }), { mode: 0o600 });
+	writeFileSync(join(piHome, "mcp.json"), JSON.stringify({ mcpServers: {} }));
+	writeFileSync(join(piHome, "settings.json"), JSON.stringify({ defaultProvider: "anthropic", defaultModel: "m", packages: ["npm:foreign"], extensions: ["./x.ts"] }));
+	writeFileSync(join(piHome, "mcp-cache.json"), "{}");
+	return { ...f, env, piHome };
+}
+
+test("first isolated run without a pi home keeps the plain --link hint", (t) => {
+	const f = fixture(t);
+	const first = run({ ...f.env, PI_CODING_AGENT_DIR: undefined }, []);
+	assert.equal(first.status, 0, first.stderr);
+	assert.match(first.stderr, /Run 'gentle-shell --link' to reuse your pi sign-ins and chats\.\n/);
+	assert.doesNotMatch(first.stderr, /import-pi/);
+});
+
+test("first isolated run with a pi sign-in also mentions home import-pi", (t) => {
+	const f = importPiFixture(t);
+	const first = run(f.env, []);
+	assert.equal(first.status, 0, first.stderr);
+	assert.match(first.stderr, /'gentle-shell --link' to reuse your pi sign-ins and chats, or 'gentle-shell home import-pi'/);
+});
+
+test("--help lists home import-pi", (t) => {
+	const f = fixture(t);
+	const result = run(f.env, ["--help"]);
+	assert.match(result.stdout, /gentle-shell \[home selectors\] home import-pi \[--dry-run\]/);
+});
+
+test("home import-pi copies sign-ins, MCP servers and default model into the isolated home only", (t) => {
+	const f = importPiFixture(t);
+	const result = run(f.env, ["home", "import-pi"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.match(result.stdout, /auth\.json: copied \(0600\)/);
+	assert.match(result.stdout, /settings\.json defaultProvider: copied/);
+	assert.doesNotMatch(result.stdout + result.stderr, /dummy-refresh/);
+	assert.ok(existsSync(join(f.gentleShellHome, "auth.json")));
+	assert.equal(existsSync(join(f.gentleShellHome, "mcp-cache.json")), false);
+	if (process.platform !== "win32") assert.equal(statSync(join(f.gentleShellHome, "auth.json")).mode & 0o777, 0o600);
+	const settings = JSON.parse(readFileSync(join(f.gentleShellHome, "settings.json"), "utf8"));
+	assert.equal(settings.defaultProvider, "anthropic");
+	assert.equal(settings.tuiMode, "fullscreen", "the home is bootstrapped as a normal first launch would");
+	assert.equal(settings.packages, undefined);
+	assert.equal(settings.extensions, undefined);
+	assert.ok(existsSync(join(f.gentleShellHome, ".gentle-shell-home")));
+
+	const again = run(f.env, ["home", "import-pi"]);
+	assert.equal(again.status, 0, again.stderr);
+	assert.match(again.stdout, /auth\.json: already present, kept/);
+	assert.match(again.stdout, /Nothing to import/);
+});
+
+test("home import-pi --dry-run prints the plan and creates nothing", (t) => {
+	const f = importPiFixture(t);
+	const result = run(f.env, ["home", "import-pi", "--dry-run"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.match(result.stdout, /auth\.json: would copy/);
+	assert.equal(existsSync(f.gentleShellHome), false);
+	assert.equal(existsSync(join(f.home, ".gentle-shell")), false);
+});
+
+test("home import-pi refuses link mode and a target that is the pi home itself", (t) => {
+	const f = importPiFixture(t);
+	const before = readFileSync(join(f.piHome, "settings.json"), "utf8");
+	for (const argv of [["--link", "home", "import-pi"], ["--home", f.piHome, "home", "import-pi"]]) {
+		const result = run(f.env, argv);
+		assert.equal(result.status, 1, argv.join(" "));
+		assert.match(result.stderr, /gentle-shell home import-pi: .*nothing to import/);
+	}
+	assert.equal(run(f.env, ["home", "link"]).status, 0);
+	assert.equal(run(f.env, ["home", "import-pi"]).status, 1);
+	assert.equal(readFileSync(join(f.piHome, "settings.json"), "utf8"), before);
+	assert.equal(run(f.env, ["home", "import-pi", "--force"]).status, 2);
+});
+
+test("a --home filled by home import-pi is still auto-provisioned as gentle-shell's own", (t) => {
+	const f = importPiFixture(t);
+	const fresh = join(f.root, "fresh-home");
+	const empty = join(f.root, "empty-home");
+	mkdirSync(empty);
+	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
+	const counterPath = join(f.root, "gentle-ai-runs.log");
+	writeGentleAiScriptCountingRuns(gentleAiScript, counterPath);
+	const env = enableAutoProvision({ ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript, GENTLE_SHELL_GENTLE_AI_PIN: "3.6.0" });
+	for (const [index, target] of [fresh, empty].entries()) {
+		const imported = run(f.env, ["--home", target, "home", "import-pi"]);
+		assert.equal(imported.status, 0, imported.stderr);
+		assert.match(imported.stdout, /auth\.json: copied/);
+		const launch = run(env, ["--home", target, "--mode", "rpc"]);
+		assert.equal(launch.status, 0, launch.stderr);
+		assert.doesNotMatch(launch.stderr, /already has content and was not set up by gentle-shell/);
+		assert.equal(readFileSync(counterPath, "utf8").trim().split("\n").length, index + 1, `auto-provisioning ran for ${target}`);
+	}
+});
+
+test("home import-pi exits 1 and names the item when a write fails", { skip: process.platform === "win32" }, (t) => {
+	const f = importPiFixture(t);
+	mkdirSync(f.gentleShellHome, { recursive: true });
+	writeFileSync(join(f.gentleShellHome, "settings.json"), "{}");
+	writeFileSync(join(f.gentleShellHome, ".gentle-shell-home"), "{}");
+	chmodSync(f.gentleShellHome, 0o500);
+	let result;
+	try {
+		result = run(f.env, ["home", "import-pi"]);
+	} finally {
+		chmodSync(f.gentleShellHome, 0o700); // before the fixture's own cleanup
+	}
+	assert.equal(result.status, 1);
+	assert.match(result.stdout, /auth\.json: failed/);
+});
+
 test("forwarded args reach pi after the injected extension flags, in order", (t) => {
 	const f = fixture(t);
 	const result = run(f.env, ["--mode", "rpc", "-p", "hi"]);
@@ -815,6 +932,17 @@ test("gentle-shell install npm:<pkg> forwards the subcommand and its argument ve
 	assert.equal(payload.PI_CODING_AGENT_DIR, f.gentleShellHome);
 });
 
+// #2140: pi dispatches `mcp` on argv[0] only, so an injected -e ahead of it
+// turned `gentle-shell mcp list` into an interactive prompt.
+test("gentle-shell mcp add <server> -- <cmd> forwards to pi's own mcp verbatim, with no injected extension flags", (t) => {
+	const f = fixture(t);
+	const result = run(f.env, ["mcp", "add", "demo", "--", "npx", "-y", "demo-server"]);
+	assert.equal(result.status, 0, result.stderr);
+	const payload = JSON.parse(result.stdout);
+	assert.deepEqual(payload.args, ["mcp", "add", "demo", "--", "npx", "-y", "demo-server"]);
+	assert.equal(payload.PI_CODING_AGENT_DIR, f.gentleShellHome);
+});
+
 test("a too-old pi exits 1 naming both versions", (t) => {
 	const f = fixture(t);
 	writePiScript(f.piScript, "0.80.0");
@@ -2603,6 +2731,13 @@ test("--help mentions the setup subcommand", (t) => {
 	assert.match(result.stdout, /\bsetup\b/);
 });
 
+test("--help lists the mcp subcommand", (t) => {
+	const f = fixture(t);
+	const result = run(f.env, ["--help"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.match(result.stdout, /gentle-shell mcp /);
+});
+
 // --- --link takeover of a conflicting path package -----------------------
 //
 // Regression coverage for the settings.json shape that triggered the tool
@@ -3350,3 +3485,31 @@ test("on a TTY without colors the gentle-shell line has no ANSI styling", { skip
 	const out = runInPty({ ...f.env, GENTLE_SHELL_PI: piScript, PTY_NO_COLOR: "1" }, ["--link"]);
 	assert.ok(out.endsWith(`${PI_HINT}To resume in gentle-shell: gentle-shell --link --session abc\r\n`), JSON.stringify(out));
 });
+
+// #2143: a Gentle AI that honors GENTLE_AI_PI_EXCLUDE_PACKAGES (gentle-ai#5503)
+// never declares npm:gentle-pi, so setup neither runs `pi remove` nor prints
+// the contradictory "removing npm:gentle-pi" line.
+test("gentle-shell setup asks Gentle AI to skip npm:gentle-pi, so nothing is installed only to be removed", (t) => {
+	const f = fixture(t);
+	const gentleAiScript = join(f.root, "fake-gentle-ai.mjs");
+	writeFileSync(gentleAiScript, [
+		"#!/usr/bin/env node",
+		"import { readFileSync, writeFileSync } from 'node:fs';",
+		"import { join } from 'node:path';",
+		"const excluded = (process.env.GENTLE_AI_PI_EXCLUDE_PACKAGES ?? '').split(',').map((entry) => entry.trim());",
+		"const settingsPath = join(process.env.PI_CODING_AGENT_DIR, 'settings.json');",
+		"const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));",
+		"settings.packages = ['npm:gentle-pi', 'npm:pi-btw'].filter((source) => !excluded.includes(source));",
+		"writeFileSync(settingsPath, JSON.stringify(settings));",
+		"process.stdout.write(JSON.stringify({ args: process.argv.slice(2), excluded: process.env.GENTLE_AI_PI_EXCLUDE_PACKAGES ?? null }) + '\\n');",
+		"",
+	].join("\n"));
+	chmodSync(gentleAiScript, 0o755);
+	const result = run({ ...f.env, GENTLE_SHELL_GENTLE_AI_BIN: gentleAiScript }, ["setup"]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.doesNotMatch(result.stderr, /removing npm:gentle-pi/);
+	const lines = result.stdout.trim().split("\n").filter((line) => line.length > 0);
+	assert.equal(lines.length, 1, "no pi remove ran: " + result.stdout);
+	assert.deepEqual(JSON.parse(lines[0]), { args: ["install", "--agent", "pi", "--scope", "global"], excluded: "npm:gentle-pi" });
+});
+