openclaw-multi-auto 1.0.9 → 1.1.1

package/scripts/dev/discord-acp-plain-language-smoke.ts

@@ -0,0 +1,868 @@
+#!/usr/bin/env bun
+import { execFile } from "node:child_process";
+// Manual ACP thread smoke for plain-language routing.
+// Keep this script available for regression/debug validation. Do not delete.
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+type ThreadBindingRecord = {
+  accountId?: string;
+  channelId?: string;
+  threadId?: string;
+  targetKind?: string;
+  targetSessionKey?: string;
+  agentId?: string;
+  boundBy?: string;
+  boundAt?: number;
+};
+
+type ThreadBindingsPayload = {
+  version?: number;
+  bindings?: Record<string, ThreadBindingRecord>;
+};
+
+type DiscordMessage = {
+  id: string;
+  content?: string;
+  timestamp?: string;
+  author?: {
+    id?: string;
+    username?: string;
+    bot?: boolean;
+  };
+};
+
+type DiscordUser = {
+  id: string;
+  username: string;
+  bot?: boolean;
+};
+
+const execFileAsync = promisify(execFile);
+
+type DriverMode = "token" | "webhook" | "openclaw";
+
+type Args = {
+  channelId: string;
+  driverMode: DriverMode;
+  driverToken: string;
+  driverTokenPrefix: string;
+  botToken: string;
+  botTokenPrefix: string;
+  targetAgent: string;
+  timeoutMs: number;
+  pollMs: number;
+  mentionUserId?: string;
+  instruction?: string;
+  threadBindingsPath: string;
+  openclawBin: string;
+  json: boolean;
+};
+
+type SuccessResult = {
+  ok: true;
+  smokeId: string;
+  ackToken: string;
+  sentMessageId: string;
+  binding: {
+    threadId: string;
+    targetSessionKey: string;
+    targetKind: string;
+    agentId: string;
+    boundAt: number;
+    accountId?: string;
+    channelId?: string;
+  };
+  ackMessage: {
+    id: string;
+    authorId?: string;
+    authorUsername?: string;
+    timestamp?: string;
+    content?: string;
+  };
+};
+
+type FailureResult = {
+  ok: false;
+  smokeId: string;
+  stage: "validation" | "send-message" | "wait-binding" | "wait-ack" | "discord-api" | "unexpected";
+  error: string;
+  diagnostics?: {
+    parentChannelRecent?: Array<{
+      id: string;
+      author?: string;
+      bot?: boolean;
+      content?: string;
+    }>;
+    bindingCandidates?: Array<{
+      threadId: string;
+      targetSessionKey: string;
+      targetKind?: string;
+      agentId?: string;
+      boundAt?: number;
+    }>;
+  };
+};
+
+const DISCORD_API_BASE = "https://discord.com/api/v10";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseNumber(value: string | undefined, fallback: number): number {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function resolveStateDir(): string {
+  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  if (override) {
+    return override.startsWith("~")
+      ? path.resolve(process.env.HOME || "", override.slice(1))
+      : path.resolve(override);
+  }
+  const home = process.env.OPENCLAW_HOME?.trim() || process.env.HOME || "";
+  return path.join(home, ".openclaw");
+}
+
+function resolveArg(flag: string): string | undefined {
+  const argv = process.argv.slice(2);
+  const eq = argv.find((entry) => entry.startsWith(`${flag}=`));
+  if (eq) {
+    return eq.slice(flag.length + 1);
+  }
+  const idx = argv.indexOf(flag);
+  if (idx >= 0 && idx + 1 < argv.length) {
+    return argv[idx + 1];
+  }
+  return undefined;
+}
+
+function hasFlag(flag: string): boolean {
+  return process.argv.slice(2).includes(flag);
+}
+
+function usage(): string {
+  return (
+    "Usage: bun scripts/dev/discord-acp-plain-language-smoke.ts " +
+    "--channel <discord-channel-id> [--token <driver-token> | --driver webhook --bot-token <bot-token> | --driver openclaw] [options]\n\n" +
+    "Manual live smoke only (not CI). Sends a plain-language instruction in Discord and verifies:\n" +
+    "1) OpenClaw spawned an ACP thread binding\n" +
+    "2) agent replied in that bound thread with the expected ACK token\n\n" +
+    "Options:\n" +
+    "  --channel <id>               Parent Discord channel id (required)\n" +
+    "  --driver <token|webhook|openclaw> Driver transport mode (default: token)\n" +
+    "  --token <token>              Driver Discord token (required for driver=token)\n" +
+    "  --token-prefix <prefix>      Auth prefix for --token (default: Bot)\n" +
+    "  --bot-token <token>          Bot token for webhook driver mode\n" +
+    "  --bot-token-prefix <prefix>  Auth prefix for --bot-token (default: Bot)\n" +
+    "  --agent <id>                 Expected ACP agent id (default: codex)\n" +
+    "  --mention <user-id>          Mention this user in the instruction (optional)\n" +
+    "  --instruction <text>         Custom instruction template (optional)\n" +
+    "  --timeout-ms <n>             Total timeout in ms (default: 240000)\n" +
+    "  --poll-ms <n>                Poll interval in ms (default: 1500)\n" +
+    "  --thread-bindings-path <p>   Override thread-bindings json path\n" +
+    "  --openclaw-bin <path>        OpenClaw CLI binary for driver=openclaw (default: openclaw)\n" +
+    "  --json                       Emit JSON output\n" +
+    "\n" +
+    "Environment fallbacks:\n" +
+    "  OPENCLAW_DISCORD_SMOKE_CHANNEL_ID\n" +
+    "  OPENCLAW_DISCORD_SMOKE_DRIVER\n" +
+    "  OPENCLAW_DISCORD_SMOKE_DRIVER_TOKEN\n" +
+    "  OPENCLAW_DISCORD_SMOKE_DRIVER_TOKEN_PREFIX\n" +
+    "  OPENCLAW_DISCORD_SMOKE_BOT_TOKEN\n" +
+    "  OPENCLAW_DISCORD_SMOKE_BOT_TOKEN_PREFIX\n" +
+    "  OPENCLAW_DISCORD_SMOKE_AGENT\n" +
+    "  OPENCLAW_DISCORD_SMOKE_MENTION_USER_ID\n" +
+    "  OPENCLAW_DISCORD_SMOKE_TIMEOUT_MS\n" +
+    "  OPENCLAW_DISCORD_SMOKE_POLL_MS\n" +
+    "  OPENCLAW_DISCORD_SMOKE_THREAD_BINDINGS_PATH\n" +
+    "  OPENCLAW_DISCORD_SMOKE_OPENCLAW_BIN"
+  );
+}
+
+function parseArgs(): Args {
+  const channelId =
+    resolveArg("--channel") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_CHANNEL_ID ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_CHANNEL_ID ||
+    "";
+  const driverModeRaw =
+    resolveArg("--driver") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_DRIVER ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_DRIVER ||
+    "token";
+  const normalizedDriverMode = driverModeRaw.trim().toLowerCase();
+  const driverMode: DriverMode =
+    normalizedDriverMode === "webhook"
+      ? "webhook"
+      : normalizedDriverMode === "openclaw"
+        ? "openclaw"
+        : normalizedDriverMode === "token"
+          ? "token"
+          : "token";
+  const driverToken =
+    resolveArg("--token") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_DRIVER_TOKEN ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_DRIVER_TOKEN ||
+    "";
+  const driverTokenPrefix =
+    resolveArg("--token-prefix") || process.env.OPENCLAW_DISCORD_SMOKE_DRIVER_TOKEN_PREFIX || "Bot";
+  const botToken =
+    resolveArg("--bot-token") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_BOT_TOKEN ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_BOT_TOKEN ||
+    process.env.DISCORD_BOT_TOKEN ||
+    "";
+  const botTokenPrefix =
+    resolveArg("--bot-token-prefix") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_BOT_TOKEN_PREFIX ||
+    "Bot";
+  const targetAgent =
+    resolveArg("--agent") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_AGENT ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_AGENT ||
+    "codex";
+  const mentionUserId =
+    resolveArg("--mention") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_MENTION_USER_ID ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_MENTION_USER_ID ||
+    undefined;
+  const instruction =
+    resolveArg("--instruction") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_INSTRUCTION ||
+    process.env.CLAWDBOT_DISCORD_SMOKE_INSTRUCTION ||
+    undefined;
+  const timeoutMs = parseNumber(
+    resolveArg("--timeout-ms") || process.env.OPENCLAW_DISCORD_SMOKE_TIMEOUT_MS,
+    240_000,
+  );
+  const pollMs = parseNumber(
+    resolveArg("--poll-ms") || process.env.OPENCLAW_DISCORD_SMOKE_POLL_MS,
+    1_500,
+  );
+  const defaultBindingsPath = path.join(resolveStateDir(), "discord", "thread-bindings.json");
+  const threadBindingsPath =
+    resolveArg("--thread-bindings-path") ||
+    process.env.OPENCLAW_DISCORD_SMOKE_THREAD_BINDINGS_PATH ||
+    defaultBindingsPath;
+  const openclawBin =
+    resolveArg("--openclaw-bin") || process.env.OPENCLAW_DISCORD_SMOKE_OPENCLAW_BIN || "openclaw";
+  const json = hasFlag("--json");
+
+  if (!channelId) {
+    throw new Error(usage());
+  }
+  if (driverMode === "token" && !driverToken) {
+    throw new Error(usage());
+  }
+  if (driverMode === "webhook" && !botToken) {
+    throw new Error(usage());
+  }
+
+  return {
+    channelId,
+    driverMode,
+    driverToken,
+    driverTokenPrefix,
+    botToken,
+    botTokenPrefix,
+    targetAgent,
+    timeoutMs,
+    pollMs,
+    mentionUserId,
+    instruction,
+    threadBindingsPath,
+    openclawBin,
+    json,
+  };
+}
+
+async function openclawCliJson<T>(params: { openclawBin: string; args: string[] }): Promise<T> {
+  const result = await execFileAsync(params.openclawBin, params.args, {
+    maxBuffer: 8 * 1024 * 1024,
+    env: process.env,
+  });
+  const stdout = (result.stdout || "").trim();
+  if (!stdout) {
+    throw new Error(`openclaw ${params.args.join(" ")} returned empty stdout`);
+  }
+  return JSON.parse(stdout) as T;
+}
+
+async function readMessagesWithOpenclaw(params: {
+  openclawBin: string;
+  target: string;
+  limit: number;
+}): Promise<DiscordMessage[]> {
+  const response = await openclawCliJson<{
+    payload?: {
+      messages?: DiscordMessage[];
+    };
+  }>({
+    openclawBin: params.openclawBin,
+    args: [
+      "message",
+      "read",
+      "--channel",
+      "discord",
+      "--target",
+      params.target,
+      "--limit",
+      String(params.limit),
+      "--json",
+    ],
+  });
+  return Array.isArray(response.payload?.messages) ? response.payload.messages : [];
+}
+
+function resolveAuthorizationHeader(params: { token: string; tokenPrefix: string }): string {
+  const token = params.token.trim();
+  if (!token) {
+    throw new Error("Missing Discord driver token.");
+  }
+  if (token.includes(" ")) {
+    return token;
+  }
+  return `${params.tokenPrefix.trim() || "Bot"} ${token}`;
+}
+
+async function discordApi<T>(params: {
+  method: "GET" | "POST";
+  path: string;
+  authHeader: string;
+  body?: unknown;
+  retries?: number;
+}): Promise<T> {
+  return requestDiscordJson<T>({
+    method: params.method,
+    path: params.path,
+    headers: {
+      Authorization: params.authHeader,
+      "Content-Type": "application/json",
+    },
+    body: params.body,
+    retries: params.retries,
+    errorPrefix: "Discord API",
+  });
+}
+
+async function discordWebhookApi<T>(params: {
+  method: "POST" | "DELETE";
+  webhookId: string;
+  webhookToken: string;
+  body?: unknown;
+  query?: string;
+  retries?: number;
+}): Promise<T> {
+  const suffix = params.query ? `?${params.query}` : "";
+  const path = `/webhooks/${encodeURIComponent(params.webhookId)}/${encodeURIComponent(params.webhookToken)}${suffix}`;
+  return requestDiscordJson<T>({
+    method: params.method,
+    path,
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: params.body,
+    retries: params.retries,
+    errorPrefix: "Discord webhook API",
+  });
+}
+
+async function requestDiscordJson<T>(params: {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  retries?: number;
+  errorPrefix: string;
+}): Promise<T> {
+  const retries = params.retries ?? 6;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const response = await fetch(`${DISCORD_API_BASE}${params.path}`, {
+      method: params.method,
+      headers: params.headers,
+      body: params.body === undefined ? undefined : JSON.stringify(params.body),
+    });
+
+    if (response.status === 429) {
+      const body = (await response.json().catch(() => ({}))) as { retry_after?: number };
+      const waitSeconds = typeof body.retry_after === "number" ? body.retry_after : 1;
+      await sleep(Math.ceil(waitSeconds * 1000));
+      continue;
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `${params.errorPrefix} ${params.method} ${params.path} failed: ${response.status} ${response.statusText}${text ? ` :: ${text}` : ""}`,
+      );
+    }
+
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    return (await response.json()) as T;
+  }
+
+  throw new Error(`${params.errorPrefix} ${params.method} ${params.path} exceeded retry budget.`);
+}
+
+async function readThreadBindings(filePath: string): Promise<ThreadBindingRecord[]> {
+  const raw = await fs.readFile(filePath, "utf8");
+  const payload = JSON.parse(raw) as ThreadBindingsPayload;
+  const entries = Object.values(payload.bindings ?? {});
+  return entries.filter((entry) => Boolean(entry?.threadId && entry?.targetSessionKey));
+}
+
+function normalizeBoundAt(record: ThreadBindingRecord): number {
+  if (typeof record.boundAt === "number" && Number.isFinite(record.boundAt)) {
+    return record.boundAt;
+  }
+  return 0;
+}
+
+function resolveCandidateBindings(params: {
+  entries: ThreadBindingRecord[];
+  minBoundAt: number;
+  targetAgent: string;
+}): ThreadBindingRecord[] {
+  const normalizedTargetAgent = params.targetAgent.trim().toLowerCase();
+  return params.entries
+    .filter((entry) => {
+      const targetKind = String(entry.targetKind || "")
+        .trim()
+        .toLowerCase();
+      if (targetKind !== "acp") {
+        return false;
+      }
+      if (normalizeBoundAt(entry) < params.minBoundAt) {
+        return false;
+      }
+      const agentId = String(entry.agentId || "")
+        .trim()
+        .toLowerCase();
+      if (normalizedTargetAgent && agentId && agentId !== normalizedTargetAgent) {
+        return false;
+      }
+      return true;
+    })
+    .toSorted((a, b) => normalizeBoundAt(b) - normalizeBoundAt(a));
+}
+
+function buildInstruction(params: {
+  smokeId: string;
+  ackToken: string;
+  targetAgent: string;
+  mentionUserId?: string;
+  template?: string;
+}): string {
+  const mentionPrefix = params.mentionUserId?.trim() ? `<@${params.mentionUserId.trim()}> ` : "";
+  if (params.template?.trim()) {
+    return mentionPrefix + params.template.trim();
+  }
+  return (
+    mentionPrefix +
+    `Manual smoke ${params.smokeId}: Please spawn a ${params.targetAgent} ACP coding agent in a thread for this request, keep it persistent, and in that thread reply with exactly "${params.ackToken}" and nothing else.`
+  );
+}
+
+function toRecentMessageRow(message: DiscordMessage) {
+  return {
+    id: message.id,
+    author: message.author?.username || message.author?.id || "unknown",
+    bot: Boolean(message.author?.bot),
+    content: (message.content || "").slice(0, 500),
+  };
+}
+
+async function loadParentRecentMessages(params: {
+  args: Args;
+  readAuthHeader: string;
+}): Promise<DiscordMessage[]> {
+  if (params.args.driverMode === "openclaw") {
+    return await readMessagesWithOpenclaw({
+      openclawBin: params.args.openclawBin,
+      target: params.args.channelId,
+      limit: 20,
+    });
+  }
+  return await discordApi<DiscordMessage[]>({
+    method: "GET",
+    path: `/channels/${encodeURIComponent(params.args.channelId)}/messages?limit=20`,
+    authHeader: params.readAuthHeader,
+  });
+}
+
+function printOutput(params: { json: boolean; payload: SuccessResult | FailureResult }) {
+  if (params.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(params.payload, null, 2));
+    return;
+  }
+  if (params.payload.ok) {
+    const success = params.payload;
+    // eslint-disable-next-line no-console
+    console.log("PASS");
+    // eslint-disable-next-line no-console
+    console.log(`smokeId: ${success.smokeId}`);
+    // eslint-disable-next-line no-console
+    console.log(`sentMessageId: ${success.sentMessageId}`);
+    // eslint-disable-next-line no-console
+    console.log(`threadId: ${success.binding.threadId}`);
+    // eslint-disable-next-line no-console
+    console.log(`sessionKey: ${success.binding.targetSessionKey}`);
+    // eslint-disable-next-line no-console
+    console.log(`ackMessageId: ${success.ackMessage.id}`);
+    // eslint-disable-next-line no-console
+    console.log(
+      `ackAuthor: ${success.ackMessage.authorUsername || success.ackMessage.authorId || "unknown"}`,
+    );
+    return;
+  }
+  const failure = params.payload;
+  // eslint-disable-next-line no-console
+  console.error("FAIL");
+  // eslint-disable-next-line no-console
+  console.error(`stage: ${failure.stage}`);
+  // eslint-disable-next-line no-console
+  console.error(`smokeId: ${failure.smokeId}`);
+  // eslint-disable-next-line no-console
+  console.error(`error: ${failure.error}`);
+  if (failure.diagnostics?.bindingCandidates?.length) {
+    // eslint-disable-next-line no-console
+    console.error("binding candidates:");
+    for (const candidate of failure.diagnostics.bindingCandidates) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `  thread=${candidate.threadId} kind=${candidate.targetKind || "?"} agent=${candidate.agentId || "?"} boundAt=${candidate.boundAt || 0} session=${candidate.targetSessionKey}`,
+      );
+    }
+  }
+  if (failure.diagnostics?.parentChannelRecent?.length) {
+    // eslint-disable-next-line no-console
+    console.error("recent parent channel messages:");
+    for (const row of failure.diagnostics.parentChannelRecent) {
+      // eslint-disable-next-line no-console
+      console.error(`  ${row.id} ${row.author}${row.bot ? " [bot]" : ""}: ${row.content || ""}`);
+    }
+  }
+}
+
+async function run(): Promise<SuccessResult | FailureResult> {
+  let args: Args;
+  try {
+    args = parseArgs();
+  } catch (err) {
+    return {
+      ok: false,
+      stage: "validation",
+      smokeId: "n/a",
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const smokeId = `acp-smoke-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const ackToken = `ACP_SMOKE_ACK_${smokeId}`;
+  const instruction = buildInstruction({
+    smokeId,
+    ackToken,
+    targetAgent: args.targetAgent,
+    mentionUserId: args.mentionUserId,
+    template: args.instruction,
+  });
+
+  let readAuthHeader = "";
+  let sentMessageId = "";
+  let setupStage: "discord-api" | "send-message" = "discord-api";
+  let senderAuthorId: string | undefined;
+  let webhookForCleanup:
+    | {
+        id: string;
+        token: string;
+      }
+    | undefined;
+
+  try {
+    if (args.driverMode === "token") {
+      const authHeader = resolveAuthorizationHeader({
+        token: args.driverToken,
+        tokenPrefix: args.driverTokenPrefix,
+      });
+      readAuthHeader = authHeader;
+
+      const driverUser = await discordApi<DiscordUser>({
+        method: "GET",
+        path: "/users/@me",
+        authHeader,
+      });
+      senderAuthorId = driverUser.id;
+
+      setupStage = "send-message";
+      const sent = await discordApi<DiscordMessage>({
+        method: "POST",
+        path: `/channels/${encodeURIComponent(args.channelId)}/messages`,
+        authHeader,
+        body: {
+          content: instruction,
+          allowed_mentions: args.mentionUserId
+            ? { parse: [], users: [args.mentionUserId] }
+            : { parse: [] },
+        },
+      });
+      sentMessageId = sent.id;
+    } else if (args.driverMode === "webhook") {
+      const botAuthHeader = resolveAuthorizationHeader({
+        token: args.botToken,
+        tokenPrefix: args.botTokenPrefix,
+      });
+      readAuthHeader = botAuthHeader;
+
+      await discordApi<DiscordUser>({
+        method: "GET",
+        path: "/users/@me",
+        authHeader: botAuthHeader,
+      });
+
+      setupStage = "send-message";
+      const webhook = await discordApi<{ id: string; token?: string | null }>({
+        method: "POST",
+        path: `/channels/${encodeURIComponent(args.channelId)}/webhooks`,
+        authHeader: botAuthHeader,
+        body: {
+          name: `openclaw-acp-smoke-${smokeId.slice(-8)}`,
+        },
+      });
+      if (!webhook.id || !webhook.token) {
+        return {
+          ok: false,
+          stage: "send-message",
+          smokeId,
+          error:
+            "Discord webhook creation succeeded but no webhook token was returned; cannot post smoke message.",
+        };
+      }
+      webhookForCleanup = { id: webhook.id, token: webhook.token };
+
+      const sent = await discordWebhookApi<DiscordMessage>({
+        method: "POST",
+        webhookId: webhook.id,
+        webhookToken: webhook.token,
+        query: "wait=true",
+        body: {
+          content: instruction,
+          allowed_mentions: args.mentionUserId
+            ? { parse: [], users: [args.mentionUserId] }
+            : { parse: [] },
+        },
+      });
+      sentMessageId = sent.id;
+      senderAuthorId = sent.author?.id;
+    } else {
+      setupStage = "send-message";
+      const sent = await openclawCliJson<{
+        payload?: {
+          result?: {
+            messageId?: string;
+          };
+        };
+      }>({
+        openclawBin: args.openclawBin,
+        args: [
+          "message",
+          "send",
+          "--channel",
+          "discord",
+          "--target",
+          args.channelId,
+          "--message",
+          instruction,
+          "--json",
+        ],
+      });
+      sentMessageId = String(sent.payload?.result?.messageId || "");
+      if (!sentMessageId) {
+        throw new Error("openclaw message send did not return payload.result.messageId");
+      }
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      stage: setupStage,
+      smokeId,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const startedAt = Date.now();
+
+  const deadline = startedAt + args.timeoutMs;
+  let winningBinding: ThreadBindingRecord | undefined;
+  let latestCandidates: ThreadBindingRecord[] = [];
+
+  try {
+    while (Date.now() < deadline && !winningBinding) {
+      try {
+        const entries = await readThreadBindings(args.threadBindingsPath);
+        latestCandidates = resolveCandidateBindings({
+          entries,
+          minBoundAt: startedAt - 3_000,
+          targetAgent: args.targetAgent,
+        });
+        winningBinding = latestCandidates[0];
+      } catch {
+        // Keep polling; file may not exist yet or may be mid-write.
+      }
+      if (!winningBinding) {
+        await sleep(args.pollMs);
+      }
+    }
+
+    if (!winningBinding?.threadId || !winningBinding?.targetSessionKey) {
+      let parentRecent: DiscordMessage[] = [];
+      try {
+        parentRecent = await loadParentRecentMessages({ args, readAuthHeader });
+      } catch {
+        // Best effort diagnostics only.
+      }
+      return {
+        ok: false,
+        stage: "wait-binding",
+        smokeId,
+        error: `Timed out waiting for new ACP thread binding (path: ${args.threadBindingsPath}).`,
+        diagnostics: {
+          bindingCandidates: latestCandidates.slice(0, 6).map((entry) => ({
+            threadId: entry.threadId || "",
+            targetSessionKey: entry.targetSessionKey || "",
+            targetKind: entry.targetKind,
+            agentId: entry.agentId,
+            boundAt: entry.boundAt,
+          })),
+          parentChannelRecent: parentRecent.map(toRecentMessageRow),
+        },
+      };
+    }
+
+    const threadId = winningBinding.threadId;
+    let ackMessage: DiscordMessage | undefined;
+    while (Date.now() < deadline && !ackMessage) {
+      try {
+        const threadMessages =
+          args.driverMode === "openclaw"
+            ? await readMessagesWithOpenclaw({
+                openclawBin: args.openclawBin,
+                target: threadId,
+                limit: 50,
+              })
+            : await discordApi<DiscordMessage[]>({
+                method: "GET",
+                path: `/channels/${encodeURIComponent(threadId)}/messages?limit=50`,
+                authHeader: readAuthHeader,
+              });
+        ackMessage = threadMessages.find((message) => {
+          const content = message.content || "";
+          if (!content.includes(ackToken)) {
+            return false;
+          }
+          const authorId = message.author?.id || "";
+          return !senderAuthorId || authorId !== senderAuthorId;
+        });
+      } catch {
+        // Keep polling; thread can appear before read permissions settle.
+      }
+      if (!ackMessage) {
+        await sleep(args.pollMs);
+      }
+    }
+
+    if (!ackMessage) {
+      let parentRecent: DiscordMessage[] = [];
+      try {
+        parentRecent = await loadParentRecentMessages({ args, readAuthHeader });
+      } catch {
+        // Best effort diagnostics only.
+      }
+
+      return {
+        ok: false,
+        stage: "wait-ack",
+        smokeId,
+        error: `Thread bound (${threadId}) but timed out waiting for ACK token "${ackToken}" from OpenClaw.`,
+        diagnostics: {
+          bindingCandidates: [
+            {
+              threadId: winningBinding.threadId || "",
+              targetSessionKey: winningBinding.targetSessionKey || "",
+              targetKind: winningBinding.targetKind,
+              agentId: winningBinding.agentId,
+              boundAt: winningBinding.boundAt,
+            },
+          ],
+          parentChannelRecent: parentRecent.map(toRecentMessageRow),
+        },
+      };
+    }
+
+    return {
+      ok: true,
+      smokeId,
+      ackToken,
+      sentMessageId,
+      binding: {
+        threadId,
+        targetSessionKey: winningBinding.targetSessionKey,
+        targetKind: String(winningBinding.targetKind || "acp"),
+        agentId: String(winningBinding.agentId || args.targetAgent),
+        boundAt: normalizeBoundAt(winningBinding),
+        accountId: winningBinding.accountId,
+        channelId: winningBinding.channelId,
+      },
+      ackMessage: {
+        id: ackMessage.id,
+        authorId: ackMessage.author?.id,
+        authorUsername: ackMessage.author?.username,
+        timestamp: ackMessage.timestamp,
+        content: ackMessage.content,
+      },
+    };
+  } finally {
+    if (webhookForCleanup) {
+      await discordWebhookApi<void>({
+        method: "DELETE",
+        webhookId: webhookForCleanup.id,
+        webhookToken: webhookForCleanup.token,
+      }).catch(() => {
+        // Best-effort cleanup only.
+      });
+    }
+  }
+}
+
+if (hasFlag("--help") || hasFlag("-h")) {
+  // eslint-disable-next-line no-console
+  console.log(usage());
+  process.exit(0);
+}
+
+const result = await run().catch(
+  (err): FailureResult => ({
+    ok: false,
+    stage: "unexpected",
+    smokeId: "n/a",
+    error: err instanceof Error ? err.message : String(err),
+  }),
+);
+
+printOutput({
+  json: hasFlag("--json"),
+  payload: result,
+});
+
+process.exit(result.ok ? 0 : 1);