gentle-pi 3.7.0 → 4.1.0

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-messaging-grants.ts

@@ -0,0 +1,135 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const MESSAGING_REASON_MIN_CHARACTERS = 8;
+export const MESSAGING_REASON_MAX_UTF8_BYTES = 512;
+
+const PREVIEW_CONTROL_CHARACTER = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+
+function escapePreviewText(value: string): string {
+	return Array.from(value, (character) => {
+		if (!PREVIEW_CONTROL_CHARACTER.test(character)) return character;
+		if (character === "\r") return "\\r";
+		if (character === "\n") return "\\n";
+		if (character === "\t") return "\\t";
+		return `\\u${character.codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}`;
+	}).join("");
+}
+
+export function normalizeMessagingReason(value: unknown): string {
+	if (typeof value !== "string") throw new Error("Cross-orchestrator communication requires a concrete reason of at least 8 trimmed characters and at most 512 UTF-8 bytes.");
+	const reason = value.trim();
+	if (Array.from(reason).length < MESSAGING_REASON_MIN_CHARACTERS || Buffer.byteLength(value, "utf8") > MESSAGING_REASON_MAX_UTF8_BYTES) {
+		throw new Error("Cross-orchestrator communication requires a concrete reason of at least 8 trimmed characters and at most 512 UTF-8 bytes.");
+	}
+	return reason;
+}
+
+/**
+ * Supported decision tokens for cross-orchestrator communication consent.
+ */
+export const MESSAGING_CONSENT_DECISIONS = {
+	ALLOW_ONCE: "Allow once",
+	ALLOW_SESSION: "Allow for this session",
+	DENY: "Deny",
+} as const;
+
+export type MessagingConsentDecision =
+	(typeof MESSAGING_CONSENT_DECISIONS)[keyof typeof MESSAGING_CONSENT_DECISIONS];
+
+/**
+ * Options for requesting human authorization before outbound cross-session communication.
+ */
+export interface MessagingConsentOptions {
+	/** Outbound message payload. */
+	message: string;
+	/** Concrete caller-supplied reason explaining why this communication is needed. */
+	reason: string;
+	/** Optional abort signal for request cancellation. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Ephemeral in-memory grant manager for cross-orchestrator communication.
+ * Permissions are scoped strictly to the live session identity and session manager instance.
+ */
+export class SessionMessagingGrants {
+	private readonly grants = new Map<string, Set<string>>();
+	private manager?: ExtensionContext["sessionManager"];
+	private sessionId?: string;
+
+	/**
+	 * Authorizes an outbound cross-orchestrator message to the given recipient.
+	 * Prompts the user interactively when no session-level grant exists, and fails closed otherwise.
+	 */
+	async authorize(
+		ctx: Pick<ExtensionContext, "sessionManager" | "hasUI" | "ui">,
+		recipient: string,
+		options: MessagingConsentOptions
+	): Promise<void> {
+		const message = options.message;
+		if (typeof message !== "string" || Buffer.byteLength(message, "utf8") > 8192) throw new Error("Cross-orchestrator message is invalid.");
+		const reason = normalizeMessagingReason(options.reason);
+		const signal = options.signal;
+		if (signal?.aborted) throw new Error("Cross-orchestrator message authorization aborted.");
+		const id = ctx.sessionManager.getSessionId();
+		if (!id) throw new Error("Cross-orchestrator communication requires an active session identity.");
+		if (this.manager !== ctx.sessionManager || this.sessionId !== id) {
+			this.grants.clear();
+			this.manager = ctx.sessionManager;
+			this.sessionId = id;
+		}
+		if (!ctx.hasUI || typeof ctx.ui?.select !== "function") {
+			throw new Error("Cross-orchestrator communication requires interactive human consent before sending.");
+		}
+		if (this.grants.get(id)?.has(recipient)) return;
+
+		const previewMessage = escapePreviewText(message);
+		const isTruncated = message.length > 200;
+		const messageLabel = isTruncated
+			? `Message (${message.length} chars, preview): ${escapePreviewText(message.slice(0, 197))}...`
+			: `Message: ${previewMessage}`;
+		const title = `Authorize cross-orchestrator message to ${escapePreviewText(recipient)}?\nReason: ${escapePreviewText(reason)}\n${messageLabel}`;
+
+		const selected = await ctx.ui.select(
+			title,
+			[
+				MESSAGING_CONSENT_DECISIONS.ALLOW_ONCE,
+				MESSAGING_CONSENT_DECISIONS.ALLOW_SESSION,
+				MESSAGING_CONSENT_DECISIONS.DENY,
+			],
+			{ signal }
+		);
+
+		if (signal?.aborted) throw new Error("Cross-orchestrator message authorization aborted.");
+		if (ctx.sessionManager !== this.manager || ctx.sessionManager.getSessionId() !== id) {
+			throw new Error("Session identity changed during authorization.");
+		}
+
+		if (selected === MESSAGING_CONSENT_DECISIONS.ALLOW_SESSION) {
+			const sessionGrants = this.grants.get(id) ?? new Set<string>();
+			sessionGrants.add(recipient);
+			this.grants.set(id, sessionGrants);
+			return;
+		}
+
+		if (selected === MESSAGING_CONSENT_DECISIONS.ALLOW_ONCE) {
+			return;
+		}
+
+		throw new Error("Cross-orchestrator communication denied by user.");
+	}
+
+	/**
+	 * Checks whether a live session-level grant exists for the target recipient in the current session.
+	 */
+	assertCurrent(ctx: Pick<ExtensionContext, "sessionManager">, recipient: string): boolean {
+		if (
+			ctx.sessionManager !== this.manager ||
+			!this.sessionId ||
+			ctx.sessionManager.getSessionId() !== this.sessionId
+		) {
+			return false;
+		}
+		return this.grants.get(this.sessionId)?.has(recipient) ?? false;
+	}
+}

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();
+}