gentle-pi 4.2.0 → 4.4.0

package/runtime/gentle-shell-import-pi.mjs

@@ -0,0 +1,234 @@
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
+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.mjs";
+
+// `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                                             = [
+	{ 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                    = ["defaultProvider", "defaultModel", "defaultThinkingLevel"];
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+function tempPathFor(path        )         {
+	return join(dirname(path), `.${basename(path)}.gentle-shell-${process.pid}.tmp`);
+}
+
+function removeQuietly(path        )       {
+	try {
+		unlinkSync(path);
+	} catch {
+		// Nothing left to clean up.
+	}
+}
+
+function writeTemp(path        , data                 , mode        )         {
+	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             = {
+	kind: (path) => {
+		try {
+			const stat = lstatSync(path);
+			if (stat.isSymbolicLink()) return "other";
+			return stat.isFile() ? "file" : stat.isDirectory() ? "dir" : "other";
+		} catch (error) {
+			if ((error                         ).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         )         {
+	const code = (error                                     )?.code;
+	return typeof code === "string" ? code : error instanceof Error ? error.message : String(error);
+}
+
+function parseObject(text        )                                      {
+	try {
+		const value          = JSON.parse(text.replace(/^\uFEFF/, ""));
+		return value !== null && typeof value === "object" && !Array.isArray(value) ? (value                           ) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function importFile(name        , mode                    , input                                                                     )               {
+	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                                                                     )                 {
+	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                                                                     )                 {
+	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                 = [];
+	const added                          = {};
+	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                                                                      )                 {
+	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              )         {
+	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                , context                                                     )           {
+	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                  ) => 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/runtime/gentle-shell-launcher.mjs

@@ -1,6 +1,7 @@
 // Generated by scripts/build-runtime-modules.mjs. Do not edit.
-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,                            } from "./child-package-injection.mjs";
+import { GENTLE_SHELL_CONFIG_HOME_ENV } from "./gentle-shell-bundled.mjs";
 
 // 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,
@@ -11,7 +12,7 @@ import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection,
 // 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"]         ;
+export const PI_SUBCOMMANDS = ["install", "remove", "uninstall", "update", "list", "config", "auth", "mcp"]         ;
 
 
 
@@ -42,7 +43,7 @@ function isPiSubcommand(token        )                        {
 // 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          )                     {
-	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,
@@ -77,6 +78,9 @@ export function parseLauncherArgs(argv          )                     {
 			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;
 		}
@@ -148,6 +152,14 @@ export function parseLauncherArgs(argv          )                     {
 			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;
 		}
@@ -212,6 +224,77 @@ export function isolatedDir(env                                    , homedir
 	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              )                     {
+	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.
+
+
+
+
+
+
+
+
+
+
+
+// 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                                                           )                      {
+	const { source, target, fs } = input;
+	if (fs.kind(target) !== "missing") return { lines: [] };
+	const reason = (error         ) => (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          ;
+	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           = [];
+	const failed           = [];
+	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                  )               {
 	const { args, env, homedir, config } = input;
 
@@ -242,6 +325,15 @@ export function homeSelectorFlags(home              )           {
 	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              , input                        )         {
+	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        )         {
 	return join(homedir, ".gentle-shell", "config.json");
 }
@@ -576,6 +668,20 @@ const POST_INSTALL_REMOVAL_PACKAGES
 // bin/gentle-shell.mjs.
 export const POST_INSTALL_REMOVAL_SOURCES                    = 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                    = ["npm:gentle-pi"];
+
+export function withLauncherPackagesExcluded(env                                    )                                     {
+	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
@@ -891,13 +997,16 @@ export function discoverLooseExtensionEntries(dir        , fs                  )
 
 
 
+
+
+
 
 
 
 
 // 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
@@ -978,6 +1087,12 @@ export function buildPiInvocation(input                        )               {
 		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);
 
@@ -1004,12 +1119,17 @@ const CMD_EXE_SPECIAL_CHARS = /[\s"&|<>^%()]/;
 
 // cmd.exe quoting is deliberately simple, not a full cmd.exe parser: wrap a
 // token in double quotes when it is empty or contains whitespace or any of
-// `"&|<>^%()`, and escape an inner `"` as `\"` — doubling inner quotes is not
-// reliable in cmd.exe, unlike the `\"` convention Node's own Windows spawn
-// helpers use.
+// `&|<>^%()`. A token with an inner `"` cannot be represented: cmd.exe has no
+// backslash escape, so `\"` still ends the quoted section and the rest of the
+// token is parsed as command syntax (`x" & whoami & rem "` would run
+// `whoami`). Doubling the quote is not reliable either, so such a token is
+// refused instead of producing a command line it cannot protect.
 export function quoteForCmdExe(token        )         {
+	if (token.includes('"')) {
+		throw new Error("cannot pass an argument containing a double quote through cmd.exe: it would end the quoted argument and let the rest run as a command");
+	}
 	if (token.length > 0 && !CMD_EXE_SPECIAL_CHARS.test(token)) return token;
-	return `"${token.replace(/"/g, '\\"')}"`;
+	return `"${token}"`;
 }
 
 const POSIX_SHELL_SPECIAL_CHARS = /[\s"'`\\$&|;<>(){}*?[\]!#~]/;
@@ -1053,7 +1173,7 @@ export function planSpawn(input                )            {
 // 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        )                                                           {
+export function detectJsonFormatting(text        )                                                           {
 	const match = text.match(/\{\r?\n([ \t]+)/);
 	return { indent: match ? match[1] : undefined, trailingNewline: text.endsWith("\n") };
 }
@@ -1175,9 +1295,11 @@ export function helpText()         {
 	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",
@@ -1185,7 +1307,8 @@ export function helpText()         {
 		"",
 		"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.",
@@ -1194,6 +1317,11 @@ export function helpText()         {
 		"",
 		"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",
@@ -1205,9 +1333,15 @@ export function helpText()         {
 		"                   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.",
 		"",
@@ -1220,6 +1354,8 @@ export function helpText()         {
 		"                                   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",
@@ -1234,7 +1370,10 @@ export function helpText()         {
 		"",
 		"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/runtime/gentle-shell-startup-update.mjs

@@ -21,6 +21,30 @@
 
 
 
+
+
+
+
+
+
+
+
+/** The launcher config records the last live lookup so the everyday launch stays off the network. */
+
+
+
+
+
+/** Reads the config's `startupReleaseCheck` key; anything malformed is no cache. */
+export function parseStartupReleaseCache(value         )                                  {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const { checkedAt, latest } = value                                             ;
+	const ms = typeof checkedAt === "number" ? checkedAt : typeof checkedAt === "string" ? Date.parse(checkedAt) : Number.NaN;
+	if (!Number.isFinite(ms) || typeof latest !== "string" || latest === "") return undefined;
+	return { checkedAt: ms, latest };
+}
+
+export const STARTUP_RELEASE_TTL_MS = 24 * 60 * 60 * 1000;
 
 export function shouldCheckStartupUpdate({ args, env, bundled, inputTTY, outputTTY }                           )          {
 	if (!bundled || !inputTTY || !outputTTY || args.command || args.piSubcommand || args.error || args.help || args.version || args.packageRoot !== undefined) {
@@ -62,9 +86,30 @@ function isNewer(latest          , current          )          {
 	return false;
 }
 
-export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500 }                            )                                          {
+function offerFor(current        , latest                    , skipped                    )                                 {
 	const currentParts = stableParts(current);
 	if (!currentParts) return undefined;
+	if (latest === undefined || latest === skipped) return undefined;
+	const latestParts = stableParts(latest);
+	if (!latestParts || !isNewer(latestParts, currentParts)) return undefined;
+	return {
+		current,
+		latest,
+		notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
+	};
+}
+
+// A malformed cached latest is never trusted — it must not suppress the
+// network check for a whole TTL window — so it counts as no cache at all.
+function usableCache(cache                                 , ttlMs        , nowMs        )                                  {
+	if (cache === undefined) return undefined;
+	if (!Number.isFinite(cache.checkedAt) || typeof cache.latest !== "string" || cache.latest === "" || stableParts(cache.latest) === undefined) return undefined;
+	return nowMs - cache.checkedAt < ttlMs ? cache : undefined;
+}
+
+export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500, cache, nowMs = Date.now(), ttlMs = STARTUP_RELEASE_TTL_MS, cacheWrite }                            )                                          {
+	const cached = usableCache(cache, ttlMs, nowMs);
+	if (cached !== undefined) return offerFor(current, cached.latest, skipped);
 	const controller = new AbortController();
 	const deadline = Number.isFinite(timeoutMs) && timeoutMs >= 0 && timeoutMs <= 2_147_483_647 ? timeoutMs : 1500;
 	let timer                                           ;
@@ -77,17 +122,24 @@ export async function findStartupUpdate({ current, skipped, lookup, timeoutMs =
 		});
 		// The race bounds startup even if the injected lookup ignores cancellation.
 		const latest = await Promise.race([lookup(controller.signal), timeout]);
-		if (latest === undefined || latest === skipped) return undefined;
-		const latestParts = stableParts(latest);
-		if (!latestParts || !isNewer(latestParts, currentParts)) return undefined;
-		return {
-			current,
-			latest,
-			notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
-		};
+		// Only a real answer is worth a day's trust: a timeout or rejection must
+		// not suppress tomorrow's check.
+		if (typeof latest === "string") cacheWrite?.(latest);
+		return offerFor(current, latest, skipped);
 	} catch {
 		return undefined;
 	} finally {
 		clearTimeout(timer);
 	}
 }
+
+// Mirrors omitStartupVersion: preserves every other config key, fails loudly on
+// an invalid config, and records the lookup's answer with an injected clock.
+export function writeStartupReleaseCache(read                          , write                        , version        , nowMs = Date.now())       {
+	const text = read();
+	const config = text === undefined ? {} : JSON.parse(text);
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw new Error("Invalid launcher config");
+	const cache                      = { checkedAt: nowMs, latest: version };
+	const serialized = JSON.stringify({ ...config, startupReleaseCheck: { checkedAt: new Date(cache.checkedAt).toISOString(), latest: cache.latest } }, null, 2);
+	write(`${serialized}\n`);
+}