gentle-pi 4.2.0 → 4.4.0

package/lib/yolo-session-policy.ts

@@ -10,6 +10,12 @@ export const AUTO_MODE_NOTICE = "Auto uses additional model calls with separate
 
 export const YOLO_STATUS_KEY = "gentle:yolo";
 export const YOLO_STATUS_TEXT = "🚀 YOLO ON 🔥 — destructive confirmations remain";
+export const SUPER_YOLO_STATUS_TEXT = "💥 SUPER YOLO ON — no permission prompts; private paths stay blocked";
+export const SUPER_YOLO_DIRECTIVE = `<gentle-super-yolo-session>
+SUPER YOLO session standing permission is ON, authorized by the human for this live primary session and canonical workspace. No permission questions are asked in this mode: proceed through ordinary and destructive shell work (including rm, resets, force operations and configured-guard confirmations) without confirmation dialogs, and make implementation and delivery choices directly.
+The ONLY hard line is private material: never read, print, copy, transmit or commit secrets or private credentials — .env files, .ssh, keychains, *.pem/*.key/*.p12/*.pfx, secrets/ directories, cloud credential files. If a task seems to need them, stop and ask the human.
+This does NOT override explicit human restrictions in the live conversation, and never auto-answers ask_user tools, provider consent, maintenance/recovery authorization or opaque-token decisions. Children remain bounded by their delegated task; they receive no independent delivery grant or Super Yolo inheritance.
+</gentle-super-yolo-session>`;
 export const YOLO_DIRECTIVE = `<gentle-yolo-session>
 YOLO session standing permission is ON, authorized by the human for this live primary session and canonical workspace (directly or through a trusted global default).
 Qualify the default commit, push and PR confirmation clauses: for ordinary already-scoped implementation, checks, commits, non-force pushes and PR creation, this activation supplies standing permission instead of repeated permission questions. Make ordinary reversible implementation choices without needless interviews.
@@ -40,12 +46,14 @@ export class YoloSessionPolicy {
 	}
 }
 
-/** Remove our exact block as well as adding it: bridge options can be reused. */
-export function updateYoloPrompt(options: AppendableSystemPromptOptions | null | undefined, active: boolean): void {
+/** Remove our exact blocks as well as adding them: bridge options can be reused. */
+export function updateYoloPrompt(options: AppendableSystemPromptOptions | null | undefined, active: boolean, superActive = false): void {
 	if (!options) return;
 	options.appendSystemPrompt = (options.appendSystemPrompt ?? "")
-		.replace(`\n\n${YOLO_DIRECTIVE}`, "").replace(YOLO_DIRECTIVE, "");
-	if (active) appendSystemPromptOnce(options, YOLO_DIRECTIVE);
+		.replace(`\n\n${YOLO_DIRECTIVE}`, "").replace(YOLO_DIRECTIVE, "")
+		.replace(`\n\n${SUPER_YOLO_DIRECTIVE}`, "").replace(SUPER_YOLO_DIRECTIVE, "");
+	if (superActive) appendSystemPromptOnce(options, SUPER_YOLO_DIRECTIVE);
+	else if (active) appendSystemPromptOnce(options, YOLO_DIRECTIVE);
 }
 const HUMAN_ACTION = { on: "on", off: "off", toggle: "" } as const;
 type HumanAction = (typeof HUMAN_ACTION)[keyof typeof HUMAN_ACTION];
@@ -86,7 +94,8 @@ export function discoverYoloUiAdapter(pi: ExtensionAPI, context: ExtensionContex
 }
 export interface YoloSessionController {
 	active(context: ExtensionContext): Promise<boolean>;
-	mode(context: ExtensionContext): Promise<PermissionMode>;
+	superActive(context: ExtensionContext): Promise<boolean>;
+	mode(context: ExtensionContext, admission?: { toolCallId: string }): Promise<PermissionMode>;
 	setMode(mode: PermissionMode, context: ExtensionContext): Promise<boolean>;
 	defaultMode(): PermissionMode;
 	saveDefault(mode: PermissionMode, context: ExtensionContext): Promise<boolean>;
@@ -101,7 +110,7 @@ interface ModeIdentity {
 }
 /** UI/slash authoring only. Defaults are read from the dedicated trusted user store. */
 export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessEnv,
-	options: { onChange?: () => void } = {}): YoloSessionController {
+	options: { onChange?: () => void; resolveIdentity?: typeof resolveCanonicalGitRepositoryIdentity } = {}): YoloSessionController {
 	const store = { gentlePiConfigHome: gentlePiConfigHome(env) };
 	let generation = 0;
 	let ownerGeneration = 0;
@@ -112,6 +121,15 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 	const seen = new WeakMap<object, Set<string>>();
 	const observers = new Set<() => void>();
 	const pendingCaptures = new Set<{ manager: ModeIdentity["manager"]; id: string }>();
+	// Identity is re-captured for every tool admission: freshness is a security
+	// invariant, so cross-admission reuse is never allowed (a mid-lookup mode
+	// reselection must invalidate). Within one admission the redundant mode()
+	// lookups of the same tool call share at most ONE capture, keyed by that
+	// admission's tool call id; a different or absent id re-captures, and a
+	// generation bump or cwd change still invalidates a shared slot.
+	let capturedMode: (ModeIdentity & { cwd: string; generation: number; admission: string }) | undefined;
+	// Rendered strings last published for each context; identical repaints are skipped.
+	const published = new WeakMap<ExtensionContext, { yolo: string | undefined; modeText: string }>();
 	const primary = () => env.GENTLE_PI_AGENTS_CHILD !== "1";
 	const interactive = (ctx: ExtensionContext): boolean => {
 		if (!primary() || !ctx.hasUI) return false;
@@ -129,10 +147,15 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 		const ids = seen.get(scope.manager) ?? new Set<string>(); ids.add(scope.id); seen.set(scope.manager, ids);
 	};
 	const publish = (ctx: ExtensionContext): void => {
-		const yolo = liveMode === "yolo";
-		try { ctx.ui.setStatus(YOLO_STATUS_KEY, yolo ? YOLO_STATUS_TEXT : undefined); } catch { /* display only */ }
-		try { ctx.ui.setWidget(YOLO_STATUS_KEY, yolo ? [YOLO_STATUS_TEXT] : undefined); } catch { /* display only */ }
-		try { ctx.ui.setStatus(MODE_STATUS_KEY, `Permissions: ${liveMode.toUpperCase()}`); } catch { /* display only */ }
+		const yolo = liveMode === "yolo" ? YOLO_STATUS_TEXT : liveMode === "super-yolo" ? SUPER_YOLO_STATUS_TEXT : undefined;
+		const modeText = `Permissions: ${liveMode.toUpperCase()}`;
+		const previous = published.get(ctx);
+		if (previous && previous.yolo === yolo && previous.modeText === modeText) return;
+		let painted = true;
+		try { ctx.ui.setStatus(YOLO_STATUS_KEY, yolo); } catch { painted = false; /* display only */ }
+		try { ctx.ui.setWidget(YOLO_STATUS_KEY, yolo ? [yolo] : undefined); } catch { painted = false; /* display only */ }
+		try { ctx.ui.setStatus(MODE_STATUS_KEY, modeText); } catch { painted = false; /* display only */ }
+		if (painted) published.set(ctx, { yolo, modeText });
 	};
 	const changed = (ctx: ExtensionContext): void => {
 		generation += 1; publish(ctx);
@@ -162,17 +185,25 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 		try {
 			const canonical = await realpath(cwd);
 			if (!current()) return undefined;
-			const clone = await resolveCanonicalGitRepositoryIdentity(canonical);
+			const clone = await (options.resolveIdentity ?? resolveCanonicalGitRepositoryIdentity)(canonical);
 			if (!current()) return undefined;
 			return { ...scope, workspace: clone ?? `cwd:${canonical}` };
 		} catch { return undefined; }
 		finally { pendingCaptures.delete(scope); }
 	};
 	const defaultMode = (): PermissionMode => resolvePermissionModePolicy(store).mode;
-	const mode = async (ctx: ExtensionContext): Promise<PermissionMode> => {
-		const epoch = generation;
-		const identity = await capture(ctx);
-		if (epoch !== generation) return "normal";
+	const mode = async (ctx: ExtensionContext, admission?: { toolCallId: string }): Promise<PermissionMode> => {
+		const scope = session(ctx);
+		const admissionId = admission?.toolCallId;
+		let identity: ModeIdentity | undefined;
+		if (admissionId !== undefined && scope && capturedMode &&
+			capturedMode.admission === admissionId && capturedMode.generation === generation &&
+			capturedMode.manager === scope.manager && capturedMode.id === scope.id && capturedMode.cwd === ctx.cwd) identity = capturedMode;
+		if (!identity) {
+			const epoch = generation;
+			identity = await capture(ctx);
+			if (epoch !== generation) return "normal";
+		}
 		if (binding && (!identity || binding.manager !== identity.manager || binding.id !== identity.id ||
 			binding.workspace !== identity.workspace || (interactiveGrant && !interactive(ctx)))) {
 			binding = undefined; liveMode = "normal"; interactiveGrant = false; changed(ctx);
@@ -182,12 +213,17 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 			remember(identity); binding = identity;
 			if (fresh) { liveMode = defaultMode(); interactiveGrant = false; changed(ctx); }
 		}
+		// Record after the binding pass: internal changed() bumps above must not strand
+		// a cache entry stamped with a superseded generation. Only admission-keyed
+		// lookups record; the slot is overwritten when a different admission id arrives.
+		if (identity && scope && admissionId !== undefined) capturedMode = { ...identity, cwd: ctx.cwd, generation, admission: admissionId };
 		publish(ctx);
 		return identity && binding ? liveMode : "normal";
 	};
 	const active = async (ctx: ExtensionContext): Promise<boolean> => await mode(ctx) === "yolo";
+	const superActive = async (ctx: ExtensionContext): Promise<boolean> => await mode(ctx) === "super-yolo";
 	const reset = (ctx: ExtensionContext): void => {
-		ownerGeneration += 1;
+		ownerGeneration += 1; capturedMode = undefined;
 		// Initial session_start remains fresh; shutdown/reload of an observed session revokes.
 		if (binding) remember(binding);
 		const scope = session(ctx);
@@ -228,7 +264,7 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 	};
 	const humanAction = async (action: HumanAction, ctx: ExtensionContext, current = () => true): Promise<boolean> => {
 		if (!current()) return false;
-		const enable = action === HUMAN_ACTION.on || (action === HUMAN_ACTION.toggle && liveMode !== "yolo");
+		const enable = action === HUMAN_ACTION.on || (action === HUMAN_ACTION.toggle && liveMode !== "yolo" && liveMode !== "super-yolo");
 		const pending = setMode(enable ? "yolo" : "normal", ctx, current);
 		const epoch = generation; // setMode revokes synchronously, then publishes once on success.
 		const result = await pending;
@@ -253,7 +289,7 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 				const epoch = generation, value = await mode(ctx);
 				if (!current()) return YOLO_DISPLAY.unavailable;
 				if (epoch !== generation) return read();
-				return binding ? value === "yolo" ? YOLO_DISPLAY.on : YOLO_DISPLAY.off : YOLO_DISPLAY.unavailable;
+				return binding ? value === "yolo" || value === "super-yolo" ? YOLO_DISPLAY.on : YOLO_DISPLAY.off : YOLO_DISPLAY.unavailable;
 			};
 			request.respond({
 				read,
@@ -276,7 +312,7 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 		} catch { /* obsolete trusted context: discovery expires closed */ }
 	});
 	pi.registerCommand("gentle:mode", {
-		description: "Permissions: normal|auto|yolo|status; default normal|auto|yolo saves for new primary sessions.",
+		description: "Permissions: normal|auto|yolo|super-yolo|status; default normal|auto|yolo|super-yolo saves for new primary sessions.",
 		handler: async (args, ctx) => {
 			const words = args.trim().split(/\s+/);
 			if (!args.trim() || args.trim() === "status") {
@@ -290,7 +326,7 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 				else notify(ctx, "Mode unchanged — interactive primary session required or the session changed.", true);
 				return;
 			}
-			notify(ctx, "Use /gentle:mode normal|auto|yolo|status or /gentle:mode default normal|auto|yolo. State unchanged.", true);
+				notify(ctx, "Use /gentle:mode normal|auto|yolo|super-yolo|status or /gentle:mode default normal|auto|yolo|super-yolo. State unchanged.", true);
 		},
 	});
 	pi.registerCommand("gentle:yolo", {
@@ -301,7 +337,7 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 			if (!args.trim() && ctx.hasUI && typeof ctx.ui.select === "function") {
 				current = bindCurrent(ctx);
 				const state = await active(ctx) ? YOLO_DISPLAY.on : YOLO_DISPLAY.off;
-				const selected = await ctx.ui.select(`🚀 Gentle YOLO 🔥 — full speed, destructive actions still ask (current: ${state})`, ["enable", "disable", "status"]);
+				const selected = await ctx.ui.select(`🚀 Gentle YOLO 🔥 — standing permission (current: ${state})`, ["enable", "disable", "status"]);
 				if (selected === undefined) return;
 				action = selected;
 			}
@@ -313,5 +349,5 @@ export function registerYoloSessionPolicy(pi: ExtensionAPI, env: NodeJS.ProcessE
 			notify(ctx, "YOLO unchanged — the session changed while the menu was open.", true);
 		},
 	});
-	return { active, mode, setMode, defaultMode, saveDefault, epoch: () => generation, humanAction, reset };
+	return { active, superActive, mode, setMode, defaultMode, saveDefault, epoch: () => generation, humanAction, reset };
 }

package/lib/yolo-temp-scratch.ts

@@ -0,0 +1,69 @@
+// YOLO temp-scratch waiver: a recursive `rm` whose every literal target is the
+// session's own scratch under a temp root needs no data-loss confirmation.
+// Pure over an injectable filesystem view so tests never touch real paths.
+// Callers own the policy gate: primary session with active YOLO only.
+import { lstatSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { posix } from "node:path";
+import type { DestructiveCommandMatch } from "./destructive-command-guard.ts";
+
+export interface TempScratchStat {
+	uid: number;
+	isDirectory(): boolean;
+	isFile(): boolean;
+	isSymbolicLink(): boolean;
+}
+
+export interface TempScratchFs {
+	/** Throws an error with code `ENOENT` when the path is missing. */
+	lstat(path: string): TempScratchStat;
+	/** Current process uid; undefined where POSIX ownership is unavailable. */
+	uid: number | undefined;
+	/** Resolved `os.tmpdir()`, when resolvable. */
+	tmpdir: string | undefined;
+	home: string;
+}
+
+const FIXED_TEMP_ROOTS = ["/tmp", "/var/tmp"];
+const MKTEMP_NAME_RE = /^tmp\.[A-Za-z0-9]{6,}$/;
+// A closed character set: expansion, quoting, glob, brace and redirection
+// characters (`$`, backtick, `~`, `*?[{`, quotes, `<>`) make the shell
+// target differ from the text or add a write elsewhere.
+const LITERAL_PATH_RE = /^\/[A-Za-z0-9._@%+=:,/-]*$/;
+
+export function defaultTempScratchFs(): TempScratchFs {
+	let resolvedTmpdir: string | undefined;
+	try { resolvedTmpdir = realpathSync(tmpdir()); } catch { resolvedTmpdir = undefined; }
+	return { lstat: (path) => lstatSync(path), uid: process.getuid?.(), tmpdir: resolvedTmpdir, home: homedir() };
+}
+
+/** A temp root equal to, above or below home would expose home entries as scratch. */
+function tempRoots(fs: TempScratchFs): string[] {
+	const home = posix.normalize(fs.home);
+	return [...FIXED_TEMP_ROOTS, fs.tmpdir].filter((root): root is string =>
+		root !== undefined && posix.isAbsolute(root) && posix.normalize(root) === root && root !== "/" &&
+		root !== home && !home.startsWith(`${root}/`) && !root.startsWith(`${home}/`));
+}
+
+/** One literal path component directly under a temp root, proven own scratch by an admission-time lstat. */
+export function isTempScratchTarget(target: string, fs: TempScratchFs): boolean {
+	if (fs.uid === undefined || !LITERAL_PATH_RE.test(target)) return false;
+	if (target.endsWith("/") || posix.normalize(target) !== target) return false;
+	const name = posix.basename(target);
+	if (name === "" || name === "." || name === ".." || !tempRoots(fs).includes(posix.dirname(target))) return false;
+	let stat: TempScratchStat;
+	try {
+		stat = fs.lstat(target);
+	} catch (error) {
+		return (error as { code?: unknown }).code === "ENOENT";
+	}
+	if (stat.isSymbolicLink()) return true;
+	if (stat.uid !== fs.uid) return false;
+	return stat.isFile() || (stat.isDirectory() && MKTEMP_NAME_RE.test(name));
+}
+
+/** A recognized effect is waivable temp scratch only when it is a direct recursive `rm` of temp scratch alone. */
+export function isTempScratchRemoval(match: DestructiveCommandMatch, fs: TempScratchFs): boolean {
+	if (match.hardDeny || match.kind !== "filesystem" || match.removalTargets === undefined) return false;
+	return match.removalTargets.every((target) => isTempScratchTarget(target, fs));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "4.2.0",
+	"version": "4.4.0",
 	"description": "Turn Pi into el Gentleman: an ODD development harness with focused subagents, configured TDD evidence, native review, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
@@ -42,7 +42,6 @@
 	],
 	"scripts": {
 		"check:provider-contract": "node scripts/check-provider-contract.mjs",
-		"mirror:odd-routing": "node scripts/mirror-odd-routing.mjs",
 		"postinstall": "node scripts/install-gentle-ai.mjs",
 		"test": "node scripts/run-test-suite.mjs",
 		"test:harness": "node --experimental-strip-types tests/runtime-harness.mjs",

package/runtime/gentle-ai-binary.mjs

@@ -15,7 +15,7 @@ import {
 	resolveGentleAiReleaseAsset,
 } from "../scripts/gentle-ai-installer.mjs";
 import { engramPinVersion } from "../scripts/installer-downloads.mjs";
-import { bundledGentlePiConfigHome, bundledPiConfigDir, bundledPiConfigParent, runningBundledPrefix } from "./gentle-shell-bundled.mjs";
+import { bundledPiConfigDir, bundledPiConfigParent, GENTLE_SHELL_CONFIG_HOME_ENV, resolveGentlePiConfigHome, runningBundledPrefix } from "./gentle-shell-bundled.mjs";
 import { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
@@ -87,9 +87,11 @@ export function bundledGentleAiPaths(prefix        , platform         = process.
  * (only when the pinned Engram is published), GENTLE_AI_NO_SELF_UPDATE=1 and
  * GENTLE_PI_CONFIG_HOME (the parent of GENTLE_AI_PI_CONFIG_DIR)
  * when this gentle-pi runs from the valid bundled install GENTLE_SHELL_PREFIX
- * names (runningBundledPrefix). Otherwise `env` itself, unchanged: a gentle-pi
- * installed elsewhere (the user's own, started from the agent's shell, which
- * inherits the variable) keeps its own Gentle AI.
+ * names (runningBundledPrefix). In the standalone launcher's isolated home
+ * (#2201) only the config pair, for the folder its marker names. Otherwise
+ * `env` itself, unchanged: a gentle-pi installed elsewhere (the user's own,
+ * started from the agent's shell, which inherits the variable) keeps its own
+ * Gentle AI.
  */
 export function gentleAiIsolationEnv(
 	env                   ,
@@ -97,7 +99,7 @@ export function gentleAiIsolationEnv(
 )                    {
 	const platform = options.platform ?? process.platform;
 	const prefix = runningBundledPrefix(env, { packageRoot: options.packageRoot, platform });
-	if (prefix === undefined) return env;
+	if (prefix === undefined) return standaloneGentleAiEnv(env, platform);
 	const paths = bundledGentleAiPaths(prefix, platform);
 	let engram = false;
 	try {
@@ -126,6 +128,23 @@ export function gentleAiIsolationEnv(
 	};
 }
 
+// #2201: the same config pair as a bundled install, for the folder the
+// standalone launcher's marker names, when it decides the config home
+// (resolveGentlePiConfigHome; an explicit GENTLE_PI_CONFIG_HOME keeps its
+// existing meaning for Gentle AI). Gentle AI's own state stays where it was.
+// The parent is given only for a folder named gentle-ai, the one Gentle AI
+// 4.0.0 appends to it.
+function standaloneGentleAiEnv(env                   , platform        )                    {
+	const marker = env[GENTLE_SHELL_CONFIG_HOME_ENV];
+	if (marker === undefined || resolveGentlePiConfigHome(env, homedir(), { platform }) !== marker) return env;
+	const path = platform === "win32" ? win32 : posix;
+	return {
+		...env,
+		GENTLE_AI_PI_CONFIG_DIR: marker,
+		...(path.basename(marker) === "gentle-ai" ? { GENTLE_PI_CONFIG_HOME: path.dirname(marker) } : {}),
+	};
+}
+
 function sha256(value        )         {
 	return createHash("sha256").update(value).digest("hex");
 }
@@ -137,7 +156,9 @@ function sha256(value        )         {
 //   1. GENTLE_PI_GENTLE_AI_DEV_BINARY (session override, absolute path), then
 //   2. the persistent registration file at
 //      <config home>/dev-binary.json (a bundled prefix's gentle-pi, else
-//      GENTLE_PI_CONFIG_HOME, else ~/.pi/gentle-ai) with the strict
+//      GENTLE_PI_CONFIG_HOME, else ~/.pi/gentle-ai, never the standalone
+//      launcher's marker: the main channel writes it outside any session,
+//      #2201) with the strict
 //      shape {"schema":"gentle-pi.dev-binary/v1","path":"<absolute path>"}.
 //
 // The registration deliberately pins no digest: it is the unpinned field-test
@@ -195,7 +216,7 @@ function ambientDevBinaryEnvironment()                               {
 }
 
 export function gentleAiDevBinaryRegistrationPath(environment                               = ambientDevBinaryEnvironment())         {
-	const configHome = bundledGentlePiConfigHome(environment.env) ?? environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
+	const configHome = resolveGentlePiConfigHome(environment.env, environment.home, { launcherMarker: false });
 	return join(configHome, "dev-binary.json");
 }
 

package/runtime/gentle-shell-bundled.mjs

@@ -2,7 +2,7 @@
 import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { request as httpRequest } from "node:http";
 import { createConnection } from "node:net";
-import { dirname, posix, win32 } from "node:path";
+import { dirname, isAbsolute, posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // The launcher in a bundled install (S5, S8): pure decisions over an injected
@@ -28,6 +28,46 @@ import { fileURLToPath } from "node:url";
 
 
 
+/**
+ * Builds the detached shared server's environment without retaining session scratch.
+ * Windows Node can reintroduce an omitted TEMP from its parent, so use the
+ * original stable ancestor there; POSIX omits scratch temp settings instead.
+ */
+export function sharedEngramEnv(base     , platform         = process.platform)      {
+	const path = pathFor(platform);
+	const env      = {};
+	const scratch = (value        ) => /^(gp|ga)[A-Za-z0-9]{6}$/.test(path.basename(path.normalize(value)));
+	let stableTemp                    ;
+	let tempKey                    ;
+	for (const [key, value] of Object.entries(base)) {
+		const name = platform === "win32" ? key.toUpperCase() : key;
+		if (name.startsWith("ENGRAM_") || name === "GH_TOKEN" || name === "GITHUB_TOKEN") continue;
+		if (["TMPDIR", "TMP", "TEMP"].includes(name) && value !== undefined && scratch(value)) {
+			if (platform !== "win32") continue;
+			// A drive-relative or root-relative path depends on ambient state.
+			const root = win32.parse(value).root;
+			if (!/^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+[\\/]?)$/.test(root) || value.split(/[\\/]/).includes("..")) {
+				throw new Error("An absolute Windows scratch temp path is required for shared Engram.");
+			}
+			let stable = win32.normalize(value);
+			while (scratch(stable)) {
+				const parent = win32.dirname(stable);
+				if (parent === stable) throw new Error("An absolute Windows scratch temp path is required for shared Engram.");
+				stable = parent;
+			}
+			env[key] = stable;
+			stableTemp ??= stable;
+		} else {
+			env[key] = value;
+		}
+		if (name === "TEMP") tempKey = key;
+	}
+	// Keep an existing custom TEMP, even if TMP/TMPDIR chose another root.
+	if (stableTemp !== undefined && (tempKey === undefined || env[tempKey] === undefined)) env[tempKey ?? "TEMP"] = stableTemp;
+	env.ENGRAM_NO_UPDATE_CHECK = "1";
+	return env;
+}
+
 // The same rules scripts/bundled-install.mjs writes versions and markers with.
 const VERSION_ID = /^[0-9A-Za-z][0-9A-Za-z.-]*$/;
 const VERSION_MARKER = ".gentle-shell-version";
@@ -176,6 +216,29 @@ export function bundledGentlePiConfigHome(env     )                     {
 	return prefix === undefined ? undefined : bundledPiConfigDir(prefix);
 }
 
+// #2201: the standalone launcher gives Pi this variable in its isolated home
+// only, naming the config folder next to the agent dir (standaloneConfigHome:
+// ~/.gentle-shell/gentle-ai by default). It is launcher-owned, never
+// GENTLE_PI_CONFIG_HOME: Gentle AI 4.0.0 reads that one as the parent of its
+// own gentle-ai folder, and the agent's shell would pass it to any gentle-ai.
+export const GENTLE_SHELL_CONFIG_HOME_ENV = "GENTLE_SHELL_CONFIG_HOME";
+
+// gentle-pi's config home, the one rule every reader shares: a bundled
+// prefix's folder, then an explicit GENTLE_PI_CONFIG_HOME, then the launcher's
+// marker (absolute only), then ~/.pi/gentle-ai. Empty values count as unset.
+// `launcherMarker: false` is for install-level state written outside a session
+// (the main channel's channel.json, builds and dev-binary.json): the installer
+// and `gentle-shell upgrade` never see the marker, so their readers ignore it.
+export function resolveGentlePiConfigHome(env     , home        , options                                                  = {})         {
+	const path = pathFor(options.platform ?? process.platform);
+	const bundled = bundledGentlePiConfigHome(env);
+	if (bundled !== undefined) return bundled;
+	if (env.GENTLE_PI_CONFIG_HOME) return env.GENTLE_PI_CONFIG_HOME;
+	const marker = env[GENTLE_SHELL_CONFIG_HOME_ENV];
+	if (options.launcherMarker !== false && marker && path.isAbsolute(marker)) return marker;
+	return path.join(home, ".pi", "gentle-ai");
+}
+
 // The exact Pi of the version (S8): the Pi the version's package.json pins,
 // installed inside the version folder with Pi's own bin entry. Never another Pi.
 export function bundledPi(install                , input                                     )            {
@@ -210,13 +273,14 @@ export function bundledPi(install                , input
 // Gentle AI's variables, never set here because the agent's shell would pass
 // them to a gentle-ai the user runs), and the published Engram as
 // gentle-engram's ENGRAM_BIN unless the user chose one. With a memory decision
-// (S2, S6): the startup policy, and ENGRAM_BIN is the verified core only when
-// memory is allowed locally; otherwise the Shell-owned guard, so no provider,
-// whatever loaded it, runs an Engram binary against an unverified store.
+// (S2, S6): the startup policy, and ENGRAM_BIN is the Shell-owned guard, so no
+// provider, whatever loaded it, runs an Engram binary against a store; allowed
+// memory reaches the shared server through ENGRAM_URL only.
 export const ENGRAM_COMPANION_SOURCE = "npm:gentle-engram@0.4.2";
-export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe store or server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
+export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server on 127.0.0.1:7437 with verified /compatibility evidence; Shell never stops or replaces a server already listening there. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
+export const ENGRAM_START_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not start the shared Engram server, or it did not report ready in time. Restart Shell to retry; if another program holds 127.0.0.1:7437, stop it first. Shell remains usable without memory.";
+export const ENGRAM_NEWER_SCHEMA_NOTICE = "Engram memory disabled: ~/.engram was migrated by a newer Engram than Shell's bundled core, so Shell will not start a server on it. Start that newer Engram's server yourself (engram serve); Shell reuses a running server with verified /compatibility evidence. Back up the store; do not delete or downgrade it. Shell remains usable without memory.";
 // `gentle-shell setup` publishes the verified core (ensureEngram) on every run.
-export const ENGRAM_PROVISION_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not provision a new Engram store identity, so it cannot vouch for that store. Restart Shell to retry. If Shell keeps reporting unknown compatibility and ~/.engram holds only .instance-id files, back it up and remove it, then restart Shell. Shell remains usable without memory.";
 export const ENGRAM_CORE_MISSING_NOTICE = "Engram memory disabled: the bundled Engram core is not installed yet. Run 'gentle-shell setup' to install the verified core, then restart Shell. Shell remains usable without memory.";
 // The first Engram release whose server answers GET /compatibility (PR #1792).
 export const ENGRAM_COMPATIBILITY_MIN_VERSION = "3.4.0";
@@ -237,12 +301,13 @@ function outdatedServerVersion(version                    )
 // The default endpoint gentle-engram uses without ENGRAM_URL or ENGRAM_PORT.
 export const ENGRAM_DEFAULT_PORT = 7437;
 export const ENGRAM_DEFAULT_URL = `http://127.0.0.1:${ENGRAM_DEFAULT_PORT}`;
-const ENGRAM_SELECTIONS = ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_DATABASE_URL"];
+const ENGRAM_SELECTIONS = ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_SOCKET", "ENGRAM_DATABASE_URL", "ENGRAM_SERVER_MODE"];
 const HEX32 = /^[a-f0-9]{32}$/;
 
 
-// `fresh`: Shell provisions a new store this run and may record its provenance.
-// `url`: a running server verified through /compatibility, reached explicitly.
+// `url`: the shared server, reached explicitly once /compatibility verified it.
+// `spawn`: nothing listens yet; Shell starts the bundled core's server and must
+// see it verified before Pi starts, or memory is disabled for that launch.
 
 
 // Without an invalid policy or an explicit Engram selection, the default
@@ -253,26 +318,24 @@ export function engramProbeAllowed(env     )          {
 }
 
 // Evidence only: never run an executable, open SQLite or infer compatibility
-// from versions. `provenance` means Shell's own record matched the store
-// (directory, .instance-id, core digest) and its header showed no newer schema.
-// A server version only selects the wording of a disabled decision.
-export function classifyEngramStartup(input
-	                                                          )                {
+// from versions. Like other agents' hooks, Shell shares the global server: a
+// verified listener is reused, and with nothing listening the verified bundled
+// core starts one on Engram's defaults, unless the default store's header
+// (`userVersion`) shows a newer schema than that core's. A listener that does
+// not verify is never replaced. A server version only selects the wording.
+export function classifyEngramStartup(input                                                                                               )                {
 	if (!engramProbeAllowed(input.env)) return { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
 	const endpoint = input.endpoint;
-	const outdated = endpoint.kind === "listening" && !endpoint.compatible ? outdatedServerVersion(endpoint.healthVersion) : undefined;
-	const unknown                = { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 	if (endpoint.kind === "listening" && endpoint.compatible) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
-	if (endpoint.kind === "refused" && input.store === "absent") {
-		return input.core ? { policy: "allow", fresh: true } : { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
+	if (endpoint.kind === "refused") {
+		if (!input.core) return { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
+		if (input.userVersion !== undefined && !engramHeaderAllows(input.userVersion, bundledEngramSchema(input.coreVersion))) {
+			return { policy: "disabled", notice: ENGRAM_NEWER_SCHEMA_NOTICE };
+		}
+		return { policy: "allow", url: ENGRAM_DEFAULT_URL, spawn: true };
 	}
-	const own = input.provenance;
-	if (own === undefined || !input.core || input.store !== "present") return unknown;
-	// Shell's own store, created by this exact core: offline, the provider starts
-	// that core; a running server must be that store and that exact core.
-	if (endpoint.kind === "refused") return { policy: "allow" };
-	if (endpoint.kind === "listening" && endpoint.healthInstanceId === own.instanceId && endpoint.healthVersion === input.coreVersion) return { policy: "allow" };
-	return unknown;
+	const outdated = endpoint.kind === "listening" ? outdatedServerVersion(endpoint.healthVersion) : undefined;
+	return { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 }
 
 // The exact contract a startup-verified store reports (Engram GET /compatibility).
@@ -332,8 +395,8 @@ export async function probeEngramEndpoint(input
 	return { kind: "listening", compatible: false, healthInstanceId: identified ? body.instance_id : undefined, healthVersion: identified ? body.version : undefined };
 }
 
-// Shell's own record of a store it provisioned fresh with the verified core.
-// Written only after Shell itself provisioned the store's identity, before Pi starts.
+// Shell's record of a store an earlier Shell provisioned with its bundled core,
+// read only by the explicit `gentle-shell memory migrate` recovery.
 
 
 export function engramProvenancePath(prefix        , platform         = process.platform)         {
@@ -347,14 +410,10 @@ export function parseEngramProvenance(text                    )
 	return { schema: 1, dataDir: record.dataDir, instanceId: record.instanceId, coreSha256: record.coreSha256 };
 }
 
-export function engramProvenanceMatches(record                              , observed                                                               )          {
-	return record !== undefined && record.dataDir === observed.dataDir && record.instanceId === observed.instanceId && record.coreSha256 === observed.coreSha256;
-}
-
 // The bundled core's own schema (SQLite user_version), verified from the
-// tagged sources v3.3.2 and v3.4.0: internal/store/store.go `const schemaVersion = 1`.
+// tagged sources v3.3.2, v3.4.0 and v3.5.2: internal/store/store.go `const schemaVersion = 1`.
 // A pin without a verified entry leaves the header check unavailable.
-const BUNDLED_ENGRAM_SCHEMA                         = { "3.3.2": 1, "3.4.0": 1 };
+const BUNDLED_ENGRAM_SCHEMA                         = { "3.3.2": 1, "3.4.0": 1, "3.5.2": 1 };
 
 export function bundledEngramSchema(coreVersion        )                     {
 	return Object.hasOwn(BUNDLED_ENGRAM_SCHEMA, coreVersion) ? BUNDLED_ENGRAM_SCHEMA[coreVersion] : undefined;
@@ -424,8 +483,7 @@ export function bundledChildEnv(base     , input
 		return env;
 	}
 	if (memory.url !== undefined) env.ENGRAM_URL = memory.url;
-	const local = memory.policy === "allow" && memory.url === undefined ? input.engram : undefined;
-	env.ENGRAM_BIN = local ?? input.guard;
+	env.ENGRAM_BIN = input.guard;
 	return env;
 }
 
@@ -458,6 +516,58 @@ export function withBundledNpmCommand(settingsText                    , command
 
 
 
+// settings.json without `npmCommand`: every other key kept in order and the
+// file's indentation and final newline kept.
+function settingsWithoutNpmCommand(settingsText        , settings                         )         {
+	const indent = settingsText.match(/\{\r?\n([ \t]+)/)?.[1] ?? "  ";
+	const { npmCommand: _removed, ...rest } = settings;
+	const serialized = JSON.stringify(rest, null, indent);
+	return settingsText.endsWith("\n") ? `${serialized}\n` : serialized;
+}
+
+// The agent home's settings.json without a `npmCommand` naming the prefix a
+// bundled self-uninstall removed (gentle-shell-uninstall.ts): one absolute
+// entry inside `withinRemoved` drops the whole key, every other key kept in
+// order and the file's indentation and final newline kept. A file that is not
+// a JSON object is never rewritten; a command naming nothing inside it stays.
+export function withoutBundledNpmCommand(settingsText                    , withinRemoved                           )                           {
+	if (settingsText === undefined) return { status: "unchanged" };
+	const settings = parseJson(settingsText);
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { status: "malformed" };
+	const current = settings.npmCommand;
+	if (!Array.isArray(current) || !current.some((part) => typeof part === "string" && isAbsolute(part) && withinRemoved(part))) return { status: "unchanged" };
+	return { status: "removed", text: settingsWithoutNpmCommand(settingsText, settings) };
+}
+
+// An `npmCommand` a bundled install wrote (scripts/bundled-install.mjs
+// bundledNpmCommand, with npm-cli.js and --prefix in earlier releases): our
+// node in runtime/node-<v>, then npm's settings and cache flags, and
+// --update-notifier=false last. A command the user chose never matches, even
+// when its program is missing.
+export function isBundledNpmCommand(command                    )          {
+	const [node] = command;
+	return typeof node === "string" && /[\\/]runtime[\\/]node-[^\\/]+[\\/](node\.exe|bin[\\/]node)$/.test(node)
+		&& ["--userconfig=", "--globalconfig=", "--cache="].every((flag) => command.some((part) => typeof part === "string" && part.startsWith(flag)))
+		&& command[command.length - 1] === "--update-notifier=false";
+}
+
+// The agent home's settings.json without an `npmCommand` a bundled install
+// wrote whose executable (its first entry) no longer exists, as after a
+// bundled self-uninstall that kept the home (#2469): Pi runs that command for
+// every package install, so a key naming a deleted node.exe fails them all
+// with ENOENT. A command whose executable exists, that names no absolute
+// path, or that the user set themselves is never touched.
+export function withoutMissingBundledNpmCommand(settingsText                    , exists                           )                           {
+	if (settingsText === undefined) return { status: "unchanged" };
+	const settings = parseJson(settingsText);
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { status: "malformed" };
+	const executable = Array.isArray(settings.npmCommand) ? settings.npmCommand[0] : undefined;
+	if (typeof executable !== "string" || !isAbsolute(executable) || exists(executable) || !isBundledNpmCommand(settings.npmCommand             )) return { status: "unchanged" };
+	return { status: "removed", text: settingsWithoutNpmCommand(settingsText, settings) };
+}
+
+
+