gentle-pi 3.7.0 → 4.1.0

package/bin/gentle-shell.mjs

@@ -6,23 +6,28 @@
 // process, filesystem, and child process.
 import {
 	accessSync,
+	chmodSync,
 	closeSync,
 	constants as fsConstants,
 	existsSync,
+	fstatSync,
+	lstatSync,
 	mkdirSync,
+	mkdtempSync,
 	openSync,
 	readdirSync,
 	readFileSync,
+	readSync,
 	realpathSync,
 	renameSync,
 	rmSync,
 	statSync,
 	writeFileSync,
 } from "node:fs";
-import { createRequire } from "node:module";
-import { constants as osConstants, homedir } from "node:os";
+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,
@@ -53,8 +58,46 @@ import {
 	restoreJsonField,
 	shellQuote,
 } from "../runtime/gentle-shell-launcher.mjs";
-import { GENTLE_AI_VERSION, gentleAiBinaryPath, PackageLocalGentleAiBinaryMissingError } from "../runtime/gentle-ai-binary.mjs";
+import {
+	BUNDLED_VERIFY_ENV,
+	bundledEngramSchema,
+	classifyEngramStartup,
+	ENGRAM_COMPANION_SOURCE,
+	ENGRAM_PROVISION_FAILED_NOTICE,
+	ENGRAM_RECOVERY_NOTICE,
+	engramHeaderAllows,
+	engramProbeAllowed,
+	engramProvenanceMatches,
+	engramProvenancePath,
+	parseEngramProvenance,
+	piVersionOrHelpRequested,
+	probeEngramEndpoint,
+	sqliteHeaderUserVersion,
+	supportsEngramStartupPolicy,
+	bundledChildEnv,
+	bundledPi,
+	bundledSetupEnv,
+	bundledUpdateNext,
+	bundledUpdateNotice,
+	bundledUpdatePlan,
+	nodeBundledFs,
+	parseBundledUpgradeArgs,
+	resolveBundledInstall,
+	withBundledNpmCommand,
+} from "../runtime/gentle-shell-bundled.mjs";
+import {
+	parseResumeHandoff,
+	planResumeHint,
+	RESUME_HANDOFF_DIR_PREFIX,
+	RESUME_HANDOFF_ENV,
+	RESUME_HANDOFF_FILE,
+} from "../runtime/gentle-shell-resume-hint.mjs";
+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 { promptStartupUpdate } from "../runtime/gentle-shell-update-panel.mjs";
+import { applyStartupChoice, omitStartupVersion, resolveStartupRelaunch } from "../runtime/gentle-shell-startup-flow.mjs";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 
@@ -72,17 +115,30 @@ function readJsonIfExists(path) {
 	}
 }
 
