feat: add slack replyToModeByChatType overrides (#1442) (thanks @stefangalescu)

Adds support for separate replyToMode settings for DMs vs channels:

- Add channels.slack.dm.replyToMode for DM-specific threading
- Keep channels.slack.replyToMode as default for channels
- Add resolveSlackReplyToMode helper to centralize logic
- Pass chatType through threading resolution chain

Usage:
```json5
{
  channels: {
    slack: {
      replyToMode: "off",     // channels
      dm: {
        replyToMode: "all"    // DMs always thread
      }
    }
  }
}
```

When dm.replyToMode is set, DMs use that mode; channels use the
top-level replyToMode. Backward compatible when not configured.

CHANGELOG.md

@@ -8,11 +8,14 @@ Docs: https://docs.clawd.bot
 - Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster
 - 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.
+- Slack: add chat-type reply threading overrides via `replyToModeByChatType`. (#1442) Thanks @stefangalescu.
 - 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, #1482) 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.
 - UI: show per-session assistant identity in the Control UI. (#1420) Thanks @robbyczgw-cla.
+- Onboarding: add hatch choice (TUI/Web/Later), token explainer, background dashboard seed on macOS, and showcase link.
 - Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).
 - Signal: add typing indicators and DM read receipts via signal-cli.
 - MSTeams: add file uploads, adaptive cards, and attachment handling improvements. (#1410) Thanks @Evizero.
@@ -31,12 +34,14 @@ Docs: https://docs.clawd.bot
 - Agents: make OpenAI sessions image-sanitize-only; gate tool-id/repair sanitization by provider.
 - Doctor: honor CLAWDBOT_GATEWAY_TOKEN for auth checks and security audit token reuse. (#1448) Thanks @azade-c.
 - Agents: make tool summaries more readable and only show optional params when set.
+- Agents: honor SOUL.md guidance even when the file is nested or path-qualified. (#1434) Thanks @neooriginal.
 - CLI: prefer `~` for home paths in output.
 - Mattermost (plugin): enforce pairing/allowlist gating, keep @username targets, and clarify plugin-only docs. (#1428) Thanks @damoahdominic.
 - Agents: centralize transcript sanitization in the runner; keep <final> tags and error turns intact.
 - 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,7 +147,8 @@ 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`)
+- **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.
 
 ### Message IDs (short vs full)
 Clawdbot may surface *short* message IDs (e.g., `1`, `2`) to save tokens.

docs/channels/slack.md

@@ -304,7 +304,8 @@ Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
       "policy": "pairing",
       "allowFrom": ["U123", "U456", "*"],
       "groupEnabled": false,
-      "groupChannels": ["G123"]
+      "groupChannels": ["G123"],
+      "replyToMode": "all"
     },
     "channels": {
       "C123": { "allow": true, "requireMention": true },
@@ -361,6 +362,25 @@ By default, Clawdbot replies in the main channel. Use `channels.slack.replyToMod
 
 The mode applies to both auto-replies and agent tool calls (`slack sendMessage`).
 
+### Per-chat-type threading
+You can configure different threading behavior per chat type by setting `channels.slack.replyToModeByChatType`:
+
+```json5
+{
+  channels: {
+    slack: {
+      replyToMode: "off",        // default for channels
+      replyToModeByChatType: {
+        direct: "all",           // DMs always thread
+        group: "first"           // group DMs/MPIM thread first reply
+      },
+    }
+  }
+}
+```
+
+When a chat-type override is set, it takes precedence for that chat type. Otherwise the top-level `replyToMode` is used.
+
 ### Manual threading tags
 For fine-grained control, use these tags in agent responses:
 - `[[reply_to_current]]` — reply to the triggering message (start/continue thread).

extensions/bluebubbles/src/actions.test.ts

@@ -521,6 +521,42 @@ 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,7 +3,6 @@ import {
   BLUEBUBBLES_ACTIONS,
   createActionGate,
   jsonResult,
-  readBooleanParam,
   readNumberParam,
   readReactionParams,
   readStringParam,
@@ -51,6 +50,17 @@ 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);
 
@@ -356,6 +366,7 @@ 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");
@@ -380,6 +391,7 @@ 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 } from "./attachments.js";
+import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";
 import type { BlueBubblesAttachment } from "./types.js";
 
 vi.mock("./accounts.js", () => ({
@@ -238,3 +238,109 @@ 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,4 +1,5 @@
 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";
@@ -19,6 +20,30 @@ 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({
@@ -104,6 +129,7 @@ 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;
@@ -113,12 +139,37 @@ export async function sendBlueBubblesAttachment(params: {
   caption?: string;
   replyToMessageGuid?: string;
   replyToPartIndex?: number;
+  asVoice?: boolean;
   opts?: BlueBubblesAttachmentOpts;
 }): Promise<SendBlueBubblesAttachmentResult> {
-  const { to, buffer, filename, contentType, caption, replyToMessageGuid, replyToPartIndex, opts = {} } =
-    params;
+  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 { 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,
@@ -170,6 +221,11 @@ 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,6 +59,7 @@ export async function sendBlueBubblesMedia(params: {
   caption?: string;
   replyToId?: string | null;
   accountId?: string;
+  asVoice?: boolean;
 }) {
   const {
     cfg,
@@ -71,6 +72,7 @@ export async function sendBlueBubblesMedia(params: {
     caption,
     replyToId,
     accountId,
+    asVoice,
   } = params;
   const core = getBlueBubblesRuntime();
   const maxBytes = resolveChannelMediaMaxBytes({
@@ -146,6 +148,7 @@ export async function sendBlueBubblesMedia(params: {
     filename: resolvedFilename ?? "attachment",
     contentType: resolvedContentType ?? undefined,
     replyToMessageGuid,
+    asVoice,
     opts: {
       cfg,
       accountId,

extensions/slack/src/channel.ts

@@ -19,6 +19,7 @@ import {
   readStringParam,
   resolveDefaultSlackAccountId,
   resolveSlackAccount,
+  resolveSlackReplyToMode,
   resolveSlackGroupRequireMention,
   buildSlackThreadingToolContext,
   setAccountEnabledInConfigSection,
@@ -162,8 +163,8 @@ export const slackPlugin: ChannelPlugin<ResolvedSlackAccount> = {
     resolveRequireMention: resolveSlackGroupRequireMention,
   },
   threading: {
-    resolveReplyToMode: ({ cfg, accountId }) =>
-      resolveSlackAccount({ cfg, accountId }).replyToMode ?? "off",
+    resolveReplyToMode: ({ cfg, accountId, chatType }) =>
+      resolveSlackReplyToMode(resolveSlackAccount({ cfg, accountId }), chatType),
     allowTagsWhenOff: true,
     buildToolContext: (params) => buildSlackThreadingToolContext(params),
   },

scripts/run-node.mjs

@@ -115,7 +115,11 @@ if (!shouldBuild()) {
   runNode();
 } else {
   logRunner("Building TypeScript (dist is stale).");
-  const build = spawn("pnpm", ["exec", compiler, ...projectArgs], {
+  const pnpmArgs = ["exec", compiler, ...projectArgs];
+  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/system-prompt.test.ts

@@ -237,6 +237,20 @@ describe("buildAgentSystemPrompt", () => {
     expect(prompt).toContain("Bravo");
   });
 
+  it("adds SOUL guidance when a soul file is present", () => {
+    const prompt = buildAgentSystemPrompt({
+      workspaceDir: "/tmp/clawd",
+      contextFiles: [
+        { path: "./SOUL.md", content: "Persona" },
+        { path: "dir\\SOUL.md", content: "Persona Windows" },
+      ],
+    });
+
+    expect(prompt).toContain(
+      "If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.",
+    );
+  });
+
   it("summarizes the message tool when available", () => {
     const prompt = buildAgentSystemPrompt({
       workspaceDir: "/tmp/clawd",

src/agents/system-prompt.ts

@@ -517,12 +517,18 @@ export function buildAgentSystemPrompt(params: {
 
   const contextFiles = params.contextFiles ?? [];
   if (contextFiles.length > 0) {
-    lines.push(
-      "# Project Context",
-      "",
-      "The following project context files have been loaded:",
-      "",
-    );
+    const hasSoulFile = contextFiles.some((file) => {
+      const normalizedPath = file.path.trim().replace(/\\/g, "/");
+      const baseName = normalizedPath.split("/").pop() ?? normalizedPath;
+      return baseName.toLowerCase() === "soul.md";
+    });
+    lines.push("# Project Context", "", "The following project context files have been loaded:");
+    if (hasSoulFile) {
+      lines.push(
+        "If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.",
+      );
+    }
+    lines.push("");
     for (const file of contextFiles) {
       lines.push(`## ${file.path}`, "", file.content, "");
     }

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/auto-reply/reply/agent-runner.ts

@@ -136,6 +136,7 @@ export async function runReplyAgent(params: {
     followupRun.run.config,
     replyToChannel,
     sessionCtx.AccountId,
+    sessionCtx.ChatType,
   );
   const applyReplyToMode = createReplyToModeFilterForChannel(replyToMode, replyToChannel);
   const cfg = followupRun.run.config;

src/auto-reply/reply/followup-runner.ts

@@ -204,6 +204,7 @@ export function createFollowupRunner(params: {
         queued.run.config,
         replyToChannel,
         queued.originatingAccountId,
+        queued.originatingChatType,
       );
 
       const replyTaggedPayloads: ReplyPayload[] = applyReplyThreading({

src/auto-reply/reply/get-reply-run.ts

@@ -358,6 +358,7 @@ export async function runPreparedReply(
     originatingTo: ctx.OriginatingTo,
     originatingAccountId: ctx.AccountId,
     originatingThreadId: ctx.MessageThreadId,
+    originatingChatType: ctx.ChatType,
     run: {
       agentId,
       agentDir,

src/auto-reply/reply/queue/types.ts

@@ -39,6 +39,8 @@ export type FollowupRun = {
   originatingAccountId?: string;
   /** Thread id for reply routing (Telegram topic id or Matrix thread event id). */
   originatingThreadId?: string | number;
+  /** Chat type for context-aware threading (e.g., DM vs channel). */
+  originatingChatType?: string;
   run: {
     agentId: string;
     agentDir: string;

src/auto-reply/reply/reply-threading.test.ts

@@ -31,6 +31,33 @@ describe("resolveReplyToMode", () => {
     expect(resolveReplyToMode(cfg, "discord")).toBe("first");
     expect(resolveReplyToMode(cfg, "slack")).toBe("all");
   });
+
+  it("uses chat-type replyToMode overrides for Slack when configured", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "off",
+          replyToModeByChatType: { direct: "all", group: "first" },
+        },
+      },
+    } as ClawdbotConfig;
+    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("all");
+    expect(resolveReplyToMode(cfg, "slack", null, "group")).toBe("first");
+    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("off");
+    expect(resolveReplyToMode(cfg, "slack", null, undefined)).toBe("off");
+  });
+
+  it("falls back to top-level replyToMode when no chat-type override is set", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "first",
+        },
+      },
+    } as ClawdbotConfig;
+    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("first");
+    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("first");
+  });
 });
 
 describe("createReplyToModeFilter", () => {

src/auto-reply/reply/reply-threading.ts

@@ -9,12 +9,14 @@ export function resolveReplyToMode(
   cfg: ClawdbotConfig,
   channel?: OriginatingChannelType,
   accountId?: string | null,
+  chatType?: string | null,
 ): ReplyToMode {
   const provider = normalizeChannelId(channel);
   if (!provider) return "all";
   const resolved = getChannelDock(provider)?.threading?.resolveReplyToMode?.({
     cfg,
     accountId,
+    chatType,
   });
   return resolved ?? "all";
 }

src/channels/dock.ts

@@ -2,7 +2,7 @@ import type { ClawdbotConfig } from "../config/config.js";
 import { resolveDiscordAccount } from "../discord/accounts.js";
 import { resolveIMessageAccount } from "../imessage/accounts.js";
 import { resolveSignalAccount } from "../signal/accounts.js";
-import { resolveSlackAccount } from "../slack/accounts.js";
+import { resolveSlackAccount, resolveSlackReplyToMode } from "../slack/accounts.js";
 import { buildSlackThreadingToolContext } from "../slack/threading-tool-context.js";
 import { resolveTelegramAccount } from "../telegram/accounts.js";
 import { normalizeE164 } from "../utils.js";
@@ -224,8 +224,8 @@ const DOCKS: Record<ChatChannelId, ChannelDock> = {
       resolveRequireMention: resolveSlackGroupRequireMention,
     },
     threading: {
-      resolveReplyToMode: ({ cfg, accountId }) =>
-        resolveSlackAccount({ cfg, accountId }).replyToMode ?? "off",
+      resolveReplyToMode: ({ cfg, accountId, chatType }) =>
+        resolveSlackReplyToMode(resolveSlackAccount({ cfg, accountId }), chatType),
       allowTagsWhenOff: true,
       buildToolContext: (params) => buildSlackThreadingToolContext(params),
     },

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/channels/plugins/types.core.ts

@@ -198,6 +198,7 @@ export type ChannelThreadingAdapter = {
   resolveReplyToMode?: (params: {
     cfg: ClawdbotConfig;
     accountId?: string | null;
+    chatType?: string | null;
   }) => "off" | "first" | "all";
   allowTagsWhenOff?: boolean;
   buildToolContext?: (params: {

src/cli/argv.ts

@@ -94,9 +94,13 @@ 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();
   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/commands/onboard-helpers.ts

@@ -217,6 +217,19 @@ export async function openUrl(url: string): Promise<boolean> {
   }
 }
 
+export async function openUrlInBackground(url: string): Promise<boolean> {
+  if (process.platform !== "darwin") return false;
+  const resolved = await resolveBrowserOpenCommand();
+  if (!resolved.argv || resolved.command !== "open") return false;
+  const command = ["open", "-g", url];
+  try {
+    await runCommandWithTimeout(command, { timeoutMs: 5_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function ensureWorkspaceAndSessions(
   workspaceDir: string,
   runtime: RuntimeEnv,

src/config/logging.ts

@@ -0,0 +1,18 @@
+import type { RuntimeEnv } from "../runtime.js";
+import { displayPath } from "../utils.js";
+import { CONFIG_PATH_CLAWDBOT } from "./paths.js";
+
+type LogConfigUpdatedOptions = {
+  path?: string;
+  suffix?: string;
+};
+
+export function formatConfigPath(path: string = CONFIG_PATH_CLAWDBOT): string {
+  return displayPath(path);
+}
+
+export function logConfigUpdated(runtime: RuntimeEnv, opts: LogConfigUpdatedOptions = {}): void {
+  const path = formatConfigPath(opts.path ?? CONFIG_PATH_CLAWDBOT);
+  const suffix = opts.suffix ? ` ${opts.suffix}` : "";
+  runtime.log(`Updated ${path}${suffix}`);
+}

src/config/types.slack.ts

@@ -117,6 +117,11 @@ export type SlackAccountConfig = {
   reactionAllowlist?: Array<string | number>;
   /** Control reply threading when reply tags are present (off|first|all). */
   replyToMode?: ReplyToMode;
+  /**
+   * Optional per-chat-type reply threading overrides.
+   * Example: { direct: "all", group: "first", channel: "off" }.
+   */
+  replyToModeByChatType?: Partial<Record<"direct" | "group" | "channel", ReplyToMode>>;
   /** Thread session behavior. */
   thread?: SlackThreadConfig;
   actions?: SlackActionConfig;

src/config/zod-schema.providers-core.ts

@@ -280,6 +280,14 @@ export const SlackThreadSchema = z
   })
   .strict();
 
+const SlackReplyToModeByChatTypeSchema = z
+  .object({
+    direct: ReplyToModeSchema.optional(),
+    group: ReplyToModeSchema.optional(),
+    channel: ReplyToModeSchema.optional(),
+  })
+  .strict();
+
 export const SlackAccountSchema = z
   .object({
     name: z.string().optional(),
@@ -307,6 +315,7 @@ export const SlackAccountSchema = z
     reactionNotifications: z.enum(["off", "own", "all", "allowlist"]).optional(),
     reactionAllowlist: z.array(z.union([z.string(), z.number()])).optional(),
     replyToMode: ReplyToModeSchema.optional(),
+    replyToModeByChatType: SlackReplyToModeByChatTypeSchema.optional(),
     thread: SlackThreadSchema.optional(),
     actions: z
       .object({

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/plugin-sdk/index.ts

@@ -230,6 +230,7 @@ export {
   listSlackAccountIds,
   resolveDefaultSlackAccountId,
   resolveSlackAccount,
+  resolveSlackReplyToMode,
   type ResolvedSlackAccount,
 } from "../slack/accounts.js";
 export { slackOnboardingAdapter } from "../channels/plugins/onboarding/slack.js";

src/slack/accounts.ts

@@ -1,5 +1,6 @@
 import type { ClawdbotConfig } from "../config/config.js";
 import type { SlackAccountConfig } from "../config/types.js";
+import { normalizeChatType } from "../channels/chat-type.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
 import { resolveSlackAppToken, resolveSlackBotToken } from "./token.js";
 
@@ -20,6 +21,7 @@ export type ResolvedSlackAccount = {
   reactionNotifications?: SlackAccountConfig["reactionNotifications"];
   reactionAllowlist?: SlackAccountConfig["reactionAllowlist"];
   replyToMode?: SlackAccountConfig["replyToMode"];
+  replyToModeByChatType?: SlackAccountConfig["replyToModeByChatType"];
   actions?: SlackAccountConfig["actions"];
   slashCommand?: SlackAccountConfig["slashCommand"];
   dm?: SlackAccountConfig["dm"];
@@ -95,6 +97,7 @@ export function resolveSlackAccount(params: {
     reactionNotifications: merged.reactionNotifications,
     reactionAllowlist: merged.reactionAllowlist,
     replyToMode: merged.replyToMode,
+    replyToModeByChatType: merged.replyToModeByChatType,
     actions: merged.actions,
     slashCommand: merged.slashCommand,
     dm: merged.dm,
@@ -107,3 +110,15 @@ export function listEnabledSlackAccounts(cfg: ClawdbotConfig): ResolvedSlackAcco
     .map((accountId) => resolveSlackAccount({ cfg, accountId }))
     .filter((account) => account.enabled);
 }
+
+export function resolveSlackReplyToMode(
+  account: ResolvedSlackAccount,
+  chatType?: string | null,
+): "off" | "first" | "all" {
+  const normalized = normalizeChatType(chatType ?? undefined);
+  const overrides = account.replyToModeByChatType;
+  if (normalized && overrides && overrides[normalized] !== undefined) {
+    return overrides[normalized] ?? "off";
+  }
+  return account.replyToMode ?? "off";
+}

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,

src/slack/threading-tool-context.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { buildSlackThreadingToolContext } from "./threading-tool-context.js";
+
+const emptyCfg = {} as ClawdbotConfig;
+
+describe("buildSlackThreadingToolContext", () => {
+  it("uses top-level replyToMode by default", () => {
+    const cfg = {
+      channels: {
+        slack: { replyToMode: "first" },
+      },
+    } as ClawdbotConfig;
+    const result = buildSlackThreadingToolContext({
+      cfg,
+      accountId: null,
+      context: { ChatType: "channel" },
+    });
+    expect(result.replyToMode).toBe("first");
+  });
+
+  it("uses chat-type replyToMode overrides for direct messages when configured", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "off",
+          replyToModeByChatType: { direct: "all" },
+        },
+      },
+    } as ClawdbotConfig;
+    const result = buildSlackThreadingToolContext({
+      cfg,
+      accountId: null,
+      context: { ChatType: "direct" },
+    });
+    expect(result.replyToMode).toBe("all");
+  });
+
+  it("uses top-level replyToMode for channels when no channel override is set", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "off",
+          replyToModeByChatType: { direct: "all" },
+        },
+      },
+    } as ClawdbotConfig;
+    const result = buildSlackThreadingToolContext({
+      cfg,
+      accountId: null,
+      context: { ChatType: "channel" },
+    });
+    expect(result.replyToMode).toBe("off");
+  });
+
+  it("falls back to top-level when no chat-type override is set", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "first",
+        },
+      },
+    } as ClawdbotConfig;
+    const result = buildSlackThreadingToolContext({
+      cfg,
+      accountId: null,
+      context: { ChatType: "direct" },
+    });
+    expect(result.replyToMode).toBe("first");
+  });
+
+  it("uses all mode when ThreadLabel is present", () => {
+    const cfg = {
+      channels: {
+        slack: { replyToMode: "off" },
+      },
+    } as ClawdbotConfig;
+    const result = buildSlackThreadingToolContext({
+      cfg,
+      accountId: null,
+      context: { ChatType: "channel", ThreadLabel: "some-thread" },
+    });
+    expect(result.replyToMode).toBe("all");
+  });
+
+  it("defaults to off when no replyToMode is configured", () => {
+    const result = buildSlackThreadingToolContext({
+      cfg: emptyCfg,
+      accountId: null,
+      context: { ChatType: "direct" },
+    });
+    expect(result.replyToMode).toBe("off");
+  });
+});

src/slack/threading-tool-context.ts

@@ -3,7 +3,7 @@ import type {
   ChannelThreadingToolContext,
 } from "../channels/plugins/types.js";
 import type { ClawdbotConfig } from "../config/config.js";
-import { resolveSlackAccount } from "./accounts.js";
+import { resolveSlackAccount, resolveSlackReplyToMode } from "./accounts.js";
 
 export function buildSlackThreadingToolContext(params: {
   cfg: ClawdbotConfig;
@@ -11,11 +11,11 @@ export function buildSlackThreadingToolContext(params: {
   context: ChannelThreadingContext;
   hasRepliedRef?: { value: boolean };
 }): ChannelThreadingToolContext {
-  const configuredReplyToMode =
-    resolveSlackAccount({
-      cfg: params.cfg,
-      accountId: params.accountId,
-    }).replyToMode ?? "off";
+  const account = resolveSlackAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const configuredReplyToMode = resolveSlackReplyToMode(account, params.context.ChatType);
   const effectiveReplyToMode = params.context.ThreadLabel ? "all" : configuredReplyToMode;
   const threadId = params.context.MessageThreadId ?? params.context.ReplyToId;
   return {

src/wizard/onboarding.finalize.ts

@@ -13,6 +13,7 @@ import {
   detectBrowserOpenSupport,
   formatControlUiSshHint,
   openUrl,
+  openUrlInBackground,
   probeGatewayReachable,
   waitForGatewayReachable,
   resolveControlUiLinks,
@@ -282,6 +283,11 @@ export async function finalizeOnboardingWizard(options: FinalizeOnboardingOption
     "Control UI",
   );
 
+  let controlUiOpened = false;
+  let controlUiOpenHint: string | undefined;
+  let seededInBackground = false;
+  let hatchChoice: "tui" | "web" | "later" | null = null;
+
   if (!opts.skipUi && gatewayProbe.ok) {
     if (hasBootstrap) {
       await prompter.note(
@@ -293,11 +299,27 @@ export async function finalizeOnboardingWizard(options: FinalizeOnboardingOption
         ].join("\n"),
         "Start TUI (best option!)",
       );
-      const wantsTui = await prompter.confirm({
-        message: "Do you want to hatch your bot now?",
-        initialValue: true,
-      });
-      if (wantsTui) {
+      await prompter.note(
+        [
+          "Gateway token: shared auth for the Gateway + Control UI.",
+          "Stored in: ~/.clawdbot/clawdbot.json (gateway.auth.token) or CLAWDBOT_GATEWAY_TOKEN.",
+          "Web UI stores a copy in this browser's localStorage (clawdbot.control.settings.v1).",
+          `Get the tokenized link anytime: ${formatCliCommand("clawdbot dashboard --no-open")}`,
+        ].join("\n"),
+        "Token",
+      );
+
+      hatchChoice = (await prompter.select({
+        message: "How do you want to hatch your bot?",
+        options: [
+          { value: "tui", label: "Hatch in TUI (recommended)" },
+          { value: "web", label: "Open the Web UI" },
+          { value: "later", label: "Do this later" },
+        ],
+        initialValue: "tui",
+      })) as "tui" | "web" | "later";
+
+      if (hatchChoice === "tui") {
         await runTui({
           url: links.wsUrl,
           token: settings.authMode === "token" ? settings.gatewayToken : undefined,
@@ -306,6 +328,52 @@ export async function finalizeOnboardingWizard(options: FinalizeOnboardingOption
           deliver: false,
           message: "Wake up, my friend!",
         });
+        if (settings.authMode === "token" && settings.gatewayToken) {
+          seededInBackground = await openUrlInBackground(authedUrl);
+        }
+        if (seededInBackground) {
+          await prompter.note(
+            `Web UI seeded in the background. Open later with: ${formatCliCommand(
+              "clawdbot dashboard --no-open",
+            )}`,
+            "Web UI",
+          );
+        }
+      } else if (hatchChoice === "web") {
+        const browserSupport = await detectBrowserOpenSupport();
+        if (browserSupport.ok) {
+          controlUiOpened = await openUrl(authedUrl);
+          if (!controlUiOpened) {
+            controlUiOpenHint = formatControlUiSshHint({
+              port: settings.port,
+              basePath: controlUiBasePath,
+              token: settings.gatewayToken,
+            });
+          }
+        } else {
+          controlUiOpenHint = formatControlUiSshHint({
+            port: settings.port,
+            basePath: controlUiBasePath,
+            token: settings.gatewayToken,
+          });
+        }
+        await prompter.note(
+          [
+            `Dashboard link (with token): ${authedUrl}`,
+            controlUiOpened
+              ? "Opened in your browser. Keep that tab to control Clawdbot."
+              : "Copy/paste this URL in a browser on this machine to control Clawdbot.",
+            controlUiOpenHint,
+          ]
+            .filter(Boolean)
+            .join("\n"),
+          "Dashboard ready",
+        );
+      } else {
+        await prompter.note(
+          `When you're ready: ${formatCliCommand("clawdbot dashboard --no-open")}`,
+          "Later",
+        );
       }
     } else {
       const browserSupport = await detectBrowserOpenSupport();
@@ -342,9 +410,10 @@ export async function finalizeOnboardingWizard(options: FinalizeOnboardingOption
   );
 
   const shouldOpenControlUi =
-    !opts.skipUi && settings.authMode === "token" && Boolean(settings.gatewayToken);
-  let controlUiOpened = false;
-  let controlUiOpenHint: string | undefined;
+    !opts.skipUi &&
+    settings.authMode === "token" &&
+    Boolean(settings.gatewayToken) &&
+    hatchChoice === null;
   if (shouldOpenControlUi) {
     const browserSupport = await detectBrowserOpenSupport();
     if (browserSupport.ok) {
@@ -406,9 +475,16 @@ export async function finalizeOnboardingWizard(options: FinalizeOnboardingOption
     "Web search (optional)",
   );
 
+  await prompter.note(
+    'What now: https://clawd.bot/showcase ("What People Are Building").',
+    "What now",
+  );
+
   await prompter.outro(
     controlUiOpened
       ? "Onboarding complete. Dashboard opened with your token; keep that tab to control Clawdbot."
-      : "Onboarding complete. Use the tokenized dashboard link above to control Clawdbot.",
+      : seededInBackground
+        ? "Onboarding complete. Web UI seeded in the background; open it anytime with the tokenized link above."
+        : "Onboarding complete. Use the tokenized dashboard link above to control Clawdbot.",
   );
 }

src/wizard/onboarding.test.ts

@@ -177,19 +177,19 @@ describe("runOnboardingWizard", () => {
     const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-onboard-"));
     await fs.writeFile(path.join(workspaceDir, DEFAULT_BOOTSTRAP_FILENAME), "{}");
 
-    const confirm: WizardPrompter["confirm"] = vi.fn(async (opts) => {
-      if (opts.message === "Do you want to hatch your bot now?") return true;
-      return opts.initialValue ?? false;
+    const select: WizardPrompter["select"] = vi.fn(async (opts) => {
+      if (opts.message === "How do you want to hatch your bot?") return "tui";
+      return "quickstart";
     });
 
     const prompter: WizardPrompter = {
       intro: vi.fn(async () => {}),
       outro: vi.fn(async () => {}),
       note: vi.fn(async () => {}),
-      select: vi.fn(async () => "quickstart"),
+      select,
       multiselect: vi.fn(async () => []),
       text: vi.fn(async () => ""),
-      confirm,
+      confirm: vi.fn(async () => false),
       progress: vi.fn(() => ({ update: vi.fn(), stop: vi.fn() })),
     };
 
@@ -267,8 +267,7 @@ describe("runOnboardingWizard", () => {
 
       const calls = (note as unknown as { mock: { calls: unknown[][] } }).mock.calls;
       expect(calls.length).toBeGreaterThan(0);
-      const lastCall = calls[calls.length - 1];
-      expect(lastCall?.[1]).toBe("Web search (optional)");
+      expect(calls.some((call) => call?.[1] === "Web search (optional)")).toBe(true);
     } finally {
       if (prevBraveKey === undefined) {
         delete process.env.BRAVE_API_KEY;