pi-cursor-sdk 0.5.2 → 0.5.4

package/dist/cursor-provider-turn-runner.js

@@ -1,5 +1,6 @@
+import { assertCursorNativeToolsRuntime, resolveCursorNativeToolsEnabled } from "./cursor-native-tools.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
-import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns, drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
@@ -45,6 +46,12 @@ export class CursorProviderTurnRunner {
             this.throwIfAborted();
             const { scope } = this.params;
             const cwd = scope.cwd;
+            // Resolved once here, before any drain await, so the drain decision and the
+            // prepare dispatch below always act on the same config snapshot.
+            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
+            this.runtimeTarget = resolvedConfig.runtime.value;
+            const nativeToolsEnabled = resolveCursorNativeToolsEnabled();
+            assertCursorNativeToolsRuntime(this.runtimeTarget, nativeToolsEnabled);
             this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
                 cwd,
                 modelId: model.id,
@@ -53,12 +60,8 @@ export class CursorProviderTurnRunner {
             });
             sdkEventDebugRef.current = this.sdkEventDebug;
             this.sdkEventDebug?.recordContextSnapshot(context);
-            // Resolved once here, before any drain await, so the drain decision and the
-            // prepare dispatch below always act on the same config snapshot.
-            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
-            this.runtimeTarget = resolvedConfig.runtime.value;
             if (resolvedConfig.runtime.value === "local" && this.params.request.purpose === "normal") {
-                if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor)) ===
+                if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor, nativeToolsEnabled)) ===
                     "stream_ended") {
                     return;
                 }
