gentle-pi 4.0.0 → 4.1.0

package/lib/selection-engine.ts

@@ -3,7 +3,7 @@ import { isKeyRelease, matchesKey, truncateToWidth, visibleWidth, type EditorCom
 
 /**
  * Native text-selection engine for GentlePromptEditor: shift+home / shift+end
- * selection, alt+a select-all, and replace-on-key (backspace / delete /
+ * selection, alt+e / alt+a select-all, and replace-on-key (backspace / delete /
  * printable character) with reverse-video highlight and a bottom-rule hint.
  * Ported from @exopro/pi-select-del so the petal prompt owns the feature
  * natively — no factory composition, no cross-extension focus handoff.
@@ -12,7 +12,10 @@ import { isKeyRelease, matchesKey, truncateToWidth, visibleWidth, type EditorCom
  *   - shift+home — anchor at the cursor, move to line start (held presses at
  *     the edge keep the selection; only a zero-width span collapses)
  *   - shift+end — anchor at the cursor, move to line end
- *   - alt+a — select all
+ *   - alt+e — select all; alt+a too when no extension shortcut claims it
+ *     (Gentle Agents owns alt+a by default, gentle-shell#1565)
+ *   - a registered extension shortcut always wins over these selection chords,
+ *     matching CustomEditor's own precedence
  *   - backspace / delete / printable character or bracketed paste over an
  *     active selection — replace it in one atomic edit (undo restores text AND cursor)
  *   - any other key — collapse the selection first, then behave natively
@@ -275,8 +278,10 @@ export class SelectionEngine {
 	 * Selection dispatch in front of the native chain. Selection and replace
 	 * keys are handled here; everything else collapses the anchor first, then
 	 * behaves natively. Degraded hosts keep pure native key handling.
+	 * `shortcut` probes registered extension shortcuts before a selection chord
+	 * is consumed; it returns true when a shortcut handled the key.
 	 */
-	handleInput(data: string, native: (data: string) => void): void {
+	handleInput(data: string, native: (data: string) => void, shortcut?: (data: string) => boolean): void {
 		if (this.degraded) {
 			native(data);
 			return;
@@ -314,12 +319,13 @@ export class SelectionEngine {
 			this.pasteBufferedBytes = 0;
 			this.pasteTail = "";
 			this.replaceSelectionWithPaste(frame, native);
-			if (remaining) this.handleInput(remaining, native);
+			if (remaining) this.handleInput(remaining, native, shortcut);
 			return;
 		}
 		// Kitty flag 2 release byte strings still match their own key, so
 		// releases must be dropped before any matchesKey.
 		if (isKeyRelease(data)) return;
+		if (this.isSelectionChord(data) && shortcut?.(data)) return;
 		if (matchesKey(data, "shift+home")) {
 			this.selectToLineEdge(false);
 			return;
@@ -328,7 +334,7 @@ export class SelectionEngine {
 			this.selectToLineEdge(true);
 			return;
 		}
-		if (matchesKey(data, "alt+a")) {
+		if (matchesKey(data, "alt+e") || matchesKey(data, "alt+a")) {
 			this.selectAll();
 			return;
 		}
@@ -424,7 +430,13 @@ export class SelectionEngine {
 		this.internals.tui.requestRender();
 	}
 
-	/** Select the entire editor text (alt+a). Cursor moves to the end of the last line. */
+	/** Chords the engine itself consumes; extension shortcuts are probed first. */
+	private isSelectionChord(data: string): boolean {
+		return matchesKey(data, "shift+home") || matchesKey(data, "shift+end")
+			|| matchesKey(data, "alt+e") || matchesKey(data, "alt+a");
+	}
+
+	/** Select the entire editor text (alt+e / alt+a). Cursor moves to the end of the last line. */
 	private selectAll(): void {
 		const lines = this.s.lines;
 		const lastLine = Math.max(0, lines.length - 1);

package/lib/session-change-capture.ts

@@ -5,7 +5,7 @@ import { dirname, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { resolveSessionWorktree, type WorktreeResolver } from "./session-worktree-registry.ts";
 import { SessionChanges, readChangeSnapshot, sameSnapshot, textSnapshot, isSessionChangeEvidence,
-	SESSION_CHANGE_ENTRY, SESSION_CHANGE_EVENT, SESSION_CHANGE_RELAY, type SessionChangeEvidence, type ChangeSnapshot } from "./session-changes.ts";
+	SESSION_CHANGE_ENTRY, SESSION_CHANGE_RELAY, type SessionChangeEvidence, type ChangeSnapshot } from "./session-changes.ts";
 
 const foreignPublishers = new WeakMap<ExtensionAPI, (sessionId: string, evidence: SessionChangeEvidence) => void>();
 /** Internal authenticated handoff from a successful child tool callback, never a model message or public event. */
@@ -17,7 +17,10 @@ interface Pending { sessionId: string; inputPath: string; path: string; root: st
 const normalized = (text: string) => text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
 const unknown = (): ChangeSnapshot => ({ kind: "unavailable", reason: "Tool snapshots could not be verified; diff unavailable." });
 
-/** Observe explicit write/edit outcomes, never infer ownership from Git status or shell text. */
+/**
+ * Observe explicit write/edit outcomes, never infer ownership from Git status or shell text.
+ * The evidence feeds session statistics and names the roots /gentle:changes reads from Git.
+ */
 export function installSessionChangeCapture(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env, resolver: WorktreeResolver = resolveSessionWorktree): void {
 	const child = env.GENTLE_PI_AGENTS_CHILD === "1";
 	const pending = new Map<string, Pending>();
@@ -26,8 +29,6 @@ export function installSessionChangeCapture(pi: ExtensionAPI, env: NodeJS.Proces
 	const publish = (evidence: SessionChangeEvidence) => {
 		if (!current || !store || current.sessionManager.getSessionId() !== store.sessionId) return;
 		if (store.record(evidence)) pi.appendEntry(SESSION_CHANGE_ENTRY, { sessionId: store.sessionId, evidence });
-		const notice = store.takeNotice();
-		pi.events.emit(SESSION_CHANGE_EVENT, { sessionId: store.sessionId, ...(notice ? { notice } : {}) });
 	};
 	foreignPublishers.set(pi, (sessionId, evidence) => {
 		if (!child && current?.sessionManager.getSessionId() === sessionId && isSessionChangeEvidence(evidence)) publish(evidence);

package/lib/session-changes.ts

@@ -1,12 +1,14 @@
 import { constants } from "node:fs";
-import { createHash } from "node:crypto";
 import { open } from "node:fs/promises";
 import { isAbsolute } from "node:path";
 import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
 import { changesModel, type ChangedFile, type WorktreeChanges } from "./shell-changes.ts";
+import { SESSION_WORKTREE_ENTRY } from "./session-worktree-registry.ts";
 
+// Captured write/edit evidence of a session and its subagents. It feeds
+// session statistics and tells /gentle:changes which roots the session
+// touched; the files Changes lists always come from Git.
 export const SESSION_CHANGE_ENTRY = "gentle-pi.session-change/v1";
-export const SESSION_CHANGE_EVENT = "gentle-pi:session-change";
 export const SESSION_CHANGE_RELAY = "gentle-pi:child-session-change";
 export const MAX_CHANGE_BYTES = 64 * 1024;
 const MAX_RECORDS = 256;
@@ -65,13 +67,29 @@ export function isSessionChangeEvidence(value: unknown): value is SessionChangeE
 export const sameSnapshot = (a: ChangeSnapshot, b: ChangeSnapshot): boolean =>
 	a.kind === b.kind && (a.kind === "absent" || (a.kind === "text" && b.kind === "text" && a.text === b.text));
 const snapshotText = (value: ChangeSnapshot) => value.kind === "text" ? value.text : "";
+const shown = (state: FileState) => Boolean(state.unavailable) || !sameSnapshot(state.before, state.after);
+
+/**
+ * Roots this session works in: its registered worktrees (own root, explicit and
+ * subagent registrations) and the roots of captured evidence (subagents in an
+ * independent repository). Only roots, never files.
+ */
+export function sessionChangeRoots(sessionId: string, entries: readonly Entry[]): string[] {
+	const roots = new Set<string>();
+	for (const entry of entries) {
+		if (entry.type !== "custom" || !entry.data || typeof entry.data !== "object") continue;
+		const data = entry.data as { sessionId?: unknown; root?: unknown; evidence?: unknown };
+		if (data.sessionId !== sessionId) continue;
+		if (entry.customType === SESSION_WORKTREE_ENTRY && typeof data.root === "string" && isAbsolute(data.root)) roots.add(data.root);
+		if (entry.customType === SESSION_CHANGE_ENTRY && isSessionChangeEvidence(data.evidence)) roots.add(data.evidence.root);
+	}
+	return [...roots];
+}
 
 export class SessionChanges {
 	private readonly seen = new Set<string>();
 	private readonly files = new Map<string, Map<string, FileState>>();
 	private bytes = 0;
-	private announced = false;
-	notice: string | undefined;
 	readonly sessionId: string;
 	private cached: WorktreeChanges[] | undefined;
 	constructor(sessionId: string, entries: readonly Entry[] = []) { this.sessionId = sessionId; this.restore(entries); }
@@ -86,10 +104,8 @@ export class SessionChanges {
 	record(evidence: SessionChangeEvidence): boolean {
 		if (!isSessionChangeEvidence(evidence) || this.seen.has(evidence.id)) return false;
 		const bytes = Buffer.byteLength(JSON.stringify(evidence));
-		if (this.seen.size >= MAX_RECORDS || this.bytes + bytes > MAX_SESSION_BYTES) {
-			this.notice = "Session change capture limit reached; additional changes are not displayed.";
-			return false;
-		}
+		// Bounds session-file growth; Changes itself lists from Git without a cap.
+		if (this.seen.size >= MAX_RECORDS || this.bytes + bytes > MAX_SESSION_BYTES) return false;
 		this.seen.add(evidence.id);
 		this.bytes += bytes;
 		if (sameSnapshot(evidence.before, evidence.after)) return false;
@@ -109,13 +125,13 @@ export class SessionChanges {
 	}
 	private changed(root: string): ChangedFile[] {
 		return [...(this.files.get(root) ?? [])].flatMap(([path, state]) => {
-			if (!state.unavailable && sameSnapshot(state.before, state.after)) return [];
+			if (!shown(state)) return [];
 			const patch = this.patch(path, state);
 			const patchLines = patch.split("\n");
 			const firstHunk = patchLines.findIndex(line => line.startsWith("@@"));
 			const lines = firstHunk < 0 ? [] : patchLines.slice(firstHunk + 1);
 			return [{
-				path, diffRevision: createHash("sha256").update(patch).digest("hex"), status: state.before.kind === "absent" ? "added" as const : state.after.kind === "absent" ? "deleted" as const : "modified" as const,
+				path, status: state.before.kind === "absent" ? "added" as const : state.after.kind === "absent" ? "deleted" as const : "modified" as const,
 				added: state.unavailable ? 0 : lines.filter(line => line.startsWith("+")).length,
 				deleted: state.unavailable ? 0 : lines.filter(line => line.startsWith("-")).length,
 				...(state.unavailable ? { countsUnavailable: state.unavailable } : {}),
@@ -131,17 +147,6 @@ export class SessionChanges {
 	}
 	get model() {
 		const trees = this.worktrees;
-		return { ...changesModel(trees.flatMap(tree => tree.model.files.map(file => ({ ...file, path: trees.length === 1 ? file.path : tree.root + "/" + file.path })))), ...(this.notice ? { notice: this.notice } : {}) };
-	}
-	/** Return the capture-limit notice once, for a single user notification. The `notice` field stays set. */
-	takeNotice(): string | undefined {
-		if (!this.notice || this.announced) return undefined;
-		this.announced = true;
-		return this.notice;
-	}
-	async refresh() { return this.model; }
-	loadDiff(root: string, file: ChangedFile): string {
-		const state = this.files.get(root)?.get(file.path);
-		return state ? this.patch(file.path, state) : "No captured agent diff for this file.";
+		return changesModel(trees.flatMap(tree => tree.model.files.map(file => ({ ...file, path: trees.length === 1 ? file.path : tree.root + "/" + file.path }))));
 	}
 }

package/lib/session-profile-binding.ts

@@ -0,0 +1,83 @@
+// Session-bound active profiles (gentle-shell#1064, slice 1).
+//
+// One parent Pi session may bind one saved profile for its own launches without
+// touching any shared state: no clone pin (`p`), no repository declaration (`P`),
+// no global routing, no materialized stores, no agent frontmatter, no Pi default
+// settings. The binding is an in-process store keyed by the parent session id, so
+// concurrent Pi processes are isolated by construction and a resumed session
+// starts from the shared layers (`p → P → global`) until it binds again.
+// Persistence across resume and reload semantics are deliberate follow-up
+// slices; this module never writes a file.
+//
+// Pi loads every extension entrypoint with its own Jiti instance and
+// `moduleCache: false` (loader.js `loadExtensionModule`), so a module-local Map
+// would be re-evaluated per entrypoint: the panel writes one copy while the
+// launch, usage, and status readers hold their own empty copies
+// (gentle-shell#1558). The store therefore lives on `globalThis` behind a
+// `Symbol.for` key, which every evaluation of this module in one process
+// resolves to the same symbol and therefore the same shared Map.
+import type { AgentModelConfig } from "./model-routing-authority.ts";
+
+/** A session's bound profile: its saved name plus the routing snapshot taken at bind time. */
+export interface SessionProfileBinding {
+	readonly name: string;
+	readonly modelProfiles: AgentModelConfig;
+}
+
+const bindingsRegistryKey = Symbol.for("gentle-pi:session-profile-bindings");
+
+/** The one process-wide binding store, shared across every extension entrypoint that imports this module. */
+function bindingsBySession(): Map<string, SessionProfileBinding> {
+	const holder = globalThis as { [bindingsRegistryKey]?: Map<string, SessionProfileBinding> };
+	(holder[bindingsRegistryKey] ??= new Map());
+	return holder[bindingsRegistryKey]!;
+}
+
+/** Copy one routing snapshot level deep — the layer a defensive copy needs, so a binding never aliases its source or its readers. */
+function cloneProfiles(profiles: AgentModelConfig): AgentModelConfig {
+	return Object.fromEntries(Object.entries(profiles).map(([agent, entry]) => [agent, { ...entry }]));
+}
+
+/**
+ * Bind (or rebind) one parent session to a profile. The routing snapshot is
+ * copied, so later edits to the caller's object or to the saved profile
+ * definition never mutate a session that already bound it; refreshing a bound
+ * session requires an explicit re-selection.
+ */
+export function bindSessionProfile(sessionId: string, name: string, modelProfiles: AgentModelConfig): void {
+	bindingsBySession().set(sessionId, { name, modelProfiles: cloneProfiles(modelProfiles) });
+}
+
+/**
+ * Read a session's binding as a private copy. Returns `undefined` for unknown,
+ * cleared, or undefined session ids: an unbound session keeps resolving the
+ * shared layers exactly as before.
+ */
+export function readSessionProfileBinding(sessionId: string | undefined): SessionProfileBinding | undefined {
+	if (sessionId === undefined) return undefined;
+	const binding = bindingsBySession().get(sessionId);
+	return binding === undefined ? undefined : { name: binding.name, modelProfiles: cloneProfiles(binding.modelProfiles) };
+}
+
+/** Remove one session's binding without touching any other session's. */
+export function clearSessionProfileBinding(sessionId: string): void {
+	bindingsBySession().delete(sessionId);
+}
+
+/** Testing-only reset of every binding. */
+export function resetSessionProfileBindingsForTesting(): void {
+	bindingsBySession().clear();
+}
+
+/**
+ * The launch-time precedence for wholesale routing replacement: a session
+ * binding outranks a winning pin, a pin alone still replaces, and neither
+ * leaves today's routing untouched. Named so the precedence rule a launch and
+ * the status display agree on lives in exactly one place.
+ */
+export function sessionOrPinModelProfiles(
+	session: AgentModelConfig | undefined,
+	pin: AgentModelConfig | undefined,
+): AgentModelConfig | undefined {
+	return session ?? pin;
+}

package/lib/session-profile-freeze.ts

@@ -0,0 +1,266 @@
+// Inherited profile freeze (gentle-shell#1064 slice 3b-ii).
+//
+// A parent session that never pressed Enter in `/gentle:profiles` resolves the
+// shared defaults `p → P → G` (local pin, repository declaration, global
+// `active` in profiles.json) ONCE, at startup, and keeps that snapshot with its
+// origin. Changing a default later only affects new sessions, exactly like Pi's
+// "set as default" for the orchestrator model; an open session changes profile
+// only through its own Enter. Each launch re-resolves the defaults to compare
+// and shows one drift notice per distinct change.
+//
+// Precedence, the single rule every consumer reads through
+// `resolveSessionProfile`:
+//
+//   explicit Enter binding  →  frozen inherited snapshot  →  live p → P → G
+//
+// The live resolution applies only in `follow` mode (GENTLE_PI_PROFILE_FOLLOW=1,
+// for CI and headless runs), in subagent children (their routing comes from the
+// parent through --model), and when no session id is available. In `follow`
+// mode the orchestrator still comes from the startup profile while children
+// follow later defaults: an accepted, documented limitation.
+//
+// The frozen state is in-process only, like the explicit binding of slice 2: it
+// lives on `globalThis` behind a `Symbol.for` key because Pi evaluates this
+// module once per extension entrypoint. A resumed session (`--resume`,
+// `--continue`, `--session`) therefore freezes again from the current defaults,
+// and its drift memory starts empty. Persisting the freeze as a
+// `gentle-pi.session-profile/v1` entry with origin `local | repo | global` is
+// the integration point with slice 3b-i.
+import { createHash } from "node:crypto";
+import { profileRoleEntries, profilesFilePath, readProfilesFileResult } from "./agent-profiles.ts";
+import { readProfilePinStatus, resolveProfilePin, resolveUnversionedProjectProfile } from "./agent-profile-pin.ts";
+import type { AgentModelConfig } from "./model-routing-authority.ts";
+import { readSessionProfileBinding } from "./session-profile-binding.ts";
+import type { WorktreeIdentity, WorktreeResolver } from "./session-worktree-registry.ts";
+
+/** Opt-in that keeps the live `p → P → G` resolution instead of freezing it at startup. */
+export const PROFILE_FOLLOW_ENV = "GENTLE_PI_PROFILE_FOLLOW";
+
+/** Which shared default supplied an inherited profile. */
+export type InheritedProfileOrigin = "local" | "repo" | "global";
+
+/** A profile resolved from the shared defaults: its name, its origin, and its role routing. */
+export interface InheritedProfile {
+	readonly name: string;
+	readonly origin: InheritedProfileOrigin;
+	readonly modelProfiles: AgentModelConfig;
+}
+
+/** A frozen session: `profile` is `undefined` when no layer had a profile at startup. */
+export interface FrozenInheritedProfile {
+	readonly profile: InheritedProfile | undefined;
+}
+
+/**
+ * The profile a session uses. `inherited` is the startup snapshot (with or
+ * without a profile); `follow` and `live` carry the current defaults.
+ */
+export type SessionProfileResolution =
+	| { kind: "explicit"; name: string; modelProfiles: AgentModelConfig }
+	| { kind: "inherited"; profile: InheritedProfile | undefined }
+	| { kind: "follow"; profile: InheritedProfile | undefined }
+	| { kind: "live"; profile: InheritedProfile | undefined };
+
+export interface InheritedProfileOptions {
+	cwd: string;
+	configHome: string;
+	resolveWorktree?: WorktreeResolver;
+}
+
+export interface SessionProfileOptions extends InheritedProfileOptions {
+	sessionId: string | undefined;
+	env?: NodeJS.ProcessEnv;
+}
+
+interface FreezeRegistry {
+	frozen: Map<string, FrozenInheritedProfile>;
+	// Drift fingerprints already reported, per session.
+	notified: Map<string, Set<string>>;
+}
+
+const freezeRegistryKey = Symbol.for("gentle-pi:session-profile-freeze");
+
+function registry(): FreezeRegistry {
+	const holder = globalThis as { [freezeRegistryKey]?: FreezeRegistry };
+	(holder[freezeRegistryKey] ??= { frozen: new Map(), notified: new Map() });
+	return holder[freezeRegistryKey]!;
+}
+
+function cloneProfiles(profiles: AgentModelConfig): AgentModelConfig {
+	return Object.fromEntries(Object.entries(profiles).map(([agent, entry]) => [agent, { ...entry }]));
+}
+
+function cloneProfile(profile: InheritedProfile | undefined): InheritedProfile | undefined {
+	return profile === undefined ? undefined : { name: profile.name, origin: profile.origin, modelProfiles: cloneProfiles(profile.modelProfiles) };
+}
+
+function roleRouting(config: AgentModelConfig): AgentModelConfig {
+	return Object.fromEntries(profileRoleEntries(config).map(([agent, entry]) => [agent, { ...entry }]));
+}
+
+export function profileFollowEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[PROFILE_FOLLOW_ENV] === "1";
+}
+
+function isChildSession(env: NodeJS.ProcessEnv): boolean {
+	return env.GENTLE_PI_AGENTS_CHILD === "1";
+}
+
+/**
+ * The shared defaults `p → P → G` for one directory, with the layer that won.
+ * Pin layers keep `resolveProfilePin` semantics; outside a Git worktree the
+ * repository declaration is read as admission does for non-Git projects; the
+ * global layer is the `active` profile of profiles.json. The orchestrator key
+ * is never part of the routing. `undefined` means no layer has a profile.
+ */
+export function resolveInheritedProfile(options: InheritedProfileOptions): InheritedProfile | undefined {
+	// One worktree lookup serves both the pin layers and the non-Git check.
+	let resolved = false;
+	let identity: WorktreeIdentity | undefined;
+	const resolveWorktree: WorktreeResolver | undefined = options.resolveWorktree === undefined ? undefined : (cwd, base) => {
+		if (!resolved) {
+			resolved = true;
+			identity = options.resolveWorktree!(cwd, base);
+		}
+		return identity;
+	};
+	const pin = resolveProfilePin({ cwd: options.cwd, configHome: options.configHome, resolveWorktree });
+	if (pin !== undefined) return { name: pin.profile, origin: pin.source, modelProfiles: pin.modelProfiles };
+	if (readProfilePinStatus(options.cwd, resolveWorktree) === undefined) {
+		const declaration = resolveUnversionedProjectProfile(options.cwd, options.configHome);
+		if (declaration !== undefined) return { name: declaration.profile, origin: "repo", modelProfiles: declaration.modelProfiles };
+	}
+	const store = readProfilesFileResult(profilesFilePath(options.configHome));
+	if (store.status !== "valid" || store.file.active === undefined) return undefined;
+	const active = store.file.active;
+	if (!Object.prototype.hasOwnProperty.call(store.file.profiles, active)) return undefined;
+	return { name: active, origin: "global", modelProfiles: roleRouting(store.file.profiles[active]!) };
+}
+
+/** A copy of one session's frozen snapshot, or `undefined` when it never froze. */
+export function readFrozenInheritedProfile(sessionId: string | undefined): FrozenInheritedProfile | undefined {
+	if (sessionId === undefined) return undefined;
+	const frozen = registry().frozen.get(sessionId);
+	return frozen === undefined ? undefined : { profile: cloneProfile(frozen.profile) };
+}
+
+function freezes(options: SessionProfileOptions): boolean {
+	const env = options.env ?? process.env;
+	return options.sessionId !== undefined && options.sessionId.length > 0 && !isChildSession(env) && !profileFollowEnabled(env);
+}
+
+// Only called after `freezes(options)`, which guarantees a session id.
+function frozenOrFreeze(options: SessionProfileOptions): FrozenInheritedProfile {
+	const store = registry().frozen;
+	const sessionId = options.sessionId!;
+	let frozen = store.get(sessionId);
+	if (frozen === undefined) {
+		frozen = { profile: cloneProfile(resolveInheritedProfile(options)) };
+		store.set(sessionId, frozen);
+	}
+	return { profile: cloneProfile(frozen.profile) };
+}
+
+/**
+ * Freeze a parent session's inherited profile at startup. Idempotent: the
+ * first snapshot wins, so a session keeps it across `/reload` in the same
+ * process. Children and `follow` sessions never freeze.
+ */
+export function freezeSessionProfileAtStartup(options: SessionProfileOptions): void {
+	if (freezes(options)) frozenOrFreeze(options);
+}
+
+/**
+ * The single precedence rule for launch, status and Usage. A parent session
+ * that has not frozen yet freezes here, so the snapshot never depends on which
+ * extension's `session_start` ran first.
+ */
+export function resolveSessionProfile(options: SessionProfileOptions): SessionProfileResolution {
+	const explicit = readSessionProfileBinding(options.sessionId);
+	if (explicit !== undefined) return { kind: "explicit", name: explicit.name, modelProfiles: explicit.modelProfiles };
+	if (freezes(options)) return { kind: "inherited", profile: frozenOrFreeze(options).profile };
+	const env = options.env ?? process.env;
+	const profile = resolveInheritedProfile(options);
+	return isChildSession(env) || !profileFollowEnabled(env) ? { kind: "live", profile } : { kind: "follow", profile };
+}
+
+/** The routing that replaces subagent model profiles, or `undefined` for today's routing. */
+export function sessionProfileModelProfiles(resolution: SessionProfileResolution): AgentModelConfig | undefined {
+	return resolution.kind === "explicit" ? resolution.modelProfiles : resolution.profile?.modelProfiles;
+}
+
+/**
+ * The routing one launch target uses under a resolution read once per request.
+ * Explicit and frozen profiles belong to the session, so they apply wherever
+ * the launch goes, a foreign repository included; a `follow` or `live`
+ * resolution reads the defaults of the target itself. A session frozen without
+ * a profile has nothing to carry into a foreign repository, so that
+ * repository keeps its own pin layers (local pin, then declaration), as
+ * before the freeze; the global active profile is not the repository's own
+ * default and does not apply there either.
+ */
+export function sessionProfileRoutingAt(
+	resolution: SessionProfileResolution,
+	target: InheritedProfileOptions & { foreignRepository?: boolean },
+): AgentModelConfig | undefined {
+	if (resolution.kind === "explicit") return resolution.modelProfiles;
+	if (resolution.kind === "inherited") {
+		if (resolution.profile !== undefined || target.foreignRepository !== true) return resolution.profile?.modelProfiles;
+		return resolveProfilePin(target)?.modelProfiles;
+	}
+	return resolveInheritedProfile(target)?.modelProfiles;
+}
+
+/** The status label, spelled as before: `name (session)`, `name (local)`, `name (repo)`, or the bare global name. */
+export function sessionProfileLabel(resolution: SessionProfileResolution): string | undefined {
+	if (resolution.kind === "explicit") return `${resolution.name} (session)`;
+	const profile = resolution.profile;
+	if (profile === undefined) return undefined;
+	return profile.origin === "global" ? profile.name : `${profile.name} (${profile.origin})`;
+}
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+// The origin does not route anything: the same profile reached through another
+// layer is not drift.
+function fingerprint(profile: InheritedProfile | undefined): string {
+	if (profile === undefined) return "none";
+	return createHash("sha256").update(stableJson({ name: profile.name, modelProfiles: profile.modelProfiles })).digest("hex");
+}
+
+function describe(profile: InheritedProfile | undefined): string {
+	return profile === undefined ? "no profile" : `"${profile.name}" (${profile.origin})`;
+}
+
+/**
+ * Compare a frozen inherited session with the current defaults. Returns the
+ * one-line notice the first time a given current default differs from the
+ * snapshot, and `undefined` otherwise: the same change is never reported
+ * twice in one session. Explicit bindings, `follow` sessions and children are
+ * never compared. The comparison never adopts the new default.
+ */
+export function inheritedProfileDriftNotice(options: SessionProfileOptions): string | undefined {
+	const resolution = resolveSessionProfile(options);
+	if (resolution.kind !== "inherited") return undefined;
+	const current = resolveInheritedProfile(options);
+	const key = fingerprint(current);
+	if (key === fingerprint(resolution.profile)) return undefined;
+	const notified = registry().notified;
+	const seen = notified.get(options.sessionId!) ?? new Set<string>();
+	if (seen.has(key)) return undefined;
+	seen.add(key);
+	notified.set(options.sessionId!, seen);
+	return `el Gentleman: the default profile changed to ${describe(current)}, this session keeps ${describe(resolution.profile)}. Press Enter on a profile in /gentle:profiles to adopt it.`;
+}
+
+/** Testing-only reset of every frozen snapshot and drift memory. */
+export function resetFrozenInheritedProfilesForTesting(): void {
+	registry().frozen.clear();
+	registry().notified.clear();
+}

package/lib/session-worktree-registry.ts

@@ -1,7 +1,7 @@
 import { execFileSync } from "node:child_process";
-import { realpathSync, statSync } from "node:fs";
+import { lstatSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 export const SESSION_WORKTREE_ENTRY = "gentle-pi.session-worktree/v1";
 export const SESSION_WORKTREE_CHANGED = "gentle-pi:session-worktree-changed";
@@ -23,12 +23,16 @@ export function worktreeGitEnvironment(env: NodeJS.ProcessEnv = process.env): No
 }
 
 // Match Pi's ordinary path spelling; Git, not the argument, establishes identity.
+function canonicalDirectory(path: string, cwd: string): string {
+	let spelling = path.replace(/^@/, "").replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
+	if (spelling === "~" || spelling.startsWith("~/")) spelling = homedir() + spelling.slice(1);
+	const canonical = realpathSync(resolve(cwd, spelling));
+	return statSync(canonical).isDirectory() ? canonical : dirname(canonical);
+}
+
 export function resolveSessionWorktreeWithGit(path: string, cwd: string, run: typeof execFileSync = execFileSync): WorktreeIdentity | undefined {
 	try {
-		let spelling = path.replace(/^@/, "").replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
-		if (spelling === "~" || spelling.startsWith("~/")) spelling = homedir() + spelling.slice(1);
-		const canonical = realpathSync(resolve(cwd, spelling));
-		const directory = statSync(canonical).isDirectory() ? canonical : dirname(canonical);
+		const directory = canonicalDirectory(path, cwd);
 		// Ambient Git routing must not redirect a path into another repository.
 		const env = worktreeGitEnvironment();
 		const git = (arg: string) => String(run("git", ["--no-optional-locks", "-C", directory, "rev-parse", "--path-format=absolute", arg], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true, env })).replace(/\r?\n$/, "");
@@ -38,7 +42,69 @@ export function resolveSessionWorktreeWithGit(path: string, cwd: string, run: ty
 	}
 }
 
-export const resolveSessionWorktree: WorktreeResolver = resolveSessionWorktreeWithGit;
+// Filesystem identity of everything Git used to answer: no `.git` between the
+// directory and its root, and the same root, `.git` entry and common dir.
+// Undefined when any of it cannot be proven, so the answer is not memoized.
+function worktreeFingerprint(directory: string, identity: WorktreeIdentity): string | undefined {
+	const same = (a: string, b: string) => process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+	try {
+		for (let current = directory; !same(current, identity.root); current = dirname(current)) {
+			if (dirname(current) === current) return undefined;
+			try { lstatSync(join(current, ".git")); return undefined; }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return undefined; }
+		}
+		const marker = lstatSync(join(identity.root, ".git"));
+		const parts = [statSync(identity.root), marker, statSync(identity.commonDir)].map(entry => `${entry.dev}:${entry.ino}`);
+		// A linked worktree's `.git` file can be rewritten in place to another clone.
+		if (marker.isFile()) parts.push(`${marker.size}:${marker.mtimeMs}`);
+		return parts.join("|");
+	} catch {
+		return undefined;
+	}
+}
+
+export interface WorktreeMemoOptions { ttlMs?: number; now?: () => number }
+interface MemoEntry { identity: WorktreeIdentity; directory: string; fingerprint: string; expiresAt: number }
+const memoInvalidators = new Set<() => void>();
+
+// Startup asks the same (cwd, cwd) question from several extensions; each
+// answer costs two synchronous Git children. Only proven repositories are
+// memoized, and every hit re-checks their filesystem identity, so removal,
+// replacement, a nested `.git` and bootstrap (never cached) are seen at once.
+// The TTL bounds what stat cannot see, such as Git config edits.
+export function memoizeWorktreeResolver(resolver: WorktreeResolver, { ttlMs = 5000, now = Date.now }: WorktreeMemoOptions = {}): WorktreeResolver {
+	const memo = new Map<string, MemoEntry>();
+	memoInvalidators.add(() => memo.clear());
+	return (path, cwd) => {
+		const key = `${path}\u0000${cwd}`;
+		const cached = memo.get(key);
+		if (cached && cached.expiresAt > now()) {
+			try {
+				const directory = canonicalDirectory(path, cwd);
+				if (directory === cached.directory && worktreeFingerprint(directory, cached.identity) === cached.fingerprint) return { ...cached.identity };
+			} catch { /* Fall through to a fresh resolution. */ }
+		}
+		memo.delete(key);
+		const identity = resolver(path, cwd);
+		if (!identity) return undefined;
+		try {
+			const directory = canonicalDirectory(path, cwd);
+			const fingerprint = worktreeFingerprint(directory, identity);
+			if (fingerprint !== undefined) {
+				if (memo.size >= 256) memo.clear();
+				memo.set(key, { identity: { ...identity }, directory, fingerprint, expiresAt: now() + ttlMs });
+			}
+		} catch { /* Unprovable identity is returned but never memoized. */ }
+		return identity;
+	};
+}
+
+/** Drops every memoized worktree identity; the next lookup asks Git again. */
+export function clearSessionWorktreeMemo(): void {
+	for (const invalidate of memoInvalidators) invalidate();
+}
+
+export const resolveSessionWorktree: WorktreeResolver = memoizeWorktreeResolver(resolveSessionWorktreeWithGit);
 
 export function toolWorktreePath(name: string, input: Record<string, unknown>): string | undefined {
 	if (!["read", "write", "edit", "grep", "find", "ls"].includes(name)) return undefined;
@@ -82,7 +148,7 @@ export class SessionWorktreeRegistry {
 		if (!this.isCurrent()) throw new Error("Cannot register a worktree for an inactive session.");
 		const identity = this.refreshIdentity();
 		const target = this.resolver(path, this.cwd);
-		if (!target || !identity || target.commonDir !== identity.commonDir) throw new Error("Select an existing worktree in the same Git clone as this session.");
+		if (!target || !identity || target.commonDir !== identity.commonDir) throw new Error("Select an existing worktree in the same Git clone as this session. To work in an independent Git repository, delegate with subagent_run with repository_root instead; it asks for your consent first.");
 		return target.root;
 	}