gentle-pi 4.2.0 → 4.3.0

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

@@ -239,7 +239,7 @@ const FAKE_PI = [
 	"const args = process.argv.slice(2);",
 	"if (args[0] === 'install' && args[1] === 'npm:gentle-engram@0.4.2' && process.env.FIXTURE_INSTALL_CAPABILITY !== '0') {",
 	" const home = process.env.PI_CODING_AGENT_DIR; const metadata = join(home, 'npm/node_modules/gentle-engram/package.json'); mkdirSync(dirname(metadata), {recursive:true});",
-	" writeFileSync(metadata, JSON.stringify({name:'gentle-engram',version:'0.4.2',engram:{startupPolicy:1}}));",
+	" writeFileSync(metadata, JSON.stringify({name:'gentle-engram',version:'0.4.2',engram:{startupPolicy:1,...(process.env.FIXTURE_OWNED_COMPANION === '0' ? {} : {sessionOwned:1})}}));",
 	" const path = join(home,'settings.json'); let settings={}; try {settings=JSON.parse(readFileSync(path,'utf8'));} catch {}",
 	" if (process.env.FIXTURE_INSTALL_CAPABILITY !== 'metadata-only') { const packages = settings.packages ?? []; const index = packages.findIndex(p => /^npm:gentle-engram(?:@|$)/.test(typeof p === 'string' ? p : p.source));",
 	" if (index < 0) packages.push(args[1]); else packages[index] = typeof packages[index] === 'string' ? args[1] : {...packages[index], source:args[1]}; settings.packages = packages; writeFileSync(path, JSON.stringify(settings)); }",
@@ -255,7 +255,7 @@ const FAKE_PI = [
 	" }",
 	"}",
 	"const pick = ['PATH', 'GENTLE_SHELL_PI', 'GENTLE_PI_AGENTS_PI', 'PI_SKIP_VERSION_CHECK', 'npm_config_prefix', 'npm_config_registry', 'NODE_OPTIONS', 'PI_CODING_AGENT_DIR',",
-	"\t'GENTLE_SHELL_PREFIX', 'GENTLE_PI_CONFIG_HOME', 'ENGRAM_BIN', 'ENGRAM_URL', 'ENGRAM_STARTUP_POLICY', 'ENGRAM_STARTUP_NOTICE', 'GENTLE_AI_HOME', 'GENTLE_AI_PI_CONFIG_DIR', 'GENTLE_AI_ENGRAM_BIN', 'GENTLE_AI_NO_SELF_UPDATE', 'GH_TOKEN', 'ENGRAM_NO_UPDATE_CHECK'];",
+	"\t'GENTLE_SHELL_PREFIX', 'GENTLE_PI_CONFIG_HOME', 'ENGRAM_BIN', 'ENGRAM_URL', 'ENGRAM_SERVER_MODE', 'ENGRAM_SOCKET', 'ENGRAM_STARTUP_POLICY', 'ENGRAM_STARTUP_NOTICE', 'GENTLE_AI_HOME', 'GENTLE_AI_PI_CONFIG_DIR', 'GENTLE_AI_ENGRAM_BIN', 'GENTLE_AI_NO_SELF_UPDATE', 'GH_TOKEN', 'ENGRAM_NO_UPDATE_CHECK'];",
 	"const record = join(process.env.GENTLE_SHELL_PREFIX ?? '', 'config', 'engram-provenance.json');",
 	"const provenance = (() => { try { return JSON.parse(readFileSync(record, 'utf8')); } catch { return null; } })();",
 	"console.log(JSON.stringify({ cli: process.argv[1], args, provenance, env: Object.fromEntries(pick.map((k) => [k, process.env[k]])) }));",
@@ -264,6 +264,7 @@ const FAKE_PI = [
 ].join("\n");
 const FIXTURE_CORE = [
 	"#!/bin/sh",
+	'if [ "$1" = --help ] && [ "$FIXTURE_OWNED_CORE" != 0 ]; then echo "  serve --session-owned  Private ephemeral HTTP server"; exit 0; fi',
 	'if [ "$1" != instance-id ]; then echo engram; exit 0; fi',
 	'[ -z "$FIXTURE_PROVISION_ENV" ] || env > "$FIXTURE_PROVISION_ENV"',
 	'[ -z "$FIXTURE_INSTANCE_ID_FAIL" ] || exit 3',
@@ -457,10 +458,170 @@ test("provenance mismatches disable memory behind the guard: instance, core dige
 		assert.equal(result.status, 0, `${name}: ${result.stderr}`);
 		const seen = lastLaunch(result);
 		assert.deepEqual([seen.env.ENGRAM_STARTUP_POLICY, seen.env.ENGRAM_BIN], ["disabled", prefix.guard], name);
-		assert.match(result.stderr, /memory disabled.*could not verify.*compatibility.*Back up/s, name);
+		assert.match(result.stderr, name === "core digest" ? /memory disabled.*bundled core changed.*memory migrate --confirm-quiescent/s : /memory disabled.*could not verify.*compatibility.*Back up/s, name);
 	}
 });
 
+function migrationFixture(t: TestContext, outcome = "success") {
+	const prefix = bundledPrefix(t);
+	assert.equal(prefix.run([], { FIXTURE_CREATE_STORE: STORE_ID }).status, 0);
+	const source = join(prefix.home, ".engram");
+	writeFileSync(join(source, "config.json"), '{"preserved":true}\n');
+	const originalRecord = readFileSync(provenancePath(prefix), "utf8");
+	const sourceBytes = readFileSync(join(source, "engram.db"));
+	const invocation = join(prefix.home, "migration-invoked");
+	writeFileSync(prefix.engram, `#!${process.execPath}\nimport {cpSync,writeFileSync} from 'node:fs';\nconst args=process.argv.slice(2);\nif(args[0]==='--help'){console.log(${JSON.stringify(outcome === "unsupported" ? "Commands: compatibility" : "  migrate-copy --data-dir <absolute-source> --output-dir <new-absolute-destination> --confirm-quiescent --json\n  serve --session-owned  Private ephemeral HTTP server")});process.exit(0);}\nwriteFileSync(${JSON.stringify(invocation)},JSON.stringify({args,token:process.env.GH_TOKEN,cloud:process.env.ENGRAM_CLOUD_TOKEN}));\nif(args[0]!=='migrate-copy') process.exit(2);\nconst source=args[args.indexOf('--data-dir')+1],output=args[args.indexOf('--output-dir')+1];\nif(${JSON.stringify(outcome)}==='failure'){process.stderr.write('migration rejected\\n');process.exit(1);}\ncpSync(source,output,{recursive:true});\nconsole.log(JSON.stringify({source_dir:source,output_dir:output,instance_id:${JSON.stringify(outcome === "wrong-identity" ? OTHER_STORE_ID : STORE_ID)},migration_completed:true}));\n`, { mode: 0o700 });
+	return { ...prefix, source, originalRecord, sourceBytes, invocation };
+}
+
+test("bundled local memory selects a verified session-owned provider instead of a detached shared server", { skip: posixHost }, (t) => {
+	const prefix = bundledPrefix(t);
+	const result = prefix.run([], { FIXTURE_CREATE_STORE: STORE_ID });
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(memoryOf(result), ["allow", prefix.engram]);
+	const seen = lastLaunch(result);
+	assert.equal(seen.env.ENGRAM_SERVER_MODE, "session-owned");
+	assert.equal(seen.env.ENGRAM_URL, undefined);
+	assert.equal(seen.env.ENGRAM_SOCKET, undefined);
+	assert.equal(seen.provenance.instanceId, STORE_ID);
+});
+
+test("missing private capabilities never silently fall back or provision a store", { skip: posixHost }, (t) => {
+	for (const env of [{ FIXTURE_OWNED_CORE: "0" }, { FIXTURE_OWNED_COMPANION: "0" }]) {
+		const prefix = bundledPrefix(t);
+		const result = prefix.run([], { ...env, FIXTURE_CREATE_STORE: STORE_ID });
+		assert.equal(result.status, 0, result.stderr);
+		assert.deepEqual(memoryOf(result), ["disabled", prefix.guard]);
+		assert.match(result.stderr, /session-owned.*supporting published/s);
+		assert.equal(existsSync(join(prefix.home, ".engram")), false);
+		assert.equal(existsSync(provenancePath(prefix)), false);
+	}
+});
+
+test("every selected companion must advertise private support, including mixed local and npm selections", { skip: posixHost }, (t) => {
+	const prefix = bundledPrefix(t);
+	const local = join(prefix.home, "legacy-companion");
+	mkdirSync(local);
+	writeFileSync(join(local, "package.json"), JSON.stringify({ name: "gentle-engram", engram: { startupPolicy: 1 } }));
+	writeFileSync(prefix.metadata, JSON.stringify({ name: "gentle-engram", engram: { startupPolicy: 1, sessionOwned: 1 } }));
+	const settings = join(prefix.home, ".gentle-shell", "agent", "settings.json");
+	const selected = JSON.stringify({ packages: [local, "npm:gentle-engram@0.4.2"] });
+	writeFileSync(settings, selected);
+	const result = prefix.run([], { FIXTURE_CREATE_STORE: STORE_ID });
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(memoryOf(result), ["disabled", prefix.guard]);
+	assert.match(result.stderr, /session-owned.*supporting published/s);
+	assert.deepEqual(JSON.parse(readFileSync(settings, "utf8")).packages, JSON.parse(selected).packages);
+	assert.equal(existsSync(join(prefix.home, ".engram")), false);
+	assert.equal(existsSync(provenancePath(prefix)), false);
+});
+
+test("explicit empty or conflicting private modes remain invalid without provisioning", { skip: posixHost }, (t) => {
+	for (const mode of ["", "shared", " "]) {
+		const prefix = bundledPrefix(t);
+		const result = prefix.run([], { ENGRAM_SERVER_MODE: mode, FIXTURE_CREATE_STORE: STORE_ID });
+		assert.equal(result.status, 0, result.stderr);
+		assert.deepEqual(memoryOf(result), ["disabled", prefix.guard]);
+		assert.equal(lastLaunch(result).env.ENGRAM_SERVER_MODE, mode);
+		assert.match(result.stderr, /explicit ENGRAM_SERVER_MODE.*unset.*session-owned/s);
+		assert.equal(existsSync(join(prefix.home, ".engram")), false);
+		assert.equal(existsSync(provenancePath(prefix)), false);
+	}
+});
+
+test("an explicit Engram socket remains untouched and is never probed", { skip: posixHost }, (t) => {
+	const prefix = bundledPrefix(t);
+	const result = prefix.run([], { ENGRAM_SOCKET: "/fixture/selected.sock", FIXTURE_NO_PROBE: "1" });
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(memoryOf(result), ["disabled", prefix.guard]);
+	assert.equal(lastLaunch(result).env.ENGRAM_SOCKET, "/fixture/selected.sock");
+	assert.equal(existsSync(join(prefix.home, ".engram")), false);
+});
+
+test("a stopped Shell store with a changed core gets migration guidance, not a server upgrade guess", { skip: posixHost }, (t) => {
+	const prefix = migrationFixture(t);
+	const result = prefix.run([]);
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(memoryOf(result), ["disabled", prefix.guard]);
+	assert.match(result.stderr, /bundled core changed/);
+	assert.match(result.stderr, /gentle-shell memory migrate --confirm-quiescent/);
+	assert.equal(existsSync(prefix.invocation), false);
+	assert.equal(readFileSync(provenancePath(prefix), "utf8"), prefix.originalRecord);
+	assert.deepEqual(readFileSync(join(prefix.source, "engram.db")), prefix.sourceBytes);
+});
+
+test("memory migrate explicitly promotes a verified copy and retains the original store", { skip: posixHost }, (t) => {
+	const prefix = migrationFixture(t);
+	const result = prefix.run(["memory", "migrate", "--confirm-quiescent"], { FIXTURE_NO_PROBE: "1", GH_TOKEN: "fixture-secret", ENGRAM_CLOUD_TOKEN: "fixture-cloud" });
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(result.stderr, "");
+	const receipt = JSON.parse(result.stdout);
+	assert.deepEqual(Object.keys(receipt).sort(), ["backup_dir", "instance_id", "status"]);
+	assert.equal(receipt.status, "migrated");
+	assert.equal(receipt.instance_id, STORE_ID);
+	assert.deepEqual(readFileSync(join(receipt.backup_dir, "engram.db")), prefix.sourceBytes);
+	assert.equal(readFileSync(join(receipt.backup_dir, "config.json"), "utf8"), '{"preserved":true}\n');
+	assert.equal(readFileSync(join(prefix.source, "config.json"), "utf8"), '{"preserved":true}\n');
+	assert.deepEqual(JSON.parse(readFileSync(provenancePath(prefix), "utf8")), { schema: 1, dataDir: prefix.source, instanceId: STORE_ID, coreSha256: sha256File(prefix.engram) });
+	const invoked = JSON.parse(readFileSync(prefix.invocation, "utf8"));
+	assert.equal(invoked.args[0], "migrate-copy");
+	assert.equal(invoked.token, undefined);
+	assert.equal(invoked.cloud, undefined);
+	assert.equal(existsSync(join(prefix.root, "config", "engram-migration.json")), false);
+	assert.deepEqual(memoryOf(prefix.run([])), ["allow", prefix.engram]);
+});
+
+test("memory migrate rejects missing confirmation and malformed flags without invoking Engram", { skip: posixHost }, (t) => {
+	const prefix = migrationFixture(t);
+	for (const args of [["memory", "migrate"], ["memory", "migrate", "--confirm-quiescent", "--unknown"], ["memory", "migrate", "--confirm-quiescent", "--confirm-quiescent"]]) {
+		const result = prefix.run(args, { FIXTURE_NO_PROBE: "1" });
+		assert.equal(result.status, 2, result.stderr);
+		assert.equal(result.stdout, "");
+		assert.equal(result.stderr, "Usage: gentle-shell memory migrate --confirm-quiescent\nStop every Engram client before running this command.\n");
+		assert.equal(existsSync(prefix.invocation), false);
+		assert.equal(readFileSync(provenancePath(prefix), "utf8"), prefix.originalRecord);
+		assert.deepEqual(readFileSync(join(prefix.source, "engram.db")), prefix.sourceBytes);
+	}
+});
+
+test("memory migrate never sends an unknown command to an older bundled core", { skip: posixHost }, (t) => {
+	const prefix = migrationFixture(t, "unsupported");
+	const result = prefix.run(["memory", "migrate", "--confirm-quiescent"], { FIXTURE_NO_PROBE: "1" });
+	assert.equal(result.status, 1, result.stderr);
+	assert.equal(result.stdout, "");
+	assert.match(result.stderr, /does not support migrate-copy/);
+	assert.equal(existsSync(prefix.invocation), false);
+	assert.equal(readFileSync(provenancePath(prefix), "utf8"), prefix.originalRecord);
+	assert.deepEqual(readFileSync(join(prefix.source, "engram.db")), prefix.sourceBytes);
+});
+
+test("memory migrate refuses provider failure and mismatched evidence without changing provenance or source", { skip: posixHost }, (t) => {
+	for (const outcome of ["failure", "wrong-identity"]) {
+		const prefix = migrationFixture(t, outcome);
+		const result = prefix.run(["memory", "migrate", "--confirm-quiescent"], { FIXTURE_NO_PROBE: "1" });
+		assert.equal(result.status, 1, result.stderr);
+		assert.equal(result.stdout, "");
+		assert.match(result.stderr, /^gentle-shell: memory migration failed:/);
+		assert.equal(readFileSync(provenancePath(prefix), "utf8"), prefix.originalRecord);
+		assert.deepEqual(readFileSync(join(prefix.source, "engram.db")), prefix.sourceBytes);
+		assert.equal(existsSync(join(prefix.root, "config", "engram-migration.json")), false);
+	}
+});
+
+test("an interrupted memory promotion blocks fresh provisioning until recovery", { skip: posixHost }, (t) => {
+	const prefix = bundledPrefix(t);
+	mkdirSync(join(prefix.root, "config"), { recursive: true });
+	const marker = join(prefix.root, "config", "engram-migration.json");
+	writeFileSync(marker, '{"interrupted":true}\n');
+	const result = prefix.run([], { FIXTURE_NO_PROBE: "1" });
+	assert.equal(result.status, 0, result.stderr);
+	assert.deepEqual(memoryOf(result), ["disabled", prefix.guard]);
+	assert.match(result.stderr, /incomplete memory migration/);
+	assert.equal(existsSync(join(prefix.home, ".engram")), false);
+	assert.equal(readFileSync(marker, "utf8"), '{"interrupted":true}\n');
+	assert.equal(existsSync(provenancePath(prefix)), false);
+});
+
 test("public help explains compatibility evidence without promising update recovery", { skip: posixHost }, (t) => {
 	const prefix = bundledPrefix(t);
 	const result = prefix.run(["--help"]);
@@ -497,7 +658,8 @@ test("a listening server is reused for Shell's store only with the recorded /hea
 		assert.equal(result.status, 0, `${name}: ${result.stderr}`);
 		const seen = lastLaunch(result);
 		assert.deepEqual([seen.env.ENGRAM_STARTUP_POLICY, seen.env.ENGRAM_BIN, seen.env.ENGRAM_URL],
-			[policy, policy === "allow" ? prefix.engram : prefix.guard, undefined], name);
+			[policy, prefix.guard, policy === "allow" ? "http://127.0.0.1:7437" : undefined], name);
+		assert.equal(seen.env.ENGRAM_SERVER_MODE, undefined, name);
 	}
 });
 
