Merge branch 'main' into eager-id

Author: flying-sheep

docs/managing-python-projects.md

@@ -211,6 +211,8 @@ You can set default managers that apply to all projects without explicit overrid
 }
 ```
 
+> **Important**: The extension never writes settings to the User (global) scope. All extension-managed settings are written at the Workspace or Workspace Folder level only. This prevents the extension from setting values that persist across unrelated projects and cause unexpected interference (see [#1468](https://github.com/microsoft/vscode-python-environments/issues/1468)). If a user wants a user-level default, they can set it manually in their User `settings.json`.
+
 ## Working with Multi-Root Workspaces
 
 Multi-root workspaces contain multiple top-level folders. The extension handles these seamlessly:

src/common/telemetry/constants.ts

@@ -101,6 +101,16 @@ export enum EventNames {
      * - hasPersistedSelection: boolean (whether a persisted env path existed in workspace state)
      */
     ENV_SELECTION_RESULT = 'ENV_SELECTION.RESULT',
+    /**
+     * Telemetry event fired when applyInitialEnvironmentSelection returns.
+     * Duration measures the blocking time (excludes deferred global scope).
+     * Properties:
+     * - globalScopeDeferred: boolean (true = global scope fired in background, false = awaited)
+     * - workspaceFolderCount: number (total workspace folders)
+     * - resolvedFolderCount: number (folders that resolved with a non-undefined env)
+     * - settingErrorCount: number (user-configured settings that could not be applied)
+     */
+    ENV_SELECTION_COMPLETED = 'ENV_SELECTION.COMPLETED',
     /**
      * Telemetry event fired when a lazily-registered manager completes its first initialization.
      * Replaces MANAGER_REGISTRATION_SKIPPED and MANAGER_REGISTRATION_FAILED for managers
@@ -122,6 +132,42 @@ export enum EventNames {
      * - duration: number (milliseconds taken for the CLI operation)
      */
     PET_JSON_CLI_FALLBACK = 'PET.JSON_CLI_FALLBACK',
+    /**
+     * Telemetry event for a PET refresh attempt (the core discovery RPC call).
+     * Properties:
+     * - result: 'success' | 'timeout' | 'error'
+     * - envCount: number (environments returned via notifications)
+     * - unresolvedCount: number (envs that needed follow-up resolve calls)
+     * - workspaceDirCount: number (workspace directories sent in configure)
+     * - searchPathCount: number (extra search paths sent in configure)
+     * - attempt: number (0 = first try, 1 = retry)
+     * - errorType: string (classified error category, on failure only)
+     */
+    PET_REFRESH = 'PET.REFRESH',
+    /**
+     * Telemetry event for a PET configure RPC call.
+     * Properties:
+     * - result: 'success' | 'timeout' | 'error' | 'skipped'
+     * - workspaceDirCount: number
+     * - envDirCount: number (environmentDirectories count)
+     * - retryCount: number (consecutive timeout count from ConfigureRetryState)
+     */
+    PET_CONFIGURE = 'PET.CONFIGURE',
+    /**
+     * Telemetry event for PET process restart attempts.
+     * Properties:
+     * - attempt: number (1-based restart attempt number)
+     * - result: 'success' | 'error'
+     * - errorType: string (classified error category, on failure only)
+     */
+    PET_PROCESS_RESTART = 'PET.PROCESS_RESTART',
+    /**
+     * Telemetry event for PET resolve calls (single-env resolution).
+     * Properties:
+     * - result: 'success' | 'timeout' | 'error'
+     * - errorType: string (classified error category, on failure only)
+     */
+    PET_RESOLVE = 'PET.RESOLVE',
 }
 
 // Map all events to their properties
@@ -395,6 +441,21 @@ export interface IEventNamePropertyMapping {
         hasPersistedSelection: boolean;
     };
 
+    /* __GDPR__
+        "env_selection.completed": {
+            "globalScopeDeferred": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "workspaceFolderCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "resolvedFolderCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "settingErrorCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.ENV_SELECTION_COMPLETED]: {
+        globalScopeDeferred: boolean;
+        workspaceFolderCount: number;
+        resolvedFolderCount: number;
+        settingErrorCount: number;
+    };
+
     /* __GDPR__
         "manager.lazy_init": {
             "managerName": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
@@ -424,4 +485,68 @@ export interface IEventNamePropertyMapping {
         operation: 'refresh' | 'resolve';
         result: 'success' | 'error';
     };
+
+    /* __GDPR__
+        "pet.refresh": {
+            "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "envCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "unresolvedCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "workspaceDirCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "searchPathCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "attempt": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.PET_REFRESH]: {
+        result: 'success' | 'timeout' | 'error';
+        envCount?: number;
+        unresolvedCount?: number;
+        workspaceDirCount?: number;
+        searchPathCount?: number;
+        attempt: number;
+        errorType?: string;
+    };
+
+    /* __GDPR__
+        "pet.configure": {
+            "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "workspaceDirCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "envDirCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "retryCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.PET_CONFIGURE]: {
+        result: 'success' | 'timeout' | 'error' | 'skipped';
+        workspaceDirCount?: number;
+        envDirCount?: number;
+        retryCount: number;
+    };
+
+    /* __GDPR__
+        "pet.process_restart": {
+            "attempt": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
+            "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.PET_PROCESS_RESTART]: {
+        attempt: number;
+        result: 'success' | 'error';
+        errorType?: string;
+    };
+
+    /* __GDPR__
+        "pet.resolve": {
+            "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.PET_RESOLVE]: {
+        result: 'success' | 'timeout' | 'error';
+        errorType?: string;
+    };
 }

src/features/interpreterSelection.ts

@@ -290,14 +290,16 @@ export async function applyInitialEnvironmentSelection(
         `[interpreterSelection] Applying initial environment selection for ${folders.length} workspace folder(s)`,
     );
 
-    // Checkpoint 1: env selection starting — managers are registered
     sendTelemetryEvent(EventNames.ENV_SELECTION_STARTED, activationToReadyDurationMs, {
         registeredManagerCount: envManagers.managers.length,
         registeredManagerIds: envManagers.managers.map((m) => m.id).join(','),
         workspaceFolderCount: folders.length,
     });
 
     const allErrors: SettingResolutionError[] = [];
+    let workspaceFolderResolved = false;
+    let resolvedFolderCount = 0;
+    const selectionStopWatch = new StopWatch();
 
     for (const folder of folders) {
         try {
@@ -311,23 +313,24 @@ export async function applyInitialEnvironmentSelection(
             );
             allErrors.push(...errors);
 
-            // Checkpoint 2: priority chain resolved — which path?
-            const isPathA = result.environment !== undefined;
-
-            // Get the specific environment if not already resolved
             const env = result.environment ?? (await result.manager.get(folder.uri));
 
             sendTelemetryEvent(EventNames.ENV_SELECTION_RESULT, scopeStopWatch.elapsedTime, {
                 scope: 'workspace',
                 prioritySource: result.source,
                 managerId: result.manager.id,
-                resolutionPath: isPathA ? 'envPreResolved' : 'managerDiscovery',
+                resolutionPath: result.environment ? 'envPreResolved' : 'managerDiscovery',
                 hasPersistedSelection: env !== undefined,
             });
 
             // Cache only — NO settings.json write (shouldPersistSettings = false)
             await envManagers.setEnvironment(folder.uri, env, false);
 
+            if (env) {
+                workspaceFolderResolved = true;
+                resolvedFolderCount++;
+            }
+
             traceInfo(
                 `[interpreterSelection] ${folder.name}: ${env?.displayName ?? 'none'} (source: ${result.source})`,
             );
@@ -336,49 +339,94 @@ export async function applyInitialEnvironmentSelection(
         }
     }
 
-    // Also apply initial selection for global scope (no workspace folder)
-    // This ensures defaultInterpreterPath is respected even without a workspace
-    try {
-        const globalStopWatch = new StopWatch();
-        const { result, errors } = await resolvePriorityChainCore(undefined, envManagers, undefined, nativeFinder, api);
-        allErrors.push(...errors);
+    // Resolve global scope (fallback for files outside workspace folders).
+    // Deferred to background when a workspace folder already resolved.
+    const resolveGlobalScope = async (): Promise<SettingResolutionError[]> => {
+        try {
+            const globalStopWatch = new StopWatch();
+            const { result, errors: globalErrors } = await resolvePriorityChainCore(
+                undefined,
+                envManagers,
+                undefined,
+                nativeFinder,
+                api,
+            );
 
-        const isPathA = result.environment !== undefined;
+            const env = result.environment ?? (await result.manager.get(undefined));
 
-        // Get the specific environment if not already resolved
-        const env = result.environment ?? (await result.manager.get(undefined));
+            sendTelemetryEvent(EventNames.ENV_SELECTION_RESULT, globalStopWatch.elapsedTime, {
+                scope: 'global',
+                prioritySource: result.source,
+                managerId: result.manager.id,
+                resolutionPath: result.environment ? 'envPreResolved' : 'managerDiscovery',
+                hasPersistedSelection: env !== undefined,
+            });
 
-        sendTelemetryEvent(EventNames.ENV_SELECTION_RESULT, globalStopWatch.elapsedTime, {
-            scope: 'global',
-            prioritySource: result.source,
-            managerId: result.manager.id,
-            resolutionPath: isPathA ? 'envPreResolved' : 'managerDiscovery',
-            hasPersistedSelection: env !== undefined,
-        });
+            // Cache only — NO settings.json write
+            await envManagers.setEnvironments('global', env, false);
 
-        // Cache only — NO settings.json write (shouldPersistSettings = false)
-        await envManagers.setEnvironments('global', env, false);
+            traceInfo(`[interpreterSelection] global: ${env?.displayName ?? 'none'} (source: ${result.source})`);
 
-        traceInfo(`[interpreterSelection] global: ${env?.displayName ?? 'none'} (source: ${result.source})`);
-    } catch (err) {
-        traceError(`[interpreterSelection] Failed to set global environment: ${err}`);
+            return globalErrors;
+        } catch (err) {
+            traceError(`[interpreterSelection] Failed to set global environment: ${err}`);
+            return [];
+        }
+    };
+
+    if (workspaceFolderResolved) {
+        // Defer global scope so it doesn't block post-selection startup.
+        traceInfo('[interpreterSelection] Workspace env resolved, deferring global scope to background');
+        resolveGlobalScope()
+            .then(async (globalErrors) => {
+                if (globalErrors.length > 0) {
+                    await notifyUserOfSettingErrors(globalErrors);
+                }
+            })
+            .catch((err) => traceError(`[interpreterSelection] Background global scope resolution failed: ${err}`));
+    } else {
+        // No workspace folder resolved — global scope is the primary fallback, must await.
+        const globalErrors = await resolveGlobalScope();
+        allErrors.push(...globalErrors);
     }
 
-    // Notify user if any settings could not be applied
+    // Notify user if any settings could not be applied (workspace + global when awaited)
     if (allErrors.length > 0) {
         await notifyUserOfSettingErrors(allErrors);
     }
+
+    // Duration measures blocking time only (excludes deferred global scope).
+    sendTelemetryEvent(EventNames.ENV_SELECTION_COMPLETED, selectionStopWatch.elapsedTime, {
+        globalScopeDeferred: workspaceFolderResolved,
+        workspaceFolderCount: folders.length,
+        resolvedFolderCount,
+        settingErrorCount: allErrors.length,
+    });
 }
 
 /**
  * Notify the user when their configured settings could not be applied.
  * Shows a warning message with an option to open settings.
+ * Tracks already-warned settings to avoid duplicate dialogs (e.g., when
+ * the same user-level misconfiguration is hit by both workspace and
+ * deferred global scope resolution).
  */
+const warnedSettings = new Set<string>();
+
+export function resetSettingWarnings(): void {
+    warnedSettings.clear();
+}
+
 async function notifyUserOfSettingErrors(errors: SettingResolutionError[]): Promise<void> {
     // Group errors by setting type to avoid spamming the user
     const uniqueSettings = [...new Set(errors.map((e) => e.setting))];
 
     for (const setting of uniqueSettings) {
+        if (warnedSettings.has(setting)) {
+            continue;
+        }
+        warnedSettings.add(setting);
+
         const settingErrors = errors.filter((e) => e.setting === setting);
         const firstError = settingErrors[0];