feat: add triggerReason to pet.process_restart and globalScopeDeferred to setup.hang_detected

- pet.process_restart now emits triggerReason (process_exit:<code>:<signal>,
  process_error, rpc_connection_error, rpc_refresh_timeout, rpc_resolve_timeout,
  rpc_configure_timeout, start_failed, unknown) so we can distinguish crash
  restarts from timeout restarts in Kusto
- setup.hang_detected now emits globalScopeDeferred (true/false/undefined) so
  we can tell whether a watchdog trip was a real foreground hang or a background
  global-scope scan running past 120s after the user already had an env selected
- Updated GDPR declarations and TypeScript types in constants.ts for both events
- Thread globalScopeDeferredRef through applyInitialEnvironmentSelection so the
  hang watchdog can read the deferred flag before envSelection returns

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

Author: eleanorjboyd

src/common/telemetry/constants.ts

@@ -391,12 +391,15 @@ export interface IEventNamePropertyMapping {
     /* __GDPR__
         "setup.hang_detected": {
             "failureStage": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+            "globalScopeDeferred": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
             "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
             "<stageDuration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
         }
     */
     [EventNames.SETUP_HANG_DETECTED]: {
         failureStage: string;
+        /** Whether the global Python scope search was deferred to background at time of hang. undefined = hang fired before env-selection stage. */
+        globalScopeDeferred: boolean | undefined;
     };
 
     /* __GDPR__
@@ -549,13 +552,16 @@ export interface IEventNamePropertyMapping {
             "attempt": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },
             "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
             "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "triggerReason": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
             "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
         }
     */
     [EventNames.PET_PROCESS_RESTART]: {
         attempt: number;
         result: 'success' | 'error';
         errorType?: string;
+        /** Why the PET process needed restarting: process_exit:<code>:<signal>, process_error, rpc_connection_error, rpc_refresh_timeout, rpc_resolve_timeout, rpc_configure_timeout, start_failed, or unknown */
+        triggerReason: string;
     };
 
     /* __GDPR__

src/extension.ts

@@ -553,6 +553,9 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
     setImmediate(async () => {
         let failureStage = 'nativeFinder';
         const stageWatch = new StopWatch();
+        // Mutable ref so the hang watchdog can report whether global scope was deferred
+        // even if it fires mid-envSelection before applyInitialEnvironmentSelection returns.
+        const globalScopeDeferredRef: { value: boolean | undefined } = { value: undefined };
         // Watchdog: fires if setup hasn't completed within 120s, indicating a likely hang
         const SETUP_HANG_TIMEOUT_MS = 120_000;
         let hangWatchdogActive = true;
@@ -572,7 +575,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             sendTelemetryEvent(
                 EventNames.SETUP_HANG_DETECTED,
                 { duration: start.elapsedTime, stageDuration: stageWatch.elapsedTime },
-                { failureStage },
+                { failureStage, globalScopeDeferred: globalScopeDeferredRef.value },
             );
         }, SETUP_HANG_TIMEOUT_MS);
         context.subscriptions.push({ dispose: clearHangWatchdog });
@@ -618,7 +621,14 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
 
             failureStage = 'envSelection';
             stageWatch.reset();
-            await applyInitialEnvironmentSelection(envManagers, projectManager, nativeFinder, api, start.elapsedTime);
+            await applyInitialEnvironmentSelection(
+                envManagers,
+                projectManager,
+                nativeFinder,
+                api,
+                start.elapsedTime,
+                globalScopeDeferredRef,
+            );
 
             // Register manager-agnostic terminal watcher for package-modifying commands
             failureStage = 'terminalWatcher';

src/features/interpreterSelection.ts

@@ -284,6 +284,7 @@ export async function applyInitialEnvironmentSelection(
     nativeFinder: NativePythonFinder,
     api: PythonEnvironmentApi,
     activationToReadyDurationMs?: number,
+    globalScopeDeferredRef?: { value: boolean | undefined },
 ): Promise<void> {
     const folders = getWorkspaceFolders() ?? [];
     traceInfo(
@@ -377,6 +378,9 @@ export async function applyInitialEnvironmentSelection(
     if (workspaceFolderResolved) {
         // Defer global scope so it doesn't block post-selection startup.
         traceInfo('[interpreterSelection] Workspace env resolved, deferring global scope to background');
+        if (globalScopeDeferredRef) {
+            globalScopeDeferredRef.value = true;
+        }
         resolveGlobalScope()
             .then(async (globalErrors) => {
                 if (globalErrors.length > 0) {
@@ -386,6 +390,9 @@ export async function applyInitialEnvironmentSelection(
             .catch((err) => traceError(`[interpreterSelection] Background global scope resolution failed: ${err}`));
     } else {
         // No workspace folder resolved — global scope is the primary fallback, must await.
+        if (globalScopeDeferredRef) {
+            globalScopeDeferredRef.value = false;
+        }
         const globalErrors = await resolveGlobalScope();
         allErrors.push(...globalErrors);
     }

src/managers/common/nativePythonFinder.ts

@@ -237,6 +237,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
     private startFailed: boolean = false;
     private restartAttempts: number = 0;
     private isRestarting: boolean = false;
+    private processExitReason: string | undefined = undefined;
     private readonly configureRetry = new ConfigureRetryState();
 
     constructor(
@@ -279,6 +280,8 @@ class NativePythonFinderImpl implements NativePythonFinder {
                     this.outputChannel.warn(`[pet] Resolve request ${reason}, killing process for restart`);
                     this.killProcess();
                     this.processExited = true;
+                    this.processExitReason =
+                        ex instanceof rpc.ConnectionError ? 'rpc_connection_error' : 'rpc_resolve_timeout';
                 }
                 throw ex;
             }
@@ -339,6 +342,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
         this.isRestarting = true;
         this.restartAttempts++;
         const attempt = this.restartAttempts;
+        const triggerReason = this.processExitReason ?? (this.startFailed ? 'start_failed' : 'unknown');
 
         const backoffMs = RESTART_BACKOFF_BASE_MS * Math.pow(2, this.restartAttempts - 1);
         this.outputChannel.warn(
@@ -361,22 +365,27 @@ class NativePythonFinderImpl implements NativePythonFinder {
             // Reset state flags
             this.processExited = false;
             this.startFailed = false;
+            this.processExitReason = undefined;
             this.lastConfiguration = undefined; // Force reconfiguration
             this.configureRetry.reset();
 
             // Start fresh
             this.connection = this.start();
 
             this.outputChannel.info('[pet] Python Environment Tools restarted successfully');
-            sendTelemetryEvent(EventNames.PET_PROCESS_RESTART, sw.elapsedTime, { attempt, result: 'success' });
+            sendTelemetryEvent(EventNames.PET_PROCESS_RESTART, sw.elapsedTime, {
+                attempt,
+                result: 'success',
+                triggerReason,
+            });
 
             // Reset restart attempts on successful start (process didn't immediately fail)
             // We'll reset this only after a successful request completes
         } catch (ex) {
             sendTelemetryEvent(
                 EventNames.PET_PROCESS_RESTART,
                 sw.elapsedTime,
-                { attempt, result: 'error', errorType: classifyError(ex) },
+                { attempt, result: 'error', errorType: classifyError(ex), triggerReason },
                 ex instanceof Error ? ex : undefined,
             );
             this.outputChannel.error('[pet] Failed to restart Python Environment Tools:', ex);
@@ -520,15 +529,19 @@ class NativePythonFinderImpl implements NativePythonFinder {
             this.proc.on('exit', (code, signal) => {
                 this.processExited = true;
                 if (code !== 0) {
+                    this.processExitReason = `process_exit:${code ?? 'null'}:${signal ?? 'none'}`;
                     this.outputChannel.error(
                         `[pet] Python Environment Tools exited unexpectedly with code ${code}, signal ${signal}`,
                     );
+                } else {
+                    this.processExitReason = 'process_exit:0';
                 }
             });
 
             // Handle process errors (e.g., ENOENT if executable not found)
             this.proc.on('error', (err) => {
                 this.processExited = true;
+                this.processExitReason = 'process_error';
                 this.outputChannel.error('[pet] Process error:', err);
             });
 
@@ -626,6 +639,8 @@ class NativePythonFinderImpl implements NativePythonFinder {
                         // Kill and restart for retry
                         this.killProcess();
                         this.processExited = true;
+                        this.processExitReason =
+                            ex instanceof rpc.ConnectionError ? 'rpc_connection_error' : 'rpc_refresh_timeout';
                         continue;
                     }
                     // Final attempt failed
@@ -737,6 +752,8 @@ class NativePythonFinderImpl implements NativePythonFinder {
                 this.outputChannel.warn(`[pet] PET process ${reason}, killing for restart`);
                 this.killProcess();
                 this.processExited = true;
+                this.processExitReason =
+                    ex instanceof rpc.ConnectionError ? 'rpc_connection_error' : 'rpc_refresh_timeout';
             }
             this.outputChannel.error('[pet] Error refreshing', ex);
             throw ex;
@@ -806,6 +823,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
                     );
                     this.killProcess();
                     this.processExited = true;
+                    this.processExitReason = 'rpc_configure_timeout';
                 } else {
                     this.outputChannel.warn(
                         `[pet] Configure request timed out (attempt ${this.configureRetry.timeoutCount}/${MAX_CONFIGURE_TIMEOUTS_BEFORE_KILL}), ` +