fix: avoid spurious 'restart terminal' prompts on window reload

VS Code shows a 'restart terminal to apply environment variable changes'
prompt whenever an extension's EnvironmentVariableCollection differs from
what is already applied to running terminals. The previous No-Config
Debug activation flow called collection.clear() followed by replace() /
append() unconditionally, which VS Code always interprets as a change
even when the resulting values are byte-identical, so the prompt fired
on every window reload.

Refactor the activation to diff-aware helpers (applyReplaceIfChanged,
applyAppendIfChanged, deleteIfPresent) that only write to the collection
when the existing mutator's type, value, or options actually differ from
what we want. The hot path on a normal reload becomes a sequence of
no-op get() comparisons, so VS Code never observes a change and the
prompt no longer appears.

Additional notes:
* Compare normalized EnvironmentVariableMutatorOptions
  (applyAtProcessCreation / applyAtShellIntegration) so future options
  changes still trigger a write.
* When the Java Language Server cannot resolve a Java home, keep the
  previously stored VSCODE_JAVA_EXEC instead of deleting it, to avoid
  churn caused by transient startup failures.
* Explicitly clean up legacy keys (currently JAVA_TOOL_OPTIONS) that
  older versions of this extension used to set but no longer manage.
* Set a human-readable description on the collection so users can see
  the source in VS Code's environment variable UI.

Fixes #1647

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

Author: Copilot

src/envVarSync.ts

@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+import * as vscode from "vscode";
+
+/**
+ * Helpers that update a {@link vscode.EnvironmentVariableCollection} only when
+ * the resulting mutation would actually change the collection.
+ *
+ * Background: VS Code shows a "Restart terminal to apply environment variable
+ * changes" prompt whenever an extension's collection differs from what has
+ * already been applied to running terminals. Calling `replace()` / `append()`
+ * with the same value, or calling `clear()` followed by re-adding identical
+ * entries, still counts as a change and re-triggers the prompt on every
+ * window reload. See issue #1647.
+ *
+ * These helpers compare the existing mutator (type + value + options) against
+ * the desired one and skip the write entirely when they match.
+ */
+
+const DEFAULT_OPTIONS: Required<vscode.EnvironmentVariableMutatorOptions> = {
+    applyAtProcessCreation: true,
+    applyAtShellIntegration: false,
+};
+
+function normalizeOptions(
+    options?: vscode.EnvironmentVariableMutatorOptions,
+): Required<vscode.EnvironmentVariableMutatorOptions> {
+    return { ...DEFAULT_OPTIONS, ...options };
+}
+
+function sameOptions(
+    existing: vscode.EnvironmentVariableMutator,
+    desired?: vscode.EnvironmentVariableMutatorOptions,
+): boolean {
+    const e = normalizeOptions(existing.options);
+    const d = normalizeOptions(desired);
+    return e.applyAtProcessCreation === d.applyAtProcessCreation
+        && e.applyAtShellIntegration === d.applyAtShellIntegration;
+}
+
+/**
+ * Calls `collection.replace(variable, value, options)` only when the existing
+ * mutator (if any) does not already match.
+ *
+ * @returns `true` if the collection was actually written to.
+ */
+export function applyReplaceIfChanged(
+    collection: vscode.EnvironmentVariableCollection,
+    variable: string,
+    value: string,
+    options?: vscode.EnvironmentVariableMutatorOptions,
+): boolean {
+    const existing = collection.get(variable);
+    if (existing
+        && existing.type === vscode.EnvironmentVariableMutatorType.Replace
+        && existing.value === value
+        && sameOptions(existing, options)) {
+        return false;
+    }
+    if (options) {
+        collection.replace(variable, value, options);
+    } else {
+        collection.replace(variable, value);
+    }
+    return true;
+}
+
+/**
+ * Calls `collection.append(variable, value, options)` only when the existing
+ * mutator (if any) does not already match.
+ *
+ * @returns `true` if the collection was actually written to.
+ */
+export function applyAppendIfChanged(
+    collection: vscode.EnvironmentVariableCollection,
+    variable: string,
+    value: string,
+    options?: vscode.EnvironmentVariableMutatorOptions,
+): boolean {
+    const existing = collection.get(variable);
+    if (existing
+        && existing.type === vscode.EnvironmentVariableMutatorType.Append
+        && existing.value === value
+        && sameOptions(existing, options)) {
+        return false;
+    }
+    if (options) {
+        collection.append(variable, value, options);
+    } else {
+        collection.append(variable, value);
+    }
+    return true;
+}
+
+/**
+ * Deletes the mutator for `variable` only when one is currently present.
+ *
+ * @returns `true` if a mutator was deleted.
+ */
+export function deleteIfPresent(
+    collection: vscode.EnvironmentVariableCollection,
+    variable: string,
+): boolean {
+    if (collection.get(variable)) {
+        collection.delete(variable);
+        return true;
+    }
+    return false;
+}

