@emmaneugene/pi-cursor-sdk 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.2 - 2026-09-07
+
+### Fixed
+
+- Register an isolated Cursor provider, SDK agent scope, and pi tool bridge for nested in-process child sessions. A non-Cursor parent can now dispatch a pi subagent with a Cursor model, and a Cursor parent can dispatch a Cursor-model pi subagent without waiting on or disposing its own busy Cursor SDK agent.
+
+## 0.4.1 - 2026-09-07
+
+### Fixed
+
+- Keep the first in-process factory as the Cursor owner. A pi child session that calls `createAgentSession` + `bindExtensions` no longer re-runs the factory in a way that disposes the live parent bridge (`Cursor pi tool bridge extension reloaded`), steals session scope, or aborts the parent `pi__subagent` call.
+
 ## 0.4.0 - 2026-09-06
 
 Breaking: Cursor Cloud support is removed. Cursor SDK runs are local-only.

package/README.md

@@ -367,6 +367,8 @@ Local Cursor runs use two separate tool surfaces:
 
 Bridge capabilities are snapshotted from `pi.getActiveTools()` and `pi.getAllTools()` for each Cursor run, including per-tool prompt guidelines when pi exposes them. Cursor sees active bridgeable pi tools as collision-safe MCP names such as `pi__sem_reindex` only when they are exposed in that current run. When exposed, Cursor is instructed to prefer `pi__mcp` for MCP work and `pi__subagent` for delegation; Cursor-configured MCP and Cursor-native subagents are fallbacks when the matching pi tool is not exposed or is unavailable. Pi session output, tool cards, confirmations, hooks, renderers, history, and abort behavior use the real pi tool name, such as `sem_reindex`. The bridge queues Cursor's MCP call, emits a normal pi `toolCall`, waits for the matching pi `toolResult`, and resolves that result back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled. The bridge does not call pi tool `execute()` handlers directly.
 
+Pi subagents can select Cursor models under both Cursor and non-Cursor parents. Each nested Cursor child registers a child-local provider and bridge and uses an isolated SDK agent scope, so it does not replace or wait on the parent's active Cursor agent.
+
 Overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are hidden by default because Cursor local agents already have native equivalents. Extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. The bridge also exposes `cursor_ask_question` as `pi__cursor_ask_question` when enabled, allowing Cursor to ask the user through pi UI instead of silently choosing a default. When pi has visible Agent Skills loaded, the extension rewrites pi's skill catalog for Cursor and exposes `cursor_activate_skill` as `pi__cursor_activate_skill`; Cursor should call that bridge tool with a listed skill name to load the full `SKILL.md` and bundled resource list before applying the skill. If the bridge is disabled, the catalog remains available and instructs Cursor to fall back to reading the listed `SKILL.md` path directly.
 
 Cursor-native tool replay is separate from the bridge. Replay cards are display-only recorded Cursor SDK activity. They never re-run Cursor-side commands, reapply Cursor edits, call MCP servers, or mutate pi state. See [Cursor native tool replay](docs/cursor-native-tool-replay.md).

package/dist/cursor-extension-factory-guard.js

@@ -0,0 +1,31 @@
+let factoryOwnerToken;
+export function claimCursorExtensionFactory() {
+    if (factoryOwnerToken)
+        return { kind: "nested" };
+    const token = Symbol("cursor-extension-factory-owner");
+    factoryOwnerToken = token;
+    return { kind: "owner", token };
+}
+export function releaseCursorExtensionFactory(token) {
+    if (factoryOwnerToken === token) {
+        factoryOwnerToken = undefined;
+    }
+}
+/**
+ * Install the owner's release handler after all other factory registration
+ * succeeds. The final handler keeps ownership until earlier shutdown cleanup
+ * has finished.
+ */
+export function registerCursorExtensionFactoryRelease(pi, claim) {
+    pi.on("session_shutdown", () => {
+        releaseCursorExtensionFactory(claim.token);
+    });
+}
+export const __testUtils = {
+    isInstalled() {
+        return factoryOwnerToken !== undefined;
+    },
+    reset() {
+        factoryOwnerToken = undefined;
+    },
+};

package/dist/cursor-pi-tool-bridge-server.js

@@ -41,6 +41,9 @@ export class CursorPiToolBridgeRegistry {
         run.emitStartDiagnostics(bridgeEnabled);
         return run;
     }
