test: speed up gateway suite setup

src/gateway/openai-http.e2e.test.ts

@@ -49,7 +49,8 @@ function parseSseDataLines(text: string): string[] {
 }
 
 describe("OpenAI-compatible HTTP API (e2e)", () => {
-  it("is disabled by default (requires config)", { timeout: 120_000 }, async () => {
+  it("rejects when disabled (default + config)", { timeout: 120_000 }, async () => {
+    {
       const port = await getFreePort();
       const server = await startServerWithDefaultConfig(port);
       try {
@@ -61,9 +62,9 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
       } finally {
         await server.close({ reason: "test done" });
       }
-  });
+    }
 
-  it("can be disabled via config (404)", async () => {
+    {
       const port = await getFreePort();
       const server = await startServer(port, {
         openAiChatCompletionsEnabled: false,
@@ -77,45 +78,39 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
       } finally {
         await server.close({ reason: "test done" });
       }
+    }
   });
 
-  it("rejects non-POST", async () => {
+  it("handles request validation and routing", async () => {
     const port = await getFreePort();
     const server = await startServer(port);
+    const mockAgentOnce = (payloads: Array<{ text: string }>) => {
+      agentCommand.mockReset();
+      agentCommand.mockResolvedValueOnce({ payloads } as never);
+    };
+
     try {
+      {
         const res = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
           method: "GET",
           headers: { authorization: "Bearer secret" },
         });
         expect(res.status).toBe(405);
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("rejects missing auth", async () => {
+      {
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ messages: [{ role: "user", content: "hi" }] }),
         });
         expect(res.status).toBe(401);
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("routes to a specific agent via header", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(
           port,
           { model: "clawdbot", messages: [{ role: "user", content: "hi" }] },
@@ -128,19 +123,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
           /^agent:beta:/,
         );
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("routes to a specific agent via model (no custom headers)", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot:beta",
           messages: [{ role: "user", content: "hi" }],
@@ -152,19 +139,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
           /^agent:beta:/,
         );
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("prefers explicit header agent over model agent", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(
           port,
           {
@@ -180,19 +159,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
           /^agent:alpha:/,
         );
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("honors x-clawdbot-session-key override", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(
           port,
           { model: "clawdbot", messages: [{ role: "user", content: "hi" }] },
@@ -207,19 +178,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect((opts as { sessionKey?: string } | undefined)?.sessionKey).toBe(
           "agent:beta:openai:custom",
         );
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("uses OpenAI user for a stable session key", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           user: "alice",
           model: "clawdbot",
@@ -231,19 +194,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toContain(
           "openai-user:alice",
         );
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("extracts user message text from array content", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot",
           messages: [
@@ -260,19 +215,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
 
         const [opts] = agentCommand.mock.calls[0] ?? [];
         expect((opts as { message?: string } | undefined)?.message).toBe("hello\nworld");
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("includes conversation history when multiple messages are provided", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "I am Claude" }]);
-      payloads: [{ text: "I am Claude" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot",
           messages: [
@@ -291,19 +238,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect(message).toContain("Assistant: I am Claude.");
         expect(message).toContain(CURRENT_MESSAGE_MARKER);
         expect(message).toContain("User: What did I just ask you?");
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("does not include history markers for single message", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot",
           messages: [
@@ -318,19 +257,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect(message).not.toContain(HISTORY_CONTEXT_MARKER);
         expect(message).not.toContain(CURRENT_MESSAGE_MARKER);
         expect(message).toBe("Hello");
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("treats developer role same as system role", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot",
           messages: [
@@ -344,19 +275,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         const extraSystemPrompt =
           (opts as { extraSystemPrompt?: string } | undefined)?.extraSystemPrompt ?? "";
         expect(extraSystemPrompt).toBe("You are a helpful assistant.");
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("includes tool output when it is the latest message", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "ok" }]);
-      payloads: [{ text: "ok" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot",
           messages: [
@@ -375,19 +298,11 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         expect(message).toContain("Assistant: Checking the weather.");
         expect(message).toContain(CURRENT_MESSAGE_MARKER);
         expect(message).toContain("Tool: Sunny, 70F.");
-    } finally {
+        await res.text();
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("returns a non-streaming OpenAI chat.completion response", async () => {
+      {
-    agentCommand.mockResolvedValueOnce({
+        mockAgentOnce([{ text: "hello" }]);
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           stream: false,
           model: "clawdbot",
@@ -401,30 +316,30 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
         const msg = (choice0.message as Record<string, unknown> | undefined) ?? {};
         expect(msg.role).toBe("assistant");
         expect(msg.content).toBe("hello");
-    } finally {
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("requires a user message", async () => {
+      {
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           model: "clawdbot",
           messages: [{ role: "system", content: "yo" }],
         });
         expect(res.status).toBe(400);
-      const json = (await res.json()) as Record<string, unknown>;
+        const missingUserJson = (await res.json()) as Record<string, unknown>;
-      expect((json.error as Record<string, unknown> | undefined)?.type).toBe(
+        expect((missingUserJson.error as Record<string, unknown> | undefined)?.type).toBe(
           "invalid_request_error",
         );
+      }
     } finally {
       await server.close({ reason: "test done" });
     }
   });
 
-  it("streams SSE chunks when stream=true (delta events)", async () => {
+  it("streams SSE chunks when stream=true", async () => {
+    const port = await getFreePort();
+    const server = await startServer(port);
+    try {
+      {
+        agentCommand.mockReset();
         agentCommand.mockImplementationOnce(async (opts: unknown) => {
           const runId = (opts as { runId?: string } | undefined)?.runId ?? "";
           emitAgentEvent({ runId, stream: "assistant", data: { delta: "he" } });
@@ -432,9 +347,6 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
           return { payloads: [{ text: "hello" }] } as never;
         });
 
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
         const res = await postChatCompletions(port, {
           stream: true,
           model: "clawdbot",
@@ -457,12 +369,10 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
           .filter((v): v is string => typeof v === "string")
           .join("");
         expect(allContent).toBe("hello");
-    } finally {
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("preserves repeated identical deltas when streaming SSE", async () => {
+      {
+        agentCommand.mockReset();
         agentCommand.mockImplementationOnce(async (opts: unknown) => {
           const runId = (opts as { runId?: string } | undefined)?.runId ?? "";
           emitAgentEvent({ runId, stream: "assistant", data: { delta: "hi" } });
@@ -470,48 +380,41 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
           return { payloads: [{ text: "hihi" }] } as never;
         });
 
-    const port = await getFreePort();
+        const repeatedRes = await postChatCompletions(port, {
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
           stream: true,
           model: "clawdbot",
           messages: [{ role: "user", content: "hi" }],
         });
-      expect(res.status).toBe(200);
+        expect(repeatedRes.status).toBe(200);
-      const text = await res.text();
+        const repeatedText = await repeatedRes.text();
-      const data = parseSseDataLines(text);
+        const repeatedData = parseSseDataLines(repeatedText);
-      const jsonChunks = data
+        const repeatedChunks = repeatedData
           .filter((d) => d !== "[DONE]")
           .map((d) => JSON.parse(d) as Record<string, unknown>);
-      const allContent = jsonChunks
+        const repeatedContent = repeatedChunks
           .flatMap((c) => (c.choices as Array<Record<string, unknown>> | undefined) ?? [])
           .map((choice) => (choice.delta as Record<string, unknown> | undefined)?.content)
           .filter((v): v is string => typeof v === "string")
           .join("");
-      expect(allContent).toBe("hihi");
+        expect(repeatedContent).toBe("hihi");
-    } finally {
-      await server.close({ reason: "test done" });
       }
-  });
 
-  it("streams SSE chunks when stream=true (fallback when no deltas)", async () => {
+      {
+        agentCommand.mockReset();
         agentCommand.mockResolvedValueOnce({
           payloads: [{ text: "hello" }],
         } as never);
 
-    const port = await getFreePort();
+        const fallbackRes = await postChatCompletions(port, {
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
           stream: true,
           model: "clawdbot",
           messages: [{ role: "user", content: "hi" }],
         });
-      expect(res.status).toBe(200);
+        expect(fallbackRes.status).toBe(200);
-      const text = await res.text();
+        const fallbackText = await fallbackRes.text();
-      expect(text).toContain("[DONE]");
+        expect(fallbackText).toContain("[DONE]");
-      expect(text).toContain("hello");
+        expect(fallbackText).toContain("hello");
+      }
     } finally {
       await server.close({ reason: "test done" });
     }

src/gateway/server.config-apply.test.ts

@@ -1,39 +1,47 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { WebSocket } from "ws";
 
 import {
   connectOk,
+  getFreePort,
   installGatewayTestHooks,
   onceMessage,
-  startServerWithClient,
+  startGatewayServer,
 } from "./test-helpers.js";
 
-installGatewayTestHooks();
+installGatewayTestHooks({ scope: "suite" });
 
-const servers: Array<Awaited<ReturnType<typeof startServerWithClient>>> = [];
+let server: Awaited<ReturnType<typeof startGatewayServer>>;
+let port = 0;
+let previousToken: string | undefined;
 
-afterEach(async () => {
+beforeAll(async () => {
-  for (const { server, ws } of servers) {
+  previousToken = process.env.CLAWDBOT_GATEWAY_TOKEN;
-    try {
+  delete process.env.CLAWDBOT_GATEWAY_TOKEN;
-      ws.close();
+  port = await getFreePort();
-      await server.close();
+  server = await startGatewayServer(port);
-    } catch {
-      /* ignore */
-    }
-  }
-  servers.length = 0;
-  await new Promise((resolve) => setTimeout(resolve, 50));
 });
 
+afterAll(async () => {
+  await server.close();
+  if (previousToken === undefined) delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+  else process.env.CLAWDBOT_GATEWAY_TOKEN = previousToken;
+});
+
+const openClient = async () => {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+  await new Promise<void>((resolve) => ws.once("open", resolve));
+  await connectOk(ws);
+  return ws;
+};
+
 describe("gateway config.apply", () => {
   it("writes config, stores sentinel, and schedules restart", async () => {
-    const result = await startServerWithClient();
+    const ws = await openClient();
-    servers.push(result);
+    try {
-    const { ws } = result;
-    await connectOk(ws);
-
       const id = "req-1";
       ws.send(
         JSON.stringify({
@@ -67,14 +75,14 @@ describe("gateway config.apply", () => {
         // File may not exist if signal delivery is mocked, verify response was ok instead
         expect(res.ok).toBe(true);
       }
+    } finally {
+      ws.close();
+    }
   });
 
   it("rejects invalid raw config", async () => {
-    const result = await startServerWithClient();
+    const ws = await openClient();
-    servers.push(result);
+    try {
-    const { ws } = result;
-    await connectOk(ws);
-
       const id = "req-2";
       ws.send(
         JSON.stringify({
@@ -91,5 +99,8 @@ describe("gateway config.apply", () => {
         (o) => o.type === "res" && o.id === id,
       );
       expect(res.ok).toBe(false);
+    } finally {
+      ws.close();
+    }
   });
 });

src/gateway/server.cron.test.ts

@@ -12,7 +12,7 @@ import {
   waitForSystemEvent,
 } from "./test-helpers.js";
 
-installGatewayTestHooks();
+installGatewayTestHooks({ scope: "suite" });
 
 async function yieldToEventLoop() {
   // Avoid relying on timers (fake timers can leak between tests).

src/gateway/server.health.test.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, test } from "vitest";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { WebSocket } from "ws";
 import { emitAgentEvent } from "../infra/agent-events.js";
 import {
@@ -21,12 +21,35 @@ import {
 } from "./test-helpers.js";
 import { buildDeviceAuthPayload } from "./device-auth.js";
 
-installGatewayTestHooks();
+installGatewayTestHooks({ scope: "suite" });
+
+let server: Awaited<ReturnType<typeof startGatewayServer>>;
+let port = 0;
+let previousToken: string | undefined;
+
+beforeAll(async () => {
+  previousToken = process.env.CLAWDBOT_GATEWAY_TOKEN;
+  delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+  port = await getFreePort();
+  server = await startGatewayServer(port);
+});
+
+afterAll(async () => {
+  await server.close();
+  if (previousToken === undefined) delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+  else process.env.CLAWDBOT_GATEWAY_TOKEN = previousToken;
+});
+
+const openClient = async (opts?: Parameters<typeof connectOk>[1]) => {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+  await new Promise<void>((resolve) => ws.once("open", resolve));
+  await connectOk(ws, opts);
+  return ws;
+};
 
 describe("gateway server health/presence", () => {
   test("connect + health + presence + status succeed", { timeout: 60_000 }, async () => {
-    const { server, ws } = await startServerWithClient();
+    const ws = await openClient();
-    await connectOk(ws);
 
     const healthP = onceMessage(ws, (o) => o.type === "res" && o.id === "health1");
     const statusP = onceMessage(ws, (o) => o.type === "res" && o.id === "status1");
@@ -51,7 +74,6 @@ describe("gateway server health/presence", () => {
     expect(Array.isArray(presence.payload)).toBe(true);
 
     ws.close();
-    await server.close();
   });
 
   test("broadcasts heartbeat events and serves last-heartbeat", async () => {
@@ -76,8 +98,7 @@ describe("gateway server health/presence", () => {
       payload?: unknown;
     };
 
-    const { server, ws } = await startServerWithClient();
+    const ws = await openClient();
-    await connectOk(ws);
 
     const waitHeartbeat = onceMessage<EventFrame>(
       ws,
@@ -117,12 +138,10 @@ describe("gateway server health/presence", () => {
     expect((toggle.payload as { enabled?: boolean } | undefined)?.enabled).toBe(false);
 
     ws.close();
-    await server.close();
   });
 
   test("presence events carry seq + stateVersion", { timeout: 8000 }, async () => {
-    const { server, ws } = await startServerWithClient();
+    const ws = await openClient();
-    await connectOk(ws);
 
     const presenceEventP = onceMessage(ws, (o) => o.type === "event" && o.event === "presence");
     ws.send(
@@ -140,12 +159,10 @@ describe("gateway server health/presence", () => {
     expect(Array.isArray(evt.payload?.presence)).toBe(true);
 
     ws.close();
-    await server.close();
   });
 
   test("agent events stream with seq", { timeout: 8000 }, async () => {
-    const { server, ws } = await startServerWithClient();
+    const ws = await openClient();
-    await connectOk(ws);
 
     const runId = randomUUID();
     const evtPromise = onceMessage(
@@ -163,7 +180,6 @@ describe("gateway server health/presence", () => {
     expect(evt.payload.data.msg).toBe("hi");
 
     ws.close();
-    await server.close();
   });
 
   test("shutdown event is broadcast on close", { timeout: 8000 }, async () => {
@@ -177,16 +193,7 @@ describe("gateway server health/presence", () => {
   });
 
   test("presence broadcast reaches multiple clients", { timeout: 8000 }, async () => {
-    const port = await getFreePort();
+    const clients = await Promise.all([openClient(), openClient(), openClient()]);
-    const server = await startGatewayServer(port);
-    const mkClient = async () => {
-      const c = new WebSocket(`ws://127.0.0.1:${port}`);
-      await new Promise<void>((resolve) => c.once("open", resolve));
-      await connectOk(c);
-      return c;
-    };
-
-    const clients = await Promise.all([mkClient(), mkClient(), mkClient()]);
     const waits = clients.map((c) =>
       onceMessage(c, (o) => o.type === "event" && o.event === "presence"),
     );
@@ -204,7 +211,6 @@ describe("gateway server health/presence", () => {
       expect(typeof evt.seq).toBe("number");
     }
     for (const c of clients) c.close();
-    await server.close();
   });
 
   test("presence includes client fingerprint", async () => {
@@ -222,8 +228,7 @@ describe("gateway server health/presence", () => {
       signedAtMs,
       token: null,
     });
-    const { server, ws } = await startServerWithClient();
+    const ws = await openClient({
-    await connectOk(ws, {
       role,
       scopes,
       client: {
@@ -264,13 +269,11 @@ describe("gateway server health/presence", () => {
     expect(clientEntry?.modelIdentifier).toBe("iPad16,6");
 
     ws.close();
-    await server.close();
   });
 
   test("cli connections are not tracked as instances", async () => {
-    const { server, ws } = await startServerWithClient();
     const cliId = `cli-${randomUUID()}`;
-    await connectOk(ws, {
+    const ws = await openClient({
       client: {
         id: GATEWAY_CLIENT_NAMES.CLI,
         version: "dev",
@@ -294,6 +297,5 @@ describe("gateway server health/presence", () => {
     expect(entries.some((e) => e.instanceId === cliId)).toBe(false);
 
     ws.close();
-    await server.close();
   });
 });

src/gateway/server.ios-client-id.test.ts

@@ -1,9 +1,21 @@
-import { test } from "vitest";
+import { afterAll, beforeAll, test } from "vitest";
 import WebSocket from "ws";
 
 import { PROTOCOL_VERSION } from "./protocol/index.js";
 import { getFreePort, onceMessage, startGatewayServer } from "./test-helpers.server.js";
 
+let server: Awaited<ReturnType<typeof startGatewayServer>>;
+let port = 0;
+
+beforeAll(async () => {
+  port = await getFreePort();
+  server = await startGatewayServer(port);
+});
+
+afterAll(async () => {
+  await server.close();
+});
+
 function connectReq(
   ws: WebSocket,
   params: { clientId: string; platform: string; token?: string; password?: string },
@@ -43,8 +55,6 @@ function connectReq(
 }
 
 test("accepts clawdbot-ios as a valid gateway client id", async () => {
-  const port = await getFreePort();
-  const server = await startGatewayServer(port);
   const ws = new WebSocket(`ws://127.0.0.1:${port}`);
   await new Promise<void>((resolve) => ws.once("open", resolve));
 
@@ -61,12 +71,9 @@ test("accepts clawdbot-ios as a valid gateway client id", async () => {
   }
 
   ws.close();
-  await server.close();
 });
 
 test("accepts clawdbot-android as a valid gateway client id", async () => {
-  const port = await getFreePort();
-  const server = await startGatewayServer(port);
   const ws = new WebSocket(`ws://127.0.0.1:${port}`);
   await new Promise<void>((resolve) => ws.once("open", resolve));
 
@@ -83,5 +90,4 @@ test("accepts clawdbot-android as a valid gateway client id", async () => {
   }
 
   ws.close();
-  await server.close();
 });

src/gateway/server.sessions.gateway-server-sessions-a.test.ts

@@ -1,14 +1,16 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import { WebSocket } from "ws";
 import {
   connectOk,
   embeddedRunMock,
+  getFreePort,
   installGatewayTestHooks,
   piSdkMock,
   rpcReq,
-  startServerWithClient,
+  startGatewayServer,
   testState,
   writeSessionStore,
 } from "./test-helpers.js";
@@ -39,7 +41,31 @@ vi.mock("../auto-reply/reply/abort.js", async () => {
   };
 });
 
-installGatewayTestHooks();
+installGatewayTestHooks({ scope: "suite" });
+
+let server: Awaited<ReturnType<typeof startGatewayServer>>;
+let port = 0;
+let previousToken: string | undefined;
+
+beforeAll(async () => {
+  previousToken = process.env.CLAWDBOT_GATEWAY_TOKEN;
+  delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+  port = await getFreePort();
+  server = await startGatewayServer(port);
+});
+
+afterAll(async () => {
+  await server.close();
+  if (previousToken === undefined) delete process.env.CLAWDBOT_GATEWAY_TOKEN;
+  else process.env.CLAWDBOT_GATEWAY_TOKEN = previousToken;
+});
+
+const openClient = async (opts?: Parameters<typeof connectOk>[1]) => {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+  await new Promise<void>((resolve) => ws.once("open", resolve));
+  const hello = await connectOk(ws, opts);
+  return { ws, hello };
+};
 
 describe("gateway server sessions", () => {
   beforeEach(() => {
@@ -98,8 +124,7 @@ describe("gateway server sessions", () => {
       },
     });
 
-    const { server, ws } = await startServerWithClient();
+    const { ws, hello } = await openClient();
-    const hello = await connectOk(ws);
     expect((hello as unknown as { features?: { methods?: string[] } }).features?.methods).toEqual(
       expect.arrayContaining([
         "sessions.list",
@@ -336,7 +361,6 @@ describe("gateway server sessions", () => {
     );
 
     ws.close();
-    await server.close();
   });
 
   test("sessions.preview returns transcript previews", async () => {
@@ -365,8 +389,7 @@ describe("gateway server sessions", () => {
       },
     });
 
-    const { server, ws } = await startServerWithClient();
+    const { ws } = await openClient();
-    await connectOk(ws);
     const preview = await rpcReq<{
       previews: Array<{
         key: string;
@@ -383,7 +406,6 @@ describe("gateway server sessions", () => {
     expect(entry?.items[1]?.text).toContain("call weather");
 
     ws.close();
-    await server.close();
   });
 
   test("sessions.delete rejects main and aborts active runs", async () => {
@@ -415,8 +437,7 @@ describe("gateway server sessions", () => {
     embeddedRunMock.activeIds.add("sess-active");
     embeddedRunMock.waitResults.set("sess-active", true);
 
-    const { server, ws } = await startServerWithClient();
+    const { ws } = await openClient();
-    await connectOk(ws);
 
     const mainDelete = await rpcReq(ws, "sessions.delete", { key: "main" });
     expect(mainDelete.ok).toBe(false);
@@ -439,6 +460,5 @@ describe("gateway server sessions", () => {
     expect(embeddedRunMock.waitCalls).toEqual(["sess-active"]);
 
     ws.close();
-    await server.close();
   });
 });

src/gateway/test-helpers.server.ts

@@ -3,7 +3,7 @@ import { type AddressInfo, createServer } from "node:net";
 import os from "node:os";
 import path from "node:path";
 
-import { afterEach, beforeEach, expect, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, expect, vi } from "vitest";
 import { WebSocket } from "ws";
 
 import { resolveMainSessionKeyFromConfig, type SessionEntry } from "../config/sessions.js";
@@ -75,11 +75,7 @@ export async function writeSessionStore(params: {
   await fs.writeFile(storePath, JSON.stringify(store, null, 2), "utf-8");
 }
 
-export function installGatewayTestHooks() {
+async function setupGatewayTestHome() {
-  beforeEach(async () => {
-    // Some tests intentionally use fake timers; ensure they don't leak into gateway suites.
-    vi.useRealTimers();
-    setLoggerOverride({ level: "silent", consoleLevel: "silent" });
   previousHome = process.env.HOME;
   previousUserProfile = process.env.USERPROFILE;
   previousStateDir = process.env.CLAWDBOT_STATE_DIR;
@@ -92,10 +88,25 @@ export function installGatewayTestHooks() {
   process.env.USERPROFILE = tempHome;
   process.env.CLAWDBOT_STATE_DIR = path.join(tempHome, ".clawdbot");
   delete process.env.CLAWDBOT_CONFIG_PATH;
+}
+
+function applyGatewaySkipEnv() {
   process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER = "1";
   process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = "1";
   process.env.CLAWDBOT_SKIP_CANVAS_HOST = "1";
-    tempConfigRoot = path.join(tempHome, ".clawdbot-test");
+}
+
+async function resetGatewayTestState(options: { uniqueConfigRoot: boolean }) {
+  // Some tests intentionally use fake timers; ensure they don't leak into gateway suites.
+  vi.useRealTimers();
+  setLoggerOverride({ level: "silent", consoleLevel: "silent" });
+  if (!tempHome) {
+    throw new Error("resetGatewayTestState called before temp home was initialized");
+  }
+  applyGatewaySkipEnv();
+  tempConfigRoot = options.uniqueConfigRoot
+    ? await fs.mkdtemp(path.join(tempHome, "clawdbot-test-"))
+    : path.join(tempHome, ".clawdbot-test");
   setTestConfigRoot(tempConfigRoot);
   sessionStoreSaveDelayMs.value = 0;
   testTailnetIPv4.value = undefined;
@@ -131,11 +142,12 @@ export function installGatewayTestHooks() {
   piSdkMock.enabled = false;
   piSdkMock.discoverCalls = 0;
   piSdkMock.models = [];
-  }, 60_000);
+}
 
-  afterEach(async () => {
+async function cleanupGatewayTestHome(options: { restoreEnv: boolean }) {
   vi.useRealTimers();
   resetLogger();
+  if (options.restoreEnv) {
     if (previousHome === undefined) delete process.env.HOME;
     else process.env.HOME = previousHome;
     if (previousUserProfile === undefined) delete process.env.USERPROFILE;
@@ -151,7 +163,8 @@ export function installGatewayTestHooks() {
     else process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = previousSkipGmailWatcher;
     if (previousSkipCanvasHost === undefined) delete process.env.CLAWDBOT_SKIP_CANVAS_HOST;
     else process.env.CLAWDBOT_SKIP_CANVAS_HOST = previousSkipCanvasHost;
-    if (tempHome) {
+  }
+  if (options.restoreEnv && tempHome) {
     await fs.rm(tempHome, {
       recursive: true,
       force: true,
@@ -161,6 +174,34 @@ export function installGatewayTestHooks() {
     tempHome = undefined;
   }
   tempConfigRoot = undefined;
+}
+
+export function installGatewayTestHooks(options?: { scope?: "test" | "suite" }) {
+  const scope = options?.scope ?? "test";
+  if (scope === "suite") {
+    beforeAll(async () => {
+      await setupGatewayTestHome();
+      await resetGatewayTestState({ uniqueConfigRoot: true });
+    });
+    beforeEach(async () => {
+      await resetGatewayTestState({ uniqueConfigRoot: true });
+    }, 60_000);
+    afterEach(async () => {
+      await cleanupGatewayTestHome({ restoreEnv: false });
+    });
+    afterAll(async () => {
+      await cleanupGatewayTestHome({ restoreEnv: true });
+    });
+    return;
+  }
+
+  beforeEach(async () => {
+    await setupGatewayTestHome();
+    await resetGatewayTestState({ uniqueConfigRoot: false });
+  }, 60_000);
+
+  afterEach(async () => {
+    await cleanupGatewayTestHome({ restoreEnv: true });
   });
 }