feat(profiles): bind the active profile to the parent session (#1064 1/2)

extensions/gentle-ai.ts

@@ -100,6 +100,7 @@ import {
 	type ProfilePinSource,
 	type ProfilePinStatus,
 } from "../lib/agent-profile-pin.ts";
+import { bindSessionProfile, readSessionProfileBinding } from "../lib/session-profile-binding.ts";
 import {
 	applyOrchestratorSettings,
 	readOrchestratorSettings,
@@ -3564,6 +3565,7 @@ function updateCurrentProfileFromSavedRouting(ctx: ExtensionContext, pi: Extensi
 
 type ProfilesPanelResult =
 	| { type: "apply"; name: string }
+	| { type: "apply-global"; name: string }
 	| { type: "create" }
 	| { type: "update"; name: string }
 	| { type: "duplicate"; name: string }
@@ -3751,6 +3753,7 @@ class ProfilesPanel implements OverlayComponent {
 	private readonly orchestratorSettings: OrchestratorSettingsReadResult;
 	// Actions reopen the panel, refreshing this snapshot without disk reads during rendering.
 	private readonly pinStatus: ProfilePinStatus | undefined;
+	private readonly sessionBoundName: string | undefined;
 
 	constructor(
 		file: AgentProfilesFile,
@@ -3764,6 +3767,7 @@ class ProfilesPanel implements OverlayComponent {
 		saveSnapshot: ProfilesSnapshotHandler,
 		requestRender: () => void,
 		pinStatus: () => ProfilePinStatus | undefined,
+		sessionBound: () => string | undefined,
 		feedback?: string,
 	) {
 		this.file = file;
@@ -3776,7 +3780,8 @@ class ProfilesPanel implements OverlayComponent {
 		this.rows = rows;
 		this.orchestratorSettings = orchestratorSettings;
 		this.pinStatus = pinStatus();
-		const items = buildProfileListItems(file, evaluateProfilePin(this.pinStatus, file.profiles).winner?.profile);
+		this.sessionBoundName = sessionBound();
+		const items = buildProfileListItems(file, evaluateProfilePin(this.pinStatus, file.profiles).winner?.profile, this.sessionBoundName);
 		this.listItems = items;
 		this.list = new NativeChoiceList<ProfileListItem>(
 			items,
@@ -3839,6 +3844,7 @@ class ProfilesPanel implements OverlayComponent {
 			this.requestRender();
 			return;
 		}
+		if (data === "a") return this.finish({ type: "apply-global", name });
 		if (data === "d") return this.finish({ type: "duplicate", name });
 		if (data === "r") return this.finish({ type: "rename", name });
 		if (data === "x") return this.finish({ type: "delete", name });
@@ -3964,7 +3970,7 @@ class ProfilesPanel implements OverlayComponent {
 
 	private renderFooterRow(width: number): string {
 		const hints =
-			"enter apply · c create · s snapshot · d duplicate · r rename · x delete · e export · i import · p pin · P share · j/k line · ctrl+j/k page · esc close";
+			"enter use in this session · a set as global default · c create · s snapshot · d duplicate · r rename · x delete · e export · i import · p pin · P share · j/k line · ctrl+j/k page · esc close";
 		const text = this.feedback ?? hints;
 		return [
 			this.renderText("│", "border"),
@@ -4000,6 +4006,14 @@ class ProfilesPanel implements OverlayComponent {
 			// any invalid or stale layer, and the scope sentence all come from the shared
 			// precedence rule the launch resolver uses.
 			...profilePinDetailLines(this.pinStatus, this.file.profiles).map((line) => this.renderLine(line, width, "muted")),
+			// gentle-shell#1064 slice 1: the binding is stored for this session and
+			// outranks the pin in the panel list, so it is named right after the pin
+			// layers. Launch resolution ships with slice 2 (gentle-shell#1558); this
+			// slice stores the binding only, launch routing is unchanged, and nothing
+			// was written.
+			...(this.sessionBoundName === undefined
+				? []
+				: [this.renderLine(`session        ${sanitizeTerminalText(this.sessionBoundName)} (session) — stored for this session; launch routing is unchanged; nothing was written`, width, "muted")]),
 			"",
 			this.renderLine("Profile routing", width, "accent"),
 			...this.indentLines(this.routingLines(profileRows, widths), width),
@@ -4056,13 +4070,15 @@ class ProfilesPanel implements OverlayComponent {
 	}
 }
 
+/** The full-screen profile picker: one visit per action, so every reopen reads fresh store, pin, orchestrator, and session-binding state. */
 async function showProfilesPanel(
 	ctx: ExtensionContext,
 	file: AgentProfilesFile,
 	currentConfig: AgentModelConfig,
 	selectedName: string | undefined,
 	saveSnapshot: ProfilesSnapshotHandler,
 	status?: string,
+	sessionBoundName?: string,
 ): Promise<ProfilesPanelResult> {
 	// Both orchestrator and pin state are snapshots for this panel visit.
 	// Actions (including p/P) reopen the panel and read fresh state.
@@ -4081,6 +4097,7 @@ async function showProfilesPanel(
 				saveSnapshot,
 				() => tui.requestRender(),
 				() => readProfilePinStatus(ctx.cwd),
+				() => sessionBoundName,
 				status,
 			);
 			const container = createNativeFullscreenInteraction({
@@ -4178,6 +4195,7 @@ function profileSnapshotFrom(
 	return snapshot;
 }
 
+/** Runs one finished panel action against the store and the live session, returning the file the reopened panel should show. */
 async function runProfilesPanelAction(
 	ctx: ExtensionContext,
 	live: LiveSession,
@@ -4188,6 +4206,30 @@ async function runProfilesPanelAction(
 ): Promise<AgentProfilesFile> {
 	switch (result.type) {
 		case "apply": {
+			if (!hasOwnProfile(file.profiles, result.name)) return file;
+			// gentle-shell#1064 slice 1: Enter binds the selected profile to this
+			// parent session. The binding is in-process state keyed by the session
+			// id: it writes no store marker, no global routing, no materialized
+			// stores, no agent frontmatter, no Pi settings, and no pin or declaration
+			// layer, pin or not. This slice stores the binding only: launch routing
+			// is unchanged until slice 2 (gentle-shell#1558) resolves the binding
+			// at launch. Refreshing the binding means selecting again.
+			const sessionId = ctx.sessionManager?.getSessionId?.();
+			if (typeof sessionId !== "string" || sessionId.length === 0) {
+				ctx.ui.notify(
+					`el Gentleman cannot bind profile "${result.name}" to this session: no parent session id is available here. Set it as the global default with a instead.`,
+					"warning",
+				);
+				return file;
+			}
+			bindSessionProfile(sessionId, result.name, normalizeModelConfig(file.profiles[result.name]) ?? {});
+			ctx.ui.notify(
+				`el Gentleman bound profile "${result.name}" to this session — shown as "${result.name} (session)". The binding is stored for this session; launch routing is unchanged. Nothing was written: the global routing, pins, and materialized stores are untouched. Set as global default with a.`,
+				"info",
+			);
+			return file;
+		}
+		case "apply-global": {
 			if (!hasOwnProfile(file.profiles, result.name)) return file;
 			// A pinned repository resolves its subagent routing from the profile at launch,
 			// so a global apply would move global state this repository never reads. When a
@@ -4688,6 +4730,7 @@ async function runProfilesPanelAction(
 	}
 }
 
+/** `/gentle:profiles`: seed or open the store, then loop the panel over one action at a time until it closes. */
 async function handleProfilesCommand(ctx: ExtensionContext, live: LiveSession): Promise<void> {
 	const path = profilesFilePath(gentleAiConfigHome());
 	const read = readProfilesFileResult(path);
@@ -4729,12 +4772,15 @@ async function handleProfilesCommand(ctx: ExtensionContext, live: LiveSession):
 		return next;
 	};
 	let selectedName: string | undefined;
+	const sessionBoundName = () => readSessionProfileBinding(ctx.sessionManager?.getSessionId?.())?.name;
 	let result = await showProfilesPanel(
 		ctx,
 		file,
 		await readEffectiveModelConfigAsync(ctx.cwd),
 		selectedName,
 		saveSnapshot,
+		undefined,
+		sessionBoundName(),
 	);
 	while (result.type !== "close") {
 		const report: ProfilesPanelReport = {};
@@ -4747,6 +4793,7 @@ async function handleProfilesCommand(ctx: ExtensionContext, live: LiveSession):
 			selectedName,
 			saveSnapshot,
 			report.status,
+			sessionBoundName(),
 		);
 	}
 }
@@ -6309,6 +6356,11 @@ const processRetainedNativeStatusSelections = new Map<PendingReviewConsentSessio
 // and a fresh primary-loop start resets it to 0.
 const processAgentEndSubagentDepth = new Map<PendingReviewConsentSessionKey, number>();
 
+// gentle-shell#1064 slice 1: the parent-session profile binding store lives in
+// lib/session-profile-binding.ts (in-process, keyed by parent session id). The
+// panel binds on Enter; the launch resolver, the shell status reader, and the
+// usage provider scope read the same store through the lib.
+
 // gentle-pi#677: gentle-ai#4309 owns anonymous usage telemetry end to end;
 // Pi only nudges it once per process. This is a plain process-lifetime
 // guard, not a session-keyed map, because the nudge is meant to fire at most
@@ -9149,6 +9201,7 @@ export const __testing = {
 	parseReviewControllerParameters,
 	parseReviewCaptureParameters,
 	parseReviewCaptureGroupParameters,
+	runProfilesPanelAction,
 	resolveReviewModeGate,
 	readEffectiveModelConfig,
 	readEffectiveModelConfigAsync,

lib/agent-profiles.ts

@@ -406,18 +406,28 @@ export interface ProfileListItem {
 	description: string;
 }
 
+/** One list item per saved profile, named with the markers that explain what a launch would use: the global `(active)` claim, plus `(pinned)` for the pin winner or `(session)` for this session's binding when either applies. */
 export function buildProfileListItems(
 	file: AgentProfilesFile,
 	pinned?: string,
+	sessionBound?: string,
 ): ProfileListItem[] {
 	return Object.entries(file.profiles).map(([name, config]) => {
 		const roles = profileRoleEntries(config).length;
 		const active = name === file.active ? `${name} (active)` : name;
+		// A pinned profile is the one this repository launches with, which is not the
+		// same thing as the globally active profile, so both are named. A session
+		// binding outranks the pin in this list (slice 1 stores it; slice 2,
+		// gentle-shell#1558, makes launches resolve it), so its marker wins on the
+		// same profile.
+		const label = name === sessionBound
+			? `${active} (session)`
+			: name === pinned
+				? `${active} (pinned)`
+				: active;
 		return {
 			id: name,
-			// A pinned profile is the one this repository launches with, which is not the
-			// same thing as the globally active profile, so both are named.
-			label: name === pinned ? `${active} (pinned)` : active,
+			label,
 			description: `${roles} ${roles === 1 ? "role" : "roles"}`,
 		};
 	});

lib/session-profile-binding.ts

@@ -0,0 +1,68 @@
+// 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 map 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.
+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 bindingsBySession = new Map<string, SessionProfileBinding>();
+
+/** 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;
+}

tests/agent-profiles.test.ts

@@ -767,3 +767,15 @@ test("formatOrchestratorSelection separates set, inherit, and inherit-with-think
 		"nan/glm5.3 · max",
 	);
 });
+
+test("buildProfileListItems marks the session-bound profile ahead of the pinned one", () => {
+	const file = createProfile(createProfile(emptyProfilesFile(), "work", { worker: { model: "zai/glm-4.7" } }), "personal", { solo: { model: "openai/o4-mini" } });
+	const items = buildProfileListItems(file, "work", "personal");
+	assert.equal(items.find((item) => item.id === "personal")?.label, "personal (session)");
+	assert.equal(items.find((item) => item.id === "work")?.label, "work (pinned)");
+	assert.equal(items.find((item) => item.id === "personal")?.description, "1 role");
+	const both = buildProfileListItems(file, "work", "work");
+	assert.equal(both.find((item) => item.id === "work")?.label, "work (session)", "the session marker outranks the pin marker on the same profile");
+	const unbound = buildProfileListItems(file, "work");
+	assert.equal(unbound.find((item) => item.id === "personal")?.label, "personal", "no session marker without a binding");
+});