src/noConfigDebugInit.ts

@@ -9,6 +9,14 @@ import * as vscode from 'vscode';
 import { sendInfo, sendError } from "vscode-extension-telemetry-wrapper";
 import { getJavaHome } from "./utility";
 import { buildNoConfigPathAppendValue } from "./pathUtil";
+import { applyAppendIfChanged, applyReplaceIfChanged, deleteIfPresent } from "./envVarSync";
+
+// Environment variables that older versions of this extension contributed but
+// no longer manage. They are cleaned up explicitly on activation so they do
+// not linger in the persistent EnvironmentVariableCollection. See issue #1647.
+const LEGACY_ENV_VARS = ["JAVA_TOOL_OPTIONS"];
+
+const ENV_VAR_COLLECTION_DESCRIPTION = "Java No-Config Debug";
 
 /**
  * Registers the configuration-less debugging setup for the extension.
@@ -21,7 +29,7 @@ import { buildNoConfigPathAppendValue } from "./pathUtil";
  *
  * Environment Variables:
  * - `VSCODE_JDWP_ADAPTER_ENDPOINTS`: Path to the file containing the debugger adapter endpoint.
- * - `JAVA_TOOL_OPTIONS`: JDWP configuration for automatic debugging.
+ * - `VSCODE_JAVA_EXEC`: Path to the java executable from the Java Language Server (when available).
  * - `PATH`: Appends the path to the noConfigScripts directory.
  */
 export async function registerNoConfigDebug(
@@ -69,30 +77,46 @@ export async function registerNoConfigDebug(
         }
     }
 
-    // clear the env var collection to remove any existing env vars
-    collection.clear();
+    // Surface a description in VS Code's environment variable UI so users can
+    // see which extension is contributing these variables.
+    if (collection.description !== ENV_VAR_COLLECTION_DESCRIPTION) {
+        collection.description = ENV_VAR_COLLECTION_DESCRIPTION;
+    }
+
+    // Remove any variables that older versions of this extension used to set
+    // but no longer manage. Doing this idempotently (only when present) keeps
+    // subsequent reloads from triggering the "restart terminal" prompt.
+    for (const legacy of LEGACY_ENV_VARS) {
+        deleteIfPresent(collection, legacy);
+    }
 
-    // Add env var for VSCODE_JDWP_ADAPTER_ENDPOINTS
+    // Apply our managed variables using diff-aware helpers. On a typical
+    // window reload the values are unchanged and these calls are no-ops, so
+    // VS Code does not prompt the user to restart their existing terminals.
+    // See issue #1647.
+    //
     // Note: We do NOT set JAVA_TOOL_OPTIONS globally to avoid affecting all Java processes
     // (javac, maven, gradle, language server, etc.). Instead, JAVA_TOOL_OPTIONS is set
     // only in the debugjava wrapper scripts (debugjava.ps1, debugjava.bat, debugjava)
-    collection.replace('VSCODE_JDWP_ADAPTER_ENDPOINTS', tempFilePath);
+    applyReplaceIfChanged(collection, 'VSCODE_JDWP_ADAPTER_ENDPOINTS', tempFilePath);
 
     // Try to get Java executable from Java Language Server
-    // This ensures we use the same Java version as the project is compiled with
+    // This ensures we use the same Java version as the project is compiled with.
+    // If detection fails or returns nothing, we deliberately keep any previously
+    // set VSCODE_JAVA_EXEC to avoid churn from transient startup failures.
     try {
         const javaHome = await getJavaHome();
         if (javaHome) {
             const javaExec = path.join(javaHome, 'bin', 'java');
-            collection.replace('VSCODE_JAVA_EXEC', javaExec);
+            applyReplaceIfChanged(collection, 'VSCODE_JAVA_EXEC', javaExec);
         }
     } catch (error) {
         // If we can't get Java from Language Server, that's okay
         // The wrapper script will fall back to JAVA_HOME or PATH
     }
 
     const noConfigScriptsDir = path.join(extPath, 'bundled', 'scripts', 'noConfigScripts');
-    collection.append('PATH', buildNoConfigPathAppendValue(noConfigScriptsDir));
+    applyAppendIfChanged(collection, 'PATH', buildNoConfigPathAppendValue(noConfigScriptsDir));
 
     // create file system watcher for the debuggerAdapterEndpointFolder for when the communication port is written
     const fileSystemWatcher = vscode.workspace.createFileSystemWatcher(