@@ -72,6 +75,7 @@ export class CursorProviderTurnRunner {
                 sdkEventDebug: this.sdkEventDebug,
                 throwIfAborted: () => this.throwIfAborted(),
                 resolvedConfig,
+                nativeToolsEnabled,
             });
             const usage = await this.params.usageRecorder.start({
                 agent: prepared.agent,
@@ -145,6 +149,13 @@ export class CursorProviderTurnRunner {
             });
         }
         catch (error) {
+            // This body owns the session turn lease; a queued request aborted before
+            // entry must not release another request's run in handleOuterCatch().
+            if (!prepared && (error instanceof CursorLiveRunAbortError || options?.signal?.aborted)) {
+                const pending = cursorLiveRuns.getActiveForScope(this.params.scope.scopeKey);
+                if (pending && !pending.disposed)
+                    await cursorLiveRuns.release(pending);
+            }
             await runFinalizer.applyTerminalEvent({ kind: "error", prepared: started ?? prepared, error });
         }
         finally {

package/dist/cursor-provider-turn-summary.js

@@ -33,7 +33,7 @@ export async function prepareCursorSummaryProviderTurn(prepareParams, selection)
         configureCursorSdkHttp1(sdk, resolvedConfig.local.useHttp1ForAgent);
         restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
         sessionStore = (await openCursorSessionStoreForScope({
-            cwd, scopeKey: params.scope.scopeKey, persistent: false,
+            cwd, scopeKey: params.scope.persistentScopeKey ?? params.scope.scopeKey, persistent: false,
         })).sessionStore;
         throwIfAborted();
         agent = await suppressCursorSdkOutput(() => sdk.Agent.create({

package/dist/cursor-provider.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
-import { cursorLiveRuns, DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS, getPendingCursorLiveRun, hasTrailingUserMessagesAfterToolResults, releaseAllPendingCursorLiveRunsForTests, resetCursorNativeReplayIdleDisposeMs, setCursorNativeReplayIdleDisposeMs, } from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns, hasTrailingUserMessagesAfterToolResults, releaseAllPendingCursorLiveRunsForTests, resetCursorNativeReplayIdleDisposeMs, setCursorNativeReplayIdleDisposeMs, } from "./cursor-provider-live-run-drain.js";
 import { disposeAllSessionCursorAgents } from "./cursor-session-agent.js";
 import { attachCursorSdkEventDebugPiStreamTap } from "./cursor-sdk-event-debug.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
@@ -66,10 +66,7 @@ export function streamCursor(model, context, options, ownership) {
     return stream;
 }
 export const __testUtils = {
-    DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
     pendingCursorNativeRunCount: cursorLiveRuns.count,
-    getPendingCursorLiveRun,
-    getActiveCursorLiveRunForScope: cursorLiveRuns.getActiveForScope,
     hasTrailingUserMessagesAfterToolResults,
     setCursorNativeReplayIdleDisposeMs,
     resetCursorNativeReplayIdleDisposeMs,

package/dist/cursor-runtime-state.js

@@ -4,8 +4,8 @@ import { asRecord } from "./cursor-record-utils.js";
 import { getResolvedSessionCursorHttp1Enabled } from "./cursor-http1.js";
 import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 import { cursorSettingsScopeForContext, getCursorSessionSettings } from "./cursor-session-settings.js";
-export const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
-export const CURSOR_CLOUD_ACK_DISCLOSURE = [
+const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
+const CURSOR_CLOUD_ACK_DISCLOSURE = [
     "Cursor Cloud executes this work remotely.",
     "Fresh context is used by default; prior Pi context is included only with explicit bootstrap opt-in.",
     "Pi-local tools and the Pi bridge are unavailable, and Pi environment variables are not forwarded.",
@@ -76,7 +76,7 @@ export function resolveCursorStatusRuntime(ctx) {
         return { kind: "invalid", message: error instanceof Error ? error.message : String(error) };
     }
 }
-export function formatResolvedCursorRuntime(runtime) {
+function formatResolvedCursorRuntime(runtime) {
     const cap = runtime.cappedBy;
     return cap
         ? `${runtime.value} (source: ${runtime.source} safety cap over ${cap.cappedSource} ${cap.cappedValue})`

package/dist/cursor-sdk-event-debug.js

@@ -60,10 +60,10 @@ export function resolveCursorSdkEventDebugEnabled(env = process.env) {
     return parseEnvBoolean(env[CURSOR_SDK_EVENT_DEBUG_ENV], false);
 }
 export const DISCARDED_INCOMPLETE_TOOL_CALL_REASON = "no-completion-at-run-end";
-export function hashCursorSdkCallId(callId) {
+function hashCursorSdkCallId(callId) {
     return createHash("sha256").update(callId).digest("hex").slice(0, 8);
 }
-export function serializeDiscardedIncompleteStartedToolCall(record) {
+function serializeDiscardedIncompleteStartedToolCall(record) {
     return {
         event: "discarded-incomplete-started-tool-call",
         toolName: record.toolName,

package/dist/cursor-sdk-output-filter.js

@@ -1 +1 @@
-export { CURSOR_SDK_STARTUP_NOISE_PATTERNS, withCursorSdkOutputNoticeHandler, installCursorSdkOutputFilter, isCursorSdkOutputSuppressed, isCursorSdkStartupNoise, suppressCursorSdkOutput, } from "../shared/cursor-sdk-output-filter.mjs";
+export { __testUtils, installCursorSdkProcessOutputFilter, withCursorSdkOutputNoticeHandler, installCursorSdkOutputFilter, isCursorSdkOutputSuppressed, isCursorSdkStartupNoise, suppressCursorSdkOutput, } from "../shared/cursor-sdk-output-filter.mjs";

package/dist/cursor-sdk-process-error-guard.js

@@ -1,4 +1,4 @@
-import { classifyCursorConnectError, isCursorSdkAbortConnectError, isCursorSdkConnectionStalledError } from "./cursor-provider-errors.js";
+import { classifyCursorConnectError, isCursorSdkConnectionStalledError } from "./cursor-provider-errors.js";
 // Cursor SDK controlled-exec tasks can reject after their originating provider turn
 // has ended. The exact closed-writable failure is therefore session-scoped; existing
 // ConnectRPC suppression remains scoped to active provider turns.
@@ -128,7 +128,6 @@ export const __testUtils = {
         lifecycleSessionGuards.clear();
     },
 };
-export { isCursorSdkAbortConnectError };
 export function installCursorSdkProcessErrorGuard() {
     const token = { suppressAbortErrors: false };
     activeProviderTurns.add(token);

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

@@ -3,6 +3,7 @@ import { fsyncExistingRegularFile } from "./cursor-durable-fs.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import { CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE, isCursorLocalAgentId, parseCursorSessionAgentResumeEntryData, readResumableCursorSessionAgentIds, resolveCursorSessionRepoRoot, } from "./cursor-session-agent-resume.js";
 import { withCursorSessionStoreIdentities, openCursorSessionStore, resolveCursorSessionStoreIdentity, } from "./cursor-session-store.js";
 export const CURSOR_SESSION_AGENT_CLEANUP_ENTRY_TYPE = "cursor-sdk-agent-cleanup";
@@ -260,7 +261,15 @@ export async function runCursorSessionAgentCleanupCommand(pi, args, ctx, storeRo
                         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 });
+                    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) {

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,8 +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";
@@ -41,7 +42,7 @@ function rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey,
 const sessionAgentsByScope = new Map();
 const invalidatedScopeKeys = new Set();
 const deadTransportScopeKeys = new Set();
-let deadTransportAgentDisposeTimeoutMs = 3000;
+const DEAD_TRANSPORT_AGENT_DISPOSE_TIMEOUT_MS = 3000;
 const terminalDisposedScopeGenerations = new Map();
 const scopeCreationGenerations = new Map();
 const EMPTY_POOL_STATE = { status: "empty" };
@@ -107,7 +108,7 @@ function buildCustomSubagentPoolKeySuffix(agents) {
 }
 function buildSessionAgentPoolKey(scopeKey, params) {
     return [
-        scopeKey,
+        params.scope?.persistentScopeKey ?? scopeKey,
         params.cwd,
         buildModelPoolKey(params.modelSelection),
         buildSettingSourcesPoolKey(params.settingSources),
@@ -120,6 +121,8 @@ function buildSessionAgentPoolKey(scopeKey, params) {
         buildApiKeyPoolKeyFingerprint(params.apiKey),
         buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
         ...buildCustomSubagentPoolKeySuffix(params.agents),
+        // Omit for the default so historical durable keys remain byte-for-byte stable.
+        ...(params.nativeToolsEnabled === false ? ["tools:mcp-only"] : []),
     ].join("\0");
 }
 async function disposePoolEntry(entry, options) {
@@ -132,14 +135,15 @@ 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
             ? Promise.race([
                 disposal,
-                new Promise((resolve) => setTimeout(resolve, deadTransportAgentDisposeTimeoutMs).unref?.()),
+                new Promise((resolve) => setTimeout(resolve, DEAD_TRANSPORT_AGENT_DISPOSE_TIMEOUT_MS).unref?.()),
             ])
             : disposal);
     }
@@ -147,6 +151,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);
@@ -296,6 +302,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) {
@@ -320,7 +327,7 @@ 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,
             storeRoot: params.storeRoot,
             resume: resumeHandle ? { identity: resumeHandle.storeIdentity, agentId: resumeHandle.agentId } : undefined,
@@ -338,6 +345,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
                 localSafety: params.localSafety,
                 store: sessionStore.store,
             }),
+            ...(params.nativeToolsEnabled === false ? { tools: ["mcp"] } : {}),
             ...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
             ...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
         });
@@ -345,12 +353,17 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
         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 (storeSelection.persistent && !cursorSessionStoreIdentitiesEqual(sessionStore.identity, storeSelection.identities.sessionStore)) {
@@ -366,6 +379,9 @@ 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,
@@ -378,6 +394,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
             sendState: effectiveSendState,
             resumeEnabled: params.localResume === true,
             resumed,
+            releaseAgentClaim,
             ...(resumeNotice ? { resumeNotice } : {}),
         };
     }
@@ -385,19 +402,20 @@ 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;
     }
 }
 export { buildCursorSessionSendPrompt, MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP, planCursorSessionSend, } from "./cursor-session-send-policy.js";
-export function invalidateSessionAgent(scopeKey = getCursorSessionScopeKey(), options) {
+export function invalidateSessionAgent(scopeKey, options) {
     invalidatedScopeKeys.add(scopeKey);
     if (options?.deadTransport)
         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);
@@ -519,11 +537,6 @@ export const __testUtils = {
     resetSessionCursorAgent,
     refreshSessionCursorAgentConfig,
     disposeAllSessionCursorAgents,
-    setDeadTransportAgentDisposeTimeoutMs(ms) {
-        const previous = deadTransportAgentDisposeTimeoutMs;
-        deadTransportAgentDisposeTimeoutMs = ms;
-        return previous;
-    },
     SessionCursorAgentCreationSupersededError,
     SessionCursorAgentScopeClosedError,
 };

package/dist/cursor-session-scope.js

@@ -3,7 +3,7 @@ import { parseArgs } from "@earendil-works/pi-coding-agent";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
 const EPHEMERAL_SESSION_SCOPE_PREFIX = "__ephemeral__:";
-export const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
+const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
 const state = {
     sessionCwd: process.cwd(),
     sessionFile: undefined,
@@ -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,37 +58,29 @@ 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);
 }
 export function getCursorSessionScopeGeneration(scopeKey = getCursorSessionScopeKey()) {
     return scopeGenerations.get(scopeKey) ?? 0;
 }
-export function getCursorSessionCwd() {
-    return state.sessionCwd;
-}
 export function getCursorSessionProjectTrusted(pi) {
     return pi ? scopes.get(pi)?.projectTrusted === true : state.projectTrusted;
 }
-export function getCursorSessionName() {
-    return state.sessionName;
-}
 function normalizeCursorSessionName(name) {
     if (name === undefined)
         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 +93,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 +101,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 +112,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 +123,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-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.

package/dist/cursor-session-store.js

@@ -9,7 +9,7 @@ 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) {
+function hashCursorSessionStoreScope(scopeKey) {
     return createHash("sha256")
         .update("pi-cursor-sdk-session-store\0")
         .update(scopeKey)
@@ -143,7 +143,7 @@ function workspaceHashes(cwd) {
     }
 }
 function assertSafeWorkspaceLayout(cwd) {
-    // ponytail: SDK 1.0.36 has no public read-only root resolver; use one when exposed.
+    // 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, "");