-// @earendil-works/pi-coding-agent ships as an optional peer dependency: it may
-// not be installed at all, so a resolution failure here is expected, not an error.
+// Resolve the public ESM entry without importing the agent or reaching through
+// its exports map. Only an absent optional peer permits PATH fallback; malformed
+// installed metadata must not silently select a different runtime.
 function resolveBundledCli() {
+	let publicEntry;
 	try {
-		const require = createRequire(import.meta.url);
-		const pkgJsonPath = require.resolve("@earendil-works/pi-coding-agent/package.json");
-		const cliPath = join(dirname(pkgJsonPath), "dist", "bundle", "cli.js");
-		return existsSync(cliPath) ? cliPath : undefined;
-	} catch {
-		return undefined;
+		publicEntry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+	} catch (error) {
+		if (error.code === "ERR_MODULE_NOT_FOUND") return undefined;
+		throw error;
+	}
+	const entry = realpathSync(publicEntry);
+	const root = dirname(dirname(entry));
+	const expectedEntry = join(root, "dist", "index.js");
+	const metadata = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+	if (entry !== expectedEntry || metadata.name !== "@earendil-works/pi-coding-agent" ||
+		metadata.bin?.pi !== "dist/bundle/cli.js") {
+		throw new Error("Unsupported adjacent Pi package entry/name/bin metadata");
+	}
+	const cliPath = join(root, metadata.bin.pi);
+	if (realpathSync(cliPath) !== cliPath || !statSync(cliPath).isFile()) {
+		throw new Error("Unsupported adjacent Pi CLI path");
 	}
+	return cliPath;
 }
 
 function findOnPath(name) {
@@ -107,6 +163,218 @@ function signalExitCode(signal) {
 	return 128 + (typeof number === "number" ? number : 0);
 }
 
+// A bundled install (S8): this package inside <prefix>/versions/<id> that
+// `current` names (lib/gentle-shell-bundled.ts decides from these reads).
+const bundledFs = nodeBundledFs;
+
+// Set in a bundled install: the environment every child (Pi, setup, the version
+// probe) starts from instead of process.env (the user's own plus Gentle Shell's
+// variables), and the folders setup puts ahead of the user's PATH.
+let bundledEnv;
+let bundledSetupDirs;
+// The bundled install and its Pi cli, for bundledProcessEnv and setup's Engram.
+let bundledInstall;
+let bundledCli;
+let bundledMemory;
+// The Shell-owned guard ENGRAM_BIN names when memory is disabled (bin/engram-guard).
+const ENGRAM_GUARD = join(packageRoot, "bin", "engram-guard");
+
+// The pinned core only as ensureEngram published it: its runtime marker for
+// this release's archive and a regular file. Never a link or a PATH engram.
+function verifiedBundledCore() {
+	const core = bundledGentleAiPaths(bundledInstall.root, process.platform).engram;
+	try {
+		const marker = readFileSync(join(dirname(core), ".gentle-shell-runtime"), "utf8");
+		if (marker === `${artifactFor("engram", process.platform, process.arch).url}\n` && lstatSync(core).isFile()) return core;
+	} catch {
+		// Missing, unmarked, or an unsupported target: no verified core.
+	}
+	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) {
+	let fd;
+	try {
+		const seen = lstatSync(path);
+		if (!seen.isFile()) return undefined;
+		fd = openSync(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+		const opened = fstatSync(fd);
+		if (opened.ino !== seen.ino || opened.dev !== seen.dev) return undefined;
+		const header = Buffer.alloc(100);
+		return readSync(fd, header, 0, 100, 0) === 100 ? sqliteHeaderUserVersion(header, opened.size) : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+}
+
+// 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.
+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();
+	const endpoint = await probeEngramEndpoint();
+	return classifyEngramStartup({ ...decision, store: observed.store, endpoint, provenance: ownEngramStore(observed, core) });
+}
+
+// Verified read-only in Engram v3.3.2: `engram instance-id` first runs a GitHub
+// update check that sends GH_TOKEN or GITHUB_TOKEN (cmd/engram/main.go:742-744,
+// 835-847; internal/version/check.go:23-24,60-70,171-176) unless
+// ENGRAM_NO_UPDATE_CHECK is set (check.go:19,49-51,114-117). It then resolves the
+// default ~/.engram (main.go:749-765) and runs EnsureInstanceID
+// (internal/store/instance.go:15-79): the data dir, `.instance-id.lock` (waits
+// up to 60s, internal/store/migration_lock.go:29-76) and `.instance-id`. It
+// returns (main.go:767-775) before orphan migration (main.go:779) and opens no
+// database. The timeout stays below that lock wait: a held lock means a
+// concurrent creator, and memory then stays off for the 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 core = verifiedBundledCore();
+	if (core === undefined || observeEngramStore().store !== "absent") return false;
+	let target;
+	try {
+		target = join(realpathSync(homedir()), ".engram");
+	} catch {
+		return false;
+	}
+	// 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;
+	}
+}
+
+// Use Pi's supported configuration-only install command, never an alternate
+// extension loader. Verify advertised enforcement before trusting the policy.
+async function ensureEngramCompanion(home, runtime, stdio, timeoutMs) {
+	const metadata = join(home.dir, "npm", "node_modules", "gentle-engram", "package.json");
+	let packages;
+	try {
+		packages = JSON.parse(readJsonIfExists(join(home.dir, "settings.json")) ?? "{}").packages ?? [];
+	} catch {
+		return { ok: false, exitCode: 1, message: "gentle-shell: cannot verify Engram startupPolicy from malformed settings; repair settings and recheck" };
+	}
+	if (!Array.isArray(packages)) return { ok: false, exitCode: 1, message: "gentle-shell: cannot verify Engram startupPolicy from non-array packages" };
+	let pinned = false;
+	let local = false;
+	let npmSelected = false;
+	for (const entry of packages) {
+		const source = typeof entry === "string" ? entry : entry?.source;
+		if (source === ENGRAM_COMPANION_SOURCE) pinned = true;
+		if (typeof source === "string" && /^npm:gentle-engram(?:@|$)/.test(source)) npmSelected = true;
+		if (typeof source !== "string" || source.startsWith("npm:")) continue;
+		// Preserve an explicit local companion selection rather than overwrite it.
+		const selected = resolvePath(home.dir, source);
+		if (readPackageName(selected) !== "gentle-engram") continue;
+		if (!supportsEngramStartupPolicy(readJsonIfExists(join(selected, "package.json")))) {
+			return { ok: false, exitCode: 1, message: `gentle-shell: selected companion ${source} lacks engram.startupPolicy=1; update it and recheck (selection preserved)` };
+		}
+		local = true;
+	}
+	if (local && !npmSelected) return { ok: true };
+	if (pinned && supportsEngramStartupPolicy(readJsonIfExists(metadata))) return { ok: true };
+	process.stderr.write(`gentle-shell: installing policy-capable companion ${ENGRAM_COMPANION_SOURCE} through Pi\n`);
+	const result = await spawnAndWait(runtime.command, [...runtime.args, "install", ENGRAM_COMPANION_SOURCE], buildSetupEnv(home, runtime), stdio, timeoutMs);
+	let declared = false;
+	try {
+		declared = JSON.parse(readJsonIfExists(join(home.dir, "settings.json")) ?? "{}").packages?.some((entry) =>
+			(typeof entry === "string" ? entry : entry?.source) === ENGRAM_COMPANION_SOURCE) === true;
+	} catch { /* Missing or malformed readback cannot establish enforcement. */ }
+	if (!result.ok || result.timedOut || !declared || !supportsEngramStartupPolicy(readJsonIfExists(metadata))) {
+		return { ok: false, exitCode: 1, message: "gentle-shell: companion installation did not establish engram.startupPolicy=1; the Engram guard still keeps unverified stores closed. Repair gentle-engram, then restart Shell." };
+	}
+	return { ok: true };
+}
+
+// The bundled children's environment (bundledChildEnv), with the pinned Engram
+// only once it is published: computed again right before Pi starts, so an
+// Engram the automatic setup just published is used in the same launch.
+function bundledProcessEnv() {
+	return bundledChildEnv(process.env, { node: process.execPath, cli: bundledCli, prefix: bundledInstall.root, engram: verifiedBundledCore(),
+		guard: ENGRAM_GUARD, memory: bundledMemory });
+}
+
 function ownPackageVersion() {
 	const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
 	return packageJson.version;
@@ -162,6 +430,45 @@ function isDirectory(path) {
 	}
 }
 
+// Reuse Herdr's managed bridge, never its transport. This process-boundary
+// lookup is deliberately best-effort and does not modify either agent home.
+function managedHerdrExtensionArgs(home, args) {
+	const env = process.env;
+	if (home.mode !== "isolated" || args.piSubcommand !== undefined || args.passthrough[0] === "mcp") return [];
+	if (env.HERDR_ENV !== "1" || !env.HERDR_SOCKET_PATH?.trim() || !env.HERDR_PANE_ID?.trim()) return [];
+	if (env.GENTLE_PI_AGENTS_CHILD === "1" || !process.stdin.isTTY || !process.stdout.isTTY) return [];
+	// Only automatic interactive loading: a user opt-out must not become an
+	// explicit -e (which Pi loads even under --no-extensions). Conservatively
+	// skip ambiguous mode flags too; --mode text alone still allows a TUI.
+	const forwarded = args.passthrough;
+	if (forwarded.some((arg) => ["--no-extensions", "-ne", "--print", "-p", "--export", "--list-models", "-v"].includes(arg))) return [];
+	if (forwarded.some((arg, i) => (arg === "--mode" && forwarded[i + 1] !== "text") || arg.startsWith("--mode="))) return [];
+	try {
+		if (!statSync(env.HERDR_SOCKET_PATH).isSocket()) return [];
+	} catch {
+		return [];
+	}
+	// Prefer a bridge in the selected home over adding a competing copy; keep
+	// the incoming Pi home override before falling back to Herdr's usual home.
+	const agentHomes = [home.dir, env.PI_CODING_AGENT_DIR, join(homedir(), ".pi", "agent")];
+	for (const agentHome of agentHomes) {
+		if (!agentHome) continue;
+		const bridge = join(agentHome, "extensions", "herdr-agent-state.ts");
+		try {
+			if (!statSync(bridge).isFile()) continue;
+			accessSync(bridge, fsConstants.R_OK);
+			// Pi's package-manager.toResolvedPaths and resource-loader.mergePaths
+			// dedupe canonical files across discovery, explicit -e and manifests.
+			// Existence alone is NOT proof of loading: declare the resource and
+			// let that resolver dedupe it, including explicit aliases from argv.
+			return ["-e", realpathSync(bridge)];
+		} catch {
+			// An absent/unreadable bridge never prevents the ordinary launch.
+		}
+	}
+	return [];
+}
+
 // Real-fs adapter for discoverLooseExtensionEntries (lib/gentle-shell-launcher.ts):
 // statSync-based isFile/isDirectory (not readdirSync's Dirent, which uses
 // lstat and so would treat a symlinked file or directory as neither) so a
