pi-cursor-sdk 0.5.0 → 0.5.3

package/dist/cursor-session-agent-cleanup.js

@@ -3,8 +3,9 @@ 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, 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 +203,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 +237,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 +245,42 @@ 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);
+                    }
+                    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));

package/dist/cursor-session-agent-lifecycle.js

@@ -1,9 +1,9 @@
 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, resetSessionCursorAgent, } from "./cursor-session-agent.js";
 export function registerCursorSessionAgentLifecycle(pi) {
     let scopeKey;
-    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/dist/cursor-session-agent-lineage.js

@@ -52,7 +52,7 @@ function readRecordedAgentIds(entries, sessionId) {
 export function recordCursorSessionAgentLineage(agentId, turnScopeKey) {
     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;
@@ -83,24 +83,27 @@ export function registerCursorSessionAgentLineage(pi) {
     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();
     });
@@ -111,6 +114,7 @@ function resetStateForTests() {
     state.sessionId = undefined;
     state.sessionFile = undefined;
     state.scopeKey = undefined;
+    state.runtimeScopeKey = undefined;
     state.cwd = undefined;
     state.recordedAgentIds = new Set();
 }

package/dist/cursor-session-agent-resume.js

@@ -266,7 +266,7 @@ function restoreFromBranch(branch, allEntries, state) {
 }
 export function getMatchingCursorSessionAgentResumeHandle(poolKey, scopeKey) {
     const state = getResumeState(scopeKey);
-    if (scopeKey !== undefined && state.scopeKey !== scopeKey)
+    if (scopeKey !== undefined && (state.runtimeScopeKey ?? state.scopeKey) !== scopeKey)
         return undefined;
     const handle = state.activeHandle;
     if (!handle || !isCursorLocalAgentId(handle.agentId))
@@ -292,7 +292,7 @@ export function getMatchingCursorSessionAgentResumeHandle(poolKey, scopeKey) {
 }
 export function persistCursorSessionAgentResumeHandle(input, scopeKey) {
     const state = getResumeState(scopeKey);
-    if (scopeKey !== undefined && state.scopeKey !== scopeKey)
+    if (scopeKey !== undefined && (state.runtimeScopeKey ?? state.scopeKey) !== scopeKey)
         return;
     if (!isCursorLocalAgentId(input.agentId))
         return;
@@ -343,8 +343,9 @@ function flushPendingCursorSessionAgentResumeHandle(branch, state) {
     }
 }
 export function registerCursorSessionAgentResume(pi) {
+    const scope = getCursorSessionScopeSnapshot(pi);
     const sessionState = {
-        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(),
     };
@@ -355,10 +356,13 @@ export function registerCursorSessionAgentResume(pi) {
         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;
@@ -399,8 +403,9 @@ export function registerCursorSessionAgentResume(pi) {
         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;
     });
@@ -412,6 +417,7 @@ function resetStateForTests() {
     const state = lastBoundState;
     state.appendEntry = undefined;
     state.scopeKey = getCursorSessionScopeKey();
+    state.runtimeScopeKey = undefined;
     state.sessionFile = undefined;
     state.sessionId = undefined;
     state.cwd = process.cwd();

package/dist/cursor-session-agent.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
+import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import { getRegisteredCursorPiToolBridge, } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
-import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { getMatchingCursorSessionAgentResumeHandle, persistCursorSessionAgentResumeHandle, } from "./cursor-session-agent-resume.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { cursorSessionStoreIdentitiesEqual, openCursorSessionStore, openCursorSessionStoreForScope, } from "./cursor-session-store.js";
@@ -26,11 +28,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,9 +92,23 @@ 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,
+        params.scope?.persistentScopeKey ?? scopeKey,
         params.cwd,
         buildModelPoolKey(params.modelSelection),
         buildSettingSourcesPoolKey(params.settingSources),
@@ -101,6 +120,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) {
@@ -113,8 +133,9 @@ async function disposePoolEntry(entry, options) {
     catch {
         // disposal failure should not block session replacement
     }
+    let disposal;
     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
@@ -128,6 +149,8 @@ async function disposePoolEntry(entry, 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, options) {
     invalidateScopeCreations(scopeKey);
@@ -252,11 +275,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 +292,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);
@@ -277,6 +300,7 @@ async function tryLeaseReadyEntry(entry, scopeKey, params, poolKey, created) {
 async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, sendState, params) {
     let bridgeRun;
     let sessionStore;
+    let releaseAgentClaim;
     try {
         const registeredBridge = params.bridge;
         if (registeredBridge) {
@@ -301,13 +325,12 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
         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 = () => ({
@@ -321,22 +344,30 @@ 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;
         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;
                 }
             }
         }
@@ -345,9 +376,13 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             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,
@@ -356,6 +391,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             sendState: effectiveSendState,
             resumeEnabled: params.localResume === true,
             resumed,
+            releaseAgentClaim,
             ...(resumeNotice ? { resumeNotice } : {}),
         };
     }
@@ -363,6 +399,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
         bridgeRun?.cancel("Cursor session agent create failed");
         await bridgeRun?.dispose().catch(() => undefined);
         await sessionStore?.dispose().catch(() => undefined);
+        releaseAgentClaim?.();
         throw error;
     }
 }
@@ -373,9 +410,10 @@ export function invalidateSessionAgent(scopeKey = getCursorSessionScopeKey(), op
         deadTransportScopeKeys.add(scopeKey);
 }
 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;
+    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);
         if (invalidatedScopeKeys.has(scopeKey)) {
@@ -383,7 +421,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 +436,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 +446,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 +474,7 @@ export async function acquireSessionCursorAgent(input) {
         placeholder = {
             status: "creating",
             poolKey,
+            storeRoot: params.storeRoot,
             instanceId,
             scopeKey,
             sendState,
@@ -456,7 +495,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 +534,6 @@ export const __testUtils = {
     resetSessionCursorAgent,
     refreshSessionCursorAgentConfig,
     disposeAllSessionCursorAgents,
-    buildApiKeyPoolKeyFingerprint,
-    buildSessionAgentPoolKey,
     setDeadTransportAgentDisposeTimeoutMs(ms) {
         const previous = deadTransportAgentDisposeTimeoutMs;
         deadTransportAgentDisposeTimeoutMs = ms;

package/dist/cursor-session-scope.js

@@ -11,23 +11,31 @@ const state = {
     sessionName: undefined,
     projectTrusted: false,
     sessionGeneration: 0,
+    runtimeOwner: undefined,
 };
 const scopes = new Map();
 const scopeChangeHandlers = new Map();
 const scopeGenerations = new Map([[ANONYMOUS_SESSION_SCOPE_KEY, 0]]);
 const projectTrustResolutionCwds = new Set();
 let nextSessionGeneration = 1;
+let nextRuntimeOwner = 1;
+let runtimeOwners = new WeakMap();
+function persistentScopeKeyFor(record) {
+    return record.sessionFile ?? (record.sessionId ? `${EPHEMERAL_SESSION_SCOPE_PREFIX}${record.sessionId}` : ANONYMOUS_SESSION_SCOPE_KEY);
+}
 function scopeKeyFor(record) {
-    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) {
-    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) {
+    const persistent = cursorSessionScopeKeyForManager(manager);
+    const owner = runtimeOwners.get(manager);
+    return owner === undefined ? persistent : `${persistent}\0runtime:${owner}`;
 }
 export function getCursorSessionScopeSnapshot(pi) {
     if (!pi && scopes.size > 1)
@@ -39,6 +47,7 @@ export function getCursorSessionScopeSnapshot(pi) {
     return Object.freeze({
         cwd: record.sessionCwd,
         scopeKey,
+        persistentScopeKey: persistentScopeKeyFor(record),
         sessionFile: record.sessionFile,
         sessionId: record.sessionId,
         sessionName: record.sessionName,
@@ -49,10 +58,7 @@ export function getCursorSessionScopeSnapshot(pi) {
 export function hasLiveCursorSessions() {
     return scopes.size > 0;
 }
-export function getCursorSessionFile() {
-    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() {
     return scopeKeyFor(state);
 }
@@ -73,13 +79,14 @@ function normalizeCursorSessionName(name) {
         return undefined;
     return truncateCursorDisplayLine(name, MAX_CURSOR_SESSION_NAME_LENGTH) || undefined;
 }
-function setCursorSessionScope(cwd, sessionFile, sessionId, projectTrusted = false, sessionName) {
+function setCursorSessionScope(cwd, sessionFile, sessionId, projectTrusted = false, sessionName, runtimeOwner) {
     state.sessionCwd = cwd;
     state.sessionFile = sessionFile;
     state.sessionId = sessionId;
     state.sessionName = normalizeCursorSessionName(sessionName);
     state.projectTrusted = projectTrusted;
     state.sessionGeneration = nextSessionGeneration++;
+    state.runtimeOwner = runtimeOwner;
     scopeGenerations.set(scopeKeyFor(state), state.sessionGeneration);
 }
 function recordProjectTrustResolution(cwd) {
@@ -92,6 +99,7 @@ function resetCursorSessionScope() {
     Object.assign(state, {
         sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
         sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+        runtimeOwner: undefined,
     });
     nextSessionGeneration = 1;
     scopeGenerations.clear();
@@ -99,6 +107,8 @@ function resetCursorSessionScope() {
     projectTrustResolutionCwds.clear();
     scopes.clear();
     scopeChangeHandlers.clear();
+    runtimeOwners = new WeakMap();
+    nextRuntimeOwner = 1;
 }
 export function onCursorSessionScopeKeyChange(pi, handler) {
     scopeChangeHandlers.set(pi, handler);
@@ -108,6 +118,7 @@ export function registerCursorSessionScope(pi) {
     const record = {
         sessionCwd: process.cwd(), sessionFile: undefined, sessionId: undefined,
         sessionName: undefined, projectTrusted: false, sessionGeneration: 0,
+        runtimeOwner: undefined,
     };
     scopes.set(pi, record);
     const trustedCwds = new Set();
@@ -118,8 +129,10 @@ export function registerCursorSessionScope(pi) {
     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, ctx.sessionManager?.getSessionId?.() ?? undefined, ctx.isProjectTrusted?.() === true
-            && (trustedCwds.has(resolve(ctx.cwd)) || projectTrustResolutionCwds.has(resolve(ctx.cwd)) || isCliProjectTrustApproved()), ctx.sessionManager?.getSessionName?.() ?? undefined);
+            && (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);
         if (wasBound && previousScopeKey !== scopeKeyFor(record)) {

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-settings.js

@@ -1,4 +1,4 @@
-import { cursorSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { cursorRuntimeSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
 function createCliSettings() {
     return {
         forceFast: false, forceNoFast: false,
@@ -34,7 +34,7 @@ export function getCursorSessionSettings(scopeKey) {
 }
 export function cursorSettingsScopeForContext(ctx) {
     const manager = ctx.sessionManager;
-    return manager ? cursorSessionScopeKeyForManager(manager) : undefined;
+    return manager ? cursorRuntimeSessionScopeKeyForManager(manager) : undefined;
 }
 export function registerCursorSessionSettings(pi) {
     let scopeKey;
@@ -42,7 +42,7 @@ export function registerCursorSessionSettings(pi) {
     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.