pi-cursor-sdk 0.5.0 → 0.5.2

package/dist/cursor-sdk-runtime.js

@@ -1,16 +1,15 @@
-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";
+/**
+ * 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() {
-    // 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/dist/cursor-sdk-vendor-env.js

@@ -0,0 +1,20 @@
+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() {
+    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/dist/cursor-session-agent-cleanup.js

@@ -4,7 +4,7 @@ import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
 import { CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE, isCursorLocalAgentId, parseCursorSessionAgentResumeEntryData, readResumableCursorSessionAgentIds, resolveCursorSessionRepoRoot, } from "./cursor-session-agent-resume.js";
-import { cursorSessionStoreIdentitiesEqual, getCursorSessionStoreIdentities, openCursorSessionStore, } from "./cursor-session-store.js";
+import { withCursorSessionStoreIdentities, openCursorSessionStore, resolveCursorSessionStoreIdentity, } from "./cursor-session-store.js";
 export const CURSOR_SESSION_AGENT_CLEANUP_ENTRY_TYPE = "cursor-sdk-agent-cleanup";
 class InvalidCursorSessionStoreIdentityError extends Error {
 }
@@ -202,7 +202,7 @@ function appendDurableCleanupEntry(pi, ctx, data) {
         return false;
     return fsyncExistingRegularFile(sessionFile);
 }
-export async function runCursorSessionAgentCleanupCommand(pi, args, ctx) {
+export async function runCursorSessionAgentCleanupCommand(pi, args, ctx, storeRoot) {
     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");
@@ -236,7 +236,7 @@ export async function runCursorSessionAgentCleanupCommand(pi, args, ctx) {
         }
         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;
     }
@@ -244,31 +244,34 @@ export async function runCursorSessionAgentCleanupCommand(pi, args, ctx) {
     const failedAgentIds = [];
     const openedStores = new Map();
     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);
+                    }
+                    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 } : {}),
+                    });
                 }
-                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));

package/dist/cursor-session-agent.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 import { getRegisteredCursorPiToolBridge, } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
 import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
@@ -26,11 +27,14 @@ function assertScopeAcceptsAcquire(scopeKey) {
     }
     terminalDisposedScopeGenerations.delete(scopeKey);
 }
-function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error) {
+function samePoolIdentity(entry, poolKey, capturedStoreRoot) {
+    return entry.poolKey === poolKey && entry.storeRoot === capturedStoreRoot;
+}
+function rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, storeRoot, error) {
     if (!(error instanceof SessionCursorAgentCreationSupersededError))
         return;
     const replacement = sessionAgentsByScope.get(scopeKey);
-    if (replacement && replacement.poolKey !== poolKey) {
+    if (replacement && !samePoolIdentity(replacement, poolKey, storeRoot)) {
         throw error;
     }
 }
@@ -87,6 +91,20 @@ function buildBridgePoolKeySuffix(registeredBridge) {
         return "bridge:absent";
     return registeredBridge.getToolSurfaceSignature();
 }
+function buildCustomSubagentPoolKeySuffix(agents) {
+    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, params) {
     return [
         scopeKey,
@@ -101,6 +119,7 @@ function buildSessionAgentPoolKey(scopeKey, params) {
                 : "http1:off",
         buildApiKeyPoolKeyFingerprint(params.apiKey),
         buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
+        ...buildCustomSubagentPoolKeySuffix(params.agents),
     ].join("\0");
 }
 async function disposePoolEntry(entry, options) {
@@ -252,11 +271,11 @@ function leaseFromEntry(entry, scopeKey, params, created) {
         },
     };
 }
-function getCurrentReadyPoolEntry(scopeKey, poolKey) {
+function getCurrentReadyPoolEntry(scopeKey, poolKey, storeRoot) {
     const current = sessionAgentsByScope.get(scopeKey);
     if (current?.status !== "ready")
         return undefined;
-    if (current.poolKey !== poolKey)
+    if (!samePoolIdentity(current, poolKey, storeRoot))
         return undefined;
     return current;
 }
@@ -269,7 +288,7 @@ async function tryLeaseReadyEntry(entry, scopeKey, params, poolKey, created) {
         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);
@@ -303,11 +322,10 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             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 = () => ({
@@ -321,6 +339,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
                 store: sessionStore.store,
             }),
             ...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
+            ...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
         });
         let agent;
         let effectiveSendState = sendState;
@@ -334,9 +353,11 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             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;
                 }
             }
         }
@@ -348,6 +369,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
         return {
             status: "ready",
             poolKey: resolvedPoolKey,
+            storeRoot: params.storeRoot,
             instanceId,
             scopeKey,
             agent,
@@ -376,6 +398,7 @@ export async function acquireSessionCursorAgent(input) {
     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);
         if (invalidatedScopeKeys.has(scopeKey)) {
@@ -383,7 +406,7 @@ export async function acquireSessionCursorAgent(input) {
         }
         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;
         }
@@ -398,7 +421,7 @@ export async function acquireSessionCursorAgent(input) {
             continue;
         }
         if (state.status === "creating") {
-            if (state.poolKey !== poolKey) {
+            if (!samePoolIdentity(state, poolKey, params.storeRoot)) {
                 await disposePoolEntryForScope(scopeKey);
                 continue;
             }
@@ -408,7 +431,7 @@ export async function acquireSessionCursorAgent(input) {
             catch (error) {
                 if (error instanceof SessionCursorAgentCreationSupersededError) {
                     assertScopeAcceptsAcquire(scopeKey);
-                    rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+                    rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
                     continue;
                 }
                 throw error;
@@ -436,6 +459,7 @@ export async function acquireSessionCursorAgent(input) {
         placeholder = {
             status: "creating",
             poolKey,
+            storeRoot: params.storeRoot,
             instanceId,
             scopeKey,
             sendState,
@@ -456,7 +480,7 @@ export async function acquireSessionCursorAgent(input) {
             }
             if (error instanceof SessionCursorAgentCreationSupersededError) {
                 assertScopeAcceptsAcquire(scopeKey);
-                rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+                rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
                 continue;
             }
             throw error;
@@ -495,8 +519,6 @@ export const __testUtils = {
     resetSessionCursorAgent,
     refreshSessionCursorAgentConfig,
     disposeAllSessionCursorAgents,
-    buildApiKeyPoolKeyFingerprint,
-    buildSessionAgentPoolKey,
     setDeadTransportAgentDisposeTimeoutMs(ms) {
         const previous = deadTransportAgentDisposeTimeoutMs;
         deadTransportAgentDisposeTimeoutMs = ms;

package/dist/cursor-session-send-policy.js

@@ -1,14 +1,14 @@
 import { buildCursorIncrementalPrompt, buildCursorPrompt, shouldBootstrapCursorContext, } from "./context.js";
 // Long-lived SDK session agents can drift tool-call behavior; recreate the agent after this many successful incremental sends.
 export const MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP = 20;
-export function planCursorSessionSend(sendState, context) {
+export function planCursorSessionSend(sendState, context, nativeSourceRoles) {
     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/dist/cursor-session-store.js

@@ -1,9 +1,14 @@
 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 { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { guardCursorCustomStorePath, normalizeCursorCustomStoreRoot, prepareCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 let sdkOperationsForTests;
+const activeWorkspaceRoots = new Map();
+// 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) {
     return createHash("sha256")
         .update("pi-cursor-sdk-session-store\0")
@@ -11,9 +16,8 @@ export function hashCursorSessionStoreScope(scopeKey) {
         .digest("hex")
         .slice(0, 32);
 }
-export function buildCursorSessionStateRoot(defaultStateRoot, scopeKey, persistent) {
-    const baseRoot = persistent ? defaultStateRoot : join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
-    return join(baseRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
+export function buildCursorSessionStateRoot(defaultStateRoot, scopeKey) {
+    return join(defaultStateRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
 }
 async function getSdkOperations() {
     if (sdkOperationsForTests)
@@ -27,76 +31,262 @@ async function getSdkOperations() {
         openSqliteStore: (options) => SqliteLocalAgentStore.open(options),
     };
 }
-export async function getCursorSessionStoreIdentities(cwd, scopeKey, persistent) {
-    const defaultStateRoot = await (await getSdkOperations()).getDefaultStateRoot(cwd);
+function leaseWorkspaceRoot(key, ownership) {
+    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, storeRoot) {
+    return JSON.stringify([cwd, storeRoot ?? null]);
+}
+function acquireWorkspaceRoot(cwd, storeRoot) {
+    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, workspaceRoot, storeRoot) {
+    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(cwd, scopeKey, selectedRoot, use) {
+    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", defaultStore: { version: 1, stateRoot: workspaceRoot } }
+                : { domain: "custom", storeRoot }),
+        });
+    }
+    finally {
+        lease.release();
+    }
+}
 export function cursorSessionStoreIdentitiesEqual(left, right) {
     return left.version === right.version && left.stateRoot === right.stateRoot;
 }
-async function openOwnedCursorSessionStore(cwd, identity, removalRoot) {
+function rejectedStorePath(stateRoot, base) {
+    // 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.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+function assertSafeStorePath(stateRoot, base, label) {
+    const rejected = rejectedStorePath(stateRoot, base);
+    if (rejected)
+        throw new Error(`Cursor ${label} path contains a link or non-directory: ${rejected}`);
+}
+function workspaceHashes(cwd) {
+    const current = createHash("sha256").update(cwd).digest("hex");
+    try {
+        return { current, legacy: createHash("md5").update(cwd).digest("hex") };
+    }
+    catch (error) {
+        if (error.code === "ERR_OSSL_EVP_UNSUPPORTED" ||
+            (error instanceof Error && error.message === "Digest method not supported"))
+            return { current, legacy: undefined };
+        throw error;
+    }
+}
+function assertSafeWorkspaceLayout(cwd) {
+    // ponytail: SDK 1.0.36 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, defaultStateRoot) {
+    // 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) {
+    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, 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, 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, identity, options) {
     const openedIdentity = Object.freeze({ ...identity });
+    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;
     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();
             }
         },
     };
 }
-export function openCursorSessionStore(cwd, identity) {
-    return openOwnedCursorSessionStore(cwd, identity);
+export function openCursorSessionStore(cwd, identity, workspaceRoot, storeRoot) {
+    return openOwnedCursorSessionStore(cwd, identity, { workspaceRoot, storeRoot });
 }
 export async function openCursorSessionStoreForScope(options) {
-    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;
-    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, 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;
+        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 = {
     setSdkOperations(operations) {