improvements from comments

Author: eleanorjboyd

docs/startup-flow.md

@@ -62,24 +62,25 @@ python environments extension begins activation
        → falls through to `await result.manager.get(scope)`
 
        **--- inner fork: fast path vs slow path (tryFastPathGet in fastPath.ts) ---**
-       three conditions checked:
+      Conditions checked before entering fast path:
          a. `_initialized` deferred is undefined (never created) OR has not yet completed
          b. scope is a `Uri` (not global/undefined)
-         c. a persisted env path exists in workspace state for this scope (folder Uri)
 
-       FAST PATH (run if above three conditions are true):
+         FAST PATH (background init kickoff + optional early return):
          **Race-condition safety (runs before any await):**
          1. if `_initialized` doesn't exist yet:
             - create deferred and **register immediately** via `setInitialized()` callback
             - this blocks concurrent callers from spawning duplicate background inits
-            - kick off `startBackgroundInit()` as fire-and-forget
+              - kick off `startBackgroundInit()` as fire-and-forget
+                 - this happens as soon as (a) and (b) are true, **even if** no persisted path exists
          2. get project fsPath: `getProjectFsPathForScope(api, scope)` 
             - prefers resolved project path if available, falls back to scope.fsPath
             - shared across all managers to avoid lambda duplication
-         3. read persisted path 
-         4. `resolve(persistedPath)` 
-            1. failure → see SLOW PATH
-            2. successful → return env immediately (background init continues in parallel)
+           3. read persisted path (only if scope is a `Uri`; may return undefined)
+           4. if a persisted path exists:
+              - attempt `resolve(persistedPath)`
+              - failure (no env, mismatched manager, etc.) → fall through to SLOW PATH
+              - success → return env immediately (background init continues in parallel)
          **Failure recovery (in startBackgroundInit error handler):**
          - if background init throws: `setInitialized(undefined)` — clear deferred so next `get()` call retries init
 

src/managers/common/fastPath.ts

@@ -66,15 +66,21 @@ export async function tryFastPathGet(opts: FastPathOptions): Promise<FastPathRes
         deferred = createDeferred<void>();
         opts.setInitialized(deferred);
         const deferredRef = deferred;
-        Promise.resolve(opts.startBackgroundInit()).then(
-            () => deferredRef.resolve(),
-            (err) => {
-                traceError(`[${opts.label}] Background initialization failed: ${err}`);
-                // Allow subsequent get()/initialize() calls to retry after a background init failure.
-                opts.setInitialized(undefined);
-                deferredRef.resolve();
-            },
-        );
+        try {
+            Promise.resolve(opts.startBackgroundInit()).then(
+                () => deferredRef.resolve(),
+                (err) => {
+                    traceError(`[${opts.label}] Background initialization failed:`, err);
+                    // Allow subsequent get()/initialize() calls to retry after a background init failure.
+                    opts.setInitialized(undefined);
+                    deferredRef.resolve();
+                },
+            );
+        } catch (syncErr) {
+            traceError(`[${opts.label}] Background initialization threw synchronously:`, syncErr);
+            opts.setInitialized(undefined);
+            deferredRef.resolve();
+        }
     }
 
     const fsPath = opts.getProjectFsPath(opts.scope);
@@ -87,9 +93,7 @@ export async function tryFastPathGet(opts: FastPathOptions): Promise<FastPathRes
                 return { env: resolved };
             }
         } catch (err) {
-            traceWarn(
-                `[${opts.label}] Fast path resolve failed for '${persistedPath}', falling back to full init: ${err}`,
-            );
+            traceWarn(`[${opts.label}] Fast path resolve failed for '${persistedPath}', falling back to full init:`, err);
         }
     }
 

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

@@ -187,4 +187,26 @@ suite('tryFastPathGet', () => {
 
         assert.ok(result, 'Should resolve successfully with Thenable init');
     });
+
+    test('synchronous background init failure resets initialized for retry', async () => {
+        const startBackgroundInit = sinon.stub().throws(new Error('init crashed sync'));
+        const { opts, setInitialized } = createOpts({ startBackgroundInit });
+        const result = await tryFastPathGet(opts);
+
+        assert.ok(result, 'Should still return resolved env even when background init throws synchronously');
+        assert.ok(
+            setInitialized.called,
+            'Should set initialized before attempting background init even when it throws synchronously',
+        );
+
+        // Allow any background init error handling to run.
+        await new Promise((resolve) => setImmediate(resolve));
+
+        const lastCallArg = setInitialized.lastCall.args[0] as unknown;
+        assert.strictEqual(
+            lastCallArg,
+            undefined,
+            'Should clear initialized after synchronous background init failure',
+        );
+    });
 });