From cba92f893da447028e5e045a713f1df9fbb63aaf Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 24 Apr 2026 18:25:45 +0100
Subject: [PATCH] fix(gateway): await startup sidecars by default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: 忻役 <xinyi@mininglamp.com>
---
 src/gateway/server-startup-post-attach.test.ts | 1 +
 src/gateway/server-startup-post-attach.ts      | 2 +-
 src/gateway/server.impl.ts                     | 4 +++-
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/gateway/server-startup-post-attach.test.ts b/src/gateway/server-startup-post-attach.test.ts
index bd1c29b03fc..95c26b22746 100644
--- a/src/gateway/server-startup-post-attach.test.ts
+++ b/src/gateway/server-startup-post-attach.test.ts
@@ -197,6 +197,7 @@ describe("startGatewayPostAttachRuntime", () => {
       {
         ...createPostAttachParams(),
         unavailableGatewayMethods,
+        awaitSidecars: false,
       },
       createPostAttachRuntimeDeps({ startGatewaySidecars }),
     );
diff --git a/src/gateway/server-startup-post-attach.ts b/src/gateway/server-startup-post-attach.ts
index ff8d08d062c..4417fc0fbeb 100644
--- a/src/gateway/server-startup-post-attach.ts
+++ b/src/gateway/server-startup-post-attach.ts
@@ -520,7 +520,7 @@ export async function startGatewayPostAttachRuntime(
       params.log.warn(`gateway sidecars failed to start: ${String(err)}`);
     });
 
-  if (params.awaitSidecars === true) {
+  if (params.awaitSidecars !== false) {
     const [stopGatewayUpdateCheck, tailscaleCleanup, sidecarsResult] = await Promise.all([
       stopGatewayUpdateCheckPromise,
       tailscaleCleanupPromise,
diff --git a/src/gateway/server.impl.ts b/src/gateway/server.impl.ts
index 4872810fed9..981c1d5a295 100644
--- a/src/gateway/server.impl.ts
+++ b/src/gateway/server.impl.ts
@@ -230,7 +230,9 @@ export type GatewayServerOptions = {
     prompter: import("../wizard/prompts.js").WizardPrompter,
   ) => Promise<void>;
   /**
-   * Test-only: wait for post-listen sidecars such as plugin services before returning.
+   * Whether to wait for post-listen sidecars (channels, plugin services) to finish
+   * starting before marking the gateway as ready. Defaults to true; pass false to
+   * let sidecars start in the background.
    */
   awaitStartupSidecars?: boolean;
   /**