gentle-pi 4.2.0 → 4.4.0

package/bin/gentle-shell.mjs

@@ -9,6 +9,7 @@ import {
 	chmodSync,
 	closeSync,
 	constants as fsConstants,
+	copyFileSync,
 	existsSync,
 	fstatSync,
 	lstatSync,
@@ -27,7 +28,6 @@ import {
 import { constants as osConstants, homedir, tmpdir } from "node:os";
 import { delimiter, dirname, join, resolve as resolvePath } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import {
 	buildPiInvocation,
@@ -50,26 +50,30 @@ import {
 	parseRawLauncherConfig,
 	planSpawn,
 	POST_INSTALL_REMOVAL_SOURCES,
+	withLauncherPackagesExcluded,
 	postInstallRemovals,
 	provisionedEntry,
+	migrateStandaloneConfig,
 	recordProvisioned,
 	resolveHome,
 	resolvePiRuntime,
 	restoreJsonField,
+	separateHomeHint,
 	shellQuote,
+	standaloneConfigHome,
+	userPiHome,
 } from "../runtime/gentle-shell-launcher.mjs";
+import { formatImportPiReport, importPi } from "../runtime/gentle-shell-import-pi.mjs";
 import {
 	BUNDLED_VERIFY_ENV,
-	bundledEngramSchema,
 	classifyEngramStartup,
 	ENGRAM_COMPANION_SOURCE,
-	ENGRAM_PROVISION_FAILED_NOTICE,
+	ENGRAM_DEFAULT_URL,
 	ENGRAM_RECOVERY_NOTICE,
-	engramHeaderAllows,
+	ENGRAM_START_FAILED_NOTICE,
+	GENTLE_SHELL_CONFIG_HOME_ENV,
 	engramProbeAllowed,
-	engramProvenanceMatches,
-	engramProvenancePath,
-	parseEngramProvenance,
+	sharedEngramEnv,
 	piVersionOrHelpRequested,
 	probeEngramEndpoint,
 	sqliteHeaderUserVersion,
@@ -84,6 +88,7 @@ import {
 	parseBundledUpgradeArgs,
 	resolveBundledInstall,
 	withBundledNpmCommand,
+	withoutMissingBundledNpmCommand,
 } from "../runtime/gentle-shell-bundled.mjs";
 import {
 	parseResumeHandoff,
@@ -95,7 +100,8 @@ import {
 import { bundledGentleAiPaths, GENTLE_AI_VERSION, gentleAiBinaryPath, gentleAiIsolationEnv, PackageLocalGentleAiBinaryMissingError } from "../runtime/gentle-ai-binary.mjs";
 import { DEFAULT_THEME_NAME, installIsolatedTuiModeSetting } from "../scripts/install-tui-mode-setting.mjs";
 import { artifactFor, engramPinVersion } from "../scripts/installer-downloads.mjs";
-import { shouldCheckStartupUpdate, findStartupUpdate } from "../runtime/gentle-shell-startup-update.mjs";
+import { migrateBundledEngram, migrationPending, MIGRATION_PENDING_NOTICE, MIGRATION_USAGE } from "../scripts/bundled-engram-migration.mjs";
+import { findStartupUpdate, parseStartupReleaseCache, shouldCheckStartupUpdate, writeStartupReleaseCache } from "../runtime/gentle-shell-startup-update.mjs";
 import { promptStartupUpdate } from "../runtime/gentle-shell-update-panel.mjs";
 import { applyStartupChoice, omitStartupVersion, resolveStartupRelaunch } from "../runtime/gentle-shell-startup-flow.mjs";
 
@@ -192,19 +198,6 @@ function verifiedBundledCore() {
 	return undefined;
 }
 
-function sha256File(path) {
-	return createHash("sha256").update(readFileSync(path)).digest("hex");
-}
-
-function readSmallRegularFile(path, limit) {
-	try {
-		const info = lstatSync(path);
-		return info.isFile() && info.size <= limit ? readFileSync(path, "utf8") : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
 // The database's raw SQLite header, read as a plain file (never through
 // SQLite): a regular, unlinked engram.db whose opened identity is the one seen.
 function readSqliteUserVersion(path) {
@@ -224,100 +217,49 @@ function readSqliteUserVersion(path) {
 	}
 }
 
-// The default data directory without opening it: presence, canonical path,
-// the .instance-id file and the database header. A link is never followed.
-function observeEngramStore() {
-	const dir = join(homedir(), ".engram");
-	let dataDir;
-	try {
-		if (!lstatSync(dir).isDirectory()) return { store: "unknown" };
-		dataDir = realpathSync(dir);
-	} catch (error) {
-		return { store: error.code === "ENOENT" ? "absent" : "unknown" };
-	}
-	return { store: "present", dir, dataDir, instanceId: readSmallRegularFile(join(dir, ".instance-id"), 128)?.trim() };
-}
-
-// Only the identity files Engram's `instance-id` writes: a store Shell
-// provisioned whose session has not created its database yet.
-function identityOnlyStore(dir) {
-	try {
-		return readdirSync(dir).every((name) => name === ".instance-id" || name === ".instance-id.lock" || name.startsWith(".instance-id-"));
-	} catch {
-		return false;
-	}
-}
-
-// Shell's own store: the record Shell wrote when it provisioned this exact
-// directory's identity, the same core digest, and a database header no newer
-// than the bundled schema (or no database yet).
-function ownEngramStore(observed, core) {
-	let record;
-	try {
-		record = parseEngramProvenance(readJsonIfExists(engramProvenancePath(bundledInstall.root, process.platform)));
-	} catch {
-		return undefined;
-	}
-	if (record === undefined || observed.store !== "present" || core === undefined) return undefined;
-	if (!engramProvenanceMatches(record, { dataDir: observed.dataDir, instanceId: observed.instanceId, coreSha256: sha256File(core) })) return undefined;
-	const headerAllows = engramHeaderAllows(readSqliteUserVersion(join(observed.dir, "engram.db")), bundledEngramSchema(engramPinVersion));
-	return headerAllows || identityOnlyStore(observed.dir) ? { instanceId: record.instanceId } : undefined;
-}
-
-// Evidence only: file metadata, the raw header and a bounded read-only probe
-// of the default endpoint. No Engram executable, SQLite, identity repair, or
-// contact with an explicitly selected endpoint.
+// Evidence only: the default store's raw header and a bounded read-only probe
+// of the default endpoint. No Engram executable, SQLite, or contact with an
+// explicitly selected endpoint. A `spawn` decision starts nothing here.
 async function classifyBundledMemory() {
-	const core = verifiedBundledCore();
-	const decision = { env: process.env, core: core !== undefined, coreVersion: engramPinVersion };
-	if (!engramProbeAllowed(process.env)) return classifyEngramStartup({ ...decision, store: "unknown", endpoint: { kind: "unknown" } });
-	const observed = observeEngramStore();
+	if (migrationPending(bundledInstall.root)) return { policy: "disabled", notice: MIGRATION_PENDING_NOTICE };
+	const decision = { env: process.env, core: verifiedBundledCore() !== undefined, coreVersion: engramPinVersion };
+	if (!engramProbeAllowed(process.env)) return classifyEngramStartup({ ...decision, endpoint: { kind: "unknown" } });
 	const endpoint = await probeEngramEndpoint();
-	return classifyEngramStartup({ ...decision, store: observed.store, endpoint, provenance: ownEngramStore(observed, core) });
-}
-
-// Verified with the published Engram v3.4.0 darwin-arm64 binary in an isolated
-// HOME: `instance-id` creates only `.instance-id.lock` and `.instance-id`,
-// without a database. Keep update checks suppressed and GitHub tokens removed
-// for this provisioning invocation. The timeout stays below the identity lock
-// wait: a held lock means a concurrent creator, so memory stays off that launch.
-const ENGRAM_PROVISION_TIMEOUT_MS = 15000;
-
-// A fresh launch's store identity, provisioned by Shell itself with the verified
-// core before Pi starts, then recorded. False when any step fails.
-function provisionEngramStore() {
+	const userVersion = endpoint.kind === "refused" ? readSqliteUserVersion(join(homedir(), ".engram", "engram.db")) : undefined;
+	return classifyEngramStartup({ ...decision, endpoint, userVersion });
+}
+
+// Like other agents' hooks, Shell starts the shared server when nothing
+// listens: the verified core's plain `serve` on Engram's own default port and
+// data directory, detached so it outlives Pi. Its environment drops the user's
+// Engram settings and GitHub tokens and skips the update check. Ready means the
+// same /compatibility contract any reused server must answer, so a concurrent
+// launch that wins the bind converges too: after the child exits, polling
+// continues for a short grace within the overall bound.
+const ENGRAM_START_TIMEOUT_MS = 10000;
+const ENGRAM_START_EXIT_GRACE_MS = 2000;
+
+async function startSharedEngram() {
+	const failed = { policy: "disabled", notice: ENGRAM_START_FAILED_NOTICE };
 	const core = verifiedBundledCore();
-	if (core === undefined || observeEngramStore().store !== "absent") return false;
-	let target;
+	if (core === undefined) return failed;
+	let deadline = Date.now() + ENGRAM_START_TIMEOUT_MS;
+	const exited = () => { deadline = Math.min(deadline, Date.now() + ENGRAM_START_EXIT_GRACE_MS); };
 	try {
-		target = join(realpathSync(homedir()), ".engram");
+		const env = sharedEngramEnv(process.env);
+		const child = spawn(core, ["serve"], { cwd: homedir(), env, detached: true, stdio: "ignore", windowsHide: true });
+		child.once("error", exited);
+		child.once("exit", exited);
+		child.unref();
 	} catch {
-		return false;
+		return failed;
 	}
-	// The provider's own environment, except for this one invocation: no update
-	// check and no GitHub tokens. ENGRAM_DATA_DIR is never set here.
-	const env = { ...process.env, ENGRAM_NO_UPDATE_CHECK: "1" };
-	delete env.GH_TOKEN;
-	delete env.GITHUB_TOKEN;
-	const result = spawnSync(core, ["instance-id"], { env, encoding: "utf8", timeout: ENGRAM_PROVISION_TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
-	const observed = observeEngramStore();
-	if (result.status !== 0 || observed.store !== "present" || observed.dataDir !== target || !/^[a-f0-9]{32}$/.test(observed.instanceId ?? "") ||
-		String(result.stdout).trim() !== observed.instanceId) return false;
-	return writeEngramProvenance({ schema: 1, dataDir: target, instanceId: observed.instanceId, coreSha256: sha256File(core) });
-}
-
-function writeEngramProvenance(record) {
-	try {
-		const path = engramProvenancePath(bundledInstall.root, process.platform);
-		mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-		const temporary = `${path}.${process.pid}.tmp`;
-		writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: "wx" });
-		renameSync(temporary, path);
-		return true;
-	} catch (error) {
-		process.stderr.write(`gentle-shell: could not record Engram provenance (${error.message})\n`);
-		return false;
+	while (Date.now() < deadline) {
+		const endpoint = await probeEngramEndpoint({ timeoutMs: 500 });
+		if (endpoint.kind === "listening" && endpoint.compatible) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
+		await new Promise((resolve) => setTimeout(resolve, 100));
 	}
+	return failed;
 }
 
 // Use Pi's supported configuration-only install command, never an alternate
@@ -627,6 +569,42 @@ function handleHomeCommand(commandArgs) {
 	process.exit(0);
 }
 
+// `gentle-shell [home selectors] home import-pi [--dry-run]`: copies the
+// user's pi sign-ins, MCP servers and default model into the resolved
+// separate home (lib/gentle-shell-import-pi.ts). A home that is new or empty
+// is first bootstrapped exactly as a first launch would, so the files this
+// adds never make it look foreign to auto-provisioning (homeIsForeign).
+async function handleImportPiCommand(args) {
+	const options = args.commandArgs.slice(1);
+	if (options.some((option) => option !== "--dry-run")) fail("gentle-shell home import-pi accepts only --dry-run. Run 'gentle-shell --help'.", 2);
+	const dryRun = options.includes("--dry-run");
+	let home = resolveHome({ args, env: process.env, homedir: homedir(), config: loadConfig() });
+	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
+	const source = resolvePath(userPiHome(process.env, homedir()));
+	const refusal = "Choose a separate home with --isolated or --home <path>.";
+	if (home.mode === "link") {
+		fail(`gentle-shell home import-pi: the selected home is your pi home itself (--link), so there is nothing to import. ${refusal}`, 1);
+	}
+	if ([source, join(homedir(), ".pi", "agent")].some((piHome) => safeRealpath(piHome) === safeRealpath(home.dir))) {
+		fail(`gentle-shell home import-pi: ${home.dir} is your pi home itself, so there is nothing to import. ${refusal}`, 1);
+	}
+	if (homeNeedsBootstrap(home.dir)) {
+		if (dryRun) {
+			process.stdout.write(`Would prepare ${home.dir} as a new Gentle Shell home\n`);
+		} else {
+			try {
+				await bootstrapOwnedHome(home);
+			} catch (error) {
+				fail(`gentle-shell home import-pi: could not prepare ${home.dir} (${error.message}); nothing was imported`, 1);
+			}
+			process.stdout.write(`Prepared ${home.dir} as a new Gentle Shell home\n`);
+		}
+	}
+	const result = importPi({ source, target: home.dir, dryRun });
+	for (const line of formatImportPiReport(result, { source, target: home.dir, dryRun })) process.stdout.write(`${line}\n`);
+	process.exitCode = result.failed ? 1 : 0;
+}
+
 // Test/development-only override for the setup subcommand's gentle-ai
 // executable path. Lets a test point at a stub script (or a deliberately
 // missing path) without touching the real pinned .gentle-ai/v<version>/gentle-ai
@@ -799,12 +777,18 @@ function buildSetupEnv(home, runtime, piLauncherDir) {
 		const env = bundledSetupEnv({ ...bundledEnv, PI_CODING_AGENT_DIR: home.dir, GENTLE_PI_AGENT_HOME: home.dir }, { dirs: bundledSetupDirs, platform: process.platform });
 		return gentleAiIsolationEnv(env, { packageRoot });
 	}
-	return {
+	const env = {
 		...process.env,
 		PI_CODING_AGENT_DIR: home.dir,
 		GENTLE_PI_AGENT_HOME: home.dir,
 		PATH: [...(piLauncherDir ? [piLauncherDir] : []), dirname(runtime.command), process.env.PATH ?? ""].join(delimiter),
 	};
+	// #2201: the isolated home's own config folder, given to Gentle AI the
+	// bundled way (gentleAiIsolationEnv); never an outer session's marker.
+	const configHome = standaloneConfigHome(home);
+	if (configHome === undefined) delete env[GENTLE_SHELL_CONFIG_HOME_ENV];
+	else env[GENTLE_SHELL_CONFIG_HOME_ENV] = configHome;
+	return gentleAiIsolationEnv(env, { packageRoot });
 }
 
 // Gentle AI requires a `pi` on its PATH and runs `pi install npm:gentle-pi`
@@ -847,15 +831,34 @@ function sharedPersonaPath() {
 	return join(homedir(), ".pi", "gentle-ai", "persona.json");
 }
 
-// The persona files a setup run may rewrite. Bundled (S9): the prefix's own,
-// which a Gentle AI with GENTLE_AI_PI_CONFIG_DIR (gentle-ai #5462) writes, and
-// still the user's, which a pinned Gentle AI without it writes; restoring an
-// unchanged file does nothing.
-function setupPersonaPaths() {
-	if (!bundledInstall) return [sharedPersonaPath()];
-	return [join(bundledGentleAiPaths(bundledInstall.root, process.platform).piConfig, "persona.json"), sharedPersonaPath()];
+// The persona files a setup run may rewrite. Bundled (S9) and the standalone
+// isolated home (#2201): its own config folder's, which a Gentle AI with
+// GENTLE_AI_PI_CONFIG_DIR (gentle-ai #5462) writes, and still the user's,
+// which a pinned Gentle AI without it writes; restoring an unchanged file
+// does nothing.
+function setupPersonaPaths(home) {
+	if (bundledInstall) return [join(bundledGentleAiPaths(bundledInstall.root, process.platform).piConfig, "persona.json"), sharedPersonaPath()];
+	const configHome = standaloneConfigHome(home);
+	return configHome === undefined ? [sharedPersonaPath()] : [join(configHome, "persona.json"), sharedPersonaPath()];
 }
 
+// The real filesystem behind migrateStandaloneConfig (#2201).
+const configMigrationFs = {
+	kind: (path) => {
+		try {
+			const stat = lstatSync(path);
+			return stat.isDirectory() ? "dir" : stat.isFile() ? "file" : "other";
+		} catch {
+			return "missing";
+		}
+	},
+	list: (path) => readdirSync(path),
+	mkdirPrivate: (path) => {
+		mkdirSync(path, { recursive: true, mode: 0o700 });
+	},
+	copyNew: (from, to) => copyFileSync(from, to, fsConstants.COPYFILE_EXCL),
+};
+
 // Bundled setup (S9): the pinned Engram GENTLE_AI_ENGRAM_BIN names, published
 // once in runtime/ (verified, never brew or the user's PATH). A failure stops
 // setup rather than let Gentle AI acquire another Engram.
@@ -1123,7 +1126,7 @@ async function runSetupFlow(home, runtime, { dryRun, stdio, timeoutMs }) {
 		if (!engram.ok) return engram;
 	}
 	// The memory decision never skips setup: it only selects the Engram
-	// environment (core or guard, policy, ENGRAM_URL) setup's children and the
+	// environment (guard, policy, ENGRAM_URL) setup's children and the
 	// launched Pi get. Gentle AI's `install --agent pi` and `pi-engram init` open
 	// no store. Reclassified now that the verified core may just be published.
 	if (bundledInstall) {
@@ -1134,8 +1137,10 @@ async function runSetupFlow(home, runtime, { dryRun, stdio, timeoutMs }) {
 
 	const setupArgs = ["install", "--agent", "pi", "--scope", "global", ...(dryRun ? ["--dry-run"] : [])];
 	const piLauncherDir = writeSetupPiLauncher(runtime);
-	const env = buildSetupEnv(home, runtime, piLauncherDir);
-	const personaSnapshots = setupPersonaPaths().map((path) => [path, safely("snapshot your Pi persona file", path, undefined, () => snapshotFile(path))]);
+	// #2143: a Gentle AI with package exclusion never installs the launcher-owned
+	// gentle-pi; an older one ignores this and runPostInstallCleanup removes it.
+	const env = withLauncherPackagesExcluded(buildSetupEnv(home, runtime, piLauncherDir));
+	const personaSnapshots = setupPersonaPaths(home).map((path) => [path, safely("snapshot your Pi persona file", path, undefined, () => snapshotFile(path))]);
 	const statePath = sharedGentleAiStatePath();
 	const originalStateText = safely("read your Gentle AI state file", statePath, undefined, () => readParsableJsonText(statePath));
 	// Theme restore (never for --link — that home is the user's own
@@ -1387,6 +1392,25 @@ function writeHomeOwnershipMarker(home) {
 	writeFileSync(homeOwnershipMarkerPath(home), `${content}\n`, "utf8");
 }
 
+// The isolated/--home bootstrap: the first launch's own (main, below) and
+// `home import-pi`'s before it adds files to a new or empty home.
+async function bootstrapOwnedHome(home) {
+	// 0700: under umask 002 a default mode would leave ~/.gentle-shell group-writable,
+	// which the bundled install's prefix claim must tighten or refuse.
+	mkdirSync(home.dir, { recursive: true, mode: 0o700 });
+	await installIsolatedTuiModeSetting(home.dir);
+	writeHomeOwnershipMarker(home); // R3-001: lets a failed first auto-provision attempt still be retried later
+}
+
+function homeNeedsBootstrap(dir) {
+	if (!existsSync(dir)) return true;
+	try {
+		return isDirectory(dir) && readdirSync(dir).length === 0;
+	} catch {
+		return false;
+	}
+}
+
 // `homeHadContentBeforeBootstrap` must be read by the caller (main, below)
 // before the isolated/--home bootstrap runs: that bootstrap itself creates
 // and seeds a brand-new directory (settings.json with tuiMode, and now the
@@ -1580,7 +1604,9 @@ async function packageManagerAdapters() {
 		fs: await import("node:fs/promises"),
 		which: async (name) => findOnPath(name) ?? null,
 		...(invocation ? { invocation } : {}),
-		run: (command, argv, options = {}) => run(command, argv, { env: options.env ?? process.env, cwd: options.cwd, deadlineMs: options.deadlineMs ?? 20 * 60_000 }),
+		// stderrTail: a caller that asks for it, such as a failed `update` install, gets the bounded stderr.
+		run: (command, argv, options = {}) => run(command, argv, { env: options.env ?? process.env, cwd: options.cwd, deadlineMs: options.deadlineMs ?? 20 * 60_000,
+			...(options.stderrTail === undefined ? {} : { stderrTail: options.stderrTail }) }),
 	};
 }
 
@@ -1679,6 +1705,26 @@ async function ensureBundledNpmCommand(bundled, home, homeHadContentBeforeBootst
 	}
 }
 
+// The npmCommand a bundled install wrote into a home it owns must not outlive
+// it (#2469): Pi runs it for every package install, so a key naming a deleted
+// node.exe fails them all with ENOENT. A main-channel bootstrap drops the key
+// when it has the shape a bundled install writes and its node is gone; a
+// command the user set is never touched, and neither are an existing
+// executable, a link home and a foreign home.
+async function removeMissingNpmCommand(home, homeHadContentBeforeBootstrap) {
+	if (home.mode === "link") return;
+	const previous = provisionedEntry(readRawConfig(resolveConfigPath()), safeRealpath(home.dir));
+	if (homeIsForeign(home, previous, homeHadContentBeforeBootstrap) || !isDirectory(home.dir)) return;
+	const settingsPath = join(home.dir, "settings.json");
+	const edit = withoutMissingBundledNpmCommand(readJsonIfExists(settingsPath), (path) => existsSync(path));
+	if (edit.status === "malformed") {
+		process.stderr.write(`gentle-shell: ${settingsPath} is not a JSON object, so a stale npmCommand in it is not repaired\n`);
+	} else if (edit.status === "removed") {
+		writeFileAtomically(settingsPath, edit.text);
+		process.stderr.write(`gentle-shell: removed the bundled npmCommand naming a missing executable from ${settingsPath}; Pi installs packages with the npm on your PATH\n`);
+	}
+}
+
 // `gentle-shell self-uninstall` in a bundled install (S6, S7): the prefix's own
 // folders and exactly the PATH entry its receipt records; on Windows the running
 // node.exe and launcher are removed by a detached process after this one exits.
@@ -1736,11 +1782,27 @@ async function startupUpdate(bundled, args, startupEnv) {
 	if (!shouldCheckStartupUpdate({ args, env: startupEnv, bundled: Boolean(bundled),
 		inputTTY: process.stdin.isTTY === true, outputTTY: process.stdout.isTTY === true })) return undefined;
 	const configPath = resolveConfigPath();
-	let skipped;
-	try { skipped = readRawConfig(configPath).skippedStartupRelease; } catch { /* A notice must not prevent opening. */ }
+	let skipped, cache;
+	try {
+		const raw = readRawConfig(configPath);
+		skipped = raw.skippedStartupRelease;
+		// The last recorded lookup answers today's check without the network; a
+		// stale or malformed record just means this launch looks again.
+		cache = parseStartupReleaseCache(raw.startupReleaseCheck);
+	} catch { /* A notice must not prevent opening. */ }
 	const { latestRelease } = await import("../scripts/main-channel.mjs");
-	const offer = await findStartupUpdate({ current: ownPackageVersion(), skipped,
-		lookup: (signal) => latestRelease((url, options) => fetch(url, { ...options, signal })) });
+	const offer = await findStartupUpdate({ current: ownPackageVersion(), skipped, cache,
+		lookup: (signal) => latestRelease((url, options) => fetch(url, { ...options, signal })),
+		// Only a live lookup reaches this: persisting it keeps the next launches
+		// off the network. A failed write is retried by tomorrow's stale cache.
+		cacheWrite: (latest) => {
+			try {
+				writeStartupReleaseCache(() => readJsonIfExists(configPath), (text) => {
+					mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+					writeFileAtomically(configPath, text, { mode: 0o600 });
+				}, latest);
+			} catch { /* A notice must not prevent opening. */ }
+		}, });
 	if (!offer) return undefined;
 	let choice;
 	try { choice = await promptStartupUpdate(offer, { color: process.stdout.hasColors?.() === true }); }
@@ -1778,16 +1840,31 @@ async function main() {
 	if (args.error !== undefined) fail(`${args.error}\nRun 'gentle-shell --help' for usage.`, 2);
 	if (args.help) {
 		process.stdout.write("Pi updates: update reinstalls the verified supplier of the Pi this launcher runs (a global Pi, or the\nShell package whose adjacent peer it is, at the same Shell version) and reads the resulting Pi version back.\nUnknown ownership refuses without installing; update --extensions-only stays Pi-only.\nPrefix-bundled Pi updates with gentle-shell upgrade.\n");
-		process.stdout.write(`${helpText()}\nBundled Engram safety: memory opens only a fresh, verified or Shell-provisioned store; otherwise ENGRAM_BIN\nis Shell's guard and memory stays off. Matching versions or updating alone do not prove compatibility.\nReuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity.\nBack up existing data before manual changes; do not delete it or bypass the safety check.\nShell rechecks on every launch and remains usable without memory.\nAn explicit ENGRAM_BIN or ENGRAM_URL is kept and bypasses the guard.\n`);
+		process.stdout.write(`${helpText()}\nBundled Engram memory: Shell shares the global Engram server on 127.0.0.1:7437, like other agents' hooks.\nA running server is reused only with verified /compatibility evidence; when nothing listens, Shell starts the\nbundled core's engram serve (default ~/.engram) and waits for that evidence. Otherwise ENGRAM_BIN is Shell's\nguard and memory stays off for that launch. Matching versions or updating alone do not prove compatibility.\nBack up existing data before manual changes; do not delete it or bypass the safety check.\nShell rechecks on every launch and remains usable without memory.\nAn explicit ENGRAM_BIN or ENGRAM_URL is kept and bypasses the guard.\n`);
 		process.exit(0);
 	}
 	if (args.command === "home") {
-		handleHomeCommand(args.commandArgs);
+		if (args.commandArgs[0] === "import-pi") await handleImportPiCommand(args);
+		else handleHomeCommand(args.commandArgs);
 		return;
 	}
 	// The verification input applies to `--version` only (scripts/bundled-install.mjs upgradeBundled).
 	const verifying = args.version && args.command === undefined ? process.env[BUNDLED_VERIFY_ENV] : undefined;
 	const bundled = resolveBundledInstall({ packageRoot, platform: process.platform, fs: bundledFs, verifying });
+	if (args.command === "memory") {
+		if (args.commandArgs.length !== 2 || args.commandArgs[0] !== "migrate" || args.commandArgs[1] !== "--confirm-quiescent") {
+			process.stderr.write(MIGRATION_USAGE);
+			process.exitCode = 2;
+			return;
+		}
+		if (!bundled) fail("gentle-shell: memory migrate requires a prefix-bundled installation", 1);
+		bundledInstall = bundled;
+		const result = migrateBundledEngram({ prefix: bundled.root, core: verifiedBundledCore(), home: homedir(), env: process.env });
+		process.stdout.write(result.stdout);
+		process.stderr.write(result.stderr);
+		process.exitCode = result.code;
+		return;
+	}
 	if (args.command === "upgrade") {
 		if (bundled) process.exitCode = await handleBundledUpgrade(bundled, args.commandArgs);
 		else await handleUpgradeCommand(args.commandArgs);
@@ -1810,7 +1887,7 @@ async function main() {
 	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
 
 	// Version and help runs (Shell's own or forwarded to Pi) never probe Engram,
-	// ensure the companion, print memory notices or touch provenance.
+	// ensure the companion, print memory notices or start a server.
 	const engramQuiet = args.version || piVersionOrHelpRequested(args.passthrough);
 	let runtime;
 	if (bundled) {
@@ -1843,7 +1920,11 @@ async function main() {
 	});
 	if (versionProbe.error) fail(`Could not run the pi runtime at "${runtime.command}": ${versionProbe.error.message}`, 1);
 	const versionCheck = checkPiVersion(versionProbe.stdout ?? "");
-	if (!versionCheck.ok) fail(versionCheck.message, 1);
+	// A managed self update is how an old Pi gets replaced, so the minimum-version
+	// gate must not block it; everything else still requires the minimum.
+	const managedSelfUpdate = !bundled && args.piSubcommand === "update" && versionCheck.version !== undefined
+		&& (await import("../scripts/pi-update.mjs")).managedUpdatePlan(args.passthrough).self;
+	if (!versionCheck.ok && !managedSelfUpdate) fail(versionCheck.message, 1);
 
 	if (args.version) {
 		process.stdout.write(`${describeVersion({ gentlePiVersion: ownPackageVersion(), piVersion: versionCheck.version, home })}\n`);
@@ -1869,7 +1950,7 @@ async function main() {
 		const { managedUpdatePlan, updateSelectedPi } = await import("../scripts/pi-update.mjs");
 		const plan = managedUpdatePlan(args.passthrough);
 		if (plan.self) {
-			process.exitCode = await updateSelectedPi({ runtime, packageRoot, platform: process.platform, currentVersion: versionCheck.version, cwd: tmpdir(),
+			process.exitCode = await updateSelectedPi({ runtime, packageRoot, platform: process.platform, currentVersion: versionCheck.version, cwd: tmpdir(), env: process.env, home: homedir(),
 				adapters: await packageManagerAdapters(), out: (line) => process.stdout.write(`${line}\n`) });
 			if (plan.piArgs === undefined) return;
 		}
@@ -1893,12 +1974,22 @@ async function main() {
 	// Isolated-home bootstrap: only on a home gentle-shell has not seen before
 	// (link never bootstraps — it reuses the user's own pi agent home as-is).
 	if ((home.mode === "isolated" || home.mode === "path") && !existsSync(home.dir)) {
-		// 0700: under umask 002 a default mode would leave ~/.gentle-shell group-writable,
-		// which the bundled install's prefix claim must tighten or refuse.
-		mkdirSync(home.dir, { recursive: true, mode: 0o700 });
-		await installIsolatedTuiModeSetting(home.dir);
-		writeHomeOwnershipMarker(home); // R3-001: lets a failed first auto-provision attempt still be retried later
-		process.stderr.write(`gentle-shell: using a separate home at ${home.dir}. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.\n`);
+		await bootstrapOwnedHome(home);
+		const piSignIns = existsSync(join(userPiHome(process.env, homedir()), "auth.json"));
+		process.stderr.write(`${separateHomeHint(home, { piSignIns })}\n`);
+	}
+
+	// #2201: the standalone isolated home's own config folder, seeded once from
+	// the shared ~/.pi/gentle-ai. Not when an explicit GENTLE_PI_CONFIG_HOME
+	// decides the config home; never blocks the launch.
+	const configHome = bundled || process.env.GENTLE_PI_CONFIG_HOME ? undefined : standaloneConfigHome(home);
+	if (configHome !== undefined) {
+		try {
+			const migration = migrateStandaloneConfig({ source: join(homedir(), ".pi", "gentle-ai"), target: configHome, fs: configMigrationFs });
+			for (const line of migration.lines) process.stderr.write(`${line}\n`);
+		} catch (error) {
+			process.stderr.write(`gentle-shell: could not prepare ${configHome} (${error.message}); continuing\n`);
+		}
 	}
 
 	if (bundled) {
@@ -1907,6 +1998,12 @@ async function main() {
 		} catch (error) {
 			process.stderr.write(`gentle-shell: could not give Pi the bundled npm in ${join(home.dir, "settings.json")} (${error.message}); continuing\n`);
 		}
+	} else {
+		try {
+			await removeMissingNpmCommand(home, homeHadContentBeforeBootstrap);
+		} catch (error) {
+			process.stderr.write(`gentle-shell: could not repair the npmCommand in ${join(home.dir, "settings.json")} (${error.message}); continuing\n`);
+		}
 	}
 
 	if (args.command === "setup") {
@@ -2040,7 +2137,7 @@ async function main() {
 
 	if (bundled) {
 		// Recheck after setup and before provider loading: never carry a stale
-		// fresh-store decision across an installer that could create data.
+		// decision across an installer that could create data.
 		if (args.piSubcommand === undefined && !engramQuiet) {
 			bundledMemory = await classifyBundledMemory();
 			bundledEnv = bundledProcessEnv();
@@ -2048,9 +2145,9 @@ async function main() {
 			// could not be verified is reported, never a reason to stop Shell.
 			const companion = await ensureEngramCompanion(home, runtime, ["ignore", 2, 2], 10000);
 			if (!companion.ok) process.stderr.write(`${companion.message}\n`);
-			// A fresh store's identity and provenance exist before Pi starts, or
-			// memory stays off: Pi never runs with allow without a written record.
-			if (bundledMemory.fresh && !provisionEngramStore()) bundledMemory = { policy: "disabled", notice: ENGRAM_PROVISION_FAILED_NOTICE };
+			// Only this final decision starts the shared server, and Pi gets its
+			// URL only once the server verified.
+			if (bundledMemory.spawn) bundledMemory = await startSharedEngram();
 			if (bundledMemory.notice) process.stderr.write(`gentle-shell: ${bundledMemory.notice}\n`);
 		}
 		bundledEnv = bundledProcessEnv();
@@ -2066,6 +2163,7 @@ async function main() {
 		passthrough: [...managedHerdrExtensionArgs(home, args), ...passthrough],
 		piSubcommand: args.piSubcommand,
 		baseEnv: bundledEnv ?? process.env,
+		bundled: Boolean(bundled),
 		homedir: homedir(),
 		// The spawn below sets no cwd, so pi runs in the launcher's own.
 		cwd: process.cwd(),

package/contracts/review-provider-contract-mirror/provider-contract.lock.json

@@ -1,16 +1,17 @@
 {
   "schema": "gentle-pi.review-provider-contract-mirror-lock/v1",
   "acquisition": "field-test-local",
-  "contract_semver": "1.3.0",
+  "contract_semver": "1.4.0",
   "source": {
     "kind": "archive",
-    "archive_sha256": "b04b6b75d1a446c942a816fbf92932d16f8c3d3001f93159dee2a92bbf2ebe44"
+    "archive_sha256": "9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b"
   },
-  "tree_sha256": "a2b95892ec8f10340d8d1bb4fc805f9c92db000f58b60b382ff859d312fdc023",
+  "tree_sha256": "aab5ab7fe7ee6bb180d8bbce21c034cebb0c0d284afcc8664a9b3bb57323c35d",
   "entries": {
-    "README.md": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085",
-    "manifest.json": "4e335a987e053dac42425ffe31628253eb43dd26f1235085fa90b200bce13d13",
+    "README.md": "3a655c2f19aee02636da062f0cae7a189b7e5f691c8ba8010f2ed50e5d8e8d70",
+    "manifest.json": "d2b5765e28df5b2459848379e91a27beb806916fabc96207060ad1cc5e911972",
     "orchestration/pi.md": "2d7ddd99f1c739a97f4a6b3929e5e2bdddcbf69aed69356395038d90bca25b2f",
+    "routing/pi.md": "1c7466e2333c08e386b4b5afb081531146d181030692463431e7695df7f90690",
     "schemas/lens.schema.json": "9b8a2354a570888486015434501b66b51441a3baf5bf858635e4fff56b2e8298",
     "schemas/refuter.schema.json": "36f8267c6c3f04600b8f1cb77df70d90858611af822cc81922efd6b3502fb646",
     "schemas/targeted-validator.schema.json": "40e397195bdfbc6782fc3090f20c5be082e4d14d2855314f99ecb8506133eddc",
@@ -19,8 +20,8 @@
     "vectors/targeted-validator.json": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
   },
   "generated": {
-    "generated/provider-capabilities.baseline.json": "f439a3f83394219dae5257a88f112eba5e67f9d4e566eb6d9f3f5608b727c1f7",
-    "generated/provider-roles.baseline.json": "71982937962834120b8304c795bf0e90c04b262a4293c6b96bf423b68a5781e0"
+    "generated/provider-capabilities.baseline.json": "bca708f5f67f506b4acb2cfdcb775b02a51468579fc7d6b4d169785ff411a215",
+    "generated/provider-roles.baseline.json": "aa36ec6f7469ac6faab756eec681f68f234cbadc1e12b345a93c6c34aa01f7aa"
   },
   "runtimes": [
     "claude-code",

package/contracts/review-provider-contract-mirror/{v1.3.0 → v1.4.0}/bundle/README.md

@@ -19,4 +19,11 @@ It carries no executable content, same as every other file in this bundle: a
 runtime mirrors and delivers the text as-is and still relies on Go for every
 review decision, prompt, receipt, and delivery gate.
 
+## Routing
+
+manifest.json's routing array lists, for closed runtimes only, one
+routing/<runtime>.md file: the exact ODD implementation-routing block Gentle
+AI renders for that runtime, whose prompt Gentle AI does not install. It is
+data only as well: a runtime mirrors and delivers the text as-is.
+
 Go remains the admission authority for prompts, results, receipts, and delivery gates.