+    hasLiveRuns() {
+        return this.runs.size > 0;
+    }
     async disposeAll(reason = "Cursor pi tool bridge disposed") {
         await Promise.all([...this.runs].map(async (run) => {
             run.cancel(reason);

package/dist/cursor-pi-tool-bridge.js

@@ -48,13 +48,9 @@ Get-CimInstance Win32_Process -Filter "Name = 'bash.exe' OR Name = 'sh.exe'" |
         windowsHide: true,
     });
 }
-export function registerCursorPiToolBridge(pi) {
-    bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
-    void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
-    const bridge = new CursorPiToolBridgeRegistry(pi);
-    registeredCursorPiToolBridge = bridge;
+function attachCursorPiToolBridgeHandlers(pi, bridge, options) {
     pi.on("tool_call", (event, ctx) => {
-        if (registeredCursorPiToolBridge !== bridge)
+        if (!options.isActive())
             return undefined;
         if (!bridge.hasPendingPiToolCallId(event.toolCallId)) {
             return isCursorPiBridgeToolCallId(event.toolCallId)
@@ -81,9 +77,34 @@ export function registerCursorPiToolBridge(pi) {
     });
     pi.on("session_shutdown", async (event) => {
         const reason = `Cursor pi tool bridge session shutdown: ${event.reason}`;
-        bridgeToolExecutionAbortTracker.abortAll(reason);
+        if (options.abortAllOnShutdown)
+            bridgeToolExecutionAbortTracker.abortAll(reason);
         await bridge.disposeAll(reason);
     });
+}
+export function registerCursorPiToolBridge(pi) {
+    // Replacing a bridge during a live MCP run cancels its pending pi tool
+    // calls. Keep the active registry as a final safety belt.
+    if (registeredCursorPiToolBridge?.hasLiveRuns()) {
+        return registeredCursorPiToolBridge;
+    }
+    bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
+    void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
+    const bridge = new CursorPiToolBridgeRegistry(pi);
+    registeredCursorPiToolBridge = bridge;
+    attachCursorPiToolBridgeHandlers(pi, bridge, {
+        abortAllOnShutdown: true,
+        isActive: () => registeredCursorPiToolBridge === bridge,
+    });
+    return bridge;
+}
+/** Register a bridge owned only by one nested in-process child session. */
+export function registerNestedCursorPiToolBridge(pi) {
+    const bridge = new CursorPiToolBridgeRegistry(pi);
+    attachCursorPiToolBridgeHandlers(pi, bridge, {
+        abortAllOnShutdown: false,
+        isActive: () => true,
+    });
     return bridge;
 }
 export function getRegisteredCursorPiToolBridge() {

package/dist/cursor-provider-lazy.js

@@ -21,11 +21,11 @@ function makeProviderRuntimeErrorMessage(model, error, apiKey) {
         errorMessage: `Cursor provider runtime failed: ${sanitizeCursorProviderError(error, apiKey)}`,
     };
 }
-export function streamCursorLazy(model, context, options) {
+export function streamCursorLazy(model, context, options, runtimeContext) {
     const outer = createAssistantMessageEventStream();
     queueMicrotask(async () => {
         try {
-            for await (const event of streamCursor(model, context, options)) {
+            for await (const event of streamCursor(model, context, options, runtimeContext)) {
                 outer.push(event);
             }
         }

package/dist/cursor-provider-live-run-drain.js

@@ -32,8 +32,8 @@ function getCursorNativeReplayIdFromToolCallId(toolCallId) {
 export function getPendingCursorLiveRun(context) {
     return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId);
 }
-export function getActiveCursorLiveRunForCurrentScope() {
-    return cursorLiveRuns.getActiveForScope();
+export function getActiveCursorLiveRunForScope(scopeKey) {
+    return cursorLiveRuns.getActiveForScope(scopeKey);
 }
 function splitTextIntoReplayDeltas(text) {
     const deltas = [];
@@ -334,10 +334,10 @@ export async function drainCursorLiveRunTurn(stream, partial, model, context, ru
         });
     }
 }
-export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder) {
+export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder, scopeKey) {
     turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
     while (true) {
-        const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
+        const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForScope(scopeKey);
         if (!run || run.disposed) {
             turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
             return "continue_send";

package/dist/cursor-provider-run-finalizer.js

@@ -89,6 +89,7 @@ export class CursorRunFinalizer {
         if (liveCompletion) {
             void liveCompletion.waitCompletion
                 .finally(async () => {
+                await prepared?.lifecycle.dispose().catch(() => { });
                 await this.finalizeSdkEventDebugBestEffort();
                 this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
             })

package/dist/cursor-provider-runtime-context.js

@@ -0,0 +1 @@
+export {};

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

@@ -20,20 +20,23 @@ import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
-export function resolveCursorProviderTurnConfig(cwd) {
-    return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+export function resolveCursorProviderTurnConfig(cwd, projectTrusted = getCursorSessionProjectTrusted()) {
+    return resolveEffectiveCursorConfig({ cwd, projectTrusted });
 }
-function buildLocalCursorProviderTurnLifecycle(lease, scopeKey) {
+function buildLocalCursorProviderTurnLifecycle(lease, scopeKey, disposeAgentAfterTurn) {
     return {
         trackRunCompletion: (completion) => lease.trackRunCompletion(completion),
         commitSend: (context, bootstrapped) => lease.commitSend(context, bootstrapped),
         abandon: () => abandonSessionCursorAgent(scopeKey),
-        dispose: async () => { },
+        dispose: async () => {
+            if (disposeAgentAfterTurn)
+                await resetSessionCursorAgent(scopeKey);
+        },
     };
 }
 async function prepareCursorLocalProviderTurn(prepareParams) {
     const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
-    const { model, context, options } = params;
+    const { model, context, options, runtimeContext } = params;
     let restoreCursorSdkOutputFilter;
     let sessionAgentScopeKey;
     let liveRun;
@@ -54,6 +57,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         const queuedBridgeRequestsBeforeLiveRun = [];
         let liveRunForBridgeQueue;
         const bridgeExcludeToolNames = buildCursorBridgeExcludeToolNames(resolvedConfig);
+        const localResumeEnabled = runtimeContext?.localResume ?? resolvedConfig.local.resume.value;
         const sessionAgentAcquireParams = {
             apiKey: resolvedApiKey,
             agentMode,
@@ -61,8 +65,12 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             modelSelection: selection,
             settingSources,
             localSafety,
-            localResume: resolvedConfig.local.resume.value,
+            localResume: localResumeEnabled,
             useHttp1ForAgent,
+            runtimeScope: runtimeContext
+                ? { scopeKey: runtimeContext.scopeKey, sessionFile: runtimeContext.sessionFile }
+                : undefined,
+            bridge: runtimeContext?.bridge,
             bridgeExcludeToolNames,
             debugRecorder: sdkEventDebug,
             onBridgeToolRequest: (request) => {
@@ -124,7 +132,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         };
         const sessionBridgeRun = bridgeRun;
         const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
-        const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+        const useNativeToolReplay = runtimeContext?.nativeToolReplay ?? isCursorNativeToolDisplayRuntimeEnabled();
         const activeToolNames = getActiveContextToolNames(context);
         sdkEventDebug?.recordProviderMeta({
             model: {
@@ -142,7 +150,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             toolManifestEnabled: resolveCursorToolManifestEnabled(),
             agentMode,
             localForce: resolvedConfig.local.force.value,
-            localResume: resolvedConfig.local.resume.value,
+            localResume: localResumeEnabled,
             resumedAgent: sessionAgentLease.resumed,
             activeToolNames: activeToolNames ? [...activeToolNames] : [],
             sessionAgentScopeKey,
@@ -204,7 +212,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             sessionAgentLease,
             localForce: resolvedConfig.local.force,
             restoreCursorSdkOutputFilter,
-            lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey),
+            lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey, runtimeContext?.disposeAgentAfterTurn === true),
             runtime: liveRun
                 ? { kind: "live", liveRun, turnCoordinator }
                 : { kind: "direct", turnCoordinator },

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

@@ -42,7 +42,8 @@ export class CursorProviderTurnRunner {
         });
         try {
             this.throwIfAborted();
-            const cwd = getCursorSessionCwd();
+            const runtimeContext = this.params.runtimeContext;
+            const cwd = runtimeContext?.cwd ?? getCursorSessionCwd();
             this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
                 cwd,
                 modelId: model.id,
@@ -50,10 +51,10 @@ export class CursorProviderTurnRunner {
             });
             sdkEventDebugRef.current = this.sdkEventDebug;
             this.sdkEventDebug?.recordContextSnapshot(context);
-            const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
-            const localScopeKey = getCursorSessionScopeKey();
+            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, runtimeContext?.projectTrusted);
+            const localScopeKey = runtimeContext?.scopeKey ?? getCursorSessionScopeKey();
             sdkProcessErrorGuard.containLocalTransportClosedPipe(() => invalidateSessionAgent(localScopeKey, { deadTransport: true }));
-            if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+            if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, localScopeKey)) ===
                 "stream_ended") {
                 return;
             }

package/dist/cursor-provider.js

@@ -27,7 +27,7 @@ function makeInitialMessage(model) {
         timestamp: Date.now(),
     };
 }
-export function streamCursor(model, context, options) {
+export function streamCursor(model, context, options, runtimeContext) {
     const stream = createAssistantMessageEventStream();
     const sdkEventDebugRef = {};
     attachCursorSdkEventDebugPiStreamTap(stream, sdkEventDebugRef);
@@ -39,11 +39,12 @@ export function streamCursor(model, context, options) {
             stream,
             partial,
             options,
+            runtimeContext,
             sdkEventDebugRef,
         });
         try {
             stream.push({ type: "start", partial });
-            await runExclusiveCursorSessionTurn(getCursorSessionScopeKey(), () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
+            await runExclusiveCursorSessionTurn(runtimeContext?.scopeKey ?? getCursorSessionScopeKey(), () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
         }
         catch (error) {
             await runner.handleOuterCatch(error);

package/dist/cursor-session-agent.js

@@ -283,16 +283,18 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
     let bridgeRun;
     let sessionStore;
     try {
-        const registeredBridge = getRegisteredCursorPiToolBridge();
+        const registeredBridge = params.bridge ?? getRegisteredCursorPiToolBridge();
         if (registeredBridge) {
-            bridgeRun = await registeredBridge.createRun({
+            const createdBridgeRun = await registeredBridge.createRun({
                 onToolRequest: params.onBridgeToolRequest,
                 debugRecorder: params.debugRecorder,
                 excludeToolNames: params.bridgeExcludeToolNames,
             });
-            if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
-                await bridgeRun.dispose();
-                bridgeRun = undefined;
+            if (!createdBridgeRun.enabled || !createdBridgeRun.mcpServers) {
+                await createdBridgeRun.dispose();
+            }
+            else {
+                bridgeRun = createdBridgeRun;
             }
         }
         const resolvedPoolKey = buildSessionAgentPoolKey(scopeKey, params);
@@ -382,8 +384,8 @@ export function invalidateSessionAgent(scopeKey = getCursorSessionScopeKey(), op
         deadTransportScopeKeys.add(scopeKey);
 }
 export async function acquireSessionCursorAgent(params) {
-    const scopeKey = getCursorSessionScopeKey();
-    const persistentStore = getCursorSessionFile() !== undefined;
+    const scopeKey = params.runtimeScope?.scopeKey ?? getCursorSessionScopeKey();
+    const persistentStore = params.runtimeScope ? params.runtimeScope.sessionFile !== undefined : getCursorSessionFile() !== undefined;
     let forceCreate = params.forceCreate === true;
     while (true) {
         assertScopeAcceptsAcquire(scopeKey);

package/dist/index.js

@@ -1,7 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { discoverModels } from "./model-discovery.js";
 import { registerCursorRuntimeControls } from "./cursor-state.js";
 import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-registration.js";
-import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import { registerCursorPiToolBridge, registerNestedCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
 import { registerCursorSkillTool } from "./cursor-skill-tool.js";
 import { registerCursorSessionScope } from "./cursor-session-scope.js";
@@ -15,68 +16,122 @@ import { registerCursorAgentsContextDedup } from "./cursor-agents-context-regist
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
-function createCursorProviderConfig(models) {
+import { disposeSessionCursorAgent } from "./cursor-session-agent.js";
+import { getCursorSessionCwd, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { claimCursorExtensionFactory, registerCursorExtensionFactoryRelease, releaseCursorExtensionFactory, } from "./cursor-extension-factory-guard.js";
+let activeCursorProviderModels;
+function createCursorProviderConfig(models, streamSimple = streamCursorLazy) {
     return {
         name: "Cursor",
         baseUrl: "https://cursor.com",
         apiKey: CURSOR_API_KEY_CONFIG_VALUE,
         api: "cursor-sdk",
         models,
-        streamSimple: streamCursorLazy,
+        streamSimple,
     };
 }
-function registerCursorProvider(pi, models) {
-    pi.registerProvider("cursor", createCursorProviderConfig(models));
+function registerCursorProvider(pi, models, streamSimple) {
+    pi.registerProvider("cursor", createCursorProviderConfig(models, streamSimple));
 }
-export default async function (pi) {
-    // Session cwd must register before other session_start listeners that depend on it.
-    registerCursorSessionScope(pi);
-    registerCursorSessionAgentLineage(pi);
-    registerCursorSessionAgentLifecycle(pi);
-    registerCursorSessionAgentResume(pi);
-    pi.on("session_before_compact", async () => {
-        await prepareCursorSessionForCompaction();
+function registerNestedCursorProvider(pi, models) {
+    const bridge = registerNestedCursorPiToolBridge(pi);
+    const nestedRuntimeId = randomUUID();
+    let runtimeContext = {
+        scopeKey: `__nested_cursor__:${nestedRuntimeId}`,
+        cwd: getCursorSessionCwd(),
+        sessionFile: undefined,
+        projectTrusted: getCursorSessionProjectTrusted(),
+        bridge,
+        localResume: false,
+        nativeToolReplay: false,
+        disposeAgentAfterTurn: true,
+    };
+    pi.on("session_start", (_event, ctx) => {
+        const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? undefined;
+        const sessionId = ctx.sessionManager?.getSessionId?.() ?? nestedRuntimeId;
+        runtimeContext = {
+            ...runtimeContext,
+            scopeKey: sessionFile ?? `__nested_cursor__:${sessionId}`,
+            cwd: ctx.cwd,
+            sessionFile,
+            projectTrusted: ctx.isProjectTrusted?.() === true || runtimeContext.projectTrusted,
+        };
     });
-    registerCursorRuntimeControls(pi);
-    registerCursorNativeToolDisplay(pi);
-    registerCursorQuestionTool(pi);
-    registerCursorSkillTool(pi);
-    registerCursorPiToolBridge(pi);
-    registerCursorAgentsContextDedup(pi);
-    registerCursorOverflowNormalization(pi);
-    let fallbackIssue;
-    const models = await discoverModels({
-        onFallback: (issue) => {
-            fallbackIssue = issue;
-        },
+    pi.on("session_shutdown", async () => {
+        await disposeSessionCursorAgent(runtimeContext.scopeKey);
     });
-    if (fallbackIssue) {
-        registerCursorFallbackIssueWarning(pi, fallbackIssue);
+    registerCursorProvider(pi, models, (model, context, options) => streamCursorLazy(model, context, options, runtimeContext));
+}
+export default async function (pi) {
+    const factoryClaim = claimCursorExtensionFactory();
+    if (factoryClaim.kind === "nested") {
+        if (!activeCursorProviderModels) {
+            throw new Error("Nested Cursor provider loaded before the owner model catalog was ready");
+        }
+        registerNestedCursorProvider(pi, activeCursorProviderModels);
+        return;
+    }
+    try {
+        // Discover first. A discovery failure must not leave process-global
+        // registrars from a discarded extension load.
+        let fallbackIssue;
+        const models = await discoverModels({
+            onFallback: (issue) => {
+                fallbackIssue = issue;
+            },
+        });
+        activeCursorProviderModels = models;
+        // Session cwd must register before other session_start listeners that depend on it.
+        registerCursorSessionScope(pi);
+        registerCursorSessionAgentLineage(pi);
+        registerCursorSessionAgentLifecycle(pi);
+        registerCursorSessionAgentResume(pi);
+        pi.on("session_before_compact", async () => {
+            await prepareCursorSessionForCompaction();
+        });
+        registerCursorRuntimeControls(pi);
+        registerCursorNativeToolDisplay(pi);
+        registerCursorQuestionTool(pi);
+        registerCursorSkillTool(pi);
+        registerCursorPiToolBridge(pi);
+        registerCursorAgentsContextDedup(pi);
+        registerCursorOverflowNormalization(pi);
+        if (fallbackIssue) {
+            registerCursorFallbackIssueWarning(pi, fallbackIssue);
+        }
+        pi.registerCommand("cursor-refresh-models", {
+            description: "Refresh the live Cursor model catalog without restarting pi",
+            handler: async (_args, ctx) => {
+                let refreshFallbackIssue;
+                const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
+                const refreshedModels = await discoverModels({
+                    apiKey,
+                    forceRefresh: true,
+                    onFallback: (issue) => {
+                        refreshFallbackIssue = issue;
+                    },
+                });
+                registerCursorProvider(pi, refreshedModels);
+                if (!ctx.hasUI)
+                    return;
+                if (refreshFallbackIssue) {
+                    ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
+                }
+                else {
+                    ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
+                }
+            },
+        });
+        registerCursorProvider(pi, models);
+        // Keep the process error guard near the end so earlier Cursor cleanup
+        // remains protected during session shutdown.
+        registerCursorSdkSessionProcessErrorGuard(pi);
+        // Register last so ownership remains protected until all other Cursor
+        // session_shutdown handlers finish.
+        registerCursorExtensionFactoryRelease(pi, factoryClaim);
+    }
+    catch (error) {
+        releaseCursorExtensionFactory(factoryClaim.token);
+        throw error;
     }
-    pi.registerCommand("cursor-refresh-models", {
-        description: "Refresh the live Cursor model catalog without restarting pi",
-        handler: async (_args, ctx) => {
-            let refreshFallbackIssue;
-            const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
-            const refreshedModels = await discoverModels({
-                apiKey,
-                forceRefresh: true,
-                onFallback: (issue) => {
-                    refreshFallbackIssue = issue;
-                },
-            });
-            registerCursorProvider(pi, refreshedModels);
-            if (!ctx.hasUI)
-                return;
-            if (refreshFallbackIssue) {
-                ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
-            }
-            else {
-                ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
-            }
-        },
-    });
-    registerCursorProvider(pi, models);
-    // Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
-    registerCursorSdkSessionProcessErrorGuard(pi);
 }

package/docs/cursor-live-smoke-checklist.md

@@ -183,7 +183,7 @@ npm run smoke:visual -- "${VISUAL_ARGS[@]}" \
   --prompt 'Stay in Cursor plan mode. If Cursor exposes plan, todo, task, or mode activity for this request, use that capability to outline a tiny unit test without editing files. Otherwise answer with a concise numbered plan. Do not use shell or file mutation tools.'
 ```
 
-By default, `npm run smoke:visual` writes `.ansi`, `.txt`, `.html`, `.png`, and `.jsonl.path` artifacts. If Playwright Chromium is unavailable in an agent-harness run, rerun with `--no-screenshot`, open the generated `.html` with `agent_browser`, save a PNG screenshot, and record that PNG path beside the runner artifacts. To visually audit bridge behavior or ambient Cursor settings, opt in with `--bridge`, `--bridge --expose-builtin-tools`, or `--setting-sources <value>` and label that evidence separately; do not count those opt-in runs as default native replay matrix proof.
+By default, `npm run smoke:visual` writes `.ansi`, `.txt`, `.html`, `.png`, and `.jsonl.path` artifacts. The runner uses Playwright's Chromium or a system Chrome installation. If neither is available in an agent-harness run, rerun with `--no-screenshot`, open the generated `.html` with `agent_browser`, save a PNG screenshot, and record that PNG path beside the runner artifacts. To visually audit bridge behavior or ambient Cursor settings, opt in with `--bridge`, `--bridge --expose-builtin-tools`, or `--setting-sources <value>` and label that evidence separately; do not count those opt-in runs as default native replay matrix proof.
 
 Expected proof for each category is defined in [Cursor Native Tool Visual Audit Workflow](./cursor-native-tool-visual-audit.md). Do not mark a category passed because the prompt was sent. A category passes only when the PNG shows the expected card and the JSONL shows the expected completed `toolCall` / `toolResult` pair with the expected `isError` state.
 

package/docs/cursor-model-ux-spec.md

@@ -29,7 +29,7 @@ Current implementation notes:
 - The bridge queues MCP calls, emits provider `toolcall_*` events, waits for matching pi `toolResult` messages by `toolCallId`, resolves the result back into the same live Cursor SDK run without creating a new `Agent`, and never calls tool `execute()` handlers directly. The same-run resume invariant holds unless the run was disposed, aborted, or cancelled.
 - Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.30 still has a 60-second MCP request default with no public per-server timeout option. The extension extends the verified Cursor SDK MCP `callTool` timeout path to 3600 seconds by default and shortens the verified first-send MCP initialize/listTools timeout paths to 10 seconds by default so unavailable configured MCP servers do not block the first reply for a full minute; unknown MCP protocol timeout stacks keep the SDK default. Users can override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`. Bridged `CallTool` waits also have a local fail-closed deadline that defaults to and cannot exceed the effective MCP tool timeout; `PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS` can lower it, expiry or MCP cancellation aborts active pi execution when available, and expired bridge events are dropped before pi tool emission.
 - Cursor SDK local safety controls are off by default. `--cursor-auto-review` / `PI_CURSOR_AUTO_REVIEW` and `--cursor-sandbox` / `PI_CURSOR_SANDBOX` pass only explicit enabled values into `Agent.create({ local })`; user or trusted project config can set `local.autoReview` and `local.sandboxOptions.enabled`; project config is active only when Pi's project-trust flow reached the extension and approved the project or the run used explicit `--approve`, and project saves require the same immutable trust provenance rather than creating Pi trust resources automatically. Pi 0.84.0 loads `pi install -l` project-local extensions after the trust event, so those installs require `--approve` on every run that reads or writes `.pi/cursor-sdk.json`. Fast-default and HTTP transport saves preserve unrecognized config fields, reject malformed or non-object JSON without rewriting it, and use one lock-protected read-modify-write path; fast saves mutate only the selected model key. Because Pi can mutate its in-memory session branch before a journal append throws, a completed global save is authoritative and the command reports the partial journal failure instead of attempting an ambiguous rollback; the new global value stays authoritative over stale branch entries until a later successful save or session restart.
-- Local HTTP/1.1/SSE compatibility is strictly opt-in through `PI_CURSOR_HTTP_1_1`, `/cursor-http on|off|toggle`, or user `cursor-sdk.json` `local.useHttp1ForAgent`. Precedence is session, environment, user, then the built-in unset default; project config is excluded. Unset makes no `Cursor.configure()` call. Explicit values configure the installed SDK before local `Agent.create()`, extension-owned explicit state is cleared with the SDK's documented `null` reset when returning to unset and during session shutdown before module reload, and default/HTTP2/HTTP1 choices split pooled local agents. Pi's supported CLI/TUI/print/RPC lifecycle has one active session runtime per process; concurrent independent `AgentSession` embedding in one process is outside this transport toggle's contract because the installed SDK setting and executor cache are module-global. The footer adds `http1` only when HTTP/1.1 transport is enabled.
+- Local HTTP/1.1/SSE compatibility is strictly opt-in through `PI_CURSOR_HTTP_1_1`, `/cursor-http on|off|toggle`, or user `cursor-sdk.json` `local.useHttp1ForAgent`. Precedence is session, environment, user, then the built-in unset default; project config is excluded. Unset makes no `Cursor.configure()` call. Explicit values configure the installed SDK before local `Agent.create()`, extension-owned explicit state is cleared with the SDK's documented `null` reset when returning to unset and during session shutdown before module reload, and default/HTTP2/HTTP1 choices split pooled local agents. Pi's supported CLI/TUI/print/RPC lifecycle has one active session runtime per process; concurrent independent `AgentSession` embedding in one process is outside this transport toggle's contract because the installed SDK setting and executor cache are module-global. The extension factory has process-owner and nested-child paths. The first load owns process-global controls, session scope, native replay state, and the owner SDK agent pool. A nested child `createAgentSession` load registers only a child-local Cursor provider, bridge, and SDK agent scope. This split keeps the parent bridge live and lets a Cursor child run without waiting on the busy parent SDK agent. The footer adds `http1` only when HTTP/1.1 transport is enabled.
 - Bridge diagnostics are opt-in only: `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` writes typed, allowlisted, scrubbed single-line JSONL records to `process.stderr` with prefix `[pi-cursor-sdk:bridge]`. Diagnostics are scrubbed operational logs, not anonymous telemetry. They intentionally include tool names, safe correlation IDs, run lifecycle, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. Correlation IDs are generated independently from the tokenized endpoint path, and Cursor MCP call IDs are hashed before serialization. Diagnostics must not include endpoint paths/URLs/path components/tokens, API keys, bearer tokens, cookies, session credentials, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, or local private session paths in tracked docs, and they must not call pi UI status, notification, or footer APIs. If tool names themselves are unacceptable for a release target, bridge debug diagnostics are not safe for shared logs under the current contract.
 - This repo does not provide a generic desktop-automation, browser-driver, or CDP recipe. Provider docs should describe pi-cursor-sdk's Cursor provider/bridge contract only.
 - Cursor internal tool activity is recorded from SDK events and scrubbed. Maintainer reference for `@cursor/sdk@1.0.30` `ToolType` values, runtime alias normalization, and intentional mapping/fallback rules: [Cursor native tool replay — SDK ToolType replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix) (official SDK docs: https://cursor.com/docs/sdk/typescript). In TUI sessions and structured JSON/RPC modes, supported completed `read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`, diagnostics, delete, todo/plan, task, image generation, MCP, semantic search, and screen recording activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so users and JSON/RPC consumers can see native-looking cards/events without rerunning Cursor's reads/shell commands/file edits. Cursor `glob` activity is replayed through native `find` cards. Cursor write activity is replayed through native-looking `write` cards, and Cursor StrReplace/edit activity uses native-looking `edit` only when recorded arguments truthfully satisfy pi's `edit` schema; path-only Cursor edit and notebook edit replay falls back to neutral Cursor activity before pi validation. Diagnostics, delete, todos/plans, task/subagent, image, and MCP activity use neutral Cursor activity cards with pi's default success/error shell. Cursor SDK `task` activity is labeled **Cursor subagent** by default because it represents Cursor-spawned child-agent work; the card summary includes description plus subagent kind/model/short ID when Cursor reports them, and `PI_CURSOR_TASK_PRESENTATION=task` restores the older **Cursor task** wording for comparison. This is visibility over Cursor SDK task events, not a native pi subagent session: pi shows start/final output plus any `conversationSteps` tool-call summaries Cursor returns, but cannot show a live nested read/shell/MCP trail when the SDK only returns final subagent text. Neutral Cursor activity calls include `activityTitle` and, when available, `activitySummary` so partial/collapsed cards preserve identity such as `Cursor plan`, `Cursor todos`, `Cursor subagent`, `Cursor MCP`, or `Cursor edit`. For long-running or externally meaningful Cursor tools (`task`, `shell`, `mcp`, `generateImage`, `recordScreen`, `semSearch`, web search/fetch, plan/todo), the provider may surface one low-noise deferred in-progress thinking line such as `Cursor MCP: external_search` from bounded, scrubbed SDK args; fast local tools (`read`, `grep`, `glob`, and similar) skip lifecycle lines when completion follows immediately, and pi bridge MCP calls are excluded because pi already shows real pi tool execution ([lifecycle visibility](./cursor-native-tool-replay.md#low-noise-tool-lifecycle-visibility)). Replay-only tools display recorded Cursor results, normalize workspace-local paths/diff headers for display, use pi diff colors for edit previews and path-inferred syntax highlighting for write previews, and fail closed if called without a recorded result. Native replay wrappers are registered only for tool names not already owned by another extension; conflicting tools use the bounded scrubbed transcript fallback. Cursor workflow tools such as mode/task/todo/plan activity are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards can be followed by Cursor's final plan text, selected from `run.wait().result` when Cursor provides one and trimmed against already-emitted text. Started Cursor SDK tool calls that never receive a completion event are surfaced with bounded user-visible labels/traces (neutral activity cards when native replay routing allows, otherwise the same inactive or transcript trace fallbacks used for completed replay) instead of being silently discarded when the run failed, was aborted, or produced no assistant text; after a successful text-producing run, missing-completion starts remain maintainer-debug-only for all tools: installed `@cursor/sdk` 1.0.30 emits `tool-call-started` with no completion delta, step, or conversation entry when a permission policy or hook denies a call, and offers no way to distinguish such denials from lost completions, so suppression is the deliberate choice over false error cards. Explicit failures remain visible when Cursor reports them through completed tool calls or step results. Pi bridge MCP starts remain excluded from duplicate incomplete Cursor cards because pi already shows real pi tool execution. `PI_CURSOR_NATIVE_TOOL_DISPLAY=0` disables native replay, and `PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is a registration-only opt-out that keeps the transcript fallback without shadowing pi tool names. When bridge or native replay cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK activity arrives: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later tool batches as further `toolUse` turns, then Cursor's final assistant answer. For shell replay, completed `stdout` / `stderr` are primary; unambiguous `shell-output-delta` data is also shown as bounded live progress while one shell call is active and used as display-only fallback for empty successful shell completions, while overlapping shell calls drop ambiguous deltas instead of guessing. Print mode keeps bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when no live-run turn split is active.

package/docs/cursor-native-tool-visual-audit.md

@@ -76,7 +76,7 @@ npm install
 npx playwright install chromium
 ```
 
-`npx playwright install chromium` is only needed for automatic PNG capture. When running inside the pi agent harness, `agent_browser` is the preferred screenshot tool for generated HTML/ANSI output because it can open local files, verify saved artifacts, and capture exact evidence paths; in that case, run `npm run smoke:visual -- --no-screenshot ...` and screenshot the generated `.html` with `agent_browser`. Outside the harness, use Playwright through the checked-in runner.
+Automatic PNG capture uses Playwright's Chromium or a system Chrome installation. If neither is available, run `npx playwright install chromium`. When running inside the pi agent harness, `agent_browser` is the preferred screenshot tool for generated HTML/ANSI output because it can open local files, verify saved artifacts, and capture exact evidence paths. In that case, run `npm run smoke:visual -- --no-screenshot ...` and screenshot the generated `.html` with `agent_browser`. Outside the harness, use Playwright through the checked-in runner.
 
 ## Runner contract
 
@@ -95,8 +95,8 @@ npx playwright install chromium
 - `TERM=xterm-256color`
 - cwd set to the target audit repo; the tmux session starts in `--cwd` with a non-login shell so a stale tmux-server cwd cannot print `getcwd` errors
 - `--session-id` forwarded to pi only when explicitly provided, so fresh captures avoid the new-session warning line
-- prompt paste plus carriage return into the interactive TUI
-- bounded post-prompt wait via `--wait-ms`
+- prompt submitted after the Cursor TUI footer appears, using bracketed tmux paste and a literal carriage return
+- bounded TUI readiness wait via `--startup-ms` and bounded post-submit wait via `--wait-ms`
 - artifacts outside the repo by default
 - `<label>.ansi`, `<label>.txt`, `<label>.html`, `<label>.png`, `<label>.jsonl.path`, and `<label>.manifest.json`
 - `--label`, `--ext`, `--cwd`, `--prompt`, `--prompt-file`, `--wait-ms`, and `--out-dir`

package/docs/cursor-testing-lessons.md

@@ -28,6 +28,30 @@ Passing hundreds of unit tests did not prove that chain was safe. Regression cov
 
 When changing provider/runtime behavior, ask whether the bug spans **pi extension lifecycle**, **active tool state**, **provider streaming**, and **persisted JSONL**. If yes, add an integration-style unit test or live smoke coverage for that chain.
 
+## In-process child sessions re-run the extension factory
+
+Pi subagents build a child `AgentSession` in the same process (`createAgentSession` + `bindExtensions`). That re-invokes the `pi-cursor-sdk` factory against a new ExtensionAPI while the parent Cursor run still owns the process-global bridge, session scope, and pooled SDK agent.
+
+The first observed failure: the child died at `0 tool uses` with no transcript file. The parent turn aborted with `This operation was aborted`. Bridge diagnostics showed `request_rejected` / `cancelled` with `Cursor pi tool bridge extension reloaded`.
+
+The process-owner guard fixed that abort, but an unconditional nested-factory return introduced a second failure. A child that selected `cursor/grok-4.6` had model metadata from the parent but no `cursor` provider in its own model runtime. Pi reported `unrecognized provider error` before the first child turn.
+
+Nested factories must split registration by ownership:
+
+- The owner registers process-global controls, session state, native replay, and the owner bridge.
+- Each nested child registers the Cursor provider on its own ExtensionAPI.
+- Each nested child uses its own scope key and SDK agent pool entry. A Cursor child must not wait for the busy parent agent that is waiting for the subagent result.
+- Each nested child uses its own bridge registry over the child's active pi tools. Child shutdown must not call the process-wide bridge abort path.
+- Nested children disable local resume and native replay wrappers. They dispose their isolated SDK agent after the provider run completes.
+
+Regression coverage:
+
+- `test/cursor-extension-factory-guard.test.ts` — owner tokens reject stale release and release for every Pi shutdown reason
+- `test/index-factory-guard.test.ts` — nested factories register only the child-local provider and bridge hooks without stealing owner scope
+- `test/cursor-session-agent.test.ts` — a nested scope acquires its own SDK agent while the parent scope is busy
+- `test/cursor-pi-tool-bridge.test.ts` — nested bridge shutdown does not reject a pending owner bridge call
+- `test/cursor-provider-run-finalizer.test.ts` — live provider completion runs the nested lifecycle disposal path
+
 ## Dual-check invariant: `context.tools` vs pi active tools
 
 Native replay routing intentionally uses two layers:

package/docs/platform-smoke.md

@@ -434,7 +434,7 @@ Doctor checks:
 17. `tar` is available on macOS and native Windows.
 18. `node-pty` self-test passes on every target.
 19. Target pi tool probe proves the shell tool accepts platform-rendered commands on every target.
-20. Host-side xterm/Playwright render self-test passes by rendering a minimal ANSI fixture through the repo xterm helper and launching Playwright Chromium to write a tiny PNG. If this fails, run `npm install` and `npx playwright install chromium` before live suites.
+20. Host-side xterm/Playwright render self-test passes by rendering a minimal ANSI fixture through the repo xterm helper and launching Playwright Chromium or system Chrome to write a tiny PNG. If neither browser is available, run `npm install` and `npx playwright install chromium` before live suites.
 21. `CURSOR_API_KEY` is present.
 22. Artifact root is writable.
 23. `git status --short` is recorded.