fix: cover Windows exe argv (#1480) (thanks @Takhoffman)

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Rodrigo Uroz <rodrigouroz@users.noreply.github.com>

CHANGELOG.md

@@ -9,7 +9,6 @@ Docs: https://docs.clawd.bot
 - Lobster: allow workflow file args via `argsJson` in the plugin tool. https://docs.clawd.bot/tools/lobster
 - Agents: add identity avatar config support and Control UI avatar rendering. (#1329, #1424) Thanks @dlauer.
 - Memory: prevent CLI hangs by deferring vector probes, adding sqlite-vec/embedding timeouts, and showing sync progress early.
-- BlueBubbles: add `asVoice` support for MP3/CAF voice memos in sendAttachment. (#1477) Thanks @Nicell.
 - Docs: add troubleshooting entry for gateway.mode blocking gateway start. https://docs.clawd.bot/gateway/troubleshooting
 - Docs: add /model allowlist troubleshooting note. (#1405)
 - Docs: add per-message Gmail search example for gog. (#1220) Thanks @mbelinky.
@@ -25,6 +24,7 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - BlueBubbles: stop typing indicator on idle/no-reply. (#1439) Thanks @Nicell.
 - Message tool: keep path/filePath as-is for send; hydrate buffers only for sendAttachment. (#1444) Thanks @hopyky.
+- CLI: handle Windows runtime exe argv and pnpm build shims more reliably. (#1480) Thanks @Takhoffman.
 - Auto-reply: only report a model switch when session state is available. (#1465) Thanks @robbyczgw-cla.
 - Control UI: resolve local avatar URLs with basePath across injection + identity RPC. (#1457) Thanks @dlauer.
 - Agents: surface concrete API error details instead of generic AI service errors.
@@ -38,6 +38,7 @@ Docs: https://docs.clawd.bot
 - Auth: skip auth profiles in cooldown during initial selection and rotation. (#1316) Thanks @odrobnik.
 - Agents/TUI: honor user-pinned auth profiles during cooldown and preserve search picker ranking. (#1432) Thanks @tobiasbischoff.
 - Docs: fix gog auth services example to include docs scope. (#1454) Thanks @zerone0x.
+- Slack: read thread replies for message reads when threadId is provided (replies-only). (#1450) Thanks @rodrigouroz.
 - macOS: prefer linked channels in gateway summary to avoid false “not linked” status.
 - Providers: improve GitHub Copilot integration (enterprise support, base URL, and auth flow alignment).
 

docs/channels/bluebubbles.md

@@ -147,8 +147,7 @@ Available actions:
 - **addParticipant**: Add someone to a group (`chatGuid`, `address`)
 - **removeParticipant**: Remove someone from a group (`chatGuid`, `address`)
 - **leaveGroup**: Leave a group chat (`chatGuid`)
-- **sendAttachment**: Send media/files (`to`, `buffer`, `filename`, `asVoice`)
-  - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
+- **sendAttachment**: Send media/files (`to`, `buffer`, `filename`)
 
 ### Message IDs (short vs full)
 Clawdbot may surface *short* message IDs (e.g., `1`, `2`) to save tokens.

extensions/bluebubbles/src/actions.test.ts

@@ -521,42 +521,6 @@ describe("bluebubblesMessageActions", () => {
       });
     });
 
-    it("passes asVoice through sendAttachment", async () => {
-      const { sendBlueBubblesAttachment } = await import("./attachments.js");
-
-      const cfg: ClawdbotConfig = {
-        channels: {
-          bluebubbles: {
-            serverUrl: "http://localhost:1234",
-            password: "test-password",
-          },
-        },
-      };
-
-      const base64Buffer = Buffer.from("voice").toString("base64");
-
-      await bluebubblesMessageActions.handleAction({
-        action: "sendAttachment",
-        params: {
-          to: "+15551234567",
-          filename: "voice.mp3",
-          buffer: base64Buffer,
-          contentType: "audio/mpeg",
-          asVoice: true,
-        },
-        cfg,
-        accountId: null,
-      });
-
-      expect(sendBlueBubblesAttachment).toHaveBeenCalledWith(
-        expect.objectContaining({
-          filename: "voice.mp3",
-          contentType: "audio/mpeg",
-          asVoice: true,
-        }),
-      );
-    });
-
     it("throws when buffer is missing for setGroupIcon", async () => {
       const cfg: ClawdbotConfig = {
         channels: {

extensions/bluebubbles/src/actions.ts

@@ -3,6 +3,7 @@ import {
   BLUEBUBBLES_ACTIONS,
   createActionGate,
   jsonResult,
+  readBooleanParam,
   readNumberParam,
   readReactionParams,
   readStringParam,
@@ -50,17 +51,6 @@ function readMessageText(params: Record<string, unknown>): string | undefined {
   return readStringParam(params, "text") ?? readStringParam(params, "message");
 }
 
-function readBooleanParam(params: Record<string, unknown>, key: string): boolean | undefined {
-  const raw = params[key];
-  if (typeof raw === "boolean") return raw;
-  if (typeof raw === "string") {
-    const trimmed = raw.trim().toLowerCase();
-    if (trimmed === "true") return true;
-    if (trimmed === "false") return false;
-  }
-  return undefined;
-}
-
 /** Supported action names for BlueBubbles */
 const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>(BLUEBUBBLES_ACTION_NAMES);
 
@@ -366,7 +356,6 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
       const caption = readStringParam(params, "caption");
       const contentType =
         readStringParam(params, "contentType") ?? readStringParam(params, "mimeType");
-      const asVoice = readBooleanParam(params, "asVoice");
 
       // Buffer can come from params.buffer (base64) or params.path (file path)
       const base64Buffer = readStringParam(params, "buffer");
@@ -391,7 +380,6 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
         filename,
         contentType: contentType ?? undefined,
         caption: caption ?? undefined,
-        asVoice: asVoice ?? undefined,
         opts,
       });
 

extensions/bluebubbles/src/attachments.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 
-import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";
+import { downloadBlueBubblesAttachment } from "./attachments.js";
 import type { BlueBubblesAttachment } from "./types.js";
 
 vi.mock("./accounts.js", () => ({
@@ -238,109 +238,3 @@ describe("downloadBlueBubblesAttachment", () => {
     expect(result.buffer).toEqual(new Uint8Array([1]));
   });
 });
-
-describe("sendBlueBubblesAttachment", () => {
-  beforeEach(() => {
-    vi.stubGlobal("fetch", mockFetch);
-    mockFetch.mockReset();
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  function decodeBody(body: Uint8Array) {
-    return Buffer.from(body).toString("utf8");
-  }
-
-  it("marks voice memos when asVoice is true and mp3 is provided", async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-1" })),
-    });
-
-    await sendBlueBubblesAttachment({
-      to: "chat_guid:iMessage;-;+15551234567",
-      buffer: new Uint8Array([1, 2, 3]),
-      filename: "voice.mp3",
-      contentType: "audio/mpeg",
-      asVoice: true,
-      opts: { serverUrl: "http://localhost:1234", password: "test" },
-    });
-
-    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
-    const bodyText = decodeBody(body);
-    expect(bodyText).toContain('name="isAudioMessage"');
-    expect(bodyText).toContain("true");
-    expect(bodyText).toContain('filename="voice.mp3"');
-  });
-
-  it("normalizes mp3 filenames for voice memos", async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-2" })),
-    });
-
-    await sendBlueBubblesAttachment({
-      to: "chat_guid:iMessage;-;+15551234567",
-      buffer: new Uint8Array([1, 2, 3]),
-      filename: "voice",
-      contentType: "audio/mpeg",
-      asVoice: true,
-      opts: { serverUrl: "http://localhost:1234", password: "test" },
-    });
-
-    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
-    const bodyText = decodeBody(body);
-    expect(bodyText).toContain('filename="voice.mp3"');
-    expect(bodyText).toContain('name="voice.mp3"');
-  });
-
-  it("throws when asVoice is true but media is not audio", async () => {
-    await expect(
-      sendBlueBubblesAttachment({
-        to: "chat_guid:iMessage;-;+15551234567",
-        buffer: new Uint8Array([1, 2, 3]),
-        filename: "image.png",
-        contentType: "image/png",
-        asVoice: true,
-        opts: { serverUrl: "http://localhost:1234", password: "test" },
-      }),
-    ).rejects.toThrow("voice messages require audio");
-    expect(mockFetch).not.toHaveBeenCalled();
-  });
-
-  it("throws when asVoice is true but audio is not mp3 or caf", async () => {
-    await expect(
-      sendBlueBubblesAttachment({
-        to: "chat_guid:iMessage;-;+15551234567",
-        buffer: new Uint8Array([1, 2, 3]),
-        filename: "voice.wav",
-        contentType: "audio/wav",
-        asVoice: true,
-        opts: { serverUrl: "http://localhost:1234", password: "test" },
-      }),
-    ).rejects.toThrow("require mp3 or caf");
-    expect(mockFetch).not.toHaveBeenCalled();
-  });
-
-  it("sanitizes filenames before sending", async () => {
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      text: () => Promise.resolve(JSON.stringify({ messageId: "msg-3" })),
-    });
-
-    await sendBlueBubblesAttachment({
-      to: "chat_guid:iMessage;-;+15551234567",
-      buffer: new Uint8Array([1, 2, 3]),
-      filename: "../evil.mp3",
-      contentType: "audio/mpeg",
-      opts: { serverUrl: "http://localhost:1234", password: "test" },
-    });
-
-    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
-    const bodyText = decodeBody(body);
-    expect(bodyText).toContain('filename="evil.mp3"');
-    expect(bodyText).toContain('name="evil.mp3"');
-  });
-});

extensions/bluebubbles/src/attachments.ts

@@ -1,5 +1,4 @@
 import crypto from "node:crypto";
-import path from "node:path";
 import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import { resolveChatGuidForTarget } from "./send.js";
@@ -20,30 +19,6 @@ export type BlueBubblesAttachmentOpts = {
 };
 
 const DEFAULT_ATTACHMENT_MAX_BYTES = 8 * 1024 * 1024;
-const AUDIO_MIME_MP3 = new Set(["audio/mpeg", "audio/mp3"]);
-const AUDIO_MIME_CAF = new Set(["audio/x-caf", "audio/caf"]);
-
-function sanitizeFilename(input: string | undefined, fallback: string): string {
-  const trimmed = input?.trim() ?? "";
-  const base = trimmed ? path.basename(trimmed) : "";
-  return base || fallback;
-}
-
-function ensureExtension(filename: string, extension: string, fallbackBase: string): string {
-  const currentExt = path.extname(filename);
-  if (currentExt.toLowerCase() === extension) return filename;
-  const base = currentExt ? filename.slice(0, -currentExt.length) : filename;
-  return `${base || fallbackBase}${extension}`;
-}
-
-function resolveVoiceInfo(filename: string, contentType?: string) {
-  const normalizedType = contentType?.trim().toLowerCase();
-  const extension = path.extname(filename).toLowerCase();
-  const isMp3 = extension === ".mp3" || (normalizedType ? AUDIO_MIME_MP3.has(normalizedType) : false);
-  const isCaf = extension === ".caf" || (normalizedType ? AUDIO_MIME_CAF.has(normalizedType) : false);
-  const isAudio = isMp3 || isCaf || Boolean(normalizedType?.startsWith("audio/"));
-  return { isAudio, isMp3, isCaf };
-}
 
 function resolveAccount(params: BlueBubblesAttachmentOpts) {
   const account = resolveBlueBubblesAccount({
@@ -129,7 +104,6 @@ function extractMessageId(payload: unknown): string {
 /**
  * Send an attachment via BlueBubbles API.
  * Supports sending media files (images, videos, audio, documents) to a chat.
- * When asVoice is true, expects MP3/CAF audio and marks it as an iMessage voice memo.
  */
 export async function sendBlueBubblesAttachment(params: {
   to: string;
@@ -139,37 +113,12 @@ export async function sendBlueBubblesAttachment(params: {
   caption?: string;
   replyToMessageGuid?: string;
   replyToPartIndex?: number;
-  asVoice?: boolean;
   opts?: BlueBubblesAttachmentOpts;
 }): Promise<SendBlueBubblesAttachmentResult> {
-  const { to, caption, replyToMessageGuid, replyToPartIndex, asVoice, opts = {} } = params;
-  let { buffer, filename, contentType } = params;
-  const wantsVoice = asVoice === true;
-  const fallbackName = wantsVoice ? "Audio Message" : "attachment";
-  filename = sanitizeFilename(filename, fallbackName);
-  contentType = contentType?.trim() || undefined;
+  const { to, buffer, filename, contentType, caption, replyToMessageGuid, replyToPartIndex, opts = {} } =
+    params;
   const { baseUrl, password } = resolveAccount(opts);
 
-  // Validate voice memo format when requested (BlueBubbles converts MP3 -> CAF when isAudioMessage).
-  const isAudioMessage = wantsVoice;
-  if (isAudioMessage) {
-    const voiceInfo = resolveVoiceInfo(filename, contentType);
-    if (!voiceInfo.isAudio) {
-      throw new Error("BlueBubbles voice messages require audio media (mp3 or caf).");
-    }
-    if (voiceInfo.isMp3) {
-      filename = ensureExtension(filename, ".mp3", fallbackName);
-      contentType = contentType ?? "audio/mpeg";
-    } else if (voiceInfo.isCaf) {
-      filename = ensureExtension(filename, ".caf", fallbackName);
-      contentType = contentType ?? "audio/x-caf";
-    } else {
-      throw new Error(
-        "BlueBubbles voice messages require mp3 or caf audio (convert before sending).",
-      );
-    }
-  }
-
   const target = resolveSendTarget(to);
   const chatGuid = await resolveChatGuidForTarget({
     baseUrl,
@@ -221,11 +170,6 @@ export async function sendBlueBubblesAttachment(params: {
   addField("tempGuid", `temp-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`);
   addField("method", "private-api");
 
-  // Add isAudioMessage flag for voice memos
-  if (isAudioMessage) {
-    addField("isAudioMessage", "true");
-  }
-
   const trimmedReplyTo = replyToMessageGuid?.trim();
   if (trimmedReplyTo) {
     addField("selectedMessageGuid", trimmedReplyTo);

extensions/bluebubbles/src/media-send.ts

@@ -59,7 +59,6 @@ export async function sendBlueBubblesMedia(params: {
   caption?: string;
   replyToId?: string | null;
   accountId?: string;
-  asVoice?: boolean;
 }) {
   const {
     cfg,
@@ -72,7 +71,6 @@ export async function sendBlueBubblesMedia(params: {
     caption,
     replyToId,
     accountId,
-    asVoice,
   } = params;
   const core = getBlueBubblesRuntime();
   const maxBytes = resolveChannelMediaMaxBytes({
@@ -148,7 +146,6 @@ export async function sendBlueBubblesMedia(params: {
     filename: resolvedFilename ?? "attachment",
     contentType: resolvedContentType ?? undefined,
     replyToMessageGuid,
-    asVoice,
     opts: {
       cfg,
       accountId,

scripts/run-node.mjs

@@ -115,7 +115,12 @@ if (!shouldBuild()) {
   runNode();
 } else {
   logRunner("Building TypeScript (dist is stale).");
-  const build = spawn("pnpm", ["exec", compiler, ...projectArgs], {
+  const pnpmArgs = ["exec", compiler, ...projectArgs];
+  // On Windows, pnpm is a .cmd shim, so use cmd.exe for reliable resolution.
+  const buildCmd = process.platform === "win32" ? "cmd.exe" : "pnpm";
+  const buildArgs =
+    process.platform === "win32" ? ["/d", "/s", "/c", "pnpm", ...pnpmArgs] : pnpmArgs;
+  const build = spawn(buildCmd, buildArgs, {
     cwd,
     env,
     stdio: "inherit",

src/agents/tools/slack-actions.test.ts

@@ -357,6 +357,20 @@ describe("handleSlackAction", () => {
     expect(payload.messages[0].timestampUtc).toBe(new Date(expectedMs).toISOString());
   });
 
+  it("passes threadId through to readSlackMessages", async () => {
+    const cfg = { channels: { slack: { botToken: "tok" } } } as ClawdbotConfig;
+    readSlackMessages.mockClear();
+    readSlackMessages.mockResolvedValueOnce({ messages: [], hasMore: false });
+
+    await handleSlackAction(
+      { action: "readMessages", channelId: "C1", threadId: "12345.6789" },
+      cfg,
+    );
+
+    const [, opts] = readSlackMessages.mock.calls[0] ?? [];
+    expect(opts?.threadId).toBe("12345.6789");
+  });
+
   it("adds normalized timestamps to pin payloads", async () => {
     const cfg = { channels: { slack: { botToken: "tok" } } } as ClawdbotConfig;
     listSlackPins.mockResolvedValueOnce([

src/agents/tools/slack-actions.ts

@@ -214,11 +214,13 @@ export async function handleSlackAction(
           typeof limitRaw === "number" && Number.isFinite(limitRaw) ? limitRaw : undefined;
         const before = readStringParam(params, "before");
         const after = readStringParam(params, "after");
+        const threadId = readStringParam(params, "threadId");
         const result = await readSlackMessages(channelId, {
           ...readOpts,
           limit,
           before: before ?? undefined,
           after: after ?? undefined,
+          threadId: threadId ?? undefined,
         });
         const messages = result.messages.map((message) =>
           withNormalizedTimestamp(

src/channels/plugins/slack.actions.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ClawdbotConfig } from "../../config/config.js";
+import { createSlackActions } from "./slack.actions.js";
+
+const handleSlackAction = vi.fn(async () => ({ details: { ok: true } }));
+
+vi.mock("../../agents/tools/slack-actions.js", () => ({
+  handleSlackAction: (...args: unknown[]) => handleSlackAction(...args),
+}));
+
+describe("slack actions adapter", () => {
+  it("forwards threadId for read", async () => {
+    const cfg = { channels: { slack: { botToken: "tok" } } } as ClawdbotConfig;
+    const actions = createSlackActions("slack");
+
+    await actions.handleAction?.({
+      channel: "slack",
+      action: "read",
+      cfg,
+      params: {
+        channelId: "C1",
+        threadId: "171234.567",
+      },
+    });
+
+    const [params] = handleSlackAction.mock.calls[0] ?? [];
+    expect(params).toMatchObject({
+      action: "readMessages",
+      channelId: "C1",
+      threadId: "171234.567",
+    });
+  });
+});

src/channels/plugins/slack.actions.ts

@@ -133,6 +133,7 @@ export function createSlackActions(providerId: string): ChannelMessageActionAdap
             limit,
             before: readStringParam(params, "before"),
             after: readStringParam(params, "after"),
+            threadId: readStringParam(params, "threadId"),
             accountId: accountId ?? undefined,
           },
           cfg,

src/cli/argv.test.ts

@@ -78,6 +78,16 @@ describe("argv helpers", () => {
     });
     expect(nodeArgv).toEqual(["node", "clawdbot", "status"]);
 
+    const nodeExeArgv = buildParseArgv({
+      programName: "clawdbot",
+      rawArgs: ["C:\\\\Program Files\\\\nodejs\\\\Node.EXE", "clawdbot", "status"],
+    });
+    expect(nodeExeArgv).toEqual([
+      "C:\\\\Program Files\\\\nodejs\\\\Node.EXE",
+      "clawdbot",
+      "status",
+    ]);
+
     const directArgv = buildParseArgv({
       programName: "clawdbot",
       rawArgs: ["clawdbot", "status"],
@@ -89,6 +99,12 @@ describe("argv helpers", () => {
       rawArgs: ["bun", "src/entry.ts", "status"],
     });
     expect(bunArgv).toEqual(["bun", "src/entry.ts", "status"]);
+
+    const bunExeArgv = buildParseArgv({
+      programName: "clawdbot",
+      rawArgs: ["C:\\\\bun\\\\bun.exe", "src\\\\entry.ts", "status"],
+    });
+    expect(bunExeArgv).toEqual(["C:\\\\bun\\\\bun.exe", "src\\\\entry.ts", "status"]);
   });
 
   it("builds parse argv from fallback args", () => {

src/cli/argv.ts

@@ -94,9 +94,14 @@ export function buildParseArgv(params: {
       : baseArgv[0]?.endsWith("clawdbot")
         ? baseArgv.slice(1)
         : baseArgv;
-  const executable = normalizedArgv[0]?.split(/[/\\]/).pop() ?? "";
+  const executable = (normalizedArgv[0]?.split(/[/\\]/).pop() ?? "").toLowerCase();
+  // Normalize Windows `.exe` runtimes (node.exe/bun.exe) for runtime detection.
   const looksLikeNode =
-    normalizedArgv.length >= 2 && (executable === "node" || executable === "bun");
+    normalizedArgv.length >= 2 &&
+    (executable === "node" ||
+      executable === "node.exe" ||
+      executable === "bun" ||
+      executable === "bun.exe");
   if (looksLikeNode) return normalizedArgv;
   return ["node", programName || "clawdbot", ...normalizedArgv];
 }

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

@@ -49,469 +49,372 @@ function parseSseDataLines(text: string): string[] {
 }
 
 describe("OpenAI-compatible HTTP API (e2e)", () => {
-  it("is disabled by default (requires config)", { timeout: 120_000 }, async () => {
-    const port = await getFreePort();
-    const server = await startServerWithDefaultConfig(port);
-    try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [{ role: "user", content: "hi" }],
+  it("rejects when disabled (default + config)", { timeout: 120_000 }, async () => {
+    {
+      const port = await getFreePort();
+      const server = await startServerWithDefaultConfig(port);
+      try {
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(res.status).toBe(404);
+      } finally {
+        await server.close({ reason: "test done" });
+      }
+    }
+
+    {
+      const port = await getFreePort();
+      const server = await startServer(port, {
+        openAiChatCompletionsEnabled: false,
       });
-      expect(res.status).toBe(404);
-    } finally {
-      await server.close({ reason: "test done" });
+      try {
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(res.status).toBe(404);
+      } 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,
-    });
-    try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [{ role: "user", content: "hi" }],
-      });
-      expect(res.status).toBe(404);
-    } 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 server.close({ reason: "test done" });
-    }
-  });
+      {
+        const res = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+          method: "GET",
+          headers: { authorization: "Bearer secret" },
+        });
+        expect(res.status).toBe(405);
+        await res.text();
+      }
 
-  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 server.close({ reason: "test done" });
-    }
-  });
+      {
+        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);
+        await res.text();
+      }
 
-  it("routes to a specific agent via header", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(
+          port,
+          { model: "clawdbot", messages: [{ role: "user", content: "hi" }] },
+          { "x-clawdbot-agent-id": "beta" },
+        );
+        expect(res.status).toBe(200);
 
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(
-        port,
-        { model: "clawdbot", messages: [{ role: "user", content: "hi" }] },
-        { "x-clawdbot-agent-id": "beta" },
-      );
-      expect(res.status).toBe(200);
+        expect(agentCommand).toHaveBeenCalledTimes(1);
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
+          /^agent:beta:/,
+        );
+        await res.text();
+      }
 
-      expect(agentCommand).toHaveBeenCalledTimes(1);
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
-        /^agent:beta:/,
-      );
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("routes to a specific agent via model (no custom headers)", async () => {
-    agentCommand.mockResolvedValueOnce({
-      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" }],
-      });
-      expect(res.status).toBe(200);
-
-      expect(agentCommand).toHaveBeenCalledTimes(1);
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
-        /^agent:beta:/,
-      );
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("prefers explicit header agent over model agent", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(
-        port,
-        {
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(port, {
           model: "clawdbot:beta",
           messages: [{ role: "user", content: "hi" }],
-        },
-        { "x-clawdbot-agent-id": "alpha" },
-      );
-      expect(res.status).toBe(200);
+        });
+        expect(res.status).toBe(200);
 
-      expect(agentCommand).toHaveBeenCalledTimes(1);
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
-        /^agent:alpha:/,
-      );
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
+        expect(agentCommand).toHaveBeenCalledTimes(1);
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
+          /^agent:beta:/,
+        );
+        await res.text();
+      }
 
-  it("honors x-clawdbot-session-key override", async () => {
-    agentCommand.mockResolvedValueOnce({
-      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" }] },
-        {
-          "x-clawdbot-agent-id": "beta",
-          "x-clawdbot-session-key": "agent:beta:openai:custom",
-        },
-      );
-      expect(res.status).toBe(200);
-
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      expect((opts as { sessionKey?: string } | undefined)?.sessionKey).toBe(
-        "agent:beta:openai:custom",
-      );
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("uses OpenAI user for a stable session key", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
-        user: "alice",
-        model: "clawdbot",
-        messages: [{ role: "user", content: "hi" }],
-      });
-      expect(res.status).toBe(200);
-
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toContain(
-        "openai-user:alice",
-      );
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("extracts user message text from array content", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(
+          port,
           {
-            role: "user",
-            content: [
-              { type: "text", text: "hello" },
-              { type: "input_text", text: "world" },
-            ],
+            model: "clawdbot:beta",
+            messages: [{ role: "user", content: "hi" }],
           },
-        ],
-      });
-      expect(res.status).toBe(200);
+          { "x-clawdbot-agent-id": "alpha" },
+        );
+        expect(res.status).toBe(200);
 
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      expect((opts as { message?: string } | undefined)?.message).toBe("hello\nworld");
+        expect(agentCommand).toHaveBeenCalledTimes(1);
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toMatch(
+          /^agent:alpha:/,
+        );
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(
+          port,
+          { model: "clawdbot", messages: [{ role: "user", content: "hi" }] },
+          {
+            "x-clawdbot-agent-id": "beta",
+            "x-clawdbot-session-key": "agent:beta:openai:custom",
+          },
+        );
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        expect((opts as { sessionKey?: string } | undefined)?.sessionKey).toBe(
+          "agent:beta:openai:custom",
+        );
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(port, {
+          user: "alice",
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        expect((opts as { sessionKey?: string } | undefined)?.sessionKey ?? "").toContain(
+          "openai-user:alice",
+        );
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [
+            {
+              role: "user",
+              content: [
+                { type: "text", text: "hello" },
+                { type: "input_text", text: "world" },
+              ],
+            },
+          ],
+        });
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        expect((opts as { message?: string } | undefined)?.message).toBe("hello\nworld");
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "I am Claude" }]);
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [
+            { role: "system", content: "You are a helpful assistant." },
+            { role: "user", content: "Hello, who are you?" },
+            { role: "assistant", content: "I am Claude." },
+            { role: "user", content: "What did I just ask you?" },
+          ],
+        });
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        const message = (opts as { message?: string } | undefined)?.message ?? "";
+        expect(message).toContain(HISTORY_CONTEXT_MARKER);
+        expect(message).toContain("User: Hello, who are you?");
+        expect(message).toContain("Assistant: I am Claude.");
+        expect(message).toContain(CURRENT_MESSAGE_MARKER);
+        expect(message).toContain("User: What did I just ask you?");
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [
+            { role: "system", content: "You are a helpful assistant." },
+            { role: "user", content: "Hello" },
+          ],
+        });
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        const message = (opts as { message?: string } | undefined)?.message ?? "";
+        expect(message).not.toContain(HISTORY_CONTEXT_MARKER);
+        expect(message).not.toContain(CURRENT_MESSAGE_MARKER);
+        expect(message).toBe("Hello");
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [
+            { role: "developer", content: "You are a helpful assistant." },
+            { role: "user", content: "Hello" },
+          ],
+        });
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        const extraSystemPrompt =
+          (opts as { extraSystemPrompt?: string } | undefined)?.extraSystemPrompt ?? "";
+        expect(extraSystemPrompt).toBe("You are a helpful assistant.");
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "ok" }]);
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [
+            { role: "system", content: "You are a helpful assistant." },
+            { role: "user", content: "What's the weather?" },
+            { role: "assistant", content: "Checking the weather." },
+            { role: "tool", content: "Sunny, 70F." },
+          ],
+        });
+        expect(res.status).toBe(200);
+
+        const [opts] = agentCommand.mock.calls[0] ?? [];
+        const message = (opts as { message?: string } | undefined)?.message ?? "";
+        expect(message).toContain(HISTORY_CONTEXT_MARKER);
+        expect(message).toContain("User: What's the weather?");
+        expect(message).toContain("Assistant: Checking the weather.");
+        expect(message).toContain(CURRENT_MESSAGE_MARKER);
+        expect(message).toContain("Tool: Sunny, 70F.");
+        await res.text();
+      }
+
+      {
+        mockAgentOnce([{ text: "hello" }]);
+        const res = await postChatCompletions(port, {
+          stream: false,
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(res.status).toBe(200);
+        const json = (await res.json()) as Record<string, unknown>;
+        expect(json.object).toBe("chat.completion");
+        expect(Array.isArray(json.choices)).toBe(true);
+        const choice0 = (json.choices as Array<Record<string, unknown>>)[0] ?? {};
+        const msg = (choice0.message as Record<string, unknown> | undefined) ?? {};
+        expect(msg.role).toBe("assistant");
+        expect(msg.content).toBe("hello");
+      }
+
+      {
+        const res = await postChatCompletions(port, {
+          model: "clawdbot",
+          messages: [{ role: "system", content: "yo" }],
+        });
+        expect(res.status).toBe(400);
+        const missingUserJson = (await res.json()) as Record<string, unknown>;
+        expect((missingUserJson.error as Record<string, unknown> | undefined)?.type).toBe(
+          "invalid_request_error",
+        );
+      }
     } finally {
       await server.close({ reason: "test done" });
     }
   });
 
-  it("includes conversation history when multiple messages are provided", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "I am Claude" }],
-    } as never);
-
+  it("streams SSE chunks when stream=true", async () => {
     const port = await getFreePort();
     const server = await startServer(port);
     try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [
-          { role: "system", content: "You are a helpful assistant." },
-          { role: "user", content: "Hello, who are you?" },
-          { role: "assistant", content: "I am Claude." },
-          { role: "user", content: "What did I just ask you?" },
-        ],
-      });
-      expect(res.status).toBe(200);
+      {
+        agentCommand.mockReset();
+        agentCommand.mockImplementationOnce(async (opts: unknown) => {
+          const runId = (opts as { runId?: string } | undefined)?.runId ?? "";
+          emitAgentEvent({ runId, stream: "assistant", data: { delta: "he" } });
+          emitAgentEvent({ runId, stream: "assistant", data: { delta: "llo" } });
+          return { payloads: [{ text: "hello" }] } as never;
+        });
 
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      const message = (opts as { message?: string } | undefined)?.message ?? "";
-      expect(message).toContain(HISTORY_CONTEXT_MARKER);
-      expect(message).toContain("User: Hello, who are you?");
-      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 server.close({ reason: "test done" });
-    }
-  });
+        const res = await postChatCompletions(port, {
+          stream: true,
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(res.status).toBe(200);
+        expect(res.headers.get("content-type") ?? "").toContain("text/event-stream");
 
-  it("does not include history markers for single message", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
+        const text = await res.text();
+        const data = parseSseDataLines(text);
+        expect(data[data.length - 1]).toBe("[DONE]");
 
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [
-          { role: "system", content: "You are a helpful assistant." },
-          { role: "user", content: "Hello" },
-        ],
-      });
-      expect(res.status).toBe(200);
+        const jsonChunks = data
+          .filter((d) => d !== "[DONE]")
+          .map((d) => JSON.parse(d) as Record<string, unknown>);
+        expect(jsonChunks.some((c) => c.object === "chat.completion.chunk")).toBe(true);
+        const allContent = jsonChunks
+          .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("hello");
+      }
 
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      const message = (opts as { message?: string } | undefined)?.message ?? "";
-      expect(message).not.toContain(HISTORY_CONTEXT_MARKER);
-      expect(message).not.toContain(CURRENT_MESSAGE_MARKER);
-      expect(message).toBe("Hello");
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
+      {
+        agentCommand.mockReset();
+        agentCommand.mockImplementationOnce(async (opts: unknown) => {
+          const runId = (opts as { runId?: string } | undefined)?.runId ?? "";
+          emitAgentEvent({ runId, stream: "assistant", data: { delta: "hi" } });
+          emitAgentEvent({ runId, stream: "assistant", data: { delta: "hi" } });
+          return { payloads: [{ text: "hihi" }] } as never;
+        });
 
-  it("treats developer role same as system role", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
+        const repeatedRes = await postChatCompletions(port, {
+          stream: true,
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(repeatedRes.status).toBe(200);
+        const repeatedText = await repeatedRes.text();
+        const repeatedData = parseSseDataLines(repeatedText);
+        const repeatedChunks = repeatedData
+          .filter((d) => d !== "[DONE]")
+          .map((d) => JSON.parse(d) as Record<string, unknown>);
+        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(repeatedContent).toBe("hihi");
+      }
 
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [
-          { role: "developer", content: "You are a helpful assistant." },
-          { role: "user", content: "Hello" },
-        ],
-      });
-      expect(res.status).toBe(200);
+      {
+        agentCommand.mockReset();
+        agentCommand.mockResolvedValueOnce({
+          payloads: [{ text: "hello" }],
+        } as never);
 
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      const extraSystemPrompt =
-        (opts as { extraSystemPrompt?: string } | undefined)?.extraSystemPrompt ?? "";
-      expect(extraSystemPrompt).toBe("You are a helpful assistant.");
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("includes tool output when it is the latest message", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "ok" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
-        model: "clawdbot",
-        messages: [
-          { role: "system", content: "You are a helpful assistant." },
-          { role: "user", content: "What's the weather?" },
-          { role: "assistant", content: "Checking the weather." },
-          { role: "tool", content: "Sunny, 70F." },
-        ],
-      });
-      expect(res.status).toBe(200);
-
-      const [opts] = agentCommand.mock.calls[0] ?? [];
-      const message = (opts as { message?: string } | undefined)?.message ?? "";
-      expect(message).toContain(HISTORY_CONTEXT_MARKER);
-      expect(message).toContain("User: What's the weather?");
-      expect(message).toContain("Assistant: Checking the weather.");
-      expect(message).toContain(CURRENT_MESSAGE_MARKER);
-      expect(message).toContain("Tool: Sunny, 70F.");
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("returns a non-streaming OpenAI chat.completion response", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    const server = await startServer(port);
-    try {
-      const res = await postChatCompletions(port, {
-        stream: false,
-        model: "clawdbot",
-        messages: [{ role: "user", content: "hi" }],
-      });
-      expect(res.status).toBe(200);
-      const json = (await res.json()) as Record<string, unknown>;
-      expect(json.object).toBe("chat.completion");
-      expect(Array.isArray(json.choices)).toBe(true);
-      const choice0 = (json.choices as Array<Record<string, unknown>>)[0] ?? {};
-      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>;
-      expect((json.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 () => {
-    agentCommand.mockImplementationOnce(async (opts: unknown) => {
-      const runId = (opts as { runId?: string } | undefined)?.runId ?? "";
-      emitAgentEvent({ runId, stream: "assistant", data: { delta: "he" } });
-      emitAgentEvent({ runId, stream: "assistant", data: { delta: "llo" } });
-      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",
-        messages: [{ role: "user", content: "hi" }],
-      });
-      expect(res.status).toBe(200);
-      expect(res.headers.get("content-type") ?? "").toContain("text/event-stream");
-
-      const text = await res.text();
-      const data = parseSseDataLines(text);
-      expect(data[data.length - 1]).toBe("[DONE]");
-
-      const jsonChunks = data
-        .filter((d) => d !== "[DONE]")
-        .map((d) => JSON.parse(d) as Record<string, unknown>);
-      expect(jsonChunks.some((c) => c.object === "chat.completion.chunk")).toBe(true);
-      const allContent = jsonChunks
-        .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("hello");
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("preserves repeated identical deltas when streaming SSE", async () => {
-    agentCommand.mockImplementationOnce(async (opts: unknown) => {
-      const runId = (opts as { runId?: string } | undefined)?.runId ?? "";
-      emitAgentEvent({ runId, stream: "assistant", data: { delta: "hi" } });
-      emitAgentEvent({ runId, stream: "assistant", data: { delta: "hi" } });
-      return { payloads: [{ text: "hihi" }] } as never;
-    });
-
-    const port = await getFreePort();
-    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);
-      const text = await res.text();
-      const data = parseSseDataLines(text);
-      const jsonChunks = data
-        .filter((d) => d !== "[DONE]")
-        .map((d) => JSON.parse(d) as Record<string, unknown>);
-      const allContent = jsonChunks
-        .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");
-    } finally {
-      await server.close({ reason: "test done" });
-    }
-  });
-
-  it("streams SSE chunks when stream=true (fallback when no deltas)", async () => {
-    agentCommand.mockResolvedValueOnce({
-      payloads: [{ text: "hello" }],
-    } as never);
-
-    const port = await getFreePort();
-    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);
-      const text = await res.text();
-      expect(text).toContain("[DONE]");
-      expect(text).toContain("hello");
+        const fallbackRes = await postChatCompletions(port, {
+          stream: true,
+          model: "clawdbot",
+          messages: [{ role: "user", content: "hi" }],
+        });
+        expect(fallbackRes.status).toBe(200);
+        const fallbackText = await fallbackRes.text();
+        expect(fallbackText).toContain("[DONE]");
+        expect(fallbackText).toContain("hello");
+      }
     } finally {
       await server.close({ reason: "test done" });
     }

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

@@ -1,95 +1,106 @@
 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 () => {
-  for (const { server, ws } of servers) {
-    try {
-      ws.close();
-      await server.close();
-    } catch {
-      /* ignore */
-    }
-  }
-  servers.length = 0;
-  await new Promise((resolve) => setTimeout(resolve, 50));
+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 () => {
+  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();
-    servers.push(result);
-    const { ws } = result;
-    await connectOk(ws);
-
-    const id = "req-1";
-    ws.send(
-      JSON.stringify({
-        type: "req",
-        id,
-        method: "config.apply",
-        params: {
-          raw: '{ "agents": { "list": [{ "id": "main", "workspace": "~/clawd" }] } }',
-          sessionKey: "agent:main:whatsapp:dm:+15555550123",
-          restartDelayMs: 0,
-        },
-      }),
-    );
-    const res = await onceMessage<{ ok: boolean; payload?: unknown }>(
-      ws,
-      (o) => o.type === "res" && o.id === id,
-    );
-    expect(res.ok).toBe(true);
-
-    // Verify sentinel file was created (restart was scheduled)
-    const sentinelPath = path.join(os.homedir(), ".clawdbot", "restart-sentinel.json");
-
-    // Wait for file to be written
-    await new Promise((resolve) => setTimeout(resolve, 100));
-
+    const ws = await openClient();
     try {
-      const raw = await fs.readFile(sentinelPath, "utf-8");
-      const parsed = JSON.parse(raw) as { payload?: { kind?: string } };
-      expect(parsed.payload?.kind).toBe("config-apply");
-    } catch {
-      // File may not exist if signal delivery is mocked, verify response was ok instead
+      const id = "req-1";
+      ws.send(
+        JSON.stringify({
+          type: "req",
+          id,
+          method: "config.apply",
+          params: {
+            raw: '{ "agents": { "list": [{ "id": "main", "workspace": "~/clawd" }] } }',
+            sessionKey: "agent:main:whatsapp:dm:+15555550123",
+            restartDelayMs: 0,
+          },
+        }),
+      );
+      const res = await onceMessage<{ ok: boolean; payload?: unknown }>(
+        ws,
+        (o) => o.type === "res" && o.id === id,
+      );
       expect(res.ok).toBe(true);
+
+      // Verify sentinel file was created (restart was scheduled)
+      const sentinelPath = path.join(os.homedir(), ".clawdbot", "restart-sentinel.json");
+
+      // Wait for file to be written
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      try {
+        const raw = await fs.readFile(sentinelPath, "utf-8");
+        const parsed = JSON.parse(raw) as { payload?: { kind?: string } };
+        expect(parsed.payload?.kind).toBe("config-apply");
+      } catch {
+        // 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();
-    servers.push(result);
-    const { ws } = result;
-    await connectOk(ws);
-
-    const id = "req-2";
-    ws.send(
-      JSON.stringify({
-        type: "req",
-        id,
-        method: "config.apply",
-        params: {
-          raw: "{",
-        },
-      }),
-    );
-    const res = await onceMessage<{ ok: boolean; error?: unknown }>(
-      ws,
-      (o) => o.type === "res" && o.id === id,
-    );
-    expect(res.ok).toBe(false);
+    const ws = await openClient();
+    try {
+      const id = "req-2";
+      ws.send(
+        JSON.stringify({
+          type: "req",
+          id,
+          method: "config.apply",
+          params: {
+            raw: "{",
+          },
+        }),
+      );
+      const res = await onceMessage<{ ok: boolean; error?: unknown }>(
+        ws,
+        (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();
-    await connectOk(ws);
+    const ws = await openClient();
 
     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();
-    await connectOk(ws);
+    const ws = await openClient();
 
     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();
-    await connectOk(ws);
+    const ws = await openClient();
 
     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();
-    await connectOk(ws);
+    const ws = await openClient();
 
     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 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 clients = await Promise.all([openClient(), openClient(), openClient()]);
     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();
-    await connectOk(ws, {
+    const ws = await openClient({
       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 hello = await connectOk(ws);
+    const { ws, hello } = await openClient();
     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();
-    await connectOk(ws);
+    const { ws } = await openClient();
     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();
-    await connectOk(ws);
+    const { ws } = await openClient();
 
     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,67 +75,79 @@ export async function writeSessionStore(params: {
   await fs.writeFile(storePath, JSON.stringify(store, null, 2), "utf-8");
 }
 
-export function installGatewayTestHooks() {
-  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;
-    previousConfigPath = process.env.CLAWDBOT_CONFIG_PATH;
-    previousSkipBrowserControl = process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER;
-    previousSkipGmailWatcher = process.env.CLAWDBOT_SKIP_GMAIL_WATCHER;
-    previousSkipCanvasHost = process.env.CLAWDBOT_SKIP_CANVAS_HOST;
-    tempHome = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-gateway-home-"));
-    process.env.HOME = tempHome;
-    process.env.USERPROFILE = tempHome;
-    process.env.CLAWDBOT_STATE_DIR = path.join(tempHome, ".clawdbot");
-    delete process.env.CLAWDBOT_CONFIG_PATH;
-    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");
-    setTestConfigRoot(tempConfigRoot);
-    sessionStoreSaveDelayMs.value = 0;
-    testTailnetIPv4.value = undefined;
-    testState.gatewayBind = undefined;
-    testState.gatewayAuth = undefined;
-    testState.gatewayControlUi = undefined;
-    testState.hooksConfig = undefined;
-    testState.canvasHostPort = undefined;
-    testState.legacyIssues = [];
-    testState.legacyParsed = {};
-    testState.migrationConfig = null;
-    testState.migrationChanges = [];
-    testState.cronEnabled = false;
-    testState.cronStorePath = undefined;
-    testState.sessionConfig = undefined;
-    testState.sessionStorePath = undefined;
-    testState.agentConfig = undefined;
-    testState.agentsConfig = undefined;
-    testState.bindingsConfig = undefined;
-    testState.channelsConfig = undefined;
-    testState.allowFrom = undefined;
-    testIsNixMode.value = false;
-    cronIsolatedRun.mockClear();
-    agentCommand.mockClear();
-    embeddedRunMock.activeIds.clear();
-    embeddedRunMock.abortCalls = [];
-    embeddedRunMock.waitCalls = [];
-    embeddedRunMock.waitResults.clear();
-    drainSystemEvents(resolveMainSessionKeyFromConfig());
-    resetAgentRunContextForTest();
-    const mod = await serverModulePromise;
-    mod.__resetModelCatalogCacheForTest();
-    piSdkMock.enabled = false;
-    piSdkMock.discoverCalls = 0;
-    piSdkMock.models = [];
-  }, 60_000);
+async function setupGatewayTestHome() {
+  previousHome = process.env.HOME;
+  previousUserProfile = process.env.USERPROFILE;
+  previousStateDir = process.env.CLAWDBOT_STATE_DIR;
+  previousConfigPath = process.env.CLAWDBOT_CONFIG_PATH;
+  previousSkipBrowserControl = process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER;
+  previousSkipGmailWatcher = process.env.CLAWDBOT_SKIP_GMAIL_WATCHER;
+  previousSkipCanvasHost = process.env.CLAWDBOT_SKIP_CANVAS_HOST;
+  tempHome = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-gateway-home-"));
+  process.env.HOME = tempHome;
+  process.env.USERPROFILE = tempHome;
+  process.env.CLAWDBOT_STATE_DIR = path.join(tempHome, ".clawdbot");
+  delete process.env.CLAWDBOT_CONFIG_PATH;
+}
 
-  afterEach(async () => {
-    vi.useRealTimers();
-    resetLogger();
+function applyGatewaySkipEnv() {
+  process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER = "1";
+  process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = "1";
+  process.env.CLAWDBOT_SKIP_CANVAS_HOST = "1";
+}
+
+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;
+  testState.gatewayBind = undefined;
+  testState.gatewayAuth = undefined;
+  testState.gatewayControlUi = undefined;
+  testState.hooksConfig = undefined;
+  testState.canvasHostPort = undefined;
+  testState.legacyIssues = [];
+  testState.legacyParsed = {};
+  testState.migrationConfig = null;
+  testState.migrationChanges = [];
+  testState.cronEnabled = false;
+  testState.cronStorePath = undefined;
+  testState.sessionConfig = undefined;
+  testState.sessionStorePath = undefined;
+  testState.agentConfig = undefined;
+  testState.agentsConfig = undefined;
+  testState.bindingsConfig = undefined;
+  testState.channelsConfig = undefined;
+  testState.allowFrom = undefined;
+  testIsNixMode.value = false;
+  cronIsolatedRun.mockClear();
+  agentCommand.mockClear();
+  embeddedRunMock.activeIds.clear();
+  embeddedRunMock.abortCalls = [];
+  embeddedRunMock.waitCalls = [];
+  embeddedRunMock.waitResults.clear();
+  drainSystemEvents(resolveMainSessionKeyFromConfig());
+  resetAgentRunContextForTest();
+  const mod = await serverModulePromise;
+  mod.__resetModelCatalogCacheForTest();
+  piSdkMock.enabled = false;
+  piSdkMock.discoverCalls = 0;
+  piSdkMock.models = [];
+}
+
+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,16 +163,45 @@ 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) {
-      await fs.rm(tempHome, {
-        recursive: true,
-        force: true,
-        maxRetries: 20,
-        retryDelay: 25,
-      });
-      tempHome = undefined;
-    }
-    tempConfigRoot = undefined;
+  }
+  if (options.restoreEnv && tempHome) {
+    await fs.rm(tempHome, {
+      recursive: true,
+      force: true,
+      maxRetries: 20,
+      retryDelay: 25,
+    });
+    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 });
   });
 }
 

src/slack/actions.read.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { WebClient } from "@slack/web-api";
+
+import { readSlackMessages } from "./actions.js";
+
+function createClient() {
+  return {
+    conversations: {
+      replies: vi.fn(async () => ({ messages: [], has_more: false })),
+      history: vi.fn(async () => ({ messages: [], has_more: false })),
+    },
+  } as unknown as WebClient & {
+    conversations: {
+      replies: ReturnType<typeof vi.fn>;
+      history: ReturnType<typeof vi.fn>;
+    };
+  };
+}
+
+describe("readSlackMessages", () => {
+  it("uses conversations.replies and drops the parent message", async () => {
+    const client = createClient();
+    client.conversations.replies.mockResolvedValueOnce({
+      messages: [{ ts: "171234.567" }, { ts: "171234.890" }, { ts: "171235.000" }],
+      has_more: true,
+    });
+
+    const result = await readSlackMessages("C1", {
+      client,
+      threadId: "171234.567",
+      token: "xoxb-test",
+    });
+
+    expect(client.conversations.replies).toHaveBeenCalledWith({
+      channel: "C1",
+      ts: "171234.567",
+      limit: undefined,
+      latest: undefined,
+      oldest: undefined,
+    });
+    expect(client.conversations.history).not.toHaveBeenCalled();
+    expect(result.messages.map((message) => message.ts)).toEqual(["171234.890", "171235.000"]);
+  });
+
+  it("uses conversations.history when threadId is missing", async () => {
+    const client = createClient();
+    client.conversations.history.mockResolvedValueOnce({
+      messages: [{ ts: "1" }],
+      has_more: false,
+    });
+
+    const result = await readSlackMessages("C1", {
+      client,
+      limit: 20,
+      token: "xoxb-test",
+    });
+
+    expect(client.conversations.history).toHaveBeenCalledWith({
+      channel: "C1",
+      limit: 20,
+      latest: undefined,
+      oldest: undefined,
+    });
+    expect(client.conversations.replies).not.toHaveBeenCalled();
+    expect(result.messages.map((message) => message.ts)).toEqual(["1"]);
+  });
+});

src/slack/actions.ts

@@ -186,9 +186,29 @@ export async function readSlackMessages(
     limit?: number;
     before?: string;
     after?: string;
+    threadId?: string;
   } = {},
 ): Promise<{ messages: SlackMessageSummary[]; hasMore: boolean }> {
   const client = await getClient(opts);
+
+  // Use conversations.replies for thread messages, conversations.history for channel messages.
+  if (opts.threadId) {
+    const result = await client.conversations.replies({
+      channel: channelId,
+      ts: opts.threadId,
+      limit: opts.limit,
+      latest: opts.before,
+      oldest: opts.after,
+    });
+    return {
+      // conversations.replies includes the parent message; drop it for replies-only reads.
+      messages: (result.messages ?? []).filter(
+        (message) => (message as SlackMessageSummary)?.ts !== opts.threadId,
+      ) as SlackMessageSummary[],
+      hasMore: Boolean(result.has_more),
+    };
+  }
+
   const result = await client.conversations.history({
     channel: channelId,
     limit: opts.limit,