@songsid/agend 2.1.4-beta.4 → 2.1.4-beta.41

package/dist/channel/adapters/discord.js

@@ -6,9 +6,13 @@ import { join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { createWriteStream } from "node:fs";
-import { Client, GatewayIntentBits, Partials, ActionRowBuilder, ButtonBuilder, ButtonStyle, StringSelectMenuBuilder, ApplicationCommandOptionType, ChannelType, MessageFlags, } from "discord.js";
+import { Client, GatewayIntentBits, Partials, ActionRowBuilder, ButtonBuilder, ButtonStyle, StringSelectMenuBuilder, ApplicationCommandOptionType, ChannelType, MessageFlags, Status, } from "discord.js";
 import { MessageQueue } from "../message-queue.js";
 const DISCORD_MAX_LENGTH = 2000;
+const GATEWAY_WATCHDOG_INTERVAL_MS = 30_000;
+const GATEWAY_STALE_MIN_MS = 180_000;
+const GATEWAY_RECONNECT_WAIT_MS = 30_000;
+const GATEWAY_MAX_BACKOFF_MS = 5 * 60_000;
 /** Curated ClassicBot backends for Discord's native slash-option dropdown. */
 export const DISCORD_START_BACKEND_CHOICES = [
     { name: "Claude Code", value: "claude-code" },
@@ -24,6 +28,27 @@ export class DiscordAdapter extends EventEmitter {
     topology = "channels";
     id;
     client;
+    clientFactory;
+    now;
+    watchdogIntervalMs;
+    staleThresholdMs;
+    reconnectBaseDelayMs;
+    desiredRunning = false;
+    lifecycleEpoch = 0;
+    clientGeneration = 0;
+    reconnectPromise = null;
+    watchdogTimer = null;
+    lastWatchdogTickAt = 0;
+    generationReadyAt = 0;
+    generationNonReadySince = 0;
+    shardNonReadySince = new Map();
+    previousHeartbeatAck = new Map();
+    observedHeartbeatInterval = new Map();
+    healthStatus = "stopped";
+    lastDispatchAt = null;
+    lastReconnectAt = null;
+    lastReconnectReason = null;
+    reconnectCount = 0;
     botToken;
     accessManager;
     inboxDir;
@@ -47,20 +72,12 @@ export class DiscordAdapter extends EventEmitter {
         this.generalChannelId = opts.generalChannelId;
         this.registerCommands = opts.registerCommands !== false;
         mkdirSync(this.inboxDir, { recursive: true });
-        this.client = new Client({
-            intents: [
-                GatewayIntentBits.Guilds,
-                GatewayIntentBits.GuildMessages,
-                GatewayIntentBits.MessageContent,
-                // Required to receive messageReactionAdd/Remove at all.
-                GatewayIntentBits.GuildMessageReactions,
-            ],
-            // Reactions on messages that are not in the cache — which is every message
-            // sent before the current process started, i.e. the common case after any
-            // restart — arrive as PARTIAL objects. Without these, discord.js drops those
-            // events entirely and reactions appear to work only on very recent messages.
-            partials: [Partials.Message, Partials.Reaction, Partials.User],
-        });
+        this.clientFactory = opts.clientFactory ?? (() => this.buildClient());
+        this.now = opts.now ?? Date.now;
+        this.watchdogIntervalMs = opts.watchdogIntervalMs ?? GATEWAY_WATCHDOG_INTERVAL_MS;
+        this.staleThresholdMs = opts.staleThresholdMs ?? GATEWAY_STALE_MIN_MS;
+        this.reconnectBaseDelayMs = opts.reconnectBaseDelayMs ?? 5_000;
+        this.client = this.clientFactory();
         this.queue = new MessageQueue({
             send: async (chatId, threadId, text) => {
                 const channel = await this._fetchTextChannel(threadId ?? chatId);
@@ -78,23 +95,87 @@ export class DiscordAdapter extends EventEmitter {
                 return { messageId: msg.id };
             },
         });
-        this._registerHandlers();
+        this.registerClientHandlers(this.client, this.clientGeneration);
+    }
+    buildClient() {
+        return new Client({
+            intents: [
+                GatewayIntentBits.Guilds,
+                GatewayIntentBits.GuildMessages,
+                GatewayIntentBits.MessageContent,
+                GatewayIntentBits.GuildMessageReactions,
+            ],
+            // Events for messages/reactions created before this process started are partial.
+            partials: [Partials.Message, Partials.Reaction, Partials.User],
+        });
     }
     async _fetchTextChannel(channelId) {
-        const channel = await this.client.channels.fetch(channelId);
+        const client = await this.readyClient();
+        const channel = await client.channels.fetch(channelId);
         if (!channel?.isTextBased()) {
             throw new Error(`Channel ${channelId} is not a text channel`);
         }
         return channel;
     }
-    _registerHandlers() {
+    registerClientHandlers(client, generation) {
         // Client/shard errors (WebSocket hiccups, gateway resumes, etc.). discord.js
         // auto-reconnects; we just need a listener so Node's EventEmitter doesn't
         // rethrow on "error" — without one it surfaces as an uncaughtException and
         // the process-level handler tears down the whole fleet (the built-in adapter
         // shares the fleet process).
-        this.client.on("error", (err) => console.warn(`[discord] client error: ${err?.message ?? err}`));
-        this.client.on("shardError", (err) => console.warn(`[discord] shard error: ${err?.message ?? err}`));
+        client.on("error", (err) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            console.warn(`[discord:${this.id}] client error: ${err?.message ?? err}`);
+            this.healthStatus = "retrying";
+            this.emitHealthChanged();
+        });
+        client.on("shardError", (err, shardId) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            console.warn(`[discord:${this.id}] shard ${shardId} error: ${err?.message ?? err}`);
+            this.healthStatus = "retrying";
+            this.emitHealthChanged();
+        });
+        client.on("shardReconnecting", (shardId) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            this.healthStatus = "retrying";
+            console.warn(`[discord:${this.id}] shard ${shardId} reconnecting`);
+        });
+        client.on("shardResume", (shardId, replayedEvents) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            this.healthStatus = "connected";
+            this.shardNonReadySince.delete(shardId);
+            console.info(`[discord:${this.id}] shard ${shardId} resumed (${replayedEvents} replayed event(s))`);
+        });
+        client.on("shardReady", (shardId) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            this.healthStatus = "connected";
+            this.shardNonReadySince.delete(shardId);
+        });
+        client.on("shardDisconnect", (event, shardId) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            this.healthStatus = "retrying";
+            this.shardNonReadySince.set(shardId, this.now());
+            console.warn(`[discord:${this.id}] shard ${shardId} disconnected (${event.code}: ${event.reason || "no reason"})`);
+        });
+        client.on("invalidated", () => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            console.warn(`[discord:${this.id}] gateway session invalidated; rebuilding client`);
+            void this.reconnectGateway("gateway session invalidated").catch(() => { });
+        });
+        client.on("raw", (packet) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            if (packet.t)
+                this.lastDispatchAt = this.now();
+        });
+        client.once("ready", () => void this.handleClientReady(client, generation));
         // Reactions on the bot's messages, as inbound events (#408). Both add and remove
         // are reported so an agent can see an approval being withdrawn.
         const onReaction = async (reaction, user, action) => {
@@ -109,7 +190,9 @@ export class DiscordAdapter extends EventEmitter {
                         return;
                     }
                 }
