Stop the Aspire CLI and own its RPC connections during extension deactivation

[Adam Ratzman (adamint)]

Description

Split out of #19124, which combined notification presentation with extension shutdown/lifecycle hardening. This branch now contains only the shutdown work.

Extension deactivation was fire-and-forget: deactivate() returned void, so VS Code did not wait for CLI stop requests and closing a window could leave aspire run processes alive. RPC connections still inside the debug-session handshake were not owned by the server, and late status updates could repaint progress after transport disposal.

The extension now has one bounded shutdown path:

• deactivate() returns AspireExtensionContext.deactivate() so VS Code can await it.
• The context stops every live or newly registered session, waits up to five seconds, then force-cleans remaining owned processes and transports.
• Debug sessions reuse in-flight CLI stop requests, wait for a late RPC client when needed, and prevent a CLI from spawning after shutdown starts.
• Long-lived POSIX CLI launches own a process group; Windows cleanup avoids targeting an exited/reused leader PID.
• AspireRpcServer owns connections from creation, including pending handshakes, and rejects connections added after disposal.
• RPC clients and interaction services dispose idempotently and ignore late status updates.

The E2E now starts a real AppHost through the generated VSIX and repo CLI, records the owned CLI and AppHost process IDs, invokes the process-owner cleanup path while keeping the extension host alive, and verifies both processes and the AppHost/debug-session state stop.

Verification

corepack yarn --silent compile-tests
corepack yarn --silent compile-e2e
corepack yarn --silent unit-test --grep "AspireExtensionContext|AspireDebugSession tests|CLI process termination|spawnCliProcess tests|AspireRpcServer|InteractionService endpoints"

  122 passing
  1 pending

Additional exact-head proof:

• Pending RPC/handshake boundary: 9 passing
• Focused edgeCases.e2e.test.js: 5/5 passing against the generated VSIX and repo CLI
• Exported deactivate() wiring: focused unit coverage verifies VS Code receives the context shutdown promise
• Real process-owner cleanup E2E: 1/1 passing; owned CLI and AppHost processes terminated and extension state returned to no running AppHost/debug sessions
• Windows process-tree behavior remains unit-tested; the real process-owner cleanup proof ran on macOS

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19152

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19152"

[Copilot]

Pull request overview

Hardens VS Code extension shutdown and prevents absolute paths from appearing in debug configuration names.

Changes:

• Awaits CLI stop requests during deactivation with bounded teardown.
• Owns and disposes RPC connections and status notifications.
• Adds cross-platform workspace-path handling and regression tests.

Show a summary per file

File	Description
extension/src/extension.ts	Awaits extension deactivation.
extension/src/AspireExtensionContext.ts	Coordinates bounded CLI shutdown and disposal.
extension/src/debugger/AspireDebugSession.ts	Deduplicates CLI stop requests.
extension/src/server/AspireRpcServer.ts	Tracks and disposes RPC clients.
extension/src/server/rpcClient.ts	Adds idempotent transport disposal.
extension/src/server/interactionService.ts	Clears and suppresses disposed status updates.
extension/src/utils/workspace.ts	Adds cross-platform path filtering.
extension/src/test/AspireExtensionContext.test.ts	Tests deactivation sequencing and failures.
extension/src/test/aspireDebugSession.test.ts	Tests stop-request deduplication.
extension/src/test/rpc/aspireRpcServer.test.ts	Tests RPC ownership during races.
extension/src/test/rpc/interactionServiceTests.test.ts	Tests transport and status cleanup.
extension/src/test/workspace.test.ts	Tests path fallback behavior.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 2
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

extension/src/AspireExtensionContext.ts:171

• A session can dispose/remove itself while _settleStopRequests is awaiting (for example when its AppHost session terminates). This final loop then loses that session's process handle, so a hung stop receives no immediate termination; only the session's unref'd 10-second timer remains, even though deactivation resolves after 5 seconds and the extension host may exit first. Retain the session objects associated with every collected stop request and terminate the union of those sessions and the currently registered sessions. A regression test should remove a session while its stop request is pending.

        for (const session of this._aspireDebugSessions) {
            try {
                session.terminateCliProcessTree();

• Files reviewed: 12/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 2
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

extension/src/AspireExtensionContext.ts:75

• Disposed sessions are now hidden here but remain in _aspireDebugSessions for up to the 10-second termination grace period, while addAspireDebugSession still treats every backing-array entry as an active duplicate. TestRunSessionManager first observes getAspireDebugSession(lease.sessionId) === null and can then create a replacement with that same lease ID, only for registration to throw debugSessionAlreadyExists because the old process owner is retained. Keep pending process owners separate from active-session identity/subscription bookkeeping (or otherwise make lookup, duplicate detection, and removal consistently distinguish the session instance).

        // Disposed sessions can remain tracked only as CLI process owners. They must still be
        // visible to deactivation, but not to RPC lookups or extension-state snapshots.
        return this._aspireDebugSessions.filter(session => !session.isDisposed);

extension/src/debugger/AspireDebugSession.ts:173

• If deactivation lands after createDebugAdapterDescriptor registers the session but before VS Code sends the DAP launch request, there is no RPC client, no CLI process, and no spawnAspireCommand continuation that can call completePendingCliStopWithoutRpcClient(). This promise therefore remains pending until the context's full 5-second deadline even though nothing was launched, unnecessarily delaying window shutdown. Track whether CLI launch is actually in flight and resolve immediately when shutdown prevents a not-yet-started launch; preserve this pending path only when a CLI may already exist/connect.

    if (!this._rpcClient) {
      this._cliStopPromise = new Promise<void>((resolve, reject) => {
        this._pendingCliStopWithoutRpcClient = { resolve, reject };
        this._stopCliWhenRpcClientConnects = client => {
          client.stopCli().then(resolve, reject).finally(() => {
            this._pendingCliStopWithoutRpcClient = undefined;
          });
        };
      });

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

extension/src/debugger/AspireDebugSession.ts:165

• A debug session is registered before its launch has necessarily spawned a CLI. If deactivation lands in that window, both _rpcClient and _cliProcess are absent, so this promise can only be completed by a connection or process exit that will never occur; shutdown therefore always burns the full 5-second timeout despite having no process to stop. Resolve immediately when no child exists (the shutdown latch already prevents a later spawn), and cover the pre-launch session case.

    if (!this._rpcClient) {
      this._cliStopPromise = new Promise<void>((resolve, reject) => {
        this._pendingCliStopWithoutRpcClient = { resolve, reject };
        this._stopCliWhenRpcClientConnects = client => {

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Ella Hathaway (ellahathaway)]

I reviewed the shutdown flow end to end, including cooperative CLI stop, timeout/force termination, RPC ownership, and disposal ordering. I didn't find a new correctness issue beyond the concerns already addressed in resolved threads. I left two nonblocking coverage/description notes.

[Copilot]

Review details

Suppressed comments (1)

extension/src/test/rpc/aspireRpcServer.test.ts:48

• If an assertion before line 35 fails, this finally closes only the client transport and leaves the TLS server listening, which can keep the Mocha process alive and obscure the original failure. Dispose rpcServer in the unconditional cleanup path as the other server tests do.

        finally {
            handshakeResult.resolve(null);
            await new Promise<void>(resolve => setImmediate(resolve));
            transport.connection.end();
            transport.connection.dispose();
            transport.socket.destroy();
            rpcClient?.dispose();

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced