switch to optimistic +lazy registration for pipenv, pyenv and poetry managers

Author: eleanorjboyd

docs/startup-flow.md

@@ -18,13 +18,22 @@ ASYNC (setImmediate callback, still in extension.ts):
 1. spawn PET process (`createNativePythonFinder`)
    1. sets up a JSON-RPC connection to it over stdin/stdout
 2. register all built-in managers in parallel (Promise.all):
-   - for each manager (system, conda, pyenv, pipenv, poetry):
-     1. check if tool exists (e.g. `getConda(nativeFinder)` asks PET for the conda binary)
-     2. if tool not found → log, return early (manager not registered)
-     3. if tool found → create manager, call `api.registerEnvironmentManager(manager)`
-        - this adds it to the `EnvironmentManagers` map
-        - fires `onDidChangeEnvironmentManager` → `ManagerReady` deferred resolves for this manager
-3. all registrations complete (Promise.all resolves)
+   - system: create SysPythonManager + VenvManager + PipPackageManager, register immediately
+     - ✅ NO PET call — managers are created and registered with no tool detection
+     - sets up file watcher for venv activation scripts
+   - conda: `getConda(nativeFinder)` checks settings → cache → persistent state → PATH
+     - if found → register CondaEnvManager + CondaPackageManager
+     - if not found → PET fallback as last resort (rarely hit, conda is usually on PATH)
+     - if not found at all → skip, send MANAGER_REGISTRATION.SKIPPED telemetry
+   - pyenv: create PyEnvManager, register immediately
+     - ✅ NO PET call — always registers unconditionally (lazy discovery)
+   - pipenv: create PipenvManager, register immediately
+     - ✅ NO PET call — always registers unconditionally (lazy discovery)
+   - poetry: create PoetryManager + PoetryPackageManager, register immediately
+     - ✅ NO PET call — always registers unconditionally (lazy discovery)
+   - shellStartupVars: initialize
+   - all managers fire `onDidChangeEnvironmentManager` → ManagerReady resolves
+3. all registrations complete (Promise.all resolves) — fast, typically milliseconds
 
 --- gate point: `applyInitialEnvironmentSelection` ---
    📊 TELEMETRY: ENV_SELECTION.STARTED { duration (activation→here), registeredManagerCount, registeredManagerIds, workspaceFolderCount }
@@ -55,26 +64,29 @@ ASYNC (setImmediate callback, still in extension.ts):
    managerDiscovery — P1, P2, or P4 won (manager → interpreter):
      `resolvePriorityChainCore` returns { manager, environment: undefined }
        → result.environment is undefined → falls through to `await result.manager.get(scope)`
-     `manager.get(scope)` (e.g. `CondaEnvManager.get()`):
+     `manager.get(scope)` (e.g. `CondaEnvManager.get()`, `PyEnvManager.get()`):
        4. `initialize()` — lazy, once-only per manager (guarded by deferred)
           a. `nativeFinder.refresh(hardRefresh=false)`:
-             → `handleSoftRefresh()` checks in-memory cache (Map) for key 'all' (bc one big scan, shared cache, all managers benefit)
+             → `handleSoftRefresh()` checks in-memory cache (Map) for key 'all'
                - on reload: cache is empty (Map was destroyed) → cache miss
                - falls through to `handleHardRefresh()`
              → `handleHardRefresh()`:
                - adds request to WorkerPool queue (concurrency 1, so serialized)
                - when its turn comes, calls `doRefresh()`:
                  1. `configure()` — JSON-RPC to PET with search paths, conda/poetry/pipenv paths, cache dir
                  2. `refresh` — JSON-RPC to PET, PET scans filesystem
+                    - PET has had time to warm up since spawn (registration was fast)
                     - PET may use its own on-disk cache (cacheDirectory) to speed this up
                     - PET streams back results as 'environment' and 'manager' notifications
                     - envs missing version/prefix get an inline resolve() call
                  3. returns NativeInfo[] (all envs of all types)
                - result stored in in-memory cache under key 'all'
              → subsequent managers calling nativeFinder.refresh(false) get cache hit → instant