-                if (user.id === this.client.user?.id)
+                if (!this.isCurrentClient(client, generation))
+                    return;
+                if (user.id === client.user?.id)
                     return; // our own reaction
                 // Other bots' reactions are DELIVERED on purpose: agents react to each
                 // other's messages as signals (agent A 👍 → agent B sees it). The noise
@@ -119,11 +202,11 @@ export class DiscordAdapter extends EventEmitter {
                 const message = reaction.message;
                 // Only reactions on OUR messages are meaningful as agent signals; a user
                 // reacting to another user's message is chatter.
-                if (message.author?.id && message.author.id !== this.client.user?.id)
+                if (message.author?.id && message.author.id !== client.user?.id)
                     return;
                 if (message.guildId && message.guildId !== this.guildId && !this.openChannels.has(message.channelId))
                     return;
-                this.emit("reaction", {
+                this.emitFromClient(client, generation, "reaction", {
                     source: "discord",
                     adapterId: this.id,
                     chatId: this.guildId,
@@ -142,11 +225,13 @@ export class DiscordAdapter extends EventEmitter {
                 console.warn(`[discord] reaction ${action} handler error (${err.message})`);
             }
         };
-        this.client.on("messageReactionAdd", (reaction, user) => void onReaction(reaction, user, "add"));
-        this.client.on("messageReactionRemove", (reaction, user) => void onReaction(reaction, user, "remove"));
-        this.client.on("messageCreate", async (msg) => {
+        client.on("messageReactionAdd", (reaction, user) => void onReaction(reaction, user, "add"));
+        client.on("messageReactionRemove", (reaction, user) => void onReaction(reaction, user, "remove"));
+        client.on("messageCreate", async (msg) => {
             try {
-                if (msg.author.id === this.client.user?.id)
+                if (!this.isCurrentClient(client, generation))
+                    return;
+                if (msg.author.id === client.user?.id)
                     return; // Ignore own messages
                 if (!msg.guildId)
                     return;
@@ -265,6 +350,33 @@ export class DiscordAdapter extends EventEmitter {
                     size: att.size,
                     filename: att.name ?? undefined,
                 }));
+                // A Discord reply carries only the referenced message id on the new
+                // message. Fetch the original so image attachments are delivered with
+                // the reply rather than reducing the reference to text alone. Keep this
+                // limited to real attachments: ordinary URL auto-embeds must not become
+                // downloads (the same policy as the outer message above).
+                let replyToText;
+                if (msg.reference?.messageId) {
+                    try {
+                        const ref = await msg.fetchReference();
+                        replyToText = ref.content || ref.embeds?.[0]?.description || undefined;
+                        for (const att of ref.attachments?.values() ?? []) {
+                            if (!att.contentType?.startsWith("image/"))
+                                continue;
+                            if (!attachments.some(existing => existing.fileId === att.id)) {
+                                attachments.push({
+                                    kind: "photo",
+                                    fileId: att.id,
+                                    mime: att.contentType,
+                                    size: att.size,
+                                    filename: att.name ?? undefined,
+                                });
+                            }
+                            this.attachmentUrls.set(att.id, att.url);
+                        }
+                    }
+                    catch { /* deleted message or no permission */ }
+                }
                 // Embed images become synthetic photo attachments so the normal download
                 // path (attachment-handler → downloadAttachment → image_path) serves them
                 // without knowing where the bytes came from. Their synthetic ids are
@@ -293,15 +405,7 @@ export class DiscordAdapter extends EventEmitter {
                     else
                         break;
                 }
-                let replyToText;
-                if (msg.reference?.messageId) {
-                    try {
-                        const ref = await msg.fetchReference();
-                        replyToText = ref.content || ref.embeds?.[0]?.description || undefined;
-                    }
-                    catch { /* deleted message or no permission */ }
-                }
-                this.emit("message", {
+                this.emitFromClient(client, generation, "message", {
                     source: "discord",
                     adapterId: this.id,
                     chatId,
@@ -326,8 +430,10 @@ export class DiscordAdapter extends EventEmitter {
         // Handle button interactions and slash commands
         // Trust boundary: interaction responses can throw DiscordAPIError[10062] if the
         // interaction expires (>3s). Catch to prevent crashing the entire daemon.
-        this.client.on("interactionCreate", async (interaction) => {
+        client.on("interactionCreate", async (interaction) => {
             try {
+                if (!this.isCurrentClient(client, generation))
+                    return;
                 // Buttons: acknowledge IMMEDIATELY, before any guild/channel filtering.
                 // A button has a 3s ack window; any early return (unknown guild/channel)
                 // or a downstream no-op (e.g. the cancel button was already cleared) would
@@ -344,7 +450,7 @@ export class DiscordAdapter extends EventEmitter {
                         // console.log(`[discord] ignoring button from non-primary guild ${interaction.guildId} channel ${interaction.channelId}`);
                         return;
                     }
-                    this.emit("callback_query", {
+                    this.emitFromClient(client, generation, "callback_query", {
                         callbackData: interaction.customId,
                         chatId: this.guildId,
                         threadId: interaction.channelId,
@@ -372,7 +478,7 @@ export class DiscordAdapter extends EventEmitter {
                     const callbackData = interaction.values[0];
                     if (!callbackData)
                         return;
-                    this.emit("callback_query", {
+                    this.emitFromClient(client, generation, "callback_query", {
                         callbackData,
                         chatId: this.guildId,
                         threadId: interaction.channelId,
@@ -392,7 +498,7 @@ export class DiscordAdapter extends EventEmitter {
                     if (interaction.commandName === "chat") {
                         const text = interaction.options.getString("message") ?? "";
                         await interaction.deferReply();
-                        this.emit("slash_command", {
+                        this.emitFromClient(client, generation, "slash_command", {
                             command: "chat",
                             channelId: interaction.channelId,
                             channelName,
@@ -419,7 +525,7 @@ export class DiscordAdapter extends EventEmitter {
                         for (const opt of interaction.options.data) {
                             options[opt.name] = opt.value;
                         }
-                        this.emit("slash_command", {
+                        this.emitFromClient(client, generation, "slash_command", {
                             command: interaction.commandName,
                             channelId: interaction.channelId,
                             channelName,
@@ -433,6 +539,12 @@ export class DiscordAdapter extends EventEmitter {
                             catch {
                                 return undefined;
                             } },
+                            dismissResponse: async () => {
+                                try {
+                                    await interaction.deleteReply();
+                                }
+                                catch { /* interaction may already be gone */ }
+                            },
                             respondChoices: async (text, choices) => {
                                 const select = new StringSelectMenuBuilder()
                                     .setCustomId(CLASSIC_START_BACKEND_SELECT_ID)
@@ -459,14 +571,18 @@ export class DiscordAdapter extends EventEmitter {
             }
         });
         // Handle channel deletion (equivalent to topic_closed)
-        this.client.on("guildCreate", (guild) => {
-            this.emit("new_group_detected", {
+        client.on("guildCreate", (guild) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
+            this.emitFromClient(client, generation, "new_group_detected", {
                 groupId: guild.id,
                 groupTitle: guild.name,
                 source: "discord",
             });
         });
-        this.client.on("channelDelete", (channel) => {
+        client.on("channelDelete", (channel) => {
+            if (!this.isCurrentClient(client, generation))
+                return;
             if (!("guildId" in channel))
                 return;
             if (channel.guildId !== this.guildId) {
@@ -474,7 +590,7 @@ export class DiscordAdapter extends EventEmitter {
                     return;
                 // Allowed: an open classic channel in a non-primary guild was deleted.
             }
-            this.emit("topic_closed", {
+            this.emitFromClient(client, generation, "topic_closed", {
                 chatId: this.guildId,
                 threadId: channel.id,
             });
@@ -486,19 +602,252 @@ export class DiscordAdapter extends EventEmitter {
         // console.log(`[AgEnD] setOpenChannels: ${channelIds.length} channels`, channelIds);
     }
     // ── Lifecycle ──────────────────────────────────────────────────────────
-    async start() {
-        this.queue.start();
-        this.client.once("ready", async () => {
+    isCurrentClient(client, generation) {
+        // lifecycleEpoch===0 preserves constructor-level handler tests; a real Client
+        // cannot dispatch gateway events before start/login.
+        return (this.desiredRunning || this.lifecycleEpoch === 0)
+            && this.client === client
+            && this.clientGeneration === generation;
+    }
+    emitFromClient(client, generation, event, ...args) {
+        return this.isCurrentClient(client, generation) ? this.emit(event, ...args) : false;
+    }
+    emitHealthChanged() {
+        this.emit("gateway_health", this.getHealthSnapshot());
+    }
+    async loginFreshClient(reason, epoch) {
+        const oldClient = this.client;
+        // A destroyed discord.js Client cannot be logged in again. Destroy first to
+        // avoid overlapping gateway sessions delivering MESSAGE_CREATE twice.
+        oldClient.destroy();
+        const client = this.clientFactory();
+        const generation = ++this.clientGeneration;
+        this.client = client;
+        this.generationReadyAt = 0;
+        this.generationNonReadySince = this.now();
+        this.shardNonReadySince.clear();
+        this.previousHeartbeatAck.clear();
+        this.observedHeartbeatInterval.clear();
+        this.registerClientHandlers(client, generation);
+        this.emitHealthChanged();
+        try {
+            await client.login(this.botToken);
+            if (!this.desiredRunning || epoch !== this.lifecycleEpoch || this.client !== client) {
+                client.destroy();
+                throw new Error("Discord gateway login superseded by lifecycle change");
+            }
+            this.lastReconnectAt = this.now();
+            this.lastReconnectReason = reason;
+            this.healthStatus = client.isReady() ? "connected" : "starting";
+            this.emitHealthChanged();
+        }
+        catch (err) {
+            client.destroy();
+            throw err;
+        }
+    }
+    /** Rebuild just this bot's gateway Client. Calls coalesce into one generation. */
+    reconnectGateway(reason) {
+        if (this.reconnectPromise)
+            return this.reconnectPromise;
+        if (!this.desiredRunning)
+            return Promise.reject(new Error("Discord adapter is stopped"));
+        const epoch = this.lifecycleEpoch;
+        const reconnect = (async () => {
+            // Yield once so reconnectPromise is installed before destroy/login can emit
+            // a synchronous gateway error and re-enter this method.
+            await Promise.resolve();
+            if (!this.desiredRunning || epoch !== this.lifecycleEpoch) {
+                throw new Error("Discord gateway reconnect cancelled by adapter stop");
+            }
+            this.healthStatus = "retrying";
+            this.lastReconnectReason = reason;
+            this.reconnectCount++;
+            this.emitHealthChanged();
+            for (let attempt = 0; this.desiredRunning && epoch === this.lifecycleEpoch; attempt++) {
+                if (attempt > 0) {
+                    const delay = Math.min(this.reconnectBaseDelayMs * 2 ** Math.min(attempt - 1, 6), GATEWAY_MAX_BACKOFF_MS);
+                    await new Promise(resolve => {
+                        const timer = setTimeout(resolve, delay);
+                        timer.unref?.();
+                    });
+                    if (!this.desiredRunning || epoch !== this.lifecycleEpoch)
+                        break;
+                }
+                try {
+                    await this.loginFreshClient(reason, epoch);
+                    if (this.desiredRunning && epoch === this.lifecycleEpoch) {
+                        this.healthStatus = "connected";
+                        this.emitHealthChanged();
+                    }
+                    return;
+                }
+                catch (err) {
+                    if (!this.desiredRunning || epoch !== this.lifecycleEpoch)
+                        break;
+                    this.healthStatus = "retrying";
+                    console.warn(`[discord:${this.id}] gateway rebuild attempt ${attempt + 1} failed: ${err.message}`);
+                    this.emitHealthChanged();
+                }
+            }
+            throw new Error("Discord gateway reconnect cancelled by adapter stop");
+        })().finally(() => {
+            if (this.reconnectPromise === reconnect)
+                this.reconnectPromise = null;
+        });
+        this.reconnectPromise = reconnect;
+        return reconnect;
+    }
+    async readyClient() {
+        // A few focused unit tests install a minimal REST-only client stand-in. Real
+        // discord.js Clients always expose isReady().
+        const isReady = typeof this.client.isReady === "function"
+            ? this.client.isReady()
+            : true;
+        if (isReady && !this.reconnectPromise)
+            return this.client;
+        const reconnect = this.reconnectPromise ?? this.reconnectGateway("outbound requested while gateway unavailable");
+        let timer;
+        try {
+            await Promise.race([
+                reconnect,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("Discord gateway reconnect timed out")), GATEWAY_RECONNECT_WAIT_MS);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (!this.client.isReady())
+            throw new Error("Discord gateway is not ready");
+        return this.client;
+    }
+    startGatewayWatchdog() {
+        if (this.watchdogTimer)
+            clearInterval(this.watchdogTimer);
+        this.lastWatchdogTickAt = this.now();
+        this.watchdogTimer = setInterval(() => this.checkGatewayLiveness(), this.watchdogIntervalMs);
+        this.watchdogTimer.unref?.();
+    }
+    checkGatewayLiveness() {
+        if (!this.desiredRunning || this.reconnectPromise)
+            return;
+        const now = this.now();
+        const elapsed = now - this.lastWatchdogTickAt;
+        this.lastWatchdogTickAt = now;
+        // Host suspend / an overloaded event loop makes wall-clock ACK age jump. Give
+        // discord.js a fresh heartbeat window instead of rebuilding immediately.
+        if (elapsed > this.watchdogIntervalMs * 3) {
+            this.generationReadyAt = now;
+            this.generationNonReadySince = now;
+            this.shardNonReadySince.clear();
+            return;
+        }
+        const shards = [...this.client.ws.shards.values()];
+        let staleReason = null;
+        if (!this.client.isReady() && this.generationNonReadySince === 0)
+            this.generationNonReadySince = now;
+        if (this.client.isReady())
+            this.generationNonReadySince = 0;
+        if (!this.client.isReady() && now - this.generationNonReadySince > this.staleThresholdMs) {
+            staleReason = `client non-ready for ${now - this.generationNonReadySince}ms`;
+        }
+        for (const shard of shards) {
+            const lastAck = shard.lastPingTimestamp;
+            const previous = this.previousHeartbeatAck.get(shard.id);
+            if (lastAck >= 0 && previous != null && lastAck > previous) {
+                const interval = lastAck - previous;
+                if (interval >= 5_000 && interval <= 120_000)
+                    this.observedHeartbeatInterval.set(shard.id, interval);
+            }
+            if (lastAck >= 0)
+                this.previousHeartbeatAck.set(shard.id, lastAck);
+            const threshold = Math.max(this.staleThresholdMs, 3 * (this.observedHeartbeatInterval.get(shard.id) ?? 0));
+            if (shard.status === Status.Ready) {
+                this.shardNonReadySince.delete(shard.id);
+                if (lastAck === -1) {
+                    if (this.generationReadyAt > 0 && now - this.generationReadyAt > threshold) {
+                        staleReason = `shard ${shard.id} has no heartbeat ACK after startup grace`;
+                    }
+                }
+                else if (now - lastAck > threshold) {
+                    staleReason = `shard ${shard.id} heartbeat ACK stale by ${now - lastAck}ms`;
+                }
+            }
+            else {
+                const since = this.shardNonReadySince.get(shard.id) ?? now;
+                this.shardNonReadySince.set(shard.id, since);
+                if (now - since > threshold)
+                    staleReason = `shard ${shard.id} status ${shard.status} for ${now - since}ms`;
+            }
+        }
+        if (staleReason) {
+            this.healthStatus = "stale";
+            this.emitHealthChanged();
+            console.warn(`[discord:${this.id}] gateway watchdog detected ${staleReason}`);
+            void this.reconnectGateway(`watchdog: ${staleReason}`).catch(() => { });
+        }
+        else if (this.client.isReady()
+            && shards.every(shard => shard.status === Status.Ready)
+            && this.healthStatus !== "connected") {
+            // discord.js owns the first recovery layer (RESUME + replay). Clear a
+            // transient error marker once ACK/status prove that native recovery won.
+            this.healthStatus = "connected";
+            this.emitHealthChanged();
+        }
+    }
+    getHealthSnapshot() {
+        const now = this.now();
+        const shards = [...this.client.ws.shards.values()].map(shard => {
+            const lastAck = shard.lastPingTimestamp >= 0 ? shard.lastPingTimestamp : null;
+            return {
+                id: shard.id,
+                status: shard.status,
+                lastHeartbeatAckAt: lastAck,
+                heartbeatAgeMs: lastAck == null ? null : Math.max(0, now - lastAck),
+            };
+        });
+        const heartbeatAcks = shards
+            .map(shard => shard.lastHeartbeatAckAt)
+            .filter((value) => value != null);
+        const lastHeartbeatAckAt = heartbeatAcks.length > 0 ? Math.min(...heartbeatAcks) : null;
+        return {
+            id: this.id,
+            type: this.type,
+            status: this.healthStatus,
+            generation: this.clientGeneration,
+            isReady: this.client.isReady(),
+            wsStatus: this.client.ws.status ?? null,
+            lastHeartbeatAckAt,
+            heartbeatAgeMs: lastHeartbeatAckAt == null ? null : Math.max(0, now - lastHeartbeatAckAt),
+            shards,
+            lastDispatchAt: this.lastDispatchAt,
+            lastReconnectAt: this.lastReconnectAt,
+            lastReconnectReason: this.lastReconnectReason,
+            reconnectCount: this.reconnectCount,
+        };
+    }
+    async handleClientReady(client, generation) {
+        if (!this.isCurrentClient(client, generation))
+            return;
+        this.healthStatus = "connected";
+        this.generationReadyAt = this.now();
+        this.generationNonReadySince = 0;
+        this.shardNonReadySince.clear();
+        try {
             // Register classic bot slash commands (skipped for a secondary bot sharing
             // a guild with the primary — only the primary owns the guild's commands).
             if (this.registerCommands)
                 try {
-                    await this.client.application?.commands.set([
+                    await client.application?.commands.set([
                         {
                             name: "start", description: t("slash.start"),
                             options: [{
                                     name: "backend",
-                                    description: "Backend to start",
+                                    description: t("slash.option.backend"),
                                     type: ApplicationCommandOptionType.String,
                                     required: true,
                                     choices: DISCORD_START_BACKEND_CHOICES,
@@ -506,16 +855,16 @@ export class DiscordAdapter extends EventEmitter {
                         },
                         { name: "stop", description: t("slash.stop") },
                         {
-                            name: "pause", description: "🔒 Pause an idle instance",
-                            options: [{ name: "instance", description: "Instance name (required in General)", type: ApplicationCommandOptionType.String, required: false }],
+                            name: "pause", description: "🔒 " + t("slash.pause"),
+                            options: [{ name: "instance", description: t("slash.option.instance"), type: ApplicationCommandOptionType.String, required: false }],
                         },
                         {
-                            name: "wake", description: "🔒 Wake a paused instance",
-                            options: [{ name: "instance", description: "Instance name (required in General)", type: ApplicationCommandOptionType.String, required: false }],
+                            name: "wake", description: "🔒 " + t("slash.wake"),
+                            options: [{ name: "instance", description: t("slash.option.instance"), type: ApplicationCommandOptionType.String, required: false }],
                         },
                         {
                             name: "chat", description: t("slash.chat"),
-                            options: [{ name: "message", description: "Your message", type: 3, required: true }],
+                            options: [{ name: "message", description: t("slash.option.message"), type: 3, required: true }],
                         },
                         { name: "status", description: "🔒 " + t("slash.status") },
                         { name: "sysinfo", description: t("slash.sysinfo") },
@@ -525,15 +874,77 @@ export class DiscordAdapter extends EventEmitter {
                         { name: "update", description: "🔒 " + t("slash.update") },
                         { name: "doctor", description: "🔒 " + t("slash.doctor") },
                         { name: "usage", description: t("slash.usage") },
+                        {
+                            name: "tips", description: t("slash.tips"),
+                            options: [{
+                                    name: "mode", description: t("slash.option.tips_mode"),
+                                    type: ApplicationCommandOptionType.String, required: false,
+                                    choices: [
+                                        { name: "on", value: "on" },
+                                        { name: "off", value: "off" },
+                                        { name: "advanced on", value: "advanced on" },
+                                    ],
+                                }],
+                        },
                         { name: "compact", description: "🔒 " + t("slash.compact") },
+                        {
+                            name: "steer", description: t("slash.steer"),
+                            options: [{
+                                    name: "message", description: t("slash.option.steer_message"),
+                                    type: ApplicationCommandOptionType.String, required: true,
+                                }],
+                        },
+                        {
+                            name: "btw", description: t("slash.btw"),
+                            options: [{
+                                    name: "message", description: t("slash.option.btw_message"),
+                                    type: ApplicationCommandOptionType.String, required: true,
+                                }],
+                        },
+                        {
+                            name: "login", description: "🔒 " + t("slash.login"),
+                            options: [
+                                {
+                                    name: "backend", description: t("slash.option.login_backend"),
+                                    type: ApplicationCommandOptionType.String, required: false,
+                                    choices: [
+                                        { name: "claude-code", value: "claude-code" },
+                                        { name: "codex", value: "codex" },
+                                        { name: "kiro-cli", value: "kiro-cli" },
+                                        { name: "grok", value: "grok" },
+                                        { name: "antigravity", value: "antigravity" },
+                                    ],
+                                },
+                                { name: "code", description: t("slash.option.login_code"), type: ApplicationCommandOptionType.String, required: false },
+                                { name: "cancel", description: t("slash.option.login_cancel"), type: ApplicationCommandOptionType.Boolean, required: false },
+                            ],
+                        },
+                        {
+                            name: "install-cli", description: "🔒 " + t("slash.install_cli"),
+                            options: [
+                                {
+                                    name: "backend", description: t("slash.option.install_backend"),
+                                    type: ApplicationCommandOptionType.String, required: false,
+                                    choices: [
+                                        { name: "claude-code", value: "claude-code" },
+                                        { name: "codex", value: "codex" },
+                                        { name: "kiro-cli", value: "kiro-cli" },
+                                        { name: "grok", value: "grok" },
+                                        { name: "antigravity", value: "antigravity" },
+                                        { name: "opencode", value: "opencode" },
+                                    ],
+                                },
+                                { name: "cancel", description: t("slash.option.install_cancel"), type: ApplicationCommandOptionType.Boolean, required: false },
+                            ],
+                        },
                         { name: "clear", description: "🔒 " + t("slash.clear") },
                         {
-                            name: "model", description: "🔒 Switch model (admin only)",
+                            name: "model", description: "🔒 " + t("slash.model"),
                         },
                         {
                             name: "effort", description: "🔒 " + t("slash.effort"),
                             options: [{
-                                    name: "level", description: "low | medium | high | xhigh | max",
+                                    name: "level", description: t("slash.option.effort_level"),
                                     type: ApplicationCommandOptionType.String, required: false,
                                     choices: [
                                         { name: "low", value: "low" }, { name: "medium", value: "medium" },
@@ -546,13 +957,13 @@ export class DiscordAdapter extends EventEmitter {
                         {
                             name: "save", description: "🔒 " + t("slash.save"),
                             options: [
-                                { name: "filename", description: "File name to save as", type: 3, required: true },
-                                { name: "force", description: "Overwrite if file exists", type: 5, required: false },
+                                { name: "filename", description: t("slash.option.save_filename"), type: 3, required: true },
+                                { name: "force", description: t("slash.option.save_force"), type: 5, required: false },
                             ],
                         },
                         {
                             name: "load", description: "🔒 " + t("slash.load"),
-                            options: [{ name: "filename", description: "File name to load", type: 3, required: true }],
+                            options: [{ name: "filename", description: t("slash.option.load_filename"), type: 3, required: true }],
                         },
                         { name: "cancel", description: t("slash.cancel") },
                     ]);
@@ -560,11 +971,40 @@ export class DiscordAdapter extends EventEmitter {
                 catch (err) {
                     // Non-fatal — slash commands may fail on network issues
                 }
-            this.emit("started", this.client.user?.username ?? "discord-bot", this.client.user?.id);
-        });
-        await this.client.login(this.botToken);
+            if (!this.isCurrentClient(client, generation))
+                return;
+            this.emit("started", client.user?.username ?? "discord-bot", client.user?.id);
+        }
+        catch (err) {
+            console.warn(`[discord:${this.id}] ready handler failed: ${err.message}`);
+        }
+    }
+    async start() {
+        if (this.desiredRunning && this.client.isReady())
+            return;
+        this.desiredRunning = true;
+        const epoch = ++this.lifecycleEpoch;
+        this.healthStatus = "starting";
+        this.queue.start();
+        try {
+            await this.loginFreshClient("startup", epoch);
+            this.startGatewayWatchdog();
+        }
+        catch (err) {
+            if (epoch === this.lifecycleEpoch) {
+                this.desiredRunning = false;
+                this.healthStatus = "stopped";
+            }
+            throw err;
+        }
     }
     async stop() {
+        this.desiredRunning = false;
+        this.lifecycleEpoch++;
+        this.healthStatus = "stopped";
+        if (this.watchdogTimer)
+            clearInterval(this.watchdogTimer);
+        this.watchdogTimer = null;
         this.queue.stop();
         this.client.destroy();
     }
@@ -597,13 +1037,15 @@ export class DiscordAdapter extends EventEmitter {
         const chunks = splitText(text, chunkLimit);
         if (chunks.length === 0)
             throw new Error("Empty text");
-        // disablePreview → suppress the link embed(s) for this message.
-        const first = await channel.send(opts?.disablePreview
-            ? { content: chunks[0], flags: MessageFlags.SuppressEmbeds }
-            : chunks[0]);
-        // Enqueue remaining chunks
-        for (let i = 1; i < chunks.length; i++) {
-            this.queue.enqueue(chatId, opts?.threadId, { type: "content", text: chunks[i] });
+        // Await every platform POST before reporting success. Previously only the
+        // first chunk was awaited and later chunks were fire-and-forget queue items,
+        // so the reply tool could return success for a silently truncated message.
+        let first;
+        for (const chunk of chunks) {
+            const sent = await channel.send(opts?.disablePreview
+                ? { content: chunk, flags: MessageFlags.SuppressEmbeds }
+                : chunk);
+            first ??= sent;
         }
         return {
             messageId: first.id,
@@ -629,7 +1071,7 @@ export class DiscordAdapter extends EventEmitter {
         }
         catch { /* not in that channel — fall through to scan */ }
         try {
-            const guild = await this.client.guilds.fetch(this.guildId);
+            const guild = await (await this.readyClient()).guilds.fetch(this.guildId);
             const channels = guild.channels.cache.filter((c) => c.type === ChannelType.GuildText);
             for (const [, ch] of channels) {
                 try {
@@ -653,6 +1095,12 @@ export class DiscordAdapter extends EventEmitter {
     }
     /** Edit text and clear components (Discord keeps components on a plain edit,
      * so we must pass an empty array to drop the Cancel button). */
+    /** Keyboard-only removal — Discord keeps the original content untouched. */
+    async removeMessageButtons(chatId, messageId, threadId) {
+        const channel = await this._fetchTextChannel(threadId ?? chatId);
+        const msg = await channel.messages.fetch(messageId);
+        await msg.edit({ components: [] });
+    }
     async editMessageRemoveButtons(chatId, messageId, text, threadId) {
         // Prefer the exact channel (handles forum-topic threads, which a GuildText
         // scan misses); fall back to scanning top-level text channels.
@@ -664,7 +1112,7 @@ export class DiscordAdapter extends EventEmitter {
         }
         catch { /* not in that channel — fall through to scan */ }
         try {
-            const guild = await this.client.guilds.fetch(this.guildId);
+            const guild = await (await this.readyClient()).guilds.fetch(this.guildId);
             const channels = guild.channels.cache.filter((c) => c.type === ChannelType.GuildText);
             for (const [, ch] of channels) {
                 try {
@@ -691,7 +1139,7 @@ export class DiscordAdapter extends EventEmitter {
         }
         catch { /* not in that channel — fall through to scan */ }
         try {
-            const guild = await this.client.guilds.fetch(this.guildId);
+            const guild = await (await this.readyClient()).guilds.fetch(this.guildId);
             const channels = guild.channels.cache.filter((c) => c.type === ChannelType.GuildText);
             for (const [, ch] of channels) {
                 try {
@@ -714,7 +1162,7 @@ export class DiscordAdapter extends EventEmitter {
         const encoded = encodeURIComponent(emoji);
         try {
             // Direct REST call — single API request instead of 3 (fetchChannel → fetchMessage → react)
-            await this.client.rest.put(`/channels/${channelId}/messages/${messageId}/reactions/${encoded}/@me`);
+            await (await this.readyClient()).rest.put(`/channels/${channelId}/messages/${messageId}/reactions/${encoded}/@me`);
             return;
         }
         catch (directError) {
@@ -882,7 +1330,7 @@ export class DiscordAdapter extends EventEmitter {
     }
     // ── Topology: create channel ────────────────────────────────────────────
     async _resolveCategory() {
-        const guild = await this.client.guilds.fetch(this.guildId);
+        const guild = await (await this.readyClient()).guilds.fetch(this.guildId);
         await guild.channels.fetch();
         const existing = guild.channels.cache.find((c) => c.type === ChannelType.GuildCategory && c.name === this.categoryName);
         if (existing)
@@ -903,7 +1351,7 @@ export class DiscordAdapter extends EventEmitter {
         return this.categoryIdPromise;
     }
     async createTopic(name) {
-        const guild = await this.client.guilds.fetch(this.guildId);
+        const guild = await (await this.readyClient()).guilds.fetch(this.guildId);
         const categoryId = await this.ensureCategoryId();
         try {
             const channel = await guild.channels.create({
@@ -929,7 +1377,7 @@ export class DiscordAdapter extends EventEmitter {
         }
     }
     async deleteTopic(topicId) {
-        const channel = await this.client.channels.fetch(String(topicId));
+        const channel = await (await this.readyClient()).channels.fetch(String(topicId));
         // Only delete GuildText channels created by createTopic — never categories or forums
         if (channel && "type" in channel && channel.type === ChannelType.GuildText && "delete" in channel) {
             await channel.delete();
@@ -937,7 +1385,7 @@ export class DiscordAdapter extends EventEmitter {
     }
     async topicExists(topicId) {
         try {
-            const channel = await this.client.channels.fetch(String(topicId));
+            const channel = await (await this.readyClient()).channels.fetch(String(topicId));
             return channel != null;
         }
         catch {