pi-cursor-sdk 0.5.2 → 0.5.3

package/src/cursor-local-agent-ownership.ts

@@ -0,0 +1,18 @@
+import type { CursorSessionStoreIdentity } from "./cursor-session-store.js";
+
+// ponytail: process-local claims protect extension-owned handles and cleanup.
+// Cross-process SDK ownership requires an upstream store/agent lease contract.
+// Unproven disposal retains the exact handle claim until process exit.
+const claims = new Set<string>();
+
+export function claimCursorLocalAgent(identity: CursorSessionStoreIdentity, agentId: string): (() => void) | undefined {
+	const key = JSON.stringify([identity.stateRoot, agentId]);
+	if (claims.has(key)) return undefined;
+	claims.add(key);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		claims.delete(key);
+	};
+}

package/src/cursor-mcp-timeout-override.ts

@@ -91,7 +91,7 @@ export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boole
 
 export function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
 	if (!stack || !isCursorSdkMcpProtocolTimeoutStack(stack)) return false;
-	// SDK 1.0.36 minifies the Client class name; the protocol method and SDK
+	// The SDK minifies the Client class name; the protocol method and SDK
 	// frame, not that constructor's spelling, establish this timeout purpose.
 	return /^\s*at (?:[\w$]+\.)?(?:connect|listTools|getTools)\s*\(.*(?:node_modules[/\\]@cursor[/\\]sdk|@cursor\/sdk\/dist)/m.test(stack);
 }

package/src/cursor-pi-tool-bridge-diagnostics.ts

@@ -49,6 +49,17 @@ interface CursorPiToolBridgeRunDisposedDiagnostic extends CursorPiToolBridgeLife
 	event: "run_disposed";
 }
 