-          b. filter results to this manager's env type (e.g. conda filters to kind=conda)
-          c. convert NativeEnvInfo → PythonEnvironment objects → populate collection
-          d. `loadEnvMap()` — reads persisted env path from workspace state
+          b. filter results to this manager's env type (e.g. conda filters to kind=conda, pyenv to kind=pyenv)
+          c. for pipenv/poetry/pyenv: if tool CLI was not found via PATH during registration,
+             extract tool executable from PET's manager info in the refresh results
+          d. convert NativeEnvInfo → PythonEnvironment objects → populate collection
+          e. `loadEnvMap()` — reads persisted env path from workspace state
              → matches path against freshly discovered collection via `findEnvironmentByPath()`
              → populates `fsPathToEnv` map
        5. look up scope in `fsPathToEnv` → return the matched env
@@ -86,6 +98,15 @@ ASYNC (setImmediate callback, still in extension.ts):
 
    📊 TELEMETRY: EXTENSION.MANAGER_REGISTRATION_DURATION { duration (activation→here), result, failureStage?, errorType? }
 
+SIDEBAR ACCESS (on-demand, if user opens Python environments panel):
+- view iterates `providers.managers` → all registered managers appear (including pyenv/pipenv/poetry)
+- user expands a manager node → `getChildren()` → `manager.getEnvironments('all')`
+  → `initialize()` (lazy, once-only) → `nativeFinder.refresh(false)`:
+    - if cache populated from earlier env selection → instant cache hit
+    - if first access → warm PET call (no concurrent pressure, single caller)
+  → environments appear under the manager node
+  → if no environments found → "No environments" placeholder shown
+
 POST-INIT:
 1. register terminal package watcher
 2. register settings change listener (`registerInterpreterSettingsChangeListener`) — re-runs priority chain if settings change

src/extension.ts

@@ -601,12 +601,9 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                     'conda',
                     registerCondaFeatures(nativeFinder, context.subscriptions, outputChannel, projectManager),
                 ),
-                safeRegister('pyenv', registerPyenvFeatures(nativeFinder, context.subscriptions, projectManager)),
-                safeRegister('pipenv', registerPipenvFeatures(nativeFinder, context.subscriptions, projectManager)),
-                safeRegister(
-                    'poetry',
-                    registerPoetryFeatures(nativeFinder, context.subscriptions, outputChannel, projectManager),
-                ),
+                safeRegister('pyenv', registerPyenvFeatures(nativeFinder, context.subscriptions)),
+                safeRegister('pipenv', registerPipenvFeatures(nativeFinder, context.subscriptions)),
+                safeRegister('poetry', registerPoetryFeatures(nativeFinder, context.subscriptions, outputChannel)),
                 safeRegister('shellStartupVars', shellStartupVarsMgr.initialize()),
             ]);
 

src/managers/pipenv/main.ts

@@ -1,65 +1,17 @@
 import { Disposable } from 'vscode';
 import { PythonEnvironmentApi } from '../../api';
 import { traceInfo } from '../../common/logging';
-import { EventNames } from '../../common/telemetry/constants';
-import { classifyError } from '../../common/telemetry/errorClassifier';
-import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { getPythonApi } from '../../features/pythonApi';
-import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
 import { PipenvManager } from './pipenvManager';
-import { getPipenv, hasPipenvEnvironments } from './pipenvUtils';
-
-import { notifyMissingManagerIfDefault } from '../common/utils';
 
 export async function registerPipenvFeatures(
     nativeFinder: NativePythonFinder,
     disposables: Disposable[],
-    projectManager: PythonProjectManager,
 ): Promise<void> {
-    let stage = 'getPythonApi';
     const api: PythonEnvironmentApi = await getPythonApi();
 
-    try {
-        stage = 'getPipenv';
-        const pipenv = await getPipenv(nativeFinder);
-
-        // Register the manager if the CLI is found, or if there are existing pipenv environments.
-        // This allows users with existing pipenv environments to still see and use them.
-        stage = 'hasPipenvEnvironments';
-        const hasPipenvEnvs = !pipenv && (await hasPipenvEnvironments(nativeFinder));
-
-        if (pipenv || hasPipenvEnvs) {
-            stage = 'createManager';
-            const mgr = new PipenvManager(nativeFinder, api);
-            stage = 'registerManager';
-            disposables.push(mgr, api.registerEnvironmentManager(mgr));
-            if (!pipenv) {
-                traceInfo(
-                    'Pipenv CLI not found, but pipenv environments were discovered. Registering manager for read-only environment management. To enable full pipenv features, set the "python.pipenvPath" setting to the path of your pipenv executable.',
-                );
-            }
-        } else {
-            traceInfo(
-                'Pipenv not found, turning off pipenv features. If you have pipenv installed in a non-standard location, set the "python.pipenvPath" setting.',
-            );
-            sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_SKIPPED, undefined, {
-                managerName: 'pipenv',
-                reason: 'tool_not_found',
-            });
-            await notifyMissingManagerIfDefault('ms-python.python:pipenv', projectManager, api);
-        }
-    } catch (ex) {
-        const failureStage = (ex as Error & { failureStage?: string })?.failureStage ?? stage;
-        traceInfo(
-            'Pipenv not found, turning off pipenv features. If you have pipenv installed in a non-standard location, set the "python.pipenvPath" setting.',
-            ex,
-        );
-        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
-            managerName: 'pipenv',
-            errorType: classifyError(ex),
-            failureStage,
-        });
-        await notifyMissingManagerIfDefault('ms-python.python:pipenv', projectManager, api);
-    }
+    traceInfo('Registering pipenv manager (environments will be discovered lazily)');
+    const mgr = new PipenvManager(nativeFinder, api);
+    disposables.push(mgr, api.registerEnvironmentManager(mgr));
 }

