pi-cursor-sdk 0.5.0 → 0.5.2

package/src/cursor-session-store.ts

@@ -1,9 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
 import { rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { dirname, join, toNamespacedPath } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep, toNamespacedPath } from "node:path";
 import type { LocalAgentStore } from "@cursor/sdk";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { guardCursorCustomStorePath, normalizeCursorCustomStoreRoot, prepareCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 
 export interface CursorSessionStoreIdentity {
 	readonly version: 1;
@@ -16,15 +18,32 @@ export interface OpenCursorSessionStore {
 	dispose(): Promise<void>;
 }
 
-export interface CursorSessionStoreSelection {
+type CursorPersistentStoreIdentities = {
+	workspaceRoot: string;
+	sessionStore: CursorSessionStoreIdentity;
+} & ({
+	domain: "default";
+	defaultStore: CursorSessionStoreIdentity;
+	storeRoot?: never;
+} | {
+	domain: "custom";
+	storeRoot: string;
+	defaultStore?: never;
+});
+
+export type CursorSessionStoreSelection = {
 	sessionStore: OpenCursorSessionStore;
-	identities: {
-		defaultStore: CursorSessionStoreIdentity;
-		sessionStore: CursorSessionStoreIdentity;
-	};
+} & ({
+	persistent: true;
+	identities: CursorPersistentStoreIdentities;
 	resumeAttemptAllowed: boolean;
 	resumeFallback: boolean;
-}
+} | {
+	persistent: false;
+	identities: { sessionStore: CursorSessionStoreIdentity };
+	resumeAttemptAllowed: false;
+	resumeFallback: false;
+});
 
 interface CursorSessionStoreSdkOperations {
 	getDefaultStateRoot(cwd: string): string | Promise<string>;
@@ -32,6 +51,9 @@ interface CursorSessionStoreSdkOperations {
 }
 
 let sdkOperationsForTests: CursorSessionStoreSdkOperations | undefined;
+const activeWorkspaceRoots = new Map<string, { root: Promise<string>; users: number }>();
+// ponytail: leases protect only extension-owned stores in this process. Other SDK
+// users/processes must stop before upgrade; a cross-process lock belongs in the SDK.
 
 export function hashCursorSessionStoreScope(scopeKey: string): string {
 	return createHash("sha256")
@@ -41,9 +63,8 @@ export function hashCursorSessionStoreScope(scopeKey: string): string {
 		.slice(0, 32);
 }
 
-export function buildCursorSessionStateRoot(defaultStateRoot: string, scopeKey: string, persistent: boolean): string {
-	const baseRoot = persistent ? defaultStateRoot : join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
-	return join(baseRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
+export function buildCursorSessionStateRoot(defaultStateRoot: string, scopeKey: string): string {
+	return join(defaultStateRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
 }
 
 async function getSdkOperations(): Promise<CursorSessionStoreSdkOperations> {
@@ -58,21 +79,81 @@ async function getSdkOperations(): Promise<CursorSessionStoreSdkOperations> {
 	};
 }
 
-export async function getCursorSessionStoreIdentities(
-	cwd: string,
-	scopeKey: string,
-	persistent: boolean,
-): Promise<{ defaultStore: CursorSessionStoreIdentity; sessionStore: CursorSessionStoreIdentity }> {
-	const defaultStateRoot = await (await getSdkOperations()).getDefaultStateRoot(cwd);
+function leaseWorkspaceRoot(key: string, ownership: { root: Promise<string>; users: number }) {
+	ownership.users++;
+	let released = false;
 	return {
-		defaultStore: { version: 1, stateRoot: defaultStateRoot },
-		sessionStore: {
-			version: 1,
-			stateRoot: buildCursorSessionStateRoot(defaultStateRoot, scopeKey, persistent),
+		root: ownership.root,
+		release: () => {
+			if (released) return;
+			released = true;
+			if (--ownership.users === 0) activeWorkspaceRoots.delete(key);
 		},
 	};
 }
 
+function workspaceLeaseKey(cwd: string, storeRoot: string | undefined): string {
+	return JSON.stringify([cwd, storeRoot ?? null]);
+}
+
+function acquireWorkspaceRoot(cwd: string, storeRoot: string | undefined) {
+	const key = workspaceLeaseKey(cwd, storeRoot);
+	let ownership = activeWorkspaceRoots.get(key);
+	if (!ownership) {
+		ownership = {
+			// Publish ownership synchronously, before SDK loading or the public getter.
+			root: Promise.resolve().then(async () => {
+				if (storeRoot !== undefined) {
+					const root = prepareCursorCustomStoreRoot(storeRoot);
+					return join(root, createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 32));
+				}
+				const operations = await getSdkOperations();
+				assertSafeWorkspaceLayout(cwd);
+				const root = await operations.getDefaultStateRoot(cwd);
+				assertSafeStorePath(root, dirname(root), "local store");
+				return root;
+			}),
+			users: 0,
+		};
+		activeWorkspaceRoots.set(key, ownership);
+	}
+	return leaseWorkspaceRoot(key, ownership);
+}
+
+function retainWorkspaceRoot(cwd: string, workspaceRoot: string, storeRoot: string | undefined) {
+	const key = workspaceLeaseKey(cwd, storeRoot);
+	const ownership = activeWorkspaceRoots.get(key);
+	if (!ownership) throw new Error("Cursor local workspace ownership is not active");
+	const lease = leaseWorkspaceRoot(key, ownership);
+	return {
+		...lease,
+		root: lease.root.then((root) => {
+			if (root !== workspaceRoot) throw new Error("Cursor local workspace ownership root mismatch");
+			return root;
+		}),
+	};
+}
+
+export async function withCursorSessionStoreIdentities<T>(
+	cwd: string,
+	scopeKey: string,
+	selectedRoot: string | undefined,
+	use: (identities: CursorPersistentStoreIdentities) => Promise<T>,
+): Promise<T> {
+	const storeRoot = selectedRoot === undefined ? undefined : normalizeCursorCustomStoreRoot(selectedRoot);
+	const lease = acquireWorkspaceRoot(cwd, storeRoot);
+	try {
+		const workspaceRoot = await lease.root;
+		return await use({
+			workspaceRoot,
+			sessionStore: { version: 1, stateRoot: buildCursorSessionStateRoot(workspaceRoot, scopeKey) },
+			...(storeRoot === undefined
+				? { domain: "default" as const, defaultStore: { version: 1 as const, stateRoot: workspaceRoot } }
+				: { domain: "custom" as const, storeRoot }),
+		});
+	} finally { lease.release(); }
+}
+
 export function cursorSessionStoreIdentitiesEqual(
 	left: CursorSessionStoreIdentity,
 	right: CursorSessionStoreIdentity,
@@ -80,30 +161,151 @@ export function cursorSessionStoreIdentitiesEqual(
 	return left.version === right.version && left.stateRoot === right.stateRoot;
 }
 
+function rejectedStorePath(stateRoot: string, base: string): string | undefined {
+	// User-managed ancestors above the SDK prefix (or our temporary removal root)
+	// may be links/junctions. Owned components, including the base, may not.
+	let path = resolve(base);
+	const suffix = relative(path, resolve(stateRoot));
+	if (suffix === ".." || suffix.startsWith(`..${sep}`) || isAbsolute(suffix)) return stateRoot;
+	for (const component of ["", ...suffix.split(sep).filter(Boolean)]) {
+		path = join(path, component);
+		try {
+			if (!lstatSync(path).isDirectory()) return path;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+}
+
+function assertSafeStorePath(stateRoot: string, base: string, label: string): void {
+	const rejected = rejectedStorePath(stateRoot, base);
+	if (rejected) throw new Error(`Cursor ${label} path contains a link or non-directory: ${rejected}`);
+}
+
+function workspaceHashes(cwd: string): { current: string; legacy: string | undefined } {
+	const current = createHash("sha256").update(cwd).digest("hex");
+	try {
+		return { current, legacy: createHash("md5").update(cwd).digest("hex") };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ERR_OSSL_EVP_UNSUPPORTED" ||
+			(error instanceof Error && error.message === "Digest method not supported")) return { current, legacy: undefined };
+		throw error;
+	}
+}
+
+function assertSafeWorkspaceLayout(cwd: string): void {
+	// ponytail: SDK 1.0.36 has no public read-only root resolver; use one when exposed.
+	// This pure layout is contract-verified against its factory and public getter;
+	// guard it before that getter can rename MD5 history through an owned link.
+	const slug = cwd.replace(/[^a-zA-Z0-9]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+	const prefix = join(homedir(), ".cursor", "projects", slug, "sdk-agent-store");
+	const { current, legacy } = workspaceHashes(cwd);
+	for (const hash of [current, legacy]) {
+		if (hash) assertSafeStorePath(join(prefix, hash), prefix, "local store");
+	}
+}
+
+function legacyWorkspaceRoot(cwd: string, defaultStateRoot: string): string | undefined {
+	// The public getter owns migration and may return MD5 after a failed rename.
+	const { current, legacy } = workspaceHashes(cwd);
+	if (!legacy) return undefined;
+	const prefix = dirname(defaultStateRoot);
+	if (defaultStateRoot !== join(prefix, current) && defaultStateRoot !== join(prefix, legacy)) return undefined;
+	return join(prefix, legacy);
+}
+
+export async function resolveCursorSessionStoreIdentity(options: {
+	cwd: string;
+	scopeKey: string;
+	identities: CursorPersistentStoreIdentities;
+	recordedIdentity?: CursorSessionStoreIdentity;
+	agentId: string;
+}): Promise<CursorSessionStoreIdentity | undefined> {
+	const { cwd, scopeKey, identities, agentId } = options;
+	if (identities.domain === "custom") {
+		if (!options.recordedIdentity || !cursorSessionStoreIdentitiesEqual(options.recordedIdentity, identities.sessionStore)) return undefined;
+		// Cleanup admits each candidate before cached-store reuse, which skips the open-time guard.
+		assertSafeStorePath(identities.sessionStore.stateRoot, dirname(identities.workspaceRoot), "local store");
+		guardCursorCustomStorePath(dirname(identities.workspaceRoot), identities.sessionStore.stateRoot).verify();
+		return identities.sessionStore;
+	}
+	const legacyRoot = legacyWorkspaceRoot(cwd, identities.defaultStore.stateRoot);
+	const legacyDefault = legacyRoot ? { version: 1 as const, stateRoot: legacyRoot } : undefined;
+	// Version-1 handles predate recorded identities and used the default workspace
+	// store. If both roots survive, that old store still owns their data.
+	const recorded = options.recordedIdentity ?? legacyDefault ?? identities.defaultStore;
+	const base = dirname(identities.defaultStore.stateRoot);
+	const current = [identities.defaultStore, identities.sessionStore];
+	const exact = current.find((identity) => cursorSessionStoreIdentitiesEqual(identity, recorded));
+	if (exact) {
+		assertSafeStorePath(exact.stateRoot, base, "local store");
+		return exact;
+	}
+	if (!legacyRoot) return undefined;
+	const legacySession = { version: 1 as const, stateRoot: buildCursorSessionStateRoot(legacyRoot, scopeKey) };
+	const legacy = [legacyDefault, legacySession].find((identity) =>
+		identity && cursorSessionStoreIdentitiesEqual(identity, recorded));
+	if (!legacy) return undefined;
+	assertSafeStorePath(legacy.stateRoot, base, "local store");
+	if (existsSync(legacyRoot)) return legacy; // No merge or silent owner switch.
+	const migrated = legacy === legacyDefault ? identities.defaultStore : identities.sessionStore;
+	assertSafeStorePath(migrated.stateRoot, base, "local store");
+	if (!existsSync(migrated.stateRoot)) return undefined;
+	// A missing legacy path alone is not migration proof. The exact cwd/scope
+	// destination must independently contain this recorded agent with this cwd.
+	const opened = await openCursorSessionStore(cwd, migrated, identities.defaultStore.stateRoot);
+	try {
+		const agent = await opened.store.agents.get({ agentId });
+		return agent?.cwd === cwd ? migrated : undefined;
+	} finally {
+		await opened.dispose();
+	}
+}
+
 async function openOwnedCursorSessionStore(
 	cwd: string,
 	identity: CursorSessionStoreIdentity,
-	removalRoot?: string,
+	options: { workspaceRoot: string; storeRoot?: string } | { removalRoot: string },
 ): Promise<OpenCursorSessionStore> {
 	const openedIdentity = Object.freeze({ ...identity });
-	let store: LocalAgentStore & { dispose(): Promise<void> };
+	const lease = "workspaceRoot" in options ? retainWorkspaceRoot(cwd, options.workspaceRoot, options.storeRoot) : undefined;
+	const removalRoot = "removalRoot" in options ? options.removalRoot : undefined;
+	const removeTemporaryStore = async () => {
+		if (removalRoot) {
+			assertSafeStorePath(openedIdentity.stateRoot, removalRoot, "temporary store removal");
+			await rm(removalRoot, { recursive: true, force: true });
+		}
+	};
+	let store: (LocalAgentStore & { dispose(): Promise<void> }) | undefined;
 	try {
-		store = await (await getSdkOperations()).openSqliteStore({
+		await lease?.root;
+		const base = "workspaceRoot" in options ? dirname(options.workspaceRoot) : options.removalRoot;
+		assertSafeStorePath(openedIdentity.stateRoot, base, "local store");
+		const guard = "workspaceRoot" in options && options.storeRoot !== undefined
+			? guardCursorCustomStorePath(base, openedIdentity.stateRoot) : undefined;
+		const operations = await getSdkOperations();
+		guard?.verify();
+		store = await operations.openSqliteStore({
 			workspaceRef: cwd,
 			stateRoot: toNamespacedPath(openedIdentity.stateRoot),
 		});
+		guard?.verify();
 	} catch (error) {
-		if (removalRoot) await rm(removalRoot, { recursive: true, force: true }).catch(() => undefined);
+		await store?.dispose().catch(() => undefined);
+		lease?.release();
+		await removeTemporaryStore().catch(() => undefined);
 		throw error;
 	}
+	const openedStore = store;
 	return {
 		identity: openedIdentity,
-		store,
+		store: openedStore,
 		dispose: async () => {
 			try {
-				await store.dispose();
+				await openedStore.dispose();
 			} finally {
-				if (removalRoot) await rm(removalRoot, { recursive: true, force: true });
+				lease?.release();
+				await removeTemporaryStore();
 			}
 		},
 	};
@@ -112,40 +314,44 @@ async function openOwnedCursorSessionStore(
 export function openCursorSessionStore(
 	cwd: string,
 	identity: CursorSessionStoreIdentity,
+	workspaceRoot: string,
+	storeRoot?: string,
 ): Promise<OpenCursorSessionStore> {
-	return openOwnedCursorSessionStore(cwd, identity);
+	return openOwnedCursorSessionStore(cwd, identity, { workspaceRoot, storeRoot });
 }
 
 export async function openCursorSessionStoreForScope(options: {
 	cwd: string;
 	scopeKey: string;
 	persistent: boolean;
-	hasResumeHandle: boolean;
-	resumeIdentity?: CursorSessionStoreIdentity;
+	storeRoot?: string;
+	resume?: { identity?: CursorSessionStoreIdentity; agentId: string };
 }): Promise<CursorSessionStoreSelection> {
-	const identities = await getCursorSessionStoreIdentities(options.cwd, options.scopeKey, options.persistent);
-	const requestedResumeIdentity = options.hasResumeHandle
-		? options.resumeIdentity ?? (options.persistent ? identities.defaultStore : undefined)
-		: undefined;
-	const resumableIdentities = options.persistent
-		? [identities.defaultStore, identities.sessionStore]
-		: [identities.sessionStore];
-	const resumeIdentity = requestedResumeIdentity && resumableIdentities
-		.find((identity) => cursorSessionStoreIdentitiesEqual(identity, requestedResumeIdentity));
-	let resumeAttemptAllowed = options.hasResumeHandle && resumeIdentity !== undefined;
-	let resumeFallback = options.persistent && options.hasResumeHandle && !resumeIdentity;
-	const selectedIdentity = resumeIdentity ?? identities.sessionStore;
-	const removalRoot = options.persistent ? undefined : dirname(dirname(identities.sessionStore.stateRoot));
-	let sessionStore: OpenCursorSessionStore;
-	try {
-		sessionStore = await openOwnedCursorSessionStore(options.cwd, selectedIdentity, removalRoot);
-	} catch (error) {
-		if (!resumeIdentity || cursorSessionStoreIdentitiesEqual(resumeIdentity, identities.sessionStore)) throw error;
-		resumeAttemptAllowed = false;
-		resumeFallback = true;
-		sessionStore = await openOwnedCursorSessionStore(options.cwd, identities.sessionStore);
+	if (!options.persistent) {
+		const removalRoot = join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
+		const identity = { version: 1 as const, stateRoot: buildCursorSessionStateRoot(removalRoot, options.scopeKey) };
+		const sessionStore = await openOwnedCursorSessionStore(options.cwd, identity, { removalRoot });
+		return { persistent: false, sessionStore, identities: { sessionStore: identity }, resumeAttemptAllowed: false, resumeFallback: false };
 	}
-	return { sessionStore, identities, resumeAttemptAllowed, resumeFallback };
+	return withCursorSessionStoreIdentities(options.cwd, options.scopeKey, options.storeRoot, async (identities) => {
+		const resumeIdentity = options.resume ? await resolveCursorSessionStoreIdentity({
+			cwd: options.cwd, scopeKey: options.scopeKey, identities,
+			recordedIdentity: options.resume.identity, agentId: options.resume.agentId,
+		}).catch(() => undefined) : undefined; // Unreadable resume storage falls back; fresh-store failures still propagate.
+		let resumeAttemptAllowed = resumeIdentity !== undefined;
+		let resumeFallback = options.resume !== undefined && !resumeIdentity;
+		const selectedIdentity = resumeIdentity ?? identities.sessionStore;
+		let sessionStore: OpenCursorSessionStore;
+		try {
+			sessionStore = await openCursorSessionStore(options.cwd, selectedIdentity, identities.workspaceRoot, identities.storeRoot);
+		} catch (error) {
+			if (!resumeIdentity || cursorSessionStoreIdentitiesEqual(resumeIdentity, identities.sessionStore)) throw error;
+			resumeAttemptAllowed = false;
+			resumeFallback = true;
+			sessionStore = await openCursorSessionStore(options.cwd, identities.sessionStore, identities.workspaceRoot, identities.storeRoot);
+		}
+		return { persistent: true, sessionStore, identities, resumeAttemptAllowed, resumeFallback };
+	});
 }
 
 export const __testUtils = {

package/src/cursor-state.ts

@@ -24,6 +24,7 @@ import {
 	DEFAULT_CURSOR_SETTING_SOURCES,
 	resolveCursorSettingSources,
 } from "./cursor-setting-sources.js";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
 import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
 import { asRecord } from "./cursor-record-utils.js";
@@ -37,6 +38,7 @@ import {
 	loadCursorSdkUserConfig,
 	mergeCursorSdkConfigForUpdate,
 	resolveCursorFastDefault,
+	resolveCursorLocalStoreRoot,
 	updateCursorSdkConfig,
 } from "./cursor-config.js";
 import {
@@ -59,6 +61,8 @@ export {
 	getCursorSessionConfig,
 } from "./cursor-runtime-state.js";
 
+export const CURSOR_FOOTER_ENV = "PI_CURSOR_FOOTER";
+
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const MODE_ENTRY_TYPE = "cursor-mode-state";
 
@@ -250,7 +254,7 @@ export function getCursorProviderAgentModeOrThrow(scopeKey?: string): AgentModeO
 type CursorStatusContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "isProjectTrusted" | "sessionManager">>;
 
 function updateCursorStatus(ctx: CursorStatusContext & Pick<ExtensionContext, "model" | "ui">, model = ctx.model): void {
-	if (!model || !isCursorModel(model)) {
+	if (!model || !isCursorModel(model) || !parseEnvBoolean(process.env[CURSOR_FOOTER_ENV], true)) {
 		ctx.ui.setStatus("cursor", undefined);
 		return;
 	}
@@ -559,7 +563,8 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 	pi.registerCommand("cursor-local-resume-cleanup", {
 		description: "Dry-run or delete recorded superseded local Cursor SDK agents",
 		handler: async (args, ctx) => {
-			await runCursorSessionAgentCleanupCommand(pi, args, ctx);
+			const storeRoot = resolveCursorLocalStoreRoot({ user: loadCursorSdkUserConfig() }).value;
+			await runCursorSessionAgentCleanupCommand(pi, args, ctx, storeRoot);
 		},
 	});
 

package/src/cursor-tool-manifest.ts

@@ -4,7 +4,7 @@ import type { CursorPiToolBridgeSnapshot } from "./cursor-pi-tool-bridge-types.j
 export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
 
 /**
- * Representative @cursor/sdk@1.0.32 local-agent ToolType values; actual exposure can vary by run.
+ * Representative Cursor SDK local-agent ToolType values; actual exposure can vary by run.
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY =

package/src/index.ts

@@ -10,7 +10,7 @@ import { getCursorSessionScopeSnapshot, registerCursorSessionScope } from "./cur
 import { registerCursorSessionAgentLifecycle } from "./cursor-session-agent-lifecycle.js";
 import { registerCursorSessionAgentLineage } from "./cursor-session-agent-lineage.js";
 import { registerCursorSessionAgentResume } from "./cursor-session-agent-resume.js";
-import { resolveCursorApiKey } from "./cursor-api-key.js";
+import { normalizeCursorApiKey } from "./cursor-api-key.js";
 import { registerCursorFallbackIssueWarning } from "./cursor-fallback-warning.js";
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context-registration.js";
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
@@ -41,7 +41,9 @@ export default async function (pi: CursorExtensionApi) {
 	registerCursorSessionScope(pi);
 	registerCursorUsageLedger(pi);
 	registerCursorUsageCommand(pi);
+	let fallbackIssue: CursorModelFallbackIssue | undefined;
 	const registerCursorProvider = registerCursorProviderBinding(pi);
+	const setFallbackWarning = registerCursorFallbackIssueWarning(pi);
 	registerCursorSessionAgentLineage(pi);
 	registerCursorSessionAgentLifecycle(pi);
 	registerCursorSessionAgentResume(pi);
@@ -55,40 +57,38 @@ export default async function (pi: CursorExtensionApi) {
 	registerCursorPiToolBridge(pi);
 	registerCursorAgentsContextDedup(pi);
 	registerCursorOverflowNormalization(pi);
-	let fallbackIssue: CursorModelFallbackIssue | undefined;
 	const models = await discoverModels({
+		apiKey: normalizeCursorApiKey(process.env.CURSOR_API_KEY),
+		allowNetwork: false,
 		onFallback: (issue) => {
 			fallbackIssue = issue;
 		},
 	});
 
-	if (fallbackIssue) {
-		registerCursorFallbackIssueWarning(pi, fallbackIssue);
-	}
+	setFallbackWarning(fallbackIssue);
 
 	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(refreshedModels);
+			const result = await ctx.modelRegistry.refresh({ providers: ["cursor"], allowNetwork: true, force: true, signal: ctx.signal });
 			if (!ctx.hasUI) return;
-			if (refreshFallbackIssue) {
-				ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
+			if (result.aborted) {
+				ctx.ui.notify("Cursor model catalog refresh was cancelled.", "warning");
+			} else if (result.errors.has("cursor")) {
+				ctx.ui.notify("Cursor model catalog refresh failed; the previous catalog was retained.", "warning");
+			} else if (fallbackIssue) {
+				ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${fallbackIssue.message}`, "warning");
 			} else {
-				ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
+				const count = ctx.modelRegistry.getAll().filter((model) => model.provider === "cursor").length;
+				ctx.ui.notify(`Cursor model catalog refreshed with ${count} model${count === 1 ? "" : "s"}.`, "info");
 			}
 		},
 	});
 
-	registerCursorProvider(models);
+	registerCursorProvider(models, (issue) => {
+		fallbackIssue = issue;
+		setFallbackWarning(issue);
+	});
 	// Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
 	registerCursorSdkSessionProcessErrorGuard(pi);
 }