gentle-pi 4.2.0 → 4.3.0

package/lib/destructive-command-guard.ts

@@ -6,6 +6,11 @@ export interface DestructiveCommandMatch {
 	kind: DestructionKind;
 	triggerIndex: number;
 	hardDeny: boolean;
+	/**
+	 * Literal targets of a direct, top-level, unwrapped and unquoted recursive
+	 * `rm` that runs before every other segment of the command; absent otherwise.
+	 */
+	removalTargets?: readonly string[];
 }
 interface Token {
 	value: string;
@@ -14,6 +19,10 @@ interface Token {
 	index: number;
 }
 const separators = new Set([";", "&&", "||", "|", "&", "\n", "(", ")"]);
+// Separators after which the next segment starts only once this one finished.
+// Pipes, background jobs and subshell parentheses run segments concurrently or
+// out of textual order.
+const SEQUENTIAL_SEPARATORS = new Set(["", ";", "&&", "||", "\n"]);
 
 /** Literal, named heredocs are data, not executable shell segments; offsets are preserved. */
 function blankHeredocs(command: string): string {
@@ -49,10 +58,14 @@ const WRAPPER_VALUE_OPTIONS: Record<string, readonly string[]> = {
 	xargs: ["-n", "-I", "-P", "--max-args", "--replace", "--max-procs"],
 };
 const WRAPPERS = ["env", "sudo", "command", "exec", "nohup", "timeout", "xargs"];
+// gentle-pi#2285: unquoted reserved words that open a compound body or a
+// condition are followed by a command in command position.
+const RESERVED_WORDS = new Set(["then", "else", "elif", "do", "{", "!", "if", "while", "until"]);
 
-/** Index of the executable token after assignments and familiar wrappers. */
+/** Index of the executable token after reserved words, assignments and familiar wrappers. */
 function headCursor(segment: readonly Token[]): number {
 	let cursor = 0;
+	while (cursor < segment.length && segment[cursor].raw === segment[cursor].value && RESERVED_WORDS.has(segment[cursor].value)) cursor++;
 	while (cursor < segment.length) {
 		const value = segment[cursor].value;
 		if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(value)) {
@@ -85,29 +98,63 @@ const DATA_COMMANDS = new Set([
 const INERT_COMMANDS = new Set(["cd", "pwd", "true", "false", "test", "[", "mkdir", "touch"]);
 const HEREDOC_RE = /<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g;
 
+type Ranges = Array<readonly [number, number]>;
+// A simple `$(...)`: no nested substitution, quoting, expansion or escapes in its body.
+const SIMPLE_SUBSTITUTION_RE = /\$\(([^()'"`$\\]*)\)/g;
+
+/**
+ * Replace each simple `$(...)` whose body is itself only data and inert
+ * commands with a same-length placeholder word, so offsets are preserved.
+ * Such a substitution runs nothing guarded; its output is only more words.
+ * Returns undefined when any substitution is not provably data, or when a
+ * heredoc could expand one in its body.
+ */
+function maskDataSubstitutions(command: string): { masked: string; ranges: Ranges } | undefined {
+	if (!command.includes("$(")) return { masked: command, ranges: [] };
+	if (command.includes("<<")) return undefined;
+	const ranges: Ranges = [];
+	let opaque = false;
+	const masked = command.replace(SIMPLE_SUBSTITUTION_RE, (raw: string, body: string, offset: number) => {
+		const inner = dataRanges(body);
+		if (inner === undefined) opaque = true;
+		else ranges.push(...inner.map(([from, to]) => [offset + 2 + from, offset + 2 + to] as const));
+		return "_".repeat(raw.length);
+	});
+	return opaque || masked.includes("$(") ? undefined : { masked, ranges };
+}
+
 /**
  * Byte ranges of the command that are plain arguments of a known data command
  * (gentle-shell#2174). A guarded or denied pattern matching only inside these
  * ranges is prose, not an operation. Returns no ranges, keeping every lexical
- * match, when the command is opaque: command or process substitution, an
+ * match, when the command is opaque: a command substitution that is not
+ * itself only data commands, process substitution or backticks, an
  * interpreter or remote shell anywhere, or quoting the tokenizer cannot
  * account for.
  */
-export function dataArgumentRanges(command: string): Array<readonly [number, number]> {
-	if (/\$\(|`|[<>]\(/.test(command)) return [];
+export function dataArgumentRanges(command: string): Ranges {
+	return dataRanges(command) ?? [];
+}
+
+/** Undefined means opaque; an empty list means only inert commands. */
+function dataRanges(original: string): Ranges | undefined {
+	const substitutions = maskDataSubstitutions(original);
+	if (substitutions === undefined) return undefined;
+	const command = substitutions.masked;
+	if (/`|[<>]\(/.test(command)) return undefined;
 	// A heredoc counts only when its `<<` starts an unquoted token of the raw
 	// command; quoted text such as `echo '<<x'` must not blank following lines.
 	const rawStarts = new Set(tokenize(command, false).filter((token) => token.raw.startsWith("<<")).map((token) => token.index));
 	const heredocs = [...command.matchAll(HEREDOC_RE)];
-	if (heredocs.some((heredoc) => !rawStarts.has(heredoc.index))) return [];
+	if (heredocs.some((heredoc) => !rawStarts.has(heredoc.index))) return undefined;
 	const blanked = blankHeredocs(command);
 	const tokens = tokenize(command);
 	const covered = new Uint8Array(blanked.length);
 	for (const token of tokens) covered.fill(1, token.index, token.index + token.raw.length);
 	for (let index = 0; index < blanked.length; index++) {
-		if (!covered[index] && !/\s/.test(blanked[index])) return [];
+		if (!covered[index] && !/\s/.test(blanked[index])) return undefined;
 	}
-	const ranges: Array<readonly [number, number]> = [];
+	const ranges: Ranges = [...substitutions.ranges];
 	let start = 0;
 	for (let end = 0; end <= tokens.length; end++) {
 		if (end < tokens.length && !tokens[end].operator) continue;
@@ -120,10 +167,12 @@ export function dataArgumentRanges(command: string): Array<readonly [number, num
 		if (segment[0].value === "env") cursor++;
 		while (cursor < segment.length && /^[A-Za-z_][A-Za-z_0-9]*=/.test(segment[cursor].value)) cursor++;
 		const head = segment[cursor];
-		if (head === undefined || head.value !== head.raw) return [];
+		// A segment of plain assignments only (`f=$(ls)`) runs no command.
+		if (head === undefined && cursor > 0 && segment[0].value !== "env") continue;
+		if (head === undefined || head.value !== head.raw) return undefined;
 		const name = head.value;
 		if (INERT_COMMANDS.has(name)) continue;
-		if (!DATA_COMMANDS.has(name)) return [];
+		if (!DATA_COMMANDS.has(name)) return undefined;
 		ranges.push([head.index + head.raw.length, tokens[end]?.index ?? command.length]);
 	}
 	// A heredoc body belongs to the segment of its `<<` header, which the
@@ -148,12 +197,58 @@ function sqlDestroys(sql: string): boolean {
 	});
 }
 
+/** Operands of a plain `rm` invocation, or undefined when any argument is quoted, escaped or disables root protection. */
+function removalTargets(args: readonly Token[]): string[] | undefined {
+	const targets: string[] = [];
+	let options = true;
+	for (const arg of args) {
+		if (arg.raw !== arg.value || arg.value === "--no-preserve-root") return undefined;
+		if (options && arg.value === "--") options = false;
+		else if (options && arg.value.startsWith("-")) continue;
+		else targets.push(arg.value);
+	}
+	return targets.length > 0 ? targets : undefined;
+}
+
+/**
+ * Bodies of backtick command substitutions outside single quotes, with the
+ * backslash escapes that backticks remove, and the offset of each opening
+ * backtick. An unterminated substitution is a shell syntax error and runs
+ * nothing, so it yields no body. Heredoc bodies stay data, as elsewhere.
+ */
+function backtickBodies(command: string): Array<{ body: string; index: number }> {
+	const bodies: Array<{ body: string; index: number }> = [];
+	const text = blankHeredocs(command);
+	let quote: "'" | '"' | undefined;
+	for (let index = 0; index < text.length; index++) {
+		const char = text[index];
+		if (quote === "'") {
+			if (char === "'") quote = undefined;
+		} else if (char === "\\") {
+			index++;
+		} else if (char === "'" && quote === undefined) {
+			quote = "'";
+		} else if (char === '"') {
+			quote = quote === '"' ? undefined : '"';
+		} else if (char === "`") {
+			let end = index + 1;
+			while (end < text.length && text[end] !== "`") end += text[end] === "\\" ? 2 : 1;
+			if (end >= text.length) break;
+			bodies.push({ body: text.slice(index + 1, end).replace(/\\([\\$`])/g, "$1"), index });
+			index = end;
+		}
+	}
+	return bodies;
+}
+
 export function recognizeDestructiveCommands(command: string, depth = 0): DestructiveCommandMatch[] {
 	if (depth > 4) return [];
 	const tokens = tokenize(command);
 	const matches: DestructiveCommandMatch[] = [];
 	let previous: Token[] = [];
 	let previousSeparator = "";
+	// True while every earlier segment was a leading literal recursive `rm`.
+	let leadingRemovals = depth === 0;
 	let start = 0;
 	for (let end = 0; end <= tokens.length; end++) {
 		if (end < tokens.length && !tokens[end].operator) continue;
@@ -172,6 +267,11 @@ export function recognizeDestructiveCommands(command: string, depth = 0): Destru
 				matches.push(...recognizeDestructiveCommands(args[flag + 1], depth + 1).map((match) => ({ ...match, triggerIndex: head.index })));
 			}
 		}
+		// `eval` runs its arguments joined by spaces, like a literal `sh -c` payload.
+		if (name === "eval") {
+			const payload = (args[0] === "--" ? args.slice(1) : args).join(" ");
+			matches.push(...recognizeDestructiveCommands(payload, depth + 1).map((match) => ({ ...match, triggerIndex: head.index })));
+		}
 		if (["psql", "mysql", "mariadb", "sqlite3"].includes(name)) {
 			const payloads = args.map((arg) => arg.replace(/^(?:--command|--execute)=/, ""));
 			const heredoc = command.slice(head.index).match(/^[^\n]*<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n([\s\S]*?)\n\2(?=\n|$)/);
@@ -184,6 +284,13 @@ export function recognizeDestructiveCommands(command: string, depth = 0): Destru
 		if (name === "rm" && args.some((arg) => /^-[^-]*[rR]/.test(arg) || arg === "--recursive")) {
 			const rootTarget = args.some((arg) => /^(?:\/(?:\*+)?$|\.{1,2}\/?$|~(?:\/|$)|\$\{?HOME\}?(?:\/|$))/.test(arg));
 			add(DESTRUCTION_KIND.FILESYSTEM, rootTarget);
+			const sequential = SEQUENTIAL_SEPARATORS.has(tokens[end]?.raw ?? "");
+			const targets = leadingRemovals && sequential && cursor === 0 && head.raw === "rm" ? removalTargets(segment.slice(1)) : undefined;
+			if (targets !== undefined) matches[matches.length - 1].removalTargets = targets;
+			else leadingRemovals = false;
+		} else if (segment.length > 0 || tokens[end]?.raw !== "\n") {
+			// Only blank lines may sit between leading removals.
+			leadingRemovals = false;
 		}
 		if (name === "find") {
 			if (args.includes("-delete")) add(DESTRUCTION_KIND.FILESYSTEM);
@@ -216,5 +323,9 @@ export function recognizeDestructiveCommands(command: string, depth = 0): Destru
 		previousSeparator = tokens[end]?.value ?? "";
 		start = end + 1;
 	}
+	// Backtick substitutions run like `$(...)`, also inside double quotes.
+	for (const { body, index } of backtickBodies(command)) {
+		matches.push(...recognizeDestructiveCommands(body, depth + 1).map((match) => ({ ...match, triggerIndex: index })));
+	}
 	return matches;
 }

package/lib/gauge-theme.ts

@@ -0,0 +1,146 @@
+// Gauge theme roles from the installed theme source (issue #2222).
+//
+// Pi's theme schema is closed at every level (colors, export and the theme
+// object itself reject unknown properties) and `theme.fg` throws on unknown
+// tokens, so gauge roles cannot be theme colors or a top-level block. The
+// one open map is `vars` (a free-form record of color values), so themes
+// declare the roles there under reserved `gauge.` keys. Color values resolve
+// like any Pi theme value: an existing theme token name (painted through
+// `theme.fg`), or a direct color (hex, okhsl, or a 256-color index, painted
+// as raw ANSI so the gauges alone recolor). Glyph values are literal single
+// characters. Everything is optional and falls back per role to the gauge's
+// historical roles, so themes without the keys — and invalid values — render
+// exactly as before.
+
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { colorToRgb, parseColor } from "@earendil-works/pi-tui";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { GaugePaint } from "./shell-gauge.ts";
+
+const MAX_BYTES = 256_000;
+const REFERENCE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+const COLOR_KEYS = ["ok", "warning", "error", "empty"] as const;
+const GLYPH_KEYS = ["filled", "emptyGlyph"] as const;
+// Reserved `vars` names that carry the gauge customization, e.g. "vars": { "gauge.ok": "#22c55e" }.
+const gaugeVar = (key: string): string => `gauge.${key}`;
+
+interface CacheEntry {
+	mtimeMs: number;
+	size: number;
+	paint: GaugePaint | undefined;
+}
+
+// The bar and panel render many times a second, so a render pays at most one
+// statSync per call; the file is opened and parsed only when the stat changes,
+// and a failed resolve is cached like any other result so a malformed theme
+// costs no repeated reads on the render path.
+const cache = new Map<string, CacheEntry>();
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** One visible terminal column, single code point, no control characters or escape sequences. */
+function isGlyph(value: unknown): value is string {
+	return typeof value === "string" && [...value].length === 1 && visibleWidth(value) === 1 && !/[\u0000-\u001f\u007f\x1b]/.test(value);
+}
+
+// A color entry resolves like a Pi theme value: variable references expand
+// first, then either an existing theme token keeps its name (so the theme's
+// own resolved ANSI applies) or the value delegates to pi-tui's `parseColor`,
+// the same grammar themes use everywhere else (3 or 6 digit hex, oklch,
+// case-insensitive okhsl), and becomes raw foreground ANSI. Direct colors are
+// what let a theme recolor only the gauges, exactly like the issue's
+// green/yellow/red statusline use case.
+function resolveGaugeColor(value: unknown, colors: Record<string, unknown>, vars: Record<string, unknown>): string | undefined {
+	const seen = new Set<unknown>();
+	while (typeof value === "string" && REFERENCE.test(value) && Object.hasOwn(vars, value)) {
+		if (seen.has(value)) return undefined;
+		seen.add(value);
+		value = vars[value];
+	}
+	if (typeof value === "string" && Object.hasOwn(colors, value)) return value;
+	if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 255) return `\x1b[38;5;${value}m`;
+	if (typeof value === "string") {
+		try {
+			const { r, g, b } = colorToRgb(parseColor(value));
+			return `\x1b[38;2;${r};${g};${b}m`;
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+/** Read only the installed theme source supplied by Pi; never fall back to the active theme. */
+function readThemeSource(sourcePath: string): unknown {
+	const resolved = realpathSync(sourcePath);
+	const fd = openSync(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	let text: string;
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error("Theme source unavailable or too large.");
+		text = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(fd));
+	} finally {
+		closeSync(fd);
+	}
+	return JSON.parse(text);
+}
+
+/**
+ * Gauge roles and glyphs declared by the theme source, or undefined when the
+ * theme declares none. Invalid entries are dropped individually, never
+ * throwing: a bad `gaugeWarning` keeps `warning` rather than disabling the rest.
+ */
+export function resolveGaugePaint(sourcePath: string): GaugePaint | undefined {
+	const document: unknown = readThemeSource(sourcePath);
+	if (!record(document) || !record(document.vars)) return undefined;
+	const vars = document.vars;
+	const hasGaugeVars = COLOR_KEYS.some((key) => gaugeVar(key) in vars) || GLYPH_KEYS.some((key) => gaugeVar(key) in vars);
+	if (!hasGaugeVars) return undefined;
+	const colors = record(document.colors) ? document.colors : {};
+	const paint: GaugePaint = {};
+	for (const key of COLOR_KEYS) {
+		const declared = vars[gaugeVar(key)];
+		if (declared === undefined) continue;
+		const value = resolveGaugeColor(declared, colors, vars);
+		if (value !== undefined) paint[key] = value;
+	}
+	for (const key of GLYPH_KEYS) {
+		const value = vars[gaugeVar(key)];
+		if (isGlyph(value)) paint[key] = value;
+	}
+	return paint;
+}
+
+/** Memoized `resolveGaugePaint`; undefined whenever the theme source is unavailable or invalid. */
+export function gaugePaintFor(sourcePath: string | undefined): GaugePaint | undefined {
+	if (!sourcePath) return undefined;
+	let stat;
+	try {
+		stat = statSync(sourcePath);
+	} catch {
+		// A missing source stays uncached: recreating it must take effect.
+		return undefined;
+	}
+	const cached = cache.get(sourcePath);
+	if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) return cached.paint;
+	// Validate the stat before any open: a path that is not a regular file (a
+	// FIFO, a device) must never reach openSync, and an oversized file must
+	// never reach a read. Failures resolve to the historical roles.
+	let paint: GaugePaint | undefined;
+	if (stat.isFile() && stat.size <= MAX_BYTES) {
+		try {
+			paint = resolveGaugePaint(sourcePath);
+		} catch {
+			paint = undefined;
+		}
+	}
+	cache.set(sourcePath, { mtimeMs: stat.mtimeMs, size: stat.size, paint });
+	return paint;
+}
+
+/** Test hook: drop every cached theme source entry. */
+export function clearGaugePaintCache(): void {
+	cache.clear();
+}

package/lib/gentle-ai-binary.ts

@@ -14,7 +14,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.ts";
+import { bundledPiConfigDir, bundledPiConfigParent, GENTLE_SHELL_CONFIG_HOME_ENV, resolveGentlePiConfigHome, runningBundledPrefix } from "./gentle-shell-bundled.ts";
 import { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
@@ -86,9 +86,11 @@ export function bundledGentleAiPaths(prefix: string, platform: string = 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: NodeJS.ProcessEnv,
@@ -96,7 +98,7 @@ export function gentleAiIsolationEnv(
 ): NodeJS.ProcessEnv {
 	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 {
@@ -125,6 +127,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: NodeJS.ProcessEnv, platform: string): NodeJS.ProcessEnv {
+	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: Buffer): string {
 	return createHash("sha256").update(value).digest("hex");
 }
@@ -136,7 +155,9 @@ function sha256(value: Buffer): string {
 //   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
@@ -194,7 +215,7 @@ function ambientDevBinaryEnvironment(): GentleAiDevBinaryEnvironment {
 }
 
 export function gentleAiDevBinaryRegistrationPath(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): string {
-	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/lib/gentle-shell-bundled.ts

@@ -175,6 +175,29 @@ export function bundledGentlePiConfigHome(env: Env): string | undefined {
 	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: Env, home: string, options: { launcherMarker?: boolean; platform?: string } = {}): string {
+	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: BundledInstall, input: { platform: string; fs: BundledFs }): BundledPi {
@@ -213,6 +236,8 @@ export function bundledPi(install: BundledInstall, input: { platform: string; fs
 // memory is allowed locally; otherwise the Shell-owned guard, so no provider,
 // whatever loaded it, runs an Engram binary against an unverified store.
 export const ENGRAM_COMPANION_SOURCE = "npm:gentle-engram@0.4.2";
+export const ENGRAM_PRIVATE_REQUIRED_NOTICE = "Engram memory disabled: session-owned servers require a supporting published bundled core and companion. This bundle does not establish both capabilities; it will not fall back to a detached shared server. Install a supporting published bundle and restart Shell. Existing shared services are not stopped or adopted as session-owned.";
+export const ENGRAM_CORE_CHANGED_NOTICE = "Engram memory disabled: the bundled core changed since Shell recorded this store. Install a published bundle supporting migrate-copy, stop every Engram client, retain a complete backup, then run gentle-shell memory migrate --confirm-quiescent. The command verifies and migrates a copy before updating provenance; older bundles refuse safely. Do not edit coreSha256 or delete the original store. Shell remains usable without memory.";
 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.";
 // `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.";
@@ -236,13 +261,13 @@ function outdatedServerVersion(version: string | undefined): string | undefined
 // 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"];
 const HEX32 = /^[a-f0-9]{32}$/;
 
 export type EngramProbe = { kind: "refused" } | { kind: "unknown" } | { kind: "listening"; compatible: boolean; healthInstanceId?: string; healthVersion?: string };
 // `fresh`: Shell provisions a new store this run and may record its provenance.
 // `url`: a running server verified through /compatibility, reached explicitly.
-export type EngramStartup = { policy: "allow" | "disabled"; notice?: string; url?: string; fresh?: true };
+export type EngramStartup = { policy: "allow" | "disabled"; notice?: string; url?: string; fresh?: true; owned?: true };
 
 // Without an invalid policy or an explicit Engram selection, the default
 // endpoint may be probed; an explicit selection is never contacted.
@@ -270,7 +295,7 @@ export function classifyEngramStartup(input: { env: Env; store: "absent" | "pres
 	// 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" };
+	if (endpoint.kind === "listening" && endpoint.healthInstanceId === own.instanceId && endpoint.healthVersion === input.coreVersion) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
 	return unknown;
 }
 
@@ -401,6 +426,11 @@ export function supportsEngramStartupPolicy(metadata: string | undefined): boole
 	return pkg?.name === "gentle-engram" && pkg.engram?.startupPolicy === 1;
 }
 
+export function supportsEngramSessionOwned(metadata: string | undefined): boolean {
+	const pkg = parseJson(metadata);
+	return supportsEngramStartupPolicy(metadata) && pkg?.engram?.sessionOwned === 1;
+}
+
 export function bundledChildEnv(base: Env, input: { node: string; cli: string; prefix: string; engram?: string; guard?: string; memory?: EngramStartup }): Env {
 	const env: Env = { ...base, PI_SKIP_VERSION_CHECK: "1", [GENTLE_SHELL_PREFIX_ENV]: input.prefix };
 	delete env.GENTLE_SHELL_PI;
@@ -425,6 +455,12 @@ export function bundledChildEnv(base: Env, input: { node: string; cli: string; p
 	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;
+	if (local && memory.owned) {
+		env.ENGRAM_SERVER_MODE = "session-owned";
+		delete env.ENGRAM_URL;
+		delete env.ENGRAM_PORT;
+		delete env.ENGRAM_SOCKET;
+	}
 	return env;
 }