@@ -720,8 +882,9 @@ test("capability readback also requires Pi to declare the selected pinned compan
 	const result = prefix.run([], { FIXTURE_INSTALL_CAPABILITY: "metadata-only" });
 	assert.equal(result.status, 0, result.stderr);
 	assert.match(result.stderr, /startupPolicy/);
-	// Only the identity Shell provisions before Pi: no database is opened.
-	assert.deepEqual(readdirSync(join(prefix.home, ".engram")), [".instance-id"]);
+	// Unverified companion capability cannot authorize even fresh provisioning.
+	assert.equal(existsSync(join(prefix.home, ".engram")), false);
+	assert.equal(existsSync(provenancePath(prefix)), false);
 });
 
 test("pinning preserves resource filters and unrelated settings and does not reinstall next launch", { skip: posixHost }, (t) => {

package/tests/gentle-shell-import-pi.test.ts

@@ -0,0 +1,262 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { formatImportPiReport, importPi, nodeImportPiFs } from "../lib/gentle-shell-import-pi.ts";
+
+// `gentle-shell home import-pi` core: real temp directories, never the real
+// ~/.pi or ~/.gentle-shell. Credential contents never appear in assertions.
+
+const AUTH = JSON.stringify({ anthropic: { type: "oauth", refresh: "dummy-refresh", access: "dummy-access" } });
+const MCP = JSON.stringify({ mcpServers: { demo: { command: "demo" } } }, null, 2);
+
+function fixture(t: test.TestContext) {
+	const root = mkdtempSync(join(tmpdir(), "gentle-shell-import-pi-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const source = join(root, "pi-agent");
+	const target = join(root, "gentle-agent");
+	mkdirSync(source, { recursive: true });
+	mkdirSync(target, { recursive: true });
+	return { root, source, target };
+}
+
+function seedSource(source: string) {
+	writeFileSync(join(source, "auth.json"), AUTH, { mode: 0o644 });
+	chmodSync(join(source, "auth.json"), 0o644);
+	writeFileSync(join(source, "mcp.json"), MCP);
+	chmodSync(join(source, "mcp.json"), 0o640);
+	writeFileSync(join(source, "settings.json"), `${JSON.stringify({
+		defaultProvider: "anthropic",
+		defaultModel: "claude-opus-5-5",
+		defaultThinkingLevel: "high",
+		packages: ["npm:foreign"],
+		extensions: ["./x.ts"],
+		theme: "dark",
+		npmCommand: ["npm"],
+	}, null, 2)}\n`);
+	writeFileSync(join(source, "mcp-cache.json"), "{}");
+	writeFileSync(join(source, "mcp-npx-cache.json"), "{}");
+	writeFileSync(join(source, "AGENTS.md"), "# agents\n");
+	mkdirSync(join(source, "sessions"));
+}
+
+function snapshot(dir: string) {
+	return Object.fromEntries(readdirSync(dir).sort().map((name) => {
+		const stat = statSync(join(dir, name));
+		const hash = stat.isFile() ? createHash("sha256").update(readFileSync(join(dir, name))).digest("hex") : "dir";
+		return [name, { hash, mode: stat.mode, mtimeMs: stat.mtimeMs }];
+	}));
+}
+
+function statusOf(result: ReturnType<typeof importPi>, item: string) {
+	return result.items.find((entry) => entry.item === item)?.status;
+}
+
+const modeOf = (path: string) => statSync(path).mode & 0o777;
+
+test("copies auth.json (0600) and mcp.json (source mode) only when absent in the target", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "auth.json"), "copied");
+	assert.equal(statusOf(result, "mcp.json"), "copied");
+	assert.ok(readFileSync(join(f.target, "auth.json"), "utf8") === AUTH, "auth.json bytes copied verbatim");
+	assert.ok(readFileSync(join(f.target, "mcp.json"), "utf8") === MCP);
+	if (process.platform !== "win32") {
+		assert.equal(modeOf(join(f.target, "auth.json")), 0o600);
+		assert.equal(modeOf(join(f.target, "mcp.json")), 0o640);
+	}
+});
+
+test("never overwrites a target file that already exists and is idempotent", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	writeFileSync(join(f.target, "auth.json"), "{\"mine\":true}");
+	const first = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(first, "auth.json"), "present");
+	assert.ok(readFileSync(join(f.target, "auth.json"), "utf8") === "{\"mine\":true}", "existing target auth.json kept");
+	const before = snapshot(f.target);
+	const second = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(second.failed, false);
+	assert.ok(second.items.every((entry) => entry.status !== "copied"), "a second run copies nothing");
+	assert.deepEqual(snapshot(f.target), before);
+});
+
+test("never modifies the source: content, mode and mtime stay the same", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const before = snapshot(f.source);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(snapshot(f.source), before);
+});
+
+test("never copies caches, AGENTS.md, sessions or any other file", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(readdirSync(f.target).sort(), ["auth.json", "mcp.json", "settings.json"]);
+});
+
+test("missing source files are reported as not found, not errors", (t) => {
+	const f = fixture(t);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "auth.json"), "not found");
+	assert.equal(statusOf(result, "mcp.json"), "not found");
+	assert.equal(statusOf(result, "settings.json"), "not found");
+	assert.deepEqual(readdirSync(f.target), []);
+});
+
+test("skips a symlinked or non-regular source file", { skip: process.platform === "win32" }, (t) => {
+	const f = fixture(t);
+	writeFileSync(join(f.root, "elsewhere.json"), AUTH);
+	symlinkSync(join(f.root, "elsewhere.json"), join(f.source, "auth.json"));
+	mkdirSync(join(f.source, "mcp.json"));
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(result, "auth.json"), "skipped");
+	assert.equal(statusOf(result, "mcp.json"), "skipped");
+	assert.equal(existsSync(join(f.target, "auth.json")), false);
+	assert.equal(existsSync(join(f.target, "mcp.json")), false);
+});
+
+test("settings: copies only the default provider/model/thinking keys absent in the target, preserving every target key and order", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	writeFileSync(join(f.target, "settings.json"), `${JSON.stringify({ tuiMode: "fullscreen", theme: "Gentleman-Cute", defaultModel: "kept-model", packages: ["npm:own"] }, null, 2)}\n`);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "settings.json defaultProvider"), "copied");
+	assert.equal(statusOf(result, "settings.json defaultModel"), "present");
+	assert.equal(statusOf(result, "settings.json defaultThinkingLevel"), "copied");
+	const text = readFileSync(join(f.target, "settings.json"), "utf8");
+	assert.equal(text, `${JSON.stringify({
+		tuiMode: "fullscreen", theme: "Gentleman-Cute", defaultModel: "kept-model", packages: ["npm:own"],
+		defaultProvider: "anthropic", defaultThinkingLevel: "high",
+	}, null, 2)}\n`);
+});
+
+test("settings: the target keeps its own indentation and trailing-newline style", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	writeFileSync(join(f.target, "settings.json"), `{\n\t"tuiMode": "fullscreen",\n\t"zeta": 1\n}`);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(readFileSync(join(f.target, "settings.json"), "utf8"), JSON.stringify({
+		tuiMode: "fullscreen", zeta: 1, defaultProvider: "anthropic", defaultModel: "claude-opus-5-5", defaultThinkingLevel: "high",
+	}, null, "\t"));
+});
+
+test("settings: an unreadable settings.json is reported per item while the other items still run", (t) => {
+	if (process.platform === "win32" || process.getuid?.() === 0) return t.skip("needs POSIX permissions as a non-root user");
+	const f = fixture(t);
+	seedSource(f.source);
+	const settings = join(f.target, "settings.json");
+	writeFileSync(settings, "{}\n");
+	chmodSync(settings, 0o000);
+	try {
+		const result = importPi({ source: f.source, target: f.target, dryRun: false });
+		assert.equal(statusOf(result, "auth.json"), "copied");
+		assert.equal(statusOf(result, "settings.json"), "failed");
+		assert.equal(result.failed, true);
+		assert.match(formatImportPiReport(result, { source: f.source, target: f.target, dryRun: false }).join("\n"), /settings\.json: failed/);
+	} finally {
+		chmodSync(settings, 0o600);
+	}
+});
+
+test("a destination that cannot be classified is one failed item while the other items still run", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const blocked = join(f.target, "auth.json");
+	const fs = { ...nodeImportPiFs, kind: (path: string) => {
+		if (path === blocked) throw Object.assign(new Error(`ENOTDIR: not a directory, lstat '${path}'`), { code: "ENOTDIR" });
+		return nodeImportPiFs.kind(path);
+	} };
+	for (const dryRun of [true, false]) {
+		const result = importPi({ source: f.source, target: f.target, dryRun, fs });
+		assert.equal(statusOf(result, "auth.json"), "failed", `dryRun=${dryRun}`);
+		assert.equal(statusOf(result, "mcp.json"), dryRun ? "would copy" : "copied");
+		assert.equal(result.failed, true);
+	}
+});
+
+test("settings: a missing target settings.json gets only the allowlisted keys", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(JSON.parse(readFileSync(join(f.target, "settings.json"), "utf8")), {
+		defaultProvider: "anthropic", defaultModel: "claude-opus-5-5", defaultThinkingLevel: "high",
+	});
+});
+
+test("settings: nothing to add leaves the target settings.json untouched", (t) => {
+	const f = fixture(t);
+	writeFileSync(join(f.source, "settings.json"), JSON.stringify({ packages: ["npm:x"] }));
+	writeFileSync(join(f.target, "settings.json"), "{\"tuiMode\":\"fullscreen\"}");
+	const before = snapshot(f.target);
+	importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.deepEqual(snapshot(f.target), before);
+});
+
+test("settings: malformed source or target JSON is reported and nothing is written", (t) => {
+	const f = fixture(t);
+	writeFileSync(join(f.source, "settings.json"), "{ not json");
+	const badSource = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(badSource, "settings.json"), "skipped");
+	assert.equal(badSource.failed, false);
+	assert.equal(existsSync(join(f.target, "settings.json")), false);
+
+	writeFileSync(join(f.source, "settings.json"), JSON.stringify({ defaultProvider: "anthropic" }));
+	writeFileSync(join(f.target, "settings.json"), "[1, 2]");
+	const badTarget = importPi({ source: f.source, target: f.target, dryRun: false });
+	assert.equal(statusOf(badTarget, "settings.json"), "skipped");
+	assert.equal(readFileSync(join(f.target, "settings.json"), "utf8"), "[1, 2]");
+});
+
+test("dry run reports the same plan and writes nothing, not even the target directory", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const target = join(f.root, "not-created", "agent");
+	const result = importPi({ source: f.source, target, dryRun: true });
+	assert.equal(result.failed, false);
+	assert.equal(statusOf(result, "auth.json"), "would copy");
+	assert.equal(statusOf(result, "settings.json defaultProvider"), "would copy");
+	assert.equal(existsSync(join(f.root, "not-created")), false);
+});
+
+test("a write failure is reported per item and keeps what was already copied", { skip: process.platform === "win32" }, (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	// A read-only target makes every write fail; nothing is half-written.
+	writeFileSync(join(f.target, "settings.json"), "{}");
+	chmodSync(f.target, 0o500);
+	let result;
+	try {
+		result = importPi({ source: f.source, target: f.target, dryRun: false });
+	} finally {
+		chmodSync(f.target, 0o700); // before the fixture's own cleanup
+	}
+	assert.equal(result.failed, true);
+	assert.equal(statusOf(result, "auth.json"), "failed");
+	assert.equal(statusOf(result, "settings.json defaultProvider"), "failed");
+});
+
+test("the report has one line per item and a summary, and never prints credential contents", (t) => {
+	const f = fixture(t);
+	seedSource(f.source);
+	const result = importPi({ source: f.source, target: f.target, dryRun: false });
+	const lines = formatImportPiReport(result, { source: f.source, target: f.target, dryRun: false });
+	const text = lines.join("\n");
+	assert.match(text, /auth\.json: copied \(0600\)/);
+	assert.match(text, /mcp\.json: copied/);
+	assert.match(text, /settings\.json defaultModel: copied/);
+	assert.match(text, /Imported 5 item\(s\)/);
+	assert.doesNotMatch(text, /dummy-refresh|dummy-access/);
+
+	const again = formatImportPiReport(importPi({ source: f.source, target: f.target, dryRun: true }), { source: f.source, target: f.target, dryRun: true });
+	assert.match(again.join("\n"), /auth\.json: already present, kept/);
+	assert.match(again.join("\n"), /Dry run/);
+	assert.match(again.join("\n"), /Nothing to import/);
+});

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

