gentle-pi 4.2.0 → 4.3.0

package/lib/gentle-shell-import-pi.ts

@@ -0,0 +1,233 @@
+import { chmodSync, closeSync, linkSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { detectJsonFormatting } from "./gentle-shell-launcher.ts";
+
+// `gentle-shell home import-pi`: a one-time, opt-in copy of the user's pi
+// sign-ins and MCP servers into a separate Gentle Shell home, as an
+// alternative to --link. Only the files and settings keys below are read;
+// packages, extensions, caches, AGENTS.md and sessions are never copied, so
+// the target home keeps its own provisioning. Nothing is ever overwritten and
+// the source is only read.
+
+// auth.json holds OAuth tokens and API keys: always private in the copy.
+const IMPORTED_FILES: readonly { name: string; mode?: number }[] = [
+	{ name: "auth.json", mode: 0o600 },
+	{ name: "mcp.json" },
+];
+
+// Pi 1.2.0's own settings for the default model (SettingsManager
+// get/setDefaultProvider, DefaultModel, DefaultThinkingLevel).
+export const IMPORTED_SETTINGS_KEYS: readonly string[] = ["defaultProvider", "defaultModel", "defaultThinkingLevel"];
+
+export interface ImportPiFs {
+	// lstat: a symbolic link is "other", never followed.
+	kind: (path: string) => "missing" | "file" | "dir" | "other";
+	mode: (path: string) => number;
+	readText: (path: string) => string;
+	// Creates `to` with exactly `mode`; throws when it already exists.
+	copyNew: (from: string, to: string, mode: number) => void;
+	// Temp file next to `path`, then a rename onto it.
+	writeAtomic: (path: string, text: string) => void;
+}
+
+export type ImportPiStatus = "copied" | "would copy" | "present" | "not found" | "skipped" | "failed";
+
+export interface ImportPiItem {
+	item: string;
+	status: ImportPiStatus;
+	// The copy's mode, or why the item was skipped or failed. Never file content.
+	detail?: string;
+}
+
+export interface ImportPiResult {
+	items: ImportPiItem[];
+	failed: boolean;
+}
+
+function tempPathFor(path: string): string {
+	return join(dirname(path), `.${basename(path)}.gentle-shell-${process.pid}.tmp`);
+}
+
+function removeQuietly(path: string): void {
+	try {
+		unlinkSync(path);
+	} catch {
+		// Nothing left to clean up.
+	}
+}
+
+function writeTemp(path: string, data: string | Buffer, mode: number): string {
+	const temp = tempPathFor(path);
+	const fd = openSync(temp, "wx", mode);
+	try {
+		try {
+			writeFileSync(fd, data);
+		} finally {
+			closeSync(fd);
+		}
+		chmodSync(temp, mode); // the umask must not change the mode
+	} catch (error) {
+		// A partial copy may hold credentials: never leave it behind.
+		removeQuietly(temp);
+		throw error;
+	}
+	return temp;
+}
+
+export const nodeImportPiFs: ImportPiFs = {
+	kind: (path) => {
+		try {
+			const stat = lstatSync(path);
+			if (stat.isSymbolicLink()) return "other";
+			return stat.isFile() ? "file" : stat.isDirectory() ? "dir" : "other";
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+			throw error;
+		}
+	},
+	mode: (path) => lstatSync(path).mode & 0o777,
+	readText: (path) => readFileSync(path, "utf8"),
+	copyNew: (from, to, mode) => {
+		const temp = writeTemp(to, readFileSync(from), mode);
+		try {
+			linkSync(temp, to); // EEXIST instead of replacing a file that appeared meanwhile
+		} finally {
+			removeQuietly(temp);
+		}
+	},
+	writeAtomic: (path, text) => {
+		const mode = lstatSync(path, { throwIfNoEntry: false })?.mode;
+		const temp = writeTemp(path, text, mode === undefined ? 0o600 : mode & 0o777);
+		try {
+			renameSync(temp, path);
+		} catch (error) {
+			removeQuietly(temp);
+			throw error;
+		}
+	},
+};
+
+function reason(error: unknown): string {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" ? code : error instanceof Error ? error.message : String(error);
+}
+
+function parseObject(text: string): Record<string, unknown> | undefined {
+	try {
+		const value: unknown = JSON.parse(text.replace(/^\uFEFF/, ""));
+		return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function importFile(name: string, mode: number | undefined, input: { source: string; target: string; dryRun: boolean; fs: ImportPiFs }): ImportPiItem {
+	const { fs } = input;
+	const from = join(input.source, name);
+	const to = join(input.target, name);
+	// Classification can throw too (ENOTDIR under a file): one failed item, never an aborted report.
+	try {
+		const kind = fs.kind(from);
+		if (kind === "missing") return { item: name, status: "not found" };
+		if (kind !== "file") return { item: name, status: "skipped", detail: "not a regular file" };
+		if (fs.kind(to) !== "missing") return { item: name, status: "present" };
+		const copyMode = mode ?? fs.mode(from);
+		const detail = `${copyMode.toString(8).padStart(4, "0")}`;
+		if (input.dryRun) return { item: name, status: "would copy", detail };
+		fs.copyNew(from, to, copyMode);
+		return { item: name, status: "copied", detail };
+	} catch (error) {
+		return { item: name, status: "failed", detail: reason(error) };
+	}
+}
+
+function importSettings(input: { source: string; target: string; dryRun: boolean; fs: ImportPiFs }): ImportPiItem[] {
+	try {
+		return planAndWriteSettings(input);
+	} catch (error) {
+		// An unreadable settings.json stays one failed item, never an aborted report.
+		return [{ item: "settings.json", status: "failed", detail: reason(error) }];
+	}
+}
+
+function planAndWriteSettings(input: { source: string; target: string; dryRun: boolean; fs: ImportPiFs }): ImportPiItem[] {
+	const { fs } = input;
+	const from = join(input.source, "settings.json");
+	const to = join(input.target, "settings.json");
+	const sourceKind = fs.kind(from);
+	if (sourceKind === "missing") return [{ item: "settings.json", status: "not found" }];
+	if (sourceKind !== "file") return [{ item: "settings.json", status: "skipped", detail: "not a regular file" }];
+	const source = parseObject(fs.readText(from));
+	if (source === undefined) return [{ item: "settings.json", status: "skipped", detail: `${from} is not a JSON object` }];
+	const targetKind = fs.kind(to);
+	if (targetKind !== "missing" && targetKind !== "file") return [{ item: "settings.json", status: "skipped", detail: `${to} is not a regular file` }];
+	const targetText = targetKind === "missing" ? undefined : fs.readText(to);
+	const target = targetText === undefined ? {} : parseObject(targetText);
+	if (target === undefined) return [{ item: "settings.json", status: "skipped", detail: `${to} is not a JSON object` }];
+
+	const items: ImportPiItem[] = [];
+	const added: Record<string, unknown> = {};
+	for (const key of IMPORTED_SETTINGS_KEYS) {
+		const item = `settings.json ${key}`;
+		if (!Object.hasOwn(source, key)) items.push({ item, status: "not found" });
+		else if (Object.hasOwn(target, key)) items.push({ item, status: "present" });
+		else if (typeof source[key] !== "string") items.push({ item, status: "skipped", detail: "not a string" });
+		else {
+			added[key] = source[key];
+			items.push({ item, status: input.dryRun ? "would copy" : "copied" });
+		}
+	}
+	if (input.dryRun || Object.keys(added).length === 0) return items;
+	try {
+		// Keep the target's own indentation and trailing-newline style.
+		const style = targetText === undefined ? { indent: undefined, trailingNewline: true } : detectJsonFormatting(targetText);
+		const body = JSON.stringify({ ...target, ...added }, null, style.indent ?? 2);
+		fs.writeAtomic(to, style.trailingNewline ? `${body}\n` : body);
+		return items;
+	} catch (error) {
+		const detail = reason(error);
+		return items.map((entry) => (entry.status === "copied" ? { ...entry, status: "failed", detail } : entry));
+	}
+}
+
+// Copies what the target lacks. A dry run reads the same files and writes
+// nothing. The caller has already made sure `target` is a home this launcher
+// owns (and exists, unless this is a dry run).
+export function importPi(input: { source: string; target: string; dryRun: boolean; fs?: ImportPiFs }): ImportPiResult {
+	const options = { ...input, fs: input.fs ?? nodeImportPiFs };
+	const items = IMPORTED_FILES.map((file) => importFile(file.name, file.mode, options));
+	items.push(...importSettings(options));
+	return { items, failed: items.some((item) => item.status === "failed") };
+}
+
+function describe(item: ImportPiItem): string {
+	switch (item.status) {
+		case "copied":
+		case "would copy":
+			return item.detail !== undefined && item.item === "auth.json" ? `${item.status} (${item.detail})` : item.status;
+		case "present":
+			return "already present, kept";
+		case "not found":
+			return "not found";
+		case "skipped":
+			return `skipped: ${item.detail}`;
+		case "failed":
+			return `failed: ${item.detail}`;
+	}
+}
+
+export function formatImportPiReport(result: ImportPiResult, context: { source: string; target: string; dryRun: boolean }): string[] {
+	const lines = [
+		context.dryRun
+			? `Dry run: would import from ${context.source} into ${context.target} (nothing is written)`
+			: `Importing from ${context.source} into ${context.target}`,
+	];
+	for (const item of result.items) lines.push(`  ${item.item}: ${describe(item)}`);
+	const count = (...statuses: ImportPiStatus[]) => result.items.filter((item) => statuses.includes(item.status)).length;
+	const imported = count("copied", "would copy");
+	const rest = `${count("present")} already present, ${count("not found")} not found, ${count("skipped")} skipped`;
+	if (result.failed) lines.push(`Import failed for ${count("failed")} item(s); ${count("copied")} copied and kept. ${rest}.`);
+	else if (imported === 0) lines.push(`Nothing to import: ${rest}.`);
+	else lines.push(`${context.dryRun ? "Would import" : "Imported"} ${imported} item(s); ${rest}.`);
+	return lines;
+}

package/lib/gentle-shell-launcher.ts

@@ -1,16 +1,17 @@
-import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection, type ChildPackageInjection } from "./child-package-injection.ts";
+import { GENTLE_SHELL_CONFIG_HOME_ENV } from "./gentle-shell-bundled.ts";
 
 // The gentle-shell launcher: pure, side-effect-free functions over injected
 // env/fs/exec. `bin/gentle-shell.mjs` (T2) wires these into the real process,
 // filesystem and child process so this module stays fully unit-testable.
 
-export type LauncherCommand = "home" | "setup" | "upgrade" | "self-uninstall";
+export type LauncherCommand = "home" | "setup" | "upgrade" | "self-uninstall" | "memory";
 
 // pi's own package-management subcommands (see pi's cli/args.ts printHelp
 // "Commands" list): each is dispatched by pi itself, before pi's own flag
 // parsing, purely on argv[0]. `uninstall` is pi's alias for `remove`.
-export const PI_SUBCOMMANDS = ["install", "remove", "uninstall", "update", "list", "config", "auth"] as const;
+export const PI_SUBCOMMANDS = ["install", "remove", "uninstall", "update", "list", "config", "auth", "mcp"] as const;
 
 export type PiSubcommand = (typeof PI_SUBCOMMANDS)[number];
 
@@ -41,7 +42,7 @@ export interface ParsedLauncherArgs {
 // untouched as commandArgs — T2 owns interpreting `home link|isolated|<path>`.
 // `self-uninstall` is not `uninstall`, which stays pi's own alias for `remove`.
 export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
-	if (argv[0] === "home" || argv[0] === "upgrade" || argv[0] === "self-uninstall") {
+	if (argv[0] === "home" || argv[0] === "upgrade" || argv[0] === "self-uninstall" || argv[0] === "memory") {
 		return {
 			link: false,
 			isolated: false,
@@ -76,6 +77,9 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 			if (passthrough.length === 0 && rest.length > 0 && isPiSubcommand(rest[0])) {
 				piSubcommand = rest[0];
 			}
+			// After a pi subcommand the separator belongs to it, e.g.
+			// `mcp add <server> -- <command>`; only a leading one is the launcher's.
+			if (piSubcommand !== undefined && passthrough.length > 0) passthrough.push(arg);
 			passthrough.push(...rest);
 			break;
 		}
@@ -147,6 +151,14 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 			commandArgs = argv.slice(i + 1);
 			break;
 		}
+		// `home import-pi` likewise takes the home selectors ahead of it, so it
+		// imports into the home they resolve to; any other `home` after a
+		// selector stays pi's.
+		if (arg === "home" && argv[i + 1] === "import-pi" && command === undefined && passthrough.length === 0) {
+			command = "home";
+			commandArgs = argv.slice(i + 1);
+			break;
+		}
 		if (passthrough.length === 0 && isPiSubcommand(arg)) {
 			piSubcommand = arg;
 		}
@@ -211,6 +223,77 @@ export function isolatedDir(env: Record<string, string | undefined>, homedir: st
 	return env.GENTLE_SHELL_HOME || join(homedir, ".gentle-shell", "agent");
 }
 
+// #2201: the isolated home keeps Gentle Shell's config in a gentle-ai folder
+// next to its agent dir (~/.gentle-shell/gentle-ai by default), given to Pi as
+// GENTLE_SHELL_CONFIG_HOME_ENV. `--link` and a custom `--home` keep the shared
+// ~/.pi/gentle-ai: undefined for them.
+export function standaloneConfigHome(home: ResolvedHome): string | undefined {
+	if (home.mode !== "isolated") return undefined;
+	const dir = resolvePath(home.dir);
+	const parent = dirname(dir);
+	// Only inside a .gentle-shell folder is the sibling Gentle Shell's own: next
+	// to a custom GENTLE_SHELL_HOME (~/myagent) it would adopt ~/gentle-ai, which
+	// may be anyone's, so such homes keep the shared config home.
+	return basename(dir) === "agent" && basename(parent) === ".gentle-shell" ? join(parent, "gentle-ai") : undefined;
+}
+
+// The filesystem behind migrateStandaloneConfig; bin/gentle-shell.mjs wires the real one.
+export interface ConfigMigrationFs {
+	// lstat: a symbolic link is "other", never followed.
+	kind: (path: string) => "missing" | "dir" | "file" | "other";
+	// The entry names of a directory (following a linked directory); throws when unreadable.
+	list: (path: string) => string[];
+	// mkdir -p with mode 0700; throws on failure.
+	mkdirPrivate: (path: string) => void;
+	// Copies a regular file, never overwriting `to`; throws on failure.
+	copyNew: (from: string, to: string) => void;
+}
+
+// Install-level main-channel state stays in ~/.pi/gentle-ai: the installer and
+// `gentle-shell upgrade` write it outside any session (gentleAiDevBinaryRegistrationPath).
+const UNMIGRATED_CONFIG_FILES = new Set(["dev-binary.json", "channel.json"]);
+
+// #2201: the first isolated launch after the move keeps the user's settings.
+// Only when `target` does not exist yet: it is created (0700), and the regular
+// files of `source` are copied into it, never overwriting and never changing
+// `source`, which stays for Pi; symbolic links, subdirectories and the
+// main-channel files are skipped. Once the folder exists this does nothing, so
+// it is a one-time snapshot. A failure is reported in `lines`, never thrown:
+// it never blocks the launch.
+export function migrateStandaloneConfig(input: { source: string; target: string; fs: ConfigMigrationFs }): { lines: string[] } {
+	const { source, target, fs } = input;
+	if (fs.kind(target) !== "missing") return { lines: [] };
+	const reason = (error: unknown) => (error instanceof Error ? error.message : String(error));
+	try {
+		fs.mkdirPrivate(target);
+	} catch (error) {
+		return { lines: [`gentle-shell: could not create ${target} for your Gentle Shell settings (${reason(error)}); continuing`] };
+	}
+	if (fs.kind(source) === "missing") return { lines: [] };
+	let names: string[];
+	try {
+		names = fs.list(source).sort();
+	} catch (error) {
+		return { lines: [`gentle-shell: could not copy your settings from ${source} to ${target} (${reason(error)}); continuing`] };
+	}
+	const copied: string[] = [];
+	const failed: string[] = [];
+	for (const name of names) {
+		if (UNMIGRATED_CONFIG_FILES.has(name) || fs.kind(join(source, name)) !== "file") continue;
+		try {
+			fs.copyNew(join(source, name), join(target, name));
+			copied.push(name);
+		} catch (error) {
+			failed.push(`${name}: ${reason(error)}`);
+		}
+	}
+	if (failed.length > 0) {
+		return { lines: [`gentle-shell: could not copy ${failed.join("; ")} from ${source} to ${target}; continuing with ${copied.length} copied file(s)`] };
+	}
+	if (copied.length === 0) return { lines: [] };
+	return { lines: [`gentle-shell: copied ${copied.length} settings file(s) from ${source} to ${target}, Gentle Shell's own config folder from now on (one-time copy; ${source} stays for Pi)`] };
+}
+
 export function resolveHome(input: ResolveHomeInput): ResolvedHome {
 	const { args, env, homedir, config } = input;
 
@@ -241,6 +324,15 @@ export function homeSelectorFlags(home: ResolvedHome): string[] {
 	return [];
 }
 
+// The first-run line of a separate home. `home import-pi` is offered only
+// when the user's pi home has sign-ins (auth.json) to copy.
+export function separateHomeHint(home: ResolvedHome, input: { piSignIns: boolean }): string {
+	const base = `gentle-shell: using a separate home at ${home.dir}. Run 'gentle-shell --link' to reuse your pi sign-ins and chats`;
+	if (!input.piSignIns) return `${base}.`;
+	const command = ["gentle-shell", ...homeSelectorFlags(home).map(shellQuote), "home", "import-pi"].join(" ");
+	return `${base}, or '${command}' to copy your sign-ins and MCP servers into this home.`;
+}
+
 export function launcherConfigPath(homedir: string): string {
 	return join(homedir, ".gentle-shell", "config.json");
 }
@@ -575,6 +667,20 @@ const POST_INSTALL_REMOVAL_PACKAGES: readonly { readonly name: string; readonly
 // bin/gentle-shell.mjs.
 export const POST_INSTALL_REMOVAL_SOURCES: readonly string[] = POST_INSTALL_REMOVAL_PACKAGES.map((entry) => entry.source);
 
+// #2143: a Gentle AI with package exclusion (gentle-ai#5503) skips these
+// managed Pi packages instead of installing them only for the post-install
+// removal above to delete them. An older Gentle AI ignores the variable (a flag
+// would be rejected), so the removal stays as the fallback. Only sources Gentle
+// AI manages belong here: it rejects any other value.
+export const GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV = "GENTLE_AI_PI_EXCLUDE_PACKAGES";
+const LAUNCHER_EXCLUDED_PI_PACKAGES: readonly string[] = ["npm:gentle-pi"];
+
+export function withLauncherPackagesExcluded(env: Record<string, string | undefined>): Record<string, string | undefined> {
+	const own = (env[GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV] ?? "").split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	const merged = [...own, ...LAUNCHER_EXCLUDED_PI_PACKAGES.filter((source) => !own.includes(source))];
+	return { ...env, [GENTLE_AI_PI_EXCLUDE_PACKAGES_ENV]: merged.join(",") };
+}
+
 // Scans a settings.json `packages` list (same string/object-source parsing
 // as settingsDeclareGentlePi/findGentlePiDeclaration above) for any entry
 // whose npm package name matches POST_INSTALL_REMOVAL_PACKAGES, at any
@@ -875,10 +981,13 @@ export interface BuildPiInvocationInput {
 	passthrough: string[];
 	// Set when parseLauncherArgs recognised passthrough[0] as one of
 	// PI_SUBCOMMANDS. pi dispatches install/remove/uninstall/update/list/
-	// config/auth on argv[0] before its own flag parsing, so none of the
+	// config/auth/mcp on argv[0] before its own flag parsing, so none of the
 	// gentle-pi extension injection below may precede it.
 	piSubcommand?: PiSubcommand;
 	baseEnv: Record<string, string | undefined>;
+	// A bundled launch: its gentle-pi keeps its config in the prefix, so Pi gets
+	// no standalone config marker (standaloneConfigHome).
+	bundled?: boolean;
 	// The OS home behind userPiHome's conventional ~/.pi/agent fallback.
 	homedir: string;
 	// The directory pi is spawned in, which pi resolves a relative -e path
@@ -896,7 +1005,7 @@ export interface PiInvocation {
 
 // Four cases, checked in this order — `piSubcommand` first, then `takeOver`:
 //   - piSubcommand: pi dispatches install/remove/uninstall/update/list/
-//     config/auth on argv[0] before it even parses flags, so any injected
+//     config/auth/mcp on argv[0] before it even parses flags, so any injected
 //     -e flag ahead of it stops pi from
 //     recognising its subcommand at all — this is exactly the observed
 //     2026-09-22 bug where `gentle-shell install npm:x` opened an
@@ -977,6 +1086,12 @@ export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 		GENTLE_PI_AGENT_HOME: input.home.dir,
 		[USER_PI_HOME_ENV]: userPiHome(input.baseEnv, input.homedir),
 	};
+	// #2201: only the standalone isolated home gets its own config folder; any
+	// other launch removes an inherited marker, so a nested `--link` launch from
+	// an isolated session reads ~/.pi/gentle-ai again.
+	const configHome = input.bundled === true ? undefined : standaloneConfigHome(input.home);
+	if (configHome === undefined) delete env[GENTLE_SHELL_CONFIG_HOME_ENV];
+	else env[GENTLE_SHELL_CONFIG_HOME_ENV] = configHome;
 	if (childInjection === undefined) delete env[CHILD_PACKAGE_INJECTION_ENV];
 	else env[CHILD_PACKAGE_INJECTION_ENV] = encodeChildPackageInjection(childInjection);
 
@@ -1052,7 +1167,7 @@ export function planSpawn(input: PlanSpawnInput): SpawnPlan {
 // formatting as practical instead of imposing its own. `indent` is
 // `undefined` for compact (no-whitespace) JSON, matching what
 // `JSON.stringify(value)` (no third argument) produces.
-function detectJsonFormatting(text: string): { indent: string | undefined; trailingNewline: boolean } {
+export function detectJsonFormatting(text: string): { indent: string | undefined; trailingNewline: boolean } {
 	const match = text.match(/\{\r?\n([ \t]+)/);
 	return { indent: match ? match[1] : undefined, trailingNewline: text.endsWith("\n") };
 }
@@ -1174,9 +1289,11 @@ export function helpText(): string {
 	return [
 		"Usage: gentle-shell [options] [-- pi-args...]",
 		"       gentle-shell home [link|isolated|<path>]",
+		"       gentle-shell [home selectors] home import-pi [--dry-run]",
 		"       gentle-shell [home selectors] setup [--dry-run]",
 		"       gentle-shell upgrade [--channel release|main]",
 		"       gentle-shell upgrade --rollback",
+		"       gentle-shell memory migrate --confirm-quiescent",
 		"       gentle-shell self-uninstall [--dry-run] [--yes] [--include-shared]",
 		"",
 		"Opens pi with the Gentle Shell package loaded, without touching your",
@@ -1184,7 +1301,8 @@ export function helpText(): string {
 		"",
 		"Options:",
 		"  --link           Use your existing pi agent home (never edits its settings.json).",
-		"  --isolated       Use the dedicated ~/.gentle-shell/agent home (default).",
+		"  --isolated       Use the dedicated ~/.gentle-shell/agent home (default), with its own",
+		"                   settings in ~/.gentle-shell/gentle-ai (copied once from ~/.pi/gentle-ai).",
 		"  --home <path>    Use a custom agent home directory.",
 		"  --package-root <dir>  Force this directory as the gentle-pi package to load, taking over",
 		"                        from any conflicting package the target settings.json already declares.",
@@ -1193,6 +1311,11 @@ export function helpText(): string {
 		"",
 		"Commands:",
 		"  home             Print or persist the effective home mode (link, isolated, or a path).",
+		"  home import-pi   Copy your pi sign-ins (auth.json) and MCP servers (mcp.json) into the",
+		"                   resolved separate home, plus your default provider, model and thinking",
+		"                   level when it has none. Never overwrites a file or setting, never copies",
+		"                   packages, extensions or caches, and never changes your pi home.",
+		"                   --dry-run only shows the plan. Refuses --link (nothing to import).",
 		"  setup            Provision the resolved home with the gentle-ai companion packages",
 		"                   (runs the package-local gentle-ai 'install --agent pi --scope global').",
 		"                   Accepts --dry-run, forwarded to gentle-ai. Accepts a home selector",
@@ -1204,9 +1327,15 @@ export function helpText(): string {
 		"                   installer's own Node, pnpm and Pi) follows the release channel only:",
 		"                   it installs the new version beside the current one, verifies it, then",
 		"                   switches; --rollback switches back to the previous kept version.",
+		"  memory migrate   Explicit bundled-store recovery using the verified core's migrate-copy.",
+		"                   Requires --confirm-quiescent: stop ALL Engram clients first. Keeps the",
+		"                   original directory as a backup; never runs automatically on upgrade.",
+		"                   Requires a bundled core release supporting migrate-copy; older cores",
+		"                   fail closed without changing the source or its provenance.",
 		"  self-uninstall   Remove Gentle Shell: its own data, the isolated home and the gentle-pi",
-		"                   package. Shows the plan first and asks before removing (--yes skips",
-		"                   the question). The shared ~/.pi/gentle-ai configuration is kept unless",
+		"                   package, with its settings in ~/.gentle-shell/gentle-ai. Shows the plan",
+		"                   first and asks before removing (--yes skips the question). The shared",
+		"                   ~/.pi/gentle-ai configuration is kept unless",
 		"                   you accept or pass --include-shared; --dry-run only shows the plan.",
 		"                   Never touches your pi home or custom --home homes.",
 		"",
@@ -1219,6 +1348,8 @@ export function helpText(): string {
 		"                                   runs 'gentle-shell upgrade' instead of updating Pi.",
 		"  gentle-shell config              Run pi's own 'config' against the resolved home.",
 		"  gentle-shell auth <command>      Run pi's own 'auth' against the resolved home.",
+		"  gentle-shell mcp <command>       Run pi's own 'mcp' (add, list, login, logout) against the",
+		"                                   resolved home, e.g. gentle-shell mcp add <name> -- <command>.",
 		"  'gentle-shell uninstall <source>' is pi's own alias for 'remove'; to remove Gentle",
 		"  Shell itself, use 'gentle-shell self-uninstall'.",
 		"  These run pi's own commands, forwarded verbatim, against the --isolated home",
@@ -1233,7 +1364,10 @@ export function helpText(): string {
 		"",
 		"Environment variables:",
 		"  GENTLE_SHELL_PI       Path to the pi executable to run.",
-		"  GENTLE_SHELL_HOME     Directory for the isolated home (default: ~/.gentle-shell/agent).",
+		"  GENTLE_SHELL_HOME     Directory for the isolated home (default: ~/.gentle-shell/agent);",
+		"                        inside a .gentle-shell folder, its settings live in the gentle-ai",
+		"                        folder next to it; elsewhere they stay in ~/.pi/gentle-ai.",
+		"  GENTLE_PI_CONFIG_HOME Gentle Shell settings folder for every home, overriding the above.",
 		"  PI_CODING_AGENT_DIR   Directory for the --link home, shared with pi itself.",
 		"",
 		"Every other argument is forwarded to pi unchanged.",

package/lib/gentle-shell-uninstall.ts

@@ -263,6 +263,14 @@ async function planSelfUninstall(input: SelfUninstallInput, configHome: string,
 		{ path: gentleAiState, label: "Gentle AI's state", inside: true },
 	];
 	const defaultConfigHome = canonical(join(homedir, ".pi", "gentle-ai"));
+	// #2201: the standalone launcher keeps the isolated home's config in a
+	// gentle-ai folder next to it (standaloneConfigHome). Next to the default
+	// home it lies inside ~/.gentle-shell and is Gentle Shell's by location;
+	// next to a GENTLE_SHELL_HOME it may be anyone's, so it is only listed.
+	// When GENTLE_PI_CONFIG_HOME names it, the config home's rules apply instead.
+	const defaultHome = resolve(isolated) === resolve(join(homedir, ".gentle-shell", "agent"));
+	const ownConfig = join(dirname(isolated), "gentle-ai");
+	const ownConfigSeparate = comparable(canonical(ownConfig), platform) !== comparable(canonical(configHome), platform);
 	const candidates = [
 		{
 			who: env.GENTLE_SHELL_HOME ? `GENTLE_SHELL_HOME points at ${isolated}` : `The isolated home ${isolated}`,
@@ -278,6 +286,12 @@ async function planSelfUninstall(input: SelfUninstallInput, configHome: string,
 			allowedInsidePi: defaultConfigHome,
 		},
 		{ who: `The launcher folder ${shellDirectory}`, path: shellDirectory, guards, allowedInsidePi: undefined },
+		...(defaultHome && ownConfigSeparate ? [{
+			who: `Gentle Shell's config folder ${ownConfig}`,
+			path: ownConfig,
+			guards: [...guards, { path: configHome, label: "the Gentle AI config home", inside: true }],
+			allowedInsidePi: undefined,
+		}] : []),
 	];
 	for (const candidate of candidates) {
 		const real = canonical(candidate.path);
@@ -312,11 +326,14 @@ async function planSelfUninstall(input: SelfUninstallInput, configHome: string,
 
 	// The default isolated home is Gentle Shell's by location; a GENTLE_SHELL_HOME
 	// directory only with the launcher's ownership marker or setup record.
-	const defaultHome = resolve(isolated) === resolve(join(homedir, ".gentle-shell", "agent"));
 	const owned = defaultHome || inspect(join(isolated, HOME_OWNERSHIP_MARKER), "file") === "ok"
 		|| provisionedEntry(launcherConfig, isolatedReal) !== undefined;
 	if (owned || inspect(isolated, "dir") !== "ok") consider({ path: isolated, label: "isolated home: its sign-ins, chats and settings", kind: "dir" });
 	else plan.kept.push(`${isolated}: not created by Gentle Shell (no ${HOME_OWNERSHIP_MARKER} marker or setup record)`);
+	if (defaultHome && ownConfigSeparate) consider({ path: ownConfig, label: "Gentle Shell's own configuration: profiles, banner and other preferences", kind: "dir" });
+	else if (ownConfigSeparate && inspect(ownConfig, "dir") !== "missing") {
+		plan.kept.push(`${ownConfig}: next to GENTLE_SHELL_HOME, so it may not be Gentle Shell's; remove it yourself if it holds only Gentle Shell settings`);
+	}
 	consider({ path: configPath, label: "launcher settings", kind: "file" });
 
 	for (const name of SHARED_CONFIG_FILES) {

package/lib/herdr-activity.ts

@@ -111,6 +111,30 @@ export function activitySummary(tasks: unknown, columns = FALLBACK_COLUMNS): str
 	return `${first}\n  ${second}${overflow ? "…" : ""}`;
 }
 
+/** Herdr pane environment: HERDR_ENV=1 plus nonblank pane and socket variables. */
+export function herdrDetected(env: NodeJS.ProcessEnv): boolean {
+	return env.HERDR_ENV === "1" && !!env.HERDR_PANE_ID?.trim() && !!env.HERDR_SOCKET_PATH?.trim();
+}
+
+/** Read-only /gentle:doctor guidance; empty outside Herdr. Never touches Herdr config. */
+export function herdrSetupHint(
+	env: NodeJS.ProcessEnv,
+	session: { interactive: boolean; isSocket: (path: string) => boolean },
+): string[] {
+	if (!herdrDetected(env)) return [];
+	const inactive = env.GENTLE_PI_AGENTS_CHILD === "1" ? "Gentle Agents child session"
+		: !session.interactive ? "requires the interactive Pi TUI"
+		: !session.isSocket(env.HERDR_SOCKET_PATH!) ? "HERDR_SOCKET_PATH is not a Unix socket" : undefined;
+	return [
+		"Herdr",
+		inactive ? `warn: Herdr task-summary publishing inactive: ${inactive}` : "pass: Herdr task-summary publishing active",
+		"info: Herdr's default sidebar does not show task titles; add these two rows to the Agents sidebar rows in your Herdr config: ['$summary'], ['$summary2']",
+		"info: Sidebar rows belong to the config of the Herdr client that displays the session, including when Pi runs over SSH",
+		"info: After editing, reload or restart Herdr; Gentle Shell never changes Herdr config",
+		"info: Details: https://github.com/Gentleman-Programming/gentle-shell/blob/main/docs/readme-reference.md#herdr-active-work-summary",
+	];
+}
+
 export function metadataArgs(pane: string, summary: string | null, seq: number): string[] {
 	const rows = summary?.split("\n") ?? [];
 	const tokens = ["summary", "summary2"].flatMap((token, index) => rows[index]

package/lib/native-review-cli.ts

@@ -119,7 +119,8 @@ export interface NativeReviewCli {
 	// Read-only risk assessment (gentle-ai#4295, landing in parallel with
 	// gentle-pi#662). Same plain-versioned shape as reviewMode/reviewStatus:
 	// an older binary without the verb, or any other process/decode failure,
-	// rejects the returned promise -- callers fail closed to `high` risk.
+	// rejects the returned promise -- callers report the tier as `unassessable`, which informs
+	// the verification plan but never adds an independent verifier by itself.
 	assess?(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1>;
 }
 
@@ -1082,6 +1083,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// b04b6b75d1a446c942a816fbf92932d16f8c3d3001f93159dee2a92bbf2ebe44.
 	// No new negotiated capability identity is asserted.
 	"4.1.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.2.0 repeats 4.1.1: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2. The provider contract moved
+	// from 1.3.0 to 1.4.0 (routing/pi.md, gentle-ai#5536), with published
+	// tarball SHA-256
+	// 9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b.
+	// No new negotiated capability identity is asserted.
+	"4.2.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {

package/lib/orchestrator-discovery.ts

@@ -1,13 +1,16 @@
 import { readCatalog, type CatalogPage } from "./orchestrator-catalog.ts";
 import type { PublishedWork } from "./orchestrator-work.ts";
 import type { PresenceRecord } from "./agents-session-transport.ts";
-import { activationHash, listPresence, readDiscovery, sessionHash, type DiscoveryMetadata } from "./orchestrator-presence.ts";
+import { activationHash, discoveryAbsent, listPresence, readDiscovery, sessionHash, type DiscoveryMetadata } from "./orchestrator-presence.ts";
 
 export interface OrchestratorCandidate {
 	sessionId: string;
 	reachability: "unknown";
 	freshness: "unknown" | "recent" | "stale";
 	label?: string;
+	/** Display-only label of a live peer whose code predates discovery publication:
+	 * its schema-1 header heartbeats, but it never writes a discovery sidecar. */
+	legacyLabel?: string;
 	aliases?: DiscoveryMetadata["aliases"];
 	workspace?: string;
 	tasks?: DiscoveryMetadata["tasks"];
@@ -36,6 +39,7 @@ export function discoverOrchestrators(profile: string, peers: readonly PresenceR
 		if (matches.length !== 1) return unknown;
 		const header = matches[0];
 		const metadata = readDiscovery(profile, header);
+		if (!metadata && header.recent && discoveryAbsent(profile, header)) return { ...unknown, legacyLabel: header.label };
 		if (metadata?.activation !== activationHash(activations[0])) return unknown;
 		if (!header.recent) return { ...unknown, freshness: "stale" };
 		const catalog = readCatalog(profile, header, metadata.activation, selection?.recipientSessionId === sessionId ? selection.cursor : undefined);