pi-cursor-sdk 0.5.0 → 0.5.3

package/src/cursor-sdk-runtime.ts

@@ -1,19 +1,18 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { resolveCursorSdkPlatformPackageDirectory } from "./cursor-ripgrep-path.js";
+// Vendor env must initialize before the static @cursor/sdk import below so
+// tree-sitter natives resolve when Pi lives outside this package's node_modules.
+import "./cursor-sdk-vendor-env.js";
+import * as CursorSdk from "@cursor/sdk";
 
-export type CursorSdkModule = typeof import("@cursor/sdk");
+export type CursorSdkModule = typeof CursorSdk;
 
+/**
+ * Load the Cursor SDK module.
+ *
+ * Uses a static import so Pi's compiled-Bun extension graph includes @cursor/sdk
+ * (a runtime dynamic bare import is omitted from that graph; see #228).
+ * `loadCursorSdk` remains async for call-site compatibility and so vendor-env
+ * side effects (imported above) always run before callers receive the module.
+ */
 export async function loadCursorSdk(): Promise<CursorSdkModule> {
-	// The SDK searches launcher ancestors, which miss Pi's separately installed extension packages.
-	if (process.env.CURSOR_TREE_SITTER_VENDOR_DIR === undefined) {
-		const packageDirectory = resolveCursorSdkPlatformPackageDirectory();
-		if (packageDirectory) {
-			const vendor = join(packageDirectory, "vendor");
-			if (existsSync(join(vendor, "tree-sitter", "index.js")) && existsSync(join(vendor, "tree-sitter-bash", "index.js"))) {
-				process.env.CURSOR_TREE_SITTER_VENDOR_DIR = vendor;
-			}
-		}
-	}
-	return import("@cursor/sdk");
+	return CursorSdk;
 }

package/src/cursor-sdk-vendor-env.ts

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCursorSdkPlatformPackageDirectory } from "./cursor-ripgrep-path.js";
+
+/**
+ * Ensure CURSOR_TREE_SITTER_VENDOR_DIR is set before @cursor/sdk first loads.
+ * Must run as a side effect of importing this module (before a static SDK import).
+ */
+export function ensureCursorTreeSitterVendorDir(): void {
+	if (process.env.CURSOR_TREE_SITTER_VENDOR_DIR !== undefined) return;
+	const packageDirectory = resolveCursorSdkPlatformPackageDirectory();
+	if (!packageDirectory) return;
+	const vendor = join(packageDirectory, "vendor");
+	if (
+		existsSync(join(vendor, "tree-sitter", "index.js")) &&
+		existsSync(join(vendor, "tree-sitter-bash", "index.js"))
+	) {
+		process.env.CURSOR_TREE_SITTER_VENDOR_DIR = vendor;
+	}
+}
+
+ensureCursorTreeSitterVendorDir();

package/src/cursor-session-agent-cleanup.ts

@@ -5,6 +5,7 @@ import { fsyncExistingRegularFile } from "./cursor-durable-fs.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import {
 	CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE,
 	isCursorLocalAgentId,
@@ -16,9 +17,9 @@ import {
 	type CursorSessionAgentResumeScope,
 } from "./cursor-session-agent-resume.js";
 import {
-	cursorSessionStoreIdentitiesEqual,
-	getCursorSessionStoreIdentities,
+	withCursorSessionStoreIdentities,
 	openCursorSessionStore,
+	resolveCursorSessionStoreIdentity,
 } from "./cursor-session-store.js";
 
 export const CURSOR_SESSION_AGENT_CLEANUP_ENTRY_TYPE = "cursor-sdk-agent-cleanup";
@@ -264,7 +265,7 @@ function appendDurableCleanupEntry(
 	return fsyncExistingRegularFile(sessionFile);
 }
 
