Fix five PEP 723 inline-script defects: cancellation, rename, shared builds, terminal scope, and package drift (#1772)

## Summary

Five fixes to the PEP 723 inline-script feature, found while working
through reported issues against the testbed. Each is independently
reviewable and has unit coverage that was checked to **fail when the
corresponding guard is removed**, not merely to pass.

The feature remains behind the undeclared
`python-envs.inlineScripts.enabled` flag (default `false`), so nothing
here is user-visible until that is enabled.

## Commits and the issue each addresses

| Commit | Issue addressed |
|---|---|
| `0a21a2c1` | Cancelling setup retained the cache lock with no cleanup,
so the retry failed with `Lock was retained after an interrupted
operation` |
| `887548d8` | Renaming a script dropped its environment association
even though nothing about the environment changed |
| `eaa71423` | Cancelling a build shared by two scripts reported
cancellation to only one of them |
| `22628e1f` | Selecting a script environment could leak into general
workspace terminals |
| `669cb8ed` | Editing packages on a shared environment silently broke
other scripts |

Two earlier commits on this branch (`9acf5a21`, `cd7d214a`) predate this
work and are unrelated to the above.

---

### `0a21a2c1` — Discard cancelled environments instead of quarantining
them

Cancelling package installation retained the cache-entry lock and made
no cleanup attempt. The cancellation surfaced as a generic *"Failed to
set up the environment for this script"*, and the next attempt failed
with `ELOCKRETAINED`. Recovery required clearing the entire cache.

Cancellation now cleans up automatically. `discardCacheEntry` deletes
`.meta.json` and any `.meta.json.backup-*` **first**, then removes the
directory with bounded retry.

**The key invariant for reviewers:** the sidecar is the correctness
guarantee, not the directory. `inspectCacheEntry` treats a missing
sidecar as `stale`, and `writeMetaJson` is the only writer of that file
— four call sites, all under the cache-entry lock (see the comment above
`withCacheEntryLock`). A surviving installer writes into `site-packages`
and cannot recreate a sidecar. So an entry whose directory survives
deletion is inert, and gets rebuilt or TTL-swept rather than reused.

Retry exists because a just-stopped installer can hold file handles
briefly, most visibly on Windows.

Also fixes two bulk-setup bugs:
`setUpInlineScriptEnvironmentsInWorkspace` only counted successes and
never surfaced outcomes, so a mid-run cancellation was invisible and the
next install started immediately. It now stops the run on cancellation
and reports failures distinctly.

### `887548d8` — Follow renames instead of dropping associations

A cache entry is keyed by normalized dependencies and base interpreter —
**the script path is not an input** — so a rename cannot invalidate it.
Neither the metadata block nor the environment changes.

This also left two subsystems disagreeing. `PythonProjectManagerImpl`
already follows renames via `updatePythonProjectSettingPath`, which
rewrites the `pythonProjects` entry and preserves its
`_inlineScriptRegistration` marker. Clearing the association therefore
produced a managed inline-script project entry pointing at a file with
no environment behind it.

The record is transferred in one persistence transaction and then
**re-validated rather than trusted**: its metadata binding is
content-derived, so if the file at the new path no longer matches,
ordinary validation clears it and the CodeLens returns.

Guards: destination must still be a routable local `.py`; renaming onto
an already-associated script replaces it; deletes are unchanged.

**Known gap:** directory renames are not covered — VS Code reports one
event per folder rather than one per contained file. Moving an
individual *file* already works, since VS Code reports a move as a
rename.

### `eaa71423` — Cancellation reaches every script sharing a build

Scripts whose dependencies normalize to the same list resolve to the
same cache key, so a second request joins the in-flight build via
`pendingCreations` instead of starting its own. Cancelling recorded an
outcome only against the initiating URI. The joined script fell through
to a generic failure, and in a bulk run its outcome was not a
cancellation — so the run kept installing.

The failure is now recorded on the shared `PendingCreationContext` and
translated per caller after awaiting the shared promise.

**Note for reviewers:** same-file coalescing (`pendingSetups`) and
different-file shared builds (`pendingCreations`) are separate
mechanisms. Only the second was broken. Bulk setup is sequential, so
selecting both files in one bulk run does not reproduce it — the second
request must overlap the first build.

### `22628e1f` — Shell startup variables resolve at folder scope

Shell-startup activation keeps a single activation command per workspace
folder (for example `VSCODE_PYTHON_PWSH_ACTIVATE`), injected into every
terminal opened there. `handleEnvironmentChange` wrote whichever
environment the event carried into that slot after collapsing the
event's URI to its containing folder — so a per-file selection became
the folder default.

The handler now resolves the folder's own environment via
`getEnvironment(workspaceFolder.uri)`. This matches what
`initializeInternal` already did, so the two paths no longer disagree,
and it fixes the whole class rather than special-casing the
inline-script manager: any file-scoped environment is excluded. A folder
already polluted by an earlier session self-repairs on the next
environment change.

Only reachable with `python-envs.terminal.autoActivationType:
"shellStartup"`; the default is `"command"`. Adds the first unit
coverage for this manager.

### `669cb8ed` — Invalidate an environment when its packages are edited

Cache entries are shared by design. Editing packages there through the
package UI silently affected every bound script: nothing validated
installed versions, so the entry stayed valid, the CodeLens stayed
hidden, and a script the user never opened would run the wrong version
while its own header still declared the original pin. Re-running setup
reused the modified entry rather than repairing it.

A package change on an owned entry now records `manuallyModified` in the
sidecar and un-routes every associated script, so the CodeLens returns
for each. `inspectCacheEntry` treats a marked entry as stale, so the
next setup rebuilds from declared metadata.

**Please look closely at the in-flight guard.** Setup installs through
`managePackages`, which fires this same event. Without the guard, every
setup would mark the environment it had just built and rebuild
endlessly. The guard relies on VS Code's `EventEmitter` being
synchronous, so a build still registered in `pendingCreations` is
recognised before any `await`; the check is repeated once the lock is
held.

**Known gaps, deliberately not addressed:** sharing is still not
surfaced before an edit; a deliberate ad-hoc install is discarded by the
next setup without explanation; package changes made outside VS Code
fire no event and remain undetected.

---

---------

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

Author: StellaHuang95

src/common/inlineScript/cacheLayout.ts

@@ -42,6 +42,8 @@ export interface InlineScriptEnvMeta {
     readonly baseInterpreterVersion: string;
     /** Last successful use as a canonical UTC string produced by `Date.toISOString()`. */
     readonly lastUsedAt: string;
+    /** Set when packages changed outside setup; the entry no longer matches its declared dependencies. */
+    readonly manuallyModified?: boolean;
     /** Bounded SHA-256 hashes of metadata identities proven for this cache entry. */
     readonly sourceMetadataIdentityHashes?: readonly string[];
 }
@@ -447,11 +449,7 @@ function validateMeta(value: unknown): InlineScriptEnvMeta | 'unsupported' | und
         return undefined;
     }
     const obj = value as Record<string, unknown>;
