From f07b00de664989b655d13272d0f43fc6439f57b3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 24 Apr 2026 18:58:06 +0100
Subject: [PATCH] refactor(gateway): rename startup sidecar deferral option

---
 src/gateway/gateway-acp-bind.live.test.ts     |  1 -
 src/gateway/gateway-codex-bind.live.test.ts   |  1 -
 .../server-startup-post-attach.test.ts        | 30 ++++++++++++++++++-
 src/gateway/server-startup-post-attach.ts     |  4 +--
 src/gateway/server.impl.ts                    |  9 +++---
 5 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/src/gateway/gateway-acp-bind.live.test.ts b/src/gateway/gateway-acp-bind.live.test.ts
index c74e85c554a..9efd325262c 100644
--- a/src/gateway/gateway-acp-bind.live.test.ts
+++ b/src/gateway/gateway-acp-bind.live.test.ts
@@ -583,7 +583,6 @@ describeLive("gateway live (ACP bind)", () => {
         bind: "loopback",
         auth: { mode: "token", token },
         controlUiEnabled: false,
-        awaitStartupSidecars: true,
       });
       logLiveStep("gateway startup returned");
       await waitForGatewayPort({ host: "127.0.0.1", port, timeoutMs: CONNECT_TIMEOUT_MS });
diff --git a/src/gateway/gateway-codex-bind.live.test.ts b/src/gateway/gateway-codex-bind.live.test.ts
index 22c89ec0b00..5cddfa0a6dc 100644
--- a/src/gateway/gateway-codex-bind.live.test.ts
+++ b/src/gateway/gateway-codex-bind.live.test.ts
@@ -365,7 +365,6 @@ describeLive("gateway live (native Codex conversation binding)", () => {
         bind: "loopback",
         auth: { mode: "token", token },
         controlUiEnabled: false,
-        awaitStartupSidecars: true,
       });
       const client = await connectTestGatewayClient({
         url: `ws://127.0.0.1:${port}`,
diff --git a/src/gateway/server-startup-post-attach.test.ts b/src/gateway/server-startup-post-attach.test.ts
index 95c26b22746..e0c271949dd 100644
--- a/src/gateway/server-startup-post-attach.test.ts
+++ b/src/gateway/server-startup-post-attach.test.ts
@@ -183,6 +183,34 @@ describe("startGatewayPostAttachRuntime", () => {
     });
   });
 
+  it("waits for sidecars by default before returning", async () => {
+    let resumeSidecars!: () => void;
+    const sidecarsReady = new Promise<{ pluginServices: null }>((resolve) => {
+      resumeSidecars = () => resolve({ pluginServices: null });
+    });
+    const startGatewaySidecars = vi.fn(async () => {
+      return await sidecarsReady;
+    });
+    let returned = false;
+
+    const runtimePromise = startGatewayPostAttachRuntime(
+      createPostAttachParams(),
+      createPostAttachRuntimeDeps({ startGatewaySidecars }),
+    ).then(() => {
+      returned = true;
+    });
+
+    await vi.waitFor(() => {
+      expect(startGatewaySidecars).toHaveBeenCalledTimes(1);
+    });
+    await Promise.resolve();
+    expect(returned).toBe(false);
+
+    resumeSidecars();
+    await runtimePromise;
+    expect(returned).toBe(true);
+  });
+
   it("keeps startup-gated methods unavailable while sidecars are still resuming", async () => {
     let resumeSidecars!: () => void;
     const sidecarsReady = new Promise<{ pluginServices: null }>((resolve) => {
@@ -197,7 +225,7 @@ describe("startGatewayPostAttachRuntime", () => {
       {
         ...createPostAttachParams(),
         unavailableGatewayMethods,
-        awaitSidecars: false,
+        deferSidecars: true,
       },
       createPostAttachRuntimeDeps({ startGatewaySidecars }),
     );
diff --git a/src/gateway/server-startup-post-attach.ts b/src/gateway/server-startup-post-attach.ts
index 4417fc0fbeb..31fb20debe1 100644
--- a/src/gateway/server-startup-post-attach.ts
+++ b/src/gateway/server-startup-post-attach.ts
@@ -420,7 +420,7 @@ export async function startGatewayPostAttachRuntime(
     onPluginServices?: (pluginServices: PluginServicesHandle | null) => void;
     onSidecarsReady?: () => void;
     startupTrace?: GatewayStartupTrace;
-    awaitSidecars?: boolean;
+    deferSidecars?: boolean;
   },
   runtimeDeps: GatewayPostAttachRuntimeDeps = defaultGatewayPostAttachRuntimeDeps,
 ) {
@@ -520,7 +520,7 @@ export async function startGatewayPostAttachRuntime(
       params.log.warn(`gateway sidecars failed to start: ${String(err)}`);
     });
 
-  if (params.awaitSidecars !== false) {
+  if (params.deferSidecars !== true) {
     const [stopGatewayUpdateCheck, tailscaleCleanup, sidecarsResult] = await Promise.all([
       stopGatewayUpdateCheckPromise,
       tailscaleCleanupPromise,
diff --git a/src/gateway/server.impl.ts b/src/gateway/server.impl.ts
index 981c1d5a295..8471361da46 100644
--- a/src/gateway/server.impl.ts
+++ b/src/gateway/server.impl.ts
@@ -230,11 +230,10 @@ export type GatewayServerOptions = {
     prompter: import("../wizard/prompts.js").WizardPrompter,
   ) => Promise<void>;
   /**
-   * 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.
+   * Let post-listen sidecars (channels, plugin services) finish in the background.
+   * Defaults to false so gateway startup waits until sidecars are ready.
    */
-  awaitStartupSidecars?: boolean;
+  deferStartupSidecars?: boolean;
   /**
    * Optional startup timestamp used for concise readiness logging.
    */
@@ -844,7 +843,7 @@ export async function startGatewayServer(
           startupSidecarsReady = true;
         },
         startupTrace,
-        awaitSidecars: opts.awaitStartupSidecars,
+        deferSidecars: opts.deferStartupSidecars === true,
       }),
     ));
     startupTrace.mark("ready");