src/managers/pipenv/pipenvUtils.ts

@@ -51,37 +51,16 @@ export async function clearPipenvCache(): Promise<void> {
     pipenvPath = undefined;
 }
 
-/**
- * Check if any pipenv environments exist without requiring the pipenv CLI.
- * This allows the manager to be registered even if the CLI is not found.
- */
-export async function hasPipenvEnvironments(nativeFinder: NativePythonFinder): Promise<boolean> {
-    let stage = 'nativeFinderRefresh';
-    try {
-        const data = await nativeFinder.refresh(false);
-        stage = 'filterPipenvEnvs';
-        return data
-            .filter((e) => isNativeEnvInfo(e))
-            .some((e) => (e as NativeEnvInfo).kind === NativePythonEnvironmentKind.pipenv);
-    } catch (ex) {
-        const err = ex instanceof Error ? ex : new Error(String(ex));
-        (err as Error & { failureStage?: string }).failureStage = `hasPipenvEnvironments:${stage}`;
-        throw err;
-    }
-}
-
 function getPipenvPathFromSettings(): string | undefined {
     const pipenvPath = getSettingWorkspaceScope<string>('python', 'pipenvPath');
     return pipenvPath ? pipenvPath : undefined;
 }
 
-export async function getPipenv(native?: NativePythonFinder): Promise<string | undefined> {
-    let stage = 'checkSettings';
+export async function getPipenv(): Promise<string | undefined> {
     try {
         // Priority 1: Settings (if explicitly set and valid)
         const settingPath = getPipenvPathFromSettings();
         if (settingPath) {
-            stage = 'validateSettingsPath';
             if (await fs.exists(untildify(settingPath))) {
                 traceInfo(`Using pipenv from settings: ${settingPath}`);
                 return untildify(settingPath);
@@ -90,22 +69,17 @@ export async function getPipenv(native?: NativePythonFinder): Promise<string | u
         }
 
         // Priority 2: In-memory cache
-        stage = 'checkCache';
         if (pipenvPath) {
-            stage = 'validateCachePath';
             if (await fs.exists(untildify(pipenvPath))) {
                 return untildify(pipenvPath);
             }
             pipenvPath = undefined;
         }
 
         // Priority 3: Persistent state
-        stage = 'getPersistentState';
         const state = await getWorkspacePersistentState();
-        stage = 'checkPersistentState';
         const storedPath = await state.get<string>(PIPENV_PATH_KEY);
         if (storedPath) {
-            stage = 'validatePersistentStatePath';
             if (await fs.exists(untildify(storedPath))) {
                 pipenvPath = storedPath;
                 traceInfo(`Using pipenv from persistent state: ${pipenvPath}`);
@@ -115,37 +89,18 @@ export async function getPipenv(native?: NativePythonFinder): Promise<string | u
         }
 
         // Priority 4: PATH lookup
-        stage = 'pathLookup';
         const foundPipenv = await findPipenv();
         if (foundPipenv) {
             pipenvPath = foundPipenv;
             traceInfo(`Found pipenv in PATH: ${foundPipenv}`);
             return foundPipenv;
         }
 
-        // Priority 5: Native finder as fallback
-        stage = 'nativeFinderRefresh';
-        if (native) {
-            const data = await native.refresh(false);
-            stage = 'filterNativeFinderResults';
-            const managers = data
-                .filter((e) => !isNativeEnvInfo(e))
-                .map((e) => e as NativeEnvManagerInfo)
-                .filter((e) => e.tool.toLowerCase() === 'pipenv');
-            if (managers.length > 0) {
-                pipenvPath = managers[0].executable;
-                traceInfo(`Using pipenv from native finder: ${pipenvPath}`);
-                stage = 'persistNativeFinderResult';
-                await state.set(PIPENV_PATH_KEY, pipenvPath);
-                return pipenvPath;
-            }
-        }
-
-        traceInfo('Pipenv not found');
+        traceInfo('Pipenv not found via settings, cache, or PATH');
         return undefined;
     } catch (ex) {
         const err = ex instanceof Error ? ex : new Error(String(ex));
-        (err as Error & { failureStage?: string }).failureStage = `getPipenv:${stage}`;
+        (err as Error & { failureStage?: string }).failureStage = `getPipenv`;
         throw err;
     }
 }

src/managers/poetry/main.ts

@@ -1,64 +1,26 @@
 import { Disposable, LogOutputChannel } from 'vscode';
 import { PythonEnvironmentApi } from '../../api';
 import { traceInfo } from '../../common/logging';
-import { EventNames } from '../../common/telemetry/constants';
-import { classifyError } from '../../common/telemetry/errorClassifier';
-import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { getPythonApi } from '../../features/pythonApi';
-import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
-import { notifyMissingManagerIfDefault } from '../common/utils';
 import { PoetryManager } from './poetryManager';
 import { PoetryPackageManager } from './poetryPackageManager';
-import { getPoetry, getPoetryVersion } from './poetryUtils';
 
 export async function registerPoetryFeatures(
     nativeFinder: NativePythonFinder,
     disposables: Disposable[],
     outputChannel: LogOutputChannel,
-    projectManager: PythonProjectManager,
 ): Promise<void> {
-    let stage = 'getPythonApi';
     const api: PythonEnvironmentApi = await getPythonApi();
 
-    try {
-        stage = 'getPoetry';
-        const poetryPath = await getPoetry(nativeFinder);
-        if (poetryPath) {
-            traceInfo(
-                'The `shell` command is not available by default in Poetry versions 2.0.0 and above. Therefore all shell activation will be handled by calling `source <path-to-activate>`. If you face any problems with shell activation, please file an issue at https://github.com/microsoft/vscode-python-environments/issues to help us improve this implementation.',
-            );
-            stage = 'getPoetryVersion';
-            const version = await getPoetryVersion(poetryPath);
-            traceInfo(`Poetry found at ${poetryPath}, version: ${version}`);
-            stage = 'createEnvManager';
-            const envManager = new PoetryManager(nativeFinder, api);
-            stage = 'createPkgManager';
-            const pkgManager = new PoetryPackageManager(api, outputChannel, envManager);
+    traceInfo('Registering poetry manager (environments will be discovered lazily)');
+    const envManager = new PoetryManager(nativeFinder, api);
+    const pkgManager = new PoetryPackageManager(api, outputChannel, envManager);
 
-            stage = 'registerManagers';
-            disposables.push(
-                envManager,
-                pkgManager,
-                api.registerEnvironmentManager(envManager),
-                api.registerPackageManager(pkgManager),
-            );
-        } else {
-            traceInfo('Poetry not found, turning off poetry features.');
-            sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_SKIPPED, undefined, {
-                managerName: 'poetry',
-                reason: 'tool_not_found',
-            });
-            await notifyMissingManagerIfDefault('ms-python.python:poetry', projectManager, api);
-        }
-    } catch (ex) {
-        const failureStage = (ex as Error & { failureStage?: string })?.failureStage ?? stage;
-        traceInfo('Poetry not found, turning off poetry features.', ex);
-        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
-            managerName: 'poetry',
-            errorType: classifyError(ex),
-            failureStage,
-        });
-        await notifyMissingManagerIfDefault('ms-python.python:poetry', projectManager, api);
-    }
+    disposables.push(
+        envManager,
+        pkgManager,
+        api.registerEnvironmentManager(envManager),
+        api.registerPackageManager(pkgManager),
+    );
 }