Keep launch-configuration AppHost targets out of the workspace default

extension/src/dcp/types.ts

@@ -1,5 +1,6 @@
 import * as vscode from 'vscode';
 import type { AspireDebugSession, DashboardLaunchBehavior } from '../debugger/AspireDebugSession';
+import { appHostSelectionOriginConfigKey, type AppHostSelectionOrigin } from '../debugger/AspireDebugConfigurationMetadata';
 
 export interface ErrorResponse {
     error: ErrorDetails;
@@ -209,6 +210,7 @@ export interface AspireExtendedDebugConfiguration extends vscode.DebugConfigurat
     step?: string;
     skipCliAvailabilityCheck?: boolean;
     env?: { [key: string]: string };
+    [appHostSelectionOriginConfigKey]?: AppHostSelectionOrigin;
 }
 
 interface AspireDebuggersConfiguration {

extension/src/debugger/AspireDebugConfigurationMetadata.ts

@@ -1 +1,15 @@
 export const appHostTelemetryTargetPathConfigKey = '__aspireAppHostTelemetryTargetPath';
+
+// This internal field survives VS Code's two debug-configuration resolver stages so the
+// eventual CLI process can distinguish a launch.json-owned target from a persisted default.
+export const appHostSelectionOriginConfigKey = '__aspireAppHostSelectionOrigin';
+
+/**
+ * Who chose the AppHost this session launches.
+ *
+ * The CLI decides from this value whether the target may become the workspace default recorded in
+ * `aspire.config.json`. `user-selection` and `default-discovery` are statements about the project;
+ * `explicit-launch-configuration` (a `launch.json` entry naming a specific target) is scoped to the
+ * one invocation and must never replace a default the user already has.
+ */
+export type AppHostSelectionOrigin = 'explicit-launch-configuration' | 'default-discovery' | 'user-selection';

extension/src/debugger/AspireDebugConfigurationProvider.ts

@@ -1,14 +1,21 @@
 import * as vscode from 'vscode';
 import { defaultConfigurationName } from '../loc/strings';
 import type { AspireExtendedDebugConfiguration } from '../dcp/types';
-import { AppHostDiscoveryService, getDebugTargetForCandidate } from '../utils/appHostDiscovery';
+import { AppHostDiscoveryService, getDebugTargetForCandidate, isSamePath } from '../utils/appHostDiscovery';
 import type { CandidateAppHostDisplayInfo } from '../utils/appHostDiscovery';
 import { checkCliAvailableOrRedirect } from '../utils/workspace';
 import { extensionLogOutputChannel } from '../utils/logging';
-import { appHostTelemetryTargetPathConfigKey } from './AspireDebugConfigurationMetadata';
+import { appHostSelectionOriginConfigKey, appHostTelemetryTargetPathConfigKey } from './AspireDebugConfigurationMetadata';
 
 export class AspireDebugConfigurationProvider implements vscode.DebugConfigurationProvider {
-    constructor(private readonly _appHostDiscoveryService: AppHostDiscoveryService) {
+    constructor(
+        private readonly _appHostDiscoveryService: AppHostDiscoveryService,
+        // VS Code writes the configurations returned by an `Initial`-kind provider verbatim into a
+        // newly created launch.json, while `Dynamic`-kind configurations stay ephemeral. Only the
+        // ephemeral ones may carry the internal selection-origin marker: persisting it would bake a
+        // stale provenance into a user-owned file and permanently defeat the launch-configuration
+        // scoping this marker exists to enable. See https://github.com/microsoft/aspire/issues/19080.
+        private readonly _triggerKind: vscode.DebugConfigurationProviderTriggerKind = vscode.DebugConfigurationProviderTriggerKind.Dynamic) {
     }
 
     async provideDebugConfigurations(folder: vscode.WorkspaceFolder | undefined, token?: vscode.CancellationToken): Promise<vscode.DebugConfiguration[]> {
@@ -31,16 +38,17 @@ export class AspireDebugConfigurationProvider implements vscode.DebugConfigurati
             return [this.createDefaultConfiguration(folder)];
         }
 
-        return [{
+        return [this.withProvidedSelectionOrigin({
             type: 'aspire',
             request: 'launch',
             name: defaultConfigurationName,
-            program: getDebugTargetForCandidate(candidate)
-        }];
+            program: getDebugTargetForCandidate(candidate),
+        })];
     }
 
     async resolveDebugConfiguration(folder: vscode.WorkspaceFolder | undefined, config: vscode.DebugConfiguration, token?: vscode.CancellationToken): Promise<vscode.DebugConfiguration | null | undefined> {
         const aspireConfig = config as AspireExtendedDebugConfiguration;
+        this.ensureAppHostSelectionOrigin(aspireConfig);
         if (!aspireConfig.skipCliAvailabilityCheck) {
             const result = await checkCliAvailableOrRedirect('debug_gate');
             if (!result.available) {
@@ -69,10 +77,19 @@ export class AspireDebugConfigurationProvider implements vscode.DebugConfigurati
 
     async resolveDebugConfigurationWithSubstitutedVariables(folder: vscode.WorkspaceFolder | undefined, config: vscode.DebugConfiguration, token?: vscode.CancellationToken): Promise<vscode.DebugConfiguration | null | undefined> {
         const aspireConfig = config as AspireExtendedDebugConfiguration;
+        this.ensureAppHostSelectionOrigin(aspireConfig);
         delete aspireConfig.skipCliAvailabilityCheck;
 
         if (typeof config.program === 'string') {
             const program = config.program;
+            if (aspireConfig[appHostSelectionOriginConfigKey] === 'explicit-launch-configuration' && this.isWorkspaceFolderRoot(program, folder)) {
+                // Only a program pointing at the workspace folder root delegates the choice back to
+                // normal discovery, which is what the extension's own default configuration does. A
+                // configuration naming a specific AppHost file *or* subdirectory is scoped to that
+                // target and must not become the workspace default.
+                aspireConfig[appHostSelectionOriginConfigKey] = 'default-discovery';
+            }
+
             config.program = await this.resolveDebugTarget(program, folder);
 
             const telemetryTarget = await this.tryFindWorkspaceDefaultCandidate(program, folder);
@@ -118,11 +135,37 @@ export class AspireDebugConfigurationProvider implements vscode.DebugConfigurati
     }
 
     private createDefaultConfiguration(folder: vscode.WorkspaceFolder): vscode.DebugConfiguration {
-        return {
+        return this.withProvidedSelectionOrigin({
             type: 'aspire',
             request: 'launch',
             name: defaultConfigurationName,
-            program: folder.uri.fsPath
-        };
+            program: folder.uri.fsPath,
+        });
+    }
+
+    private withProvidedSelectionOrigin(config: vscode.DebugConfiguration): vscode.DebugConfiguration {
+        if (this._triggerKind !== vscode.DebugConfigurationProviderTriggerKind.Dynamic) {
+            // Leave the marker off so resolve-time classification runs against whatever the user
+            // ends up with in launch.json rather than against provenance frozen at creation time.
+            return config;
+        }
+
+        return { ...config, [appHostSelectionOriginConfigKey]: 'default-discovery' };
+    }
+
+    private isWorkspaceFolderRoot(program: string, folder: vscode.WorkspaceFolder | undefined): boolean {
+        const owningFolder = folder ?? vscode.workspace.getWorkspaceFolder(vscode.Uri.file(program));
+
+        return owningFolder !== undefined && isSamePath(program, owningFolder.uri.fsPath);
+    }
+
+    private ensureAppHostSelectionOrigin(config: AspireExtendedDebugConfiguration): void {
+        if (config[appHostSelectionOriginConfigKey]) {
+            return;
+        }
+
+        config[appHostSelectionOriginConfigKey] = config.program
+            ? 'explicit-launch-configuration'
+            : 'default-discovery';
     }
 }

extension/src/debugger/AspireDebugSession.ts

@@ -25,7 +25,7 @@ import { classifyAppHostPath, classifyAppHostDirectory } from "../utils/appHostL
 import { bucketAspireCommand } from "../utils/telemetryBuckets";
 import { getAppHostTargetVersion } from "../utils/appHostTargetVersion";
 import type { AspireDebugConsoleOutputEvent } from "../types/extensionApi";
-import { appHostTelemetryTargetPathConfigKey } from "./AspireDebugConfigurationMetadata";
+import { appHostSelectionOriginConfigKey, appHostTelemetryTargetPathConfigKey } from "./AspireDebugConfigurationMetadata";
 
 export type DashboardLaunchBehavior = 'none' | 'notification' | DashboardBrowserType;
 export type DashboardBrowserType = 'openExternalBrowser' | 'integratedBrowser' | 'debugChrome' | 'debugEdge' | 'debugFirefox';
@@ -236,6 +236,7 @@ export class AspireDebugSession implements vscode.DebugAdapter {
     const appHostTelemetryTargetPath = typeof this._session.configuration[appHostTelemetryTargetPathConfigKey] === 'string'
       ? this._session.configuration[appHostTelemetryTargetPathConfigKey]
       : undefined;
+    const appHostSelectionOrigin = this.configuration[appHostSelectionOriginConfigKey];
     const extensionArgs: string[] = [];
     // Telemetry: emit `debug/apphost/start` once per AppHost launch. This must
     // happen before any awaited filesystem metadata work because child
@@ -307,13 +308,13 @@ export class AspireDebugSession implements vscode.DebugAdapter {
     if (appHostIsDirectory) {
       this.sendMessageWithEmoji("📁", launchingWithDirectory(sessionType, appHostPath));
 
-      void this.spawnAspireCommand(args, appHostPath, noDebug, commandLabel);
+      void this.spawnAspireCommand(args, appHostPath, noDebug, commandLabel, this.getAppHostSelectionOriginEnvironment(appHostSelectionOrigin));
     }
     else {
       this.sendMessageWithEmoji("📂", launchingWithAppHost(sessionType, appHostPath));
 
       const workspaceFolder = path.dirname(appHostPath);
-      void this.spawnAspireCommand(args, workspaceFolder, noDebug, commandLabel);
+      void this.spawnAspireCommand(args, workspaceFolder, noDebug, commandLabel, this.getAppHostSelectionOriginEnvironment(appHostSelectionOrigin));
     }
   }
 
@@ -355,7 +356,13 @@ export class AspireDebugSession implements vscode.DebugAdapter {
     return this._appHostTargetVersionAtLaunch;
   }
 
-  async spawnAspireCommand(args: string[], workingDirectory: string | undefined, noDebug: boolean, commandLabel: string = 'aspire run') {
+  private getAppHostSelectionOriginEnvironment(selectionOrigin: AspireExtendedDebugConfiguration[typeof appHostSelectionOriginConfigKey]): EnvVar[] | undefined {
+    return selectionOrigin
+      ? [{ name: EnvironmentVariables.ASPIRE_CLI_APPHOST_SELECTION_ORIGIN, value: selectionOrigin }]
+      : undefined;
+  }
+
+  async spawnAspireCommand(args: string[], workingDirectory: string | undefined, noDebug: boolean, commandLabel: string = 'aspire run', internalEnv?: EnvVar[]) {
     const disposable = this._rpcServer.onNewConnection((client: ICliRpcClient) => {
       if (client.debugSessionId === this.debugSessionId) {
         this._rpcClient = client;
@@ -366,7 +373,10 @@ export class AspireDebugSession implements vscode.DebugAdapter {
     const configuredEnv = this.configuration.env;
     const env = configuredEnv
       ? Object.entries(configuredEnv).map(([name, value]) => ({ name, value: String(value) }))
-      : undefined;
+      : [];
+    if (internalEnv) {
+      env.push(...internalEnv);
+    }
 
     // Per-stream line buffers. CLI stdio chunks aren't guaranteed to arrive aligned to line
     // boundaries; without buffering, partial lines (and split-point ANSI sequences) would be
@@ -429,7 +439,7 @@ export class AspireDebugSession implements vscode.DebugAdapter {
         workingDirectory: workingDirectory,
         debugSessionId: this.debugSessionId,
         noDebug: noDebug,
-        env: env
+        env: env.length > 0 ? env : undefined
       },
     );
 

extension/src/extension.ts

@@ -345,12 +345,13 @@ export async function activate(context: vscode.ExtensionContext) {
   context.subscriptions.push(cliUpdateCommandRegistration, cliUpdateSelfCommandRegistration, settingsCommandRegistration, openLocalSettingsCommandRegistration, openGlobalSettingsCommandRegistration, runAppHostCommandRegistration, debugAppHostCommandRegistration);
   context.subscriptions.push(installCliRegistration, verifyCliInstalledRegistration);
 
-  const debugConfigProvider = new AspireDebugConfigurationProvider(appHostDiscoveryService);
+  const dynamicDebugConfigProvider = new AspireDebugConfigurationProvider(appHostDiscoveryService, vscode.DebugConfigurationProviderTriggerKind.Dynamic);
+  const initialDebugConfigProvider = new AspireDebugConfigurationProvider(appHostDiscoveryService, vscode.DebugConfigurationProviderTriggerKind.Initial);
   context.subscriptions.push(
-    vscode.debug.registerDebugConfigurationProvider('aspire', debugConfigProvider, vscode.DebugConfigurationProviderTriggerKind.Dynamic)
+    vscode.debug.registerDebugConfigurationProvider('aspire', dynamicDebugConfigProvider, vscode.DebugConfigurationProviderTriggerKind.Dynamic)
   );
   context.subscriptions.push(
-    vscode.debug.registerDebugConfigurationProvider('aspire', debugConfigProvider, vscode.DebugConfigurationProviderTriggerKind.Initial)
+    vscode.debug.registerDebugConfigurationProvider('aspire', initialDebugConfigProvider, vscode.DebugConfigurationProviderTriggerKind.Initial)
   );
 
   context.subscriptions.push(vscode.debug.registerDebugAdapterDescriptorFactory('aspire', new AspireDebugAdapterDescriptorFactory(rpcServer, dcpServer, terminalProvider, aspireExtensionContext.addAspireDebugSession.bind(aspireExtensionContext), aspireExtensionContext.removeAspireDebugSession.bind(aspireExtensionContext))));
@@ -363,7 +364,7 @@ export async function activate(context: vscode.ExtensionContext) {
     getAspireDebugSession: aspireExtensionContext.getAspireDebugSession.bind(aspireExtensionContext),
   }));
 
-  aspireExtensionContext.initialize(rpcServer, context, debugConfigProvider, dcpServer, terminalProvider, editorCommandProvider);
+  aspireExtensionContext.initialize(rpcServer, context, dynamicDebugConfigProvider, dcpServer, terminalProvider, editorCommandProvider);
 
   // Register Aspire MCP server definition provider so the Aspire MCP server
   // appears automatically in VS Code's MCP tools list for Aspire workspaces.

extension/src/server/interactionService.ts

@@ -11,6 +11,7 @@ import { AspireExtendedDebugConfiguration, EnvVar } from '../dcp/types';
 import { AnsiColors } from '../utils/AspireTerminalProvider';
 import { AspireDebugSession } from '../debugger/AspireDebugSession';
 import type { DashboardLaunchBehavior } from '../debugger/AspireDebugSession';
+import { appHostSelectionOriginConfigKey } from '../debugger/AspireDebugConfigurationMetadata';
 import { isDirectory } from '../utils/io';
 import { sendTelemetryEvent } from '../utils/telemetry';
 import { dashboardDefaultChangedNotificationKey } from '../utils/dashboardNotificationState';
@@ -674,6 +675,7 @@ export class InteractionService implements IInteractionService {
             command: command as AspireExtendedDebugConfiguration['command'],
             args: options?.args,
             noDebug: !debug,
+            [appHostSelectionOriginConfigKey]: projectFile ? 'user-selection' : 'default-discovery',
         };
 
         const workspaceFolder = vscode.workspace.getWorkspaceFolder(vscode.Uri.file(workingDirectory));

extension/src/services/AppHostLaunchService.ts

@@ -2,6 +2,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import * as vscode from 'vscode';
 import { AspireCommandType, AspireExtendedDebugConfiguration } from '../dcp/types';
+import { appHostSelectionOriginConfigKey } from '../debugger/AspireDebugConfigurationMetadata';
 import { startDebuggingDeclined } from '../loc/strings';
 import { classifyAppHostDirectory, classifyAppHostPath } from '../utils/appHostLanguage';
 import { classifyError, isCommandCancellation, sendTelemetryEvent, type EventProperties } from '../utils/telemetry';
@@ -148,7 +149,8 @@ export class AppHostLaunchService implements vscode.Disposable {
             request: 'launch',
             program: appHostPath,
             command,
-            noDebug
+            noDebug,
+            [appHostSelectionOriginConfigKey]: 'user-selection',
         };
 
         if (doStep) {