@botcord/daemon 0.2.91 → 0.2.93

package/src/gateway/__tests__/dispatcher-park.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Integration tests for the agent-driven `botcord wait` park / re-wake path.
+ *
+ * A group-room turn can write a park marker (here simulated via the fake
+ * runtime's `observeRun`, standing in for the `botcord wait` CLI writing to
+ * `BOTCORD_WAIT_FILE` = `opts.waitMarkerFile`). The dispatcher reads it at the
+ * turn boundary and re-dispatches the same message after the (clamped) wait —
+ * unless a new message arrives first, or the per-queue caps are hit.
+ */
+import { writeFileSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Dispatcher, type RuntimeFactory } from "../dispatcher.js";
+import { SessionStore } from "../session-store.js";
+import { WAIT_MARKER_FILENAME } from "../wait-marker.js";
+import type {
+  ChannelAdapter,
+  ChannelSendContext,
+  ChannelSendResult,
+  GatewayConfig,
+  GatewayInboundEnvelope,
+  GatewayInboundMessage,
+  RuntimeAdapter,
+  RuntimeRunOptions,
+  RuntimeRunResult,
+} from "../types.js";
+import type { GatewayLogger } from "../log.js";
+
+function silentLogger(): GatewayLogger {
+  return { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} };
+}
+
+class FakeChannel implements ChannelAdapter {
+  readonly id = "botcord";
+  readonly type = "botcord";
+  readonly sends: ChannelSendContext[] = [];
+  async start(): Promise<void> {}
+  async send(ctx: ChannelSendContext): Promise<ChannelSendResult> {
+    this.sends.push(ctx);
+    return {};
+  }
+}
+
+class FakeRuntime implements RuntimeAdapter {
+  readonly id = "claude-code";
+  readonly calls: RuntimeRunOptions[] = [];
+  constructor(private readonly observeRun?: (opts: RuntimeRunOptions, callNo: number) => void) {}
+  async run(options: RuntimeRunOptions): Promise<RuntimeRunResult> {
+    this.calls.push(options);
+    this.observeRun?.(options, this.calls.length);
+    return { text: "NO_REPLY", newSessionId: "" };
+  }
+}
+
+/** Simulate `botcord wait <s>`: write a park marker to the path the dispatcher
+ *  handed the subprocess via `BOTCORD_WAIT_FILE` (`opts.waitMarkerFile`). Falls
+ *  back to the legacy cwd path when unset, so non-eligible rooms still "write"
+ *  somewhere the dispatcher will never consume. */
+function writeMarker(opts: RuntimeRunOptions, deadlineFromNowMs: number): void {
+  const target = opts.waitMarkerFile ?? path.join(opts.cwd, WAIT_MARKER_FILENAME);
+  writeFileSync(target, JSON.stringify({ deadlineMs: Date.now() + deadlineFromNowMs }), "utf8");
+}
+
+const GROUP_CONVO = { id: "rm_grp1", kind: "group" as const };
+const OWNER_CONVO = { id: "rm_oc_1", kind: "group" as const };
+const DM_CONVO = { id: "rm_dm_1", kind: "direct" as const };
+
+function makeEnvelope(partial: Partial<GatewayInboundMessage> = {}): GatewayInboundEnvelope {
+  return {
+    message: {
+      id: partial.id ?? "hub_msg_1",
+      channel: "botcord",
+      accountId: "ag_me",
+      conversation: partial.conversation ?? GROUP_CONVO,
+      sender: partial.sender ?? { id: "ag_peer", name: "peer", kind: "agent" },
+      text: partial.text ?? "anyone know how to fix this?",
+      raw: {},
+      replyTo: null,
+      receivedAt: Date.now(),
+    },
+  };
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("Dispatcher — botcord wait park/re-wake", () => {
+  let cwd: string;
+  let storeDir: string;
+
+  beforeEach(async () => {
+    cwd = await mkdtemp(path.join(tmpdir(), "park-cwd-"));
+    storeDir = await mkdtemp(path.join(tmpdir(), "park-store-"));
+  });
+  afterEach(async () => {
+    vi.useRealTimers();
+    await rm(cwd, { recursive: true, force: true });
+    await rm(storeDir, { recursive: true, force: true });
+  });
+
+  async function scaffold(runtime: FakeRuntime) {
+    const store = new SessionStore({ path: path.join(storeDir, "sessions.json") });
+    await store.load();
+    const channel = new FakeChannel();
+    const config: GatewayConfig = {
+      channels: [{ id: "botcord", type: "botcord", accountId: "ag_me" }],
+      defaultRoute: { runtime: "claude-code", cwd },
+      routes: [],
+    };
+    const dispatcher = new Dispatcher({
+      config,
+      channels: new Map<string, ChannelAdapter>([[channel.id, channel]]),
+      runtime: (() => runtime) as RuntimeFactory,
+      sessionStore: store,
+      log: silentLogger(),
+    });
+    return { dispatcher };
+  }
+
+  it("re-wakes a group-room turn after the marker deadline", async () => {
+    const runtime = new FakeRuntime((opts, callNo) => {
+      if (callNo === 1) writeMarker(opts, 40);
+    });
+    const { dispatcher } = await scaffold(runtime);
+
+    await dispatcher.handle(makeEnvelope());
+    expect(runtime.calls.length).toBe(1);
+    expect(runtime.calls[0]!.waitMarkerFile).toBeTruthy(); // env wired for group room
+
+    await sleep(140);
+    expect(runtime.calls.length).toBe(2); // original + one re-wake
+  });
+
+  it("a new inbound during the park cancels the scheduled re-wake", async () => {
+    const runtime = new FakeRuntime((opts, callNo) => {
+      if (callNo === 1) writeMarker(opts, 300);
+    });
+    const { dispatcher } = await scaffold(runtime);
+
+    await dispatcher.handle(makeEnvelope({ id: "m1" }));
+    expect(runtime.calls.length).toBe(1);
+    await dispatcher.handle(makeEnvelope({ id: "m2", text: "never mind, solved it" }));
+    expect(runtime.calls.length).toBe(2);
+
+    await sleep(380);
+    expect(runtime.calls.length).toBe(2); // no phantom third turn
+  });
+
+  it("stops re-waking after MAX_PARKS consecutive parks", async () => {
+    const runtime = new FakeRuntime((opts) => writeMarker(opts, 30));
+    const { dispatcher } = await scaffold(runtime);
+
+    await dispatcher.handle(makeEnvelope());
+    await sleep(360);
+    expect(runtime.calls.length).toBe(4); // 1 original + MAX_PARKS (3) re-wakes
+  });
+
+  it("isolates concurrent group-room turns for the same agent/cwd", async () => {
+    vi.useFakeTimers();
+    // Two different group rooms → two queues → two markers under one workspace.
+    // Each parks once; neither clobbers the other.
+    const parked = new Set<string>();
+    const runtime = new FakeRuntime((opts) => {
+      const room = String(opts.context?.roomId ?? "");
+      if (!parked.has(room)) {
+        parked.add(room);
+        writeMarker(opts, 40);
+      }
+    });
+    const { dispatcher } = await scaffold(runtime);
+
+    await Promise.all([
+      dispatcher.handle(makeEnvelope({ id: "a1", conversation: { id: "rm_gA", kind: "group" } })),
+      dispatcher.handle(makeEnvelope({ id: "b1", conversation: { id: "rm_gB", kind: "group" } })),
+    ]);
+    expect(runtime.calls.length).toBe(2);
+    // Distinct per-queue marker paths.
+    expect(runtime.calls[0]!.waitMarkerFile).not.toBe(runtime.calls[1]!.waitMarkerFile);
+
+    await vi.advanceTimersByTimeAsync(160);
+    // Both rooms re-woke exactly once → 4 total, not 2 (one swallowed) or 3.
+    expect(runtime.calls.length).toBe(4);
+    const reWokenRooms = runtime.calls.map((c) => c.context?.roomId).sort();
+    expect(reWokenRooms).toEqual(["rm_gA", "rm_gA", "rm_gB", "rm_gB"]);
+  });
+
+  it("ignores the marker in an owner-chat room", async () => {
+    const runtime = new FakeRuntime((opts) => writeMarker(opts, 40));
+    const { dispatcher } = await scaffold(runtime);
+
+    await dispatcher.handle(makeEnvelope({ conversation: OWNER_CONVO }));
+    expect(runtime.calls[0]!.waitMarkerFile).toBeUndefined(); // not park-eligible
+    await sleep(140);
+    expect(runtime.calls.length).toBe(1);
+  });
+
+  it("ignores the marker in a non-group (DM) room", async () => {
+    const runtime = new FakeRuntime((opts) => writeMarker(opts, 40));
+    const { dispatcher } = await scaffold(runtime);
+
+    await dispatcher.handle(makeEnvelope({ conversation: DM_CONVO }));
+    expect(runtime.calls[0]!.waitMarkerFile).toBeUndefined();
+    await sleep(140);
+    expect(runtime.calls.length).toBe(1);
+  });
+});

package/src/gateway/__tests__/dispatcher.test.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -2221,6 +2221,53 @@ describe("Dispatcher", () => {
   // Owner-chat reply gating
   // ─────────────────────────────────────────────────────────────────────
 
+  it("owner-chat reply auto-attaches generated local artifacts mentioned by relative path", async () => {
+    const workDir = await mkdtemp(path.join(tmpdir(), "dispatcher-artifacts-"));
+    tempDirs.push(workDir);
+    await mkdir(path.join(workDir, "output"), { recursive: true });
+    await mkdir(path.join(workDir, "social-card-botcord-agent-hub"), { recursive: true });
+    await writeFile(path.join(workDir, "output", "xhs-01-cover.png"), "png-bytes");
+    await writeFile(path.join(workDir, "social-card-botcord-agent-hub", "index.html"), "<html></html>");
+
+    const runtime = new FakeRuntime({
+      reply: [
+        "成品路径：",
+        "",
+        "output/xhs-01-cover.png",
+        "",
+        "项目文件在：",
+        "",
+        "social-card-botcord-agent-hub/index.html",
+      ].join("\n"),
+      newSessionId: "sid-1",
+    });
+    const { dispatcher, channel } = await scaffold({
+      config: baseConfig({ defaultRoute: { runtime: "claude-code", cwd: workDir } }),
+      runtimeFactory: () => runtime,
+    });
+
+    await dispatcher.handle(makeEnvelope({ conversation: { id: "rm_oc_1", kind: "direct" } }));
+
+    const realWorkDir = await realpath(workDir);
+    expect(channel.sends.length).toBe(1);
+    expect(channel.sends[0].message.attachments).toEqual([
+      {
+        filePath: path.join(realWorkDir, "output", "xhs-01-cover.png"),
+        filename: "xhs-01-cover.png",
+        contentType: "image/png",
+        sourcePath: "output/xhs-01-cover.png",
+        kind: "image",
+      },
+      {
+        filePath: path.join(realWorkDir, "social-card-botcord-agent-hub", "index.html"),
+        filename: "index.html",
+        contentType: "text/html",
+        sourcePath: "social-card-botcord-agent-hub/index.html",
+        kind: "file",
+      },
+    ]);
+  });
+
   it("non-owner-chat room: discards result.text, agent must use botcord_send", async () => {
     const runtime = new FakeRuntime({ reply: "would-be-reply", newSessionId: "sid-1" });
     const { dispatcher, channel, store } = await scaffold({

package/src/gateway/__tests__/wait-marker.test.ts

@@ -0,0 +1,90 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  WAIT_MARKER_FILENAME,
+  MAX_WAIT_MS,
+  waitMarkerPath,
+  resolveWaitMarkerPath,
+  clearWaitMarker,
+  consumeWaitMarker,
+} from "../wait-marker.js";
+
+describe("wait-marker", () => {
+  let dir: string;
+  let marker: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "wait-marker-"));
+    marker = waitMarkerPath(dir);
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  const write = (obj: unknown, at: string = marker) =>
+    writeFile(at, JSON.stringify(obj), "utf8");
+
+  it("returns null when no marker exists", () => {
+    expect(consumeWaitMarker(marker)).toBeNull();
+  });
+
+  it("reads a valid marker, clamps to the deadline, and deletes the file", async () => {
+    const now = 1_000_000;
+    await write({ deadlineMs: now + 8_000, seconds: 8 });
+    expect(consumeWaitMarker(marker, now)).toEqual({ deadlineMs: now + 8_000 });
+    expect(existsSync(marker)).toBe(false);
+  });
+
+  it("preserves a reason string when present", async () => {
+    const now = 1_000_000;
+    await write({ deadlineMs: now + 5_000, reason: "letting alice answer" });
+    expect(consumeWaitMarker(marker, now)).toEqual({
+      deadlineMs: now + 5_000,
+      reason: "letting alice answer",
+    });
+  });
+
+  it("clamps a deadline beyond MAX_WAIT_MS down to now + MAX_WAIT_MS", async () => {
+    const now = 1_000_000;
+    await write({ deadlineMs: now + 10 * MAX_WAIT_MS });
+    expect(consumeWaitMarker(marker, now)).toEqual({ deadlineMs: now + MAX_WAIT_MS });
+  });
+
+  it("returns null for a past deadline (and still deletes the file)", async () => {
+    const now = 1_000_000;
+    await write({ deadlineMs: now - 1 });
+    expect(consumeWaitMarker(marker, now)).toBeNull();
+    expect(existsSync(marker)).toBe(false);
+  });
+
+  it("returns null for malformed / non-numeric markers", async () => {
+    await write({ nope: true });
+    expect(consumeWaitMarker(marker)).toBeNull();
+    await writeFile(marker, "{ not json", "utf8");
+    expect(consumeWaitMarker(marker)).toBeNull();
+  });
+
+  it("clearWaitMarker removes a stale marker and is a no-op when absent", async () => {
+    await write({ deadlineMs: Date.now() + 5_000 });
+    clearWaitMarker(marker);
+    expect(existsSync(marker)).toBe(false);
+    expect(() => clearWaitMarker(marker)).not.toThrow();
+  });
+
+  it("scopes the path per queue and sanitizes the queue key", () => {
+    const p = resolveWaitMarkerPath(dir, "botcord:ag_me:rm_g1:tp_x");
+    expect(p).toBe(path.join(dir, ".botcord-wait.botcord_ag_me_rm_g1_tp_x.json"));
+    // Distinct queues → distinct files (the core of the concurrency fix).
+    expect(resolveWaitMarkerPath(dir, "botcord:ag_me:rm_g1:")).not.toBe(
+      resolveWaitMarkerPath(dir, "botcord:ag_me:rm_g2:"),
+    );
+  });
+
+  it("uses the documented legacy filename", () => {
+    expect(WAIT_MARKER_FILENAME).toBe(".botcord-wait.json");
+    expect(waitMarkerPath(dir)).toBe(path.join(dir, ".botcord-wait.json"));
+  });
+});

package/src/gateway/channels/botcord.ts

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import WebSocket from "ws";
 import {
   BotCordClient,
@@ -6,6 +7,7 @@ import {
   loadStoredCredentials,
   updateCredentialsToken,
   type InboxMessage,
+  type MessageAttachment,
 } from "@botcord/protocol-core";
 import type {
   ChannelAdapter,
@@ -57,16 +59,26 @@ export interface BotCordChannelClient {
     roomId?: string;
   }): Promise<{ messages: InboxMessage[]; count: number; has_more: boolean }>;
   ackMessages(messageIds: string[]): Promise<void>;
+  uploadFile?(
+    filePath: string,
+    filename: string,
+    contentType?: string,
+  ): Promise<{
+    original_filename: string;
+    url: string;
+    content_type?: string;
+    size_bytes?: number;
+  }>;
   sendMessage(
     to: string,
     text: string,
-    options?: { replyTo?: string; topic?: string },
+    options?: { replyTo?: string; topic?: string; attachments?: MessageAttachment[] },
   ): Promise<{ hub_msg_id?: string; message_id?: string } & Record<string, unknown>>;
   sendTypedMessage?(
     to: string,
     type: "result" | "error",
     text: string,
-    options?: { replyTo?: string; topic?: string },
+    options?: { replyTo?: string; topic?: string; attachments?: MessageAttachment[] },
   ): Promise<{ hub_msg_id?: string; message_id?: string } & Record<string, unknown>>;
   getHubUrl(): string;
   onTokenRefresh?: (token: string, expiresAt: number) => void;
@@ -118,6 +130,65 @@ function isUnclaimedAgentError(err: unknown): boolean {
   );
 }
 
+async function uploadOutboundAttachments(
+  client: BotCordChannelClient,
+  attachments: NonNullable<ChannelSendContext["message"]["attachments"]>,
+  log: GatewayLogger,
+): Promise<{ attachments: MessageAttachment[]; replacements: Array<{ sourcePath: string; url: string }> }> {
+  if (attachments.length === 0) return { attachments: [], replacements: [] };
+  if (!client.uploadFile) {
+    log.warn("botcord send: outbound attachments skipped because uploadFile is unavailable", {
+      count: attachments.length,
+    });
+    return { attachments: [], replacements: [] };
+  }
+
+  const uploaded: MessageAttachment[] = [];
+  const replacements: Array<{ sourcePath: string; url: string }> = [];
+  for (const attachment of attachments) {
+    if (!attachment.filePath) {
+      log.warn("botcord send: attachment without filePath skipped", {
+        filename: attachment.filename ?? null,
+      });
+      continue;
+    }
+    try {
+      const resp = await client.uploadFile(
+        attachment.filePath,
+        attachment.filename ?? basename(attachment.filePath),
+        attachment.contentType,
+      );
+      if (attachment.sourcePath) {
+        replacements.push({ sourcePath: attachment.sourcePath, url: resp.url });
+      }
+      uploaded.push({
+        filename: resp.original_filename,
+        url: resp.url,
+        ...(resp.content_type ? { content_type: resp.content_type } : {}),
+        ...(typeof resp.size_bytes === "number" ? { size_bytes: resp.size_bytes } : {}),
+      });
+    } catch (err) {
+      log.warn("botcord send: attachment upload failed; continuing without it", {
+        filename: attachment.filename ?? attachment.filePath,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return { attachments: uploaded, replacements };
+}
+
+function rewriteUploadedAttachmentPaths(
+  text: string,
+  replacements: Array<{ sourcePath: string; url: string }>,
+): string {
+  let out = text;
+  for (const { sourcePath, url } of replacements) {
+    if (!sourcePath || !url) continue;
+    out = out.replaceAll(sourcePath, url);
+  }
+  return out;
+}
+
 /** Default factory: wrap `loadStoredCredentials` + `new BotCordClient`. */
 function defaultClientFactory(input: {
   agentId: string;
@@ -911,13 +982,16 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
     async send(ctx: ChannelSendContext): Promise<ChannelSendResult> {
       const client = ensureClient();
       const { message } = ctx;
-      const options: { replyTo?: string; topic?: string } = {};
+      const options: { replyTo?: string; topic?: string; attachments?: MessageAttachment[] } = {};
       if (message.replyTo) options.replyTo = message.replyTo;
       if (message.threadId) options.topic = message.threadId;
+      const upload = await uploadOutboundAttachments(client, message.attachments ?? [], ctx.log);
+      if (upload.attachments.length > 0) options.attachments = upload.attachments;
+      const text = rewriteUploadedAttachmentPaths(message.text, upload.replacements);
       const resp =
         message.type === "error" && client.sendTypedMessage
-          ? await client.sendTypedMessage(message.conversationId, "error", message.text, options)
-          : await client.sendMessage(message.conversationId, message.text, options);
+          ? await client.sendTypedMessage(message.conversationId, "error", text, options)
+          : await client.sendMessage(message.conversationId, text, options);
       const providerMessageId =
         (resp && typeof resp.hub_msg_id === "string" && resp.hub_msg_id) ||
         (resp && typeof (resp as { message_id?: unknown }).message_id === "string"

package/src/gateway/channels/feishu.ts

@@ -70,6 +70,31 @@ interface FeishuMessageEvent {
   message?: FeishuEventMessage;
 }
 
+export interface FeishuDiscoveredChat {
+  chatId: string;
+  senderOpenId: string;
+  kind: "direct" | "group";
+  label?: string | null;
+  lastSeenAt: number;
+}
+
+export interface FeishuChatDiscoveryOptions {
+  appId: string;
+  appSecret: string;
+  domain?: FeishuDomain;
+  userOpenId: string;
+  timeoutSeconds?: number;
+  sdkOverride?: {
+    createWsClient(args: Record<string, unknown>): {
+      start(opts: unknown): unknown;
+      close(opts?: unknown): unknown;
+    };
+    createDispatcher(): {
+      register(handlers: Record<string, (data: unknown) => unknown>): void;
+    };
+  };
+}
+
 interface FeishuProviderState {
   seenMessageIds?: Record<string, number>;
 }
@@ -132,6 +157,103 @@ function senderLabel(event: FeishuMessageEvent): string | undefined {
   return typeof hit?.name === "string" && hit.name ? hit.name : undefined;
 }
 
+export function feishuDiscoveryChatFromEvent(
+  event: FeishuMessageEvent,
+  allowedSenderOpenId: string,
+  now: () => number = () => Date.now(),
+): FeishuDiscoveredChat | null {
+  const message = event.message;
+  const senderOpenId = event.sender?.sender_id?.open_id;
+  const chatId = message?.chat_id;
+  if (!message || !senderOpenId || !chatId) return null;
+  if (senderOpenId !== allowedSenderOpenId) return null;
+  const chatType = message.chat_type ?? "";
+  const kind: "direct" | "group" = chatType === "p2p" ? "direct" : "group";
+  const label = senderLabel(event) ?? null;
+  return {
+    chatId,
+    senderOpenId,
+    kind,
+    label,
+    lastSeenAt: Number(message.create_time) || now(),
+  };
+}
+
+export async function discoverFeishuChats(
+  opts: FeishuChatDiscoveryOptions,
+): Promise<FeishuDiscoveredChat[]> {
+  const timeoutSeconds =
+    typeof opts.timeoutSeconds === "number"
+      ? Math.min(Math.max(Math.floor(opts.timeoutSeconds), 0), 10)
+      : 0;
+  const chats = new Map<string, FeishuDiscoveredChat>();
+  const sdk = Lark as unknown as {
+    EventDispatcher: new (args?: Record<string, unknown>) => {
+      register(handlers: Record<string, (data: unknown) => unknown>): void;
+    };
+    WSClient: new (args: Record<string, unknown>) => {
+      start(opts: unknown): unknown;
+      close(opts?: unknown): unknown;
+    };
+    LoggerLevel?: { info?: unknown };
+  };
+  const dispatcher = opts.sdkOverride
+    ? opts.sdkOverride.createDispatcher()
+    : new sdk.EventDispatcher({});
+  dispatcher.register({
+    "im.message.receive_v1": (data: unknown) => {
+      const discovered = feishuDiscoveryChatFromEvent(
+        data as FeishuMessageEvent,
+        opts.userOpenId,
+      );
+      if (!discovered) return;
+      const previous = chats.get(discovered.chatId);
+      chats.set(discovered.chatId, {
+        ...previous,
+        ...discovered,
+        label: discovered.label ?? previous?.label ?? null,
+        lastSeenAt: Math.max(previous?.lastSeenAt ?? 0, discovered.lastSeenAt),
+      });
+    },
+  });
+  const wsClientArgs = {
+    appId: opts.appId,
+    appSecret: opts.appSecret,
+    domain: sdkDomain(opts.domain),
+    loggerLevel: sdk.LoggerLevel?.info,
+  };
+  const wsClient = opts.sdkOverride
+    ? opts.sdkOverride.createWsClient(wsClientArgs)
+    : new sdk.WSClient(wsClientArgs);
+  try {
+    const startFailure = Promise.resolve()
+      .then(() => wsClient.start({ eventDispatcher: dispatcher }))
+      .then(
+        () => new Promise<never>(() => {}),
+        (err) => Promise.reject(err),
+      );
+    const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+    await Promise.race([startFailure, delay(0)]);
+    await Promise.race([startFailure, delay(timeoutSeconds * 1000)]);
+  } finally {
+    try {
+      const closeResult = wsClient.close({ force: true });
+      if (
+        closeResult &&
+        (typeof closeResult === "object" || typeof closeResult === "function") &&
+        typeof (closeResult as PromiseLike<unknown>).then === "function"
+      ) {
+        void Promise.resolve(closeResult).catch(() => {
+          // best effort
+        });
+      }
+    } catch {
+      // best effort
+    }
+  }
+  return [...chats.values()].sort((a, b) => b.lastSeenAt - a.lastSeenAt);
+}
+
 export function createFeishuChannel(opts: FeishuChannelOptions): ChannelAdapter {
   const splitAt = opts.splitAt && opts.splitAt > 0 ? opts.splitAt : DEFAULT_SPLIT_AT;
   const allowedSenderIds = new Set((opts.allowedSenderIds ?? []).map(String));

package/src/gateway/cli-resolver.ts

@@ -77,10 +77,12 @@ export function buildCliEnv(opts: {
   hubUrl?: string;
   accountId?: string;
   basePath?: string | undefined;
+  waitMarkerFile?: string;
 }): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {};
   if (opts.hubUrl) env.BOTCORD_HUB = opts.hubUrl;
   if (opts.accountId) env.BOTCORD_AGENT_ID = opts.accountId;
+  if (opts.waitMarkerFile) env.BOTCORD_WAIT_FILE = opts.waitMarkerFile;
   const cli = resolveBundledCliBin();
   if (cli) {
     const existing = opts.basePath ?? "";