@@ -5,7 +5,9 @@ import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection, parseChildPackageInjection } from "../lib/child-package-injection.ts";
 import {
+	GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV,
 	MIN_PI_VERSION,
+	withLauncherPackagesExcluded,
 	MIN_SETUP_GENTLE_AI_VERSION,
 	PI_SUBCOMMANDS,
 	buildPiInvocation,
@@ -37,6 +39,7 @@ import {
 	userPiHome,
 	resolvePiRuntime,
 	restoreJsonField,
+	separateHomeHint,
 	settingsDeclareGentlePi,
 	shellQuote,
 	type PackageJsonPeerShape,
@@ -66,6 +69,20 @@ test("parseLauncherArgs returns all-false defaults for an empty argv", () => {
 	});
 });
 
+test("parseLauncherArgs reserves explicit memory recovery without consuming prior commands or escaped prompts", () => {
+	const memory = parseLauncherArgs(["memory", "migrate", "--confirm-quiescent"]);
+	assert.equal(memory.command, "memory");
+	assert.deepEqual(memory.commandArgs, ["migrate", "--confirm-quiescent"]);
+	assert.deepEqual(memory.passthrough, []);
+	for (const command of ["home", "upgrade", "self-uninstall"] as const) {
+		const parsed = parseLauncherArgs([command, "--help"]);
+		assert.equal(parsed.command, command);
+		assert.deepEqual(parsed.commandArgs, ["--help"]);
+	}
+	assert.deepEqual(parseLauncherArgs(["--", "memory"]).passthrough, ["memory"]);
+	assert.match(helpText(), /gentle-shell memory migrate --confirm-quiescent/);
+});
+
 test("parseLauncherArgs captures a --package-root value from the next argument", () => {
 	assert.equal(parseLauncherArgs(["--package-root", "/custom/root"]).packageRoot, "/custom/root");
 });