+interface CursorPiToolBridgeMcpInitializedDiagnostic {
+	event: "mcp_initialized";
+	runId: string;
+}
+
+interface CursorPiToolBridgeMcpToolsListDiagnostic {
+	event: "mcp_tools_list";
+	runId: string;
+	toolCount: number;
+}
+
 export interface CursorPiToolBridgeRequestDiagnosticFields {
 	runId: string;
 	bridgeCallId: string;
@@ -79,6 +90,8 @@ export type CursorPiToolBridgeDiagnosticEvent =
 	| CursorPiToolBridgeToolsExposedDiagnostic
 	| CursorPiToolBridgeRunCancelledDiagnostic
 	| CursorPiToolBridgeRunDisposedDiagnostic
+	| CursorPiToolBridgeMcpInitializedDiagnostic
+	| CursorPiToolBridgeMcpToolsListDiagnostic
 	| CursorPiToolBridgeRequestQueuedDiagnostic
 	| CursorPiToolBridgeRequestResolvedDiagnostic
 	| CursorPiToolBridgeRequestRejectedDiagnostic;
@@ -89,6 +102,10 @@ function assertNeverDiagnosticEvent(_event: never): never {
 
 export function serializeCursorPiToolBridgeDiagnostic(event: CursorPiToolBridgeDiagnosticEvent): Record<string, unknown> {
 	switch (event.event) {
+		case "mcp_initialized":
+			return { event: event.event, runId: event.runId };
+		case "mcp_tools_list":
+			return { event: event.event, runId: event.runId, toolCount: event.toolCount };
 		case "run_created":
 			return {
 				event: event.event,

package/src/cursor-pi-tool-bridge-run.ts

@@ -274,9 +274,16 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 			sessionIdGenerator: randomUUID,
 		});
 
-		server.setRequestHandler("tools/list", async () => ({
-			tools: this.snapshot.tools.map(snapshotToolToMcpTool),
-		}));
+		// ponytail: server-side receipts only, not SDK/model consumption or ongoing
+		// connection health; upgrade when Cursor exposes public MCP lifecycle callbacks.
+		server.oninitialized = () => {
+			this.emitDiagnostic({ event: "mcp_initialized", runId: this.id });
+		};
+		server.setRequestHandler("tools/list", async () => {
+			const tools = this.snapshot.tools.map(snapshotToolToMcpTool);
+			this.emitDiagnostic({ event: "mcp_tools_list", runId: this.id, toolCount: tools.length });
+			return { tools };
+		});
 		server.setRequestHandler("tools/call", async (request, context) => {
 			return this.enqueueToolRequest(
 				request.params.name,

package/src/cursor-provider-errors.ts

@@ -168,7 +168,7 @@ function isCursorSdkStallAbortNetworkError(code: unknown, evidence: string, stac
 }
 
 /**
- * @cursor/sdk@1.0.36 throws internal RetriableError (name/kind "RetriableError") with message
+ * @cursor/sdk@1.0.37 throws internal RetriableError (name/kind "RetriableError") with message
  * "Connection stalled" or "Connection stalled repeatedly" after fetchWithRetry exhausts stalls.
  * The ConnectError is only the cause; the top-level error is not a ConnectError.
  */
@@ -229,7 +229,7 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 
 	const directAbort = (code === 1 || code === "canceled") &&
 		(causeName === "AbortError" || /AbortError/.test(stack));
-	// The vendored 1.0.36 transport wraps a canceled ConnectError as Unknown.
+	// The vendored SDK transport can wrap a canceled ConnectError as Unknown.
 	// Require the observed canceled -> AbortError cause chain, not generic text.
 	const wrappedAbort = (code === 2 || code === "unknown") &&
 		causeName === "ConnectError" &&

package/src/cursor-provider-turn-summary.ts

@@ -40,7 +40,7 @@ export async function prepareCursorSummaryProviderTurn(
 		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/src/cursor-session-agent-cleanup.ts

@@ -5,6 +5,7 @@ import { fsyncExistingRegularFile } from "./cursor-durable-fs.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import {
 	CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE,
 	isCursorLocalAgentId,
@@ -323,7 +324,11 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 						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) {
 					failedAgentIds.push({

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

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

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

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

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

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

package/src/cursor-session-agent.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { AgentModeOption, AgentOptions, LocalAgentOptions, LocalAgentStore, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
 import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import {
 	getRegisteredCursorPiToolBridge,
 	type CursorPiToolBridge,
@@ -9,7 +10,7 @@ import {
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
-import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
 import {
 	getMatchingCursorSessionAgentResumeHandle,
 	persistCursorSessionAgentResumeHandle,
@@ -68,6 +69,7 @@ interface SessionCursorAgentReadyEntry extends SessionCursorAgentPoolEntryBase {
 	resumeEnabled: boolean;
 	resumed: boolean;
 	resumeNotice?: string;
+	releaseAgentClaim: () => void;
 }
 
 interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
@@ -78,6 +80,7 @@ interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
 	resumeEnabled: boolean;
 	resumed: boolean;
 	resumeNotice?: string;
+	releaseAgentClaim: () => void;
 	completionSettled: Promise<void>;
 	pendingCompletion: Promise<void>;
 	releaseBusyWait: () => void;
@@ -238,7 +241,7 @@ function buildCustomSubagentPoolKeySuffix(agents: AgentOptions["agents"]): strin
 
 function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCreateParams): string {
 	return [
-		scopeKey,
+		params.scope?.persistentScopeKey ?? scopeKey,
 		params.cwd,
 		buildModelPoolKey(params.modelSelection),
 		buildSettingSourcesPoolKey(params.settingSources),
@@ -262,8 +265,9 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: {
 	} catch {
 		// disposal failure should not block session replacement
 	}
+	let disposal: Promise<unknown> | undefined;
 	try {
-		const disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]()).catch(() => undefined);
+		disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]());
 		// A dead local transport may never settle SDK disposal; bound the wait so the
 		// next acquire recreates instead of hanging on the dead agent.
 		await (options?.deadTransport
@@ -276,6 +280,8 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: {
 		// disposal failure should not block session replacement
 	}
 	await entry.sessionStore.dispose().catch(() => undefined);
+	// Timeout/rejection is not proof of closure; only successful SDK disposal releases ownership.
+	void disposal?.then(entry.releaseAgentClaim, () => {});
 }
 
 async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?: boolean }): Promise<void> {
@@ -470,6 +476,7 @@ async function createSessionAgentEntry(
 ): Promise<SessionCursorAgentReadyEntry> {
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	let sessionStore: OpenCursorSessionStore | undefined;
+	let releaseAgentClaim: (() => void) | undefined;
 	try {
 		const registeredBridge = params.bridge;
 		if (registeredBridge) {
@@ -495,7 +502,7 @@ async function createSessionAgentEntry(
 		const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey, scopeKey) : undefined;
 		const storeSelection = await openCursorSessionStoreForScope({
 			cwd: params.cwd,
-			scopeKey,
+			scopeKey: params.scope?.persistentScopeKey ?? scopeKey,
 			persistent: persistentStore,
 			storeRoot: params.storeRoot,
 			resume: resumeHandle ? { identity: resumeHandle.storeIdentity, agentId: resumeHandle.agentId } : undefined,
@@ -520,11 +527,16 @@ async function createSessionAgentEntry(
 		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)) {
 					const { identities } = storeSelection;
@@ -537,6 +549,8 @@ async function createSessionAgentEntry(
 		agent ??= await createAgent(buildAgentOptions());
 		if (!agent) throw new Error("Cursor SDK agent creation returned no agent");
 		if (!sessionStore) throw new Error("Cursor SDK session store was not opened");
+		releaseAgentClaim ??= claimCursorLocalAgent(sessionStore.identity, agent.agentId);
+		if (!releaseAgentClaim) throw new Error("Cursor SDK agent is already owned by another runtime");
 
 		return {
 			status: "ready",
@@ -550,12 +564,14 @@ async function createSessionAgentEntry(
 			sendState: effectiveSendState,
 			resumeEnabled: params.localResume === true,
 			resumed,
+			releaseAgentClaim,
 			...(resumeNotice ? { resumeNotice } : {}),
 		};
 	} catch (error) {
 		bridgeRun?.cancel("Cursor session agent create failed");
 		await bridgeRun?.dispose().catch(() => undefined);
 		await sessionStore?.dispose().catch(() => undefined);
+		releaseAgentClaim?.();
 		throw error;
 	}
 }
@@ -576,9 +592,9 @@ export function invalidateSessionAgent(
 }
 
 export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
-	const params = { ...input, bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
-	const scopeKey = params.scope?.scopeKey ?? getCursorSessionScopeKey();
-	const persistentStore = (params.scope ? params.scope.sessionFile : getCursorSessionFile()) !== undefined;
+	const params = { ...input, scope: input.scope ?? getCursorSessionScopeSnapshot(), bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
+	const scopeKey = params.scope.scopeKey;
+	const persistentStore = params.scope.sessionFile !== undefined;
 	params.storeRoot = persistentStore && params.storeRoot !== undefined ? normalizeCursorCustomStoreRoot(params.storeRoot) : undefined;
 
 	while (true) {

package/src/cursor-session-scope.ts

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

package/src/cursor-session-settings.ts

@@ -1,7 +1,7 @@
 import type { AgentModeOption } from "@cursor/sdk";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { CursorExplicitSdkConfig, CursorRuntime } from "./cursor-config.js";
-import { cursorSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { cursorRuntimeSessionScopeKeyForManager, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
 
 export type CursorCliModeState =
 	| { kind: "unset" }
@@ -45,7 +45,7 @@ export function getCursorSessionSettings(scopeKey?: string) {
 
 export function cursorSettingsScopeForContext(ctx: Partial<Pick<ExtensionContext, "sessionManager">>): string | undefined {
 	const manager = ctx.sessionManager;
-	return manager ? cursorSessionScopeKeyForManager(manager) : undefined;
+	return manager ? cursorRuntimeSessionScopeKeyForManager(manager) : undefined;
 }
 
 export function registerCursorSessionSettings(pi: Pick<ExtensionAPI, "on">): void {
@@ -53,7 +53,7 @@ export function registerCursorSessionSettings(pi: Pick<ExtensionAPI, "on">): voi
 	let cli = createCliSettings();
 	pi.on("session_start", (_event, ctx) => {
 		if (scopeKey) settings.delete(scopeKey);
-		scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager);
+		scopeKey = cursorRuntimeSessionScopeKeyForManager(ctx.sessionManager);
 		legacySettings = getCursorSessionSettings(scopeKey);
 		// Reload creates a new ExtensionAPI but retains the same public manager.
 		// Keep the run's one-shot CLI consumption without retaining dead managers.

package/src/cursor-session-store.ts

@@ -194,7 +194,7 @@ function workspaceHashes(cwd: string): { current: string; legacy: string | undef
 }
 
 function assertSafeWorkspaceLayout(cwd: string): void {
-	// 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, "");

package/src/cursor-state.ts

@@ -1,7 +1,7 @@
 import type { AgentModeOption } from "@cursor/sdk";
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import {
-	buildCursorToolManifestText,
+	CURSOR_HOST_TOOL_MANIFEST_SUMMARY,
 	CURSOR_TOOL_MANIFEST_ENV,
 	resolveCursorToolManifestEnabled,
 } from "./cursor-tool-manifest.js";
@@ -17,8 +17,10 @@ import {
 import {
 	buildCursorPiToolBridgeSnapshot,
 	CURSOR_PI_TOOL_BRIDGE_ENV,
+	resolveCursorPiToolBridgeBuiltinsEnabled,
 	resolveCursorPiToolBridgeEnabled,
 } from "./cursor-pi-tool-bridge-snapshot.js";
+import { CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV } from "./cursor-pi-tool-bridge-diagnostics.js";
 import {
 	CURSOR_SETTING_SOURCES_ENV,
 	DEFAULT_CURSOR_SETTING_SOURCES,
@@ -388,7 +390,7 @@ export function formatCursorToolsDebugReport(
 	const bridgeEnabled = resolveCursorPiToolBridgeEnabled(env);
 	const manifestEnabled = resolveCursorToolManifestEnabled(env);
 	const lines = [
-		"Cursor tool surfaces (current session):",
+		"Cursor tool surfaces (current registry snapshot; not a live run):",
 		`${CURSOR_PI_TOOL_BRIDGE_ENV}: ${bridgeEnabled ? "enabled" : "disabled"}`,
 		`${CURSOR_TOOL_MANIFEST_ENV}: ${manifestEnabled ? "enabled" : "disabled"}`,
 		`${CURSOR_SETTING_SOURCES_ENV}: ${formatEffectiveCursorSettingSourcesLabel(env[CURSOR_SETTING_SOURCES_ENV])}`,
@@ -397,13 +399,31 @@ export function formatCursorToolsDebugReport(
 	let bridgeSnapshot;
 	if (bridgeEnabled) {
 		try {
-			bridgeSnapshot = buildCursorPiToolBridgeSnapshot(pi);
+			bridgeSnapshot = buildCursorPiToolBridgeSnapshot(pi, {
+				exposeOverlappingBuiltins: resolveCursorPiToolBridgeBuiltinsEnabled(env),
+			});
 		} catch {
 			lines.push("Pi bridge snapshot: unavailable (extension tool APIs required).");
 		}
 	}
 
-	lines.push(buildCursorToolManifestText({ bridgeSnapshot, piBridgeEnabled: bridgeEnabled }));
+	lines.push(
+		`Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`,
+		"Pi tool toggles affect pi tools/bridge exposure only; they do not disable Cursor host/configured MCP tools.",
+	);
+	if (!bridgeEnabled) {
+		lines.push("Pi bridge: disabled (PI_CURSOR_PI_TOOL_BRIDGE=0).");
+	} else if (bridgeSnapshot) {
+		const names = bridgeSnapshot.tools.map((tool) => tool.mcpToolName).sort();
+		lines.push(`Pi bridge exposure eligibility: ${names.length ? names.join(", ") : "no eligible pi__* tools"}.`);
+	}
+	lines.push(
+		"This snapshot does not prove a run's endpoint attachment, MCP initialization, catalog fetch, or tool calls.",
+		`For per-run observations, enable ${CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV}=1 before the turn.`,
+		"run_created/tools_exposed record exposure only; mcp_initialized records a validated notifications/initialized receipt; mcp_tools_list records catalog-handler output (toolCount), not client/model consumption or ongoing connection health.",
+		"request_queued/resolved/rejected record actual bridge call handling; absent receipts do not diagnose why a client/model made no request.",
+		"Not callable: cursor-replay-* IDs, pi history names, transcript labels.",
+	);
 	return lines.join("\n");
 }
 
@@ -496,7 +516,7 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 	});
 
 	pi.registerCommand("cursor-tools", {
-		description: "Show live Cursor tool surfaces for this session (maintainer debug)",
+		description: "Show current-registry Cursor tool exposure eligibility (maintainer debug)",
 		handler: async (_args, ctx) => {
 			emitCursorToolsDebugReport(pi, ctx);
 		},