@bongos/core 1.17.0

package/modules/discord/discord-bot.js

@@ -0,0 +1,545 @@
+'use strict';
+
+// Discord bot process — Phase 3 F3 (ADR 0033 §F3).
+//
+// An in-process discord.js gateway client that runs INSIDE the existing Node
+// server (no separate service — one droplet, one process), started from
+// server.js. This file is JUST the connection scaffolding: log in, stay
+// connected, reconnect on transient drops, shut down cleanly. It performs NO
+// GDS writes. Reactions (F4), role-sync (F5), and inbound (F6) build their
+// handlers on top of the client this module owns — but none of that is here.
+//
+// TRUST BOUNDARY (ADR 0033 §1 / ADR 0016): the bot is a service principal
+// trusted ONLY to assert "this Discord user, who acted, is linked builder X."
+// It is never an authority. Because F3 writes nothing, there is nothing here
+// for the boundary to defend yet — the invariant becomes load-bearing in F4.
+//
+// KILL-SWITCH (ADR 0033 "Hosting & secrets"): gated by DISCORD_BOT_ENABLED,
+// default OFF, fail-closed — exactly like BFG_WRITE_ENABLED (src/bongos/routes/
+// memory.js). When off, start() is a no-op and discord.js is never even
+// required, so a server with the switch off carries zero bot surface area.
+//
+// FAIL-SAFE: the web/game process is the priority. start() never throws and
+// never crashes the server — a missing token, a bad token, or a Discord
+// outage logs and returns; the HTTP server keeps serving. The bot is
+// best-effort infrastructure, not a critical dependency.
+
+const auth = require('./auth');
+const db = require('./db');
+const ic = require('../../src/module-api');
+
+let client = null;        // the live discord.js Client (or null when disabled/down)
+let starting = false;     // guard against double-start
+let reconcileTimer = null; // F5 periodic role-sync interval (cleared on stop)
+let channelTimer = null;   // ADR 0037 periodic channel-reconcile interval (cleared on stop)
+
+// How often the bot re-syncs every linked builder's Discord rank-role from the
+// live GDS rank (F5 reconcile, ADR 0033 §4). Catches anything the event-driven
+// syncs missed (bot was down during a rank change, a manual role edit, etc.).
+const ROLE_RECONCILE_MS = 6 * 60 * 60 * 1000; // 6h
+
+// How often the bot re-applies the channel config (ADR 0037). Same cadence as
+// role-sync; catches manual edits drifting the guild away from channels.json.
+const CHANNEL_RECONCILE_MS = 6 * 60 * 60 * 1000; // 6h
+
+// Kill-switch for the PASSIVE channel reconcile sweep (ADR 0037). Default OFF,
+// fail-closed — mirrors BFG_WRITE_ENABLED. When off, the bot never auto-edits
+// channels; an Archon must trigger it explicitly via routes/discord.js.
+function channelsManaged() {
+  return process.env.DISCORD_CHANNELS_MANAGED === 'true';
+}
+
+// The 👍 reaction is the upvote signal (ADR 0033 §3). Match on the unicode
+// emoji name discord.js reports for a standard thumbs-up.
+const UPVOTE_EMOJI = '👍';
+
+// The 👍/👎 approval reactions (task 1100). In #member-approvals a 👍 invites
+// and a 👎 dismisses; mapped to a decision in discord-approvals.
+const APPROVAL_EMOJI = new Set(['👍', '👎']);
+
+// PURE — the #ship-feed channel id the bot watches for reactions (F4). Env
+// DISCORD_SHIP_FEED_CHANNEL_ID wins, else `ship_feed_channel_id` in
+// ~/.config/otb/discord-bot.json. Returns null when unconfigured — and the
+// reaction handler then does NOTHING (fail-closed): with no channel pinned, the
+// bot won't act on reactions in arbitrary channels.
+function loadShipFeedChannelId() {
+  const envVal = process.env.DISCORD_SHIP_FEED_CHANNEL_ID;
+  if (envVal) return envVal;
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const os = require('node:os');
+    const raw = ic.readConfigFileSync('discord-bot.json');
+    const cfg = JSON.parse(raw);
+    if (cfg.ship_feed_channel_id) return String(cfg.ship_feed_channel_id);
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+// PURE — the #ideas channel id the bot files inbound messages from (F6). Env
+// DISCORD_IDEAS_CHANNEL_ID wins, else `ideas_channel_id` in the creds file.
+// Null → inbound is inert (the handler files nothing).
+function loadIdeasChannelId() {
+  const envVal = process.env.DISCORD_IDEAS_CHANNEL_ID;
+  if (envVal) return envVal;
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const os = require('node:os');
+    const raw = ic.readConfigFileSync('discord-bot.json');
+    const cfg = JSON.parse(raw);
+    if (cfg.ideas_channel_id) return String(cfg.ideas_channel_id);
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+// PURE — the #bugs channel id the bot files inbound bug-tasks from (F8). Env
+// DISCORD_BUGS_CHANNEL_ID wins, else `bugs_channel_id` in the creds file.
+// Null → bug intake is inert (the handler files nothing). Mirrors #ideas.
+function loadBugsChannelId() {
+  const envVal = process.env.DISCORD_BUGS_CHANNEL_ID;
+  if (envVal) return envVal;
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const os = require('node:os');
+    const raw = ic.readConfigFileSync('discord-bot.json');
+    const cfg = JSON.parse(raw);
+    if (cfg.bugs_channel_id) return String(cfg.bugs_channel_id);
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+// PURE — the #member-approvals channel id the bot watches for Archon 👍/👎 on
+// new-builder access requests (task 1100). Env DISCORD_MEMBER_APPROVALS_CHANNEL_ID
+// wins, else `member_approvals_channel_id` in the creds file. Null → member
+// approvals are inert (the handler acts on nothing — fail-closed).
+function loadMemberApprovalsChannelId() {
+  const envVal = process.env.DISCORD_MEMBER_APPROVALS_CHANNEL_ID;
+  if (envVal) return envVal;
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const os = require('node:os');
+    const raw = ic.readConfigFileSync('discord-bot.json');
+    const cfg = JSON.parse(raw);
+    if (cfg.member_approvals_channel_id) return String(cfg.member_approvals_channel_id);
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+// PURE — pull image attachment URLs off a discord.js message. An attachment is
+// an image when it carries an image/* content-type (or, defensively, a width).
+// Shared by the #bugs and #ideas handlers so both intakes treat images
+// identically. Returns [] for a message with no image attachments.
+function extractImageUrls(msg) {
+  const urls = [];
+  if (msg && msg.attachments && typeof msg.attachments.forEach === 'function') {
+    msg.attachments.forEach((a) => {
+      const isImage = (a.contentType && a.contentType.startsWith('image/')) || a.width != null;
+      if (isImage && a.url) urls.push(a.url);
+    });
+  }
+  return urls;
+}
+
+// Build a thin #ideas / #bugs MessageCreate listener. The two inbound channels
+// share this EXACT guard prologue — fail-closed on channel config, ignore
+// bots/webhooks, skip empty messages — and differ only in the channel id, the
+// aggregator, and the error-log label (task 1091, C7). NEVER throws into the
+// gateway (the catch swallows + logs, same as the inlined copies).
+function makeInboundChannelHandler({ channelId, aggregator, logLabel }) {
+  return async (msg) => {
+    try {
+      if (!channelId) return;                         // fail-closed: no channel pinned
+      if (msg.channelId !== channelId) return;        // only the target channel
+      if (msg.author?.bot) return;                    // ignore bots/webhooks (incl. self)
+      if (msg.webhookId) return;                      // ignore webhook posts
+      const imageUrls = extractImageUrls(msg);
+      const hasText = msg.content && msg.content.trim();
+      if (!hasText && imageUrls.length === 0) return; // nothing to file
+      aggregator.enqueue({
+        discordUserId: msg.author.id,
+        content: msg.content || '',
+        imageUrls,
+        messageId: msg.id,
+      });
+    } catch (err) {
+      console.error(`[discord-bot] ${logLabel} error:`, err.message);
+    }
+  };
+}
+
+// PURE — the kill-switch read. Mirrors BFG_WRITE_ENABLED: a flag is ON only
+// when the env var is the exact string 'true'. Anything else (unset, '1',
+// 'false', '') is OFF. Pure + injectable so it's unit-tested without env
+// mutation. Default-OFF is the whole point: a fresh deploy never connects a
+// bot until someone deliberately sets the flag.
+function botEnabled(env = process.env) {
+  return env.DISCORD_BOT_ENABLED === 'true';
+}
+
+// The live client, for the feature modules that come later (F4/F5/F6). Null
+// until start() has connected; consumers must null-check.
+function getClient() {
+  return client;
+}
+
+// Start the bot. Idempotent-ish: a no-op if disabled, already started, or
+// already starting. Returns the Client on a login attempt, else null. Awaiting
+// it resolves once login is *initiated* (discord.js fires 'ready' async after);
+// it never rejects — all failure is caught and logged so the caller (server.js
+// boot) can't be taken down by Discord.
+async function start() {
+  if (!botEnabled()) {
+    console.log('[discord-bot] disabled (DISCORD_BOT_ENABLED is not "true") — not connecting.');
+    return null;
+  }
+  if (client || starting) {
+    console.log('[discord-bot] start() called but a client is already active — skipping.');
+    return client;
+  }
+
+  const token = auth.loadDiscordBotToken();
+  if (!token) {
+    // Enabled but no token: a misconfiguration, not a crash. Log loudly and
+    // bail so the rest of the server still boots.
+    console.error('[discord-bot] DISCORD_BOT_ENABLED is on but no bot token is configured '
+      + '(set DISCORD_BOT_TOKEN or bot_token in ~/.config/otb/discord-bot.json) — not connecting.');
+    return null;
+  }
+
+  starting = true;
+  try {
+    // Lazy require: when the switch is off (the default), discord.js and its
+    // 240-package tree are never loaded into the process at all. Also keeps
+    // unit tests that don't enable the bot free of the dependency.
+    const { Client, GatewayIntentBits, Events, Partials } = require('discord.js');
+    const reaction = require('./discord-reaction');
+    const approvals = require('./discord-approvals');
+    const inbound = require('./discord-inbound');
+    const bugs = require('./discord-bugs');
+
+    // Intents (least-privilege, widened per feature): Guilds (F3) +
+    // GuildMessageReactions (F4 — 👍 on #ship-feed) + GuildMembers (F5,
+    // PRIVILEGED — fetch members to set rank roles) + GuildMessages +
+    // MessageContent (F6, PRIVILEGED — read #ideas messages to file them as
+    // ideas). Partials let us receive reactions on messages NOT in the bot's
+    // cache (e.g. feed messages posted before the bot started).
+    const c = new Client({
+      intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessageReactions,
+        GatewayIntentBits.GuildMembers,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+      ],
+      partials: [Partials.Message, Partials.Channel, Partials.Reaction],
+    });
+
+    c.once(Events.ClientReady, (ready) => {
+      const guilds = ready.guilds?.cache?.size ?? 0;
+      // ready.user.tag is the bot's name#id — safe to log; the TOKEN never is.
+      console.log(`[discord-bot] connected as ${ready.user.tag} — in ${guilds} guild(s).`);
+      if (guilds === 0) {
+        const worldName = (() => { try { return ic.branding().identity?.worldName || 'project'; } catch { return 'project'; } })();
+        console.log(`[discord-bot] note: bot is in 0 guilds. Invite it to the ${worldName} `
+          + 'server (F5/role-sync needs it there with Manage Roles) before role/reaction features can act.');
+      }
+      // Ensure all managed rank roles exist in the guild — creates any missing
+      // ones and saves their ids to the config file. Runs before the reconcile
+      // sweep so newly-created role ids are available for member syncs.
+      const roleSync = require('./discord-role-sync');
+      const guild = roleSync.loadGuildId()
+        ? ready.guilds?.cache?.get(roleSync.loadGuildId()) || null
+        : ready.guilds?.cache?.first() || null;
+      roleSync.ensureRankRoles(guild).catch((e) =>
+        console.error('[discord-bot] ensureRankRoles failed:', e.message));
+
+      // F5 role-sync (ADR 0033 §4): an initial reconcile once connected, then a
+      // periodic sweep. Both best-effort — a Discord perms/hierarchy problem
+      // logs inside the sync and never affects the GDS.
+      runRoleReconcile('on-connect');
+      reconcileTimer = setInterval(() => runRoleReconcile('periodic'), ROLE_RECONCILE_MS);
+      if (reconcileTimer.unref) reconcileTimer.unref(); // don't keep the process alive
+
+      // ADR 0037: passive channel reconcile — make the guild's channel layout
+      // match docs/discord/channels.json. KILL-SWITCHED behind
+      // DISCORD_CHANNELS_MANAGED (default OFF, fail-closed) so the bot never
+      // surprise-edits a guild; when off, channels are only ever touched by an
+      // explicit Archon command (routes/discord.js). Best-effort, like role-sync.
+      if (channelsManaged()) {
+        runChannelReconcile('on-connect');
+        channelTimer = setInterval(() => runChannelReconcile('periodic'), CHANNEL_RECONCILE_MS);
+        if (channelTimer.unref) channelTimer.unref();
+      }
+    });
+
+    // discord.js auto-reconnects transient gateway drops on its own; we only
+    // LOG the lifecycle so an operator can see the connection's health in the
+    // journal. No custom reconnect loop — that would fight the library.
+    c.on(Events.Error, (err) => console.error('[discord-bot] client error:', err.message));
+    c.on(Events.Warn, (msg) => console.warn('[discord-bot] warning:', msg));
+    c.on(Events.ShardError, (err) => console.error('[discord-bot] shard error:', err.message));
+    c.on(Events.ShardDisconnect, (event, id) =>
+      console.warn(`[discord-bot] shard ${id} disconnected (code ${event?.code}) — discord.js will attempt to reconnect.`));
+    c.on(Events.ShardReconnecting, (id) =>
+      console.log(`[discord-bot] shard ${id} reconnecting…`));
+    c.on(Events.ShardResume, (id) =>
+      console.log(`[discord-bot] shard ${id} resumed.`));
+    // 'invalidated' = the session can't be recovered (e.g. token revoked).
+    // discord.js will NOT auto-reconnect; reconnecting would hammer the API.
+    // Log loudly, tear down, and leave it for a human — a revoked token is an
+    // operator action, not a transient blip.
+    c.on(Events.Invalidated, () => {
+      console.error('[discord-bot] session invalidated (token revoked or auth failed) — '
+        + 'destroying client; a human must re-check the token and restart.');
+      stop().catch(() => {});
+    });
+
+    // Resolve the watched #ship-feed channel id ONCE at startup — NOT per
+    // reaction. loadShipFeedChannelId() can do a synchronous fs.readFileSync
+    // (file fallback); calling it inside the event handler would block the
+    // event loop on every 👍 guild-wide (F4 efficiency finding). Config is
+    // boot-time anyway (changing it needs a restart, like the kill-switch).
+    const shipFeedChannelId = loadShipFeedChannelId();
+    console.log(shipFeedChannelId
+      ? `[discord-bot] watching #ship-feed (${shipFeedChannelId}) for 👍 upvotes.`
+      : '[discord-bot] no DISCORD_SHIP_FEED_CHANNEL_ID set — upvoting is inert (no channel pinned).');
+
+    // Approval channel (task 1100): #member-approvals (Archon 👍/👎 admits a new
+    // builder). Resolved once at startup; null → the approval surface is inert
+    // (fail-closed — the bot won't act on reactions in arbitrary channels).
+    const memberApprovalsChannelId = loadMemberApprovalsChannelId();
+    console.log(memberApprovalsChannelId
+      ? `[discord-bot] watching #member-approvals (${memberApprovalsChannelId}) for Archon 👍/👎.`
+      : '[discord-bot] no DISCORD_MEMBER_APPROVALS_CHANNEL_ID set — member approvals are inert (no channel pinned).');
+
+    // F6 inbound: the #ideas channel whose messages become idea_inbox entries.
+    // Resolved once at startup (config is boot-time). Null → inbound is inert.
+    const ideasChannelId = loadIdeasChannelId();
+    console.log(ideasChannelId
+      ? `[discord-bot] watching #ideas (${ideasChannelId}) for inbound ideas.`
+      : '[discord-bot] no DISCORD_IDEAS_CHANNEL_ID set — inbound idea filing is inert (no channel pinned).');
+
+    // #ideas auto-pairing + images (task #979): buffer a per-author burst of
+    // #ideas messages and file the combined burst (text + re-hosted images) as
+    // ONE idea once they go quiet. Mirrors the #bugs aggregator. Built once at
+    // startup; onFlush is the real filing path (recordInboundIdea).
+    const ideaAggregator = inbound.createIdeaAggregator({
+      onFlush: (combined) => inbound.recordInboundIdea(combined).then((result) => {
+        console.log(`[discord-bot] #ideas burst → ${result.outcome}${result.ideaId ? ` (idea #${result.ideaId}, ${result.images || 0} img)` : (result.reason ? ` (${result.reason})` : '')}`);
+        return result;
+      }),
+    });
+
+    // F8 bug intake (ADR 0047): the #bugs channel whose messages become GDS
+    // tasks (kind='bug') straight-through, under the anti-abuse guard in
+    // discord-bugs.js. Resolved once at startup. Null → bug intake is inert.
+    const bugsChannelId = loadBugsChannelId();
+    console.log(bugsChannelId
+      ? `[discord-bot] watching #bugs (${bugsChannelId}) for inbound bug-tasks.`
+      : '[discord-bot] no DISCORD_BUGS_CHANNEL_ID set — inbound bug filing is inert (no channel pinned).');
+
+    // F8 auto-pairing (task #936): buffer a per-author burst of #bugs messages
+    // and file the combined burst as ONE bug once they go quiet. onFlush is the
+    // real filing path (recordInboundBug). Built once at startup.
+    const bugAggregator = bugs.createBugAggregator({
+      onFlush: (combined) => bugs.recordInboundBug(combined).then((result) => {
+        console.log(`[discord-bot] #bugs burst → ${result.outcome}${result.taskId ? ` (task #${result.taskId}, ${result.status}, ${result.images || 0} img)` : (result.reason ? ` (${result.reason})` : '')}`);
+        return result;
+      }),
+    });
+
+    // Upvoting (F4, ADR 0033 §3). A 👍 in #ship-feed → real peer-vote (if the
+    // reacting user is linked to a Metic+ non-author) or cosmetic applause
+    // (everyone else). ALL authorization is re-derived server-side in
+    // discord-reaction.recordDiscordReaction against the linked builder's LIVE
+    // rank — the bot only asserts WHO reacted, never WHAT they may do. This
+    // handler is deliberately thin and NEVER throws into the gateway. Cheap
+    // gates (captured channel id, emoji, channel match) run BEFORE any network
+    // fetch so off-target reactions cost nothing.
+    c.on(Events.MessageReactionAdd, async (rxn, user) => {
+      try {
+        if (user?.bot) return;                              // ignore bots, incl. self
+        if (!shipFeedChannelId) return;                     // fail-closed: no channel pinned
+        if (rxn.emoji?.name !== UPVOTE_EMOJI) return;       // only 👍 is the upvote
+        // channelId is present on the partial reaction (no fetch needed yet) —
+        // reject off-channel reactions before paying for any hydration.
+        if (rxn.message?.channelId && rxn.message.channelId !== shipFeedChannelId) return;
+        // Reactions on uncached messages arrive partial — hydrate before reading.
+        if (rxn.partial) { try { await rxn.fetch(); } catch { return; } }
+        const msg = rxn.message;
+        if (msg.partial) { try { await msg.fetch(); } catch { return; } }
+        if (msg.channelId !== shipFeedChannelId) return;    // only #ship-feed (re-check post-hydrate)
+        // Only count reactions on WEBHOOK-posted ledger lines (Mozzie). A
+        // webhook message carries a non-null webhookId; a normal member message
+        // does not, and a member cannot post as a webhook (needs Manage
+        // Webhooks + the secret URL). This makes the F4 Hacker "fake #<id> line"
+        // concern fail-closed IN CODE, not just via the channel-permission lock.
+        if (!msg.webhookId) return;
+        const taskId = reaction.parseShipMarker(msg.content || '');
+        if (!taskId) return;                                // not a ship-marker line
+        const result = await reaction.recordDiscordReaction({ discordUserId: user.id, taskId });
+        // Don't log the reacting user's Discord id on the success path — the
+        // systemd journal is less access-controlled than audit_log (Archon-only),
+        // which already records the id with surface='discord_bot'. Log only the
+        // task + outcome here (Hacker finding).
+        console.log(`[discord-bot] 👍 on task #${taskId} → ${result.outcome}`);
+      } catch (err) {
+        console.error('[discord-bot] reaction handler error:', err.message);
+      }
+    });
+
+    // Archon approvals (task 1100). A 👍/👎 in #member-approvals, by an Archon, on a
+    // webhook-posted request line → the existing approve/decline action (admit a
+    // new builder). ALL authorization is re-derived server-side in
+    // discord-approvals against the reacting builder's LIVE rank (must be Archon) —
+    // the bot only asserts WHO reacted. Thin, fail-closed on channel config, NEVER
+    // throws into the gateway. Cheap gates (channel pinned, emoji, channel match)
+    // run before any fetch.
+    c.on(Events.MessageReactionAdd, async (rxn, user) => {
+      try {
+        if (user?.bot) return;                              // ignore bots, incl. self
+        if (!memberApprovalsChannelId) return;              // fail-closed
+        if (!APPROVAL_EMOJI.has(rxn.emoji?.name)) return;   // only 👍 / 👎
+        const ch = rxn.message?.channelId;
+        // Pre-hydration channel gate: reject reactions outside the approval
+        // channel before paying for any fetch.
+        if (ch && ch !== memberApprovalsChannelId) return;
+        if (rxn.partial) { try { await rxn.fetch(); } catch { return; } }
+        const msg = rxn.message;
+        if (msg.partial) { try { await msg.fetch(); } catch { return; } }
+        // Confirm post-hydration that this is the #member-approvals channel.
+        if (msg.channelId !== memberApprovalsChannelId) return;
+        const kind = 'member';
+        // Only act on WEBHOOK-posted request lines (the GDS posts these). A member
+        // message carries no webhookId and cannot forge one — so a hand-typed
+        // "member-request #5" can't trigger an approval. Fail-closed in code.
+        if (!msg.webhookId) return;
+        const marker = approvals.parseApprovalMarker(msg.content || '');
+        if (!marker || marker.kind !== kind) return;        // not a request line / wrong channel
+        const decision = approvals.emojiToDecision(rxn.emoji.name);
+        if (!decision) return;
+        const result = await approvals.recordApprovalReaction({
+          discordUserId: user.id, kind, decision, recordId: marker.id,
+        });
+        // Post a short confirmation back to the channel for the ones that acted,
+        // so the Archon sees the outcome inline. Best-effort via the webhook (the
+        // bot posts nothing of authority); silent on no-ops / ignores.
+        if (result.outcome === 'approved' || result.outcome === 'declined') {
+          const verb = decision === 'approve' ? 'invited to the hall' : 'dismissed';
+          const who = result.resolved && result.resolved.github_login
+            ? result.resolved.github_login
+            : `member-request #${marker.id}`;
+          require('./webhook')
+            .postWebhook('member_approvals', `✅ ${who} ${verb}.`)
+            .catch(() => {});
+        }
+        // Don't log the reacting Discord id (audit_log already records it,
+        // Archon-only). Log only the record + outcome.
+        console.log(`[discord-bot] approval ${kind} #${marker.id} (${decision}) → ${result.outcome}`);
+      } catch (err) {
+        console.error('[discord-bot] approval handler error:', err.message);
+      }
+    });
+
+    // Inbound idea filing (F6, ADR 0033 §5). A message in #ideas → an
+    // idea_inbox entry (attributed to the linked builder when known). All
+    // filing logic + attribution + audit lives in discord-inbound; this handler
+    // is thin, fail-closed on channel config, and NEVER throws into the gateway.
+    c.on(Events.MessageCreate, makeInboundChannelHandler({
+      channelId: ideasChannelId, aggregator: ideaAggregator, logLabel: 'inbound handler',
+    }));
+
+    // Inbound bug filing (F8, ADR 0047). A message in #bugs → a GDS task
+    // (kind='bug') straight-through, under the anti-abuse guard (linked-only +
+    // rank-aware landing + per-builder rate-limit + body screen) — all in
+    // discord-bugs.recordInboundBug. This handler is thin, fail-closed on
+    // channel config, and NEVER throws into the gateway. Separate listener from
+    // #ideas so the two intakes stay structurally independent.
+    c.on(Events.MessageCreate, makeInboundChannelHandler({
+      channelId: bugsChannelId, aggregator: bugAggregator, logLabel: 'bug handler',
+    }));
+
+    // Role-on-arrival (F7, ADR 0033 — the link-first onboarding gate's safety
+    // net). The auto-join path (routes/auth.js) already sets the rank role at
+    // add-time, so a builder who linked-then-joined is correct immediately. This
+    // handler covers every OTHER way a member can appear — a stray pre-existing
+    // invite, a manual add, a re-join after leaving — by re-deriving their role
+    // from their LIVE GDS rank the instant they arrive. ONE-WAY (ADR 0016): it
+    // reads builders.rank and writes a Discord role, never the reverse. An
+    // unlinked arrival maps to no builder and is left untouched. Thin, never
+    // throws into the gateway.
+    c.on(Events.GuildMemberAdd, async (member) => {
+      try {
+        if (member?.user?.bot) return; // ignore bots, incl. self
+        const builder = await db.getBuilderByDiscordUserId(member.id);
+        if (!builder) return;          // unlinked arrival — nothing to sync
+        const roleSync = require('./discord-role-sync');
+        const r = await roleSync.syncBuilderRole(builder.id);
+        console.log(`[discord-bot] member joined → role-sync for builder ${builder.id}: ${r.ok ? (r.noop ? 'noop' : 'synced') : r.reason}`);
+      } catch (err) {
+        console.error('[discord-bot] member-add handler error:', err.message);
+      }
+    });
+
+    client = c;
+    // login() rejects on a bad token / network failure — catch it so a Discord
+    // problem never propagates into the HTTP boot path.
+    await c.login(token).catch((err) => {
+      console.error('[discord-bot] login failed:', err.message);
+      // Tear the half-built client down so a later start() can retry cleanly.
+      try { c.destroy(); } catch (_) { /* ignore */ }
+      client = null;
+    });
+    return client;
+  } catch (err) {
+    console.error('[discord-bot] failed to start:', err.message);
+    client = null;
+    return null;
+  } finally {
+    starting = false;
+  }
+}
+
+// Run the F5 role-sync reconcile sweep (best-effort, lazy-required to avoid a
+// require cycle with discord-role-sync). Logs a one-line summary.
+function runRoleReconcile(trigger) {
+  const roleSync = require('./discord-role-sync');
+  roleSync.reconcileAll()
+    .then((r) => console.log(`[discord-bot] role-sync reconcile (${trigger}): ${r.synced}/${r.total} linked builders synced.`))
+    .catch((err) => console.error(`[discord-bot] role-sync reconcile (${trigger}) failed:`, err.message));
+}
+
+// Run the ADR 0037 channel reconcile sweep (best-effort, lazy-required). Makes
+// the guild match docs/discord/channels.json. Logs a one-line summary.
+function runChannelReconcile(trigger) {
+  const channels = require('./discord-channels');
+  channels.reconcileChannels()
+    .then((r) => {
+      if (!r.ok) console.log(`[discord-bot] channel reconcile (${trigger}): skipped (${r.reason}).`);
+      else console.log(`[discord-bot] channel reconcile (${trigger}): ${r.applied} applied, ${r.failed} failed of ${r.total}.`);
+    })
+    .catch((err) => console.error(`[discord-bot] channel reconcile (${trigger}) failed:`, err.message));
+}
+
+// Graceful shutdown — close the gateway connection. Safe to call when never
+// started (no-op). Idempotent. Wired to SIGTERM/SIGINT in server.js so a
+// systemd restart / Ctrl-C closes the socket cleanly instead of leaving a
+// zombie session that Discord later reaps.
+async function stop() {
+  if (reconcileTimer) { clearInterval(reconcileTimer); reconcileTimer = null; }
+  if (channelTimer) { clearInterval(channelTimer); channelTimer = null; }
+  if (!client) return;
+  const c = client;
+  client = null;
+  try {
+    await c.destroy();
+    console.log('[discord-bot] disconnected.');
+  } catch (err) {
+    console.error('[discord-bot] error during shutdown:', err.message);
+  }
+}
+
+module.exports = { start, stop, getClient, botEnabled, loadShipFeedChannelId, loadIdeasChannelId, loadBugsChannelId, loadMemberApprovalsChannelId, channelsManaged };