-export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanupApi, args: string, ctx: LocalResumeCleanupCommandContext): Promise<void> {
+export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanupApi, args: string, ctx: LocalResumeCleanupCommandContext, storeRoot?: string): Promise<void> {
 	const usage = "Usage: /cursor-local-resume-cleanup [--dry-run|--yes]";
 	const tokens = args.trim().split(/\s+/).filter(Boolean);
 	const dryRun = tokens.length === 0 || (tokens.length === 1 && tokens[0] === "--dry-run");
@@ -299,7 +300,7 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 		return;
 	}
 
-	if (!appendDurableCleanupEntry(pi, ctx, { action: "delete", phase: "intent", ...baseEntry })) {
+	if (!scope.sessionFile || !appendDurableCleanupEntry(pi, ctx, { action: "delete", phase: "intent", ...baseEntry })) {
 		ctx.ui.notify("Cleanup intent could not be durably recorded. No agents were deleted.", "error");
 		return;
 	}
@@ -308,31 +309,36 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 	const failedAgentIds: CursorSessionAgentCleanupFailure[] = [];
 	const openedStores = new Map<string, Awaited<ReturnType<typeof openCursorSessionStore>>>();
 	try {
-		const operations = await getSdkOperations();
-		const identities = await getCursorSessionStoreIdentities(ctx.cwd, scope.scopeKey, scope.sessionFile !== undefined);
-		for (const candidate of plan.candidates) {
-			const { agentId } = candidate;
-			try {
-				const identity = candidate.storeIdentity ?? identities.defaultStore;
-				if (
-					!cursorSessionStoreIdentitiesEqual(identity, identities.defaultStore) &&
-					!cursorSessionStoreIdentitiesEqual(identity, identities.sessionStore)
-				) throw new InvalidCursorSessionStoreIdentityError("Recorded Cursor local store identity is not valid for this pi session");
-				let openedStore = openedStores.get(identity.stateRoot);
-				if (!openedStore) {
-					openedStore = await openCursorSessionStore(ctx.cwd, identity);
-					openedStores.set(identity.stateRoot, openedStore);
+		await withCursorSessionStoreIdentities(ctx.cwd, scope.scopeKey, storeRoot, async (identities) => {
+			const operations = await getSdkOperations();
+			for (const candidate of plan.candidates) {
+				const { agentId } = candidate;
+				try {
+					const identity = await resolveCursorSessionStoreIdentity({
+						cwd: ctx.cwd, scopeKey: scope.scopeKey,
+						identities, recordedIdentity: candidate.storeIdentity, agentId,
+					});
+					if (!identity) throw new InvalidCursorSessionStoreIdentityError("Recorded Cursor local store identity is not valid for this pi session");
+					let openedStore = openedStores.get(identity.stateRoot);
+					if (!openedStore) {
+						openedStore = await openCursorSessionStore(ctx.cwd, identity, identities.workspaceRoot, identities.storeRoot);
+						openedStores.set(identity.stateRoot, openedStore);
+					}
+					const release = claimCursorLocalAgent(identity, agentId);
+					if (!release) throw new Error("Cursor local agent is still owned by an active runtime");
+					try {
+						await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
+					} finally { release(); }
+					deletedAgentIds.push(agentId);
+				} catch (error) {
+					failedAgentIds.push({
+						agentId,
+						error: scrubSensitiveText(getString(asRecord(error), "message") ?? String(error)),
+						...(error instanceof InvalidCursorSessionStoreIdentityError ? { retryable: false } : {}),
+					});
 				}
-				await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
-				deletedAgentIds.push(agentId);
-			} catch (error) {
-				failedAgentIds.push({
-					agentId,
-					error: scrubSensitiveText(getString(asRecord(error), "message") ?? String(error)),
-					...(error instanceof InvalidCursorSessionStoreIdentityError ? { retryable: false } : {}),
-				});
 			}
-		}
+		});
 	} catch (error) {
 		const message = scrubSensitiveText(getString(asRecord(error), "message") ?? String(error));
 		failedAgentIds.push(...plan.candidateAgentIds.map((agentId) => ({ agentId, error: message })));

package/src/cursor-session-agent-lifecycle.ts

@@ -7,7 +7,7 @@ import type {
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { clearCursorSdkHttp1 } from "./cursor-http1.js";
-import { cursorSessionScopeKeyForManager, hasLiveCursorSessions, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import { cursorRuntimeSessionScopeKeyForManager, hasLiveCursorSessions, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
 import {
 	disposeSessionCursorAgent,
 	invalidateSessionAgent,
@@ -25,7 +25,7 @@ export interface CursorSessionAgentLifecycleExtensionApi {
 
 export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
 	let scopeKey: string | undefined;
-	pi.on("session_start", (_event, ctx) => { scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager); });
+	pi.on("session_start", (_event, ctx) => { scopeKey = cursorRuntimeSessionScopeKeyForManager(ctx.sessionManager); });
 	onCursorSessionScopeKeyChange(pi, async (previousScopeKey) => {
 		await disposeSessionCursorAgent(previousScopeKey);
 	});

package/src/cursor-session-agent-lineage.ts

@@ -29,6 +29,7 @@ interface CursorSessionAgentLineageState {
 	sessionId?: string;
 	sessionFile?: string;
 	scopeKey?: string;
+	runtimeScopeKey?: string;
 	cwd?: string;
 	recordedAgentIds: Set<string>;
 }
@@ -82,7 +83,7 @@ function readRecordedAgentIds(entries: readonly SessionEntry[], sessionId: strin
 export function recordCursorSessionAgentLineage(agentId: string, turnScopeKey?: string): void {
 	const sessionState = turnScopeKey === undefined
 		? state
-		: statesByScope.get(turnScopeKey) ?? (state.scopeKey === turnScopeKey ? state : undefined);
+		: statesByScope.get(turnScopeKey) ?? ((state.runtimeScopeKey ?? state.scopeKey) === turnScopeKey ? state : undefined);
 	if (!sessionState) return;
 	const { appendEntry, sessionId, sessionFile, scopeKey, cwd } = sessionState;
 	if (!appendEntry || !sessionId || !scopeKey || !cwd) return;
@@ -115,22 +116,25 @@ export function registerCursorSessionAgentLineage(pi: CursorSessionAgentLineageE
 	pi.on("session_start", (_event, ctx) => {
 		state = sessionState;
 		const record = sessionState;
-		if (record.scopeKey && statesByScope.get(record.scopeKey) === record) statesByScope.delete(record.scopeKey);
+		if (record.runtimeScopeKey && statesByScope.get(record.runtimeScopeKey) === record) statesByScope.delete(record.runtimeScopeKey);
 		record.appendEntry = pi.appendEntry;
 		record.sessionId = ctx.sessionManager.getSessionId();
 		record.sessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
-		record.scopeKey = getCursorSessionScopeSnapshot(pi).scopeKey;
-		statesByScope.set(record.scopeKey, record);
+		const scope = getCursorSessionScopeSnapshot(pi);
+		record.runtimeScopeKey = scope.scopeKey;
+		record.scopeKey = scope.persistentScopeKey ?? scope.scopeKey;
+		statesByScope.set(scope.scopeKey, record);
 		record.cwd = ctx.cwd;
 		record.recordedAgentIds = readRecordedAgentIds(ctx.sessionManager.getEntries(), record.sessionId);
 	});
 	pi.on("session_shutdown", () => {
 		const state = sessionState;
-		if (state.scopeKey && statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
+		if (state.runtimeScopeKey && statesByScope.get(state.runtimeScopeKey) === state) statesByScope.delete(state.runtimeScopeKey);
 		state.appendEntry = undefined;
 		state.sessionId = undefined;
 		state.sessionFile = undefined;
 		state.scopeKey = undefined;
+		state.runtimeScopeKey = undefined;
 		state.cwd = undefined;
 		state.recordedAgentIds = new Set();
 	});
@@ -142,6 +146,7 @@ function resetStateForTests(): void {
 	state.sessionId = undefined;
 	state.sessionFile = undefined;
 	state.scopeKey = undefined;
+	state.runtimeScopeKey = undefined;
 	state.cwd = undefined;
 	state.recordedAgentIds = new Set();
 }

package/src/cursor-session-agent-resume.ts

@@ -60,6 +60,7 @@ interface PendingCursorSessionAgentResumeHandle {
 
 interface CursorSessionResumeState {
 	appendEntry?: ExtensionAPI["appendEntry"];
+	runtimeScopeKey?: string;
 	scopeKey: string;
 	sessionFile?: string;
 	sessionId?: string;
@@ -355,7 +356,7 @@ function restoreFromBranch(branch: readonly SessionEntry[], allEntries: readonly
 
 export function getMatchingCursorSessionAgentResumeHandle(poolKey: string, scopeKey?: string): CursorSessionAgentResumeEntryData | undefined {
 	const state = getResumeState(scopeKey);
-	if (scopeKey !== undefined && state.scopeKey !== scopeKey) return undefined;
+	if (scopeKey !== undefined && (state.runtimeScopeKey ?? state.scopeKey) !== scopeKey) return undefined;
 	const handle = state.activeHandle;
 	if (!handle || !isCursorLocalAgentId(handle.agentId)) return undefined;
 	if (handle.poolKey !== poolKey) return undefined;
@@ -373,7 +374,7 @@ export function getMatchingCursorSessionAgentResumeHandle(poolKey: string, scope
 
 export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle, scopeKey?: string): void {
 	const state = getResumeState(scopeKey);
-	if (scopeKey !== undefined && state.scopeKey !== scopeKey) return;
+	if (scopeKey !== undefined && (state.runtimeScopeKey ?? state.scopeKey) !== scopeKey) return;
 	if (!isCursorLocalAgentId(input.agentId)) return;
 	state.pendingHandle = {
 		runtime: input.runtime,
@@ -427,8 +428,9 @@ interface CursorSessionAgentResumeExtensionApi {
 }
 
 export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExtensionApi): void {
+	const scope = getCursorSessionScopeSnapshot(pi);
 	const sessionState: CursorSessionResumeState = {
-		appendEntry: pi.appendEntry, scopeKey: getCursorSessionScopeSnapshot(pi).scopeKey,
+		appendEntry: pi.appendEntry, scopeKey: scope.persistentScopeKey ?? scope.scopeKey,
 		cwd: process.cwd(), branchPathHash: EMPTY_BRANCH_HASH,
 		compactionGeneration: 0, unownedUserEntryIds: new Set(),
 	};
@@ -439,9 +441,12 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		restoreFromBranch(branch, entries.length > 0 ? entries : branch, state);
 	};
 	pi.on("session_start", (_event, ctx) => {
-		if (statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
-		state.scopeKey = getCursorSessionScopeSnapshot(pi).scopeKey;
-		statesByScope.set(state.scopeKey, state);
+		const key = state.runtimeScopeKey ?? state.scopeKey;
+		if (statesByScope.get(key) === state) statesByScope.delete(key);
+		const scope = getCursorSessionScopeSnapshot(pi);
+		state.runtimeScopeKey = scope.scopeKey;
+		state.scopeKey = scope.persistentScopeKey ?? scope.scopeKey;
+		statesByScope.set(scope.scopeKey, state);
 		lastBoundState = state;
 		state.sessionFile = ctx.sessionManager.getSessionFile?.() ?? undefined;
 		state.sessionId = ctx.sessionManager.getSessionId?.() ?? undefined;
@@ -482,7 +487,8 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		state.branchPathHash = hashBranchStep(state.branchPathHash, event.compactionEntry);
 	});
 	pi.on("session_shutdown", () => {
-		if (statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
+		const key = state.runtimeScopeKey ?? state.scopeKey;
+		if (statesByScope.get(key) === state) statesByScope.delete(key);
 		state.appendEntry = undefined;
 		state.pendingHandle = undefined;
 	});
@@ -496,6 +502,7 @@ function resetStateForTests(): void {
 	const state = lastBoundState;
 	state.appendEntry = undefined;
 	state.scopeKey = getCursorSessionScopeKey();
+	state.runtimeScopeKey = undefined;
 	state.sessionFile = undefined;
 	state.sessionId = undefined;
 	state.cwd = process.cwd();

package/src/cursor-session-agent.ts

@@ -1,6 +1,8 @@
 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 { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import {
 	getRegisteredCursorPiToolBridge,
 	type CursorPiToolBridge,
@@ -8,7 +10,7 @@ import {
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
-import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
 import {
 	getMatchingCursorSessionAgentResumeHandle,
 	persistCursorSessionAgentResumeHandle,
@@ -47,6 +49,7 @@ export interface SessionCursorAgentLease {
 
 interface SessionCursorAgentPoolEntryBase {
 	poolKey: string;
+	storeRoot: string | undefined;
 	instanceId: number;
 	scopeKey: string;
 	sendState: SessionCursorAgentSendState;
@@ -66,6 +69,7 @@ interface SessionCursorAgentReadyEntry extends SessionCursorAgentPoolEntryBase {
 	resumeEnabled: boolean;
 	resumed: boolean;
 	resumeNotice?: string;
+	releaseAgentClaim: () => void;
 }
 
 interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
@@ -76,6 +80,7 @@ interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
 	resumeEnabled: boolean;
 	resumed: boolean;
 	resumeNotice?: string;
+	releaseAgentClaim: () => void;
 	completionSettled: Promise<void>;
 	pendingCompletion: Promise<void>;
 	releaseBusyWait: () => void;
@@ -113,10 +118,14 @@ 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;
 	}
 }
@@ -130,10 +139,12 @@ interface SessionCursorAgentCreateParams {
 	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"];
@@ -213,9 +224,24 @@ function buildBridgePoolKeySuffix(registeredBridge: CursorPiToolBridge | undefin
 	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,
+		params.scope?.persistentScopeKey ?? scopeKey,
 		params.cwd,
 		buildModelPoolKey(params.modelSelection),
 		buildSettingSourcesPoolKey(params.settingSources),
@@ -227,6 +253,7 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 				: "http1:off",
 		buildApiKeyPoolKeyFingerprint(params.apiKey),
 		buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
+		...buildCustomSubagentPoolKeySuffix(params.agents),
 	].join("\0");
 }
 
@@ -238,8 +265,9 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: {
 	} catch {
 		// disposal failure should not block session replacement
 	}
+	let disposal: Promise<unknown> | undefined;
 	try {
-		const disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]()).catch(() => undefined);
+		disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]());
 		// A dead local transport may never settle SDK disposal; bound the wait so the
 		// next acquire recreates instead of hanging on the dead agent.
 		await (options?.deadTransport
@@ -252,6 +280,8 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: {
 		// disposal failure should not block session replacement
 	}
 	await entry.sessionStore.dispose().catch(() => undefined);
+	// Timeout/rejection is not proof of closure; only successful SDK disposal releases ownership.
+	void disposal?.then(entry.releaseAgentClaim, () => {});
 }
 
 async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?: boolean }): Promise<void> {
@@ -410,10 +440,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;
 }
 
@@ -432,7 +462,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);
 }
@@ -446,6 +476,7 @@ async function createSessionAgentEntry(
 ): Promise<SessionCursorAgentReadyEntry> {
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	let sessionStore: OpenCursorSessionStore | undefined;
+	let releaseAgentClaim: (() => void) | undefined;
 	try {
 		const registeredBridge = params.bridge;
 		if (registeredBridge) {
@@ -471,13 +502,12 @@ async function createSessionAgentEntry(
 		const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey, scopeKey) : undefined;
 		const storeSelection = await openCursorSessionStoreForScope({
 			cwd: params.cwd,
-			scopeKey,
+			scopeKey: params.scope?.persistentScopeKey ?? 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 = () => ({
@@ -491,30 +521,41 @@ 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;
 		let resumed = false;
 		if (resumeHandle && resumeAttemptAllowed && resumeAgent) {
+			releaseAgentClaim = claimCursorLocalAgent(sessionStore.identity, resumeHandle.agentId);
+		}
+		if (resumeHandle && resumeAttemptAllowed && resumeAgent && releaseAgentClaim) {
 			try {
 				agent = await resumeAgent(resumeHandle.agentId, buildAgentOptions());
 				effectiveSendState = { ...resumeHandle.sendState };
 				resumed = true;
 			} catch {
+				releaseAgentClaim();
+				releaseAgentClaim = undefined;
 				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;
 				}
 			}
 		}
 		agent ??= await createAgent(buildAgentOptions());
 		if (!agent) throw new Error("Cursor SDK agent creation returned no agent");
 		if (!sessionStore) throw new Error("Cursor SDK session store was not opened");
+		releaseAgentClaim ??= claimCursorLocalAgent(sessionStore.identity, agent.agentId);
+		if (!releaseAgentClaim) throw new Error("Cursor SDK agent is already owned by another runtime");
 
 		return {
 			status: "ready",
 			poolKey: resolvedPoolKey,
+			storeRoot: params.storeRoot,
 			instanceId,
 			scopeKey,
 			agent,
@@ -523,12 +564,14 @@ async function createSessionAgentEntry(
 			sendState: effectiveSendState,
 			resumeEnabled: params.localResume === true,
 			resumed,
+			releaseAgentClaim,
 			...(resumeNotice ? { resumeNotice } : {}),
 		};
 	} catch (error) {
 		bridgeRun?.cancel("Cursor session agent create failed");
 		await bridgeRun?.dispose().catch(() => undefined);
 		await sessionStore?.dispose().catch(() => undefined);
+		releaseAgentClaim?.();
 		throw error;
 	}
 }
@@ -549,9 +592,10 @@ export function invalidateSessionAgent(
 }
 
 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;
+	const params = { ...input, scope: input.scope ?? getCursorSessionScopeSnapshot(), bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
+	const scopeKey = params.scope.scopeKey;
+	const persistentStore = params.scope.sessionFile !== undefined;
+	params.storeRoot = persistentStore && params.storeRoot !== undefined ? normalizeCursorCustomStoreRoot(params.storeRoot) : undefined;
 
 	while (true) {
 		assertScopeAcceptsAcquire(scopeKey);
@@ -562,7 +606,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 		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;
 		}
@@ -579,7 +623,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 		}
 
 		if (state.status === "creating") {
-			if (state.poolKey !== poolKey) {
+			if (!samePoolIdentity(state, poolKey, params.storeRoot)) {
 				await disposePoolEntryForScope(scopeKey);
 				continue;
 			}
@@ -588,7 +632,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 			} catch (error) {
 				if (error instanceof SessionCursorAgentCreationSupersededError) {
 					assertScopeAcceptsAcquire(scopeKey);
-					rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+					rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
 					continue;
 				}
 				throw error;
@@ -618,6 +662,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 		placeholder = {
 			status: "creating",
 			poolKey,
+			storeRoot: params.storeRoot,
 			instanceId,
 			scopeKey,
 			sendState,
@@ -637,7 +682,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 			}
 			if (error instanceof SessionCursorAgentCreationSupersededError) {
 				assertScopeAcceptsAcquire(scopeKey);
-				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+				rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
 				continue;
 			}
 			throw error;
@@ -680,8 +725,6 @@ export const __testUtils = {
 	resetSessionCursorAgent,
 	refreshSessionCursorAgentConfig,
 	disposeAllSessionCursorAgents,
-	buildApiKeyPoolKeyFingerprint,
-	buildSessionAgentPoolKey,
 	setDeadTransportAgentDisposeTimeoutMs(ms: number): number {
 		const previous = deadTransportAgentDisposeTimeoutMs;
 		deadTransportAgentDisposeTimeoutMs = ms;