pi-cursor-sdk 0.5.0 → 0.5.3

package/src/cursor-session-scope.ts

@@ -19,6 +19,8 @@ type CursorSessionScopeChangeHandler = (previousScopeKey: string) => Promise<voi
 export interface CursorTurnScope {
 	readonly cwd: string;
 	readonly scopeKey: string;
+	/** Durable identity only; never use it to own live runtime resources. */
+	readonly persistentScopeKey?: string;
 	readonly sessionFile: string | undefined;
 	readonly sessionId: string | undefined;
 	readonly sessionName: string | undefined;
@@ -33,6 +35,7 @@ const state = {
 	sessionName: undefined as string | undefined,
 	projectTrusted: false,
 	sessionGeneration: 0,
+	runtimeOwner: undefined as number | undefined,
 };
 type ScopeRecord = typeof state;
 const scopes = new Map<object, ScopeRecord>();
@@ -40,20 +43,34 @@ 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 nextRuntimeOwner = 1;
+let runtimeOwners = new WeakMap<object, number>();
+
+function persistentScopeKeyFor(record: Pick<ScopeRecord, "sessionFile" | "sessionId">): string {
+	return record.sessionFile ?? (record.sessionId ? `${EPHEMERAL_SESSION_SCOPE_PREFIX}${record.sessionId}` : ANONYMOUS_SESSION_SCOPE_KEY);
+}
 
 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;
+	const persistent = persistentScopeKeyFor(record);
+	return record.runtimeOwner === undefined ? persistent : `${persistent}\0runtime:${record.runtimeOwner}`;
 }
 
 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);
