Respect terminal cwd when resolving local venvs (#1708)

## Summary

- resolve terminal environments from the terminal cwd before using
workspace-wide fallbacks
- reject a selected local venv when it belongs to a sibling directory,
then use one nearest, unambiguous venv that contains the cwd
- fail closed instead of activating another project's environment when
the cwd project has no safe match
- keep terminal activation menu context synchronized with the currently
active terminal

Fixes #1631

## Context

The issue uses a single VS Code workspace folder as a container for
several independent Python projects:

```text
AILab/
  ProjectA/.venv
  ProjectB/.venv
  ProjectC/.venv
```

With the default `workspaceSearchPaths` (`[".venv", "*/.venv"]`), all
three environments are discovered. However, the workspace root is
automatically registered as the only Python project unless the nested
projects are explicitly added. A terminal opened in ProjectC could
therefore receive ProjectA's activation command.

Besides activating the wrong dependencies and Python version, this
affects every integrated terminal opened by other extensions because
auto-activation runs on the terminal-open event.

## Root cause

The failure was caused by two scope-collapsing decisions:

1. Nested environment paths resolve to the automatically registered
workspace-root project through ancestor project lookup. `VenvManager`
can therefore associate one sorted or persisted sibling venv with that
root.
2. `getEnvironmentForTerminal()` previously preferred project-wide
environment consensus before checking terminal cwd. With exactly one
registered project, it returned the root's selected environment
immediately, so the cwd heuristic never ran.

Simply moving the existing cwd lookup earlier is insufficient:
`api.getEnvironment(ProjectC)` still maps ProjectC back to the root
project and returns the same sibling environment.

## Fix

### Cwd-aware terminal resolution

The terminal resolver now:

1. reads shell-integration cwd first, then terminal creation cwd
2. finds the most-specific registered project containing that cwd
3. preserves the project's selected environment unless it is a built-in
venv located on a divergent sibling branch
4. for a sibling venv only, searches already-known environments for
candidates that:
   - belong to the built-in venv manager
   - are valid and have an absolute `sysPrefix`
   - live inside the containing project
   - have an owner directory that is an ancestor of the terminal cwd
5. selects exactly one nearest candidate

If no candidate exists, multiple candidates are equally near, lookup
fails, or lookup exceeds one second, the resolver returns no environment
rather than activating the wrong one. The losing timeout is cancelled
after a successful lookup.

A known cwd project with no selected environment also stops resolution,
preventing another project's sole environment from leaking through the
previous multi-project fallback.

### Compatibility boundaries

This is intentionally terminal-only. It does not change central
environment selection, persisted manager state, debugger/Pylance
resolution, status-bar selection, task execution, or the public
environment API.

| Scenario | Behavior |
| --- | --- |
| `workspace/.venv` with a terminal in `workspace/src` | Existing root
venv remains selected |
| Registered nested project with an explicit environment | Existing
project environment remains selected |
| Conda/Poetry/Pyenv or another external environment | Existing selected
environment remains selected |
| Terminal cwd outside all registered projects | Existing fallback
behavior remains |
| Terminal cwd unavailable | Existing fallback behavior remains |
| Selected venv is under ProjectA and cwd is under ProjectC | Use
ProjectC's unique nearest venv, or activate nothing |
| Cwd project has no selected environment | Activate nothing; do not
borrow another project's environment |

### Terminal activation UI

Safe resolution can intentionally return `undefined`. The activation
menu contexts are now cleared in that case instead of retaining the
previous terminal's Activate/Deactivate state. Async context updates
also verify that the originating terminal is still active, preventing
slower lookups or background activation events from overwriting the
currently focused terminal's global menu state.

## Tests

Added direct coverage for:

- normal workspace-root venvs and nested cwd paths
- sibling ProjectA/ProjectB/ProjectC venv resolution
- shell-integration cwd precedence
- ambiguous equally near venvs
- missing local venvs
- global venv exclusion
- workspace-root terminals with a selected descendant venv
- projects with no selected environment
- preventing another project's environment from leaking into the cwd
project
- environment-list rejection and timeout
- external environments, explicit nested projects, outside-workspace
cwd, and unavailable cwd
- clearing activation menu contexts when no environment resolves

Validation performed:

- `npm run compile-tests`
- `npm run compile`
- ESLint on all changed TypeScript files
- all 97 tracked unit-test files: **1,525 passing, 5 expected pending**

## Out of scope

The shell-execution timeout also reported in #1631 is a separate
activation-state issue. This PR addresses only selecting the correct
environment for a terminal cwd.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2f537bc5-b389-4ee2-aac2-e2b83be47f5c

Author: StellaHuang95

src/extension.ts

@@ -523,13 +523,15 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             }
         }),
         terminalActivation.onDidChangeTerminalActivationState(async (e) => {
-            await setActivateMenuButtonContext(e.terminal, e.environment, e.activated);
+            if (activeTerminal() === e.terminal) {
+                await setActivateMenuButtonContext(e.terminal, e.environment, e.activated);
+            }
         }),
         onDidChangeActiveTerminal(async (t) => {
             if (t) {
                 const env = terminalActivation.getEnvironment(t) ?? (await getEnvironmentForTerminal(api, t));
-                if (env) {
-                    await setActivateMenuButtonContext(t, env, terminalActivation.isActivated(t));
+                if (activeTerminal() === t) {
+                    await setActivateMenuButtonContext(t, env, env ? terminalActivation.isActivated(t) : false);
                 }
             }
         }),

src/features/terminal/activateMenuButton.ts

@@ -6,13 +6,13 @@ import { isTaskTerminal } from './utils';
 
 export async function setActivateMenuButtonContext(
     terminal: Terminal,
-    env: PythonEnvironment,
+    env: PythonEnvironment | undefined,
     activated?: boolean,
 ): Promise<void> {
-    const activatable = !isTaskTerminal(terminal) && isActivatableEnvironment(env);
+    const activatable = !!env && !isTaskTerminal(terminal) && isActivatableEnvironment(env);
     await executeCommand('setContext', 'pythonTerminalActivation', activatable);
 
-    if (activated !== undefined) {
-        await executeCommand('setContext', 'pythonTerminalActivated', activated);
+    if (!env || activated !== undefined) {
+        await executeCommand('setContext', 'pythonTerminalActivated', env ? activated : false);
     }
 }

src/features/terminal/utils.ts

@@ -1,7 +1,14 @@
 import * as path from 'path';
 import { Disposable, env, ExtensionTerminalOptions, tasks, Terminal, TerminalOptions, Uri } from 'vscode';
-import { PythonEnvironment, PythonProject, PythonProjectEnvironmentApi, PythonProjectGetterApi } from '../../api';
-import { traceVerbose } from '../../common/logging';
+import {
+    PythonEnvironment,
+    PythonEnvironmentApi,
+    PythonProject,
+    PythonProjectEnvironmentApi,
+    PythonProjectGetterApi,
+} from '../../api';
+import { VENV_MANAGER_ID } from '../../common/constants';
+import { traceError, traceVerbose } from '../../common/logging';
 import { timeout } from '../../common/utils/asyncUtils';
 import { createSimpleDebounce } from '../../common/utils/debounce';
 import { onDidChangeTerminalShellIntegration, onDidWriteTerminalData } from '../../common/window.apis';
@@ -10,6 +17,7 @@ import { identifyTerminalShell } from '../common/shellDetector';
 import { shellIntegrationSupportedShells } from './shells/common/shellUtils';
 
 export const SHELL_INTEGRATION_TIMEOUT = 500; // 0.5 seconds
+const LOCAL_VENV_LOOKUP_TIMEOUT_MS = 1000;
 
 /**
  * Use `terminal.integrated.shellIntegration.timeout` setting if available.
@@ -191,13 +199,152 @@ async function getDistinctProjectEnvs(
     return envs;
 }
 
+function isSameOrParentPath(parentPath: string, candidatePath: string): boolean {
+    const relative = path.relative(path.resolve(parentPath), path.resolve(candidatePath));
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function getProjectForCwd(projects: readonly PythonProject[], cwd: string): PythonProject | undefined {
+    return [...projects]
+        .filter((project) => isSameOrParentPath(project.uri.fsPath, cwd))
+        .sort((a, b) => b.uri.fsPath.length - a.uri.fsPath.length)[0];
+}
+
+function getLocalVenvOwner(environment: PythonEnvironment): string | undefined {
+    if (
+        environment.envId.managerId !== VENV_MANAGER_ID ||
+        environment.error ||
+        !path.isAbsolute(environment.sysPrefix)
+    ) {
+        return undefined;
+    }
+    return path.dirname(path.resolve(environment.sysPrefix));
+}
+
+function isSiblingVenv(environment: PythonEnvironment, project: PythonProject, cwd: string): boolean {
+    const owner = getLocalVenvOwner(environment);
+    return (
+        !!owner &&
+        isSameOrParentPath(project.uri.fsPath, owner) &&
+        !isSameOrParentPath(owner, cwd) &&
+        !isSameOrParentPath(cwd, owner)
+    );
+}
+
+async function getLocalVenvForCwd(
+    api: PythonEnvironmentApi,
+    project: PythonProject,
+    cwd: string,
+): Promise<PythonEnvironment | undefined> {
+    const environmentLookup = api
+        .getEnvironments('all')
+        .then((environments) => ({ environments }))
+        .catch((error) => {
+            traceError('Failed to get environments for terminal cwd resolution', error);
+            return { environments: undefined };
+        });
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const lookupTimeout = new Promise<{ environments: undefined }>((resolve) => {
+        timeoutHandle = setTimeout(() => {
+            traceVerbose(`Timed out looking for a local virtual environment for terminal cwd: ${cwd}`);
+            resolve({ environments: undefined });
+        }, LOCAL_VENV_LOOKUP_TIMEOUT_MS);
+    });
+    const lookupResult = await Promise.race([environmentLookup, lookupTimeout]).finally(() => {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    });
+    if (!lookupResult.environments) {
+        return undefined;
+    }
+
+    const candidates = lookupResult.environments
+        .map((environment) => ({ environment, owner: getLocalVenvOwner(environment) }))
+        .filter(
+            (candidate): candidate is { environment: PythonEnvironment; owner: string } =>
+                candidate.owner !== undefined &&
+                isSameOrParentPath(project.uri.fsPath, candidate.owner) &&
+                isSameOrParentPath(candidate.owner, cwd),
+        )
+        .map((candidate) => ({
+            ...candidate,
+            distance: path
+                .relative(path.resolve(candidate.owner), path.resolve(cwd))
+                .split(path.sep)
+                .filter(Boolean).length,
+        }));
+
+    if (candidates.length === 0) {
+        return undefined;
+    }
+
+    const nearestDistance = Math.min(...candidates.map((candidate) => candidate.distance));
+    const nearest = candidates.filter((candidate) => candidate.distance === nearestDistance);
+    const unique = Array.from(
+        new Map(nearest.map((candidate) => [candidate.environment.envId.id, candidate.environment])).values(),
+    );
+
+    if (unique.length !== 1) {
+        traceVerbose(`Multiple local virtual environments match terminal cwd: ${cwd}`);
+        return undefined;
+    }
+
+    return unique[0];
+}
+
+interface CwdEnvironmentResolution {
+    environment?: PythonEnvironment;
+    stopFallback: boolean;
+}
+
+async function getEnvironmentForCwd(
+    api: PythonEnvironmentApi,
+    projects: readonly PythonProject[],
+    cwd: string,
+): Promise<CwdEnvironmentResolution> {
+    const project = getProjectForCwd(projects, cwd);
+    if (!project) {
+        return { stopFallback: false };
+    }
+
+    const projectEnvironment = await api.getEnvironment(project.uri);
+    if (projectEnvironment && !isSiblingVenv(projectEnvironment, project, cwd)) {
+        return { environment: projectEnvironment, stopFallback: true };
+    }
+
+    if (!projectEnvironment) {
+        return { stopFallback: true };
+    }
+
+    traceVerbose(`Ignoring virtual environment outside terminal cwd: ${projectEnvironment.environmentPath.fsPath}`);
+
+    const localEnvironment = await getLocalVenvForCwd(api, project, cwd);
+    if (localEnvironment) {
+        traceVerbose(`Using local virtual environment for terminal cwd: ${localEnvironment.environmentPath.fsPath}`);
+        return { environment: localEnvironment, stopFallback: true };
+    }
+
+    return {
+        stopFallback: true,
+    };
+}
+
 export async function getEnvironmentForTerminal(
-    api: PythonProjectGetterApi & PythonProjectEnvironmentApi,
+    api: PythonEnvironmentApi,
     terminal?: Terminal,
 ): Promise<PythonEnvironment | undefined> {
     let env: PythonEnvironment | undefined;
 
     const projects = api.getPythonProjects();
+    const terminalCwd = terminal ? getTerminalCwd(terminal) : undefined;
+    if (terminalCwd) {
+        const cwdResolution = await getEnvironmentForCwd(api, projects, terminalCwd);
+        if (cwdResolution.environment || cwdResolution.stopFallback) {
+            return cwdResolution.environment;
+        }
+    }
+
     if (projects.length === 0) {
         env = await api.getEnvironment(undefined);
     } else if (projects.length === 1) {
@@ -217,10 +364,9 @@ export async function getEnvironmentForTerminal(
     if (env) {
         return env;
     }
-
     // This is a heuristic approach to attempt to find the environment for this terminal.
     // This is not guaranteed to work, but is better than nothing.
-    const terminalCwd = terminal ? getTerminalCwd(terminal) : undefined;
+    // This is not guaranteed to work, but is better than nothing.
     if (terminalCwd) {
         env = await api.getEnvironment(Uri.file(path.resolve(terminalCwd)));
     } else {

src/test/features/terminal/activateMenuButton.unit.test.ts

@@ -54,4 +54,19 @@ suite('Terminal - Activate Menu Button', () => {
             'Should set pythonTerminalActivation to false for task terminal',
         );
     });
+
+    test('should clear activation contexts when no environment is resolved', async () => {
+        await setActivateMenuButtonContext(mockTerminal, undefined);
+
+        assert.ok(
+            executeCommandStub.calledWith('setContext', 'pythonTerminalActivation', false),
+            'Should hide the activation button',
+        );
+        assert.ok(
+            executeCommandStub.calledWith('setContext', 'pythonTerminalActivated', false),
+            'Should clear the activated state',
+        );
+        assert.ok(isTaskTerminalStub.notCalled, 'Should not inspect terminal type without an environment');
+        assert.ok(isActivatableEnvironmentStub.notCalled, 'Should not inspect an undefined environment');
+    });
 });