@@ -205,6 +222,40 @@ test("parseLauncherArgs treats home as a plain passthrough token when it is not
 	assert.deepEqual(parsed.passthrough, ["home"]);
 });
 
+test("parseLauncherArgs accepts home selectors ahead of home import-pi only", () => {
+	const link = parseLauncherArgs(["--link", "home", "import-pi"]);
+	assert.equal(link.link, true);
+	assert.equal(link.command, "home");
+	assert.deepEqual(link.commandArgs, ["import-pi"]);
+	assert.deepEqual(link.passthrough, []);
+	const path = parseLauncherArgs(["--home", "/x", "home", "import-pi", "--dry-run"]);
+	assert.equal(path.home, "/x");
+	assert.equal(path.command, "home");
+	assert.deepEqual(path.commandArgs, ["import-pi", "--dry-run"]);
+	const first = parseLauncherArgs(["home", "import-pi", "--dry-run"]);
+	assert.equal(first.command, "home");
+	assert.deepEqual(first.commandArgs, ["import-pi", "--dry-run"]);
+	// Anything else after a selector stays pi's, as before.
+	assert.deepEqual(parseLauncherArgs(["--link", "home", "link"]).passthrough, ["home", "link"]);
+	assert.deepEqual(parseLauncherArgs(["-p", "home", "import-pi"]).passthrough, ["-p", "home", "import-pi"]);
+});
+
+test("help text documents gentle-shell home import-pi", () => {
+	const text = helpText();
+	assert.ok(text.includes("       gentle-shell [home selectors] home import-pi [--dry-run]"));
+	assert.match(text, /import-pi\s+Copy your pi sign-ins \(auth\.json\) and MCP servers \(mcp\.json\)/);
+});
+
+test("separateHomeHint mentions home import-pi only when the user's pi home has sign-ins", () => {
+	const isolated: ResolvedHome = { mode: "isolated", dir: "/h/.gentle-shell/agent", source: "default" };
+	const without = separateHomeHint(isolated, { piSignIns: false });
+	assert.equal(without, "gentle-shell: using a separate home at /h/.gentle-shell/agent. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.");
+	const withSignIns = separateHomeHint(isolated, { piSignIns: true });
+	assert.match(withSignIns, /Run 'gentle-shell --link' to reuse your pi sign-ins and chats, or 'gentle-shell home import-pi' to copy your sign-ins and MCP servers into this home\.$/);
+	const path = separateHomeHint({ mode: "path", dir: "/custom", source: "flag" }, { piSignIns: true });
+	assert.match(path, /'gentle-shell --home \/custom home import-pi'/);
+});
+
 // --- setup subcommand ----------------------------------------------------
 //
 // Unlike `home`, `setup` is not restricted to argv[0]: it accepts the home
