Register PEP 723 scripts as exact projects (PEP 723 PR 10/16) (#1744)

> Part of #1602 (PEP 723 inline script env support). Design doc: #1601.

### Roadmap context

This is **PR 10 of 16** in the PEP 723 inline-script roadmap. PRs 7-9
persist, discover, validate, and route per-script environments; this PR
gives each configured script an exact project identity that survives
restart and can be consumed by per-file integrations.

| Phase 3 / integration | PR | Status |
|---|---|---|
| | PR 7: per-script persistence | merged (#1697) |
| | PR 8: activation-time discovery | merged (#1722) |
| | PR 9: automatic per-script routing | merged (#1729) |
| | **PR 10: exact script project registration** | **this PR** |
| | PRs 11-12: CodeLens and bulk setup UX | follow-up |
| | PR 17: Pylance per-file Python path |
[microsoft/pyrx#9265](microsoft/pyrx#9265) |
| | PR 19: Python extension per-file lookup |
[microsoft/vscode-python#26129](microsoft/vscode-python#26129)
|

### Why this PR

PR 9 can route a saved script to a validated inline environment, but the
project manager still identifies the script through its containing
workspace project. That prevents the per-file identity from surviving
restart consistently and leaves downstream configuration and
environment-change consumers without an exact script scope.

The registration also needs an ownership boundary: clearing inline
environments must remove entries created by the extension without
deleting user-authored project settings.

### What this PR does

- Registers an exact `pythonProjects` entry before binding an inline
environment.
- Stores the normal environment and package manager as the script's
fallback rather than replacing them with the inline manager.
- Marks extension-managed entries as either:
  - `created`: remove the entry during inline cleanup;
  - `adopted`: remove only the marker and preserve the user's entry.
- Ignores the managed fallback entry while a validated inline
association is routeable.
- Uses that entry normally when the feature is disabled or the
association becomes stale.
- Rolls back a newly prepared registration if inline association binding
fails.
- Supports single and batch script selection.
- Converts a managed entry into an ordinary user-owned entry when the
user explicitly selects a non-inline manager.
- Coordinates explicit managed selections with the dedicated clear-cache
operation.
- Resolves and updates same-named scripts correctly in multi-root
workspaces.

### Registration and cleanup semantics

| Condition | Behavior |
|---|---|
| No exact project entry exists | Create a marked entry containing the
ordinary fallback managers |
| An exact user entry exists | Temporarily mark it without changing its
manager choices |
| Inline binding fails | Roll back the marker/created entry and any
newly added in-memory project |
| Validated association exists | Route through the inline manager |
| Association is stale or unavailable | Use the stored fallback manager
|
| User selects a non-inline manager | Update the owning setting and
remove the managed marker |
| Clear Script Environment Cache | Remove created entries; restore
adopted entries |
| Two roots contain the same relative script path | Match using the
`workspace` discriminator |

### Performance and safety

- No workspace scan is introduced.
- Configuration writes occur only during explicit persisted selection,
rollback, manager changes, or dedicated cache cleanup.
- Serialization is limited to managed inline-script project mutations;
unrelated environment routing and refresh operations are not queued.
- User-owned project settings are never deleted by inline cleanup.

### User impact

The feature remains behind `python-envs.inlineScripts.enabled`. Existing
users and projects without a managed inline-script entry retain their
current manager-selection behavior. After setup, a script has a stable
exact project scope across reloads; when inline routing is unavailable,
its previous project/workspace environment remains the fallback.

### Tests

- `npm run compile-tests`
- `npm run compile`
- `npm run lint`
- Focused command, environment-manager, and settings tests: **92
passing**
- The full unit suite was also run. Six unchanged timing-sensitive
inline-manager tests failed only under full-suite load and passed
together in an isolated rerun.

### Scope and follow-up

This PR does not add the setup CodeLens, bulk setup command, TTL
eviction, or public feature enablement. Those remain in PRs 11, 12, and
14. Per-file language-service and debugger integration are handled by
the companion cross-repository PRs above.

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

Author: StellaHuang95

src/extension.ts

@@ -407,7 +407,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         ...(isInlineScriptsFeatureEnabled()
             ? [
                   commands.registerCommand('python-envs.clearScriptEnvCache', async () => {
-                      await clearScriptEnvironmentCacheCommand(envManagers, projectManager);
+                      await clearScriptEnvironmentCacheCommand(envManagers);
                   }),
               ]
             : []),

src/features/envCommands.ts

@@ -31,7 +31,6 @@ import {
     PythonProjectManager,
 } from '../internal.api';
 import {
-    removeInlineScriptPythonProjectSettings,
     removePythonProjectSetting,
     setEnvironmentManager,
     setPackageManager,
@@ -704,7 +703,6 @@ export async function clearEnvironmentCachesCommand(
 
 export async function clearScriptEnvironmentCacheCommand(
     em: EnvironmentManagers,
-    wm: PythonProjectManager,
 ): Promise<void> {
     const manager = em.getEnvironmentManager(INLINE_SCRIPT_MANAGER_ID);
     if (!manager || !manager.supportsClearCache()) {
@@ -725,11 +723,7 @@ export async function clearScriptEnvironmentCacheCommand(
         return;
     }
 
-    await manager.clearCache();
-    const loadedProjectsToRemove = await removeInlineScriptPythonProjectSettings(wm.getProjects());
-    if (loadedProjectsToRemove.length > 0) {
-        wm.remove(loadedProjectsToRemove);
-    }
+    await em.clearInlineScriptCache();
 }
 
 export async function getPackageCommandOptions(

src/features/envManagers.ts

@@ -1,3 +1,4 @@
+import * as path from 'path';
 import { ConfigurationTarget, Disposable, Event, EventEmitter, Uri, workspace } from 'vscode';
 import {
     DidChangeEnvironmentEventArgs,
@@ -43,7 +44,14 @@ import {
     EditAllManagerSettings,
     getDefaultEnvManagerSetting,
     getDefaultPkgManagerSetting,
+    getExactPythonProjectSetting,
+    getManagedInlineScriptProjectRegistration,
     getProjectEnvironmentManagerSetting,
+    InlineScriptPythonProjectRegistration,
+    registerInlineScriptPythonProjectSetting,
+    removeInlineScriptPythonProjectSettings,
+    removeManagedInlineScriptPythonProjectSetting,
+    rollbackInlineScriptPythonProjectSetting,
     setAllManagerSettings,
 } from './settings/settingHelpers';
 
@@ -73,6 +81,7 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
     private readonly _inlineRoutingOverrides = new Map<string, string>();
     private readonly _selectionRevisions = new Map<string, number>();
     private readonly _selectionOperationCounters = new Map<string, number>();
+    private inlineScriptProjectSelectionQueue: Promise<void> = Promise.resolve();
 
     private _onDidChangeEnvironmentManager = new EventEmitter<DidChangeEnvironmentManagerEventArgs>();
     private _onDidChangePackageManager = new EventEmitter<DidChangePackageManagerEventArgs>();
@@ -99,6 +108,15 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
     public onDidChangeActiveEnvironment: Event<DidChangeEnvironmentEventArgs> =
         this._onDidChangeActiveEnvironment.event;
 
+    private enqueueInlineScriptProjectSelection<T>(operation: () => Promise<T>): Promise<T> {
+        const run = this.inlineScriptProjectSelectionQueue.then(operation);
+        this.inlineScriptProjectSelectionQueue = run.then(
+            () => undefined,
+            () => undefined,
+        );
+        return run;
+    }
+
     constructor(
         private readonly pm: PythonProjectManager,
         private readonly inlineScriptRouting?: InlineScriptRoutingRegistry,
@@ -343,6 +361,20 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         }
     }
 
+    public clearInlineScriptCache(): Promise<void> {
+        return this.enqueueInlineScriptProjectSelection(async () => {
+            const manager = this._environmentManagers.get(INLINE_SCRIPT_MANAGER_ID);
+            if (!manager || !manager.supportsClearCache()) {
+                throw new Error('Inline-script environment manager is unavailable.');
+            }
+            await manager.clearCache();
+            const projectsToRemove = await removeInlineScriptPythonProjectSettings(this.pm.getProjects());
+            if (projectsToRemove.length > 0) {
+                this.pm.remove(projectsToRemove);
+            }
+        });
+    }
+
     /**
      * Sets the environment for a single scope, scope of undefined checks 'global'.
      * If given an array of scopes, delegates to setEnvironments for batch setting.
@@ -353,15 +385,27 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
      *   Pass `false` when setting environments during initial selection/auto-discovery
      *   to avoid writing to settings.json.
      */
-    public async setEnvironment(
+    public setEnvironment(
         scope: SetEnvironmentScope,
         environment?: PythonEnvironment,
         shouldPersistSettings: boolean = true,
     ): Promise<void> {
         if (Array.isArray(scope)) {
             return this.setEnvironments(scope, environment, shouldPersistSettings);
         }
+        if (this.shouldSerializeInlineScriptProjectSelection(scope, environment, shouldPersistSettings)) {
+            return this.enqueueInlineScriptProjectSelection(() =>
+                this.setEnvironmentCore(scope, environment, shouldPersistSettings),
+            );
+        }
+        return this.setEnvironmentCore(scope, environment, shouldPersistSettings);
+    }
 
+    private async setEnvironmentCore(
+        scope: Uri | undefined,
+        environment: PythonEnvironment | undefined,
+        shouldPersistSettings: boolean,
+    ): Promise<void> {
         const customScope = environment ? environment : scope;
         const manager = this.getEnvironmentManager(customScope);
         if (!manager) {
@@ -374,6 +418,10 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
             traceError(this.managers.map((m) => m.id).join(', '));
             return;
         }
+        const inlineRegistration =
+            scope && environment && manager.id === INLINE_SCRIPT_MANAGER_ID && shouldPersistSettings
+                ? await this.prepareInlineScriptProjectRegistration(scope)
+                : undefined;
         const project = scope ? this.pm.get(scope) : undefined;
         const key = this.getActiveSelectionKey(scope, manager, project);
         const operation = this.beginSelectionOperation(key);
@@ -393,7 +441,21 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
             this.inlineScriptRouting?.shouldRoute(scope)
                 ? this.beginSelectionOperation(this.getInlineScriptSelectionKey(scope))
                 : undefined;
-        await manager.set(scope, environment);
+        try {
+            await manager.set(scope, environment);
+        } catch (error) {
+            if (inlineRegistration) {
+                await this.rollbackInlineScriptProjectRegistration(inlineRegistration);
+            }
+            throw error;
+        }
+
+        if (scope && !environment && manager.id === INLINE_SCRIPT_MANAGER_ID && shouldPersistSettings && project) {
+            const removeProject = await removeManagedInlineScriptPythonProjectSetting(project);
+            if (removeProject) {
+                this.pm.remove(project);
+            }
+        }
 
         // Only persist to settings when explicitly requested
         if (shouldPersistSettings && scope) {
@@ -482,10 +544,23 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
      *   Pass `false` when setting environments during initial selection/auto-discovery
      *   to avoid writing to settings.json.
      */
-    public async setEnvironments(
+    public setEnvironments(
         scope: Uri[] | string,
         environment?: PythonEnvironment,
         shouldPersistSettings: boolean = true,
+    ): Promise<void> {
+        if (this.shouldSerializeInlineScriptProjectSelection(scope, environment, shouldPersistSettings)) {
+            return this.enqueueInlineScriptProjectSelection(() =>
+                this.setEnvironmentsCore(scope, environment, shouldPersistSettings),
+            );
+        }
+        return this.setEnvironmentsCore(scope, environment, shouldPersistSettings);
+    }
+
+    private async setEnvironmentsCore(
+        scope: Uri[] | string,
+        environment: PythonEnvironment | undefined,
+        shouldPersistSettings: boolean,
     ): Promise<void> {
         if (environment) {
             const manager = this.managers.find((m) => m.id === environment.envId.managerId);
@@ -502,8 +577,17 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
             const settings: EditAllManagerSettings[] = [];
             const events: DidChangeEnvironmentEventArgs[] = [];
             if (Array.isArray(scope) && scope.every((s) => s instanceof Uri)) {
+                const inlineRegistrations =
+                    manager.id === INLINE_SCRIPT_MANAGER_ID && shouldPersistSettings
+                        ? await this.prepareInlineScriptProjectRegistrations(scope)
+                        : [];
                 const selections = scope.map((uri) => this.beginPendingSelection(uri, manager));
-                await manager.set(scope, environment);
+                try {
+                    await manager.set(scope, environment);
+                } catch (error) {
+                    await this.rollbackInlineScriptProjectRegistrations(inlineRegistrations);
+                    throw error;
+                }
                 selections.forEach((selection) => {
                     const m = this.getEnvironmentManager(selection.scope);
                     // Always add settings when persisting, OR when manager differs
@@ -518,7 +602,7 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
                         });
                     }
                 });
-                if (shouldPersistSettings) {
+                if (shouldPersistSettings && settings.length > 0) {
                     await setAllManagerSettings(settings);
                 }
                 selections.forEach((selection) => {
@@ -601,6 +685,19 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
                     const events: DidChangeEnvironmentEventArgs[] = [];
                     const selections = uris.map((uri) => this.beginPendingSelection(uri, manager));
                     await manager.set(uris);
+                    if (manager.id === INLINE_SCRIPT_MANAGER_ID && shouldPersistSettings) {
+                        for (const selection of selections) {
+                            if (!selection.project) {
+                                continue;
+                            }
+                            const removeProject = await removeManagedInlineScriptPythonProjectSetting(
+                                selection.project,
+                            );
+                            if (removeProject) {
+                                this.pm.remove(selection.project);
+                            }
+                        }
+                    }
                     await Promise.all(
                         selections.map(async (selection) => {
                             const newEnv = await manager.get(selection.scope);
@@ -767,6 +864,10 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         if (!project || normalizePath(project.uri.fsPath) !== normalizePath(scope.fsPath)) {
             return undefined;
         }
+        const exactSetting = getExactPythonProjectSetting(this.pm, scope);
+        if (getManagedInlineScriptProjectRegistration(exactSetting)) {
+            return undefined;
+        }
         const exactManagerId = getProjectEnvironmentManagerSetting(this.pm, scope);
         return exactManagerId ? this._environmentManagers.get(exactManagerId) : undefined;
     }
@@ -977,16 +1078,99 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         );
     }
 
-    private canPersistManagerSettingForScope(
+    private shouldSerializeInlineScriptProjectSelection(
+        scope: SetEnvironmentScope | string,
+        environment: PythonEnvironment | undefined,
+        shouldPersistSettings: boolean,
+    ): boolean {
+        if (!shouldPersistSettings) {
+            return false;
+        }
+        if (environment?.envId.managerId === INLINE_SCRIPT_MANAGER_ID) {
+            return true;
+        }
+        const scopes = scope instanceof Uri ? [scope] : Array.isArray(scope) ? scope : [];
+        return scopes.some((uri) =>
+            getManagedInlineScriptProjectRegistration(getExactPythonProjectSetting(this.pm, uri)),
+        );
+    }
+
+    private async prepareInlineScriptProjectRegistration(
         scope: Uri,
+    ): Promise<PreparedInlineScriptProjectRegistration | undefined> {
+        const existingProject = this.pm.get(scope);
+        const hasExactProject =
+            existingProject !== undefined &&
+            normalizePath(existingProject.uri.fsPath) === normalizePath(scope.fsPath);
+        const project = hasExactProject
+            ? existingProject
+            : this.pm.create(path.basename(scope.fsPath) || scope.fsPath, scope);
+        const registration = await registerInlineScriptPythonProjectSetting(this.pm, project);
+        if (!registration) {
+            return undefined;
+        }
+
+        const addedProject = !hasExactProject;
+        try {
+            if (addedProject) {
+                await this.pm.add(project, { persistSettings: false });
+            }
+        } catch (error) {
+            const removeProject = await rollbackInlineScriptPythonProjectSetting(project, registration);
+            if (removeProject && addedProject) {
+                this.pm.remove(project);
+            }
+            throw error;
+        }
+        return { project, registration, addedProject };
+    }
+
+    private async prepareInlineScriptProjectRegistrations(
+        scopes: readonly Uri[],
+    ): Promise<PreparedInlineScriptProjectRegistration[]> {
+        const registrations: PreparedInlineScriptProjectRegistration[] = [];
+        try {
+            for (const scope of scopes) {
+                const registration = await this.prepareInlineScriptProjectRegistration(scope);
+                if (registration) {
+                    registrations.push(registration);
+                }
+            }
+            return registrations;
+        } catch (error) {
+            await this.rollbackInlineScriptProjectRegistrations(registrations);
+            throw error;
+        }
+    }
+
+    private async rollbackInlineScriptProjectRegistrations(
+        registrations: readonly PreparedInlineScriptProjectRegistration[],
+    ): Promise<void> {
+        for (const registration of [...registrations].reverse()) {
+            await this.rollbackInlineScriptProjectRegistration(registration);
+        }
+    }
+
+    private async rollbackInlineScriptProjectRegistration(
+        prepared: PreparedInlineScriptProjectRegistration,
+    ): Promise<void> {
+        const removeProject = await rollbackInlineScriptPythonProjectSetting(
+            prepared.project,
+            prepared.registration,
+        );
+        if (removeProject && prepared.addedProject) {
+            this.pm.remove(prepared.project);
+        }
+    }
+
+    private canPersistManagerSettingForScope(
+        _scope: Uri,
         manager: InternalEnvironmentManager,
-        project: PythonProject | undefined,
+        _project: PythonProject | undefined,
     ): boolean {
-        // Inline associations are per file; never promote one to its containing project's manager setting.
-        return (
-            manager.id !== INLINE_SCRIPT_MANAGER_ID ||
-            (!!project && normalizePath(project.uri.fsPath) === normalizePath(scope.fsPath))
-        );
+        // Inline associations are persisted by the inline manager. The managed exact-project entry
+        // stores the ordinary fallback manager rather than replacing it with the inline manager.
+        return manager.id !== INLINE_SCRIPT_MANAGER_ID;
     }
 
     private beginSelectionOperation(key: string): number {
@@ -1055,3 +1239,9 @@ interface PendingEnvironmentSelection {
     readonly publishInlineSelection: boolean;
     readonly inlineClearOperation: number | undefined;
 }
+
+interface PreparedInlineScriptProjectRegistration {
+    readonly project: PythonProject;
+    readonly registration: InlineScriptPythonProjectRegistration;
+    readonly addedProject: boolean;
+}

src/features/projectManager.ts

@@ -197,7 +197,10 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         return new PythonProjectsImpl(name, uri, options);
     }
 
-    async add(projects: PythonProject | ProjectArray): Promise<void> {
+    async add(
+        projects: PythonProject | ProjectArray,
+        options?: { persistSettings?: boolean },
+    ): Promise<void> {
         const _projects = Array.isArray(projects) ? projects : [projects];
         if (_projects.length === 0) {
             return;
@@ -228,7 +231,7 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         });
         this._onDidChangeProjects.fire(Array.from(this._projects.values()));
 
-        if (edits.length > 0) {
+        if (options?.persistSettings !== false && edits.length > 0) {
             await addPythonProjectSetting(edits);
         }
     }