gentle-pi 3.7.0 → 4.1.0

package/lib/yolo-session-policy.ts

@@ -0,0 +1,317 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { appendSystemPromptOnce, type AppendableSystemPromptOptions } from "./append-system-prompt.ts";
+import { sameReviewSessionIdentity, resolveCanonicalGitRepositoryIdentity, type ReviewSessionIdentity } from "./review-session-standing-permission.ts";
+import { realpath } from "node:fs/promises";
+import { gentlePiConfigHome } from "./agent-home.ts";
+import { isPermissionMode, resolvePermissionModePolicy, writePermissionModePolicy, type PermissionMode } from "./permission-mode-policy.ts";
+export type { PermissionMode } from "./permission-mode-policy.ts";
+export const MODE_STATUS_KEY = "gentle:mode";
+export const AUTO_MODE_NOTICE = "Auto uses additional model calls with separate usage accounting; hard safety and independent consent remain.";
+
+export const YOLO_STATUS_KEY = "gentle:yolo";
+export const YOLO_STATUS_TEXT = "🚀 YOLO ON 🔥 — destructive confirmations remain";
+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.
+This does NOT override explicit human restrictions, repository policy, project trust, configured confirmations or blocks, or the authorized task scope. Ask before scope expansion, privacy-sensitive disclosure, genuinely unresolved consequential product choices, or ambiguous destinations or credentials. Never invent destinations or credentials.
+Destructive/data-loss confirmations remain mandatory and independent. Never auto-answer ask_user tools, provider consent, maintenance/recovery authorization or opaque-token decisions. Review standing permission and RDD are unchanged. Children remain bounded by their delegated task; they receive no independent delivery grant or YOLO inheritance.
+</gentle-yolo-session>`;
+
+/** Legacy standalone API; separate from review grants and their registry. */
+export class YoloSessionPolicy {
+	private grant: ReviewSessionIdentity | undefined;
+	private generation = 0;
+	get epoch(): number { return this.generation; }
+	get enabled(): boolean { return this.grant !== undefined; }
+	reset(): void { this.generation += 1; this.grant = undefined; }
+	set(enabled: boolean, identity: ReviewSessionIdentity | undefined, expectedEpoch = this.epoch): boolean {
+		if (expectedEpoch !== this.epoch) return false;
+		this.reset();
+		if (!enabled) return true;
+		if (identity === undefined) return false;
+		this.grant = identity;
+		return true;
+	}
+	active(identity: ReviewSessionIdentity | undefined): boolean {
+		if (!this.grant) return false;
+		if (identity !== undefined && sameReviewSessionIdentity(this.grant, identity)) return true;
+		this.reset();
+		return false;
+	}
+}
+
+/** Remove our exact block as well as adding it: bridge options can be reused. */
+export function updateYoloPrompt(options: AppendableSystemPromptOptions | null | undefined, active: boolean): void {
+	if (!options) return;
+	options.appendSystemPrompt = (options.appendSystemPrompt ?? "")
+		.replace(`\n\n${YOLO_DIRECTIVE}`, "").replace(YOLO_DIRECTIVE, "");
+	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];
+export const YOLO_DISPLAY = { on: "ON", off: "OFF", unavailable: "UNAVAILABLE" } as const;
+export type YoloDisplay = (typeof YOLO_DISPLAY)[keyof typeof YOLO_DISPLAY];
+const HOST_UI_CHANNEL = "gentle:yolo:host-ui";
+const DISCOVERY_TIMEOUT_MS = 100;
+export interface YoloUiAdapter {
+	read(): Promise<YoloDisplay>;
+	readMode?(): Promise<PermissionMode>;
+	readSnapshot?(): Promise<{ yolo: YoloDisplay; mode: PermissionMode; defaultMode: PermissionMode }>;
+	setMode?(mode: PermissionMode): Promise<boolean>;
+	readDefault?(): PermissionMode;
+	saveDefault?(mode: PermissionMode): Promise<boolean>;
+	toggle(): Promise<void>;
+	observe(refresh: () => void): () => void;
+	dispose(): void;
+}
+interface HostUiRequest { context: ExtensionContext; respond(adapter: YoloUiAdapter): void }
+function isUiAdapter(value: unknown): value is YoloUiAdapter {
+	if (!value || typeof value !== "object") return false;
+	const adapter = value as Partial<YoloUiAdapter>;
+	return [adapter.read, adapter.toggle, adapter.observe, adapter.dispose].every(fn => typeof fn === "function");
+}
+/** emit is void (and listeners may be wrapped async); explicitly bound the callback wait. */
+export function discoverYoloUiAdapter(pi: ExtensionAPI, context: ExtensionContext): Promise<YoloUiAdapter | undefined> {
+	return new Promise(resolve => {
+		let settled = false;
+		const timer = setTimeout(() => { settled = true; resolve(undefined); }, DISCOVERY_TIMEOUT_MS);
+		const respond = (value: unknown) => {
+			if (!isUiAdapter(value)) return;
+			if (settled) { value.dispose(); return; }
+			settled = true; clearTimeout(timer); resolve(value);
+		};
+		try { pi.events.emit(HOST_UI_CHANNEL, { context, respond } satisfies HostUiRequest); }
+		catch { settled = true; clearTimeout(timer); resolve(undefined); }
+	});
+}
+export interface YoloSessionController {
+	active(context: ExtensionContext): Promise<boolean>;
+	mode(context: ExtensionContext): Promise<PermissionMode>;
+	setMode(mode: PermissionMode, context: ExtensionContext): Promise<boolean>;
+	defaultMode(): PermissionMode;
+	saveDefault(mode: PermissionMode, context: ExtensionContext): Promise<boolean>;
+	epoch(): number;
+	humanAction(action: HumanAction, context: ExtensionContext, current?: () => boolean): Promise<boolean>;
+	reset(context: ExtensionContext): void;
+}
+interface ModeIdentity {
+	manager: ExtensionContext["sessionManager"];
+	id: string;
+	workspace: string;
+}
+/** 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 {
+	const store = { gentlePiConfigHome: gentlePiConfigHome(env) };
+	let generation = 0;
+	let ownerGeneration = 0;
+	let liveMode: PermissionMode = "normal";
+	let binding: ModeIdentity | undefined;
+	let interactiveGrant = false;
+	// A same-session revocation must not replay the global elevated preference.
+	const seen = new WeakMap<object, Set<string>>();
+	const observers = new Set<() => void>();
+	const pendingCaptures = new Set<{ manager: ModeIdentity["manager"]; id: string }>();
+	const primary = () => env.GENTLE_PI_AGENTS_CHILD !== "1";
+	const interactive = (ctx: ExtensionContext): boolean => {
+		if (!primary() || !ctx.hasUI) return false;
+		const mode = (ctx as ExtensionContext & { mode?: string }).mode;
+		if (mode !== undefined) return mode === "tui";
+		try { return (ctx.ui.getAllThemes?.().length ?? 0) > 0; } catch { return false; }
+	};
+	const session = (ctx: ExtensionContext): { manager: ModeIdentity["manager"]; id: string } | undefined => {
+		try {
+			const manager = ctx.sessionManager, id = manager.getSessionId();
+			return manager && typeof id === "string" && id.length > 0 ? { manager, id } : undefined;
+		} catch { return undefined; }
+	};
+	const remember = (scope: { manager: object; id: string }): void => {
+		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 changed = (ctx: ExtensionContext): void => {
+		generation += 1; publish(ctx);
+		try { options.onChange?.(); } catch { /* observer is not authority */ }
+		for (const refresh of [...observers]) { try { refresh(); } catch { /* display only */ } }
+	};
+	const notify = (ctx: ExtensionContext, message: string, warning = false): void => {
+		try { ctx.ui.notify(message, warning ? "warning" : "info"); } catch { /* headless/stale UI */ }
+	};
+	// Capture plain identity before async filesystem work; recheck after every await.
+	const bindCurrent = (ctx: ExtensionContext, disposed = () => false, requireUI = true): (() => boolean) => {
+		const owner = ownerGeneration, scope = session(ctx), cwd = ctx.cwd;
+		return () => {
+			try {
+				const now = session(ctx);
+				return !disposed() && owner === ownerGeneration && !!scope && !!now &&
+					scope.manager === now.manager && scope.id === now.id && cwd === ctx.cwd &&
+					(!requireUI || interactive(ctx));
+			} catch { return false; }
+		};
+	};
+	const capture = async (ctx: ExtensionContext): Promise<ModeIdentity | undefined> => {
+		if (!primary()) return undefined;
+		const scope = session(ctx), cwd = ctx.cwd, current = bindCurrent(ctx, () => false, false);
+		if (!scope) return undefined;
+		pendingCaptures.add(scope);
+		try {
+			const canonical = await realpath(cwd);
+			if (!current()) return undefined;
+			const clone = await 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";
+		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);
+		}
+		if (!binding && identity) {
+			const fresh = !seen.get(identity.manager)?.has(identity.id);
+			remember(identity); binding = identity;
+			if (fresh) { liveMode = defaultMode(); interactiveGrant = false; changed(ctx); }
+		}
+		publish(ctx);
+		return identity && binding ? liveMode : "normal";
+	};
+	const active = async (ctx: ExtensionContext): Promise<boolean> => await mode(ctx) === "yolo";
+	const reset = (ctx: ExtensionContext): void => {
+		ownerGeneration += 1;
+		// Initial session_start remains fresh; shutdown/reload of an observed session revokes.
+		if (binding) remember(binding);
+		const scope = session(ctx);
+		if (scope && [...pendingCaptures].some(pending => pending.manager === scope.manager && pending.id === scope.id)) remember(scope);
+		binding = undefined; liveMode = "normal"; interactiveGrant = false;
+		changed(ctx); observers.clear();
+	};
+	const setMode = async (requested: PermissionMode, ctx: ExtensionContext, lifetime = () => true): Promise<boolean> => {
+		if (!isPermissionMode(requested) || !interactive(ctx) || !lifetime()) return false;
+		const current = bindCurrent(ctx, () => !lifetime());
+		// Revoke immediately, including off versus a pending activation race.
+		const scope = session(ctx); if (scope) remember(scope);
+		binding = undefined; liveMode = "normal"; interactiveGrant = false; changed(ctx);
+		const epoch = generation;
+		const identity = await capture(ctx);
+		if (!current() || epoch !== generation || !identity) return false;
+		binding = identity; remember(identity); liveMode = requested; interactiveGrant = true; changed(ctx);
+		if (requested === "auto") notify(ctx, AUTO_MODE_NOTICE);
+		return true;
+	};
+	const saveDefault = async (requested: PermissionMode, ctx: ExtensionContext, lifetime = () => true): Promise<boolean> => {
+		if (!isPermissionMode(requested) || !interactive(ctx) || !lifetime()) return false;
+		const current = bindCurrent(ctx, () => !lifetime()), epoch = generation;
+		const identity = await capture(ctx);
+		if (!identity || !current() || epoch !== generation) return false;
+		// Initialize before saving, without another await that could let a superseding
+		// mode action authorize this stale save. Observer reentrancy is checked too.
+		if (!binding || binding.manager !== identity.manager || binding.id !== identity.id || binding.workspace !== identity.workspace) {
+			liveMode = seen.get(identity.manager)?.has(identity.id) ? "normal" : defaultMode();
+			binding = identity; remember(identity); interactiveGrant = false; changed(ctx);
+			if (!current() || generation !== epoch + 1) return false;
+		}
+		try { writePermissionModePolicy(requested, store); }
+		catch { notify(ctx, "Default unchanged — permission mode preference is malformed, unreadable or could not be saved.", true); return false; }
+		notify(ctx, `Default ${requested.toUpperCase()} saved for next primary sessions.${requested === "auto" ? ` ${AUTO_MODE_NOTICE}` : ""}`);
+		for (const refresh of [...observers]) { try { refresh(); } catch { /* display only */ } }
+		return true;
+	};
+	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 pending = setMode(enable ? "yolo" : "normal", ctx, current);
+		const epoch = generation; // setMode revokes synchronously, then publishes once on success.
+		const result = await pending;
+		if (!current()) return false;
+		// Supersession is not activation failure: the winning action owns notification.
+		if (generation !== epoch + (result ? 1 : 0)) return true;
+		notify(ctx, result ? enable ? YOLO_STATUS_TEXT : "YOLO OFF" :
+			"YOLO OFF — activation requires an interactive primary TUI session and an identifiable workspace.", !result);
+		return true;
+	};
+	pi.events?.on?.(HOST_UI_CHANNEL, (payload: unknown) => {
+		if (!payload || typeof payload !== "object") return;
+		const request = payload as Partial<HostUiRequest>;
+		if (typeof request.respond !== "function" || !request.context) return;
+		const ctx = request.context;
+		try {
+			let disposed = false;
+			const subscriptions = new Set<() => void>();
+			const current = bindCurrent(ctx, () => disposed);
+			const read = async (): Promise<YoloDisplay> => {
+				if (!current()) return YOLO_DISPLAY.unavailable;
+				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;
+			};
+			request.respond({
+				read,
+				readSnapshot: async () => {
+					const yolo = await read();
+					return { yolo, mode: current() ? liveMode : "normal", defaultMode: defaultMode() };
+				},
+				readMode: async () => current() ? mode(ctx) : "normal",
+				setMode: async value => setMode(value, ctx, current),
+				readDefault: defaultMode,
+				saveDefault: async value => saveDefault(value, ctx, current),
+				toggle: async () => { await humanAction(HUMAN_ACTION.toggle, ctx, current); },
+				observe: refresh => {
+					if (!current()) return () => {};
+					subscriptions.add(refresh); observers.add(refresh);
+					return () => { subscriptions.delete(refresh); observers.delete(refresh); };
+				},
+				dispose: () => { disposed = true; for (const refresh of subscriptions) observers.delete(refresh); subscriptions.clear(); },
+			});
+		} 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.",
+		handler: async (args, ctx) => {
+			const words = args.trim().split(/\s+/);
+			if (!args.trim() || args.trim() === "status") {
+				notify(ctx, `Permissions: ${(await mode(ctx)).toUpperCase()} — default: ${defaultMode().toUpperCase()}`); return;
+			}
+			if (words.length === 2 && words[0] === "default" && isPermissionMode(words[1])) {
+				await saveDefault(words[1], ctx); return;
+			}
+			if (words.length === 1 && isPermissionMode(words[0])) {
+				if (await setMode(words[0], ctx)) notify(ctx, `Permissions: ${words[0].toUpperCase()}`);
+				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);
+		},
+	});
+	pi.registerCommand("gentle:yolo", {
+		description: "Ordinary development/delivery permission (enable|disable|status); no argument opens a menu. Destructive confirmations remain.",
+		handler: async (args, ctx) => {
+			let action = args.trim() || "status";
+			let current = () => true;
+			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"]);
+				if (selected === undefined) return;
+				action = selected;
+			}
+			if (action !== "enable" && action !== "disable" && action !== "status") {
+				notify(ctx, "Use /gentle:yolo enable|disable|status. State unchanged.", true); return;
+			}
+			if (action === "status") { notify(ctx, await active(ctx) ? YOLO_STATUS_TEXT : "YOLO OFF"); return; }
+			if (await humanAction(action === "enable" ? HUMAN_ACTION.on : HUMAN_ACTION.off, ctx, current)) return;
+			notify(ctx, "YOLO unchanged — the session changed while the menu was open.", true);
+		},
+	});
+	return { active, mode, setMode, defaultMode, saveDefault, epoch: () => generation, humanAction, reset };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "gentle-pi",
-	"version": "3.7.0",
-	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
+	"version": "4.1.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",
 	"bin": {
@@ -13,8 +13,7 @@
 		"pi-coding-agent",
 		"gentle-pi",
 		"gentle-ai",
-		"sdd",
-		"openspec",
+		"odd",
 		"subagents",
 		"tdd",
 		"code-review",
@@ -37,6 +36,7 @@
 		"skills/",
 		"scripts/",
 		"tests/",
+		"!tests/fixtures/legacy/sdd-research-v2.5.0.md",
 		"themes/",
 		"README.md"
 	],
@@ -44,7 +44,7 @@
 		"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 --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",
+		"test": "node scripts/run-test-suite.mjs",
 		"test:harness": "node --experimental-strip-types tests/runtime-harness.mjs",
 		"test:dev-binary": "node --experimental-strip-types --test tests/devbinary/*.devtest.ts",
 		"test:cross-lane": "node tests/crosslane/cross-lane.mjs",
@@ -72,22 +72,34 @@
 		]
 	},
 	"dependencies": {
-		"@earendil-works/pi-tui": "0.85.1",
 		"@heyhuynhgiabuu/pi-pretty": "0.6.27"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": ">=0.85.1",
+		"@earendil-works/pi-coding-agent": ">=0.99.1",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
 		"@earendil-works/pi-coding-agent": {
 			"optional": true
+		},
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@earendil-works/pi-coding-agent": ">=1.0.0",
+		"@earendil-works/pi-ai": ">=1.0.0",
+		"@earendil-works/pi-tui": ">=1.0.0",
 		"@types/node": "^24.13.3",
 		"typescript": "^5.9.3"
 	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
 	"packageManager": "pnpm@11.1.1"
 }

package/runtime/child-package-injection.mjs

@@ -0,0 +1,63 @@
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
+import { isAbsolute } from "node:path";
+
+// #1690: the gentle-shell launcher injects the gentle-pi package into the
+// parent pi with `-e` instead of a settings declaration, so delegated children
+// would otherwise start without it. The launcher records the exact extension
+// set it injected in this variable; the subagent runner forwards that set to
+// every child. Kept free of launcher imports so the runner can load it cheaply.
+export const CHILD_PACKAGE_INJECTION_ENV = "GENTLE_SHELL_CHILD_PACKAGE_INJECTION";
+
+const CHILD_PACKAGE_INJECTION_VERSION = 1;
+
+
+
+
+
+
+
+
+
+export function encodeChildPackageInjection(value                       )         {
+	return JSON.stringify({
+		version: CHILD_PACKAGE_INJECTION_VERSION,
+		noExtensions: value.noExtensions,
+		extensionPaths: value.extensionPaths,
+	});
+}
+
+// Returns undefined for an absent or invalid value and never throws: a bad
+// signal must degrade to "no forwarding", not break a child launch. The path
+// flavor is injectable so tests can check Windows paths on any platform.
+export function parseChildPackageInjection(
+	env                                    ,
+	pathFlavor                                        = { isAbsolute },
+)                                    {
+	const raw = env[CHILD_PACKAGE_INJECTION_ENV];
+	if (raw === undefined || raw.length === 0) return undefined;
+	let parsed         ;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+	const record = parsed                           ;
+	if (record.version !== CHILD_PACKAGE_INJECTION_VERSION) return undefined;
+	if (typeof record.noExtensions !== "boolean") return undefined;
+	const paths = record.extensionPaths;
+	if (!Array.isArray(paths) || paths.length === 0) return undefined;
+	const extensionPaths           = [];
+	for (const path of paths) {
+		if (typeof path !== "string" || path.length === 0 || !pathFlavor.isAbsolute(path)) return undefined;
+		extensionPaths.push(path);
+	}
+	return { noExtensions: record.noExtensions, extensionPaths };
+}
+
+// Plain argv elements for a child pi: spawned without a shell, so no quoting.
+export function childPackageExtensionArgs(injection                       )           {
+	const args = injection.noExtensions ? ["--no-extensions"] : [];
+	for (const path of injection.extensionPaths) args.push("--extension", path);
+	return args;
+}

package/runtime/gentle-ai-binary.mjs

@@ -2,7 +2,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, posix, relative, resolve, win32 } from "node:path";
 import {
 	GENTLE_AI_INSTALL_METHOD,
 	GENTLE_AI_WINDOWS_SOURCE_MODULE,
@@ -14,6 +14,8 @@ import {
 	isWindowsGoSumdbSourceTarget,
 	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 { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
@@ -46,6 +48,84 @@ export function gentleAiBinaryPath(
 	);
 }
 
+// ---------------------------------------------------------------------------
+// Bundled isolation (S9). The bundled launcher (bin/gentle-shell.mjs) gives Pi
+// and setup GENTLE_SHELL_PREFIX, its prefix. Every gentle-ai run a bundled
+// gentle-pi starts gets Gentle AI's own variables (gentle-ai #5462): its state,
+// backups and telemetry under <prefix>/gentle-ai, the gentle-pi config folder
+// <prefix>/config/gentle-ai for its persona and background subagent files
+// (and, for Gentle AI 4.0.0, GENTLE_PI_CONFIG_HOME=<prefix>/config), the pinned
+// Engram in runtime/ with no Engram acquisition or dependency probe, and no
+// self-update. They are never put in Pi's own environment: the agent's shell
+// inherits it, and a gentle-ai the user runs there stays the user's. A
+// gentle-ai release without #5462 ignores them.
+// ---------------------------------------------------------------------------
+
+
+
+
+
+
+
+
+
+
+
+
+export function bundledGentleAiPaths(prefix        , platform         = process.platform)                       {
+	const path = platform === "win32" ? win32 : posix;
+	return {
+		home: path.join(prefix, "gentle-ai"),
+		piConfigParent: bundledPiConfigParent(prefix, platform),
+		piConfig: bundledPiConfigDir(prefix, platform),
+		engram: path.join(prefix, "runtime", `engram-${engramPinVersion}`, platform === "win32" ? "engram.exe" : "engram"),
+	};
+}
+
+/**
+ * `env` plus GENTLE_AI_HOME, GENTLE_AI_PI_CONFIG_DIR, GENTLE_AI_ENGRAM_BIN
+ * (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.
+ */
+export function gentleAiIsolationEnv(
+	env                   ,
+	options                                              = {},
+)                    {
+	const platform = options.platform ?? process.platform;
+	const prefix = runningBundledPrefix(env, { packageRoot: options.packageRoot, platform });
+	if (prefix === undefined) return env;
+	const paths = bundledGentleAiPaths(prefix, platform);
+	let engram = false;
+	try {
+		engram = lstatSync(paths.engram).isFile();
+	} catch {
+		// Not published (a prefix from before Engram shipped): Gentle AI gets none.
+	}
+	// Gentle AI 4.0.0 ignores GENTLE_AI_ENGRAM_BIN and looks `engram` up on PATH
+	// first, then falls back to Homebrew (`brew tap`, #2105): the pinned one goes first.
+	const pathKey = Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? (platform === "win32" ? "Path" : "PATH");
+	const pathModule = platform === "win32" ? win32 : posix;
+	const path = engram
+		? { [pathKey]: [pathModule.dirname(paths.engram), ...(env[pathKey] ?? "").split(pathModule.delimiter).filter((entry) => entry.length > 0)].join(pathModule.delimiter) }
+		: {};
+	return {
+		...env,
+		...path,
+		GENTLE_AI_HOME: paths.home,
+		GENTLE_AI_PI_CONFIG_DIR: paths.piConfig,
+		...(engram ? { GENTLE_AI_ENGRAM_BIN: paths.engram } : {}),
+		GENTLE_AI_NO_SELF_UPDATE: "1",
+		// Gentle AI 4.0.0 knows no GENTLE_AI_PI_CONFIG_DIR: it writes gentle-pi's
+		// background-subagents policy to <GENTLE_PI_CONFIG_HOME>/gentle-ai, the same
+		// folder. Only these Gentle AI processes get it, never Pi or its shell.
+		GENTLE_PI_CONFIG_HOME: paths.piConfigParent,
+	};
+}
+
 function sha256(value        )         {
 	return createHash("sha256").update(value).digest("hex");
 }
@@ -56,7 +136,8 @@ function sha256(value        )         {
 // Two explicit activation paths, in precedence order:
 //   1. GENTLE_PI_GENTLE_AI_DEV_BINARY (session override, absolute path), then
 //   2. the persistent registration file at
-//      <GENTLE_PI_CONFIG_HOME|~/.pi/gentle-ai>/dev-binary.json with the strict
+//      <config home>/dev-binary.json (a bundled prefix's gentle-pi, else
+//      GENTLE_PI_CONFIG_HOME, else ~/.pi/gentle-ai) 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
@@ -114,7 +195,7 @@ function ambientDevBinaryEnvironment()                               {
 }
 
 export function gentleAiDevBinaryRegistrationPath(environment                               = ambientDevBinaryEnvironment())         {
-	const configHome = environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
+	const configHome = bundledGentlePiConfigHome(environment.env) ?? environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
 	return join(configHome, "dev-binary.json");
 }
 
@@ -269,6 +350,30 @@ function sameFile(before                              , after
 	return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs;
 }
 
+// Reading and hashing the whole binary on every native call is expensive, and
+// on Windows antivirus scans each read. The digest is reused only while the
+// file keeps its full identity; any rewrite changes ctime, which callers cannot
+// set, so a replaced binary is always hashed again. Keyed per reader so an
+// injected reader never sees another reader's digest.
+const binaryDigestCache = new WeakMap                                                                                               ();
+
+function binaryIdentity(path        )         {
+	const details = lstatSync(path, { bigint: true });
+	return [details.dev, details.ino, details.size, details.mtimeNs, details.ctimeNs].join(":");
+}
+
+function binaryDigest(path        , readBinary                          )         {
+	let entries = binaryDigestCache.get(readBinary);
+	if (entries === undefined) binaryDigestCache.set(readBinary, entries = new Map());
+	const identity = binaryIdentity(path);
+	const cached = entries.get(path);
+	if (cached?.identity === identity) return cached.sha256;
+	const digest = sha256(readBinary(path));
+	if (binaryIdentity(path) === identity) entries.set(path, { identity, sha256: digest });
+	else entries.delete(path);
+	return digest;
+}
+
 export function resolveGentleAiBinary(
 	packageRoot = dirname(dirname(fileURLToPath(import.meta.url))),
 	platform = process.platform,
@@ -297,7 +402,7 @@ export function resolveGentleAiBinary(
 		const beforeManifest = lstatSync(manifestPath);
 		const manifestContents = readFileSync(manifestPath, "utf8");
 		const manifest = JSON.parse(manifestContents)                           ;
-		const binarySha256 = sha256(readBinary(binaryPath));
+		const binarySha256 = binaryDigest(binaryPath, readBinary);
 		const expected = expectedRuntimeManifest(platform, binarySha256, manifest);
 		if (!isCanonicalManifest(manifestContents, manifest, expected)) throw new Error("invalid runtime integrity manifest");
 		const afterBinary = lstatSync(binaryPath);