pi-cursor-sdk 0.1.59 → 0.1.60

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.60 - 2026-07-17
+
+### Fixed
+
+- Contain the fatal raw `write EPIPE` uncaught exception the Cursor SDK's local shell executor can surface when a spawned child exits mid stdin write. Containment matches only the exact observed shape (code `EPIPE`, syscall `write`, stack exactly the single async pipe-write completion frame `WriteWrap.onWriteComplete`) and only while a local Cursor provider turn is active (from the turn's pre-send live-run drain through run completion, including the live-run wait window). A contained hit marks that turn's pooled/resumable local agent transport dead so the next acquire disposes it with a bounded wait and recreates it. EPIPE outside an active local turn — including idle pooled agents between turns — and the multi-frame synchronous write-path EPIPE from pi's own piped stdout or a dead terminal stay fatal. Known limit: an in-flight async pipe write anywhere in the process produces an identical shape, so one such EPIPE landing exactly during an active local turn is also contained; the next write to that pipe still dies normally.
+
 ## 0.1.59 - 2026-07-16
 
 ### Changed

package/README.md

@@ -438,7 +438,7 @@ When a Cursor run fails after auth is configured, pi now surfaces scrubbed provi
 
 Aborted runs now include a likely cause when determinable, for example `Cancelled: prompt interrupted.` for user cancel or `Cancelled: Cursor SDK run was cancelled.` for SDK-side cancellation.
 
-Network failures from the Cursor SDK connect layer (for example `ConnectError: read ETIMEDOUT` or `ConnectError: [aborted] read ECONNRESET`) surface as scrubbed `Network error` messages instead of crashing pi, matching pi's native auto-retry classifier. The exact Cursor SDK 1.0.23-provenance `WriteIterableClosedError: WritableIterable is closed` race is contained for the Pi session lifecycle because controlled-exec can reject after the originating provider turn; Connect/network/abort suppression remains active-turn scoped, and unrelated failures remain fatal. The affected run may still report its underlying transport or tool failure normally. Persistent failures may indicate a transient Cursor service or network issue.
+Network failures from the Cursor SDK connect layer (for example `ConnectError: read ETIMEDOUT` or `ConnectError: [aborted] read ECONNRESET`) surface as scrubbed `Network error` messages instead of crashing pi, matching pi's native auto-retry classifier. The exact Cursor SDK 1.0.23-provenance `WriteIterableClosedError: WritableIterable is closed` race is contained for the Pi session lifecycle because controlled-exec can reject after the originating provider turn; Connect/network/abort suppression remains active-turn scoped, and unrelated failures remain fatal. The observed raw `write EPIPE` uncaught exception (SDK 1.0.23 local shell executor writes child stdin without a stream error listener, so a child exiting mid-write surfaces a single-frame async pipe-write EPIPE) is contained only for that exact shape and only while a local Cursor provider turn is active; a contained closed pipe marks that turn's pooled/resumable agent transport dead so the next turn recreates it. EPIPE outside an active local turn, and the multi-frame synchronous write-path EPIPE from pi's own piped stdout or a dead terminal, stay fatal. The affected run may still report its underlying transport or tool failure normally. Persistent failures may indicate a transient Cursor service or network issue.
 
 You can also restart pi with a key in the same shell or launcher that starts pi:
 

package/docs/cursor-native-tool-replay.md

@@ -158,7 +158,7 @@ These are integration boundaries, not pi replay bugs:
 - **Live web-search ordering:** local Cursor WebSearch can be absent from live `onDelta`, `onStep`, and `run.stream()` tool events. When the only evidence is a post-run local transcript `webSearchToolCall`, pi can display the **Cursor web search** card only after `run.wait()` finishes. The extension intentionally keeps assistant text streaming instead of buffering the whole answer just to reorder that card.
 - **WebFetch availability:** `pi-cursor-sdk` can display a Cursor web fetch only after the SDK reports a `webFetchToolCall`, web-fetch-shaped MCP completion, or web-fetch host alias. It cannot make the Cursor SDK expose or execute WebFetch in a run where Cursor's tool set does not include it.
 - **Future SDK tools:** Cursor's official SDK docs say tool names, args, and result payloads can change. Unknown completed tools therefore fall back to neutral Cursor activity cards with bounded, scrubbed text. The extension cannot render tools that the SDK never emits.