-    if (
-        typeof obj.schemaVersion !== 'number' ||
-        !Number.isSafeInteger(obj.schemaVersion) ||
-        obj.schemaVersion <= 0
-    ) {
+    if (typeof obj.schemaVersion !== 'number' || !Number.isSafeInteger(obj.schemaVersion) || obj.schemaVersion <= 0) {
         return undefined;
     }
     if (obj.schemaVersion > META_SCHEMA_VERSION) {
@@ -469,6 +467,9 @@ function validateMeta(value: unknown): InlineScriptEnvMeta | 'unsupported' | und
     if (!isCanonicalIsoTimestamp(obj.lastUsedAt)) {
         return undefined;
     }
+    if (obj.manuallyModified !== undefined && typeof obj.manuallyModified !== 'boolean') {
+        return undefined;
+    }
     const sourceMetadataIdentityHashes = validateSourceMetadataIdentityHashes(obj.sourceMetadataIdentityHashes);
     if (obj.sourceMetadataIdentityHashes !== undefined && sourceMetadataIdentityHashes === undefined) {
         return undefined;
@@ -479,6 +480,7 @@ function validateMeta(value: unknown): InlineScriptEnvMeta | 'unsupported' | und
         baseInterpreterPath: obj.baseInterpreterPath,
         baseInterpreterVersion: obj.baseInterpreterVersion,
         lastUsedAt: obj.lastUsedAt,
+        ...(obj.manuallyModified === true ? { manuallyModified: true } : {}),
         ...(sourceMetadataIdentityHashes ? { sourceMetadataIdentityHashes } : {}),
     };
 }

src/common/inlineScript/routingRegistry.ts

@@ -3,10 +3,10 @@
 
 import * as path from 'path';
 import { Disposable, Event, EventEmitter, Uri } from 'vscode';
+import type { InlineScriptEnvErrorCategory } from '../telemetry/constants';
+import { normalizePath } from '../utils/pathUtils';
 import { normalizeDependency } from './cacheKey';
 import { InlineScriptMetadata } from './metadata';
-import { normalizePath } from '../utils/pathUtils';
-import type { InlineScriptEnvErrorCategory } from '../telemetry/constants';
 
 export interface InlineScriptRouteabilityChangeEvent {
     readonly uri: Uri;
@@ -32,6 +32,7 @@ export type InlineScriptSetupOutcome =
           readonly category: InlineScriptEnvErrorCategory;
           readonly requiresPython?: string;
       }
+    | { readonly kind: 'cancelled' }
     | { readonly kind: 'skipped' };
 
 interface ScriptRoutingState {
@@ -150,6 +151,11 @@ export class InlineScriptRoutingRegistry implements Disposable {
         }
     }
 
+    public getSetupOutcome(script: Uri | string): InlineScriptSetupOutcome | undefined {
+        const scriptPath = getInlineScriptRoutingKey(script);
+        return scriptPath ? this.setupOutcomes.get(scriptPath) : undefined;
+    }
+
     public takeSetupOutcome(script: Uri | string): InlineScriptSetupOutcome | undefined {
         const scriptPath = getInlineScriptRoutingKey(script);
         if (!scriptPath) {

src/features/inlineScript/setupEnvironment.ts

@@ -75,6 +75,9 @@ export async function setUpInlineScriptEnvironment(
         return undefined;
     }
     await em.setEnvironment(scriptUri, environment);
+    // Outcomes are read non-consumingly, so a success must retire the previous attempt's outcome
+    // rather than relying on the next `create` to clear it on entry.
+    routing.clearSetupOutcome(scriptUri);
     return environment;
 }
 
@@ -124,12 +127,16 @@ function setupInlineScriptEnvironmentHandler(
     };
 }
 
-function notifyInlineScriptSetupOutcome(uri: Uri, routing: InlineScriptRoutingRegistry): void {
-    const outcome = routing.takeSetupOutcome(uri);
+export function notifyInlineScriptSetupOutcome(uri: Uri, routing: InlineScriptRoutingRegistry): void {
+    const outcome = routing.getSetupOutcome(uri);
     if (outcome?.kind === 'skipped') {
         // Env built but intentionally not associated (metadata changed mid-setup); stay silent.
         return;
     }
+    if (outcome?.kind === 'cancelled') {
+        showInformationMessage(l10n.t('Environment setup was canceled.'));
+        return;
+    }
     if (outcome?.kind === 'failed') {
         if (outcome.category === 'compatible-python-declined') {
             // User declined the install prompt; don't nag.
@@ -223,16 +230,57 @@ export async function setUpInlineScriptEnvironmentsInWorkspace(
         return;
     }
     let succeeded = 0;
+    let attempted = 0;
+    let failed = 0;
+    let cancelled = false;
     for (const pick of picks) {
+        attempted += 1;
         try {
             if (await setUpInlineScriptEnvironment(pick.uri, em, routing)) {
                 succeeded += 1;
+                continue;
+            }
+            const outcome = routing.getSetupOutcome(pick.uri);
+            if (outcome?.kind === 'cancelled') {
+                // Cancelling one script's installer stops the whole run rather than immediately
+                // starting the next script's install.
+                cancelled = true;
+                break;
+            }
+            if (outcome?.kind !== 'skipped') {
+                failed += 1;
             }
         } catch (error) {
+            failed += 1;
             traceError(`Failed to set up the inline-script environment for ${pick.uri.fsPath}:`, error);
         }
     }
-    traceInfo(`Inline-script bulk setup: created or reused ${succeeded} of ${picks.length} environment(s).`);
+    traceInfo(
+        `Inline-script bulk setup: created or reused ${succeeded} of ${picks.length} environment(s)` +
+            `${cancelled ? ' (canceled)' : ''}.`,
+    );
+    if (cancelled) {
+        showWarningMessage(
+            l10n.t(
+                'Environment setup was canceled. Set up {0} of {1} selected inline script environment(s); the remaining {2} were not started.',
+                succeeded,
+                picks.length,
+                picks.length - attempted,
+            ),
+        );
+        return;
+    }
+    if (failed > 0) {
+        showWarningMessage(
+            l10n.t(
+                'Set up {0} of {1} selected inline script environment(s). {2} failed — see the Python Environments output for details.',
+                succeeded,
+                picks.length,
+                failed,
+            ),
+        );
+        return;
+    }
     showInformationMessage(l10n.t('Set up {0} of {1} selected inline script environment(s).', succeeded, picks.length));
 }
 

src/features/terminal/shellStartupActivationVariablesManager.ts

@@ -48,21 +48,25 @@ export class ShellStartupActivationVariablesManagerImpl implements ShellStartupA
 
     private async handleEnvironmentChange(e: DidChangeEnvironmentEventArgs) {
         const autoActType = getAutoActivationType();
-        if (autoActType === ACT_TYPE_SHELL && e.uri) {
-            const wf = getWorkspaceFolder(e.uri);
-            if (wf) {
-                const envVars = this.envCollection.getScoped({ workspaceFolder: wf });
-                if (envVars) {
-                    this.shellEnvsProviders.forEach((provider) => {
-                        if (e.new) {
-                            provider.updateEnvVariables(envVars, e.new);
-                        } else {
-                            provider.removeEnvVariables(envVars);
-                        }
-                    });
-                }
-            }
+        if (autoActType !== ACT_TYPE_SHELL || !e.uri) {
+            return;
         }
+        const wf = getWorkspaceFolder(e.uri);
+        if (!wf) {
+            return;
+        }
+        const envVars = this.envCollection.getScoped({ workspaceFolder: wf });
+        if (!envVars) {
+            return;
+        }
+        const folderEnvironment = await this.api.getEnvironment(wf.uri);
+        this.shellEnvsProviders.forEach((provider) => {
+            if (folderEnvironment) {
+                provider.updateEnvVariables(envVars, folderEnvironment);
+            } else {
+                provider.removeEnvVariables(envVars);
+            }
+        });
     }
 
     private async initializeInternal(): Promise<void> {