@emmaneugene/pi-cursor-sdk 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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/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

@@ -49,6 +49,11 @@ Get-CimInstance Win32_Process -Filter "Name = 'bash.exe' OR Name = 'sh.exe'" |
     });
 }
 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);

package/dist/index.js

@@ -15,6 +15,7 @@ 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";
+import { claimCursorExtensionFactory, registerCursorExtensionFactoryRelease, releaseCursorExtensionFactory, } from "./cursor-extension-factory-guard.js";
 function createCursorProviderConfig(models) {
     return {
         name: "Cursor",
@@ -29,54 +30,69 @@ function registerCursorProvider(pi, models) {
     pi.registerProvider("cursor", createCursorProviderConfig(models));
 }
 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();
-    });
-    registerCursorRuntimeControls(pi);
-    registerCursorNativeToolDisplay(pi);
-    registerCursorQuestionTool(pi);
-    registerCursorSkillTool(pi);
-    registerCursorPiToolBridge(pi);
-    registerCursorAgentsContextDedup(pi);
-    registerCursorOverflowNormalization(pi);
-    let fallbackIssue;
-    const models = await discoverModels({
-        onFallback: (issue) => {
-            fallbackIssue = issue;
-        },
-    });
-    if (fallbackIssue) {
-        registerCursorFallbackIssueWarning(pi, fallbackIssue);
+    const factoryClaim = claimCursorExtensionFactory();
+    if (factoryClaim.kind === "nested")
+        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;
+            },
+        });
+        // 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 is also process-global: the first load owns the bridge, session scope, and pooled SDK agent. A nested child `createAgentSession` load is ignored until that owner session shuts down, so a live parent `pi__subagent` MCP run is not disposed as an extension reload. 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,21 @@ 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 observed failure: the child dies at `0 tool uses` with no transcript file, the parent turn aborts with `This operation was aborted`, and bridge diagnostics show `request_rejected` / `cancelled` with `Cursor pi tool bridge extension reloaded`.
+
+Regression coverage:
+
+- `src/cursor-extension-factory-guard.ts` — the first factory owns the process; nested loads no-op until the owner session shuts down and Pi can create its replacement runtime
+- `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 factory does not re-register, does not steal session scope, and does not dispose a live parent MCP run
+- `test/cursor-pi-tool-bridge.test.ts` — `registerCursorPiToolBridge` keeps the existing registry when a run is live
+
+If the host resolves a Cursor model for a child, that child uses the process-global Cursor agent pool. This guard stops the parent teardown; it does not give the child an independent Cursor session agent. Cursor-child model selection remains a separate live-test requirement.
+
 ## 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.

package/node_modules/cross-spawn/node_modules/which/CHANGELOG.md

@@ -0,0 +1,166 @@
+# Changes
+
+
+## 2.0.2
+
+* Rename bin to `node-which`
+
+## 2.0.1
+
+* generate changelog and publish on version bump
+* enforce 100% test coverage
+* Promise interface
+
+## 2.0.0
+
+* Parallel tests, modern JavaScript, and drop support for node < 8
+
+## 1.3.1
+
+* update deps
+* update travis
+
+## v1.3.0
+
+* Add nothrow option to which.sync
+* update tap
+
+## v1.2.14
+
+* appveyor: drop node 5 and 0.x
+* travis-ci: add node 6, drop 0.x
+
+## v1.2.13
+
+* test: Pass missing option to pass on windows
+* update tap
+* update isexe to 2.0.0
+* neveragain.tech pledge request
+
+## v1.2.12
+
+* Removed unused require
+
+## v1.2.11
+
+* Prevent changelog script from being included in package
+
+## v1.2.10
+
+* Use env.PATH only, not env.Path
+
+## v1.2.9
+
+* fix for paths starting with ../
+* Remove unused `is-absolute` module
+
+## v1.2.8
+
+* bullet items in changelog that contain (but don't start with) #
+
+## v1.2.7
+
+* strip 'update changelog' changelog entries out of changelog
+
+## v1.2.6
+
+* make the changelog bulleted
+
+## v1.2.5
+
+* make a changelog, and keep it up to date
+* don't include tests in package
+* Properly handle relative-path executables
+* appveyor
+* Attach error code to Not Found error
+* Make tests pass on Windows
+
+## v1.2.4
+
+* Fix typo
+
+## v1.2.3
+
+* update isexe, fix regression in pathExt handling
+
+## v1.2.2
+
+* update deps, use isexe module, test windows
+
+## v1.2.1
+
+* Sometimes windows PATH entries are quoted
+* Fixed a bug in the check for group and user mode bits. This bug was introduced during refactoring for supporting strict mode.
+* doc cli
+
+## v1.2.0
+
+* Add support for opt.all and -as cli flags
+* test the bin
+* update travis
+* Allow checking for multiple programs in bin/which
+* tap 2
+
+## v1.1.2
+
+* travis
+* Refactored and fixed undefined error on Windows
+* Support strict mode
+
+## v1.1.1
+
+* test +g exes against secondary groups, if available
+* Use windows exe semantics on cygwin & msys
+* cwd should be first in path on win32, not last
+* Handle lower-case 'env.Path' on Windows
+* Update docs
+* use single-quotes
+
+## v1.1.0
+
+* Add tests, depend on is-absolute
+
+## v1.0.9
+
+* which.js: root is allowed to execute files owned by anyone
+
+## v1.0.8
+
+* don't use graceful-fs
+
+## v1.0.7
+
+* add license to package.json
+
+## v1.0.6
+
+* isc license
+
+## 1.0.5
+
+* Awful typo
+
+## 1.0.4
+
+* Test for path absoluteness properly
+* win: Allow '' as a pathext if cmd has a . in it
+
+## 1.0.3
+
+* Remove references to execPath
+* Make `which.sync()` work on Windows by honoring the PATHEXT variable.
+* Make `isExe()` always return true on Windows.
+* MIT
+
+## 1.0.2
+
+* Only files can be exes
+
+## 1.0.1
+
+* Respect the PATHEXT env for win32 support
+* should 0755 the bin
+* binary
+* guts
+* package
+* 1st

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emmaneugene/pi-cursor-sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "pi provider extension backed by @cursor/sdk local agents",
   "publishConfig": {
     "access": "public"

package/scripts/lib/cursor-visual-render.mjs

@@ -112,7 +112,17 @@ export async function writeTerminalScreenshot(htmlPath, pngPath, width, height)
 	let browser;
 	try {
 		const { chromium } = await import("playwright");
-		browser = await chromium.launch();
+		try {
+			browser = await chromium.launch();
+		} catch (bundledBrowserError) {
+			try {
+				browser = await chromium.launch({ channel: "chrome" });
+			} catch (systemBrowserError) {
+				const bundledMessage = bundledBrowserError instanceof Error ? bundledBrowserError.message : String(bundledBrowserError);
+				const systemMessage = systemBrowserError instanceof Error ? systemBrowserError.message : String(systemBrowserError);
+				throw new Error(`bundled Chromium: ${bundledMessage}\nsystem Chrome: ${systemMessage}`);
+			}
+		}
 		const page = await browser.newPage({
 			viewport: {
 				width: Math.max(1_200, width * 10),
@@ -125,7 +135,7 @@ export async function writeTerminalScreenshot(htmlPath, pngPath, width, height)
 		await page.locator("#terminal").screenshot({ path: pngPath });
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`failed to capture PNG with Playwright: ${message}\nInstall Chromium with: npx playwright install chromium\nOr rerun with --no-screenshot and capture ${htmlPath} with agent_browser.`);
+		throw new Error(`failed to capture PNG with Playwright: ${message}\nInstall system Chrome or Chromium with: npx playwright install chromium\nOr rerun with --no-screenshot and capture ${htmlPath} with agent_browser.`);
 	} finally {
 		if (browser) await browser.close();
 	}

package/scripts/visual-tui-smoke-self-test.mjs

@@ -24,7 +24,7 @@ function parseEnvCapture(path) {
 }
 
 export function runVisualSmokeSelfTest(deps) {
-	const { ROOT, DEFAULT_MODE, DEFAULT_MODEL, DEFAULT_SETTING_SOURCES, DEBUG_ENV_NAMES, shellQuote, parseArgs, snapshotJsonlMtimes, findLatestJsonl, sealedNodePath, resolveCommand, requireNode, requireCommand, buildLaunchPlan, run, runVisualSmoke } = deps;
+	const { ROOT, DEFAULT_MODE, DEFAULT_MODEL, DEFAULT_SETTING_SOURCES, DEBUG_ENV_NAMES, shellQuote, parseArgs, snapshotJsonlMtimes, findLatestJsonl, jsonlContainsUserPrompt, waitForCursorTui, sealedNodePath, resolveCommand, requireNode, requireCommand, buildLaunchPlan, run, runVisualSmoke } = deps;
 	const tempDir = mkdtempSync(join(tmpdir(), "pi-cursor-sdk-visual-self-test-"));
 	try {
 		const binDir = join(tempDir, "bin");
@@ -59,6 +59,9 @@ export function runVisualSmokeSelfTest(deps) {
 		utimesSync(freshJsonl, new Date(3_000), new Date(3_000));
 		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 2_000, previousMtimes: previousJsonlMtimes }) === freshJsonl, "JSONL discovery should ignore unchanged stale files before run start");
 		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 4_000, previousMtimes: snapshotJsonlMtimes(jsonlDir) }) === undefined, "JSONL discovery should not return stale evidence when current run has no changed JSONL");
+		writeFileSync(freshJsonl, `${JSON.stringify({ type: "message", message: { role: "user", content: "submitted prompt" } })}\n`, "utf8");
+		assertSelfTest(jsonlContainsUserPrompt(freshJsonl, "submitted prompt"), "JSONL prompt check should find the submitted user message");
+		assertSelfTest(!jsonlContainsUserPrompt(freshJsonl, "different prompt"), "JSONL prompt check should reject a different user message");
 
 		assertSelfTest(!sealedNodePath(process.execPath, "").includes(delimiter), "empty inherited PATH must not leave an empty PATH segment");
 		const hostilePath = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
@@ -73,6 +76,7 @@ export function runVisualSmokeSelfTest(deps) {
 			cwd: ROOT,
 			mode: DEFAULT_MODE,
 			model: DEFAULT_MODEL,
+			prompt: "self-test prompt",
 			outDir: tempDir,
 			safeLabel: "self-test",
 			sessionDir: join(tempDir, "session"),
@@ -96,6 +100,7 @@ export function runVisualSmokeSelfTest(deps) {
 			assertSelfTest(plan.clearEnvNames.includes(name), `${name} must be cleared by default`);
 		}
 		assertSelfTest(plan.script.includes(shellQuote(fakePi)), "launch script must use resolved pi path");
+		assertSelfTest(!plan.script.includes(baseOptions.prompt), "launch script must keep the prompt out of the process command line");
 		assertSelfTest(!plan.script.includes(" exec pi "), "launch script must not use bare pi");
 		const hostileEnv = {
 			...process.env,
@@ -144,48 +149,18 @@ export function runVisualSmokeSelfTest(deps) {
 		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_STDERR"), "stale event debug stderr flag should be cleared");
 
 		const fakeTmux = join(binDir, "tmux");
-		const deleteBufferMarker = join(tempDir, "delete-buffer-called");
-		writeFileSync(
-			fakeTmux,
-			`#!/bin/sh\ncase "$1" in\n  -V) echo 'tmux fake'; exit 0 ;;\n  new-session) exit 0 ;;\n  load-buffer) cat >/dev/null; exit 0 ;;\n  paste-buffer) exit 77 ;;\n  delete-buffer) echo deleted > ${shellQuote(deleteBufferMarker)}; exit 0 ;;\n  kill-session) exit 0 ;;\n  *) echo "unexpected tmux command: $*" >&2; exit 64 ;;\nesac\n`,
-			"utf8",
-		);
-		chmodSync(fakeTmux, 0o755);
-		const originalPath = process.env.PATH;
-		try {
-			process.env.PATH = hostilePath;
-			let pasteFailed = false;
-			try {
-				runVisualSmoke({
-					...baseOptions,
-					prompt: "buffer cleanup prompt",
-					startupMs: 1,
-					waitMs: 1,
-					width: 80,
-					height: 24,
-					historyLines: 100,
-				});
-			} catch (error) {
-				pasteFailed = /paste-buffer failed/.test(error instanceof Error ? error.message : String(error));
-			}
-			assertSelfTest(pasteFailed, "fake tmux paste failure should exercise prompt-buffer cleanup path");
-			assertSelfTest(existsSync(deleteBufferMarker), "prompt tmux buffer should be deleted when paste/send fails");
-		} finally {
-			if (originalPath === undefined) delete process.env.PATH;
-			else process.env.PATH = originalPath;
-		}
-
 		writeFileSync(
 			fakeTmux,
 			`#!/bin/sh
 case "$1" in
   -V) echo 'tmux fake'; exit 0 ;;
   new-session) exit 0 ;;
+  set-option) exit 0 ;;
   load-buffer) cat >/dev/null; exit 0 ;;
   paste-buffer) exit 0 ;;
   send-keys) exit 0 ;;
   delete-buffer) exit 0 ;;
-  capture-pane) echo 'captured visual smoke output'; exit 0 ;;
+  capture-pane) printf 'captured visual smoke output\ncursor · fast:off\n'; exit 0 ;;
   kill-session) exit 0 ;;
   *) echo "unexpected tmux command: $*" >&2; exit 64 ;;
 esac
@@ -194,6 +169,7 @@ esac
 		);
 		chmodSync(fakeTmux, 0o755);
 		const noJsonlManifest = join(tempDir, "self-test-jsonl-missing.manifest.json");
+		const originalPath = process.env.PATH;
 		try {
 			process.env.PATH = hostilePath;
 			let missingJsonlFailed = false;

package/scripts/visual-tui-smoke.mjs

@@ -14,7 +14,7 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DEFAULT_WIDTH = 150;
 const DEFAULT_HEIGHT = 45;
 const DEFAULT_WAIT_MS = 60_000;
-const DEFAULT_STARTUP_MS = 5_000;
+const DEFAULT_STARTUP_MS = 15_000;
 const DEFAULT_HISTORY_LINES = 3_000;
 const DEFAULT_MODEL = "cursor/grok-4.6";
 const DEFAULT_MODE = "plan";
@@ -33,15 +33,15 @@ Usage:
 
 Required:
   --label LABEL                 Artifact filename prefix. Sanitized for paths.
-  --prompt PROMPT               Prompt to paste into the interactive pi TUI.
+  --prompt PROMPT               Prompt to submit in the interactive pi TUI.
                                 Use --prompt-file PATH for multi-line prompts.
 
 Common options:
   --ext PATH                    Extension repo to load with pi -e. Default: repo root.
   --cwd PATH                    Working directory for the pi session. Default: current directory.
   --out-dir PATH                Artifact directory. Default: /tmp/pi-cursor-sdk-visual-smoke-<timestamp>.
-  --wait-ms N                   Milliseconds to wait after sending the prompt. Default: ${DEFAULT_WAIT_MS}.
-  --startup-ms N                Milliseconds to wait before pasting the prompt. Default: ${DEFAULT_STARTUP_MS}.
+  --wait-ms N                   Milliseconds to wait for the response before capture. Default: ${DEFAULT_WAIT_MS}.
+  --startup-ms N                Maximum milliseconds to wait for TUI readiness. Default: ${DEFAULT_STARTUP_MS}.
   --model MODEL                 Cursor model. Default: ${DEFAULT_MODEL}.
   --mode agent|plan             Cursor SDK mode. Default: ${DEFAULT_MODE}.
   --session-dir PATH            pi session directory. Default: <out-dir>/<label>.session.
@@ -82,8 +82,8 @@ Artifacts written:
 Prerequisites:
   - pi, node, tmux, and npm-installed dev dependencies on PATH / in node_modules.
   - The runner resolves pi/tmux from the parent PATH, uses process.execPath for node, and seals pi-shim PATH for prereq checks and tmux.
-  - For automatic PNG capture, install a Playwright browser once when needed:
-      npx playwright install chromium
+  - Automatic PNG capture uses Playwright's Chromium or a system Chrome installation.
+    If neither is available, install Chromium once: npx playwright install chromium
   - In the pi agent harness, --no-screenshot plus agent_browser on the generated HTML is also acceptable.
 
 Examples:
@@ -340,6 +340,41 @@ function findLatestJsonl(root, { sinceMs = 0, previousMtimes = new Map() } = {})
 	return matches[0]?.path;
 }
 
+function jsonlContainsUserPrompt(path, prompt) {
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		if (!line.trim()) continue;
+		let entry;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (entry?.type !== "message" || entry.message?.role !== "user") continue;
+		const content = entry.message.content;
+		const text = typeof content === "string"
+			? content
+			: Array.isArray(content)
+				? content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("")
+				: "";
+		if (text === prompt) return true;
+	}
+	return false;
+}
+
+function waitForCursorTui(commands, sessionName, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	do {
+		try {
+			const pane = capturePane(commands.tmux, sessionName, ["-p", "-S", "-100"]);
+			if (pane.includes("cursor ·")) return;
+		} catch {
+			// The pane can be unavailable briefly while tmux starts the shell.
+		}
+		sleep(100);
+	} while (Date.now() < deadline);
+	throw new Error(`Cursor TUI did not become ready within ${timeoutMs}ms`);
+}
+
 function checkLeftovers(patterns) {
 	if (patterns.length === 0) return;
 	const result = run("ps", ["-axo", "pid,etime,command"]);
@@ -465,18 +500,19 @@ function runVisualSmoke(options) {
 		]);
 		if (start.status !== 0) throw new Error(`tmux new-session failed: ${start.stderr?.toString().trim() || start.status}`);
 		sessionStarted = true;
+		const remainOnExit = run(commands.tmux, ["set-option", "-t", sessionName, "remain-on-exit", "on"]);
+		if (remainOnExit.status !== 0) throw new Error(`tmux remain-on-exit setup failed: ${remainOnExit.stderr?.toString().trim() || remainOnExit.status}`);
 
-		sleep(options.startupMs);
+		waitForCursorTui(commands, sessionName, options.startupMs);
 		const load = run(commands.tmux, ["load-buffer", "-b", bufferName, "-"], { input: Buffer.from(options.prompt, "utf8") });
 		if (load.status !== 0) throw new Error(`tmux load-buffer failed: ${load.stderr?.toString().trim() || load.status}`);
 		bufferLoaded = true;
 		try {
-			const paste = run(commands.tmux, ["paste-buffer", "-b", bufferName, "-t", sessionName]);
+			const paste = run(commands.tmux, ["paste-buffer", "-p", "-S", "-b", bufferName, "-t", sessionName]);
 			if (paste.status !== 0) throw new Error(`tmux paste-buffer failed: ${paste.stderr?.toString().trim() || paste.status}`);
-			// Give bracketed paste handling a moment to finish before submitting.
 			sleep(250);
-			const enter = run(commands.tmux, ["send-keys", "-t", sessionName, "Enter"]);
-			if (enter.status !== 0) throw new Error(`tmux send-keys failed: ${enter.stderr?.toString().trim() || enter.status}`);
+			const submit = run(commands.tmux, ["send-keys", "-t", sessionName, "-H", "0d"]);
+			if (submit.status !== 0) throw new Error(`tmux prompt submit failed: ${submit.stderr?.toString().trim() || submit.status}`);
 		} finally {
 			run(commands.tmux, ["delete-buffer", "-b", bufferName]);
 			bufferLoaded = false;
@@ -507,6 +543,11 @@ function runVisualSmoke(options) {
 			writeVisualManifest(manifestPath, options, partialArtifacts, { message, writtenAt: new Date().toISOString() });
 			throw new Error(message);
 		}
+		if (!jsonlContainsUserPrompt(jsonlPath, options.prompt)) {
+			const message = "current-run JSONL does not contain the submitted prompt";
+			writeVisualManifest(manifestPath, options, { ...partialArtifacts, jsonlPath }, { message, writtenAt: new Date().toISOString() });
+			throw new Error(message);
+		}
 		writeUtf8(jsonlPathFile, `${jsonlPath}\n`);
 
 		return { ...partialArtifacts, jsonlPath };
@@ -531,6 +572,8 @@ try {
 			parseArgs,
 			snapshotJsonlMtimes,
 			findLatestJsonl,
+			jsonlContainsUserPrompt,
+			waitForCursorTui,
 			sealedNodePath,
 			resolveCommand,
 			requireNode,

package/src/cursor-extension-factory-guard.ts

@@ -0,0 +1,57 @@
+import type { ExtensionHandler, SessionShutdownEvent } from "@earendil-works/pi-coding-agent";
+
+/**
+ * First factory invocation in this process owns Cursor's process-global
+ * registrars (bridge, session scope, pooled SDK agent). Pi child sessions call
+ * `createAgentSession` + `bindExtensions` in the same process, which re-invokes
+ * this factory against a new ExtensionAPI while the parent Cursor run is still
+ * live. A nested factory must not re-register.
+ *
+ * Ownership ends after the owner's shutdown handlers finish. Pi then reloads
+ * the extension for `new`, `resume`, `fork`, and explicit reload operations.
+ */
+export type CursorExtensionFactoryClaim =
+	| { kind: "owner"; token: symbol }
+	| { kind: "nested" };
+
+export interface CursorExtensionFactoryGuardApi {
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+}
+
+let factoryOwnerToken: symbol | undefined;
+
+export function claimCursorExtensionFactory(): CursorExtensionFactoryClaim {
+	if (factoryOwnerToken) return { kind: "nested" };
+	const token = Symbol("cursor-extension-factory-owner");
+	factoryOwnerToken = token;
+	return { kind: "owner", token };
+}
+
+export function releaseCursorExtensionFactory(token: symbol): void {
+	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: CursorExtensionFactoryGuardApi,
+	claim: Extract<CursorExtensionFactoryClaim, { kind: "owner" }>,
+): void {
+	pi.on("session_shutdown", () => {
+		releaseCursorExtensionFactory(claim.token);
+	});
+}
+
+export const __testUtils = {
+	isInstalled(): boolean {
+		return factoryOwnerToken !== undefined;
+	},
+	reset(): void {
+		factoryOwnerToken = undefined;
+	},
+};

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

@@ -64,6 +64,10 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 		return run;
 	}
 
+	hasLiveRuns(): boolean {
+		return this.runs.size > 0;
+	}
+
 	async disposeAll(reason = "Cursor pi tool bridge disposed"): Promise<void> {
 		await Promise.all([...this.runs].map(async (run) => {
 			run.cancel(reason);

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

@@ -89,6 +89,11 @@ Get-CimInstance Win32_Process -Filter "Name = 'bash.exe' OR Name = 'sh.exe'" |
 }
 
 export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi): CursorPiToolBridge {
+	// 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);

package/src/index.ts

@@ -16,6 +16,11 @@ 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";
+import {
+	claimCursorExtensionFactory,
+	registerCursorExtensionFactoryRelease,
+	releaseCursorExtensionFactory,
+} from "./cursor-extension-factory-guard.js";
 
 type CursorExtensionApi =
 	& Pick<ExtensionAPI, "registerProvider" | "registerCommand" | "on">
@@ -31,7 +36,8 @@ type CursorExtensionApi =
 	& Parameters<typeof registerCursorFallbackIssueWarning>[0]
 	& Parameters<typeof registerCursorAgentsContextDedup>[0]
 	& Parameters<typeof registerCursorOverflowNormalization>[0]
-	& Parameters<typeof registerCursorSdkSessionProcessErrorGuard>[0];
+	& Parameters<typeof registerCursorSdkSessionProcessErrorGuard>[0]
+	& Parameters<typeof registerCursorExtensionFactoryRelease>[0];
 
 function createCursorProviderConfig(models: ProviderModelConfig[]): ProviderConfig {
 	return {
@@ -49,55 +55,70 @@ function registerCursorProvider(pi: Pick<ExtensionAPI, "registerProvider">, mode
 }
 
 export default async function (pi: CursorExtensionApi) {
-	// 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);
-	let fallbackIssue: CursorModelFallbackIssue | undefined;
-	const models = await discoverModels({
-		onFallback: (issue) => {
-			fallbackIssue = issue;
-		},
-	});
+	const factoryClaim = claimCursorExtensionFactory();
+	if (factoryClaim.kind === "nested") return;
 
-	if (fallbackIssue) {
-		registerCursorFallbackIssueWarning(pi, fallbackIssue);
-	}
+	try {
+		// Discover first. A discovery failure must not leave process-global
+		// registrars from a discarded extension load.
+		let fallbackIssue: CursorModelFallbackIssue | undefined;
+		const models = await discoverModels({
+			onFallback: (issue) => {
+				fallbackIssue = issue;
+			},
+		});
+
+		// 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);
 
-	pi.registerCommand("cursor-refresh-models", {
-		description: "Refresh the live Cursor model catalog without restarting pi",
-		handler: async (_args, ctx) => {
-			let refreshFallbackIssue: CursorModelFallbackIssue | undefined;
-			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");
-			}
-		},
-	});
+		if (fallbackIssue) {
+			registerCursorFallbackIssueWarning(pi, fallbackIssue);
+		}
 
-	registerCursorProvider(pi, models);
-	// Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
-	registerCursorSdkSessionProcessErrorGuard(pi);
+		pi.registerCommand("cursor-refresh-models", {
+			description: "Refresh the live Cursor model catalog without restarting pi",
+			handler: async (_args, ctx) => {
+				let refreshFallbackIssue: CursorModelFallbackIssue | undefined;
+				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;
+	}
 }