sdk: make client startup single-flight

dotnet/src/Client.cs

@@ -365,7 +365,56 @@
     /// </example>
     public Task StartAsync(CancellationToken cancellationToken = default)
     {
-        return _connectionTask ??= StartCoreAsync(cancellationToken);
+        var connectionTask = Volatile.Read(ref _connectionTask);
+        if (connectionTask is not null)
+        {
+            return connectionTask;
+        }
+
+        var completion = new TaskCompletionSource<Connection>(
+            TaskCreationOptions.RunContinuationsAsynchronously);
+        // Publish before startup begins because StartCoreAsync executes synchronously
+        // until its first incomplete await and can re-enter user-provided callbacks.
+        connectionTask = Interlocked.CompareExchange(
+            ref _connectionTask,
+            completion.Task,
+            null);
+        if (connectionTask is not null)
+        {
+            return connectionTask;
+        }
+
+        _ = CompleteStartAsync(completion, cancellationToken);
+        return completion.Task;
+
+        async Task CompleteStartAsync(
+            TaskCompletionSource<Connection> startCompletion,
+            CancellationToken ct)
+        {
+            try
+            {
+                var connection = await StartCoreAsync(ct).ConfigureAwait(false);
+                startCompletion.TrySetResult(connection);
+            }
+            catch (OperationCanceledException)
+            {
+                // Clear before waking waiters so continuations can immediately retry.
+                _ = Interlocked.CompareExchange(
+                    ref _connectionTask,
+                    null,
+                    startCompletion.Task);
+                startCompletion.TrySetCanceled(ct);
+            }
+            catch (Exception ex)
+            {
+                // Clear before waking waiters so continuations can immediately retry.
+                _ = Interlocked.CompareExchange(
+                    ref _connectionTask,
+                    null,
+                    startCompletion.Task);
+                startCompletion.TrySetException(ex);
+            }
+        }
 
         async Task<Connection> StartCoreAsync(CancellationToken ct)
         {
@@ -375,6 +424,7 @@
             Connection? connection = null;
             Process? cliProcess = null;
             ProcessStderrPump? stderrPump = null;
+            FfiRuntimeHost? ffiHost = null;
 
             try
             {
@@ -427,7 +477,7 @@
                             ?? throw new InvalidOperationException(
                                 $"In-process FFI runtime library not found at '{searchedRuntime}'.")
                         : ResolveRuntimePathForExplicitCli(explicitCliPath);
-                    var ffiHost = FfiRuntimeHost.Create(
+                    ffiHost = FfiRuntimeHost.Create(
                         ffiRuntimePath,
                         explicitCliPath,
                         ffiEnvironment,
@@ -503,6 +553,12 @@
                 {
                     await CleanupCliProcessAsync(cliProcess, stderrPump, errors: null, _logger);
                 }
+                else if (ffiHost is not null)
+                {
+                    try { ffiHost.Dispose(); }
+                    catch (Exception cleanupError) { AddCleanupError(null, cleanupError, _logger); }
+                    _ffiHost = null;
+                }
 
                 if (ex is IOException
                     && cliProcess is not null
@@ -627,14 +683,12 @@
 
     private async Task CleanupConnectionAsync(List<Exception>? errors, bool gracefulRuntimeShutdown)
     {
-        var connectionTask = _connectionTask;
+        var connectionTask = Interlocked.Exchange(ref _connectionTask, null);
         if (connectionTask is null)
         {
             return;
         }
 
-        _connectionTask = null;
-
         Connection ctx;
         try
         {
@@ -2741,7 +2795,7 @@
             _logger.LogDebug(exception, "JSON-RPC connection completed with an error");
         }
 
-        var connectionTask = _connectionTask;
+        var connectionTask = Volatile.Read(ref _connectionTask);
         if (connectionTask is null
             || connectionTask.Status != System.Threading.Tasks.TaskStatus.RanToCompletion
             || !ReferenceEquals(connectionTask.Result.Rpc, rpc))

dotnet/test/Unit/ClientSessionLifetimeTests.cs

@@ -13,6 +13,7 @@
 using System.Text.Json;
 using GitHub.Copilot.Rpc;
 using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
 using Xunit;
 
 namespace GitHub.Copilot.Test.Unit;
@@ -21,6 +22,66 @@ public sealed class ClientSessionLifetimeTests
 {
     private sealed record RpcRequestRecord(string Method, JsonElement Params);
 
+    [Fact]
+    public async Task StartAsync_Concurrent_Callers_Share_One_Startup()
+    {
+        await using var server = await FakeCopilotServer.StartAsync();
+        var logger = new BlockingStartLogger();
+        await using var client = new CopilotClient(new CopilotClientOptions
+        {
+            Connection = RuntimeConnection.ForUri(server.Url),
+            Logger = logger
+        });
+        using var cancellation = new CancellationTokenSource();
+
+        var firstInvocation = Task.Run<Task>(() => client.StartAsync(cancellation.Token));
+        await logger.FirstStartEntered.WaitAsync(TimeSpan.FromSeconds(5));
+
+        Task secondStart;
+        int startCount;
+        try
+        {
+            // Cancel before releasing the blocked first attempt so both code paths
+            // terminate without opening a connection if startup is duplicated.
+            cancellation.Cancel();
+            secondStart = client.StartAsync(cancellation.Token);
+            startCount = logger.StartCount;
+        }
+        finally
+        {
+            logger.ReleaseFirstStart();
+        }
+
+        var firstStart = await firstInvocation;
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(() => firstStart);
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(() => secondStart);
+
+        Assert.Equal(1, startCount);
+        Assert.Same(firstStart, secondStart);
+
+        await client.StartAsync();
+        Assert.Equal(2, logger.StartCount);
+    }
+
+    [Fact]
+    public async Task StartAsync_Retries_After_Failed_Startup()
+    {
+        await using var server = await FakeCopilotServer.StartAsync();
+        var logger = new FailFirstStartLogger();
+        await using var client = new CopilotClient(new CopilotClientOptions
+        {
+            Connection = RuntimeConnection.ForUri(server.Url),
+            Logger = logger
+        });
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => client.StartAsync());
+        Assert.Equal("first startup failed", error.Message);
+
+        await client.StartAsync();
+
+        Assert.Equal(2, logger.StartCount);
+    }
+
     [Theory]
     [InlineData("static")]
     [InlineData("")]
@@ -2183,6 +2244,70 @@ private static Process StartExitedProcess()
         return process;
     }
 
+    private sealed class BlockingStartLogger : ILogger
+    {
+        private readonly TaskCompletionSource _firstStartEntered =
+            new(TaskCreationOptions.RunContinuationsAsynchronously);
+        private readonly TaskCompletionSource _allowFirstStart =
+            new(TaskCreationOptions.RunContinuationsAsynchronously);
+        private int _startCount;
+
+        public Task FirstStartEntered => _firstStartEntered.Task;
+
+        public int StartCount => Volatile.Read(ref _startCount);
+
+        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+
+        public bool IsEnabled(LogLevel logLevel) => logLevel == LogLevel.Debug;
+
+        public void Log<TState>(
+            LogLevel logLevel,
+            EventId eventId,
+            TState state,
+            Exception? exception,
+            Func<TState, Exception?, string> formatter)
+        {
+            if (formatter(state, exception) != "Starting Copilot client")
+            {
+                return;
+            }
+
+            var startCount = Interlocked.Increment(ref _startCount);
+            if (startCount == 1)
+            {
+                _firstStartEntered.TrySetResult();
+                _allowFirstStart.Task.GetAwaiter().GetResult();
+            }
+        }
+
+        public void ReleaseFirstStart() => _allowFirstStart.TrySetResult();
+    }
+
+    private sealed class FailFirstStartLogger : ILogger
+    {
+        private int _startCount;
+
+        public int StartCount => Volatile.Read(ref _startCount);
+
+        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+
+        public bool IsEnabled(LogLevel logLevel) => logLevel == LogLevel.Debug;
+
+        public void Log<TState>(
+            LogLevel logLevel,
+            EventId eventId,
+            TState state,
+            Exception? exception,
+            Func<TState, Exception?, string> formatter)
+        {
+            if (formatter(state, exception) == "Starting Copilot client"
+                && Interlocked.Increment(ref _startCount) == 1)
+            {
+                throw new InvalidOperationException("first startup failed");
+            }
+        }
+    }
+
     private sealed class FakeCopilotServer : IAsyncDisposable
     {
         private readonly TcpListener _listener;

nodejs/src/client.ts

@@ -448,6 +448,8 @@ export class CopilotClient {
     private runtimePort: number | null = null;
     private actualHost: string = "localhost";
     private state: "disconnected" | "connecting" | "connected" | "error" = "disconnected";
+    /** Shared in-flight start; concurrent callers await it instead of spawning another CLI. */
+    private startPromise: Promise<void> | null = null;
     private sessions: Map<string, CopilotSession> = new Map();
     private stderrBuffer: string = ""; // Captures CLI stderr for error messages
     /** Resolved connection mode chosen in the constructor. */
@@ -935,6 +937,20 @@ export class CopilotClient {
             return;
         }
 
+        // Concurrent callers share one in-progress start instead of each spawning a CLI.
+        if (this.startPromise) {
+            return this.startPromise;
+        }
+
+        this.startPromise = this.doStart();
+        try {
+            await this.startPromise;
+        } finally {
+            this.startPromise = null;
+        }
+    }
+
+    private async doStart(): Promise<void> {
         this.forceStopping = false;
         this.connectionClosed = false;
         this.processTransportError = null;

nodejs/test/client.test.ts

@@ -62,6 +62,64 @@ describe("approveAll", () => {
 });
 
 describe("CopilotClient", () => {
+    it("start() is single-flight: concurrent callers share one startup", async () => {
+        const client = new CopilotClient({ autoStart: false });
+        onTestFinished(() => client.forceStop());
+
+        // Stub the underlying startup (doStart) that the single-flight guard
+        // dedupes. Transport-independent: this is the same regardless of the
+        // stdio vs in-process connection path. The delay makes all three
+        // start() calls overlap; on success it marks the client connected like
+        // the real doStart does.
+        const doStart = vi.fn().mockImplementation(
+            () =>
+                new Promise<void>((resolve) =>
+                    setTimeout(() => {
+                        (client as any).state = "connected";
+                        resolve();
+                    }, 50)
+                )
+        );
+        (client as any).doStart = doStart;
+
+        // Before the fix, each concurrent caller ran startup (and spawned its own
+        // CLI, orphaning all but the last). With single-flight they share one.
+        await Promise.all([client.start(), client.start(), client.start()]);
+
+        expect(doStart).toHaveBeenCalledTimes(1);
+        expect((client as any).state).toBe("connected");
+
+        // Once connected, a further start() is a no-op (no extra startup).
+        await client.start();
+        expect(doStart).toHaveBeenCalledTimes(1);
+    });
+
+    it("start() retries after a failed attempt (single-flight guard is cleared)", async () => {
+        const client = new CopilotClient({ autoStart: false });
+        onTestFinished(() => client.forceStop());
+
+        // Stub the underlying startup: fail once, then succeed. Transport-
+        // independent (does not depend on the stdio vs in-process path).
+        const doStart = vi
+            .fn()
+            .mockImplementationOnce(async () => {
+                (client as any).state = "error";
+                throw new Error("boom");
+            })
+            .mockImplementationOnce(async () => {
+                (client as any).state = "connected";
+            });
+        (client as any).doStart = doStart;
+
+        await expect(client.start()).rejects.toThrow(/boom/);
+        expect((client as any).state).toBe("error");
+
+        // The guard must have cleared so a later start() can retry.
+        await client.start();
+        expect(doStart).toHaveBeenCalledTimes(2);
+        expect((client as any).state).toBe("connected");
+    });
+
     it.each([
         {
             source: "connection path",