+	return persistentScopeKeyFor({
+		sessionFile: manager.getSessionFile?.() ?? undefined, sessionId: manager.getSessionId?.(),
+	});
+}
+
+export function cursorRuntimeSessionScopeKeyForManager(manager: {
+	getSessionFile?(): string | undefined | null;
+	getSessionId?(): string | undefined;
+}): string {
+	const persistent = cursorSessionScopeKeyForManager(manager);
+	const owner = runtimeOwners.get(manager);
+	return owner === undefined ? persistent : `${persistent}\0runtime:${owner}`;
 }
 
 export function getCursorSessionScopeSnapshot(pi?: object): CursorTurnScope {
@@ -64,6 +81,7 @@ export function getCursorSessionScopeSnapshot(pi?: object): CursorTurnScope {
 	return Object.freeze({
 		cwd: record.sessionCwd,
 		scopeKey,
+		persistentScopeKey: persistentScopeKeyFor(record),
 		sessionFile: record.sessionFile,
 		sessionId: record.sessionId,
 		sessionName: record.sessionName,
@@ -76,11 +94,7 @@ export function hasLiveCursorSessions(): boolean {
 	return scopes.size > 0;
 }
 
-export function getCursorSessionFile(): string | undefined {
-	return state.sessionFile;
-}
-
-/** Stable pool key, with process-local anonymous fallback before session_start. */
+/** Runtime ownership key; persisted identities are captured separately. */
 export function getCursorSessionScopeKey(): string {
 	return scopeKeyFor(state);
 }
@@ -112,6 +126,7 @@ function setCursorSessionScope(
 	sessionId?: string,
 	projectTrusted = false,
 	sessionName?: string,
+	runtimeOwner?: number,
 ): void {
 	state.sessionCwd = cwd;
 	state.sessionFile = sessionFile;
@@ -119,6 +134,7 @@ function setCursorSessionScope(
 	state.sessionName = normalizeCursorSessionName(sessionName);
 	state.projectTrusted = projectTrusted;
 	state.sessionGeneration = nextSessionGeneration++;
+	state.runtimeOwner = runtimeOwner;
 	scopeGenerations.set(scopeKeyFor(state), state.sessionGeneration);
 }
 
@@ -134,6 +150,7 @@ function resetCursorSessionScope(): void {
 	Object.assign(state, {
 		sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
 		sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+		runtimeOwner: undefined,
 	});
 	nextSessionGeneration = 1;
 	scopeGenerations.clear();
@@ -141,6 +158,8 @@ function resetCursorSessionScope(): void {
 	projectTrustResolutionCwds.clear();
 	scopes.clear();
 	scopeChangeHandlers.clear();
+	runtimeOwners = new WeakMap();
+	nextRuntimeOwner = 1;
 }
 
 export function onCursorSessionScopeKeyChange(pi: object, handler: CursorSessionScopeChangeHandler): void {
@@ -152,6 +171,7 @@ export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi):
 	const record: ScopeRecord = {
 		sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
 		sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+		runtimeOwner: undefined,
 	};
 	scopes.set(pi, record);
 	const trustedCwds = new Set<string>();
@@ -162,6 +182,7 @@ export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi):
 	pi.on("session_start", async (_event, ctx) => {
 		const previousScopeKey = scopeKeyFor(record);
 		const wasBound = record.sessionGeneration > 0;
+		if (!runtimeOwners.has(ctx.sessionManager)) runtimeOwners.set(ctx.sessionManager, nextRuntimeOwner++);
 		setCursorSessionScope(
 			ctx.cwd,
 			ctx.sessionManager?.getSessionFile?.() ?? undefined,
@@ -169,6 +190,7 @@ export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi):
 			ctx.isProjectTrusted?.() === true
 				&& (trustedCwds.has(resolve(ctx.cwd)) || projectTrustResolutionCwds.has(resolve(ctx.cwd)) || isCliProjectTrustApproved()),
 			ctx.sessionManager?.getSessionName?.() ?? undefined,
+			runtimeOwners.get(ctx.sessionManager),
 		);
 		Object.assign(record, state);
 		scopes.set(pi, record);

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

@@ -1,7 +1,7 @@
 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";
+import { cursorRuntimeSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
 
 export type CursorCliModeState =
 	| { kind: "unset" }
@@ -45,7 +45,7 @@ export function getCursorSessionSettings(scopeKey?: string) {
 
 export function cursorSettingsScopeForContext(ctx: Partial<Pick<ExtensionContext, "sessionManager">>): string | undefined {
 	const manager = ctx.sessionManager;
-	return manager ? cursorSessionScopeKeyForManager(manager) : undefined;
+	return manager ? cursorRuntimeSessionScopeKeyForManager(manager) : undefined;
 }
 
 export function registerCursorSessionSettings(pi: Pick<ExtensionAPI, "on">): void {
@@ -53,7 +53,7 @@ export function registerCursorSessionSettings(pi: Pick<ExtensionAPI, "on">): voi
 	let cli = createCliSettings();
 	pi.on("session_start", (_event, ctx) => {
 		if (scopeKey) settings.delete(scopeKey);
-		scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager);
+		scopeKey = cursorRuntimeSessionScopeKeyForManager(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.

package/src/cursor-session-store.ts

@@ -1,9 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
 import { rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { dirname, join, toNamespacedPath } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep, toNamespacedPath } from "node:path";
 import type { LocalAgentStore } from "@cursor/sdk";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { guardCursorCustomStorePath, normalizeCursorCustomStoreRoot, prepareCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 
 export interface CursorSessionStoreIdentity {
 	readonly version: 1;
@@ -16,15 +18,32 @@ export interface OpenCursorSessionStore {
 	dispose(): Promise<void>;
 }
 
-export interface CursorSessionStoreSelection {
+type CursorPersistentStoreIdentities = {
+	workspaceRoot: string;
+	sessionStore: CursorSessionStoreIdentity;
+} & ({
+	domain: "default";
+	defaultStore: CursorSessionStoreIdentity;
+	storeRoot?: never;
+} | {
+	domain: "custom";
+	storeRoot: string;
+	defaultStore?: never;
+});
+
+export type CursorSessionStoreSelection = {
 	sessionStore: OpenCursorSessionStore;
-	identities: {
-		defaultStore: CursorSessionStoreIdentity;
-		sessionStore: CursorSessionStoreIdentity;
-	};
+} & ({
+	persistent: true;
+	identities: CursorPersistentStoreIdentities;
 	resumeAttemptAllowed: boolean;
 	resumeFallback: boolean;
-}
+} | {
+	persistent: false;
+	identities: { sessionStore: CursorSessionStoreIdentity };
+	resumeAttemptAllowed: false;
+	resumeFallback: false;
+});
 
 interface CursorSessionStoreSdkOperations {
 	getDefaultStateRoot(cwd: string): string | Promise<string>;
@@ -32,6 +51,9 @@ interface CursorSessionStoreSdkOperations {
 }
 
 let sdkOperationsForTests: CursorSessionStoreSdkOperations | undefined;
+const activeWorkspaceRoots = new Map<string, { root: Promise<string>; users: number }>();
+// ponytail: leases protect only extension-owned stores in this process. Other SDK
+// users/processes must stop before upgrade; a cross-process lock belongs in the SDK.
 
 export function hashCursorSessionStoreScope(scopeKey: string): string {
 	return createHash("sha256")
@@ -41,9 +63,8 @@ export function hashCursorSessionStoreScope(scopeKey: string): string {
 		.slice(0, 32);
 }
 
-export function buildCursorSessionStateRoot(defaultStateRoot: string, scopeKey: string, persistent: boolean): string {
-	const baseRoot = persistent ? defaultStateRoot : join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
-	return join(baseRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
+export function buildCursorSessionStateRoot(defaultStateRoot: string, scopeKey: string): string {
+	return join(defaultStateRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
 }
 
 async function getSdkOperations(): Promise<CursorSessionStoreSdkOperations> {
@@ -58,21 +79,81 @@ async function getSdkOperations(): Promise<CursorSessionStoreSdkOperations> {
 	};
 }
 
-export async function getCursorSessionStoreIdentities(
-	cwd: string,
-	scopeKey: string,
-	persistent: boolean,
-): Promise<{ defaultStore: CursorSessionStoreIdentity; sessionStore: CursorSessionStoreIdentity }> {
-	const defaultStateRoot = await (await getSdkOperations()).getDefaultStateRoot(cwd);
+function leaseWorkspaceRoot(key: string, ownership: { root: Promise<string>; users: number }) {
+	ownership.users++;
+	let released = false;
 	return {
-		defaultStore: { version: 1, stateRoot: defaultStateRoot },
-		sessionStore: {
-			version: 1,
-			stateRoot: buildCursorSessionStateRoot(defaultStateRoot, scopeKey, persistent),
+		root: ownership.root,
+		release: () => {
+			if (released) return;
+			released = true;
+			if (--ownership.users === 0) activeWorkspaceRoots.delete(key);
 		},
 	};
 }
 
+function workspaceLeaseKey(cwd: string, storeRoot: string | undefined): string {
+	return JSON.stringify([cwd, storeRoot ?? null]);
+}
+
+function acquireWorkspaceRoot(cwd: string, storeRoot: string | undefined) {
+	const key = workspaceLeaseKey(cwd, storeRoot);
+	let ownership = activeWorkspaceRoots.get(key);
+	if (!ownership) {
+		ownership = {
+			// Publish ownership synchronously, before SDK loading or the public getter.
+			root: Promise.resolve().then(async () => {
+				if (storeRoot !== undefined) {
+					const root = prepareCursorCustomStoreRoot(storeRoot);
+					return join(root, createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 32));
+				}
+				const operations = await getSdkOperations();
+				assertSafeWorkspaceLayout(cwd);
+				const root = await operations.getDefaultStateRoot(cwd);
+				assertSafeStorePath(root, dirname(root), "local store");
+				return root;
+			}),
+			users: 0,
+		};
+		activeWorkspaceRoots.set(key, ownership);
+	}
+	return leaseWorkspaceRoot(key, ownership);
+}
+
+function retainWorkspaceRoot(cwd: string, workspaceRoot: string, storeRoot: string | undefined) {
+	const key = workspaceLeaseKey(cwd, storeRoot);
+	const ownership = activeWorkspaceRoots.get(key);
+	if (!ownership) throw new Error("Cursor local workspace ownership is not active");
+	const lease = leaseWorkspaceRoot(key, ownership);
+	return {
+		...lease,
+		root: lease.root.then((root) => {
+			if (root !== workspaceRoot) throw new Error("Cursor local workspace ownership root mismatch");
+			return root;
+		}),
+	};
+}
+
+export async function withCursorSessionStoreIdentities<T>(
+	cwd: string,
+	scopeKey: string,
+	selectedRoot: string | undefined,
+	use: (identities: CursorPersistentStoreIdentities) => Promise<T>,
+): Promise<T> {
+	const storeRoot = selectedRoot === undefined ? undefined : normalizeCursorCustomStoreRoot(selectedRoot);
+	const lease = acquireWorkspaceRoot(cwd, storeRoot);
+	try {
+		const workspaceRoot = await lease.root;
+		return await use({
+			workspaceRoot,
+			sessionStore: { version: 1, stateRoot: buildCursorSessionStateRoot(workspaceRoot, scopeKey) },
+			...(storeRoot === undefined
+				? { domain: "default" as const, defaultStore: { version: 1 as const, stateRoot: workspaceRoot } }
+				: { domain: "custom" as const, storeRoot }),
+		});
+	} finally { lease.release(); }
+}
+
 export function cursorSessionStoreIdentitiesEqual(
 	left: CursorSessionStoreIdentity,
 	right: CursorSessionStoreIdentity,
@@ -80,30 +161,151 @@ export function cursorSessionStoreIdentitiesEqual(
 	return left.version === right.version && left.stateRoot === right.stateRoot;
 }
 
+function rejectedStorePath(stateRoot: string, base: string): string | undefined {
+	// User-managed ancestors above the SDK prefix (or our temporary removal root)
+	// may be links/junctions. Owned components, including the base, may not.
+	let path = resolve(base);
+	const suffix = relative(path, resolve(stateRoot));
+	if (suffix === ".." || suffix.startsWith(`..${sep}`) || isAbsolute(suffix)) return stateRoot;
+	for (const component of ["", ...suffix.split(sep).filter(Boolean)]) {
+		path = join(path, component);
+		try {
+			if (!lstatSync(path).isDirectory()) return path;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+}
+
+function assertSafeStorePath(stateRoot: string, base: string, label: string): void {
+	const rejected = rejectedStorePath(stateRoot, base);
+	if (rejected) throw new Error(`Cursor ${label} path contains a link or non-directory: ${rejected}`);
+}
+
+function workspaceHashes(cwd: string): { current: string; legacy: string | undefined } {
+	const current = createHash("sha256").update(cwd).digest("hex");
+	try {
+		return { current, legacy: createHash("md5").update(cwd).digest("hex") };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ERR_OSSL_EVP_UNSUPPORTED" ||
+			(error instanceof Error && error.message === "Digest method not supported")) return { current, legacy: undefined };
+		throw error;
+	}
+}
+
+function assertSafeWorkspaceLayout(cwd: string): void {
+	// ponytail: SDK 1.0.37 has no public read-only root resolver; use one when exposed.
+	// This pure layout is contract-verified against its factory and public getter;
+	// guard it before that getter can rename MD5 history through an owned link.
+	const slug = cwd.replace(/[^a-zA-Z0-9]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+	const prefix = join(homedir(), ".cursor", "projects", slug, "sdk-agent-store");
+	const { current, legacy } = workspaceHashes(cwd);
+	for (const hash of [current, legacy]) {
+		if (hash) assertSafeStorePath(join(prefix, hash), prefix, "local store");
+	}
+}
+
+function legacyWorkspaceRoot(cwd: string, defaultStateRoot: string): string | undefined {
+	// The public getter owns migration and may return MD5 after a failed rename.
+	const { current, legacy } = workspaceHashes(cwd);
+	if (!legacy) return undefined;
+	const prefix = dirname(defaultStateRoot);
+	if (defaultStateRoot !== join(prefix, current) && defaultStateRoot !== join(prefix, legacy)) return undefined;
+	return join(prefix, legacy);
+}
+
+export async function resolveCursorSessionStoreIdentity(options: {
+	cwd: string;
+	scopeKey: string;
+	identities: CursorPersistentStoreIdentities;
+	recordedIdentity?: CursorSessionStoreIdentity;
+	agentId: string;
+}): Promise<CursorSessionStoreIdentity | undefined> {
+	const { cwd, scopeKey, identities, agentId } = options;
+	if (identities.domain === "custom") {
+		if (!options.recordedIdentity || !cursorSessionStoreIdentitiesEqual(options.recordedIdentity, identities.sessionStore)) return undefined;
+		// Cleanup admits each candidate before cached-store reuse, which skips the open-time guard.
+		assertSafeStorePath(identities.sessionStore.stateRoot, dirname(identities.workspaceRoot), "local store");
+		guardCursorCustomStorePath(dirname(identities.workspaceRoot), identities.sessionStore.stateRoot).verify();
+		return identities.sessionStore;
+	}
+	const legacyRoot = legacyWorkspaceRoot(cwd, identities.defaultStore.stateRoot);
+	const legacyDefault = legacyRoot ? { version: 1 as const, stateRoot: legacyRoot } : undefined;
+	// Version-1 handles predate recorded identities and used the default workspace
+	// store. If both roots survive, that old store still owns their data.
+	const recorded = options.recordedIdentity ?? legacyDefault ?? identities.defaultStore;
+	const base = dirname(identities.defaultStore.stateRoot);
+	const current = [identities.defaultStore, identities.sessionStore];
+	const exact = current.find((identity) => cursorSessionStoreIdentitiesEqual(identity, recorded));
+	if (exact) {
+		assertSafeStorePath(exact.stateRoot, base, "local store");
+		return exact;
+	}
+	if (!legacyRoot) return undefined;
+	const legacySession = { version: 1 as const, stateRoot: buildCursorSessionStateRoot(legacyRoot, scopeKey) };
+	const legacy = [legacyDefault, legacySession].find((identity) =>
+		identity && cursorSessionStoreIdentitiesEqual(identity, recorded));
+	if (!legacy) return undefined;
+	assertSafeStorePath(legacy.stateRoot, base, "local store");
+	if (existsSync(legacyRoot)) return legacy; // No merge or silent owner switch.
+	const migrated = legacy === legacyDefault ? identities.defaultStore : identities.sessionStore;
+	assertSafeStorePath(migrated.stateRoot, base, "local store");
+	if (!existsSync(migrated.stateRoot)) return undefined;
+	// A missing legacy path alone is not migration proof. The exact cwd/scope
+	// destination must independently contain this recorded agent with this cwd.
+	const opened = await openCursorSessionStore(cwd, migrated, identities.defaultStore.stateRoot);
+	try {
+		const agent = await opened.store.agents.get({ agentId });
+		return agent?.cwd === cwd ? migrated : undefined;
+	} finally {
+		await opened.dispose();
+	}
+}
+
 async function openOwnedCursorSessionStore(
 	cwd: string,
 	identity: CursorSessionStoreIdentity,
-	removalRoot?: string,
+	options: { workspaceRoot: string; storeRoot?: string } | { removalRoot: string },
 ): Promise<OpenCursorSessionStore> {
 	const openedIdentity = Object.freeze({ ...identity });
-	let store: LocalAgentStore & { dispose(): Promise<void> };
+	const lease = "workspaceRoot" in options ? retainWorkspaceRoot(cwd, options.workspaceRoot, options.storeRoot) : undefined;
+	const removalRoot = "removalRoot" in options ? options.removalRoot : undefined;
+	const removeTemporaryStore = async () => {
+		if (removalRoot) {
+			assertSafeStorePath(openedIdentity.stateRoot, removalRoot, "temporary store removal");
+			await rm(removalRoot, { recursive: true, force: true });
+		}
+	};
+	let store: (LocalAgentStore & { dispose(): Promise<void> }) | undefined;
 	try {
-		store = await (await getSdkOperations()).openSqliteStore({
+		await lease?.root;
+		const base = "workspaceRoot" in options ? dirname(options.workspaceRoot) : options.removalRoot;
+		assertSafeStorePath(openedIdentity.stateRoot, base, "local store");
+		const guard = "workspaceRoot" in options && options.storeRoot !== undefined
+			? guardCursorCustomStorePath(base, openedIdentity.stateRoot) : undefined;
+		const operations = await getSdkOperations();
+		guard?.verify();
+		store = await operations.openSqliteStore({
 			workspaceRef: cwd,
 			stateRoot: toNamespacedPath(openedIdentity.stateRoot),
 		});
+		guard?.verify();
 	} catch (error) {
-		if (removalRoot) await rm(removalRoot, { recursive: true, force: true }).catch(() => undefined);
+		await store?.dispose().catch(() => undefined);
+		lease?.release();
+		await removeTemporaryStore().catch(() => undefined);
 		throw error;
 	}
+	const openedStore = store;
 	return {
 		identity: openedIdentity,
-		store,
+		store: openedStore,
 		dispose: async () => {
 			try {
-				await store.dispose();
+				await openedStore.dispose();
 			} finally {
-				if (removalRoot) await rm(removalRoot, { recursive: true, force: true });
+				lease?.release();
+				await removeTemporaryStore();
 			}
 		},
 	};
@@ -112,40 +314,44 @@ async function openOwnedCursorSessionStore(
 export function openCursorSessionStore(
 	cwd: string,
 	identity: CursorSessionStoreIdentity,
+	workspaceRoot: string,
+	storeRoot?: string,
 ): Promise<OpenCursorSessionStore> {
-	return openOwnedCursorSessionStore(cwd, identity);
+	return openOwnedCursorSessionStore(cwd, identity, { workspaceRoot, storeRoot });
 }
 
 export async function openCursorSessionStoreForScope(options: {
 	cwd: string;
 	scopeKey: string;
 	persistent: boolean;
-	hasResumeHandle: boolean;
-	resumeIdentity?: CursorSessionStoreIdentity;
+	storeRoot?: string;
+	resume?: { identity?: CursorSessionStoreIdentity; agentId: string };
 }): Promise<CursorSessionStoreSelection> {
-	const identities = await getCursorSessionStoreIdentities(options.cwd, options.scopeKey, options.persistent);
-	const requestedResumeIdentity = options.hasResumeHandle
-		? options.resumeIdentity ?? (options.persistent ? identities.defaultStore : undefined)
-		: undefined;
-	const resumableIdentities = options.persistent
-		? [identities.defaultStore, identities.sessionStore]
-		: [identities.sessionStore];
-	const resumeIdentity = requestedResumeIdentity && resumableIdentities
-		.find((identity) => cursorSessionStoreIdentitiesEqual(identity, requestedResumeIdentity));
-	let resumeAttemptAllowed = options.hasResumeHandle && resumeIdentity !== undefined;
-	let resumeFallback = options.persistent && options.hasResumeHandle && !resumeIdentity;
-	const selectedIdentity = resumeIdentity ?? identities.sessionStore;
-	const removalRoot = options.persistent ? undefined : dirname(dirname(identities.sessionStore.stateRoot));
-	let sessionStore: OpenCursorSessionStore;
-	try {
-		sessionStore = await openOwnedCursorSessionStore(options.cwd, selectedIdentity, removalRoot);
-	} catch (error) {
-		if (!resumeIdentity || cursorSessionStoreIdentitiesEqual(resumeIdentity, identities.sessionStore)) throw error;
-		resumeAttemptAllowed = false;
-		resumeFallback = true;
-		sessionStore = await openOwnedCursorSessionStore(options.cwd, identities.sessionStore);
+	if (!options.persistent) {
+		const removalRoot = join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
+		const identity = { version: 1 as const, stateRoot: buildCursorSessionStateRoot(removalRoot, options.scopeKey) };
+		const sessionStore = await openOwnedCursorSessionStore(options.cwd, identity, { removalRoot });
+		return { persistent: false, sessionStore, identities: { sessionStore: identity }, resumeAttemptAllowed: false, resumeFallback: false };
 	}
-	return { sessionStore, identities, resumeAttemptAllowed, resumeFallback };
+	return withCursorSessionStoreIdentities(options.cwd, options.scopeKey, options.storeRoot, async (identities) => {
+		const resumeIdentity = options.resume ? await resolveCursorSessionStoreIdentity({
+			cwd: options.cwd, scopeKey: options.scopeKey, identities,
+			recordedIdentity: options.resume.identity, agentId: options.resume.agentId,
+		}).catch(() => undefined) : undefined; // Unreadable resume storage falls back; fresh-store failures still propagate.
+		let resumeAttemptAllowed = resumeIdentity !== undefined;
+		let resumeFallback = options.resume !== undefined && !resumeIdentity;
+		const selectedIdentity = resumeIdentity ?? identities.sessionStore;
+		let sessionStore: OpenCursorSessionStore;
+		try {
+			sessionStore = await openCursorSessionStore(options.cwd, selectedIdentity, identities.workspaceRoot, identities.storeRoot);
+		} catch (error) {
+			if (!resumeIdentity || cursorSessionStoreIdentitiesEqual(resumeIdentity, identities.sessionStore)) throw error;
+			resumeAttemptAllowed = false;
+			resumeFallback = true;
+			sessionStore = await openCursorSessionStore(options.cwd, identities.sessionStore, identities.workspaceRoot, identities.storeRoot);
+		}
+		return { persistent: true, sessionStore, identities, resumeAttemptAllowed, resumeFallback };
+	});
 }
 
 export const __testUtils = {