fix: skip package refresh for deleted environments (#1833)

Fixes #1824

## Problem

Deleting and recreating a virtual environment (for example `make
clean-venv` followed by `make venv`) surfaced an **"Error refreshing
packages"** notification.


### Explanation 
The package watcher observes `site-packages`. Deleting the environment
fires delete events, which schedule a debounced refresh. That refresh
then ran `pip list` against the interpreter that had just been removed,
so the failure was an expected consequence of the deletion rather than
an actionable problem — but it was reported to the user as an error.

## Fix

`watchPackageChangesForEnvironment` now verifies the environment
executable exists before refreshing.

- If the executable is missing, the refresh is not attempted
- Because a deletion is usually followed by a recreation, the watcher
retries on the existing 500ms debounce interval for up to 30 seconds
- If the executable never returns, the watcher stops retrying and logs
at debug level.
- Genuine stat failures and genuine refresh failures are still logged as
errors.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: eleanorjboyd

src/common/utils/filesystem.ts

@@ -1,11 +1,21 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+/**
+ * Determines whether an error indicates that a file system entry does not exist.
+ *
+ * Supports Node.js and VS Code file system error codes.
+ *
+ * @param error The error to inspect.
+ * @returns Whether the error represents a missing file system entry.
+ */
 export function isFileNotFoundError(error: unknown): error is NodeJS.ErrnoException {
     return (
         typeof error === 'object' &&
         error !== null &&
-        'code' in error &&
-        (error as NodeJS.ErrnoException).code === 'ENOENT'
+        (('code' in error &&
+            ((error as NodeJS.ErrnoException).code === 'ENOENT' ||
+                (error as NodeJS.ErrnoException).code === 'FileNotFound')) ||
+            ('name' in error && String(error.name).startsWith('EntryNotFound')))
     );
 }

src/common/workspace.fs.apis.ts

@@ -1,4 +1,5 @@
 import { FileStat, Uri, workspace } from 'vscode';
+import { isFileNotFoundError } from './utils/filesystem';
 
 export function readFile(uri: Uri): Thenable<Uint8Array> {
     return workspace.fs.readFile(uri);
@@ -7,3 +8,21 @@ export function readFile(uri: Uri): Thenable<Uint8Array> {
 export function stat(uri: Uri): Thenable<FileStat> {
     return workspace.fs.stat(uri);
 }
+
+/**
+ * Checks whether a workspace file system entry exists.
+ *
+ * @param uri The URI of the entry to check.
+ * @returns Whether the entry exists.
+ */
+export async function pathExists(uri: Uri): Promise<boolean> {
+    try {
+        await workspace.fs.stat(uri);
+        return true;
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}

src/managers/common/packageWatcher.ts

@@ -3,6 +3,7 @@ import { Disposable, Event, LogOutputChannel, RelativePattern, Terminal, Uri } f
 import { PackageManager, PythonEnvironment } from '../../api';
 import { createSimpleDebounce } from '../../common/utils/debounce';
 import { onDidCloseTerminal } from '../../common/window.apis';
+import { pathExists } from '../../common/workspace.fs.apis';
 import { createFileSystemWatcher, getConfiguration, onDidChangeConfiguration } from '../../common/workspace.apis';
 import type { EnvironmentManagers } from '../../features/envManagers';
 
@@ -14,6 +15,8 @@ export interface PackageWatcherTerminalActivation {
     }>;
 }
 
+const MAX_MISSING_EXECUTABLE_REFRESH_RETRIES = 60;
+
 /**
  * Derives the file system watch targets for a given Python environment.
  *
@@ -63,18 +66,43 @@ export function watchPackageChangesForEnvironment(
         return new Disposable(() => undefined);
     }
 
+    let missingExecutableRefreshRetries = 0;
     const debouncedRefresh = createSimpleDebounce(500, () => {
-        log.debug(`Package change detected for environment ${env.envId.id}, refreshing packages.`);
-        const currentPackageManager = resolvePackageManager();
-        if (!currentPackageManager) {
-            log.debug(`No current package manager found for environment ${env.envId.id}`);
-            return;
-        }
-        void currentPackageManager.refresh(env).catch((ex) => {
-            log.error(
-                `Failed to refresh packages for environment ${env.envId.id}: ${ex instanceof Error ? ex.message : String(ex)}`,
-            );
-        });
+        void (async () => {
+            try {
+                if (!(await pathExists(Uri.file(env.execInfo.run.executable)))) {
+                    if (missingExecutableRefreshRetries < MAX_MISSING_EXECUTABLE_REFRESH_RETRIES) {
+                        missingExecutableRefreshRetries += 1;
+                        debouncedRefresh.trigger();
+                    } else {
+                        log.debug(
+                            `Package change detected for environment ${env.envId.id}, but its executable did not reappear. Skipping package refresh.`,
+                        );
+                    }
+                    return;
+                }
+            } catch (ex) {
+                log.error(
+                    `Failed to check the executable for environment ${env.envId.id}: ${ex instanceof Error ? ex.message : String(ex)}`,
+                );
+                return;
+            }
+
+            missingExecutableRefreshRetries = 0;
+            log.debug(`Package change detected for environment ${env.envId.id}, refreshing packages.`);
+            const currentPackageManager = resolvePackageManager();
+            if (!currentPackageManager) {
+                log.debug(`No current package manager found for environment ${env.envId.id}`);
+                return;
+            }
+            try {
+                await currentPackageManager.refresh(env);
+            } catch (ex) {
+                log.error(
+                    `Failed to refresh packages for environment ${env.envId.id}: ${ex instanceof Error ? ex.message : String(ex)}`,
+                );
+            }
+        })();
     });
     const disposables: Disposable[] = [debouncedRefresh];
     const trigger = debouncedRefresh.trigger.bind(debouncedRefresh);

src/test/common/filesystem.unit.test.ts

@@ -11,8 +11,19 @@ suite('filesystem utilities', () => {
         assert.strictEqual(isFileNotFoundError(error), true);
     });
 
+    test('returns true for VS Code missing file errors', () => {
+        assert.strictEqual(isFileNotFoundError(Object.assign(new Error('missing'), { code: 'FileNotFound' })), true);
+        assert.strictEqual(
+            isFileNotFoundError(Object.assign(new Error('missing'), { name: 'EntryNotFound (FileSystemError)' })),
+            true,
+        );
+    });
+
     test('rejects other errors and non-errors', () => {
-        assert.strictEqual(isFileNotFoundError(Object.assign(new Error('not a directory'), { code: 'ENOTDIR' })), false);
+        assert.strictEqual(
+            isFileNotFoundError(Object.assign(new Error('not a directory'), { code: 'ENOTDIR' })),
+            false,
+        );
         assert.strictEqual(isFileNotFoundError(new Error('missing code')), false);
         assert.strictEqual(isFileNotFoundError(undefined), false);
         assert.strictEqual(isFileNotFoundError('ENOENT'), false);

src/test/managers/common/packageWatcher.unit.test.ts

@@ -12,6 +12,7 @@ import {
     PythonProject,
 } from '../../../api';
 import * as windowApis from '../../../common/window.apis';
+import * as workspaceFsApis from '../../../common/workspace.fs.apis';
 import * as workspaceApis from '../../../common/workspace.apis';
 import type { EnvironmentManagers } from '../../../features/envManagers';
 import { InternalPackageManager } from '../../../managers/common/registeredManagers';
@@ -41,6 +42,7 @@ suite('Package Watcher', () => {
             debug: sandbox.stub(),
         };
         createFileSystemWatcherStub = sandbox.stub(workspaceApis, 'createFileSystemWatcher');
+        sandbox.stub(workspaceFsApis, 'pathExists').resolves(true);
         sandbox.stub(workspaceApis, 'getConfiguration').returns({
             get: (_key: string, defaultValue?: unknown) => defaultValue ?? true,
         } as ReturnType<typeof workspaceApis.getConfiguration>);
@@ -300,6 +302,60 @@ suite('Package Watcher', () => {
             clock.restore();
         });
 
+        test('should not refresh packages when the environment executable was deleted', async () => {
+            const clock = sandbox.useFakeTimers();
+            const mockWatcher = createMockWatcher();
+            createFileSystemWatcherStub.returns(mockWatcher);
+            (workspaceFsApis.pathExists as sinon.SinonStub).resolves(false);
+
+            const env = createMockEnvironment();
+            const packageManager = createMockPackageManager();
+
+            watchPackageChangesForEnvironment(
+                env,
+                packageManager as PackageManager,
+                mockLogOutputChannel as LogOutputChannel,
+            );
+
+            mockWatcher._deleteEmitter.fire(Uri.file('/path/to/pkg.dist-info/METADATA'));
+            await clock.tickAsync(600);
+
+            assert.strictEqual(
+                (packageManager.refresh as sinon.SinonStub).callCount,
+                0,
+                'Should not refresh packages for a deleted environment',
+            );
+
+            clock.restore();
+        });
+
+        test('should refresh packages when a deleted environment executable reappears', async () => {
+            const clock = sandbox.useFakeTimers();
+            const mockWatcher = createMockWatcher();
+            createFileSystemWatcherStub.returns(mockWatcher);
+            (workspaceFsApis.pathExists as sinon.SinonStub).onFirstCall().resolves(false).resolves(true);
+
+            const env = createMockEnvironment();
+            const packageManager = createMockPackageManager();
+
+            watchPackageChangesForEnvironment(
+                env,
+                packageManager as PackageManager,
+                mockLogOutputChannel as LogOutputChannel,
+            );
+
+            mockWatcher._deleteEmitter.fire(Uri.file('/path/to/pkg.dist-info/METADATA'));
+            await clock.tickAsync(1_200);
+
+            assert.strictEqual(
+                (packageManager.refresh as sinon.SinonStub).callCount,
+                1,
+                'Should refresh packages after the environment is recreated',
+            );
+
+            clock.restore();
+        });
+
         test('should debounce multiple rapid file events', () => {
             const mockWatcher = createMockWatcher();
             createFileSystemWatcherStub.returns(mockWatcher);
@@ -528,7 +584,9 @@ suite('Package Watcher', () => {
             const terminal = { name: 'terminal' } as Terminal;
             const envManagers = {
                 onDidChangeActiveEnvironment: environmentChanges.event,
-                getPackageManager: sandbox.stub().callsFake((context) => (context === env ? packageManager : undefined)),
+                getPackageManager: sandbox
+                    .stub()
+                    .callsFake((context) => (context === env ? packageManager : undefined)),
             } as unknown as EnvironmentManagers;
 
             registerPackageWatchers(envManagers, mockTerminalActivation, mockLogOutputChannel as LogOutputChannel);