refactor: trim PR scope to lock retirement, serialized clears, inline-key preservation

Reduce this PR's net diff versus its merge-base to only three logical changes:

- #3 atomic canonical lock retirement on release (src/common/lockfile.apis.ts)
- #6 serialized persistent-state clears (src/common/persistentState.ts)
- #7 generic Clear Cache preserves the inline association key
  (constants.ts, envCommands.ts, extension.ts, and an import-only change in
  the inline-script envManager)

Revert the other seven changes to the merge-base content:
- #1 root-generation nonce, #2 root/entry admission decoupling,
  #9 create-counting order (inline-script envManager)
- #4/#5 reclaim-side lock retirement + generation-specific inspection
  (keep only the minimal release-side companions inspect/reclaim need to
  stay correct: .release-* recognition and ENOENT-on-readdir tolerance)
- #8 workspace-root protection (settingHelpers)
- #10 typed ClearCacheNotSupported (envManagers, NotSupportedError)

Also revert the associated test changes for the removed items, keeping the
new persistentState suite (#6), the new Clear Environment Caches suite (#7),
and the release-side lock-retirement tests (#3).

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

Author: StellaHuang95

src/common/errors/NotSupportedError.ts

@@ -11,9 +11,3 @@ export class RemoveEnvironmentNotSupported extends BaseError {
         super('NotSupported', message);
     }
 }
-
-export class ClearCacheNotSupported extends BaseError {
-    constructor(message: string) {
-        super('NotSupported', message);
-    }
-}

src/common/lockfile.apis.ts

@@ -19,7 +19,6 @@ export interface AcquiredFileLock {
 export const FILE_LOCK_DIR_SUFFIX = '.lock';
 export const FILE_LOCK_OWNER_MARKER_PREFIX = 'owner-';
 export const FILE_LOCK_RETAINED_MARKER_PREFIX = 'retained-';
-export const FILE_LOCK_RECLAIM_MARKER_PREFIX = '.reclaim-';
 export const FILE_LOCK_RELEASE_MARKER_PREFIX = '.release-';
 export const FILE_LOCK_RETIRED_DIR_INFIX = '.retired-';
 /** Legacy retained marker. It remains recognizable but cannot be safely reclaimed. */
@@ -141,7 +140,7 @@ export async function inspectFileLock(filePath: string, options?: InspectFileLoc
 interface FileLockSnapshot {
     readonly state: FileLockState;
     readonly marker?: string;
-    readonly markerKind?: 'owner' | 'retained' | 'reclaim' | 'release';
+    readonly markerKind?: 'owner' | 'retained' | 'release';
     readonly generationMarker?: string;
 }
 
@@ -176,14 +175,12 @@ async function inspectFileLockSnapshot(
     }
     const ownerEntries = entries.filter((entry) => entry.startsWith(FILE_LOCK_OWNER_MARKER_PREFIX));
     const generationRetainedEntries = entries.filter((entry) => entry.startsWith(FILE_LOCK_RETAINED_MARKER_PREFIX));
-    const reclaimEntries = entries.filter((entry) => entry.startsWith(FILE_LOCK_RECLAIM_MARKER_PREFIX));
     const releaseEntries = entries.filter((entry) => entry.startsWith(FILE_LOCK_RELEASE_MARKER_PREFIX));
     const retainedEntries = entries.filter((entry) => entry === FILE_LOCK_RETAINED_MARKER);
     const unknownEntries = entries.filter(
         (entry) =>
             !entry.startsWith(FILE_LOCK_OWNER_MARKER_PREFIX) &&
             !entry.startsWith(FILE_LOCK_RETAINED_MARKER_PREFIX) &&
-            !entry.startsWith(FILE_LOCK_RECLAIM_MARKER_PREFIX) &&
             !entry.startsWith(FILE_LOCK_RELEASE_MARKER_PREFIX) &&
             entry !== FILE_LOCK_RETAINED_MARKER,
     );
@@ -192,13 +189,11 @@ async function inspectFileLockSnapshot(
         unknownEntries.length > 0 ||
         ownerEntries.length > 1 ||
         generationRetainedEntries.length > 1 ||
-        reclaimEntries.length > 1 ||
         releaseEntries.length > 1 ||
         retainedEntries.length > 1 ||
-        (retainedEntries.length === 1 &&
-            generationRetainedEntries.length + reclaimEntries.length + releaseEntries.length > 0) ||
+        (retainedEntries.length === 1 && generationRetainedEntries.length + releaseEntries.length > 0) ||
         (retainedEntries.length === 0 &&
-            ownerEntries.length + generationRetainedEntries.length + reclaimEntries.length + releaseEntries.length > 1)
+            ownerEntries.length + generationRetainedEntries.length + releaseEntries.length > 1)
     ) {
         return { state: 'malformed' };
     }
@@ -212,27 +207,6 @@ async function inspectFileLockSnapshot(
         }
         return { state: 'retained', marker: generationRetainedEntries[0], markerKind: 'retained' };
     }
-    if (reclaimEntries.length === 1) {
-        const reclaimMarker = parseTransitionMarker(reclaimEntries[0], FILE_LOCK_RECLAIM_MARKER_PREFIX);
-        if (!reclaimMarker) {
-            return { state: 'malformed' };
-        }
-        const liveness = await (options?.checkProcessLiveness ?? getProcessLiveness)(reclaimMarker.pid);
-        if (liveness === 'dead') {
-            return {
-                state: 'stale',
-                marker: reclaimEntries[0],
-                markerKind: 'reclaim',
-                generationMarker: reclaimMarker.generationMarker,
-            };
-        }
-        return {
-            state: liveness === 'live' ? 'held' : 'unavailable',
-            marker: reclaimEntries[0],
-            markerKind: 'reclaim',
-            generationMarker: reclaimMarker.generationMarker,
-        };
-    }
     if (releaseEntries.length === 1) {
         const releaseMarker = parseTransitionMarker(releaseEntries[0], FILE_LOCK_RELEASE_MARKER_PREFIX);
         if (!releaseMarker) {
@@ -269,7 +243,7 @@ async function inspectFileLockSnapshot(
 }
 
 /**
- * Claim the exact observed stale or retained generation, then atomically retire its canonical directory.
+ * Claim and remove the exact observed stale or retained generation without releasing the lock directory.
  */
 export async function reclaimFileLock(filePath: string, options?: InspectFileLockOptions): Promise<boolean> {
     const lockPath = getFileLockPath(filePath);
@@ -282,32 +256,29 @@ export async function reclaimFileLock(filePath: string, options?: InspectFileLoc
         return false;
     }
 
-    const generationMarker = snapshot.generationMarker ?? snapshot.marker;
-    const claimedMarkerName =
-        `${FILE_LOCK_RECLAIM_MARKER_PREFIX}${process.pid}-${crypto.randomBytes(16).toString('hex')}-${generationMarker}`;
-    const claimedMarker = path.join(lockPath, claimedMarkerName);
-    const observedMarker = path.join(lockPath, snapshot.marker);
+    const claimedMarker = path.join(
+        lockPath,
+        `.reclaim-${process.pid}-${crypto.randomBytes(16).toString('hex')}-${snapshot.marker}`,
+    );
     try {
-        await fsapi.rename(observedMarker, claimedMarker);
+        await fsapi.rename(path.join(lockPath, snapshot.marker), claimedMarker);
     } catch (error) {
         if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'EEXIST')) {
             return false;
         }
         throw error;
     }
 
-    const retiredPath = getRetiredLockPath(lockPath);
     try {
-        await retireCanonicalLockDirectory(lockPath, retiredPath);
+        await fsapi.unlink(claimedMarker);
+        await fsapi.rmdir(lockPath);
+        return true;
     } catch (error) {
-        await fsapi.rename(claimedMarker, observedMarker).catch(() => undefined);
         if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'ENOTEMPTY')) {
             return false;
         }
         throw error;
     }