@@ -293,6 +344,19 @@ test("parseLauncherArgs recognises a pi subcommand as the first token after --",
 	assert.deepEqual(parsed.passthrough, ["install", "npm:x"]);
 });
 
+test("parseLauncherArgs keeps a separator that follows a pi subcommand (#2140)", () => {
+	const parsed = parseLauncherArgs(["mcp", "add", "demo", "--", "npx", "demo-server"]);
+	assert.equal(parsed.piSubcommand, "mcp");
+	assert.deepEqual(parsed.passthrough, ["mcp", "add", "demo", "--", "npx", "demo-server"]);
+});
+
+test("parseLauncherArgs still consumes a later separator when no pi subcommand started", () => {
+	const parsed = parseLauncherArgs(["hello", "--", "--link"]);
+	assert.equal(parsed.piSubcommand, undefined);
+	assert.equal(parsed.link, false);
+	assert.deepEqual(parsed.passthrough, ["hello", "--link"]);
+});
+
 test("parseLauncherArgs errors when --link is combined with --isolated", () => {
 	const parsed = parseLauncherArgs(["--link", "--isolated"]);
 	assert.match(parsed.error ?? "", /--link/);
@@ -2032,3 +2096,18 @@ test("the isolated-home bootstrap creates ~/.gentle-shell as 0700 under umask 00
 		rmSync(root, { recursive: true, force: true });
 	}
 });