@@ -254,9 +561,46 @@ function readRawConfig(configPath) {
 function writeRawConfig(configPath, config) {
 	const configDir = dirname(configPath);
 	if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true, mode: 0o700 });
-	const tempPath = join(configDir, `.${basenameOf(configPath)}.gentle-shell-${process.pid}.tmp`);
-	writeFileSync(tempPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-	renameSync(tempPath, configPath);
+	writeFileAtomically(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+// The one atomic write every launcher-owned config/settings update goes
+// through: a temp file next to the real target, then a rename onto it, so a
+// crash or kill never leaves a partial file. When `path` is a symlink (Nix
+// home-manager, stow, and similar dotfile managers ship settings.json and
+// config.json that way), the write lands on the link's real target and the
+// link itself stays in place; renaming onto `path` would replace the link
+// with a regular file. A missing path or a dangling link has no real target
+// to preserve, so it is written at `path` itself, exactly as before this
+// helper existed, instead of creating a file wherever a dangling link points.
+// The permission bits are `mode` when given, otherwise the real target's own
+// (applied with chmod, so the umask cannot narrow them); a new file keeps
+// the default creation mode. The temp file is removed when the write or
+// rename throws, and the error propagates to the caller's own handling.
+function writeFileAtomically(path, data, { mode } = {}) {
+	let target = path;
+	try {
+		target = realpathSync(path);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	let targetMode = mode;
+	if (targetMode === undefined) {
+		try {
+			targetMode = statSync(target).mode & 0o777;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+	}
+	const tempPath = join(dirname(target), `.${basenameOf(target)}.gentle-shell-${process.pid}.tmp`);
+	try {
+		writeFileSync(tempPath, data);
+		if (targetMode !== undefined) chmodSync(tempPath, targetMode);
+		renameSync(tempPath, target);
+	} catch (error) {
+		rmSync(tempPath, { force: true });
+		throw error;
+	}
 }
 
 function loadConfig() {
@@ -453,15 +797,50 @@ function ensurePackageLocalGentleAi(binaryPath, pinnedVersion, stdio) {
 // home, and the resolved pi runtime's directory is prepended to PATH so
 // gentle-ai's (or pi's own) preflight finds `pi` even when it is bundled or
 // given through GENTLE_SHELL_PI.
-function buildSetupEnv(home, runtime) {
+function buildSetupEnv(home, runtime, piLauncherDir) {
+	// Bundled: our node, then the version's `pi`, ahead of the user's PATH, and
+	// Gentle AI's state, persona and Engram inside the prefix (S9).
+	if (bundledEnv) {
+		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 {
 		...process.env,
 		PI_CODING_AGENT_DIR: home.dir,
 		GENTLE_PI_AGENT_HOME: home.dir,
-		PATH: `${dirname(runtime.command)}${delimiter}${process.env.PATH ?? ""}`,
+		PATH: [...(piLauncherDir ? [piLauncherDir] : []), dirname(runtime.command), process.env.PATH ?? ""].join(delimiter),
 	};
 }
 
+// Gentle AI requires a `pi` on its PATH and runs `pi install npm:gentle-pi`
+// with it. A Pi gentle-shell resolved elsewhere (the adjacent package, run
+// as `node <cli>`, or GENTLE_SHELL_PI) is not that `pi`, so a first launch
+// from a terminal without one failed every time. This writes a private,
+// temporary `pi` that runs exactly the resolved runtime; null when the
+// runtime already is the `pi` on PATH (or for a bundled install, whose
+// setup PATH already starts with the version's node_modules/.bin).
+function writeSetupPiLauncher(runtime) {
+	if (bundledEnv || runtime.kind === "path") return null;
+	let dir;
+	try {
+		dir = mkdtempSync(join(tmpdir(), "gentle-shell-pi-"));
+	} catch {
+		// No usable temp folder: setup runs as it did before, without this `pi`.
+		return null;
+	}
+	if (process.platform === "win32") {
+		// Batch expands % even inside quotes; double it so a path stays literal.
+		const quote = (value) => `"${value.replaceAll("%", "%%")}"`;
+		// A batch runtime needs `call`, or control never returns for `exit /b`.
+		const call = /\.(?:cmd|bat)$/i.test(runtime.command) ? "call " : "";
+		writeFileSync(join(dir, "pi.cmd"), `@echo off\r\n${call}${[runtime.command, ...runtime.args].map(quote).join(" ")} %*\r\nexit /b %errorlevel%\r\n`);
+	} else {
+		const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+		writeFileSync(join(dir, "pi"), `#!/bin/sh\nexec ${[runtime.command, ...runtime.args].map(quote).join(" ")} "$@"\n`, { mode: 0o700 });
+	}
+	return dir;
+}
+
 // The shared Pi persona file gentle-ai writes on every install, regardless
 // of the target home: its own PiPersonaConfigPath always resolves against
 // the OS home, never PI_CODING_AGENT_DIR (gentle-ai internal/components/persona/inject.go),
@@ -473,6 +852,29 @@ 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()];
+}
+
+// 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.
+async function ensureBundledEngram() {
+	const { ensureEngram, prefixLayout } = await import("../scripts/bundled-install.mjs");
+	const layout = prefixLayout({ platform: process.platform, env: process.env, home: homedir(), root: bundledInstall.root });
+	try {
+		await ensureEngram({ layout, platform: process.platform, arch: process.arch, env: process.env });
+		return { ok: true };
+	} catch (error) {
+		return { ok: false, exitCode: 1, message: `gentle-shell: could not install the pinned Engram in ${layout.engramDir} (${error.message})` };
+	}
+}
+
 // Records `path`'s current state before a child process that might rewrite
 // it runs: whether it exists, and if so its exact bytes and mode. Returns
 // `{ path, existed: false }` for a missing file so restoreFile below knows
@@ -512,9 +914,7 @@ function restoreFile(snapshot) {
 	}
 	if (currentBytes !== undefined && currentBytes.equals(snapshot.bytes)) return false;
 	mkdirSync(dirname(path), { recursive: true });
-	const tempPath = join(dirname(path), `.${basenameOf(path)}.gentle-shell-restore-${process.pid}.tmp`);
-	writeFileSync(tempPath, snapshot.bytes, { mode: snapshot.mode });
-	renameSync(tempPath, path);
+	writeFileAtomically(path, snapshot.bytes, { mode: snapshot.mode });
 	return true;
 }
 
@@ -574,10 +974,7 @@ function restoreManagedAssetDigestField(path, originalText) {
 	if (currentText === undefined) return false;
 	const restoredText = restoreJsonField(originalText, currentText, MANAGED_ASSET_DIGEST_FIELD);
 	if (restoredText === undefined) return false;
-	const mode = statSync(path).mode & 0o777;
-	const tempPath = join(dirname(path), `.${basenameOf(path)}.gentle-shell-restore-${process.pid}.tmp`);
-	writeFileSync(tempPath, restoredText, { mode });
-	renameSync(tempPath, path);
+	writeFileAtomically(path, restoredText);
 	return true;
 }
 
@@ -618,10 +1015,7 @@ function enforceDefaultThemeField(settingsPath, originalSettingsText) {
 		? restoreJsonField(originalSettingsText, currentText, "theme")
 		: forceJsonFieldIfAbsentInOriginal(originalSettingsText, currentText, "theme", DEFAULT_THEME_NAME);
 	if (newText === undefined) return false;
-	const mode = statSync(settingsPath).mode & 0o777;
-	const tempPath = join(dirname(settingsPath), `.${basenameOf(settingsPath)}.gentle-shell-restore-${process.pid}.tmp`);
-	writeFileSync(tempPath, newText, { mode });
-	renameSync(tempPath, settingsPath);
+	writeFileAtomically(settingsPath, newText);
 	return originalHadTheme ? "restored" : "forced";
 }
 
@@ -641,6 +1035,53 @@ function safely(label, path, fallback, fn) {
 	}
 }
 
+// gentle-pi replaces Pi's replaceable builtin codemode with its own decorated
+// codemode tool (extensions/quiet-tools.ts -> registerCompactCodemode in
+// lib/codemode-renderer.ts), and Pi prints a startup warning whenever a
+// builtin loses its tool to another extension. Pi's only per-builtin opt-out
+// is a `-builtin:<name>` entry in the settings `extensions` array, so every
+// normal launch ensures that entry in the settings.json of a home
+// gentle-shell owns (see main, below).
+const BUILTIN_CODEMODE_EXTENSION = "builtin:codemode";
+
+// Pure: returns `settingsText` with `-<builtin>` appended to its `extensions`
+// array (created when absent), or undefined when nothing should change — the
+// text does not parse as a JSON object, `extensions` exists but is not an
+// array, or the array already holds any explicit entry for the builtin
+// (`+`, `-`, `!`, or bare), which is the user's own decision. Keeps every
+// other key and entry in place, plus the text's own indentation and trailing
+// newline (same detection as detectJsonFormatting in
+// lib/gentle-shell-launcher.ts).
+function withBuiltinExtensionExcluded(settingsText, builtin) {
+	let settings;
+	try {
+		settings = JSON.parse(settingsText);
+	} catch {
+		return undefined;
+	}
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return undefined;
+	const extensions = Object.prototype.hasOwnProperty.call(settings, "extensions") ? settings.extensions : [];
+	if (!Array.isArray(extensions)) return undefined;
+	if (extensions.some((entry) => typeof entry === "string" && entry.replace(/^[+!-]/, "") === builtin)) return undefined;
+	const indent = settingsText.match(/\{\r?\n([ \t]+)/)?.[1];
+	const serialized = JSON.stringify({ ...settings, extensions: [...extensions, `-${builtin}`] }, null, indent);
+	return settingsText.endsWith("\n") ? `${serialized}\n` : serialized;
+}
+
+// Applies withBuiltinExtensionExcluded to an existing settings.json with the
+// same atomic temp-file-then-rename write as the restores above. A missing
+// settings.json is left missing: only the brand-new-home bootstrap
+// (installIsolatedTuiModeSetting) seeds that file, and this launch-time step
+// never takes over that role. Returns true when it actually wrote the file.
+function ensureBuiltinCodemodeExcluded(settingsPath) {
+	const currentText = readJsonIfExists(settingsPath);
+	if (currentText === undefined) return false;
+	const newText = withBuiltinExtensionExcluded(currentText, BUILTIN_CODEMODE_EXTENSION);
+	if (newText === undefined) return false;
+	writeFileAtomically(settingsPath, newText);
+	return true;
+}
+
 // Provisions `home` with everything `gentle-ai install --agent pi` installs
 // into a regular Pi, by spawning the package-local pinned gentle-ai binary
 // (never a PATH `gentle-ai`) with PI_CODING_AGENT_DIR/GENTLE_PI_AGENT_HOME set
@@ -682,10 +1123,24 @@ async function runSetupFlow(home, runtime, { dryRun, stdio, timeoutMs }) {
 
 	process.stderr.write(`gentle-shell: provisioning ${home.dir} with the gentle-ai companion packages\n`);
 
+	if (bundledInstall && !dryRun) {
+		const engram = await ensureBundledEngram();
+		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
+	// 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) {
+		bundledMemory = await classifyBundledMemory();
+		bundledEnv = bundledProcessEnv();
+		if (bundledMemory.notice) process.stderr.write(`gentle-shell: ${bundledMemory.notice}\n`);
+	}
+
 	const setupArgs = ["install", "--agent", "pi", "--scope", "global", ...(dryRun ? ["--dry-run"] : [])];
-	const env = buildSetupEnv(home, runtime);
-	const personaPath = sharedPersonaPath();
-	const personaSnapshot = safely("snapshot your Pi persona file", personaPath, undefined, () => snapshotFile(personaPath));
+	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))]);
 	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
@@ -702,8 +1157,11 @@ async function runSetupFlow(home, runtime, { dryRun, stdio, timeoutMs }) {
 	try {
 		installResult = await spawnAndWait(binaryPath, setupArgs, env, stdio, timeoutMs);
 	} finally {
-		if (personaSnapshot !== undefined && safely("restore your Pi persona file", personaPath, false, () => restoreFile(personaSnapshot))) {
-			process.stderr.write(`gentle-shell: kept your Pi persona unchanged (gentle-ai rewrote ${personaPath}; tracked upstream)\n`);
+		if (piLauncherDir) rmSync(piLauncherDir, { recursive: true, force: true });
+		for (const [personaPath, personaSnapshot] of personaSnapshots) {
+			if (personaSnapshot !== undefined && safely("restore your Pi persona file", personaPath, false, () => restoreFile(personaSnapshot))) {
+				process.stderr.write(`gentle-shell: kept your Pi persona unchanged (gentle-ai rewrote ${personaPath}; tracked upstream)\n`);
+			}
 		}
 		if (safely("restore your Gentle AI managed-asset record", statePath, false, () => restoreManagedAssetDigestField(statePath, originalStateText))) {
 			process.stderr.write(
@@ -725,7 +1183,63 @@ async function runSetupFlow(home, runtime, { dryRun, stdio, timeoutMs }) {
 	}
 	if (!installResult.ok) return installResult;
 
-	return runPostInstallCleanup(home, runtime, dryRun, stdio, timeoutMs);
+	const cleanupResult = await runPostInstallCleanup(home, runtime, dryRun, stdio, timeoutMs);
+	if (cleanupResult.ok && !dryRun) {
+		warnDisabledMCP(home);
+		// The guard and policy protect memory, so the companion check only warns.
+		const companion = bundledInstall ? await ensureEngramCompanion(home, runtime, stdio, timeoutMs) : { ok: true };
+		if (!companion.ok) process.stderr.write(`${companion.message}\n`);
+	}
+	return cleanupResult;
+}
+
+function mcpAdapterActivity(packages) {
+	if (typeof packages === "string") return packages === "npm:pi-mcp-adapter" || packages.startsWith("npm:pi-mcp-adapter@") ? "active" : "inactive";
+	if (Array.isArray(packages)) {
+		const activities = packages.map(mcpAdapterActivity);
+		return activities.includes("active") ? "active" : activities.includes("unknown") ? "unknown" : "inactive";
+	}
+	if (packages === null || typeof packages !== "object") return "inactive";
+	if (typeof packages.source !== "string") return mcpAdapterActivity(Object.keys(packages));
+	if (mcpAdapterActivity(packages.source) === "inactive") return "inactive";
+	const patterns = packages.extensions;
+	if (patterns === undefined) return packages.autoload === false ? "inactive" : "active";
+	if (!Array.isArray(patterns)) return "unknown";
+	if (patterns.length === 0) return "inactive";
+	if (packages.autoload === false) {
+		return patterns.some(pattern => typeof pattern === "string" && !pattern.startsWith("!") && !pattern.startsWith("-")) ? "unknown" : "inactive";
+	}
+	// Ordinary exclusions run after includes, but exact +path entries can
+	// restore resources. Other filters need actual package files to resolve.
+	if (patterns.includes("!**") && !patterns.some(pattern => typeof pattern === "string" && pattern.startsWith("+"))) return "inactive";
+	return "unknown";
+}
+
+// Onboarding cannot prove who disabled MCP: diagnose, never re-enable servers.
+// This also covers automatic provisioning because both routes share setup.
+function warnDisabledMCP(home) {
+	const settingsPath = join(home.dir, "settings.json");
+	const mcpPath = join(home.dir, "mcp.json");
+	let inspecting = settingsPath;
+	try {
+		const settingsText = readJsonIfExists(settingsPath);
+		if (settingsText === undefined) return;
+		const settings = JSON.parse(settingsText);
+		if (!Array.isArray(settings?.extensions) || !settings.extensions.includes("-builtin:mcp")) return;
+		const activity = mcpAdapterActivity(settings.packages);
+		if (activity === "active") return;
+		inspecting = mcpPath;
+		const mcpText = readJsonIfExists(mcpPath);
+		if (mcpText === undefined) return;
+		const servers = JSON.parse(mcpText)?.mcpServers;
+		if (servers === null || typeof servers !== "object" || Array.isArray(servers) || Object.keys(servers).length === 0) return;
+		const diagnosis = activity === "unknown"
+			? `pi-mcp-adapter activity cannot be confirmed from its extension filters, so servers in ${mcpPath} may not load`
+			: `pi-mcp-adapter is absent or inactive, so servers in ${mcpPath} will not load`;
+		process.stderr.write(`gentle-shell: WARNING: Pi built-in MCP is disabled in ${settingsPath}; ${diagnosis}. If you want these servers enabled, remove -builtin:mcp from extensions in ${settingsPath}, then restart Pi. If MCP is intentionally disabled, keep the setting.\n`);
+	} catch (error) {
+		process.stderr.write(`gentle-shell: WARNING: Pi MCP configuration could not be inspected in ${inspecting}: ${error.message}; inspect or repair it manually.\n`);
+	}
 }
 
 // The stderr line printed once `source` is actually removed from `home`.
@@ -805,7 +1319,11 @@ async function removePostInstallSources(sources, index, home, runtime, stdio, ti
 // --dry-run, runs the shared flow with the child's stdio inherited (today's
 // behavior, unchanged), then exits with its result — this is the one place
 // that keeps the pre-S7 exit semantics `handleSetupCommand` always had.
-async function handleSetupCommand(commandArgs, home, runtime) {
+// A successful real run records the home exactly as auto-provisioning does
+// (#2106: both installers finish with this command, and the first launch
+// must not install the packages again), but only for a home auto-provisioning
+// itself would own: never pi's own default home or an unrelated directory.
+async function handleSetupCommand(commandArgs, home, runtime, { homeHadContentBeforeBootstrap }) {
 	let dryRun = false;
 	for (const arg of commandArgs) {
 		if (arg === "--dry-run") {
@@ -817,6 +1335,19 @@ async function handleSetupCommand(commandArgs, home, runtime) {
 
 	const result = await runSetupFlow(home, runtime, { dryRun, stdio: "inherit" });
 	if (!result.ok && result.message !== undefined) process.stderr.write(`${result.message}\n`);
+	if (result.ok && !dryRun && (home.mode === "isolated" || home.mode === "path")) {
+		const configPath = resolveConfigPath();
+		const homeKey = safeRealpath(home.dir);
+		const config = readRawConfig(configPath);
+		if (!homeIsForeign(home, provisionedEntry(config, homeKey), homeHadContentBeforeBootstrap)) {
+			try {
+				writeRawConfig(configPath, recordProvisioned(config, homeKey, resolveSetupGentleAiPin(), ownPackageVersion(), new Date().toISOString()));
+			} catch (error) {
+				// Setup itself succeeded; the next launch only sets the home up again.
+				process.stderr.write(`gentle-shell: could not record the setup in ${configPath} (${error.message})\n`);
+			}
+		}
+	}
 	process.exit(result.exitCode);
 }
 
@@ -1043,29 +1574,268 @@ async function maybeAutoProvisionHome(home, runtime, { homeHadContentBeforeBoots
 	}
 }
 
+// The adapters `upgrade` and `self-uninstall` run npm and pnpm with: { fs, which, run, invocation? }.
+async function packageManagerAdapters() {
+	const { hostAdapters } = await import("../scripts/installer-probes.mjs");
+	const { upgradeInvocation } = await import("../scripts/installer-runner.mjs");
+	const { run, fs: probeFs } = hostAdapters();
+	// Windows: npm and pnpm are .cmd shims; run what they run, never through cmd.exe.
+	const invocation = upgradeInvocation({ platform: process.platform, env: process.env, run, fs: probeFs });
+	return {
+		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 }),
+	};
+}
+
+// `gentle-shell upgrade`: runs before any Pi runtime check, since it may replace this package.
+// On release, a global pnpm or npm install moves to the bundled one when the
+// latest release publishes its assets (S4), with one question about the old package.
+async function handleUpgradeCommand(commandArgs) {
+	const { MainChannelError, runUpgrade } = await import("../scripts/main-channel.mjs");
+	const { fetchDistribution, migrateGlobalShell, windowsPathRegistry } = await import("../scripts/bundled-wizard.mjs");
+	const { askLine } = await import("../runtime/gentle-shell-uninstall.mjs");
+	const managers = await packageManagerAdapters();
+	const out = (line) => process.stdout.write(`${line}\n`);
+	const migrate = ({ latest, owner }) => migrateGlobalShell({
+		latest,
+		currentVersion: ownPackageVersion(),
+		platform: process.platform,
+		arch: process.arch,
+		env: process.env,
+		home: homedir(),
+		interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+		// End of input or Ctrl+C answers No.
+		ask: (question) => askLine(question, { input: process.stdin, output: process.stdout }).catch(() => ""),
+		out,
+		adapters: { owner, distribution: (version) => fetchDistribution({ version }), run: managers.run,
+			...(process.platform === "win32" ? { registry: windowsPathRegistry(process.env) } : {}) },
+	});
+	try {
+		process.exitCode = await runUpgrade({
+			args: commandArgs,
+			ctx: { env: process.env, home: homedir() },
+			platform: process.platform,
+			packageRoot,
+			currentVersion: ownPackageVersion(),
+			adapters: { fetch: globalThis.fetch, ...managers, migrate },
+			out,
+		});
+	} catch (error) {
+		if (error instanceof MainChannelError) fail(`gentle-shell upgrade: ${error.message}`, error.code === "upgrade-usage" ? 2 : 1);
+		throw error;
+	}
+}
+
+// `gentle-shell upgrade` in a bundled install: the latest release installed
+// beside the active version, verified, then `current` switched (two versions
+// kept), or `--rollback` to the kept one. Returns the exit code (a failure is
+// printed, not thrown, so `update --all` can go on); a failure leaves `current`
+// as it was.
+async function handleBundledUpgrade(bundled, commandArgs) {
+	const parsed = parseBundledUpgradeArgs(commandArgs);
+	if ("error" in parsed) fail(`gentle-shell upgrade: ${parsed.error}`, parsed.usage ? 2 : 1);
+	const { prefixLayout, rollbackBundled, upgradeBundled } = await import("../scripts/bundled-install.mjs");
+	const layout = prefixLayout({ platform: process.platform, env: process.env, home: homedir(), root: bundled.root });
+	const out = (line) => process.stdout.write(`${line}\n`);
+	try {
+		if (parsed.action === "rollback") {
+			const { from, to } = await rollbackBundled({ layout, home: homedir(), platform: process.platform, arch: process.arch, env: process.env });
+			out(`Switched Gentle Shell from ${from} to ${to}.`);
+			return 0;
+		}
+		const { fetchDistribution } = await import("../scripts/bundled-wizard.mjs");
+		const { latestRelease } = await import("../scripts/main-channel.mjs");
+		await upgradeBundled({
+			layout,
+			home: homedir(),
+			platform: process.platform,
+			arch: process.arch,
+			env: process.env,
+			adapters: { latest: () => latestRelease(globalThis.fetch), distribution: (version) => fetchDistribution({ version }) },
+			out,
+		});
+		return 0;
+	} catch (error) {
+		process.stderr.write(`gentle-shell upgrade: ${error.message}${error.stderr ? `\n${error.stderr}` : ""}\n`);
+		return 1;
+	}
+}
+
+// The bundled npm as the `npmCommand` of a home Gentle Shell owns (the isolated
+// home, or a --home it created or provisioned; never --link or a foreign home),
+// so Pi installs packages with our npm while its tools keep the user's PATH.
+// Only that key is written, and only when it differs.
+async function ensureBundledNpmCommand(bundled, 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 { bundledNpmCommand, ensureNpmShim, prefixLayout } = await import("../scripts/bundled-install.mjs");
+	const layout = prefixLayout({ platform: process.platform, env: process.env, home: homedir(), root: bundled.root });
+	// The entry npmCommand names, also for a runtime installed before it existed.
+	ensureNpmShim(layout);
+	const settingsPath = join(home.dir, "settings.json");
+	const edit = withBundledNpmCommand(readJsonIfExists(settingsPath), bundledNpmCommand(layout));
+	if (edit.status === "malformed") {
+		process.stderr.write(`gentle-shell: ${settingsPath} is not a JSON object, so Pi's package installs use the npm on your PATH\n`);
+	} else if (edit.status === "write") {
+		writeFileAtomically(settingsPath, edit.text);
+	}
+}
+
+// `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.
+async function handleBundledSelfUninstall(bundled, commandArgs) {
+	const { askLine, runBundledSelfUninstall } = await import("../runtime/gentle-shell-uninstall.mjs");
+	const { describePathReceipt, prefixLayout, readPathReceipt, removePathEntry, scheduleWindowsRemoval } = await import("../scripts/bundled-install.mjs");
+	const windows = process.platform === "win32";
+	const layout = prefixLayout({ platform: process.platform, env: process.env, home: homedir(), root: bundled.root });
+	// Trusted only for the link or startup file the PATH plan can choose for this user.
+	const receipt = readPathReceipt(layout, { env: process.env, home: homedir() });
+	let pathEntry = receipt;
+	if (receipt.status === "recorded") {
+		const registry = windows ? (await import("../scripts/bundled-wizard.mjs")).windowsPathRegistry(process.env) : undefined;
+		pathEntry = { status: "recorded", description: describePathReceipt(receipt.receipt), remove: () => removePathEntry(receipt.receipt, { registry }) };
+	}
+	return runBundledSelfUninstall({
+		args: commandArgs,
+		env: process.env,
+		homedir: homedir(),
+		platform: process.platform,
+		interactive: process.stdin.isTTY === true,
+		root: bundled.root,
+		pathEntry,
+		process: { pid: process.pid, execPath: process.execPath },
+		...(windows ? { deferRemoval: (request) => scheduleWindowsRemoval({ ...request, env: process.env }) } : {}),
+		ask: (question) => askLine(question, { input: process.stdin, output: process.stdout }),
+		out: (line) => process.stdout.write(`${line}\n`),
+		err: (line) => process.stderr.write(`${line}\n`),
+	});
+}
+
+// `gentle-shell self-uninstall`: like upgrade, runs before any Pi runtime check,
+// so it also works when pi is missing.
+async function handleSelfUninstallCommand(commandArgs) {
+	const { askLine, runSelfUninstall } = await import("../runtime/gentle-shell-uninstall.mjs");
+	const { ownerManager } = await import("../scripts/main-channel.mjs");
+	const managers = await packageManagerAdapters();
+	const ctx = { env: process.env, home: homedir() };
+	process.exitCode = await runSelfUninstall({
+		args: commandArgs,
+		env: process.env,
+		homedir: homedir(),
+		platform: process.platform,
+		interactive: process.stdin.isTTY === true,
+		resolveOwner: () => ownerManager({ ctx, platform: process.platform, packageRoot, adapters: managers, command: "uninstall" }),
+		run: (command, argv) => managers.run(command, argv),
+		ask: (question) => askLine(question, { input: process.stdin, output: process.stdout }),
+		out: (line) => process.stdout.write(`${line}\n`),
+		err: (line) => process.stderr.write(`${line}\n`),
+	});
+}
+
+// Before Pi exists: only the bundled interactive opening may offer an update.
+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. */ }
+	const { latestRelease } = await import("../scripts/main-channel.mjs");
+	const offer = await findStartupUpdate({ current: ownPackageVersion(), skipped,
+		lookup: (signal) => latestRelease((url, options) => fetch(url, { ...options, signal })) });
+	if (!offer) return undefined;
+	let choice;
+	try { choice = await promptStartupUpdate(offer, { color: process.stdout.hasColors?.() === true }); }
+	catch { return undefined; }
+	return applyStartupChoice(choice, {
+		omit: () => omitStartupVersion(() => readJsonIfExists(configPath), (text) => {
+			mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+			writeFileAtomically(configPath, text, { mode: 0o600 });
+		}, offer.latest),
+		warn: (message) => process.stderr.write(`gentle-shell: ${message}\n`),
+		upgrade: () => handleBundledUpgrade(bundled, []),
+		relaunch: async () => {
+			const next = await resolveStartupRelaunch({ root: bundled.root, home: homedir(), platform: process.platform,
+				env: process.env, argv: process.argv.slice(2) });
+			return new Promise((resolve, reject) => {
+				const child = spawn(next.command, next.args, { stdio: "inherit", env: next.env, shell: false });
+				const forwards = ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => {
+					const handler = () => child.kill(signal);
+					process.on(signal, handler);
+					return [signal, handler];
+				});
+				const cleanup = () => { for (const [signal, handler] of forwards) process.off(signal, handler); };
+				child.once("error", (error) => { cleanup(); reject(error); });
+				child.once("exit", (code, signal) => { cleanup(); resolve(signal ? signalExitCode(signal) : (code ?? 1)); });
+			});
+		},
+	});
+}
+
 async function main() {
+	// One launch only: never leak the update handoff opt-out into Pi or its tools.
+	const startupEnv = { ...process.env };
+	delete process.env.GENTLE_SHELL_SKIP_STARTUP_UPDATE;
 	const args = parseLauncherArgs(process.argv.slice(2));
 	if (args.error !== undefined) fail(`${args.error}\nRun 'gentle-shell --help' for usage.`, 2);
 	if (args.help) {
-		process.stdout.write(`${helpText()}\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. Back up data, update Engram, restart its server and Shell, then recheck.\nAn explicit ENGRAM_BIN or ENGRAM_URL is kept and bypasses the guard.\n`);
 		process.exit(0);
 	}
 	if (args.command === "home") {
 		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 === "upgrade") {
+		if (bundled) process.exitCode = await handleBundledUpgrade(bundled, args.commandArgs);
+		else await handleUpgradeCommand(args.commandArgs);
+		return;
+	}
+	if (args.command === "self-uninstall") {
+		if (bundled) process.exitCode = await handleBundledSelfUninstall(bundled, args.commandArgs);
+		else await handleSelfUninstallCommand(args.commandArgs);
+		return;
+	}
+
+	const startupCode = await startupUpdate(bundled, args, startupEnv);
+	if (startupCode !== undefined) {
+		process.exitCode = startupCode;
+		return;
+	}
 
 	const config = loadConfig();
 	let home = resolveHome({ args, env: process.env, homedir: homedir(), config });
 	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
 
-	const runtime = resolvePiRuntime({
-		env: process.env,
-		resolveBundledCli,
-		findOnPath,
-		nodeExecPath: process.execPath,
-	});
-	if (runtime === undefined) fail(missingPiMessage(), 1);
+	// Version and help runs (Shell's own or forwarded to Pi) never probe Engram,
+	// ensure the companion, print memory notices or touch provenance.
+	const engramQuiet = args.version || piVersionOrHelpRequested(args.passthrough);
+	let runtime;
+	if (bundled) {
+		// S8: only the version's own Pi, never GENTLE_SHELL_PI, an adjacent fallback or PATH.
+		const pi = bundledPi(bundled, { platform: process.platform, fs: bundledFs });
+		if (!pi.ok) fail(pi.message, 1);
+		runtime = { kind: "bundled", command: process.execPath, args: [pi.cli] };
+		bundledInstall = bundled;
+		bundledCli = pi.cli;
+		bundledMemory = engramQuiet ? { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE } : await classifyBundledMemory();
+		bundledEnv = bundledProcessEnv();
+		bundledSetupDirs = [dirname(process.execPath), join(bundled.versionDir, "node_modules", ".bin")];
+	} else {
+		runtime = resolvePiRuntime({
+			env: process.env,
+			resolveBundledCli,
+			findOnPath,
+			nodeExecPath: process.execPath,
+		});
+		if (runtime === undefined) fail(missingPiMessage(), 1);
+	}
 
 	const versionProbePlan = planSpawn({ command: runtime.command, args: [...runtime.args, "--version"], platform: process.platform });
 	const versionProbe = spawnSync(versionProbePlan.command, versionProbePlan.args, {
@@ -1073,6 +1843,7 @@ async function main() {
 		timeout: 15000,
 		encoding: "utf8",
 		shell: versionProbePlan.shell,
+		env: bundledEnv ?? process.env,
 	});
 	if (versionProbe.error) fail(`Could not run the pi runtime at "${runtime.command}": ${versionProbe.error.message}`, 1);
 	const versionCheck = checkPiVersion(versionProbe.stdout ?? "");
@@ -1083,6 +1854,23 @@ async function main() {
 		process.exit(0);
 	}
 
+	// S5: in a bundled install Pi updates only with Gentle Shell, so Pi's own
+	// update becomes `gentle-shell upgrade` (run when interactive, named
+	// otherwise); package updates still reach Pi.
+	let passthrough = args.passthrough;
+	if (bundled && args.piSubcommand === "update") {
+		const plan = bundledUpdatePlan(args.passthrough);
+		if (plan.self) {
+			const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+			for (const line of bundledUpdateNotice({ piVersion: versionCheck.version, interactive })) process.stdout.write(`${line}\n`);
+			const code = interactive ? await handleBundledUpgrade(bundled, []) : undefined;
+			const next = bundledUpdateNext(plan, code);
+			if ("exitCode" in next) process.exit(next.exitCode);
+			if (next.note) process.stderr.write(`${next.note}\n`);
+		}
+		passthrough = plan.piArgs;
+	}
+
 	// Home-ownership signal for auto-provisioning (S9, homeIsForeign): must be
 	// read before the isolated-home bootstrap below creates and seeds a
 	// brand-new --home directory with its own settings.json — after that
@@ -1100,14 +1888,24 @@ 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)) {
-		mkdirSync(home.dir, { recursive: true });
+		// 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`);
 	}
 
+	if (bundled) {
+		try {
+			await ensureBundledNpmCommand(bundled, home, homeHadContentBeforeBootstrap);
+		} catch (error) {
+			process.stderr.write(`gentle-shell: could not give Pi the bundled npm in ${join(home.dir, "settings.json")} (${error.message}); continuing\n`);
+		}
+	}
+
 	if (args.command === "setup") {
-		await handleSetupCommand(args.commandArgs, home, runtime);
+		await handleSetupCommand(args.commandArgs, home, runtime, { homeHadContentBeforeBootstrap });
 		return;
 	}
 
@@ -1139,6 +1937,21 @@ async function main() {
 		// exits with the same signal-derived code instead of falling through
 		// to launch pi.
 		if (autoProvisionResult !== undefined) process.exit(autoProvisionResult.exitCode);
+
+		// Runs after auto-provision, so it sees settings.json exactly as that
+		// run left it. Only a home gentle-shell owns, by the same rule
+		// auto-provisioning uses (homeIsForeign): never --link (excluded above),
+		// a foreign --home, or pi's own default agent home, since plain pi may
+		// share those and would lose its builtin codemode. `setup` (including
+		// --dry-run) returned before this point.
+		const settingsPath = join(home.dir, "settings.json");
+		const excluded = safely("exclude Pi's builtin codemode in your Gentle Shell settings", settingsPath, false, () => {
+			const previous = provisionedEntry(readRawConfig(resolveConfigPath()), safeRealpath(home.dir));
+			return !homeIsForeign(home, previous, homeHadContentBeforeBootstrap) && ensureBuiltinCodemodeExcluded(settingsPath);
+		});
+		if (excluded) {
+			process.stderr.write(`gentle-shell: disabled Pi's builtin codemode in ${settingsPath} (Gentle Shell ships its own codemode tool)\n`);
+		}
 	}
 
 	const packageRootExplicit = args.packageRoot !== undefined;
@@ -1220,6 +2033,23 @@ 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.
+		if (args.piSubcommand === undefined && !engramQuiet) {
+			bundledMemory = await classifyBundledMemory();
+			bundledEnv = bundledProcessEnv();
+			// The guard protects memory whatever provider loads, so a companion that
+			// 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 };
+			if (bundledMemory.notice) process.stderr.write(`gentle-shell: ${bundledMemory.notice}\n`);
+		}
+		bundledEnv = bundledProcessEnv();
+	}
 	const invocation = buildPiInvocation({
 		runtime,
 		home,
@@ -1228,22 +2058,98 @@ async function main() {
 		takeOver,
 		otherPackagePaths,
 		looseExtensionEntries,
-		passthrough: args.passthrough,
+		passthrough: [...managedHerdrExtensionArgs(home, args), ...passthrough],
 		piSubcommand: args.piSubcommand,
-		baseEnv: process.env,
+		baseEnv: bundledEnv ?? process.env,
+		homedir: homedir(),
+		// The spawn below sets no cwd, so pi runs in the launcher's own.
+		cwd: process.cwd(),
 	});
 
+	// Only an interactive session ends with pi's exit resume hint, which
+	// gentle-shell completes with its own line; a pi subcommand gets no handoff.
+	const resumeHandoff = args.piSubcommand === undefined ? createResumeHandoff() : undefined;
+	const childEnv = resumeHandoff ? { ...invocation.env, [RESUME_HANDOFF_ENV]: resumeHandoff.path } : invocation.env;
+
 	const launchPlan = planSpawn({ command: invocation.command, args: invocation.args, platform: process.platform });
-	const child = spawn(launchPlan.command, launchPlan.args, { stdio: "inherit", env: invocation.env, shell: launchPlan.shell });
+	let child;
+	try {
+		child = spawn(launchPlan.command, launchPlan.args, { stdio: "inherit", env: childEnv, shell: launchPlan.shell });
+	} catch (error) {
+		resumeHandoff?.dispose();
+		throw error;
+	}
+	// Only SIGHUP means the terminal is gone. pi may survive a forwarded
+	// SIGINT and keep running, so other signals must not silence the hint.
+	let terminalHungUp = false;
 	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-		process.on(signal, () => child.kill(signal));
+		process.on(signal, () => {
+			if (signal === "SIGHUP") terminalHungUp = true;
+			child.kill(signal);
+		});
 	}
-	child.on("error", (error) => fail(`Could not start pi: ${error.message}`, 1));
+	child.on("error", (error) => {
+		resumeHandoff?.dispose();
+		fail(`Could not start pi: ${error.message}`, 1);
+	});
 	child.on("exit", (code, signal) => {
-		process.exit(signal ? signalExitCode(signal) : (code ?? 1));
+		const exitCode = signal ? signalExitCode(signal) : (code ?? 1);
+		if (resumeHandoff) {
+			const hint = planResumeHint({
+				handoff: resumeHandoff.read(),
+				homeFlags: homeSelectorFlags(home),
+				stdoutIsTTY: process.stdout.isTTY === true,
+				terminalHungUp,
+				platform: process.platform,
+				color: process.stdout.hasColors?.() === true,
+			});
+			resumeHandoff.dispose();
+			// TTY writes are asynchronous on Windows: exit only once the
+			// hint is flushed, or it can be lost.
+			if (hint) {
+				// A write error (e.g. EIO on a closed terminal) must not turn
+				// pi's exit into a launcher crash.
+				process.stdout.once("error", () => process.exit(exitCode));
+				process.stdout.write(hint, () => process.exit(exitCode));
+				return;
+			}
+		}
+		process.exit(exitCode);
 	});
 }
 
+// Private temp dir for the resume-hint handoff (lib/gentle-shell-resume-hint.ts).
+// Best effort: if it cannot be created, only pi's own hint is printed.
+function createResumeHandoff() {
+	let dir;
+	try {
+		dir = mkdtempSync(join(tmpdir(), RESUME_HANDOFF_DIR_PREFIX));
+	} catch {
+		return undefined;
+	}
+	const path = join(dir, RESUME_HANDOFF_FILE);
+	return {
+		path,
+		read: () => {
+			try {
+				const text = readJsonIfExists(path);
+				return text === undefined ? undefined : parseResumeHandoff(text);
+			} catch {
+				return undefined;
+			}
+		},
+		// Never throws: it runs inside the exit handler, where an EPERM on
+		// Windows would otherwise replace pi's exit code with a crash.
+		dispose: () => {
+			try {
+				rmSync(dir, { recursive: true, force: true });
+			} catch {
+				// A leftover empty temp dir is harmless.
+			}
+		},
+	};
+}
+
 main().catch((error) => {
 	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
 	process.exit(1);