-    await cleanupRetiredLock(retiredPath, claimedMarkerName);
-    return true;
 }
 
 export async function getProcessLiveness(pid: number): Promise<ProcessLiveness> {

src/features/envManagers.ts

@@ -15,7 +15,6 @@ import {
     EnvironmentManagerAlreadyRegisteredError,
     PackageManagerAlreadyRegisteredError,
 } from '../common/errors/AlreadyRegisteredError';
-import { ClearCacheNotSupported } from '../common/errors/NotSupportedError';
 import {
     InlineScriptRouteabilityChangeEvent,
     InlineScriptRoutingRegistry,
@@ -337,29 +336,12 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
             return;
         }
 
-        if (
-            scope === INLINE_SCRIPT_MANAGER_ID ||
-            (!(scope instanceof Uri) &&
-                typeof scope !== 'string' &&
-                scope.envId.managerId === INLINE_SCRIPT_MANAGER_ID)
-        ) {
-            this.throwInlineClearNotSupported();
-        }
         const manager = this.getEnvironmentManager(scope);
-        if (manager?.id === INLINE_SCRIPT_MANAGER_ID) {
-            this.throwInlineClearNotSupported();
-        }
-        if (manager) {
+        if (manager && manager.id !== INLINE_SCRIPT_MANAGER_ID) {
             await manager.clearCache();
         }
     }
 
-    private throwInlineClearNotSupported(): never {
-        throw new ClearCacheNotSupported(
-            `Clear Cache for ${INLINE_SCRIPT_MANAGER_ID} requires the dedicated inline-script cache lifecycle.`,
-        );
-    }
-
     /**
      * Sets the environment for a single scope, scope of undefined checks 'global'.
      * If given an array of scopes, delegates to setEnvironments for batch setting.

src/features/settings/settingHelpers.ts

@@ -635,13 +635,9 @@ export async function removeInlineScriptPythonProjectSettings(
 
     await Promise.all(promises);
 
-    const workspaceRootPaths = new Set(workspaceFolders.map((folder) => normalizePath(folder.uri.fsPath)));
     return Array.from(removedProjects.values())
         .map((project) => currentProjectsByUri.get(project.uri.toString()))
-        .filter(
-            (project): project is PythonProject =>
-                project !== undefined && !workspaceRootPaths.has(normalizePath(project.uri.fsPath)),
-        );
+        .filter((project): project is PythonProject => project !== undefined);
 }
 
 export async function addPythonProjectSetting(edits: EditProjectSettings[]): Promise<void> {