+
+// #2143: Gentle AI installs npm:gentle-pi into the home only for the launcher
+// to remove it again; a Gentle AI with package exclusion (gentle-ai#5503)
+// skips it, and an older one ignores the variable.
+test("withLauncherPackagesExcluded asks Gentle AI to skip npm:gentle-pi, keeping a caller's own exclusions", () => {
+	assert.equal(GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV, "GENTLE_AI_PI_EXCLUDE_PACKAGES");
+	assert.equal(withLauncherPackagesExcluded({ PATH: "/bin" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:gentle-pi");
+	assert.equal(withLauncherPackagesExcluded({ GENTLE_AI_PI_EXCLUDE_PACKAGES: "" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:gentle-pi");
+	assert.equal(withLauncherPackagesExcluded({ GENTLE_AI_PI_EXCLUDE_PACKAGES: "npm:pi-btw" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:pi-btw,npm:gentle-pi");
+	assert.equal(withLauncherPackagesExcluded({ GENTLE_AI_PI_EXCLUDE_PACKAGES: "npm:gentle-pi, npm:pi-btw" }).GENTLE_AI_PI_EXCLUDE_PACKAGES, "npm:gentle-pi,npm:pi-btw");
+	const input = { PATH: "/bin" };
+	assert.equal(withLauncherPackagesExcluded(input).PATH, "/bin");
+	assert.deepEqual(input, { PATH: "/bin" }, "the caller's env is not mutated");
+});
+

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

@@ -976,3 +976,33 @@ test("bundled on Windows: the user Path entry goes first, the running node.exe,
 		assert.equal(existsSync(join(w.shared.agent, "auth.json")), true);
 	} finally { w.cleanup(); }
 });
+
+// #2201: the standalone isolated home keeps its config in ~/.gentle-shell/gentle-ai.
+test("Gentle Shell's own config folder next to the isolated home is removed; the shared config home keeps its rule", async () => {
+	const w = world();
+	try {
+		const own = join(w.shell, "gentle-ai");
+		write(join(own, "profiles.json"));
+		write(join(own, "persona.json"));
+		assert.equal(await w.uninstall(["--dry-run"]), 0);
+		assert.ok(section(w.out, "Remove Gentle Shell data:").some((line) => line.includes(own)), w.out.join("\n"));
+		assert.equal(await w.uninstall(["--yes"]), 0);
+		assert.equal(existsSync(own), false);
+		assert.equal(existsSync(w.shell), false);
+		for (const name of ["profiles.json", "persona.json"]) assert.equal(existsSync(join(w.config, name)), true, name);
+	} finally { w.cleanup(); }
+});
+
+test("the gentle-ai folder next to a custom GENTLE_SHELL_HOME is kept: it may not be Gentle Shell's", async () => {
+	const w = world();
+	try {
+		const custom = join(w.root, "elsewhere", "agent");
+		const sibling = join(w.root, "elsewhere", "gentle-ai");
+		write(join(custom, ".gentle-shell-home"));
+		write(join(sibling, "notes.json"));
+		assert.equal(await w.uninstall(["--yes"], { env: { GENTLE_SHELL_HOME: custom } }), 0);
+		assert.equal(existsSync(custom), false);
+		assert.equal(existsSync(join(sibling, "notes.json")), true);
+		assert.ok(section(w.out, "Kept:").some((line) => line.includes(sibling)), w.out.join("\n"));
+	} finally { w.cleanup(); }
+});