-- **Process-level transport exceptions:** Connect/network/abort suppression remains scoped to active provider turns. The exact SDK-provenance `WriteIterableClosedError: WritableIterable is closed` is guarded for the Pi session lifecycle because SDK 1.0.23 controlled-exec can reject after its originating provider turn when it writes an error frame after output closes. Unrelated failures remain fatal; a materially different future SDK process error must be added only after observation.
+- **Process-level transport exceptions:** Connect/network/abort suppression remains scoped to active provider turns. The exact SDK-provenance `WriteIterableClosedError: WritableIterable is closed` is guarded for the Pi session lifecycle because SDK 1.0.23 controlled-exec can reject after its originating provider turn when it writes an error frame after output closes. The observed raw `write EPIPE` (SDK 1.0.23 local shell executor child stdin write with no stream error listener; stack exactly the single async `WriteWrap.onWriteComplete` frame, no SDK provenance) is guarded only while a local Cursor provider turn is active, and a contained closed pipe marks that turn's pooled/resumable agent transport dead for bounded disposal and recreation on the next acquire. Idle pooled agents do not suppress anything, and multi-frame synchronous write-path EPIPE (piped stdout, dead terminal) stays fatal. Unrelated failures remain fatal; a materially different future SDK process error must be added only after observation.
 
 Maintainer debug (`PI_CURSOR_SDK_EVENT_DEBUG=1`) still records the same discarded started-call events in `coordinator-events.jsonl` under phase `discarded-incomplete-started-tool-call` for investigation (**#52**), including fast local starts suppressed from successful text-producing runs. User-visible incomplete cards and debug artifacts are complementary: cards explain actionable gaps in the TUI; debug files retain normalized tool names and scrubbed call-id hashes without changing default stderr behavior.
 

package/docs/cursor-testing-lessons.md

@@ -412,7 +412,7 @@ npm run debug:sdk-events -- \
 
 Start with whether pi stayed alive:
 
-0. **pi process exited / shell returned with an uncaught SDK transport error** — examples include `ConnectError` with `ETIMEDOUT`/`ECONNRESET` and `WriteIterableClosedError: WritableIterable is closed`. Current code keeps Connect/network/abort suppression scoped to active provider turns. The exact SDK-provenance closed-writable shape is guarded for the Pi session lifecycle because `@cursor/sdk` 1.0.23 controlled-exec can reject after the originating provider turn when it attempts to write a `throw` frame after its internal output iterable has already closed; Bun requires an explicit rejection listener because it bypasses the patched `process.emit` path. Unrelated failures remain fatal. This proves the secondary process-killing write, not the earlier condition that first closed the SDK iterable. Treat a fresh process exit as a process-guard regression, capture the stack/session tail, and route it separately from #40 model text echo. If tools were mid-flight, note whether session JSONL ends abruptly and whether the final tool call lacks a result.
+0. **pi process exited / shell returned with an uncaught SDK transport error** — examples include `ConnectError` with `ETIMEDOUT`/`ECONNRESET` and `WriteIterableClosedError: WritableIterable is closed`. Current code keeps Connect/network/abort suppression scoped to active provider turns. The exact SDK-provenance closed-writable shape is guarded for the Pi session lifecycle because `@cursor/sdk` 1.0.23 controlled-exec can reject after the originating provider turn when it attempts to write a `throw` frame after its internal output iterable has already closed; Bun requires an explicit rejection listener because it bypasses the patched `process.emit` path. The observed raw `write EPIPE` uncaught exception (code `EPIPE`, syscall `write`, stack exactly the single async `WriteWrap.onWriteComplete` frame) from the SDK 1.0.23 local shell executor writing a spawned child's stdin without a stream error listener is guarded only while a local Cursor provider turn is active; containment marks that turn's pooled/resumable agent transport dead so the next acquire disposes it with a bounded wait and recreates it. Idle pooled agents do not suppress EPIPE, and the multi-frame synchronous write-path shape (piped stdout, dead terminal) stays fatal. The Windows sibling surfaces as `write EOF` and intentionally stays fatal because it does not match the observed Node EPIPE contract. Unrelated failures remain fatal. This proves the secondary process-killing write, not the earlier condition that first closed the SDK iterable. Treat a fresh process exit as a process-guard regression, capture the stack/session tail, and route it separately from #40 model text echo. If tools were mid-flight, note whether session JSONL ends abruptly and whether the final tool call lacks a result.
 
 Then inspect the failing assistant turn in `$SMOKE_DIR/session/*.jsonl`:
 
@@ -432,7 +432,7 @@ rg '"type": "toolCall"|Tool call \(Cursor|cursor-replay-' "$SMOKE_DIR/session"/*
 
 ### When to file follow-ups
 
-- **#43/#107** — pi exited from an uncaught Cursor SDK transport failure (hard crash, not a scrubbed #55 toast). Observed Connect/network/abort shapes remain guarded only during active provider turns; the exact SDK-provenance `WriteIterableClosedError` is guarded for the Pi session lifecycle because controlled-exec can reject after a turn. Unrelated failures remain fatal, and new exits need stack/session evidence.
+- **#43/#107** — pi exited from an uncaught Cursor SDK transport failure (hard crash, not a scrubbed #55 toast). Observed Connect/network/abort shapes remain guarded only during active provider turns; the exact local-turn `write EPIPE` shape is guarded only during active local Cursor provider turns and invalidates only that turn's local agent transport. The exact SDK-provenance `WriteIterableClosedError` is guarded for the Pi session lifecycle because controlled-exec can reject after a turn. Unrelated failures remain fatal, and new exits need stack/session evidence.
 - **#55** — caught SDK run failure or abort with missing/opaque detail (already addressed on main for surfacing).
 - **#52** — stale/inactive native replay routing after plan-strip or stale `context.tools` snapshot (`Tool * not found` in JSONL, `inactive_trace` in `display-decisions.jsonl`); or maintainer needs an explicit "started X, never completed" debug line when JSONL shows no completion and no model text echo.
 - **New issue** — bridge dispatch failure with `[pi-cursor-sdk:bridge]` evidence, or proven provider bug with JSONL showing missing `toolCall` despite SDK `tool-call-completed` in `on-delta.jsonl` from `debug:provider-events` or `debug:sdk-events` artifacts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cursor-sdk",
-  "version": "0.1.59",
+  "version": "0.1.60",
   "description": "pi provider extension backed by @cursor/sdk local and cloud agents",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",

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

@@ -1,6 +1,7 @@
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
-import { getCursorSessionCwd } from "./cursor-session-scope.js";
+import { invalidateSessionAgent } from "./cursor-session-agent.js";
+import { getCursorSessionCwd, getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
@@ -74,6 +75,14 @@ export class CursorProviderTurnRunner {
 			// prepare dispatch below always act on the same config snapshot.
 			const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
 			if (resolvedConfig.runtime.value === "local") {
+				// The observed local-executor closed-pipe EPIPE is contained only from this
+				// turn's pre-send live-run drain through run completion; for live runs the
+				// finalizer holds the guard until run.wait() settles. A hit marks
+				// this scope's pooled agent transport dead so the next acquire recreates it.
+				const localScopeKey = getCursorSessionScopeKey();
+				sdkProcessErrorGuard.containLocalTransportClosedPipe(() =>
+					invalidateSessionAgent(localScopeKey, { deadTransport: true }),
+				);
 				if (
 					(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
 					"stream_ended"

package/src/cursor-sdk-process-error-guard.ts

@@ -3,12 +3,14 @@ import { classifyCursorConnectError, isCursorSdkAbortConnectError } from "./curs
 
 interface CursorSdkProcessErrorGuardToken {
 	suppressAbortErrors: boolean;
+	onLocalTransportClosedPipe?: () => void;
 }
 
 interface CursorSdkSessionProcessErrorGuardToken {}
 
 export interface CursorSdkProcessErrorGuard {
 	suppressAbortErrors(): void;
+	containLocalTransportClosedPipe(onClosedPipe: () => void): void;
 	dispose(): void;
 }
 
@@ -52,9 +54,46 @@ function isCursorSdkWriteIterableClosedError(error: unknown): boolean {
 	);
 }
 
+// The exact observed incident: the Cursor SDK 1.0.23 local shell executor writes a
+// spawned child's stdin without a stream 'error' listener, so a child exiting while
+// a write is in flight surfaces a raw `write EPIPE` uncaught exception whose stack
+// is exactly the single async pipe-write completion frame. Pi's own piped-stdout or
+// dead-terminal EPIPE normally surfaces through the synchronous write-dispatch path
+// with multiple frames (afterWriteDispatched/Socket._writeGeneric) and must stay
+// fatal per Unix convention, so anything beyond this one-frame contract is rejected.
+const OBSERVED_CLOSED_PIPE_STACK_FRAME =
+	/^\s+at WriteWrap\.onWriteComplete \[as oncomplete\] \(node:internal\/stream_base_commons:\d+:\d+\)$/;
+
+function isObservedLocalTransportClosedPipeWriteError(error: unknown): boolean {
+	if (!(error instanceof Error) || error.name !== "Error") return false;
+	const { code, syscall } = error as NodeJS.ErrnoException;
+	if (code !== "EPIPE" || syscall !== "write" || !error.message.startsWith("write EPIPE")) return false;
+	const frames = (error.stack ?? "").split("\n").filter((line) => /^\s+at /.test(line));
+	return frames.length === 1 && OBSERVED_CLOSED_PIPE_STACK_FRAME.test(frames[0] ?? "");
+}
+
+// Contained only while a provider turn that declared a local transport is active;
+// each contained turn invalidates its own session-agent scope for recreation.
+function containLocalTransportClosedPipeError(): boolean {
+	let contained = false;
+	for (const turn of [...activeProviderTurns]) {
+		if (!turn.onLocalTransportClosedPipe) continue;
+		contained = true;
+		try {
+			turn.onLocalTransportClosedPipe();
+		} catch {
+			// stale-agent invalidation must not throw inside process error handling
+		}
+	}
+	return contained;
+}
+
 function shouldSuppressProcessError(event: string | symbol, args: readonly unknown[]): boolean {
 	if (event !== "uncaughtException" && event !== "unhandledRejection") return false;
 	const error = args[0];
+	if (isObservedLocalTransportClosedPipeWriteError(error)) {
+		return containLocalTransportClosedPipeError();
+	}
 	if (isCursorSdkWriteIterableClosedError(error)) return activeSessions.size > 0;
 	const classification = classifyCursorConnectError(error);
 	if (!classification) return false;
@@ -137,6 +176,10 @@ export function installCursorSdkProcessErrorGuard(): CursorSdkProcessErrorGuard
 			if (disposed) return;
 			token.suppressAbortErrors = true;
 		},
+		containLocalTransportClosedPipe(onClosedPipe: () => void): void {
+			if (disposed) return;
+			token.onLocalTransportClosedPipe = onClosedPipe;
+		},
 		dispose(): void {
 			if (disposed) return;
 			disposed = true;

package/src/cursor-session-agent.ts

@@ -126,6 +126,8 @@ interface SessionCursorAgentCreateParams {
 
 const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
 const invalidatedScopeKeys = new Set<string>();
+const deadTransportScopeKeys = new Set<string>();
+let deadTransportAgentDisposeTimeoutMs = 3000;
 const terminalDisposedScopeGenerations = new Map<string, number>();
 const scopeCreationGenerations = new Map<string, number>();
 const EMPTY_POOL_STATE: SessionCursorAgentPoolState = { status: "empty" };
@@ -206,7 +208,7 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 	].join("\0");
 }
 
-async function disposePoolEntry(entry: SessionCursorAgentPoolEntry): Promise<void> {
+async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: { deadTransport?: boolean }): Promise<void> {
 	if (!isActivePoolEntry(entry)) return;
 	entry.bridgeRun?.cancel("Cursor session agent disposed");
 	try {
@@ -215,7 +217,15 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry): Promise<voi
 		// disposal failure should not block session replacement
 	}
 	try {
-		await entry.agent[Symbol.asyncDispose]();
+		const disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]()).catch(() => undefined);
+		// A dead local transport may never settle SDK disposal; bound the wait so the
+		// next acquire recreates instead of hanging on the dead agent.
+		await (options?.deadTransport
+			? Promise.race([
+					disposal,
+					new Promise<void>((resolve) => setTimeout(resolve, deadTransportAgentDisposeTimeoutMs).unref?.()),
+				])
+			: disposal);
 	} catch {
 		// disposal failure should not block session replacement
 	}
@@ -228,6 +238,7 @@ async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?:
 	}
 	const entry = sessionAgentsByScope.get(scopeKey);
 	invalidatedScopeKeys.delete(scopeKey);
+	const deadTransport = deadTransportScopeKeys.delete(scopeKey);
 	if (!entry) return;
 	sessionAgentsByScope.delete(scopeKey);
 	if (entry.status === "busy") {
@@ -239,7 +250,7 @@ async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?:
 		});
 		return;
 	}
-	await disposePoolEntry(entry);
+	await disposePoolEntry(entry, { deadTransport });
 }
 
 function createInitialSendState(): SessionCursorAgentSendState {
@@ -489,8 +500,12 @@ export {
 	type CursorSessionSendPlan,
 } from "./cursor-session-send-policy.js";
 
-export function invalidateSessionAgent(scopeKey: string = getCursorSessionScopeKey()): void {
+export function invalidateSessionAgent(
+	scopeKey: string = getCursorSessionScopeKey(),
+	options?: { deadTransport?: boolean },
+): void {
 	invalidatedScopeKeys.add(scopeKey);
+	if (options?.deadTransport) deadTransportScopeKeys.add(scopeKey);
 }
 
 export async function acquireSessionCursorAgent(params: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
@@ -611,6 +626,7 @@ export async function disposeAllSessionCursorAgents(): Promise<void> {
 	const scopeKeys = [...new Set([...sessionAgentsByScope.keys(), ...terminalDisposedScopeGenerations.keys()])];
 	await Promise.all(scopeKeys.map((scopeKey) => disposePoolEntryForScope(scopeKey, { terminal: true })));
 	invalidatedScopeKeys.clear();
+	deadTransportScopeKeys.clear();
 	terminalDisposedScopeGenerations.clear();
 }
 
@@ -624,6 +640,11 @@ export const __testUtils = {
 	disposeAllSessionCursorAgents,
 	buildApiKeyPoolKeyFingerprint,
 	buildSessionAgentPoolKey,
+	setDeadTransportAgentDisposeTimeoutMs(ms: number): number {
+		const previous = deadTransportAgentDisposeTimeoutMs;
+		deadTransportAgentDisposeTimeoutMs = ms;
+		return previous;
+	},
 	SessionCursorAgentCreationSupersededError,
 	SessionCursorAgentScopeClosedError,
 };