pi-cursor-sdk 0.4.0 → 0.5.2

package/src/cursor-session-agent.ts

@@ -1,13 +1,15 @@
 import { createHash } from "node:crypto";
-import type { AgentModeOption, LocalAgentOptions, LocalAgentStore, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
+import type { AgentModeOption, AgentOptions, LocalAgentOptions, LocalAgentStore, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
+import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 import {
 	getRegisteredCursorPiToolBridge,
+	type CursorPiToolBridge,
 	type CursorPiBridgeToolRequest,
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
-import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
 import {
 	getMatchingCursorSessionAgentResumeHandle,
 	persistCursorSessionAgentResumeHandle,
@@ -46,6 +48,7 @@ export interface SessionCursorAgentLease {
 
 interface SessionCursorAgentPoolEntryBase {
 	poolKey: string;
+	storeRoot: string | undefined;
 	instanceId: number;
 	scopeKey: string;
 	sendState: SessionCursorAgentSendState;
@@ -112,25 +115,33 @@ function assertScopeAcceptsAcquire(scopeKey: string): void {
 	terminalDisposedScopeGenerations.delete(scopeKey);
 }
 
-function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey: string, poolKey: string, error: unknown): void {
+function samePoolIdentity(entry: SessionCursorAgentPoolEntryBase, poolKey: string, capturedStoreRoot: string | undefined): boolean {
+	return entry.poolKey === poolKey && entry.storeRoot === capturedStoreRoot;
+}
+
+function rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey: string, poolKey: string, storeRoot: string | undefined, error: unknown): void {
 	if (!(error instanceof SessionCursorAgentCreationSupersededError)) return;
 	const replacement = sessionAgentsByScope.get(scopeKey);
-	if (replacement && replacement.poolKey !== poolKey) {
+	if (replacement && !samePoolIdentity(replacement, poolKey, storeRoot)) {
 		throw error;
 	}
 }
 
 interface SessionCursorAgentCreateParams {
+	scope?: CursorTurnScope;
+	bridge?: CursorPiToolBridge;
 	apiKey: string;
 	agentMode: AgentModeOption;
 	cwd: string;
 	modelSelection: ModelSelection;
 	settingSources?: SettingSource[];
 	localSafety?: CursorLocalSafetyOptions;
+	agents?: AgentOptions["agents"];
 	useHttp1ForAgent?: boolean;
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
 	localResume?: boolean;
+	storeRoot?: string;
 	forceCreate?: boolean;
 	createAgent?: CursorSdkModule["Agent"]["create"];
 	resumeAgent?: CursorSdkModule["Agent"]["resume"];
@@ -205,12 +216,26 @@ function buildApiKeyPoolKeyFingerprint(apiKey: string): string {
 	return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
 
-function buildBridgePoolKeySuffix(): string {
-	const registeredBridge = getRegisteredCursorPiToolBridge();
+function buildBridgePoolKeySuffix(registeredBridge: CursorPiToolBridge | undefined): string {
 	if (!registeredBridge) return "bridge:absent";
 	return registeredBridge.getToolSurfaceSignature();
 }
 
+function buildCustomSubagentPoolKeySuffix(agents: AgentOptions["agents"]): string[] {
+	const definitions = Object.entries(agents ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	if (!definitions.length) return [];
+	const content = definitions.map(([name, entry]) => [
+		name, entry.description, entry.prompt,
+		entry.model === undefined ? null : entry.model === "inherit" ? "inherit" : {
+			id: entry.model.id,
+			params: [...(entry.model.params ?? [])].sort((a, b) =>
+				a.id < b.id ? -1 : a.id > b.id ? 1 : a.value < b.value ? -1 : a.value > b.value ? 1 : 0)
+				.map(({ id, value }) => ({ id, value })),
+		},
+	]);
+	return [`subagents:${createHash("sha256").update(JSON.stringify(content)).digest("hex")}`];
+}
+
 function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCreateParams): string {
 	return [
 		scopeKey,
@@ -224,7 +249,8 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 				? "http1:on"
 				: "http1:off",
 		buildApiKeyPoolKeyFingerprint(params.apiKey),
-		buildBridgePoolKeySuffix(),
+		buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
+		...buildCustomSubagentPoolKeySuffix(params.agents),
 	].join("\0");
 }
 
@@ -309,7 +335,7 @@ function commitSessionAgentSendForLease(
 			poolKey: entry.poolKey,
 			sendState: entry.sendState,
 			storeIdentity: entry.sessionStore.identity,
-		});
+		}, scopeKey);
 	}
 }
 
@@ -408,10 +434,10 @@ function leaseFromEntry(
 	};
 }
 
-function getCurrentReadyPoolEntry(scopeKey: string, poolKey: string): SessionCursorAgentReadyEntry | undefined {
+function getCurrentReadyPoolEntry(scopeKey: string, poolKey: string, storeRoot: string | undefined): SessionCursorAgentReadyEntry | undefined {
 	const current = sessionAgentsByScope.get(scopeKey);
 	if (current?.status !== "ready") return undefined;
-	if (current.poolKey !== poolKey) return undefined;
+	if (!samePoolIdentity(current, poolKey, storeRoot)) return undefined;
 	return current;
 }
 
@@ -430,7 +456,7 @@ async function tryLeaseReadyEntry(
 		await disposePoolEntryForScope(scopeKey);
 		return undefined;
 	}
-	const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey);
+	const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey, params.storeRoot);
 	if (!readyEntry) return undefined;
 	return leaseFromEntry(readyEntry, scopeKey, params, created);
 }
@@ -445,7 +471,7 @@ async function createSessionAgentEntry(
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	let sessionStore: OpenCursorSessionStore | undefined;
 	try {
-		const registeredBridge = getRegisteredCursorPiToolBridge();
+		const registeredBridge = params.bridge;
 		if (registeredBridge) {
 			bridgeRun = await registeredBridge.createRun({
 				onToolRequest: params.onBridgeToolRequest,
@@ -466,16 +492,15 @@ async function createSessionAgentEntry(
 			createAgent ??= sdk.Agent.create;
 			resumeAgent ??= sdk.Agent.resume;
 		}
-		const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey) : undefined;
+		const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey, scopeKey) : undefined;
 		const storeSelection = await openCursorSessionStoreForScope({
 			cwd: params.cwd,
 			scopeKey,
 			persistent: persistentStore,
-			hasResumeHandle: resumeHandle !== undefined,
-			resumeIdentity: resumeHandle?.storeIdentity,
+			storeRoot: params.storeRoot,
+			resume: resumeHandle ? { identity: resumeHandle.storeIdentity, agentId: resumeHandle.agentId } : undefined,
 		});
 		sessionStore = storeSelection.sessionStore;
-		const { identities } = storeSelection;
 		const resumeAttemptAllowed = storeSelection.resumeAttemptAllowed;
 		let resumeNotice = storeSelection.resumeFallback ? LOCAL_RESUME_FALLBACK_NOTICE : undefined;
 		const buildAgentOptions = () => ({
@@ -489,6 +514,7 @@ async function createSessionAgentEntry(
 				store: sessionStore!.store,
 			}),
 			...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
+			...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
 		});
 		let agent: SDKAgent | undefined;
 		let effectiveSendState = sendState;
@@ -500,9 +526,11 @@ async function createSessionAgentEntry(
 				resumed = true;
 			} catch {
 				if (persistentStore) resumeNotice = LOCAL_RESUME_FALLBACK_NOTICE;
-				if (!cursorSessionStoreIdentitiesEqual(sessionStore.identity, identities.sessionStore)) {
+				if (storeSelection.persistent && !cursorSessionStoreIdentitiesEqual(sessionStore.identity, storeSelection.identities.sessionStore)) {
+					const { identities } = storeSelection;
+					const replacement = await openCursorSessionStore(params.cwd, identities.sessionStore, identities.workspaceRoot, identities.storeRoot);
 					await sessionStore.dispose().catch(() => undefined);
-					sessionStore = await openCursorSessionStore(params.cwd, identities.sessionStore);
+					sessionStore = replacement;
 				}
 			}
 		}
@@ -513,6 +541,7 @@ async function createSessionAgentEntry(
 		return {
 			status: "ready",
 			poolKey: resolvedPoolKey,
+			storeRoot: params.storeRoot,
 			instanceId,
 			scopeKey,
 			agent,
@@ -546,9 +575,11 @@ export function invalidateSessionAgent(
 	if (options?.deadTransport) deadTransportScopeKeys.add(scopeKey);
 }
 
-export async function acquireSessionCursorAgent(params: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
-	const scopeKey = getCursorSessionScopeKey();
-	const persistentStore = getCursorSessionFile() !== undefined;
+export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
+	const params = { ...input, bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
+	const scopeKey = params.scope?.scopeKey ?? getCursorSessionScopeKey();
+	const persistentStore = (params.scope ? params.scope.sessionFile : getCursorSessionFile()) !== undefined;
+	params.storeRoot = persistentStore && params.storeRoot !== undefined ? normalizeCursorCustomStoreRoot(params.storeRoot) : undefined;
 
 	while (true) {
 		assertScopeAcceptsAcquire(scopeKey);
@@ -559,7 +590,7 @@ export async function acquireSessionCursorAgent(params: SessionCursorAgentCreate
 		const poolKey = buildSessionAgentPoolKey(scopeKey, params);
 		const state = getSessionCursorAgentPoolState(scopeKey);
 
-		if ((state.status === "ready" || state.status === "busy") && state.poolKey !== poolKey) {
+		if ((state.status === "ready" || state.status === "busy") && !samePoolIdentity(state, poolKey, params.storeRoot)) {
 			await disposePoolEntryForScope(scopeKey);
 			continue;
 		}
@@ -576,7 +607,7 @@ export async function acquireSessionCursorAgent(params: SessionCursorAgentCreate
 		}
 
 		if (state.status === "creating") {
-			if (state.poolKey !== poolKey) {
+			if (!samePoolIdentity(state, poolKey, params.storeRoot)) {
 				await disposePoolEntryForScope(scopeKey);
 				continue;
 			}
@@ -585,7 +616,7 @@ export async function acquireSessionCursorAgent(params: SessionCursorAgentCreate
 			} catch (error) {
 				if (error instanceof SessionCursorAgentCreationSupersededError) {
 					assertScopeAcceptsAcquire(scopeKey);
-					rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+					rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
 					continue;
 				}
 				throw error;
@@ -615,6 +646,7 @@ export async function acquireSessionCursorAgent(params: SessionCursorAgentCreate
 		placeholder = {
 			status: "creating",
 			poolKey,
+			storeRoot: params.storeRoot,
 			instanceId,
 			scopeKey,
 			sendState,
@@ -634,7 +666,7 @@ export async function acquireSessionCursorAgent(params: SessionCursorAgentCreate
 			}
 			if (error instanceof SessionCursorAgentCreationSupersededError) {
 				assertScopeAcceptsAcquire(scopeKey);
-				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+				rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
 				continue;
 			}
 			throw error;
@@ -677,8 +709,6 @@ export const __testUtils = {
 	resetSessionCursorAgent,
 	refreshSessionCursorAgentConfig,
 	disposeAllSessionCursorAgents,
-	buildApiKeyPoolKeyFingerprint,
-	buildSessionAgentPoolKey,
 	setDeadTransportAgentDisposeTimeoutMs(ms: number): number {
 		const previous = deadTransportAgentDisposeTimeoutMs;
 		deadTransportAgentDisposeTimeoutMs = ms;

package/src/cursor-session-compaction-prep.ts

@@ -1,19 +1,14 @@
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
-import { suppressCursorSessionAgentResumeHandlePersist } from "./cursor-session-agent-resume.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 
 /**
- * Prepare the pooled Cursor session agent for pi compaction summarization.
- * Releases any scoped live-run drain state still tied to the pooled agent, then
- * disposes the pool entry so summarization acquires a clean SDK agent.
- * Suppresses local-resume handle persist so the summarizer send cannot leak
- * a one-message handle into the next normal turn (#223).
+ * Release scoped conversation runs and reset the pool before compaction.
+ * Summary execution owns a separate temporary agent, never this pool.
  */
 export async function prepareCursorSessionForCompaction(
 	scopeKey: string = getCursorSessionScopeKey(),
 ): Promise<void> {
-	suppressCursorSessionAgentResumeHandlePersist();
 	while (true) {
 		const run = cursorLiveRuns.getActiveForScope(scopeKey);
 		if (!run || run.disposed) break;

package/src/cursor-session-scope.ts

@@ -1,12 +1,13 @@
 import { resolve } from "node:path";
 import { parseArgs } from "@earendil-works/pi-coding-agent";
-import type { ExtensionHandler, ProjectTrustHandler, SessionInfoChangedEvent, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionHandler, ProjectTrustHandler, SessionInfoChangedEvent, SessionStartEvent, SessionShutdownEvent } from "@earendil-works/pi-coding-agent";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 
 interface CursorSessionScopeExtensionApi {
 	on(event: "project_trust", handler: ProjectTrustHandler): void;
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
 	on(event: "session_info_changed", handler: ExtensionHandler<SessionInfoChangedEvent>): void;
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
 }
 
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
@@ -15,6 +16,16 @@ export const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
 
 type CursorSessionScopeChangeHandler = (previousScopeKey: string) => Promise<void> | void;
 
+export interface CursorTurnScope {
+	readonly cwd: string;
+	readonly scopeKey: string;
+	readonly sessionFile: string | undefined;
+	readonly sessionId: string | undefined;
+	readonly sessionName: string | undefined;
+	readonly projectTrusted: boolean;
+	readonly generation: number;
+}
+
 const state = {
 	sessionCwd: process.cwd(),
 	sessionFile: undefined as string | undefined,
@@ -23,44 +34,67 @@ const state = {
 	projectTrusted: false,
 	sessionGeneration: 0,
 };
-
-const scopeGenerations = new Map<string, number>([[ANONYMOUS_SESSION_SCOPE_KEY, state.sessionGeneration]]);
+type ScopeRecord = typeof state;
+const scopes = new Map<object, ScopeRecord>();
+const scopeChangeHandlers = new Map<object, CursorSessionScopeChangeHandler>();
+const scopeGenerations = new Map<string, number>([[ANONYMOUS_SESSION_SCOPE_KEY, 0]]);
 const projectTrustResolutionCwds = new Set<string>();
 let nextSessionGeneration = 1;
-let scopeChangeHandler: CursorSessionScopeChangeHandler | undefined;
 
-/**
- * Pi session file when known; used to scope reused Cursor SDK agents to one pi session.
- */
+function scopeKeyFor(record: ScopeRecord): string {
+	if (record.sessionFile) return record.sessionFile;
+	if (record.sessionId) return `${EPHEMERAL_SESSION_SCOPE_PREFIX}${record.sessionId}`;
+	return ANONYMOUS_SESSION_SCOPE_KEY;
+}
+
+export function cursorSessionScopeKeyForManager(manager: {
+	getSessionFile?(): string | undefined | null;
+	getSessionId?(): string | undefined;
+}): string {
+	return manager.getSessionFile?.() ?? (manager.getSessionId?.()
+		? `${EPHEMERAL_SESSION_SCOPE_PREFIX}${manager.getSessionId()}`
+		: ANONYMOUS_SESSION_SCOPE_KEY);
+}
+
+export function getCursorSessionScopeSnapshot(pi?: object): CursorTurnScope {
+	if (!pi && scopes.size > 1) throw new Error("Cursor provider ownership requires a session-bound provider closure when multiple extensions are loaded.");
+	const record = pi ? scopes.get(pi) : state;
+	if (!record) throw new Error("Cursor session binding is no longer active.");
+	const scopeKey = scopeKeyFor(record);
+	return Object.freeze({
+		cwd: record.sessionCwd,
+		scopeKey,
+		sessionFile: record.sessionFile,
+		sessionId: record.sessionId,
+		sessionName: record.sessionName,
+		projectTrusted: record.projectTrusted,
+		generation: getCursorSessionScopeGeneration(scopeKey),
+	});
+}
+
+export function hasLiveCursorSessions(): boolean {
+	return scopes.size > 0;
+}
+
 export function getCursorSessionFile(): string | undefined {
 	return state.sessionFile;
 }
 
-/**
- * Stable scope key for session-agent pooling. Falls back to a process-local anonymous key
- * before the first session_start (tests and early startup).
- */
+/** Stable pool key, with process-local anonymous fallback before session_start. */
 export function getCursorSessionScopeKey(): string {
-	if (state.sessionFile) return state.sessionFile;
-	if (state.sessionId) return `${EPHEMERAL_SESSION_SCOPE_PREFIX}${state.sessionId}`;
-	return ANONYMOUS_SESSION_SCOPE_KEY;
+	return scopeKeyFor(state);
 }
 
 export function getCursorSessionScopeGeneration(scopeKey: string = getCursorSessionScopeKey()): number {
 	return scopeGenerations.get(scopeKey) ?? 0;
 }
 
-/**
- * Pi session cwd when known; falls back to process.cwd() before session_start.
- * Updated on session_start only until pi threads cwd into streamSimple—mid-session cwd
- * changes without a new session_start event are not reflected here.
- */
 export function getCursorSessionCwd(): string {
 	return state.sessionCwd;
 }
 
-export function getCursorSessionProjectTrusted(): boolean {
-	return state.projectTrusted;
+export function getCursorSessionProjectTrusted(pi?: object): boolean {
+	return pi ? scopes.get(pi)?.projectTrusted === true : state.projectTrusted;
 }
 
 export function getCursorSessionName(): string | undefined {
@@ -84,9 +118,8 @@ function setCursorSessionScope(
 	state.sessionId = sessionId;
 	state.sessionName = normalizeCursorSessionName(sessionName);
 	state.projectTrusted = projectTrusted;
-	state.sessionGeneration = nextSessionGeneration;
-	nextSessionGeneration += 1;
-	scopeGenerations.set(getCursorSessionScopeKey(), state.sessionGeneration);
+	state.sessionGeneration = nextSessionGeneration++;
+	scopeGenerations.set(scopeKeyFor(state), state.sessionGeneration);
 }
 
 function recordProjectTrustResolution(cwd: string): void {
@@ -98,43 +131,58 @@ function isCliProjectTrustApproved(args = process.argv.slice(2)): boolean {
 }
 
 function resetCursorSessionScope(): void {
-	state.sessionCwd = process.cwd();
-	state.sessionFile = undefined;
-	state.sessionId = undefined;
-	state.sessionName = undefined;
-	state.projectTrusted = false;
-	state.sessionGeneration = 0;
+	Object.assign(state, {
+		sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
+		sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+	});
 	nextSessionGeneration = 1;
 	scopeGenerations.clear();
-	scopeGenerations.set(ANONYMOUS_SESSION_SCOPE_KEY, state.sessionGeneration);
+	scopeGenerations.set(ANONYMOUS_SESSION_SCOPE_KEY, 0);
 	projectTrustResolutionCwds.clear();
+	scopes.clear();
+	scopeChangeHandlers.clear();
 }
 
-export function onCursorSessionScopeKeyChange(handler: CursorSessionScopeChangeHandler): void {
-	scopeChangeHandler = handler;
+export function onCursorSessionScopeKeyChange(pi: object, handler: CursorSessionScopeChangeHandler): void {
+	scopeChangeHandlers.set(pi, handler);
 }
 
 export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi): void {
+	// A fresh binding has no previous pooled scope to steal from the last-bound mirror.
+	const record: ScopeRecord = {
+		sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
+		sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+	};
+	scopes.set(pi, record);
+	const trustedCwds = new Set<string>();
 	pi.on("project_trust", (event) => {
-		recordProjectTrustResolution(event.cwd);
+		trustedCwds.add(resolve(event.cwd));
 		return { trusted: "undecided" };
 	});
 	pi.on("session_start", async (_event, ctx) => {
-		const previousScopeKey = getCursorSessionScopeKey();
+		const previousScopeKey = scopeKeyFor(record);
+		const wasBound = record.sessionGeneration > 0;
 		setCursorSessionScope(
 			ctx.cwd,
 			ctx.sessionManager?.getSessionFile?.() ?? undefined,
 			ctx.sessionManager?.getSessionId?.() ?? undefined,
 			ctx.isProjectTrusted?.() === true
-				&& (projectTrustResolutionCwds.has(resolve(ctx.cwd)) || isCliProjectTrustApproved()),
+				&& (trustedCwds.has(resolve(ctx.cwd)) || projectTrustResolutionCwds.has(resolve(ctx.cwd)) || isCliProjectTrustApproved()),
 			ctx.sessionManager?.getSessionName?.() ?? undefined,
 		);
-		if (previousScopeKey !== getCursorSessionScopeKey()) {
-			await scopeChangeHandler?.(previousScopeKey);
+		Object.assign(record, state);
+		scopes.set(pi, record);
+		if (wasBound && previousScopeKey !== scopeKeyFor(record)) {
+			await scopeChangeHandlers.get(pi)?.(previousScopeKey);
 		}
 	});
 	pi.on("session_info_changed", (event) => {
-		state.sessionName = normalizeCursorSessionName(event.name);
+		record.sessionName = normalizeCursorSessionName(event.name);
+		Object.assign(state, record);
+	});
+	pi.on("session_shutdown", () => {
+		scopes.delete(pi);
+		scopeChangeHandlers.delete(pi);
 	});
 }
 

package/src/cursor-session-send-policy.ts

@@ -21,14 +21,14 @@ export interface CursorSessionSendPlan {
 	reason: CursorSessionSendReason;
 }
 
-export function planCursorSessionSend(sendState: SessionCursorAgentSendState, context: Context): CursorSessionSendPlan {
+export function planCursorSessionSend(sendState: SessionCursorAgentSendState, context: Context, nativeSourceRoles?: readonly string[]): CursorSessionSendPlan {
 	if (!sendState.bootstrapped) {
 		return { mode: "bootstrap", resetAgent: false, reason: "initial" };
 	}
 	if (sendState.incrementalSendCount >= MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP) {
 		return { mode: "bootstrap", resetAgent: true, reason: "incremental_threshold" };
 	}
-	if (shouldBootstrapCursorContext(sendState, context)) {
+	if (shouldBootstrapCursorContext(sendState, context, nativeSourceRoles)) {
 		return { mode: "bootstrap", resetAgent: true, reason: "context_divergence" };
 	}
 	return { mode: "incremental", resetAgent: false, reason: "incremental" };

package/src/cursor-session-settings.ts

@@ -0,0 +1,72 @@
+import type { AgentModeOption } from "@cursor/sdk";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CursorExplicitSdkConfig, CursorRuntime } from "./cursor-config.js";
+import { cursorSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+
+export type CursorCliModeState =
+	| { kind: "unset" }
+	| { kind: "valid"; mode: AgentModeOption }
+	| { kind: "invalid"; raw: string; message: string };
+
+function createCliSettings() {
+	return {
+		forceFast: false, forceNoFast: false,
+		mode: { kind: "unset" } as CursorCliModeState,
+		config: {} as CursorExplicitSdkConfig,
+		cloudEnvNames: undefined as string | undefined,
+		localForceConsumed: false,
+	};
+}
+
+function createSettings() {
+	return {
+		fast: new Map<string, boolean>(),
+		mode: undefined as AgentModeOption | undefined,
+		runtime: undefined as CursorRuntime | undefined,
+		cloudAcknowledged: false,
+		http1: undefined as boolean | undefined,
+		projectTrusted: false,
+		cli: createCliSettings(),
+	};
+}
+const settings = new Map<string, ReturnType<typeof createSettings>>();
+let cliOwners = new WeakMap<object, ReturnType<typeof createCliSettings>>();
+let legacySettings = createSettings();
+
+export function getCursorSessionSettings(scopeKey?: string) {
+	if (scopeKey === undefined) return legacySettings;
+	let value = settings.get(scopeKey);
+	if (!value) {
+		value = createSettings();
+		settings.set(scopeKey, value);
+	}
+	return value;
+}
+
+export function cursorSettingsScopeForContext(ctx: Partial<Pick<ExtensionContext, "sessionManager">>): string | undefined {
+	const manager = ctx.sessionManager;
+	return manager ? cursorSessionScopeKeyForManager(manager) : undefined;
+}
+
+export function registerCursorSessionSettings(pi: Pick<ExtensionAPI, "on">): void {
+	let scopeKey: string | undefined;
+	let cli = createCliSettings();
+	pi.on("session_start", (_event, ctx) => {
+		if (scopeKey) settings.delete(scopeKey);
+		scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager);
+		legacySettings = getCursorSessionSettings(scopeKey);
+		// Reload creates a new ExtensionAPI but retains the same public manager.
+		// Keep the run's one-shot CLI consumption without retaining dead managers.
+		cli = cliOwners.get(ctx.sessionManager) ?? cli;
+		cliOwners.set(ctx.sessionManager, cli);
+		legacySettings.cli = cli;
+		legacySettings.projectTrusted = getCursorSessionProjectTrusted(pi);
+	});
+	pi.on("session_shutdown", () => { if (scopeKey) settings.delete(scopeKey); });
+}
+
+export function resetCursorSessionSettingsForTests(): void {
+	settings.clear();
+	cliOwners = new WeakMap();
+	legacySettings = createSettings();
+}